@amigo-ai/platform-sdk 0.3.0 → 0.4.1

package/README.md

@@ -23,29 +23,38 @@ const client = new AmigoClient({
 })
 
 // List agents
-const { items: agents } = await client.agents.list()
-
-// Emit a world event
-await client.world.emitEvent({
-  entity_id: 'entity-id',
-  event_type: 'appointment_scheduled',
-  data: { appointment_id: 'appt-001' },
+const { items: agents } = await client.agents.list({ limit: 10 })
+console.log(agents.map((agent) => agent.name))
+
+// Search entities in the world model
+const entityResults = await client.world.listEntities({
+  q: 'Jane Doe',
+  entity_type: ['patient'],
+  limit: 5,
 })
+console.log(entityResults.entities[0]?.display_name)
 
 // Get call analytics for the last 30 days
-const stats = await client.analytics.getCalls({ period: '30d' })
+const stats = await client.analytics.getCalls({ days: 30 })
 console.log(stats.total_calls, stats.avg_duration_seconds)
 ```
 
+## Examples and Docs
+
+- Product docs and API reference: [docs.amigo.ai](https://docs.amigo.ai/)
+- Repo-local SDK examples: [examples/README.md](./examples/README.md)
+
+The docs site remains the primary reference. The examples in this repo stay close to the package surface and are typechecked in CI to reduce drift.
+
 ## Configuration
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `apiKey` | `string` | Yes | Your Platform API key — create one at Workspace Settings > API Keys |
-| `workspaceId` | `string` | Yes | Your workspace ID — all resource operations are scoped to this |
-| `baseUrl` | `string` | No | Override the API base URL (default: `https://api.platform.amigo.ai`) |
-| `retry` | `RetryOptions` | No | Retry configuration for transient failures |
-| `fetch` | `typeof fetch` | No | Custom fetch for BFF proxy, cookie forwarding, or test mocking |
+| Option        | Type           | Required | Description                                                          |
+| ------------- | -------------- | -------- | -------------------------------------------------------------------- |
+| `apiKey`      | `string`       | Yes      | Your Platform API key — create one at Workspace Settings > API Keys  |
+| `workspaceId` | `string`       | Yes      | Your workspace ID — all resource operations are scoped to this       |
+| `baseUrl`     | `string`       | No       | Override the API base URL (default: `https://api.platform.amigo.ai`) |
+| `retry`       | `RetryOptions` | No       | Retry configuration for transient failures                           |
+| `fetch`       | `typeof fetch` | No       | Custom fetch for BFF proxy, cookie forwarding, or test mocking       |
 
 ### Retry options
 
@@ -54,8 +63,8 @@ const client = new AmigoClient({
   apiKey: 'your-key',
   workspaceId: 'your-workspace-id',
   retry: {
-    maxAttempts: 3,    // Total attempts including first. Default: 3
-    baseDelayMs: 250,  // Base delay for exponential backoff. Default: 250
+    maxAttempts: 3, // Total attempts including first. Default: 3
+    baseDelayMs: 250, // Base delay for exponential backoff. Default: 250
     maxDelayMs: 30000, // Cap on delay. Default: 30_000
   },
 })
@@ -63,6 +72,23 @@ const client = new AmigoClient({
 
 GET requests are retried on 408, 429, 500, 502, 503, 504. POST requests are only retried on 429 with a `Retry-After` header. Backoff uses full jitter.
 
+## Generated Types
+
+The SDK ships with generated OpenAPI types and re-exports them for direct use:
+
+```typescript
+import type { components, operations, paths } from '@amigo-ai/platform-sdk'
+
+type Agent = components['schemas']['AgentResponse']
+type ListAgentsQuery = operations['list_agents_v1__workspace_id__agents_get']['parameters']['query']
+```
+
+Public builds are generated from the committed [`openapi.json`](./openapi.json) snapshot in this repo so type output stays deterministic across machines and CI runs. When you need to refresh that snapshot, run:
+
+```bash
+npm run openapi:sync
+```
+
 ## Resources
 
 ### Agents
@@ -139,25 +165,27 @@ console.log(service.agent_name, service.channel_type, service.version_sets)
 The world model tracks entities (patients, contacts, appointments) and the events that flow through them.
 
 ```typescript
-// Create an entity
-const patient = await client.world.createEntity({
-  entity_type: 'patient',
-  canonical_id: 'MRN-12345',
-  display_name: 'Jane Doe',
+// Filter entities with simple list queries
+const patients = await client.world.listEntities({
+  q: 'Jane Doe',
+  entity_type: ['patient'],
+  limit: 10,
 })
+console.log(patients.entities.length)
 
-// Emit an event
-await client.world.emitEvent({
-  entity_id: patient.id,
-  event_type: 'call_completed',
-  data: { duration_seconds: 180, outcome: 'appointment_scheduled' },
-})
+// Get a single entity
+const patient = await client.world.getEntity('entity-id')
+console.log(patient.display_name, patient.entity_type)
 
 // Query timeline
-const timeline = await client.world.getTimeline(patient.id)
+const timeline = await client.world.getTimeline('entity-id', { limit: 20 })
 
-// Search entities
-const results = await client.world.search('Jane Doe', { entity_type: 'patient' })
+// Semantic search over the world model
+const results = await client.world.search({
+  q: 'Jane Doe',
+  entity_type: 'patient',
+  limit: 5,
+})
 
 // View sync status from connectors
 const syncStatus = await client.world.getSyncStatusBySink()
@@ -191,7 +219,7 @@ console.log(dashboard.call_volume.value, dashboard.call_volume.delta_pct)
 console.log(dashboard.avg_quality.value)
 
 // Call volume time series
-const calls = await client.analytics.getCalls({ period: '30d' })
+const calls = await client.analytics.getCalls({ days: 30, interval: '1d' })
 console.log(calls.total_calls, calls.calls_by_date)
 
 // Per-agent performance
@@ -229,11 +257,9 @@ console.log(analytics.coverage_rate, analytics.total_facts)
 const { items: integrations } = await client.integrations.list({ enabled: true })
 
 // Test a specific endpoint
-const result = await client.integrations.testEndpoint(
-  'integration-id',
-  'geocode',
-  { textQuery: '123 Main St, Springfield' },
-)
+const result = await client.integrations.testEndpoint('integration-id', 'geocode', {
+  textQuery: '123 Main St, Springfield',
+})
 ```
 
 ### Data Sources
@@ -367,6 +393,41 @@ const dest = await client.webhookDestinations.create({
 const deliveries = await client.webhookDestinations.listDeliveries(dest.id)
 ```
 
+## Webhook Verification
+
+Use the raw request body when verifying webhook deliveries. Timestamped signatures are replay-protected by default.
+
+```typescript
+import { parseWebhookEvent, WebhookVerificationError } from '@amigo-ai/platform-sdk'
+
+const body = await request.text()
+
+try {
+  const event = await parseWebhookEvent({
+    payload: body,
+    signature: request.headers.get('x-amigo-signature') ?? '',
+    timestamp: request.headers.get('x-amigo-timestamp') ?? undefined,
+    secret: process.env.AMIGO_WEBHOOK_SECRET!,
+  })
+
+  console.log(event.type, event.data)
+} catch (error) {
+  if (error instanceof WebhookVerificationError) {
+    console.error('Rejected webhook:', error.message)
+  } else {
+    throw error
+  }
+}
+```
+
+If your delivery channel only provides a legacy HMAC without a timestamp, the original helper signature still works:
+
+```typescript
+import { parseWebhookEvent } from '@amigo-ai/platform-sdk'
+
+const event = await parseWebhookEvent(rawBody, signature, secret)
+```
+
 ## BFF Proxy (Next.js)
 
 For frontend apps that use a Backend-for-Frontend proxy:
@@ -422,20 +483,22 @@ try {
 }
 ```
 
+Webhook verification errors are separate from API transport errors and throw `WebhookVerificationError`.
+
 ### Error classes
 
-| Class | HTTP Status | Description |
-|-------|-------------|-------------|
-| `BadRequestError` | 400 | Malformed request |
-| `AuthenticationError` | 401 | Invalid or expired API key |
-| `PermissionError` | 403 | Insufficient permissions |
-| `NotFoundError` | 404 | Resource does not exist |
-| `ConflictError` | 409 | Duplicate slug or version conflict |
-| `ValidationError` | 422 | Request body validation failure |
-| `RateLimitError` | 429 | Too many requests — check `.retryAfter` |
-| `ServerError` | 5xx | Server-side error |
-| `ConfigurationError` | — | SDK misconfiguration at init time |
-| `NetworkError` | — | Fetch/network failure |
+| Class                 | HTTP Status | Description                             |
+| --------------------- | ----------- | --------------------------------------- |
+| `BadRequestError`     | 400         | Malformed request                       |
+| `AuthenticationError` | 401         | Invalid or expired API key              |
+| `PermissionError`     | 403         | Insufficient permissions                |
+| `NotFoundError`       | 404         | Resource does not exist                 |
+| `ConflictError`       | 409         | Duplicate slug or version conflict      |
+| `ValidationError`     | 422         | Request body validation failure         |
+| `RateLimitError`      | 429         | Too many requests — check `.retryAfter` |
+| `ServerError`         | 5xx         | Server-side error                       |
+| `ConfigurationError`  | —           | SDK misconfiguration at init time       |
+| `NetworkError`        | —           | Fetch/network failure                   |
 
 ## CommonJS (CJS) usage
 

package/dist/core/errors.js

@@ -140,9 +140,8 @@ export class ConfigurationError extends AmigoError {
 }
 export async function createApiError(response) {
     let body = {};
-    let rawBody;
     try {
-        rawBody = await response.text();
+        const rawBody = await response.text();
         body = JSON.parse(rawBody);
     }
     catch {
@@ -151,7 +150,7 @@ export async function createApiError(response) {
     const ctx = {
         statusCode: response.status,
         errorCode: body.error_code,
-        requestId: body.request_id,
+        requestId: body.request_id ?? response.headers.get('x-request-id') ?? undefined,
         detail: body.detail,
         context: { url: response.url, response: body },
     };

package/dist/core/errors.js.map

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

package/dist/core/webhooks.js

@@ -1,17 +1,137 @@
-export async function verifyWebhookSignature(payload, signature, secret) {
-    const encoder = new TextEncoder();
-    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
-    const mac = await crypto.subtle.sign('HMAC', key, typeof payload === 'string' ? encoder.encode(payload) : payload);
-    const expected = Array.from(new Uint8Array(mac))
-        .map((b) => b.toString(16).padStart(2, '0'))
-        .join('');
-    return signature === `sha256=${expected}`;
-}
-export async function parseWebhookEvent(payload, signature, secret) {
-    const valid = await verifyWebhookSignature(payload, signature, secret);
+const textEncoder = new TextEncoder();
+const MAX_TIMESTAMP_SKEW_MS = 5 * 60 * 1000;
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WebhookVerificationError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export async function verifyWebhookSignature(payloadOrOptions, signature, secret) {
+    const options = normalizeVerificationOptions(payloadOrOptions, signature, secret);
+    const payloadBytes = toUint8Array(options.payload);
+    const expectedSignature = await signWebhookPayload(payloadBytes, options.secret, options.timestamp);
+    const actualSignature = normalizeSignature(options.signature);
+    if (!actualSignature || !constantTimeEqual(expectedSignature, actualSignature)) {
+        return false;
+    }
+    if (options.timestamp) {
+        const timestampMs = parseTimestamp(options.timestamp);
+        if (timestampMs === undefined)
+            return false;
+        const maxAgeMs = options.maxAgeMs ?? MAX_TIMESTAMP_SKEW_MS;
+        const now = Date.now();
+        if (timestampMs > now + maxAgeMs || now - timestampMs > maxAgeMs) {
+            return false;
+        }
+    }
+    return true;
+}
+export async function parseWebhookEvent(payloadOrOptions, signature, secret) {
+    const options = normalizeParseOptions(payloadOrOptions, signature, secret);
+    const valid = await verifyWebhookSignature(options);
     if (!valid) {
-        throw new Error('Invalid webhook signature');
+        throw new WebhookVerificationError('Invalid or expired webhook signature');
+    }
+    const payloadText = decodePayload(options.payload);
+    let event;
+    try {
+        event = JSON.parse(payloadText, options.reviver);
+    }
+    catch {
+        throw new WebhookVerificationError('Invalid JSON webhook payload');
+    }
+    if (options.expectedType && event.type !== options.expectedType) {
+        throw new WebhookVerificationError(`Unexpected webhook event type: expected ${options.expectedType}, received ${event.type}`);
+    }
+    options.validate?.(event);
+    return event;
+}
+function normalizeVerificationOptions(payloadOrOptions, signature, secret) {
+    if (typeof payloadOrOptions === 'object' &&
+        payloadOrOptions !== null &&
+        'payload' in payloadOrOptions) {
+        return payloadOrOptions;
+    }
+    if (!signature || !secret) {
+        throw new TypeError('signature and secret are required');
+    }
+    return {
+        payload: payloadOrOptions,
+        signature,
+        secret,
+    };
+}
+function normalizeParseOptions(payloadOrOptions, signature, secret) {
+    if (typeof payloadOrOptions === 'object' &&
+        payloadOrOptions !== null &&
+        'payload' in payloadOrOptions) {
+        return payloadOrOptions;
     }
-    return JSON.parse(payload);
+    if (!signature || !secret) {
+        throw new TypeError('signature and secret are required');
+    }
+    return {
+        payload: payloadOrOptions,
+        signature,
+        secret,
+    };
+}
+function decodePayload(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    return new TextDecoder().decode(toUint8Array(payload));
+}
+function toUint8Array(payload) {
+    if (typeof payload === 'string')
+        return textEncoder.encode(payload);
+    if (payload instanceof Uint8Array)
+        return payload;
+    return new Uint8Array(payload);
+}
+async function signWebhookPayload(payload, secret, timestamp) {
+    const key = await crypto.subtle.importKey('raw', textEncoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const message = timestamp
+        ? concatUint8Arrays(textEncoder.encode(`v1:${timestamp}:`), payload)
+        : payload;
+    const mac = await crypto.subtle.sign('HMAC', key, toCryptoBuffer(message));
+    return new Uint8Array(mac);
+}
+function normalizeSignature(signature) {
+    const normalized = signature.startsWith('sha256=') ? signature.slice(7) : signature;
+    if (!/^[a-fA-F0-9]+$/.test(normalized) || normalized.length % 2 !== 0) {
+        return undefined;
+    }
+    const bytes = new Uint8Array(normalized.length / 2);
+    for (let index = 0; index < normalized.length; index += 2) {
+        bytes[index / 2] = Number.parseInt(normalized.slice(index, index + 2), 16);
+    }
+    return bytes;
+}
+function constantTimeEqual(expected, actual) {
+    const maxLength = Math.max(expected.length, actual.length);
+    let diff = expected.length ^ actual.length;
+    for (let index = 0; index < maxLength; index += 1) {
+        diff |= (expected[index] ?? 0) ^ (actual[index] ?? 0);
+    }
+    return diff === 0;
+}
+function parseTimestamp(timestamp) {
+    const numeric = Number(timestamp);
+    if (Number.isFinite(numeric)) {
+        return numeric < 1_000_000_000_000 ? numeric * 1000 : numeric;
+    }
+    const parsed = Date.parse(timestamp);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+function concatUint8Arrays(left, right) {
+    const combined = new Uint8Array(left.length + right.length);
+    combined.set(left, 0);
+    combined.set(right, left.length);
+    return combined;
+}
+function toCryptoBuffer(bytes) {
+    const copy = Uint8Array.from(bytes);
+    return copy.buffer;
 }
 //# sourceMappingURL=webhooks.js.map

package/dist/core/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/core/webhooks.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAA4B,EAC5B,SAAiB,EACjB,MAAc;IAEd,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;IACjC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACvC,KAAK,EACL,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EACtB,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,CAClC,MAAM,EACN,GAAG,EACH,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAChE,CAAA;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;SAC7C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAA;IACX,OAAO,SAAS,KAAK,UAAU,QAAQ,EAAE,CAAA;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAe,EACf,SAAiB,EACjB,MAAc;IAEd,MAAM,KAAK,GAAG,MAAM,sBAAsB,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAA;IACtE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAA;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,CAAA;AAC/C,CAAC"}
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/core/webhooks.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -45,6 +45,7 @@ __export(index_exports, {
   ServerError: () => ServerError,
   ServiceUnavailableError: () => ServiceUnavailableError,
   ValidationError: () => ValidationError,
+  WebhookVerificationError: () => WebhookVerificationError,
   actionId: () => actionId,
   agentId: () => agentId,
   apiKeyId: () => apiKeyId,
@@ -204,16 +205,15 @@ var ConfigurationError = class extends AmigoError {
 };
 async function createApiError(response) {
   let body = {};
-  let rawBody;
   try {
-    rawBody = await response.text();
+    const rawBody = await response.text();
     body = JSON.parse(rawBody);
   } catch {
   }
   const ctx = {
     statusCode: response.status,
     errorCode: body.error_code,
-    requestId: body.request_id,
+    requestId: body.request_id ?? response.headers.get("x-request-id") ?? void 0,
     detail: body.detail,
     context: { url: response.url, response: body }
   };
@@ -2199,29 +2199,142 @@ function parseRateLimitHeaders(headers) {
 }
 
 // src/core/webhooks.ts
-async function verifyWebhookSignature(payload, signature, secret) {
-  const encoder = new TextEncoder();
+var textEncoder = new TextEncoder();
+var MAX_TIMESTAMP_SKEW_MS = 5 * 60 * 1e3;
+var WebhookVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookVerificationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+async function verifyWebhookSignature(payloadOrOptions, signature, secret) {
+  const options = normalizeVerificationOptions(payloadOrOptions, signature, secret);
+  const payloadBytes = toUint8Array(options.payload);
+  const expectedSignature = await signWebhookPayload(
+    payloadBytes,
+    options.secret,
+    options.timestamp
+  );
+  const actualSignature = normalizeSignature(options.signature);
+  if (!actualSignature || !constantTimeEqual(expectedSignature, actualSignature)) {
+    return false;
+  }
+  if (options.timestamp) {
+    const timestampMs = parseTimestamp(options.timestamp);
+    if (timestampMs === void 0) return false;
+    const maxAgeMs = options.maxAgeMs ?? MAX_TIMESTAMP_SKEW_MS;
+    const now = Date.now();
+    if (timestampMs > now + maxAgeMs || now - timestampMs > maxAgeMs) {
+      return false;
+    }
+  }
+  return true;
+}
+async function parseWebhookEvent(payloadOrOptions, signature, secret) {
+  const options = normalizeParseOptions(payloadOrOptions, signature, secret);
+  const valid = await verifyWebhookSignature(options);
+  if (!valid) {
+    throw new WebhookVerificationError("Invalid or expired webhook signature");
+  }
+  const payloadText = decodePayload(options.payload);
+  let event;
+  try {
+    event = JSON.parse(payloadText, options.reviver);
+  } catch {
+    throw new WebhookVerificationError("Invalid JSON webhook payload");
+  }
+  if (options.expectedType && event.type !== options.expectedType) {
+    throw new WebhookVerificationError(
+      `Unexpected webhook event type: expected ${options.expectedType}, received ${event.type}`
+    );
+  }
+  options.validate?.(event);
+  return event;
+}
+function normalizeVerificationOptions(payloadOrOptions, signature, secret) {
+  if (typeof payloadOrOptions === "object" && payloadOrOptions !== null && "payload" in payloadOrOptions) {
+    return payloadOrOptions;
+  }
+  if (!signature || !secret) {
+    throw new TypeError("signature and secret are required");
+  }
+  return {
+    payload: payloadOrOptions,
+    signature,
+    secret
+  };
+}
+function normalizeParseOptions(payloadOrOptions, signature, secret) {
+  if (typeof payloadOrOptions === "object" && payloadOrOptions !== null && "payload" in payloadOrOptions) {
+    return payloadOrOptions;
+  }
+  if (!signature || !secret) {
+    throw new TypeError("signature and secret are required");
+  }
+  return {
+    payload: payloadOrOptions,
+    signature,
+    secret
+  };
+}
+function decodePayload(payload) {
+  if (typeof payload === "string") return payload;
+  return new TextDecoder().decode(toUint8Array(payload));
+}
+function toUint8Array(payload) {
+  if (typeof payload === "string") return textEncoder.encode(payload);
+  if (payload instanceof Uint8Array) return payload;
+  return new Uint8Array(payload);
+}
+async function signWebhookPayload(payload, secret, timestamp) {
   const key = await crypto.subtle.importKey(
     "raw",
-    encoder.encode(secret),
+    textEncoder.encode(secret),
     { name: "HMAC", hash: "SHA-256" },
     false,
     ["sign"]
   );
-  const mac = await crypto.subtle.sign(
-    "HMAC",
-    key,
-    typeof payload === "string" ? encoder.encode(payload) : payload
-  );
-  const expected = Array.from(new Uint8Array(mac)).map((b) => b.toString(16).padStart(2, "0")).join("");
-  return signature === `sha256=${expected}`;
+  const message = timestamp ? concatUint8Arrays(textEncoder.encode(`v1:${timestamp}:`), payload) : payload;
+  const mac = await crypto.subtle.sign("HMAC", key, toCryptoBuffer(message));
+  return new Uint8Array(mac);
 }
-async function parseWebhookEvent(payload, signature, secret) {
-  const valid = await verifyWebhookSignature(payload, signature, secret);
-  if (!valid) {
-    throw new Error("Invalid webhook signature");
+function normalizeSignature(signature) {
+  const normalized = signature.startsWith("sha256=") ? signature.slice(7) : signature;
+  if (!/^[a-fA-F0-9]+$/.test(normalized) || normalized.length % 2 !== 0) {
+    return void 0;
+  }
+  const bytes = new Uint8Array(normalized.length / 2);
+  for (let index = 0; index < normalized.length; index += 2) {
+    bytes[index / 2] = Number.parseInt(normalized.slice(index, index + 2), 16);
+  }
+  return bytes;
+}
+function constantTimeEqual(expected, actual) {
+  const maxLength = Math.max(expected.length, actual.length);
+  let diff = expected.length ^ actual.length;
+  for (let index = 0; index < maxLength; index += 1) {
+    diff |= (expected[index] ?? 0) ^ (actual[index] ?? 0);
   }
-  return JSON.parse(payload);
+  return diff === 0;
+}
+function parseTimestamp(timestamp) {
+  const numeric = Number(timestamp);
+  if (Number.isFinite(numeric)) {
+    return numeric < 1e12 ? numeric * 1e3 : numeric;
+  }
+  const parsed = Date.parse(timestamp);
+  return Number.isNaN(parsed) ? void 0 : parsed;
+}
+function concatUint8Arrays(left, right) {
+  const combined = new Uint8Array(left.length + right.length);
+  combined.set(left, 0);
+  combined.set(right, left.length);
+  return combined;
+}
+function toCryptoBuffer(bytes) {
+  const copy = Uint8Array.from(bytes);
+  return copy.buffer;
 }
 
 // src/index.ts