@stewardhq/sdk 0.1.0-rc.0

package/dist/testing.d.ts

@@ -0,0 +1,629 @@
+import { $t as EventRecord, Cr as CatalogSyncInput, Dr as FeatureDef, Ft as ErrorCode, Gn as PortalSessionCreateInputSchema, Gt as CancelSubscriptionResponse, Pn as GrantCreateInputSchema, Qn as CheckoutPrefill, Rn as Stats, Tr as CatalogSyncResult, Un as PortalSession, Ut as BillingProfileResponse, Vt as AccountUpsertResponse, Wr as EntitlementValue, Zt as EventList, ar as CheckoutSessionCreateParsed, cn as InvoiceIssueResponse, dr as Consent, ei as Interval, gn as InvoiceIssueInputSchema, gt as PlanSetInputSchema, jn as CancelSubscriptionInputSchema, mn as Invoice, nr as CheckoutSession, nt as ProductSettingsPatch, or as CheckoutSessionCreated, pr as LegacyCheckoutSessionCreateParsed, qt as CheckoutSessionResponse, tn as GrantCreateResponse, tt as ProductSettings, wr as CatalogSyncInputSchema, wt as ResyncResult, yr as AccountsRefreshResult, yt as PlanSetResponse, zt as AccountDetail } from "./_chunks/index.js";
+import { B as AccountUpsertInputSchema, C as AccountDeleteResponse, D as AccountInclude, F as AccountState, V as BillingProfile, a as BillingEvent, f as EventType, o as BillingEventOf, q as SubscriptionStatus, u as EventDetail } from "./_chunks/events.js";
+import { a as Steward, c as StewardOptions } from "./_chunks/steward.js";
+import { z } from "zod";
+//#endregion
+//#region src/testing/world.d.ts
+type Ms = number;
+type DunningAction = "retry_payment" | "suspend" | "terminate";
+/** Servisin `products.dunning_policy` şekli. */
+type FakeDunningPolicy = {
+  readonly steps: readonly {
+    readonly afterDays: number;
+    readonly action: DunningAction;
+  }[];
+  /** true (servisin varsayılanı): adımlar yalnızca sayılır, askı/sonlandırma yok. */
+  readonly dryRun: boolean;
+};
+/** Servisin `DEFAULT_DUNNING_POLICY` kopyası (`domain/dunning-policy.ts`). */
+export declare const DEFAULT_DUNNING_POLICY: FakeDunningPolicy;
+type PlanRow = {
+  code: string;
+  name: string;
+  rank: number;
+  sellable: boolean;
+  active: boolean;
+  entitlements: Record<string, EntitlementValue>;
+};
+type PriceRow = {
+  id: string;
+  planCode: string;
+  interval: Interval;
+  intervalCount: number;
+  currency: string;
+  amountMinor: number;
+  taxInclusive: boolean;
+  taxRateBps: number;
+  active: boolean;
+  createdAt: Ms;
+};
+type AccountRow = {
+  ref: string;
+  displayName: string;
+  metadata: Record<string, string>;
+  createdAt: Ms;
+  version: number;
+  /** Saklı durum; ilk commit'e kadar null. */
+  state: AccountState | null;
+  /** Yazılan her durum (version sırasıyla); `simulate.deliver({outOfOrder})` eski durumu buradan alır. */
+  history: AccountState[];
+  profile: BillingProfile | null;
+  /** KVKK anonimleştirme anı (F4e, `deleteAccount`); doluysa hesap yolunun uçları 410. */
+  deletedAt?: Ms;
+};
+type SubscriptionRow = {
+  id: string;
+  accountRef: string;
+  priceId: string;
+  providerSubscriptionRef: string;
+  status: SubscriptionStatus;
+  cancelAtPeriodEnd: boolean;
+  cancelAt: Ms | null;
+  cancelReason: string | null;
+  canceledAt: Ms | null;
+  startedAt: Ms;
+  currentPeriodStart: Ms | null;
+  currentPeriodEnd: Ms | null;
+  dunningStartedAt: Ms | null;
+  pastDueSince: Ms | null;
+  dunningStep: number;
+  nextDunningAt: Ms | null;
+  /**
+   * Sağlayıcıya giden son "ödemeyi yeniden dene" (portal ya da dunning adımı). Servis bunu
+   * denetim izinden okur (`lastPaymentRetryAt`); portal sıklık sınırı (F3a) buna bakar.
+   */
+  lastPaymentRetryAt: Ms | null;
+};
+/** Hosted müşteri portalı oturumu (F3a; servisin `portal_sessions`). Satır değişmez; süresi geçince silinir. */
+type PortalSessionRow = {
+  id: string;
+  accountRef: string;
+  /** Sayfa anahtarı (`url`deki `k`; sahtede düz saklanır, servis yalnızca sha256'sını). */
+  pageKey: string;
+  locale: "tr" | "en";
+  /** "Ürüne dön"; verilmediyse null (sayfa `settings.appUrl`e döner). */
+  returnUrl: string | null;
+  actorRef: string;
+  expiresAt: Ms;
+  createdAt: Ms;
+};
+type SessionRow = {
+  id: string;
+  accountRef: string;
+  priceId: string;
+  status: CheckoutSession["status"];
+  locale: string;
+  returnUrl: string;
+  /** Hosted oturum (F2b): başarı adresi (yer tutucularıyla); eski gövdede null. */
+  successUrl: string | null;
+  /** Hosted: "Vazgeç" hedefi; verilmediyse null (dönüş `settings.appUrl`). */
+  cancelUrl: string | null;
+  /** Hosted: onaylatılacak belgeler (eski gövdede boş). */
+  consentDocs: {
+    document: string;
+    version: string;
+    url: string;
+  }[];
+  /** Hosted: ürünün ön doldurması; oturum kapanınca silinir (servis K21). */
+  prefill: CheckoutPrefill | null;
+  /** Hosted sayfa anahtarı (`url`deki `k`; sahtede düz saklanır); oturum kapanınca null. */
+  pageKey: string | null;
+  consents: Consent[];
+  actorRef: string | null;
+  failureReason: string | null;
+  subscriptionId: string | null;
+  expiresAt: Ms;
+  createdAt: Ms;
+  completedAt: Ms | null;
+  /** Sahte sağlayıcı formu; hosted oturumda sahte sayfanın `details` adımı olmadığından null. */
+  providerToken: string | null;
+};
+type PaymentRow = {
+  id: string;
+  subscriptionId: string;
+  providerOrderRef: string;
+  status: "succeeded" | "failed";
+  attempt: number;
+  amountMinor: number;
+  currency: string;
+  periodStart: Ms | null;
+  periodEnd: Ms | null;
+  occurredAt: Ms;
+  createdAt: Ms;
+};
+type InvoiceRow = {
+  id: string;
+  accountRef: string;
+  subscriptionId: string | null;
+  paymentId: string | null;
+  status: Invoice["status"];
+  number: string | null;
+  currency: string;
+  subtotalMinor: number;
+  taxMinor: number;
+  totalMinor: number;
+  taxRateBps: number;
+  buyer: BillingProfile;
+  lines: Invoice["lines"];
+  externalRef: string | null;
+  issuedAt: Ms | null;
+  createdAt: Ms;
+  document: {
+    bytes: Uint8Array;
+    sha256: string;
+  } | null;
+  /** Manuel fatura (F4f); ödemeli faturada null. */
+  dueAt?: Ms | null;
+  note?: string | null;
+  voidedAt?: Ms | null;
+  voidReason?: string | null;
+};
+type GrantRow = {
+  id: string;
+  accountRef: string;
+  planCode: string | null;
+  overrides: Record<string, EntitlementValue>;
+  reason: string;
+  actorRef: string | null;
+  startsAt: Ms;
+  endsAt: Ms | null;
+  revokedAt: Ms | null;
+  createdAt: Ms;
+  startApplied: boolean;
+  endApplied: boolean;
+};
+type DeliveryRow = {
+  status: "pending" | "delivered" | "dead";
+  attempts: number;
+  lastHttpStatus: number | null;
+  lastError: string | null;
+  nextAttemptAt: Ms;
+  deliveredAt: Ms | null;
+};
+/** Yönetim ucuyla açılan endpoint (`admin.ts`): yalnızca kayıt, teslimat yok; sır saklanmaz. */
+type AdminEndpointRow = {
+  id: string;
+  url: string;
+  status: "active" | "inactive";
+  eventTypes: EventType[];
+  description: string | null;
+  createdAt: Ms;
+  rotatedAt: Ms | null;
+};
+type EventRow = {
+  id: string;
+  accountRef: string;
+  type: EventType;
+  /** Servisin outbox'taki gövdesi: eski tiplerde de `data.account` tam durum. */
+  payload: BillingEvent;
+  /** Endpoint yoksa ya da filtresi tipi içermiyorsa null. */
+  delivery: DeliveryRow | null;
+};
+type World = {
+  readonly productCode: string;
+  /** Ürün ayarları (`GET/PATCH /v1/admin/settings`; checkout TTL ve dönüş origin'i buradan). */
+  settings: ProductSettings;
+  /**
+   * true: dönüş origin'i ayarlanana kadar (`appUrl`/`extraReturnOrigins` boş ve yamada
+   * verilmedi) her `returnUrl` kabul — sahtenin kolaylığı; servis ayar ister.
+   */
+  permissiveReturnOrigins: boolean;
+  adminEndpoints: AdminEndpointRow[];
+  readonly dunningPolicy: FakeDunningPolicy;
+  /** Endpoint'in aldığı tipler; webhook yoksa null. */
+  readonly endpoint: {
+    readonly id: string;
+    readonly types: ReadonlySet<string>;
+  } | null;
+  features: FeatureDef[];
+  plans: Map<string, PlanRow>;
+  prices: PriceRow[];
+  defaultPlanCode: string | null;
+  accounts: Map<string, AccountRow>;
+  subscriptions: SubscriptionRow[];
+  sessions: SessionRow[];
+  portalSessions: PortalSessionRow[];
+  payments: PaymentRow[];
+  invoices: InvoiceRow[];
+  grants: GrantRow[];
+  events: EventRow[];
+  now(): Ms;
+  /** Saati ileri alır (geri almaz). */
+  setNow(ms: Ms): void;
+  /** Saate göre monoton UUIDv7. */
+  id(): string;
+};
+declare namespace operations_d_exports {
+  export { Failure, PORTAL_CANCEL_REASON, PORTAL_INVOICE_LIMIT, PORTAL_RETRY_INTERVAL_MS, PortalActionResult, PortalView, Result, accountDetail, advanceTo, applyRenewalPayment, cancelCheckout, cancelSubscription, checkoutSessionResponse, completeCheckout, createCheckoutSession, createGrant, createHostedCheckoutSession, createPortalSession, customerActorRef, deleteAccount, failCheckout, hostedPageUrl, hostedPortalUrl, issueInvoice, listEvents, livePortalSession, openHostedSession, openPortalSession, portalCancel, portalInvoiceDocument, portalRetryPayment, portalView, putBillingProfile, redeliverEvent, refreshAccounts, resyncAccount, revokeGrant, sessionRow, setPlan, stats, syncCatalog, updatePortalProfile, upsertAccount, validatePortalProfile };
+}
+type Failure = {
+  ok: false;
+  code: ErrorCode;
+  message?: string;
+};
+type Result<T> = {
+  ok: true;
+  value: T;
+} | Failure;
+type CatalogInput = z.output<typeof CatalogSyncInputSchema>;
+type UpsertInput = z.output<typeof AccountUpsertInputSchema>;
+/** Eski gövde (K16); hosted gövde `HostedCheckoutInput` (http.ts `isLegacyCheckoutInput` ile ayırır). */
+type CheckoutInput = LegacyCheckoutSessionCreateParsed;
+type HostedCheckoutInput = CheckoutSessionCreateParsed;
+type CancelInput = z.output<typeof CancelSubscriptionInputSchema>;
+type GrantInput = z.output<typeof GrantCreateInputSchema>;
+type IssueInput = z.output<typeof InvoiceIssueInputSchema>;
+type PlanSetInput = z.output<typeof PlanSetInputSchema>;
+/** `syncCatalogWithProvider`: K4 tamlığı, farkın uygulanması, etkilenen hesapların yenilenmesi. */
+declare function syncCatalog(w: World, input: CatalogInput): Result<CatalogSyncResult>;
+/** `refreshAccounts` (`POST /v1/admin/accounts/refresh`). */
+declare function refreshAccounts(w: World): AccountsRefreshResult;
+declare function upsertAccount(w: World, ref: string, input: UpsertInput): {
+  account: AccountUpsertResponse;
+  created: boolean;
+};
+declare function putBillingProfile(w: World, ref: string, profile: BillingProfile): Result<BillingProfileResponse>;
+declare function accountDetail(w: World, ref: string, include: readonly AccountInclude[]): AccountDetail | null;
+/** Hosted checkout sayfası (servisin `hostedCheckoutUrl`); sahtede `hosted.ts` sunar. */
+declare const hostedPageUrl: (baseUrl: string, id: string, pageKey: string) => string;
+declare function createCheckoutSession(w: World, baseUrl: string, ref: string, input: CheckoutInput, actorRef: string): Result<CheckoutSessionCreated>;
+/**
+ * `createHostedCheckoutSession` (hosted gövde, F2b): sağlayıcıya gidilmez; doğrulama sırası ve
+ * kodları servisle aynı (hesap, dönüş origin'leri, canlı abonelik, satılabilir fiyat). Hesap
+ * yoksa `displayName` ile açılır. `url` sahte steward'ın hosted sayfasıdır (`hosted.ts`).
+ */
+declare function createHostedCheckoutSession(w: World, baseUrl: string, ref: string, input: HostedCheckoutInput, actorRef: string): Result<CheckoutSessionCreated>;
+declare function checkoutSessionResponse(w: World, id: string): CheckoutSessionResponse | null;
+declare function sessionRow(w: World, id: string): SessionRow;
+/** Hosted oturumun sayfası açık mı: anahtar bu oturumun, oturum açık ve süresi geçmemiş (servis `openSession`). */
+declare function openHostedSession(w: World, id: string, pageKey: string): SessionRow | null;
+/** `completeCheckoutReturn` başarısızlık yolu: yalnızca `open` oturum kapanır. */
+declare function failCheckout(w: World, session: SessionRow, reason: string): void;
+/**
+ * Hosted sayfada vazgeç (`HostedCheckoutPort.cancel`; sahte sayfada sağlayıcı formu olmadığından
+ * her zaman kapanır): yalnızca açık oturum; `canceled`, iç neden `checkout.canceled`. Dönüş
+ * adresi `cancelUrl ?? settings.appUrl` (yoksa null). Açık olmayan oturumda değişiklik yok.
+ */
+declare function cancelCheckout(w: World, session: SessionRow): string | null;
+/** `completeCheckoutReturn` başarı yolu: abonelik, ilk tahsilat, event'ler, taslak fatura. */
+declare function completeCheckout(w: World, session: SessionRow): void;
+declare function issueInvoice(w: World, id: string, input: IssueInput): Result<InvoiceIssueResponse>;
+declare function cancelSubscription(w: World, id: string, input: CancelInput, actorRef: string): Result<CancelSubscriptionResponse>;
+declare function createGrant(w: World, ref: string, input: GrantInput, actorRef: string): Result<GrantCreateResponse>;
+/** Zaten iptal edilmiş grant: idempotent başarı. */
+declare function revokeGrant(w: World, id: string): boolean;
+/**
+ * `setPlan` (K6): aktif plan grant'leri (henüz başlamamışlar dahil; override
+ * grant'leri hariç) iptal + yeni plan grant'i + `commitAccountChange(grant.plan_set)`.
+ * Tek aktif plan grant'i aynı plan/`endsAt`/`overrides` ise korunur. Canlı abonelik
+ * planı hak kuralında hedefi geçiyorsa `strict` → `subscription_plan_higher` (yazım
+ * yok), `ensure` → uyarı. Sahtede eşzamanlılık yok (servis advisory lock'la sıralar).
+ */
+declare function setPlan(w: World, ref: string, input: PlanSetInput, actorRef: string): Result<PlanSetResponse>;
+/** `resyncAccount`: saklı durum `account.state_changed` (`cause: "resync"`) olarak; version aynı. */
+declare function resyncAccount(w: World, ref: string): Result<ResyncResult>;
+/**
+ * `deleteAccount` (`domain/account-deletion.ts`, F4e): önkoşullar sırayla (hesap yok 404,
+ * silinmiş 410, canlı abonelik, formu açık checkout — sahte steward'da yalnızca eski
+ * gövdeli oturumun formu vardır) ve hiçbiri tutmazsa değişiklik yok. Sonra anonimleştirme:
+ * ad/metadata/profil, oturumların ön doldurması/anahtarı ve onay izinin `ipHash`/`userAgent`'ı,
+ * portal oturumları, aktif grant'ler; eski event yüklerinde `displayName`. Faturalar kalır.
+ */
+declare function deleteAccount(w: World, ref: string, actorRef: string): Result<AccountDeleteResponse>;
+declare function stats(w: World): Stats;
+/** Portal sayfası (servisin `hostedPortalUrl`); sahtede `portal.ts` sunar. */
+declare const hostedPortalUrl: (baseUrl: string, id: string, pageKey: string) => string;
+declare const PORTAL_CANCEL_REASON = "customer_portal";
+/** Abonelik başına portal "yeniden dene" aralığı (sağlayıcıya giden son retry'dan itibaren; servisle aynı). */
+declare const PORTAL_RETRY_INTERVAL_MS: number;
+declare const PORTAL_INVOICE_LIMIT = 24;
+/** Portal aksiyonlarının aktörü (servisin `customerActorRef`). */
+declare const customerActorRef: (accountRef: string) => string;
+/**
+ * Portal aksiyonunun sonucu: `ok` ya da servisin portal portundaki `not_allowed` nedeni
+ * (değişiklik yok). Sahte sağlayıcı hata vermediği için `provider_error` yok.
+ */
+type PortalActionResult = "ok" | "no_subscription" | "already_scheduled" | "nothing_to_retry" | "no_failed_payment" | "retry_too_soon";
+type PortalSessionInput = z.output<typeof PortalSessionCreateInputSchema>;
+/**
+ * `createPortalSession`: hesap yoksa `account_not_found` (checkout'taki gibi açılmaz), `returnUrl`
+ * origin'i izinli değilse `return_url_not_allowed`; dil verilmezse `defaultLocale`, süre
+ * `portalTtlMinutes`. Anahtar 32 bayt base64url. Durum değişmez, event yok.
+ */
+declare function createPortalSession(w: World, baseUrl: string, ref: string, input: PortalSessionInput, actorRef: string): Result<PortalSession>;
+/** Süresi geçmemiş portal oturumu (anahtarsız; `simulate`). Yoksa null. */
+declare function livePortalSession(w: World, id: string): PortalSessionRow | null;
+/** Servisin `validSession`'ı: bilinmeyen id, yanlış anahtar ve süresi geçmiş oturum AYNI sonuç (null). */
+declare function openPortalSession(w: World, id: string, pageKey: string): PortalSessionRow | null;
+type PortalView = {
+  session: PortalSessionRow;
+  account: AccountRow;
+  state: AccountState;
+  planName: string;
+  subscription: {
+    row: SubscriptionRow;
+    price: PriceRow;
+    planName: string;
+    canCancel: boolean;
+    canRetryPayment: boolean;
+  } | null;
+  /** En yeni önce, en çok 24 (ödemeli taslak dahil; manuel taslak yok). */
+  invoices: InvoiceRow[];
+  /** `returnUrl ?? settings.appUrl`; yoksa null. */
+  returnUrl: string | null;
+};
+/** Servisin portal `load` görünümü (sayfa için). */
+declare function portalView(w: World, session: PortalSessionRow): PortalView;
+/**
+ * Portal iptali (`HostedPortalPort.cancelAtPeriodEnd`): canlı abonelik dönem sonunda
+ * (`cancelSubscription`, neden `customer_portal`, aktör `customer:<ref>`; `/v1` iptaliyle aynı
+ * kurallar ve event'ler). Zaten planlıysa `already_scheduled` (iz/event yok).
+ */
+declare function portalCancel(w: World, session: PortalSessionRow): PortalActionResult;
+/**
+ * Portal "ödemeyi yeniden dene" (`HostedPortalPort.retryPayment`): past_due/suspended abonelikte
+ * son başarısız sipariş sahte sağlayıcıya gönderilmiş sayılır — DURUM DEĞİŞMEZ, event yok;
+ * tahsilatın sonucu servisteki gibi sonradan gelir (`simulate.renewal(ref)` aynı siparişi
+ * başarılı/`fail` sayar). Abonelik başına 10 dakikada bir (portal ya da dunning retry'ı).
+ */
+declare function portalRetryPayment(w: World, session: PortalSessionRow): PortalActionResult;
+/**
+ * Servisin `validateProfile`'ı (hosted-checkout.ts `checkProfile`): alan anahtarları
+ * `profile.<alan>`, alan başına ilk kod; öncelik required > invalid_kind > invalid_characters >
+ * şema kodları > VKN/E.164. Değer koda girmez.
+ */
+declare function validatePortalProfile(input: Record<string, unknown>): {
+  ok: true;
+  profile: BillingProfile;
+} | {
+  ok: false;
+  fieldErrors: Record<string, string>;
+};
+/**
+ * Portal profil güncellemesi (`HostedPortalPort.updateProfile`): ülke verilmezse saklı değer
+ * korunur (yoksa TR); bireyselde kurumsal alanlar düşer. Durumda yalnızca profilin varlığı ve
+ * türü olduğundan event yalnızca bunlar değişince (`billing_profile.updated`).
+ */
+declare function updatePortalProfile(w: World, session: PortalSessionRow, input: Record<string, unknown>): {
+  ok: true;
+} | {
+  ok: false;
+  fieldErrors: Record<string, string>;
+};
+/** Portal belge indirme: yalnızca oturumun hesabının kesilmiş ve belgeli faturası; yoksa null. */
+declare function portalInvoiceDocument(w: World, session: PortalSessionRow, invoiceId: string): {
+  bytes: Uint8Array;
+  filename: string;
+} | null;
+declare function listEvents(w: World, query: {
+  accountRef?: string;
+  cursor?: string;
+  limit: number;
+}): Result<EventList>;
+declare function redeliverEvent(w: World, id: string): EventRecord | null;
+/**
+ * Tahsilat sonucu. Dunning'deki abonelikte AYNI başarısız siparişin yeniden
+ * denemesidir (iyzico retry'ı; servisin `existingPayment` yolu), aksi halde
+ * mevcut dönem sonundan başlayan yeni sipariş.
+ */
+declare function applyRenewalPayment(w: World, sub: SubscriptionRow, outcome: "succeeded" | "failed"): void;
+/** Saati `target`a ilerletir; her zamanlanmış iş kendi anında koşar. */
+declare function advanceTo(w: World, target: Ms): void;
+//#endregion
+//#region src/testing/fake-steward.d.ts
+/** Sahte steward'ın teslimat yaptığı ürün alıcısı. */
+type FakeWebhookHandler = (req: Request) => Response | Promise<Response>;
+type FakeWebhookOptions = {
+  /** İmza sırrı; dizi verilirse rotasyondaki gibi hepsiyle imzalanır. */
+  secret: string | readonly string[];
+  /** Ürünün alıcısı, ör. `(req) => webhooks.handle(req)`. Verilmezse `fake.connect(handler)` ile sonradan. */
+  handler?: FakeWebhookHandler;
+  /**
+   * Endpoint filtresi. Verilmezse `["account.state_changed"]` (yönetim ucunun yeni ürüne
+   * varsayılanı); `"legacy"`: `LEGACY_EVENT_TYPES` (pod CLI `add-endpoint`'in NULL filtresi, 15 eski tip).
+   */
+  eventTypes?: readonly EventType[] | "legacy";
+  /** İsteğin adresi (yalnızca `Request.url`). */
+  url?: string;
+};
+type FakeStewardOptions = {
+  /** Oluşturmada senkronlanan katalog. Verilmezse katalog uçları `catalog_not_configured`, hesap açılışı 500 (servis gibi). */
+  catalog?: CatalogSyncInput | {
+    toSyncInput(): CatalogSyncInput;
+  };
+  /** Ürün kapsamlı anahtar; verilmezse `stw_…` biçiminde üretilir. */
+  apiKey?: string;
+  /** Admin kapsamlı anahtar; verilmezse üretilir. */
+  adminApiKey?: string;
+  /** Varsayılan `http://steward.test`. Bu tabanın dışındaki istekler ağ hatası alır. */
+  baseUrl?: string;
+  /** Event'lerin `product` alanı ve `/v1/me`. Varsayılan `example`. */
+  productCode?: string;
+  /** Sahte saatin kaynağı; `simulate.advance`/`renewal` bunun üstüne ekler. Varsayılan gerçek saat. */
+  now?: () => Date;
+  webhook?: FakeWebhookOptions;
+  /**
+   * Başlangıç ürün ayarları (`PATCH /v1/admin/settings` yamasıyla aynı biçim). Sağlayıcı
+   * her zaman sahte (`provider: "fake"`). Dönüş origin'i (`appUrl`, `extraReturnOrigins`,
+   * `returnOrigins`) hiç verilmez ve yamalanmazsa her `returnUrl` kabul edilir.
+   */
+  settings?: ProductSettingsPatch;
+  /** Checkout `returnUrl` origin listesi = `settings.extraReturnOrigins` (ikisi birlikte verilemez). */
+  returnOrigins?: readonly string[];
+  /** = `settings.checkoutTtlMinutes`; varsayılan 30 (sahte sağlayıcının formu da 30 dk). */
+  checkoutTtlMinutes?: number;
+  /** Varsayılan servisinki: `dryRun: true` (adımlar sayılır, askı/sonlandırma yok). */
+  dunningPolicy?: FakeDunningPolicy;
+  /** `fake.steward` ek ayarları (bağlantı ayarları sahteden gelir). */
+  steward?: Omit<StewardOptions, "baseUrl" | "apiKey" | "adminBaseUrl" | "adminApiKey" | "fetch" | "env">;
+  /** 500'e dönüşen iç hatalar (servis gibi). Varsayılan `console`. */
+  logger?: {
+    error(message: string): void;
+  };
+};
+/** Sahteye gelen istek (sırasıyla). `status` 0: ağ hatası (kesinti ya da taban dışı adres). */
+type FakeRequest = {
+  method: string;
+  url: string;
+  /** Tabana göre yol + sorgu, ör. `/v1/accounts/org_1/state`. */
+  path: string;
+  headers: Record<string, string>;
+  body: string | null;
+  status: number;
+};
+type FakeDelivery = {
+  event: BillingEvent;
+  body: string;
+  headers: Record<string, string>;
+  response: Response;
+};
+type FakeDeliverOptions = {
+  ref: string;
+  /** `account.state_changed` için `detail.cause`; varsayılan `account.refreshed`. */
+  cause?: string;
+  /** Aynı event (aynı id ve gövde) ikinci kez. */
+  duplicate?: boolean;
+  /** Güncel event'ten sonra bir önceki version'ın durumuyla eski bir event. */
+  outOfOrder?: boolean;
+};
+/** `simulate.portalCancel/portalRetryPayment` sonucu. */
+type FakePortalActionResult = {
+  /**
+   * `ok` ya da servisin portal portundaki `not_allowed` nedeni (hiçbir şey değişmedi):
+   * `no_subscription`, `already_scheduled` (iptal), `nothing_to_retry` / `no_failed_payment` /
+   * `retry_too_soon` (yeniden dene). Sayfa bunları `error=` koduna eşler.
+   */
+  result: PortalActionResult;
+  /** İşlem sonrası hesap durumu. */
+  account: AccountState;
+};
+/** `simulate.completeHostedCheckout` sonucu. */
+type FakeHostedCheckoutResult = {
+  /** Oturum id'si (`url`'den). */
+  id: string;
+  /** Sayfanın 303 yönlendirdiği adres: `successUrl`, yer tutucular servisle aynı kuralla dolu. */
+  redirectUrl: string;
+  /** İşlem sonrası oturum (`completed` ya da `failed`; `completed`'da `account`). */
+  session: CheckoutSessionResponse;
+};
+type FakeSimulate = {
+  /**
+   * Sağlayıcı formu ödendi: abonelik, ilk tahsilat, fatura taslağı, event'ler. Açık olmayan
+   * oturumda değişiklik yok. Hosted oturumda önce sayfanın `details` izi yazılır (profil yoksa
+   * ön doldurmadan sahte profil, onay izi; `billing_profile.updated`).
+   */
+  checkoutCompleted(sessionId: string): Promise<CheckoutSessionResponse>;
+  /** Kart reddedildi (`fake:card_declined`). */
+  checkoutFailed(sessionId: string, options?: {
+    reason?: string;
+  }): Promise<CheckoutSessionResponse>;
+  /**
+   * Hosted checkout'u açılış yanıtındaki `url`'den tarayıcı gibi sürer (F2b): sahte sayfayı açar
+   * (`fake.fetch`, `fake.requests`'e yazılır), "Tamamla" (`outcome: "succeeded"`, varsayılan) ya da
+   * "Reddet" gönderir, 303 dönüş adresini verir. Sonuç `checkoutCompleted/Failed` ile aynıdır.
+   * Sayfa 404 (bilinmeyen, kapalı ya da süresi geçmiş oturum, yanlış anahtar) ya da kesinti fırlatır.
+   */
+  completeHostedCheckout(url: string, options?: {
+    outcome?: "succeeded" | "failed";
+  }): Promise<FakeHostedCheckoutResult>;
+  /**
+   * Müşteri hosted sayfada vazgeçti (F2b): oturum `canceled`, iç neden `checkout.canceled`
+   * (eski tipli event yok). Yalnızca hosted oturum; açık olmayan oturumda değişiklik yok.
+   */
+  checkoutCanceled(sessionId: string): Promise<CheckoutSessionResponse>;
+  /**
+   * Yenileme tahsilatı. Saat önce `advanceDays` kadar, verilmezse dönem sonuna
+   * ilerler (arada zamanlanmış işler koşar). Başarı → `subscription.renewed`
+   * (+fatura; dunning'deyse `subscription.reactivated`), `fail` →
+   * `subscription.payment_failed`, `past_due`, dunning başlar. Dunning'deki
+   * abonelikte aynı başarısız siparişin yeniden denemesidir.
+   */
+  renewal(ref: string, options?: {
+    advanceDays?: number;
+    fail?: boolean;
+  }): Promise<AccountState>;
+  /**
+   * Müşteri portalda "Dönem sonunda iptal"i onayladı (F3a; sayfanın `cancel` + `confirm=1`
+   * adımıyla aynı işlem): canlı abonelik dönem sonunda iptal edilir — `subscriptions.cancel`
+   * (`at_period_end`) ile aynı kurallar ve event'ler (`subscription.cancel_scheduled`,
+   * `account.state_changed`), neden `customer_portal`, aktör `customer:<ref>`. Zaten planlıysa
+   * `already_scheduled`, abonelik yoksa `no_subscription` (değişiklik yok). Bilinmeyen ya da
+   * süresi geçmiş oturum fırlatır (sayfa 404 verirdi).
+   */
+  portalCancel(portalSessionId: string): Promise<FakePortalActionResult>;
+  /**
+   * Müşteri portalda "Ödemeyi yeniden dene"ye bastı (F3a): past_due/suspended abonelikte istek
+   * kabul edilir (`ok`) ama DURUM DEĞİŞMEZ — servisteki gibi tahsilatın sonucu sonradan gelir:
+   * `renewal(ref)` aynı başarısız siparişi başarılı sayar (`subscription.reactivated`),
+   * `renewal(ref, {fail: true})` yine başarısız. Abonelik başına 10 dakikada bir (`retry_too_soon`;
+   * saat `advance` ile ilerler); aktif abonelikte `nothing_to_retry`. Bilinmeyen ya da süresi
+   * geçmiş oturum fırlatır.
+   */
+  portalRetryPayment(portalSessionId: string): Promise<FakePortalActionResult>;
+  /** Saati ilerletir; her zamanlanmış iş kendi anında koşar. Süresiz çağrı yalnızca vadesi gelenleri koşar. */
+  advance(duration?: {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+  }): Promise<void>;
+  /** `network`: fetch `TypeError("fetch failed")` ile reddeder; `503`: `database_unavailable` (tekrar denenebilir). */
+  outage(on: boolean, options?: {
+    mode?: "network" | "503";
+  }): void;
+  /** Hesabın GÜNCEL durumuyla `type` event'ini alıcıya gönderir (outbox'a yazılmaz, filtre uygulanmaz). */
+  deliver(type: EventType, options: FakeDeliverOptions): Promise<FakeDelivery[]>;
+  /** Bekleyen (teslim edilmemiş) outbox event'lerini sırayla alıcıya gönderir. */
+  flush(): Promise<FakeDelivery[]>;
+};
+type FakeSteward = {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  readonly adminApiKey: string;
+  readonly fetch: typeof fetch;
+  readonly steward: Steward;
+  readonly requests: readonly FakeRequest[];
+  readonly simulate: FakeSimulate;
+  /**
+   * Webhook alıcısını bağlar ya da değiştirir (`webhook.handler` yerine): sahte steward ürün
+   * uygulamasından önce kurulur, uygulama `fake.steward`/`fake.fetch` ile oluşturulup sonra bağlanır.
+   * `webhook` seçeneği (sır, filtre) verilmemişse fırlatır.
+   */
+  connect(handler: FakeWebhookHandler): void;
+  /** Yayınlanan event'ler, yayın sırasıyla (`GET /v1/events`'in içeriği; eski tiplerde de tam durum). */
+  events(ref?: string): readonly BillingEvent[];
+  /** Sahte saat. */
+  now(): Date;
+};
+export declare function createFakeSteward(options?: FakeStewardOptions): FakeSteward;
+//#endregion
+//#region src/testing/signed-event.d.ts
+type SignedEventOverrides<T extends EventType = EventType> = {
+  id?: string;
+  apiVersion?: string;
+  createdAt?: string;
+  product?: string;
+  accountRef?: string;
+  data?: {
+    /** Fixture'ın hesabına sığ birleşir; tam `AccountState` verilebilir (F1+ sunucu eski tiplere de koyar). */
+    account?: Partial<AccountState>;
+    detail?: Partial<EventDetail<T>>;
+  };
+};
+type SignedEventOptions = {
+  /** İmza sırları (`yeni,eski` rotasyonu için dizi). Verilmezse `STEWARD_WEBHOOK_SECRET`. */
+  secret?: string | readonly string[];
+  /** Unix saniye; varsayılan şimdi. */
+  timestamp?: number;
+};
+type SignedEvent<T extends EventType = EventType> = {
+  event: BillingEventOf<T>;
+  /** Ham gövde (imzalanan metin). */
+  body: string;
+  /** İmza başlıkları + `content-type`. */
+  headers: Record<string, string>;
+  /** Alıcıya verilecek `POST` isteği (her çağrıda yeni `Request`). */
+  request(url?: string): Request;
+};
+export declare function signedEvent<T extends EventType>(type: T, overrides?: SignedEventOverrides<T>, options?: SignedEventOptions): SignedEvent<T>;
+//#endregion
+export type { FakeDeliverOptions, FakeDelivery, FakeDunningPolicy, FakeHostedCheckoutResult, FakePortalActionResult, FakeRequest, FakeSimulate, FakeSteward, FakeStewardOptions, FakeWebhookHandler, FakeWebhookOptions, SignedEvent, SignedEventOptions, SignedEventOverrides };