@stewardhq/sdk 0.2.0 → 0.5.0

package/dist/server.d.ts

@@ -1,7 +1,6 @@
-import { Fn as PortalSession, Gt as CheckoutSessionResponse, In as PortalSessionCreateInput, Qn as CheckoutSessionCreated, Wn as CheckoutPrefill, Wr as Interval, Yn as CheckoutSessionCreateInput, tr as CheckoutStatus } 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 { r as MutationOptions } from "./_chunks/steward.js";
-import { r as StewardLogger, t as StewardLocale } from "./_chunks/locale.js";
+import { Ba as CheckoutStatus, La as CheckoutSessionCreated, Pa as CheckoutSessionCreateInput, ba as PortalSession, di as CheckoutSessionResponse, ka as CheckoutPrefill, xa as PortalSessionCreateInput, xc as Interval, yo as AccountBenefit } from "./_chunks/index.js";
+import { O as AccountInclude, U as AccountState, Y as BillingProfile, a as BillingEvent, f as EventType, n as AnyBillingEvent, o as BillingEventOf, u as EventDetail } from "./_chunks/events.js";
+import { r as StewardLogger, s as MutationOptions, 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
@@ -148,6 +147,35 @@ type NotificationHookArgs<T extends CauseEventType, S extends HookState = HookSt
   /** `includeProfile: true` ise steward'dan okunan fatura profili (e-posta; K15). */
   profile?: BillingProfile | null;
 };
+/** Benefit grant types with a dedicated hook (`onBenefitGranted` / `onBenefitRevoked` / `onBenefitCycled`). */
+type BenefitHookEventType = "benefit_grant.created" | "benefit_grant.revoked" | "benefit_grant.cycled";
+type BenefitHookArgs<T extends BenefitHookEventType, S extends HookState = HookState> = {
+  ref: string;
+  cause: T;
+  /** The benefit grant event itself (the hook does not run for an `account.state_changed`, which carries no benefit). */
+  event: BillingEventOf<T>;
+  /** `event.data.detail.benefit`: the benefit as granted or revoked at the time of the event. */
+  benefit: AccountBenefit;
+  /** Grant log row id (`event.data.detail.grantId`). */
+  grantId: string;
+  /** The delivery's full state (live with refetch): `state.benefits` is the current set. */
+  state: S;
+};
+/** `onBenefitCycled` (`benefit_grant.cycled`): the renewed `meter_credit` grant and its new meter period. */
+type BenefitCycledHookArgs<S extends HookState = HookState> = BenefitHookArgs<"benefit_grant.cycled", S> & {
+  periodStart: string;
+  periodEnd: string;
+};
+/** `onMeterThreshold` (`meter.threshold_crossed`, cause hook). */
+type MeterThresholdHookArgs<S extends HookState = HookState> = CauseHookArgs<"meter.threshold_crossed", S> & {
+  /** The event's detail when the event itself was delivered; `null` for an `account.state_changed` caused by it. */
+  threshold: EventDetail<"meter.threshold_crossed"> | null;
+};
+/** `onMeterPeriodClosed` (`meter.period_closed`, cause hook). */
+type MeterPeriodClosedHookArgs<S extends HookState = HookState> = CauseHookArgs<"meter.period_closed", S> & {
+  /** The event's detail when the event itself was delivered; `null` for an `account.state_changed` caused by it. */
+  period: EventDetail<"meter.period_closed"> | null;
+};
 type UnknownEventArgs<S extends HookState = HookState> = {
   ref: string;
   cause: string;
@@ -187,7 +215,13 @@ type WebhooksCache = {
   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> & {
+type WebhooksOptions<S extends HookState = HookState> = Omit<CauseHooks<S>, "onMeterPeriodClosed"> & {
+  /** `meter.period_closed` (cause hook); `period` is the event's detail when the event itself was delivered. */
+  onMeterPeriodClosed?: Hook<MeterPeriodClosedHookArgs<S>>;
+  /** A meter's standing changed (`meter.threshold_crossed`, cause hook); after `onMeterThresholdCrossed`. */
+  onMeterThreshold?: Hook<MeterThresholdHookArgs<S>>;
+  /** A `meter_credit` grant was renewed (`benefit_grant.cycled`; the endpoint must list the type). After `onBenefitGrantCycled`. */
+  onBenefitCycled?: Hook<BenefitCycledHookArgs<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). */
@@ -207,6 +241,10 @@ type WebhooksOptions<S extends HookState = HookState> = CauseHooks<S> & {
   onPaymentFailed?: Hook<NotificationHookArgs<"subscription.payment_failed", S>>;
   onSuspended?: Hook<NotificationHookArgs<"subscription.suspended", S>>;
   onTerminated?: Hook<NotificationHookArgs<"subscription.terminated", S>>;
+  /** A benefit was granted (`benefit_grant.created`; the endpoint must list the type). After `onBenefitGrantCreated`. */
+  onBenefitGranted?: Hook<BenefitHookArgs<"benefit_grant.created", S>>;
+  /** A benefit was revoked (`benefit_grant.revoked`; the endpoint must list the type). After `onBenefitGrantRevoked`. */
+  onBenefitRevoked?: Hook<BenefitHookArgs<"benefit_grant.revoked", 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>>;
@@ -233,4 +271,4 @@ export declare function Webhooks<const R extends boolean | undefined = undefined
   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 };
+export type { AfterArgs, BenefitCycledHookArgs, BenefitHookArgs, BenefitHookEventType, CauseEventType, CauseHookArgs, CheckoutCache, CheckoutCreateInput, CheckoutCreated, CheckoutHandler, CheckoutOptions, CheckoutResult, CheckoutSteward, ConsentDoc, CustomerPortalClient, CustomerPortalCreateArgs, CustomerPortalOptions, CustomerPortalSteward, EventHookName, HookState, MeterPeriodClosedHookArgs, MeterThresholdHookArgs, NotificationHookArgs, StateChangedArgs, UnknownEventArgs, WebhookErrorCode, WebhookHandled, WebhookRequest, WebhookResult, WebhooksCache, WebhooksHandler, WebhooksHookState, WebhooksOptions, WebhooksSteward };

package/dist/server.js

@@ -1,4 +1,4 @@
-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 { Gn as IdSchema, Hn as ExternalRefSchema, Mn as ActorRefSchema, a as EVENT_TYPES, l as PING_EVENT_TYPE, r as BillingEventSchema, t as AnyBillingEventSchema, u as PingSchema, w as AccountStateSchema } from "./_chunks/events.js";
 import "./_chunks/src.js";
 import { n as StewardConfigError, r as StewardContractError, t as StewardApiError } from "./_chunks/errors.js";
 import { i as verifyWebhookRaw } from "./_chunks/webhook.js";
@@ -126,6 +126,12 @@ const NOTIFICATION_HOOKS = {
 	"subscription.suspended": "onSuspended",
 	"subscription.terminated": "onTerminated"
 };
+const BENEFIT_HOOKS = {
+	"benefit_grant.created": "onBenefitGranted",
+	"benefit_grant.revoked": "onBenefitRevoked",
+	"benefit_grant.cycled": "onBenefitCycled"
+};
+const isBenefitHookEvent = (event) => Object.hasOwn(BENEFIT_HOOKS, event.type);
 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);
@@ -282,12 +288,33 @@ function Webhooks(input) {
 				event: d.event,
 				state: d.state
 			};
-			await hooks[eventHookName(d.causeType)]?.(args);
+			const causeArgs = d.causeType === "meter.period_closed" ? {
+				...args,
+				period: d.event.type === "meter.period_closed" ? d.event.data.detail : null
+			} : args;
+			await hooks[eventHookName(d.causeType)]?.(causeArgs);
 			const notification = NOTIFICATION_HOOKS[d.causeType];
 			if (notification) await hooks[notification]?.(profile === void 0 ? args : {
 				...args,
 				profile
 			});
+			if (isBenefitHookEvent(d.event)) {
+				const { benefit, grantId } = d.event.data.detail;
+				const period = d.event.type === "benefit_grant.cycled" ? {
+					periodStart: d.event.data.detail.periodStart,
+					periodEnd: d.event.data.detail.periodEnd
+				} : {};
+				await hooks[BENEFIT_HOOKS[d.event.type]]?.({
+					...args,
+					benefit,
+					grantId,
+					...period
+				});
+			}
+			if (d.causeType === "meter.threshold_crossed") await hooks.onMeterThreshold?.({
+				...args,
+				threshold: d.event.type === "meter.threshold_crossed" ? d.event.data.detail : null
+			});
 		}
 		const handled = d.state ? "received" : "no_state";
 		await options.after?.({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stewardhq/sdk",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Steward SDK: contract schemas, typed API client and webhook signing.",
   "type": "module",
   "repository": {
@@ -33,11 +33,6 @@
       "types": "./dist/webhook/web.d.ts",
       "default": "./dist/webhook/web.js"
     },
-    "./testing": {
-      "types": "./dist/testing.d.ts",
-      "default": "./dist/testing.js"
-    },
-    "./testing/fixtures/events/*": "./dist/testing/fixtures/events/*",
     "./package.json": "./package.json"
   },
   "files": [
@@ -45,8 +40,7 @@
   ],
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org",
-    "provenance": true
+    "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
     "zod": "^4.0.0"
@@ -55,9 +49,9 @@
     "@types/node": "^24.13.3",
     "tsdown": "^0.23.0",
     "typescript": "^5.9.0",
-    "vitest": "^3.0.0",
+    "vitest": "^5.0.1",
     "workerd": "^1.20260916.1",
-    "@steward/contract": "0.2.0"
+    "@steward/contract": "0.4.0"
   },
   "scripts": {
     "build": "tsdown && node scripts/check-dist.mjs",

package/dist/_chunks/steward.d.ts

@@ -1,189 +0,0 @@
-import { An as Stats, B as WebhookEndpointRotateInput, F as WebhookEndpoint, Fn as PortalSession, Gt as CheckoutSessionResponse, I as WebhookEndpointCreateInput, In as PortalSessionCreateInput, Qn as CheckoutSessionCreated, R as WebhookEndpointList, Sn as CancelSubscriptionInput, Tn as GrantCreateInput, Ut as CancelSubscriptionResponse, Vt as AccountUpsertResponse, Yn as CheckoutSessionCreateInput, dr as Catalog, en as InvoiceIssueResponse, g as DoctorReport, gn as ManualInvoiceInput, hr as CatalogSyncResult, ht as PlanSetInput, in as ManualInvoiceResponse, lr as AccountsRefreshResult, nn as InvoiceVoidResponse, nt as ProductSettingsPatch, pn as InvoiceVoidInput, pr as CatalogSyncInput, qt as GrantCreateResponse, sn as InvoiceIssueInput, tt as ProductSettings, wt as ResyncResult, yt as PlanSetResponse, zt as AccountDetail } from "./index.js";
-import { C as AccountDeleteResponse, D as AccountInclude, F as AccountState, z as AccountUpsertInput } from "./events.js";
-//#region ../contract/src/client.d.ts
-type CallOptions = {
-  idempotencyKey?: string;
-  actorRef?: string;
-};
-/** `getAccountState` sonucu: 304'te gövde yok, elindeki durum güncel. */
-type AccountStateRead = {
-  notModified: false;
-  etag: string | null;
-  state: AccountState;
-} | {
-  notModified: true;
-  etag: string;
-};
-//#endregion
-//#region src/retry.d.ts
-type RetryClass = "network" | "5xx" | "429";
-type RetryOptions = {
-  /** İlk istekten sonraki en çok tekrar sayısı; 0 kapatır. Varsayılan 2. */
-  attempts?: number;
-  /** Tekrar denenen hata sınıfları. Varsayılan hepsi. */
-  on?: readonly RetryClass[];
-  /** Tek bir beklemenin üst sınırı (Retry-After dahil), ms. Varsayılan 5000. */
-  maxDelayMs?: number;
-  /** Test için: bekleme. Varsayılan `setTimeout`. */
-  sleep?: (ms: number) => Promise<void>;
-  /** Test için: jitter kaynağı, [0, 1). Varsayılan `Math.random`. */
-  random?: () => number;
-};
-//#endregion
-//#region src/steward.d.ts
-type StewardEnv = Readonly<Record<string, string | undefined>>;
-type StewardOptions = {
-  /** Varsayılan `STEWARD_URL`. Ürün adresi ve anahtarı ikisi de yoksa ve admin ayarları tamsa istemci yalnızca `admin.*` içindir. */
-  baseUrl?: string;
-  /** Varsayılan `STEWARD_API_KEY`. */
-  apiKey?: string;
-  /** Ayarların okunduğu ortam; varsayılan `process.env` (varsa). */
-  env?: StewardEnv;
-  fetch?: typeof fetch;
-  /** Deneme başına zaman aşımı, ms. Varsayılan 10 sn. */
-  timeoutMs?: number;
-  /**
-   * Mutasyonlarda varsayılan `X-Actor-Ref` (ör. `system`); çağrıdaki `actorRef` ezer. İkisi de
-   * yoksa mutasyon istek göndermeden `StewardConfigError` (`actor_ref_required`) fırlatır.
-   */
-  actorRef?: string;
-  /** Varsayılan `STEWARD_ADMIN_URL`; yalnızca `admin.*` için. */
-  adminBaseUrl?: string;
-  /** Varsayılan `STEWARD_ADMIN_API_KEY`; yalnızca `admin.*` için. */
-  adminApiKey?: string;
-  retries?: RetryOptions;
-};
-/** Mutasyon çağrısı seçenekleri: `Idempotency-Key` ve `X-Actor-Ref`. */
-type MutationOptions = CallOptions;
-/** Koşullu katalog okuması: 304'te gövde yok, elindeki katalog güncel. */
-type CatalogRead = {
-  notModified: false;
-  etag: string | null;
-  catalog: Catalog;
-} | {
-  notModified: true;
-  etag: string;
-};
-type InvoiceDocument = {
-  contentType: string;
-  bytes: Uint8Array;
-};
-/** `GET /v1/me`: anahtarın ürünü ve kapsamı (kurulum doğrulaması). */
-type StewardMe = {
-  product: string;
-  keyName: string;
-  scope: "product" | "admin";
-};
-type Steward = {
-  accounts: {
-    /** `PUT /v1/accounts/{ref}` — hesabı oluşturur ya da günceller. */
-    upsert(ref: string, input: AccountUpsertInput, options?: MutationOptions): Promise<AccountUpsertResponse>;
-    get(ref: string, options?: {
-      include?: readonly AccountInclude[];
-    }): Promise<AccountDetail>;
-    /** `GET /v1/accounts/{ref}/state`. */
-    state(ref: string): Promise<AccountState>;
-    /** Koşullu durum okuması (önbellekler için): `etag` verilir ve durum değişmediyse `{notModified: true}`. */
-    readState(ref: string, options?: {
-      etag?: string;
-    }): Promise<AccountStateRead>;
-    /**
-     * `PUT /v1/accounts/{ref}/plan` — atomik plan (K6): aktif plan grant'leri tek plan
-     * grant'iyle değişir, `planCode: null` kaldırır. Canlı abonelik planı hedefi
-     * geçiyorsa `mode: "ensure"` (varsayılan) sonuç + `warnings`, `"strict"`
-     * `StewardApiError` `subscription_plan_higher` (409). Yanıttaki `account` önbelleğe `prime` edilebilir.
-     */
-    setPlan(ref: string, input: PlanSetInput, options?: MutationOptions): Promise<PlanSetResponse>;
-    /** `POST /v1/accounts/{ref}/resync` — saklı durumu `account.state_changed` (`cause: "resync"`) olarak yeniden yayınlar; version değişmez. */
-    resync(ref: string, options?: MutationOptions): Promise<ResyncResult>;
-    /**
-     * `DELETE /v1/accounts/{ref}` — KVKK anonimleştirme (F4e): profil ve kişisel veri silinir,
-     * faturalar kalır → `{ref, deletedAt}`. Sonra hesabın her ucu `account_deleted` (410; aynı
-     * ref'le `upsert` dahil). Canlı abonelikte `subscription_active` (409; önce `immediate`
-     * iptal), formu açık checkout'ta `checkout_in_progress` (409; süresi dolunca tekrar);
-     * zaten silinmişse `account_deleted` — iş tekrarında başarı sayılabilir.
-     */
-    delete(ref: string, options?: MutationOptions): Promise<AccountDeleteResponse>;
-  };
-  checkoutSessions: {
-    create(ref: string, input: CheckoutSessionCreateInput, options?: MutationOptions): Promise<CheckoutSessionCreated>;
-    get(id: string): Promise<CheckoutSessionResponse>;
-  };
-  /**
-   * Hosted müşteri portalı (F3a): `POST /v1/accounts/{ref}/portal-sessions` → `{id, url, expiresAt}`.
-   * Tarayıcı `url`e yönlendirilir (iptal, ödemeyi yeniden dene, fatura, profil steward'da).
-   * Yetki üründe; `actorRef` portalı açan kullanıcı. Durum değişmez, event yok.
-   */
-  portalSessions: {
-    create(ref: string, input?: PortalSessionCreateInput, options?: MutationOptions): Promise<PortalSession>;
-  };
-  subscriptions: {
-    cancel(id: string, input: CancelSubscriptionInput, options?: MutationOptions): Promise<CancelSubscriptionResponse>;
-  };
-  grants: {
-    create(ref: string, input: GrantCreateInput, options?: MutationOptions): Promise<GrantCreateResponse>;
-    revoke(id: string, options?: MutationOptions): Promise<void>;
-  };
-  invoices: {
-    issue(id: string, input: InvoiceIssueInput, options?: MutationOptions): Promise<InvoiceIssueResponse>;
-    document(id: string): Promise<InvoiceDocument>;
-    /**
-     * `POST /v1/accounts/{ref}/invoices` (F4f) — manuel taslak fatura (Enterprise satışı); `issue` ile kesilir.
-     * Hesabın fatura profili gerekir (422 `billing_profile_required`). `invoice.created` yayınlanır, durum değişmez.
-     */
-    createManual(ref: string, input: ManualInvoiceInput, options?: MutationOptions): Promise<ManualInvoiceResponse>;
-    /**
-     * `POST /v1/invoices/{id}/void` (F4f) — yalnızca manuel fatura (taslak ya da kesilmiş; numara ve belge kalır).
-     * Ödemeli fatura 409 `invoice_has_payment`, zaten void 409 `invoice_not_voidable`. `invoice.voided` yayınlanır.
-     */
-    void(id: string, input: InvoiceVoidInput, options?: MutationOptions): Promise<InvoiceVoidResponse>;
-  };
-  catalog: {
-    get(): Promise<Catalog>;
-    /** Conditional read (`If-None-Match`); used by `steward catalog push` to report the current version. */
-    read(options?: {
-      etag?: string;
-    }): Promise<CatalogRead>;
-  };
-  stats(): Promise<Stats>;
-  me(): Promise<StewardMe>;
-  /**
-   * `GET /v1/doctor` — kurulum teşhisi (K11): katalog senkronu, sağlayıcı, ayarlar, hosted
-   * sayfa hazırlığı, endpoint teslimat teşhisi (`wrong_secret` = son teslimat 401),
-   * dunning ve `warnings[{code, severity, message}]`; `ok` = `error` önemde uyarı yok.
-   * Ürün anahtarıyla çalışır (yalnızca admin ayarlı istemcide admin anahtarıyla). Sağlayıcı
-   * sağlığı yanıtı veren pod'un gözlemidir.
-   */
-  doctor(): Promise<DoctorReport>;
-  /** Admin kapsamlı uçlar: `adminBaseUrl`/`adminApiKey` (ya da `STEWARD_ADMIN_*`) gerekir. */
-  admin: {
-    catalog: {
-      sync(input: CatalogSyncInput, options?: MutationOptions): Promise<CatalogSyncResult>;
-    };
-    accounts: {
-      refresh(options?: MutationOptions): Promise<AccountsRefreshResult>;
-    };
-    settings: {
-      /** `GET /v1/admin/settings`. */
-      get(): Promise<ProductSettings>;
-      /** `PATCH /v1/admin/settings`: verilmeyen alan değişmez, `null` temizler, `branding` sığ birleşir. */
-      update(patch: ProductSettingsPatch, options?: MutationOptions): Promise<ProductSettings>;
-    };
-    /**
-     * Webhook endpoint'leri. Sırrı çağıran üretir (`generateWebhookSecret()`) ve
-     * saklar; steward hiçbir yanıtta geri vermez.
-     */
-    endpoints: {
-      list(): Promise<WebhookEndpointList>;
-      /** `eventTypes` verilmezse yalnızca `account.state_changed`. */
-      create(input: WebhookEndpointCreateInput, options?: MutationOptions): Promise<WebhookEndpoint>;
-      /** Yeni sır; eskisi ürün geçişi bitene kadar ikinci imza olarak kalır. */
-      rotate(id: string, input: WebhookEndpointRotateInput, options?: MutationOptions): Promise<WebhookEndpoint>;
-      /** `status: inactive`; geri alınmaz (yeni endpoint açılır). */
-      deactivate(id: string, options?: MutationOptions): Promise<WebhookEndpoint>;
-    };
-  };
-};
-declare function createSteward(options?: StewardOptions): Steward;
-//#endregion
-export { StewardEnv as a, createSteward as c, AccountStateRead as d, Steward as i, RetryClass as l, InvoiceDocument as n, StewardMe as o, MutationOptions as r, StewardOptions as s, CatalogRead as t, RetryOptions as u };