@dokus/client 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,36 @@
+Dokus SDK Pre-Release Evaluation License
+
+Copyright (c) 2026 Dokus. All rights reserved.
+
+Subject to the restrictions below, Dokus grants you a limited, revocable,
+non-exclusive, non-transferable, non-sublicensable license to install and use
+this pre-release SDK solely to evaluate Dokus and to develop and test
+integrations that communicate with Dokus services using credentials you are
+authorized to use.
+
+You may not:
+
+1. use the SDK in production or provide it as part of a production service;
+2. copy, publish, redistribute, sublicense, sell, rent, lease, or otherwise
+   make the SDK available to another party;
+3. modify the SDK, create derivative works from it, or reverse engineer,
+   decompile, or disassemble it, except to the limited extent applicable law
+   expressly prohibits this restriction;
+4. use the SDK or information derived from it to create or improve a product
+   or service that competes with Dokus; or
+5. remove or alter proprietary notices.
+
+Dokus and its licensors retain all ownership and intellectual-property rights
+in the SDK. No rights are granted except those stated expressly in this
+license. Access to Dokus services remains subject to the applicable service
+terms and may be suspended or terminated independently of this license.
+
+This license terminates automatically if you breach it or when Dokus replaces
+this pre-release license for the SDK version you use. On termination, you must
+stop using and delete the SDK.
+
+THE SDK IS PRE-RELEASE SOFTWARE PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY LAW,
+DOKUS WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL,
+OR EXEMPLARY DAMAGES, OR FOR LOSS OF DATA, PROFITS, REVENUE, OR BUSINESS,
+ARISING FROM OR RELATED TO THE SDK.

package/README.md

@@ -0,0 +1,114 @@
+# `@dokus/client`
+
+Server-only, typed HTTP access to Dokus document rendering, runs, outputs, and
+workflow generation. Use `@dokus/contracts` to author semantic render intent,
+then send that inert contract inline with the render request.
+
+This alpha is evaluation software under the included restrictive license. It
+is ESM-only and requires Node.js 22.12 or newer.
+
+```sh
+npm install @dokus/client@alpha
+```
+
+```ts
+import { createDokusClient } from "@dokus/client";
+import {
+  JSON_SCHEMA_DRAFT_2020_12,
+  defineRenderContract,
+  input,
+  values,
+} from "@dokus/contracts";
+
+const dokus = createDokusClient({
+  apiKey: process.env.DOKUS_API_KEY!,
+});
+
+const contract = defineRenderContract({
+  inputSchema: {
+    $schema: JSON_SCHEMA_DRAFT_2020_12,
+    type: "object",
+    properties: { customerName: { type: "string" } },
+    required: ["customerName"],
+    additionalProperties: false,
+  },
+  rules: [values({ "customer.name": input("customerName") })],
+});
+
+const started = await dokus.documents.render(
+  {
+    documentId: "019e744b-8ed8-7dab-a72a-a894043f2f37",
+    versionId: "019e744d-fd08-7c8f-b292-434a214e660b",
+    contract,
+    data: { customerName: "Ada Lovelace" },
+    generatePdf: true,
+    mode: "async",
+  },
+  { idempotencyKey: "render-quarterly-report-2026-q3" },
+);
+
+const run = await dokus.runs.wait(started.runId);
+```
+
+The inline contract path is the real no-download scripting path: the server
+loads the exact selected document version, resolves aliases and placeholder
+keys, compiles the contract to a fingerprint-bound render plan, and renders it.
+Callers do not download or modify a DKSD package.
+
+`@dokus/dksd` provides pure authoring artifacts and transaction types, but the
+public API does not yet mount persistence or mutation endpoints for document
+definitions, snapshots, snapshot packages, or transactions. Accordingly,
+`@dokus/client` does not expose decorative methods for those operations. It
+also has no persisted-contract resource; submit contracts inline to
+`documents.render`.
+
+The client never reads credentials from the environment. The example reads the
+environment in application code and passes the value into a closure explicitly.
+Do not import this package in a browser or web worker; conditional exports and a
+runtime check reject those environments.
+
+## Resources
+
+- `documents.render` accepts data, exact version selection, either `planId` or
+  an inline contract, sync/async mode, PDF/DOCX output choices, and output
+  expiry.
+- `runs.get`, `outputs`, `outputDownload`, `rotatePreviewLink`,
+  `revokePreviewLink`, `delete`, and `wait` operate on mounted run/output routes.
+- `workflows.generate`, `generateSync`, `generateAll`, and `documentRuns`
+  expose the currently mounted workflow operations. Workflow generation does
+  not accept plan or contract selectors.
+
+`documents.render` calls `POST /api/documents/:documentId/run`. `planId` and an
+inline `contract: DokusRenderContractV1` are mutually exclusive. Select a
+version with either `version: "latest" | "draft"` or an exact `versionId`, not
+both.
+
+The default `mode: "sync"` returns `DokusDocumentRenderCompleted`: the canonical
+run result plus `documentId`, `documentVersionId`, and the selected `planId`.
+Explicit `mode: "async"` returns `DokusDocumentRenderStarted` with the pending
+run identity; pass its `runId` to `runs.wait`.
+
+All public option and input records must be plain or null-prototype data
+objects. Unknown, inherited, accessor, non-enumerable, and symbol-keyed fields
+are rejected before any request is sent. JSON request values are cloned from
+descriptors without invoking getters and must be strict JSON: no `undefined`,
+functions, symbols, bigint, non-finite numbers, cycles, sparse/decorated arrays,
+or class instances. Requests are bounded to 32 nesting levels, 100,000 nodes,
+and 1 MiB of UTF-8 JSON.
+
+State-changing calls require an `idempotencyKey` of 8-128 safe opaque
+characters as a stable operation identifier. The currently mounted public
+routes do not promise durable replay or deduplication, so the client never
+automatically retries POST, PUT, or DELETE. Treat an ambiguous write failure as
+non-retryable until application code has reconciled the operation's state.
+Only GET requests are retried on transient network errors and HTTP 408, 429,
+502, 503, or 504. `Retry-After` is honored within the configured delay cap.
+
+Every request has a deadline, composes with an application `AbortSignal`, sends
+an `x-request-id`, rejects redirects, bounds response reads, and maps failures
+to the exported `DokusError` hierarchy. Errors do not retain request headers or
+request bodies, and API-key values are redacted from server messages/details.
+
+JSON routes use `{ "success": true, "data": ... }`. Errors use
+`{ "success": false, "error": { "code", "message", "details"? } }` and should
+return `x-request-id`; throttling/transient responses may return `Retry-After`.

package/dist/browser-denied.d.ts

@@ -0,0 +1,8 @@
+export { D as DokusAbortError, a as DokusApiError, i as DokusApiErrorCode, b as DokusConnectionError, c as DokusError, j as DokusKnownApiErrorCode, d as DokusProtocolError, e as DokusResponseTooLargeError, f as DokusTimeoutError, g as DokusValidationError, h as DokusWaitTimeoutError } from './errors-Ce8Vc6yb.js';
+
+declare const DOKUS_API_BASE_URL = "https://api.dokus.pro";
+declare function createDokusClient(_options: {
+    readonly apiKey: string;
+}): never;
+
+export { DOKUS_API_BASE_URL, createDokusClient };

package/dist/browser-denied.js

@@ -0,0 +1,12 @@
+import { DokusValidationError } from './chunk-RJGJ7P2Y.js';
+export { DokusAbortError, DokusApiError, DokusConnectionError, DokusError, DokusProtocolError, DokusResponseTooLargeError, DokusTimeoutError, DokusValidationError, DokusWaitTimeoutError } from './chunk-RJGJ7P2Y.js';
+
+// src/browser-denied.ts
+var DOKUS_API_BASE_URL = "https://api.dokus.pro";
+function createDokusClient(_options) {
+  throw new DokusValidationError(
+    "@dokus/client is server-only; keep Dokus API keys out of browsers and web workers."
+  );
+}
+
+export { DOKUS_API_BASE_URL, createDokusClient };

package/dist/chunk-RJGJ7P2Y.js

@@ -0,0 +1,73 @@
+// src/errors.ts
+var DokusError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DokusError";
+  }
+};
+var DokusValidationError = class extends DokusError {
+  constructor(message) {
+    super(message);
+    this.name = "DokusValidationError";
+  }
+};
+var DokusConnectionError = class extends DokusError {
+  constructor(requestId) {
+    super("The Dokus API could not be reached.");
+    this.requestId = requestId;
+    this.name = "DokusConnectionError";
+  }
+};
+var DokusAbortError = class extends DokusError {
+  constructor(requestId) {
+    super("The Dokus API request was aborted.");
+    this.requestId = requestId;
+    this.name = "DokusAbortError";
+  }
+};
+var DokusTimeoutError = class extends DokusError {
+  constructor(timeoutMs, requestId) {
+    super(`The Dokus API request timed out after ${timeoutMs}ms.`);
+    this.timeoutMs = timeoutMs;
+    this.requestId = requestId;
+    this.name = "DokusTimeoutError";
+  }
+};
+var DokusProtocolError = class extends DokusError {
+  constructor(requestId) {
+    super("The Dokus API returned an invalid response.");
+    this.requestId = requestId;
+    this.name = "DokusProtocolError";
+  }
+};
+var DokusResponseTooLargeError = class extends DokusError {
+  constructor(limitBytes, requestId) {
+    super(`The Dokus API response exceeded the ${limitBytes}-byte limit.`);
+    this.limitBytes = limitBytes;
+    this.requestId = requestId;
+    this.name = "DokusResponseTooLargeError";
+  }
+};
+var DokusApiError = class extends DokusError {
+  constructor(message, status, requestId, code, details, retryAfterMs) {
+    super(message);
+    this.status = status;
+    this.requestId = requestId;
+    this.code = code;
+    this.details = details;
+    this.retryAfterMs = retryAfterMs;
+    this.name = "DokusApiError";
+  }
+};
+var DokusWaitTimeoutError = class extends DokusError {
+  constructor(timeoutMs, lastStatus) {
+    super(
+      `Run polling timed out after ${timeoutMs}ms with status "${lastStatus}".`
+    );
+    this.timeoutMs = timeoutMs;
+    this.lastStatus = lastStatus;
+    this.name = "DokusWaitTimeoutError";
+  }
+};
+
+export { DokusAbortError, DokusApiError, DokusConnectionError, DokusError, DokusProtocolError, DokusResponseTooLargeError, DokusTimeoutError, DokusValidationError, DokusWaitTimeoutError };

package/dist/errors-Ce8Vc6yb.d.ts

@@ -0,0 +1,45 @@
+type DokusKnownApiErrorCode = "VALIDATION_ERROR" | "NOT_FOUND" | "UNAUTHORIZED" | "FORBIDDEN" | "CONFLICT" | "ACTIVE_RUN_CONFLICT" | "VERSION_NOT_FOUND" | "UNSUPPORTED_GENERATION_FORMAT" | "SYNC_SIZE_EXCEEDED" | "OUTPUT_NOT_READY" | "NO_ROOT_DOCUMENTS" | "INVALID_DOCUMENT_SELECTION" | "GENERATION_START_FAILED" | "RATE_LIMIT_EXCEEDED";
+type DokusApiErrorCode = DokusKnownApiErrorCode | (string & {});
+declare class DokusError extends Error {
+    constructor(message: string);
+}
+declare class DokusValidationError extends DokusError {
+    constructor(message: string);
+}
+declare class DokusConnectionError extends DokusError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
+declare class DokusAbortError extends DokusError {
+    readonly requestId?: string | undefined;
+    constructor(requestId?: string | undefined);
+}
+declare class DokusTimeoutError extends DokusError {
+    readonly timeoutMs: number;
+    readonly requestId: string;
+    constructor(timeoutMs: number, requestId: string);
+}
+declare class DokusProtocolError extends DokusError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
+declare class DokusResponseTooLargeError extends DokusError {
+    readonly limitBytes: number;
+    readonly requestId: string;
+    constructor(limitBytes: number, requestId: string);
+}
+declare class DokusApiError extends DokusError {
+    readonly status: number;
+    readonly requestId: string;
+    readonly code?: DokusApiErrorCode | undefined;
+    readonly details?: unknown | undefined;
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, status: number, requestId: string, code?: DokusApiErrorCode | undefined, details?: unknown | undefined, retryAfterMs?: number | undefined);
+}
+declare class DokusWaitTimeoutError extends DokusError {
+    readonly timeoutMs: number;
+    readonly lastStatus: string;
+    constructor(timeoutMs: number, lastStatus: string);
+}
+
+export { DokusAbortError as D, DokusApiError as a, DokusConnectionError as b, DokusError as c, DokusProtocolError as d, DokusResponseTooLargeError as e, DokusTimeoutError as f, DokusValidationError as g, DokusWaitTimeoutError as h, type DokusApiErrorCode as i, type DokusKnownApiErrorCode as j };

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+import { DokusRenderContractV1, JsonObject } from '@dokus/contracts';
+export { D as DokusAbortError, a as DokusApiError, i as DokusApiErrorCode, b as DokusConnectionError, c as DokusError, j as DokusKnownApiErrorCode, d as DokusProtocolError, e as DokusResponseTooLargeError, f as DokusTimeoutError, g as DokusValidationError, h as DokusWaitTimeoutError } from './errors-Ce8Vc6yb.js';
+
+interface DokusRetryOptions {
+    /** Total attempts, including the first request. Defaults to 3; maximum 10. */
+    readonly maxAttempts?: number;
+    /** Maximum delay between attempts. Defaults to 30 seconds. */
+    readonly maxDelayMs?: number;
+}
+interface DokusClientOptions {
+    /** API key captured by the server-only client closure. */
+    readonly apiKey: string;
+    /** Dokus API origin. Defaults to https://api.dokus.pro. */
+    readonly baseUrl?: string;
+    /** Explicit fetch implementation, primarily for testing or custom Node dispatch. */
+    readonly fetch?: typeof fetch;
+    /** Default whole-request deadline. Defaults to 30 seconds. */
+    readonly timeoutMs?: number;
+    /** Retry GET requests; false disables retries. Writes are never retried. */
+    readonly retry?: false | DokusRetryOptions;
+}
+interface DokusRequestOptions {
+    readonly signal?: AbortSignal;
+    /** Override the client's request deadline for this call. */
+    readonly timeoutMs?: number;
+    /** Optional caller request ID; otherwise the client generates a UUID. */
+    readonly requestId?: string;
+}
+interface DokusWriteOptions extends DokusRequestOptions {
+    /** Stable operation identifier sent to the API; it does not imply durable replay. */
+    readonly idempotencyKey: string;
+}
+type DokusRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+type DokusOutputStatus = "pending" | "processing" | "completed" | "failed" | "skipped";
+type DokusOutputFileType = "docx" | "xlsx" | "pdf";
+interface DokusPreviewLinkMeta {
+    readonly status: "issued" | "revoked";
+    readonly createdAt: string;
+    readonly rotatedAt: string | null;
+    readonly allowDownload: boolean;
+    readonly expiresAt: string | null;
+}
+interface DokusRunOutput {
+    readonly id: number;
+    readonly fileType: DokusOutputFileType;
+    readonly outputFileName: string;
+    readonly status: DokusOutputStatus;
+    readonly error: string | null;
+    readonly size: number | null;
+    readonly pages: number | null;
+    readonly completedAt: string | null;
+    readonly downloadUrl: string | null;
+    /** Issue-once URL; `runs.wait` retains the first value observed while polling. */
+    readonly previewUrl: string | null;
+    readonly previewLink: DokusPreviewLinkMeta | null;
+}
+interface DokusRunResult {
+    readonly runId: string;
+    readonly workflowId: string;
+    readonly mode: "sync" | "async";
+    readonly status: DokusRunStatus;
+    readonly startedAt: string | null;
+    readonly completedAt: string | null;
+    readonly error: string | null;
+    readonly createdAt: string;
+    readonly outputs: readonly DokusRunOutput[];
+}
+interface DokusDocumentRenderCompleted extends DokusRunResult {
+    readonly documentId: string;
+    readonly documentVersionId: string;
+    readonly planId: string | null;
+    readonly mode: "sync";
+}
+interface DokusDocumentRenderStarted {
+    readonly documentId: string;
+    readonly documentVersionId: string;
+    readonly planId: string | null;
+    readonly runId: string;
+    readonly workflowId: string;
+    readonly status: "pending";
+}
+interface DokusRunOutputs {
+    readonly runId: string;
+    readonly outputs: readonly DokusRunOutput[];
+}
+interface DokusOutputDownload {
+    readonly url: string;
+    readonly expiresAt: string;
+}
+interface DokusPreviewLinkRotated {
+    readonly previewUrl: string;
+    readonly previewLink: DokusPreviewLinkMeta;
+}
+interface DokusGenerateStarted {
+    readonly runId: string;
+    readonly temporalWorkflowId: string;
+    readonly status: "started" | "already_running";
+}
+interface DokusGenerateAllEntry {
+    readonly documentId: string;
+    readonly runId?: string;
+    readonly temporalWorkflowId?: string;
+    readonly status: "started" | "already_running" | "failed";
+    readonly error?: string;
+}
+interface DokusDocumentRunSummary {
+    readonly id: string;
+    readonly workflowId: string;
+    readonly status: DokusRunStatus;
+    readonly startedAt: string | null;
+    readonly completedAt: string | null;
+    readonly error: string | null;
+    readonly triggeredByType: string;
+    readonly triggeredById: string | null;
+    readonly createdAt: string;
+    readonly outputCount: number;
+}
+interface DokusVersionSelection {
+    readonly version?: "latest" | "draft";
+    readonly versionId?: string;
+}
+
+interface DokusRenderDocumentInput extends DokusVersionSelection {
+    readonly documentId: string;
+    readonly planId?: string;
+    readonly contract?: DokusRenderContractV1;
+    readonly data?: JsonObject;
+    readonly generatePdf?: boolean;
+    readonly generateDocx?: boolean;
+    readonly expireAt?: number | Date | null;
+    readonly mode?: "sync" | "async";
+}
+type SyncRenderInput = DokusRenderDocumentInput & {
+    readonly mode?: "sync";
+};
+type AsyncRenderInput = DokusRenderDocumentInput & {
+    readonly mode: "async";
+};
+interface DokusDocuments {
+    /** Existing execution route: POST /api/documents/:documentId/run. */
+    render(input: AsyncRenderInput, options: DokusWriteOptions): Promise<DokusDocumentRenderStarted>;
+    render(input: SyncRenderInput, options: DokusWriteOptions): Promise<DokusDocumentRenderCompleted>;
+    render(input: DokusRenderDocumentInput, options: DokusWriteOptions): Promise<DokusDocumentRenderCompleted | DokusDocumentRenderStarted>;
+}
+
+interface DokusRunGetOptions extends DokusRequestOptions {
+    readonly expireAt?: number | Date | null;
+}
+interface DokusRunWaitOptions {
+    readonly expireAt?: number | Date | null;
+    readonly signal?: AbortSignal;
+    readonly requestId?: string;
+    /** Poll interval. Defaults to 2 seconds. */
+    readonly intervalMs?: number;
+    /** Overall polling deadline. Defaults to 2 minutes. */
+    readonly timeoutMs?: number;
+    /** Deadline for each individual polling request. */
+    readonly requestTimeoutMs?: number;
+}
+interface DokusRotatePreviewOptions extends DokusWriteOptions {
+    readonly allowDownload?: boolean;
+    readonly expiresIn?: {
+        readonly days: number;
+    } | null;
+}
+interface DokusRuns {
+    get(runId: string, options?: DokusRunGetOptions): Promise<DokusRunResult>;
+    outputs(runId: string, options?: DokusRequestOptions): Promise<DokusRunOutputs>;
+    outputDownload(runId: string, outputId: number, options?: DokusRequestOptions): Promise<DokusOutputDownload>;
+    rotatePreviewLink(runId: string, outputId: number, options: DokusRotatePreviewOptions): Promise<DokusPreviewLinkRotated>;
+    revokePreviewLink(runId: string, outputId: number, options: DokusWriteOptions): Promise<void>;
+    delete(runId: string, options: DokusWriteOptions): Promise<void>;
+    wait(runId: string, options?: DokusRunWaitOptions): Promise<DokusRunResult>;
+}
+
+interface DokusGenerateInput {
+    readonly documentId: string;
+    readonly data?: JsonObject;
+    readonly versionId?: string;
+    readonly versionSpec?: "latest" | "draft";
+    readonly outputFileNameOverride?: string;
+    readonly generatePdf?: boolean;
+    readonly generateDocx?: boolean;
+}
+interface DokusGenerateAllInput {
+    readonly data?: JsonObject;
+    readonly versionSpec?: "latest" | "draft";
+    readonly generatePdf?: boolean;
+    readonly generateDocx?: boolean;
+    readonly documentIds?: readonly string[];
+}
+interface DokusWorkflows {
+    generate(workflowId: string, input: DokusGenerateInput, options: DokusWriteOptions): Promise<DokusGenerateStarted>;
+    generateSync(workflowId: string, input: DokusGenerateInput, options: DokusWriteOptions): Promise<DokusRunResult>;
+    generateAll(workflowId: string, input: DokusGenerateAllInput | undefined, options: DokusWriteOptions): Promise<readonly DokusGenerateAllEntry[]>;
+    documentRuns(workflowId: string, documentId: string, options?: DokusRequestOptions & {
+        readonly limit?: number;
+    }): Promise<readonly DokusDocumentRunSummary[]>;
+}
+
+declare const DOKUS_API_BASE_URL = "https://api.dokus.pro";
+
+interface DokusClient {
+    readonly documents: DokusDocuments;
+    readonly runs: DokusRuns;
+    readonly workflows: DokusWorkflows;
+}
+/** Create one server-only, API-key-authenticated Dokus client. */
+declare function createDokusClient(options: DokusClientOptions): DokusClient;
+
+export { DOKUS_API_BASE_URL, type DokusClient, type DokusClientOptions, type DokusDocumentRenderCompleted, type DokusDocumentRenderStarted, type DokusDocumentRunSummary, type DokusDocuments, type DokusGenerateAllEntry, type DokusGenerateAllInput, type DokusGenerateInput, type DokusGenerateStarted, type DokusOutputDownload, type DokusOutputFileType, type DokusOutputStatus, type DokusPreviewLinkMeta, type DokusPreviewLinkRotated, type DokusRenderDocumentInput, type DokusRequestOptions, type DokusRetryOptions, type DokusRotatePreviewOptions, type DokusRunGetOptions, type DokusRunOutput, type DokusRunOutputs, type DokusRunResult, type DokusRunStatus, type DokusRunWaitOptions, type DokusRuns, type DokusVersionSelection, type DokusWorkflows, type DokusWriteOptions, createDokusClient };