FastOG SDK — Download e Utilizzo

Un file per linguaggio, zero dipendenze, nessun gestore di pacchetti richiesto. Scaricalo qui sotto (oppure curl dal nostro CDN) e copialo nel tuo progetto (solo lato server). Mantenuto come v1 proprio qui — quando il contratto cambia, aggiorniamo questa pagina e i file scaricabili insieme. Per il contratto di firma completo e le implementazioni scritte a mano in qualsiasi linguaggio, vedi Integrazione con Agent e LLM.

Download

Scegli un linguaggio e premi download (oppure clic destro → Salva con nome):

Questi link puntano a /sdk/<file>, che serve il file come download — oppure usa curl -O https://fastog.com/sdk/<file> se preferisci la riga di comando.

Vue, Next.js, Astro ed Express girano su Node — condividono gli stessi file signer testati (CommonJS per Express, ESM per gli altri); cambia solo l'uso/README. Il sdk/<name>/README.md di ogni framework mostra l'integrazione esatta.

Ogni file è l'intero SDK. Copialo nel tuo progetto, require/import e il gioco è fatto.

Utilizzo

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 (in +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) — importa la funzione di firma (signer), chiama ogImageUrl(params, { key, secret }) nel tuo codice server e renderizza l'URL nell'head. Consulta la sdk/<name>/README.md di ciascun framework.

Inserisci url in <meta property="og:image">. I crawler lo recuperano via GET — cache perimetrale (edge-cache), un solo rendering per immagine unica.

Versioning

Questa è la v1 e viene mantenuta sul posto. Quando il contratto cambia, aggiorniamo i file insieme a questa pagina (v2, v3, …) — per aggiornare ti basta riscaricare i file. Nessun registro di pacchetti da sincronizzare, nessuna cerimonia semver, nessuna deriva tra più pacchetti.

Come funziona

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))

• Qualsiasi modifica a un parametro invalida la firma → 401, nessun rendering, nessun conteggio quota.
• Parametri identici → URL identico → memorizzabile nella cache per sempre.
• I parametri array (features) vengono emessi come key[]= / key[0]= così il server li decodifica correttamente.
• Revoca ruotando il segreto della chiave.

Verifica

Tutti gli SDK vengono testati con lo stesso golden vector generato dal server FastOG:

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

Se la tua copia produce quella firma per quei parametri, il server accetterà i tuoi URL.

Sicurezza

• secret è solo lato server — mai nel browser, mai in uno script CDN pubblico.
• key è pubblico (compare negli URL) — è previsto.
• Firma sul tuo server; l'URL FastOG è ciò che incorpori, non il segreto.