@medalsocial/sdk 1.5.0 → 1.7.0

package/dist/src/index.d.mts

@@ -1,51 +1,28 @@
 export { components as OpenApiComponents, operations as OpenApiOperations, paths as OpenApiPaths } from './openapi.generated.mjs';
 
-/** Configuration for the low-level HTTP client. */
-interface ClientConfig {
-    baseUrl: string;
-    token: string;
-    workspaceId?: string;
-    timeout: number;
-    userAgent: string;
+/** Successful API response wrapper */
+interface ApiResponse<T> {
+    data: T;
 }
-/** 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;
+/** Paginated API response */
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        has_more: boolean;
+        next_cursor: string | null;
+    };
 }
-/**
- * Low-level HTTP client used by all resource classes.
- * Handles authentication, retries, timeout, and error parsing.
- */
-declare class BaseClient {
-    /** Resolved client configuration. */
-    readonly config: ClientConfig;
-    constructor(config: ClientConfig);
-    /** 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, options?: RequestOptions): Promise<T>;
-    /** Execute an authenticated PATCH request with a JSON body. */
-    patch<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
-    /** Execute an authenticated DELETE request. */
-    delete<T>(path: string, options?: RequestOptions): Promise<T>;
-    private writeHeaders;
-    private buildUrl;
-    private request;
+/** API error thrown by the client */
+declare class MedalApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+/** Pagination options for list endpoints */
+interface PaginationOptions {
+    limit?: number;
+    cursor?: string;
 }
 
 /** Lifecycle status of a hosted connect link. */
@@ -91,8 +68,8 @@ interface ConnectLink {
     /** Unix timestamp in milliseconds. */
     created_at: number;
 }
-/** Filters for listing connect links. */
-interface ListConnectLinksOptions {
+/** Filters and cursor pagination for listing connect links. */
+interface ListConnectLinksOptions extends PaginationOptions {
     channel_type?: string;
     status?: ConnectLinkStatus;
 }
@@ -120,35 +97,1008 @@ interface ChannelConnectionDisconnectResult {
     state: "disconnected";
 }
 
-/** Successful API response wrapper */
-interface ApiResponse<T> {
-    data: T;
+/** 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;
 }
-/** Paginated API response */
-interface PaginatedResponse<T> {
-    data: T[];
-    pagination: {
-        has_more: boolean;
-        next_cursor: string | null;
+/**
+ * Outbound delivery state of a helpdesk message.
+ *
+ * - `pending` — queued for the channel, not handed off yet.
+ * - `sent` — handed to the channel provider, no confirmation yet.
+ * - `delivered` — the channel confirmed delivery to the customer.
+ * - `failed` — delivery failed; see `delivery_error` on the message.
+ */
+type MessageDeliveryStatus = "pending" | "sent" | "delivered" | "failed";
+/** 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;
+    /**
+     * Outbound delivery state, or `null` for inbound messages and internal
+     * notes — neither is ever sent to a channel, so neither has delivery state.
+     *
+     * **A `201` from `helpdesk.replies.create` means the reply was ACCEPTED, not
+     * delivered.** The channel hand-off happens asynchronously afterwards: poll
+     * this field (or subscribe to the `helpdesk.message_delivery_updated`
+     * webhook event, which carries the same values) to learn whether the message
+     * actually reached the customer.
+     */
+    delivery_status: MessageDeliveryStatus | null;
+    /**
+     * Last send error for a `failed` outbound message, or `null` when there is
+     * no error to report (including on inbound messages and internal notes).
+     */
+    delivery_error: string | null;
+    /** 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;
+}
+
+/** 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.
+ *
+ * `id` is the same value sent as the `X-Medal-Delivery-Id` and
+ * `Idempotency-Key` headers on the outbound request, so you can join your own
+ * receiving log to this listing exactly.
+ *
+ * **Deliveries never carry payload bodies.** The event payload can contain
+ * customer PII, so it is not returned here — use the correlation fields below
+ * to look the subject up through the regular API instead.
+ *
+ * All correlation fields (`resource_id`, `conversation_id`, `message_id`,
+ * `connection_ref`, `channel`, `channel_connection_id`) are derived from the
+ * stored event and **fail closed to `null`** whenever no canonical event
+ * exists for the delivery — e.g. `test.ping` deliveries, or events that have
+ * aged out of retention. Always null-check before using them.
+ */
+interface WebhookDelivery {
+    id: string;
+    event_type: string;
+    /**
+     * Primary subject id of the announced event (a message id for message
+     * events, a connection id for channel lifecycle events, …), or `null`.
+     */
+    resource_id: string | null;
+    /** Helpdesk conversation the event belongs to, or `null`. */
+    conversation_id: string | null;
+    /** Helpdesk message the event belongs to, or `null`. */
+    message_id: string | null;
+    /** Opaque connection reference carried by the event, or `null`. */
+    connection_ref: string | null;
+    /** Channel type (e.g. `telegram_inbox`, `widget`), or `null`. */
+    channel: string | null;
+    /** Channel connection the event belongs to, or `null`. */
+    channel_connection_id: string | null;
+    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.
+ *
+ * This endpoint is **not** cursor-paginated — it returns the most recent
+ * deliveries only, capped by `limit`. There is no `cursor` parameter; to keep
+ * a durable record, ingest deliveries as they arrive (or poll and de-duplicate
+ * on the delivery `id`).
+ */
+interface ListDeliveriesOptions {
+    limit?: number;
+}
+/** Result returned after queuing a test delivery (HTTP 202). */
+interface WebhookTestResult {
+    delivery_id: string;
+    status: string;
+}
+
+/**
+ * Capability confirmation types.
+ *
+ * Medal's confirmable write routes require BOTH an `Idempotency-Key` and an
+ * `X-Capability-Confirmation` token whenever the calling credential holds the
+ * capability scope *directly* — which is the case for every correctly-scoped
+ * partner key and OAuth grant. (API keys carrying only legacy scopes are
+ * exempt.) The token is minted by `POST /api/v1/capability-confirmations` and
+ * is bound to the workspace, the auth subject, the HTTP method + path, the
+ * capability's required scopes, and the idempotency key.
+ */
+/**
+ * Confirmable capability ids backing the write routes this SDK exposes.
+ *
+ * Mirrors the server-side capability registry. Each id maps to exactly one
+ * method + path template — see {@link CAPABILITY_ROUTES}.
+ */
+declare const CAPABILITY_IDS: readonly ["channel.connect_link.create.execute", "channel.connect_link.revoke.execute", "channel.connection.disconnect.execute", "helpdesk.conversation.reply.execute", "helpdesk.conversation.update.execute", "helpdesk.webhook.create.execute", "helpdesk.webhook.update.execute", "helpdesk.webhook.delete.execute"];
+/** A confirmable capability id backing an SDK write route. */
+type CapabilityId = (typeof CAPABILITY_IDS)[number];
+/** The API route a capability confirms, as registered server-side. */
+interface CapabilityRoute {
+    method: "POST" | "PATCH" | "DELETE";
+    /** Path template; `{id}` is filled from `path_params.id`. */
+    path_template: string;
+}
+/**
+ * Method + path template for each confirmable capability.
+ *
+ * The server resolves the same mapping from its capability registry — this
+ * copy exists so the SDK can build human-readable previews and supply
+ * `path_params` without a round trip.
+ */
+declare const CAPABILITY_ROUTES: Record<CapabilityId, CapabilityRoute>;
+/** Primitive accepted as a capability path parameter value. */
+type CapabilityPathParamValue = string | number | boolean;
+/** Input for `POST /api/v1/capability-confirmations`. */
+interface IssueCapabilityConfirmationInput {
+    /**
+     * Capability to confirm. Unknown ids are rejected with
+     * `CAPABILITY_NOT_FOUND`; read-only or non-confirmable capabilities with
+     * `CAPABILITY_NOT_CONFIRMABLE`.
+     */
+    capability_id: CapabilityId | (string & {});
+    /**
+     * Concrete `/api/v1/...` path the token should be bound to. Optional when
+     * the capability has exactly one API target (all capabilities in
+     * {@link CAPABILITY_ROUTES} do); required when it has several. Must match a
+     * path built from the capability's own templates.
+     */
+    api_path?: string;
+    /** Values for the capability path template's parameters, e.g. `{ id: 'wh_1' }`. */
+    path_params?: Record<string, CapabilityPathParamValue>;
+    /**
+     * The exact `Idempotency-Key` you will send on the confirmed write. The
+     * token is bound to it — a mismatch is rejected. Required for every
+     * capability in {@link CAPABILITY_ROUTES}.
+     */
+    idempotency_key?: string;
+    /**
+     * Human-readable description of the action being approved (1–4000 chars).
+     * This is the text your user saw and approved, and it is retained for audit.
+     */
+    preview_summary: string;
+    /**
+     * Must be `true`.
+     *
+     * **This asserts that a human on your side approved this specific action.**
+     * Do not send it to rubber-stamp unattended writes — it is the audit record
+     * that a person, not a script, authorised the change.
+     */
+    user_approved: true;
+}
+/** A minted capability confirmation token. */
+interface CapabilityConfirmation {
+    /** Send this as the `X-Capability-Confirmation` header on the write. */
+    confirmation_token: string;
+    token_type: "medal_capability_confirmation";
+    capability_id: string;
+    /** HTTP method the token is bound to. */
+    method: string;
+    /** Concrete API path the token is bound to. */
+    path: string;
+    /** Capability scopes the token was minted against. */
+    required_scopes: string[];
+    /** Idempotency key the token is bound to, or `null` if it was minted unbound. */
+    idempotency_key: string | null;
+    /** Lifetime in seconds (60–900). */
+    expires_in: number;
+    /** ISO-8601 expiry timestamp. */
+    expires_at: string;
+    /** Echo of the submitted `preview_summary`. */
+    preview_summary: string;
+}
+/**
+ * Request body type for each confirmable capability.
+ *
+ * `undefined` for routes that take no request body (the `DELETE` routes).
+ */
+interface CapabilityWriteBodies {
+    "channel.connect_link.create.execute": CreateConnectLinkInput;
+    "channel.connect_link.revoke.execute": undefined;
+    "channel.connection.disconnect.execute": undefined;
+    "helpdesk.conversation.reply.execute": CreateReplyInput;
+    "helpdesk.conversation.update.execute": UpdateConversationInput;
+    "helpdesk.webhook.create.execute": CreateWebhookInput;
+    "helpdesk.webhook.update.execute": UpdateWebhookInput;
+    "helpdesk.webhook.delete.execute": undefined;
+}
+/**
+ * A capability paired with the request body for that exact route.
+ *
+ * Modelled as a discriminated union rather than two independent parameters so
+ * the pair cannot be decoupled: passing a `helpdesk.conversation.reply.execute`
+ * id alongside a webhook payload is a compile error, even when the id's static
+ * type is the full {@link CapabilityId} union.
+ */
+type CapabilityWriteRequest = {
+    [K in CapabilityId]: {
+        /** Capability about to be confirmed. */
+        capabilityId: K;
+        /** The request body of the pending write, or `undefined` for `DELETE` routes. */
+        body: CapabilityWriteBodies[K];
     };
+}[CapabilityId];
+/** Fields common to every {@link AutoConfirmContext} variant. */
+interface AutoConfirmContextBase {
+    /** HTTP method of the write. */
+    method: string;
+    /** Resolved API path of the write (path params substituted + encoded). */
+    path: string;
+    /** Path parameters used to resolve `path`, if any. */
+    pathParams?: Record<string, CapabilityPathParamValue>;
+    /** Idempotency key that will be bound to the token and sent on the write. */
+    idempotencyKey: string;
 }
-/** API error thrown by the client */
-declare class MedalApiError extends Error {
-    readonly status: number;
-    readonly code: string;
-    readonly details?: unknown;
-    constructor(status: number, code: string, message: string, details?: unknown);
+/**
+ * Context handed to an {@link AutoConfirmOptions.previewSummary} callback.
+ *
+ * A discriminated union on `capabilityId` — narrow on it to get the exact
+ * `body` type for that route:
+ *
+ * ```ts
+ * previewSummary: (ctx) => {
+ *   if (ctx.capabilityId === 'helpdesk.conversation.reply.execute') {
+ *     // ctx.body is CreateReplyInput here
+ *     return `Reply to ${ctx.body.conversation_id}: ${ctx.body.body}`;
+ *   }
+ *   return `${ctx.method} ${ctx.path}`;
+ * }
+ * ```
+ *
+ * `body` is the **exact object you passed to the SDK method**, by reference
+ * and unmodified — it is your own payload, so there is nothing to redact and
+ * nothing crosses a tenant boundary. Treat it as read-only: mutating it from
+ * the callback would change what is actually sent.
+ */
+type AutoConfirmContext = AutoConfirmContextBase & CapabilityWriteRequest;
+/**
+ * Opt-in auto-confirmation.
+ *
+ * When configured, the SDK mints an idempotency key and a confirmation token
+ * for you before each confirmable write, then attaches both headers.
+ *
+ * **This is not a bypass.** Every minted token carries
+ * `user_approved: true`, which asserts that *your own user* approved that
+ * specific action — the `preview_summary` you return is the audit record of
+ * what they approved. Only enable this on a code path where a human really did
+ * approve the write. Never wire it into unattended automation.
+ */
+interface AutoConfirmOptions {
+    /**
+     * Build the `preview_summary` for the pending write. Must return a
+     * non-empty string describing what the user approved; returning blank text
+     * throws instead of asserting an approval that has no description.
+     *
+     * The context includes the pending request `body`, so the summary can name
+     * the specific action rather than the route — narrow on
+     * `context.capabilityId` to get the exact payload type. Prefer a
+     * payload-aware summary: `"Reply to conv_1: 'Refund issued'"` is an audit
+     * record, `"POST /api/v1/helpdesk/replies"` is not.
+     *
+     * The server caps `preview_summary` at 4000 characters, so summarise the
+     * payload rather than serialising it wholesale.
+     */
+    previewSummary: (context: AutoConfirmContext) => string;
+}
+
+/** Configuration for the low-level HTTP client. */
+interface ClientConfig {
+    baseUrl: string;
+    token: string;
+    workspaceId?: string;
+    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;
+    /**
+     * Opt in to (or out of) automatic capability confirmation for this call.
+     *
+     * Supply `{ previewSummary }` to have the SDK mint the idempotency key and
+     * the `X-Capability-Confirmation` token itself; pass `false` to suppress a
+     * client-level `autoConfirmCapabilities` default. Defaults to the client
+     * setting, which itself defaults to OFF.
+     *
+     * Auto-confirmation sends `user_approved: true` on your behalf, asserting
+     * that a human on your side approved this exact action — only use it where
+     * that is true.
+     *
+     * Ignored on routes that do not require a capability confirmation.
+     */
+    autoConfirm?: AutoConfirmOptions | false;
+}
+/**
+ * Low-level HTTP client used by all resource classes.
+ * Handles authentication, retries, timeout, and error parsing.
+ */
+declare class BaseClient {
+    /** Resolved client configuration. */
+    readonly config: ClientConfig;
+    constructor(config: ClientConfig);
+    /** 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, options?: RequestOptions): Promise<T>;
+    /**
+     * Execute a POST that must never execute twice, guaranteeing an
+     * `Idempotency-Key`.
+     *
+     * {@link BaseClient.post} retries 429 and 5xx automatically, so a write
+     * whose transaction committed before the gateway failed would otherwise be
+     * submitted a second time — booking the same slot twice. A key turns that
+     * retry into a replay: the server keys on the key, the workspace, and the
+     * method+path, and answers a repeat with the stored response, or 409 while
+     * the first attempt is still in flight. Either way the write happens once.
+     *
+     * The key is minted ONCE here, outside the retry loop in `request`, so every
+     * attempt of the same logical call carries the same value — a key minted per
+     * attempt would deduplicate nothing. A caller-supplied key always wins, so
+     * callers keeping their own records stay in control. See
+     * {@link resolveIdempotencyKey} for what counts as supplied.
+     */
+    postOnce<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /** Execute an authenticated PATCH request with a JSON body. */
+    patch<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    /** Execute an authenticated DELETE request. */
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    private writeHeaders;
+    private buildUrl;
+    private request;
+}
+
+/**
+ * A timestamp on the way IN to the booking API: Unix milliseconds, or an
+ * ISO 8601 date-time string.
+ *
+ * Both are accepted so a caller can book by echoing back the `start_ts` of a
+ * slot it just fetched — responses render every timestamp as ISO, requests
+ * take either. The API normalises to milliseconds server-side.
+ */
+type BookingTimestampInput = number | string;
+/** Lifecycle state of a booking. */
+type BookingStatus = "pending" | "confirmed" | "completed" | "cancelled" | "no_show";
+/**
+ * Who cancelled a booking. `staff` is a cancel made through
+ * `bookings.cancel(id)`, `customer` one made through
+ * `bookings.manage.cancel(token)`, `system` an automated one.
+ */
+type BookingCancelledBy = "customer" | "staff" | "system";
+/** Payment state of a booking. */
+type BookingPaymentStatus = "none" | "reserved" | "captured" | "refunded";
+/** Surface a booking was created through. API-created bookings are `api`. */
+type BookingCreatedVia = "web" | "dashboard" | "walk_in" | "api";
+/** Kind of bookable resource a booking lands on. */
+type BookingResourceType = "staff" | "room" | "equipment";
+/**
+ * One appointment: a contact holding a service slot on a resource.
+ *
+ * Money is `amount_ore` — an INTEGER number of øre, never a float and never
+ * kroner. Timestamps are ISO 8601 strings.
+ */
+interface Booking {
+    id: string;
+    contact_id: string | null;
+    service_id: string | null;
+    resource_id: string | null;
+    start_ts: string | null;
+    end_ts: string | null;
+    booked_for_name: string | null;
+    /** Birth year (not a birthdate) of whoever the appointment is for. */
+    booked_for_birth_year: number | null;
+    /** Shared by every booking created in the same party request. */
+    party_sequence_id: string | null;
+    status: BookingStatus;
+    cancelled_by: BookingCancelledBy | null;
+    cancel_reason: string | null;
+    /** Set on the booking a reschedule created, pointing at the one it replaced. */
+    rescheduled_from_id: string | null;
+    payment_status: BookingPaymentStatus;
+    /** Price in integer øre. */
+    amount_ore: number | null;
+    /** Customer-visible note. */
+    notes: string | null;
+    /** Staff-only note; never shown to the customer. */
+    internal_notes: string | null;
+    created_via: BookingCreatedVia | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+/** A bookable service in the workspace catalogue. */
+interface BookingService {
+    id: string;
+    name: string | null;
+    description: string | null;
+    category: string | null;
+    duration_minutes: number | null;
+    buffer_before_minutes: number | null;
+    buffer_after_minutes: number | null;
+    /** Price in integer øre. */
+    price_ore: number | null;
+    weekend_surcharge_pct: number | null;
+    /** Resource types this service needs, e.g. `["staff"]`. */
+    resource_requirements: string[];
+    bookable_online: boolean;
+    max_per_booking: number | null;
+    color: string | null;
+    sort_order: number | null;
+    active: boolean;
+    created_at: string | null;
+    updated_at: string | null;
+}
+/** Who or what performs a service: a staff member, a room, or equipment. */
+interface BookingResource {
+    id: string;
+    type: BookingResourceType | null;
+    name: string | null;
+    photo_url: string | null;
+    bio: string | null;
+    /** Services this resource can perform. */
+    service_ids: string[];
+    capacity: number | null;
+    sort_order: number | null;
+    active: boolean;
+    created_at: string | null;
+    updated_at: string | null;
+}
+/** One free slot returned by `bookings.availability(...)`. */
+interface BookingSlot {
+    start_ts: string | null;
+    end_ts: string | null;
+    resource_id: string | null;
+}
+/**
+ * One date a service can be booked on, from `bookings.schedule(...)`.
+ *
+ * `date` is the workspace's own calendar date (`YYYY-MM-DD`), not a timestamp.
+ * `last_start_ts` is the last start this service could occupy on that date —
+ * not the closing time; a 30-minute service at a salon closing 17:00 has its
+ * last start at 16:30 — and is `null` for a date with posted hours that is
+ * shut outright (a public holiday). A date ABSENT from the list is closed.
+ */
+interface BookingScheduleDay {
+    date: string | null;
+    opens_ts: string | null;
+    closes_ts: string | null;
+    last_start_ts: string | null;
+}
+/** One line of a party booking — a single service on a single slot. */
+interface CreateBookingItemInput {
+    service_id: string;
+    /** Leave unset to let the engine pick a free resource. */
+    resource_id?: string;
+    start_ts: BookingTimestampInput;
+    booked_for_name?: string;
+    /** Birth year (not a birthdate) of whoever the appointment is for. */
+    booked_for_birth_year?: number;
+}
+/** The person the booking is made under. Phone is the CRM dedupe key. */
+interface BookingContactInput {
+    phone: string;
+    email?: string;
+    name?: string;
+}
+/**
+ * Input for `bookings.create(...)`. `items` is a PARTY — one request books a
+ * whole family in one all-or-nothing transaction (max 50 items).
+ */
+/** Provenance an API caller may claim. `dashboard` and `walk_in` are staff-only and rejected. */
+type BookingClaimableCreatedVia = "web" | "api";
+interface CreateBookingInput {
+    items: CreateBookingItemInput[];
+    contact: BookingContactInput;
+    notes?: string;
+    /**
+     * Defaults to `api`. A workspace's OWN website should send `web`, so "how
+     * many bookings did the site bring in" is answerable; integrations leave it
+     * unset. `dashboard` and `walk_in` are refused with 400 — a bearer token
+     * proves which workspace is calling, not that a member typed it in.
+     */
+    created_via?: BookingClaimableCreatedVia;
+}
+/** One entry of `BookingCreateResult.bookings`, in request order. */
+interface CreatedBooking {
+    id: string;
+    /**
+     * Show-once secret for the customer's manage link.
+     *
+     * Only its SHA-256 hash is stored, so this response is the ONLY place it
+     * ever appears — persist it here or it is gone. It is **absent** (the key is
+     * dropped, not nulled) when the response is replayed from an
+     * `Idempotency-Key`, since tokens are redacted from replays.
+     *
+     * A lost token cannot be recovered: {@link Booking} carries no token field,
+     * so re-reading the booking will not produce it. Either reschedule the
+     * booking (which mints a fresh token) or have staff act on it by id.
+     */
+    manage_token?: string;
+}
+/** Result returned after creating a booking or party. */
+interface BookingCreateResult {
+    bookings: CreatedBooking[];
+    contact_id: string;
+}
+/** Result of a cancel or no-show. */
+interface BookingActionResult {
+    success: true;
+}
+/**
+ * Result of a reschedule. A reschedule cancels the old booking and inserts a
+ * new one, so `booking_id` is a NEW id — the one you passed in is now cancelled.
+ */
+interface BookingRescheduleResult {
+    success: true;
+    booking_id: string;
+    /**
+     * Freshly minted manage token for the new booking. Same show-once rule as
+     * {@link CreatedBooking.manage_token}: absent on an idempotent replay.
+     */
+    manage_token?: string;
+}
+/**
+ * What the holder of a manage token may see and do — the payload behind a
+ * customer's "manage my booking" link.
+ *
+ * `can_cancel` / `can_reschedule` already account for the workspace's policy
+ * windows, so honour them rather than re-deriving from the window hours.
+ */
+interface ManageSummary {
+    booking_id: string;
+    contact_id: string | null;
+    status: BookingStatus | null;
+    cancelled_by: BookingCancelledBy | null;
+    cancel_reason: string | null;
+    rescheduled_from_id: string | null;
+    start_ts: string | null;
+    end_ts: string | null;
+    service_id: string | null;
+    service_name: string | null;
+    resource_id: string | null;
+    resource_name: string | null;
+    booked_for_name: string | null;
+    party_sequence_id: string | null;
+    /** Price in integer øre. */
+    amount_ore: number | null;
+    payment_status: BookingPaymentStatus | null;
+    /** IANA zone the booking's local times should be rendered in. */
+    time_zone: string | null;
+    cancel_window_hours: number | null;
+    reschedule_window_hours: number | null;
+    can_cancel: boolean;
+    can_reschedule: boolean;
+}
+/** The annotation fields a booking accepts. */
+interface BookingNoteFields {
+    /** Customer-visible note. Pass `""` to clear it. */
+    notes?: string;
+    /** Staff-only note; never shown to the customer. Pass `""` to clear it. */
+    internal_notes?: string;
+}
+/**
+ * Input for annotating a booking.
+ *
+ * At least one of `notes` or `internal_notes` must be present: the API's
+ * `updateBookingSchema` refuses a body carrying neither with a 400, so the
+ * union turns `update(id, {})` into a compile error rather than a wasted round
+ * trip. Note that `""` is a meaningful value — it clears the field — which is
+ * why the constraint is on presence, not on emptiness.
+ */
+type UpdateBookingInput = (BookingNoteFields & {
+    notes: string;
+}) | (BookingNoteFields & {
+    internal_notes: string;
+});
+/** Optional reason recorded against a cancellation. */
+interface CancelBookingInput {
+    reason?: string;
+}
+/** Input for moving a booking to a new slot, and optionally a new resource. */
+interface RescheduleBookingInput {
+    new_start_ts: BookingTimestampInput;
+    new_resource_id?: string;
+}
+/**
+ * Pagination for a bookings page.
+ *
+ * `truncated` is the extra statement this list carries: the underlying read is
+ * capped, and when the cap binds there are matching bookings that no cursor
+ * from this call reaches. Narrow `from_ts`/`to_ts` when you see it.
+ */
+interface BookingsPagination {
+    has_more: boolean;
+    next_cursor: string | null;
+    truncated: boolean;
+}
+/** A page of bookings. Carries `truncated` on top of the usual pagination. */
+interface BookingsPage {
+    data: Booking[];
+    pagination: BookingsPagination;
+}
+/** Options for listing bookings with pagination and filters. */
+interface ListBookingsOptions extends PaginationOptions {
+    from_ts?: BookingTimestampInput;
+    to_ts?: BookingTimestampInput;
+    status?: BookingStatus;
+    resource_id?: string;
+}
+/** Options for listing the service catalogue. The endpoint is not paginated. */
+interface ListBookingServicesOptions {
+    /** Include services with `active: false`. Defaults to active-only. */
+    include_inactive?: boolean;
+}
+/**
+ * Options for `bookings.schedule(...)`. Same shape as availability, and for
+ * the same reason: the last bookable start depends on the service's duration
+ * and buffers, so a 30-minute cut and a 90-minute colour run out at different
+ * hours of the same afternoon.
+ */
+interface BookingScheduleOptions {
+    service_id: string;
+    from_ts: BookingTimestampInput;
+    /** Must be after `from_ts`. */
+    to_ts: BookingTimestampInput;
+    /** Restrict to one resource's hours. */
+    resource_id?: string;
+}
+/** Options for querying free slots. The window is required and half-open. */
+interface BookingAvailabilityOptions {
+    service_id: string;
+    from_ts: BookingTimestampInput;
+    /** Must be after `from_ts`. */
+    to_ts: BookingTimestampInput;
+    /** Restrict slots to one resource. Defaults to every capable resource. */
+    resource_id?: string;
+}
+
+/**
+ * Customer-side booking management, addressed by the show-once manage token
+ * from `bookings.create(...)` rather than by booking id.
+ *
+ * These are NOT the staff routes with a different lookup key: possession of
+ * the token is the customer's own authorization, so the workspace's cancel and
+ * reschedule windows are ENFORCED here (they are bypassed on
+ * `bookings.cancel` / `bookings.reschedule`), and a cancel is attributed to
+ * the customer rather than to staff. Relay a customer's click on their
+ * confirmation-email link through these; act as the business through the
+ * id-addressed methods.
+ */
+declare class BookingsManage {
+    private client;
+    constructor(client: BaseClient);
+    /**
+     * Read what the holder of a manage token may see and do. Honour
+     * `can_cancel` / `can_reschedule` — they already apply the policy windows.
+     */
+    get(token: string): Promise<ApiResponse<ManageSummary>>;
+    /** Cancel on the customer's behalf. Rejected outside the cancel window. */
+    cancel(token: string, input?: CancelBookingInput, options?: RequestOptions): Promise<ApiResponse<BookingActionResult>>;
+    /**
+     * Move the booking on the customer's behalf. Rejected outside the reschedule
+     * window. Returns a NEW booking id and a new manage token — the old token
+     * stops working, so relay the new one into whatever link you send next.
+     */
+    reschedule(token: string, input: RescheduleBookingInput, options?: RequestOptions): Promise<ApiResponse<BookingRescheduleResult>>;
+}
+/**
+ * Appointment bookings: the service catalogue, free slots, and the bookings
+ * themselves.
+ *
+ * Every method here acts as the BUSINESS — policy windows are bypassed and a
+ * cancel is recorded against staff. To relay a customer's own action on their
+ * confirmation-email link, use {@link Bookings.manage} instead.
+ *
+ * Money is always integer øre (`amount_ore`, `price_ore`). Timestamps come
+ * back as ISO 8601 strings; on the way in, either Unix milliseconds or an ISO
+ * string is accepted.
+ *
+ * @example
+ * ```ts
+ * const { data: slots } = await medal.bookings.availability({
+ *   service_id: "svc_1",
+ *   from_ts: Date.now(),
+ *   to_ts: Date.now() + 7 * 86_400_000,
+ * });
+ * const { data } = await medal.bookings.create({
+ *   items: [{ service_id: "svc_1", start_ts: slots[0].start_ts! }],
+ *   contact: { phone: "+4790000000", name: "Ida" },
+ * });
+ * ```
+ */
+declare class Bookings {
+    private client;
+    /** Customer-side actions addressed by manage token. */
+    readonly manage: BookingsManage;
+    constructor(client: BaseClient);
+    /** List the bookable service catalogue. Active-only unless asked otherwise. */
+    listServices(options?: ListBookingServicesOptions): Promise<ApiResponse<BookingService[]>>;
+    /** List the bookable resources — staff, rooms, and equipment. */
+    listResources(): Promise<ApiResponse<BookingResource[]>>;
+    /**
+     * List free slots for a service over a window. Slots reflect opening hours,
+     * time off, buffers, and existing bookings at the moment of the call — they
+     * are not held, so a slot can be taken before you book it.
+     */
+    availability(options: BookingAvailabilityOptions): Promise<ApiResponse<BookingSlot[]>>;
+    /**
+     * The dates a service can be booked on — the half `availability` cannot
+     * answer. Availability returns free slots and nothing else, so a closed day,
+     * an evening past closing and a fully booked day are all the same empty
+     * array. A date absent from this list is closed; on a listed date, compare
+     * `last_start_ts` against the clock to tell "too late today" from "full".
+     */
+    schedule(options: BookingScheduleOptions): Promise<ApiResponse<BookingScheduleDay[]>>;
+    /**
+     * List bookings with cursor-based pagination and optional filters.
+     *
+     * Check `pagination.truncated`: when true the read window was clipped and
+     * matching bookings exist that no cursor reaches — narrow `from_ts`/`to_ts`.
+     */
+    list(options?: ListBookingsOptions): Promise<BookingsPage>;
+    /**
+     * Book a party — every item succeeds or none do (max 50).
+     *
+     * Each created booking comes back with a `manage_token` exactly once; only
+     * its hash is stored, so persist it if you need the customer's manage link.
+     *
+     * Automatically idempotent: the SDK mints an `Idempotency-Key` so its own
+     * 5xx retries replay rather than book the slot twice. Supply
+     * `options.idempotencyKey` to deduplicate across your OWN retries too — the
+     * server keys on it for 24 hours, so re-sending the same key after a network
+     * timeout returns the original bookings instead of a second set.
+     */
+    create(input: CreateBookingInput, options?: RequestOptions): Promise<ApiResponse<BookingCreateResult>>;
+    /** Get a booking by ID. */
+    get(id: string): Promise<ApiResponse<Booking>>;
+    /**
+     * Annotate a booking. At least one of `notes` (customer-visible) or
+     * `internal_notes` (staff-only) is required; `""` clears a field.
+     */
+    update(id: string, input: UpdateBookingInput, options?: RequestOptions): Promise<ApiResponse<Booking>>;
+    /** Cancel as the business — the cancel window is bypassed. */
+    cancel(id: string, input?: CancelBookingInput, options?: RequestOptions): Promise<ApiResponse<BookingActionResult>>;
+    /**
+     * Move a booking as the business — the reschedule window is bypassed.
+     * Returns a NEW booking id and a new manage token; the old booking is
+     * cancelled and its token stops working.
+     */
+    reschedule(id: string, input: RescheduleBookingInput, options?: RequestOptions): Promise<ApiResponse<BookingRescheduleResult>>;
+    /** Mark a booking as a no-show. */
+    markNoShow(id: string, options?: RequestOptions): Promise<ApiResponse<BookingActionResult>>;
+}
+
+/**
+ * Mint short-lived capability confirmation tokens.
+ *
+ * Medal's confirmable write routes (connect links, channel connections,
+ * helpdesk replies/updates, webhook endpoint writes) require BOTH an
+ * `Idempotency-Key` and an `X-Capability-Confirmation` header when the calling
+ * credential holds the capability scope *directly* — which is the case for
+ * every correctly-scoped partner key. This resource issues that header value.
+ *
+ * @example Explicit flow
+ * ```ts
+ * const idempotencyKey = crypto.randomUUID();
+ * const { data: confirmation } = await medal.capabilityConfirmations.create({
+ *   capability_id: 'channel.connect_link.create.execute',
+ *   idempotency_key: idempotencyKey,
+ *   preview_summary: 'Mint a Telegram connect link for Acme Support',
+ *   user_approved: true, // a human on your side approved this exact action
+ * });
+ *
+ * await medal.channels.connectLinks.create(
+ *   { channel_type: 'telegram_inbox', label: 'Acme Support' },
+ *   { idempotencyKey, capabilityConfirmation: confirmation.confirmation_token },
+ * );
+ * ```
+ */
+declare class CapabilityConfirmations {
+    private client;
+    constructor(client: BaseClient);
+    /**
+     * Issue a confirmation token for one pending write.
+     *
+     * The token is bound to the workspace, the auth subject, the capability's
+     * method + path, its required scopes, and `idempotency_key` — so it is
+     * usable exactly once, for exactly the write it describes, and expires
+     * within 15 minutes.
+     *
+     * Setting `user_approved: true` asserts that a human on your side approved
+     * this specific action. `preview_summary` is what they approved, and is
+     * retained for audit — write it for a human reader, not a log parser.
+     *
+     * Deliberately unkeyed, unlike the writes it authorizes. Minting is not the
+     * state change the guarantee exists to protect: the write itself is already
+     * bound to `idempotency_key`, so a retry that mints a second token cannot
+     * produce a second write. Keying this call would instead park a credential
+     * designed to expire in 15 minutes inside a replay cache that answers for 24
+     * hours — a worse trade than the duplicate token it would avoid.
+     */
+    create(input: IssueCapabilityConfirmationInput): Promise<ApiResponse<CapabilityConfirmation>>;
 }
-/** Pagination options for list endpoints */
-interface PaginationOptions {
-    limit?: number;
-    cursor?: string;
+
+/**
+ * Resolves the `Idempotency-Key` + `X-Capability-Confirmation` pair required
+ * by confirmable write routes.
+ *
+ * Auto-confirmation is OFF unless the integrator opts in — either globally via
+ * the `Medal` constructor's `autoConfirmCapabilities`, or per call via
+ * `{ autoConfirm: { previewSummary } }`. When it is off this is a pass-through:
+ * whatever headers the caller supplied are what gets sent.
+ */
+declare class CapabilityConfirmer {
+    private confirmations;
+    private defaults?;
+    constructor(confirmations: CapabilityConfirmations, defaults?: AutoConfirmOptions | undefined);
+    /**
+     * Return the request options to use for a confirmable write, minting the
+     * idempotency key and confirmation token first when auto-confirm is active.
+     *
+     * `body` is the pending request payload (`undefined` for `DELETE` routes).
+     * It is handed to the `previewSummary` callback by reference so the summary
+     * can describe the specific action, not just the route — it is the caller's
+     * own payload, so it is passed through unmodified and unredacted.
+     */
+    prepare(request: CapabilityWriteRequest, pathParams?: Record<string, CapabilityPathParamValue>, options?: RequestOptions): Promise<RequestOptions | undefined>;
 }
 
 /** Mint, list, and revoke hosted connect links. */
 declare class ChannelConnectLinks {
     private client;
-    constructor(client: BaseClient);
+    private confirmer;
+    constructor(client: BaseClient, confirmer: CapabilityConfirmer);
     /**
      * Mint a single-use hosted connect link. Returns HTTP 201.
      *
@@ -159,19 +1109,46 @@ declare class ChannelConnectLinks {
      *
      * Requires the `channel.connect.manage` scope; OAuth callers additionally
      * need the workspace `admin` role.
+     *
+     * Automatically idempotent: an unkeyed retry mints a SECOND live single-use
+     * link for the same person, and only one of the two can ever be consumed —
+     * the other stays outstanding until it is revoked or expires. The key the
+     * confirmer chose is the key that goes out — a capability confirmation is
+     * bound to its idempotency key, so minting a fresh one here would invalidate
+     * the confirmation.
      */
     create(input: CreateConnectLinkInput, options?: RequestOptions): Promise<ApiResponse<ConnectLinkCreateResult>>;
-    /** List the workspace's connect links (tokens are never returned). */
-    list(options?: ListConnectLinksOptions): Promise<ApiResponse<ConnectLink[]>>;
+    /**
+     * List the workspace's connect links (tokens are never returned), newest
+     * first, with cursor-based pagination.
+     *
+     * `limit` defaults to 50 server-side and is capped at 100. Follow
+     * `pagination.next_cursor` while `pagination.has_more` is true.
+     *
+     * The `channel_type` / `status` filters are applied **within** each page,
+     * so a page may hold fewer than `limit` items while `has_more` is still
+     * true — drive the loop off `has_more`, never off the item count.
+     */
+    list(options?: ListConnectLinksOptions): Promise<PaginatedResponse<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[]>>;
+    private confirmer;
+    constructor(client: BaseClient, confirmer: CapabilityConfirmer);
+    /**
+     * List the workspace's channel connections (generic, channel-agnostic
+     * shape), newest first, with cursor-based pagination.
+     *
+     * `limit` defaults to 50 server-side and is capped at 100. Follow
+     * `pagination.next_cursor` while `pagination.has_more` is true. Rows that
+     * are not projectable as connections are dropped within the page, so a page
+     * may hold fewer than `limit` items while `has_more` is still true — drive
+     * the loop off `has_more`, never off the item count.
+     */
+    list(options?: PaginationOptions): Promise<PaginatedResponse<ChannelConnection>>;
     /**
      * Disconnect a connected channel account (best-effort platform logout, then
      * local revoke). Emits a `helpdesk.channel_disconnected` webhook event with
@@ -188,7 +1165,7 @@ declare class ChannelConnections {
 declare class Channels {
     readonly connectLinks: ChannelConnectLinks;
     readonly connections: ChannelConnections;
-    constructor(client: BaseClient);
+    constructor(client: BaseClient, confirmer?: CapabilityConfirmer);
 }
 
 /** A contact in the workspace CRM. */
@@ -315,8 +1292,16 @@ declare class Contacts {
     constructor(client: BaseClient);
     /** List contacts with cursor-based pagination and optional filters. */
     list(options?: ListContactsOptions): Promise<PaginatedResponse<Contact>>;
-    /** Create a new contact. Email must be unique in the workspace. */
-    create(input: CreateContactInput): Promise<ApiResponse<ContactCreateResult>>;
+    /**
+     * Create a new contact. Email must be unique in the workspace.
+     *
+     * Automatically idempotent: the SDK mints an `Idempotency-Key` so its own
+     * 5xx retries replay rather than run the create a second time. Uniqueness
+     * alone would not save you here — it turns the retry of a committed create
+     * into a spurious conflict, which reads as "the contact was not created".
+     * Supply `options.idempotencyKey` to deduplicate across your OWN retries too.
+     */
+    create(input: CreateContactInput, options?: RequestOptions): Promise<ApiResponse<ContactCreateResult>>;
     /** Get a contact by ID. */
     get(id: string): Promise<ApiResponse<Contact>>;
     /** Update one or more fields on a contact. */
@@ -325,10 +1310,23 @@ declare class Contacts {
     remove(id: string): Promise<ApiResponse<ContactRemoveResult>>;
     /** Get the activity timeline for a contact. */
     activities(id: string, options?: PaginationOptions): Promise<PaginatedResponse<Activity>>;
-    /** Add a note to a contact's timeline. */
-    addNote(id: string, input: AddNoteInput): Promise<ApiResponse<ContactNoteResult>>;
-    /** Bulk import contacts (max 500). Duplicates are skipped. */
-    import(contacts: ImportContactInput[]): Promise<ApiResponse<ImportContactsResult>>;
+    /**
+     * Add a note to a contact's timeline.
+     *
+     * Automatically idempotent: nothing about a note is unique, so an unkeyed
+     * retry appends the same text to the timeline twice. Supply
+     * `options.idempotencyKey` to deduplicate across your OWN retries too.
+     */
+    addNote(id: string, input: AddNoteInput, options?: RequestOptions): Promise<ApiResponse<ContactNoteResult>>;
+    /**
+     * Bulk import contacts (max 500). Duplicates are skipped.
+     *
+     * Automatically idempotent: the import is processed in chunks, so a retry
+     * after a partial failure re-walks the whole batch and reports `added` /
+     * `skipped` counts for a run that was not the first. Supply
+     * `options.idempotencyKey` to deduplicate across your OWN retries too.
+     */
+    import(contacts: ImportContactInput[], options?: RequestOptions): Promise<ApiResponse<ImportContactsResult>>;
 }
 
 /** A sponsorship or brand deal in the workspace. */
@@ -407,8 +1405,14 @@ declare class Deals {
     constructor(client: BaseClient);
     /** List deals with cursor-based pagination and optional filters. */
     list(options?: ListDealsOptions): Promise<PaginatedResponse<Deal>>;
-    /** Create a new deal. */
-    create(input: CreateDealInput): Promise<ApiResponse<DealCreateResult>>;
+    /**
+     * Create a new deal.
+     *
+     * Automatically idempotent: nothing about a deal is unique, so an unkeyed
+     * retry puts a second identical deal in the pipeline. Supply
+     * `options.idempotencyKey` to deduplicate across your OWN retries too.
+     */
+    create(input: CreateDealInput, options?: RequestOptions): Promise<ApiResponse<DealCreateResult>>;
     /** Get a deal by ID. */
     get(id: string): Promise<ApiResponse<Deal>>;
     /** Update one or more fields on a deal. Set contact_id to null to unlink. */
@@ -550,15 +1554,29 @@ declare class Emails {
     /**
      * 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.
+     *
+     * Automatically idempotent: the SDK mints an `Idempotency-Key` so its own
+     * 5xx retries replay rather than queue a second copy into someone's inbox —
+     * a send that already committed cannot be un-sent. Supply
+     * `options.idempotencyKey` to deduplicate across your OWN retries too.
+     *
+     * `input.idempotency_key` is the older, body-level form of the same control
+     * and still takes precedence server-side, so setting it keeps working
+     * unchanged.
      */
-    send(input: SendEmailInput): Promise<ApiResponse<EmailSendResult>>;
+    send(input: SendEmailInput, options?: RequestOptions): 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, HTTP 202). Each
      * queued recipient gets its own send id in `results` for `emails.get(id)`.
+     *
+     * Automatically idempotent — and this is the call where it matters most: an
+     * unkeyed retry of a batch that already committed sends up to 100 duplicate
+     * emails. Supply `options.idempotencyKey` to deduplicate across your OWN
+     * retries too.
      */
-    batch(input: BatchSendInput): Promise<ApiResponse<BatchSendSummary>>;
+    batch(input: BatchSendInput, options?: RequestOptions): Promise<ApiResponse<BatchSendSummary>>;
 }
 
 /** A workspace data export request and its current status. */
@@ -630,8 +1648,16 @@ interface CookieCategoryConsent {
 declare class Gdpr {
     private client;
     constructor(client: BaseClient);
-    /** Request a workspace data export. Runs asynchronously. */
-    requestExport(): Promise<ApiResponse<{
+    /**
+     * Request a workspace data export. Runs asynchronously.
+     *
+     * Automatically idempotent: the request is recorded and the export is
+     * scheduled in one step with no de-duplication of its own, so an unkeyed
+     * retry files a second subject-access request and runs a second full export
+     * of the workspace. Supply `options.idempotencyKey` to deduplicate across
+     * your OWN retries too.
+     */
+    requestExport(options?: RequestOptions): Promise<ApiResponse<{
         request_id: string;
         status: string;
     }>>;
@@ -639,105 +1665,36 @@ declare class Gdpr {
     listExports(): Promise<ApiResponse<GdprExport[]>>;
     /** Get the status of a specific export. */
     getExport(id: string): Promise<ApiResponse<GdprExport>>;
-    /** Record a GDPR consent decision for a contact by email. */
+    /**
+     * Record a GDPR consent decision for a contact by email.
+     *
+     * Deliberately unkeyed: a decision is stored once per
+     * (workspace, email, consent type) and overwritten in place, so re-sending
+     * the same body reaches the same state and returns the same record id.
+     */
     recordConsent(input: RecordConsentInput): Promise<ApiResponse<ConsentResult>>;
     /** Get all consent records for a contact by email. */
     getConsent(email: string): Promise<ApiResponse<ConsentRecord[]>>;
-    /** Record cookie consent from an external site (legacy endpoint). */
+    /**
+     * Record cookie consent from an external site (legacy endpoint).
+     *
+     * Deliberately unkeyed: this legacy route predates the versioned API and
+     * does not run the `Idempotency-Key` machinery, so a key here would be a
+     * header that changes nothing while implying a guarantee the endpoint cannot
+     * make. Treat a failed call as "unknown" and re-send only if a missing
+     * consent log matters more to you than a duplicate one.
+     */
     cookieConsent(input: CookieConsentInput): Promise<{
         success: boolean;
         logId?: string;
     }>;
 }
 
-/** 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);
+    private confirmer;
+    constructor(client: BaseClient, confirmer: CapabilityConfirmer);
     /** List/search conversations with cursor-based pagination and optional filters. */
     list(options?: ListConversationsOptions): Promise<PaginatedResponse<Conversation>>;
     /** Get a conversation by ID. */
@@ -750,12 +1707,21 @@ declare class HelpdeskConversations {
 /** Send operator replies (or internal notes) into conversations. */
 declare class HelpdeskReplies {
     private client;
-    constructor(client: BaseClient);
+    private confirmer;
+    constructor(client: BaseClient, confirmer: CapabilityConfirmer);
     /**
      * 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.
+     * Automatically idempotent: a reply is a message to a real person, and an
+     * unkeyed retry sends it to them twice. The key the confirmer chose is the
+     * key that goes out — a capability confirmation is bound to its idempotency
+     * key, so minting a fresh one here would invalidate the confirmation.
+     *
+     * Pass `options.idempotencyKey` to deduplicate across your OWN retries too.
+     * It is REQUIRED for capability-scoped tokens, which need it paired with a
+     * `capabilityConfirmation` — a generated key satisfies the pairing's key
+     * half only; the confirmation is still yours to supply (or to let
+     * `autoConfirm` mint).
      */
     create(input: CreateReplyInput, options?: RequestOptions): Promise<ApiResponse<ReplyCreateResult>>;
 }
@@ -763,7 +1729,7 @@ declare class HelpdeskReplies {
 declare class Helpdesk {
     readonly conversations: HelpdeskConversations;
     readonly replies: HelpdeskReplies;
-    constructor(client: BaseClient);
+    constructor(client: BaseClient, confirmer?: CapabilityConfirmer);
 }
 
 /** A post in the workspace (list view). */
@@ -850,8 +1816,14 @@ declare class Posts {
     constructor(client: BaseClient);
     /** List posts with cursor-based pagination and optional filters. */
     list(options?: ListPostsOptions): Promise<PaginatedResponse<Post>>;
-    /** Create a new post with content and target channels. */
-    create(input: CreatePostInput): Promise<ApiResponse<{
+    /**
+     * Create a new post with content and target channels.
+     *
+     * Automatically idempotent: the SDK mints an `Idempotency-Key` so its own
+     * 5xx retries replay rather than draft the post twice. Supply
+     * `options.idempotencyKey` to deduplicate across your OWN retries too.
+     */
+    create(input: CreatePostInput, options?: RequestOptions): Promise<ApiResponse<{
         id: string;
     }>>;
     /** Get a post by ID, including its per-channel variants. */
@@ -864,105 +1836,196 @@ declare class Posts {
     remove(id: string): Promise<ApiResponse<{
         success: boolean;
     }>>;
-    /** Schedule a post for future publication. */
+    /**
+     * Schedule a post for future publication.
+     *
+     * Deliberately unkeyed: re-sending the same `scheduled_at` for an
+     * already-scheduled post returns the original `workflow_id` rather than
+     * starting a second one, so a retried schedule cannot double-publish. A
+     * *different* time is rejected — unschedule first.
+     */
     schedule(id: string, input: SchedulePostInput): Promise<ApiResponse<ScheduleResult>>;
-    /** Publish a post immediately to all target channels. */
+    /**
+     * Publish a post immediately to all target channels.
+     *
+     * Deliberately unkeyed: publishing moves the post out of the set of statuses
+     * that may be published, so the retry of a publish that already committed is
+     * refused rather than posting a second time. It is refused with a 400 though
+     * — treat an error here as "check the post's status", not as "nothing
+     * happened".
+     */
     publish(id: string): Promise<ApiResponse<PublishResult>>;
     /** List connected publishing channels for this workspace. */
     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 scan — provide exactly ONE of `url`, `orgnr`, or `name`. */
+interface ScanCreateInput {
+    /** Website URL to scan directly (https is assumed when the scheme is missing). */
+    url?: string;
+    /** 9-digit Norwegian organisation number — resolved via the public registry. */
+    orgnr?: string;
+    /** Company name — resolved to the best registry match before scanning. */
+    name?: string;
 }
-/** Input for creating a webhook endpoint. */
-interface CreateWebhookInput {
-    /** Display name (max 100 characters). */
+/** Reference returned when a scan job is queued (HTTP 202). */
+interface ScanCreateResult {
+    id: string;
+    status: "pending" | string;
+    message?: string;
+}
+/** Lifecycle of an asynchronous scan job. */
+type ScanStatus = "pending" | "running" | "done" | "failed";
+/** A company-registry search hit from `scan.companies()`. */
+interface ScanCompany {
+    orgnr: string;
     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[];
+    org_form: string | null;
+    industry: string | null;
+    city: string | null;
+    website: string | null;
+}
+/** Nettskår sub-scores (0–100); null = the axis could not be measured. */
+interface ScanSubScores {
+    fart: number | null;
+    google: number | null;
+    ai: number | null;
+    trygghet: number | null;
+    omdomme: number | null;
 }
 /**
- * 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.
+ * The versioned scan findings payload. Shapes within are additive per
+ * `version`; string unions stay open (`| string`) so new detections never
+ * break consumers.
  */
-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;
+interface ScanResultPayload {
+    version: number;
+    /** Weighted composite score (0–100); null when nothing could be measured. */
+    nettskaar: number | null;
+    subScores: ScanSubScores;
+    registry?: {
+        orgnr: string;
+        navn: string;
+        organisasjonsform?: string;
+        naeringBeskrivelse?: string;
+        antallAnsatte?: number;
+        poststed?: string;
+    };
+    signals: {
+        version: number;
+        tech: string[];
+        pixels: string[];
+        consent: string[];
+        commerce: string[];
+        marketing?: string[];
+        social: Record<string, string | undefined>;
+        emailProvider?: string;
+        unreachable?: boolean;
+        inconclusive?: boolean;
+        dnsPending?: boolean;
+    };
+    pagespeed?: {
+        mobileScore?: number;
+        lcpMs?: number;
+        cls?: number;
+        inpMs?: number;
+        error?: string;
+    };
+    seo: {
+        titleLength: number;
+        metaDescriptionLength: number;
+        h1Count: number;
+        hasOg: boolean;
+        hasCanonical: boolean;
+        hreflangCount: number;
+        hasViewport: boolean;
+    };
+    ai: {
+        /** null = llms.txt could not be checked (unknown), false = confirmed absent. */
+        llmsTxtFound: boolean | null;
+        /** null = robots.txt could not be read (unknown, not "none blocked"). */
+        blockedBots: string[] | null;
+        jsonLdTypes: string[];
+        faqFound: boolean;
+    };
+    gdpr: {
+        /**
+         * true = tracking pixels load with no consent platform; false = clean or
+         * a consent platform is present; null = unknown (unreachable / JS-only).
+         */
+        trackingBeforeConsent: boolean | null;
+        cmp: string | null;
+        privacyPageFound: boolean;
+    };
+    mailAuth: {
+        spf: "ok" | "missing" | "unknown" | string;
+        dmarc: "ok" | "missing" | "unknown" | string;
+        dmarcPolicy?: string;
+    };
+    httpsOk: boolean;
 }
-/** A delivery attempt record for a webhook endpoint. */
-interface WebhookDelivery {
+/** A scan job as returned by `scan.get()`. */
+interface ScanJob {
     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;
+    status: ScanStatus | string;
+    input: ScanCreateInput;
+    resolved: {
+        orgnr?: string;
+        companyName?: string;
+        websiteUrl?: string;
+    } | null;
+    result: ScanResultPayload | null;
+    /** Public-safe failure code (`company_not_found`, `no_website`, …). */
+    error: string | null;
+    created_at: string | null;
+    finished_at: string | null;
 }
-/** Options for listing recent deliveries. */
-interface ListDeliveriesOptions {
-    limit?: number;
+/** Options for `scan.waitForResult()`. */
+interface WaitForScanOptions {
+    /** Poll interval in milliseconds. Default 2500. */
+    intervalMs?: number;
+    /** Give up after this long. Default 120000 (scans normally finish in ~30 s). */
+    timeoutMs?: number;
 }
-/** Result returned after queuing a test delivery (HTTP 202). */
-interface WebhookTestResult {
-    delivery_id: string;
-    status: string;
+
+/**
+ * Company & website scans (Nettsjekk) — score a Norwegian company's web
+ * presence (performance, SEO, GDPR consent, AI visibility, mail auth) from a
+ * URL, an organisation number, or a company name.
+ */
+declare class Scan {
+    private client;
+    constructor(client: BaseClient);
+    /**
+     * Queue a scan. Provide exactly one of `url`, `orgnr`, or `name`.
+     * Runs asynchronously — poll with `get()` or use `waitForResult()`.
+     *
+     * Automatically idempotent: a scan job is queued the moment it is created,
+     * so an unkeyed retry starts a second crawl of the same site and returns an
+     * id for a job that duplicates one already running. Supply
+     * `options.idempotencyKey` to deduplicate across your OWN retries too.
+     *
+     * @throws Error before any request when zero or several selectors are set —
+     * the server would reject the body anyway; failing locally is clearer.
+     */
+    create(input: ScanCreateInput, options?: RequestOptions): Promise<ApiResponse<ScanCreateResult>>;
+    /** Get a scan job's status and, once done, its findings payload. */
+    get(id: string): Promise<ApiResponse<ScanJob>>;
+    /** Search the Norwegian company registry by name (typeahead, top 5 hits). */
+    companies(q: string): Promise<ApiResponse<ScanCompany[]>>;
+    /**
+     * Poll a scan until it settles. Resolves with the job for both `done` and
+     * `failed` (check `job.error`); throws only when the deadline passes while
+     * the scan is still pending/running.
+     */
+    waitForResult(id: string, options?: WaitForScanOptions): Promise<ScanJob>;
 }
 
 /** Manage webhook endpoints and inspect their deliveries. */
 declare class Webhooks {
     private client;
-    constructor(client: BaseClient);
+    private confirmer;
+    constructor(client: BaseClient, confirmer?: CapabilityConfirmer);
     /** List all webhook endpoints in the workspace. */
     list(): Promise<ApiResponse<WebhookEndpoint[]>>;
     /**
@@ -976,6 +2039,13 @@ declare class Webhooks {
      * `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).
+     *
+     * Automatically idempotent: a duplicate endpoint is not a stray row, it is a
+     * second copy of every future delivery to the same URL, forever. The key the
+     * confirmer chose is the key that goes out — a capability confirmation is
+     * bound to its idempotency key, so minting a fresh one here would invalidate
+     * the confirmation. That the SDK now always sends a key is also what makes
+     * the replay-without-secret case above reachable on a plain 5xx retry.
      */
     create(input: CreateWebhookInput, options?: RequestOptions): Promise<ApiResponse<WebhookEndpoint>>;
     /** Get a webhook endpoint by ID. */
@@ -991,7 +2061,14 @@ declare class Webhooks {
     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. */
+    /**
+     * Queue a signed `test.ping` delivery to the endpoint. Returns HTTP 202.
+     *
+     * Deliberately unkeyed: a duplicate ping is the one duplicate that costs
+     * nothing. Real deliveries are retried too, so any endpoint worth pointing at
+     * already tolerates receiving the same event twice — that is what this call
+     * exists to prove.
+     */
     test(id: string): Promise<ApiResponse<WebhookTestResult>>;
 }
 
@@ -1227,6 +2304,37 @@ interface MedalOptions {
      * OAuth tokens can access multiple workspaces, so you must specify which one.
      */
     workspaceId?: string;
+    /**
+     * Opt in to automatic capability confirmation for confirmable writes.
+     * **Defaults to OFF.**
+     *
+     * Medal's confirmable write routes (connect links, channel connections,
+     * helpdesk replies/updates, webhook endpoint writes) require BOTH an
+     * `Idempotency-Key` and an `X-Capability-Confirmation` token whenever the
+     * credential holds the capability scope directly — which is the case for
+     * every correctly-scoped partner key. With this option set, the SDK mints
+     * both for you before each such write instead of making you hand-roll
+     * `POST /api/v1/capability-confirmations`.
+     *
+     * **Read before enabling:** each minted token carries `user_approved: true`,
+     * which asserts to Medal that *a human on your side approved that specific
+     * action*, and the `previewSummary` you return is retained as the audit
+     * record of what they approved. Enable it only on code paths where that is
+     * genuinely true — never to rubber-stamp unattended writes. Pass
+     * `{ autoConfirm: false }` on an individual call to opt out again, or use
+     * `medal.capabilityConfirmations.create(...)` for full manual control.
+     *
+     * @example
+     * ```ts
+     * const medal = new Medal('medal_xxx', {
+     *   autoConfirmCapabilities: {
+     *     previewSummary: (ctx) =>
+     *       `${operator.email} approved ${ctx.method} ${ctx.path}`,
+     *   },
+     * });
+     * ```
+     */
+    autoConfirmCapabilities?: AutoConfirmOptions;
 }
 /**
  * Medal Social SDK client.
@@ -1267,6 +2375,13 @@ interface MedalOptions {
  *   variables: { name: 'John' },
  * });
  *
+ * // Bookings — free slots, then book a party (money is integer øre)
+ * const { data: slots } = await medal.bookings.availability({
+ *   service_id: 'svc_1',
+ *   from_ts: Date.now(),
+ *   to_ts: Date.now() + 7 * 86_400_000,
+ * });
+ *
  * // Contacts, Deals, GDPR, Workspaces
  * const contacts = await medal.contacts.list({ status: 'lead' });
  * const { data: deal } = await medal.deals.create({ title: 'Acme', value: 50000 });
@@ -1275,6 +2390,8 @@ interface MedalOptions {
  * ```
  */
 declare class Medal {
+    readonly bookings: Bookings;
+    readonly capabilityConfirmations: CapabilityConfirmations;
     readonly channels: Channels;
     readonly emails: Emails;
     readonly contacts: Contacts;
@@ -1282,6 +2399,7 @@ declare class Medal {
     readonly gdpr: Gdpr;
     readonly helpdesk: Helpdesk;
     readonly posts: Posts;
+    readonly scan: Scan;
     readonly webhooks: Webhooks;
     readonly workspaces: Workspaces;
     constructor(token: string, options?: MedalOptions);
@@ -1290,4 +2408,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 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 };
+export { type Activity, type AddNoteInput, type ApiResponse, type AutoConfirmContext, type AutoConfirmOptions, BaseClient, type BatchSendInput, type BatchSendResult, type BatchSendSummary, type Booking, type BookingActionResult, type BookingAvailabilityOptions, type BookingCancelledBy, type BookingClaimableCreatedVia, type BookingContactInput, type BookingCreateResult, type BookingCreatedVia, type BookingPaymentStatus, type BookingRescheduleResult, type BookingResource, type BookingResourceType, type BookingScheduleDay, type BookingScheduleOptions, type BookingService, type BookingSlot, type BookingStatus, type BookingTimestampInput, Bookings, type BookingsPage, type BookingsPagination, CAPABILITY_IDS, CAPABILITY_ROUTES, type CancelBookingInput, type CapabilityConfirmation, CapabilityConfirmations, CapabilityConfirmer, type CapabilityId, type CapabilityPathParamValue, type CapabilityRoute, type CapabilityWriteBodies, type CapabilityWriteRequest, 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 CreateBookingInput, type CreateBookingItemInput, type CreateConnectLinkInput, type CreateContactInput, type CreateDealInput, type CreatePostInput, type CreateReplyInput, type CreateWebhookInput, type CreatedBooking, 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 IssueCapabilityConfirmationInput, type ListBookingServicesOptions, type ListBookingsOptions, type ListConnectLinksOptions, type ListContactsOptions, type ListConversationsOptions, type ListDealsOptions, type ListDeliveriesOptions, type ListPostsOptions, type ManageSummary, Medal, MedalApiError, type MedalOptions, type MessageAuthorType, type MessageDeliveryStatus, 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 RescheduleBookingInput, Scan, type ScanCompany, type ScanCreateInput, type ScanCreateResult, type ScanJob, type ScanResultPayload, type ScanStatus, type ScanSubScores, type SchedulePostInput, type ScheduleResult, type SendEmailInput, type TestPingEvent, type UpdateBookingInput, type UpdateContactInput, type UpdateConversationInput, type UpdateDealInput, type UpdatePostInput, type UpdateWebhookInput, type VerifyWebhookSignatureInput, type WaitForScanOptions, 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 };