@kirimdev/sdk 2.0.1 → 3.0.0

package/README.md

@@ -17,24 +17,58 @@ import { Kirim } from '@kirimdev/sdk'
 
 const kirim = new Kirim({ apiKey: process.env.KIRIM_API_KEY! })
 
+// Scope to a WhatsApp phone number (Meta `business_phone_number_id`).
+// Look it up via `kirim.accounts.list()` if you don't have it handy.
+const phone = kirim.phoneNumbers('106540352242922')
+
 // Send a message
-const msg = await kirim.messages.send({
+const msg = await phone.messages.send({
   to: '628123456789',
   type: 'text',
   text: { body: 'Halo dari SDK!' },
 })
 
 // Paginate
-for await (const m of kirim.messages.list({ limit: 50 })) {
+for await (const m of phone.messages.list({ limit: 50 })) {
   console.log(m.id, m.status)
 }
+```
 
-// Webhook verification
-import { verifyWebhookSignature } from '@kirimdev/sdk/webhooks'
+## Webhook verification
 
-const ok = verifyWebhookSignature(rawBody, req.headers['x-kirim-signature'], secret)
+`verifyWebhookSignature` parses the `X-Kirim-Signature` header (Stripe-style
+`t=<unix>,v1=<hex>` format), checks the timestamp against a tolerance window,
+verifies the HMAC-SHA256 against one or more active secrets (supports rotation),
+and returns the parsed JSON body. It **throws** on every failure mode — never
+returns `false`. Uses Web Crypto so it runs unchanged on Node 18+, Bun, Deno,
+and edge runtimes.
+
+```ts
+import { verifyWebhookSignature, InvalidSignatureError } from '@kirimdev/sdk/webhooks'
+
+export async function POST(req: Request) {
+  const rawBody = await req.text()
+  try {
+    const event = await verifyWebhookSignature({
+      rawBody,
+      signatureHeader: req.headers.get('x-kirim-signature'),
+      secrets: [process.env.KIRIM_WEBHOOK_SECRET!],
+    })
+    // event is KirimWebhookEvent — narrow on event.type or event.object
+    return new Response('ok')
+  } catch (err) {
+    if (err instanceof InvalidSignatureError) return new Response('bad sig', { status: 401 })
+    throw err
+  }
+}
 ```
 
+Errors thrown (all extend `KirimWebhookError`):
+
+- `InvalidSignatureError` — header missing/malformed, or no `v1=` matched any provided secret
+- `SignatureExpiredError` — `|now - t|` exceeds `toleranceSeconds` (default 300s)
+- `MalformedPayloadError` — signature matched but body is not valid JSON
+
 ## Features
 
 - Full coverage of the Kirim `/v1` API (~35 endpoints)

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /**
- * Error class hierarchy for `@kirimdev/sdk`.
+ * HTTP error class hierarchy for `@kirimdev/sdk`.
  *
  * Every HTTP error from the Kirim API is mapped to a subclass of
  * `KirimError`. Network/timeout failures throw `ConnectionError`. The
@@ -8,6 +8,17 @@
  * specific stable identifier.
  *
  * Source of truth for codes: `apps/api/src/lib/api-error.ts` (ERROR_CATALOG).
+ *
+ * NOTE: Webhook signature verification errors live in a SEPARATE hierarchy
+ * rooted at `KirimWebhookError` (see `@kirimdev/sdk/webhooks`). They do
+ * not extend `KirimError` because they carry no HTTP shape — no
+ * `requestId`, `status`, or `type`. Consumers wanting to catch both must
+ * catch each base class separately, or use a union check:
+ *
+ *   catch (e) {
+ *     if (e instanceof KirimError) {...}
+ *     else if (e instanceof KirimWebhookError) {...}
+ *   }
  */
 export type KirimErrorType = 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'not_found' | 'conflict' | 'rate_limit_error' | 'api_error' | 'connection_error';
 export interface KirimErrorPayload {

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,cAAc,GACtB,uBAAuB,GACvB,sBAAsB,GACtB,kBAAkB,GAClB,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,WAAW,GACX,kBAAkB,CAAA;AAEtB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,6CAA6C;IAC7C,GAAG,CAAC,EAAE,OAAO,CAAA;CACd;AAED,4DAA4D;AAC5D,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;gBAET,OAAO,EAAE,iBAAiB;CAUvC;AAED,qBAAa,mBAAoB,SAAQ,UAAU;gBACrC,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,mBAAoB,SAAQ,UAAU;gBACrC,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,eAAgB,SAAQ,UAAU;gBACjC,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,cAAe,SAAQ,UAAU;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;gBACtB,OAAO,EAAE,iBAAiB,GAAG;QAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAKvE;AAED,qBAAa,cAAe,SAAQ,UAAU;gBAChC,OAAO,EAAE,iBAAiB;CAIvC;AAED,6DAA6D;AAC7D,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;gBACX,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAW5C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,UAAU,CAiCZ"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,cAAc,GACtB,uBAAuB,GACvB,sBAAsB,GACtB,kBAAkB,GAClB,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,WAAW,GACX,kBAAkB,CAAA;AAEtB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,6CAA6C;IAC7C,GAAG,CAAC,EAAE,OAAO,CAAA;CACd;AAED,4DAA4D;AAC5D,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;gBAET,OAAO,EAAE,iBAAiB;CAUvC;AAED,qBAAa,mBAAoB,SAAQ,UAAU;gBACrC,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,mBAAoB,SAAQ,UAAU;gBACrC,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,eAAgB,SAAQ,UAAU;gBACjC,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,cAAe,SAAQ,UAAU;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;gBACtB,OAAO,EAAE,iBAAiB,GAAG;QAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAKvE;AAED,qBAAa,cAAe,SAAQ,UAAU;gBAChC,OAAO,EAAE,iBAAiB;CAIvC;AAED,6DAA6D;AAC7D,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;gBACX,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAW5C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,UAAU,CAiCZ"}

package/dist/errors.js

@@ -1,5 +1,5 @@
 /**
- * Error class hierarchy for `@kirimdev/sdk`.
+ * HTTP error class hierarchy for `@kirimdev/sdk`.
  *
  * Every HTTP error from the Kirim API is mapped to a subclass of
  * `KirimError`. Network/timeout failures throw `ConnectionError`. The
@@ -8,6 +8,17 @@
  * specific stable identifier.
  *
  * Source of truth for codes: `apps/api/src/lib/api-error.ts` (ERROR_CATALOG).
+ *
+ * NOTE: Webhook signature verification errors live in a SEPARATE hierarchy
+ * rooted at `KirimWebhookError` (see `@kirimdev/sdk/webhooks`). They do
+ * not extend `KirimError` because they carry no HTTP shape — no
+ * `requestId`, `status`, or `type`. Consumers wanting to catch both must
+ * catch each base class separately, or use a union check:
+ *
+ *   catch (e) {
+ *     if (e instanceof KirimError) {...}
+ *     else if (e instanceof KirimWebhookError) {...}
+ *   }
  */
 /** Base class. All errors thrown by the SDK extend this. */
 export class KirimError extends Error {

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/webhooks.d.ts

@@ -1,100 +1,101 @@
 /**
  * Webhook HMAC verification + typed event payloads.
  *
- * The Kirim API signs outbound webhook deliveries with HMAC-SHA256 over the
- * raw request body, encoded as `sha256=<hex>` in the `X-Kirim-Signature`
- * header. This module exposes a constant-time verifier using Web Crypto
- * (`crypto.subtle`) so it runs on Node 18+, Bun, Deno, and edge runtimes.
+ * Kirim signs outbound webhook deliveries using a Stripe-style header
+ * format mirroring `apps/worker/src/jobs/webhook-delivery/sign.ts`:
  *
- * The signing scheme mirrors `apps/api/src/lib/webhook-security.ts`.
+ *   X-Kirim-Signature: t=<unix_seconds>,v1=<hex>[,v1=<hex>...]
  *
- * Usage:
- *   import { verifyWebhookSignature } from '@kirimdev/sdk/webhooks'
+ * - `t` is the time the signature was computed; callers reject when
+ *   |now - t| exceeds `toleranceSeconds` (default 5 minutes).
+ * - Each `v1=` is HMAC-SHA256 of `${t}.${rawBody}` under one ACTIVE
+ *   signing secret. During rotation a subscription may have multiple
+ *   active secrets and the header carries one `v1=` per secret —
+ *   verification passes if ANY caller-supplied secret matches ANY
+ *   `v1=` value.
  *
- *   const ok = await verifyWebhookSignature(
- *     await req.text(),
- *     req.headers.get('x-kirim-signature') ?? '',
- *     process.env.KIRIM_WEBHOOK_SECRET!,
- *   )
- *   if (!ok) return new Response('bad signature', { status: 401 })
- */
-/**
- * Verify a Kirim webhook signature.
- *
- * MUST be called with the raw request body (the same bytes Kirim signed —
- * re-serializing JSON will break the signature). Returns `false` (never
- * throws) when the header is absent / malformed / mismatched. The caller
- * MUST reject the request when this returns `false` (fail-closed).
- */
-export declare function verifyWebhookSignature(body: string, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
-/**
- * Discriminated union of all event types Kirim can deliver to a webhook
- * subscription. The `type` literal is the discriminator.
+ * Uses Web Crypto (`crypto.subtle`) so this module runs unchanged on
+ * Node 18+, Bun, Deno, and edge runtimes.
  *
- * The list of events here MUST stay in sync with what the API actually
- * emits (see the worker's webhook dispatch + `apps/api` event constants).
- * Treat unknown event types as forward-compatible: callers should keep a
- * `default` branch and ignore unknown payloads rather than throwing.
+ * The error classes in this module (`KirimWebhookError`,
+ * `InvalidSignatureError`, `SignatureExpiredError`,
+ * `MalformedPayloadError`) form a SEPARATE hierarchy from the HTTP
+ * `KirimError` tree in `@kirimdev/sdk` — webhook errors carry no
+ * `requestId` / `status` / `code` because they fire before any HTTP
+ * round-trip. Consumers wanting a single catch surface should branch
+ * on `instanceof KirimWebhookError` separately from `instanceof
+ * KirimError`.
  */
-export type KirimWebhookEvent = MessageCreatedEvent | MessageStatusUpdatedEvent | ConversationCreatedEvent | ConversationUpdatedEvent | ContactCreatedEvent | ContactUpdatedEvent;
-interface BaseEvent {
-    id: string;
-    created_at: string;
-    /** Subscription id that triggered the delivery. */
-    subscription_id: string;
+export declare class KirimWebhookError extends Error {
+    constructor(message: string);
 }
-export interface MessageCreatedEvent extends BaseEvent {
-    type: 'message.created';
-    data: {
-        id: string;
-        object: 'message';
-        conversation_id?: string;
-        to: string;
-        type: string;
-        status: string;
-        created_at: string;
-    };
+export declare class InvalidSignatureError extends KirimWebhookError {
+    constructor(message?: string);
 }
-export interface MessageStatusUpdatedEvent extends BaseEvent {
-    type: 'message.status_updated';
-    data: {
-        id: string;
-        object: 'message';
-        status: 'sent' | 'delivered' | 'read' | 'failed' | 'queued' | 'pending';
-        error?: {
-            code: string;
-            message: string;
-            provider_code: number | null;
-        };
-    };
+export declare class SignatureExpiredError extends KirimWebhookError {
+    constructor(message?: string);
 }
-export interface ConversationCreatedEvent extends BaseEvent {
-    type: 'conversation.created';
-    data: {
-        id: string;
-        object: 'conversation';
-    };
+export declare class MalformedPayloadError extends KirimWebhookError {
+    constructor(message?: string);
 }
-export interface ConversationUpdatedEvent extends BaseEvent {
-    type: 'conversation.updated';
-    data: {
-        id: string;
-        object: 'conversation';
-    };
+export interface VerifyOptions {
+    rawBody: string;
+    signatureHeader: string | null | undefined;
+    secrets: string[];
+    /** Default 300 seconds (5 minutes). */
+    toleranceSeconds?: number;
+    /** Override the wall clock — primarily for tests. */
+    nowSeconds?: () => number;
 }
-export interface ContactCreatedEvent extends BaseEvent {
-    type: 'contact.created';
-    data: {
-        id: string;
-        object: 'contact';
-    };
+export declare function verifyWebhookSignature(opts: VerifyOptions): Promise<unknown>;
+/**
+ * Native Kirim event envelope (server emits `conversation.*` and
+ * `contact.*` in this shape). The `message.received` and `message.status`
+ * events are forwarded VERBATIM from Meta's webhook body and do NOT use
+ * this envelope — see `MetaPassthroughBody` below.
+ */
+export interface KirimEventEnvelope<TType extends string, TData> {
+    id: string;
+    type: TType;
+    created_at: string;
+    data: TData;
 }
-export interface ContactUpdatedEvent extends BaseEvent {
-    type: 'contact.updated';
-    data: {
+export type ConversationAssignedEvent = KirimEventEnvelope<'conversation.assigned', {
+    id: string;
+    object: 'conversation';
+    [k: string]: unknown;
+}>;
+export type ConversationClosedEvent = KirimEventEnvelope<'conversation.closed', {
+    id: string;
+    object: 'conversation';
+    [k: string]: unknown;
+}>;
+export type ContactCreatedEvent = KirimEventEnvelope<'contact.created', {
+    id: string;
+    object: 'contact';
+    [k: string]: unknown;
+}>;
+export type ContactUpdatedEvent = KirimEventEnvelope<'contact.updated', {
+    id: string;
+    object: 'contact';
+    [k: string]: unknown;
+}>;
+export type KirimNativeWebhookEvent = ConversationAssignedEvent | ConversationClosedEvent | ContactCreatedEvent | ContactUpdatedEvent;
+/**
+ * Meta passthrough body — `message.received` and `message.status`
+ * deliveries forward Meta's WhatsApp Cloud webhook payload unchanged.
+ * Callers should branch on `X-Kirim-Event` to decide whether to parse
+ * the body as `KirimNativeWebhookEvent` or `MetaPassthroughBody`.
+ */
+export interface MetaPassthroughBody {
+    object: 'whatsapp_business_account';
+    entry: Array<{
         id: string;
-        object: 'contact';
-    };
+        changes: Array<{
+            value: unknown;
+            field: 'messages' | string;
+        }>;
+    }>;
 }
-export {};
+export type KirimWebhookEvent = KirimNativeWebhookEvent | MetaPassthroughBody;
 //# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC1C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAYlB;AAqCD;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,yBAAyB,GACzB,wBAAwB,GACxB,wBAAwB,GACxB,mBAAmB,GACnB,mBAAmB,CAAA;AAEvB,UAAU,SAAS;IACjB,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,mBAAoB,SAAQ,SAAS;IACpD,IAAI,EAAE,iBAAiB,CAAA;IACvB,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAA;QACV,MAAM,EAAE,SAAS,CAAA;QACjB,eAAe,CAAC,EAAE,MAAM,CAAA;QACxB,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;KACnB,CAAA;CACF;AAED,MAAM,WAAW,yBAA0B,SAAQ,SAAS;IAC1D,IAAI,EAAE,wBAAwB,CAAA;IAC9B,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAA;QACV,MAAM,EAAE,SAAS,CAAA;QACjB,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;QACvE,KAAK,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,CAAA;KACxE,CAAA;CACF;AAED,MAAM,WAAW,wBAAyB,SAAQ,SAAS;IACzD,IAAI,EAAE,sBAAsB,CAAA;IAC5B,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,cAAc,CAAA;KAAE,CAAA;CAC7C;AAED,MAAM,WAAW,wBAAyB,SAAQ,SAAS;IACzD,IAAI,EAAE,sBAAsB,CAAA;IAC5B,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,cAAc,CAAA;KAAE,CAAA;CAC7C;AAED,MAAM,WAAW,mBAAoB,SAAQ,SAAS;IACpD,IAAI,EAAE,iBAAiB,CAAA;IACvB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAA;CACxC;AAED,MAAM,WAAW,mBAAoB,SAAQ,SAAS;IACpD,IAAI,EAAE,iBAAiB,CAAA;IACvB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAA;CACxC"}
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,qBAAsB,SAAQ,iBAAiB;gBAC9C,OAAO,SAA8B;CAIlD;AAED,qBAAa,qBAAsB,SAAQ,iBAAiB;gBAC9C,OAAO,SAAyD;CAI7E;AAED,qBAAa,qBAAsB,SAAQ,iBAAiB;gBAC9C,OAAO,SAAsC;CAI1D;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IAC1C,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,MAAM,CAAA;CAC1B;AA8BD,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBlF;AAgCD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,KAAK,SAAS,MAAM,EAAE,KAAK;IAC7D,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,KAAK,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,KAAK,CAAA;CACZ;AAED,MAAM,MAAM,yBAAyB,GAAG,kBAAkB,CACxD,uBAAuB,EACvB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAC7D,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,CACtD,qBAAqB,EACrB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAC7D,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,CAClD,iBAAiB,EACjB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CACxD,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,CAClD,iBAAiB,EACjB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CACxD,CAAA;AAED,MAAM,MAAM,uBAAuB,GAC/B,yBAAyB,GACzB,uBAAuB,GACvB,mBAAmB,GACnB,mBAAmB,CAAA;AAEvB;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,2BAA2B,CAAA;IACnC,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAA;QACV,OAAO,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,OAAO,CAAC;YAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAA;SAAE,CAAC,CAAA;KAC/D,CAAC,CAAA;CACH;AAED,MAAM,MAAM,iBAAiB,GAAG,uBAAuB,GAAG,mBAAmB,CAAA"}

package/dist/webhooks.js

@@ -1,64 +1,125 @@
 /**
  * Webhook HMAC verification + typed event payloads.
  *
- * The Kirim API signs outbound webhook deliveries with HMAC-SHA256 over the
- * raw request body, encoded as `sha256=<hex>` in the `X-Kirim-Signature`
- * header. This module exposes a constant-time verifier using Web Crypto
- * (`crypto.subtle`) so it runs on Node 18+, Bun, Deno, and edge runtimes.
+ * Kirim signs outbound webhook deliveries using a Stripe-style header
+ * format mirroring `apps/worker/src/jobs/webhook-delivery/sign.ts`:
  *
- * The signing scheme mirrors `apps/api/src/lib/webhook-security.ts`.
+ *   X-Kirim-Signature: t=<unix_seconds>,v1=<hex>[,v1=<hex>...]
  *
- * Usage:
- *   import { verifyWebhookSignature } from '@kirimdev/sdk/webhooks'
+ * - `t` is the time the signature was computed; callers reject when
+ *   |now - t| exceeds `toleranceSeconds` (default 5 minutes).
+ * - Each `v1=` is HMAC-SHA256 of `${t}.${rawBody}` under one ACTIVE
+ *   signing secret. During rotation a subscription may have multiple
+ *   active secrets and the header carries one `v1=` per secret —
+ *   verification passes if ANY caller-supplied secret matches ANY
+ *   `v1=` value.
  *
- *   const ok = await verifyWebhookSignature(
- *     await req.text(),
- *     req.headers.get('x-kirim-signature') ?? '',
- *     process.env.KIRIM_WEBHOOK_SECRET!,
- *   )
- *   if (!ok) return new Response('bad signature', { status: 401 })
- */
-/**
- * Verify a Kirim webhook signature.
+ * Uses Web Crypto (`crypto.subtle`) so this module runs unchanged on
+ * Node 18+, Bun, Deno, and edge runtimes.
  *
- * MUST be called with the raw request body (the same bytes Kirim signed —
- * re-serializing JSON will break the signature). Returns `false` (never
- * throws) when the header is absent / malformed / mismatched. The caller
- * MUST reject the request when this returns `false` (fail-closed).
+ * The error classes in this module (`KirimWebhookError`,
+ * `InvalidSignatureError`, `SignatureExpiredError`,
+ * `MalformedPayloadError`) form a SEPARATE hierarchy from the HTTP
+ * `KirimError` tree in `@kirimdev/sdk` — webhook errors carry no
+ * `requestId` / `status` / `code` because they fire before any HTTP
+ * round-trip. Consumers wanting a single catch surface should branch
+ * on `instanceof KirimWebhookError` separately from `instanceof
+ * KirimError`.
  */
-export async function verifyWebhookSignature(body, signatureHeader, secret) {
-    if (!signatureHeader || !secret)
-        return false;
-    const provided = signatureHeader.startsWith('sha256=')
-        ? signatureHeader.slice('sha256='.length)
-        : signatureHeader;
-    const expected = await hmacSha256Hex(secret, body);
-    // Length comparison short-circuits *before* the timing-safe step. That's
-    // safe because byte length is not a secret (HMAC-SHA256 hex is always 64
-    // chars); leaking it gives the attacker nothing.
-    if (expected.length !== provided.length)
-        return false;
-    return timingSafeEqualHex(expected, provided);
+export class KirimWebhookError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KirimWebhookError';
+    }
+}
+export class InvalidSignatureError extends KirimWebhookError {
+    constructor(message = 'Invalid webhook signature') {
+        super(message);
+        this.name = 'InvalidSignatureError';
+    }
+}
+export class SignatureExpiredError extends KirimWebhookError {
+    constructor(message = 'Webhook signature timestamp outside tolerance window') {
+        super(message);
+        this.name = 'SignatureExpiredError';
+    }
+}
+export class MalformedPayloadError extends KirimWebhookError {
+    constructor(message = 'Webhook payload is not valid JSON') {
+        super(message);
+        this.name = 'MalformedPayloadError';
+    }
+}
+function parseHeader(header) {
+    const parts = header.split(',').map((s) => s.trim()).filter(Boolean);
+    let t = null;
+    const v1 = [];
+    for (const part of parts) {
+        const eq = part.indexOf('=');
+        if (eq <= 0)
+            return null;
+        const k = part.slice(0, eq);
+        const v = part.slice(eq + 1);
+        if (k === 't') {
+            const n = Number(v);
+            if (!Number.isFinite(n) || n <= 0)
+                return null;
+            t = n;
+        }
+        else if (k === 'v1') {
+            if (!/^[0-9a-f]+$/i.test(v))
+                return null;
+            v1.push(v.toLowerCase());
+        }
+        // Unknown scheme tokens (future-proof: e.g. v2=) are ignored.
+    }
+    if (t === null || v1.length === 0)
+        return null;
+    return { t, v1 };
+}
+export async function verifyWebhookSignature(opts) {
+    const tolerance = opts.toleranceSeconds ?? 300;
+    const now = (opts.nowSeconds ?? (() => Math.floor(Date.now() / 1000)))();
+    if (!opts.signatureHeader || opts.secrets.length === 0) {
+        throw new InvalidSignatureError('Missing signature header or secrets');
+    }
+    const parsed = parseHeader(opts.signatureHeader);
+    if (!parsed)
+        throw new InvalidSignatureError('Malformed signature header');
+    if (Math.abs(now - parsed.t) > tolerance) {
+        throw new SignatureExpiredError();
+    }
+    const signedString = `${parsed.t}.${opts.rawBody}`;
+    for (const secret of opts.secrets) {
+        const expected = await hmacSha256Hex(secret, signedString);
+        for (const candidate of parsed.v1) {
+            if (expected.length === candidate.length && timingSafeEqualHex(expected, candidate)) {
+                try {
+                    return JSON.parse(opts.rawBody);
+                }
+                catch {
+                    throw new MalformedPayloadError();
+                }
+            }
+        }
+    }
+    throw new InvalidSignatureError('No v1 signature matched any provided secret');
 }
 async function hmacSha256Hex(secret, body) {
     const enc = new TextEncoder();
     const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
     const buf = await crypto.subtle.sign('HMAC', key, enc.encode(body));
-    return bufferToHex(new Uint8Array(buf));
-}
-function bufferToHex(buf) {
     let out = '';
-    for (let i = 0; i < buf.length; i++) {
-        const byte = buf[i] ?? 0;
-        out += byte.toString(16).padStart(2, '0');
+    const view = new Uint8Array(buf);
+    for (let i = 0; i < view.length; i++) {
+        out += (view[i] ?? 0).toString(16).padStart(2, '0');
     }
     return out;
 }
-/** Constant-time string comparison. Inputs MUST be equal length. */
 function timingSafeEqualHex(a, b) {
     let diff = 0;
     for (let i = 0; i < a.length; i++) {
-        diff |= (a.charCodeAt(i) ^ b.charCodeAt(i));
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
     }
     return diff === 0;
 }

package/dist/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAY,EACZ,eAA0C,EAC1C,MAAc;IAEd,IAAI,CAAC,eAAe,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAC7C,MAAM,QAAQ,GAAG,eAAe,CAAC,UAAU,CAAC,SAAS,CAAC;QACpD,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;QACzC,CAAC,CAAC,eAAe,CAAA;IAEnB,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAClD,yEAAyE;IACzE,yEAAyE;IACzE,iDAAiD;IACjD,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IACrD,OAAO,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;AAC/C,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,IAAY;IACvD,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAA;IAC7B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACvC,KAAK,EACL,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAClB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAA;IACD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IACnE,OAAO,WAAW,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;AACzC,CAAC;AAED,SAAS,WAAW,CAAC,GAAe;IAClC,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACxB,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAC3C,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,oEAAoE;AACpE,SAAS,kBAAkB,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7C,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAA;AACnB,CAAC"}
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,iBAAiB;IAC1D,YAAY,OAAO,GAAG,2BAA2B;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,iBAAiB;IAC1D,YAAY,OAAO,GAAG,sDAAsD;QAC1E,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,iBAAiB;IAC1D,YAAY,OAAO,GAAG,mCAAmC;QACvD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAiBD,SAAS,WAAW,CAAC,MAAc;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACpE,IAAI,CAAC,GAAkB,IAAI,CAAA;IAC3B,MAAM,EAAE,GAAa,EAAE,CAAA;IACvB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC5B,IAAI,EAAE,IAAI,CAAC;YAAE,OAAO,IAAI,CAAA;QACxB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QAC3B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;QAC5B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACd,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;YACnB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAA;YAC9C,CAAC,GAAG,CAAC,CAAA;QACP,CAAC;aAAM,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACtB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAA;YACxC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAA;QAC1B,CAAC;QACD,8DAA8D;IAChE,CAAC;IACD,IAAI,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAC9C,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,CAAA;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAAmB;IAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,IAAI,GAAG,CAAA;IAC9C,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IACxE,IAAI,CAAC,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,CAAC,CAAA;IACxE,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;IAChD,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,qBAAqB,CAAC,4BAA4B,CAAC,CAAA;IAC1E,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC;QACzC,MAAM,IAAI,qBAAqB,EAAE,CAAA;IACnC,CAAC;IACD,MAAM,YAAY,GAAG,GAAG,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAA;IAClD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;QAC1D,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YAClC,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM,IAAI,kBAAkB,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;gBACpF,IAAI,CAAC;oBACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;gBACjC,CAAC;gBAAC,MAAM,CAAC;oBACP,MAAM,IAAI,qBAAqB,EAAE,CAAA;gBACnC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,qBAAqB,CAAC,6CAA6C,CAAC,CAAA;AAChF,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,IAAY;IACvD,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAA;IAC7B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACvC,KAAK,EACL,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAClB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAA;IACD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IACnE,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAA;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACrD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,kBAAkB,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;IAC3C,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAA;AACnB,CAAC"}