Benefits Admin Policy SDK (TypeScript)

TypeScript SDK for interacting with the Benefits Admin Policy service.

Features

• Retrieve policy versions from S3
• Type-safe policy models with hand-rolled TypeScript types
• JSON Schema exports for runtime validation
• Support for policy requirements, benefits, and exceptions

Prerequisites

• Node.js >= 22.14.0 (see .nvmrc in repo root; use nvm install && nvm use to switch)
• Yarn 4 (corepack enable will install it automatically)

For full environment setup, see docs/CONTRIBUTING.md.

Installation

Stable Release

npm install @guildeducationinc/benefits-admin-policy-sdk
# or
yarn add @guildeducationinc/benefits-admin-policy-sdk

Canary Release (Pre-release for Testing)

To test changes from a pull request before they're merged:

# Install the latest canary version
npm install @guildeducationinc/benefits-admin-policy-sdk@canary

# Or install a specific canary version
npm install @guildeducationinc/[email protected]

Note: Canary releases are pre-release versions published from pull requests for testing purposes. They should not be used in production.

Environment Variables

The STAGE environment variable must be set at runtime. It controls which S3 bucket the SDK reads from.

| Value | Target bucket | | ----- | ------------- | | dev or development | benefits-admin-policy-versions-dev | | staging or stage | benefits-admin-policy-versions-staging | | prod or production | benefits-admin-policy-versions-prod | | test, local, or any unknown value | benefits-admin-policy-versions-dev |

export STAGE=dev

STAGE is not required when an explicit bucketName is passed to PolicyClientConfig. See docs/POLICY_CLIENT.md for the full STAGE and SANDBOX_PREFIX reference.

Usage

import { PolicyClient, PolicyVersion } from '@guildeducationinc/benefits-admin-policy-sdk';

// Create a client instance
const client = new PolicyClient();

// Retrieve a policy version by URI
const policyVersion: PolicyVersion = await client.retrievePolicyVersion('policies/policy123/version456.json');

// Access typed policy data
const { name, populations, benefits } = policyVersion;

Runtime Validation with JSON Schema

The SDK exports JSON schemas that can be used for runtime validation:

import { policySchema, policyVersionSchema, policyOverrideSchema } from '@guildeducationinc/benefits-admin-policy-sdk';
import Ajv from 'ajv';

const ajv = new Ajv();
const validatePolicyVersion = ajv.compile(policyVersionSchema);

if (!validatePolicyVersion(data)) {
  throw new Error('Invalid policy version data');
}

Available schemas:

• policySchema - Validates Policy documents
• policyVersionSchema - Validates PolicyVersion documents
• policyOverrideSchema - Validates PolicyOverride documents

Error Handling

All SDK errors extend PolicySdkError. Import specific error classes to handle known failure cases:

import {
  PolicyClient,
  PolicySdkError,
  PolicyVersionNotFoundError,
  PolicyVersionDeserializationError,
  PolicySdkConfigurationError,
  PolicySdkAwsError,
  PolicySdkSsmParameterAccessError,
} from '@guildeducationinc/benefits-admin-policy-sdk';

const client = new PolicyClient();

try {
  const policyVersion = await client.retrievePolicyVersion('policies/policy123/version456.json');
} catch (error) {
  if (error instanceof PolicyVersionNotFoundError) {
    // Policy version does not exist at the given URI
  } else if (error instanceof PolicyVersionDeserializationError) {
    // Retrieved JSON could not be parsed into a PolicyVersion
  } else if (error instanceof PolicySdkConfigurationError) {
    // STAGE env var is missing, or client config is invalid
  } else if (error instanceof PolicySdkAwsError) {
    // An underlying AWS operation (S3 or STS) failed
  } else if (error instanceof PolicySdkSsmParameterAccessError) {
    // IAM permission denied when reading an SSM parameter
  } else if (error instanceof PolicySdkError) {
    // Catch-all for any other SDK error
    throw error;
  }
}

| Error class | When it is thrown | | --- | --- | | PolicySdkError | Base class — all SDK errors extend this | | PolicyVersionNotFoundError | Policy version not found at the requested URI | | PolicyVersionDeserializationError | Retrieved JSON cannot be parsed into a PolicyVersion | | PolicyOverrideDocumentNotFoundError | Policy override document not found at the requested URI | | PolicyOverrideDocumentDeserializationError | Retrieved JSON cannot be parsed into a PolicyOverrideDocument | | PolicySdkAwsError | An underlying AWS operation (S3 or STS) failed | | PolicySdkConfigurationError | STAGE is not set, or client config is invalid | | PolicySdkSsmParameterAccessError | IAM permission denied when reading an SSM parameter |

Development

Setup

yarn install

Run Tests

yarn test
yarn test:coverage   # with coverage report

Build

yarn build

Linting

yarn lint        # Check for issues
yarn lint:fix    # Auto-fix issues

Formatting

yarn format:check   # Check formatting
yarn format         # Auto-fix formatting

Types

This SDK uses hand-rolled TypeScript types derived from JSON Schema definitions. The types are located in src/models/ and provide full type safety for policy domain models.

Documentation

• Authentication — AWS IAM setup for consuming services
• Client Reference — Full PolicyClient API, config options, and environment variables
• Design Principles — SDK design guidelines
• Contributing — Development environment setup and contribution guidelines