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

package/dist/src/client.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Main Candescent DI TypeScript SDK client.
+ *
+ * Wraps OpenAPI-generated API classes with automatic auth injection,
+ * tracing headers, and token lifecycle management. Generated API methods
+ * have clean signatures with typed models — no raw JSON.
+ *
+ * @example Client credentials (server-to-server)
+ * ```ts
+ * import { CandescentClient, Environment } from "@candescent/di-typescript-sdk";
+ *
+ * const client = new CandescentClient({
+ *   clientId: "my-id",
+ *   clientSecret: "my-secret",
+ *   institutionId: "12345",
+ *   environment: Environment.Stage,
+ * });
+ *
+ * // Register a customer with typed models
+ * const result = await client.customerManagement.register({
+ *   diFiid: "05523",
+ *   fICustomer: { fiId: { value: "05523" }, memberNumber: "123456789", ... },
+ * });
+ *
+ * // List accounts (hostUserId and loginId are mutually exclusive — pass one, not both)
+ * const accounts = await client.accounts.list({ hostUserId: "HOST01" });
+ *
+ * await client.close();
+ * ```
+ *
+ * @example From environment variables
+ * ```ts
+ * const client = CandescentClient.fromEnv();
+ * ```
+ */
+import { type TokenProvider } from "./auth.js";
+import { AccountsApi, AlertConfigurationApi, AlertDeliveryApi, AlertPreferencesApi, AuthenticationApi, BusinessBankingApi, CustomerCampaignsApi, CustomerManagementApi, DocumentsAndPreferencesApi, MoneyMovementApi, MXApi, NotificationChannelsApi } from "../generated/src/apis/index.js";
+export { type RequestOptions } from "./transport.js";
+export declare enum Environment {
+    Stage = "https://api.candescent.com/digitalbanking/stage",
+    Production = "https://api.candescent.com/digitalbanking"
+}
+export interface ClientConfig {
+    clientId?: string;
+    clientSecret?: string;
+    institutionId: string;
+    username?: string;
+    password?: string;
+    environment?: Environment;
+    baseUrl?: string;
+    bearerToken?: string;
+    /** Provide a custom token provider; used for both V1 and V2 paths. */
+    tokenProvider?: TokenProvider;
+    debug?: boolean;
+}
+export declare class CandescentClient {
+    private readonly v2TokenProvider;
+    private readonly v1TokenProvider;
+    readonly accounts: AccountsApi;
+    readonly alertConfiguration: AlertConfigurationApi;
+    readonly alertDelivery: AlertDeliveryApi;
+    readonly alertPreferences: AlertPreferencesApi;
+    readonly authentication: AuthenticationApi;
+    readonly businessBanking: BusinessBankingApi;
+    readonly customerCampaigns: CustomerCampaignsApi;
+    readonly customerManagement: CustomerManagementApi;
+    readonly documents: DocumentsAndPreferencesApi;
+    readonly moneyMovement: MoneyMovementApi;
+    readonly mx: MXApi;
+    readonly notificationChannels: NotificationChannelsApi;
+    constructor(config: ClientConfig);
+    close(): Promise<void>;
+    /**
+     * Build a client from environment variables (zero hardcoded secrets).
+     *
+     * Reads:
+     * - `CANDESCENT_CLIENT_ID`
+     * - `CANDESCENT_CLIENT_SECRET`
+     * - `CANDESCENT_INSTITUTION_ID`
+     * - `CANDESCENT_BEARER_TOKEN` (skip OAuth entirely)
+     * - `CANDESCENT_ENVIRONMENT` ("stage" | "production")
+     * - `CANDESCENT_USERNAME` (optional, for password grant)
+     * - `CANDESCENT_PASSWORD` (optional, for password grant)
+     */
+    static fromEnv(): CandescentClient;
+}

package/dist/src/client.js

@@ -0,0 +1,399 @@
+/**
+ * Main Candescent DI TypeScript SDK client.
+ *
+ * Wraps OpenAPI-generated API classes with automatic auth injection,
+ * tracing headers, and token lifecycle management. Generated API methods
+ * have clean signatures with typed models — no raw JSON.
+ *
+ * @example Client credentials (server-to-server)
+ * ```ts
+ * import { CandescentClient, Environment } from "@candescent/di-typescript-sdk";
+ *
+ * const client = new CandescentClient({
+ *   clientId: "my-id",
+ *   clientSecret: "my-secret",
+ *   institutionId: "12345",
+ *   environment: Environment.Stage,
+ * });
+ *
+ * // Register a customer with typed models
+ * const result = await client.customerManagement.register({
+ *   diFiid: "05523",
+ *   fICustomer: { fiId: { value: "05523" }, memberNumber: "123456789", ... },
+ * });
+ *
+ * // List accounts (hostUserId and loginId are mutually exclusive — pass one, not both)
+ * const accounts = await client.accounts.list({ hostUserId: "HOST01" });
+ *
+ * await client.close();
+ * ```
+ *
+ * @example From environment variables
+ * ```ts
+ * const client = CandescentClient.fromEnv();
+ * ```
+ */
+import { ClientCredentialsProvider, PasswordGrantProvider, StaticTokenProvider, TokenEndpoint, } from "./auth.js";
+import { CandescentError, errorForStatus } from "./errors.js";
+import { validateUrlParams } from "./validate.js";
+import { DEFAULT_RETRY, withRetry } from "./retry.js";
+import { Configuration, } from "../generated/src/runtime.js";
+import { AccountsApi, AlertConfigurationApi, AlertDeliveryApi, AlertPreferencesApi, AuthenticationApi, BusinessBankingApi, CustomerCampaignsApi, CustomerManagementApi, DocumentsAndPreferencesApi, MoneyMovementApi, MXApi, NotificationChannelsApi, } from "../generated/src/apis/index.js";
+export var Environment;
+(function (Environment) {
+    Environment["Stage"] = "https://api.candescent.com/digitalbanking/stage";
+    Environment["Production"] = "https://api.candescent.com/digitalbanking";
+})(Environment || (Environment = {}));
+/**
+ * URL path segments that require a V1 (legacy) OAuth token.
+ * All other paths use V2 (current) tokens.
+ */
+const V1_PATH_SEGMENTS = [
+    "/bankingservices/",
+    "/registration/",
+    "/destinations/",
+    "/subscriptions/",
+    "/send-event/",
+];
+function isV1Path(url) {
+    return V1_PATH_SEGMENTS.some((seg) => url.includes(seg));
+}
+// ── XML → JSON transparent conversion ───────────────────────────────
+// Several Candescent endpoints (registration, bankingservices) return
+// XML regardless of the Accept header. The generated runtime assumes
+// JSON, so we intercept XML responses in a `post` middleware and
+// convert them to JSON transparently.
+const XML_ENTITIES = {
+    "&": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&apos;": "'",
+    "&quot;": '"',
+};
+function decodeXmlEntities(s) {
+    return s
+        .replace(/&amp;|&lt;|&gt;|&apos;|&quot;/g, (m) => XML_ENTITIES[m] ?? m)
+        .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)));
+}
+function stripCdata(s) {
+    return s.replace(/<!\[CDATA\[([\s\S]*?)]]>/g, (_, content) => content);
+}
+/**
+ * Check if a parent element name is the plural/collection form of a
+ * child name, meaning the child should always be an array.
+ * Handles: channelInfos→channelInfo, destinations→destination,
+ * postalAddresses→postalAddress, phoneNumbers→phoneNumber, etc.
+ */
+function isCollectionParent(parentKey, childKey) {
+    const p = parentKey.toLowerCase();
+    const c = childKey.toLowerCase();
+    return (p === c + "s" ||
+        p === c + "es" ||
+        (c.endsWith("y") && p === c.slice(0, -1) + "ies") ||
+        (p.endsWith("s") && p.startsWith(c)));
+}
+function normalizeArrays(obj, parentKey) {
+    if (obj === null || obj === undefined || typeof obj !== "object")
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map((item) => normalizeArrays(item));
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        let normalized = normalizeArrays(value, key);
+        if (parentKey && isCollectionParent(parentKey, key) && !Array.isArray(normalized)) {
+            normalized = [normalized];
+        }
+        result[key] = normalized;
+    }
+    return result;
+}
+function parseXmlToJson(xml) {
+    const processed = stripCdata(xml).replace(/<\?xml[^?]*\?>\s*/, "");
+    const stack = [];
+    let root = {};
+    let current = null;
+    const tagRe = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?]]>|<\/?([^\s>\/]+)[^>]*>|([^<]+)/g;
+    let match;
+    while ((match = tagRe.exec(processed)) !== null) {
+        const full = match[0];
+        const text = match[2];
+        // Skip comments and any residual CDATA markers
+        if (full.startsWith("<!--") || full.startsWith("<!["))
+            continue;
+        if (text !== undefined) {
+            if (current)
+                current.text += decodeXmlEntities(text.trim());
+            continue;
+        }
+        if (full.startsWith("</")) {
+            if (!current)
+                continue;
+            const rawTag = current.tag;
+            const key = rawTag.includes(":") ? rawTag.split(":").pop() : rawTag;
+            const hasChildren = Object.keys(current.children).length > 0;
+            const value = hasChildren ? current.children : (current.text || null);
+            const parent = stack.pop();
+            if (parent) {
+                if (key in parent.children) {
+                    const existing = parent.children[key];
+                    parent.children[key] = Array.isArray(existing)
+                        ? [...existing, value]
+                        : [existing, value];
+                }
+                else {
+                    parent.children[key] = value;
+                }
+                current = parent;
+            }
+            else {
+                root[key] = value;
+                current = null;
+            }
+        }
+        else if (!full.endsWith("/>")) {
+            const tag = match[1];
+            const node = { tag, children: {}, text: "" };
+            if (current)
+                stack.push(current);
+            current = node;
+        }
+        else {
+            const tag = match[1];
+            const key = tag.includes(":") ? tag.split(":").pop() : tag;
+            if (current) {
+                current.children[key] = null;
+            }
+            else {
+                root[key] = null;
+            }
+        }
+    }
+    return normalizeArrays(root);
+}
+/**
+ * Middleware that converts XML responses into JSON transparently.
+ * If a response has an XML content-type, the body is parsed and a new
+ * Response with `application/json` is returned so the generated
+ * `JSONApiResponse.value()` works correctly.
+ *
+ * When the XML has a single root element, the converted JSON includes
+ * BOTH the wrapped form (root key → children) and the unwrapped children
+ * at the top level. This ensures compatibility with both transformer
+ * styles: some expect `{FICustomer: {...}}` while others expect the
+ * inner fields directly.
+ */
+const xmlToJsonMiddleware = {
+    async post(context) {
+        const ct = context.response.headers.get("content-type") ?? "";
+        if (!ct.includes("xml"))
+            return;
+        const text = await context.response.text();
+        let json;
+        try {
+            json = parseXmlToJson(text);
+        }
+        catch {
+            return new Response(text, {
+                status: context.response.status,
+                statusText: context.response.statusText,
+                headers: context.response.headers,
+            });
+        }
+        // If the XML had a single root element, merge its children at the
+        // top level so both wrapped and unwrapped transformers can find data.
+        const keys = Object.keys(json);
+        if (keys.length === 1 && typeof json[keys[0]] === "object" && json[keys[0]] !== null) {
+            json = { ...json[keys[0]], ...json };
+        }
+        return new Response(JSON.stringify(json), {
+            status: context.response.status,
+            statusText: context.response.statusText,
+            headers: {
+                ...Object.fromEntries(context.response.headers.entries()),
+                "content-type": "application/json",
+                "x-original-content-type": ct,
+            },
+        });
+    },
+};
+/**
+ * Middleware that intercepts non-2xx responses and throws a rich ApiError
+ * (with status, body, headers) instead of the generated ResponseError
+ * which only says "Response returned an error code".
+ */
+const errorBodyMiddleware = {
+    async post(context) {
+        const { response } = context;
+        if (response.ok)
+            return;
+        const body = await response.text();
+        let message = `${response.status} ${response.statusText}`;
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed.message)
+                message = `${message}: ${parsed.message}`;
+            if (parsed.code)
+                message = `[${parsed.code}] ${message}`;
+        }
+        catch {
+            if (body)
+                message = `${message}\n${body}`;
+        }
+        throw errorForStatus(response.status, response.headers, body, new Response(body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        }));
+    },
+};
+export class CandescentClient {
+    v2TokenProvider;
+    v1TokenProvider;
+    accounts;
+    alertConfiguration;
+    alertDelivery;
+    alertPreferences;
+    authentication;
+    businessBanking;
+    customerCampaigns;
+    customerManagement;
+    documents;
+    moneyMovement;
+    mx;
+    notificationChannels;
+    constructor(config) {
+        const baseUrl = config.baseUrl ?? config.environment ?? Environment.Stage;
+        const institutionId = config.institutionId;
+        if (config.tokenProvider) {
+            this.v2TokenProvider = config.tokenProvider;
+            this.v1TokenProvider = config.tokenProvider;
+        }
+        else if (config.bearerToken) {
+            const staticProvider = new StaticTokenProvider(config.bearerToken);
+            this.v2TokenProvider = staticProvider;
+            this.v1TokenProvider = staticProvider;
+        }
+        else if (config.clientId && config.clientSecret && config.username && config.password) {
+            this.v2TokenProvider = new PasswordGrantProvider(config.clientId, config.clientSecret, config.username, config.password, institutionId, baseUrl, TokenEndpoint.V2_CURRENT);
+            this.v1TokenProvider = new PasswordGrantProvider(config.clientId, config.clientSecret, config.username, config.password, institutionId, baseUrl, TokenEndpoint.V1_LEGACY);
+        }
+        else if (config.clientId && config.clientSecret) {
+            this.v2TokenProvider = new ClientCredentialsProvider(config.clientId, config.clientSecret, institutionId, baseUrl, TokenEndpoint.V2_CURRENT);
+            this.v1TokenProvider = new ClientCredentialsProvider(config.clientId, config.clientSecret, institutionId, baseUrl, TokenEndpoint.V1_LEGACY);
+        }
+        else {
+            throw new CandescentError("Provide clientId+clientSecret, bearerToken, or a custom tokenProvider");
+        }
+        const v2tp = this.v2TokenProvider;
+        const v1tp = this.v1TokenProvider;
+        const debugMode = config.debug ?? false;
+        const dualTokenMiddleware = {
+            async pre(context) {
+                const isV1 = isV1Path(context.url);
+                const tp = isV1 ? v1tp : v2tp;
+                const token = await tp.getToken();
+                const uuid = crypto.randomUUID();
+                const tidKey = isV1 ? "di_tid" : "transactionId";
+                const headers = {
+                    Accept: "application/json",
+                    ...context.init.headers,
+                    Authorization: `${token.tokenType} ${token.token}`,
+                    [tidKey]: uuid,
+                    correlationId: uuid,
+                    institutionId,
+                };
+                if (debugMode) {
+                    const method = context.init.method ?? "GET";
+                    const safeHeaders = { ...headers };
+                    delete safeHeaders["Authorization"];
+                    console.debug(`[candescent] ${method} ${context.url}`, safeHeaders);
+                }
+                return { url: context.url, init: { ...context.init, headers } };
+            },
+            async post(context) {
+                if (debugMode) {
+                    const { response } = context;
+                    console.debug(`[candescent] ${response.status} ${response.statusText} ${context.url}`);
+                }
+                return undefined;
+            },
+        };
+        const paramValidationMiddleware = {
+            async pre(context) {
+                validateUrlParams(context.url);
+                return undefined;
+            },
+        };
+        const generatedConfig = new Configuration({
+            basePath: baseUrl,
+            fetchApi: (url, init) => withRetry(() => fetch(url, init), DEFAULT_RETRY),
+            middleware: [
+                paramValidationMiddleware,
+                dualTokenMiddleware,
+                xmlToJsonMiddleware,
+                errorBodyMiddleware,
+            ],
+        });
+        this.accounts = new AccountsApi(generatedConfig);
+        this.alertConfiguration = new AlertConfigurationApi(generatedConfig);
+        this.alertDelivery = new AlertDeliveryApi(generatedConfig);
+        this.alertPreferences = new AlertPreferencesApi(generatedConfig);
+        this.authentication = new AuthenticationApi(generatedConfig);
+        this.businessBanking = new BusinessBankingApi(generatedConfig);
+        this.customerCampaigns = new CustomerCampaignsApi(generatedConfig);
+        this.customerManagement = new CustomerManagementApi(generatedConfig);
+        this.documents = new DocumentsAndPreferencesApi(generatedConfig);
+        this.moneyMovement = new MoneyMovementApi(generatedConfig);
+        this.mx = new MXApi(generatedConfig);
+        this.notificationChannels = new NotificationChannelsApi(generatedConfig);
+    }
+    async close() {
+        for (const tp of [this.v2TokenProvider, this.v1TokenProvider]) {
+            if (tp.revokeToken) {
+                try {
+                    await tp.revokeToken();
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
+    /**
+     * Build a client from environment variables (zero hardcoded secrets).
+     *
+     * Reads:
+     * - `CANDESCENT_CLIENT_ID`
+     * - `CANDESCENT_CLIENT_SECRET`
+     * - `CANDESCENT_INSTITUTION_ID`
+     * - `CANDESCENT_BEARER_TOKEN` (skip OAuth entirely)
+     * - `CANDESCENT_ENVIRONMENT` ("stage" | "production")
+     * - `CANDESCENT_USERNAME` (optional, for password grant)
+     * - `CANDESCENT_PASSWORD` (optional, for password grant)
+     */
+    static fromEnv() {
+        const env = (k) => process.env[k];
+        const clientId = env("CANDESCENT_CLIENT_ID");
+        const clientSecret = env("CANDESCENT_CLIENT_SECRET");
+        const institutionId = env("CANDESCENT_INSTITUTION_ID");
+        const bearerToken = env("CANDESCENT_BEARER_TOKEN");
+        const envName = env("CANDESCENT_ENVIRONMENT")?.toLowerCase();
+        const username = env("CANDESCENT_USERNAME");
+        const password = env("CANDESCENT_PASSWORD");
+        if (!institutionId) {
+            throw new CandescentError("CANDESCENT_INSTITUTION_ID is required");
+        }
+        if (!bearerToken && !(clientId && clientSecret)) {
+            throw new CandescentError("Set CANDESCENT_BEARER_TOKEN or both CANDESCENT_CLIENT_ID and CANDESCENT_CLIENT_SECRET");
+        }
+        const environment = envName === "production" ? Environment.Production : Environment.Stage;
+        return new CandescentClient({
+            clientId,
+            clientSecret,
+            institutionId,
+            bearerToken,
+            username,
+            password,
+            environment,
+        });
+    }
+}

package/dist/src/completions.d.ts

@@ -0,0 +1,4 @@
+export declare const TAG_GROUP_NAMES: string[];
+export declare const TAG_NAMES: string[];
+export declare const BROWSABLE_NAMES: string[];
+export declare const QUALIFIED_OP_NAMES: string[];

package/dist/src/completions.js

@@ -0,0 +1,5 @@
+// Auto-generated — lightweight string arrays for shell autocomplete
+export const TAG_GROUP_NAMES = ["authentication", "customer-management", "core-banking", "business-banking", "money-movement", "alerts-and-notifications", "documents-and-preferences", "customer-campaigns", "mx"];
+export const TAG_NAMES = ["oauth-v1", "oauth-v2", "registration-and-access", "profile-and-status", "contact-info", "accounts", "transactions", "banking-activities", "images", "registration", "profile", "entitlements", "recipients", "transfers", "system-alerts", "institution-alerts", "templates", "institution-preferences", "user-preferences", "notification-channels", "history-and-events", "institution-disclosures", "user-disclosures", "electronic-statements", "experience-groups", "jobs", "promotions-suite", "audience", "users", "data", "widgets"];
+export const BROWSABLE_NAMES = ["authentication", "customer-management", "core-banking", "business-banking", "money-movement", "alerts-and-notifications", "documents-and-preferences", "customer-campaigns", "mx", "oauth-v1", "oauth-v2", "registration-and-access", "profile-and-status", "contact-info", "accounts", "transactions", "banking-activities", "images", "registration", "profile", "entitlements", "recipients", "transfers", "system-alerts", "institution-alerts", "templates", "institution-preferences", "user-preferences", "notification-channels", "history-and-events", "institution-disclosures", "user-disclosures", "electronic-statements", "experience-groups", "jobs", "promotions-suite", "audience", "users", "data", "widgets"];
+export const QUALIFIED_OP_NAMES = ["accounts.list", "accounts.get", "audience.getUserListDetails", "audience.createUserListMetadata", "images.listBankingImages", "images.getBankingImage", "institution-disclosures.listInstitutionDisclosures", "institution-disclosures.createInstitutionDisclosure", "institution-disclosures.updateInstitutionDisclosure", "user-disclosures.listUserDisclosures", "user-disclosures.updateUserDisclosure", "user-disclosures.createUserDisclosure", "user-disclosures.deleteUserDisclosure", "experience-groups.uploadUserListFile", "experience-groups.createExperienceGroup", "experience-groups.listExperienceGroups", "jobs.getJobErrors", "jobs.getJob", "jobs.listJobs", "experience-groups.deleteExperienceGroup", "experience-groups.updateExperienceGroup", "profile-and-status.getInstitutionUser", "history-and-events.listHistory", "history-and-events.getHistoryContent", "templates.listTemplates", "templates.createTemplate", "templates.updateTemplate", "templates.deleteTemplate", "system-alerts.listTypes", "system-alerts.createType", "system-alerts.updateType", "system-alerts.deleteType", "institution-alerts.listInstitutionTypes", "institution-alerts.createInstitutionType", "institution-alerts.updateInstitutionType", "institution-alerts.deleteInstitutionType", "user-preferences.list", "user-preferences.create", "user-preferences.get", "user-preferences.update", "user-preferences.delete", "institution-preferences.listInstitution", "institution-preferences.createInstitution", "institution-preferences.updateInstitution", "institution-preferences.deleteInstitution", "history-and-events.publishEvents", "recipients.listRecipients", "recipients.createRecipient", "recipients.getRecipient", "recipients.updateRecipient", "recipients.deleteRecipient", "transactions.listTransactions", "transfers.createTransfer", "profile-and-status.getInformation", "accounts.getAccounts", "electronic-statements.getEstatementsReport", "contact-info.getContactMethods", "registration-and-access.resetPassword", "registration-and-access.unlockUser", "contact-info.updateContactInfo", "electronic-statements.getDisclosuresByAccount", "electronic-statements.updateStatementDeliveryPreference", "electronic-statements.updateEStatementPreferences", "oauth-v2.getAuthorizationCode", "oauth-v2.authorizeClient", "profile-and-status.getCustomer", "accounts.listCustomerAccounts", "oauth-v1.createLegacyToken", "promotions-suite.createUserList", "promotions-suite.getUserListStatus", "registration-and-access.register", "notification-channels.listUserSubscriptions", "notification-channels.updateSubscription", "notification-channels.createSubscription", "notification-channels.listInstitutionSubscriptions", "notification-channels.getSubscription", "notification-channels.deleteSubscription", "notification-channels.sendCustomerEvent", "oauth-v2.createToken", "oauth-v2.revokeToken", "profile-and-status.getUserStatus", "banking-activities.searchActivities", "users.listUsers", "users.getUser", "widgets.getWidgetUrl", "data.downloadTransactionLogs", "profile.getBusinessDetails", "registration.getRegistrationConfig", "registration.getRegistrationByConfirmation", "registration.createRegistration", "registration.getRegistrationById", "entitlements.getBusinessEntitlements", "entitlements.getUserEntitlements"];

package/dist/src/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Candescent SDK error hierarchy.
+ *
+ * Modeled after Stainless — each HTTP status gets its own class.
+ * Every ApiError exposes: statusCode, message, headers, body, rawResponse.
+ */
+export declare class CandescentError extends Error {
+    constructor(message: string);
+}
+export declare class ApiError extends CandescentError {
+    readonly statusCode: number;
+    readonly headers: Headers;
+    readonly body: string;
+    readonly rawResponse: Response;
+    constructor(statusCode: number, message: string, headers: Headers, body: string, rawResponse: Response);
+    toString(): string;
+}
+export declare class BadRequestError extends ApiError {
+    constructor(h: Headers, b: string, r: Response);
+}
+export declare class AuthenticationError extends ApiError {
+    constructor(h: Headers, b: string, r: Response);
+}
+export declare class PermissionDeniedError extends ApiError {
+    constructor(h: Headers, b: string, r: Response);
+}
+export declare class NotFoundError extends ApiError {
+    constructor(h: Headers, b: string, r: Response);
+}
+export declare class ConflictError extends ApiError {
+    constructor(h: Headers, b: string, r: Response);
+}
+export declare class UnprocessableEntityError extends ApiError {
+    constructor(h: Headers, b: string, r: Response);
+}
+export declare class RateLimitError extends ApiError {
+    readonly retryAfter: number | null;
+    constructor(h: Headers, b: string, r: Response);
+}
+export declare class InternalServerError extends ApiError {
+    constructor(status: number, h: Headers, b: string, r: Response);
+}
+export declare class ConnectionError extends CandescentError {
+    constructor(message: string);
+}
+export declare class RequestTimeoutError extends CandescentError {
+    constructor(message: string);
+}
+export declare function errorForStatus(statusCode: number, headers: Headers, body: string, rawResponse: Response): ApiError;

package/dist/src/errors.js

@@ -0,0 +1,119 @@
+/**
+ * Candescent SDK error hierarchy.
+ *
+ * Modeled after Stainless — each HTTP status gets its own class.
+ * Every ApiError exposes: statusCode, message, headers, body, rawResponse.
+ */
+export class CandescentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CandescentError";
+    }
+}
+export class ApiError extends CandescentError {
+    statusCode;
+    headers;
+    body;
+    rawResponse;
+    constructor(statusCode, message, headers, body, rawResponse) {
+        super(message);
+        this.name = "ApiError";
+        this.statusCode = statusCode;
+        this.headers = headers;
+        this.body = body;
+        this.rawResponse = rawResponse;
+    }
+    toString() {
+        let s = `${this.name} (HTTP ${this.statusCode})`;
+        if (this.body) {
+            try {
+                const parsed = JSON.parse(this.body);
+                s += `: ${JSON.stringify(parsed, null, 2)}`;
+            }
+            catch {
+                s += `: ${this.body}`;
+            }
+        }
+        return s;
+    }
+}
+export class BadRequestError extends ApiError {
+    constructor(h, b, r) {
+        super(400, b, h, b, r);
+        this.name = "BadRequestError";
+    }
+}
+export class AuthenticationError extends ApiError {
+    constructor(h, b, r) {
+        super(401, b, h, b, r);
+        this.name = "AuthenticationError";
+    }
+}
+export class PermissionDeniedError extends ApiError {
+    constructor(h, b, r) {
+        super(403, b, h, b, r);
+        this.name = "PermissionDeniedError";
+    }
+}
+export class NotFoundError extends ApiError {
+    constructor(h, b, r) {
+        super(404, b, h, b, r);
+        this.name = "NotFoundError";
+    }
+}
+export class ConflictError extends ApiError {
+    constructor(h, b, r) {
+        super(409, b, h, b, r);
+        this.name = "ConflictError";
+    }
+}
+export class UnprocessableEntityError extends ApiError {
+    constructor(h, b, r) {
+        super(422, b, h, b, r);
+        this.name = "UnprocessableEntityError";
+    }
+}
+export class RateLimitError extends ApiError {
+    retryAfter;
+    constructor(h, b, r) {
+        super(429, b, h, b, r);
+        this.name = "RateLimitError";
+        const ra = h.get("Retry-After");
+        this.retryAfter = ra ? parseFloat(ra) || null : null;
+    }
+}
+export class InternalServerError extends ApiError {
+    constructor(status, h, b, r) {
+        super(status, b, h, b, r);
+        this.name = "InternalServerError";
+    }
+}
+export class ConnectionError extends CandescentError {
+    constructor(message) {
+        super(message);
+        this.name = "ConnectionError";
+    }
+}
+export class RequestTimeoutError extends CandescentError {
+    constructor(message) {
+        super(message);
+        this.name = "RequestTimeoutError";
+    }
+}
+const STATUS_MAP = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+};
+export function errorForStatus(statusCode, headers, body, rawResponse) {
+    const Cls = STATUS_MAP[statusCode];
+    if (Cls)
+        return new Cls(headers, body, rawResponse);
+    if (statusCode >= 500)
+        return new InternalServerError(statusCode, headers, body, rawResponse);
+    return new ApiError(statusCode, body, headers, body, rawResponse);
+}