@wazapi/sdk 0.2.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

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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wazapi/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official Node.js SDK for the Wazapi Public API v1",
   "license": "MIT",
   "type": "module",