@wazapi/sdk 0.2.0 → 0.4.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/client.d.ts

@@ -1,4 +1,4 @@
-import type { AcceptedResult, Channel, Contact, ContactWrite, Conversation, ExecuteFlowInput, Flow, ListParams, Message, Operation, Paginated, SendMessageInput, Template } from './types.js';
+import type { AcceptedResult, Channel, Contact, ContactWrite, Conversation, ConversationDetail, ExecuteFlowInput, Flow, ListParams, Message, Operation, Paginated, SendMessageInput, StoreBatchResult, StoreOrder, StoreOrderStatus, StoreProduct, StoreProductWrite, StoreSummary, Template } from './types.js';
 export interface WazapiClientOptions {
     /** Bearer token issued in Settings → Wazapi API (starts with `waz_api_`). */
     token: string;
@@ -45,7 +45,15 @@ export declare class WazapiClient {
     getFlow(uuid: string): Promise<Flow>;
     executeFlow(flowUuid: string, input: ExecuteFlowInput, idempotencyKey?: string): Promise<AcceptedResult>;
     listConversations(params?: ListParams): Promise<Paginated<Conversation>>;
-    getConversation(uuid: string): Promise<Conversation>;
+    /**
+     * Everything about the chat in one call: contact (with tags), assigned agent
+     * and group, channel, status and counters. Pass `options.include = 'messages'`
+     * to embed the first page of messages — audio messages carry their
+     * `transcript` as a first-level field.
+     */
+    getConversation(uuid: string, options?: {
+        include?: 'messages';
+    }): Promise<ConversationDetail>;
     listMessages(conversationUuid: string, params?: ListParams): Promise<Paginated<Message>>;
     sendMessage(input: SendMessageInput, idempotencyKey?: string): Promise<AcceptedResult>;
     /** Convenience wrapper for a plain text send. */
@@ -56,6 +64,28 @@ export declare class WazapiClient {
         language?: string;
         parameters?: string[];
     }, idempotencyKey?: string): Promise<AcceptedResult>;
+    /** Storefront status, public URL and product/order counts. Requires `store:read`. */
+    getStore(): Promise<StoreSummary>;
+    listStoreProducts(params?: ListParams): Promise<Paginated<StoreProduct>>;
+    getStoreProduct(uuid: string): Promise<StoreProduct>;
+    createStoreProduct(input: StoreProductWrite): Promise<StoreProduct>;
+    updateStoreProduct(uuid: string, input: StoreProductWrite): Promise<StoreProduct>;
+    /**
+     * Creates or updates up to 100 products in one call with a per-item result —
+     * one invalid product does not fail the batch. Items whose `import_handle`
+     * matches an existing product UPDATE it instead of creating a duplicate: this
+     * is the migration path for an external catalog (Shopify, an ERP).
+     */
+    batchStoreProducts(products: StoreProductWrite[]): Promise<StoreBatchResult>;
+    listStoreOrders(params?: ListParams): Promise<Paginated<StoreOrder>>;
+    getStoreOrder(uuid: string): Promise<StoreOrder>;
+    /**
+     * Transitions an order through its state machine (novo→confirmado→pago→entregue,
+     * cancel from any non-terminal state). An invalid transition throws a
+     * `WazapiError` with code `invalid_status_transition` (422). Cancelling
+     * restores tracked stock.
+     */
+    updateStoreOrderStatus(uuid: string, status: Exclude<StoreOrderStatus, 'novo'>): Promise<StoreOrder>;
     getOperation(uuid: string): Promise<Operation>;
     /**
      * Polls an operation until it reaches a terminal status. Resolves with the final

package/dist/client.js

@@ -62,8 +62,17 @@ export class WazapiClient {
     listConversations(params = {}) {
         return this.request('GET', this.withQuery('/conversations', params));
     }
-    async getConversation(uuid) {
-        const body = await this.request('GET', `/conversations/${encode(uuid)}`);
+    /**
+     * Everything about the chat in one call: contact (with tags), assigned agent
+     * and group, channel, status and counters. Pass `options.include = 'messages'`
+     * to embed the first page of messages — audio messages carry their
+     * `transcript` as a first-level field.
+     */
+    async getConversation(uuid, options = {}) {
+        const path = options.include
+            ? `/conversations/${encode(uuid)}?include=${options.include}`
+            : `/conversations/${encode(uuid)}`;
+        const body = await this.request('GET', path);
         return body.data;
     }
     listMessages(conversationUuid, params = {}) {
@@ -81,6 +90,55 @@ export class WazapiClient {
     sendTemplate(channelUuid, phone, template, idempotencyKey) {
         return this.sendMessage({ channel_uuid: channelUuid, recipient: { phone }, type: 'template', content: template }, idempotencyKey);
     }
+    // ---- Store ------------------------------------------------------------
+    /** Storefront status, public URL and product/order counts. Requires `store:read`. */
+    async getStore() {
+        const body = await this.request('GET', '/store');
+        return body.data;
+    }
+    listStoreProducts(params = {}) {
+        return this.request('GET', this.withQuery('/store/products', params));
+    }
+    async getStoreProduct(uuid) {
+        const body = await this.request('GET', `/store/products/${encode(uuid)}`);
+        return body.data;
+    }
+    async createStoreProduct(input) {
+        const body = await this.request('POST', '/store/products', {
+            body: input,
+        });
+        return body.data;
+    }
+    async updateStoreProduct(uuid, input) {
+        const body = await this.request('PATCH', `/store/products/${encode(uuid)}`, { body: input });
+        return body.data;
+    }
+    /**
+     * Creates or updates up to 100 products in one call with a per-item result —
+     * one invalid product does not fail the batch. Items whose `import_handle`
+     * matches an existing product UPDATE it instead of creating a duplicate: this
+     * is the migration path for an external catalog (Shopify, an ERP).
+     */
+    batchStoreProducts(products) {
+        return this.request('POST', '/store/products/batch', { body: { products } });
+    }
+    listStoreOrders(params = {}) {
+        return this.request('GET', this.withQuery('/store/orders', params));
+    }
+    async getStoreOrder(uuid) {
+        const body = await this.request('GET', `/store/orders/${encode(uuid)}`);
+        return body.data;
+    }
+    /**
+     * Transitions an order through its state machine (novo→confirmado→pago→entregue,
+     * cancel from any non-terminal state). An invalid transition throws a
+     * `WazapiError` with code `invalid_status_transition` (422). Cancelling
+     * restores tracked stock.
+     */
+    async updateStoreOrderStatus(uuid, status) {
+        const body = await this.request('POST', `/store/orders/${encode(uuid)}/status`, { body: { status } });
+        return body.data;
+    }
     // ---- Operations -------------------------------------------------------
     async getOperation(uuid) {
         const body = await this.request('GET', `/operations/${encode(uuid)}`);

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

@@ -1,4 +1,4 @@
-export type PublicApiScope = 'channels:read' | 'contacts:read' | 'contacts:write' | 'conversations:read' | 'messages:read' | 'messages:write' | 'templates:read' | 'flows:read' | 'flows:execute' | 'operations:read';
+export type PublicApiScope = 'channels:read' | 'contacts:read' | 'contacts:write' | 'conversations:read' | 'messages:read' | 'messages:write' | 'templates:read' | 'flows:read' | 'flows:execute' | 'operations:read' | 'store:read' | 'store:write';
 export interface PaginationMeta {
     next_cursor: string | null;
 }
@@ -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;
@@ -80,17 +88,50 @@ export interface Conversation {
     created_at: string | null;
     updated_at: string | null;
 }
+/**
+ * `GET /conversations/{uuid}` — everything about the chat in one call: contact
+ * (with tags), assigned agent and group, channel, status and counters. Pass
+ * `include: 'messages'` to embed the first page of messages.
+ */
+export interface ConversationDetail extends Conversation {
+    channel_provider: string | null;
+    assigned_agent: {
+        uuid: string;
+        name: string | null;
+    } | null;
+    assigned_group: {
+        uuid: string;
+        name: string;
+    } | null;
+    message_count: number;
+    /** Present only when requested with `include: 'messages'`. */
+    messages?: Message[];
+}
 export interface Message {
     uuid: string;
     direction: 'inbound' | 'outbound';
     type: string;
     status: string;
     content: Record<string, unknown>;
+    /**
+     * Transcription of an inbound audio message, when available. Populated
+     * asynchronously after transcription; also delivered via the
+     * `message.transcribed` webhook. `null` for non-audio messages and audios
+     * not yet transcribed.
+     */
+    transcript: string | null;
     provider_message_id: string | null;
     created_at: string | null;
     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,7 +184,132 @@ 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';
+export interface StoreSummary {
+    enabled: boolean;
+    mode: 'links_only' | 'store_only' | 'both' | null;
+    slug: string | null;
+    /** Public storefront path (relative, e.g. `/loja/minha-loja`). */
+    url: string | null;
+    product_count: number;
+    order_count: number;
+}
+export interface StoreProductVariant {
+    uuid: string;
+    label: string;
+    price_cents: number | null;
+    stock: number | null;
+    active: boolean;
+    position: number;
+}
+export interface StoreProduct {
+    uuid: string;
+    name: string;
+    description: string | null;
+    category_uuid: string | null;
+    price_cents: number;
+    promo_price_cents: number | null;
+    effective_price_cents: number;
+    images: string[];
+    highlighted: boolean;
+    track_stock: boolean;
+    stock: number | null;
+    active: boolean;
+    position: number;
+    /**
+     * External catalog handle (e.g. Shopify Handle). Products sharing the same
+     * handle are updated on re-import/batch instead of duplicated.
+     */
+    import_handle: string | null;
+    variants: StoreProductVariant[];
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface StoreProductWrite {
+    name: string;
+    description?: string | null;
+    category_uuid?: string | null;
+    price_cents: number;
+    promo_price_cents?: number | null;
+    highlighted?: boolean;
+    track_stock?: boolean;
+    stock?: number | null;
+    active?: boolean;
+    position?: number;
+    import_handle?: string | null;
+    /**
+     * On update the variant list replaces the existing one: variants whose `uuid`
+     * is present are kept/updated, the rest are deleted.
+     */
+    variants?: {
+        uuid?: string | null;
+        label: string;
+        price_cents?: number | null;
+        stock?: number | null;
+        active?: boolean;
+    }[];
+}
+export type StoreOrderStatus = 'novo' | 'confirmado' | 'pago' | 'entregue' | 'cancelado';
+export interface StoreOrderItem {
+    product_uuid: string;
+    name: string;
+    variant_label: string | null;
+    quantity: number;
+    unit_price_cents: number;
+    total_cents: number;
+}
+export type StoreOrderSource = 'storefront' | 'whatsapp_catalog';
+export interface StoreOrder {
+    uuid: string;
+    /** Short human reference (first 8 chars of the uuid) shown to the customer. */
+    ref: string;
+    status: StoreOrderStatus;
+    /** Where the order was placed: storefront checkout or the native WhatsApp catalog. */
+    source: StoreOrderSource;
+    /** Provider-side id for orders that originated outside the storefront (WhatsApp catalog order message id). */
+    provider_order_id: string | null;
+    /**
+     * Allowlisted attribution subset stamped at creation (utm_*, click IDs incl.
+     * ctwa_clid, ad referral fields). Conversation values win over contact values
+     * (last touch over first touch). Null when the order has no attributable source.
+     */
+    tracking: Record<string, unknown> | null;
+    customer_name: string;
+    customer_phone: string;
+    contact_uuid: string | null;
+    /** Inbox conversation opened by the order automation, when available. */
+    conversation_uuid: string | null;
+    items: StoreOrderItem[];
+    subtotal_cents: number;
+    shipping_name: string | null;
+    shipping_cents: number;
+    total_cents: number;
+    /** `catalog` = order from the native WhatsApp catalog (payment arranged in chat). */
+    payment_method: 'pix' | 'link' | 'on_delivery' | 'catalog';
+    notes: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export type StoreBatchResultItem = {
+    index: number;
+    status: 'created' | 'updated';
+    uuid: string;
+} | {
+    index: number;
+    status: 'error';
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export interface StoreBatchResult {
+    data: StoreBatchResultItem[];
+    meta: {
+        created: number;
+        updated: number;
+        failed: number;
+    };
+}
+export type WebhookEventType = 'message.received' | 'message.status.updated' | 'conversation.created' | 'conversation.updated' | 'flow.execution.updated' | 'order.created' | 'webhook.test';
 /**
  * Allowlisted attribution subset of the contact's and conversation's custom
  * fields. Conversation values win over contact values (last touch over first
@@ -200,6 +366,24 @@ export interface FlowExecutionUpdatedData {
         message: string | null;
     } | null;
 }
+/** A store order was created — storefront checkout or native WhatsApp catalog. */
+export interface OrderCreatedData extends WebhookContactRefs {
+    order_uuid: string;
+    ref: string;
+    status: string;
+    source: StoreOrderSource;
+    customer_name: string;
+    customer_phone: string;
+    contact_uuid: string | null;
+    items: StoreOrderItem[];
+    subtotal_cents: number;
+    shipping_name: string | null;
+    shipping_cents: number;
+    total_cents: number;
+    payment_method: string;
+    notes: string | null;
+    created_at: string | null;
+}
 export interface WebhookTestData {
     integration_uuid: string;
     message: string;
@@ -217,7 +401,8 @@ export type MessageStatusUpdatedEvent = WebhookEnvelope<'message.status.updated'
 export type ConversationCreatedEvent = WebhookEnvelope<'conversation.created', ConversationCreatedData>;
 export type ConversationUpdatedEvent = WebhookEnvelope<'conversation.updated', ConversationUpdatedData>;
 export type FlowExecutionUpdatedEvent = WebhookEnvelope<'flow.execution.updated', FlowExecutionUpdatedData>;
+export type OrderCreatedEvent = WebhookEnvelope<'order.created', OrderCreatedData>;
 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 type WazapiWebhookEvent = MessageReceivedEvent | MessageStatusUpdatedEvent | ConversationCreatedEvent | ConversationUpdatedEvent | FlowExecutionUpdatedEvent | OrderCreatedEvent | WebhookTestEvent;
 export {};

package/package.json

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