@stewardhq/sdk 0.1.0-rc.0

package/dist/server.d.ts

@@ -0,0 +1,236 @@
+import { Qn as CheckoutPrefill, Un as PortalSession, Wn as PortalSessionCreateInput, ei as Interval, lr as CheckoutStatus, or as CheckoutSessionCreated, qt as CheckoutSessionResponse, rr as CheckoutSessionCreateInput } from "./_chunks/index.js";
+import { D as AccountInclude, F as AccountState, V as BillingProfile, a as BillingEvent, f as EventType, n as AnyBillingEvent, o as BillingEventOf } from "./_chunks/events.js";
+import { i as MutationOptions } from "./_chunks/steward.js";
+import { r as StewardLogger, t as StewardLocale } from "./_chunks/locale.js";
+import { a as HeaderSource, s as VerifyRawFailure } from "./_chunks/webhook-core.js";
+import "./_chunks/webhook.js";
+//#region src/server/checkout.d.ts
+/** Hosted sayfada onaylatılan belge (ürünün yasal metni). */
+type ConsentDoc = {
+  document: string;
+  version: string;
+  url: string;
+};
+/** `createSteward()` sonucunun `Checkout`'un kullandığı kısmı. */
+type CheckoutSteward = {
+  checkoutSessions: {
+    create(ref: string, input: CheckoutSessionCreateInput, options?: {
+      actorRef?: string;
+      idempotencyKey?: string;
+    }): Promise<CheckoutSessionCreated>;
+    get(id: string): Promise<CheckoutSessionResponse>;
+  };
+};
+/** Tamamlanan oturumun durumunu alan önbellek (`stateCache()` karşılar). */
+type CheckoutCache = {
+  prime(account: AccountState): unknown;
+};
+type CheckoutOptions = {
+  steward: CheckoutSteward;
+  cache?: CheckoutCache;
+  /**
+   * Mutlak dönüş adresi; origin'i steward ürün ayarında izinli olmalı (`appUrl` +
+   * `extraReturnOrigins`). Yer tutucular `{CHECKOUT_ID}` `{STATUS}` `{ACCOUNT_REF}` `{LOCALE}`
+   * varsa steward yalnızca onları doldurur; yoksa `?session=&status=` ekler.
+   */
+  successUrl: string;
+  /** Sayfadaki "Vazgeç" hedefi (mutlak); verilmezse steward ayarı `appUrl`. */
+  cancelUrl?: string;
+  /** Onaylatılacak belgeler; dile göre değişiyorsa işlev. */
+  consents?: readonly ConsentDoc[] | ((locale: StewardLocale | undefined) => readonly ConsentDoc[]);
+  /** Varsayılan sayfa dili (`tr`, `en`; `tr-TR` → `tr`); verilmezse steward ayarı `defaultLocale`. */
+  locale?: string;
+  /** Verilmezse steward ayarı `defaultCurrency`. */
+  currency?: string;
+};
+type CheckoutCreateInput = {
+  /** Hesap ref'i (ürünün kimliği; ör. organizasyon id'si). */
+  ref: string;
+  planCode: string;
+  interval: Interval;
+  /** Sayfa dili, BCP-47 benzeri (`tr`, `tr-TR`, `en-US`); desteklenmeyen dil yok sayılır (seçenekteki dil ya da steward varsayılanı). */
+  locale?: string;
+  /** `X-Actor-Ref` (ör. `user:42`): satın almayı başlatan. */
+  actorRef: string;
+  /** Hesap steward'da yoksa bu adla açılır (varsa adı değişmez); verilmez ve hesap yoksa `account_not_found`. */
+  displayName?: string;
+  /** Sayfanın ön doldurması (ad, e-posta, tür); kimlik verisi değil (K21). */
+  prefill?: CheckoutPrefill;
+};
+type CheckoutCreated = {
+  id: string;
+  url: string;
+  expiresAt: string;
+};
+type CheckoutResult = {
+  status: CheckoutStatus;
+  planCode?: string;
+  /** Yalnızca `completed`: işlem sonrası hesap durumu (önbelleğe yazıldı). */
+  account?: AccountState;
+};
+type CheckoutHandler = {
+  create(input: CheckoutCreateInput): Promise<CheckoutCreated>;
+  result(id: string, options: {
+    ref: string;
+  }): Promise<CheckoutResult>;
+};
+export declare function Checkout(options: CheckoutOptions): CheckoutHandler;
+//#endregion
+//#region src/server/portal.d.ts
+/** `createSteward()` sonucunun `CustomerPortal`'ın kullandığı kısmı. */
+type CustomerPortalSteward = {
+  portalSessions: {
+    create(ref: string, input?: PortalSessionCreateInput, options?: MutationOptions): Promise<PortalSession>;
+  };
+};
+type CustomerPortalOptions = {
+  steward: CustomerPortalSteward;
+  /** Varsayılan "Ürüne dön" adresi (mutlak http(s)); verilmezse steward ürün ayarı `appUrl`. */
+  returnUrl?: string;
+};
+type CustomerPortalCreateArgs = {
+  /** Hesabın ürün tarafındaki kimliği (`accounts.external_ref`). */
+  ref: string;
+  /** Sayfa dili; `tr`/`en` dışı değer steward varsayılanına bırakılır. */
+  locale?: string;
+  returnUrl?: string;
+  /** Portalı açan kullanıcı, ör. `user:42`. */
+  actorRef: string;
+  idempotencyKey?: string;
+};
+type CustomerPortalClient = {
+  /** `POST /v1/accounts/{ref}/portal-sessions` → `{id, url, expiresAt}`; tarayıcı `url`e yönlendirilir. */
+  create(args: CustomerPortalCreateArgs): Promise<PortalSession>;
+};
+export declare function CustomerPortal(options: CustomerPortalOptions): CustomerPortalClient;
+//#endregion
+//#region src/server/webhooks.d.ts
+/** Neden hook'u olan tipler: `account.state_changed` dışındaki her tip (neden olarak da gelirler). */
+type CauseEventType = Exclude<EventType, "account.state_changed">;
+type Pascal<S extends string> = S extends `${infer Head}_${infer Tail}` ? `${Capitalize<Head>}${Pascal<Tail>}` : Capitalize<S>;
+/** `subscription.payment_failed` → `onSubscriptionPaymentFailed`. */
+type EventHookName<T extends string> = T extends `${infer Scope}.${infer Name}` ? `on${Pascal<Scope>}${Pascal<Name>}` : `on${Pascal<T>}`;
+type WebhookHandled = "received" | "no_state" | "ignored" | "deleted" | "ping";
+type WebhookErrorCode = "not_configured" | VerifyRawFailure | "invalid_payload" | "id_mismatch" | "state_unavailable" | "profile_unavailable" | "hook_failed";
+type WebhookResult = {
+  status: 200;
+  body: {
+    ok: true;
+    handled: WebhookHandled;
+  };
+} | {
+  status: 400 | 401 | 503;
+  body: {
+    error: WebhookErrorCode;
+  };
+};
+type StateChangedArgs = {
+  ref: string;
+  state: AccountState;
+  /** `detail.cause` (state_changed) ya da eski/tanınmayan tipin adı; küme açık. */
+  cause: string;
+  event: BillingEvent | AnyBillingEvent;
+};
+/**
+ * Hook'lara giden durumun tipi: `AccountState` (refetch açık: durum her teslimatta canlı okunur)
+ * ya da `AccountState | null` (varsayılan; `refetch: false`, yalnızca snapshot taşıyan eski gövde).
+ */
+type HookState = AccountState | null;
+type CauseHookArgs<T extends CauseEventType, S extends HookState = HookState> = {
+  ref: string;
+  cause: T;
+  /** Filtresiz (eski) endpoint'te o tipin event'i, yeni endpoint'te `account.state_changed`. */
+  event: BillingEventOf<T> | BillingEventOf<"account.state_changed">;
+  /** Teslimatın tam durumu (refetch'te canlı); yalnızca `refetch: false` + snapshot taşıyan eski gövdede `null`. */
+  state: S;
+};
+type NotificationHookArgs<T extends CauseEventType, S extends HookState = HookState> = CauseHookArgs<T, S> & {
+  /** `includeProfile: true` ise steward'dan okunan fatura profili (e-posta; K15). */
+  profile?: BillingProfile | null;
+};
+type UnknownEventArgs<S extends HookState = HookState> = {
+  ref: string;
+  cause: string;
+  event: AnyBillingEvent;
+  /** Tam durum (refetch'te canlı; değilse `data.account` tam `AccountState` ise — o zaman `onStateChanged` de koştu). */
+  state: S;
+};
+type AfterArgs<S extends HookState = HookState> = {
+  ref: string;
+  cause: string;
+  event: BillingEvent | AnyBillingEvent;
+  state: S;
+  /** Refetch açıkken `received` ya da (hesap silme teslimatı, F4e) `deleted`; `no_state` yalnızca `state: null` ile. */
+  handled: null extends S ? Exclude<WebhookHandled, "ping" | "ignored"> : "received" | "deleted";
+};
+/** Dönüş değeri beklenir (`await`) ama kullanılmaz: sorgu/kuyruk promise'ı doğrudan dönebilir. */
+type Hook<A> = (args: A) => unknown;
+/**
+ * Steward istemcisinin `Webhooks`'un kullandığı kısmı (`createSteward()` karşılar).
+ * Her metot yalnızca onu gerektiren seçenekte istenir: `accounts.state` →
+ * `refetch`, `accounts.get` → `includeProfile`.
+ */
+type WebhooksSteward = {
+  accounts: {
+    state?(ref: string): Promise<AccountState>;
+    get?(ref: string, options: {
+      include: readonly AccountInclude[];
+    }): Promise<{
+      profile?: BillingProfile | null | undefined;
+    }>;
+  };
+};
+/** Teslimatın durumunu alan önbellek (`stateCache()` karşılar); version'da geri gitmemek önbelleğin işidir. */
+type WebhooksCache = {
+  prime(account: AccountState): unknown;
+  /** Hesap silindiğinde (F4e) çağrılır; verilmezse önbellek TTL'le düşer. */
+  invalidate?(ref: string): unknown;
+};
+type CauseHooks<S extends HookState> = { [T in CauseEventType as EventHookName<T>]?: Hook<CauseHookArgs<T, S>>; };
+type WebhooksOptions<S extends HookState = HookState> = CauseHooks<S> & {
+  /** İmza sırları; metinse virgülle "yeni,eski". Verilmezse her teslimatta `STEWARD_WEBHOOK_SECRET`. */
+  secrets?: string | readonly string[];
+  /** Zaman damgası penceresi, saniye (varsayılan 300). */
+  toleranceSeconds?: number;
+  steward?: WebhooksSteward;
+  /**
+   * Durum her teslimatta steward'dan canlı okunur (`steward.accounts.state`); gövde
+   * yalnızca tetikleyici. Varsayılan: `steward` verildiyse `true`.
+   */
+  refetch?: boolean;
+  /** Teslimatın tam durumu hook'lardan önce buraya yazılır (`stateCache()`). */
+  cache?: WebhooksCache;
+  /** `onPaymentFailed`/`onSuspended`/`onTerminated` koşacaksa profil steward'dan okunur (`steward.accounts.get` gerekir). */
+  includeProfile?: boolean;
+  /** Tam durumlu her teslimatta (tekrar dahil). `"ignore"` dönerse hesap bilinmiyor: 200, diğer hook'lar ve `after` koşmaz. */
+  onStateChanged?: Hook<StateChangedArgs>;
+  onPaymentFailed?: Hook<NotificationHookArgs<"subscription.payment_failed", S>>;
+  onSuspended?: Hook<NotificationHookArgs<"subscription.suspended", S>>;
+  onTerminated?: Hook<NotificationHookArgs<"subscription.terminated", S>>;
+  onUnknownEvent?: Hook<UnknownEventArgs<S>>;
+  /** Diğer hook'lardan sonra, her teslimatta (tekrar dahil; `"ignore"` hariç); ör. ağlara yayılma. */
+  after?: Hook<AfterArgs<S>>;
+  logger?: StewardLogger;
+};
+/**
+ * `refetch` ve `steward` alanlarının tiplerinden hook durumu: `refetch: true` ya da (`refetch`
+ * verilmemiş ve `steward` verilmiş) → `AccountState`; aksi (ya da tip belirsizse) `AccountState | null`.
+ */
+type WebhooksHookState<R, St> = [R] extends [true] ? AccountState : [R] extends [undefined] ? ([undefined] extends [St] ? HookState : AccountState) : HookState;
+/** `Request`'in kullanılan kısmı (Hono `c.req.raw`, Next `req`, undici `Request`). */
+type WebhookRequest = {
+  readonly headers: Headers;
+  text(): Promise<string>;
+};
+type WebhooksHandler = {
+  /** Fetch-standart handler: `app.post("/billing/events", (c) => webhooks.handle(c.req.raw))`. */
+  handle(req: WebhookRequest): Promise<Response>;
+  /** Düz fonksiyon: ham gövde + başlıklar → `{status, body}` (ürün kendi yanıtını kurar). */
+  receive(rawBody: string, headers: HeaderSource): Promise<WebhookResult>;
+};
+export declare function Webhooks<const R extends boolean | undefined = undefined, St extends WebhooksSteward | undefined = undefined>(options: Omit<WebhooksOptions<WebhooksHookState<R, St>>, "refetch" | "steward"> & {
+  refetch?: R;
+  steward?: St;
+}): WebhooksHandler;
+//#endregion
+export type { AfterArgs, CauseEventType, CauseHookArgs, CheckoutCache, CheckoutCreateInput, CheckoutCreated, CheckoutHandler, CheckoutOptions, CheckoutResult, CheckoutSteward, ConsentDoc, CustomerPortalClient, CustomerPortalCreateArgs, CustomerPortalOptions, CustomerPortalSteward, EventHookName, HookState, NotificationHookArgs, StateChangedArgs, UnknownEventArgs, WebhookErrorCode, WebhookHandled, WebhookRequest, WebhookResult, WebhooksCache, WebhooksHandler, WebhooksHookState, WebhooksOptions, WebhooksSteward };

package/dist/server.js

@@ -0,0 +1,384 @@
+import { O as ActorRefSchema, R as ExternalRefSchema, a as EVENT_TYPES, c as PING_EVENT_TYPE, l as PingSchema, r as BillingEventSchema, t as AnyBillingEventSchema, y as AccountStateSchema, z as IdSchema } from "./_chunks/events.js";
+import "./_chunks/src.js";
+import { n as StewardConfigError, r as StewardContractError, t as StewardApiError } from "./_chunks/errors.js";
+import { t as hostedLocaleOf } from "./_chunks/locale.js";
+import { i as verifyWebhookRaw } from "./_chunks/webhook.js";
+//#region src/server/checkout.ts
+function isAbsoluteHttpUrl(value) {
+	if (typeof value !== "string") return false;
+	try {
+		const { protocol } = new URL(value);
+		return protocol === "https:" || protocol === "http:";
+	} catch {
+		return false;
+	}
+}
+const notFound = () => new StewardApiError({
+	code: "checkout_session_not_found",
+	httpStatus: 404,
+	category: "not_found",
+	retryable: false
+});
+function Checkout(options) {
+	const { steward, cache } = options;
+	const problems = [];
+	if (typeof steward?.checkoutSessions?.create !== "function" || typeof steward.checkoutSessions.get !== "function") problems.push("steward.checkoutSessions.create/get gerekli (createSteward())");
+	if (!isAbsoluteHttpUrl(options.successUrl)) problems.push("successUrl mutlak bir http(s) adresi olmalı");
+	if (options.cancelUrl !== void 0 && !isAbsoluteHttpUrl(options.cancelUrl)) problems.push("cancelUrl mutlak bir http(s) adresi olmalı");
+	const defaultLocale = hostedLocaleOf(options.locale);
+	if (options.locale !== void 0 && defaultLocale === void 0) problems.push("locale tr | en olmalı (ör. tr-TR)");
+	if (Array.isArray(options.consents) && options.consents.some((doc) => !isAbsoluteHttpUrl(doc?.url))) problems.push("consents[].url mutlak bir http(s) adresi olmalı");
+	if (options.consents !== void 0 && !Array.isArray(options.consents) && typeof options.consents !== "function") problems.push("consents dizi ya da (locale) => dizi olmalı");
+	if (cache !== void 0 && typeof cache?.prime !== "function") problems.push("cache.prime gerekli (stateCache())");
+	if (problems.length > 0) throw new StewardConfigError({ message: `Checkout: ${problems.join("; ")}` });
+	return {
+		async create(input) {
+			const locale = hostedLocaleOf(input.locale) ?? defaultLocale;
+			const docs = typeof options.consents === "function" ? options.consents(locale) : options.consents;
+			const body = {
+				planCode: input.planCode,
+				interval: input.interval,
+				successUrl: options.successUrl,
+				...options.cancelUrl !== void 0 ? { cancelUrl: options.cancelUrl } : {},
+				...options.currency !== void 0 ? { currency: options.currency } : {},
+				...locale !== void 0 ? { locale } : {},
+				...docs !== void 0 ? { consents: docs.map(({ document, version, url }) => ({
+					document,
+					version,
+					url
+				})) } : {},
+				...input.displayName !== void 0 ? { displayName: input.displayName } : {},
+				...input.prefill !== void 0 ? { prefill: input.prefill } : {}
+			};
+			const session = await steward.checkoutSessions.create(input.ref, body, { actorRef: input.actorRef });
+			if (typeof session.url !== "string" || session.url === "") throw new StewardContractError({ message: "Checkout: steward hosted checkout adresi (url) döndürmedi; steward sürümü F2b öncesi mi?" });
+			return {
+				id: session.id,
+				url: session.url,
+				expiresAt: session.expiresAt
+			};
+		},
+		async result(id, { ref }) {
+			if (!IdSchema.safeParse(id).success) throw notFound();
+			const session = await steward.checkoutSessions.get(id);
+			if (session.accountRef !== ref) throw notFound();
+			if (session.status === "completed" && session.account) {
+				await cache?.prime(session.account);
+				return {
+					status: session.status,
+					planCode: session.planCode,
+					account: session.account
+				};
+			}
+			return {
+				status: session.status,
+				planCode: session.planCode
+			};
+		}
+	};
+}
+//#endregion
+//#region src/server/portal.ts
+function isHttpUrl(value) {
+	try {
+		const { protocol } = new URL(value);
+		return protocol === "http:" || protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+function CustomerPortal(options) {
+	const steward = options?.steward;
+	if (typeof steward?.portalSessions?.create !== "function") throw new StewardConfigError({ message: "CustomerPortal: steward.portalSessions.create gerekli (createSteward())" });
+	if (options.returnUrl !== void 0 && !isHttpUrl(options.returnUrl)) throw new StewardConfigError({ message: "CustomerPortal: returnUrl mutlak bir http(s) adresi olmalı" });
+	const create = steward.portalSessions.create.bind(steward.portalSessions);
+	return { async create(args) {
+		if (typeof args?.ref !== "string" || !ExternalRefSchema.safeParse(args.ref).success) throw new StewardConfigError({ message: "CustomerPortal.create: ref geçersiz" });
+		if (typeof args.actorRef !== "string" || !ActorRefSchema.safeParse(args.actorRef).success) throw new StewardConfigError({ message: "CustomerPortal.create: actorRef zorunlu (tür[:kimlik], ör. user:42)" });
+		const returnUrl = args.returnUrl ?? options.returnUrl;
+		if (returnUrl !== void 0 && !isHttpUrl(returnUrl)) throw new StewardConfigError({ message: "CustomerPortal.create: returnUrl mutlak bir http(s) adresi olmalı" });
+		const locale = hostedLocaleOf(args.locale);
+		const input = {
+			...locale !== void 0 ? { locale } : {},
+			...returnUrl !== void 0 ? { returnUrl } : {}
+		};
+		return create(args.ref, input, {
+			actorRef: args.actorRef,
+			...args.idempotencyKey !== void 0 ? { idempotencyKey: args.idempotencyKey } : {}
+		});
+	} };
+}
+//#endregion
+//#region src/server/webhooks.ts
+const NOTIFICATION_HOOKS = {
+	"subscription.payment_failed": "onPaymentFailed",
+	"subscription.suspended": "onSuspended",
+	"subscription.terminated": "onTerminated"
+};
+const CAUSE_TYPES = new Set(EVENT_TYPES.filter((t) => t !== "account.state_changed"));
+const KNOWN_TYPES = new Set(EVENT_TYPES);
+const isCauseType = (value) => CAUSE_TYPES.has(value);
+const eventHookName = (type) => `on${type.split(/[._]/).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("")}`;
+function parseSecrets(value) {
+	return (typeof value === "string" ? value.split(",") : value ?? []).map((s) => s.trim()).filter(Boolean);
+}
+const isObject = (value) => typeof value === "object" && value !== null;
+function fullState(account) {
+	const parsed = AccountStateSchema.safeParse(account);
+	return parsed.success ? parsed.data : null;
+}
+/** İmzası doğrulanmış gövde → teslimat. `eventId` başlıktaki id. */
+function parseDelivery(eventId, rawBody) {
+	let json;
+	try {
+		json = JSON.parse(rawBody);
+	} catch {
+		return {
+			kind: "invalid",
+			reason: "invalid_payload",
+			detail: "gövde JSON değil"
+		};
+	}
+	const type = isObject(json) ? json.type : void 0;
+	const idMismatch = {
+		kind: "invalid",
+		reason: "id_mismatch",
+		detail: "gövdedeki id başlıktakiyle aynı değil"
+	};
+	const refMismatch = {
+		kind: "invalid",
+		reason: "invalid_payload",
+		detail: "data.account.ref accountRef ile aynı değil"
+	};
+	if (type === "endpoint.ping") {
+		const ping = PingSchema.safeParse(json);
+		if (!ping.success) return {
+			kind: "invalid",
+			reason: "invalid_payload",
+			detail: `${PING_EVENT_TYPE} şemaya uymuyor`
+		};
+		return ping.data.id === eventId ? { kind: "ping" } : idMismatch;
+	}
+	const known = BillingEventSchema.safeParse(json);
+	if (known.success) {
+		const event = known.data;
+		if (event.id !== eventId) return idMismatch;
+		const state = event.type === "account.state_changed" ? event.data.account : fullState(json.data.account);
+		if (state && state.ref !== event.accountRef) return refMismatch;
+		const cause = event.type === "account.state_changed" ? event.data.detail.cause : event.type;
+		return {
+			kind: "event",
+			ref: event.accountRef,
+			event,
+			cause,
+			causeType: isCauseType(cause) ? cause : null,
+			state
+		};
+	}
+	if (typeof type === "string" && KNOWN_TYPES.has(type)) return {
+		kind: "invalid",
+		reason: "invalid_payload",
+		detail: `${type} şemaya uymuyor`
+	};
+	const loose = AnyBillingEventSchema.safeParse(json);
+	if (!loose.success) return {
+		kind: "invalid",
+		reason: "invalid_payload",
+		detail: "event zarfı şemaya uymuyor"
+	};
+	const event = loose.data;
+	if (event.id !== eventId) return idMismatch;
+	const state = fullState(event.data.account);
+	if (state && state.ref !== event.accountRef) return refMismatch;
+	return {
+		kind: "unknown",
+		ref: event.accountRef,
+		event,
+		cause: event.type,
+		state
+	};
+}
+const describeError = (error) => error instanceof Error ? error.message : String(error);
+/** Silme teslimatı (F4e): `account.deleted` ya da onun nedeni olduğu `account.state_changed`. */
+const DELETED = "account.deleted";
+const isDeletion = (d) => d.kind === "event" && (d.event.type === DELETED || d.event.type === "account.state_changed" && d.cause === DELETED);
+function Webhooks(input) {
+	const options = input;
+	const logger = options.logger ?? console;
+	const configuredSecrets = options.secrets === void 0 ? null : parseSecrets(options.secrets);
+	const tolerance = options.toleranceSeconds;
+	const hooks = options;
+	const getAccount = options.steward?.accounts.get?.bind(options.steward.accounts);
+	const readState = options.steward?.accounts.state?.bind(options.steward.accounts);
+	const refetch = options.refetch ?? options.steward !== void 0;
+	if (options.includeProfile && !getAccount) throw new StewardConfigError({ message: "Webhooks: includeProfile için steward.accounts.get gerekli" });
+	if (refetch && !readState) throw new StewardConfigError({ message: "Webhooks: refetch için steward.accounts.state gerekli (ya da refetch: false)" });
+	if (tolerance !== void 0 && !(Number.isFinite(tolerance) && tolerance >= 0)) throw new StewardConfigError({ message: "Webhooks: toleranceSeconds negatif olmayan bir sayı olmalı" });
+	const ok = (handled) => ({
+		status: 200,
+		body: {
+			ok: true,
+			handled
+		}
+	});
+	const fail = (status, error) => ({
+		status,
+		body: { error }
+	});
+	async function fetchProfile(d) {
+		if (!options.includeProfile || !getAccount || d.kind !== "event" || d.causeType === null) return void 0;
+		const hook = NOTIFICATION_HOOKS[d.causeType];
+		if (!hook || !options[hook]) return void 0;
+		return (await getAccount(d.ref, { include: ["profile"] })).profile ?? null;
+	}
+	async function runHooks(d, profile) {
+		if (isDeletion(d)) {
+			await options.cache?.invalidate?.(d.ref);
+			await options.onAccountDeleted?.({
+				ref: d.ref,
+				cause: DELETED,
+				event: d.event,
+				state: d.state
+			});
+			await options.after?.({
+				ref: d.ref,
+				cause: d.cause,
+				event: d.event,
+				state: d.state,
+				handled: "deleted"
+			});
+			return "deleted";
+		}
+		if (d.state) {
+			await options.cache?.prime(d.state);
+			if (await options.onStateChanged?.({
+				ref: d.ref,
+				state: d.state,
+				cause: d.cause,
+				event: d.event
+			}) === "ignore") return "ignored";
+		}
+		if (d.kind === "unknown") await options.onUnknownEvent?.({
+			ref: d.ref,
+			cause: d.cause,
+			event: d.event,
+			state: d.state
+		});
+		else if (d.causeType !== null) {
+			const args = {
+				ref: d.ref,
+				cause: d.causeType,
+				event: d.event,
+				state: d.state
+			};
+			await hooks[eventHookName(d.causeType)]?.(args);
+			const notification = NOTIFICATION_HOOKS[d.causeType];
+			if (notification) await hooks[notification]?.(profile === void 0 ? args : {
+				...args,
+				profile
+			});
+		}
+		const handled = d.state ? "received" : "no_state";
+		await options.after?.({
+			ref: d.ref,
+			cause: d.cause,
+			event: d.event,
+			state: d.state,
+			handled
+		});
+		return handled;
+	}
+	async function receive(rawBody, headers) {
+		const secrets = configuredSecrets ?? parseSecrets(process.env.STEWARD_WEBHOOK_SECRET);
+		if (secrets.length === 0) {
+			logger.error("ALARM steward webhook: imza sırrı tanımlı değil (STEWARD_WEBHOOK_SECRET); steward yeniden deneyecek", {});
+			return fail(503, "not_configured");
+		}
+		const verified = verifyWebhookRaw(secrets, headers, rawBody, tolerance === void 0 ? {} : { toleranceSeconds: tolerance });
+		if (!verified.ok) {
+			logger.warn("steward webhook reddedildi", { reason: verified.reason });
+			return fail(401, verified.reason);
+		}
+		const parsed = parseDelivery(verified.eventId, rawBody);
+		if (parsed.kind === "invalid") {
+			logger.error(`ALARM steward webhook: imzalı gövde sözleşmeye uymuyor (${parsed.detail}); sözleşme sürümü?`, { eventId: verified.eventId });
+			return fail(400, parsed.reason);
+		}
+		if (parsed.kind === "ping") return ok("ping");
+		let d = parsed;
+		const context = {
+			eventId: d.event.id,
+			type: d.event.type,
+			ref: d.ref,
+			cause: d.cause
+		};
+		if (d.kind === "unknown") logger.warn("steward webhook: tanınmayan event tipi (SDK sürümü eski?)", context);
+		if (refetch && readState && !isDeletion(d)) try {
+			d = {
+				...d,
+				state: await readState(d.ref)
+			};
+		} catch (error) {
+			const { code, requestId } = typeof error === "object" && error !== null ? error : {};
+			if (code === "account_deleted") {
+				logger.warn("steward webhook: hesap silinmiş; silmeden önceki teslimat hook'suz geçildi", context);
+				try {
+					await options.cache?.invalidate?.(d.ref);
+				} catch (cacheError) {
+					logger.warn("steward webhook: cache.invalidate fırlattı", {
+						...context,
+						error: describeError(cacheError)
+					});
+				}
+				return ok("deleted");
+			}
+			logger.error("steward webhook: güncel durum okunamadı; steward yeniden deneyecek", {
+				...context,
+				error: describeError(error),
+				code: typeof code === "string" ? code : null,
+				requestId: typeof requestId === "string" ? requestId : null
+			});
+			return fail(503, "state_unavailable");
+		}
+		else if (d.state === null && d.kind === "event") logger.warn("steward webhook: gövde tam AccountState taşımıyor (yükseltme öncesi kuyruk); onStateChanged atlandı, neden hook'ları koşuyor", context);
+		let profile;
+		try {
+			profile = await fetchProfile(d);
+		} catch (error) {
+			logger.error("steward webhook: fatura profili okunamadı; steward yeniden deneyecek", {
+				...context,
+				error: describeError(error)
+			});
+			return fail(503, "profile_unavailable");
+		}
+		try {
+			const handled = await runHooks(d, profile);
+			if (handled === "ignored") logger.warn("steward webhook: bilinmeyen hesap (onStateChanged \"ignore\"); diğer hook'lar ve after atlandı", context);
+			return ok(handled);
+		} catch (error) {
+			logger.error("steward webhook: hook başarısız; steward yeniden deneyecek", {
+				...context,
+				error: describeError(error)
+			});
+			return fail(503, "hook_failed");
+		}
+	}
+	return {
+		receive,
+		async handle(req) {
+			let rawBody = null;
+			try {
+				rawBody = await req.text();
+			} catch (error) {
+				logger.error("steward webhook: istek gövdesi okunamadı", { error: describeError(error) });
+			}
+			const result = rawBody === null ? fail(400, "invalid_payload") : await receive(rawBody, req.headers);
+			return new Response(JSON.stringify(result.body), {
+				status: result.status,
+				headers: { "content-type": "application/json" }
+			});
+		}
+	};
+}
+//#endregion
+export { Checkout, CustomerPortal, Webhooks };

package/dist/testing/fixtures/events/LOCK.json

@@ -0,0 +1,27 @@
+{
+  "apiVersion": "2026-10-01",
+  "sha256": "00b36567f8972e90997f6436efcaab7e75e1104301ace40941ba3eaaea908582",
+  "additions": [
+    {
+      "since": "0.2.0",
+      "files": [
+        "account.state_changed.json"
+      ],
+      "sha256": "af2584923b587bd1d50f8aeceaca4617e76a328d092a0f08cf5b8306fe0bd2d4"
+    },
+    {
+      "since": "F4f",
+      "files": [
+        "invoice.voided.json"
+      ],
+      "sha256": "26bde921ce073e6f1634612b0b8d122835972647c8feb4608f54e776559cdeaf"
+    },
+    {
+      "since": "F4e",
+      "files": [
+        "account.deleted.json"
+      ],
+      "sha256": "68c3507812304c790d73ccaffa82389c7fd25c9be85a1ca405722597921c8b32"
+    }
+  ]
+}

package/dist/testing/fixtures/events/account.deleted.json

@@ -0,0 +1,36 @@
+{
+  "id": "evt_0192f1a0-0000-7000-8000-000000000030",
+  "type": "account.deleted",
+  "apiVersion": "2026-10-01",
+  "createdAt": "2026-10-05T09:00:00Z",
+  "product": "example",
+  "accountRef": "acct_42",
+  "data": {
+    "account": {
+      "ref": "acct_42",
+      "displayName": "",
+      "version": 9,
+      "updatedAt": "2026-10-05T09:00:00Z",
+      "planCode": "free",
+      "accessState": "active",
+      "entitlements": {
+        "max_users": 3,
+        "max_devices": 15,
+        "max_networks_per_account": 1,
+        "max_approved_routes": 0,
+        "max_exit_nodes": 0
+      },
+      "catalogVersion": "3f2a9c0e7b41d8a65c09e1f4b7d2a8c3",
+      "subscription": null,
+      "openCheckout": null,
+      "profile": {
+        "present": false,
+        "kind": null
+      }
+    },
+    "detail": {
+      "deletedAt": "2026-10-05T09:00:00Z",
+      "actorRef": "user:7"
+    }
+  }
+}