@dskripchenko/printable-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Skripchenko
+
+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,82 @@
+# Printable SDK for Node.js
+
+Official Node.js client for the Printable document-generation service
+integration API: templates, print-forms, batch rendering, document drafts
+and webhook verification — with HMAC request signing (simple and strict
+canonical modes) built in and byte-compatible with the server implementation.
+
+Zero runtime dependencies. Node.js 18+. **Server-side only** — the secret
+key must never reach a browser.
+
+## Install
+
+```bash
+npm install @dskripchenko/printable-sdk
+```
+
+## Quick start
+
+```ts
+import { PrintableClient } from '@dskripchenko/printable-sdk';
+
+const client = new PrintableClient({
+  baseUrl: 'https://printable.example.com',
+  token: 'erp-main-7f3a',
+  secretKey: process.env.PRINTABLE_SECRET!,
+  salt: process.env.PRINTABLE_SALT!,
+  strict: false, // true if the credential has "verify full payload hash" enabled
+});
+
+// Render a document
+const doc = await client.printFormCreate({
+  template: 'invoice',
+  variables: { company: { name: 'ACME Ltd' } },
+  format: 'link',
+});
+console.log(doc.link);
+
+// Batch with archive + email delivery
+const batch = await client.printFormBatch({
+  template: 'certificate',
+  items: [{ variables: { name: 'Alice' } }, { variables: { name: 'Bob' } }],
+  archive: true,
+  deliver: { email: 'hr@example.com' },
+});
+const status = await client.printFormBatchGet(batch.uuid as string);
+```
+
+## API surface
+
+`templateList` · `templateContract` · `templateExport` · `templateImport` ·
+`printFormCreate` · `printFormGet` · `printFormRules` · `printFormBatch` ·
+`printFormBatchGet` · `documentDraftCreate` · `documentDraftGet` ·
+`call(method, endpoint, params)` (escape hatch).
+
+Every method resolves with the decoded `payload` of the response envelope.
+Errors (non-2xx or `success: false`) reject with `PrintableError`
+(`status`, `errorKey`, `payload`).
+
+## Webhooks
+
+```ts
+const valid = client.verifyWebhook(
+  rawBody, // raw request body string
+  req.headers['x-printable-signature'],
+  req.headers['x-printable-timestamp'],
+);
+```
+
+## Testing your integration
+
+Inject a custom `fetch` to stub HTTP:
+
+```ts
+const client = new PrintableClient({
+  /* … */
+  fetch: async () => new Response('{"success":true,"payload":{"ok":true}}'),
+});
+```
+
+## License
+
+MIT

package/dist/canonical.d.ts

@@ -0,0 +1,14 @@
+/**
+ * PHP-compatible payload canonicalization — byte-identical to the Printable
+ * server (`App\Auth\HashSigner::canonicalize`):
+ *
+ *  - recursive key sort for objects (arrays keep their order);
+ *  - PHP `JSON_NUMERIC_CHECK` semantics: numeric strings become numbers
+ *    ("42" → 42, "100.0" → 100, "1e3" → 1000, "007" → 7);
+ *  - empty objects encode as `[]` (PHP array semantics);
+ *  - objects with sequential "0".."n" keys encode as arrays;
+ *  - unicode and slashes are not escaped.
+ *
+ * Known limitation (same as PHP): integers beyond 2^53 lose precision.
+ */
+export declare function canonicalize(payload: Record<string, unknown>): string;

package/dist/canonical.js

@@ -0,0 +1,117 @@
+/**
+ * PHP-compatible payload canonicalization — byte-identical to the Printable
+ * server (`App\Auth\HashSigner::canonicalize`):
+ *
+ *  - recursive key sort for objects (arrays keep their order);
+ *  - PHP `JSON_NUMERIC_CHECK` semantics: numeric strings become numbers
+ *    ("42" → 42, "100.0" → 100, "1e3" → 1000, "007" → 7);
+ *  - empty objects encode as `[]` (PHP array semantics);
+ *  - objects with sequential "0".."n" keys encode as arrays;
+ *  - unicode and slashes are not escaped.
+ *
+ * Known limitation (same as PHP): integers beyond 2^53 lose precision.
+ */
+/** PHP `is_numeric` for strings (PHP 8: leading/trailing whitespace allowed). */
+const NUMERIC_RE = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
+function isNumericString(value) {
+    return NUMERIC_RE.test(value.trim()) && value.trim() !== '';
+}
+function isSequentialKeys(obj) {
+    const keys = Object.keys(obj);
+    if (keys.length === 0) {
+        return false;
+    }
+    return keys.every((key, index) => key === String(index));
+}
+function encode(value) {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'true' : 'false';
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? String(value) : '0';
+    }
+    if (typeof value === 'string') {
+        if (isNumericString(value)) {
+            return String(Number(value.trim()));
+        }
+        return encodeString(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(encode).join(',') + ']';
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj);
+        // PHP: пустой объект после json_decode(assoc) — пустой array → "[]".
+        if (keys.length === 0) {
+            return '[]';
+        }
+        // Объект с ключами "0".."n" PHP считает списком.
+        if (isSequentialKeys(obj)) {
+            return '[' + keys.map((k) => encode(obj[k])).join(',') + ']';
+        }
+        const sorted = phpKsort(keys);
+        return '{' + sorted.map((k) => encodeString(k) + ':' + encode(obj[k])).join(',') + '}';
+    }
+    return 'null';
+}
+/**
+ * PHP ksort (SORT_REGULAR): числовые ключи сравниваются как числа,
+ * прочие — как строки; числовые всегда раньше строковых при сравнении
+ * числа со строкой числовая семантика PHP8 — для API-payload'ов ключи
+ * практически всегда строковые, обычной сортировки достаточно.
+ */
+function phpKsort(keys) {
+    return [...keys].sort((a, b) => {
+        const an = isNumericString(a);
+        const bn = isNumericString(b);
+        if (an && bn) {
+            return Number(a) - Number(b);
+        }
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+}
+/** JSON string escaping как в PHP с UNESCAPED_UNICODE|UNESCAPED_SLASHES. */
+function encodeString(value) {
+    let out = '"';
+    for (const ch of value) {
+        const code = ch.codePointAt(0);
+        switch (ch) {
+            case '"':
+                out += '\\"';
+                break;
+            case '\\':
+                out += '\\\\';
+                break;
+            case '\b':
+                out += '\\b';
+                break;
+            case '\f':
+                out += '\\f';
+                break;
+            case '\n':
+                out += '\\n';
+                break;
+            case '\r':
+                out += '\\r';
+                break;
+            case '\t':
+                out += '\\t';
+                break;
+            default:
+                if (code < 0x20) {
+                    out += '\\u' + code.toString(16).padStart(4, '0');
+                }
+                else {
+                    out += ch;
+                }
+        }
+    }
+    return out + '"';
+}
+export function canonicalize(payload) {
+    return encode(payload);
+}

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+export interface PrintableClientOptions {
+    /** Installation origin, e.g. `https://printable.example.com`. */
+    baseUrl: string;
+    token: string;
+    secretKey: string;
+    salt: string;
+    /** true when the credential requires full-payload HMAC verification. */
+    strict?: boolean;
+    timeoutMs?: number;
+    /** Custom fetch implementation (testing / instrumentation). */
+    fetch?: typeof fetch;
+}
+export declare class PrintableError extends Error {
+    readonly status: number;
+    readonly errorKey: string | null;
+    readonly payload: Record<string, unknown>;
+    constructor(message: string, status: number, errorKey?: string | null, payload?: Record<string, unknown>);
+}
+type Payload = Record<string, unknown>;
+/**
+ * Client for the Printable integration API (`/api/integration`).
+ * Server-side only: the secret key must never reach a browser.
+ */
+export declare class PrintableClient {
+    private readonly options;
+    private readonly signer;
+    private readonly fetchImpl;
+    constructor(options: PrintableClientOptions);
+    templateList(): Promise<Payload>;
+    templateContract(template: string, version?: string): Promise<Payload>;
+    templateExport(template: string, version?: string): Promise<Payload>;
+    templateImport(packageB64: string, groupId: number, options?: {
+        deps?: string;
+        on_conflict?: string;
+    }): Promise<Payload>;
+    printFormCreate(params: Payload): Promise<Payload>;
+    printFormGet(uuid: string, format?: 'link' | 'b64'): Promise<Payload>;
+    printFormRules(template: string, version?: string): Promise<Payload>;
+    printFormBatch(params: Payload): Promise<Payload>;
+    printFormBatchGet(uuid: string): Promise<Payload>;
+    documentDraftCreate(params: Payload): Promise<Payload>;
+    documentDraftGet(uuid: string): Promise<Payload>;
+    /** Verify an incoming Printable webhook against its signature headers. */
+    verifyWebhook(rawBody: string, signatureHeader: string, timestampHeader: string | number): boolean;
+    /** Generic escape hatch: signed call to any `{controller}/{action}`. */
+    call(method: 'GET' | 'POST', endpoint: string, params?: Payload): Promise<Payload>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,108 @@
+import { Signer } from './signer.js';
+export class PrintableError extends Error {
+    status;
+    errorKey;
+    payload;
+    constructor(message, status, errorKey = null, payload = {}) {
+        super(message);
+        this.status = status;
+        this.errorKey = errorKey;
+        this.payload = payload;
+        this.name = 'PrintableError';
+    }
+}
+/**
+ * Client for the Printable integration API (`/api/integration`).
+ * Server-side only: the secret key must never reach a browser.
+ */
+export class PrintableClient {
+    options;
+    signer;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        this.signer = new Signer(options.salt);
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    // ── Templates ──────────────────────────────────────────────────────
+    templateList() {
+        return this.call('GET', 'template/list');
+    }
+    templateContract(template, version) {
+        return this.call('GET', 'template/contract', version ? { template, version } : { template });
+    }
+    templateExport(template, version) {
+        return this.call('GET', 'template/export', version ? { template, version } : { template });
+    }
+    templateImport(packageB64, groupId, options = {}) {
+        return this.call('POST', 'template/import', { ...options, package_b64: packageB64, group_id: groupId });
+    }
+    // ── Print forms ────────────────────────────────────────────────────
+    printFormCreate(params) {
+        return this.call('POST', 'print-form/create', params);
+    }
+    printFormGet(uuid, format = 'link') {
+        return this.call('GET', 'print-form/get', { uuid, format });
+    }
+    printFormRules(template, version) {
+        return this.call('GET', 'print-form/rules', version ? { template, version } : { template });
+    }
+    printFormBatch(params) {
+        return this.call('POST', 'print-form/batch', params);
+    }
+    printFormBatchGet(uuid) {
+        return this.call('GET', 'print-form/batch-get', { uuid });
+    }
+    // ── Document drafts ────────────────────────────────────────────────
+    documentDraftCreate(params) {
+        return this.call('POST', 'document-draft/create', params);
+    }
+    documentDraftGet(uuid) {
+        return this.call('GET', 'document-draft/get', { uuid });
+    }
+    // ── Webhooks ───────────────────────────────────────────────────────
+    /** Verify an incoming Printable webhook against its signature headers. */
+    verifyWebhook(rawBody, signatureHeader, timestampHeader) {
+        const signature = signatureHeader.startsWith('sha256=') ? signatureHeader.slice(7) : signatureHeader;
+        return this.signer.verifyWebhook(signature, Number(timestampHeader), rawBody, this.options.secretKey);
+    }
+    // ── Core ───────────────────────────────────────────────────────────
+    /** Generic escape hatch: signed call to any `{controller}/{action}`. */
+    async call(method, endpoint, params = {}) {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const payload = { ...params, timestamp };
+        const hash = this.options.strict
+            ? this.signer.signPayload(payload, this.options.secretKey)
+            : this.signer.signToken(this.options.token, timestamp, this.options.secretKey);
+        const body = { ...payload, token: this.options.token, hash };
+        let url = this.options.baseUrl.replace(/\/+$/, '') + '/api/integration/' + endpoint.replace(/^\/+/, '');
+        const init = {
+            method,
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            signal: AbortSignal.timeout(this.options.timeoutMs ?? 30_000),
+        };
+        if (method === 'GET') {
+            const query = new URLSearchParams();
+            for (const [key, value] of Object.entries(body)) {
+                query.set(key, String(value));
+            }
+            url += '?' + query.toString();
+        }
+        else {
+            init.body = JSON.stringify(body);
+        }
+        const response = await this.fetchImpl(url, init);
+        let decoded;
+        try {
+            decoded = (await response.json());
+        }
+        catch {
+            throw new PrintableError(`Printable API returned a non-JSON response (HTTP ${response.status})`, response.status);
+        }
+        const payloadOut = decoded.payload ?? {};
+        if (response.status >= 400 || decoded.success !== true) {
+            throw new PrintableError(typeof payloadOut.message === 'string' ? payloadOut.message : `Printable API error (HTTP ${response.status})`, response.status, typeof payloadOut.errorKey === 'string' ? payloadOut.errorKey : null, payloadOut);
+        }
+        return payloadOut;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { PrintableClient, PrintableError, type PrintableClientOptions } from './client.js';
+export { Signer } from './signer.js';
+export { canonicalize } from './canonical.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { PrintableClient, PrintableError } from './client.js';
+export { Signer } from './signer.js';
+export { canonicalize } from './canonical.js';

package/dist/signer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Request/webhook signing, byte-compatible with the Printable server
+ * (`App\Auth\HashSigner`).
+ */
+export declare class Signer {
+    private readonly salt;
+    constructor(salt: string);
+    /** simple mode: sha256(token + timestamp + salt + secret). */
+    signToken(token: string, timestamp: number, secretKey: string): string;
+    /** strict mode: HMAC-SHA256(canonical(payload), secret + salt). */
+    signPayload(payload: Record<string, unknown>, secretKey: string): string;
+    /** Verify an incoming webhook signature (value without the "sha256=" prefix). */
+    verifyWebhook(signature: string, timestamp: number, rawBody: string, secretKey: string): boolean;
+}

package/dist/signer.js

@@ -0,0 +1,31 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { canonicalize } from './canonical.js';
+/**
+ * Request/webhook signing, byte-compatible with the Printable server
+ * (`App\Auth\HashSigner`).
+ */
+export class Signer {
+    salt;
+    constructor(salt) {
+        this.salt = salt;
+        if (salt === '') {
+            throw new Error('Printable salt must not be empty.');
+        }
+    }
+    /** simple mode: sha256(token + timestamp + salt + secret). */
+    signToken(token, timestamp, secretKey) {
+        return createHash('sha256').update(`${token}${timestamp}${this.salt}${secretKey}`).digest('hex');
+    }
+    /** strict mode: HMAC-SHA256(canonical(payload), secret + salt). */
+    signPayload(payload, secretKey) {
+        return createHmac('sha256', secretKey + this.salt).update(canonicalize(payload)).digest('hex');
+    }
+    /** Verify an incoming webhook signature (value without the "sha256=" prefix). */
+    verifyWebhook(signature, timestamp, rawBody, secretKey) {
+        const expected = createHmac('sha256', secretKey).update(`${timestamp}.${rawBody}`).digest('hex');
+        if (signature.length !== expected.length) {
+            return false;
+        }
+        return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dskripchenko/printable-sdk",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for the Printable document-generation service: HMAC-signed integration API client (templates, print-forms, batches, drafts, webhooks).",
+  "keywords": [
+    "printable",
+    "sdk",
+    "api-client",
+    "pdf",
+    "docx",
+    "document-generation",
+    "hmac"
+  ],
+  "homepage": "https://github.com/dskripchenko/printable-sdk-js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dskripchenko/printable-sdk-js.git"
+  },
+  "license": "MIT",
+  "author": "Denis Skripchenko (https://github.com/dskripchenko)",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}