@medalsocial/sdk 1.6.0 → 1.7.0

package/dist/src/index.d.mts

@@ -573,6 +573,24 @@ declare class BaseClient {
     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. */
@@ -582,6 +600,425 @@ declare class BaseClient {
     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.
  *
@@ -621,6 +1058,13 @@ declare class CapabilityConfirmations {
      * 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>>;
 }
@@ -665,6 +1109,13 @@ 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>>;
     /**
@@ -841,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. */
@@ -851,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. */
@@ -933,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. */
@@ -1076,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. */
@@ -1156,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;
     }>>;
@@ -1165,11 +1665,25 @@ 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;
@@ -1198,8 +1712,16 @@ declare class HelpdeskReplies {
     /**
      * 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>>;
 }
@@ -1294,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. */
@@ -1308,9 +1836,24 @@ 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[]>>;
@@ -1457,10 +2000,15 @@ declare class Scan {
      * 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): Promise<ApiResponse<ScanCreateResult>>;
+    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). */
@@ -1491,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. */
@@ -1506,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>>;
 }
 
@@ -1813,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 });
@@ -1821,6 +2390,7 @@ interface MedalOptions {
  * ```
  */
 declare class Medal {
+    readonly bookings: Bookings;
     readonly capabilityConfirmations: CapabilityConfirmations;
     readonly channels: Channels;
     readonly emails: Emails;
@@ -1838,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, type AutoConfirmContext, type AutoConfirmOptions, BaseClient, type BatchSendInput, type BatchSendResult, type BatchSendSummary, CAPABILITY_IDS, CAPABILITY_ROUTES, 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 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 IssueCapabilityConfirmationInput, type ListConnectLinksOptions, type ListContactsOptions, type ListConversationsOptions, type ListDealsOptions, type ListDeliveriesOptions, type ListPostsOptions, 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, Scan, type ScanCompany, type ScanCreateInput, type ScanCreateResult, type ScanJob, type ScanResultPayload, type ScanStatus, type ScanSubScores, type SchedulePostInput, type ScheduleResult, type SendEmailInput, type TestPingEvent, 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 };
+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 };