@stewardhq/sdk 0.2.0 → 0.5.0

package/README.md

@@ -17,13 +17,11 @@ ESM, Node ≥ 22. Tek çalışma zamanı bağımlılığı zod.
 
 | Import | İçerik |
 | --- | --- |
-| `@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` | Tüm şema/tipler + fırlatan istemci `createSteward`, hesap durumu önbelleği `stateCache`, `defineCatalog`, hata sınıfları + `httpStatusFor`, `isValidTckn`/`isValidVkn`/`isE164`; metering: `Events()`, `Meters()` |
 | `@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.
@@ -304,6 +302,101 @@ 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ı.
 
+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 { defineCatalog, featureFlag, flag, limit } from "@stewardhq/sdk";
+
+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
+```
+
+`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"`.
+
+`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)`.
+
+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 { count, defineCatalog, Events, meter, meterCredit, Meters, sum } from "@stewardhq/sdk";
+
+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 }],
+});
+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
+```
+
+- `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).
+
 Hatalar — ürün API'sinin durum kodu:
 
 ```ts
@@ -324,88 +417,6 @@ sayfalarındadır; SDK para biçimlendirme yardımcısı taşımaz.
 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ı
-(`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 });
-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());
-```
-
-`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
-`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 |
@@ -413,9 +424,10 @@ siparişi başarılı sayar (`subscription.reactivated`), `{fail: true}` yine ba
 | `@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` |
+| `@z9cloud/steward-contract/fixtures/events/*.json` | Yok (paketle yayınlanmaz) |
+| `@stewardhq/sdk/testing` (`signedEvent`, `createFakeSteward`) | Yok (0.4.0): servise karşı entegrasyon testi ya da `fetch` saplaması |
 | `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`) |
+| `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 |
 
 GitHub Packages `.npmrc` satırı ve Docker `--secret` bağlaması artık gerekmez.
 
@@ -423,4 +435,27 @@ GitHub Packages `.npmrc` satırı ve Docker `--secret` bağlaması artık gerekm
 
 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).
+(`.github/workflows/sdk-publish.yml`).
+
+**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** (sözleşme 0.3.0, faturalama çekirdeği Faz 1; `API_VERSION` `2026-10-01` aynı):
+
+- Kırıcı (0.x minor): `@stewardhq/sdk/testing` alt yolu (`signedEvent`, fixture'lar, sahte steward)
+  kaldırıldı; testler gerçek servise ya da `fetch` saplamasına karşı yazılır.
+- Katalog: `benefits` + `featureFlag()`, `plans[].benefits`, `typeof catalog.$benefit`; `PlanSpec.rank`
+  isteğe bağlı ve hak çözümünde okunmaz (katman birleşimi, sözleşmenin `resolveBenefits`'i).
+- Durum: `AccountState.benefits`, `subscriptions[]` (tekil `subscription` birincil abonelik),
+  `openInvoices[]`; abonelikteki `amountMinor` aboneliğin kilitli tutarıdır.
+- Olaylar (endpoint'in `eventTypes`'ında istenirse): `invoice.paid`, `benefit_grant.created/updated/revoked`;
+  hook'lar `onInvoicePaid`, `onBenefitGranted`, `onBenefitRevoked` (ve tipten türeyen
+  `onBenefitGrantCreated/Updated/Revoked`).
+- İstemci: `invoices.createPaymentSession`, `invoices.waive`, `subscriptions.change`,
+  `subscriptions.uncancel`; `me()` yanıtında `capabilities`.

package/dist/_chunks/errors.js

@@ -1,4 +1,4 @@
-import { R as errorCodeSpec } from "./src.js";
+import { nt as errorCodeSpec } from "./src.js";
 //#region src/errors.ts
 var StewardError = class extends Error {
 	code;