@omnicross/contracts 0.1.2 → 0.1.3

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnicross/contracts",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Dependency-light, host-agnostic contract types + runtime-value helpers shared by the @omnicross/* packages.",
   "license": "MIT",
   "author": "Sayo (https://github.com/Dumoedss)",
@@ -40,6 +40,16 @@
       "import": "./dist/account-tokens-types.js",
       "require": "./dist/account-tokens-types.cjs"
     },
+    "./audit-types": {
+      "types": "./dist/audit-types.d.ts",
+      "import": "./dist/audit-types.js",
+      "require": "./dist/audit-types.cjs"
+    },
+    "./billing-types": {
+      "types": "./dist/billing-types.d.ts",
+      "import": "./dist/billing-types.js",
+      "require": "./dist/billing-types.cjs"
+    },
     "./canonical-models": {
       "types": "./dist/canonical-models.d.ts",
       "import": "./dist/canonical-models.js",
@@ -60,6 +70,11 @@
       "import": "./dist/extended-context.js",
       "require": "./dist/extended-context.cjs"
     },
+    "./health-logging-types": {
+      "types": "./dist/health-logging-types.d.ts",
+      "import": "./dist/health-logging-types.js",
+      "require": "./dist/health-logging-types.cjs"
+    },
     "./llm-config": {
       "types": "./dist/llm-config.d.ts",
       "import": "./dist/llm-config.js",
@@ -105,6 +120,16 @@
       "import": "./dist/usage-types.js",
       "require": "./dist/usage-types.cjs"
     },
+    "./voucher-types": {
+      "types": "./dist/voucher-types.d.ts",
+      "import": "./dist/voucher-types.js",
+      "require": "./dist/voucher-types.cjs"
+    },
+    "./webhook-types": {
+      "types": "./dist/webhook-types.d.ts",
+      "import": "./dist/webhook-types.js",
+      "require": "./dist/webhook-types.cjs"
+    },
     "./websearch-types": {
       "types": "./dist/websearch-types.d.ts",
       "import": "./dist/websearch-types.js",