@stewardhq/sdk 0.3.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,93 +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", 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());
-```
-
-`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 |
@@ -418,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.
 
@@ -429,3 +436,26 @@ 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`).
+
+**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 { B as errorCodeSpec } from "./src.js";
+import { nt as errorCodeSpec } from "./src.js";
 //#region src/errors.ts
 var StewardError = class extends Error {
 	code;

package/dist/_chunks/events.d.ts

@@ -104,7 +104,10 @@ declare const AccountDunningStateSchema: z.ZodObject<{
   nextActionAt: z.ZodNullable<z.ZodISODateTime>;
 }, z.core.$strip>;
 type AccountDunningState = z.infer<typeof AccountDunningStateSchema>;
-/** Dönem sonunda uygulanacak plan değişikliği. F4b'ye kadar her zaman null. */
+/**
+ * Change applied at the period end (`POST /v1/subscriptions/:id/change`, MF9). Null until then.
+ * `price: "current"` on the same plan shows the same `planCode`/`interval` with the new `amountMinor`.
+ */
 declare const AccountScheduledChangeSchema: z.ZodObject<{
   planCode: z.ZodString;
   interval: z.ZodEnum<{
@@ -112,6 +115,7 @@ declare const AccountScheduledChangeSchema: z.ZodObject<{
     year: "year";
   }>;
   effectiveAt: z.ZodISODateTime;
+  amountMinor: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 type AccountScheduledChange = z.infer<typeof AccountScheduledChangeSchema>;
 declare const AccountSubscriptionStateSchema: z.ZodObject<{
@@ -146,6 +150,7 @@ declare const AccountSubscriptionStateSchema: z.ZodObject<{
       year: "year";
     }>;
     effectiveAt: z.ZodISODateTime;
+    amountMinor: z.ZodOptional<z.ZodNumber>;
   }, z.core.$strip>>;
 }, z.core.$strip>;
 type AccountSubscriptionState = z.infer<typeof AccountSubscriptionStateSchema>;
@@ -163,6 +168,52 @@ declare const AccountOpenCheckoutSchema: z.ZodObject<{
   expiresAt: z.ZodISODateTime;
 }, z.core.$strip>;
 type AccountOpenCheckout = z.infer<typeof AccountOpenCheckoutSchema>;
+/**
+ * An unpaid invoice of the account (billing core, M22/M34): renewal or final invoices written
+ * before payment. Account level (not under a subscription) so the final invoice of an ended
+ * subscription stays visible; the product can show a banner before `dueAt`.
+ */
+declare const AccountOpenInvoiceSchema: z.ZodObject<{
+  id: z.ZodUUID;
+  subscriptionId: z.ZodNullable<z.ZodUUID>;
+  billingReason: z.ZodEnum<{
+    subscription_create: "subscription_create";
+    subscription_cycle: "subscription_cycle";
+    subscription_update: "subscription_update";
+    purchase: "purchase";
+    manual: "manual";
+  }>;
+  totalMinor: z.ZodNumber;
+  currency: z.ZodString;
+  dueAt: z.ZodISODateTime;
+}, z.core.$strip>;
+type AccountOpenInvoice = z.infer<typeof AccountOpenInvoiceSchema>;
+/**
+ * Low-churn meter facts of the account state (metering, M13; Polar `active_meters`, coarse). One
+ * entry per catalog meter. Balances and period bounds are NOT here (they change with every event;
+ * read them with `GET /v1/accounts/:ref/meters`): this block changes when the plan changes, a
+ * threshold is crossed or a new period resets the standing — never per event.
+ */
+declare const AccountMeterStateSchema: z.ZodObject<{
+  includedUnits: z.ZodNullable<z.ZodNumber>;
+  billable: z.ZodBoolean;
+  standing: z.ZodEnum<{
+    ok: "ok";
+    low: "low";
+    exhausted: "exhausted";
+  }>;
+}, z.core.$strip>;
+type AccountMeterState = z.infer<typeof AccountMeterStateSchema>;
+declare const AccountMetersStateSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+  includedUnits: z.ZodNullable<z.ZodNumber>;
+  billable: z.ZodBoolean;
+  standing: z.ZodEnum<{
+    ok: "ok";
+    low: "low";
+    exhausted: "exhausted";
+  }>;
+}, z.core.$strip>>;
+type AccountMetersState = z.infer<typeof AccountMetersStateSchema>;
 /** Fatura profili özeti: yalnızca var mı ve türü (alanlar PII, burada yok). */
 declare const AccountProfileStateSchema: z.ZodObject<{
   present: z.ZodBoolean;
@@ -216,6 +267,7 @@ declare const AccountStateSchema: z.ZodObject<{
         year: "year";
       }>;
       effectiveAt: z.ZodISODateTime;
+      amountMinor: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
   }, z.core.$strip>>;
   openCheckout: z.ZodNullable<z.ZodObject<{
@@ -237,6 +289,71 @@ declare const AccountStateSchema: z.ZodObject<{
       company: "company";
     }>>;
   }, z.core.$strip>;
+  subscriptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodUUID;
+    status: z.ZodEnum<{
+      active: "active";
+      suspended: "suspended";
+      past_due: "past_due";
+      canceled: "canceled";
+      expired: "expired";
+    }>;
+    planCode: z.ZodString;
+    interval: z.ZodEnum<{
+      month: "month";
+      year: "year";
+    }>;
+    amountMinor: z.ZodNumber;
+    currency: z.ZodString;
+    currentPeriodEnd: z.ZodNullable<z.ZodISODateTime>;
+    cancelAt: z.ZodNullable<z.ZodISODateTime>;
+    cancelAtPeriodEnd: z.ZodBoolean;
+    pastDueSince: z.ZodNullable<z.ZodISODateTime>;
+    currentPeriodStart: z.ZodNullable<z.ZodISODateTime>;
+    dunning: z.ZodNullable<z.ZodObject<{
+      step: z.ZodNumber;
+      nextActionAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+    scheduledChange: z.ZodNullable<z.ZodObject<{
+      planCode: z.ZodString;
+      interval: z.ZodEnum<{
+        month: "month";
+        year: "year";
+      }>;
+      effectiveAt: z.ZodISODateTime;
+      amountMinor: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>>;
+  openInvoices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodUUID;
+    subscriptionId: z.ZodNullable<z.ZodUUID>;
+    billingReason: z.ZodEnum<{
+      subscription_create: "subscription_create";
+      subscription_cycle: "subscription_cycle";
+      subscription_update: "subscription_update";
+      purchase: "purchase";
+      manual: "manual";
+    }>;
+    totalMinor: z.ZodNumber;
+    currency: z.ZodString;
+    dueAt: z.ZodISODateTime;
+  }, z.core.$strip>>>;
+  benefits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    code: z.ZodNullable<z.ZodString>;
+    type: z.ZodString;
+    properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    source: z.ZodString;
+    grantedAt: z.ZodISODateTime;
+  }, z.core.$strip>>>;
+  meters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    includedUnits: z.ZodNullable<z.ZodNumber>;
+    billable: z.ZodBoolean;
+    standing: z.ZodEnum<{
+      ok: "ok";
+      low: "low";
+      exhausted: "exhausted";
+    }>;
+  }, z.core.$strip>>>;
 }, z.core.$strip>;
 type AccountState = z.infer<typeof AccountStateSchema>;
 declare const AccountSchema: z.ZodObject<{
@@ -327,6 +444,7 @@ declare const EVENT_DETAIL_SCHEMAS: {
     paymentId: z.ZodNullable<z.ZodUUID>;
     attempt: z.ZodNumber;
     nextRetryAt: z.ZodNullable<z.ZodISODateTime>;
+    invoiceId: z.ZodOptional<z.ZodUUID>;
     subscriptionId: z.ZodUUID;
   }, z.core.$strip>;
   readonly "subscription.suspended": z.ZodObject<{
@@ -386,6 +504,94 @@ declare const EVENT_DETAIL_SCHEMAS: {
     deletedAt: z.ZodISODateTime;
     actorRef: z.ZodNullable<z.ZodString>;
   }, z.core.$strip>;
+  readonly "invoice.paid": z.ZodObject<{
+    invoiceId: z.ZodUUID;
+    subscriptionId: z.ZodNullable<z.ZodUUID>;
+    paymentId: z.ZodUUID;
+    billingReason: z.ZodNullable<z.ZodEnum<{
+      subscription_create: "subscription_create";
+      subscription_cycle: "subscription_cycle";
+      subscription_update: "subscription_update";
+      purchase: "purchase";
+      manual: "manual";
+    }>>;
+    totalMinor: z.ZodNumber;
+    currency: z.ZodString;
+    paidAt: z.ZodISODateTime;
+  }, z.core.$strip>;
+  readonly "benefit_grant.created": z.ZodObject<{
+    grantId: z.ZodUUID;
+    benefit: z.ZodObject<{
+      code: z.ZodNullable<z.ZodString>;
+      type: z.ZodString;
+      properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      source: z.ZodString;
+      grantedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+  }, z.core.$strip>;
+  readonly "benefit_grant.updated": z.ZodObject<{
+    previousProperties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    grantId: z.ZodUUID;
+    benefit: z.ZodObject<{
+      code: z.ZodNullable<z.ZodString>;
+      type: z.ZodString;
+      properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      source: z.ZodString;
+      grantedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+  }, z.core.$strip>;
+  readonly "benefit_grant.revoked": z.ZodObject<{
+    revokedAt: z.ZodISODateTime;
+    grantId: z.ZodUUID;
+    benefit: z.ZodObject<{
+      code: z.ZodNullable<z.ZodString>;
+      type: z.ZodString;
+      properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      source: z.ZodString;
+      grantedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+  }, z.core.$strip>;
+  readonly "benefit_grant.cycled": z.ZodObject<{
+    periodStart: z.ZodISODateTime;
+    periodEnd: z.ZodISODateTime;
+    grantId: z.ZodUUID;
+    benefit: z.ZodObject<{
+      code: z.ZodNullable<z.ZodString>;
+      type: z.ZodString;
+      properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      source: z.ZodString;
+      grantedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+  }, z.core.$strip>;
+  readonly "meter.threshold_crossed": z.ZodObject<{
+    meter: z.ZodString;
+    standing: z.ZodEnum<{
+      ok: "ok";
+      low: "low";
+      exhausted: "exhausted";
+    }>;
+    previous: z.ZodEnum<{
+      ok: "ok";
+      low: "low";
+      exhausted: "exhausted";
+    }>;
+    periodStart: z.ZodISODateTime;
+    periodEnd: z.ZodISODateTime;
+    consumedUnits: z.ZodNumber;
+    creditedUnits: z.ZodNumber;
+  }, z.core.$strip>;
+  readonly "meter.period_closed": z.ZodObject<{
+    periodStart: z.ZodISODateTime;
+    periodEnd: z.ZodISODateTime;
+    subscriptionId: z.ZodNullable<z.ZodUUID>;
+    meters: z.ZodArray<z.ZodObject<{
+      meter: z.ZodString;
+      consumedUnits: z.ZodNumber;
+      creditedUnits: z.ZodNumber;
+      overageUnits: z.ZodNumber;
+    }, z.core.$strip>>;
+    meterChargeId: z.ZodNullable<z.ZodUUID>;
+  }, z.core.$strip>;
 };
 type EventType = keyof typeof EVENT_DETAIL_SCHEMAS;
 /** Tüm event tipleri (yenileri dahil). */
@@ -397,9 +603,11 @@ declare const EVENT_TYPES: EventType[];
 declare const LEGACY_EVENT_TYPES: readonly ["account.updated", "checkout.completed", "checkout.failed", "checkout.expired", "subscription.activated", "subscription.renewed", "subscription.payment_failed", "subscription.suspended", "subscription.reactivated", "subscription.cancel_scheduled", "subscription.canceled", "subscription.expired", "subscription.terminated", "invoice.created", "invoice.issued"];
 type LegacyEventType = (typeof LEGACY_EVENT_TYPES)[number];
 /** `account.state_changed.detail.cause` — bilinen değerler; küme açık. */
-type AccountStateChangeCause = LegacyEventType | "account.upserted" | "billing_profile.updated" | "checkout.opened" | "checkout.initialize_failed" | "checkout.canceled" | "grant.created" | "grant.revoked" | "grant.window_applied" | "dunning.advanced" | "dunning_policy.updated" | "payment.recorded" | "catalog.synced" | "account.refreshed" | "grant.plan_set" | "resync" | "account.deleted" | (string & Record<never, never>);
-type FullStateEventType = "account.state_changed" | "account.deleted";
+type AccountStateChangeCause = LegacyEventType | "account.upserted" | "billing_profile.updated" | "checkout.opened" | "checkout.initialize_failed" | "checkout.canceled" | "grant.created" | "grant.revoked" | "grant.window_applied" | "dunning.advanced" | "dunning_policy.updated" | "payment.recorded" | "catalog.synced" | "account.refreshed" | "grant.plan_set" | "resync" | "account.deleted" | "invoice.paid" | "subscription.period_advanced" | "subscription.uncanceled" | "subscription.change_scheduled" | "invoice.waived" | "invoice.payment_reminder" | "meter.threshold_crossed" | "meter.period_rolled" | "credits.granted" | (string & Record<never, never>);
+type FullStateEventType = "account.state_changed" | "account.deleted" | "invoice.paid" | "benefit_grant.created" | "benefit_grant.updated" | "benefit_grant.revoked" | "benefit_grant.cycled" | "meter.threshold_crossed" | "meter.period_closed";
 type AccountSchemaOf<T extends EventType> = T extends FullStateEventType ? typeof AccountStateSchema : typeof EntitlementSnapshotSchema;
+/** Event types whose `data.account` is the full `AccountState` (the others: the entitlement snapshot). */
+declare const FULL_STATE_EVENT_TYPES: ReadonlySet<string>;
 declare function envelope<T extends EventType>(type: T): z.ZodObject<{
   id: z.ZodString;
   type: z.ZodLiteral<T>;
@@ -446,6 +654,7 @@ declare function envelope<T extends EventType>(type: T): z.ZodObject<{
         paymentId: z.ZodNullable<z.ZodUUID>;
         attempt: z.ZodNumber;
         nextRetryAt: z.ZodNullable<z.ZodISODateTime>;
+        invoiceId: z.ZodOptional<z.ZodUUID>;
         subscriptionId: z.ZodUUID;
       }, z.core.$strip>;
       readonly "subscription.suspended": z.ZodObject<{
@@ -505,6 +714,94 @@ declare function envelope<T extends EventType>(type: T): z.ZodObject<{
         deletedAt: z.ZodISODateTime;
         actorRef: z.ZodNullable<z.ZodString>;
       }, z.core.$strip>;
+      readonly "invoice.paid": z.ZodObject<{
+        invoiceId: z.ZodUUID;
+        subscriptionId: z.ZodNullable<z.ZodUUID>;
+        paymentId: z.ZodUUID;
+        billingReason: z.ZodNullable<z.ZodEnum<{
+          subscription_create: "subscription_create";
+          subscription_cycle: "subscription_cycle";
+          subscription_update: "subscription_update";
+          purchase: "purchase";
+          manual: "manual";
+        }>>;
+        totalMinor: z.ZodNumber;
+        currency: z.ZodString;
+        paidAt: z.ZodISODateTime;
+      }, z.core.$strip>;
+      readonly "benefit_grant.created": z.ZodObject<{
+        grantId: z.ZodUUID;
+        benefit: z.ZodObject<{
+          code: z.ZodNullable<z.ZodString>;
+          type: z.ZodString;
+          properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+          source: z.ZodString;
+          grantedAt: z.ZodISODateTime;
+        }, z.core.$strip>;
+      }, z.core.$strip>;
+      readonly "benefit_grant.updated": z.ZodObject<{
+        previousProperties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        grantId: z.ZodUUID;
+        benefit: z.ZodObject<{
+          code: z.ZodNullable<z.ZodString>;
+          type: z.ZodString;
+          properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+          source: z.ZodString;
+          grantedAt: z.ZodISODateTime;
+        }, z.core.$strip>;
+      }, z.core.$strip>;
+      readonly "benefit_grant.revoked": z.ZodObject<{
+        revokedAt: z.ZodISODateTime;
+        grantId: z.ZodUUID;
+        benefit: z.ZodObject<{
+          code: z.ZodNullable<z.ZodString>;
+          type: z.ZodString;
+          properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+          source: z.ZodString;
+          grantedAt: z.ZodISODateTime;
+        }, z.core.$strip>;
+      }, z.core.$strip>;
+      readonly "benefit_grant.cycled": z.ZodObject<{
+        periodStart: z.ZodISODateTime;
+        periodEnd: z.ZodISODateTime;
+        grantId: z.ZodUUID;
+        benefit: z.ZodObject<{
+          code: z.ZodNullable<z.ZodString>;
+          type: z.ZodString;
+          properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+          source: z.ZodString;
+          grantedAt: z.ZodISODateTime;
+        }, z.core.$strip>;
+      }, z.core.$strip>;
+      readonly "meter.threshold_crossed": z.ZodObject<{
+        meter: z.ZodString;
+        standing: z.ZodEnum<{
+          ok: "ok";
+          low: "low";
+          exhausted: "exhausted";
+        }>;
+        previous: z.ZodEnum<{
+          ok: "ok";
+          low: "low";
+          exhausted: "exhausted";
+        }>;
+        periodStart: z.ZodISODateTime;
+        periodEnd: z.ZodISODateTime;
+        consumedUnits: z.ZodNumber;
+        creditedUnits: z.ZodNumber;
+      }, z.core.$strip>;
+      readonly "meter.period_closed": z.ZodObject<{
+        periodStart: z.ZodISODateTime;
+        periodEnd: z.ZodISODateTime;
+        subscriptionId: z.ZodNullable<z.ZodUUID>;
+        meters: z.ZodArray<z.ZodObject<{
+          meter: z.ZodString;
+          consumedUnits: z.ZodNumber;
+          creditedUnits: z.ZodNumber;
+          overageUnits: z.ZodNumber;
+        }, z.core.$strip>>;
+        meterChargeId: z.ZodNullable<z.ZodUUID>;
+      }, z.core.$strip>;
     }[T];
   }, z.core.$strip>;
 }, z.core.$strip>;
@@ -548,4 +845,4 @@ declare const PingSchema: z.ZodObject<{
 }, z.core.$strip>;
 type Ping = z.infer<typeof PingSchema>;
 //#endregion
-export { AccountOpenCheckoutSchema as A, AccountUpsertInput as B, AccountDeleteResponse as C, AccountInclude as D, AccountDunningStateSchema as E, AccountSchema as F, BillingProfileSchema as G, BillingProfile as H, AccountState as I, SubscriptionStatus as J, EntitlementSnapshot as K, AccountStateSchema as L, AccountProfileStateSchema as M, AccountScheduledChange as N, AccountLocaleSchema as O, AccountScheduledChangeSchema as P, AccountSubscriptionState as R, Account as S, AccountDunningState as T, BillingProfileInput as U, AccountUpsertInputSchema as V, BillingProfileKindSchema as W, SubscriptionSummary as X, SubscriptionStatusSchema as Y, SubscriptionSummarySchema as Z, PingSchema as _, BillingEvent as a, AccessState as b, EVENT_DETAIL_SCHEMAS as c, EventIdSchema as d, EventType as f, Ping as g, PING_EVENT_TYPE as h, ApiVersionSchema as i, AccountProfileState as j, AccountOpenCheckout as k, EVENT_TYPES as l, LegacyEventType as m, AnyBillingEvent as n, BillingEventOf as o, LEGACY_EVENT_TYPES as p, EntitlementSnapshotSchema as q, AnyBillingEventSchema as r, BillingEventSchema as s, AccountStateChangeCause as t, EventDetail as u, isEventType as v, AccountDeleteResponseSchema as w, AccessStateSchema as x, ACCOUNT_INCLUDES as y, AccountSubscriptionStateSchema as z };
+export { EntitlementSnapshot as $, AccountMeterState as A, AccountScheduledChange as B, Account as C, AccountDunningStateSchema as D, AccountDunningState as E, AccountOpenCheckoutSchema as F, AccountSubscriptionState as G, AccountSchema as H, AccountOpenInvoice as I, AccountUpsertInputSchema as J, AccountSubscriptionStateSchema as K, AccountOpenInvoiceSchema as L, AccountMetersState as M, AccountMetersStateSchema as N, AccountInclude as O, AccountOpenCheckout as P, BillingProfileSchema as Q, AccountProfileState as R, AccessStateSchema as S, AccountDeleteResponseSchema as T, AccountState as U, AccountScheduledChangeSchema as V, AccountStateSchema as W, BillingProfileInput as X, BillingProfile as Y, BillingProfileKindSchema as Z, Ping as _, BillingEvent as a, ACCOUNT_INCLUDES as b, EVENT_DETAIL_SCHEMAS as c, EventIdSchema as d, EntitlementSnapshotSchema as et, EventType as f, PING_EVENT_TYPE as g, LegacyEventType as h, ApiVersionSchema as i, SubscriptionSummarySchema as it, AccountMeterStateSchema as j, AccountLocaleSchema as k, EVENT_TYPES as l, LEGACY_EVENT_TYPES as m, AnyBillingEvent as n, SubscriptionStatusSchema as nt, BillingEventOf as o, FULL_STATE_EVENT_TYPES as p, AccountUpsertInput as q, AnyBillingEventSchema as r, SubscriptionSummary as rt, BillingEventSchema as s, AccountStateChangeCause as t, SubscriptionStatus as tt, EventDetail as u, PingSchema as v, AccountDeleteResponse as w, AccessState as x, isEventType as y, AccountProfileStateSchema as z };