@docmana/sdk 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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.
+
 ## 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.
 

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,103 +19,92 @@ 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>", {
+  file: "./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 | 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.                |
 
-| 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.
+`apiBaseUrl` is required so a migrated SDK cannot accidentally call
+`https://api.docmana.ai`.
 
 ## 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:
-
-```ts
-await docmana.runFlow("<flow-id>", { file: "./contract.pdf" });
-```
-
-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" });
-```
-
-Multiple documents:
-
-```ts
-await docmana.runFlow("<flow-id>", {
-  files: ["./statement.pdf", "./id-card.png"],
-});
-```
-
-Path objects are also supported, which is useful when your caller already models uploads as
-objects:
-
-```ts
-await docmana.runFlow("<flow-id>", {
-  files: [{ path: "./contract.pdf" }],
-});
-```
-
-## 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.
+`runFlow(flowId, input)` and `runFlowAsync(flowId, input)` accept:
+
+| 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.   |
+| `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.                                 |
+| `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`.         |
+
+`once` was removed. Use `useDraftVersion`.
+
+## Methods
+
+- `runFlowAsync(flowId, input)` 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, input)` 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
 const { executionResultId } = await docmana.runFlowAsync("<flow-id>", {
@@ -131,177 +117,103 @@ 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
 
-## CLI
-
-The package also installs a `docmana` command for simple terminal usage:
-
-```bash
-docmana flow run "<flow-id>" --files "./contract.pdf" --organisation "<organisation-id>"
-```
+`runFlowWithCallback` uses the same Consumer async endpoint with `callback_url`.
+It returns immediately and does not poll.
 
-You can create a local config file interactively:
-
-```bash
-docmana config init
-```
-
-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.
-
-Use a custom config path when needed:
-
-```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:
-
-```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"
+```ts
+const { executionResultId } = await docmana.runFlowWithCallback("<flow-id>", {
+  file: "./contract.pdf",
+  callbackUrl: "https://your-service.example.com/webhooks/docmana/executions",
+  language: "fr",
+});
 ```
 
-You can override config or environment values with flags:
+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" \
-  --client-id "<client-id>" \
-  --client-secret "<client-secret>" \
-  --organisation "<organisation-id>" \
-  --api-url "https://api.docmana.ai" \
-  --token-url "<token-endpoint>" \
-  --scope "<oauth-scope>"
-```
+## CLI
 
-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:
+The CLI can still acquire and cache a token through OAuth:
 
 ```bash
+docmana config init
 docmana login
-docmana flow run "<flow-id>" --files "./contract.pdf" --token-cache ./docmana.dev.token.json
 ```
 
-`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.
+`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`.
 
-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:
+`docmana flow run` always passes a Bearer token to the SDK. It resolves the token
+in this order:
 
-```bash
-docmana flow run "<flow-id>" --files "./contract.pdf" --organisation "<organisation-id>" --json
-```
-
-`--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:
+1. `--access-token`
+2. `DOCMANA_ACCESS_TOKEN`
+3. valid `docmana.token.json`
+4. OAuth refresh using CLI/config credentials
 
 ```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.
 
-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/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[];
+}>;