@cdx-forge/di-typescript-sdk 0.1.0-beta.1

package/dist/src/result.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Result<T, E> monad for non-throwing error handling.
+ *
+ * Inspired by Speakeasy's pattern — callers can choose between
+ * try/catch and explicit result checking:
+ *
+ *   // Approach 1: traditional
+ *   const accounts = await client.accounts.list();
+ *
+ *   // Approach 2: result monad (never throws)
+ *   const result = await safe(() => client.accounts.list({hostUserId: "user-12345"}));
+ *   if (result.ok) console.log(result.value);
+ *   else console.error(result.error);
+ */
+export type Result<T, E = Error> = Ok<T> | Err<E>;
+export interface Ok<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export interface Err<E> {
+    readonly ok: false;
+    readonly error: E;
+}
+export declare function ok<T>(value: T): Ok<T>;
+export declare function err<E>(error: E): Err<E>;
+/**
+ * Wraps an async function so it returns Result<T, E> instead of throwing.
+ */
+export declare function safe<T>(fn: () => Promise<T>): Promise<Result<T, Error>>;

package/dist/src/result.js

@@ -0,0 +1,26 @@
+/**
+ * Result<T, E> monad for non-throwing error handling.
+ *
+ * Inspired by Speakeasy's pattern — callers can choose between
+ * try/catch and explicit result checking:
+ *
+ *   // Approach 1: traditional
+ *   const accounts = await client.accounts.list();
+ *
+ *   // Approach 2: result monad (never throws)
+ *   const result = await safe(() => client.accounts.list({hostUserId: "user-12345"}));
+ *   if (result.ok) console.log(result.value);
+ *   else console.error(result.error);
+ */
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}
+/**
+ * Wraps an async function so it returns Result<T, E> instead of throwing.
+ */
+export function safe(fn) {
+    return fn().then((value) => ok(value), (error) => err(error instanceof Error ? error : new Error(String(error))));
+}

package/dist/src/retry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Retry with jittered exponential backoff.
+ *
+ * Supports per-operation override via RequestOptions.maxRetries.
+ */
+export interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+export declare const DEFAULT_RETRY: RetryConfig;
+export declare function withRetry(fn: () => Promise<Response>, config: RetryConfig): Promise<Response>;

package/dist/src/retry.js

@@ -0,0 +1,51 @@
+/**
+ * Retry with jittered exponential backoff.
+ *
+ * Supports per-operation override via RequestOptions.maxRetries.
+ */
+export const DEFAULT_RETRY = {
+    maxRetries: 2,
+    baseDelayMs: 500,
+    maxDelayMs: 30_000,
+};
+const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+export async function withRetry(fn, config) {
+    let lastResponse = null;
+    let lastError = null;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+        let response;
+        try {
+            response = await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < config.maxRetries) {
+                const delay = Math.min(config.baseDelayMs * 2 ** attempt + Math.random() * config.baseDelayMs, config.maxDelayMs);
+                await new Promise((r) => setTimeout(r, delay));
+                continue;
+            }
+            throw lastError;
+        }
+        if (!RETRYABLE_STATUS.has(response.status))
+            return response;
+        lastResponse = response;
+        if (attempt < config.maxRetries) {
+            const retryAfter = response.headers.get("Retry-After");
+            let delay;
+            if (retryAfter) {
+                const seconds = parseFloat(retryAfter);
+                if (!Number.isNaN(seconds) && seconds > 0) {
+                    delay = Math.min(seconds * 1000, config.maxDelayMs);
+                }
+                else {
+                    delay = Math.min(config.baseDelayMs * 2 ** attempt + Math.random() * config.baseDelayMs, config.maxDelayMs);
+                }
+            }
+            else {
+                delay = Math.min(config.baseDelayMs * 2 ** attempt + Math.random() * config.baseDelayMs, config.maxDelayMs);
+            }
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    return lastResponse;
+}

package/dist/src/transport.d.ts

@@ -0,0 +1,53 @@
+/**
+ * HTTP transport — wires auth injection, retry, headers, and debug logging
+ * on top of the native Fetch API.
+ */
+import type { TokenProvider } from "./auth.js";
+import { type RetryConfig } from "./retry.js";
+export interface RequestOptions {
+    /** Override the default timeout for this request (ms). */
+    timeout?: number;
+    /** Override the default max retries for this request. */
+    maxRetries?: number;
+    /** Extra headers to send with this request. */
+    headers?: Record<string, string>;
+    /** Signal for aborting the request. */
+    signal?: AbortSignal;
+    /**
+     * Institution customer ID — required for Business Banking endpoints
+     * when acting on behalf of a specific business location.
+     */
+    institutionCustomerId?: string;
+    /**
+     * User context for client_credentials grant.
+     * Many endpoints require either hostUserId or loginId when the token
+     * was obtained via client_credentials (server-to-server) to identify
+     * which end-user the operation is on behalf of.
+     * With password grant tokens this is embedded in the token itself.
+     */
+    hostUserId?: string;
+    /** Alternative to hostUserId — cannot use both simultaneously. */
+    loginId?: string;
+}
+export interface TransportConfig {
+    baseUrl: string;
+    institutionId: string;
+    tokenProvider: TokenProvider;
+    retry?: Partial<RetryConfig>;
+    timeout?: number;
+    userAgent?: string;
+    debug?: boolean;
+    fetch?: typeof globalThis.fetch;
+    interceptors?: Array<(headers: Record<string, string>) => Record<string, string>>;
+}
+export declare class Transport {
+    private readonly config;
+    constructor(cfg: TransportConfig);
+    request<T = unknown>(method: string, path: string, opts?: {
+        body?: unknown;
+        query?: Record<string, unknown>;
+        options?: RequestOptions;
+    }): Promise<T>;
+    /** Build merged headers (defaults + auth + interceptors + per-op). */
+    private buildHeaders;
+}

package/dist/src/transport.js

@@ -0,0 +1,115 @@
+/**
+ * HTTP transport — wires auth injection, retry, headers, and debug logging
+ * on top of the native Fetch API.
+ */
+import { CandescentError, errorForStatus, ConnectionError, RequestTimeoutError } from "./errors.js";
+import { withRetry, DEFAULT_RETRY } from "./retry.js";
+export class Transport {
+    config;
+    constructor(cfg) {
+        this.config = {
+            baseUrl: cfg.baseUrl.replace(/\/$/, ""),
+            institutionId: cfg.institutionId,
+            tokenProvider: cfg.tokenProvider,
+            retry: { ...DEFAULT_RETRY, ...cfg.retry },
+            timeout: cfg.timeout ?? 30_000,
+            userAgent: cfg.userAgent ?? "@candescent/di-typescript-sdk/1.0.0",
+            debug: cfg.debug ?? false,
+            fetch: cfg.fetch ?? globalThis.fetch.bind(globalThis),
+            interceptors: cfg.interceptors ?? [],
+        };
+    }
+    async request(method, path, opts) {
+        const { body, query, options = {} } = opts ?? {};
+        const mergedQuery = { ...query };
+        if (options.hostUserId)
+            mergedQuery.hostUserId = options.hostUserId;
+        if (options.loginId)
+            mergedQuery.loginId = options.loginId;
+        let url = this.config.baseUrl + path;
+        if (mergedQuery) {
+            const params = new URLSearchParams();
+            for (const [k, v] of Object.entries(mergedQuery)) {
+                if (v != null)
+                    params.set(k, String(v));
+            }
+            const qs = params.toString();
+            if (qs)
+                url += "?" + qs;
+        }
+        const headers = await this.buildHeaders(options);
+        const effectiveTimeout = options.timeout ?? this.config.timeout;
+        const effectiveRetry = {
+            ...this.config.retry,
+            ...(options.maxRetries != null ? { maxRetries: options.maxRetries } : {}),
+        };
+        const doFetch = async () => {
+            const controller = new AbortController();
+            const signal = options.signal
+                ? AbortSignal.any([options.signal, controller.signal])
+                : controller.signal;
+            const timer = setTimeout(() => controller.abort(), effectiveTimeout);
+            const init = { method, headers, signal };
+            if (body !== undefined) {
+                init.body = typeof body === "string" ? body : JSON.stringify(body);
+            }
+            if (this.config.debug) {
+                const safeHeaders = { ...headers };
+                delete safeHeaders["Authorization"];
+                console.debug(`[candescent] ${method} ${url}`, safeHeaders);
+            }
+            try {
+                const start = performance.now();
+                const resp = await this.config.fetch(url, init);
+                if (this.config.debug) {
+                    console.debug(`[candescent] ${method} ${url} -> ${resp.status} (${Math.round(performance.now() - start)}ms)`);
+                }
+                return resp;
+            }
+            catch (e) {
+                if (e instanceof DOMException && e.name === "AbortError") {
+                    throw new RequestTimeoutError(`Request timed out after ${effectiveTimeout}ms`);
+                }
+                throw new ConnectionError(e instanceof Error ? e.message : String(e));
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        const response = await withRetry(doFetch, effectiveRetry);
+        if (!response.ok) {
+            const text = await response.text();
+            throw errorForStatus(response.status, response.headers, text, response);
+        }
+        const text = await response.text();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new CandescentError(`Response is not valid JSON: ${text.slice(0, 300)}`);
+        }
+    }
+    /** Build merged headers (defaults + auth + interceptors + per-op). */
+    async buildHeaders(options) {
+        const token = await this.config.tokenProvider.getToken();
+        let headers = {
+            "User-Agent": this.config.userAgent,
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            institutionId: this.config.institutionId,
+            transactionid: crypto.randomUUID(),
+            Authorization: `${token.tokenType} ${token.token}`,
+        };
+        if (options.institutionCustomerId) {
+            headers["institutionCustomerId"] = options.institutionCustomerId;
+        }
+        for (const interceptor of this.config.interceptors) {
+            headers = interceptor(headers);
+        }
+        if (options.headers)
+            Object.assign(headers, options.headers);
+        return headers;
+    }
+}

package/dist/src/validate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parameter validation utilities powered by the operation registry.
+ *
+ * Checks mutual-exclusivity constraints (e.g. hostUserId vs loginId)
+ * before the request is sent, producing a clear client-side error
+ * instead of a cryptic 400 from the server.
+ */
+export interface MutexPair {
+    a: string;
+    b: string;
+}
+/**
+ * Extracts all unique mutual-exclusivity pairs from the registry.
+ * Result is cached after first call.
+ */
+export declare function getMutuallyExclusivePairs(): MutexPair[];
+/**
+ * Validate that no mutually exclusive parameters are both present.
+ * Throws CandescentError if a violation is found.
+ *
+ * @param params - key/value pairs being sent as query/path parameters
+ */
+export declare function validateParams(params: Record<string, unknown>): void;
+/**
+ * Validate query parameters extracted from a URL against mutual-exclusivity rules.
+ */
+export declare function validateUrlParams(url: string): void;

package/dist/src/validate.js

@@ -0,0 +1,68 @@
+/**
+ * Parameter validation utilities powered by the operation registry.
+ *
+ * Checks mutual-exclusivity constraints (e.g. hostUserId vs loginId)
+ * before the request is sent, producing a clear client-side error
+ * instead of a cryptic 400 from the server.
+ */
+import { OPERATION_REGISTRY } from "./registry.js";
+import { CandescentError } from "./errors.js";
+let _mutexPairs = null;
+/**
+ * Extracts all unique mutual-exclusivity pairs from the registry.
+ * Result is cached after first call.
+ */
+export function getMutuallyExclusivePairs() {
+    if (_mutexPairs)
+        return _mutexPairs;
+    const seen = new Set();
+    const pairs = [];
+    for (const op of Object.values(OPERATION_REGISTRY)) {
+        for (const p of op.params) {
+            if (p.mutuallyExclusiveWith?.length) {
+                for (const other of p.mutuallyExclusiveWith) {
+                    const key = [p.name, other].sort().join("+");
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        const [a, b] = [p.name, other].sort();
+                        pairs.push({ a, b });
+                    }
+                }
+            }
+        }
+    }
+    _mutexPairs = pairs;
+    return pairs;
+}
+/**
+ * Validate that no mutually exclusive parameters are both present.
+ * Throws CandescentError if a violation is found.
+ *
+ * @param params - key/value pairs being sent as query/path parameters
+ */
+export function validateParams(params) {
+    for (const { a, b } of getMutuallyExclusivePairs()) {
+        if (params[a] != null && params[b] != null) {
+            throw new CandescentError(`Parameters "${a}" and "${b}" are mutually exclusive — pass one, not both`);
+        }
+    }
+}
+/**
+ * Validate query parameters extracted from a URL against mutual-exclusivity rules.
+ */
+export function validateUrlParams(url) {
+    try {
+        const parsed = new URL(url);
+        const pairs = getMutuallyExclusivePairs();
+        for (const { a, b } of pairs) {
+            if (parsed.searchParams.has(a) && parsed.searchParams.has(b)) {
+                throw new CandescentError(`Parameters "${a}" and "${b}" are mutually exclusive — pass one, not both`);
+            }
+        }
+    }
+    catch (e) {
+        if (e instanceof CandescentError)
+            throw e;
+        // URL parsing failure — skip validation rather than blocking the request
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@cdx-forge/di-typescript-sdk",
+  "version": "0.1.0-beta.1",
+  "description": "TypeScript server SDK for the Candescent Digital Insight API",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./operations": {
+      "types": "./dist/src/operations.d.ts",
+      "import": "./dist/src/operations.js"
+    },
+    "./registry": {
+      "import": "./dist/src/registry.js",
+      "types": "./dist/src/registry.d.ts"
+    },
+    "./completions": {
+      "import": "./dist/src/completions.js",
+      "types": "./dist/src/completions.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "candescent",
+    "digital-insight",
+    "banking",
+    "sdk",
+    "api-client"
+  ],
+  "homepage": "https://github.com/dfh-digital-insight/cdx-di-typescript-sdk#readme",
+  "author": "Candescent",
+  "license": "Proprietary",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "pack:local": "pnpm run build && pnpm pack",
+    "lint": "tsc --noEmit",
+    "test": "node --test --experimental-strip-types src/pagination.test.ts src/retry.test.ts src/errors.test.ts src/result.test.ts"
+  }
+}