TypeScript SDK Guide (@aptia/one-sdk)

The TypeScript client SDK provides fully typed models, interfaces, and API classes for Node.js (18+) and modern browser applications using Axios.

---

Installation

Via Package Manager

npm install @aptia/one-sdk axios
# or
yarn add @aptia/one-sdk axios

From Downloaded Bundle

Download the bundle from the Download Center, extract it to your project, and install locally:

npm install ./path-to/typescript-sdk

---

Architecture Note: Token Exchange

No Built-In OAuth Token Exchange

The generated @aptia/one-sdk library is an API client that requires a pre-acquired Bearer access token. It does not exchange client credentials automatically. You must retrieve a token from AWS Cognito and supply it to the Configuration object.

---

Complete Executable Example

Here is a full example illustrating token acquisition, client initialization, and participant retrieval:

import axios from 'axios';
import {
  Configuration,
  ParticipantsApi,
  EnrollmentsApi,
} from '@aptia/one-sdk';

interface TokenResponse {
  access_token: string;
  expires_in: number;
  token_type: string;
}

// 1. Helper to retrieve OAuth 2.0 access token from Cognito
async function fetchCognitoToken(
  authUrl: string,
  clientId: string,
  clientSecret: string
): Promise<string> {
  const params = new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: clientId,
    client_secret: clientSecret,
    scope: 'aptia/participants.read aptia/enrollments.read',
  });

  const response = await axios.post<TokenResponse>(
    `${authUrl}/oauth2/token`,
    params.toString(),
    {
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
    }
  );

  return response.data.access_token;
}

// 2. Main workflow using the typed SDK
async function main() {
  const isSandbox = true;
  const baseUrl = isSandbox
    ? 'https://api.development.aptiaone.com'
    : 'https://api.development.aptiaone.com';
  const authUrl = isSandbox
    ? 'https://auth-api-development-us-east-1.auth.us-east-1.amazoncognito.com'
    : 'https://auth-api-development-us-east-1.auth.us-east-1.amazoncognito.com';

  const clientId = process.env.APTIA_CLIENT_ID || 'your-client-id';
  const clientSecret = process.env.APTIA_CLIENT_SECRET || 'your-client-secret';
  const tenantId = 'tenant-001';

  try {
    // Step A: Acquire OAuth 2.0 Bearer Token
    const accessToken = await fetchCognitoToken(authUrl, clientId, clientSecret);

    // Step B: Configure SDK with Base URL and Access Token
    const sdkConfig = new Configuration({
      basePath: baseUrl,
      accessToken: accessToken,
      baseOptions: {
        headers: {
          'X-Aptia-Tenant-Id': tenantId,
          'X-Correlation-Id': crypto.randomUUID(),
        },
      },
    });

    // Step C: Initialize Typed API Controller
    const participantsApi = new ParticipantsApi(sdkConfig);

    // Step D: Execute API Operation
    const response = await participantsApi.listParticipants(
      1,    // pageNumber
      10,   // pageSize
      undefined, // employmentStatus
      'Doe'      // search term
    );

    console.log(`Found ${response.data.totalCount} participants:`);
    response.data.items?.forEach((p) => {
      console.log(`- ${p.firstName} ${p.lastName} (ID: ${p.id}, Status: ${p.employmentStatus})`);
    });
  } catch (error: any) {
    if (error.response) {
      console.error('API Error Response:', error.response.status, error.response.data);
    } else {
      console.error('Network or Runtime Error:', error.message);
    }
  }
}

main();