@medalsocial/sdk 1.6.0 → 1.7.0

package/dist/src/index.mjs

@@ -1,113 +1,3 @@
-// src/types/capabilities.ts
-var CAPABILITY_IDS = [
-  "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"
-];
-var CAPABILITY_ROUTES = {
-  "channel.connect_link.create.execute": {
-    method: "POST",
-    path_template: "/api/v1/channels/connect-links"
-  },
-  "channel.connect_link.revoke.execute": {
-    method: "DELETE",
-    path_template: "/api/v1/channels/connect-links/{id}"
-  },
-  "channel.connection.disconnect.execute": {
-    method: "DELETE",
-    path_template: "/api/v1/channels/connections/{id}"
-  },
-  "helpdesk.conversation.reply.execute": {
-    method: "POST",
-    path_template: "/api/v1/helpdesk/replies"
-  },
-  "helpdesk.conversation.update.execute": {
-    method: "PATCH",
-    path_template: "/api/v1/helpdesk/conversations/{id}"
-  },
-  "helpdesk.webhook.create.execute": {
-    method: "POST",
-    path_template: "/api/v1/webhooks"
-  },
-  "helpdesk.webhook.update.execute": {
-    method: "PATCH",
-    path_template: "/api/v1/webhooks/{id}"
-  },
-  "helpdesk.webhook.delete.execute": {
-    method: "DELETE",
-    path_template: "/api/v1/webhooks/{id}"
-  }
-};
-
-// src/capability-confirmer.ts
-function newIdempotencyKey() {
-  const cryptoRef = globalThis.crypto;
-  if (typeof cryptoRef?.randomUUID === "function") {
-    return cryptoRef.randomUUID();
-  }
-  return `idem_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
-}
-function resolvePath(template, pathParams) {
-  return template.replace(/\{([^}/]+)\}/g, (_match, name) => {
-    const value = pathParams?.[name];
-    return value === void 0 ? `{${name}}` : encodeURIComponent(String(value));
-  });
-}
-var CapabilityConfirmer = class {
-  constructor(confirmations, defaults) {
-    this.confirmations = confirmations;
-    this.defaults = defaults;
-  }
-  confirmations;
-  defaults;
-  /**
-   * 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.
-   */
-  async prepare(request, pathParams, options) {
-    const auto = options?.autoConfirm === false ? void 0 : options?.autoConfirm ?? this.defaults;
-    if (!auto) return options;
-    if (options?.idempotencyKey && options?.capabilityConfirmation) return options;
-    const route = CAPABILITY_ROUTES[request.capabilityId];
-    const idempotencyKey = options?.idempotencyKey ?? newIdempotencyKey();
-    const path = resolvePath(route.path_template, pathParams);
-    const previewSummary = auto.previewSummary({
-      ...request,
-      method: route.method,
-      path,
-      ...pathParams ? { pathParams } : {},
-      idempotencyKey
-    });
-    if (typeof previewSummary !== "string" || previewSummary.trim() === "") {
-      throw new Error(
-        `autoConfirm.previewSummary must return a non-empty summary for ${request.capabilityId}. The summary is the audit record of what your user approved \u2014 refusing to assert user_approved: true without one.`
-      );
-    }
-    const { data } = await this.confirmations.create({
-      capability_id: request.capabilityId,
-      ...pathParams ? { path_params: pathParams } : {},
-      idempotency_key: idempotencyKey,
-      preview_summary: previewSummary,
-      user_approved: true
-    });
-    return {
-      ...options,
-      idempotencyKey,
-      capabilityConfirmation: data.confirmation_token
-    };
-  }
-};
-
 // src/types/common.ts
 var MedalApiError = class extends Error {
   status;
@@ -123,6 +13,21 @@ var MedalApiError = class extends Error {
 };
 
 // src/client.ts
+function randomIdempotencyKey() {
+  const webCrypto = globalThis.crypto;
+  if (typeof webCrypto.randomUUID === "function") {
+    return webCrypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  webCrypto.getRandomValues(bytes);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function resolveIdempotencyKey(supplied) {
+  return (supplied ?? "").trim() || randomIdempotencyKey();
+}
 var BaseClient = class {
   /** Resolved client configuration. */
   config;
@@ -142,6 +47,29 @@ var BaseClient = class {
       body: body !== void 0 ? JSON.stringify(body) : void 0
     });
   }
+  /**
+   * 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.
+   */
+  async postOnce(path, body, options) {
+    return this.post(path, body, {
+      ...options,
+      idempotencyKey: resolveIdempotencyKey(options?.idempotencyKey)
+    });
+  }
   /** Execute an authenticated PATCH request with a JSON body. */
   async patch(path, body, options) {
     return this.request(this.buildUrl(path), {
@@ -193,12 +121,22 @@ var BaseClient = class {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), this.config.timeout);
       let res;
+      let text = "";
+      let retrying = false;
       try {
         res = await fetch(url, { ...init, headers, signal: controller.signal });
+        retrying = (res.status === 429 || res.status >= 500 && res.status <= 599) && attempt < maxAttempts;
+        if (retrying) {
+          const drained = res.body ? res.body.pipeTo(new WritableStream()) : res.text();
+          await drained.catch(() => {
+          });
+        } else {
+          text = await res.text();
+        }
       } finally {
         clearTimeout(timeout);
       }
-      if ((res.status === 429 || res.status >= 500 && res.status <= 599) && attempt < maxAttempts) {
+      if (retrying) {
         const retryAfter = res.headers.get("retry-after");
         let delayMs = 0;
         if (retryAfter) {
@@ -211,7 +149,6 @@ var BaseClient = class {
         await new Promise((r) => setTimeout(r, delayMs));
         continue;
       }
-      const text = await res.text();
       let parsed;
       try {
         parsed = text ? JSON.parse(text) : void 0;
@@ -233,6 +170,266 @@ var BaseClient = class {
   }
 };
 
+// src/types/capabilities.ts
+var CAPABILITY_IDS = [
+  "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"
+];
+var CAPABILITY_ROUTES = {
+  "channel.connect_link.create.execute": {
+    method: "POST",
+    path_template: "/api/v1/channels/connect-links"
+  },
+  "channel.connect_link.revoke.execute": {
+    method: "DELETE",
+    path_template: "/api/v1/channels/connect-links/{id}"
+  },
+  "channel.connection.disconnect.execute": {
+    method: "DELETE",
+    path_template: "/api/v1/channels/connections/{id}"
+  },
+  "helpdesk.conversation.reply.execute": {
+    method: "POST",
+    path_template: "/api/v1/helpdesk/replies"
+  },
+  "helpdesk.conversation.update.execute": {
+    method: "PATCH",
+    path_template: "/api/v1/helpdesk/conversations/{id}"
+  },
+  "helpdesk.webhook.create.execute": {
+    method: "POST",
+    path_template: "/api/v1/webhooks"
+  },
+  "helpdesk.webhook.update.execute": {
+    method: "PATCH",
+    path_template: "/api/v1/webhooks/{id}"
+  },
+  "helpdesk.webhook.delete.execute": {
+    method: "DELETE",
+    path_template: "/api/v1/webhooks/{id}"
+  }
+};
+
+// src/capability-confirmer.ts
+function resolvePath(template, pathParams) {
+  return template.replace(/\{([^}/]+)\}/g, (_match, name) => {
+    const value = pathParams?.[name];
+    return value === void 0 ? `{${name}}` : encodeURIComponent(String(value));
+  });
+}
+var CapabilityConfirmer = class {
+  constructor(confirmations, defaults) {
+    this.confirmations = confirmations;
+    this.defaults = defaults;
+  }
+  confirmations;
+  defaults;
+  /**
+   * 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.
+   */
+  async prepare(request, pathParams, options) {
+    const auto = options?.autoConfirm === false ? void 0 : options?.autoConfirm ?? this.defaults;
+    if (!auto) return options;
+    const idempotencyKey = resolveIdempotencyKey(options?.idempotencyKey);
+    const callerKeyIsUsable = idempotencyKey === options?.idempotencyKey;
+    if (callerKeyIsUsable && options?.capabilityConfirmation) return options;
+    const route = CAPABILITY_ROUTES[request.capabilityId];
+    const path = resolvePath(route.path_template, pathParams);
+    const previewSummary = auto.previewSummary({
+      ...request,
+      method: route.method,
+      path,
+      ...pathParams ? { pathParams } : {},
+      idempotencyKey
+    });
+    if (typeof previewSummary !== "string" || previewSummary.trim() === "") {
+      throw new Error(
+        `autoConfirm.previewSummary must return a non-empty summary for ${request.capabilityId}. The summary is the audit record of what your user approved \u2014 refusing to assert user_approved: true without one.`
+      );
+    }
+    const { data } = await this.confirmations.create({
+      capability_id: request.capabilityId,
+      ...pathParams ? { path_params: pathParams } : {},
+      idempotency_key: idempotencyKey,
+      preview_summary: previewSummary,
+      user_approved: true
+    });
+    return {
+      ...options,
+      idempotencyKey,
+      capabilityConfirmation: data.confirmation_token
+    };
+  }
+};
+
+// src/resources/bookings.ts
+var BookingsManage = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Read what the holder of a manage token may see and do. Honour
+   * `can_cancel` / `can_reschedule` — they already apply the policy windows.
+   */
+  async get(token) {
+    return this.client.get(`/api/v1/bookings/manage/${encodeURIComponent(token)}`);
+  }
+  /** Cancel on the customer's behalf. Rejected outside the cancel window. */
+  async cancel(token, input, options) {
+    return this.client.postOnce(
+      `/api/v1/bookings/manage/${encodeURIComponent(token)}/cancel`,
+      input ?? {},
+      options
+    );
+  }
+  /**
+   * 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.
+   */
+  async reschedule(token, input, options) {
+    return this.client.postOnce(
+      `/api/v1/bookings/manage/${encodeURIComponent(token)}/reschedule`,
+      input,
+      options
+    );
+  }
+};
+var Bookings = class {
+  constructor(client) {
+    this.client = client;
+    this.manage = new BookingsManage(client);
+  }
+  client;
+  /** Customer-side actions addressed by manage token. */
+  manage;
+  /** List the bookable service catalogue. Active-only unless asked otherwise. */
+  async listServices(options) {
+    const params = {};
+    if (options?.include_inactive !== void 0) {
+      params.include_inactive = String(options.include_inactive);
+    }
+    return this.client.get("/api/v1/bookings/services", params);
+  }
+  /** List the bookable resources — staff, rooms, and equipment. */
+  async listResources() {
+    return this.client.get("/api/v1/bookings/resources");
+  }
+  /**
+   * 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.
+   */
+  async availability(options) {
+    const params = {
+      service_id: options.service_id,
+      from_ts: String(options.from_ts),
+      to_ts: String(options.to_ts)
+    };
+    if (options.resource_id) params.resource_id = options.resource_id;
+    return this.client.get("/api/v1/bookings/availability", params);
+  }
+  /**
+   * 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".
+   */
+  async schedule(options) {
+    const params = {
+      service_id: options.service_id,
+      from_ts: String(options.from_ts),
+      to_ts: String(options.to_ts)
+    };
+    if (options.resource_id) params.resource_id = options.resource_id;
+    return this.client.get("/api/v1/bookings/schedule", params);
+  }
+  /**
+   * 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`.
+   */
+  async list(options) {
+    const params = {};
+    if (options?.limit !== void 0) params.limit = String(options.limit);
+    if (options?.cursor) params.cursor = options.cursor;
+    if (options?.status) params.status = options.status;
+    if (options?.resource_id) params.resource_id = options.resource_id;
+    if (options?.from_ts !== void 0) params.from_ts = String(options.from_ts);
+    if (options?.to_ts !== void 0) params.to_ts = String(options.to_ts);
+    return this.client.get("/api/v1/bookings", params);
+  }
+  /**
+   * 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.
+   */
+  async create(input, options) {
+    return this.client.postOnce("/api/v1/bookings", input, options);
+  }
+  /** Get a booking by ID. */
+  async get(id) {
+    return this.client.get(`/api/v1/bookings/${encodeURIComponent(id)}`);
+  }
+  /**
+   * Annotate a booking. At least one of `notes` (customer-visible) or
+   * `internal_notes` (staff-only) is required; `""` clears a field.
+   */
+  async update(id, input, options) {
+    return this.client.patch(`/api/v1/bookings/${encodeURIComponent(id)}`, input, options);
+  }
+  /** Cancel as the business — the cancel window is bypassed. */
+  async cancel(id, input, options) {
+    return this.client.postOnce(
+      `/api/v1/bookings/${encodeURIComponent(id)}/cancel`,
+      input ?? {},
+      options
+    );
+  }
+  /**
+   * 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.
+   */
+  async reschedule(id, input, options) {
+    return this.client.postOnce(
+      `/api/v1/bookings/${encodeURIComponent(id)}/reschedule`,
+      input,
+      options
+    );
+  }
+  /** Mark a booking as a no-show. */
+  async markNoShow(id, options) {
+    return this.client.postOnce(
+      `/api/v1/bookings/${encodeURIComponent(id)}/no-show`,
+      void 0,
+      options
+    );
+  }
+};
+
 // src/resources/capability-confirmations.ts
 var CapabilityConfirmations = class {
   constructor(client) {
@@ -250,6 +447,13 @@ var CapabilityConfirmations = class {
    * 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.
    */
   async create(input) {
     return this.client.post("/api/v1/capability-confirmations", input);
@@ -274,6 +478,13 @@ var ChannelConnectLinks = class {
    *
    * 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.
    */
   async create(input, options) {
     const resolved = await this.confirmer.prepare(
@@ -281,7 +492,7 @@ var ChannelConnectLinks = class {
       void 0,
       options
     );
-    return this.client.post("/api/v1/channels/connect-links", input, resolved);
+    return this.client.postOnce("/api/v1/channels/connect-links", input, resolved);
   }
   /**
    * List the workspace's connect links (tokens are never returned), newest
@@ -376,9 +587,17 @@ var Contacts = class {
     if (options?.search) params.search = options.search;
     return this.client.get("/api/v1/contacts", params);
   }
-  /** Create a new contact. Email must be unique in the workspace. */
-  async create(input) {
-    return this.client.post("/api/v1/contacts", input);
+  /**
+   * 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.
+   */
+  async create(input, options) {
+    return this.client.postOnce("/api/v1/contacts", input, options);
   }
   /** Get a contact by ID. */
   async get(id) {
@@ -399,13 +618,26 @@ var Contacts = class {
     if (options?.cursor) params.cursor = options.cursor;
     return this.client.get(`/api/v1/contacts/${encodeURIComponent(id)}/activities`, params);
   }
-  /** Add a note to a contact's timeline. */
-  async addNote(id, input) {
-    return this.client.post(`/api/v1/contacts/${encodeURIComponent(id)}/notes`, input);
+  /**
+   * 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.
+   */
+  async addNote(id, input, options) {
+    return this.client.postOnce(`/api/v1/contacts/${encodeURIComponent(id)}/notes`, input, options);
   }
-  /** Bulk import contacts (max 500). Duplicates are skipped. */
-  async import(contacts) {
-    return this.client.post("/api/v1/contacts/import", { contacts });
+  /**
+   * 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.
+   */
+  async import(contacts, options) {
+    return this.client.postOnce("/api/v1/contacts/import", { contacts }, options);
   }
 };
 
@@ -424,9 +656,15 @@ var Deals = class {
     if (options?.search) params.search = options.search;
     return this.client.get("/api/v1/deals", params);
   }
-  /** Create a new deal. */
-  async create(input) {
-    return this.client.post("/api/v1/deals", input);
+  /**
+   * 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.
+   */
+  async create(input, options) {
+    return this.client.postOnce("/api/v1/deals", input, options);
   }
   /** Get a deal by ID. */
   async get(id) {
@@ -470,9 +708,18 @@ var Emails = class {
   /**
    * 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.
    */
-  async send(input) {
-    return this.client.post("/api/v1/emails", input);
+  async send(input, options) {
+    return this.client.postOnce("/api/v1/emails", input, options);
   }
   /** Get the delivery status of a sent email. */
   async get(id) {
@@ -481,9 +728,14 @@ var Emails = class {
   /**
    * 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.
    */
-  async batch(input) {
-    return this.client.post("/api/v1/emails/batch", input);
+  async batch(input, options) {
+    return this.client.postOnce("/api/v1/emails/batch", input, options);
   }
 };
 
@@ -493,9 +745,17 @@ var Gdpr = class {
     this.client = client;
   }
   client;
-  /** Request a workspace data export. Runs asynchronously. */
-  async requestExport() {
-    return this.client.post("/api/v1/gdpr/export");
+  /**
+   * 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.
+   */
+  async requestExport(options) {
+    return this.client.postOnce("/api/v1/gdpr/export", void 0, options);
   }
   /** List all workspace export requests. */
   async listExports() {
@@ -505,7 +765,13 @@ var Gdpr = class {
   async getExport(id) {
     return this.client.get(`/api/v1/gdpr/exports/${encodeURIComponent(id)}`);
   }
-  /** 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.
+   */
   async recordConsent(input) {
     return this.client.post("/api/v1/gdpr/consent", input);
   }
@@ -513,7 +779,15 @@ var Gdpr = class {
   async getConsent(email) {
     return this.client.get(`/api/v1/gdpr/consent/${encodeURIComponent(email)}`);
   }
-  /** 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.
+   */
   async cookieConsent(input) {
     return this.client.post("/api/cookie-consent", input);
   }
@@ -577,8 +851,16 @@ var HelpdeskReplies = class {
   /**
    * 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).
    */
   async create(input, options) {
     const resolved = await this.confirmer.prepare(
@@ -586,7 +868,7 @@ var HelpdeskReplies = class {
       void 0,
       options
     );
-    return this.client.post("/api/v1/helpdesk/replies", input, resolved);
+    return this.client.postOnce("/api/v1/helpdesk/replies", input, resolved);
   }
 };
 var Helpdesk = class {
@@ -614,9 +896,15 @@ var Posts = class {
     if (options?.type) params.type = options.type;
     return this.client.get("/api/v1/posts", params);
   }
-  /** Create a new post with content and target channels. */
-  async create(input) {
-    return this.client.post("/api/v1/posts", input);
+  /**
+   * 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.
+   */
+  async create(input, options) {
+    return this.client.postOnce("/api/v1/posts", input, options);
   }
   /** Get a post by ID, including its per-channel variants. */
   async get(id) {
@@ -630,11 +918,26 @@ var Posts = class {
   async remove(id) {
     return this.client.delete(`/api/v1/posts/${encodeURIComponent(id)}`);
   }
-  /** 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.
+   */
   async schedule(id, input) {
     return this.client.post(`/api/v1/posts/${encodeURIComponent(id)}/schedule`, input);
   }
-  /** 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".
+   */
   async publish(id) {
     return this.client.post(`/api/v1/posts/${encodeURIComponent(id)}/publish`);
   }
@@ -655,10 +958,15 @@ var Scan = class {
    * 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.
    */
-  async create(input) {
+  async create(input, options) {
     const entries = ["url", "orgnr", "name"].filter(
       (key2) => input[key2] !== void 0 && input[key2] !== ""
     );
@@ -666,7 +974,7 @@ var Scan = class {
       throw new Error("scan.create requires exactly one of url, orgnr, or name");
     }
     const key = entries[0];
-    return this.client.post("/api/v1/scan", { [key]: input[key] });
+    return this.client.postOnce("/api/v1/scan", { [key]: input[key] }, options);
   }
   /** Get a scan job's status and, once done, its findings payload. */
   async get(id) {
@@ -724,6 +1032,13 @@ var Webhooks = class {
    * `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.
    */
   async create(input, options) {
     const resolved = await this.confirmer.prepare(
@@ -731,7 +1046,7 @@ var Webhooks = class {
       void 0,
       options
     );
-    return this.client.post("/api/v1/webhooks", input, resolved);
+    return this.client.postOnce("/api/v1/webhooks", input, resolved);
   }
   /** Get a webhook endpoint by ID. */
   async get(id) {
@@ -766,7 +1081,14 @@ var Webhooks = class {
     if (options?.limit !== void 0) params.limit = String(options.limit);
     return this.client.get(`/api/v1/webhooks/${encodeURIComponent(id)}/deliveries`, params);
   }
-  /** 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.
+   */
   async test(id) {
     return this.client.post(`/api/v1/webhooks/${encodeURIComponent(id)}/test`);
   }
@@ -856,6 +1178,7 @@ async function verifyWebhookSignature(input) {
 
 // src/index.ts
 var Medal = class {
+  bookings;
   capabilityConfirmations;
   channels;
   emails;
@@ -885,6 +1208,7 @@ var Medal = class {
       this.capabilityConfirmations,
       options?.autoConfirmCapabilities
     );
+    this.bookings = new Bookings(client);
     this.channels = new Channels(client, confirmer);
     this.emails = new Emails(client);
     this.contacts = new Contacts(client);
@@ -903,6 +1227,7 @@ function createMedalClient(apiKey, options) {
 var src_default = Medal;
 export {
   BaseClient,
+  Bookings,
   CAPABILITY_IDS,
   CAPABILITY_ROUTES,
   CapabilityConfirmations,