@spokpay/chat 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,209 @@
+import type { SpokPayChatOptions, CreateConversationOptions, Conversation, GetConversationOptions, SendMessageOptions, Message, ListMessagesOptions, CloseConversationOptions, GetUploadUrlOptions, VerifyWebhookOptions } from "./types.js";
+/**
+ * SpokPay Chat SDK client.
+ *
+ * Provides methods for creating conversations, sending messages, and
+ * receiving staff replies via webhooks. Zero dependencies — uses native
+ * `fetch` and Web Crypto API.
+ *
+ * @example Basic setup
+ * ```ts
+ * import { SpokPayChat } from "@spokpay/chat";
+ *
+ * const chat = new SpokPayChat({
+ *   apiKey: "spk_live_abc123...",
+ *   baseUrl: "https://your-deployment.convex.site",
+ * });
+ * ```
+ *
+ * @example Create a conversation and send a message
+ * ```ts
+ * const conv = await chat.conversations.create({
+ *   type: "order_support",
+ *   customer: { externalId: "cust_123", name: "João" },
+ *   subject: "Issue with my order",
+ * });
+ *
+ * await chat.conversations.sendMessage({
+ *   conversationId: conv.id,
+ *   content: "When will my order arrive?",
+ * });
+ * ```
+ *
+ * @example Receive staff replies via webhook
+ * ```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!,
+ * });
+ *
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+export declare class SpokPayChat {
+    private readonly apiKey;
+    private readonly baseUrl;
+    /**
+     * Client for managing conversations and messages.
+     */
+    readonly conversations: ConversationsClient;
+    constructor(options: SpokPayChatOptions);
+    /**
+     * Verify a webhook signature to ensure the request came from SpokPay.
+     *
+     * Uses HMAC-SHA256 with constant-time comparison to prevent timing attacks.
+     * Works in all JavaScript runtimes: Node.js 18+, Deno, Cloudflare Workers,
+     * Vercel Edge, and Convex.
+     *
+     * @param options - The raw payload, signature header, and your webhook secret.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * const isValid = await SpokPayChat.verifyWebhookSignature({
+     *   payload: rawBody,
+     *   signature: req.headers.get("x-spokpay-signature")!,
+     *   secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+     * });
+     * ```
+     */
+    static verifyWebhookSignature(options: VerifyWebhookOptions): Promise<boolean>;
+}
+declare class ConversationsClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl: string);
+    /**
+     * Create a new conversation.
+     *
+     * @param options - Conversation details (type, customer, subject, etc.).
+     * @returns The created conversation.
+     * @throws {@link SpokPayChatApiError} if the API returns an error.
+     *
+     * @example
+     * ```ts
+     * const conv = await chat.conversations.create({
+     *   type: "order_support",
+     *   externalId: "ticket_123",
+     *   customer: { externalId: "cust_abc", name: "João" },
+     *   subject: "Order issue",
+     *   metadata: { orderId: "order_456" },
+     * });
+     * ```
+     */
+    create(options: CreateConversationOptions): Promise<Conversation>;
+    /**
+     * Get a conversation by SpokPay ID or your external ID.
+     *
+     * @param options - Lookup criteria (SpokPay ID or external ID).
+     * @returns The conversation object.
+     * @throws {@link SpokPayChatApiError} with status 404 if not found.
+     *
+     * @example
+     * ```ts
+     * const conv = await chat.conversations.get({ externalId: "ticket_123" });
+     * ```
+     */
+    get(options: GetConversationOptions): Promise<Conversation>;
+    /**
+     * Send a message from a customer.
+     *
+     * @param options - Message details (conversation, content, author info).
+     * @returns The created message.
+     * @throws {@link SpokPayChatApiError} if the conversation is closed or not found.
+     *
+     * @example
+     * ```ts
+     * const msg = await chat.conversations.sendMessage({
+     *   conversationId: conv.id,
+     *   content: "When will my order arrive?",
+     *   authorExternalId: "cust_abc",
+     *   authorDisplayName: "João",
+     * });
+     * ```
+     */
+    sendMessage(options: SendMessageOptions): Promise<{
+        id: string;
+        conversationId: string;
+        content: string;
+        createdAt: number;
+    }>;
+    /**
+     * List messages in a conversation.
+     *
+     * @param options - Conversation ID/externalId and pagination options.
+     * @returns Array of messages, newest first.
+     *
+     * @example
+     * ```ts
+     * const { messages } = await chat.conversations.listMessages({
+     *   conversationId: conv.id,
+     *   limit: 20,
+     * });
+     * ```
+     */
+    listMessages(options: ListMessagesOptions): Promise<{
+        messages: Message[];
+    }>;
+    /**
+     * Close a conversation.
+     *
+     * @param options - The conversation ID to close.
+     * @returns Confirmation with the closed conversation ID and status.
+     * @throws {@link SpokPayChatApiError} if the conversation is already closed or not found.
+     *
+     * @example
+     * ```ts
+     * await chat.conversations.close({ id: conv.id });
+     * ```
+     */
+    close(options: CloseConversationOptions): Promise<{
+        id: string;
+        status: "closed";
+    }>;
+    /**
+     * Get a storage upload URL for file attachments.
+     *
+     * Upload your file to the returned URL with a PUT request, then include
+     * the resulting `storageId` in your message attachments.
+     *
+     * @param options - The conversation ID.
+     * @returns An upload URL.
+     *
+     * @example
+     * ```ts
+     * const { uploadUrl } = await chat.conversations.getUploadUrl({
+     *   conversationId: conv.id,
+     * });
+     *
+     * // Upload the file
+     * const res = await fetch(uploadUrl, {
+     *   method: "POST",
+     *   headers: { "Content-Type": file.type },
+     *   body: file,
+     * });
+     * const { storageId } = await res.json();
+     *
+     * // Send message with attachment
+     * await chat.conversations.sendMessage({
+     *   conversationId: conv.id,
+     *   content: "Here is the screenshot",
+     *   attachments: [{ storageId, filename: "screenshot.png", contentType: "image/png" }],
+     * });
+     * ```
+     */
+    getUploadUrl(options: GetUploadUrlOptions): Promise<{
+        uploadUrl: string;
+    }>;
+    private request;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,300 @@
+import { SpokPayChatApiError } from "./types.js";
+const DEFAULT_BASE_URL = "https://your-convex-deployment.convex.site";
+/**
+ * SpokPay Chat SDK client.
+ *
+ * Provides methods for creating conversations, sending messages, and
+ * receiving staff replies via webhooks. Zero dependencies — uses native
+ * `fetch` and Web Crypto API.
+ *
+ * @example Basic setup
+ * ```ts
+ * import { SpokPayChat } from "@spokpay/chat";
+ *
+ * const chat = new SpokPayChat({
+ *   apiKey: "spk_live_abc123...",
+ *   baseUrl: "https://your-deployment.convex.site",
+ * });
+ * ```
+ *
+ * @example Create a conversation and send a message
+ * ```ts
+ * const conv = await chat.conversations.create({
+ *   type: "order_support",
+ *   customer: { externalId: "cust_123", name: "João" },
+ *   subject: "Issue with my order",
+ * });
+ *
+ * await chat.conversations.sendMessage({
+ *   conversationId: conv.id,
+ *   content: "When will my order arrive?",
+ * });
+ * ```
+ *
+ * @example Receive staff replies via webhook
+ * ```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!,
+ * });
+ *
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+export class SpokPayChat {
+    apiKey;
+    baseUrl;
+    /**
+     * Client for managing conversations and messages.
+     */
+    conversations;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.conversations = new ConversationsClient(this.apiKey, this.baseUrl);
+    }
+    /**
+     * Verify a webhook signature to ensure the request came from SpokPay.
+     *
+     * Uses HMAC-SHA256 with constant-time comparison to prevent timing attacks.
+     * Works in all JavaScript runtimes: Node.js 18+, Deno, Cloudflare Workers,
+     * Vercel Edge, and Convex.
+     *
+     * @param options - The raw payload, signature header, and your webhook secret.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * const isValid = await SpokPayChat.verifyWebhookSignature({
+     *   payload: rawBody,
+     *   signature: req.headers.get("x-spokpay-signature")!,
+     *   secret: process.env.SPOKPAY_WEBHOOK_SECRET!,
+     * });
+     * ```
+     */
+    static async verifyWebhookSignature(options) {
+        const { payload, signature, secret } = options;
+        if (!signature.startsWith("sha256="))
+            return false;
+        const expectedHex = signature.slice(7);
+        const encoder = new TextEncoder();
+        const key = await globalThis.crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        const signatureBuffer = await globalThis.crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+        const computedHex = Array.from(new Uint8Array(signatureBuffer))
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+        // Constant-time comparison
+        if (computedHex.length !== expectedHex.length)
+            return false;
+        let result = 0;
+        for (let i = 0; i < computedHex.length; i++) {
+            result |= computedHex.charCodeAt(i) ^ expectedHex.charCodeAt(i);
+        }
+        return result === 0;
+    }
+}
+class ConversationsClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    /**
+     * Create a new conversation.
+     *
+     * @param options - Conversation details (type, customer, subject, etc.).
+     * @returns The created conversation.
+     * @throws {@link SpokPayChatApiError} if the API returns an error.
+     *
+     * @example
+     * ```ts
+     * const conv = await chat.conversations.create({
+     *   type: "order_support",
+     *   externalId: "ticket_123",
+     *   customer: { externalId: "cust_abc", name: "João" },
+     *   subject: "Order issue",
+     *   metadata: { orderId: "order_456" },
+     * });
+     * ```
+     */
+    async create(options) {
+        const body = {
+            type: options.type,
+        };
+        if (options.externalId)
+            body.externalId = options.externalId;
+        if (options.subject)
+            body.subject = options.subject;
+        if (options.chargeId)
+            body.chargeId = options.chargeId;
+        if (options.customer)
+            body.customer = options.customer;
+        if (options.metadata)
+            body.metadata = options.metadata;
+        return this.request("/v1/conversations", body);
+    }
+    /**
+     * Get a conversation by SpokPay ID or your external ID.
+     *
+     * @param options - Lookup criteria (SpokPay ID or external ID).
+     * @returns The conversation object.
+     * @throws {@link SpokPayChatApiError} with status 404 if not found.
+     *
+     * @example
+     * ```ts
+     * const conv = await chat.conversations.get({ externalId: "ticket_123" });
+     * ```
+     */
+    async get(options) {
+        if (!options.id && !options.externalId) {
+            throw new Error("Either id or externalId is required");
+        }
+        const body = {};
+        if (options.id)
+            body.id = options.id;
+        if (options.externalId)
+            body.externalId = options.externalId;
+        return this.request("/v1/conversations/get", body);
+    }
+    /**
+     * Send a message from a customer.
+     *
+     * @param options - Message details (conversation, content, author info).
+     * @returns The created message.
+     * @throws {@link SpokPayChatApiError} if the conversation is closed or not found.
+     *
+     * @example
+     * ```ts
+     * const msg = await chat.conversations.sendMessage({
+     *   conversationId: conv.id,
+     *   content: "When will my order arrive?",
+     *   authorExternalId: "cust_abc",
+     *   authorDisplayName: "João",
+     * });
+     * ```
+     */
+    async sendMessage(options) {
+        if (!options.conversationId && !options.externalId) {
+            throw new Error("Either conversationId or externalId is required");
+        }
+        const body = {
+            content: options.content,
+        };
+        if (options.conversationId)
+            body.conversationId = options.conversationId;
+        if (options.externalId)
+            body.externalId = options.externalId;
+        if (options.authorExternalId)
+            body.authorExternalId = options.authorExternalId;
+        if (options.authorDisplayName)
+            body.authorDisplayName = options.authorDisplayName;
+        if (options.attachments)
+            body.attachments = options.attachments;
+        return this.request("/v1/conversations/messages", body);
+    }
+    /**
+     * List messages in a conversation.
+     *
+     * @param options - Conversation ID/externalId and pagination options.
+     * @returns Array of messages, newest first.
+     *
+     * @example
+     * ```ts
+     * const { messages } = await chat.conversations.listMessages({
+     *   conversationId: conv.id,
+     *   limit: 20,
+     * });
+     * ```
+     */
+    async listMessages(options) {
+        if (!options.conversationId && !options.externalId) {
+            throw new Error("Either conversationId or externalId is required");
+        }
+        const body = {};
+        if (options.conversationId)
+            body.conversationId = options.conversationId;
+        if (options.externalId)
+            body.externalId = options.externalId;
+        if (options.limit !== undefined)
+            body.limit = options.limit;
+        if (options.cursor !== undefined)
+            body.cursor = options.cursor;
+        return this.request("/v1/conversations/messages/list", body);
+    }
+    /**
+     * Close a conversation.
+     *
+     * @param options - The conversation ID to close.
+     * @returns Confirmation with the closed conversation ID and status.
+     * @throws {@link SpokPayChatApiError} if the conversation is already closed or not found.
+     *
+     * @example
+     * ```ts
+     * await chat.conversations.close({ id: conv.id });
+     * ```
+     */
+    async close(options) {
+        return this.request("/v1/conversations/close", { id: options.id });
+    }
+    /**
+     * Get a storage upload URL for file attachments.
+     *
+     * Upload your file to the returned URL with a PUT request, then include
+     * the resulting `storageId` in your message attachments.
+     *
+     * @param options - The conversation ID.
+     * @returns An upload URL.
+     *
+     * @example
+     * ```ts
+     * const { uploadUrl } = await chat.conversations.getUploadUrl({
+     *   conversationId: conv.id,
+     * });
+     *
+     * // Upload the file
+     * const res = await fetch(uploadUrl, {
+     *   method: "POST",
+     *   headers: { "Content-Type": file.type },
+     *   body: file,
+     * });
+     * const { storageId } = await res.json();
+     *
+     * // Send message with attachment
+     * await chat.conversations.sendMessage({
+     *   conversationId: conv.id,
+     *   content: "Here is the screenshot",
+     *   attachments: [{ storageId, filename: "screenshot.png", contentType: "image/png" }],
+     * });
+     * ```
+     */
+    async getUploadUrl(options) {
+        return this.request("/v1/conversations/upload-url", {
+            conversationId: options.conversationId,
+        });
+    }
+    async request(path, body) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            throw new SpokPayChatApiError(data.error ?? "Request failed", response.status, data);
+        }
+        return data;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +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";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SpokPayChat } from "./client.js";
+export { SpokPayChatApiError } from "./types.js";

package/dist/types.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Configuration options for the {@link SpokPayChat} client.
+ *
+ * @example
+ * ```ts
+ * import { SpokPayChat } from "@spokpay/chat";
+ *
+ * const chat = new SpokPayChat({
+ *   apiKey: "spk_live_abc123...",
+ *   baseUrl: "https://your-deployment.convex.site",
+ * });
+ * ```
+ */
+export interface SpokPayChatOptions {
+    /**
+     * Your SpokPay API key.
+     * Generate keys from the Plugin page in your SpokPay store dashboard.
+     */
+    apiKey: string;
+    /**
+     * The base URL of your SpokPay Convex deployment.
+     * This is the HTTP Actions URL from your Convex dashboard (ends in `.convex.site`).
+     *
+     * @example "https://your-deployment.convex.site"
+     */
+    baseUrl?: string;
+}
+/**
+ * A conversation object returned by the SpokPay API.
+ */
+export interface Conversation {
+    /** Unique SpokPay conversation ID. */
+    id: string;
+    /** The type of conversation (e.g., `"order_support"`, `"billing"`, `"general"`). */
+    type: string;
+    /** Current status of the conversation. */
+    status: "open" | "closed";
+    /** The storefront that created this conversation. */
+    storefront: "discord" | "sdk" | "dashboard";
+    /** 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;
+    /** Number of messages in the conversation. */
+    messageCount: number;
+    /** Unix timestamp (ms) of the last activity. */
+    lastActivityAt: number;
+    /** Unix timestamp (ms) when the conversation was created. */
+    createdAt: number;
+    /** Unix timestamp (ms) when the conversation was closed, if closed. */
+    closedAt?: number;
+}
+/**
+ * Options for creating a new conversation.
+ *
+ * @example
+ * ```ts
+ * const conv = await chat.conversations.create({
+ *   type: "order_support",
+ *   externalId: "ticket_123",
+ *   subject: "Issue with my order",
+ *   customer: { externalId: "cust_abc", name: "João" },
+ *   metadata: { orderId: "order_456" },
+ * });
+ * ```
+ */
+export interface CreateConversationOptions {
+    /** The type of conversation. Use any string that categorizes this conversation. */
+    type: string;
+    /**
+     * Your own unique identifier for this conversation.
+     * Must be unique per store. Useful for correlating with your system.
+     */
+    externalId?: string;
+    /** Conversation subject or title. */
+    subject?: string;
+    /** SpokPay charge ID to link to this conversation. */
+    chargeId?: string;
+    /** Customer information. If `externalId` is provided, the customer will be created or linked. */
+    customer?: {
+        /** Your own identifier for this customer. */
+        externalId?: string;
+        /** Customer's display name. */
+        name?: string;
+        /** Customer's email address. */
+        email?: string;
+    };
+    /**
+     * Arbitrary metadata to attach to the conversation.
+     * Must be less than 4KB when serialized.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for retrieving a conversation.
+ * Provide either `id` or `externalId`.
+ */
+export interface GetConversationOptions {
+    /** SpokPay conversation ID. */
+    id?: string;
+    /** Your external ID provided when the conversation was created. */
+    externalId?: string;
+}
+/**
+ * A message in a conversation.
+ */
+export interface Message {
+    /** Unique message ID. */
+    id: string;
+    /** The conversation this message belongs to. */
+    conversationId: string;
+    /** Message text content. */
+    content: string;
+    /** Who sent this message. */
+    authorType: "customer" | "staff" | "bot" | "ai";
+    /** Display name of the author. */
+    authorDisplayName?: string;
+    /** Your external ID for the author (for customer messages). */
+    authorExternalId?: string;
+    /** Whether this is a system-generated message. */
+    isSystemMessage: boolean;
+    /** Unix timestamp (ms) when the message was sent. */
+    createdAt: number;
+    /** Unix timestamp (ms) when the message was last edited. */
+    editedAt?: number;
+}
+/**
+ * Options for sending a message in a conversation.
+ *
+ * @example
+ * ```ts
+ * const msg = await chat.conversations.sendMessage({
+ *   conversationId: conv.id,
+ *   content: "When will my order arrive?",
+ *   authorExternalId: "cust_abc",
+ *   authorDisplayName: "João",
+ * });
+ * ```
+ */
+export interface SendMessageOptions {
+    /** SpokPay conversation ID. */
+    conversationId?: string;
+    /** Your external ID for the conversation (alternative to conversationId). */
+    externalId?: string;
+    /** Message text content. */
+    content: string;
+    /** Your external ID for the message author. */
+    authorExternalId?: string;
+    /** Display name for the message author. */
+    authorDisplayName?: string;
+    /** File attachments. Use `getUploadUrl()` to upload files first. */
+    attachments?: MessageAttachment[];
+}
+/**
+ * A file attachment on a message.
+ */
+export interface MessageAttachment {
+    /** Convex storage ID (from uploading via the upload URL). */
+    storageId?: string;
+    /** Direct URL to the file. */
+    url?: string;
+    /** Filename. */
+    filename: string;
+    /** MIME content type. */
+    contentType?: string;
+    /** File size in bytes. */
+    size?: number;
+}
+/**
+ * Options for listing messages in a conversation.
+ */
+export interface ListMessagesOptions {
+    /** SpokPay conversation ID. */
+    conversationId?: string;
+    /** Your external ID for the conversation (alternative to conversationId). */
+    externalId?: string;
+    /** Maximum number of messages to return. Defaults to 50. */
+    limit?: number;
+    /** Cursor for pagination — pass `createdAt` of the last message to get older messages. */
+    cursor?: number;
+}
+/**
+ * Options for closing a conversation.
+ */
+export interface CloseConversationOptions {
+    /** SpokPay conversation ID. */
+    id: string;
+}
+/**
+ * Options for getting an upload URL.
+ */
+export interface GetUploadUrlOptions {
+    /** SpokPay conversation ID. */
+    conversationId: string;
+}
+/**
+ * Webhook event payload sent by SpokPay for chat events.
+ *
+ * @example
+ * ```ts
+ * const event: ChatWebhookPayload = JSON.parse(body);
+ *
+ * if (event.type === "message.created") {
+ *   // A staff member replied to the conversation
+ *   console.log(event.data.content);
+ *   console.log(event.data.authorType); // "staff"
+ * }
+ *
+ * if (event.type === "conversation.closed") {
+ *   // The conversation was closed by staff
+ *   console.log(event.data.id);
+ * }
+ * ```
+ */
+export interface ChatWebhookPayload {
+    /**
+     * The event type.
+     *
+     * - `"message.created"` — A new message was sent (staff reply).
+     * - `"message.updated"` — A message was edited.
+     * - `"message.deleted"` — A message was deleted.
+     * - `"conversation.closed"` — The conversation was closed.
+     */
+    type: "message.created" | "message.updated" | "message.deleted" | "conversation.closed";
+    /** Event data. Shape depends on the event type. */
+    data: WebhookMessageData | WebhookConversationData;
+    /** Unix timestamp (ms) when the event was created. */
+    createdAt: number;
+}
+/** Data included in message webhook events. */
+export interface WebhookMessageData {
+    id: string;
+    conversationId: string;
+    content: string;
+    authorType: string;
+    authorDisplayName?: string;
+    authorExternalId?: string;
+    attachments: Array<{
+        filename: string;
+        contentType?: string;
+        size?: number;
+        url?: string;
+    }>;
+    createdAt: number;
+}
+/** Data included in conversation webhook events. */
+export interface WebhookConversationData {
+    id: string;
+    type: string;
+    status: string;
+    externalId?: string;
+    subject?: string;
+    metadata?: string;
+    createdAt: number;
+    closedAt?: number;
+}
+/**
+ * Options for verifying a webhook signature.
+ *
+ * @see {@link SpokPayChat.verifyWebhookSignature}
+ */
+export interface VerifyWebhookOptions {
+    /** The raw request body as a string (do NOT parse it before verifying). */
+    payload: string;
+    /** The `x-spokpay-signature` header value from the webhook request. */
+    signature: string;
+    /** Your webhook endpoint secret from the SpokPay dashboard. */
+    secret: string;
+}
+/**
+ * Error thrown when the SpokPay API returns a non-2xx response.
+ */
+export declare class SpokPayChatApiError extends Error {
+    /** HTTP status code from the API response. */
+    readonly statusCode: number;
+    /** Raw response body from the API. */
+    readonly body: unknown;
+    constructor(message: string, statusCode: number, body?: unknown);
+}

package/dist/types.js

@@ -0,0 +1,15 @@
+/**
+ * Error thrown when the SpokPay API returns a non-2xx response.
+ */
+export class SpokPayChatApiError extends Error {
+    /** HTTP status code from the API response. */
+    statusCode;
+    /** Raw response body from the API. */
+    body;
+    constructor(message, statusCode, body) {
+        super(message);
+        this.name = "SpokPayChatApiError";
+        this.statusCode = statusCode;
+        this.body = body;
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@spokpay/chat",
+  "version": "0.1.0",
+  "description": "SpokPay Chat SDK — add live chat conversations to your app",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "spokpay",
+    "chat",
+    "conversations",
+    "support",
+    "sdk"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  }
+}