@docmana/sdk 0.4.0 → 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

@@ -24,7 +24,7 @@ const docmana = new Docmana({
 });
 
 const result = await docmana.runFlow("<flow-id>", {
-  file: "./contract.pdf",
+  files: ["./contract.pdf"],
   context: { contract: { destination: "Canada" } },
   useDraftVersion: true,
 });
@@ -67,37 +67,59 @@ static `accessToken`, `401` is returned as an auth error without retry.
 `apiBaseUrl` is required so a migrated SDK cannot accidentally call
 `https://api.docmana.ai`.
 
-## Inputs
-
-`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`.         |
+## 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
 
-- `runFlowAsync(flowId, input)` posts multipart files to
+- `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, input)` starts async execution, polls status, fetches the
+- `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`.
 
@@ -106,9 +128,35 @@ 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 flows = await docmana.listFlows();
+console.log(flows.map((flow) => `${flow.id}: ${flow.name} (${flow.state})`).join("\n"));
+```
+
+```ts
+const organizations = await docmana.listOrganizations();
+console.log(organizations.map((org) => `${org.id}: ${org.name}`).join("\n"));
+```
+
+```ts
+const metadata = await docmana.getFlowMetadata("<flow-id>");
+console.log(metadata.contextSchema);
+
+const definition = await docmana.getFlowDefinition("<flow-id>");
+console.log(definition.nodes.map((node) => node.label).join("\n"));
+```
+
+```ts
+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);
+}
+```
+
 ```ts
 const { executionResultId } = await docmana.runFlowAsync("<flow-id>", {
-  file: "./contract.pdf",
+  files: ["./contract.pdf"],
 });
 
 let status = "Pending";
@@ -122,12 +170,12 @@ const result = await docmana.getResult(executionResultId, undefined, "fr");
 
 ## Webhook callbacks
 
-`runFlowWithCallback` uses the same Consumer async endpoint with `callback_url`.
-It returns immediately and does not poll.
+`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",
 });
@@ -157,6 +205,29 @@ in this order:
 3. valid `docmana.token.json`
 4. OAuth refresh using CLI/config credentials
 
+```bash
+DOCMANA_API_URL="https://consumer.example.com/v1"
+docmana flow list
+```
+
+```bash
+DOCMANA_API_URL="https://consumer.example.com/v1"
+docmana organization list
+```
+
+```bash
+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"
+```
+
+```bash
+DOCMANA_API_URL="https://consumer.example.com/v1"
+docmana flow metadata "<flow-id>"
+docmana flow definition "<flow-id>"
+```
+
 ```bash
 DOCMANA_API_URL="https://consumer.example.com/v1"
 docmana flow run "<flow-id>" --files "./contract.pdf"
@@ -174,6 +245,10 @@ docmana flow run "<flow-id>" \
 ```
 
 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.
 
 The CLI no longer sends `X-Selected-Organization`; Consumer derives identity
 from the Bearer token.

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[]>;