@medalsocial/sdk 1.2.0 → 1.3.0

package/dist/src/index.d.mts

@@ -8,6 +8,25 @@ interface ClientConfig {
     timeout: number;
     userAgent: string;
 }
+/** Per-request options for write operations. */
+interface RequestOptions {
+    /**
+     * Idempotency key sent as the `Idempotency-Key` header. Retries with the
+     * same key return the original result instead of repeating the operation.
+     * Required by some endpoints for capability-scoped tokens (e.g. helpdesk
+     * replies, webhook creation).
+     */
+    idempotencyKey?: string;
+    /**
+     * Capability confirmation token sent as the `X-Capability-Confirmation`
+     * header. Required alongside `idempotencyKey` when a token granted a
+     * capability-style scope directly (e.g. `helpdesk.webhook.manage`) executes
+     * a confirmable write route. Obtain one from
+     * `POST /api/v1/capability-confirmations`. API keys with legacy scopes do
+     * not need it.
+     */
+    capabilityConfirmation?: string;
+}
 /**
  * Low-level HTTP client used by all resource classes.
  * Handles authentication, retries, timeout, and error parsing.
@@ -19,11 +38,12 @@ declare class BaseClient {
     /** Execute an authenticated GET request and return the parsed JSON body. */
     get<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;
     /** Execute an authenticated POST request with a JSON body. */
-    post<T>(path: string, body?: unknown): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
     /** Execute an authenticated PATCH request with a JSON body. */
-    patch<T>(path: string, body: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
     /** Execute an authenticated DELETE request. */
-    delete<T>(path: string): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    private writeHeaders;
     private buildUrl;
     private request;
 }
@@ -484,6 +504,122 @@ declare class Gdpr {
     }>;
 }
 
+/** Lifecycle status of a helpdesk conversation. */
+type ConversationStatus = "open" | "snoozed" | "closed";
+/** Who authored a helpdesk message. */
+type MessageAuthorType = "visitor" | "operator" | "ai" | "system";
+/** Kind of helpdesk message. `note` is operator-internal and never delivered to the customer. */
+type HelpdeskMessageType = "chat" | "email" | "note";
+/** A helpdesk conversation across any connected channel (widget, email, social DMs, …). */
+interface Conversation {
+    id: string;
+    /** Channel type, e.g. 'widget', 'instagram', 'messenger', 'whatsapp', 'email'. */
+    channel: string;
+    channel_connection_id: string | null;
+    status: ConversationStatus;
+    subject: string | null;
+    assignee_user_id: string | null;
+    contact_id: string | null;
+    visitor_name: string | null;
+    visitor_email: string | null;
+    external_conversation_id: string | null;
+    channel_account_id: string | null;
+    message_count: number;
+    unread_for_operator: number;
+    /** Unix timestamp in milliseconds. */
+    last_message_at: number;
+    last_message_preview: string | null;
+    last_message_author_type: MessageAuthorType | null;
+    /** Unix timestamp in milliseconds. */
+    created_at: number;
+    /** Unix timestamp in milliseconds. */
+    updated_at: number;
+}
+/** A single message inside a helpdesk conversation. */
+interface ConversationMessage {
+    id: string;
+    conversation_id: string;
+    author_type: MessageAuthorType;
+    message_type: HelpdeskMessageType;
+    author_user_id: string | null;
+    author_name: string | null;
+    body: string;
+    /** Unix timestamp in milliseconds. */
+    created_at: number;
+}
+/** Filters for listing/searching helpdesk conversations. */
+interface ListConversationsOptions extends PaginationOptions {
+    status?: ConversationStatus;
+    /** Only conversations assigned to this user. */
+    assignee_user_id?: string;
+    /** Match against visitor name/email. */
+    requester?: string;
+    /** Free-text search query. */
+    query?: string;
+    /** Only conversations on these channels (serialized as CSV). */
+    channels?: string[];
+}
+/** Input for updating a conversation's status and/or assignee. At least one field is required. */
+interface UpdateConversationInput {
+    status?: ConversationStatus;
+    /** User ID to assign, or `null` to unassign. */
+    assignee_user_id?: string | null;
+}
+/** Result of a conversation update. */
+interface ConversationUpdateResult {
+    id: string;
+    status: ConversationStatus;
+    assignee_user_id: string | null;
+}
+/** Input for sending an operator reply (or internal note) into a conversation. */
+interface CreateReplyInput {
+    conversation_id: string;
+    /** Message body (max 20,000 characters). */
+    body: string;
+    /** `note` = operator-internal note (not delivered to the customer). Default `chat`. */
+    message_type?: "chat" | "note";
+    /** Agent display name for bridged replies (shown in widget + inbox). */
+    author_name?: string;
+}
+/** Result returned after creating a reply (HTTP 201). */
+interface ReplyCreateResult {
+    id: string;
+    conversation_id: string;
+    status: string;
+}
+
+/** Browse and manage helpdesk conversations. */
+declare class HelpdeskConversations {
+    private client;
+    constructor(client: BaseClient);
+    /** List/search conversations with cursor-based pagination and optional filters. */
+    list(options?: ListConversationsOptions): Promise<PaginatedResponse<Conversation>>;
+    /** Get a conversation by ID. */
+    get(id: string): Promise<ApiResponse<Conversation>>;
+    /** Update a conversation's status and/or assignee (pass `assignee_user_id: null` to unassign). */
+    update(id: string, input: UpdateConversationInput, options?: RequestOptions): Promise<ApiResponse<ConversationUpdateResult>>;
+    /** Read a conversation's messages with cursor-based pagination. */
+    messages(id: string, options?: PaginationOptions): Promise<PaginatedResponse<ConversationMessage>>;
+}
+/** Send operator replies (or internal notes) into conversations. */
+declare class HelpdeskReplies {
+    private client;
+    constructor(client: BaseClient);
+    /**
+     * Send an operator reply or internal note. Returns HTTP 201.
+     *
+     * Pass an `idempotencyKey` so retried requests do not create duplicate
+     * messages — it is REQUIRED for capability-scoped tokens.
+     */
+    create(input: CreateReplyInput, options?: RequestOptions): Promise<ApiResponse<ReplyCreateResult>>;
+}
+/** Helpdesk bridge — read conversations, reply, and manage assignment/status. */
+declare class Helpdesk {
+    readonly conversations: HelpdeskConversations;
+    readonly replies: HelpdeskReplies;
+    constructor(client: BaseClient);
+}
+
 /** A post in the workspace (list view). */
 interface Post {
     id: string;
@@ -590,6 +726,129 @@ declare class Posts {
     channels(): Promise<ApiResponse<Channel[]>>;
 }
 
+/** A webhook endpoint registered in the workspace. */
+interface WebhookEndpoint {
+    id: string;
+    name: string;
+    /** Destination URL (must be https). */
+    url: string;
+    enabled: boolean;
+    /** Subscribed event types. Empty array = all events. */
+    event_types: string[];
+    /** Channel-type filter (e.g. ['widget', 'whatsapp']), or `null` for all channels. */
+    channels: string[] | null;
+    /** Channel-connection filter, or `null` for all connections. */
+    channel_connection_ids: string[] | null;
+    /** Last 4 characters of the signing secret, for identification. */
+    secret_last4: string;
+    consecutive_failures: number;
+    /** Unix timestamps in milliseconds, or `null` if never. */
+    last_delivery_at: number | null;
+    last_success_at: number | null;
+    last_error_at: number | null;
+    last_error: string | null;
+    created_at: number;
+    updated_at: number;
+    /**
+     * Full signing secret (`whsec_…`) — present ONLY in the `create` response.
+     * It is returned exactly once and can never be retrieved again. Store it
+     * securely immediately; you need it to verify delivery signatures.
+     */
+    secret?: string;
+}
+/** Input for creating a webhook endpoint. */
+interface CreateWebhookInput {
+    /** Display name (max 100 characters). */
+    name: string;
+    /** Destination URL — must be https. */
+    url: string;
+    /** Event types to subscribe to (e.g. 'helpdesk.message_received'). Empty = all. */
+    event_types: string[];
+    /** Restrict to these channel types (e.g. ['widget', 'whatsapp']). */
+    channels?: string[];
+    /** Restrict to these channel connection IDs. */
+    channel_connection_ids?: string[];
+}
+/**
+ * Input for updating a webhook endpoint. Only provided fields change.
+ * Pass `null` for `channels` or `channel_connection_ids` to CLEAR an existing
+ * filter (deliver for all channels / all accounts again); omitting the field
+ * leaves the current filter unchanged.
+ */
+interface UpdateWebhookInput {
+    name?: string;
+    url?: string;
+    event_types?: string[];
+    channels?: string[] | null;
+    channel_connection_ids?: string[] | null;
+    enabled?: boolean;
+}
+/** Result of deleting a webhook endpoint. */
+interface WebhookDeleteResult {
+    id: string;
+    status: string;
+}
+/** A delivery attempt record for a webhook endpoint. */
+interface WebhookDelivery {
+    id: string;
+    event_type: string;
+    status: "pending" | "delivered" | "dead_letter";
+    attempt_count: number;
+    /** Unix timestamp in milliseconds of the next retry, or `null`. */
+    next_attempt_at: number | null;
+    response_status: number | null;
+    duration_ms: number | null;
+    last_error: string | null;
+    /** Unix timestamp in milliseconds, or `null` if not delivered. */
+    delivered_at: number | null;
+    created_at: number;
+}
+/** Options for listing recent deliveries. */
+interface ListDeliveriesOptions {
+    limit?: number;
+}
+/** Result returned after queuing a test delivery (HTTP 202). */
+interface WebhookTestResult {
+    delivery_id: string;
+    status: string;
+}
+
+/** Manage webhook endpoints and inspect their deliveries. */
+declare class Webhooks {
+    private client;
+    constructor(client: BaseClient);
+    /** List all webhook endpoints in the workspace. */
+    list(): Promise<ApiResponse<WebhookEndpoint[]>>;
+    /**
+     * Create a webhook endpoint. Returns HTTP 201.
+     *
+     * **The response's `data.secret` contains the signing secret EXACTLY ONCE.**
+     * It can never be retrieved again — store it securely immediately. You need
+     * it to verify the `X-Medal-Signature` header on incoming deliveries (see
+     * `verifyWebhookSignature`).
+     *
+     * `secret` is typed optional because an idempotent replay (retrying with the
+     * same `Idempotency-Key`, `X-Idempotent-Replayed: true`) returns the existing
+     * endpoint WITHOUT the secret — handle that case (rotate if you lost it).
+     */
+    create(input: CreateWebhookInput, options?: RequestOptions): Promise<ApiResponse<WebhookEndpoint>>;
+    /** Get a webhook endpoint by ID. */
+    get(id: string): Promise<ApiResponse<WebhookEndpoint>>;
+    /** Update a webhook endpoint (name, url, event types, filters, enabled). */
+    update(id: string, input: UpdateWebhookInput, options?: RequestOptions): Promise<ApiResponse<WebhookEndpoint>>;
+    /**
+     * Permanently delete a webhook endpoint (stops all outbound deliveries).
+     * Capability-scoped tokens must pass `idempotencyKey` — the API requires
+     * `Idempotency-Key` + `X-Capability-Confirmation` for direct capability
+     * grants on this route. API keys with legacy scopes may omit it.
+     */
+    delete(id: string, options?: RequestOptions): Promise<ApiResponse<WebhookDeleteResult>>;
+    /** List recent deliveries for an endpoint (most recent first). */
+    deliveries(id: string, options?: ListDeliveriesOptions): Promise<ApiResponse<WebhookDelivery[]>>;
+    /** Queue a signed `test.ping` delivery to the endpoint. Returns HTTP 202. */
+    test(id: string): Promise<ApiResponse<WebhookTestResult>>;
+}
+
 /** A Medal Social workspace accessible to the authenticated credential. */
 interface Workspace {
     id: string;
@@ -606,6 +865,178 @@ declare class Workspaces {
     list(): Promise<ApiResponse<Workspace[]>>;
 }
 
+/**
+ * Webhook event types and signature verification for the Medal Social
+ * outbound webhook bridge.
+ *
+ * Every delivery is an HTTP POST with headers:
+ * - `X-Medal-Timestamp` — Unix milliseconds when the request was signed
+ * - `X-Medal-Signature` — `sha256=<base64(HMAC-SHA256("{timestamp}.{rawBody}", secret))>`
+ * - `X-Medal-Event` — the event type
+ * - `X-Medal-Delivery-Id` / `Idempotency-Key` — unique delivery ID (deduplicate on this)
+ *
+ * Use {@link verifyWebhookSignature} to authenticate a delivery and get the
+ * parsed, typed event back. Uses Web Crypto (`crypto.subtle`) so it works in
+ * Node.js 18+, Deno, Bun, Cloudflare Workers, and browsers.
+ */
+/** Snapshot of a conversation included in every helpdesk webhook event. */
+interface WebhookConversationSnapshot {
+    id: string;
+    channel: string;
+    channelConnectionId: string | null;
+    status: string;
+    subject: string | null;
+    assigneeUserId: string | null;
+    contactId: string | null;
+    visitorName: string | null;
+    visitorEmail: string | null;
+    externalConversationId: string | null;
+    channelAccountId: string | null;
+    messageCount: number;
+    /** Unix timestamp in milliseconds. */
+    lastMessageAt: number;
+    /** Unix timestamp in milliseconds. */
+    createdAt: number;
+}
+/** Snapshot of a message included in helpdesk message events. */
+interface WebhookMessageSnapshot {
+    id: string;
+    authorType: "visitor" | "operator" | "ai" | "system";
+    messageType: "chat" | "email" | "note";
+    body: string;
+    authorUserId: string | null;
+    authorName: string | null;
+    externalMessageId: string | null;
+    deliveryStatus: string | null;
+    deliveryError: string | null;
+    /** Unix timestamp in milliseconds. */
+    createdAt: number;
+}
+/** Fields present in the `data` of every helpdesk event. */
+interface HelpdeskEventData {
+    /** Channel type at the top level, for quick filtering. */
+    channel: string;
+    channelConnectionId: string | null;
+    conversation: WebhookConversationSnapshot;
+}
+/** Envelope fields shared by all webhook events. */
+interface WebhookEventBase {
+    /** Unique delivery/event ID — use for deduplication. */
+    id: string;
+    /** Unix timestamp in milliseconds when the event was created. */
+    created_at: number;
+    workspace_id: string;
+}
+/** A new conversation was created. */
+interface ConversationCreatedEvent extends WebhookEventBase {
+    type: "helpdesk.conversation_created";
+    data: HelpdeskEventData;
+}
+/** A conversation was assigned or unassigned. */
+interface ConversationAssignedEvent extends WebhookEventBase {
+    type: "helpdesk.conversation_assigned";
+    data: HelpdeskEventData & {
+        assigneeUserId: string | null;
+        previousAssigneeUserId: string | null;
+    };
+}
+/** A conversation's status changed (open / snoozed / closed). */
+interface ConversationStatusChangedEvent extends WebhookEventBase {
+    type: "helpdesk.conversation_status_changed";
+    data: HelpdeskEventData & {
+        status: string;
+        previousStatus: string;
+    };
+}
+/** A message arrived from the visitor/customer. */
+interface MessageReceivedEvent extends WebhookEventBase {
+    type: "helpdesk.message_received";
+    data: HelpdeskEventData & {
+        message: WebhookMessageSnapshot;
+    };
+}
+/** A message was sent by an operator, AI, or the system. */
+interface MessageSentEvent extends WebhookEventBase {
+    type: "helpdesk.message_sent";
+    data: HelpdeskEventData & {
+        message: WebhookMessageSnapshot;
+    };
+}
+/** The delivery status of an outbound message changed (sent / delivered / failed …). */
+interface MessageDeliveryUpdatedEvent extends WebhookEventBase {
+    type: "helpdesk.message_delivery_updated";
+    data: HelpdeskEventData & {
+        message: WebhookMessageSnapshot;
+    };
+}
+/** A `test.ping` delivery queued via `medal.webhooks.test(id)`. Carries sample data. */
+interface TestPingEvent extends WebhookEventBase {
+    type: "test.ping";
+    data: Record<string, unknown>;
+}
+/**
+ * Discriminated union of all webhook events, keyed on `type`.
+ *
+ * @example
+ * ```ts
+ * switch (event.type) {
+ *   case 'helpdesk.message_received':
+ *     console.log(event.data.message.body);
+ *     break;
+ *   case 'helpdesk.conversation_status_changed':
+ *     console.log(event.data.previousStatus, '→', event.data.status);
+ *     break;
+ * }
+ * ```
+ */
+type WebhookEvent = ConversationCreatedEvent | ConversationAssignedEvent | ConversationStatusChangedEvent | MessageReceivedEvent | MessageSentEvent | MessageDeliveryUpdatedEvent | TestPingEvent;
+/** Machine-readable reason a webhook verification failed. */
+type WebhookVerificationErrorCode = "malformed_header" | "timestamp_out_of_tolerance" | "invalid_signature" | "invalid_payload";
+/** Thrown by {@link verifyWebhookSignature} when a delivery cannot be authenticated. */
+declare class WebhookVerificationError extends Error {
+    readonly code: WebhookVerificationErrorCode;
+    constructor(code: WebhookVerificationErrorCode, message: string);
+}
+/** Input for {@link verifyWebhookSignature}. */
+interface VerifyWebhookSignatureInput {
+    /** The RAW request body string, exactly as received (do not re-serialize parsed JSON). */
+    payload: string;
+    /** Value of the `X-Medal-Timestamp` header (Unix milliseconds). */
+    timestamp: string;
+    /** Value of the `X-Medal-Signature` header (`sha256=<base64>`). */
+    signature: string;
+    /** The endpoint signing secret (`whsec_…`) returned once at creation time. */
+    secret: string;
+    /** Max allowed clock skew between now and the signed timestamp. Default 5 minutes. */
+    toleranceMs?: number;
+}
+/** Default allowed clock skew for webhook verification (5 minutes). */
+declare const DEFAULT_WEBHOOK_TOLERANCE_MS: number;
+/**
+ * Verify a webhook delivery's signature and timestamp, then return the parsed
+ * typed event.
+ *
+ * Recomputes `HMAC-SHA256("{timestamp}.{payload}", secret)` with Web Crypto
+ * and compares it against the signature in constant time. Deliveries whose
+ * timestamp deviates from the current time by more than `toleranceMs`
+ * (default 5 minutes) are rejected to prevent replay attacks.
+ *
+ * @throws {WebhookVerificationError} if the headers are malformed, the
+ * timestamp is outside the tolerance window, the signature does not match,
+ * or the payload is not valid JSON.
+ *
+ * @example
+ * ```ts
+ * const event = await verifyWebhookSignature({
+ *   payload: rawBody,
+ *   timestamp: req.headers['x-medal-timestamp'],
+ *   signature: req.headers['x-medal-signature'],
+ *   secret: process.env.MEDAL_WEBHOOK_SECRET,
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): Promise<WebhookEvent>;
+
 /** Options for configuring the {@link Medal} client. */
 interface MedalOptions {
     /** Override the base URL (defaults to https://io.medalsocial.com). */
@@ -670,7 +1101,9 @@ declare class Medal {
     readonly contacts: Contacts;
     readonly deals: Deals;
     readonly gdpr: Gdpr;
+    readonly helpdesk: Helpdesk;
     readonly posts: Posts;
+    readonly webhooks: Webhooks;
     readonly workspaces: Workspaces;
     constructor(token: string, options?: MedalOptions);
 }
@@ -678,4 +1111,4 @@ declare class Medal {
 /** Convenience factory — equivalent to `new Medal(apiKey, options)`. */
 declare function createMedalClient(apiKey: string, options?: MedalOptions): Medal;
 
-export { type Activity, type AddNoteInput, type ApiResponse, BaseClient, type BatchSendInput, type BatchSendResult, type BatchSendSummary, type Channel, type ConsentRecord, type ConsentResult, type ConsentType, type Contact, type ContactConsents, type ContactCreateResult, type ContactNoteResult, type ContactRemoveResult, type ContactStatus, type ContactUpdateResult, Contacts, type CookieCategoryConsent, type CookieConsentInput, type CreateContactInput, type CreateDealInput, type CreatePostInput, type Deal, type DealCreateResult, type DealRemoveResult, type DealStatus, type DealUpdateResult, Deals, type EmailSend, type EmailSendResult, type EmailStatus, type EmailTemplate, type EmailTemplateDetail, Emails, Gdpr, type GdprExport, type GetTemplateOptions, type ImportContactInput, type ImportContactsResult, type ListContactsOptions, type ListDealsOptions, type ListPostsOptions, Medal, MedalApiError, type MedalOptions, type PaginatedResponse, type PaginationOptions, type Post, type PostDetail, type PostType, type PostVariant, Posts, type PublishResult, type RecordConsentInput, type SchedulePostInput, type ScheduleResult, type SendEmailInput, type UpdateContactInput, type UpdateDealInput, type UpdatePostInput, type Workspace, Workspaces, createMedalClient, Medal as default };
+export { type Activity, type AddNoteInput, type ApiResponse, BaseClient, type BatchSendInput, type BatchSendResult, type BatchSendSummary, type Channel, type ConsentRecord, type ConsentResult, type ConsentType, type Contact, type ContactConsents, type ContactCreateResult, type ContactNoteResult, type ContactRemoveResult, type ContactStatus, type ContactUpdateResult, Contacts, type Conversation, type ConversationAssignedEvent, type ConversationCreatedEvent, type ConversationMessage, type ConversationStatus, type ConversationStatusChangedEvent, type ConversationUpdateResult, type CookieCategoryConsent, type CookieConsentInput, type CreateContactInput, type CreateDealInput, type CreatePostInput, type CreateReplyInput, type CreateWebhookInput, DEFAULT_WEBHOOK_TOLERANCE_MS, type Deal, type DealCreateResult, type DealRemoveResult, type DealStatus, type DealUpdateResult, Deals, type EmailSend, type EmailSendResult, type EmailStatus, type EmailTemplate, type EmailTemplateDetail, Emails, Gdpr, type GdprExport, type GetTemplateOptions, Helpdesk, type HelpdeskMessageType, type ImportContactInput, type ImportContactsResult, type ListContactsOptions, type ListConversationsOptions, type ListDealsOptions, type ListDeliveriesOptions, type ListPostsOptions, Medal, MedalApiError, type MedalOptions, type MessageAuthorType, type MessageDeliveryUpdatedEvent, type MessageReceivedEvent, type MessageSentEvent, type PaginatedResponse, type PaginationOptions, type Post, type PostDetail, type PostType, type PostVariant, Posts, type PublishResult, type RecordConsentInput, type ReplyCreateResult, type RequestOptions, type SchedulePostInput, type ScheduleResult, type SendEmailInput, type TestPingEvent, type UpdateContactInput, type UpdateConversationInput, type UpdateDealInput, type UpdatePostInput, type UpdateWebhookInput, type VerifyWebhookSignatureInput, type WebhookConversationSnapshot, type WebhookDeleteResult, type WebhookDelivery, type WebhookEndpoint, type WebhookEvent, type WebhookMessageSnapshot, type WebhookTestResult, WebhookVerificationError, type WebhookVerificationErrorCode, Webhooks, type Workspace, Workspaces, createMedalClient, Medal as default, verifyWebhookSignature };