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

package/README.md

@@ -1,40 +1,62 @@
-# @candescent/di-typescript-sdk
+# Candescent Digital Insight — TypeScript SDK
 
-[![npm version](https://img.shields.io/npm/v/@candescent/di-typescript-sdk.svg)](https://www.npmjs.com/package/@candescent/di-typescript-sdk)
-[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/@cdx-forge/di-typescript-sdk.svg)](https://www.npmjs.com/package/@cdx-forge/di-typescript-sdk)
+[![OpenAPI spec](https://img.shields.io/badge/OpenAPI-1.6.0-6BA539?logo=openapiinitiative&logoColor=white)](https://github.com/candescent-dev/openapi/tree/v1.6.0)
+[![downloads](https://img.shields.io/npm/dm/@cdx-forge/di-typescript-sdk.svg?label=downloads)](https://www.npmjs.com/package/@cdx-forge/di-typescript-sdk)
+[![node](https://img.shields.io/node/v/@cdx-forge/di-typescript-sdk.svg)](https://www.npmjs.com/package/@cdx-forge/di-typescript-sdk)
 
+Server-side TypeScript SDK for the [Candescent Digital Insight API](https://docs.candescent.com). Covers all API operations with full type safety, automatic OAuth token management, and built-in retry logic.
 
-Server-side TypeScript/Node.js SDK for the [Candescent Digital Insight API](https://docs.candescent.com). Covers all 99 API operations across 12 service areas with full type safety, automatic OAuth token management, and built-in retry logic.
+| Package | Version |
+|---------|---------|
+| This package (`@cdx-forge/di-typescript-sdk`) | **1.0.0** |
+| OpenAPI spec ([`candescent-dev/openapi`](https://github.com/candescent-dev/openapi/tree/v1.6.0)) | **1.6.0** |
 
----
+The npm package version and the OpenAPI specification version are tracked separately. See [Versioning](#versioning) and [CHANGELOG.md](https://github.com/candescent-dev/cdx-typescript-sdk/blob/main/CHANGELOG.md).
 
-## Requirements
+## Overview
 
-- **Node.js 20+**
-- **ESM only** — use `import` syntax. `require()` is not supported (see [Troubleshooting](#commonjs-require-not-working)).
+This SDK is the recommended way for server-side TypeScript and Node.js applications to integrate with the Candescent Digital Insight platform. It wraps the full REST API surface — accounts, transactions, customer management, business banking, alerts, money movement, notifications, disclosures, e-statements, and MX services — behind a single typed client that handles the protocol complexity so your application does not have to.
 
----
+Key things the SDK takes care of on your behalf:
 
-## Installation
+- **OAuth token management** — acquires, caches, and refreshes tokens automatically across two token endpoint families (V1 and V2), and injects the correct `Authorization` header on every request.
+- **Typed models** — every request parameter and response shape is generated from the OpenAPI specification, giving you autocomplete and compile-time safety.
+- **Error hierarchy** — HTTP error codes are mapped to typed exceptions (`NotFoundError`, `RateLimitError`, etc.) so you can catch exactly what you need.
+- **Pagination** — an async-iterable `PageIterator` handles all four pagination patterns used across the API.
+- **Retry with backoff** — transient failures (408, 429, 5xx) are retried automatically with exponential backoff.
 
-```bash
-npm install @candescent/di-typescript-sdk
-```
+The SDK is ESM-only and requires Node.js 20+. For browser or edge runtimes, call the REST API directly using the [Candescent API reference](https://docs.candescent.com).
 
-```bash
-yarn add @candescent/di-typescript-sdk
-```
+## Documentation
+
+See the [Candescent API reference](https://docs.candescent.com) for full endpoint documentation, and the [examples folder](https://github.com/candescent-dev/cdx-typescript-sdk/tree/main/examples/typescript) for runnable code across every service area.
+
+## Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| Node.js | **20+** |
+| Module system | **ESM only** — use `import` syntax. `require()` will throw `ERR_REQUIRE_ESM` (see [Troubleshooting](#troubleshooting)) |
+
+## Installation
 
 ```bash
-pnpm add @candescent/di-typescript-sdk
+npm install @cdx-forge/di-typescript-sdk
+# or
+yarn add @cdx-forge/di-typescript-sdk
+# or
+pnpm add @cdx-forge/di-typescript-sdk
 ```
 
----
+## Usage
 
-## Quick Start
+The client is initialized once and reused across your application. It accepts credentials directly or reads them from environment variables. All service areas are available as properties on the client instance, and every method is fully typed — parameters, responses, and errors.
+
+Configure the client with your credentials from the [Candescent Developer Console](https://docs.candescent.com/guides/getting-started/quickstart/):
 
 ```typescript
-import { CandescentClient, Environment } from "@candescent/di-typescript-sdk";
+import { CandescentClient, Environment } from "@cdx-forge/di-typescript-sdk";
 
 const client = new CandescentClient({
   clientId: process.env.CANDESCENT_CLIENT_ID!,
@@ -49,168 +71,105 @@ console.log(`Found ${accounts.accounts?.length ?? 0} accounts`);
 await client.close();
 ```
 
----
-
-## Authentication
-
-Obtain your **Client ID**, **Client Secret**, and **Institution ID** from the [Candescent Developer Console](https://docs.candescent.com/guides/getting-started/quickstart/). For detailed steps, see the [Quick Start guide](https://docs.candescent.com/guides/getting-started/quickstart/).
-
-### Option 1 — OAuth 2.0 Client Credentials (recommended)
+Or load all credentials from environment variables:
 
 ```typescript
-import { CandescentClient, Environment } from "@candescent/di-typescript-sdk";
-
-const client = new CandescentClient({
-  clientId: "your-client-id",
-  clientSecret: "your-client-secret",
-  institutionId: "your-institution-id",
-  environment: Environment.Production,
-});
+const client = CandescentClient.fromEnv();
 ```
 
-The SDK obtains and caches OAuth tokens automatically, refreshes them before expiry, and injects the correct `Authorization` header on every request. You never handle tokens directly.
+The client is organized by service area. Each property maps to a group of fully typed API operations:
 
-### Option 2 — Environment Variables
+| Property | Service area |
+|----------|-------------|
+| `client.accounts` | Account listing, account details, transactions |
+| `client.customerManagement` | Customer registration, lookup, profile management |
+| `client.authentication` | Token creation and revocation |
+| `client.businessBanking` | Business entitlements, business details |
+| `client.alerts` | Alert configuration, delivery, preferences |
+| `client.moneyMovement` | Payments and transfers |
+| `client.notifications` | Notification channels and subscriptions |
+| `client.disclosures` | Disclosure management |
+| `client.estatements` | E-statement access |
+| `client.mx` | MX financial data services |
 
-```bash
-export CANDESCENT_CLIENT_ID=your-client-id
-export CANDESCENT_CLIENT_SECRET=your-client-secret
-export CANDESCENT_INSTITUTION_ID=your-institution-id
-export CANDESCENT_ENVIRONMENT=production  # or stage (default)
-```
-
-```typescript
-import { CandescentClient } from "@candescent/di-typescript-sdk";
+### Standalone functions
 
-const client = CandescentClient.fromEnv();
-```
-
-### Option 3 — Static Bearer Token
+For serverless environments (e.g. AWS Lambda) where managing a persistent client is impractical, import individual operation functions directly:
 
 ```typescript
-import { CandescentClient } from "@candescent/di-typescript-sdk";
+import { listAccounts, getAccount } from "@cdx-forge/di-typescript-sdk/operations";
 
-const client = new CandescentClient({
-  bearerToken: "your-pre-obtained-jwt",
-  institutionId: "your-institution-id",
-});
+// Reads credentials from process.env.CANDESCENT_*
+const accounts = await listAccounts({ hostUserId: "user-12345" });
+const account  = await getAccount({ accountId: "acc-abc123" });
 ```
 
-### Environment Variables Reference
+## Authentication
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `CANDESCENT_INSTITUTION_ID` | ✅ Always | Your institution identifier |
-| `CANDESCENT_CLIENT_ID` | Yes\* | OAuth 2.0 client ID |
-| `CANDESCENT_CLIENT_SECRET` | Yes\* | OAuth 2.0 client secret |
-| `CANDESCENT_BEARER_TOKEN` | Yes\* | Pre-obtained JWT (skips OAuth flow) |
-| `CANDESCENT_ENVIRONMENT` | No | `stage` (default) or `production` |
-| `CANDESCENT_USERNAME` | No | Password grant — user username |
-| `CANDESCENT_PASSWORD` | No | Password grant — user password |
+The package needs to be configured with your **Client ID**, **Client Secret**, and **Institution ID**, available in the [Candescent Developer Console](https://docs.candescent.com/guides/getting-started/quickstart/).
 
-\*Provide either `CANDESCENT_BEARER_TOKEN` **or** `CANDESCENT_CLIENT_ID` + `CANDESCENT_CLIENT_SECRET`.
+The SDK obtains and caches OAuth tokens automatically, refreshes them before expiry, and injects the correct `Authorization` header on every request — you never manage tokens directly.
 
-> **Note:** Node.js does not automatically load `.env` files. Either run `source .env` before your script, or use a library like [`dotenv`](https://www.npmjs.com/package/dotenv) to load them at runtime.
+### OAuth V1 and V2
 
----
-
-## Usage
+The Candescent API uses two distinct OAuth token endpoint families that exist for historical reasons. Newer endpoints use the V2 standard JSON flow; a subset of legacy endpoints require the older V1 flow (which may return XML). The SDK handles both transparently:
 
-The client is organized by API service area. Each property on `client` maps to one group of operations.
+| | V1 (Legacy) | V2 (Current) |
+|---|---|---|
+| **Token endpoint** | `POST /v1/oauth/token` | `POST /oauth2/v1/token` |
+| **Token lifetime** | ~30 minutes | ~1 hour |
+| **Response format** | XML or JSON | JSON |
+| **Typical operations** | Customer registration, account listing via `/bankingservices/`, notification channels | Accounts, alerts, MX, money movement, disclosures, e-statements |
 
-### Accounts
+The SDK inspects the request URL path at call time and selects the correct token provider automatically — V1 for paths containing `/bankingservices/`, `/registration/`, `/destinations/`, `/subscriptions/`, or `/send-event/`, and V2 for everything else. Tokens are cached and reused for their lifetime, then refreshed proactively before expiry. XML token responses from V1 endpoints are parsed internally; you always receive typed TypeScript objects regardless of what the wire format was.
 
-```typescript
-// List accounts for a user
-const accounts = await client.accounts.list({ hostUserId: "user-12345" });
+No configuration is needed beyond your client credentials. If you already have a pre-obtained JWT, you can pass it directly and skip the OAuth flow entirely (see [Using a static bearer token](#using-a-static-bearer-token) below).
 
-// Get a specific account
-const account = await client.accounts.get({ accountId: "acc-abc123" });
+### Using environment variables
 
-// List transactions for an account
-const txns = await client.accounts.listTransactions({
-  accountId: "acc-abc123",
-  hostUserId: "user-12345",
-});
+```bash
+export CANDESCENT_CLIENT_ID=your-client-id
+export CANDESCENT_CLIENT_SECRET=your-client-secret
+export CANDESCENT_INSTITUTION_ID=your-institution-id
+export CANDESCENT_ENVIRONMENT=production  # or stage (default)
 ```
 
-### Customer Management
-
 ```typescript
-import type { RegisterCustomerRequest } from "@candescent/di-typescript-sdk";
-
-// Register a new customer
-const response = await client.customerManagement.register({
-  diFiid: "05523",
-  body: {
-    fICustomer: {
-      id: { value: "0", type: "GUID" },
-      fiId: { value: "05523" },
-      memberNumber: "123456789",
-      person: {
-        personName: { firstName: "Jane", lastName: "Smith" },
-        contactInfo: { emailAddress: "jane.smith@example.com" },
-      },
-      userType: "PRIMARY",
-    },
-  },
-});
-const customerId = response.fICustomer?.id?.value;
-
-// Look up customer information
-const info = await client.customerManagement.getInformation({
-  customerId,
-});
+const client = CandescentClient.fromEnv();
 ```
 
-### Authentication
+> Scripts do not load `.env` files automatically. Run `source .env` first, or use [`dotenv`](https://www.npmjs.com/package/dotenv).
 
-```typescript
-// Create an OAuth token
-const token = await client.authentication.createToken({
-  grantType: "client_credentials",
-});
-
-// Revoke a token on logout
-await client.authentication.revokeToken({
-  token: token.accessToken,
-});
-```
+### Using a static bearer token
 
-### Business Banking
+If you have a pre-obtained JWT, pass it directly — the OAuth flow is skipped:
 
 ```typescript
-// Get business entitlements
-const entitlements = await client.businessBanking.getBusinessEntitlements({
-  businessId: "biz-456",
-});
+import { CandescentClient } from "@cdx-forge/di-typescript-sdk";
 
-// Look up business details by ID
-const details = await client.businessBanking.getBusinessDetails({
-  searchType: "BUSINESS_ID",
-  searchValue: "biz-456",
-  includeTins: true,
-  includeUsers: true,
+const client = new CandescentClient({
+  bearerToken: "your-pre-obtained-jwt",
+  institutionId: "your-institution-id",
 });
 ```
 
-### Standalone Functions (Serverless / Lambda)
-
-For environments where managing a client lifecycle is inconvenient:
-
-```typescript
-import { listAccounts, getAccount, listTransactions } from "@candescent/di-typescript-sdk/operations";
+### Environment variables reference
 
-// Reads credentials from process.env.CANDESCENT_*
-const accounts = await listAccounts({ hostUserId: "user-12345" });
-const account = await getAccount({ accountId: "acc-abc123" });
-```
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CANDESCENT_INSTITUTION_ID` | Always | Your institution identifier |
+| `CANDESCENT_CLIENT_ID` | Yes* | OAuth 2.0 client ID |
+| `CANDESCENT_CLIENT_SECRET` | Yes* | OAuth 2.0 client secret |
+| `CANDESCENT_BEARER_TOKEN` | Yes* | Pre-obtained JWT (skips OAuth flow) |
+| `CANDESCENT_ENVIRONMENT` | No | `stage` (default) or `production` |
+| `CANDESCENT_USERNAME` | No | Password grant username |
+| `CANDESCENT_PASSWORD` | No | Password grant password |
 
----
+\*Provide either `CANDESCENT_BEARER_TOKEN` **or** `CANDESCENT_CLIENT_ID` + `CANDESCENT_CLIENT_SECRET`.
 
-## Error Handling
+## Error handling
 
-All API errors are thrown as typed exceptions. Catch the base `ApiError` or any specific subclass:
+Every non-2xx response is surfaced as a typed exception rather than a generic `Error`, so you can handle specific failure modes (not found, rate limited, unauthenticated) without parsing status codes yourself. Catch the base `ApiError` for a catch-all, or catch specific subclasses for targeted handling:
 
 ```typescript
 import {
@@ -218,8 +177,7 @@ import {
   AuthenticationError,
   NotFoundError,
   RateLimitError,
-  BadRequestError,
-} from "@candescent/di-typescript-sdk";
+} from "@cdx-forge/di-typescript-sdk";
 
 try {
   const account = await client.accounts.get({ accountId: "acc-not-found" });
@@ -233,15 +191,13 @@ try {
   } else if (error instanceof ApiError) {
     console.error(`API error ${error.statusCode}:`, error.message);
   } else {
-    throw error; // re-throw unexpected errors
+    throw error;
   }
 }
 ```
 
-### Error Hierarchy
-
-| HTTP Status | Exception Class |
-|-------------|----------------|
+| HTTP status | Exception |
+|-------------|-----------|
 | Any non-2xx | `ApiError` (base) |
 | 400 | `BadRequestError` |
 | 401 | `AuthenticationError` |
@@ -252,16 +208,13 @@ try {
 | 429 | `RateLimitError` |
 | 5xx | `InternalServerError` |
 
----
-
 ## Pagination
 
-Endpoints that return lists support `PageIterator` — an async iterable that handles fetching subsequent pages automatically:
+The Candescent API uses several different pagination styles across its endpoints (offset-based, cursor-based). `PageIterator` abstracts over all of them with a single async iterable interface — you iterate over items and the SDK fetches the next page when needed, without you tracking page numbers or tokens:
 
 ```typescript
-import { PageIterator } from "@candescent/di-typescript-sdk";
+import { PageIterator } from "@cdx-forge/di-typescript-sdk";
 
-// Iterate all accounts across all pages (25 per page by default)
 for await (const account of new PageIterator(
   (req) => client.accounts.list({ hostUserId: "user-12345", ...req }),
   { page: 0, size: 50 },
@@ -270,11 +223,9 @@ for await (const account of new PageIterator(
 }
 ```
 
-Or collect all results into an array:
+To collect all results into an array:
 
 ```typescript
-import { PageIterator } from "@candescent/di-typescript-sdk";
-
 const allAccounts = [];
 for await (const account of new PageIterator(
   (req) => client.accounts.list({ hostUserId: "user-12345", ...req }),
@@ -283,27 +234,25 @@ for await (const account of new PageIterator(
 }
 ```
 
----
-
-## Retry Behavior
+## Retry behavior
 
-The SDK automatically retries on transient failures with exponential backoff:
+The SDK automatically 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 |
+| Retried on | Max retries | Initial delay | Max delay |
+|------------|-------------|---------------|-----------|
+| 408, 429, 500, 502, 503, 504 | 2 (3 total attempts) | 500 ms | 30 s |
 
-`RateLimitError` is thrown only after all retries are exhausted. The `retryAfter` property contains the value from the `Retry-After` response header.
+`RateLimitError` is thrown only after all retries are exhausted. Check `error.retryAfter` for the value from the `Retry-After` response header.
 
----
+## Framework integration
 
-## Framework Integration
+The client is stateful (it holds a token cache) and safe to instantiate once at application startup and share across requests. For serverless functions where a persistent instance is impractical, use the standalone functions export instead (see [Standalone functions](#standalone-functions) above, and the AWS Lambda example below).
 
 ### Express / Fastify
 
 ```typescript
 import express from "express";
-import { CandescentClient } from "@candescent/di-typescript-sdk";
+import { CandescentClient } from "@cdx-forge/di-typescript-sdk";
 
 const app = express();
 const client = CandescentClient.fromEnv();
@@ -316,8 +265,10 @@ app.get("/accounts/:userId", async (req, res) => {
 
 ### AWS Lambda
 
+Use the standalone functions export to avoid managing client lifecycle across invocations:
+
 ```typescript
-import { listAccounts } from "@candescent/di-typescript-sdk/operations";
+import { listAccounts } from "@cdx-forge/di-typescript-sdk/operations";
 
 export const handler = async (event: { userId: string }) => {
   const accounts = await listAccounts({ hostUserId: event.userId });
@@ -325,21 +276,34 @@ export const handler = async (event: { userId: string }) => {
 };
 ```
 
-### Lifecycle Management
+### Lifecycle management
 
-```typescript
-const client = CandescentClient.fromEnv();
+Call `client.close()` on shutdown to revoke cached tokens:
 
-// On shutdown — revokes cached tokens
+```typescript
 await client.close();
 ```
 
----
+## Hand-written wrapper layer
 
-## Configuration Reference
+The SDK is built on top of auto-generated OpenAPI client stubs, but the code your application actually interacts with is entirely hand-written and maintained separately from the generated output. The durable layer lives in [`src/`](https://github.com/candescent-dev/cdx-typescript-sdk/tree/main/src) and consists of:
+
+| File | What it does |
+|------|-------------|
+| `client.ts` | `CandescentClient` facade — mounts all service areas and runs the middleware pipeline |
+| `auth.ts` | V1 and V2 token providers — token acquisition, caching, pre-expiry refresh, and per-request routing |
+| `transport.ts` | Middleware — injects auth and tracing headers; converts XML responses to JSON before deserialization |
+| `errors.ts` | Maps HTTP status codes to typed `ApiError` subclasses |
+| `pagination.ts` | `PageIterator` — async iterable supporting offset and cursor pagination patterns |
+| `retry.ts` | Exponential backoff with jitter for transient failures |
+| `operations.ts` | Standalone functions for serverless environments |
+
+This layer is what survives when the SDK is regenerated from a new OpenAPI spec. If you want to understand exactly how a request flows — from your call site through auth, headers, retries, and back — the source files above are the place to look. You can browse them directly on [GitHub](https://github.com/candescent-dev/cdx-typescript-sdk/tree/main/src).
+
+## Configuration
 
 ```typescript
-import { CandescentClient, Environment } from "@candescent/di-typescript-sdk";
+import { CandescentClient, Environment } from "@cdx-forge/di-typescript-sdk";
 
 const client = new CandescentClient({
   // --- Required (one of the two auth methods) ---
@@ -347,93 +311,71 @@ const client = new CandescentClient({
   clientSecret: "...",        // OAuth client secret
   institutionId: "...",       // Your institution identifier
 
-  // --- OR use a static token ---
-  bearerToken: "...",         // Pre-obtained JWT
+  // OR use a static token instead of client credentials:
+  bearerToken: "...",
 
-  // --- Optional ---
-  environment: Environment.Production,  // Environment.Stage (default) | Environment.Production
+  environment: Environment.Production,  // Environment.Stage (default)
   baseUrl: "https://custom.api.host",   // Override base URL (advanced)
 });
 ```
 
----
-
 ## Examples
 
-The [`examples/`](./examples/typescript/) directory contains 21 runnable scripts covering all API operations:
-
-| Example File | What It Covers |
-|---|---|
-| `accounts.ts` | List accounts, retrieve account details, banking images |
-| `transactions.ts` | Transaction history, filtering |
-| `authentication.ts` | OAuth token lifecycle |
-| `authentication-lifecycle.ts` | Full token create / revoke flow |
-| `customer-management.ts` | Contact methods, password reset, unlock |
-| `register-and-lookup.ts` | Customer registration + 3-way lookup |
-| `disclosures.ts` | Institution and user disclosures |
-| `estatements.ts` | E-statement delivery preferences |
-| `alert-configuration.ts` | Alert templates and types |
-| `alert-preferences.ts` | User and institution alert preferences |
-| `alert-delivery.ts` | Alert history and content |
-| `notification-channels.ts` | Subscription management |
-| `business-registration.ts` | Business banking registration |
-| `business-entitlements.ts` | Business and user entitlements |
-| `business-payments.ts` | ACH and wire payments |
-| `customer-campaigns.ts` | Experience groups and campaigns |
-| `money-movement.ts` | Recipients and transfers |
-| `mx-service.ts` | MX integration — widget, users, logs |
-| `pagination.ts` | PageIterator across all pagination patterns |
-| `error-handling.ts` | Full error hierarchy showcase |
-| `user-status.ts` | User authentication status |
-
-**To run an example:**
+The [`examples/typescript/`](https://github.com/candescent-dev/cdx-typescript-sdk/tree/main/examples/typescript) folder on GitHub contains runnable scripts that show how to consume the SDK end-to-end across every service area. These are the best starting point for understanding real usage patterns — each script is a self-contained illustration of how to initialise the client, make calls, handle responses, and clean up.
 
-```bash
-# 1. Copy and fill in your credentials
-cp .env.example .env
+Coverage includes: accounts, transactions, authentication and token lifecycle, customer registration and lookup, business banking (registration, entitlements, payments), alerts (configuration, preferences, delivery), money movement, MX integration, notifications, disclosures, e-statements, pagination with `PageIterator`, and the full error handling hierarchy.
 
-# 2. Install dependencies
-npm install
+Key characteristics of the example scripts:
 
-# 3. Run any example
-node --experimental-strip-types examples/typescript/accounts.ts
-```
+- **Each script is independent.** You can run a single example to explore one service area without needing to run them all.
+- **Error handling is a separate script** (`error-handling.ts`) that exercises intentional failures and is excluded from the batch runner by design.
+- **The batch runner** (`node scripts/run-all-typescript-examples.mjs`) runs all examples in sequence and writes a log, which is useful for verifying your credentials work across the full API surface.
 
----
+See the [Examples README](https://github.com/candescent-dev/cdx-typescript-sdk/blob/main/README.md) for environment setup, how to run individual scripts, and the full list of example files with what each one covers.
 
 ## Troubleshooting
 
 **CommonJS `require()` not working**
 
-This package is ESM-only. Your project must use `"type": "module"` in `package.json` or use `.mjs` file extensions. `require('@candescent/di-typescript-sdk')` will throw `ERR_REQUIRE_ESM`.
+This package is ESM-only. Your project must use `"type": "module"` in `package.json` or use `.mjs` file extensions. `require('@cdx-forge/di-typescript-sdk')` will throw `ERR_REQUIRE_ESM`.
 
-**`Cannot find module '@candescent/di-typescript-sdk'`**
+**`Cannot find module '@cdx-forge/di-typescript-sdk'`**
 
-Run `npm install @candescent/di-typescript-sdk` and confirm the package is listed in your `package.json` dependencies.
+Run `npm install @cdx-forge/di-typescript-sdk` and confirm the package is listed in your `package.json` dependencies.
 
 **Authentication errors (401)**
 
-- Verify `CANDESCENT_CLIENT_ID` and `CANDESCENT_CLIENT_SECRET` are correct
-- Confirm `CANDESCENT_INSTITUTION_ID` matches the credentials issued to you
-- For staging environments, set `CANDESCENT_ENVIRONMENT=stage`
+- Verify `CANDESCENT_CLIENT_ID` and `CANDESCENT_CLIENT_SECRET` are correct.
+- Confirm `CANDESCENT_INSTITUTION_ID` matches the credentials issued to you.
+- For staging environments, ensure `CANDESCENT_ENVIRONMENT=stage`.
 
 **`"Parameters hostUserId and loginId are mutually exclusive"`**
 
-Pass only one user identifier per request — either `hostUserId` or `loginId`, not both.
+Pass only one user identifier per request — `hostUserId` or `loginId`, not both.
+
+## Versioning
+
+This SDK follows [semantic versioning](https://semver.org/) independently from the Candescent DI OpenAPI specification. The SDK version and spec version are tracked separately.
 
-**`"Module not found"` when running examples**
+| Package | Version |
+|---------|---------|
+| SDK (`@cdx-forge/di-typescript-sdk`) | **1.0.0** |
+| OpenAPI spec ([`candescent-dev/openapi`](https://github.com/candescent-dev/openapi/tree/v1.6.0)) | **1.6.0** |
 
-Run `npm install` in the repo root or `examples/` directory to install dependencies.
+Each SDK release is pinned to a specific spec version. See [CHANGELOG.md](https://github.com/candescent-dev/cdx-typescript-sdk/blob/main/CHANGELOG.md) for the spec version used in each release.
 
 ---
 
-## Versioning
+## License
+
+Copyright © Candescent. All rights reserved. The Digital Insight TypeScript SDK is proprietary software.
 
-This SDK follows [semantic versioning](https://semver.org/) independently from the Candescent API spec version. The API specification version (currently 1.4.0) and the SDK package version (starting at 1.0.0) are tracked separately. The [release notes](https://github.com/dfh-digital-insight/cdx-di-typescript-sdk/releases) document which API spec version each SDK release was generated from.
+See [`LICENSE`](https://github.com/candescent-dev/cdx-typescript-sdk/blob/main/LICENSE) for the proprietary terms.
 
 ---
 
 ## Support
 
-- **API Reference:** [docs.candescent.com](https://docs.candescent.com)
-- **Issues:** [GitHub Issues](https://github.com/dfh-digital-insight/cdx-di-typescript-sdk/issues)
+- **API reference:** [docs.candescent.com](https://docs.candescent.com)
+- **Issues:** [GitHub Issues](https://github.com/candescent-dev/cdx-typescript-sdk/issues)
+- **License:** Copyright © Candescent. Proprietary — see [`LICENSE`](https://github.com/candescent-dev/cdx-typescript-sdk/blob/main/LICENSE).