@medalsocial/sdk 1.6.0 → 1.8.0

package/dist/src/index.mjs

@@ -1,3 +1,191 @@
+// src/types/common.ts
+var MedalApiError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "MedalApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// 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;
+  constructor(config) {
+    this.config = config;
+  }
+  /** Execute an authenticated GET request and return the parsed JSON body. */
+  async get(path, params, options) {
+    const url = this.buildUrl(path, params);
+    return this.request(url, { method: "GET", headers: options?.headers });
+  }
+  /** Execute an authenticated POST request with a JSON body. */
+  async post(path, body, options) {
+    return this.request(
+      this.buildUrl(path),
+      {
+        method: "POST",
+        headers: this.writeHeaders(options),
+        body: body !== void 0 ? JSON.stringify(body) : void 0
+      },
+      options?.retry
+    );
+  }
+  /**
+   * 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),
+      {
+        method: "PATCH",
+        headers: this.writeHeaders(options),
+        body: JSON.stringify(body)
+      },
+      options?.retry
+    );
+  }
+  /** Execute an authenticated DELETE request. */
+  async delete(path, options) {
+    return this.request(
+      this.buildUrl(path),
+      {
+        method: "DELETE",
+        headers: this.writeHeaders(options)
+      },
+      options?.retry
+    );
+  }
+  writeHeaders(options) {
+    const headers = {};
+    for (const [key, value] of Object.entries(options?.headers ?? {})) {
+      headers[key.toLowerCase()] = value;
+    }
+    headers["content-type"] = "application/json";
+    if (options?.idempotencyKey) {
+      headers["idempotency-key"] = options.idempotencyKey;
+    }
+    if (options?.capabilityConfirmation) {
+      headers["x-capability-confirmation"] = options.capabilityConfirmation;
+    }
+    return headers;
+  }
+  buildUrl(path, params) {
+    const url = new URL(`${this.config.baseUrl}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, value);
+        }
+      }
+    }
+    return url.toString();
+  }
+  async request(url, init, retry = true) {
+    const maxAttempts = retry ? 3 : 1;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const headers = new Headers(init.headers);
+      headers.set("authorization", `Bearer ${this.config.token}`);
+      if (this.config.workspaceId) {
+        headers.set("x-workspace-id", this.config.workspaceId);
+      }
+      try {
+        headers.set("user-agent", this.config.userAgent);
+      } catch {
+      }
+      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 (retrying) {
+        const retryAfter = res.headers.get("retry-after");
+        let delayMs = 0;
+        if (retryAfter) {
+          const seconds = Number(retryAfter);
+          delayMs = Number.isFinite(seconds) ? seconds * 1e3 : 0;
+        }
+        if (delayMs <= 0) {
+          delayMs = 250 * attempt;
+        }
+        await new Promise((r) => setTimeout(r, delayMs));
+        continue;
+      }
+      let parsed;
+      try {
+        parsed = text ? JSON.parse(text) : void 0;
+      } catch {
+        parsed = text;
+      }
+      if (!res.ok) {
+        const body = parsed;
+        throw new MedalApiError(
+          res.status,
+          body?.error?.code ?? "UNKNOWN_ERROR",
+          body?.error?.message ?? `HTTP ${res.status}: ${res.statusText}`,
+          body?.error?.details
+        );
+      }
+      return parsed;
+    }
+    throw new Error("Request failed after retries");
+  }
+};
+
 // src/types/capabilities.ts
 var CAPABILITY_IDS = [
   "channel.connect_link.create.execute",
@@ -45,13 +233,6 @@ var CAPABILITY_ROUTES = {
 };
 
 // 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];
@@ -77,9 +258,10 @@ var CapabilityConfirmer = class {
   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 idempotencyKey = resolveIdempotencyKey(options?.idempotencyKey);
+    const callerKeyIsUsable = idempotencyKey === options?.idempotencyKey;
+    if (callerKeyIsUsable && 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,
@@ -108,128 +290,159 @@ var CapabilityConfirmer = class {
   }
 };
 
-// src/types/common.ts
-var MedalApiError = class extends Error {
-  status;
-  code;
-  details;
-  constructor(status, code, message, details) {
-    super(message);
-    this.name = "MedalApiError";
-    this.status = status;
-    this.code = code;
-    this.details = details;
+// 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
+    );
   }
 };
-
-// src/client.ts
-var BaseClient = class {
-  /** Resolved client configuration. */
-  config;
-  constructor(config) {
-    this.config = config;
+var Bookings = class {
+  constructor(client) {
+    this.client = client;
+    this.manage = new BookingsManage(client);
   }
-  /** Execute an authenticated GET request and return the parsed JSON body. */
-  async get(path, params) {
-    const url = this.buildUrl(path, params);
-    return this.request(url, { method: "GET" });
+  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);
   }
-  /** Execute an authenticated POST request with a JSON body. */
-  async post(path, body, options) {
-    return this.request(this.buildUrl(path), {
-      method: "POST",
-      headers: this.writeHeaders(options),
-      body: body !== void 0 ? JSON.stringify(body) : void 0
-    });
+  /** List the bookable resources — staff, rooms, and equipment. */
+  async listResources() {
+    return this.client.get("/api/v1/bookings/resources");
   }
-  /** Execute an authenticated PATCH request with a JSON body. */
-  async patch(path, body, options) {
-    return this.request(this.buildUrl(path), {
-      method: "PATCH",
-      headers: this.writeHeaders(options),
-      body: JSON.stringify(body)
-    });
+  /**
+   * 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);
   }
-  /** Execute an authenticated DELETE request. */
-  async delete(path, options) {
-    return this.request(this.buildUrl(path), {
-      method: "DELETE",
-      headers: this.writeHeaders(options)
-    });
+  /**
+   * 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);
   }
-  writeHeaders(options) {
-    const headers = { "content-type": "application/json" };
-    if (options?.idempotencyKey) {
-      headers["idempotency-key"] = options.idempotencyKey;
-    }
-    if (options?.capabilityConfirmation) {
-      headers["x-capability-confirmation"] = options.capabilityConfirmation;
-    }
-    return headers;
+  /**
+   * 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);
   }
-  buildUrl(path, params) {
-    const url = new URL(`${this.config.baseUrl}${path}`);
-    if (params) {
-      for (const [key, value] of Object.entries(params)) {
-        if (value !== void 0) {
-          url.searchParams.set(key, value);
-        }
-      }
-    }
-    return url.toString();
+  /**
+   * 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);
   }
-  async request(url, init) {
-    const maxAttempts = 3;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      const headers = new Headers(init.headers);
-      headers.set("authorization", `Bearer ${this.config.token}`);
-      if (this.config.workspaceId) {
-        headers.set("x-workspace-id", this.config.workspaceId);
-      }
-      try {
-        headers.set("user-agent", this.config.userAgent);
-      } catch {
-      }
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), this.config.timeout);
-      let res;
-      try {
-        res = await fetch(url, { ...init, headers, signal: controller.signal });
-      } finally {
-        clearTimeout(timeout);
-      }
-      if ((res.status === 429 || res.status >= 500 && res.status <= 599) && attempt < maxAttempts) {
-        const retryAfter = res.headers.get("retry-after");
-        let delayMs = 0;
-        if (retryAfter) {
-          const seconds = Number(retryAfter);
-          delayMs = Number.isFinite(seconds) ? seconds * 1e3 : 0;
-        }
-        if (delayMs <= 0) {
-          delayMs = 250 * attempt;
-        }
-        await new Promise((r) => setTimeout(r, delayMs));
-        continue;
-      }
-      const text = await res.text();
-      let parsed;
-      try {
-        parsed = text ? JSON.parse(text) : void 0;
-      } catch {
-        parsed = text;
-      }
-      if (!res.ok) {
-        const body = parsed;
-        throw new MedalApiError(
-          res.status,
-          body?.error?.code ?? "UNKNOWN_ERROR",
-          body?.error?.message ?? `HTTP ${res.status}: ${res.statusText}`,
-          body?.error?.details
-        );
-      }
-      return parsed;
-    }
-    throw new Error("Request failed after retries");
+  /** 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
+    );
   }
 };
 
@@ -250,6 +463,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 +494,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 +508,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 +603,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 +634,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 +672,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 +724,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 +744,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 +761,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 +781,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 +795,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 +867,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 +884,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 {
@@ -599,6 +897,111 @@ var Helpdesk = class {
   }
 };
 
+// src/resources/portal.ts
+function withSession(session) {
+  return { headers: { "x-portal-session": session } };
+}
+var ONCE = { retry: false };
+var PortalLogin = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * E-mail a one-time code to the address.
+   *
+   * Always 202 `{ status: "sent" }` — enumeration-safe: `"sent"` does not
+   * confirm that the address belongs to a contact. Rate-limited per address
+   * and per caller (`429 RATE_LIMITED`).
+   */
+  async start(input) {
+    return this.client.post("/api/v1/portal/login/start", input);
+  }
+  /**
+   * Exchange the e-mailed code for a session.
+   *
+   * `session_token` is a bearer credential for ONE contact — keep it in an
+   * HttpOnly cookie on the site's server. A wrong, burned or expired code all
+   * answer `401 PORTAL_CODE_INVALID`; the three are not distinguished, so the
+   * response is not an oracle for which codes exist.
+   */
+  async verify(input) {
+    return this.client.post("/api/v1/portal/login/verify", input, ONCE);
+  }
+};
+var Portal = class {
+  constructor(client) {
+    this.client = client;
+    this.login = new PortalLogin(client);
+  }
+  client;
+  /** E-mail one-time-code login: `start` sends the code, `verify` exchanges it. */
+  login;
+  /**
+   * Revoke the session. Resolves to `undefined` (the route answers 204).
+   *
+   * Not keyed: revoking twice reaches the same state — the second call answers
+   * `401 PORTAL_SESSION_INVALID`, which is the outcome you wanted anyway.
+   */
+  async logout(session) {
+    await this.client.post("/api/v1/portal/logout", void 0, {
+      ...withSession(session),
+      ...ONCE
+    });
+  }
+  /** The signed-in contact's own profile. */
+  async me(session) {
+    return this.client.get("/api/v1/portal/me", void 0, withSession(session));
+  }
+  /**
+   * Update the signed-in contact's profile. Only the supplied fields change;
+   * `phone: null` clears the number and `family` replaces the whole list.
+   * `marketing_consent` records a `marketing_email` consent decision with
+   * source `portal`. Returns the profile as it is after the change.
+   */
+  /**
+   * A profile patch is not idempotency-keyed on the server and a `marketing_consent`
+   * change records a dated consent event, so a retry after a committed-but-lost
+   * response would repeat that event: sent exactly once, like the other writes.
+   */
+  async updateMe(session, patch) {
+    return this.client.patch("/api/v1/portal/me", patch, { ...withSession(session), ...ONCE });
+  }
+  /**
+   * The contact's bookings split into `upcoming` and `past`. An upcoming
+   * booking that is still inside the workspace's policy windows carries
+   * `manage_token` and `can_manage: true`; use the token to open the site's
+   * manage page (`medal.bookings.manage.*`).
+   */
+  async myBookings(session) {
+    return this.client.get("/api/v1/portal/me/bookings", void 0, withSession(session));
+  }
+  /**
+   * Everything the workspace holds about the contact — profile, family,
+   * consents and bookings — as one JSON document (GDPR Art. 15). Synchronous,
+   * unlike `medal.gdpr.requestExport()`, which exports the whole workspace.
+   *
+   * Not keyed: a read-only snapshot, so a retried call costs nothing and
+   * duplicates nothing.
+   */
+  async exportMyData(session) {
+    return this.client.post("/api/v1/portal/me/export", void 0, withSession(session));
+  }
+  /**
+   * Erase the contact (GDPR Art. 17). Resolves to `undefined` (the route
+   * answers 204); the session is revoked as part of the deletion.
+   *
+   * Not keyed: deletion is terminal, so a retry meets a revoked session and
+   * answers `401 PORTAL_SESSION_INVALID` rather than deleting anything else.
+   */
+  async deleteMe(session) {
+    await this.client.post("/api/v1/portal/me/delete", void 0, {
+      ...withSession(session),
+      ...ONCE
+    });
+  }
+};
+
 // src/resources/posts.ts
 var Posts = class {
   constructor(client) {
@@ -614,9 +1017,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 +1039,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 +1079,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 +1095,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 +1153,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 +1167,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 +1202,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 +1299,7 @@ async function verifyWebhookSignature(input) {
 
 // src/index.ts
 var Medal = class {
+  bookings;
   capabilityConfirmations;
   channels;
   emails;
@@ -863,6 +1307,7 @@ var Medal = class {
   deals;
   gdpr;
   helpdesk;
+  portal;
   posts;
   scan;
   webhooks;
@@ -885,12 +1330,14 @@ 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);
     this.deals = new Deals(client);
     this.gdpr = new Gdpr(client);
     this.helpdesk = new Helpdesk(client, confirmer);
+    this.portal = new Portal(client);
     this.posts = new Posts(client);
     this.scan = new Scan(client);
     this.webhooks = new Webhooks(client, confirmer);
@@ -903,6 +1350,7 @@ function createMedalClient(apiKey, options) {
 var src_default = Medal;
 export {
   BaseClient,
+  Bookings,
   CAPABILITY_IDS,
   CAPABILITY_ROUTES,
   CapabilityConfirmations,
@@ -916,6 +1364,7 @@ export {
   Helpdesk,
   Medal,
   MedalApiError,
+  Portal,
   Posts,
   Scan,
   WebhookVerificationError,