@stewardhq/sdk 0.1.0-rc.0 → 0.2.0

package/README.md

@@ -17,7 +17,7 @@ ESM, Node ≥ 22. Tek çalışma zamanı bağımlılığı zod.
 
 | 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` | 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ı) |
@@ -127,7 +127,7 @@ 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.
+  // steward yalnızca onları doldurur; yoksa adres aynen kullanılır (parametre eklenmez).
   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ı)
@@ -155,9 +155,8 @@ app.get("/v1/orgs/:orgId/billing/checkout/:id", async (c) =>          // dönü
 | 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).
+ü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
@@ -211,22 +210,20 @@ await steward.grants.create(accountRef, { planCode: "team", reason: "kurumsal s
 
 | 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) |
+| `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) |
 | `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.
+  (`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ı
@@ -279,16 +276,6 @@ const report = await steward.doctor();
 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):
@@ -317,25 +304,24 @@ const placeholder = catalog.stateOf("org_1", "team", { accessState: "active", di
 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:
+Hatalar — ürün API'sinin durum kodu:
 
 ```ts
-import { httpStatusFor, messageFor, StewardError } from "@stewardhq/sdk";
+import { httpStatusFor, 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 });
+  return Response.json({ error: error.code }, { 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.
+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.
 
-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"}?)`
+Doğrulayıcılar: `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ı
@@ -378,6 +364,7 @@ await fake.simulate.renewal("org_1", { fail: true });  // saat dönem sonuna; pa
 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
 
 const { request } = signedEvent("subscription.renewed", { accountRef: "org_1" }, { secret });
 await webhooks.handle(request());
@@ -390,7 +377,7 @@ Alıcı bağlanmadan `flush`/`deliver` fırlatır (event'ler outbox'ta bekler);
 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
+`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;
@@ -419,14 +406,16 @@ sonuçlandırmaz: servisteki gibi sonuç sonradan gelir — `simulate.renewal(re
 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ş
+## `@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/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`) |
 
 GitHub Packages `.npmrc` satırı ve Docker `--secret` bağlaması artık gerekmez.
 

package/dist/_chunks/events.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 //#region ../contract/src/common.ts
 const API_VERSION = "2026-10-01";
 const CodeSchema = z.string().regex(/^[a-z][a-z0-9_]{0,62}$/, "küçük harf, rakam ve _ (harfle başlar)");
-/** Ürün tarafındaki değişmez kimlik (ör. nixscale'de ağın shortId'si). */
+/** Immutable product-side identity (e.g. the id of an org in the product). */
 const ExternalRefSchema = z.string().min(1).max(200).regex(/^[A-Za-z0-9_.:-]+$/, "yalnızca harf, rakam ve _ . : -");
 const IdSchema = z.uuid();
 const CurrencySchema = z.string().regex(/^[A-Z]{3}$/, "ISO-4217 kodu");