@docmana/sdk 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.2.1
+- 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`.
+- `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`.
+
+## 0.1.0
+- Single-call `runFlow` orchestration: upload → run → poll → result.
+- OAuth2 client-credentials auth with in-memory token cache and automatic refresh.
+- Typed error hierarchy (`DocmanaError`, `DocmanaExecutionError`, …).
+- Flexible file inputs: path, `Buffer`, `Stream`, and multi-file uploads.
+- Dual ESM + CJS distribution with bundled type definitions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Docmana
+
+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

@@ -0,0 +1,307 @@
+# @docmana/sdk
+
+Official Docmana SDK — run document-analysis flows with a single call.
+
+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" });
+```
+
+## Installation
+
+```bash
+npm install @docmana/sdk
+```
+
+Requires Node.js 20+.
+
+## Quickstart
+
+```ts
+import { Docmana } from "@docmana/sdk";
+
+const docmana = new Docmana({
+  clientId: process.env.DOCMANA_CLIENT_ID!,
+  clientSecret: process.env.DOCMANA_CLIENT_SECRET!,
+});
+
+const result = await docmana.runFlow("<flow-id>", { file: "./contract.pdf" });
+
+console.log(result.status, result.results);
+```
+
+The package ships both ESM and CommonJS builds. In a CommonJS project:
+
+```js
+const { Docmana } = require("@docmana/sdk");
+
+const docmana = new Docmana({
+  clientId: process.env.DOCMANA_CLIENT_ID,
+  clientSecret: process.env.DOCMANA_CLIENT_SECRET,
+});
+
+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.
+
+## 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:
+
+```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.
+
+```ts
+const { executionResultId } = await docmana.runFlowAsync("<flow-id>", {
+  file: "./contract.pdf",
+});
+
+let status = "Pending";
+while (status !== "Completed" && status !== "Failed") {
+  await new Promise((r) => setTimeout(r, 2000));
+  ({ status } = await docmana.getStatus(executionResultId));
+}
+
+const result = await docmana.getResult(executionResultId);
+console.log(result.status, result.results);
+```
+
+Unlike `runFlow`, `getResult` does not throw on a failed execution — inspect `result.status` and `result.errors` yourself.
+
+## CLI
+
+The package also installs a `docmana` command for simple terminal usage:
+
+```bash
+docmana flow run "<flow-id>" --files "./contract.pdf" --organisation "<organisation-id>"
+```
+
+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"
+```
+
+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>"
+```
+
+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 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
+```
+
+`--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
+```
+
+Then run:
+
+```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;
+  }
+}
+```
+
+## Security
+
+Treat `clientSecret` as a credential with full access to your Docmana account.
+
+- 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.
+
+## Requirements
+
+- Node.js 20 or later.
+- ESM and CommonJS are both supported.
+
+## 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**:
+
+```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):
+
+```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:
+
+```bash
+yalc remove @docmana/sdk
+npm install
+```
+
+For a single one-shot publish to the local yalc store (no watch), use `npm run yalc:publish`.
+
+## License
+
+MIT