@spokpay/chat 0.1.0 → 0.2.0

package/dist/client.d.ts

@@ -30,22 +30,41 @@ import type { SpokPayChatOptions, CreateConversationOptions, Conversation, GetCo
  * });
  * ```
  *
- * @example Receive staff replies via webhook
+ * @example Convex integration — reactive chat with webhooks
  * ```ts
- * // In your webhook handler
- * const body = await req.text();
- * const isValid = await SpokPayChat.verifyWebhookSignature({
- *   payload: body,
- *   signature: req.headers.get("x-spokpay-signature")!,
- *   secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+ * // convex/http.ts — Receive SpokPay chat webhooks
+ * import { SpokPayChat, type ChatWebhookPayload } from "@spokpay/chat";
+ *
+ * http.route({
+ *   path: "/webhooks/spokpay-chat",
+ *   method: "POST",
+ *   handler: httpAction(async (ctx, req) => {
+ *     const body = await req.text();
+ *     const signature = req.headers.get("x-spokpay-signature")!;
+ *
+ *     const isValid = await SpokPayChat.verifyWebhookSignature({
+ *       payload: body,
+ *       signature,
+ *       secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+ *     });
+ *     if (!isValid) return new Response("Invalid signature", { status: 401 });
+ *
+ *     const event: ChatWebhookPayload = JSON.parse(body);
+ *     if (event.type === "message.created") {
+ *       await ctx.runMutation(internal.chat.handleStaffReply, {
+ *         conversationId: event.data.conversationId,
+ *         content: event.data.content,
+ *         authorName: event.data.authorDisplayName,
+ *       });
+ *     }
+ *     return new Response("OK");
+ *   }),
  * });
  *
- * if (isValid) {
- *   const event = JSON.parse(body);
- *   if (event.type === "message.created") {
- *     // Staff replied — show the message to the customer
- *     displayMessage(event.data.content, event.data.authorDisplayName);
- *   }
+ * // React component — auto-updates when webhook triggers the mutation
+ * function ChatPage({ conversationId }: { conversationId: string }) {
+ *   const messages = useQuery(api.chat.listMessages, { conversationId });
+ *   // messages reactively updates when staff replies via the webhook
  * }
  * ```
  */
@@ -54,8 +73,45 @@ export declare class SpokPayChat {
     private readonly baseUrl;
     /**
      * Client for managing conversations and messages.
+     *
+     * @example
+     * ```ts
+     * // Create a conversation
+     * const conv = await chat.conversations.create({
+     *   type: "order_support",
+     *   customer: { externalId: "cust_123", name: "João" },
+     *   subject: "Help with my order",
+     * });
+     *
+     * // Send a message
+     * await chat.conversations.sendMessage({
+     *   conversationId: conv.id,
+     *   content: "When will my order arrive?",
+     * });
+     *
+     * // List messages
+     * const { messages } = await chat.conversations.listMessages({
+     *   conversationId: conv.id,
+     * });
+     *
+     * // Close when resolved
+     * await chat.conversations.close({ id: conv.id });
+     * ```
      */
     readonly conversations: ConversationsClient;
+    /**
+     * Creates a new SpokPay Chat client.
+     *
+     * @param options - Client configuration (API key and base URL).
+     *
+     * @example
+     * ```ts
+     * const chat = new SpokPayChat({
+     *   apiKey: process.env.SPOKPAY_API_KEY!,
+     *   baseUrl: process.env.SPOKPAY_BASE_URL!,
+     * });
+     * ```
+     */
     constructor(options: SpokPayChatOptions);
     /**
      * Verify a webhook signature to ensure the request came from SpokPay.
@@ -64,15 +120,40 @@ export declare class SpokPayChat {
      * Works in all JavaScript runtimes: Node.js 18+, Deno, Cloudflare Workers,
      * Vercel Edge, and Convex.
      *
+     * **Important:** Always verify signatures before processing webhook payloads.
+     * Use the raw request body string — do not parse it before verification.
+     *
      * @param options - The raw payload, signature header, and your webhook secret.
      * @returns `true` if the signature is valid, `false` otherwise.
      *
-     * @example
+     * @example Node.js / Express
+     * ```ts
+     * app.post("/webhooks/spokpay-chat", express.raw({ type: "*\/*" }), async (req, res) => {
+     *   const isValid = await SpokPayChat.verifyWebhookSignature({
+     *     payload: req.body.toString(),
+     *     signature: req.headers["x-spokpay-signature"] as string,
+     *     secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+     *   });
+     *
+     *   if (!isValid) return res.status(401).send("Invalid signature");
+     *
+     *   const event = JSON.parse(req.body.toString());
+     *   // Handle event...
+     *   res.sendStatus(200);
+     * });
+     * ```
+     *
+     * @example Convex httpAction
      * ```ts
-     * const isValid = await SpokPayChat.verifyWebhookSignature({
-     *   payload: rawBody,
-     *   signature: req.headers.get("x-spokpay-signature")!,
-     *   secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+     * const handler = httpAction(async (ctx, req) => {
+     *   const body = await req.text();
+     *   const isValid = await SpokPayChat.verifyWebhookSignature({
+     *     payload: body,
+     *     signature: req.headers.get("x-spokpay-signature")!,
+     *     secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+     *   });
+     *   if (!isValid) return new Response("Invalid", { status: 401 });
+     *   // Process the webhook...
      * });
      * ```
      */

package/dist/client.js

@@ -31,22 +31,41 @@ const DEFAULT_BASE_URL = "https://your-convex-deployment.convex.site";
  * });
  * ```
  *
- * @example Receive staff replies via webhook
+ * @example Convex integration — reactive chat with webhooks
  * ```ts
- * // In your webhook handler
- * const body = await req.text();
- * const isValid = await SpokPayChat.verifyWebhookSignature({
- *   payload: body,
- *   signature: req.headers.get("x-spokpay-signature")!,
- *   secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+ * // convex/http.ts — Receive SpokPay chat webhooks
+ * import { SpokPayChat, type ChatWebhookPayload } from "@spokpay/chat";
+ *
+ * http.route({
+ *   path: "/webhooks/spokpay-chat",
+ *   method: "POST",
+ *   handler: httpAction(async (ctx, req) => {
+ *     const body = await req.text();
+ *     const signature = req.headers.get("x-spokpay-signature")!;
+ *
+ *     const isValid = await SpokPayChat.verifyWebhookSignature({
+ *       payload: body,
+ *       signature,
+ *       secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+ *     });
+ *     if (!isValid) return new Response("Invalid signature", { status: 401 });
+ *
+ *     const event: ChatWebhookPayload = JSON.parse(body);
+ *     if (event.type === "message.created") {
+ *       await ctx.runMutation(internal.chat.handleStaffReply, {
+ *         conversationId: event.data.conversationId,
+ *         content: event.data.content,
+ *         authorName: event.data.authorDisplayName,
+ *       });
+ *     }
+ *     return new Response("OK");
+ *   }),
  * });
  *
- * if (isValid) {
- *   const event = JSON.parse(body);
- *   if (event.type === "message.created") {
- *     // Staff replied — show the message to the customer
- *     displayMessage(event.data.content, event.data.authorDisplayName);
- *   }
+ * // React component — auto-updates when webhook triggers the mutation
+ * function ChatPage({ conversationId }: { conversationId: string }) {
+ *   const messages = useQuery(api.chat.listMessages, { conversationId });
+ *   // messages reactively updates when staff replies via the webhook
  * }
  * ```
  */
@@ -55,8 +74,45 @@ export class SpokPayChat {
     baseUrl;
     /**
      * Client for managing conversations and messages.
+     *
+     * @example
+     * ```ts
+     * // Create a conversation
+     * const conv = await chat.conversations.create({
+     *   type: "order_support",
+     *   customer: { externalId: "cust_123", name: "João" },
+     *   subject: "Help with my order",
+     * });
+     *
+     * // Send a message
+     * await chat.conversations.sendMessage({
+     *   conversationId: conv.id,
+     *   content: "When will my order arrive?",
+     * });
+     *
+     * // List messages
+     * const { messages } = await chat.conversations.listMessages({
+     *   conversationId: conv.id,
+     * });
+     *
+     * // Close when resolved
+     * await chat.conversations.close({ id: conv.id });
+     * ```
      */
     conversations;
+    /**
+     * Creates a new SpokPay Chat client.
+     *
+     * @param options - Client configuration (API key and base URL).
+     *
+     * @example
+     * ```ts
+     * const chat = new SpokPayChat({
+     *   apiKey: process.env.SPOKPAY_API_KEY!,
+     *   baseUrl: process.env.SPOKPAY_BASE_URL!,
+     * });
+     * ```
+     */
     constructor(options) {
         this.apiKey = options.apiKey;
         this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
@@ -69,15 +125,40 @@ export class SpokPayChat {
      * Works in all JavaScript runtimes: Node.js 18+, Deno, Cloudflare Workers,
      * Vercel Edge, and Convex.
      *
+     * **Important:** Always verify signatures before processing webhook payloads.
+     * Use the raw request body string — do not parse it before verification.
+     *
      * @param options - The raw payload, signature header, and your webhook secret.
      * @returns `true` if the signature is valid, `false` otherwise.
      *
-     * @example
+     * @example Node.js / Express
+     * ```ts
+     * app.post("/webhooks/spokpay-chat", express.raw({ type: "*\/*" }), async (req, res) => {
+     *   const isValid = await SpokPayChat.verifyWebhookSignature({
+     *     payload: req.body.toString(),
+     *     signature: req.headers["x-spokpay-signature"] as string,
+     *     secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+     *   });
+     *
+     *   if (!isValid) return res.status(401).send("Invalid signature");
+     *
+     *   const event = JSON.parse(req.body.toString());
+     *   // Handle event...
+     *   res.sendStatus(200);
+     * });
+     * ```
+     *
+     * @example Convex httpAction
      * ```ts
-     * const isValid = await SpokPayChat.verifyWebhookSignature({
-     *   payload: rawBody,
-     *   signature: req.headers.get("x-spokpay-signature")!,
-     *   secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+     * const handler = httpAction(async (ctx, req) => {
+     *   const body = await req.text();
+     *   const isValid = await SpokPayChat.verifyWebhookSignature({
+     *     payload: body,
+     *     signature: req.headers.get("x-spokpay-signature")!,
+     *     secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+     *   });
+     *   if (!isValid) return new Response("Invalid", { status: 401 });
+     *   // Process the webhook...
      * });
      * ```
      */

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { SpokPayChat } from "./client.js";
 export { SpokPayChatApiError } from "./types.js";
-export type { SpokPayChatOptions, Conversation, CreateConversationOptions, GetConversationOptions, Message, SendMessageOptions, MessageAttachment, ListMessagesOptions, CloseConversationOptions, GetUploadUrlOptions, ChatWebhookPayload, WebhookMessageData, WebhookConversationData, VerifyWebhookOptions, } from "./types.js";
+export type { SpokPayChatOptions, Conversation, CreateConversationOptions, GetConversationOptions, Message, SendMessageOptions, MessageAttachment, ListMessagesOptions, CloseConversationOptions, GetUploadUrlOptions, ChatWebhookPayload, WebhookMessageData, WebhookConversationData, WebhookItemDeliveredData, WebhookItemRefundedData, VerifyWebhookOptions, } from "./types.js";

package/dist/types.d.ts

@@ -1,19 +1,33 @@
 /**
  * Configuration options for the {@link SpokPayChat} client.
  *
+ * The API key prefix determines the environment:
+ * - `spk_live_*` — Production (real conversations routed to staff)
+ * - `spk_test_*` — Development/Sandbox (test conversations, no notifications)
+ *
  * @example
  * ```ts
  * import { SpokPayChat } from "@spokpay/chat";
  *
+ * // Production
  * const chat = new SpokPayChat({
  *   apiKey: "spk_live_abc123...",
  *   baseUrl: "https://your-deployment.convex.site",
  * });
+ *
+ * // Sandbox / Testing
+ * const chatTest = new SpokPayChat({
+ *   apiKey: "spk_test_abc123...",
+ *   baseUrl: "https://your-deployment.convex.site",
+ * });
  * ```
  */
 export interface SpokPayChatOptions {
     /**
      * Your SpokPay API key.
+     * - `spk_live_*` keys target **production** (real conversations routed to staff).
+     * - `spk_test_*` keys target **SpokPay sandbox** (test conversations, no notifications).
+     *
      * Generate keys from the Plugin page in your SpokPay store dashboard.
      */
     apiKey: string;
@@ -222,40 +236,163 @@ export interface ChatWebhookPayload {
      * - `"message.updated"` — A message was edited.
      * - `"message.deleted"` — A message was deleted.
      * - `"conversation.closed"` — The conversation was closed.
+     * - `"item.delivered"` — An order item was delivered by staff.
+     * - `"item.refunded"` — An order item was refunded by staff.
      */
-    type: "message.created" | "message.updated" | "message.deleted" | "conversation.closed";
+    type: "message.created" | "message.updated" | "message.deleted" | "conversation.closed" | "item.delivered" | "item.refunded";
     /** Event data. Shape depends on the event type. */
-    data: WebhookMessageData | WebhookConversationData;
+    data: WebhookMessageData | WebhookConversationData | WebhookItemDeliveredData | WebhookItemRefundedData;
     /** Unix timestamp (ms) when the event was created. */
     createdAt: number;
 }
-/** Data included in message webhook events. */
+/**
+ * Data included in message webhook events (`message.created`, `message.updated`, `message.deleted`).
+ *
+ * @example
+ * ```ts
+ * const event: ChatWebhookPayload = JSON.parse(body);
+ * if (event.type === "message.created") {
+ *   const msg = event.data as WebhookMessageData;
+ *   console.log(`${msg.authorDisplayName}: ${msg.content}`);
+ * }
+ * ```
+ */
 export interface WebhookMessageData {
+    /** Unique message ID. */
     id: string;
+    /** The conversation this message belongs to. */
     conversationId: string;
+    /** Message text content. */
     content: string;
+    /** Who sent this message (e.g., `"staff"`, `"ai"`, `"bot"`). */
     authorType: string;
+    /** Display name of the author. */
     authorDisplayName?: string;
+    /** Your external ID for the author, if provided. */
     authorExternalId?: string;
+    /** File attachments included with the message. */
     attachments: Array<{
+        /** Filename. */
         filename: string;
+        /** MIME content type. */
         contentType?: string;
+        /** File size in bytes. */
         size?: number;
+        /** Direct URL to the file. */
         url?: string;
     }>;
+    /** Unix timestamp (ms) when the message was sent. */
     createdAt: number;
 }
-/** Data included in conversation webhook events. */
+/**
+ * Data included in conversation webhook events (`conversation.closed`).
+ *
+ * @example
+ * ```ts
+ * const event: ChatWebhookPayload = JSON.parse(body);
+ * if (event.type === "conversation.closed") {
+ *   const conv = event.data as WebhookConversationData;
+ *   console.log(`Conversation ${conv.id} closed at ${new Date(conv.closedAt!)}`);
+ * }
+ * ```
+ */
 export interface WebhookConversationData {
+    /** Unique SpokPay conversation ID. */
     id: string;
+    /** The type of conversation (e.g., `"order_support"`, `"general"`). */
     type: string;
+    /** Current status of the conversation (e.g., `"closed"`). */
     status: string;
+    /** Your external ID, if provided when creating the conversation. */
     externalId?: string;
+    /** Conversation subject or title. */
     subject?: string;
+    /** Arbitrary metadata as a JSON string, if provided. */
     metadata?: string;
+    /** Unix timestamp (ms) when the conversation was created. */
     createdAt: number;
+    /** Unix timestamp (ms) when the conversation was closed. */
     closedAt?: number;
 }
+/**
+ * Data included in `item.delivered` webhook events.
+ *
+ * Fired when a staff member marks an order item as delivered from the SpokPay dashboard.
+ *
+ * @example
+ * ```ts
+ * const event: ChatWebhookPayload = JSON.parse(body);
+ * if (event.type === "item.delivered") {
+ *   const data = event.data as WebhookItemDeliveredData;
+ *   console.log(`${data.item.name} delivered by ${data.deliveredBy}`);
+ * }
+ * ```
+ */
+export interface WebhookItemDeliveredData {
+    /** SpokPay conversation ID. */
+    conversationId: string;
+    /** Your external ID for the conversation. */
+    externalId?: string;
+    /** The delivered item. */
+    item: {
+        /** Your external ID for this product (from charge items). */
+        externalId?: string;
+        /** Product name. */
+        name: string;
+        /** Quantity delivered. */
+        quantity: number;
+        /** Delivery proof image, if provided. */
+        deliveryProof?: {
+            /** Direct URL to the proof image. */
+            url: string;
+            /** Filename. */
+            filename: string;
+            /** MIME content type. */
+            contentType: string;
+        };
+    };
+    /** Display name of the staff member who delivered. */
+    deliveredBy: string;
+    /** Unix timestamp (ms) when the item was delivered. */
+    deliveredAt: number;
+}
+/**
+ * Data included in `item.refunded` webhook events.
+ *
+ * Fired when a staff member refunds an order item from the SpokPay dashboard.
+ *
+ * @example
+ * ```ts
+ * const event: ChatWebhookPayload = JSON.parse(body);
+ * if (event.type === "item.refunded") {
+ *   const data = event.data as WebhookItemRefundedData;
+ *   console.log(`${data.item.name} refunded: ${data.item.refundReason}`);
+ * }
+ * ```
+ */
+export interface WebhookItemRefundedData {
+    /** SpokPay conversation ID. */
+    conversationId: string;
+    /** Your external ID for the conversation. */
+    externalId?: string;
+    /** The refunded item. */
+    item: {
+        /** Your external ID for this product (from charge items). */
+        externalId?: string;
+        /** Product name. */
+        name: string;
+        /** Quantity refunded. */
+        quantity: number;
+        /** Refund amount. */
+        refundAmount?: number;
+        /** Reason for the refund. */
+        refundReason?: string;
+    };
+    /** Display name of the staff member who processed the refund. */
+    refundedBy: string;
+    /** Unix timestamp (ms) when the item was refunded. */
+    refundedAt: number;
+}
 /**
  * Options for verifying a webhook signature.
  *
@@ -270,7 +407,22 @@ export interface VerifyWebhookOptions {
     secret: string;
 }
 /**
- * Error thrown when the SpokPay API returns a non-2xx response.
+ * Error thrown when the SpokPay Chat API returns a non-2xx response.
+ *
+ * @example
+ * ```ts
+ * import { SpokPayChatApiError } from "@spokpay/chat";
+ *
+ * try {
+ *   await chat.conversations.get({ id: "invalid_id" });
+ * } catch (error) {
+ *   if (error instanceof SpokPayChatApiError) {
+ *     console.error(error.message);    // "Conversation not found"
+ *     console.error(error.statusCode); // 404
+ *     console.error(error.body);       // Raw API response body
+ *   }
+ * }
+ * ```
  */
 export declare class SpokPayChatApiError extends Error {
     /** HTTP status code from the API response. */

package/dist/types.js

@@ -1,5 +1,20 @@
 /**
- * Error thrown when the SpokPay API returns a non-2xx response.
+ * Error thrown when the SpokPay Chat API returns a non-2xx response.
+ *
+ * @example
+ * ```ts
+ * import { SpokPayChatApiError } from "@spokpay/chat";
+ *
+ * try {
+ *   await chat.conversations.get({ id: "invalid_id" });
+ * } catch (error) {
+ *   if (error instanceof SpokPayChatApiError) {
+ *     console.error(error.message);    // "Conversation not found"
+ *     console.error(error.statusCode); // 404
+ *     console.error(error.body);       // Raw API response body
+ *   }
+ * }
+ * ```
  */
 export class SpokPayChatApiError extends Error {
     /** HTTP status code from the API response. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spokpay/chat",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SpokPay Chat SDK — add live chat conversations to your app",
   "type": "module",
   "main": "dist/index.js",