SDK Reference

Reference for @cdx-forge/di-typescript-sdk — client configuration, authentication, service areas, pagination, errors, and package exports.

For HTTP-level operation details, use the API Reference. For runnable scripts per API area, see Examples.

CandescentClient

Constructor

import { CandescentClient, Environment } from "@cdx-forge/di-typescript-sdk";

const client = new CandescentClient({
  clientId: "...",
  clientSecret: "...",
  institutionId: "...",
  environment: Environment.Stage, // optional; default Stage
  baseUrl: "https://custom.api.host", // optional override
});

Field	Required	Description
clientId	Yes*	OAuth client ID
clientSecret	Yes*	OAuth client secret
institutionId	Yes	Institution identifier
bearerToken	Yes*	Static JWT (skips OAuth flow)
username / password	No	Password grant (with client credentials)
tokenProvider	No	Custom TokenProvider implementation
environment	No	Environment.Stage or Environment.Production
baseUrl	No	Override API base URL (advanced)

*Provide clientId + clientSecret, bearerToken, or tokenProvider.

See Quick Start → Create a client for a code example.

CandescentClient.fromEnv()

Reads CANDESCENT_* environment variables. See Installation.

Lifecycle

Always call await client.close() on shutdown to revoke cached tokens and release resources.

const client = CandescentClient.fromEnv();
try {
  // ... API calls
} finally {
  await client.close();
}

Service areas

CandescentClient exposes generated API classes as properties. Map them to API Reference tag groups:

Client property	API area	Docs tag group
oAuthV1, oAuthV2	Authentication	Authentication
registrationAndAccess, profileAndStatus, contactInfo	Customer registration, profile, contact	Customer Management
accounts, transactions, bankingActivities, images	Accounts and transactions	Core Banking
entitlements, payments, registration	Business banking	Business Banking
recipients, transfers	Recipients and transfers	Money Movement
systemAlerts, institutionAlerts, templates, userPreferences, institutionPreferences, historyAndEvents	Alerts	Alerts and Notifications
institutionDisclosures, userDisclosures, electronicStatements	Disclosures and e-statements	Documents and Preferences
experienceGroups, jobs, promotionsSuite, audience	Campaigns and jobs	Customer Campaigns
users, data, widgets	MX integration	MX
notificationChannels	Subscriptions and events	Notification Channels

See Quick Start → Usage for Accounts and Business Banking examples. Additional service area examples:

Customer management

// Register a new customer
const response = await client.registrationAndAccess.register({
  diFiid: "05523",
  body: {
    fICustomer: {
      id: { value: "0", type: "GUID" },
      fiId: { value: "05523" },
      memberNumber: "123456789",
      person: {
        personName: { firstName: "Jane", lastName: "Smith" },
        contactInfo: { emailAddress: "[email protected]" },
      },
      userType: "PRIMARY",
    },
  },
});

// Reset password
await client.registrationAndAccess.resetPassword({ body: { loginId: "jane123" } });

Money movement

// List recipients for a user
const recipients = await client.recipients.listRecipients({ hostUserId: "user-12345" });

// Get a specific recipient
const recipient = await client.recipients.getRecipient({
  recipientId: "rec-abc123",
  hostUserId: "user-12345",
});

Notification channels

// List institution-level subscriptions
const subs = await client.notificationChannels.listInstitutionSubscriptions({});

// Get a specific subscription
const sub = await client.notificationChannels.getSubscription({
  subscriptionId: "sub-xyz",
});

Import request/response types from the main package:

import type { /* model names */ } from "@cdx-forge/di-typescript-sdk";

Standalone operations

For serverless functions or one-off scripts, use per-operation imports instead of CandescentClient. See Quick Start → Standalone functions and Framework Integration.

Operation registry

The SDK ships an operation registry that maps every API operation to its tag group, tag, HTTP method, path, and SDK accessor:

import registry from "@cdx-forge/di-typescript-sdk/registry";

Use it to enumerate available operations programmatically or build tooling that inspects the API surface at runtime.

Pagination

List endpoints support PageIterator — an async iterable that fetches subsequent pages:

import { PageIterator } from "@cdx-forge/di-typescript-sdk";

for await (const account of new PageIterator(
  (req) => client.accounts.list({ hostUserId: "user-12345", ...req }),
  { page: 0, size: 50 },
)) {
  console.log(account.accountId);
}

Omit size to use the API default page size (typically 25).

Error handling

All API errors throw typed subclasses of ApiError:

import {
  ApiError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  BadRequestError,
} from "@cdx-forge/di-typescript-sdk";

try {
  await client.accounts.get({ accountId: "missing" });
} catch (error) {
  if (error instanceof NotFoundError) {
    // 404
  } else if (error instanceof RateLimitError) {
    console.warn(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof AuthenticationError) {
    // 401 — check credentials
  } else if (error instanceof ApiError) {
    console.error(error.statusCode, error.message);
  } else {
    throw error;
  }
}

HTTP status	Exception class
Any non-2xx	ApiError (base)
400	BadRequestError
401	AuthenticationError
403	PermissionDeniedError
404	NotFoundError
409	ConflictError
422	UnprocessableEntityError
429	RateLimitError
5xx	InternalServerError

Retry behavior

The SDK retries transient failures with exponential backoff:

Retried status codes	Max retries	Initial delay	Max delay
408, 429, 500, 502, 503, 504	2 (3 total attempts)	500ms	30s

RateLimitError is thrown only after retries are exhausted. retryAfter reflects the Retry-After response header when present.

Validation

Some parameters are mutually exclusive. For example, hostUserId and loginId cannot be set on the same accounts request. When the SDK detects a constraint violation, it throws an error before making the HTTP call.

Versioning

The SDK package version and OpenAPI specification version are tracked independently:

Release	SDK (@cdx-forge/di-typescript-sdk)	OpenAPI spec (candescent-dev/openapi)
Current	1.0.0	1.6.0

When the OpenAPI spec changes, a new SDK release is generated from the updated spec. See GitHub releases for release notes.