Skip to main content

Framework Integration

Patterns for using @cdx-forge/di-typescript-sdk in long-running servers and serverless functions:

Express / Fastify​

Create one CandescentClient at process startup and reuse it across requests:

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

const app = express();
const client = CandescentClient.fromEnv();

app.get("/accounts/:userId", async (req, res) => {
  const accounts = await client.accounts.list({ hostUserId: req.params.userId });
  res.json(accounts);
});

const server = app.listen(3000);

process.on("SIGTERM", async () => {
  await client.close();
  server.close();
});

The SDK caches OAuth tokens internally, so a singleton client is safe for concurrent requests in a single Node process.

AWS Lambda​

For short-lived handlers, use standalone operations from @cdx-forge/di-typescript-sdk/operations so you do not manage the client lifecycle in every invocation:

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

export const handler = async (event: { userId: string }) => {
  const accounts = await listAccounts({ hostUserId: event.userId });
  return { statusCode: 200, body: JSON.stringify(accounts) };
};

Set CANDESCENT_CLIENT_ID, CANDESCENT_CLIENT_SECRET, CANDESCENT_INSTITUTION_ID, and CANDESCENT_ENVIRONMENT in the Lambda environment configuration (or AWS Secrets Manager).

For Lambdas that make many calls per invocation, a module-level CandescentClient singleton is also acceptable — reuse the client across warm starts and call close() (only if the runtime supports graceful shutdown hooks).

Lifecycle guidelines​

PatternWhen to use
Singleton CandescentClientExpress, Fastify, long-running workers
/operations importsLambda, one-off CLI scripts
await client.close()Process shutdown, test teardown

Production credentials​

Do not commit .env files or ship secrets in source control.

  • Local development — .env file or shell exports (see Examples)
  • Deployed environments — environment variables, AWS Secrets Manager, Azure Key Vault, or your platform's secret store
  • Developer Console — rotate Client ID / Secret if credentials are exposed

Obtain credentials via the Getting Started quickstart guide.