@wazapi/sdk 0.3.0 → 0.4.0

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/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;
 }
@@ -88,12 +88,38 @@ 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;
@@ -158,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
@@ -215,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;
@@ -232,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.3.0",
+  "version": "0.4.0",
   "description": "Official Node.js SDK for the Wazapi Public API v1",
   "license": "MIT",
   "type": "module",