@bpmnkit/api 0.0.8

package/dist/runtime/types.d.ts

@@ -0,0 +1,191 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "none";
+export interface LoggerConfig {
+    level?: LogLevel;
+    /** Custom sink. Defaults to console. */
+    sink?: (level: LogLevel, message: string, data?: unknown) => void;
+}
+export interface RetryConfig {
+    /** Maximum number of attempts (including the first). Default: 3. */
+    maxAttempts?: number;
+    /** Initial delay in ms. Default: 100. */
+    initialDelay?: number;
+    /** Maximum delay cap in ms. Default: 30_000. */
+    maxDelay?: number;
+    /** Multiplier applied to delay after each failure. Default: 2. */
+    backoffFactor?: number;
+    /** HTTP status codes that trigger a retry. Default: [429, 500, 502, 503, 504]. */
+    retryOn?: number[];
+}
+export interface CacheConfig {
+    /** Enable response caching for eventually-consistent GET/POST-search endpoints. Default: false. */
+    enabled?: boolean;
+    /** Time-to-live in ms. Default: 30_000. */
+    ttl?: number;
+    /** Maximum number of cached entries. Default: 500. */
+    maxSize?: number;
+}
+/** A cached OAuth2 access token. */
+export interface CachedToken {
+    accessToken: string;
+    /** Unix timestamp (ms) when the token expires. */
+    expiresAt: number;
+}
+/**
+ * Interface for a persistent OAuth2 token store.
+ * Implement this to store tokens in Redis, a database, or any custom backend.
+ *
+ * @example
+ * ```typescript
+ * const redisStore: TokenStore = {
+ *   async get(key) {
+ *     const raw = await redis.get(`token:${key}`);
+ *     return raw ? JSON.parse(raw) : null;
+ *   },
+ *   async set(key, token) {
+ *     const ttl = Math.floor((token.expiresAt - Date.now()) / 1000);
+ *     await redis.set(`token:${key}`, JSON.stringify(token), "EX", ttl);
+ *   },
+ * };
+ * ```
+ */
+export interface TokenStore {
+    get(key: string): Promise<CachedToken | null>;
+    set(key: string, token: CachedToken): Promise<void>;
+}
+export interface TokenCacheConfig {
+    /**
+     * Disable the persistent token cache entirely.
+     * The token will only be held in memory for the lifetime of the client instance.
+     * Default: false.
+     */
+    disabled?: boolean;
+    /**
+     * Absolute path to the token cache JSON file.
+     * Defaults to `{osConfigDir}/camunda-api/token-cache.json`.
+     */
+    filePath?: string;
+    /**
+     * Custom token store. When provided, overrides the default file-based cache.
+     * Use this to store tokens in Redis, a database, or any other backend.
+     */
+    store?: TokenStore;
+}
+export type AuthConfig = {
+    type: "bearer";
+    token: string;
+} | {
+    type: "oauth2";
+    clientId: string;
+    clientSecret: string;
+    /** Token endpoint URL. */
+    tokenUrl: string;
+    scope?: string;
+    /** OAuth2 audience parameter. Required by Camunda Cloud (default: "zeebe.camunda.io"). */
+    audience?: string;
+    /**
+     * Persistent token cache configuration.
+     * Enabled by default — tokens survive process restarts.
+     */
+    tokenCache?: TokenCacheConfig;
+} | {
+    type: "basic";
+    username: string;
+    password: string;
+} | {
+    type: "none";
+};
+export interface CamundaClientConfig {
+    /** Base URL of the Camunda cluster, e.g. http://localhost:8080/v2 */
+    baseUrl: string;
+    auth: AuthConfig;
+    /**
+     * Path to a YAML config file. Fields from the file are merged with lower
+     * priority than values passed directly to the constructor.
+     */
+    configFile?: string;
+    retry?: RetryConfig;
+    cache?: CacheConfig;
+    logger?: LoggerConfig;
+    /** Request timeout in ms. Default: 30_000. */
+    timeout?: number;
+}
+/**
+ * All fields optional — missing values are resolved from the config file
+ * or environment variables. Useful when config is fully provided via env/file.
+ */
+export type CamundaClientInput = {
+    baseUrl?: string;
+    auth?: AuthConfig;
+    configFile?: string;
+    retry?: RetryConfig;
+    cache?: CacheConfig;
+    logger?: LoggerConfig;
+    timeout?: number;
+};
+export interface RequestEvent {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: unknown;
+}
+export interface ResponseEvent {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    cached: boolean;
+}
+export interface RawResponseEvent {
+    method: string;
+    url: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+    requestHeaders: Record<string, string>;
+    requestBody?: string;
+}
+export interface ErrorEvent {
+    method: string;
+    url: string;
+    error: Error;
+}
+export interface RetryEvent {
+    method: string;
+    url: string;
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    reason: string;
+}
+export interface TokenRefreshEvent {
+    tokenUrl: string;
+}
+export interface CacheEvent {
+    url: string;
+}
+export type ClientEventMap = {
+    request: RequestEvent;
+    response: ResponseEvent;
+    rawResponse: RawResponseEvent;
+    error: ErrorEvent;
+    retry: RetryEvent;
+    tokenRefresh: TokenRefreshEvent;
+    cacheHit: CacheEvent;
+    cacheMiss: CacheEvent;
+};
+export interface RequestOptions {
+    method: string;
+    path: string;
+    pathParams?: Record<string, string | number>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    /** Whether this response may be served from cache. */
+    cacheable?: boolean;
+    /** Override timeout for this request. */
+    timeout?: number;
+    /** Custom Accept header. Defaults to "application/json". */
+    accept?: string;
+    /** How to parse the response body. Defaults to "json". */
+    responseType?: "json" | "text";
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runtime/yaml.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Minimal YAML parser for Camunda client config files.
+ * Handles block mappings, block sequences, inline arrays, all scalar types,
+ * quoted strings, and comments. No external dependencies.
+ */
+type Scalar = string | number | boolean | null;
+export interface YamlObject {
+    [key: string]: Scalar | YamlObject | YamlArray;
+}
+interface YamlArray extends Array<Scalar | YamlObject | YamlArray> {
+}
+export declare function parseYaml(text: string): YamlObject;
+export {};
+//# sourceMappingURL=yaml.d.ts.map

package/dist/runtime/yaml.js

@@ -0,0 +1,234 @@
+/**
+ * Minimal YAML parser for Camunda client config files.
+ * Handles block mappings, block sequences, inline arrays, all scalar types,
+ * quoted strings, and comments. No external dependencies.
+ */
+export function parseYaml(text) {
+    const lines = buildLines(text);
+    const [value] = parseMapping(lines, 0, 0);
+    return value;
+}
+// ─── Preprocessing ────────────────────────────────────────────────────────────
+function buildLines(text) {
+    const result = [];
+    for (const raw of text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n")) {
+        let indent = 0;
+        for (const ch of raw) {
+            if (ch === " ")
+                indent++;
+            else if (ch === "\t")
+                indent += 2;
+            else
+                break;
+        }
+        const content = stripInlineComment(raw.trim());
+        if (content !== "")
+            result.push({ indent, content });
+    }
+    return result;
+}
+function stripInlineComment(s) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (ch === "#" && !inSingle && !inDouble && i > 0 && s[i - 1] === " ") {
+            return s.slice(0, i).trimEnd();
+        }
+    }
+    return s;
+}
+// ─── Recursive parser ─────────────────────────────────────────────────────────
+/** Parse a mapping block. Returns [object, nextPos]. */
+function parseMapping(lines, startPos, baseIndent) {
+    const obj = {};
+    let pos = startPos;
+    while (pos < lines.length) {
+        const line = lines[pos];
+        if (!line || line.indent < baseIndent)
+            break;
+        if (line.indent > baseIndent) {
+            // Indented line where we don't expect it — skip safely
+            pos++;
+            continue;
+        }
+        const [key, rest] = splitMappingKey(line.content);
+        if (key === null) {
+            pos++;
+            continue;
+        }
+        pos++;
+        if (rest === null) {
+            // Value is on following lines
+            const next = lines[pos];
+            if (!next || next.indent <= baseIndent) {
+                obj[key] = null;
+                continue;
+            }
+            const childIndent = next.indent;
+            if (next.content.startsWith("- ") || next.content === "-") {
+                const [seq, nextPos] = parseSequence(lines, pos, childIndent);
+                obj[key] = seq;
+                pos = nextPos;
+            }
+            else {
+                const [map, nextPos] = parseMapping(lines, pos, childIndent);
+                obj[key] = map;
+                pos = nextPos;
+            }
+        }
+        else if (rest.startsWith("[")) {
+            obj[key] = parseInlineArray(rest);
+        }
+        else {
+            obj[key] = parseScalar(rest);
+        }
+    }
+    return [obj, pos];
+}
+/** Parse a sequence block. Returns [array, nextPos]. */
+function parseSequence(lines, startPos, baseIndent) {
+    const arr = [];
+    let pos = startPos;
+    while (pos < lines.length) {
+        const line = lines[pos];
+        if (!line || line.indent < baseIndent)
+            break;
+        if (!line.content.startsWith("- ") && line.content !== "-")
+            break;
+        const itemText = line.content.slice(1).trimStart();
+        pos++;
+        if (itemText === "") {
+            const next = lines[pos];
+            if (!next || next.indent <= baseIndent) {
+                arr.push(null);
+                continue;
+            }
+            // Could be a nested mapping or sequence
+            if (next.content.startsWith("- ") || next.content === "-") {
+                const [child, nextPos] = parseSequence(lines, pos, next.indent);
+                arr.push(child);
+                pos = nextPos;
+            }
+            else {
+                const [child, nextPos] = parseMapping(lines, pos, next.indent);
+                arr.push(child);
+                pos = nextPos;
+            }
+        }
+        else if (itemText.startsWith("[")) {
+            arr.push(parseInlineArray(itemText));
+        }
+        else {
+            arr.push(parseScalar(itemText));
+        }
+    }
+    return [arr, pos];
+}
+function parseInlineArray(text) {
+    let inner = text.trim();
+    if (inner.startsWith("["))
+        inner = inner.slice(1);
+    if (inner.endsWith("]"))
+        inner = inner.slice(0, -1);
+    if (!inner.trim())
+        return [];
+    return splitByComma(inner).map((item) => parseScalar(item.trim()));
+}
+// ─── Key extraction ───────────────────────────────────────────────────────────
+/**
+ * Split `key: value rest` → [key, "value rest"] or [key, null] for blank value.
+ * Returns [null, null] if the line is not a mapping entry.
+ */
+function splitMappingKey(content) {
+    // Quoted key
+    if (content.startsWith('"') || content.startsWith("'")) {
+        const q = content[0];
+        const close = content.indexOf(q, 1);
+        if (close >= 0 && content[close + 1] === ":") {
+            const key = content.slice(1, close);
+            const after = content.slice(close + 2).trimStart();
+            return [key, after || null];
+        }
+        return [null, null];
+    }
+    // Plain key — find `:` that is not part of `://`
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] !== ":")
+            continue;
+        const next = content[i + 1];
+        if (next === "/" || next === ":")
+            continue; // skip :// and ::
+        if (next !== " " && next !== undefined)
+            continue; // must be `: ` or end of string
+        const key = content.slice(0, i).trim();
+        if (!key)
+            continue;
+        const after = content.slice(i + 1).trimStart();
+        return [key, after || null];
+    }
+    return [null, null];
+}
+// ─── Scalar parsing ───────────────────────────────────────────────────────────
+function parseScalar(s) {
+    const str = s.trim();
+    if (str === "" || str === "null" || str === "~")
+        return null;
+    if (str === "true" || str === "yes" || str === "on")
+        return true;
+    if (str === "false" || str === "no" || str === "off")
+        return false;
+    if (str.startsWith('"') && str.endsWith('"') && str.length >= 2) {
+        return str
+            .slice(1, -1)
+            .replace(/\\n/g, "\n")
+            .replace(/\\t/g, "\t")
+            .replace(/\\"/g, '"')
+            .replace(/\\\\/g, "\\");
+    }
+    if (str.startsWith("'") && str.endsWith("'") && str.length >= 2) {
+        return str.slice(1, -1).replace(/''/g, "'");
+    }
+    if (/^-?\d+$/.test(str))
+        return Number.parseInt(str, 10);
+    if (/^-?\d*\.?\d+([eE][+-]?\d+)?$/.test(str))
+        return Number.parseFloat(str);
+    return str;
+}
+function splitByComma(text) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    for (const ch of text) {
+        if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (!inSingle && !inDouble) {
+            if (ch === "[" || ch === "{")
+                depth++;
+            else if (ch === "]" || ch === "}")
+                depth--;
+            else if (ch === "," && depth === 0) {
+                parts.push(current.trim());
+                current = "";
+                continue;
+            }
+        }
+        current += ch;
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    return parts;
+}
+//# sourceMappingURL=yaml.js.map

package/dist/runtime/yaml.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=yaml.test.d.ts.map

package/dist/runtime/yaml.test.js

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { parseYaml } from "./yaml.js";
+describe("parseYaml", () => {
+    it("parses basic key-value pairs", () => {
+        const result = parseYaml("baseUrl: http://localhost:8080/v2\ntimeout: 30000");
+        expect(result.baseUrl).toBe("http://localhost:8080/v2");
+        expect(result.timeout).toBe(30000);
+    });
+    it("parses nested mappings", () => {
+        const result = parseYaml(`
+auth:
+  type: oauth2
+  clientId: my-client
+  tokenUrl: https://example.com/token
+`);
+        expect(result.auth).toEqual({
+            type: "oauth2",
+            clientId: "my-client",
+            tokenUrl: "https://example.com/token",
+        });
+    });
+    it("parses inline arrays", () => {
+        const result = parseYaml("retryOn: [429, 500, 503]");
+        expect(result.retryOn).toEqual([429, 500, 503]);
+    });
+    it("parses block sequences", () => {
+        const result = parseYaml(`
+items:
+  - 429
+  - 500
+  - 503
+`);
+        expect(result.items).toEqual([429, 500, 503]);
+    });
+    it("parses booleans", () => {
+        const result = parseYaml("enabled: true\ndisabled: false");
+        expect(result.enabled).toBe(true);
+        expect(result.disabled).toBe(false);
+    });
+    it("parses null values", () => {
+        const result = parseYaml("value: null");
+        expect(result.value).toBeNull();
+    });
+    it("parses double-quoted strings with escapes", () => {
+        const result = parseYaml('key: "hello\\nworld"');
+        expect(result.key).toBe("hello\nworld");
+    });
+    it("parses single-quoted strings", () => {
+        const result = parseYaml("key: 'it''s fine'");
+        expect(result.key).toBe("it's fine");
+    });
+    it("strips inline comments", () => {
+        const result = parseYaml("baseUrl: http://localhost # comment\ntimeout: 5000 # ms");
+        expect(result.baseUrl).toBe("http://localhost");
+        expect(result.timeout).toBe(5000);
+    });
+    it("handles URLs with :// correctly (not treated as key: value)", () => {
+        const result = parseYaml("tokenUrl: https://login.example.com/oauth/token");
+        expect(result.tokenUrl).toBe("https://login.example.com/oauth/token");
+    });
+    it("parses a realistic config file", () => {
+        const yaml = `
+baseUrl: http://localhost:8080/v2
+auth:
+  type: oauth2
+  clientId: my-client
+  clientSecret: my-secret
+  tokenUrl: https://auth.example.com/token
+  tokenCache:
+    disabled: false
+    filePath: /tmp/token-cache.json
+retry:
+  maxAttempts: 3
+  initialDelay: 100
+  retryOn: [429, 500, 502, 503, 504]
+cache:
+  enabled: true
+  ttl: 30000
+logger:
+  level: info
+timeout: 10000
+`;
+        const result = parseYaml(yaml);
+        expect(result.baseUrl).toBe("http://localhost:8080/v2");
+        expect(result.auth.type).toBe("oauth2");
+        expect(result.auth.clientId).toBe("my-client");
+        expect(result.retry.maxAttempts).toBe(3);
+        expect(result.retry.retryOn).toEqual([429, 500, 502, 503, 504]);
+        expect(result.cache.enabled).toBe(true);
+        expect(result.timeout).toBe(10000);
+    });
+});
+//# sourceMappingURL=yaml.test.js.map

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@bpmnkit/api",
+	"version": "0.0.8",
+	"private": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": ["dist/**/*.js", "dist/**/*.d.ts"],
+	"scripts": {
+		"generate": "node scripts/generate.mjs",
+		"generate:admin": "node scripts/generate.mjs --api admin",
+		"build": "node scripts/generate.mjs && node scripts/generate.mjs --api admin && tsc",
+		"typecheck": "tsc --noEmit",
+		"check": "biome check .",
+		"test": "vitest run"
+	},
+	"dependencies": {},
+	"description": "TypeScript client for the Camunda 8 REST API — 180 typed operations, OAuth2, retries, and caching",
+	"keywords": ["camunda", "zeebe", "bpmn", "api", "client", "rest", "typescript"],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/bpmnkit/monorepo"
+	}
+}