@medalsocial/sdk 1.3.0 → 1.5.0

package/dist/src/index.d.mts

@@ -48,6 +48,78 @@ declare class BaseClient {
     private request;
 }
 
+/** Lifecycle status of a hosted connect link. */
+type ConnectLinkStatus = "pending" | "consumed" | "expired" | "revoked";
+/** Lifecycle state of a channel connection. */
+type ChannelConnectionState = "connecting" | "active" | "disconnected" | "disabled";
+/** Input for minting a hosted connect link. */
+interface CreateConnectLinkInput {
+    /** Channel type to connect (e.g. `telegram_inbox`). */
+    channel_type: string;
+    /** Display label shown on the hosted connect page (max 100 characters). */
+    label?: string;
+    /** URL the hosted page redirects to after a successful connect — must be https. */
+    redirect_url?: string;
+}
+/** Result of minting a connect link (HTTP 201). */
+interface ConnectLinkCreateResult {
+    id: string;
+    /**
+     * The single-use hosted connect URL containing the one-time link token.
+     * **Present ONLY in the live create response** — an idempotent replay
+     * (retrying with the same `Idempotency-Key`) returns the link WITHOUT `url`.
+     * If you lose it, revoke the link and mint a new one; the token can never
+     * be retrieved again.
+     */
+    url?: string;
+    channel_type: string;
+    label: string | null;
+    status: ConnectLinkStatus;
+    /** Unix timestamp in milliseconds when the link expires. */
+    expires_at: number;
+}
+/** A hosted connect link (list view — tokens are never returned). */
+interface ConnectLink {
+    id: string;
+    channel_type: string;
+    label: string | null;
+    status: ConnectLinkStatus;
+    /** Stable ref of the connection created by consuming this link, or `null`. */
+    consumed_connection_ref: string | null;
+    /** Unix timestamp in milliseconds. */
+    expires_at: number;
+    /** Unix timestamp in milliseconds. */
+    created_at: number;
+}
+/** Filters for listing connect links. */
+interface ListConnectLinksOptions {
+    channel_type?: string;
+    status?: ConnectLinkStatus;
+}
+/** Result of revoking a connect link. */
+interface ConnectLinkRevokeResult {
+    id: string;
+    status: "revoked";
+}
+/** A channel connection attached to the workspace (generic, channel-agnostic shape). */
+interface ChannelConnection {
+    id: string;
+    channel_type: string;
+    label: string | null;
+    state: ChannelConnectionState;
+    /** Privacy-preserving identity handle (e.g. a masked phone number). */
+    masked_identity: string;
+    /** Unix timestamp in milliseconds, or `null` if never active. */
+    last_activity_at: number | null;
+    /** Linked helpdesk channel connection ID, or `null`. */
+    helpdesk_connection_id: string | null;
+}
+/** Result of disconnecting a channel connection. */
+interface ChannelConnectionDisconnectResult {
+    id: string;
+    state: "disconnected";
+}
+
 /** Successful API response wrapper */
 interface ApiResponse<T> {
     data: T;
@@ -73,6 +145,52 @@ interface PaginationOptions {
     cursor?: string;
 }
 
+/** Mint, list, and revoke hosted connect links. */
+declare class ChannelConnectLinks {
+    private client;
+    constructor(client: BaseClient);
+    /**
+     * Mint a single-use hosted connect link. Returns HTTP 201.
+     *
+     * **The response's `data.url` contains the one-time link token EXACTLY
+     * ONCE.** Send it to the person who should connect their account — an
+     * idempotent replay (same `Idempotency-Key`) returns the link WITHOUT
+     * `url`, so store it immediately (or revoke and mint a new link if lost).
+     *
+     * Requires the `channel.connect.manage` scope; OAuth callers additionally
+     * need the workspace `admin` role.
+     */
+    create(input: CreateConnectLinkInput, options?: RequestOptions): Promise<ApiResponse<ConnectLinkCreateResult>>;
+    /** List the workspace's connect links (tokens are never returned). */
+    list(options?: ListConnectLinksOptions): Promise<ApiResponse<ConnectLink[]>>;
+    /** Revoke a pending connect link so it can no longer be consumed. */
+    revoke(id: string, options?: RequestOptions): Promise<ApiResponse<ConnectLinkRevokeResult>>;
+}
+/** List and disconnect the workspace's channel connections. */
+declare class ChannelConnections {
+    private client;
+    constructor(client: BaseClient);
+    /** List the workspace's channel connections (generic, channel-agnostic shape). */
+    list(): Promise<ApiResponse<ChannelConnection[]>>;
+    /**
+     * Disconnect a connected channel account (best-effort platform logout, then
+     * local revoke). Emits a `helpdesk.channel_disconnected` webhook event with
+     * `reason: "api_disconnect"` if the account was previously connected.
+     */
+    disconnect(id: string, options?: RequestOptions): Promise<ApiResponse<ChannelConnectionDisconnectResult>>;
+}
+/**
+ * Partner channel connect — mint hosted connect links that let an external
+ * person (no Medal account required) attach a channel account (e.g.
+ * `telegram_inbox`) to the workspace's helpdesk, and manage the resulting
+ * connections.
+ */
+declare class Channels {
+    readonly connectLinks: ChannelConnectLinks;
+    readonly connections: ChannelConnections;
+    constructor(client: BaseClient);
+}
+
 /** A contact in the workspace CRM. */
 interface Contact {
     id: string;
@@ -308,10 +426,21 @@ interface SendEmailInput {
     fallback_locale?: string;
     variables?: Record<string, string>;
     contact_id?: string;
+    /** Body-level idempotency key (alternative to the `Idempotency-Key` header). */
+    idempotency_key?: string;
+    /** Also send a `[Copy]` of the email to this address. */
+    copy_to?: string;
+    /** Reply-To for the copy (defaults to the primary recipient). */
+    copy_reply_to?: string;
 }
 /** Result returned after queuing a transactional email send (HTTP 202). */
 interface EmailSendResult {
-    id: string;
+    /** Email send id — poll `emails.get(id)` with it to track delivery. */
+    id: string | null;
+    /** Send id of the `copy_to` copy, or `null` when no copy was requested. */
+    copy_id: string | null;
+    /** CRM contact linked to the send, or `null`. */
+    contact_id: string | null;
     status: string;
 }
 /** Full record for a sent email, including delivery timestamps. */
@@ -341,12 +470,23 @@ interface BatchSendInput {
         variables?: Record<string, string>;
     }[];
 }
+/** Per-recipient outcome of a batch send, in request order. */
+interface BatchSendRecipientResult {
+    email: string;
+    /** Email send id — poll `emails.get(id)` with it. `null` when not queued. */
+    id: string | null;
+    status: "queued" | "failed";
+    /** Failure reason for recipients that were not queued. */
+    error: string | null;
+}
 /** Summary returned after queuing a batch email send. */
 interface BatchSendSummary {
     batch_id: string;
     total: number;
     queued: number;
     failed: number;
+    /** Per-recipient outcome, in request order. */
+    results: BatchSendRecipientResult[];
 }
 /** @deprecated Use `BatchSendSummary` for `emails.batch()` responses. */
 type BatchSendResult = BatchSendSummary;
@@ -407,11 +547,17 @@ declare class Emails {
     private client;
     readonly templates: EmailTemplates;
     constructor(client: BaseClient);
-    /** Send a transactional email using a template. Returns a queued job ID (HTTP 202). */
+    /**
+     * Send a transactional email using a template (HTTP 202). The returned `id`
+     * is an email send id — poll `emails.get(id)` with it to track delivery.
+     */
     send(input: SendEmailInput): Promise<ApiResponse<EmailSendResult>>;
     /** Get the delivery status of a sent email. */
     get(id: string): Promise<ApiResponse<EmailSend>>;
-    /** Send the same template to multiple recipients (max 100). Returns HTTP 202. */
+    /**
+     * Send the same template to multiple recipients (max 100, HTTP 202). Each
+     * queued recipient gets its own send id in `results` for `emails.get(id)`.
+     */
     batch(input: BatchSendInput): Promise<ApiResponse<BatchSendSummary>>;
 }
 
@@ -969,6 +1115,38 @@ interface MessageDeliveryUpdatedEvent extends WebhookEventBase {
         message: WebhookMessageSnapshot;
     };
 }
+/**
+ * Fields present in the `data` of channel lifecycle events. Unlike message
+ * events there is no conversation snapshot — the payload is channel-generic.
+ * `channel` / `channelConnectionId` sit at the top level so endpoint channel
+ * filters match exactly like message events.
+ */
+interface WebhookChannelLifecycleData {
+    /** Helpdesk channel type (e.g. `telegram`), or `null` for non-helpdesk channels. */
+    channel: string | null;
+    channelConnectionId: string | null;
+    /** Connector channel type (e.g. `telegram_inbox`). */
+    channel_type: string;
+    /** Adapter-defined stable connection ref (matches `consumed_connection_ref` on the connect link). */
+    connection_ref: string;
+    label: string | null;
+    masked_identity: string | null;
+}
+/** A channel account was connected to the workspace (e.g. via a partner connect link). */
+interface ChannelConnectedEvent extends WebhookEventBase {
+    type: "helpdesk.channel_connected";
+    data: WebhookChannelLifecycleData;
+}
+/** Why a channel account was disconnected. */
+type ChannelDisconnectReason = "api_disconnect" | "user_revoked" | "member_disconnect";
+/** A previously connected channel account was removed from the workspace. */
+interface ChannelDisconnectedEvent extends WebhookEventBase {
+    type: "helpdesk.channel_disconnected";
+    data: WebhookChannelLifecycleData & {
+        /** Why the account went away. */
+        reason?: ChannelDisconnectReason;
+    };
+}
 /** A `test.ping` delivery queued via `medal.webhooks.test(id)`. Carries sample data. */
 interface TestPingEvent extends WebhookEventBase {
     type: "test.ping";
@@ -989,7 +1167,7 @@ interface TestPingEvent extends WebhookEventBase {
  * }
  * ```
  */
-type WebhookEvent = ConversationCreatedEvent | ConversationAssignedEvent | ConversationStatusChangedEvent | MessageReceivedEvent | MessageSentEvent | MessageDeliveryUpdatedEvent | TestPingEvent;
+type WebhookEvent = ConversationCreatedEvent | ConversationAssignedEvent | ConversationStatusChangedEvent | MessageReceivedEvent | MessageSentEvent | MessageDeliveryUpdatedEvent | ChannelConnectedEvent | ChannelDisconnectedEvent | 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. */
@@ -1097,6 +1275,7 @@ interface MedalOptions {
  * ```
  */
 declare class Medal {
+    readonly channels: Channels;
     readonly emails: Emails;
     readonly contacts: Contacts;
     readonly deals: Deals;
@@ -1111,4 +1290,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 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 };
+export { type Activity, type AddNoteInput, type ApiResponse, BaseClient, type BatchSendInput, type BatchSendResult, type BatchSendSummary, type Channel, type ChannelConnectedEvent, type ChannelConnection, type ChannelConnectionDisconnectResult, type ChannelConnectionState, type ChannelDisconnectReason, type ChannelDisconnectedEvent, Channels, type ConnectLink, type ConnectLinkCreateResult, type ConnectLinkRevokeResult, type ConnectLinkStatus, 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 CreateConnectLinkInput, 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 ListConnectLinksOptions, 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 WebhookChannelLifecycleData, 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 };

package/dist/src/index.d.ts

@@ -48,6 +48,78 @@ declare class BaseClient {
     private request;
 }
 
+/** Lifecycle status of a hosted connect link. */
+type ConnectLinkStatus = "pending" | "consumed" | "expired" | "revoked";
+/** Lifecycle state of a channel connection. */
+type ChannelConnectionState = "connecting" | "active" | "disconnected" | "disabled";
+/** Input for minting a hosted connect link. */
+interface CreateConnectLinkInput {
+    /** Channel type to connect (e.g. `telegram_inbox`). */
+    channel_type: string;
+    /** Display label shown on the hosted connect page (max 100 characters). */
+    label?: string;
+    /** URL the hosted page redirects to after a successful connect — must be https. */
+    redirect_url?: string;
+}
+/** Result of minting a connect link (HTTP 201). */
+interface ConnectLinkCreateResult {
+    id: string;
+    /**
+     * The single-use hosted connect URL containing the one-time link token.
+     * **Present ONLY in the live create response** — an idempotent replay
+     * (retrying with the same `Idempotency-Key`) returns the link WITHOUT `url`.
+     * If you lose it, revoke the link and mint a new one; the token can never
+     * be retrieved again.
+     */
+    url?: string;
+    channel_type: string;
+    label: string | null;
+    status: ConnectLinkStatus;
+    /** Unix timestamp in milliseconds when the link expires. */
+    expires_at: number;
+}
+/** A hosted connect link (list view — tokens are never returned). */
+interface ConnectLink {
+    id: string;
+    channel_type: string;
+    label: string | null;
+    status: ConnectLinkStatus;
+    /** Stable ref of the connection created by consuming this link, or `null`. */
+    consumed_connection_ref: string | null;
+    /** Unix timestamp in milliseconds. */
+    expires_at: number;
+    /** Unix timestamp in milliseconds. */
+    created_at: number;
+}
+/** Filters for listing connect links. */
+interface ListConnectLinksOptions {
+    channel_type?: string;
+    status?: ConnectLinkStatus;
+}
+/** Result of revoking a connect link. */
+interface ConnectLinkRevokeResult {
+    id: string;
+    status: "revoked";
+}
+/** A channel connection attached to the workspace (generic, channel-agnostic shape). */
+interface ChannelConnection {
+    id: string;
+    channel_type: string;
+    label: string | null;
+    state: ChannelConnectionState;
+    /** Privacy-preserving identity handle (e.g. a masked phone number). */
+    masked_identity: string;
+    /** Unix timestamp in milliseconds, or `null` if never active. */
+    last_activity_at: number | null;
+    /** Linked helpdesk channel connection ID, or `null`. */
+    helpdesk_connection_id: string | null;
+}
+/** Result of disconnecting a channel connection. */
+interface ChannelConnectionDisconnectResult {
+    id: string;
+    state: "disconnected";
+}
+
 /** Successful API response wrapper */
 interface ApiResponse<T> {
     data: T;
@@ -73,6 +145,52 @@ interface PaginationOptions {
     cursor?: string;
 }
 
+/** Mint, list, and revoke hosted connect links. */
+declare class ChannelConnectLinks {
+    private client;
+    constructor(client: BaseClient);
+    /**
+     * Mint a single-use hosted connect link. Returns HTTP 201.
+     *
+     * **The response's `data.url` contains the one-time link token EXACTLY
+     * ONCE.** Send it to the person who should connect their account — an
+     * idempotent replay (same `Idempotency-Key`) returns the link WITHOUT
+     * `url`, so store it immediately (or revoke and mint a new link if lost).
+     *
+     * Requires the `channel.connect.manage` scope; OAuth callers additionally
+     * need the workspace `admin` role.
+     */
+    create(input: CreateConnectLinkInput, options?: RequestOptions): Promise<ApiResponse<ConnectLinkCreateResult>>;
+    /** List the workspace's connect links (tokens are never returned). */
+    list(options?: ListConnectLinksOptions): Promise<ApiResponse<ConnectLink[]>>;
+    /** Revoke a pending connect link so it can no longer be consumed. */
+    revoke(id: string, options?: RequestOptions): Promise<ApiResponse<ConnectLinkRevokeResult>>;
+}
+/** List and disconnect the workspace's channel connections. */
+declare class ChannelConnections {
+    private client;
+    constructor(client: BaseClient);
+    /** List the workspace's channel connections (generic, channel-agnostic shape). */
+    list(): Promise<ApiResponse<ChannelConnection[]>>;
+    /**
+     * Disconnect a connected channel account (best-effort platform logout, then
+     * local revoke). Emits a `helpdesk.channel_disconnected` webhook event with
+     * `reason: "api_disconnect"` if the account was previously connected.
+     */
+    disconnect(id: string, options?: RequestOptions): Promise<ApiResponse<ChannelConnectionDisconnectResult>>;
+}
+/**
+ * Partner channel connect — mint hosted connect links that let an external
+ * person (no Medal account required) attach a channel account (e.g.
+ * `telegram_inbox`) to the workspace's helpdesk, and manage the resulting
+ * connections.
+ */
+declare class Channels {
+    readonly connectLinks: ChannelConnectLinks;
+    readonly connections: ChannelConnections;
+    constructor(client: BaseClient);
+}
+
 /** A contact in the workspace CRM. */
 interface Contact {
     id: string;
@@ -308,10 +426,21 @@ interface SendEmailInput {
     fallback_locale?: string;
     variables?: Record<string, string>;
     contact_id?: string;
+    /** Body-level idempotency key (alternative to the `Idempotency-Key` header). */
+    idempotency_key?: string;
+    /** Also send a `[Copy]` of the email to this address. */
+    copy_to?: string;
+    /** Reply-To for the copy (defaults to the primary recipient). */
+    copy_reply_to?: string;
 }
 /** Result returned after queuing a transactional email send (HTTP 202). */
 interface EmailSendResult {
-    id: string;
+    /** Email send id — poll `emails.get(id)` with it to track delivery. */
+    id: string | null;
+    /** Send id of the `copy_to` copy, or `null` when no copy was requested. */
+    copy_id: string | null;
+    /** CRM contact linked to the send, or `null`. */
+    contact_id: string | null;
     status: string;
 }
 /** Full record for a sent email, including delivery timestamps. */
@@ -341,12 +470,23 @@ interface BatchSendInput {
         variables?: Record<string, string>;
     }[];
 }
+/** Per-recipient outcome of a batch send, in request order. */
+interface BatchSendRecipientResult {
+    email: string;
+    /** Email send id — poll `emails.get(id)` with it. `null` when not queued. */
+    id: string | null;
+    status: "queued" | "failed";
+    /** Failure reason for recipients that were not queued. */
+    error: string | null;
+}
 /** Summary returned after queuing a batch email send. */
 interface BatchSendSummary {
     batch_id: string;
     total: number;
     queued: number;
     failed: number;
+    /** Per-recipient outcome, in request order. */
+    results: BatchSendRecipientResult[];
 }
 /** @deprecated Use `BatchSendSummary` for `emails.batch()` responses. */
 type BatchSendResult = BatchSendSummary;
@@ -407,11 +547,17 @@ declare class Emails {
     private client;
     readonly templates: EmailTemplates;
     constructor(client: BaseClient);
-    /** Send a transactional email using a template. Returns a queued job ID (HTTP 202). */
+    /**
+     * Send a transactional email using a template (HTTP 202). The returned `id`
+     * is an email send id — poll `emails.get(id)` with it to track delivery.
+     */
     send(input: SendEmailInput): Promise<ApiResponse<EmailSendResult>>;
     /** Get the delivery status of a sent email. */
     get(id: string): Promise<ApiResponse<EmailSend>>;
-    /** Send the same template to multiple recipients (max 100). Returns HTTP 202. */
+    /**
+     * Send the same template to multiple recipients (max 100, HTTP 202). Each
+     * queued recipient gets its own send id in `results` for `emails.get(id)`.
+     */
     batch(input: BatchSendInput): Promise<ApiResponse<BatchSendSummary>>;
 }
 
@@ -969,6 +1115,38 @@ interface MessageDeliveryUpdatedEvent extends WebhookEventBase {
         message: WebhookMessageSnapshot;
     };
 }
+/**
+ * Fields present in the `data` of channel lifecycle events. Unlike message
+ * events there is no conversation snapshot — the payload is channel-generic.
+ * `channel` / `channelConnectionId` sit at the top level so endpoint channel
+ * filters match exactly like message events.
+ */
+interface WebhookChannelLifecycleData {
+    /** Helpdesk channel type (e.g. `telegram`), or `null` for non-helpdesk channels. */
+    channel: string | null;
+    channelConnectionId: string | null;
+    /** Connector channel type (e.g. `telegram_inbox`). */
+    channel_type: string;
+    /** Adapter-defined stable connection ref (matches `consumed_connection_ref` on the connect link). */
+    connection_ref: string;
+    label: string | null;
+    masked_identity: string | null;
+}
+/** A channel account was connected to the workspace (e.g. via a partner connect link). */
+interface ChannelConnectedEvent extends WebhookEventBase {
+    type: "helpdesk.channel_connected";
+    data: WebhookChannelLifecycleData;
+}
+/** Why a channel account was disconnected. */
+type ChannelDisconnectReason = "api_disconnect" | "user_revoked" | "member_disconnect";
+/** A previously connected channel account was removed from the workspace. */
+interface ChannelDisconnectedEvent extends WebhookEventBase {
+    type: "helpdesk.channel_disconnected";
+    data: WebhookChannelLifecycleData & {
+        /** Why the account went away. */
+        reason?: ChannelDisconnectReason;
+    };
+}
 /** A `test.ping` delivery queued via `medal.webhooks.test(id)`. Carries sample data. */
 interface TestPingEvent extends WebhookEventBase {
     type: "test.ping";
@@ -989,7 +1167,7 @@ interface TestPingEvent extends WebhookEventBase {
  * }
  * ```
  */
-type WebhookEvent = ConversationCreatedEvent | ConversationAssignedEvent | ConversationStatusChangedEvent | MessageReceivedEvent | MessageSentEvent | MessageDeliveryUpdatedEvent | TestPingEvent;
+type WebhookEvent = ConversationCreatedEvent | ConversationAssignedEvent | ConversationStatusChangedEvent | MessageReceivedEvent | MessageSentEvent | MessageDeliveryUpdatedEvent | ChannelConnectedEvent | ChannelDisconnectedEvent | 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. */
@@ -1097,6 +1275,7 @@ interface MedalOptions {
  * ```
  */
 declare class Medal {
+    readonly channels: Channels;
     readonly emails: Emails;
     readonly contacts: Contacts;
     readonly deals: Deals;
@@ -1111,4 +1290,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 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 };
+export { type Activity, type AddNoteInput, type ApiResponse, BaseClient, type BatchSendInput, type BatchSendResult, type BatchSendSummary, type Channel, type ChannelConnectedEvent, type ChannelConnection, type ChannelConnectionDisconnectResult, type ChannelConnectionState, type ChannelDisconnectReason, type ChannelDisconnectedEvent, Channels, type ConnectLink, type ConnectLinkCreateResult, type ConnectLinkRevokeResult, type ConnectLinkStatus, 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 CreateConnectLinkInput, 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 ListConnectLinksOptions, 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 WebhookChannelLifecycleData, 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 };

package/dist/src/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   BaseClient: () => BaseClient,
+  Channels: () => Channels,
   Contacts: () => Contacts,
   DEFAULT_WEBHOOK_TOLERANCE_MS: () => DEFAULT_WEBHOOK_TOLERANCE_MS,
   Deals: () => Deals,
@@ -164,6 +165,65 @@ var BaseClient = class {
   }
 };
 
+// src/resources/channels.ts
+var ChannelConnectLinks = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Mint a single-use hosted connect link. Returns HTTP 201.
+   *
+   * **The response's `data.url` contains the one-time link token EXACTLY
+   * ONCE.** Send it to the person who should connect their account — an
+   * idempotent replay (same `Idempotency-Key`) returns the link WITHOUT
+   * `url`, so store it immediately (or revoke and mint a new link if lost).
+   *
+   * Requires the `channel.connect.manage` scope; OAuth callers additionally
+   * need the workspace `admin` role.
+   */
+  async create(input, options) {
+    return this.client.post("/api/v1/channels/connect-links", input, options);
+  }
+  /** List the workspace's connect links (tokens are never returned). */
+  async list(options) {
+    const params = {};
+    if (options?.channel_type) params.channel_type = options.channel_type;
+    if (options?.status) params.status = options.status;
+    return this.client.get("/api/v1/channels/connect-links", params);
+  }
+  /** Revoke a pending connect link so it can no longer be consumed. */
+  async revoke(id, options) {
+    return this.client.delete(`/api/v1/channels/connect-links/${encodeURIComponent(id)}`, options);
+  }
+};
+var ChannelConnections = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** List the workspace's channel connections (generic, channel-agnostic shape). */
+  async list() {
+    return this.client.get("/api/v1/channels/connections");
+  }
+  /**
+   * Disconnect a connected channel account (best-effort platform logout, then
+   * local revoke). Emits a `helpdesk.channel_disconnected` webhook event with
+   * `reason: "api_disconnect"` if the account was previously connected.
+   */
+  async disconnect(id, options) {
+    return this.client.delete(`/api/v1/channels/connections/${encodeURIComponent(id)}`, options);
+  }
+};
+var Channels = class {
+  connectLinks;
+  connections;
+  constructor(client) {
+    this.connectLinks = new ChannelConnectLinks(client);
+    this.connections = new ChannelConnections(client);
+  }
+};
+
 // src/resources/contacts.ts
 var Contacts = class {
   constructor(client) {
@@ -272,7 +332,10 @@ var Emails = class {
   }
   client;
   templates;
-  /** Send a transactional email using a template. Returns a queued job ID (HTTP 202). */
+  /**
+   * Send a transactional email using a template (HTTP 202). The returned `id`
+   * is an email send id — poll `emails.get(id)` with it to track delivery.
+   */
   async send(input) {
     return this.client.post("/api/v1/emails", input);
   }
@@ -280,7 +343,10 @@ var Emails = class {
   async get(id) {
     return this.client.get(`/api/v1/emails/${encodeURIComponent(id)}`);
   }
-  /** Send the same template to multiple recipients (max 100). Returns HTTP 202. */
+  /**
+   * Send the same template to multiple recipients (max 100, HTTP 202). Each
+   * queued recipient gets its own send id in `results` for `emails.get(id)`.
+   */
   async batch(input) {
     return this.client.post("/api/v1/emails/batch", input);
   }
@@ -566,6 +632,7 @@ async function verifyWebhookSignature(input) {
 
 // src/index.ts
 var Medal = class {
+  channels;
   emails;
   contacts;
   deals;
@@ -587,6 +654,7 @@ var Medal = class {
       timeout: options?.timeout ?? 3e4,
       userAgent: "medalsocial-sdk/1.0.0 (+https://github.com/Medal-Social/MedalSocial)"
     });
+    this.channels = new Channels(client);
     this.emails = new Emails(client);
     this.contacts = new Contacts(client);
     this.deals = new Deals(client);
@@ -604,6 +672,7 @@ var src_default = Medal;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseClient,
+  Channels,
   Contacts,
   DEFAULT_WEBHOOK_TOLERANCE_MS,
   Deals,