@docgl/sdk 0.0.5

package/README.md

@@ -0,0 +1,99 @@
+# @docgl/sdk — TypeScript / JavaScript SDK
+
+Official TypeScript SDK for the [Docgl](https://docgl.com) document generation API.
+
+## Requirements
+
+- Node.js **≥ 18** (uses the built-in `fetch` API)
+- TypeScript **≥ 5** (optional but recommended)
+
+## Installation
+
+```bash
+npm install @docgl/sdk
+# or
+yarn add @docgl/sdk
+# or
+pnpm add @docgl/sdk
+```
+
+## Quick start
+
+```ts
+import { DocglClient } from "@docgl/sdk";
+
+const docgl = new DocglClient(process.env.DOCGL_API_TOKEN!);
+
+// 1. Queue document generation
+const { queued, errors } = await docgl.generate({
+  documents: [
+    {
+      uuid: "your-template-uuid",
+      filename: "invoice-001.pdf",
+      data: [
+        {
+          customer_name: "Acme Corp",
+          invoice_number: "INV-001",
+          total: 1500,
+        },
+      ],
+    },
+  ],
+  // Optional: route output to your own storage bucket
+  // storageConfigUuid: "your-storage-config-uuid",
+});
+
+console.log("Queued:", queued);
+// [{ jobId: "42", filename: "invoice-001.pdf" }]
+
+// 2. Poll for status
+const status = await docgl.getStatus(queued[0].jobId);
+console.log(status.status); // "waiting" | "active" | "completed" | "failed"
+```
+
+## API
+
+### `new DocglClient(token)`
+
+| Param | Type | Description |
+|---|---|---|
+| `token` | `string` | Your Docgl API token |
+
+### `client.generate(request)`
+
+Queues one or more documents for PDF generation. Returns `202 Accepted` immediately.
+
+**Returns:** `Promise<GenerateResponse>`
+
+### `client.getStatus(jobId)`
+
+Returns the current status of a queued generation job.
+
+**Returns:** `Promise<JobStatusResponse>`
+
+#### Job status values
+
+| Value | Description |
+|---|---|
+| `waiting` | In the queue, not yet started |
+| `active` | Currently being processed |
+| `completed` | PDF rendered successfully |
+| `failed` | Generation failed — check `failedReason` |
+| `delayed` | Scheduled to run later |
+| `prioritized` | Waiting with elevated priority |
+| `waiting-children` | Waiting for child jobs to complete |
+| `unknown` | Job not found (may have been cleaned up) |
+
+## Error handling
+
+```ts
+import { DocglClient, DocglError } from "@docgl/sdk";
+
+try {
+  await docgl.generate({ documents: [] });
+} catch (err) {
+  if (err instanceof DocglError) {
+    console.error(err.status, err.body);
+  }
+}
+```

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+import type { GenerateRequest, GenerateResponse, JobStatusResponse } from "./types";
+/** Error thrown when the Docgl API returns a non-2xx response */
+export declare class DocglError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+/**
+ * Official Docgl API client.
+ *
+ * @example
+ * ```ts
+ * const docgl = new DocglClient("your-api-token");
+ *
+ * const { queued } = await docgl.generate({
+ *   documents: [{
+ *     uuid: "template-uuid",
+ *     filename: "invoice.pdf",
+ *     data: [{ customer_name: "Acme Corp", total: 1500 }],
+ *   }],
+ * });
+ *
+ * const status = await docgl.getStatus(queued[0].jobId);
+ * console.log(status.status); // "completed"
+ * ```
+ */
+export declare class DocglClient {
+    private readonly token;
+    constructor(token: string);
+    private get authHeaders();
+    private handleResponse;
+    /**
+     * Queue one or more documents for generation.
+     *
+     * The API returns immediately with HTTP 202. Use {@link getStatus} to poll
+     * each `jobId` until `status` is `"completed"` or `"failed"`.
+     */
+    generate(request: GenerateRequest): Promise<GenerateResponse>;
+    /**
+     * Poll the status of a previously queued generation job.
+     *
+     * @param jobId - The `jobId` returned by {@link generate}
+     */
+    getStatus(jobId: string): Promise<JobStatusResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAIjB,iEAAiE;AACjE,qBAAa,UAAW,SAAQ,KAAK;aAEjB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,OAAO;gBADb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO;CAKhC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,KAAK,EAAE,MAAM;IAKzB,OAAO,KAAK,WAAW,GAItB;YAEa,cAAc;IAQ5B;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYnE;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAO3D"}

package/dist/client.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocglClient = exports.DocglError = void 0;
+const BASE_URL = "https://api.docgl.com";
+/** Error thrown when the Docgl API returns a non-2xx response */
+class DocglError extends Error {
+    constructor(status, body) {
+        super(`Docgl API error ${status}: ${JSON.stringify(body)}`);
+        this.status = status;
+        this.body = body;
+        this.name = "DocglError";
+    }
+}
+exports.DocglError = DocglError;
+/**
+ * Official Docgl API client.
+ *
+ * @example
+ * ```ts
+ * const docgl = new DocglClient("your-api-token");
+ *
+ * const { queued } = await docgl.generate({
+ *   documents: [{
+ *     uuid: "template-uuid",
+ *     filename: "invoice.pdf",
+ *     data: [{ customer_name: "Acme Corp", total: 1500 }],
+ *   }],
+ * });
+ *
+ * const status = await docgl.getStatus(queued[0].jobId);
+ * console.log(status.status); // "completed"
+ * ```
+ */
+class DocglClient {
+    constructor(token) {
+        if (!token)
+            throw new Error("Docgl API token is required");
+        this.token = token;
+    }
+    get authHeaders() {
+        return {
+            Authorization: `Bearer ${this.token}`,
+        };
+    }
+    async handleResponse(res) {
+        if (res.ok) {
+            return res.json();
+        }
+        const body = await res.json().catch(() => ({ message: res.statusText }));
+        throw new DocglError(res.status, body);
+    }
+    /**
+     * Queue one or more documents for generation.
+     *
+     * The API returns immediately with HTTP 202. Use {@link getStatus} to poll
+     * each `jobId` until `status` is `"completed"` or `"failed"`.
+     */
+    async generate(request) {
+        const res = await fetch(`${BASE_URL}/api/generate`, {
+            method: "POST",
+            headers: {
+                ...this.authHeaders,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(request),
+        });
+        return this.handleResponse(res);
+    }
+    /**
+     * Poll the status of a previously queued generation job.
+     *
+     * @param jobId - The `jobId` returned by {@link generate}
+     */
+    async getStatus(jobId) {
+        const res = await fetch(`${BASE_URL}/api/generate/${encodeURIComponent(jobId)}`, { headers: this.authHeaders });
+        return this.handleResponse(res);
+    }
+}
+exports.DocglClient = DocglClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAMA,MAAM,QAAQ,GAAG,uBAAuB,CAAC;AAEzC,iEAAiE;AACjE,MAAa,UAAW,SAAQ,KAAK;IACnC,YACkB,MAAc,EACd,IAAa;QAE7B,KAAK,CAAC,mBAAmB,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAH5C,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAS;QAG7B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AARD,gCAQC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,WAAW;IAGtB,YAAY,KAAa;QACvB,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAC3D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,IAAY,WAAW;QACrB,OAAO;YACL,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE;SACtC,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,cAAc,CAAI,GAAa;QAC3C,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;YACX,OAAO,GAAG,CAAC,IAAI,EAAgB,CAAC;QAClC,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QACzE,MAAM,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CAAC,OAAwB;QACrC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,QAAQ,eAAe,EAAE;YAClD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,GAAG,IAAI,CAAC,WAAW;gBACnB,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;SAC9B,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,cAAc,CAAmB,GAAG,CAAC,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,KAAa;QAC3B,MAAM,GAAG,GAAG,MAAM,KAAK,CACrB,GAAG,QAAQ,iBAAiB,kBAAkB,CAAC,KAAK,CAAC,EAAE,EACvD,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,CAC9B,CAAC;QACF,OAAO,IAAI,CAAC,cAAc,CAAoB,GAAG,CAAC,CAAC;IACrD,CAAC;CACF;AApDD,kCAoDC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { DocglClient, DocglError } from "./client";
+export type { GenerateRequest, GenerateResponse, JobStatusResponse, JobStatus, DocumentInput, DocumentVariables, VariableValue, TableRow, QueuedJob, ValidationError, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACnD,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,QAAQ,EACR,SAAS,EACT,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocglError = exports.DocglClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "DocglClient", { enumerable: true, get: function () { return client_1.DocglClient; } });
+Object.defineProperty(exports, "DocglError", { enumerable: true, get: function () { return client_1.DocglError; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAAmD;AAA1C,qGAAA,WAAW,OAAA;AAAE,oGAAA,UAAU,OAAA"}

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+/** A single cell value inside a table row */
+export type TableRow = Record<string, string | number>;
+/** All allowed values for a document variable */
+export type VariableValue = string | number | TableRow[];
+/** Key-value map of variables for one document render */
+export type DocumentVariables = Record<string, VariableValue>;
+/** A single document to be rendered */
+export interface DocumentInput {
+    /** UUID of the template registered in Docgl */
+    uuid: string;
+    /** Output filename (e.g. "invoice-001.pdf") */
+    filename: string;
+    /**
+     * Array of variable maps. Each entry produces one rendered PDF.
+     * Provide multiple entries to batch-render the same template with
+     * different data in a single request.
+     */
+    data: DocumentVariables[];
+}
+/** Body sent to POST /api/generate */
+export interface GenerateRequest {
+    documents: DocumentInput[];
+    /**
+     * UUID of a storage configuration registered in Docgl.
+     * When provided, the generated PDF is uploaded to your storage bucket.
+     */
+    storageConfigUuid?: string;
+}
+/** A successfully queued job entry */
+export interface QueuedJob {
+    jobId: string;
+    filename: string;
+}
+/** A document that failed validation */
+export interface ValidationError {
+    filename: string;
+    errors: string[];
+}
+/** Response from POST /api/generate (HTTP 202) */
+export interface GenerateResponse {
+    message: string;
+    queued: QueuedJob[];
+    errors?: ValidationError[];
+}
+/** Possible states of a generation job */
+export type JobStatus = "waiting" | "active" | "completed" | "failed" | "delayed" | "prioritized" | "waiting-children" | "unknown";
+/** Response from GET /api/generate/:jobId (HTTP 200) */
+export interface JobStatusResponse {
+    jobId: string;
+    filename: string | null;
+    status: JobStatus;
+    result: unknown | null;
+    failedReason: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,6CAA6C;AAC7C,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAEvD,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC;AAEzD,yDAAyD;AACzD,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE9D,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,IAAI,EAAE,iBAAiB,EAAE,CAAC;CAC3B;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAMD,sCAAsC;AACtC,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,SAAS,GACT,aAAa,GACb,kBAAkB,GAClB,SAAS,CAAC;AAEd,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B"}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Request types
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@docgl/sdk",
+  "version": "0.0.5",
+  "description": "Official TypeScript/JavaScript SDK for the Docgl API",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "docgl",
+    "pdf",
+    "sdk",
+    "document",
+    "generation"
+  ],
+  "license": "MIT",
+  "author": "Docgl",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/docgl-sdk/typescript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/docgl-sdk/typescript/issues"
+  },
+  "homepage": "https://github.com/docgl-sdk/typescript#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}