@omnicross/contracts 0.1.2 → 0.1.3

package/dist/index.js

@@ -1,3 +1,18 @@
+// src/audit-types.ts
+var DEFAULT_AUDIT_CONFIG = {
+  enabled: false,
+  captureBodies: false,
+  maxBodyBytes: 8192,
+  retentionDays: 7,
+  trustForwardedFor: false
+};
+
+// src/billing-types.ts
+var DEFAULT_BILLING_CONFIG = {
+  enabled: false,
+  maxRetryAgeMs: 24 * 60 * 6e4
+};
+
 // src/canonical-models.ts
 var OPENAI_MODELS = {
   "gpt-5.5": { category: "reasoning", contextLength: 105e4, maxTokens: 128e3, reasoning: true, vision: true, functionCall: true, thinkingLevels: ["none", "low", "medium", "high", "xhigh"], thinkingTokenLimit: { min: 0, max: 128e3 } },
@@ -260,6 +275,11 @@ function isExtendedContextCapable(model) {
   return EXTENDED_CONTEXT_CAPABLE_MODELS.has(model);
 }
 
+// src/health-logging-types.ts
+function healthHttpStatus(status) {
+  return status === "ok" ? 200 : 503;
+}
+
 // src/mcp-types.ts
 var DEFAULT_MCP_SESSION_CONFIG = {
   mode: "auto",
@@ -2606,6 +2626,22 @@ function buildQwenThinkingConfig(level, userMaxTokens) {
   };
 }
 
+// src/voucher-types.ts
+var DEFAULT_VOUCHER_CONFIG = {
+  enabled: false
+};
+
+// 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"];
+
 // src/websearch-types.ts
 function isApiProvider(id) {
   return !id.startsWith("local-");
@@ -2618,10 +2654,13 @@ export {
   CANNOT_DISABLE_THINKING_PATTERNS,
   CATALOG_VERSION,
   CODING_PLAN_URL_PRESETS,
+  DEFAULT_AUDIT_CONFIG,
+  DEFAULT_BILLING_CONFIG,
   DEFAULT_LITELLM_PRICING_URL,
   DEFAULT_MAX_TOKENS,
   DEFAULT_MCP_SESSION_CONFIG,
   DEFAULT_SEED_PRESET_IDS,
+  DEFAULT_VOUCHER_CONFIG,
   EFFORT_RATIO,
   EXTENDED_CONTEXT_CAPABLE_MODELS,
   KNOWN_MODELS,
@@ -2632,6 +2671,8 @@ export {
   PROVIDER_SEARCH_CONFIGS,
   REASONING_MODEL_PATTERNS,
   THINKING_TOKEN_MAP,
+  WEBHOOK_DESTINATION_TYPES,
+  WEBHOOK_EVENT_KINDS,
   applyAlias,
   buildAnthropicThinking,
   buildGeminiThinkingConfig,
@@ -2646,6 +2687,7 @@ export {
   getPresetById,
   getPresetRevision,
   getProviderSearchConfig,
+  healthHttpStatus,
   isApiProvider,
   isExtendedContextCapable,
   isLocalProvider,

package/dist/{llm-config-D1jKQLVp.d.ts → llm-config-CKOaFFdy.d.ts}

@@ -286,6 +286,14 @@ interface LLMProvider {
     modelGroups?: ModelGroup[];
     modelsEndpoint?: string;
     enabled: boolean;
+    /**
+     * For `apiFormat: 'anthropic'` providers, authenticate with
+     * `Authorization: Bearer <apiKey>` instead of the default `x-api-key` header.
+     * Set this for third-party Anthropic-Messages relays that gate on a Bearer
+     * token (the native/base header path; the transformer path uses the
+     * `UseBearer` transformer option independently).
+     */
+    useBearer?: boolean;
     transformer?: TransformerConfig;
     rerouterEnabled?: boolean;
     icon?: string;
@@ -294,7 +302,6 @@ interface LLMProvider {
     defaultSettings?: CompletionSettings;
     isSystem?: boolean;
     isOfficial?: boolean;
-    rateLimit?: number;
     maxConcurrency?: number;
     notes?: string;
     apiVersion?: string;

package/dist/{llm-config-CQjOimv2.d.cts → llm-config-DeWNx1ig.d.cts}

@@ -286,6 +286,14 @@ interface LLMProvider {
     modelGroups?: ModelGroup[];
     modelsEndpoint?: string;
     enabled: boolean;
+    /**
+     * For `apiFormat: 'anthropic'` providers, authenticate with
+     * `Authorization: Bearer <apiKey>` instead of the default `x-api-key` header.
+     * Set this for third-party Anthropic-Messages relays that gate on a Bearer
+     * token (the native/base header path; the transformer path uses the
+     * `UseBearer` transformer option independently).
+     */
+    useBearer?: boolean;
     transformer?: TransformerConfig;
     rerouterEnabled?: boolean;
     icon?: string;
@@ -294,7 +302,6 @@ interface LLMProvider {
     defaultSettings?: CompletionSettings;
     isSystem?: boolean;
     isOfficial?: boolean;
-    rateLimit?: number;
     maxConcurrency?: number;
     notes?: string;
     apiVersion?: string;

package/dist/llm-config.d.cts

@@ -1,2 +1,2 @@
 import './thinking-CBWSLel8.cjs';
-export { a as AgentDefaultModels, b as ApiFormat, c as ApiKeyEntry, C as ChatApiFormat, g as CompletionSettings, G as GlobalModelParameters, L as LLMProvider, M as ModelConfig, h as ModelGroup, i as ModelParameter, j as ModelRef, O as OpenRouterDataCollection, k as OpenRouterMaxPrice, l as OpenRouterProviderRouting, m as OpenRouterProviderSort, n as OpenRouterQuantization, o as ProviderApiType, r as ProviderTemplate, T as TransformerConfig, s as TransformerEntry } from './llm-config-CQjOimv2.cjs';
+export { a as AgentDefaultModels, b as ApiFormat, c as ApiKeyEntry, C as ChatApiFormat, g as CompletionSettings, G as GlobalModelParameters, L as LLMProvider, M as ModelConfig, h as ModelGroup, i as ModelParameter, j as ModelRef, O as OpenRouterDataCollection, k as OpenRouterMaxPrice, l as OpenRouterProviderRouting, m as OpenRouterProviderSort, n as OpenRouterQuantization, o as ProviderApiType, r as ProviderTemplate, T as TransformerConfig, s as TransformerEntry } from './llm-config-DeWNx1ig.cjs';

package/dist/llm-config.d.ts

@@ -1,2 +1,2 @@
 import './thinking-CBWSLel8.js';
-export { a as AgentDefaultModels, b as ApiFormat, c as ApiKeyEntry, C as ChatApiFormat, g as CompletionSettings, G as GlobalModelParameters, L as LLMProvider, M as ModelConfig, h as ModelGroup, i as ModelParameter, j as ModelRef, O as OpenRouterDataCollection, k as OpenRouterMaxPrice, l as OpenRouterProviderRouting, m as OpenRouterProviderSort, n as OpenRouterQuantization, o as ProviderApiType, r as ProviderTemplate, T as TransformerConfig, s as TransformerEntry } from './llm-config-D1jKQLVp.js';
+export { a as AgentDefaultModels, b as ApiFormat, c as ApiKeyEntry, C as ChatApiFormat, g as CompletionSettings, G as GlobalModelParameters, L as LLMProvider, M as ModelConfig, h as ModelGroup, i as ModelParameter, j as ModelRef, O as OpenRouterDataCollection, k as OpenRouterMaxPrice, l as OpenRouterProviderRouting, m as OpenRouterProviderSort, n as OpenRouterQuantization, o as ProviderApiType, r as ProviderTemplate, T as TransformerConfig, s as TransformerEntry } from './llm-config-CKOaFFdy.js';

package/dist/provider-presets/index.d.cts

@@ -1,5 +1,5 @@
-import { p as ProviderModelMapping, q as ProviderSearchConfig, P as PresetProviderTemplate } from '../llm-config-CQjOimv2.cjs';
-export { A as API_MODE_IDS, d as ApiMode, e as ApiModeId, f as CodingPlanConfig, S as SearchCapability } from '../llm-config-CQjOimv2.cjs';
+import { p as ProviderModelMapping, q as ProviderSearchConfig, P as PresetProviderTemplate } from '../llm-config-DeWNx1ig.cjs';
+export { A as API_MODE_IDS, d as ApiMode, e as ApiModeId, f as CodingPlanConfig, S as SearchCapability } from '../llm-config-DeWNx1ig.cjs';
 import '../thinking-CBWSLel8.cjs';
 
 /**

package/dist/provider-presets/index.d.ts

@@ -1,5 +1,5 @@
-import { p as ProviderModelMapping, q as ProviderSearchConfig, P as PresetProviderTemplate } from '../llm-config-D1jKQLVp.js';
-export { A as API_MODE_IDS, d as ApiMode, e as ApiModeId, f as CodingPlanConfig, S as SearchCapability } from '../llm-config-D1jKQLVp.js';
+import { p as ProviderModelMapping, q as ProviderSearchConfig, P as PresetProviderTemplate } from '../llm-config-CKOaFFdy.js';
+export { A as API_MODE_IDS, d as ApiMode, e as ApiModeId, f as CodingPlanConfig, S as SearchCapability } from '../llm-config-CKOaFFdy.js';
 import '../thinking-CBWSLel8.js';
 
 /**

package/dist/thinking-config.d.cts

@@ -1,5 +1,5 @@
 import { T as ThinkLevel } from './thinking-CBWSLel8.cjs';
-import { M as ModelConfig } from './llm-config-CQjOimv2.cjs';
+import { M as ModelConfig } from './llm-config-DeWNx1ig.cjs';
 
 /**
  * thinking-config — dependency-light thinking-budget / reasoning-effort helpers.

package/dist/thinking-config.d.ts

@@ -1,5 +1,5 @@
 import { T as ThinkLevel } from './thinking-CBWSLel8.js';
-import { M as ModelConfig } from './llm-config-D1jKQLVp.js';
+import { M as ModelConfig } from './llm-config-CKOaFFdy.js';
 
 /**
  * thinking-config — dependency-light thinking-budget / reasoning-effort helpers.

package/dist/usage-stats-types.d.cts

@@ -70,6 +70,27 @@ interface UsageTotals {
     /** Number of events contributing to these totals. */
     eventCount: number;
 }
+/** Granularity for a usage time-series query. `week` is NOT a bucket — a "week" view is a `day` bucket over a 7-day range. */
+type UsageTimeBucket = 'hour' | 'day' | 'month';
+/**
+ * One bucket of a usage time-series (trend chart). Buckets are query-time
+ * aggregations over the daemon's LOCAL-time boundaries and every bucket in the
+ * requested range is present (empty buckets are zero-filled), ascending by
+ * `bucketStartTs`.
+ */
+interface UsageTimeSeriesBucket {
+    /** Unix-millis of the LOCAL-time bucket boundary (hour start / local midnight / local 1st-of-month). */
+    bucketStartTs: number;
+    /** Frozen locale-agnostic label from LOCAL parts: hour `MM-DD HH:00`, day `YYYY-MM-DD`, month `YYYY-MM`. */
+    label: string;
+    /** Event count in the bucket (0 for a zero-filled bucket). */
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+}
 /** One row of the per-model breakdown. */
 interface ModelUsageRow {
     providerId: string;
@@ -140,4 +161,4 @@ interface MessageUsageRow {
     costSavedByCacheUsd: number;
 }
 
-export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTotals };
+export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals };

package/dist/usage-stats-types.d.ts

@@ -70,6 +70,27 @@ interface UsageTotals {
     /** Number of events contributing to these totals. */
     eventCount: number;
 }
+/** Granularity for a usage time-series query. `week` is NOT a bucket — a "week" view is a `day` bucket over a 7-day range. */
+type UsageTimeBucket = 'hour' | 'day' | 'month';
+/**
+ * One bucket of a usage time-series (trend chart). Buckets are query-time
+ * aggregations over the daemon's LOCAL-time boundaries and every bucket in the
+ * requested range is present (empty buckets are zero-filled), ascending by
+ * `bucketStartTs`.
+ */
+interface UsageTimeSeriesBucket {
+    /** Unix-millis of the LOCAL-time bucket boundary (hour start / local midnight / local 1st-of-month). */
+    bucketStartTs: number;
+    /** Frozen locale-agnostic label from LOCAL parts: hour `MM-DD HH:00`, day `YYYY-MM-DD`, month `YYYY-MM`. */
+    label: string;
+    /** Event count in the bucket (0 for a zero-filled bucket). */
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+}
 /** One row of the per-model breakdown. */
 interface ModelUsageRow {
     providerId: string;
@@ -140,4 +161,4 @@ interface MessageUsageRow {
     costSavedByCacheUsd: number;
 }
 
-export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTotals };
+export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals };

package/dist/voucher-types.cjs

@@ -0,0 +1,32 @@
+"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/voucher-types.ts
+var voucher_types_exports = {};
+__export(voucher_types_exports, {
+  DEFAULT_VOUCHER_CONFIG: () => DEFAULT_VOUCHER_CONFIG
+});
+module.exports = __toCommonJS(voucher_types_exports);
+var DEFAULT_VOUCHER_CONFIG = {
+  enabled: false
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_VOUCHER_CONFIG
+});

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
+});