FastOG SDK — İndirme ve Kullanım

Her dil için tek dosya, sıfır bağımlılık, paket yöneticisi gerektirmez. Aşağıdan indirin (veya CDN'den curl ile alın) ve projenize kopyalayın (yalnızca sunucu tarafı). Şu anda v1 olarak burada tutulmaktadır — sözleşme değiştiğinde bu sayfayı ve indirilebilir dosyaları birlikte güncelleriz. Tam imzalama sözleşmesi ve herhangi bir dilde elle yazılmış uygulamalar için bkz. Agent ve LLM Entegrasyonu.

İndirmeler

Bir dil seçin ve indir düğmesine tıklayın (veya sağ tıklayın → Farklı Kaydet):

Bu bağlantılar /sdk/<file> adresine gider ve dosyayı indirme olarak sunar — ya da komut satırını tercih ediyorsanız curl -O https://fastog.com/sdk/<file> kullanabilirsiniz.

Vue, Next.js, Astro ve Express Node üzerinde çalışır — aynı test edilmiş imzalayıcı dosyalarını paylaşırlar (Express için CommonJS, diğerleri için ESM); yalnızca kullanım/README farklıdır. Her framework'ün sdk/<name>/README.md dosyası tam entegrasyonu gösterir.

Her dosya SDK'nın tamamıdır. Projenize kopyalayın, require/import yapın, bitti.

Kullanım

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 (+page.server.js / +layout.server.js içinde)

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) — imzalayıcıyı (signer) içe aktarın, sunucu kodunuzda ogImageUrl(params, { key, secret }) çağrısını yapın ve URL'yi head bölümünde görüntüleyin. Her framework'ün sdk/<name>/README.md bölümüne bakın.

url öğesini <meta property="og:image"> içine ekleyin. Tarayıcılar (crawler) bunu GET ile alır — edge önbellekli, benzersiz görsel başına tek işleme.

Sürümleme

Bu v1 sürümüdür ve yerinde bakımı yapılır. Sözleşme değiştiğinde dosyaları ve bu sayfayı birlikte güncelleriz (v2, v3, …) — siz yeniden indirerek güncellersiniz. Senkronize edilecek bir paket kayıt defteri, semver töreni veya çoklu paket sürüklenmesi yoktur.

Nasıl çalışır

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

• Bir parametredeki herhangi bir değişiklik imzayı geçersiz kılar → 401, işleme yok, kota sayımı yok.
• Aynı parametreler → aynı URL → uçta (edge) süresiz olarak önbelleğe alınabilir.
• Dizi parametreleri (features) key[]= / key[0]= olarak gönderilir, böylece sunucu bunları doğru şekilde çözer.
• Anahtarın gizli anahtarını (secret) döndürerek iptal edin.

Doğrulama

Tüm SDK'lar, FastOG sunucusu tarafından üretilen aynı altın vektörle (golden vector) test edilir:

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

Kopyanız bu parametreler için bu imzayı üretiyorsa, sunucu URL'lerinizi kabul edecektir.

Güvenlik

• secret yalnızca sunucu tarafındadır — asla tarayıcıda, asla herkese açık bir CDN betiğinde bulunmaz.
• key herkese açıktır (URL'lerde görünür) — bu beklenen bir durumdur.
• Sunucunuzda imzalayın; gömdüğünüz şey FastOG URL'sidir, gizli anahtar değil.