@omnicross/contracts 0.1.2 → 0.1.4

package/dist/voucher-types.d.cts

@@ -0,0 +1,153 @@
+/**
+ * Voucher (redemption-card) contracts (voucher-redemption #9, design D2/D8).
+ *
+ * A voucher is a redeemable credit/renewal card layered on top of the outbound
+ * key-policy (#4): an admin generates a card (`CC_<entropy>`), a key-holder
+ * redeems it to raise their key's `totalCostLimitUsd` (credit) or extend its
+ * `expiresAt` (renewal). Dependency-light shapes shared across `@omnicross/*`:
+ *
+ *  - `VoucherRecord` — the FROZEN stored card. It is a CREDENTIAL RECORD but holds
+ *    NO plaintext code: only the sha256 `codeHash` (the redeem lookup key) + a
+ *    short display `codePrefix`. The plaintext `CC_…` is returned ONCE at
+ *    generation and NEVER persisted or logged. A secret-scan test asserts no
+ *    `CC_` plaintext survives in a written record.
+ *  - `VoucherGrant` — the ABSOLUTE target recorded on the card at redeem time so
+ *    the apply step (`outboundApiKeysSetPolicy`) is idempotently re-appliable
+ *    after a crash between the CAS flip and the apply (design D4).
+ *  - `VoucherInfo` — the admin-safe DTO (prefix + status + value + caps only,
+ *    NEVER the `codeHash`).
+ *  - `VoucherConfig` — the `voucher` config segment. `enabled` default OFF ⇒ the
+ *    redeem endpoint is inert + no key is ever mutated ⇒ byte-identical zero
+ *    regression, purely additive on #4.
+ *
+ * @module voucher-types
+ */
+/** A card either adds USD credit or extends the key's lifetime. */
+type VoucherType = 'credit' | 'renewal';
+/** Card lifecycle. A card leaves `unredeemed` exactly once (CAS, design D4). */
+type VoucherStatus = 'unredeemed' | 'redeemed' | 'revoked';
+/**
+ * The ABSOLUTE grant a redemption applies to a key (design D4/D5). Recorded on
+ * the voucher AT the CAS flip so re-applying it after an interrupted redeem is a
+ * no-op (idempotent to the absolute value → never double-spends). A `credit`
+ * card records `totalCostLimitUsd`; a `renewal` card records `expiresAt`.
+ */
+interface VoucherGrant {
+    /** Absolute new `totalCostLimitUsd` for the key (credit cards). */
+    totalCostLimitUsd?: number;
+    /** Absolute new `expiresAt` (epoch ms) for the key (renewal cards). */
+    expiresAt?: number;
+}
+/**
+ * One stored redemption card (design D2, FROZEN). Holds a HASH of the code
+ * (never the plaintext) + a display prefix. The `granted*` fields are the
+ * absolute target recorded at redeem time (idempotent re-apply, design D4).
+ */
+interface VoucherRecord {
+    /** Card id (independent of the code). */
+    id: string;
+    /** sha256 of the `CC_<entropy>` code — the redeem lookup key. NEVER plaintext. */
+    codeHash: string;
+    /** Short display prefix for the admin list (e.g. `CC_AB…`). NEVER the full code. */
+    codePrefix: string;
+    /** Credit (adds USD) or renewal (extends expiry). */
+    type: VoucherType;
+    /** `credit`: USD added to the key's `totalCostLimitUsd`. */
+    creditUsd?: number;
+    /** `renewal`: days added to the key's `expiresAt`. */
+    renewalDays?: number;
+    /** Anti-abuse cap on the RESULTING key `totalCostLimitUsd` (design D5). */
+    maxTotalCostLimitUsd?: number;
+    /** Anti-abuse cap on the RESULTING key lifetime, in days from now (design D5). */
+    maxExpiryDays?: number;
+    /** Lifecycle status. */
+    status: VoucherStatus;
+    /** Epoch ms the card was generated. */
+    createdAt: number;
+    /** Epoch ms the card was redeemed (set on the CAS flip). */
+    redeemedAt?: number;
+    /** The key id that redeemed the card (single-key binding). */
+    redeemedByKeyId?: string;
+    /**
+     * Whether the grant has been APPLIED to the key (design D4, revised). The CAS
+     * flip sets this `false`; the apply sets it `true` after a successful
+     * `outboundApiKeysSetPolicy`. `redeemed && grantApplied !== true` means "flipped
+     * but not (yet) applied" — the apply (of the recorded ABSOLUTE below) re-runs on
+     * the next redeem for the key, before that redeem computes anything. It is
+     * `grantApplied` that says "no work left"; the apply itself is idempotent
+     * (re-applying the same absolute is a no-op), so a crash between the apply and
+     * this mark never double-credits.
+     */
+    grantApplied?: boolean;
+    /**
+     * The recorded ABSOLUTE `totalCostLimitUsd` target (the intended final key
+     * value), computed at flip time from the CURRENT policy read INSIDE the per-key
+     * mutex. This is the AUTHORITATIVE apply source on BOTH the first pass and the
+     * reconcile/replay path — re-applying it is idempotent (never double-credits).
+     * Because redemptions for a key are serialized and a stranded card is reconciled
+     * before the next card computes, the recorded absolute is never stale.
+     */
+    grantedTotalCostLimitUsd?: number;
+    /** The recorded ABSOLUTE `expiresAt` target (see `grantedTotalCostLimitUsd`). */
+    grantedExpiresAt?: number;
+    /** Epoch ms the card was revoked. */
+    revokedAt?: number;
+}
+/**
+ * The admin-safe voucher DTO (design D2). NEVER carries the `codeHash` — the
+ * admin sees the display prefix + status + value + caps only. This is the ONLY
+ * projection an admin GET returns.
+ */
+interface VoucherInfo {
+    id: string;
+    codePrefix: string;
+    type: VoucherType;
+    creditUsd?: number;
+    renewalDays?: number;
+    maxTotalCostLimitUsd?: number;
+    maxExpiryDays?: number;
+    status: VoucherStatus;
+    createdAt: number;
+    redeemedAt?: number;
+    redeemedByKeyId?: string;
+    grantApplied?: boolean;
+    grantedTotalCostLimitUsd?: number;
+    grantedExpiresAt?: number;
+    revokedAt?: number;
+}
+/**
+ * The one-time create result: `plaintextOnce` (the `CC_…` code) is shown exactly
+ * once at generation and never again — only its hash is stored (design D3).
+ */
+interface VoucherCreated {
+    id: string;
+    codePrefix: string;
+    type: VoucherType;
+    createdAt: number;
+    /** The plaintext `CC_…` code — the ONLY time it crosses the wire. */
+    plaintextOnce: string;
+}
+/**
+ * The result a successful redeem returns to the key-holder (design D2). Reveals
+ * ONLY this key's own new balance/expiry — never any other card or key.
+ */
+interface VoucherRedeemResult {
+    type: VoucherType;
+    /** The key's new absolute `totalCostLimitUsd` (credit cards). */
+    totalCostLimitUsd?: number;
+    /** The key's new absolute `expiresAt` (epoch ms) (renewal cards). */
+    expiresAt?: number;
+}
+/**
+ * The `voucher` config segment (design D8), normalized like `audit`/`billing`.
+ * `enabled` default FALSE ⇒ the redeem endpoint rejects + no admin generate ⇒ no
+ * key is ever mutated ⇒ byte-identical zero regression, purely additive on #4.
+ */
+interface VoucherConfig {
+    /** Master switch; default FALSE (zero regression, inert product). */
+    enabled: boolean;
+}
+/** Frozen defaults for the `voucher` segment (SSOT). */
+declare const DEFAULT_VOUCHER_CONFIG: VoucherConfig;
+
+export { DEFAULT_VOUCHER_CONFIG, type VoucherConfig, type VoucherCreated, type VoucherGrant, type VoucherInfo, type VoucherRecord, type VoucherRedeemResult, type VoucherStatus, type VoucherType };

package/dist/voucher-types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Voucher (redemption-card) contracts (voucher-redemption #9, design D2/D8).
+ *
+ * A voucher is a redeemable credit/renewal card layered on top of the outbound
+ * key-policy (#4): an admin generates a card (`CC_<entropy>`), a key-holder
+ * redeems it to raise their key's `totalCostLimitUsd` (credit) or extend its
+ * `expiresAt` (renewal). Dependency-light shapes shared across `@omnicross/*`:
+ *
+ *  - `VoucherRecord` — the FROZEN stored card. It is a CREDENTIAL RECORD but holds
+ *    NO plaintext code: only the sha256 `codeHash` (the redeem lookup key) + a
+ *    short display `codePrefix`. The plaintext `CC_…` is returned ONCE at
+ *    generation and NEVER persisted or logged. A secret-scan test asserts no
+ *    `CC_` plaintext survives in a written record.
+ *  - `VoucherGrant` — the ABSOLUTE target recorded on the card at redeem time so
+ *    the apply step (`outboundApiKeysSetPolicy`) is idempotently re-appliable
+ *    after a crash between the CAS flip and the apply (design D4).
+ *  - `VoucherInfo` — the admin-safe DTO (prefix + status + value + caps only,
+ *    NEVER the `codeHash`).
+ *  - `VoucherConfig` — the `voucher` config segment. `enabled` default OFF ⇒ the
+ *    redeem endpoint is inert + no key is ever mutated ⇒ byte-identical zero
+ *    regression, purely additive on #4.
+ *
+ * @module voucher-types
+ */
+/** A card either adds USD credit or extends the key's lifetime. */
+type VoucherType = 'credit' | 'renewal';
+/** Card lifecycle. A card leaves `unredeemed` exactly once (CAS, design D4). */
+type VoucherStatus = 'unredeemed' | 'redeemed' | 'revoked';
+/**
+ * The ABSOLUTE grant a redemption applies to a key (design D4/D5). Recorded on
+ * the voucher AT the CAS flip so re-applying it after an interrupted redeem is a
+ * no-op (idempotent to the absolute value → never double-spends). A `credit`
+ * card records `totalCostLimitUsd`; a `renewal` card records `expiresAt`.
+ */
+interface VoucherGrant {
+    /** Absolute new `totalCostLimitUsd` for the key (credit cards). */
+    totalCostLimitUsd?: number;
+    /** Absolute new `expiresAt` (epoch ms) for the key (renewal cards). */
+    expiresAt?: number;
+}
+/**
+ * One stored redemption card (design D2, FROZEN). Holds a HASH of the code
+ * (never the plaintext) + a display prefix. The `granted*` fields are the
+ * absolute target recorded at redeem time (idempotent re-apply, design D4).
+ */
+interface VoucherRecord {
+    /** Card id (independent of the code). */
+    id: string;
+    /** sha256 of the `CC_<entropy>` code — the redeem lookup key. NEVER plaintext. */
+    codeHash: string;
+    /** Short display prefix for the admin list (e.g. `CC_AB…`). NEVER the full code. */
+    codePrefix: string;
+    /** Credit (adds USD) or renewal (extends expiry). */
+    type: VoucherType;
+    /** `credit`: USD added to the key's `totalCostLimitUsd`. */
+    creditUsd?: number;
+    /** `renewal`: days added to the key's `expiresAt`. */
+    renewalDays?: number;
+    /** Anti-abuse cap on the RESULTING key `totalCostLimitUsd` (design D5). */
+    maxTotalCostLimitUsd?: number;
+    /** Anti-abuse cap on the RESULTING key lifetime, in days from now (design D5). */
+    maxExpiryDays?: number;
+    /** Lifecycle status. */
+    status: VoucherStatus;
+    /** Epoch ms the card was generated. */
+    createdAt: number;
+    /** Epoch ms the card was redeemed (set on the CAS flip). */
+    redeemedAt?: number;
+    /** The key id that redeemed the card (single-key binding). */
+    redeemedByKeyId?: string;
+    /**
+     * Whether the grant has been APPLIED to the key (design D4, revised). The CAS
+     * flip sets this `false`; the apply sets it `true` after a successful
+     * `outboundApiKeysSetPolicy`. `redeemed && grantApplied !== true` means "flipped
+     * but not (yet) applied" — the apply (of the recorded ABSOLUTE below) re-runs on
+     * the next redeem for the key, before that redeem computes anything. It is
+     * `grantApplied` that says "no work left"; the apply itself is idempotent
+     * (re-applying the same absolute is a no-op), so a crash between the apply and
+     * this mark never double-credits.
+     */
+    grantApplied?: boolean;
+    /**
+     * The recorded ABSOLUTE `totalCostLimitUsd` target (the intended final key
+     * value), computed at flip time from the CURRENT policy read INSIDE the per-key
+     * mutex. This is the AUTHORITATIVE apply source on BOTH the first pass and the
+     * reconcile/replay path — re-applying it is idempotent (never double-credits).
+     * Because redemptions for a key are serialized and a stranded card is reconciled
+     * before the next card computes, the recorded absolute is never stale.
+     */
+    grantedTotalCostLimitUsd?: number;
+    /** The recorded ABSOLUTE `expiresAt` target (see `grantedTotalCostLimitUsd`). */
+    grantedExpiresAt?: number;
+    /** Epoch ms the card was revoked. */
+    revokedAt?: number;
+}
+/**
+ * The admin-safe voucher DTO (design D2). NEVER carries the `codeHash` — the
+ * admin sees the display prefix + status + value + caps only. This is the ONLY
+ * projection an admin GET returns.
+ */
+interface VoucherInfo {
+    id: string;
+    codePrefix: string;
+    type: VoucherType;
+    creditUsd?: number;
+    renewalDays?: number;
+    maxTotalCostLimitUsd?: number;
+    maxExpiryDays?: number;
+    status: VoucherStatus;
+    createdAt: number;
+    redeemedAt?: number;
+    redeemedByKeyId?: string;
+    grantApplied?: boolean;
+    grantedTotalCostLimitUsd?: number;
+    grantedExpiresAt?: number;
+    revokedAt?: number;
+}
+/**
+ * The one-time create result: `plaintextOnce` (the `CC_…` code) is shown exactly
+ * once at generation and never again — only its hash is stored (design D3).
+ */
+interface VoucherCreated {
+    id: string;
+    codePrefix: string;
+    type: VoucherType;
+    createdAt: number;
+    /** The plaintext `CC_…` code — the ONLY time it crosses the wire. */
+    plaintextOnce: string;
+}
+/**
+ * The result a successful redeem returns to the key-holder (design D2). Reveals
+ * ONLY this key's own new balance/expiry — never any other card or key.
+ */
+interface VoucherRedeemResult {
+    type: VoucherType;
+    /** The key's new absolute `totalCostLimitUsd` (credit cards). */
+    totalCostLimitUsd?: number;
+    /** The key's new absolute `expiresAt` (epoch ms) (renewal cards). */
+    expiresAt?: number;
+}
+/**
+ * The `voucher` config segment (design D8), normalized like `audit`/`billing`.
+ * `enabled` default FALSE ⇒ the redeem endpoint rejects + no admin generate ⇒ no
+ * key is ever mutated ⇒ byte-identical zero regression, purely additive on #4.
+ */
+interface VoucherConfig {
+    /** Master switch; default FALSE (zero regression, inert product). */
+    enabled: boolean;
+}
+/** Frozen defaults for the `voucher` segment (SSOT). */
+declare const DEFAULT_VOUCHER_CONFIG: VoucherConfig;
+
+export { DEFAULT_VOUCHER_CONFIG, type VoucherConfig, type VoucherCreated, type VoucherGrant, type VoucherInfo, type VoucherRecord, type VoucherRedeemResult, type VoucherStatus, type VoucherType };

package/dist/voucher-types.js

@@ -0,0 +1,7 @@
+// src/voucher-types.ts
+var DEFAULT_VOUCHER_CONFIG = {
+  enabled: false
+};
+export {
+  DEFAULT_VOUCHER_CONFIG
+};

package/dist/webhook-types.cjs

@@ -0,0 +1,40 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/webhook-types.ts
+var webhook_types_exports = {};
+__export(webhook_types_exports, {
+  WEBHOOK_DESTINATION_TYPES: () => WEBHOOK_DESTINATION_TYPES,
+  WEBHOOK_EVENT_KINDS: () => WEBHOOK_EVENT_KINDS
+});
+module.exports = __toCommonJS(webhook_types_exports);
+var WEBHOOK_EVENT_KINDS = [
+  "account.recovery",
+  "account.anomaly",
+  "key.quotaWarning",
+  "key.quotaExceeded",
+  "server.error",
+  "test"
+];
+var WEBHOOK_DESTINATION_TYPES = ["custom", "feishu"];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WEBHOOK_DESTINATION_TYPES,
+  WEBHOOK_EVENT_KINDS
+});

package/dist/webhook-types.d.cts

@@ -0,0 +1,122 @@
+/**
+ * Webhook notification contracts (webhook-notifications, design D1).
+ *
+ * Two small, dependency-light shapes shared across the `@omnicross/*` packages:
+ *  - `WebhookEvent` — the FROZEN discriminated union of operational signals a
+ *    relay can deliver out-of-band (account recovery/anomaly, key quota
+ *    warning/exceeded, server error, and a config-UI `test`). Every payload is
+ *    SECRET-FREE BY CONSTRUCTION: it carries only opaque provider/account ids, a
+ *    key id (NEVER key material or a hash), a coarse state, limit/spend numbers,
+ *    and a sanitized message. Nothing here can hold a token, secret, or hash.
+ *  - `WebhookDestination` / `WebhookConfig` — the destination config schema. A
+ *    destination's `secret` (its HMAC signing key) is the ONLY secret; it is
+ *    encrypted at rest, masked in admin views, and used ONLY to sign an outgoing
+ *    request — it is NEVER placed in a payload or a log line.
+ *
+ * The union is FROZEN: the emit port (core), the dispatcher (daemon), and the
+ * sources (#2 health / #4 quota / server-error) all agree on this one shape.
+ * Adding a destination `type` is additive behind the dispatcher's formatter.
+ *
+ * @module webhook-types
+ */
+/** The coarse anomaly state an account transitioned into (secret-free). */
+type WebhookAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded';
+/** The cost-limit scope a key quota event refers to. */
+type WebhookQuotaScope = 'daily' | 'weekly' | 'total';
+/**
+ * The FROZEN webhook event union (design D1). EVERY field is non-secret:
+ * opaque provider/account ids, a key id (NOT key material/hash), a coarse state,
+ * numbers, and a sanitized message. A test asserts no token/secret/hash string
+ * can appear in any serialized payload.
+ */
+type WebhookEvent = {
+    kind: 'account.recovery';
+    at: number;
+    providerId: string;
+    accountId: string;
+} | {
+    kind: 'account.anomaly';
+    at: number;
+    providerId: string;
+    accountId: string;
+    state: WebhookAnomalyState;
+} | {
+    kind: 'key.quotaWarning';
+    at: number;
+    keyId: string;
+    scope: WebhookQuotaScope;
+    limitUsd: number;
+    spentUsd: number;
+} | {
+    kind: 'key.quotaExceeded';
+    at: number;
+    keyId: string;
+    scope: WebhookQuotaScope;
+    limitUsd: number;
+    spentUsd: number;
+} | {
+    kind: 'server.error';
+    at: number;
+    message: string;
+} | {
+    kind: 'test';
+    at: number;
+};
+/** The event discriminator — the value a destination `events` filter matches. */
+type WebhookEventKind = WebhookEvent['kind'];
+/** All event kinds (SSOT for validation + the admin UI's filter checklist). */
+declare const WEBHOOK_EVENT_KINDS: readonly WebhookEventKind[];
+/** The v1 destination types (dingtalk/slack/… are additive later). */
+type WebhookDestinationType = 'custom' | 'feishu';
+/** All destination types (SSOT for validation + the admin UI's type select). */
+declare const WEBHOOK_DESTINATION_TYPES: readonly WebhookDestinationType[];
+/**
+ * One webhook destination (design D5). `secret` is the OPTIONAL HMAC signing key
+ * (a SECRET — encrypted at rest, masked in views, never in a payload/log). An
+ * absent/empty `events` filter matches ALL event kinds.
+ */
+interface WebhookDestination {
+    /** Stable id (the admin CRUD key + the test-button target). */
+    id: string;
+    /** The formatter/signing scheme to use. */
+    type: WebhookDestinationType;
+    /** The POST target URL. */
+    url: string;
+    /** OPTIONAL HMAC signing key (SECRET; may be an `enc:`/`$ENV` envelope at rest). */
+    secret?: string;
+    /** OPTIONAL event-kind filter; absent/empty ⇒ receive ALL kinds. */
+    events?: WebhookEventKind[];
+    /** Whether this destination receives events. */
+    enabled: boolean;
+}
+/**
+ * The `webhook` config segment (design D5). Absent/`enabled:false` ⇒ inert (no
+ * dispatcher wiring, emit is a no-op — byte-identical zero regression).
+ */
+interface WebhookConfig {
+    /** Master switch; false/absent ⇒ webhooks are inert. */
+    enabled: boolean;
+    /** Configured destinations (each independently enable-able + filterable). */
+    destinations: WebhookDestination[];
+}
+/**
+ * Secret-free projection of a destination for admin GET views: the signing
+ * `secret` is replaced by a `hasSecret` presence flag — the plaintext never
+ * leaves the daemon.
+ */
+interface SanitizedWebhookDestination {
+    id: string;
+    type: WebhookDestinationType;
+    url: string;
+    /** Whether a signing secret is configured (the value itself never leaves). */
+    hasSecret: boolean;
+    events?: WebhookEventKind[];
+    enabled: boolean;
+}
+/** Secret-free projection of the whole webhook segment (admin GET view). */
+interface SanitizedWebhookConfig {
+    enabled: boolean;
+    destinations: SanitizedWebhookDestination[];
+}
+
+export { type SanitizedWebhookConfig, type SanitizedWebhookDestination, WEBHOOK_DESTINATION_TYPES, WEBHOOK_EVENT_KINDS, type WebhookAnomalyState, type WebhookConfig, type WebhookDestination, type WebhookDestinationType, type WebhookEvent, type WebhookEventKind, type WebhookQuotaScope };

package/dist/webhook-types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Webhook notification contracts (webhook-notifications, design D1).
+ *
+ * Two small, dependency-light shapes shared across the `@omnicross/*` packages:
+ *  - `WebhookEvent` — the FROZEN discriminated union of operational signals a
+ *    relay can deliver out-of-band (account recovery/anomaly, key quota
+ *    warning/exceeded, server error, and a config-UI `test`). Every payload is
+ *    SECRET-FREE BY CONSTRUCTION: it carries only opaque provider/account ids, a
+ *    key id (NEVER key material or a hash), a coarse state, limit/spend numbers,
+ *    and a sanitized message. Nothing here can hold a token, secret, or hash.
+ *  - `WebhookDestination` / `WebhookConfig` — the destination config schema. A
+ *    destination's `secret` (its HMAC signing key) is the ONLY secret; it is
+ *    encrypted at rest, masked in admin views, and used ONLY to sign an outgoing
+ *    request — it is NEVER placed in a payload or a log line.
+ *
+ * The union is FROZEN: the emit port (core), the dispatcher (daemon), and the
+ * sources (#2 health / #4 quota / server-error) all agree on this one shape.
+ * Adding a destination `type` is additive behind the dispatcher's formatter.
+ *
+ * @module webhook-types
+ */
+/** The coarse anomaly state an account transitioned into (secret-free). */
+type WebhookAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded';
+/** The cost-limit scope a key quota event refers to. */
+type WebhookQuotaScope = 'daily' | 'weekly' | 'total';
+/**
+ * The FROZEN webhook event union (design D1). EVERY field is non-secret:
+ * opaque provider/account ids, a key id (NOT key material/hash), a coarse state,
+ * numbers, and a sanitized message. A test asserts no token/secret/hash string
+ * can appear in any serialized payload.
+ */
+type WebhookEvent = {
+    kind: 'account.recovery';
+    at: number;
+    providerId: string;
+    accountId: string;
+} | {
+    kind: 'account.anomaly';
+    at: number;
+    providerId: string;
+    accountId: string;
+    state: WebhookAnomalyState;
+} | {
+    kind: 'key.quotaWarning';
+    at: number;
+    keyId: string;
+    scope: WebhookQuotaScope;
+    limitUsd: number;
+    spentUsd: number;
+} | {
+    kind: 'key.quotaExceeded';
+    at: number;
+    keyId: string;
+    scope: WebhookQuotaScope;
+    limitUsd: number;
+    spentUsd: number;
+} | {
+    kind: 'server.error';
+    at: number;
+    message: string;
+} | {
+    kind: 'test';
+    at: number;
+};
+/** The event discriminator — the value a destination `events` filter matches. */
+type WebhookEventKind = WebhookEvent['kind'];
+/** All event kinds (SSOT for validation + the admin UI's filter checklist). */
+declare const WEBHOOK_EVENT_KINDS: readonly WebhookEventKind[];
+/** The v1 destination types (dingtalk/slack/… are additive later). */
+type WebhookDestinationType = 'custom' | 'feishu';
+/** All destination types (SSOT for validation + the admin UI's type select). */
+declare const WEBHOOK_DESTINATION_TYPES: readonly WebhookDestinationType[];
+/**
+ * One webhook destination (design D5). `secret` is the OPTIONAL HMAC signing key
+ * (a SECRET — encrypted at rest, masked in views, never in a payload/log). An
+ * absent/empty `events` filter matches ALL event kinds.
+ */
+interface WebhookDestination {
+    /** Stable id (the admin CRUD key + the test-button target). */
+    id: string;
+    /** The formatter/signing scheme to use. */
+    type: WebhookDestinationType;
+    /** The POST target URL. */
+    url: string;
+    /** OPTIONAL HMAC signing key (SECRET; may be an `enc:`/`$ENV` envelope at rest). */
+    secret?: string;
+    /** OPTIONAL event-kind filter; absent/empty ⇒ receive ALL kinds. */
+    events?: WebhookEventKind[];
+    /** Whether this destination receives events. */
+    enabled: boolean;
+}
+/**
+ * The `webhook` config segment (design D5). Absent/`enabled:false` ⇒ inert (no
+ * dispatcher wiring, emit is a no-op — byte-identical zero regression).
+ */
+interface WebhookConfig {
+    /** Master switch; false/absent ⇒ webhooks are inert. */
+    enabled: boolean;
+    /** Configured destinations (each independently enable-able + filterable). */
+    destinations: WebhookDestination[];
+}
+/**
+ * Secret-free projection of a destination for admin GET views: the signing
+ * `secret` is replaced by a `hasSecret` presence flag — the plaintext never
+ * leaves the daemon.
+ */
+interface SanitizedWebhookDestination {
+    id: string;
+    type: WebhookDestinationType;
+    url: string;
+    /** Whether a signing secret is configured (the value itself never leaves). */
+    hasSecret: boolean;
+    events?: WebhookEventKind[];
+    enabled: boolean;
+}
+/** Secret-free projection of the whole webhook segment (admin GET view). */
+interface SanitizedWebhookConfig {
+    enabled: boolean;
+    destinations: SanitizedWebhookDestination[];
+}
+
+export { type SanitizedWebhookConfig, type SanitizedWebhookDestination, WEBHOOK_DESTINATION_TYPES, WEBHOOK_EVENT_KINDS, type WebhookAnomalyState, type WebhookConfig, type WebhookDestination, type WebhookDestinationType, type WebhookEvent, type WebhookEventKind, type WebhookQuotaScope };

package/dist/webhook-types.js

@@ -0,0 +1,14 @@
+// src/webhook-types.ts
+var WEBHOOK_EVENT_KINDS = [
+  "account.recovery",
+  "account.anomaly",
+  "key.quotaWarning",
+  "key.quotaExceeded",
+  "server.error",
+  "test"
+];
+var WEBHOOK_DESTINATION_TYPES = ["custom", "feishu"];
+export {
+  WEBHOOK_DESTINATION_TYPES,
+  WEBHOOK_EVENT_KINDS
+};