@docmana/sdk 0.3.5 → 0.8.0

package/CHANGELOG.md

@@ -1,11 +1,40 @@
 # Changelog
 
+## 0.8.0
+- Add organization document depot methods and CLI commands:
+  `listOrganizationDocuments()`, `downloadOrganizationDocument()`, and
+  `downloadOrganizationDocuments()`.
+- Add `docmana organization document list/download`.
+- Make `docmana organization document download --output` optional; default output
+  is `./{path}`.
+
+## 0.7.0
+- Add `getFlowMetadata()` / `docmana flow metadata` for projected flow runtime
+  metadata from `docmana-consumer-edge-api`.
+- Add `getFlowDefinition()` / `docmana flow definition` for normalized flow
+  graph definitions without exposing the Docmana ZIP export.
+
+## 0.6.0
+- Add `listOrganizations()` and `docmana organization list` to list organizations
+  available through `docmana-consumer-edge-api`.
+
+## 0.5.0
+- Add `listFlows()` to list flows available through `docmana-consumer-edge-api`,
+  returning `{ id, name, state }[]` with `state: "unknown"` when Docmana omits it.
+- Add `docmana flow list` CLI command, with the same API URL and Bearer token resolution as `docmana flow run`.
+- Rename `RunFlowInput` to `RunFlowParams` and move polling controls to
+  `RunFlowOptions`.
+- Remove the single-file `file` shortcut from flow params; callers now pass
+  `files`.
+- Remove `fileName` from flow params; byte and stream inputs now use
+  `{ data, filename, contentType? }`.
+- Replace `runFlowWithCallback` with `runFlowAsync(..., { callbackUrl })`.
+
 ## 0.3.5
-- Add `runFlowWithCallback(flowId, input)`: starts a flow and returns `{ executionResultId, fileIds }` **without polling**, registering a `callback_url` so docmana-api POSTs a completion notification when the run finishes. Call `getResult(executionResultId)` on receipt to fetch the mapped result. Works with both `run_flow` and `run_once_flow` (via `input.once`).
-- New `RunFlowWithCallbackInput` type carries the required `callbackUrl` (wire: `callback_url`). It is intentionally separate from `RunFlowInput`: the polling `runFlow`/`runFlowAsync` remain callback-free, so a callback run never polls or fetches the result inline.
+- Add callback execution support: starts a flow and returns `{ executionResultId, fileIds }` **without polling**, registering a `callback_url` so docmana-api POSTs a completion notification when the run finishes. Call `getResult(executionResultId)` on receipt to fetch the mapped result.
 
 ## 0.3.3
-- Add `RunFlowInput.context` (business `json_context`): when provided, `runFlow`/`runFlowAsync` include `json_context` in the request body for both `run_flow` and `run_once_flow`. The context is passed through as-is — filtering against the flow's *Start* node properties is performed server-side by docmana-api.
+- Add `RunFlowParams.context` (business `json_context`): when provided, `runFlow`/`runFlowAsync` include `json_context` in the request body for both `run_flow` and `run_once_flow`. The context is passed through as-is — filtering against the flow's *Start* node properties is performed server-side by docmana-api.
 
 ## 0.3.2
 - Add `scoreDescription` to score-node results (Validation, Classification, CrossValidation, Conclusion).
@@ -29,7 +58,7 @@
 - 400 responses now throw `DocmanaRequestError` (was `DocmanaAuthError`); add `Incompleted` to `ExecutionStatus`.
 
 ## 0.2.0
-- `RunFlowInput.once` selects the ad-hoc `run_once_flow` endpoint (current/draft flow) instead of the published `run_flow`.
+- `RunFlowParams.once` selects the ad-hoc `run_once_flow` endpoint (current/draft flow) instead of the published `run_flow`.
 - `DocmanaConfig.headers` are sent on every API request (e.g. `X-Selected-Organization`), without overriding the bearer token or per-request headers.
 - `FileInput` now accepts a plain `Uint8Array` (e.g. pdf-lib output) in addition to path, `Buffer`, and `Stream`.
 - Uploads send a `Content-Type` inferred from the filename extension instead of always `application/octet-stream`.

package/README.md

@@ -1,12 +1,9 @@
 # @docmana/sdk
 
-Official Docmana SDK — run document-analysis flows with a single call.
+Official Docmana SDK for calling `docmana-consumer-edge-api`.
 
-Docmana's HTTP API requires four steps to analyze a document: upload the file, start a flow run, poll for status, then fetch the result. This SDK collapses all four into one call. Authentication, token caching, and polling are handled for you.
-
-```ts
-const result = await docmana.runFlow("<flow-id>", { file: "./contract.pdf" });
-```
+The SDK sends documents to Consumer, starts an async flow, polls Consumer for
+status, and returns the mapped Consumer execution DTO.
 
 ## Installation
 
@@ -22,107 +19,144 @@ Requires Node.js 20+.
 import { Docmana } from "@docmana/sdk";
 
 const docmana = new Docmana({
-  clientId: process.env.DOCMANA_CLIENT_ID!,
-  clientSecret: process.env.DOCMANA_CLIENT_SECRET!,
+  apiBaseUrl: process.env.DOCMANA_API_URL!,
+  accessToken: process.env.DOCMANA_ACCESS_TOKEN!,
 });
 
-const result = await docmana.runFlow("<flow-id>", { file: "./contract.pdf" });
+const result = await docmana.runFlow("<flow-id>", {
+  files: ["./contract.pdf"],
+  context: { contract: { destination: "Canada" } },
+  useDraftVersion: true,
+});
 
-console.log(result.status, result.results);
+console.log(result.status, result.executionId);
 ```
 
-The package ships both ESM and CommonJS builds. In a CommonJS project:
+## Authentication
 
-```js
-const { Docmana } = require("@docmana/sdk");
+The public SDK is Bearer-only. It does not acquire OAuth tokens and it never
+calls `docmana-api` directly. Provide either a static `accessToken` or a
+`getAccessToken` provider:
 
+```ts
 const docmana = new Docmana({
-  clientId: process.env.DOCMANA_CLIENT_ID,
-  clientSecret: process.env.DOCMANA_CLIENT_SECRET,
+  apiBaseUrl: "https://consumer.example.com/v1",
+  getAccessToken: async ({ forceRefresh } = {}) => {
+    return forceRefresh ? refreshTokenSomehow() : currentToken();
+  },
 });
-
-const result = await docmana.runFlow("<flow-id>", { file: "./contract.pdf" });
 ```
 
-## Authentication
-
-The SDK authenticates with OAuth2 `client_credentials` against the Docmana CIAM tenant. Docmana provisions a `client_id` and `client_secret` for you during onboarding — pass them to the constructor. The SDK acquires the bearer token on the first request, then caches and refreshes it automatically in memory. You never handle tokens directly.
+If Consumer returns `401` and `getAccessToken` is configured, the SDK calls
+`getAccessToken({ forceRefresh: true })` once and retries the request. With a
+static `accessToken`, `401` is returned as an auth error without retry.
 
 ## Configuration
 
-The constructor takes a single `DocmanaConfig` object.
-
-| Field            | Type           | Required | Default                                   | Description                                                  |
-| ---------------- | -------------- | -------- | ----------------------------------------- | ------------------------------------------------------------ |
-| `clientId`       | `string`       | Yes      | —                                         | OAuth2 client ID provisioned by Docmana at onboarding.       |
-| `clientSecret`   | `string`       | Yes      | —                                         | OAuth2 client secret provisioned by Docmana at onboarding.   |
-| `apiBaseUrl`     | `string`       | No       | `https://api.docmana.ai`                  | Base URL of the Docmana API.                                 |
-| `tokenEndpoint`  | `string`       | No       | Docmana CIAM `oauth2/v2.0/token` endpoint | OAuth2 token endpoint used to acquire the bearer token.      |
-| `scope`          | `string`       | No       | `api://d781e6ba-…/.default`               | OAuth2 scope requested for the token.                        |
-| `timeoutMs`      | `number`       | No       | `300000` (5 min)                          | Maximum time `runFlow` will poll before throwing a timeout.  |
-| `pollIntervalMs` | `number`       | No       | `2000` (2 s)                              | Delay between status polls in `runFlow`.                     |
-| `fetch`          | `typeof fetch` | No       | global `fetch`                            | Custom `fetch` implementation (e.g. for proxies or testing). |
-
-Most integrations only set `clientId` and `clientSecret`. The other fields exist for non-production environments or advanced networking needs.
-
-## Inputs
-
-`runFlow(flowId, input)` (and the lower-level `runFlowAsync`) accept a `RunFlowInput`:
-
-| Field            | Type                                                                | Description                                                          |
-| ---------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `file`           | `string \| { path: string } \| Buffer \| NodeJS.ReadableStream`     | A single document. A string or `{ path }` is treated as a file path. |
-| `files`          | `(string \| { path: string } \| Buffer \| NodeJS.ReadableStream)[]` | Multiple documents for a multi-document flow.                        |
-| `fileName`       | `string`                                                            | Required when passing a `Buffer` or stream with no derivable name.   |
-| `signal`         | `AbortSignal`                                                       | Cancels the in-flight run.                                           |
-| `timeoutMs`      | `number`                                                            | Overrides the configured polling timeout for this call.              |
-| `pollIntervalMs` | `number`                                                            | Overrides the configured poll interval for this call.                |
-
-Provide either `file` or `files`.
-
-A file path:
+| Field               | Type                                                                  | Required | Description                                                  |
+| ------------------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------ |
+| `apiBaseUrl`        | `string`                                                              | Yes      | Base URL of Consumer API, including version when applicable. |
+| `accessToken`       | `string`                                                              | One of   | Static Bearer token sent to Consumer.                        |
+| `getAccessToken`    | `(options?: { forceRefresh?: boolean }) => string \| Promise<string>` | One of   | Token provider for renewable Bearer tokens.                  |
+| `timeoutMs`         | `number`                                                              | No       | Maximum polling time for `runFlow`. Default: 5 minutes.      |
+| `pollIntervalMs`    | `number`                                                              | No       | Fallback minimum delay between status polls. Default: 2s.    |
+| `pollMaxIntervalMs` | `number`                                                              | No       | Fallback maximum polling delay. Default: 10s.                |
+| `fetch`             | `typeof fetch`                                                        | No       | Custom fetch implementation.                                 |
+| `headers`           | `Record<string, string>`                                              | No       | Extra headers sent on every Consumer request.                |
+
+`apiBaseUrl` is required so a migrated SDK cannot accidentally call
+`https://api.docmana.ai`.
+
+## Run flow params
+
+`runFlow(flowId, params, options)` and `runFlowAsync(flowId, params, options)`
+use `RunFlowParams` for request data:
+
+| Field             | Type                                                                 | Description                                                            |
+| ----------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `files`           | `(string \| { path: string } \| { data, filename, contentType? })[]` | Documents to upload. A string or `{ path }` is treated as a file path. |
+| `context`         | `Record<string, unknown>`                                            | Business context serialized as multipart `json_context`.               |
+| `language`        | `string`                                                             | Optional result language passed to Consumer.                           |
+| `useDraftVersion` | `boolean`                                                            | Runs the current draft flow version.                                   |
+| `callbackUrl`     | `string`                                                             | Async-only callback URL, serialized as `callback_url`.                 |
+
+`runFlow` uses `RunFlowOptions` for local execution controls:
+
+| Field               | Type              | Description                                                  |
+| ------------------- | ----------------- | ------------------------------------------------------------ |
+| `signal`            | `AbortSignal`     | Cancels the in-flight request/polling.                       |
+| `timeoutMs`         | `number`          | Overrides configured polling timeout for this call.          |
+| `pollIntervalMs`    | `number`          | Overrides configured fallback minimum polling interval.      |
+| `pollMaxIntervalMs` | `number`          | Overrides configured fallback maximum polling interval.      |
+| `onPoll`            | `(event) => void` | Called after each status poll.                               |
+| `onRateLimit`       | `(event) => void` | Called when polling receives `429`; includes `retryAfterMs`. |
+
+`runFlowAsync` accepts `RunFlowAsyncOptions` with `signal`.
+
+`once` was removed. Use `useDraftVersion`.
+
+## Methods
+
+- `listFlows()` calls `GET /v1/flows` and returns `{ id, name, state }[]` for
+  the flows available to the Bearer token. Missing flow states are returned as
+  `"unknown"`.
+- `listOrganizations()` calls `GET /v1/organizations` and returns
+  `{ id, name }[]` for the organizations available to the Bearer token.
+- `getFlowMetadata(flowId)` calls `GET /v1/flows/:flowId/metadata` and returns
+  `{ flowId, name?, contextSchema, languages, minScore?, documents }`.
+- `getFlowDefinition(flowId)` calls `GET /v1/flows/:flowId/definition` and
+  returns the normalized flow definition `{ flowId, name?, languages, minScore?, nodes }`.
+- `listOrganizationDocuments({ prefix? })` calls
+  `GET /v1/organization-documents` and returns `{ configured, documents }`.
+- `downloadOrganizationDocument(path)` calls
+  `GET /v1/organization-documents/download?path=...` and returns
+  `{ bytes, filename, contentType? }`.
+- `downloadOrganizationDocuments(paths)` downloads each requested path.
+- `runFlowAsync(flowId, params, options?)` posts multipart files to
+  `POST /v1/flows/:flowId/execute-async` and returns
+  `{ executionResultId, fileIds }`.
+- `getStatus(executionResultId)` calls
+  `GET /v1/executions/:executionResultId/status`.
+- `getResult(executionResultId, signal?, language?)` calls
+  `GET /v1/executions/:executionResultId/result`.
+- `runFlow(flowId, params, options?)` starts async execution, polls status, fetches the
+  result, respects `X-Poll-After` and `429 Retry-After` while polling, and throws
+  `DocmanaExecutionError` if the result status is `Failed`.
+
+Consumer is the polling authority. When `GET /status` returns `X-Poll-After`,
+the SDK waits that many milliseconds before the next status call. If the header
+is absent, the SDK falls back to capped exponential full jitter between
+`pollIntervalMs` and `pollMaxIntervalMs`. `Retry-After` on `429` always wins.
 
 ```ts
-await docmana.runFlow("<flow-id>", { file: "./contract.pdf" });
+const flows = await docmana.listFlows();
+console.log(flows.map((flow) => `${flow.id}: ${flow.name} (${flow.state})`).join("\n"));
 ```
 
-A `Buffer` (or stream) — supply `fileName` so Docmana can infer the document type:
-
 ```ts
-import { readFile } from "node:fs/promises";
-
-const buffer = await readFile("./contract.pdf");
-await docmana.runFlow("<flow-id>", { file: buffer, fileName: "contract.pdf" });
+const organizations = await docmana.listOrganizations();
+console.log(organizations.map((org) => `${org.id}: ${org.name}`).join("\n"));
 ```
 
-Multiple documents:
-
 ```ts
-await docmana.runFlow("<flow-id>", {
-  files: ["./statement.pdf", "./id-card.png"],
-});
-```
+const metadata = await docmana.getFlowMetadata("<flow-id>");
+console.log(metadata.contextSchema);
 
-Path objects are also supported, which is useful when your caller already models uploads as
-objects:
+const definition = await docmana.getFlowDefinition("<flow-id>");
+console.log(definition.nodes.map((node) => node.label).join("\n"));
+```
 
 ```ts
-await docmana.runFlow("<flow-id>", {
-  files: [{ path: "./contract.pdf" }],
-});
+const depot = await docmana.listOrganizationDocuments({ prefix: "dossier/" });
+if (depot.configured) {
+  const file = await docmana.downloadOrganizationDocument(depot.documents[0].path);
+  console.log(file.filename, file.bytes.byteLength);
+}
 ```
 
-## Lower-level methods
-
-`runFlow` is the recommended entry point. If you need to manage polling yourself — for example to surface progress in your own job queue — the underlying steps are exposed:
-
-- `runFlowAsync(flowId, input)` → `{ executionResultId, fileIds }` — uploads the file(s) and starts the flow without waiting; `fileIds` are the uploaded document UUIDs.
-- `getStatus(executionResultId)` → `{ status }` — current execution status (`"Pending" | "Running" | "Completed" | "Failed"`).
-- `getResult(executionResultId)` → `ExecutionResult` — the result payload once the flow has finished.
-
 ```ts
 const { executionResultId } = await docmana.runFlowAsync("<flow-id>", {
-  file: "./contract.pdf",
+  files: ["./contract.pdf"],
 });
 
 let status = "Pending";
@@ -131,221 +165,130 @@ while (status !== "Completed" && status !== "Failed") {
   ({ status } = await docmana.getStatus(executionResultId));
 }
 
-const result = await docmana.getResult(executionResultId);
-console.log(result.status, result.results);
+const result = await docmana.getResult(executionResultId, undefined, "fr");
 ```
 
-Unlike `runFlow`, `getResult` does not throw on a failed execution — inspect `result.status` and `result.errors` yourself.
-
 ## Webhook callbacks
 
-When you don't want to poll, use `runFlowWithCallback`. It starts the flow with a `callbackUrl` and returns immediately — docmana-api POSTs a completion notification to that URL when the run finishes, so your server never polls.
-
-- `runFlowWithCallback(flowId, input)` → `{ executionResultId, fileIds }` — uploads the file(s) and starts the flow with the callback registered. It does **not** poll and does **not** fetch the result.
-
-`input` is a `RunFlowWithCallbackInput`:
-
-| Field         | Type                                                                | Required | Description                                                                  |
-| ------------- | ------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- |
-| `callbackUrl` | `string`                                                            | Yes      | URL docmana-api POSTs the completion notification to (wire: `callback_url`). |
-| `file`        | `string \| { path: string } \| Buffer \| NodeJS.ReadableStream`     | —        | A single document.                                                           |
-| `files`       | `(string \| { path: string } \| Buffer \| NodeJS.ReadableStream)[]` | —        | Multiple documents for a multi-document flow.                                |
-| `fileName`    | `string`                                                            | —        | Required when passing a `Buffer`/stream with no derivable name.              |
-| `once`        | `boolean`                                                           | —        | Use the ad-hoc `run_once_flow` endpoint instead of `run_flow`.               |
-| `context`     | `Record<string, unknown>`                                           | —        | Business `json_context` passed through to the flow.                          |
-| `signal`      | `AbortSignal`                                                       | —        | Cancels the upload/start.                                                    |
-
-`callbackUrl` lives only on this input — `RunFlowInput` (used by `runFlow`/`runFlowAsync`) has no callback field, so a polling run never registers one.
-
-The notification payload docmana-api sends is a small JSON object, e.g.:
-
-```json
-{
-  "execution_id": "faad872c-…",
-  "status": "Success",
-  "timestamp": "2026-06-08T21:45:28.415402+00:00",
-  "flow_id": "f87bb991-…"
-}
-```
-
-It is a notification only — it does not carry the result. On receipt, fetch and map the full result with `getResult`:
+`runFlowAsync(flowId, params, options?)` accepts `callbackUrl` and sends it as
+`callback_url`. It returns immediately and does not poll.
 
 ```ts
-const { executionResultId } = await docmana.runFlowWithCallback("<flow-id>", {
-  file: "./contract.pdf",
+const { executionResultId } = await docmana.runFlowAsync("<flow-id>", {
+  files: ["./contract.pdf"],
   callbackUrl: "https://your-service.example.com/webhooks/docmana/executions",
+  language: "fr",
 });
-
-// …later, in your webhook handler, keyed by the notification's execution_id:
-const result = await docmana.getResult(execution_id);
-console.log(result.status, result.results);
 ```
 
-## CLI
-
-The package also installs a `docmana` command for simple terminal usage:
+Consumer posts the mapped result DTO to your callback URL when the execution is
+finished. Keep `executionResultId` if you also want to poll as a fallback.
 
-```bash
-docmana flow run "<flow-id>" --files "./contract.pdf" --organisation "<organisation-id>"
-```
+## CLI
 
-You can create a local config file interactively:
+The CLI can still acquire and cache a token through OAuth:
 
 ```bash
 docmana config init
+docmana login
 ```
 
-This writes `docmana.config.json` in the current directory. The file can include Docmana URLs,
-scope, organisation, client id, and client secret, so it is ignored by Git.
+`docmana login` reads `clientId`, `clientSecret`, `tokenEndpoint`, and `scope`
+from flags, environment variables, or `docmana.config.json`, then stores the
+access token in `docmana.token.json`.
 
-Use a custom config path when needed:
+`docmana flow run` always passes a Bearer token to the SDK. It resolves the token
+in this order:
 
-```bash
-docmana config init --config ./docmana.dev.config.json
-docmana flow run "<flow-id>" --files "./contract.pdf" --config ./docmana.dev.config.json
-```
-
-`flow run` automatically loads `./docmana.config.json` when present. Credentials and connection
-settings can also be read from the environment:
+1. `--access-token`
+2. `DOCMANA_ACCESS_TOKEN`
+3. valid `docmana.token.json`
+4. OAuth refresh using CLI/config credentials
 
 ```bash
-DOCMANA_CLIENT_ID="<client-id>"
-DOCMANA_CLIENT_SECRET="<client-secret>"
-DOCMANA_ORGANISATION="<organisation-id>"
-DOCMANA_API_URL="https://api.docmana.ai"
-DOCMANA_TOKEN_URL="<token-endpoint>"
-DOCMANA_SCOPE="<oauth-scope>"
-
-docmana flow run "<flow-id>" --files "./contract.pdf,./annexe.pdf"
+DOCMANA_API_URL="https://consumer.example.com/v1"
+docmana flow list
 ```
 
-You can override config or environment values with flags:
-
 ```bash
-docmana flow run "<flow-id>" \
-  --files "./contract.pdf" \
-  --client-id "<client-id>" \
-  --client-secret "<client-secret>" \
-  --organisation "<organisation-id>" \
-  --api-url "https://api.docmana.ai" \
-  --token-url "<token-endpoint>" \
-  --scope "<oauth-scope>"
+DOCMANA_API_URL="https://consumer.example.com/v1"
+docmana organization list
 ```
 
-The CLI caches OAuth2 access tokens in `docmana.token.json` by default, so repeated commands do
-not request a new token until the cached token expires. The cache file is ignored by Git. Use a
-custom token cache path when needed:
-
 ```bash
-docmana login
-docmana flow run "<flow-id>" --files "./contract.pdf" --token-cache ./docmana.dev.token.json
+DOCMANA_API_URL="https://consumer.example.com/v1"
+docmana organization document list --prefix "dossier/"
+docmana organization document download "dossier/facture.pdf"
+docmana organization document download "dossier/facture.pdf" --output "./facture.pdf"
 ```
 
-`docmana login` loads the same config, environment variables, and auth flags as `flow run`, then
-ensures a valid token is cached. It does not print the token.
-
-By default, the CLI prints a human-readable summary with a preview of the results. Use `--json`
-to print the complete result payload to stdout:
-
 ```bash
-docmana flow run "<flow-id>" --files "./contract.pdf" --organisation "<organisation-id>" --json
+DOCMANA_API_URL="https://consumer.example.com/v1"
+docmana flow metadata "<flow-id>"
+docmana flow definition "<flow-id>"
 ```
 
-`--files` is a simple comma-separated list. Paths containing commas are not supported.
-
-To build the local checkout and expose the `docmana` command on your machine:
-
 ```bash
-npm run cli:link
+DOCMANA_API_URL="https://consumer.example.com/v1"
+docmana flow run "<flow-id>" --files "./contract.pdf"
 ```
 
-Then run:
+You can also run without the cache:
 
 ```bash
-docmana flow run "<flow-id>" --files "./contract.pdf" --organisation "<organisation-id>"
-```
-
-## Error handling
-
-Every error thrown by the SDK extends `DocmanaError`, which carries `.status` (HTTP status, when applicable), `.code`, and an optional `.requestId`.
-
-| Error                    | Thrown when                                                                     |
-| ------------------------ | ------------------------------------------------------------------------------- |
-| `DocmanaRequestError`    | `400` — bad request (e.g. calling for a result before the flow has finished).   |
-| `DocmanaAuthError`       | `401` — bad credentials, wrong scope, or an expired/rejected token.             |
-| `DocmanaPermissionError` | `403` — the client is missing the `access_m2m_apps` role.                       |
-| `DocmanaNotFoundError`   | `404` — the flow or endpoint was not found.                                     |
-| `DocmanaExecutionError`  | The flow finished with status `"Failed"`. Carries the flow errors in `.errors`. |
-| `DocmanaTimeoutError`    | Polling exceeded `timeoutMs` before the flow reached a terminal state.          |
-| `DocmanaAbortError`      | The provided `AbortSignal` fired.                                               |
-
-```ts
-import {
-  Docmana,
-  DocmanaAuthError,
-  DocmanaExecutionError,
-  DocmanaTimeoutError,
-} from "@docmana/sdk";
-
-try {
-  const result = await docmana.runFlow("<flow-id>", { file: "./contract.pdf" });
-  console.log(result.results);
-} catch (err) {
-  if (err instanceof DocmanaAuthError) {
-    // Check client_id / client_secret / scope.
-  } else if (err instanceof DocmanaExecutionError) {
-    console.error("Flow failed:", err.errors);
-  } else if (err instanceof DocmanaTimeoutError) {
-    // Retry, or raise timeoutMs.
-  } else {
-    throw err;
-  }
-}
+docmana flow run "<flow-id>" \
+  --api-url "https://consumer.example.com/v1" \
+  --access-token "$DOCMANA_ACCESS_TOKEN" \
+  --files "./contract.pdf,./annexe.pdf" \
+  --draft \
+  --json
 ```
 
-## Security
+Use `--draft` to run the current draft flow version.
+Use `docmana flow list --json` to print the raw flow list returned by Consumer.
+Use `docmana organization list --json` to print the organization list as JSON.
+Use `docmana organization document list --json` for raw organization document JSON.
+`docmana flow metadata` and `docmana flow definition` print JSON by default.
 
-Treat `clientSecret` as a credential with full access to your Docmana account.
+The CLI no longer sends `X-Selected-Organization`; Consumer derives identity
+from the Bearer token.
 
-- Store `clientId` and `clientSecret` in a secrets manager (Azure Key Vault, AWS Secrets Manager, etc.).
-- Never commit them to source control, and never expose them in a browser or frontend bundle — this SDK is server-side only.
-- Never log them.
-
-The SDK keeps the bearer token in memory only. It is never written to disk.
+## Error handling
 
-## Requirements
+Every SDK error extends `DocmanaError`, which carries `.status`, `.code`, and an
+optional `.requestId` when available.
 
-- Node.js 20 or later.
-- ESM and CommonJS are both supported.
+| Error                    | Thrown when                                                                |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `DocmanaRequestError`    | `400` bad request.                                                         |
+| `DocmanaAuthError`       | `401` rejected or expired Bearer token.                                    |
+| `DocmanaPermissionError` | `403` missing permission.                                                  |
+| `DocmanaNotFoundError`   | `404` flow or execution not found.                                         |
+| `DocmanaExecutionError`  | The flow finished with status `"Failed"`. Carries `.errors` and `.result`. |
+| `DocmanaTimeoutError`    | Polling exceeded `timeoutMs`.                                              |
+| `DocmanaAbortError`      | The provided `AbortSignal` fired.                                          |
 
 ## Local development with yalc
 
-To test changes to this SDK inside a consuming project without publishing to npm, use [yalc](https://github.com/wclr/yalc).
-
-In **this library**:
+In this library:
 
 ```bash
 npm run dev
 ```
 
-This runs `tsup` in watch mode. After every rebuild it runs `yalc push`, propagating the freshly built package to every project that has linked it.
-
-In the **consuming project** (once):
+In the consuming project:
 
 ```bash
 yalc add @docmana/sdk
 npm install
 ```
 
-From then on, each change you save here is rebuilt and pushed automatically — the consumer picks it up without reinstalling. To stop using the local copy and restore the registry version:
+For a one-shot publish to the local yalc store:
 
 ```bash
-yalc remove @docmana/sdk
-npm install
+npm run yalc:publish
 ```
 
-For a single one-shot publish to the local yalc store (no watch), use `npm run yalc:publish`.
-
 ## License
 
 MIT

package/dist/api/execution-result.d.ts

@@ -0,0 +1,3 @@
+import type { HttpClient } from "../http/http-client.js";
+import type { DocmanaExecutionResult } from "../types.js";
+export declare function getResult(http: HttpClient, executionResultId: string, signal?: AbortSignal, language?: string): Promise<DocmanaExecutionResult>;

package/dist/api/execution-status.d.ts

@@ -0,0 +1,6 @@
+import type { HttpClient } from "../http/http-client.js";
+import type { ExecutionStatus } from "../types.js";
+export declare function getStatus(http: HttpClient, executionResultId: string, signal?: AbortSignal): Promise<{
+    status: ExecutionStatus | string;
+    pollAfterMs?: number;
+}>;

package/dist/api/flow-definition.d.ts

@@ -0,0 +1,3 @@
+import type { HttpClient } from "../http/http-client.js";
+import type { FlowDefinition } from "../types.js";
+export declare function getFlowDefinition(http: HttpClient, flowId: string): Promise<FlowDefinition>;

package/dist/api/flow-metadata.d.ts

@@ -0,0 +1,3 @@
+import type { HttpClient } from "../http/http-client.js";
+import type { FlowMetadata } from "../types.js";
+export declare function getFlowMetadata(http: HttpClient, flowId: string): Promise<FlowMetadata>;

package/dist/api/list-flows.d.ts

@@ -0,0 +1,3 @@
+import type { HttpClient } from "../http/http-client.js";
+import type { FlowListItem } from "../types.js";
+export declare function listFlows(http: HttpClient): Promise<FlowListItem[]>;

package/dist/api/list-organizations.d.ts

@@ -0,0 +1,3 @@
+import type { HttpClient } from "../http/http-client.js";
+import type { AccessibleOrganization } from "../types.js";
+export declare function listOrganizations(http: HttpClient): Promise<AccessibleOrganization[]>;

package/dist/api/organization-documents.d.ts

@@ -0,0 +1,7 @@
+import type { HttpClient } from "../http/http-client.js";
+import type { DownloadedOrganizationDocument, OrganizationDocumentsPayload } from "../types.js";
+export declare function listOrganizationDocuments(http: HttpClient, options?: {
+    prefix?: string;
+}): Promise<OrganizationDocumentsPayload>;
+export declare function downloadOrganizationDocument(http: HttpClient, path: string): Promise<DownloadedOrganizationDocument>;
+export declare function downloadOrganizationDocuments(http: HttpClient, paths: string[]): Promise<DownloadedOrganizationDocument[]>;

package/dist/api/run-flow.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedPart } from "../files/resolve-input.js";
+import type { HttpClient } from "../http/http-client.js";
+export declare function runFlow(http: HttpClient, flowId: string, parts: ResolvedPart[], signal?: AbortSignal, useDraftVersion?: boolean, context?: Record<string, unknown>, callbackUrl?: string, language?: string): Promise<{
+    executionResultId: string;
+    fileIds: string[];
+}>;