@stewardhq/sdk 0.2.0 → 0.5.0

package/dist/_chunks/locale.d.ts

@@ -1,3 +1,271 @@
+import { Ai as MeResponse, Bn as ResyncResult, Cr as EventsIngestInput, Ei as InvoiceWaiveResponse, Fn as PlanSetResponse, G as WebhookEndpoint, Go as AccountMeters, Hi as InvoicePaymentSessionCreateInput, J as WebhookEndpointList, K as WebhookEndpointCreateInput, La as CheckoutSessionCreated, Li as InvoiceIssueInput, Mt as ProductSettingsPatch, Oi as ManualInvoiceResponse, Pa as CheckoutSessionCreateInput, Pi as UncancelSubscriptionResponse, Qi as ManualInvoiceInput, Si as InvoiceIssueResponse, T as DoctorReport, Tr as EventsIngestResult, Vi as InvoicePaymentSession, Vs as MeterPeriodList, X as WebhookEndpointRotateInput, Ya as AccountsRefreshResult, Yi as InvoiceWaiveInput, Yo as CreditGrantInput, Za as Catalog, ai as AccountUpsertResponse, ba as PortalSession, di as CheckoutSessionResponse, ga as SubscriptionChangeInput, hi as GrantCreateResponse, hs as MeterChargeList, ia as CancelSubscriptionInput, jn as PlanSetInput, jt as ProductSettings, li as ChangeSubscriptionResponse, pa as Stats, pi as CreditGrantResponse, qi as InvoiceVoidInput, ri as AccountDetail, ro as CatalogSyncResult, sa as GrantCreateInput, si as CancelSubscriptionResponse, to as CatalogSyncInput, wi as InvoiceVoidResponse, xa as PortalSessionCreateInput } from "./index.js";
+import { O as AccountInclude, U as AccountState, q as AccountUpsertInput, w as AccountDeleteResponse } 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;
+};
+/** `getAccountMeters` result: on 304 there is no body and the meters you hold are current. */
+type AccountMetersRead = {
+  notModified: false;
+  etag: string | null;
+  meters: AccountMeters;
+} | {
+  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ı), and since billing core the
+ * steward's `capabilities` (`STEWARD_CAPABILITIES`; absent from an older steward). The contract's
+ * `MeResponse`.
+ */
+type StewardMe = MeResponse;
+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` — atomic plan (K6): active plan grants are replaced by one plan
+     * grant, `planCode: null` removes it. Entitlements are the layered merge of everything granted
+     * (M35, no rank): `mode` is accepted and ignored, `warnings` is always empty. The response's
+     * `account` can be `prime`d into a cache.
+     */
+    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 customer portal (F3a): `POST /v1/accounts/{ref}/portal-sessions` → `{id, url, expiresAt}`.
+   * Redirect the browser to `url` (cancel and undo cancellation, change plan, "Pay invoice",
+   * invoices and the billing profile live in steward). Authorization is the product's; `actorRef` is
+   * the user opening the portal. Opening changes no state and emits no event.
+   */
+  portalSessions: {
+    create(ref: string, input?: PortalSessionCreateInput, options?: MutationOptions): Promise<PortalSession>;
+  };
+  subscriptions: {
+    cancel(id: string, input: CancelSubscriptionInput, options?: MutationOptions): Promise<CancelSubscriptionResponse>;
+    /**
+     * `POST /v1/subscriptions/{id}/change` (billing core, MF9): schedules a plan, interval or price
+     * change (`price: "current"` re-locks the price's current amount and the plan's current metered
+     * rates, M20/M36) for the next period (`when: "next_period"`);
+     * `account.subscription.scheduledChange` shows it and the next renewal invoice is written from
+     * the new terms. The current plan and interval take a pending change back. 409
+     * `already_subscribed` (another live subscription holds or is moving to the plan),
+     * `meter_already_billed` (the target prices a meter another live subscription bills); 422
+     * `plan_not_found`, `plan_not_sellable`, `subscription_change_invalid` when not possible.
+     */
+    change(id: string, input: SubscriptionChangeInput, options?: MutationOptions): Promise<ChangeSubscriptionResponse>;
+    /**
+     * `POST /v1/subscriptions/{id}/uncancel` (billing core, MF9): takes back a cancellation scheduled
+     * for the period end. 409 `cancel_not_scheduled` (none scheduled), `already_canceled` (ended).
+     */
+    uncancel(id: string, options?: MutationOptions): Promise<UncancelSubscriptionResponse>;
+  };
+  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>;
+    /**
+     * `POST /v1/invoices/{id}/payment-sessions` (billing core): opens steward's hosted pay page for an
+     * unpaid invoice → `{id, url, expiresAt}`; redirect the customer to `url` (the product's own "Pay
+     * invoice" button; e-mails and the portal link to the same page). `url` carries the page key: do
+     * not log it. 409 `invoice_not_payable` when the invoice is not unpaid. Opening changes no state.
+     */
+    createPaymentSession(id: string, input?: InvoicePaymentSessionCreateInput, options?: MutationOptions): Promise<InvoicePaymentSession>;
+    /**
+     * `POST /v1/invoices/{id}/waive` (billing core): forgives an unpaid invoice (`paymentStatus:
+     * "waived"`, e.g. before deleting the account; it leaves `account.openInvoices`). 409
+     * `invoice_not_waivable` otherwise.
+     */
+    waive(id: string, input: InvoiceWaiveInput, options?: MutationOptions): Promise<InvoiceWaiveResponse>;
+  };
+  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>;
+  };
+  /**
+   * Metering (phase 2): the product's events (`POST /v1/events/ingest`). For tracking from request
+   * handlers use `Events()` (queued, batched, retried in the background).
+   */
+  events: {
+    /**
+     * `POST /v1/events/ingest`: 1–1 000 events → `{inserted, duplicates, rejected[]}`. Every event
+     * needs an `externalId` (unique within the product; the lasting dedup key, M10). One
+     * `Idempotency-Key` per call, reused by every retry of it; `503 events_backlog` is retried after
+     * `Retry-After`. `rejected` lists per-event rejections (`account_not_found`, `account_deleted`,
+     * `timestamp_out_of_range`); a structurally invalid batch is `422` as a whole.
+     */
+    ingest(input: EventsIngestInput, options?: MutationOptions): Promise<EventsIngestResult>;
+  };
+  /** Metering (phase 2): meter reads (M13). For gates and the product's meter card use `Meters()` (cached, with pending units). */
+  meters: {
+    /** `GET /v1/accounts/{ref}/meters`: the open period of every meter. */
+    get(ref: string): Promise<AccountMeters>;
+    /** Conditional read (`If-None-Match`; ETag = the account's meter sequence): unchanged → `{notModified: true}`. */
+    read(ref: string, options?: {
+      etag?: string;
+    }): Promise<AccountMetersRead>;
+    /** `GET /v1/accounts/{ref}/meters/periods`: closed meter periods, newest first. */
+    periods(ref: string, options?: {
+      limit?: number;
+    }): Promise<MeterPeriodList>;
+  };
+  /** Metering (phase 2): one-off credits (ops; goodwill, campaigns). */
+  credits: {
+    /**
+     * `POST /v1/accounts/{ref}/credits` `{meter, units, reason}`: credit for the meter's open period,
+     * written to the append-only credit ledger with the actor → `{entry, meters, account?}`. 422
+     * `meter_not_found` for a code that is not an active catalog meter.
+     */
+    grant(ref: string, input: CreditGrantInput, options?: MutationOptions): Promise<CreditGrantResponse>;
+  };
+  /** Metering (phase 2, MF5): overage pricing records. */
+  meterCharges: {
+    /** `GET /v1/accounts/{ref}/meter-charges`: newest first, `dry_run` ones included. */
+    list(ref: string): Promise<MeterChargeList>;
+  };
+  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
 //#region src/http-status.d.ts
 type StewardLogger = {
   warn(message: string, context: Record<string, unknown>): void;
@@ -14,4 +282,4 @@ declare function httpStatusFor(err: unknown, options?: {
 //#region src/locale.d.ts
 type StewardLocale = "tr" | "en";
 //#endregion
-export { httpStatusFor as i, HttpStatusResult as n, StewardLogger as r, StewardLocale as t };
+export { CatalogRead as a, Steward as c, StewardOptions as d, createSteward as f, AccountStateRead as g, AccountMetersRead as h, httpStatusFor as i, StewardEnv as l, RetryOptions as m, HttpStatusResult as n, InvoiceDocument as o, RetryClass as p, StewardLogger as r, MutationOptions as s, StewardLocale as t, StewardMe as u };