@medalsocial/sdk 1.5.0 → 1.6.0

package/dist/src/index.mjs

@@ -1,3 +1,113 @@
+// 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,12 +233,37 @@ var BaseClient = class {
   }
 };
 
+// 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.
+   */
+  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.
    *
@@ -141,28 +276,64 @@ var ChannelConnectLinks = class {
    * need the workspace `admin` role.
    */
   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.post("/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 +341,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);
   }
 };
 
@@ -344,10 +521,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 +545,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,10 +568,12 @@ 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.
    *
@@ -395,15 +581,21 @@ var HelpdeskReplies = class {
    * messages — it is REQUIRED for capability-scoped tokens.
    */
   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.post("/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);
   }
 };
 
@@ -452,12 +644,71 @@ 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()`.
+   *
+   * @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) {
+    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.post("/api/v1/scan", { [key]: input[key] });
+  }
+  /** 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");
@@ -475,7 +726,12 @@ var Webhooks = class {
    * endpoint WITHOUT the secret — handle that case (rotate if you lost it).
    */
   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.post("/api/v1/webhooks", input, resolved);
   }
   /** Get a webhook endpoint by ID. */
   async get(id) {
@@ -483,7 +739,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 +753,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) {
@@ -590,6 +856,7 @@ async function verifyWebhookSignature(input) {
 
 // src/index.ts
 var Medal = class {
+  capabilityConfirmations;
   channels;
   emails;
   contacts;
@@ -597,6 +864,7 @@ var Medal = class {
   gdpr;
   helpdesk;
   posts;
+  scan;
   webhooks;
   workspaces;
   constructor(token, options) {
@@ -612,14 +880,20 @@ 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.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 +903,10 @@ function createMedalClient(apiKey, options) {
 var src_default = Medal;
 export {
   BaseClient,
+  CAPABILITY_IDS,
+  CAPABILITY_ROUTES,
+  CapabilityConfirmations,
+  CapabilityConfirmer,
   Channels,
   Contacts,
   DEFAULT_WEBHOOK_TOLERANCE_MS,
@@ -639,6 +917,7 @@ export {
   Medal,
   MedalApiError,
   Posts,
+  Scan,
   WebhookVerificationError,
   Webhooks,
   Workspaces,