FastOG SDK — Descărcare și utilizare

Un fișier per limbaj, zero dependențe, fără manager de pachete necesar. Descarcă-l mai jos (sau curl de pe CDN-ul nostru) și copiază-l în proiectul tău (doar pe partea de server). Menținut ca v1 chiar aici — când contractul se schimbă, actualizăm această pagină și fișierele descărcabile împreună. Pentru contractul complet de semnare + implementări scrise manual în orice limbaj, vezi Integrare Agent & LLM.

Descărcări

Alege o limbă și apasă descarcă (sau click dreapta → Salvează ca):

Aceste linkuri duc la /sdk/<file>, care servește fișierul ca descărcare — sau folosește curl -O https://fastog.com/sdk/<file> dacă preferi linia de comandă.

Vue, Next.js, Astro și Express rulează pe Node — ele împărtășesc aceleași fișiere signer testate (CommonJS pentru Express, ESM pentru restul); doar utilizarea/README diferă. sdk/<name>/README.md al fiecărui framework arată integrarea exactă.

Fiecare fișier este întregul SDK. Copiază-l în proiectul tău, require/import-l, gata.

Utilizare

Node.js

const { ogImageUrl } = require("./fastog.js");
const url = ogImageUrl(
    {
        template: "blog",
        title: "Hello World",
        features: ["Free shipping", "30-day returns"],
    },
    { key: process.env.FASTOG_API_KEY, secret: process.env.FASTOG_HMAC_SECRET },
);

SvelteKit (în +page.server.js / +layout.server.js)

import { ogImageUrl } from "$lib/fastog.js";
const url = ogImageUrl(params, {
    key: process.env.FASTOG_API_KEY,
    secret: process.env.FASTOG_HMAC_SECRET,
});

PHP

use FastOg\FastOg;
$url = FastOg::signedUrl($params, getenv('FASTOG_API_KEY'), getenv('FASTOG_HMAC_SECRET'));

Ruby / Rails

url = FastOg.signed_url(params, ENV.fetch("FASTOG_API_KEY"), ENV.fetch("FASTOG_HMAC_SECRET"))

Python (Django / FastAPI / Flask)

import fastog
url = fastog.signed_url(params, os.environ["FASTOG_API_KEY"], os.environ["FASTOG_HMAC_SECRET"])

Go

url := fastog.SignedURL(params, os.Getenv("FASTOG_API_KEY"), os.Getenv("FASTOG_HMAC_SECRET"))

Express / Next.js / Astro / Vue (Node) — importă semnatarul (signer), apelează ogImageUrl(params, { key, secret }) în codul tău de server, apoi afișează URL-ul în secțiunea head. Vezi sdk/<name>/README.md pentru fiecare framework.

Adaugă url în <meta property="og:image">. Crawler-ele îl accesează prin GET — cache la marginea rețelei (edge-cached), o singură randare per imagine unică.

Versionare

Aceasta este v1 și este menținută la locul ei. Când contractul se schimbă, actualizăm fișierele și această pagină împreună (v2, v3, …) — te actualizezi prin re-descărcare. Nu există registry de pachete de sincronizat, nicio ceremonie semver, nicio derivă între mai multe pachete.

Cum funcționează

canonical = sorted enc(key)=enc(value) pairs of every param except `s`, including `key`
message   = "GET/api/v1/og" + "\n" + canonical
signature = hex(HMAC-SHA256(message, secret))

• Orice modificare a unui parametru invalidează semnătura → 401, fără randare, fără consum de cotă.
• Parametri identici → URL identic → memorabil în cache la edge pentru totdeauna.
• Parametri de tip array (features) sunt emiși ca key[]= / key[0]=, astfel încât serverul să îi decodifice corect.
• Revocarea se face prin rotirea secretului cheii.

Verificare

Toate SDK-urile sunt testate împotriva aceluiași vector de referință (golden vector) generat de serverul FastOG:

canonical = features=30-day%20returns&features=Free%20shipping&key=sk_test123&template=blog&title=Hello%20World
signature = a79232b15b45002aee76174f542e0a661b37cb1259df01e263c952ca4052a54d

Dacă implementarea ta produce acea semnătură pentru acești parametri, serverul va accepta URL-urile tale.

Securitate

• secret este doar pe partea de server — niciodată în browser, niciodată într-un script public CDN.
• key este public (apare în URL-uri) — acest lucru este de așteptat.
• Semnează pe serverul tău; URL-ul FastOG este ceea ce încorporezi, nu secretul.