@wazapi/sdk 0.1.0 → 0.3.0

package/README.md

@@ -108,6 +108,27 @@ operation is created):
 | `template_parameter_count_mismatch` | `parameters.length` ≠ `body_parameter_count`.        |
 | `template_format_unsupported`       | Needs media/variable header, named params, buttons.  |
 
+Compliance gates on template sends (rejected synchronously with 403/422, and
+re-checked by the worker — the same codes can appear as `error.code` on the
+polled operation):
+
+| Code                                    | Meaning                                                                  |
+| --------------------------------------- | ------------------------------------------------------------------------ |
+| `marketing_sends_disabled`              | MARKETING sending is off for the company (an owner enables it in the dashboard) or platform-wide. |
+| `recipient_opted_out`                   | The recipient opted out (reply keyword, native WhatsApp control, or manual suppression). Filter on `contact.marketing_opted_out`. |
+| `duplicate_template_send`               | Same template already sent to this phone in the last 24h.                |
+| `template_frequency_cap_exceeded`       | Per-contact MARKETING cap (1/24h, 3/7 days).                             |
+| `company_daily_marketing_cap_exceeded`  | Company-wide daily MARKETING cap.                                        |
+| `channel_marketing_paused`              | Meta flagged the number's quality; MARKETING is paused temporarily.      |
+| `template_quality_blocked`              | This specific template dropped to RED quality on Meta.                   |
+| `send_pacing_timeout`                   | Operation-only: delivery was deferred by per-channel pacing for too long. |
+
+Delivery is paced per channel to protect number quality, so an accepted `202`
+can take longer to complete under load — poll the operation instead of
+re-sending. AUTHENTICATION (OTP) templates are exempt from opt-outs and caps.
+Use `error.isComplianceBlocked` to branch on this whole family, and the
+`SendComplianceErrorCode` type to narrow `operation.error.code`.
+
 ## Contacts
 
 ```ts
@@ -119,6 +140,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/error.d.ts

@@ -21,4 +21,11 @@ export declare class WazapiError extends Error {
     });
     /** True for 429 rate-limit responses. */
     get isRateLimited(): boolean;
+    /**
+     * True when the send was refused by a compliance gate (opt-out, frequency
+     * cap, marketing policy, channel/template quality pause) rather than by a
+     * malformed request. Retrying without changing the audience will not help —
+     * fix the recipient list or the account policy instead.
+     */
+    get isComplianceBlocked(): boolean;
 }

package/dist/error.js

@@ -24,4 +24,22 @@ export class WazapiError extends Error {
     get isRateLimited() {
         return this.status === 429;
     }
+    /**
+     * True when the send was refused by a compliance gate (opt-out, frequency
+     * cap, marketing policy, channel/template quality pause) rather than by a
+     * malformed request. Retrying without changing the audience will not help —
+     * fix the recipient list or the account policy instead.
+     */
+    get isComplianceBlocked() {
+        return [
+            'marketing_sends_disabled',
+            'template_sends_disabled',
+            'recipient_opted_out',
+            'duplicate_template_send',
+            'template_frequency_cap_exceeded',
+            'company_daily_marketing_cap_exceeded',
+            'channel_marketing_paused',
+            'template_quality_blocked',
+        ].includes(this.code);
+    }
 }

package/dist/types.d.ts

@@ -30,6 +30,14 @@ export interface Contact {
     email: string | null;
     tags: string[];
     custom_fields: Record<string, unknown>;
+    /**
+     * True when the contact opted out of marketing messages (reply keyword such
+     * as PARAR/STOP, the native WhatsApp control, or manual suppression).
+     * Sending a MARKETING template to an opted-out contact fails with
+     * `recipient_opted_out` — filter your audience on this before a campaign.
+     */
+    marketing_opted_out: boolean;
+    marketing_opt_out_at: string | null;
     last_interaction_at: string | null;
     created_at: string | null;
     updated_at: string | null;
@@ -91,6 +99,13 @@ export interface Message {
     updated_at: string | null;
 }
 export type OperationStatus = 'queued' | 'processing' | 'waiting' | 'succeeded' | 'failed';
+/**
+ * Compliance codes the send guard can answer with. They surface both as a
+ * synchronous 4xx on `POST /messages` (403 for the two `*_disabled` codes,
+ * 422 for the rest) and as `error.code` on the polled operation —
+ * `send_pacing_timeout` only ever appears on the operation.
+ */
+export type SendComplianceErrorCode = 'marketing_sends_disabled' | 'template_sends_disabled' | 'recipient_opted_out' | 'duplicate_template_send' | 'template_frequency_cap_exceeded' | 'company_daily_marketing_cap_exceeded' | 'channel_marketing_paused' | 'template_quality_blocked' | 'send_pacing_timeout';
 export interface Operation {
     uuid: string;
     type: 'message.send' | 'flow.execute';
@@ -143,3 +158,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.3.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"
   }
 }