@stewardhq/sdk 0.3.0 → 0.6.0

package/README.md

@@ -1,190 +1,195 @@
 # @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).
+Steward ↔ product integration: contract schemas (zod), a typed API client and webhook signing.
+Source: [z9cloud/steward](https://github.com/z9cloud/steward/tree/main/sdk).
 
-## Kurulum
+## Installation
 
-npmjs'te public; token gerekmez.
+Public on npmjs; no token needed.
 
 ```bash
 pnpm add @stewardhq/sdk
 ```
 
-ESM, Node ≥ 22. Tek çalışma zamanı bağımlılığı zod.
+ESM, Node ≥ 22. Its only runtime dependency is zod.
 
-## Alt yollar
+## Subpaths
 
-| Import | İçerik |
+| Import | Contents |
 | --- | --- |
-| `@stewardhq/sdk` | Tüm şema/tipler + fırlatan istemci `createSteward`, hesap durumu önbelleği `stateCache`, `defineCatalog`, hata sınıfları + `httpStatusFor`, `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()` |
+| `@stewardhq/sdk` | All schemas and types + the throwing client `createSteward`, the account state cache `stateCache`, `defineCatalog`, the error classes + `httpStatusFor`, `isValidTckn`/`isValidVkn`/`isE164`; metering: `Events()`, `Meters()` |
+| `@stewardhq/sdk/contract` | Schemas and types only |
+| `@stewardhq/sdk/webhook` | `signWebhook` / `verifyWebhook` / `verifyWebhookRaw` (Node HMAC, synchronous) |
+| `@stewardhq/sdk/webhook/web` | The same API on WebCrypto (async; edge/workerd/browser) |
+| `@stewardhq/sdk/server` | `Webhooks()`: a signed event receiver, live state + cache, typed hooks (Node); `Checkout()`: a hosted checkout session (`create` → `url`) and its return result (`result`); `CustomerPortal()`: a hosted customer portal session (`create` → `url`) |
 
-Kök giriş, `./contract` ve `./webhook/web` `node:*` kullanmaz (edge/tarayıcı);
-`./webhook` senkron Node HMAC'idir.
+The root entry, `./contract` and `./webhook/web` do not use `node:*` (edge/browser);
+`./webhook` is the synchronous Node HMAC.
 
-## Kullanım
+## Usage
 
-Hesap durumu (okuma modeli) — ürün DB'sinde hak projeksiyonu tutulmaz; kapılar steward'ı
-pod başına bir önbellek üzerinden canlı okur:
+Account state (the read model) — no entitlement projection is kept in the product database;
+gates read steward live through a per-pod cache:
 
 ```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)
+  catalog,                                  // makes entitlements() typed
+  // used when steward is down and there is no stale value (AccountState | null); catalog.stateOf: full state from the catalog (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)
+  // missing: "fallback" → a record with no account in steward also goes to the fallback (if the account is only created at the first checkout)
   // 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
+await state.state(orgId, { fresh: true });  // without waiting for the TTL
+state.prime((await steward.grants.create(orgId, input)).account); // a mutation response into the cache
+const byRef = await state.many(orgIds);     // Map<ref, AccountState>, at most 8 in parallel
 ```
 
-| Durum | Davranış |
+| Situation | Behaviour |
 | --- | --- |
-| 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 |
+| Within the TTL | From memory, no request; concurrent reads of the same account share one request |
+| TTL expired | `If-None-Match`: a 304 renews the window, a 200 stores the new state |
+| Network error, timeout, 5xx, 429 | After expiry, the stale value for `staleIfErrorMs` (WARN), then `fallback` (WARN + `onFallback`), and if there is none (or it returns `null`) the original `StewardNetworkError`/`StewardApiError`. After a failed request, steward is not called again for that account for `min(ttlMs, 5 s)` |
+| 404 `account_not_found` (default `missing: "throw"`) | Not an outage: no fallback, nothing cached, `StewardApiError` is thrown (a missing `upsert` stays visible) |
+| 404 `account_not_found`, `missing: "fallback"` | `fallback(ref)` (a required option); no WARN, and `onFallback`'s reason is `account_not_found` (kept apart from the outage metric); the stale value is not used. The result is not cached, and the "absent" fact is held for `min(ttlMs, 5 s)`; `prime`/`invalidate`/`fresh` end it (a checkout result and a webhook both `prime`). A `null` fallback → the 404 is thrown |
+| `prime(account)` | Writes only when `version >= the cached one` (never goes backwards); `null`/`undefined` is ignored |
 
-Ö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.
+The cache is in-memory per pod (LRU); across many pods, consistency is bounded by the TTL.
+`invalidate(ref)` makes the next read ask immediately (with the ETag).
 
-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:
+Webhook receiver (`/server`, Node) — the signature is checked on the raw body, then the
+contract; state is read live from steward and written into the cache; the hooks are typed:
 
 ```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
+  steward, cache: state,                    // refetch (the default once steward is given): the payload is only a trigger
+  // without secrets, STEWARD_WEBHOOK_SECRET is read on every delivery ("new,old" rotation); 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
+    if (!org) return "ignore";              // unknown account: 200, and neither the other hooks nor after run
     await applyOrgPlan(org, state.planCode, state.accessState);
   },
-  onSubscriptionTerminated: ({ ref }) => flagOps(ref),       // on<Tip>: eski tipten ya da state_changed cause'undan
+  onSubscriptionTerminated: ({ ref }) => flagOps(ref),       // on<Type>: from the old type or from state_changed's cause
   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
+  after: ({ ref, state }) => propagate(ref, state.accessState), // after the other hooks, on every delivery
+  // includeProfile: true → the notification hooks get the billing profile (email); refetch: false → the state from the body
 });
 
-app.post("/v1/billing/events", (c) => webhooks.handle(c.req.raw)); // ya da: const { status, body } = await webhooks.receive(rawBody, headers)
+app.post("/v1/billing/events", (c) => webhooks.handle(c.req.raw)); // or: const { status, body } = await webhooks.receive(rawBody, headers)
 ```
 
-| Durum | Yanıt |
+| Situation | Response |
 | --- | --- |
-| 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:
+| The hooks ran | 200 `{ok: true, handled: "received"}` |
+| `onStateChanged` returned `"ignore"` | 200 `ignored` + WARN; the cause hooks and `after` do not run |
+| Account deleted: `account.deleted` or `cause: "account.deleted"` | 200 `deleted`; no live read, and `onAccountDeleted` + `after` run with the anonymised final state from the body (`onStateChanged` does not run; `cache.invalidate` is called if present). If a delivery queued before the deletion gets `account_deleted` (410) on its live read, it returns 200 `deleted` + WARN with no hooks |
+| `endpoint.ping` | 200 `ping`, no hooks |
+| `refetch: false` and the body carries only a snapshot (a queue from before the upgrade) | 200 `no_state` + WARN: `onStateChanged` does not run, and the cause hooks and `after` run with `state: null` |
+| Unrecognised type | 200; `onUnknownEvent` (preceded by `onStateChanged` if there is state) |
+| Signature / header / time window | 401 |
+| Signed but not contract-conformant body, or an id mismatch | 400 + ALARM (steward retries) |
+| No secret, current state unreadable (`state_unavailable`), profile unreadable, or a hook threw | 503 (steward retries, and every hook runs again) |
+
+Types: when `steward` is given and `refetch` is not `false`, the `state` of every hook
+(`onStateChanged`, `on<Type>`, `onPaymentFailed`…, `onUnknownEvent`, `after`) is an
+`AccountState` — if the state cannot be read, 503 is returned and no hook runs; `after`'s
+`handled` is `"received"`. With `refetch: false`, or in a receiver without `steward`, the cause
+hooks, `onUnknownEvent` and `after` get `AccountState | null` (a queue from before the upgrade;
+`onStateChanged` still runs with full state). The distinction is inferred from the types of the
+`refetch` and `steward` fields (when the type is ambiguous, the nullable one).
+
+**The SDK does not deduplicate, and holds no version gate or lock.** With `refetch`, every
+delivery reads the state live from steward: an out-of-order or repeated delivery sees the most
+current state, and even an old body carrying only a snapshot is fully usable
+(`event.data.account` may be stale; use `state`). The same event can still arrive several
+times, and deliveries for the same account can arrive concurrently: hooks must write
+idempotently (write the plan field from the state, "if already suspended, don't touch",
+`coalesce` the termination flag). To have a delivery retried, throw from a hook → 503.
+`refetch: false` uses the state in the body (no ordering guarantee; wait for the old queue to
+drain). An endpoint that asks for both the old type and `account.state_changed` for the same
+occurrence runs the cause hooks twice: pick one in the endpoint filter.
+
+Hosted checkout (`/server`) — the profile, tax identity, consents and the payment form all live
+on steward's page; the product only opens the session, redirects the user to `url`, and asks
+for the result on return:
 
 ```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 adres aynen kullanılır (parametre eklenmez).
+  // absolute; the origin must be allowed in steward's settings (appUrl + extraReturnOrigins). If
+  // placeholders are present steward fills only those; otherwise the address is used as-is (no parameters added).
   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ı)
+  consents: (locale) => legalDocs(locale),  // [{document, version, url}] or an array; consented to on the page
+  // cancelUrl (defaults to the appUrl setting), locale and currency (default to the product setting)
 });
 
 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
+  if (!(await isOwner(c))) return c.json({ error: "forbidden" }, 403); // authorization BEFORE the call is the product's job
   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
+  return c.json({ url });                                               // the browser 303s to url
 });
 
-app.get("/v1/orgs/:orgId/billing/checkout/:id", async (c) =>          // dönüş sayfası ?checkout=<id>
+app.get("/v1/orgs/:orgId/billing/checkout/:id", async (c) =>          // the return page ?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ış |
+| Situation | Behaviour |
 | --- | --- |
-| `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. `steward.checkoutSessions.create` de yalnızca
-hosted gövdeyi kabul eder; fatura profili yalnızca hosted checkout ve portal sayfalarında yazı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:
+| `create` | `POST …/checkout-sessions` with the hosted body (no profile or identity); no call to the provider; `{id, url, expiresAt}`. If the account does not exist it is opened with `displayName`, and without that, `account_not_found`. Steward's errors pass through (`already_subscribed` 409, `plan_not_sellable` 422, `return_url_not_allowed` → `httpStatusFor` 500 + ALARM) |
+| `result`, session belongs to another account / invalid id / no session | The same error: `StewardApiError` `checkout_session_not_found` (404) — `?checkout=` is user input, so ownership is not leaked |
+| `result`, `completed` | The `account` in the response is `cache.prime`d (the return page shows the new plan without waiting for the webhook; the webhook is still the source of truth) |
+| `locale` | Same rule as `CustomerPortal`: the primary subtag of a BCP-47-like tag (`tr-TR` → `tr`, `en-US` → `en`). An unsupported language in the call is ignored: the one from the options is used, and failing that nothing is sent (steward's `defaultLocale`); the `consents` function is called with that language |
+| A relative or non-http(s) `successUrl`, `cancelUrl` or document address; an unsupported `locale` in the options | `StewardConfigError` at construction |
+| No `url` in the response (a steward from before F2b) | `StewardContractError` |
+
+If the user closes the page, steward closes the session once it expires
+(`checkoutTtlMinutes`), and the product learns the result from `account.state_changed`.
+`steward.checkoutSessions.create` also only accepts the hosted body; the billing profile is
+written only on the hosted checkout and portal pages.
+
+Hosted customer portal (`/server`) — subscription status, cancel at period end, retry payment,
+the invoice list/PDF and the corporate billing profile all live on steward's page; the product
+only checks authorization, opens the session and redirects. There is no cancel, retry or
+invoice endpoint on the product side: the results arrive at `Webhooks()` as
+`account.state_changed`:
 
 ```ts
 import { CustomerPortal } from "@stewardhq/sdk/server";
 
-const portal = CustomerPortal({ steward, returnUrl: `${process.env.APP_URL}/billing` }); // returnUrl yoksa ayar appUrl
+const portal = CustomerPortal({ steward, returnUrl: `${process.env.APP_URL}/billing` }); // without returnUrl, the appUrl setting
 
 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
+  if (!(await isOwner(c))) return c.json({ error: "forbidden" }, 403); // authorization BEFORE the call is the product's job
   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
+  return c.json({ url });                                               // the browser 303s to url
 });
 ```
 
-| Durum | Davranış |
+| Situation | Behaviour |
 | --- | --- |
-| `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`) |
+| `create` | `POST …/portal-sessions {locale?, returnUrl?}` → `{id, url, expiresAt}`; state does not change and no event is emitted. The lifetime is the product setting `portalTtlMinutes` (30 minutes by default); an expired link, or one with the wrong key, gives 404 |
+| No account | `StewardApiError` `account_not_found` (404) — unlike checkout, no account is opened |
+| The `returnUrl` origin is not allowed | `return_url_not_allowed` (422; `httpStatusFor` 500 + ALARM) |
+| `locale` | `tr`/`en` (e.g. `tr-TR` → `tr`; the same rule as `Checkout`); any other language is not sent and steward uses its `defaultLocale` |
+| Missing or malformed `actorRef`, or a relative / non-http(s) `returnUrl` | `StewardConfigError` (no request is sent) |
+| Portal actions | The actor in steward's audit trail is `customer:<ref>`; a cancellation is `subscription.cancel_scheduled` (reason `customer_portal`), a profile change is `billing_profile.updated`, and a retry does not change state (the collection result is `subscription.reactivated`) |
 
-Düşük seviyede imza ham gövde üzerinde doğrulanır, sonra sözleşmeyle parse edilir:
+At the low level the signature is verified over the raw body and only then parsed with the
+contract:
 
 ```ts
 import { verifyWebhook } from "@stewardhq/sdk/webhook";
@@ -192,93 +197,100 @@ 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.
+// result.event: BillingEvent — deduplicate on `id`, and do not apply an older `version`.
 ```
 
-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:
+API client — `createSteward()` reads its settings from the options and otherwise from the
+environment (`STEWARD_URL`, `STEWARD_API_KEY`; on the edge, pass `env`), and throws
+`StewardConfigError` **at construction** if anything is missing (except for the admin-only
+client, below). A failed call throws:
 
 ```ts
 import { createSteward } from "@stewardhq/sdk";
 
-export const steward = createSteward({ actorRef: "system" }); // ya da createSteward({ env, fetch, timeoutMs: 10_000 })
+export const steward = createSteward({ actorRef: "system" }); // or 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}` });
+await steward.grants.create(accountRef, { planCode: "team", reason: "enterprise agreement" }, { actorRef: `staff:${staffId}` });
 ```
 
-| Kaynak | Metotlar |
+| Resource | Methods |
 | --- | --- |
-| `accounts` | `upsert(ref, input)`, `get(ref, {include?})`, `state(ref)`, `readState(ref, {etag?})` (304 → `{notModified: true}`), `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) |
+| `accounts` | `upsert(ref, input)`, `get(ref, {include?})`, `state(ref)`, `readState(ref, {etag?})` (304 → `{notModified: true}`), `setPlan(ref, {planCode \| null, reason, mode?, endsAt?, overrides?})` → `{grant, account, warnings}` (entitlements are a union of layers — there is no `rank`; M35: `mode` is accepted and **ignored**, and `warnings` is always empty), `resync(ref)` → `{queued, eventId}` (the stored state as `account.state_changed`, `cause: "resync"`), `delete(ref)` → `{ref, deletedAt}` (KVKK anonymisation; invoices remain; any live subscription must be cancelled `immediate` first — otherwise `subscription_active`, or `checkout_in_progress` while a checkout form is open; afterwards every endpoint for the account returns `account_deleted` 410) |
 | `checkoutSessions` | `create(ref, input)`, `get(id)` |
-| `portalSessions` | `create(ref, {locale?, returnUrl?})` → `{id, url, expiresAt}` (hosted müşteri portalı; `CustomerPortal()` bunu sarar) |
+| `portalSessions` | `create(ref, {locale?, returnUrl?})` → `{id, url, expiresAt}` (the hosted customer portal; `CustomerPortal()` wraps this) |
 | `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) |
+| `invoices` | `issue(id, input)`, `document(id)` → `{contentType, bytes}`, `createManual(ref, {lines, currency, taxRateBps, taxInclusive?, dueAt?, note?})` (a manual draft; needs a profile, and is issued with `issue`), `void(id, {reason})` (manual invoices only; `invoice.voided` goes only to an endpoint that asks for it in its filter) |
 | `catalog` | `get()`, `read({etag?})` |
-| — | `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` |
-
-- **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`).
-- **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:
+| — | `stats()`, `me()`, `doctor()` → setup diagnostics (`GET /v1/doctor`; below) |
+| `admin` | `catalog.sync(input)`, `accounts.refresh()`, `settings.{get(), update(patch)}`, `endpoints.{list(), create(input), rotate(id, {secret}), deactivate(id)}` — requires `STEWARD_ADMIN_URL` + `STEWARD_ADMIN_API_KEY` (or `adminBaseUrl`/`adminApiKey`); without them, `StewardConfigError` at the call |
+
+- **Mutations** take `{ idempotencyKey?, actorRef? }` as their last argument. Without a key,
+  one is generated per call; without `actorRef`, the default from `createSteward` is used. If
+  neither exists, or the format is invalid (`type[:id]`), the request is **not sent**:
+  `StewardConfigError` (with the same `code` as the service's: `actor_ref_required` /
+  `invalid_actor_ref`).
+- **Admin only:** when neither `STEWARD_URL` nor `STEWARD_API_KEY` is set but
+  `STEWARD_ADMIN_URL` + `STEWARD_ADMIN_API_KEY` (or `adminBaseUrl`/`adminApiKey`) are, the
+  client is constructed (for the CLI and catalog sync): `admin.*` works, `doctor()` and `me()`
+  — open to both scopes — go out with the admin key, and the product endpoints and `raw.*`
+  reject at the call with `StewardConfigError` (no request is sent). If only half of the
+  product setting is given, it still fails at construction.
+- **Errors:** an error with a response is `StewardApiError` (`code`, `httpStatus`, `category`,
+  `retryable`, `requestId`, `retryAfterMs`), no response is `StewardNetworkError`
+  (`network_error`/`timeout`), and a response that does not match the schema is
+  `StewardContractError`.
+- **Retries** (`retries: { attempts: 2, on: ["network", "5xx", "429"], maxDelayMs: 5000 }`): on
+  a network error/timeout, a 5xx or a 429, GETs and mutations carrying an `Idempotency-Key` are
+  retried at most `attempts` more times (by default at most 3 requests), with the same key on
+  every attempt. The wait is `Retry-After` when given, otherwise exponential (250 ms,
+  500 ms…) + jitter; both are capped by `maxDelayMs`. 4xx other than 429, and responses with
+  `retryable: false` (`provider_error`, `provider_not_configured`), are not retried.
+  `timeoutMs` is per attempt.
+- Requests carry `Steward-Api-Version` and `X-Steward-Sdk: @stewardhq/sdk/<version>`
+  (observability only).
+- Web standards only (`fetch`, `crypto.randomUUID`, `AbortSignal.timeout`): the same code on
+  Node 22, on the edge and on workerd. The root entry and `./webhook/web` are run on workerd
+  with `nodejs_compat` disabled on every pack check (`scripts/check-workerd.mjs`).
+
+Administration (admin key; in-cluster, port-forward) — product settings and webhook endpoints.
+**The caller generates** the webhook secret and writes it into their own Secret; steward never
+returns the secret in any response:
 
 ```ts
 import { generateWebhookSecret } from "@stewardhq/sdk";
 
 await steward.admin.settings.update({
-  appUrl: "https://app.example.com",            // origin'i checkout dönüşüne izinli; + extraReturnOrigins
+  appUrl: "https://app.example.com",            // its origin is allowed for the checkout return; + extraReturnOrigins
   privacyUrl: "https://app.example.com/kvkk",
-  branding: { name: "Acme", accentColor: "#0f766e" }, // sığ birleşir; alanı null temizler
+  branding: { name: "Acme", accentColor: "#0f766e" }, // shallow merge; null clears a field
   checkoutTtlMinutes: 30,
 });
 
-const secret = generateWebhookSecret();          // whsec_ + 32 rastgele bayt
+const secret = generateWebhookSecret();          // whsec_ + 32 random bytes
 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
+// without eventTypes, ["account.state_changed"]; the address must be https:// or http://*.svc.cluster.local
+await steward.admin.endpoints.rotate(endpoint.id, { secret: generateWebhookSecret() }); // the old secret stays as a second signature during the transition
 ```
 
-Kurulum teşhisi — ürün anahtarı yeter; ilk checkout'tan önce `ok: true` beklenir:
+Setup diagnostics — the product key is enough; expect `ok: true` before the first checkout:
 
 ```ts
 const report = await steward.doctor();
-// report.ok: `error` önemde uyarı yok
+// report.ok: no warning at `error` severity
 // 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.endpoints[].diagnosis: ok | wrong_secret (last delivery 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.
+The codes and diagnoses are an open set (display an unknown one, nothing more).
+`provider.healthy` and `lastError` are the observation of the steward pod that answered.
 
-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):
+Catalog — a typed definition in code; a missing or extra entitlement, a wrong type (`limit` →
+an integer or `null` = unlimited, `flag` → boolean, `text` → string) and a price for an
+undefined plan are compile errors, and if the types are bypassed the definition throws
+`StewardConfigError` immediately (TypeScript ≥ 5.4):
 
 ```ts
 import { defineCatalog, flag, limit } from "@stewardhq/sdk";
@@ -293,139 +305,186 @@ export const catalog = defineCatalog({
   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ı)
+await steward.admin.catalog.sync(catalog.toSyncInput()); // with the admin key (a CLI/deploy step)
 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)
+// a full AccountState: version 0, updatedAt 1970, catalogVersion null, the plan's entitlements, no subscription or open checkout,
+// profile { present: false }; without a plan, the default plan (for a stateCache fallback)
 ```
 
-`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ı.
+For a missing key or one whose type does not match, `resolve` takes the value from the
+snapshot's plan (or, if that plan is not in the catalog, from the default plan) and never
+produces "unlimited"; `onFallback` can raise an alarm. Without a snapshot, the default plan's
+entitlements.
 
-Hatalar — ürün API'sinin durum kodu:
+Benefits (billing core) — reusable definitions plans list by code; `rank` is optional (the
+benefits resolution does not read it). A `featureFlag()` sets catalog features with their
+types; an undefined benefit or feature key and a wrong value type do not compile:
 
 ```ts
-import { httpStatusFor, StewardError } from "@stewardhq/sdk";
+import { defineCatalog, featureFlag, flag, limit } 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 }, { status, headers });
-}
+export const catalog = defineCatalog({
+  defaultPlan: "free",
+  features: { max_projects: limit(), sso: flag() },
+  benefits: { sso: featureFlag({ sso: true }, { description: { tr: "Tek oturum açma", en: "Single sign-on" } }) },
+  plans: {
+    free: { name: "Free", sellable: false, entitlements: { max_projects: 1, sso: false } },
+    team: { name: "Team", sellable: true, entitlements: { max_projects: null, sso: false }, benefits: ["sso"] },
+  },
+  prices: [{ plan: "team", interval: "month", currency: "TRY", amountMinor: 125_000, taxInclusive: true, taxRateBps: 2000 }],
+});
+type BenefitCode = typeof catalog.$benefit;           // "sso"
+const { benefits } = await state.state(orgId);        // [{ code, type, properties, source, grantedAt }]; code typed
 ```
 
-Tabloda olmayan kod `category`'ye göre eşlenir (`not_found` 404, `conflict` 409,
-`provider` 502, `unavailable` 503; `validation`/`config` 500 + ERROR log).
-Kullanıcıya gösterilen metin ürünündür (`error.code` → kendi i18n'iniz); `error.message`
-log içindir (steward'ın mesajı, yoksa kod). Fiyat gösterimi hosted checkout/portal
-sayfalarındadır; SDK para biçimlendirme yardımcısı taşımaz.
+`entitlementsOf`, `resolve` and `stateOf` take a plan's entitlements from the contract's
+resolver (`resolveEntitlements`), the rule steward applies. `steward catalog push` sends a
+catalog with benefits only to a steward whose `me().capabilities` lists `"benefits"`.
 
-Doğrulayıcılar: `isValidTckn`, `isValidVkn` (sağlama hanesi), `isE164(value, {country: "TR"}?)`
-değeri olduğu gibi denetler (boşluk kırpmaz).
+`Webhooks()` gains `onInvoicePaid` (`invoice.paid`) and `onBenefitGranted` / `onBenefitRevoked`
+(`benefit_grant.created` / `.revoked`, with `benefit` and `grantId`; list these types in the
+endpoint's `eventTypes`); like every hook they get the live `state`. Invoices and subscriptions
+(billing core): `steward.invoices.createPaymentSession(id, { locale?, returnUrl? })` → `{ id, url,
+expiresAt }` (redirect to steward's pay page), `steward.invoices.waive(id, { reason })`,
+`steward.subscriptions.change(id, { planCode?, interval?, price?: "current", when: "next_period" })`,
+`steward.subscriptions.uncancel(id)`.
 
-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:
+Metering (phase 2) — the product records WHAT HAPPENED as events; catalog meters (a saved filter
++ an aggregation) decide what counts as usage; credits are `meterCredit()` benefits; a metered
+price bills overage on the renewal invoice. Units may be decimals (≤ 6 places; the SDK computes in
+micro units, never float math):
 
 ```ts
-import { createFakeSteward, signedEvent } from "@stewardhq/sdk/testing";
+import { count, defineCatalog, Events, meter, meterCredit, Meters, sum } from "@stewardhq/sdk";
 
-const fake = createFakeSteward({
-  catalog,                                             // oluşturmada senkronlanır
-  webhook: { secret },                                 // eventTypes verilmezse ["account.state_changed"]; "legacy" = 15 eski tip
+export const catalog = defineCatalog({
+  defaultPlan: "free",
+  features: { max_projects: limit(), sso: flag() },
+  benefits: { tokens_50k: meterCredit("ai_tokens", { units: 50_000 }), tokens_2m: meterCredit("ai_tokens", { units: 2_000_000, rollover: { capUnits: 1_000_000 } }) },
+  meters: {
+    ai_tokens: meter({ event: "ai.completion", aggregate: sum("tokens"), label: { tr: "AI token", en: "AI tokens" } }),
+    api_calls: meter({ aggregate: count(), label: { tr: "API isteği", en: "API requests" },
+      filter: { and: [{ name: "api.request" }, { "metadata.status": { lt: 500 } }] } }),
+  },
+  plans: { free: { …, benefits: ["tokens_50k"] }, team: { …, benefits: ["tokens_2m"] } },
+  prices: [{ plan: "team", interval: "month", currency: "TRY", amountMinor: 125_000, taxInclusive: true, taxRateBps: 2000 }],
+  meteredPrices: [{ plan: "team", meter: "ai_tokens", currency: "TRY", amountMinor: 1_250, perUnits: 1_000, taxInclusive: true, taxRateBps: 2000 }],
 });
-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", notificationEmails: ["owner@acme.com"] }); // billing email recipients (optional)
-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 });
-fake.simulate.redeliver(eventId);                      // operatörün pod CLI `redeliver-event`'i: aynı event sonraki flush'ta yeniden
-
-fake.emails("org_1");                                  // billing emails steward would send: [{ template, to, locale, eventId, … }]
-
-const { request } = signedEvent("subscription.renewed", { accountRef: "org_1" }, { secret });
-await webhooks.handle(request());
+type Meter = typeof catalog.$meter;   // "ai_tokens" | "api_calls"
+type Event = typeof catalog.$event;   // "ai.completion" (the `event` shorthands)
+
+export const events = Events({ steward, catalog, actorRef: "service:api" });
+export const meters = Meters({ steward, catalog, cache: state, events });
+
+const gate = await meters.check(org.id, "ai_tokens", { units: estimatedTokens });
+if (!gate.allowed) return c.json({ error: "credits_exhausted", balance: gate.balance }, 402);
+events.track(org.id, "ai.completion", { tokens: 1500, model: "gpt-4o" }, { externalId: `cmpl_${res.id}` });
+process.once("SIGTERM", () => void events.flush());   // the SDK never hooks process events
 ```
 
-`fake.requests` gelen istekleri, `fake.events(ref?)` yayınlanan event'leri tutar. `fake.emails(ref?)`
-steward'ın göndereceği faturalandırma e-postalarını servisle aynı kurallarla (şablon, gönderim anındaki
-alaka, alıcılar, dil, kapatılmış şablon) listeler; içerik render edilmez ve gönderim gecikmesizdir
-([e-postalar](../docs/integrate/emails.md#test)). 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
-`successUrl`/`cancelUrl`/`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.
-
-## `@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` `createSteward` (fırlatan; fırlatmayan `createBillingClient` dışa açılmaz) |
-| `@z9cloud/steward-contract/webhook` | `@stewardhq/sdk/webhook` |
-| `@z9cloud/steward-contract/fixtures/events/*.json` | `@stewardhq/sdk/testing/fixtures/events/*.json` |
-| `getEntitlements(ref)` / `accounts.entitlements(ref)` | `accounts.state(ref)` ya da `stateCache` (tek okuma modeli `AccountState`; uç 2026-09-16'da kaldırıldı) |
-| `listEvents` / `redeliverEvent` / `events.*` | Yok (2026-09-16): kaçırılan durum için `accounts.resync(ref)`; dead teslimatı operatör pod CLI `redeliver-event` ile yeniden gönderir (testte `fake.simulate.redeliver`) |
+- `Events({ steward, catalog?, actorRef?, flushIntervalMs = 2000, maxBatch = 500, maxQueue = 10_000,
+  autoFlush = true, onRejected?, onDrop? })`: `track(ref, name, metadata?, { externalId?, timestamp? })`
+  is sync and never throws (an invalid event → WARN + `onDrop`); batches go to `POST
+  /v1/events/ingest` with one `Idempotency-Key` per batch, reused by every retry (`503
+  events_backlog` included); after the retries the batch waits at the front of the queue (backoff
+  ≤ 30 s); a full queue hands its OLDEST events to `onDrop(events, { reason: "queue_full" })`, an
+  invalid event and a batch refused for good (4xx) go there too (`"invalid_event"`,
+  `"request_failed"`); per-event rejections go to `onRejected(rejected)` (not retried). `track`
+  stamps `timestamp` with the call's time unless given. Give a deterministic `externalId`
+  (`cmpl_<id>`): the generated UUID only protects against the SDK's own retries. On the edge:
+  `Events({ autoFlush: false })` + `ctx.waitUntil(events.flush())`; `flush()` never rejects (what
+  failed stays queued). `ingest(events, { idempotencyKey? })` sends directly and throws;
+  `pending(ref)` lists the account's events steward has not counted yet (queued, in flight, acked in
+  the last minute) — `Meters({ events })` subtracts them.
+- `Meters({ steward, catalog, cache?, events?, ttlMs = 10_000, staleIfErrorMs = 600_000,
+  onUnavailable = "allow", onFallback? })`: `get(ref)` (every meter, `Record<Meter, MeterBalance>`),
+  `balance(ref, meter)`, `check(ref, meter, { units = 1 })` → `{ allowed, balance, standing,
+  billable, source }` with `allowed = billable ? !capReached : includedUnits === null || balance −
+  pending ≥ units` (a billable meter closes once steward reports its period overage reached the
+  rate's `capMinor`). Reads are cached (ETag/304); this process's queued (and not yet rolled up) events are
+  subtracted; when steward is unreachable the stale value is used for 10 min, then the catalog's
+  default-plan credit (or the account's coarse facts from `cache`) and `onUnavailable` decide.
+- `stateOf()` carries the `meters` block when the catalog has meters; `Webhooks()` gains
+  `onMeterThreshold` (standing `ok → low → exhausted`, also as the cause of
+  `account.state_changed`), `onMeterPeriodClosed` (with `period`) and `onBenefitCycled`
+  (`benefit_grant.cycled`). `steward.events.ingest`, `steward.meters.get/read/periods`,
+  `steward.credits.grant`, `steward.meterCharges.list` are the raw calls. Push a catalog with
+  meters only to a steward whose `me().capabilities` lists `"meters"` (an older one drops them).
+
+Errors — the product API's status code:
 
-GitHub Packages `.npmrc` satırı ve Docker `--secret` bağlaması artık gerekmez.
+```ts
+import { httpStatusFor, StewardError } from "@stewardhq/sdk";
 
-## Sürümleme
+if (error instanceof StewardError) {
+  const { status, headers } = httpStatusFor(error, { logger }); // already_subscribed 409, rate_limited 503 + Retry-After…
+  return Response.json({ error: error.code }, { status, headers });
+}
+```
+
+A code that is not in the table is mapped by `category` (`not_found` 404, `conflict` 409,
+`provider` 502, `unavailable` 503; `validation`/`config` 500 + an ERROR log). The text shown to
+the user is the product's (`error.code` → your own i18n); `error.message` is for logs
+(steward's message, or the code if there is none). Price display lives on the hosted checkout
+and portal pages; the SDK carries no currency formatting helper.
 
-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`).
+Validators: `isValidTckn`, `isValidVkn` (checksum digit) and `isE164(value, {country: "TR"}?)`
+check the value as-is (no whitespace trimming).
+
+## Removed APIs
+
+| Old | New |
+| --- | --- |
+| `@stewardhq/sdk/testing` (`signedEvent`, `createFakeSteward`) | Gone (0.4.0): write integration tests against the service, or stub `fetch` |
+| `getEntitlements(ref)` / `accounts.entitlements(ref)` | `accounts.state(ref)` or `stateCache` (the single read model `AccountState`; the endpoint was removed on 2026-09-16) |
+| `listEvents` / `redeliverEvent` / `events.*` | Gone (2026-09-16): for missed state use `accounts.resync(ref)`; an operator redelivers a dead delivery with the pod CLI's `redeliver-event` |
+
+## Versioning
+
+Semver. Removing or renaming a field is breaking (major; before 1.0, minor). Release: bump the
+version in `sdk/package.json` and push the `sdk-v<version>` tag
+(`.github/workflows/sdk-publish.yml`). **The first version on npmjs is 0.5.0** (2026-09-21);
+0.4.0 stayed inside the repository and was never published.
+
+**0.6.0** (contract 0.5.0, bank transfer F1; additive; `API_VERSION` `2026-10-01` unchanged):
+
+- `Checkout().create({ replacesSubscriptionId })`: an upgrade that replaces the live subscription only
+  when the payment is recorded (do not cancel it before the checkout); `result()` adds `paymentMethod`.
+- State: `openCheckout.paymentMethod` (`bank_transfer` while the order waits for a transfer) and
+  `bankTransferCode`; `subscription.activated` detail `replacedSubscriptionId`; `CheckoutSession`
+  `paymentMethod` / `replacesSubscriptionId`.
+- Settings: `billing.bankTransfer` (`enabled`, `paymentDays`); email template `bank_transfer_instructions`.
+- Admin: `BankTransferRecordInputSchema` / `BankTransferRecordedSchema` (`POST /v1/admin/bank-transfers`;
+  a transfer completes a checkout or pays an unpaid invoice, `checkoutSessionId` / `invoiceId`);
+  error codes `replaces_subscription_invalid`, `bank_transfer_*`.
+- State change cause `bank_transfer.code_assigned` (the account chose bank transfer on the invoice pay page).
+
+**0.5.0** (contract 0.4.0, metering phase 2; additive; `API_VERSION` `2026-10-01` unchanged):
+
+- Catalog: `meters` + `meter()`, `count()` / `sum(key)` / `max(key)` / `unique(key)`, `meterCredit()`
+  benefits, `meteredPrices`; `typeof catalog.$meter` / `$event`; `stateOf()` adds `meters`.
+- `Events()` (`track`, `flush`, `ingest`, `pending`; `onRejected`, `onDrop(events, {reason})`) and `Meters()`
+  (`get`, `balance` → `MeterBalance`, `check`, `invalidate`) in the root entry, no `node:*`; `stateCache().peek(ref)`.
+- Client: `events.ingest`, `meters.get/read/periods`, `credits.grant`, `meterCharges.list`.
+- Hooks: `onMeterThreshold`, `onMeterPeriodClosed` (+ `period`), `onBenefitCycled`.
+
+**0.4.0** (contract 0.3.0, billing core phase 1; `API_VERSION` `2026-10-01` unchanged):
+
+- Breaking (0.x minor): the `@stewardhq/sdk/testing` subpath (`signedEvent`, the fixtures, the
+  fake steward) was removed; tests are written against the real service or a `fetch` stub.
+- Catalog: `benefits` + `featureFlag()`, `plans[].benefits`, `typeof catalog.$benefit`;
+  `PlanSpec.rank` is optional and is not read during entitlement resolution (a union of layers,
+  the contract's `resolveBenefits`).
+- State: `AccountState.benefits`, `subscriptions[]` (the singular `subscription` is the primary
+  subscription), `openInvoices[]`; `amountMinor` on a subscription is the amount that
+  subscription locked.
+- Events (when requested in the endpoint's `eventTypes`): `invoice.paid`,
+  `benefit_grant.created/updated/revoked`; the hooks `onInvoicePaid`, `onBenefitGranted`,
+  `onBenefitRevoked` (and `onBenefitGrantCreated/Updated/Revoked` derived from the type).
+- Client: `invoices.createPaymentSession`, `invoices.waive`, `subscriptions.change`,
+  `subscriptions.uncancel`; `capabilities` in the `me()` response.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).