Skip to main content

SDK Reference

SDK Packages​

The CDX Extensibility SDK is split into three packages, all installed automatically via npm install.

Core SDK — @cdx-extensions/di-sdk​

This is the main entry point. It is the platform-agnostic orchestration layer that your widget imports and uses directly. It detects the runtime environment and delegates every method call to the correct platform implementation.

How it works:

  • It is a singleton (PlatformSDK.getInstance()). The same object is returned regardless of how many times getInstance is invoked.
  • All utility calls (useUserContext, useBranding, getHttpClient) are delegated to the active platform — the harness locally, or the real platform implementation in production.

Usage in a widget:

import { PlatformSDK } from '@cdx-extensions/di-sdk';

const sdk = PlatformSDK.getInstance();
const { data: user } = sdk.useUserContext();
const { theme } = sdk.useBranding('branding-1');
const httpClient = sdk.getHttpClient();
tip

Always import from @cdx-extensions/di-sdk. Do not import from di-sdk-web or di-sdk-mobile directly — the main SDK selects the correct implementation at runtime.

Platform Harness​

The harness is the mock/harness implementation of the platform SDK for local development. It provides everything a widget needs to run locally without the real platform present.

Package: @cdx-extensions/di-sdk-web

What it provides locally:

  • Mock user context data (from mocks/userContext.json)
  • Mock API responses with simulated delays (from mocks/apiResponses.json)
  • Mock branding/theme data (from mocks/branding.json)
    • Locally, global-level branding is applied on the OLB regardless of changes at the widget level.
    • On the OLB, global branding and theming are applied automatically.
  • A mock HTTP client backed by axios-mock-adapter
info

On the public npm registry, this package is the harness. On internal JFrog, the same package name resolves to the real OLB implementation. Your widget code works in both environments — only the registry determines which version is installed.

Type Definitions — @cdx-extensions/di-sdk-types​

Shared TypeScript interfaces used across all SDK packages and your widget code. This package has no runtime logic — types only. The type definitions are identical across web and mobile.

Key types:

TypeDescription
UserContextShape of data returned by useUserContext()
PlatformInterface that both web and mobile platforms implement
HttpClientInterface for getHttpClient() — methods: get, post, put, patch, delete
HttpResponse<T>Wrapper around API responses: data, status, statusText, headers
ExtensibilityConfigPlatform config: environment, apiBaseUrl, features, customSettings
Response<T>Wrapper returned by React hooks: data, isLoading, hasError, error

Usage:

import { UserContext, HttpClient, ExtensibilityConfig } from '@cdx-extensions/di-sdk-types';

SDK Method Reference​

useUserContext()​

Returns the logged-in user's context — injected by the platform when embedded.

const sdk = PlatformSDK.getInstance();
const { data: user, isLoading, hasError } = sdk.useUserContext();

Shape of data (UserContext):

FieldTypeDescription
guidstringPlatform-wide unique user identifier
firstNamestringUser's first name
lastNamestringUser's last name
fullNamestringFull display name
userNamestringLogin username
emailstringUser email
institutionUserIdstringInstitution-specific user ID
institutionUserRolestringRole within the institution (e.g. user, admin)
institutionUserTypestringAccount tier (e.g. premium, retail)
institutionIdstringThe institution identifier

Locally: Data is read from node_modules/@cdx-extensions/di-sdk-web/dist/mocks/userContext.json.

On the OLB: The real platform injects the actual logged-in user's data. The widget code does not change — only the source of data changes.

useBranding(brandingId?)​

Returns branding tokens for styling your user interface. The return type differs by platform.

Returns a MUI theme object built from the platform's branding configuration. Pass it to MUI ThemeProvider to apply the host platform's visual style.

const { theme } = sdk.useBranding('branding-1');

return (
  <ThemeProvider theme={theme}>
    <YourComponent />
  </ThemeProvider>
);

Locally: Theme is built from the mock branding JSON files under node_modules/@cdx-extensions/di-sdk-web/dist/mocks/. Five commonly used branding variants are included (branding-1 through branding-5).

On the OLB: The platform's real branding service provides the live theme for the institution. Global-level theming is applied automatically, so widget-level theming will be overridden on the OLB.

getHttpClient()​

Returns an HTTP client for making API calls. This method has the most significant difference between local and production environments.

warning

Always use sdk.getHttpClient() for all API calls in your widget. Never use raw fetch() or import Axios directly. The HTTP client handles auth, mocking, and platform security automatically.

Behavior comparison

Local (harness)On OLB (prod)
ReturnsAxios instance backed by axios-mock-adapterReal Axios instance managed by the OLB platform
AuthNo real auth; optionally uses a static access_token stringFull OIDC flow — token is injected automatically by the platform
API callsIntercepted and served from apiResponses.jsonReal HTTP calls to your third-party API endpoints
Requires whitelistingNoYes — third-party domains must be manually whitelisted

Local: mock mode (default)​

By default, all API calls are intercepted and served from mock data.

File: node_modules/@cdx-extensions/di-sdk-web/dist/httpClient.js

The key flag:

const isMock = true;

When isMock = true:

  • Every httpClient.get(url) / post / put / patch / delete is intercepted.
  • The response comes from mocks/apiResponses.json with a simulated delay (default: 500ms–2000ms).
  • No real network call is made.
  • Responses are logged in the browser console with prefix [WEB-HARNESS-HTTP].

To add a new mock endpoint locally, add an entry to apiResponses.json:

{
  "url": "/api/your-endpoint",
  "method": "GET",
  "status": 200,
  "delay": { "min": 300, "max": 800 },
  "data": {
    "yourField": "yourValue"
  }
}

Local: real HTTP mode​

To call a real external URL during local development (e.g. a sandbox API):

  1. Open node_modules/@cdx-extensions/di-sdk-web/dist/httpClient.js

    Change line 8 from:

    const isMock = true;

    to:

    const isMock = false;

  2. Optionally set your access token on line 10:

    const access_token = 'your-real-token-here';

  3. Update the API base URL in your widget's environment file:

    widgets/web/<your-widget>/src/environments/environment.ts

  4. Set apiUrl to your real backend base URL.

When isMock = false, getHttpClient() returns a real Axios instance with a Bearer authorization header injected on every request. If you need to disable Bearer token authentication, remove the following line from getHttpClient():

request.headers['Authorization'] = `Bearer ${access_token}`;

File location: node_modules/@cdx-extensions/di-sdk-web/dist/httpClient.js

warning

Changes to node_modules/ are not committed to source control and will be overwritten by npm install. This is only for local testing sessions.

API configuration​

A common pattern for managing API endpoints is a config.ts file. For a working example, see the investment-portfolio reference widget.

export const config = {
  baseUrl: 'https://real-api-server.com',
  apiPath: '/endpoint',
};

Making API calls​

Use the HTTP client from the SDK to make requests:

import { useCallback, useMemo } from 'react';
import { PlatformSDK } from '@cdx-extensions/di-sdk';
import { config } from '../config';

export function usePortfolioData() {
  const sdk = useMemo(() => PlatformSDK.getInstance(), []);

  const fetchData = useCallback(async () => {
    const client = sdk.getHttpClient();
    const url = `${config.baseUrl}${config.apiPath}`;
    const response = await client.get(url);
    return response.data;
  }, [sdk]);

  // ... state management and error handling
}

The HttpClient interface provides the following methods:

MethodSignature
getget<T>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>>
postpost<T>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<HttpResponse<T>>
putput<T>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<HttpResponse<T>>
patchpatch<T>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<HttpResponse<T>>
deletedelete<T>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>>

Next Steps​