@wazapi/sdk 0.1.0 → 0.2.0

package/README.md

@@ -119,6 +119,52 @@ await wazapi.upsertContactByExternalId('customer-1847', {
 })
 ```
 
+## Webhooks
+
+Wazapi POSTs events to the HTTPS endpoint you register in **Settings → Wazapi API**.
+The SDK ships the payload types; the union is discriminated on `type`, so narrowing
+`event.type` narrows `event.data` with it.
+
+```ts
+import type { WazapiWebhookEvent } from '@wazapi/sdk'
+
+function handle(event: WazapiWebhookEvent) {
+  switch (event.type) {
+    case 'message.received':
+      return reply(event.data.contact_uuid, event.data.content)
+    case 'message.status.updated':
+      return markDelivered(event.data.message_uuid, event.data.status)
+    case 'flow.execution.updated':
+      return event.data.error ? alert(event.data.error.code) : done()
+  }
+}
+```
+
+Verify the signature over the **raw** body, before parsing:
+
+```ts
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+function verify(rawBody: string, headers: Record<string, string>, secret: string) {
+  const expected = createHmac('sha256', secret)
+    .update(`${headers['wazapi-timestamp']}.${rawBody}`)
+    .digest('hex')
+  const received = (headers['wazapi-signature'] ?? '').replace(/^v1=/, '')
+  const a = Buffer.from(expected)
+  const b = Buffer.from(received)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+```
+
+Delivery is at-least-once — deduplicate on `event.id` (also sent as the
+`Wazapi-Event-Id` header). Wazapi treats only `2xx` as success and retries after
+1min, 5min, 30min, 2h, 12h and 24h.
+
+Two fields are added at delivery time when they apply: `data.external_id`, your own
+identifier echoed back when the contact was linked via `upsertContactByExternalId`,
+and `data.tracking`, the allowlisted attribution subset (`utm_*`, click IDs, ad
+referral fields). No other custom field key is ever forwarded.
+
 ## Configuration
 
 ```ts

package/dist/types.d.ts

@@ -143,3 +143,81 @@ export interface AcceptedResult {
     /** True when the request replayed a previously accepted idempotent operation. */
     replayed: boolean;
 }
+export type WebhookEventType = 'message.received' | 'message.status.updated' | 'conversation.created' | 'conversation.updated' | 'flow.execution.updated' | 'webhook.test';
+/**
+ * Allowlisted attribution subset of the contact's and conversation's custom
+ * fields. Conversation values win over contact values (last touch over first
+ * touch); no other custom field key is ever forwarded.
+ */
+export type WebhookTracking = Record<string, unknown>;
+/**
+ * Added at delivery time whenever the payload carries a `contact_uuid` and that
+ * contact was linked through `PUT /contacts/external/{external_id}`.
+ */
+interface WebhookContactRefs {
+    external_id?: string;
+    tracking?: WebhookTracking;
+}
+export interface MessageReceivedData extends WebhookContactRefs {
+    message_uuid: string;
+    conversation_uuid: string;
+    contact_uuid: string;
+    channel_uuid: string;
+    type: string;
+    content: Record<string, unknown>;
+    status: string;
+}
+/**
+ * `provider_message_id` comes from the provider status callback; `operation_uuid`
+ * and `conversation_uuid` are present when the message was sent through the API.
+ */
+export interface MessageStatusUpdatedData {
+    message_uuid: string;
+    status: string;
+    provider_message_id?: string | null;
+    operation_uuid?: string;
+    conversation_uuid?: string;
+    tracking?: WebhookTracking;
+}
+export interface ConversationCreatedData extends WebhookContactRefs {
+    conversation_uuid: string;
+    contact_uuid: string;
+    channel_uuid: string;
+    status: string;
+}
+/** `unread_count` is only present when an inbound message triggered the update. */
+export interface ConversationUpdatedData extends ConversationCreatedData {
+    unread_count?: number;
+    last_message_at?: string | null;
+}
+export interface FlowExecutionUpdatedData {
+    operation_uuid: string;
+    operation_type: 'flow.execute';
+    status: OperationStatus;
+    result: Record<string, unknown> | null;
+    error: {
+        code: string;
+        message: string | null;
+    } | null;
+}
+export interface WebhookTestData {
+    integration_uuid: string;
+    message: string;
+}
+interface WebhookEnvelope<TType extends WebhookEventType, TData> {
+    /** Unique event id. Delivery is at-least-once — deduplicate on this value. */
+    id: string;
+    type: TType;
+    api_version: 'v1';
+    occurred_at: string;
+    data: TData;
+}
+export type MessageReceivedEvent = WebhookEnvelope<'message.received', MessageReceivedData>;
+export type MessageStatusUpdatedEvent = WebhookEnvelope<'message.status.updated', MessageStatusUpdatedData>;
+export type ConversationCreatedEvent = WebhookEnvelope<'conversation.created', ConversationCreatedData>;
+export type ConversationUpdatedEvent = WebhookEnvelope<'conversation.updated', ConversationUpdatedData>;
+export type FlowExecutionUpdatedEvent = WebhookEnvelope<'flow.execution.updated', FlowExecutionUpdatedData>;
+export type WebhookTestEvent = WebhookEnvelope<'webhook.test', WebhookTestData>;
+/** Discriminated on `type` — narrow it and `data` narrows with it. */
+export type WazapiWebhookEvent = MessageReceivedEvent | MessageStatusUpdatedEvent | ConversationCreatedEvent | ConversationUpdatedEvent | FlowExecutionUpdatedEvent | WebhookTestEvent;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wazapi/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official Node.js SDK for the Wazapi Public API v1",
   "license": "MIT",
   "type": "module",
@@ -10,8 +10,7 @@
   "homepage": "https://wazapi.io",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/wazap-ai/wazap-v2.git",
-    "directory": "apps/app/sdk"
+    "url": "git+https://github.com/wazap-ai/wazapi-node.git"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,7 +21,10 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "engines": {
     "node": ">=18"
   },
@@ -31,8 +33,17 @@
     "test": "npm run build && node --test --experimental-strip-types test/*.test.ts",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["wazapi", "whatsapp", "api", "sdk", "messaging"],
+  "keywords": [
+    "wazapi",
+    "whatsapp",
+    "api",
+    "sdk",
+    "messaging"
+  ],
   "devDependencies": {
     "typescript": "^5.6.0"
+  },
+  "bugs": {
+    "url": "https://github.com/wazap-ai/wazapi-node/issues"
   }
 }