@stewardhq/sdk 0.1.0-rc.0

package/README.md

@@ -0,0 +1,437 @@
+# @stewardhq/sdk
+
+Steward ↔ ürün entegrasyonu: sözleşme şemaları (zod), tipli API istemcisi ve
+webhook imzası. Kaynak: [z9cloud/steward](https://github.com/z9cloud/steward/tree/main/sdk).
+
+## Kurulum
+
+npmjs'te public; token gerekmez.
+
+```bash
+pnpm add @stewardhq/sdk
+```
+
+ESM, Node ≥ 22. Tek çalışma zamanı bağımlılığı zod.
+
+## Alt yollar
+
+| Import | İçerik |
+| --- | --- |
+| `@stewardhq/sdk` | Tüm şema/tipler + istemciler (`createSteward`, `createCatalogCache`, `stateCache`, fırlatmayan `createBillingClient`) + yardımcılar: hata sınıfları, `httpStatusFor`, `errorMessages`/`messageFor`, `defineCatalog`, `formatPrice`/`taxBreakdown`, `isValidTckn`/`isValidVkn`/`isE164` |
+| `@stewardhq/sdk/contract` | Yalnızca şemalar ve tipler |
+| `@stewardhq/sdk/webhook` | `signWebhook` / `verifyWebhook` / `verifyWebhookRaw` (Node HMAC, senkron) |
+| `@stewardhq/sdk/webhook/web` | Aynı API WebCrypto ile (async; edge/workerd/tarayıcı) |
+| `@stewardhq/sdk/testing/fixtures/events/<tür>.json` | Her event türünün örnek gövdesi |
+| `@stewardhq/sdk/server` | `Webhooks()`: imzalı event alıcısı, canlı durum + önbellek, tipli hook'lar (Node); `Checkout()`: hosted checkout oturumu (`create` → `url`) ve dönüş sonucu (`result`); `CustomerPortal()`: hosted müşteri portalı oturumu (`create` → `url`) |
+| `@stewardhq/sdk/testing` | Test çiftleri (Node): `createFakeSteward()` (HTTP düzeyinde sahte steward, `simulate.*`, `connect`), `signedEvent()` |
+
+Kök giriş, `./contract` ve `./webhook/web` `node:*` kullanmaz (edge/tarayıcı);
+`./webhook` senkron Node HMAC'idir.
+
+## Kullanım
+
+Hesap durumu (okuma modeli) — ürün DB'sinde hak projeksiyonu tutulmaz; kapılar steward'ı
+pod başına bir önbellek üzerinden canlı okur:
+
+```ts
+import { createSteward, stateCache } from "@stewardhq/sdk";
+
+export const steward = createSteward();
+export const state = stateCache(steward, {
+  catalog,                                  // entitlements() tipli olur
+  // steward kapalı ve bayat değer yoksa (AccountState | null); catalog.stateOf: katalogdan tam durum (version 0)
+  fallback: async (ref) => {
+    const org = await findOrg(ref);
+    return org ? catalog.stateOf(ref, org.plan, { displayName: org.name }) : null;
+  },
+  onFallback: ({ ref, reason }) => metrics.billingFallback.inc({ reason }),
+  // missing: "fallback" → steward'da hesabı olmayan kayıt da fallback'e (hesap ilk checkout'ta açılıyorsa)
+  // ttlMs: 30_000, staleIfErrorMs: 600_000, maxEntries: 10_000, logger
+});
+
+const e = await state.entitlements(orgId);  // { max_projects: number | null; sso: boolean }
+await state.state(orgId, { fresh: true });  // TTL'i beklemeden
+state.prime((await steward.grants.create(orgId, input)).account); // mutasyon yanıtı önbelleğe
+const byRef = await state.many(orgIds);     // Map<ref, AccountState>, en çok 8 paralel
+```
+
+| Durum | Davranış |
+| --- | --- |
+| TTL içinde | Bellekten, istek yok; aynı hesabın eşzamanlı okumaları tek istek |
+| TTL doldu | `If-None-Match`: 304 süreyi yeniler, 200 yeni durumu yazar |
+| Ağ hatası, zaman aşımı, 5xx, 429 | Süre dolduktan sonra `staleIfErrorMs` boyunca bayat değer (WARN), sonra `fallback` (WARN + `onFallback`), o da yoksa (ya da `null`) asıl `StewardNetworkError`/`StewardApiError`. Başarısız istekten sonra o hesap için `min(ttlMs, 5 sn)` steward'a gidilmez |
+| 404 `account_not_found` (varsayılan `missing: "throw"`) | Kesinti değil: fallback yok, önbelleğe girmez, `StewardApiError` fırlar (eksik `upsert` görünür kalır) |
+| 404 `account_not_found`, `missing: "fallback"` | `fallback(ref)` (zorunlu seçenek); WARN yok, `onFallback` nedeni `account_not_found` (kesinti metriğinden ayrılır); bayat değer kullanılmaz. Sonuç önbelleğe girmez, "yok" bilgisi `min(ttlMs, 5 sn)` tutulur; `prime`/`invalidate`/`fresh` bitirir (checkout sonucu ve webhook `prime` eder). Fallback `null` → 404 fırlar |
+| `prime(account)` | Yalnızca `version >= önbellekteki` ise yazar (geri gitmez); `null`/`undefined` yok sayılır |
+
+Önbellek pod başına bellek içidir (LRU); çok pod'da tutarlılık TTL kadardır.
+`invalidate(ref)` sonraki okumanın hemen (ETag'le) sormasını sağlar.
+
+Webhook alıcısı (`/server`, Node) — imza ham gövdede, sonra sözleşme; durum steward'dan
+canlı okunur, önbelleğe yazılır; hook'lar tipli:
+
+```ts
+import { Webhooks } from "@stewardhq/sdk/server";
+
+const webhooks = Webhooks({
+  steward, cache: state,                    // refetch (steward verilince varsayılan): payload yalnız tetikleyici
+  // secrets verilmezse her teslimatta STEWARD_WEBHOOK_SECRET ("yeni,eski" rotasyonu); toleranceSeconds: 300
+  onStateChanged: async ({ ref, state, cause }) => {
+    const org = await findOrg(ref);
+    if (!org) return "ignore";              // bilinmeyen hesap: 200, diğer hook'lar ve after koşmaz
+    await applyOrgPlan(org, state.planCode, state.accessState);
+  },
+  onSubscriptionTerminated: ({ ref }) => flagOps(ref),       // on<Tip>: eski tipten ya da state_changed cause'undan
+  onPaymentFailed: ({ ref, state, profile }) => mailOwner(ref, profile), // + onSuspended, onTerminated
+  after: ({ ref, state }) => propagate(ref, state.accessState), // diğer hook'lardan sonra, her teslimatta
+  // includeProfile: true → bildirim hook'ları fatura profilini (e-posta) alır; refetch: false → gövdedeki durum
+});
+
+app.post("/v1/billing/events", (c) => webhooks.handle(c.req.raw)); // ya da: const { status, body } = await webhooks.receive(rawBody, headers)
+```
+
+| Durum | Yanıt |
+| --- | --- |
+| Hook'lar koştu | 200 `{ok: true, handled: "received"}` |
+| `onStateChanged` `"ignore"` döndü | 200 `ignored` + WARN; neden hook'ları ve `after` koşmaz |
+| Hesap silindi: `account.deleted` ya da `cause: "account.deleted"` | 200 `deleted`; canlı okuma yok, `onAccountDeleted` + `after` gövdedeki anonim son durumla (`onStateChanged` koşmaz, `cache.invalidate` varsa çağrılır). Silmeden önce kuyruğa girmiş teslimatın canlı okuması `account_deleted` (410) alırsa hook'suz 200 `deleted` + WARN |
+| `endpoint.ping` | 200 `ping`, hook yok |
+| `refetch: false` ve gövdede yalnızca snapshot (yükseltme öncesi kuyruk) | 200 `no_state` + WARN: `onStateChanged` koşmaz, neden hook'ları ve `after` `state: null` ile koşar |
+| Tanınmayan tip | 200; `onUnknownEvent` (durum varsa önce `onStateChanged`) |
+| İmza/başlık/zaman penceresi | 401 |
+| İmzalı ama sözleşmeye uymayan gövde, id uyuşmazlığı | 400 + ALARM (steward yeniden dener) |
+| Sır yok, güncel durum okunamadı (`state_unavailable`), profil okunamadı, bir hook fırlattı | 503 (steward yeniden dener, hook'ların hepsi yeniden koşar) |
+
+Tipler: `steward` verilmiş ve `refetch: false` değilse her hook'un (`onStateChanged`, `on<Tip>`,
+`onPaymentFailed`…, `onUnknownEvent`, `after`) `state`'i `AccountState`'tir — durum okunamazsa 503 döner,
+hook koşmaz; `after`'ın `handled`'ı `"received"`. `refetch: false` ya da `steward`'sız alıcıda neden hook'ları,
+`onUnknownEvent` ve `after` `AccountState | null` alır (yükseltme öncesi kuyruk; `onStateChanged` yine tam
+durumla koşar). Ayrım `refetch` ve `steward` alanlarının tiplerinden çıkarılır (tip belirsizse null'lı).
+
+**SDK tekrar ayıklamaz, version kapısı ve kilit tutmaz.** `refetch` ile her teslimat
+durumu steward'dan canlı okur: sırasız ya da tekrar teslimat en güncel durumu görür,
+yalnızca snapshot taşıyan eski gövde de tam kullanılır (`event.data.account` bayat
+olabilir; `state`'i kullan). Aynı event yine birden çok kez ve aynı hesabın teslimatları
+eşzamanlı gelebilir: hook'lar idempotent yazmalı (plan alanını durumdan yaz, "zaten
+askıdaysa dokunma", sonlandırma işareti `coalesce`). Yeniden denenmesi istenen durumda hook
+fırlatır → 503. `refetch: false` gövdedeki durumu kullanır (sıra garantisi yok; eski
+kuyruğun boşalmasını bekle). Aynı olay için hem eski tipi hem `account.state_changed`'i
+isteyen endpoint neden hook'larını iki kez çalıştırır: endpoint filtresinde birini seç.
+
+Hosted checkout (`/server`) — profil, TCKN/VKN, onaylar ve ödeme formu steward'ın sayfasında;
+ürün yalnızca oturumu açar, kullanıcıyı `url`'e yönlendirir ve dönüşte sonucu sorar:
+
+```ts
+import { Checkout } from "@stewardhq/sdk/server";
+
+const checkout = Checkout({
+  steward, cache: state,
+  // mutlak; origin steward ayarında izinli (appUrl + extraReturnOrigins). Yer tutucular varsa
+  // steward yalnızca onları doldurur, yoksa ?session=&status= ekler.
+  successUrl: `${process.env.APP_URL}/{LOCALE}/app/orgs/{ACCOUNT_REF}/billing?checkout={CHECKOUT_ID}`,
+  consents: (locale) => legalDocs(locale),  // [{document, version, url}] ya da dizi; sayfada onaylatılır
+  // cancelUrl (yoksa ayar appUrl), locale ve currency (yoksa ürün ayarı)
+});
+
+app.post("/v1/orgs/:orgId/billing/checkout", async (c) => {
+  if (!(await isOwner(c))) return c.json({ error: "forbidden" }, 403); // yetki ÇAĞRIDAN ÖNCE ürünün işi
+  const { url } = await checkout.create({ ref: c.req.param("orgId"), planCode: "team", interval: "month",
+    locale: c.get("locale"), actorRef: `user:${c.get("user").id}` }); // displayName?, prefill?: {email, name, kind}
+  return c.json({ url });                                               // tarayıcı 303 url
+});
+
+app.get("/v1/orgs/:orgId/billing/checkout/:id", async (c) =>          // dönüş sayfası ?checkout=<id>
+  c.json(await checkout.result(c.req.param("id"), { ref: c.req.param("orgId") })));
+// { status: "open" | "completed" | "failed" | "expired" | "canceled", planCode?, account? }
+```
+
+| Durum | Davranış |
+| --- | --- |
+| `create` | `POST …/checkout-sessions` hosted gövdeyle (profil/kimlik yok); sağlayıcıya çağrı yok; `{id, url, expiresAt}`. Hesap yoksa `displayName` ile açılır, o da yoksa `account_not_found`. Steward hataları aynen (`already_subscribed` 409, `plan_not_sellable` 422, `return_url_not_allowed` → `httpStatusFor` 500 + ALARM) |
+| `result`, oturum başka hesabın / id geçersiz / oturum yok | Aynı hata: `StewardApiError` `checkout_session_not_found` (404) — `?checkout=` kullanıcı girdisidir, sahiplik ele verilmez |
+| `result`, `completed` | Yanıttaki `account` `cache.prime` edilir (dönüş sayfası webhook'u beklemeden yeni planı gösterir; webhook yine kaynak) |
+| `locale` | `CustomerPortal` ile aynı kural: BCP-47 benzeri etiketin birincil alt etiketi (`tr-TR` → `tr`, `en-US` → `en`). Çağrıdaki desteklenmeyen dil yok sayılır: seçenekteki dil, o da yoksa gönderilmez (steward `defaultLocale`); `consents` işlevi bu dille çağrılır |
+| Göreli/http(s) olmayan `successUrl`, `cancelUrl`, belge adresi; seçenekte desteklenmeyen `locale` | Oluşturmada `StewardConfigError` |
+| Yanıtta `url` yok (F2b öncesi steward) | `StewardContractError` |
+
+Kullanıcı sayfayı kapatırsa oturum süresi dolunca (`checkoutTtlMinutes`) steward kapatır;
+ürün sonucu `account.state_changed` ile öğrenir. `profile` + `identityNumber` taşıyan eski gövde
+(`steward.checkoutSessions.create`) açılışta sağlayıcı formu döndürmeye devam eder (N3 + 1
+release sonra kaldırılır).
+
+Hosted müşteri portalı (`/server`) — abonelik durumu, dönem sonunda iptal, ödemeyi yeniden dene,
+fatura listesi/PDF ve kurumsal fatura profili steward'ın sayfasında; ürün yalnızca yetkiyi
+denetler, oturumu açar ve yönlendirir. Ürün tarafında iptal/yeniden dene/fatura ucu yoktur:
+sonuçlar `account.state_changed` ile `Webhooks()`'a gelir:
+
+```ts
+import { CustomerPortal } from "@stewardhq/sdk/server";
+
+const portal = CustomerPortal({ steward, returnUrl: `${process.env.APP_URL}/billing` }); // returnUrl yoksa ayar appUrl
+
+app.post("/v1/orgs/:orgId/billing/portal", async (c) => {
+  if (!(await isOwner(c))) return c.json({ error: "forbidden" }, 403); // yetki ÇAĞRIDAN ÖNCE ürünün işi
+  const { url } = await portal.create({ ref: c.req.param("orgId"), locale: c.get("locale"), actorRef: `user:${c.get("user").id}` });
+  return c.json({ url });                                               // tarayıcı 303 url
+});
+```
+
+| Durum | Davranış |
+| --- | --- |
+| `create` | `POST …/portal-sessions {locale?, returnUrl?}` → `{id, url, expiresAt}`; durum değişmez, event yok. Süre ürün ayarı `portalTtlMinutes` (varsayılan 30 dk); süresi geçen ya da anahtarı yanlış bağlantı 404 |
+| Hesap yok | `StewardApiError` `account_not_found` (404) — checkout'tan farklı olarak hesap açılmaz |
+| `returnUrl` origin'i izinli değil | `return_url_not_allowed` (422; `httpStatusFor` 500 + ALARM) |
+| `locale` | `tr`/`en` (ör. `tr-TR` → `tr`; `Checkout` ile aynı kural); başka dil gönderilmez, steward `defaultLocale`'i kullanır |
+| `actorRef` eksik/biçimsiz, göreli ya da http(s) olmayan `returnUrl` | `StewardConfigError` (istek gitmez) |
+| Portal aksiyonları | Aktör steward denetim izinde `customer:<ref>`; iptal `subscription.cancel_scheduled` (neden `customer_portal`), profil `billing_profile.updated`, yeniden dene durum değiştirmez (tahsilat sonucu `subscription.reactivated`) |
+
+Düşük seviyede imza ham gövde üzerinde doğrulanır, sonra sözleşmeyle parse edilir:
+
+```ts
+import { verifyWebhook } from "@stewardhq/sdk/webhook";
+
+const rawBody = await request.text();
+const result = verifyWebhook({ secrets: [process.env.STEWARD_WEBHOOK_SECRET!], headers: request.headers, rawBody });
+if (!result.ok) return new Response(null, { status: 400 });
+// result.event: BillingEvent — tekrarı `id` ile ayıkla, eski `version`'ı uygulama.
+```
+
+API istemcisi — `createSteward()` ayarları seçeneklerden, yoksa ortamdan okur
+(`STEWARD_URL`, `STEWARD_API_KEY`; edge'de `env` verilir) ve eksikse **açılışta**
+`StewardConfigError` fırlatır (yalnızca admin ayarlı istemci hariç, aşağıda). Başarısız çağrı fırlatır:
+
+```ts
+import { createSteward } from "@stewardhq/sdk";
+
+export const steward = createSteward({ actorRef: "system" }); // ya da createSteward({ env, fetch, timeoutMs: 10_000 })
+
+const state = await steward.accounts.state(accountRef); // AccountState
+await steward.grants.create(accountRef, { planCode: "team", reason: "kurumsal sözleşme" }, { actorRef: `staff:${staffId}` });
+```
+
+| Kaynak | Metotlar |
+| --- | --- |
+| `accounts` | `upsert(ref, input)`, `get(ref, {include?})`, `state(ref)`, `readState(ref, {etag?})` (304 → `{notModified: true}`), `entitlements(ref)`, `putBillingProfile(ref, profile)`, `setPlan(ref, {planCode \| null, reason, mode?, endsAt?, overrides?})` → `{grant, account, warnings}` (canlı abonelik planı hedefi geçiyorsa `mode: "ensure"` uyarı, `"strict"` `subscription_plan_higher`), `resync(ref)` → `{queued, eventId}` (saklı durum `account.state_changed`, `cause: "resync"`), `delete(ref)` → `{ref, deletedAt}` (KVKK anonimleştirme; faturalar kalır; önce canlı abonelik `immediate` iptal — yoksa `subscription_active`, formu açık checkout'ta `checkout_in_progress`; sonra hesabın her ucu `account_deleted` 410) |
+| `checkoutSessions` | `create(ref, input)`, `get(id)` |
+| `portalSessions` | `create(ref, {locale?, returnUrl?})` → `{id, url, expiresAt}` (hosted müşteri portalı; `CustomerPortal()` bunu sarar) |
+| `subscriptions` | `cancel(id, input)` |
+| `grants` | `create(ref, input)`, `revoke(id)` |
+| `invoices` | `issue(id, input)`, `document(id)` → `{contentType, bytes}`, `createManual(ref, {lines, currency, taxRateBps, taxInclusive?, dueAt?, note?})` (manuel taslak; profil gerekir, `issue` ile kesilir), `void(id, {reason})` (yalnızca manuel fatura; `invoice.voided` yalnızca filtresinde isteyen endpoint'e) |
+| `catalog` | `get()`, `read({etag?})` |
+| `events` | `list({accountRef?, cursor?, limit?})`, `redeliver(id)` |
+| — | `stats()`, `me()`, `doctor()` → kurulum teşhisi (`GET /v1/doctor`; aşağıda) |
+| `admin` | `catalog.sync(input)`, `accounts.refresh()`, `settings.{get(), update(patch)}`, `endpoints.{list(), create(input), rotate(id, {secret}), deactivate(id)}` — `STEWARD_ADMIN_URL` + `STEWARD_ADMIN_API_KEY` (ya da `adminBaseUrl`/`adminApiKey`) ister; yoksa çağrıda `StewardConfigError` |
+| `raw` | Fırlatmayan, tekrar denemeyen sözleşme istemcisi (`createBillingClient`; `{ ok, data }` / `{ ok: false, status, error }`) |
+
+- **Mutasyonlar** son argümanda `{ idempotencyKey?, actorRef? }` alır. Anahtar
+  verilmezse çağrı başına üretilir; `actorRef` verilmezse `createSteward`'daki varsayılan gider.
+  İkisi de yoksa ya da biçimi geçersizse (`tür[:kimlik]`) istek **gitmez**: `StewardConfigError`
+  (`code` servisinkiyle aynı: `actor_ref_required` / `invalid_actor_ref`). `raw` bu denetimi yapmaz.
+- **Yalnızca yönetim:** `STEWARD_URL` ve `STEWARD_API_KEY` ikisi de yoksa ve `STEWARD_ADMIN_URL` +
+  `STEWARD_ADMIN_API_KEY` (ya da `adminBaseUrl`/`adminApiKey`) verilmişse istemci kurulur (CLI, katalog
+  senkronu): `admin.*` çalışır, iki kapsama açık `doctor()` ve `me()` admin anahtarıyla gider, ürün uçları
+  ve `raw.*` çağrıda `StewardConfigError` ile reddeder (istek gitmez). Ürün ayarının yalnızca yarısı
+  verilmişse yine açılışta hata.
+- **Hatalar:** yanıtlı hata `StewardApiError` (`code`, `httpStatus`, `category`,
+  `retryable`, `requestId`, `retryAfterMs`), yanıt yok `StewardNetworkError`
+  (`network_error`/`timeout`), şemaya uymayan yanıt `StewardContractError`.
+- **Tekrar deneme** (`retries: { attempts: 2, on: ["network", "5xx", "429"], maxDelayMs: 5000 }`):
+  ağ hatası/zaman aşımı, 5xx ve 429'da GET'ler ve `Idempotency-Key` taşıyan mutasyonlar
+  en çok `attempts` kez daha (varsayılan en çok 3 istek) denenir; anahtar bütün denemelerde
+  aynıdır. Bekleme `Retry-After` kadar, yoksa üstel (250 ms, 500 ms…) + jitter; ikisi de
+  `maxDelayMs` ile sınırlı. 429 dışındaki 4xx ve `retryable: false` yanıtlar
+  (`provider_error`, `provider_not_configured`) denenmez. `timeoutMs` deneme başınadır.
+- İstekler `Steward-Api-Version` ve `X-Steward-Sdk: @stewardhq/sdk/<sürüm>` taşır (yalnızca gözlem).
+- Yalnızca web standartları (`fetch`, `crypto.randomUUID`, `AbortSignal.timeout`): Node 22,
+  edge ve workerd'de aynı kod. Kök giriş ve `./webhook/web` her paket kontrolünde
+  workerd'de `nodejs_compat` kapalı koşturulur (`scripts/check-workerd.mjs`).
+
+Yönetim (admin anahtarı; cluster içi, port-forward) — ürün ayarları ve webhook endpoint'leri.
+Webhook sırrını **çağıran üretir** ve kendi Secret'ına yazar; steward sırrı hiçbir yanıtta
+geri vermez:
+
+```ts
+import { generateWebhookSecret } from "@stewardhq/sdk";
+
+await steward.admin.settings.update({
+  appUrl: "https://app.example.com",            // origin'i checkout dönüşüne izinli; + extraReturnOrigins
+  privacyUrl: "https://app.example.com/kvkk",
+  branding: { name: "Acme", accentColor: "#0f766e" }, // sığ birleşir; alanı null temizler
+  checkoutTtlMinutes: 30,
+});
+
+const secret = generateWebhookSecret();          // whsec_ + 32 rastgele bayt
+const endpoint = await steward.admin.endpoints.create({ url: "http://api.acme.svc.cluster.local/billing/events", secret });
+// eventTypes verilmezse ["account.state_changed"]; adres https:// ya da http://*.svc.cluster.local
+await steward.admin.endpoints.rotate(endpoint.id, { secret: generateWebhookSecret() }); // eski sır geçiş için ikinci imza
+```
+
+Kurulum teşhisi — ürün anahtarı yeter; ilk checkout'tan önce `ok: true` beklenir:
+
+```ts
+const report = await steward.doctor();
+// report.ok: `error` önemde uyarı yok
+// report.warnings: [{ code: "endpoint_wrong_secret", severity: "error", message, endpointId }, ...]
+// report.endpoints[].diagnosis: ok | wrong_secret (son teslimat 401) | old_contract (400) | unreachable | failing | no_deliveries
+// report.catalog, report.provider (environment: sandbox | live | fake), report.hosted.ready, report.dunning.dryRun
+```
+
+Kodlar ve teşhisler açık kümedir (bilinmeyeni yalnızca gösterin). `provider.healthy` ve
+`lastError` yanıtı veren steward pod'unun gözlemidir.
+
+Katalog önbelleği — TTL içinde bellekten, sonra `If-None-Match` (304 gövdeyi korur);
+eşzamanlı çağrılar tek istek; başarılı okumadan sonraki hatada bayat değer + `logger.warn`:
+
+```ts
+import { createCatalogCache } from "@stewardhq/sdk";
+
+const catalogCache = createCatalogCache(steward, { ttlMs: 60_000, logger });
+const { plans, prices } = await catalogCache.get();
+```
+
+Katalog — kodda tipli tanım; eksik/fazla hak, yanlış tip (`limit` → tam sayı ya da
+`null` = sınırsız, `flag` → boolean, `text` → string) ve tanımsız plana fiyat derleme
+hatasıdır, tipler atlatılırsa tanım anında `StewardConfigError` fırlatır (TypeScript ≥ 5.4):
+
+```ts
+import { defineCatalog, flag, limit } from "@stewardhq/sdk";
+
+export const catalog = defineCatalog({
+  defaultPlan: "free",
+  features: { max_projects: limit(), sso: flag() },
+  plans: {
+    free: { name: "Free", rank: 0, sellable: false, entitlements: { max_projects: 1, sso: false } },
+    team: { name: "Team", rank: 10, sellable: true, entitlements: { max_projects: null, sso: true } },
+  },
+  prices: [{ plan: "team", interval: "month", currency: "TRY", amountMinor: 125_000, taxInclusive: true, taxRateBps: 2000 }],
+});
+
+await steward.admin.catalog.sync(catalog.toSyncInput()); // admin anahtarıyla (CLI/deploy adımı)
+const e = catalog.resolve(snapshot); // { max_projects: number | null; sso: boolean }
+const placeholder = catalog.stateOf("org_1", "team", { accessState: "active", displayName: "Acme" });
+// tam AccountState: version 0, updatedAt 1970, catalogVersion null, haklar planınki, abonelik/açık checkout yok,
+// profil { present: false }; plan verilmezse varsayılan plan (stateCache fallback'i için)
+```
+
+`resolve` eksik ya da tipi uymayan anahtarda değeri snapshot'ın planından (plan
+katalogda yoksa varsayılan plandan) alır, asla "sınırsız" üretmez; `onFallback`
+ile alarm verilebilir. Snapshot yoksa varsayılan planın hakları.
+
+Hatalar ve metinler — ürün API'sinin durum kodu ve kullanıcı metni:
+
+```ts
+import { httpStatusFor, messageFor, StewardError } from "@stewardhq/sdk";
+
+if (error instanceof StewardError) {
+  const { status, headers } = httpStatusFor(error, { logger }); // already_subscribed 409, rate_limited 503 + Retry-After…
+  return Response.json({ error: error.code, message: messageFor(error.code, locale) }, { status, headers });
+}
+```
+
+Tabloda olmayan kod `category`'ye göre eşlenir (`not_found` 404, `conflict` 409,
+`provider` 502, `unavailable` 503; `validation`/`config` 500 + ERROR log).
+`errorMessages.{tr,en}` sözleşmenin `ERROR_CODES` kaydındaki her kodu ve istemci
+kodlarını (`network_error`, `timeout`, `invalid_response`, `config_error`) kapsar.
+
+Para ve doğrulayıcılar: `formatPrice(price, "tr")` → `₺1.250,00 · KDV dahil`;
+`taxBreakdown(price)` servisin faturadaki matrah/KDV ayrıştırmasıyla kuruşu kuruşuna
+aynıdır. `isValidTckn`, `isValidVkn` (sağlama hanesi), `isE164(value, {country: "TR"}?)`
+değeri olduğu gibi denetler (boşluk kırpmaz).
+
+Testler (`/testing`, Node) — sahte steward sunucu açmaz, `fetch` verir; başlıkları
+(`Bearer`, `X-Actor-Ref`, `Idempotency-Key` tekrarı), ETag/304, hata gövdelerini ve
+event kurallarını servis gibi uygular. Aynı uyumluluk paketi hem sahteye hem gerçek
+servis imajına karşı koşar:
+
+```ts
+import { createFakeSteward, signedEvent } from "@stewardhq/sdk/testing";
+
+const fake = createFakeSteward({
+  catalog,                                             // oluşturmada senkronlanır
+  webhook: { secret },                                 // eventTypes verilmezse ["account.state_changed"]; "legacy" = 15 eski tip
+});
+fake.connect((req) => webhooks.handle(req));           // alıcı sonradan (ya da webhook.handler); uygulama fake'ten sonra kurulabilir
+const steward = fake.steward;                          // ya da ürünün kendi createSteward({ fetch: fake.fetch, baseUrl: fake.baseUrl, … })
+await steward.accounts.upsert("org_1", { displayName: "Org" });
+const session = await steward.checkoutSessions.create("org_1", input);
+await fake.simulate.checkoutCompleted(session.id);     // ya da checkoutFailed; hosted oturumda checkoutCanceled da
+
+// Hosted (Checkout().create): url sahte steward'ın sayfası; tarayıcı gibi sürülebilir
+const { id, url } = await checkout.create({ ref: "org_1", planCode: "team", interval: "month", actorRef: "user:1" });
+const { redirectUrl, session: done } = await fake.simulate.completeHostedCheckout(url); // sayfa GET + "Tamamla" (outcome: "failed" → Reddet)
+const page = await fake.fetch(url);                    // ya da elle: "Tamamla / Reddet / Vazgeç" formları (k gizli alanda)
+const paid = await fake.fetch(new URL(`${id}/pay`, url), { method: "POST", body: new URLSearchParams({ k: new URL(url).searchParams.get("k")!, outcome: "succeeded" }) });
+paid.headers.get("location");                          // successUrl, yer tutucular servisle aynı kuralla dolu
+
+// Portal (CustomerPortal().create): url sahte portal sayfası; servisle aynı rotalar ve bildirim kodları
+const portalSession = await portal.create({ ref: "org_1", actorRef: "user:1" });
+const k = new URL(portalSession.url).searchParams.get("k")!;
+const base = `${fake.baseUrl}/public/v1/portal/${portalSession.id}`;
+await fake.fetch(`${base}/cancel`, { method: "POST", body: new URLSearchParams({ k }) });               // 200 onay sayfası
+await fake.fetch(`${base}/cancel`, { method: "POST", body: new URLSearchParams({ k, confirm: "1" }) }); // 303 …&done=canceled
+await fake.simulate.portalCancel(portalSession.id);     // ya da doğrudan: { result: "ok" | "already_scheduled" | "no_subscription", account }
+await fake.simulate.portalRetryPayment(portalSession.id); // past_due'da { result: "ok" } — durum değişmez; sonuç renewal ile
+
+await fake.simulate.flush();                           // bekleyen event'ler alıcıya, sırayla (2xx dışı → bekler)
+
+await fake.simulate.renewal("org_1", { fail: true });  // saat dönem sonuna; past_due + dunning
+await fake.simulate.advance({ days: 7 });              // zamanlanmış işler kendi anında (dunning, dönem sonu iptali, checkout süresi, grant penceresi, portal oturumu silme)
+fake.simulate.outage(true, { mode: "503" });           // ya da "network": fetch reddeder
+await fake.simulate.deliver("account.state_changed", { ref: "org_1", duplicate: true, outOfOrder: true });
+
+const { request } = signedEvent("subscription.renewed", { accountRef: "org_1" }, { secret });
+await webhooks.handle(request());
+```
+
+`fake.requests` gelen istekleri, `fake.events(ref?)` yayınlanan event'leri tutar. Endpoint `webhook`
+seçeneğiyle oluşturmada açılır; filtre verilmezse yönetim ucunun yeni ürüne verdiği
+`["account.state_changed"]`, `eventTypes: "legacy"` pod CLI'nın filtresiz (15 eski tip) endpoint'i.
+Alıcı bağlanmadan `flush`/`deliver` fırlatır (event'ler outbox'ta bekler); `connect` alıcıyı değiştirir.
+Sahtenin bilerek farklı olduğu yerler: teslimat asenkron değil (`flush()`), `dead`
+olmaz ve geri çekilme beklenmez; sağlayıcı hata vermez; dönüş origin'i (`settings.appUrl`,
+`settings.extraReturnOrigins` ya da kısayolu `returnOrigins`) hiç ayarlanmazsa her
+`returnUrl` kabul; `admin.endpoints` ile açılan endpoint yalnızca kayıttır (teslimat
+`webhook` seçeneğinin alıcısına gider, `lastDelivery` hep null; `doctor()`'da teşhisi
+`no_deliveries`, sağlayıcı `fake` ve sağlıklı); dunning'de yeniden deneme
+sonucu `renewal` ile gelir; her yanıt `X-Request-Id` (hata gövdesinde `requestId`) taşır;
+idempotency kayıtları süpürülmez. Hosted checkout'ta sahte sayfa servisin sayfasını taklit
+etmez, yalnızca `url` ↔ `simulate` sözleşmesini sürülebilir kılar: profil formu, TCKN/VKN
+doğrulaması, onay kutuları, deneme hakkı, CSP ve POST kaynak denetimi yok. Servis profili
+müşterinin `details` gönderiminde yazar; sahte bunu tamamlanma/red anında yapar — hesabın
+profili yoksa `prefill`den (ad, e-posta, tür; geri kalanı sabit test verisi, kurumsalda VKN
+`1234567890`) sahte profil yazılır (`billing_profile.updated`), varsa aynen kalır; belgeler
+o anda onaylanmış sayılır. Sayfada sağlayıcı formu olmadığından vazgeç her zaman `canceled`
+olur ve süresi dolan hosted oturumun nedeni `expired`dır.
+
+Portal oturumu (`portalSessions.create`) servisle aynı kurallarla açılır (hesap yoksa 404,
+`returnUrl` origin politikası, süre `portalTtlMinutes`, 43 karakterlik sayfa anahtarı; süresi
+geçen, anahtarsız ya da anahtarı yanlış oturum aynı 404). Sahte portal sayfası da servisin
+sayfasını taklit etmez — marka, tr/en metinler, CSP, POST kaynak denetimi (`Sec-Fetch-Site`),
+IP başına yanlış anahtar ve oturum başına aksiyon sayaçları (429) yok — ama rotaları
+(`GET ?k=`, `POST …/cancel` iki adım `confirm=1`, `…/retry-payment`, `…/profile`,
+`GET …/invoices/:id/document?k=`), 303 bildirim kodları (`done=canceled|retry_requested|profile_saved`,
+`error=no_subscription|already_canceled|nothing_to_retry|retry_too_soon`), profil alan hata kodları
+(422) ve sonuçları servisle aynıdır; uyumluluk paketi iki hedefi de sayfa üzerinden sürer.
+Yönlendirmeler mutlak adrestir (servis köke göre yol verir). Sahte sağlayıcı hata vermediğinden
+`provider_error` bildirimi yok. "Ödemeyi yeniden dene" isteği kabul eder (`ok`, abonelik başına
+10 dakikada bir; dry-run olmayan dunning retry adımı da sayılır) ama tahsilatı kendisi
+sonuçlandırmaz: servisteki gibi sonuç sonradan gelir — `simulate.renewal(ref)` aynı başarısız
+siparişi başarılı sayar (`subscription.reactivated`), `{fail: true}` yine başarısız.
+`simulate.portalCancel/portalRetryPayment` bilinmeyen ya da süresi geçmiş oturumda fırlatır.
+
+## `@z9cloud/steward-contract`'tan geçiş
+
+| Eski | Yeni |
+| --- | --- |
+| `@z9cloud/steward-contract` | `@stewardhq/sdk` (ya da yalnız şema için `@stewardhq/sdk/contract`) |
+| `@z9cloud/steward-contract/client` | `@stewardhq/sdk` (`createBillingClient` aynen; fırlatan istemci `createSteward`) |
+| `@z9cloud/steward-contract/webhook` | `@stewardhq/sdk/webhook` |
+| `@z9cloud/steward-contract/fixtures/events/*.json` | `@stewardhq/sdk/testing/fixtures/events/*.json` |
+
+GitHub Packages `.npmrc` satırı ve Docker `--secret` bağlaması artık gerekmez.
+
+## Sürümleme
+
+Semver. Alan kaldırma/yeniden adlandırma kırıcıdır (major; 1.0 öncesi minor).
+Yayın: `sdk/package.json` sürümü artırılır, `sdk-v<sürüm>` etiketi push edilir
+(`.github/workflows/sdk-publish.yml`, npm provenance ile).

package/dist/_chunks/errors.js

@@ -0,0 +1,73 @@
+import { R as errorCodeSpec } from "./src.js";
+//#region src/errors.ts
+var StewardError = class extends Error {
+	code;
+	httpStatus;
+	retryable;
+	constructor(options) {
+		super(options.message ?? options.code, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "StewardError";
+		this.code = options.code;
+		this.httpStatus = options.httpStatus ?? 0;
+		this.retryable = options.retryable ?? false;
+		if (options.category !== void 0) this.category = options.category;
+		if (options.requestId !== void 0) this.requestId = options.requestId;
+		if (options.retryAfterMs !== void 0) this.retryAfterMs = options.retryAfterMs;
+	}
+};
+/**
+* Steward 2xx dışı yanıt döndü (`{error, message?}`). Yanıt `category` /
+* `retryable` taşımıyorsa sözleşmenin `ERROR_CODES` kaydı kullanılır; kod orada
+* da yoksa 429 ve 5xx tekrar denenebilir sayılır.
+*/
+var StewardApiError = class extends StewardError {
+	constructor(options) {
+		const spec = errorCodeSpec(options.code);
+		const category = options.category ?? spec?.category;
+		super({
+			...options,
+			...category !== void 0 ? { category } : {},
+			retryable: options.retryable ?? spec?.retryable ?? (options.httpStatus === 429 || options.httpStatus >= 500)
+		});
+		this.name = "StewardApiError";
+	}
+};
+/** Steward'a ulaşılamadı ya da zaman aşımı; yanıt yok (`httpStatus` 0), tekrar denenebilir. */
+var StewardNetworkError = class extends StewardError {
+	constructor(options = {}) {
+		super({
+			...options,
+			code: options.code ?? "network_error",
+			httpStatus: 0,
+			category: "unavailable",
+			retryable: options.retryable ?? true
+		});
+		this.name = "StewardNetworkError";
+	}
+};
+/** Yanıt sözleşme şemasına uymadı (sürüm kayması); aynı istek aynı sonucu verir. */
+var StewardContractError = class extends StewardError {
+	constructor(options = {}) {
+		super({
+			...options,
+			code: options.code ?? "invalid_response",
+			retryable: options.retryable ?? false
+		});
+		this.name = "StewardContractError";
+	}
+};
+/** SDK yanlış yapılandırıldı (eksik `STEWARD_URL`, geçersiz katalog…); istek hiç gönderilmedi. */
+var StewardConfigError = class extends StewardError {
+	constructor(options = {}) {
+		super({
+			...options,
+			code: options.code ?? "config_error",
+			httpStatus: 0,
+			category: "config",
+			retryable: false
+		});
+		this.name = "StewardConfigError";
+	}
+};
+//#endregion
+export { StewardNetworkError as a, StewardError as i, StewardConfigError as n, StewardContractError as r, StewardApiError as t };