@medalsocial/sdk 1.5.0 → 1.7.0

package/dist/src/index.mjs

@@ -13,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;
@@ -32,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), {
@@ -83,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) {
@@ -101,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;
@@ -123,12 +170,304 @@ 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) {
+    this.client = client;
+  }
+  client;
+  /**
+   * 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.
+   */
+  async create(input) {
+    return this.client.post("/api/v1/capability-confirmations", input);
+  }
+};
+
 // src/resources/channels.ts
 var ChannelConnectLinks = class {
-  constructor(client) {
+  constructor(client, confirmer) {
     this.client = client;
+    this.confirmer = confirmer;
   }
   client;
+  confirmer;
   /**
    * Mint a single-use hosted connect link. Returns HTTP 201.
    *
@@ -139,30 +478,73 @@ 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) {
-    return this.client.post("/api/v1/channels/connect-links", input, options);
+    const resolved = await this.confirmer.prepare(
+      { capabilityId: "channel.connect_link.create.execute", body: input },
+      void 0,
+      options
+    );
+    return this.client.postOnce("/api/v1/channels/connect-links", input, resolved);
   }
-  /** List the workspace's connect links (tokens are never returned). */
+  /**
+   * 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.
+   */
   async list(options) {
     const params = {};
+    if (options?.limit !== void 0) params.limit = String(options.limit);
+    if (options?.cursor) params.cursor = options.cursor;
     if (options?.channel_type) params.channel_type = options.channel_type;
     if (options?.status) params.status = options.status;
     return this.client.get("/api/v1/channels/connect-links", params);
   }
   /** Revoke a pending connect link so it can no longer be consumed. */
   async revoke(id, options) {
-    return this.client.delete(`/api/v1/channels/connect-links/${encodeURIComponent(id)}`, options);
+    const resolved = await this.confirmer.prepare(
+      { capabilityId: "channel.connect_link.revoke.execute", body: void 0 },
+      { id },
+      options
+    );
+    return this.client.delete(`/api/v1/channels/connect-links/${encodeURIComponent(id)}`, resolved);
   }
 };
 var ChannelConnections = class {
-  constructor(client) {
+  constructor(client, confirmer) {
     this.client = client;
+    this.confirmer = confirmer;
   }
   client;
-  /** List the workspace's channel connections (generic, channel-agnostic shape). */
-  async list() {
-    return this.client.get("/api/v1/channels/connections");
+  confirmer;
+  /**
+   * 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.
+   */
+  async list(options) {
+    const params = {};
+    if (options?.limit !== void 0) params.limit = String(options.limit);
+    if (options?.cursor) params.cursor = options.cursor;
+    return this.client.get("/api/v1/channels/connections", params);
   }
   /**
    * Disconnect a connected channel account (best-effort platform logout, then
@@ -170,15 +552,21 @@ var ChannelConnections = class {
    * `reason: "api_disconnect"` if the account was previously connected.
    */
   async disconnect(id, options) {
-    return this.client.delete(`/api/v1/channels/connections/${encodeURIComponent(id)}`, options);
+    const resolved = await this.confirmer.prepare(
+      { capabilityId: "channel.connection.disconnect.execute", body: void 0 },
+      { id },
+      options
+    );
+    return this.client.delete(`/api/v1/channels/connections/${encodeURIComponent(id)}`, resolved);
   }
 };
 var Channels = class {
   connectLinks;
   connections;
-  constructor(client) {
-    this.connectLinks = new ChannelConnectLinks(client);
-    this.connections = new ChannelConnections(client);
+  constructor(client, confirmer) {
+    const resolved = confirmer ?? new CapabilityConfirmer(new CapabilityConfirmations(client));
+    this.connectLinks = new ChannelConnectLinks(client, resolved);
+    this.connections = new ChannelConnections(client, resolved);
   }
 };
 
@@ -199,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) {
@@ -222,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);
   }
 };
 
@@ -247,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) {
@@ -293,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) {
@@ -304,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);
   }
 };
 
@@ -316,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() {
@@ -328,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);
   }
@@ -336,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);
   }
@@ -344,10 +795,12 @@ var Gdpr = class {
 
 // src/resources/helpdesk.ts
 var HelpdeskConversations = class {
-  constructor(client) {
+  constructor(client, confirmer) {
     this.client = client;
+    this.confirmer = confirmer;
   }
   client;
+  confirmer;
   /** List/search conversations with cursor-based pagination and optional filters. */
   async list(options) {
     const params = {};
@@ -366,10 +819,15 @@ var HelpdeskConversations = class {
   }
   /** Update a conversation's status and/or assignee (pass `assignee_user_id: null` to unassign). */
   async update(id, input, options) {
+    const resolved = await this.confirmer.prepare(
+      { capabilityId: "helpdesk.conversation.update.execute", body: input },
+      { id },
+      options
+    );
     return this.client.patch(
       `/api/v1/helpdesk/conversations/${encodeURIComponent(id)}`,
       input,
-      options
+      resolved
     );
   }
   /** Read a conversation's messages with cursor-based pagination. */
@@ -384,26 +842,42 @@ var HelpdeskConversations = class {
   }
 };
 var HelpdeskReplies = class {
-  constructor(client) {
+  constructor(client, confirmer) {
     this.client = client;
+    this.confirmer = confirmer;
   }
   client;
+  confirmer;
   /**
    * 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) {
-    return this.client.post("/api/v1/helpdesk/replies", input, options);
+    const resolved = await this.confirmer.prepare(
+      { capabilityId: "helpdesk.conversation.reply.execute", body: input },
+      void 0,
+      options
+    );
+    return this.client.postOnce("/api/v1/helpdesk/replies", input, resolved);
   }
 };
 var Helpdesk = class {
   conversations;
   replies;
-  constructor(client) {
-    this.conversations = new HelpdeskConversations(client);
-    this.replies = new HelpdeskReplies(client);
+  constructor(client, confirmer) {
+    const resolved = confirmer ?? new CapabilityConfirmer(new CapabilityConfirmations(client));
+    this.conversations = new HelpdeskConversations(client, resolved);
+    this.replies = new HelpdeskReplies(client, resolved);
   }
 };
 
@@ -422,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) {
@@ -438,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`);
   }
@@ -452,12 +947,76 @@ var Posts = class {
   }
 };
 
+// src/resources/scan.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var Scan = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * 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, options) {
+    const entries = ["url", "orgnr", "name"].filter(
+      (key2) => input[key2] !== void 0 && input[key2] !== ""
+    );
+    if (entries.length !== 1) {
+      throw new Error("scan.create requires exactly one of url, orgnr, or name");
+    }
+    const key = entries[0];
+    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) {
+    return this.client.get(`/api/v1/scan/${encodeURIComponent(id)}`);
+  }
+  /** Search the Norwegian company registry by name (typeahead, top 5 hits). */
+  async companies(q) {
+    return this.client.get("/api/v1/scan/companies", { q });
+  }
+  /**
+   * 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.
+   */
+  async waitForResult(id, options = {}) {
+    const rawInterval = options.intervalMs ?? 2500;
+    const rawTimeout = options.timeoutMs ?? 12e4;
+    const intervalMs = Number.isFinite(rawInterval) && rawInterval > 0 ? rawInterval : 2500;
+    const timeoutMs = Number.isFinite(rawTimeout) ? rawTimeout : 12e4;
+    const deadline = Date.now() + timeoutMs;
+    let lastStatus = "pending";
+    for (; ; ) {
+      const { data } = await this.get(id);
+      if (data.status === "done" || data.status === "failed") return data;
+      lastStatus = data.status;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await sleep(Math.min(intervalMs, remaining));
+      if (Date.now() >= deadline) break;
+    }
+    throw new Error(`Scan ${id} timed out after ${timeoutMs}ms (status: ${lastStatus})`);
+  }
+};
+
 // src/resources/webhooks.ts
 var Webhooks = class {
-  constructor(client) {
+  constructor(client, confirmer) {
     this.client = client;
+    this.confirmer = confirmer ?? new CapabilityConfirmer(new CapabilityConfirmations(client));
   }
   client;
+  confirmer;
   /** List all webhook endpoints in the workspace. */
   async list() {
     return this.client.get("/api/v1/webhooks");
@@ -473,9 +1032,21 @@ 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) {
-    return this.client.post("/api/v1/webhooks", input, options);
+    const resolved = await this.confirmer.prepare(
+      { capabilityId: "helpdesk.webhook.create.execute", body: input },
+      void 0,
+      options
+    );
+    return this.client.postOnce("/api/v1/webhooks", input, resolved);
   }
   /** Get a webhook endpoint by ID. */
   async get(id) {
@@ -483,7 +1054,12 @@ var Webhooks = class {
   }
   /** Update a webhook endpoint (name, url, event types, filters, enabled). */
   async update(id, input, options) {
-    return this.client.patch(`/api/v1/webhooks/${encodeURIComponent(id)}`, input, options);
+    const resolved = await this.confirmer.prepare(
+      { capabilityId: "helpdesk.webhook.update.execute", body: input },
+      { id },
+      options
+    );
+    return this.client.patch(`/api/v1/webhooks/${encodeURIComponent(id)}`, input, resolved);
   }
   /**
    * Permanently delete a webhook endpoint (stops all outbound deliveries).
@@ -492,7 +1068,12 @@ var Webhooks = class {
    * grants on this route. API keys with legacy scopes may omit it.
    */
   async delete(id, options) {
-    return this.client.delete(`/api/v1/webhooks/${encodeURIComponent(id)}`, options);
+    const resolved = await this.confirmer.prepare(
+      { capabilityId: "helpdesk.webhook.delete.execute", body: void 0 },
+      { id },
+      options
+    );
+    return this.client.delete(`/api/v1/webhooks/${encodeURIComponent(id)}`, resolved);
   }
   /** List recent deliveries for an endpoint (most recent first). */
   async deliveries(id, options) {
@@ -500,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`);
   }
@@ -590,6 +1178,8 @@ async function verifyWebhookSignature(input) {
 
 // src/index.ts
 var Medal = class {
+  bookings;
+  capabilityConfirmations;
   channels;
   emails;
   contacts;
@@ -597,6 +1187,7 @@ var Medal = class {
   gdpr;
   helpdesk;
   posts;
+  scan;
   webhooks;
   workspaces;
   constructor(token, options) {
@@ -612,14 +1203,21 @@ var Medal = class {
       timeout: options?.timeout ?? 3e4,
       userAgent: "medalsocial-sdk/1.0.0 (+https://github.com/Medal-Social/MedalSocial)"
     });
-    this.channels = new Channels(client);
+    this.capabilityConfirmations = new CapabilityConfirmations(client);
+    const confirmer = new CapabilityConfirmer(
+      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);
     this.deals = new Deals(client);
     this.gdpr = new Gdpr(client);
-    this.helpdesk = new Helpdesk(client);
+    this.helpdesk = new Helpdesk(client, confirmer);
     this.posts = new Posts(client);
-    this.webhooks = new Webhooks(client);
+    this.scan = new Scan(client);
+    this.webhooks = new Webhooks(client, confirmer);
     this.workspaces = new Workspaces(client);
   }
 };
@@ -629,6 +1227,11 @@ function createMedalClient(apiKey, options) {
 var src_default = Medal;
 export {
   BaseClient,
+  Bookings,
+  CAPABILITY_IDS,
+  CAPABILITY_ROUTES,
+  CapabilityConfirmations,
+  CapabilityConfirmer,
   Channels,
   Contacts,
   DEFAULT_WEBHOOK_TOLERANCE_MS,
@@ -639,6 +1242,7 @@ export {
   Medal,
   MedalApiError,
   Posts,
+  Scan,
   WebhookVerificationError,
   Webhooks,
   Workspaces,