@superclerk/sdk 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 (2026-11-07)
+
+The first release, pinned to API version `2026-11-05`.
+
+- A typed method for every endpoint of the public API, and a typed input and output for every integration tool.
+- `tools.run`, `connect.links.wait`, `connections.fetch`, `social.media.upload`, and `webhooks.unwrap` and `webhooks.sign`.
+- Retries that are safe by construction: one `Idempotency-Key` per call, repeated on every retry, with the same bytes.
+- `SUPERCLERK_LOG=debug` prints each attempt and retry with its request ID.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benrov, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,265 @@
-# Temporary Holding Version
+# Superclerk TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official TypeScript client for the [Superclerk API](https://docs.superclerk.com): connections and their tools, the
+provider proxy, social posts and media, CRM, conversations, workflows and webhooks. It is generated from the API's
+OpenAPI document and its tool catalog, so every method, parameter and answer is typed, and so is every tool's input and
+output.
+
+It depends on nothing but `fetch` and WebCrypto. It needs Node.js 20.19 or later, or Bun. It's an ES module, which
+CommonJS code can `require` on those versions.
+
+```sh
+npm install @superclerk/sdk
+```
+
+## Usage
+
+```ts
+import { Superclerk } from "@superclerk/sdk"
+
+const superclerk = new Superclerk({ apiKey: process.env.SUPERCLERK_API_KEY })
+
+const contact = await superclerk.contacts.create({ displayName: "Ada Lovelace" })
+```
+
+`apiKey` defaults to the `SUPERCLERK_API_KEY` environment variable; [create a key](https://docs.superclerk.com/authentication)
+in Settings → Developer API. Every method is listed in [api.md](./api.md).
+
+## Connect an account
+
+A connect link is a URL you send to the person whose account it is. `connect.links.wait` reads the link until they
+finish.
+
+```ts
+const link = await superclerk.connect.links.create({ appID: "gmail", returnURL: "https://example.com/done" })
+// Send link.url to the person whose account it is, then wait while they finish.
+const finished = await superclerk.connect.links.wait(link.id)
+if (finished.status === "succeeded") console.log(finished.connection?.id)
+```
+
+## Run a tool
+
+`tools.run` runs a tool on a connection, or a built-in tool by its app, and answers its output. Both are typed by the
+tool, so a wrong input is a compile error.
+
+```ts
+const { messageId } = await superclerk.tools.run({
+  tool: "gmail_send_email",
+  connectionID: "itn_123",
+  input: { to: ["ada@example.com"], subject: "Hello", bodyText: "Hi Ada" },
+})
+```
+
+A run that ends failed throws `ToolRunError`, whose `code` is the run's error kind. To start a run without waiting for
+it, call `tools.runs.create` and read it later with `tools.runs.wait`.
+
+## Call a provider's API
+
+`connections.fetch` sends a request to the provider's own API with the connection's credentials, and answers the
+provider's response as it came, whatever its status. The path and query go as you wrote them. An app has a proxy when
+`apps.get` lists its `proxy.methods`, as Meta Ads and Google Ads do.
+
+```ts
+const response = await superclerk.connections.fetch("itn_123", "/me/adaccounts?fields=id,name")
+const accounts = await response.json()
+```
+
+A run that fails, such as a write whose outcome is unknown, throws `APIError` rather than answering as the provider.
+
+## Schedule a social post
+
+```ts
+import { readFile } from "node:fs/promises"
+
+const asset = await superclerk.social.media.upload(await readFile("launch.png"), {
+  filename: "launch.png",
+  contentType: "image/png",
+  storageAccess: "private",
+})
+const { accounts } = await superclerk.social.accounts.list()
+await superclerk.social.posts.create({
+  content: "We're live.",
+  mediaItems: [{ assetId: asset.id }],
+  platforms: [{ platform: "threads", accountId: accounts[0]!.id, platformSpecificData: {} }],
+  scheduledFor: "2026-12-01T09:00:00Z",
+})
+```
+
+To finish an upload that was cut off, call `upload` again with the same `idempotencyKey`: an asset already ready comes
+back at once, and bytes already stored are confirmed rather than sent again.
+
+## Pages
+
+A list method answers its first page when awaited, and every item across every page when iterated. `body` is the
+page's whole answer, with any fields beside its items, such as an opportunity list's `stageCounts`.
+
+```ts
+const page = await superclerk.contacts.list({ limit: 50 })
+page.items
+page.nextCursor
+
+for await (const contact of superclerk.contacts.list()) {
+  console.log(contact.displayName)
+}
+```
+
+## Webhooks
+
+`webhooks.unwrap` verifies a delivery's [Standard Webhooks](https://www.standardwebhooks.com) signature and answers its
+event, typed by its type. Pass the body exactly as it arrived, before any JSON parsing.
+
+```ts
+const event = await superclerk.webhooks.unwrap(await request.text(), request.headers, {
+  secret: process.env.SUPERCLERK_WEBHOOK_SECRET,
+})
+if (event.type === "contact.created") console.log(event.data.contactID)
+```
+
+The secret defaults to the client's `webhookSecret` option, then the `SUPERCLERK_WEBHOOK_SECRET` environment variable.
+A delivery that doesn't verify throws `WebhookVerificationError`.
+
+To test your endpoint, `webhooks.sign` makes the delivery Superclerk would send for an event, signed with the same
+secret:
+
+```ts
+const { body, headers } = await superclerk.webhooks.sign({
+  id: "evt_test",
+  type: "contact.created",
+  createdAt: new Date().toISOString(),
+  data: { contactID: "cct_123" },
+})
+await fetch("http://localhost:3000/webhooks/superclerk", { method: "POST", body, headers })
+```
+
+## Client workspaces
+
+An agency's key acts in the agency's own workspace. To act in one of its client workspaces, name it on the client or on
+one request:
+
+```ts
+const client = superclerk.withOptions({ workspace: "org_client" })
+await superclerk.contacts.list({}, { workspace: "org_client" })
+```
+
+An operation takes a client workspace only when its reference names the `Superclerk-Workspace` header. The rest act in
+the key's own workspace alone, and answer `403 workspace_not_supported` when a request names another.
+
+## Errors
+
+Everything the SDK throws is a `SuperclerkError`, apart from the reason you abort a call with. Branch on its `code`,
+which names the failure the way the API does. A request with wrong fields throws `invalid_request`, and its message
+names each one, such as `Request does not match the endpoint schema (input.url: Invalid URL)`.
+
+| Error                      | When                                                                                              |
+| -------------------------- | ------------------------------------------------------------------------------------------------- |
+| `APIError`                 | The API answered with a status that isn't 2xx: `status`, `code`, `message`, `fields`, `requestID` |
+| `APIConnectionError`       | No whole answer came: `connection_failed`, or `timeout`                                           |
+| `ToolRunError`             | A run `tools.run` started ended failed or cancelled: `run`                                        |
+| `WebhookVerificationError` | A webhook's signature didn't verify                                                               |
+
+```ts
+import { APIError } from "@superclerk/sdk"
+
+const contact = await superclerk.contacts.get("cct_123")
+try {
+  await superclerk.contacts.update(contact.id, { expectedRevision: contact.revision, displayName: "Ada King" })
+} catch (error) {
+  if (error instanceof APIError && error.code === "revision_conflict") {
+    // Someone else changed the contact first: read it again and retry.
+  }
+}
+```
+
+## Retries and idempotency
+
+A failed attempt is retried twice by default, with exponential backoff and jitter, and the wait a `Retry-After` header
+asks for:
+
+- a refusal before any work started (429, 503) is always retried
+- a timeout, a dropped connection or a 5xx is retried only when the call repeats harmlessly: a read, a `PUT` or
+  `DELETE`, or a write the API deduplicates by its `Idempotency-Key`
+
+The SDK sends an `Idempotency-Key` with every write that takes one, and repeats it on every retry of that call. To
+retry a write across processes, pass your own:
+
+```ts
+// Saved with the work, so a retry from another process sends the same key.
+const idempotencyKey = crypto.randomUUID()
+await superclerk.contacts.create({ displayName: "Ada" }, { idempotencyKey, maxRetries: 5 })
+```
+
+## Timeouts and cancelling
+
+An attempt times out when no answer has started within 60 seconds by default; once one has, reading it takes as long
+as it takes. Set `timeout` (in milliseconds) on the client or one request, or pass an `AbortSignal`, which also stops
+reading an answer. The helpers that wait, such as `tools.run`, ask the API to hold each read for the timeout less five
+seconds, up to the 30 seconds it holds, so a short timeout polls rather than timing out.
+
+```ts
+const controller = new AbortController()
+await superclerk.connections.list({}, { timeout: 5_000, signal: controller.signal })
+```
+
+## Raw responses
+
+```ts
+const { data, response, requestID } = await superclerk.contacts.get("cct_123").withResponse()
+const raw = await superclerk.contacts.get("cct_123").asResponse()
+```
+
+## Endpoints the SDK doesn't have yet
+
+`request` sends any operation in the [API reference](https://docs.superclerk.com/reference), such as one newer than your
+SDK, with the client's key, retries and timeouts, and answers its parsed body. Set `idempotent: true` on a write that
+takes an `Idempotency-Key`, and the SDK sends one and repeats it on every retry.
+
+```ts
+const contact = await superclerk.request<{ id: string }>({
+  method: "GET",
+  path: "/v1/contacts/cct_123",
+  response: "json",
+})
+```
+
+## Debugging
+
+Set `SUPERCLERK_LOG=debug` to print every attempt to stderr: its method, host and path, status, time and request ID,
+and each retry with its wait. Queries are left out, since an upload URL's query is a credential.
+
+```text
+[superclerk] POST api.superclerk.com/v1/tools/runs → 503 in 41 ms (req_8f2…)
+[superclerk] retrying in 500 ms after 503
+[superclerk] POST api.superclerk.com/v1/tools/runs → 202 in 1012 ms (req_c41…)
+```
+
+Quote the request ID when you write to support.
+
+## Coding agents
+
+Every method and type carries its documentation, and `api.md` lists every method, for the version you installed. Add
+this to your repository's `AGENTS.md` or `CLAUDE.md` so an agent reads them before writing Superclerk code:
+
+```md
+## Superclerk
+
+- Call the Superclerk API through `@superclerk/sdk`. Read `node_modules/@superclerk/sdk/README.md`, and `api.md`
+  beside it for every method, before writing Superclerk code.
+- Run tools with `superclerk.tools.run`; it waits for the run and throws `ToolRunError` when the run fails.
+- Ask before running a tool that writes, sends or posts. Never print or commit the API key.
+- Docs: https://docs.superclerk.com/llms.txt, or the docs MCP server at https://docs.superclerk.com/mcp.
+```
+
+Requests carry a `User-Agent` such as `superclerk-js/0.1.0 node/22.12.0 darwin-arm64`, which ends in the agent's name,
+such as `agent/claude_code`, when a coding agent runs the process. It names the SDK, runtime and agent, nothing else.
+
+## API versions
+
+The SDK pins the API version it was generated from, sent as the `Superclerk-Version` header, so a later API version
+can't change answers under your code. Upgrading the SDK moves you to the newer version. `API_VERSION` names it.
+
+## Development
+
+This package lives in the Superclerk repository. `bun run generate` regenerates `src/generated`, `api.md` and
+`test/generated` from `docs-site/openapi.json` and `docs-site/integrations.json`; the hand-written client is in
+`src/core` and the helpers above in `src/lib`. `bun test` runs the tests, and `bun run build` builds the package into
+`dist`, then loads it in Node.

package/api.md

@@ -0,0 +1,310 @@
+# Superclerk TypeScript SDK reference
+
+Generated from the public OpenAPI document. Every method returns an `APIPromise`; a list method returns a `PagePromise` you can await for one page or iterate for every item. See the README for the hand-written helpers: `tools.run`, `tools.runs.wait`, `connect.links.wait`, `connections.fetch`, `social.media.upload` and `webhooks.unwrap`.
+
+## connect
+
+### connect.links
+
+- `client.connect.links.create(params?)` → `ConnectLinkCreated` — `POST /v1/connect/links`
+- `client.connect.links.get(connectLinkID)` → `ConnectLink` — `GET /v1/connect/links/{connectLinkID}`
+
+## webhooks
+
+- `client.webhooks.list(params?)` → `WebhooksListResponse (paged)` — `GET /v1/webhooks`
+- `client.webhooks.create(params)` → `WebhookCreated` — `POST /v1/webhooks`
+- `client.webhooks.get(webhookID)` → `Webhook` — `GET /v1/webhooks/{webhookID}`
+- `client.webhooks.disable(webhookID)` → `Webhook` — `POST /v1/webhooks/{webhookID}/disable`
+
+### webhooks.deliveries
+
+- `client.webhooks.deliveries.list(webhookID, params?)` → `WebhooksDeliveriesListResponse (paged)` — `GET /v1/webhooks/{webhookID}/deliveries`
+- `client.webhooks.deliveries.replay(deliveryID, params)` → `WebhooksDeliveriesReplayResponse` — `POST /v1/webhooks/{webhookID}/deliveries/{deliveryID}/replay`
+
+## tools
+
+- `client.tools.list(params?)` → `ToolsListResponse` — `GET /v1/tools`
+
+### tools.runs
+
+- `client.tools.runs.create(params)` → `ToolsRunsCreateResponse` — `POST /v1/tools/runs`
+- `client.tools.runs.get(runID)` → `ToolsRunsGetResponse` — `GET /v1/tools/runs/{runID}`
+
+## workspaces
+
+- `client.workspaces.list(params?)` → `WorkspacesListResponse (paged)` — `GET /v1/workspaces`
+- `client.workspaces.create(params)` → `Workspace` — `POST /v1/workspaces`
+
+## apps
+
+- `client.apps.list(params?)` → `AppsListResponse` — `GET /v1/apps`
+- `client.apps.get(appID)` → `AppsGetResponse` — `GET /v1/apps/{appID}`
+
+### apps.tools
+
+- `client.apps.tools.list(appID, params?)` → `AppsToolsListResponse` — `GET /v1/apps/{appID}/tools`
+
+## connections
+
+- `client.connections.list(params?)` → `ConnectionsListResponse (paged)` — `GET /v1/connections`
+- `client.connections.get(connectionID)` → `Connection` — `GET /v1/connections/{connectionID}`
+- `client.connections.delete(connectionID)` → `Connection` — `DELETE /v1/connections/{connectionID}`
+
+### connections.accounts
+
+- `client.connections.accounts.list(connectionID, params?)` → `ConnectionsAccountsListResponse` — `GET /v1/connections/{connectionID}/accounts`
+- `client.connections.accounts.add(connectionID, params)` → `Connection` — `POST /v1/connections/{connectionID}/accounts`
+- `client.connections.accounts.remove(connectionID, params)` → `Connection` — `DELETE /v1/connections/{connectionID}/accounts`
+
+### connections.tools
+
+- `client.connections.tools.list(connectionID, params?)` → `ConnectionsToolsListResponse` — `GET /v1/connections/{connectionID}/tools`
+
+### connections.proxy
+
+- `client.connections.proxy.get(providerPath, params)` → `Response` — `GET /v1/connections/{connectionID}/proxy/{providerPath}`
+- `client.connections.proxy.post(providerPath, params)` → `Response` — `POST /v1/connections/{connectionID}/proxy/{providerPath}`
+- `client.connections.proxy.delete(providerPath, params)` → `Response` — `DELETE /v1/connections/{connectionID}/proxy/{providerPath}`
+
+#### connections.proxy.runs
+
+- `client.connections.proxy.runs.get(runID)` → `Response` — `GET /v1/connections/proxy/runs/{runID}`
+
+## social
+
+### social.accounts
+
+- `client.social.accounts.list()` → `SocialAccountsListResponse` — `GET /v1/social/accounts`
+- `client.social.accounts.disconnect(socialAccountID)` → `SocialAccountsDisconnectResponse` — `DELETE /v1/social/accounts/{socialAccountID}`
+
+#### social.accounts.analytics
+
+- `client.social.accounts.analytics.overview(socialAccountID)` → `SocialAccountsAnalyticsOverviewResponse` — `GET /v1/social/accounts/{socialAccountID}/analytics`
+- `client.social.accounts.analytics.posts(socialAccountID, params?)` → `SocialAccountsAnalyticsPostsResponse` — `GET /v1/social/accounts/{socialAccountID}/analytics/posts`
+
+#### social.accounts.tiktok
+
+- `client.social.accounts.tiktok.analytics(socialAccountID)` → `SocialAccountsTiktokAnalyticsResponse` — `GET /v1/social/accounts/{socialAccountID}/tiktok/analytics`
+- `client.social.accounts.tiktok.videos(socialAccountID, params?)` → `SocialAccountsTiktokVideosResponse` — `GET /v1/social/accounts/{socialAccountID}/tiktok/videos`
+
+### social.media
+
+- `client.social.media.list(params?)` → `SocialMediaListResponse (paged)` — `GET /v1/social/media`
+- `client.social.media.create(params)` → `SocialMediaCreateResponse` — `POST /v1/social/media`
+- `client.social.media.confirm(mediaID)` → `SocialMediaConfirmResponse` — `POST /v1/social/media/{mediaID}/confirm`
+- `client.social.media.download(mediaID)` → `SocialMediaDownloadResponse` — `GET /v1/social/media/{mediaID}/download`
+- `client.social.media.get(mediaID)` → `SocialMediaGetResponse` — `GET /v1/social/media/{mediaID}`
+
+### social.posts
+
+- `client.social.posts.list(params?)` → `SocialPostsListResponse (paged)` — `GET /v1/social/posts`
+- `client.social.posts.create(params)` → `SocialPostsCreateResponse` — `POST /v1/social/posts`
+- `client.social.posts.get(postID)` → `SocialPostsGetResponse` — `GET /v1/social/posts/{postID}`
+- `client.social.posts.update(postID, params)` → `SocialPostsUpdateResponse` — `PUT /v1/social/posts/{postID}`
+- `client.social.posts.reschedule(postID, params)` → `SocialPostsRescheduleResponse` — `POST /v1/social/posts/{postID}/reschedule`
+- `client.social.posts.cancel(postID, params)` → `SocialPostsCancelResponse` — `POST /v1/social/posts/{postID}/cancel`
+
+## conversations
+
+- `client.conversations.list(params?)` → `ConversationsListResponse (paged)` — `GET /v1/conversations`
+- `client.conversations.get(conversationID)` → `Conversation` — `GET /v1/conversations/{conversationID}`
+- `client.conversations.update(conversationID, params)` → `Conversation` — `PATCH /v1/conversations/{conversationID}`
+- `client.conversations.takeOver(conversationID)` → `Conversation` — `POST /v1/conversations/{conversationID}/take_over`
+- `client.conversations.handBack(conversationID)` → `Conversation` — `POST /v1/conversations/{conversationID}/hand_back`
+
+### conversations.messages
+
+- `client.conversations.messages.list(conversationID, params?)` → `ConversationsMessagesListResponse (paged)` — `GET /v1/conversations/{conversationID}/messages`
+- `client.conversations.messages.create(conversationID, params)` → `ConversationMessage` — `POST /v1/conversations/{conversationID}/messages`
+
+## tags
+
+- `client.tags.list(params?)` → `TagsListResponse (paged)` — `GET /v1/tags`
+- `client.tags.create(params)` → `TagsCreateResponse` — `POST /v1/tags`
+
+## contacts
+
+- `client.contacts.list(params?)` → `ContactsListResponse (paged)` — `GET /v1/contacts`
+- `client.contacts.create(params)` → `Contact` — `POST /v1/contacts`
+- `client.contacts.import(params)` → `ContactImport` — `POST /v1/contacts/import`
+- `client.contacts.get(contactID)` → `Contact` — `GET /v1/contacts/{contactID}`
+- `client.contacts.update(contactID, params)` → `Contact` — `PATCH /v1/contacts/{contactID}`
+- `client.contacts.archive(contactID, params)` → `Contact` — `POST /v1/contacts/{contactID}/archive`
+- `client.contacts.unarchive(contactID, params)` → `Contact` — `POST /v1/contacts/{contactID}/unarchive`
+- `client.contacts.merge(contactID, params)` → `Contact` — `POST /v1/contacts/{contactID}/merge`
+
+### contacts.lifecycle
+
+- `client.contacts.lifecycle.get()` → `ContactLifecycle` — `GET /v1/contacts/lifecycle`
+- `client.contacts.lifecycle.update(params)` → `ContactLifecycle` — `PUT /v1/contacts/lifecycle`
+
+#### contacts.lifecycle.stages
+
+- `client.contacts.lifecycle.stages.create(params)` → `ContactLifecycle` — `POST /v1/contacts/lifecycle/stages`
+- `client.contacts.lifecycle.stages.archive(lifecycleStageID, params)` → `ContactLifecycle` — `POST /v1/contacts/lifecycle/stages/{lifecycleStageID}/archive`
+
+### contacts.identities
+
+- `client.contacts.identities.create(contactID, params)` → `ContactIdentity` — `POST /v1/contacts/{contactID}/identities`
+- `client.contacts.identities.delete(identityID, params)` → `Contact` — `DELETE /v1/contacts/{contactID}/identities/{identityID}`
+- `client.contacts.identities.move(identityID, params)` → `Contact` — `POST /v1/contacts/{contactID}/identities/{identityID}/move`
+
+### contacts.notes
+
+- `client.contacts.notes.list(contactID, params?)` → `ContactsNotesListResponse (paged)` — `GET /v1/contacts/{contactID}/notes`
+- `client.contacts.notes.create(contactID, params)` → `ContactNote` — `POST /v1/contacts/{contactID}/notes`
+- `client.contacts.notes.delete(noteID, params)` → `Contact` — `DELETE /v1/contacts/{contactID}/notes/{noteID}`
+
+### contacts.tags
+
+- `client.contacts.tags.add(tagID, params)` → `Contact` — `PUT /v1/contacts/{contactID}/tags/{tagID}`
+- `client.contacts.tags.remove(tagID, params)` → `Contact` — `DELETE /v1/contacts/{contactID}/tags/{tagID}`
+
+### contacts.opportunities
+
+- `client.contacts.opportunities.list(contactID, params?)` → `ContactsOpportunitiesListResponse (paged)` — `GET /v1/contacts/{contactID}/opportunities`
+
+## customFields
+
+- `client.customFields.list(params)` → `CustomFieldsListResponse (paged)` — `GET /v1/custom_fields`
+- `client.customFields.create(params)` → `CustomFieldsCreateResponse` — `POST /v1/custom_fields`
+- `client.customFields.update(customFieldID, params)` → `CustomField` — `PUT /v1/custom_fields/{customFieldID}`
+- `client.customFields.archive(customFieldID, params)` → `CustomField` — `POST /v1/custom_fields/{customFieldID}/archive`
+- `client.customFields.unarchive(customFieldID, params)` → `CustomField` — `POST /v1/custom_fields/{customFieldID}/unarchive`
+
+## members
+
+- `client.members.list(params?)` → `MembersListResponse (paged)` — `GET /v1/members`
+- `client.members.get(memberID)` → `Member` — `GET /v1/members/{memberID}`
+
+## pipelines
+
+- `client.pipelines.list(params?)` → `PipelinesListResponse (paged)` — `GET /v1/pipelines`
+- `client.pipelines.create(params)` → `Pipeline` — `POST /v1/pipelines`
+- `client.pipelines.get(pipelineID)` → `Pipeline` — `GET /v1/pipelines/{pipelineID}`
+- `client.pipelines.update(pipelineID, params)` → `Pipeline` — `PUT /v1/pipelines/{pipelineID}`
+- `client.pipelines.archive(pipelineID, params)` → `Pipeline` — `POST /v1/pipelines/{pipelineID}/archive`
+
+### pipelines.stages
+
+- `client.pipelines.stages.archive(stageID, params)` → `Pipeline` — `POST /v1/pipelines/{pipelineID}/stages/{stageID}/archive`
+
+## opportunities
+
+- `client.opportunities.list(params)` → `OpportunitiesListResponse (paged)` — `GET /v1/opportunities`
+- `client.opportunities.create(params)` → `Opportunity` — `POST /v1/opportunities`
+- `client.opportunities.get(opportunityID)` → `Opportunity` — `GET /v1/opportunities/{opportunityID}`
+- `client.opportunities.update(opportunityID, params)` → `Opportunity` — `PATCH /v1/opportunities/{opportunityID}`
+- `client.opportunities.move(opportunityID, params)` → `Opportunity` — `POST /v1/opportunities/{opportunityID}/move`
+- `client.opportunities.archive(opportunityID, params)` → `Opportunity` — `POST /v1/opportunities/{opportunityID}/archive`
+- `client.opportunities.unarchive(opportunityID, params)` → `Opportunity` — `POST /v1/opportunities/{opportunityID}/unarchive`
+
+### opportunities.history
+
+- `client.opportunities.history.list(opportunityID, params?)` → `OpportunitiesHistoryListResponse (paged)` — `GET /v1/opportunities/{opportunityID}/history`
+
+## tasks
+
+- `client.tasks.list(params?)` → `TasksListResponse (paged)` — `GET /v1/tasks`
+- `client.tasks.create(params)` → `Task` — `POST /v1/tasks`
+- `client.tasks.update(taskID, params)` → `Task` — `PATCH /v1/tasks/{taskID}`
+- `client.tasks.archive(taskID, params)` → `Task` — `POST /v1/tasks/{taskID}/archive`
+
+## inbox
+
+### inbox.accounts
+
+- `client.inbox.accounts.list(params?)` → `InboxAccountsListResponse (paged)` — `GET /v1/inbox/accounts`
+- `client.inbox.accounts.remove(connectionID, params?)` → `InboxAIRemoval` — `POST /v1/inbox/accounts/{connectionID}/remove`
+
+#### inbox.accounts.ai
+
+- `client.inbox.accounts.ai.create(connectionID, params)` → `InboxAI` — `POST /v1/inbox/accounts/{connectionID}/ai`
+
+#### inbox.accounts.settings
+
+- `client.inbox.accounts.settings.get(connectionID, params?)` → `InboxAccountSettings` — `GET /v1/inbox/accounts/{connectionID}/settings`
+- `client.inbox.accounts.settings.update(connectionID, params)` → `InboxAccountSettings` — `PUT /v1/inbox/accounts/{connectionID}/settings`
+
+### inbox.templates
+
+- `client.inbox.templates.list(params?)` → `InboxTemplatesListResponse (paged)` — `GET /v1/inbox/templates`
+
+### inbox.agents
+
+- `client.inbox.agents.republish(agentID)` → `InboxAgentUpdate` — `POST /v1/inbox/agents/{agentID}/republish`
+
+## workflows
+
+- `client.workflows.list(params?)` → `WorkflowsListResponse` — `GET /v1/workflows`
+- `client.workflows.create(params)` → `WorkflowsCreateResponse` — `POST /v1/workflows`
+- `client.workflows.batchGet(params)` → `WorkflowsBatchGetResponse` — `POST /v1/workflows/batch_get`
+- `client.workflows.test(workflowID, params)` → `WorkflowRun` — `POST /v1/workflows/{workflowID}/test`
+- `client.workflows.get(workflowID)` → `WorkflowsGetResponse` — `GET /v1/workflows/{workflowID}`
+- `client.workflows.validate(workflowID)` → `WorkflowsValidateResponse` — `POST /v1/workflows/{workflowID}/validate`
+- `client.workflows.publish(workflowID, params)` → `WorkflowsPublishResponse` — `POST /v1/workflows/{workflowID}/publish`
+- `client.workflows.archive(workflowID, params)` → `WorkflowsArchiveResponse` — `POST /v1/workflows/{workflowID}/archive`
+- `client.workflows.pause(workflowID)` → `WorkflowsPauseResponse` — `POST /v1/workflows/{workflowID}/pause`
+- `client.workflows.resume(workflowID)` → `WorkflowsResumeResponse` — `POST /v1/workflows/{workflowID}/resume`
+
+### workflows.catalog
+
+- `client.workflows.catalog.get()` → `WorkflowCatalogResponse` — `GET /v1/workflows/catalog`
+
+### workflows.templates
+
+- `client.workflows.templates.list()` → `WorkflowsTemplatesListResponse` — `GET /v1/workflows/templates`
+- `client.workflows.templates.instantiate(templateID, params)` → `WorkflowsTemplatesInstantiateResponse` — `POST /v1/workflows/templates/{templateID}/instantiate`
+
+### workflows.alertDestinations
+
+- `client.workflows.alertDestinations.list()` → `WorkflowsAlertDestinationsListResponse` — `GET /v1/workflows/alert_destinations`
+- `client.workflows.alertDestinations.create(params)` → `WorkflowFailureAlertDestination` — `POST /v1/workflows/alert_destinations`
+- `client.workflows.alertDestinations.delete(alertDestinationID)` → `WorkflowsAlertDestinationsDeleteResponse` — `DELETE /v1/workflows/alert_destinations/{alertDestinationID}`
+
+### workflows.triggerFailures
+
+- `client.workflows.triggerFailures.list(params?)` → `WorkflowsTriggerFailuresListResponse` — `GET /v1/workflows/trigger_failures`
+- `client.workflows.triggerFailures.retry(triggerFailureID)` → `WorkflowsTriggerFailuresRetryResponse` — `POST /v1/workflows/trigger_failures/{triggerFailureID}/retry`
+
+### workflows.runs
+
+- `client.workflows.runs.list(params?)` → `WorkflowsRunsListResponse` — `GET /v1/workflows/runs`
+- `client.workflows.runs.get(workflowRunID)` → `WorkflowsRunsGetResponse` — `GET /v1/workflows/runs/{workflowRunID}`
+- `client.workflows.runs.cancel(workflowRunID)` → `WorkflowRun` — `POST /v1/workflows/runs/{workflowRunID}/cancel`
+- `client.workflows.runs.rerun(workflowRunID, params)` → `WorkflowRun` — `POST /v1/workflows/runs/{workflowRunID}/rerun`
+- `client.workflows.runs.create(workflowID, params)` → `WorkflowRun` — `POST /v1/workflows/{workflowID}/runs`
+
+#### workflows.runs.steps
+
+- `client.workflows.runs.steps.get(stepID, params)` → `WorkflowActivationPayload` — `GET /v1/workflows/runs/{workflowRunID}/steps/{stepID}`
+- `client.workflows.runs.steps.signal(stepID, params)` → `WorkflowsRunsStepsSignalResponse` — `POST /v1/workflows/runs/{workflowRunID}/steps/{stepID}/signal`
+
+### workflows.humanTasks
+
+- `client.workflows.humanTasks.list(params?)` → `WorkflowsHumanTasksListResponse` — `GET /v1/workflows/human_tasks`
+- `client.workflows.humanTasks.get(humanTaskID)` → `WorkflowHumanTask` — `GET /v1/workflows/human_tasks/{humanTaskID}`
+- `client.workflows.humanTasks.resolve(humanTaskID, params)` → `WorkflowHumanTask` — `POST /v1/workflows/human_tasks/{humanTaskID}/resolve`
+
+### workflows.draft
+
+- `client.workflows.draft.update(workflowID, params)` → `WorkflowsDraftUpdateResponse` — `PUT /v1/workflows/{workflowID}/draft`
+
+### workflows.webhook
+
+- `client.workflows.webhook.get(workflowID)` → `WorkflowsWebhookGetResponse` — `GET /v1/workflows/{workflowID}/webhook`
+- `client.workflows.webhook.rotate(workflowID, params)` → `WorkflowWebhookSecretReveal` — `POST /v1/workflows/{workflowID}/webhook/rotate`
+
+### workflows.versions
+
+- `client.workflows.versions.list(workflowID, params?)` → `WorkflowsVersionsListResponse` — `GET /v1/workflows/{workflowID}/versions`
+- `client.workflows.versions.get(workflowVersionID, params)` → `WorkflowVersionSnapshot` — `GET /v1/workflows/{workflowID}/versions/{workflowVersionID}`
+- `client.workflows.versions.activate(workflowVersionID, params)` → `WorkflowsVersionsActivateResponse` — `POST /v1/workflows/{workflowID}/versions/{workflowVersionID}/activate`
+
+## agents
+
+- `client.agents.list()` → `WorkflowAgentsResponse` — `GET /v1/agents`
+
+## receptionists
+
+- `client.receptionists.list()` → `ReceptionistsListResponse` — `GET /v1/receptionists`

package/core/api-promise.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What every method returns: a promise of the parsed answer that also hands over the raw response. The request starts
+ * when the method is called, like fetch; the body is parsed once, when the promise is first awaited.
+ */
+export declare class APIPromise<T> extends Promise<T> {
+    #private;
+    private readonly response;
+    private readonly parse;
+    constructor(response: Promise<Response>, parse: (response: Response) => Promise<T>);
+    /** The raw response, its body unread. Await the promise or call withResponse instead to read the body. */
+    asResponse(): Promise<Response>;
+    /** The parsed answer with the response it came in and the request's ID. */
+    withResponse(): Promise<{
+        data: T;
+        response: Response;
+        requestID: string | null;
+    }>;
+    private parsed;
+    then<Result = T, Failure = never>(onfulfilled?: ((value: T) => Result | PromiseLike<Result>) | null, onrejected?: ((reason: unknown) => Failure | PromiseLike<Failure>) | null): Promise<Result | Failure>;
+    catch<Failure = never>(onrejected?: ((reason: unknown) => Failure | PromiseLike<Failure>) | null): Promise<T | Failure>;
+    finally(onfinally?: (() => void) | null): Promise<T>;
+}
+/**
+ * Reads the body of an answer the SDK parses. Your abort rejects with its reason; any other failure means the answer
+ * never arrived whole.
+ */
+export declare function readBody<T>(read: Promise<T>, signal: AbortSignal | undefined): Promise<T>;