@guildeducationinc/benefits-admin-policy-sdk 1.1.0

package/README.md

@@ -0,0 +1,78 @@
+# 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
+
+## Installation
+
+```bash
+yarn install
+```
+
+## Usage
+
+```typescript
+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:
+
+```typescript
+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
+
+## Development
+
+### Setup
+
+```bash
+yarn install
+```
+
+### Run Tests
+
+```bash
+yarn test
+```
+
+### Linting
+
+```bash
+yarn lint        # Check for issues
+yarn lint:fix    # Auto-fix issues
+```
+
+## Types
+
+This SDK uses hand-rolled TypeScript types derived from JSON Schema definitions. The types are located in [src/models/](src/models/) and provide full type safety for policy domain models.

package/dist/adapters/index.d.ts

@@ -0,0 +1,3 @@
+export { S3Adapter } from './s3-adapter';
+export type { S3Credentials } from './s3-adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3Adapter = void 0;
+var s3_adapter_1 = require("./s3-adapter");
+Object.defineProperty(exports, "S3Adapter", { enumerable: true, get: function () { return s3_adapter_1.S3Adapter; } });
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":";;;AAAA,2CAAyC;AAAhC,uGAAA,SAAS,OAAA"}

package/dist/adapters/s3-adapter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AWS credentials interface
+ */
+export interface S3Credentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/**
+ * S3 adapter for policy client operations
+ * Provides methods to list and retrieve objects from S3
+ */
+export declare class S3Adapter {
+    private bucketName;
+    private client;
+    constructor(bucketName: string, regionName: string | undefined, credentials: S3Credentials);
+    /**
+     * List all object keys with the given prefix
+     * Returns an async generator that yields keys in lexicographic order
+     */
+    listUrisByPrefix(prefix: string): AsyncGenerator<string>;
+    /**
+     * List all object keys with the given prefix (non-generator version)
+     * Returns a promise that resolves to an array of keys
+     */
+    listAllUrisByPrefix(prefix: string): Promise<string[]>;
+    /**
+     * Retrieve an object from S3 by its key
+     * Returns the object body as a string, or null if not found
+     */
+    retrieveObject(key: string): Promise<string | null>;
+    /**
+     * Get the bucket name
+     */
+    getBucketName(): string;
+    /**
+     * Convert a readable stream to string
+     */
+    private streamToString;
+}
+//# sourceMappingURL=s3-adapter.d.ts.map

package/dist/adapters/s3-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/s3-adapter.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAW;gBAGvB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,YAAc,EAChC,WAAW,EAAE,aAAa;IAgB5B;;;OAGG;IACI,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC;IAgB/D;;;OAGG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ5D;;;OAGG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA4BzD;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;YAEW,cAAc;CAU7B"}

package/dist/adapters/s3-adapter.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3Adapter = void 0;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const constants_1 = require("../constants");
+/**
+ * S3 adapter for policy client operations
+ * Provides methods to list and retrieve objects from S3
+ */
+class S3Adapter {
+    constructor(bucketName, regionName = 'us-west-2', credentials) {
+        if (!bucketName) {
+            throw new Error('Bucket name is required');
+        }
+        if (!regionName) {
+            throw new Error('Region is required');
+        }
+        this.bucketName = bucketName;
+        this.client = new client_s3_1.S3Client({
+            region: regionName,
+            credentials,
+        });
+    }
+    /**
+     * List all object keys with the given prefix
+     * Returns an async generator that yields keys in lexicographic order
+     */
+    async *listUrisByPrefix(prefix) {
+        const paginator = (0, client_s3_1.paginateListObjectsV2)({ client: this.client, pageSize: constants_1.S3_PAGE_SIZE }, { Bucket: this.bucketName, Prefix: prefix });
+        for await (const page of paginator) {
+            const contents = page.Contents || [];
+            for (const obj of contents) {
+                if (obj.Key) {
+                    yield obj.Key;
+                }
+            }
+        }
+    }
+    /**
+     * List all object keys with the given prefix (non-generator version)
+     * Returns a promise that resolves to an array of keys
+     */
+    async listAllUrisByPrefix(prefix) {
+        const keys = [];
+        for await (const key of this.listUrisByPrefix(prefix)) {
+            keys.push(key);
+        }
+        return keys;
+    }
+    /**
+     * Retrieve an object from S3 by its key
+     * Returns the object body as a string, or null if not found
+     */
+    async retrieveObject(key) {
+        try {
+            const response = await this.client.send(new client_s3_1.GetObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+            }));
+            if (!response.Body) {
+                return null;
+            }
+            // Convert the readable stream to string
+            return await this.streamToString(response.Body);
+        }
+        catch (error) {
+            // Check for NoSuchKey error
+            if (error instanceof Error &&
+                'name' in error &&
+                error.name === 'NoSuchKey') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get the bucket name
+     */
+    getBucketName() {
+        return this.bucketName;
+    }
+    /**
+     * Convert a readable stream to string
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async streamToString(stream) {
+        const chunks = [];
+        for await (const chunk of stream) {
+            chunks.push(chunk);
+        }
+        const buffer = Buffer.concat(chunks);
+        return buffer.toString('utf-8');
+    }
+}
+exports.S3Adapter = S3Adapter;
+//# sourceMappingURL=s3-adapter.js.map

package/dist/adapters/s3-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-adapter.js","sourceRoot":"","sources":["../../src/adapters/s3-adapter.ts"],"names":[],"mappings":"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"}

package/dist/clients/policy-client.d.ts

@@ -0,0 +1,141 @@
+import type { PolicyVersion } from '../models';
+/**
+ * Client for retrieving Policy documents from S3 storage.
+ *
+ * Provides methods to list policies for employers and retrieve policy versions
+ * from S3 storage. Automatically handles AWS credential management and S3
+ * client configuration with TTL-based caching.
+ *
+ * @example
+ * ```typescript
+ * // Create a client instance
+ * const client = new PolicyClient();
+ *
+ * // List all policies for an employer
+ * const policyUris = await client.listPolicies('employer-uuid');
+ *
+ * // Retrieve a specific policy version by URI
+ * const policyVersion = await client.retrievePolicyVersion('path/to/policy.json');
+ *
+ * // Retrieve the current active policy version
+ * const currentPolicy = await client.retrieveCurrentPolicyVersion('policy-uuid');
+ *
+ * // Retrieve policy version as of a specific date
+ * const historicalPolicy = await client.retrieveCurrentPolicyVersion('policy-uuid', '2025-01-15');
+ * ```
+ */
+export declare class PolicyClient {
+    private s3Adapter;
+    private s3AdapterExpiresAt;
+    private bucketName;
+    private policyUriPrefix;
+    private policyUriPrefixExpiresAt;
+    private region;
+    constructor();
+    /**
+     * Get the AWS region
+     */
+    getRegion(): string;
+    /**
+     * List all policy URIs for a given employer.
+     *
+     * @param employerId - The UUID of the employer to list policies for
+     * @returns A list of full S3 URIs for all policies under the given employer
+     */
+    listPolicies(employerId: string): Promise<string[]>;
+    /**
+     * Retrieve a PolicyVersion from S3 using the given URI.
+     *
+     * @param uri - The S3 URI or resource path for the PolicyVersion. Can be:
+     *   - Full S3 URI (e.g., "s3://bucket/path/file.json")
+     *   - Relative resource path (e.g., "path/to/policy.json")
+     *
+     * @returns The deserialized PolicyVersion object
+     *
+     * @throws PolicySdkConfigurationError - If the uri format is invalid
+     * @throws PolicyVersionNotFoundError - If the PolicyVersion resource is not found
+     * @throws PolicyVersionDeserializationError - If the JSON cannot be deserialized
+     */
+    retrievePolicyVersion(uri: string): Promise<PolicyVersion>;
+    /**
+     * Retrieve the most recent active PolicyVersion for a given policy.
+     *
+     * This function finds the most recently published policy version for the specified date.
+     * If no date is provided, it defaults to the current "coverage day" (4am ET - 4am ET).
+     * If no policy version exists for the target date, it finds the most recently published
+     * version prior to that date.
+     *
+     * @param policyId - The policy identifier, which can be:
+     *   - UUID string (e.g., "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d")
+     *   - Full S3 URI (e.g., "s3://{bucket}/{dataset}/employers/{employer_id}/policies/{policy_uuid}.json")
+     *   - Relative resource path (e.g., "{dataset}/employers/{employer_id}/policies/{policy_uuid}.json")
+     *
+     * @param asOf - Optional date to use when finding the current policy version.
+     *   Can be a Date object or a date string in 'YYYY-MM-DD' format.
+     *   Defaults to the current coverage day (4am ET - 4am ET) if not provided.
+     *
+     * @returns The most recent active PolicyVersion for the specified date
+     *
+     * @throws PolicyVersionNotFoundError - If no active policy version is found
+     * @throws PolicyVersionDeserializationError - If the JSON cannot be deserialized
+     * @throws PolicySdkConfigurationError - If the policy_id or as_of format is invalid
+     */
+    retrieveCurrentPolicyVersion(policyId: string, asOf?: Date | string | null): Promise<PolicyVersion>;
+    /**
+     * Get the S3 bucket name based on the STAGE environment variable
+     */
+    private getBucketName;
+    /**
+     * Get the BA consumer role ARN from SSM parameter store
+     */
+    private getConsumerRoleArn;
+    /**
+     * Assume the BA consumer role using STS
+     */
+    private assumeRole;
+    /**
+     * Get or create the S3 adapter with caching
+     */
+    private getS3Client;
+    /**
+     * Get the policy URI prefix from SSM Parameter Store
+     */
+    private getPolicyUriPrefix;
+    /**
+     * Get the current coverage day based on ET timezone.
+     *
+     * A "coverage day" runs from 4am ET to 4am ET the next calendar day.
+     * This prevents timezone-related edge cases where UTC midnight doesn't align
+     * with business operations.
+     */
+    private getCoverageDay;
+    /**
+     * Format a date as YYYY-MM-DD string
+     */
+    private formatDate;
+    /**
+     * Parse a date string or Date object into a Date
+     */
+    private parseAsOfDate;
+    /**
+     * Validate and convert a policy version URI to a resource path
+     */
+    private validatePolicyVersionUri;
+    /**
+     * Parse policy_id and extract UUID and optional dataset prefix
+     */
+    private parsePolicyId;
+    /**
+     * Extract dataset prefix and UUID from a resource path
+     */
+    private extractDatasetAndUuid;
+    /**
+     * Filter policy version keys by date, keeping only those on or before target_date
+     */
+    private filterPolicyVersionsByDate;
+    /**
+     * Deserialize JSON string to PolicyVersion
+     */
+    private deserializePolicyVersion;
+}
+//# sourceMappingURL=policy-client.d.ts.map

package/dist/clients/policy-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-client.d.ts","sourceRoot":"","sources":["../../src/clients/policy-client.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,wBAAwB,CAAa;IAC7C,OAAO,CAAC,MAAM,CAAS;;IAQvB;;OAEG;IACH,SAAS,IAAI,MAAM;IAQnB;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUzD;;;;;;;;;;;;OAYG;IACG,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAchE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,4BAA4B,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,GAC1B,OAAO,CAAC,aAAa,CAAC;IAgDzB;;OAEG;IACH,OAAO,CAAC,aAAa;IAgBrB;;OAEG;YACW,kBAAkB;IAiChC;;OAEG;YACW,UAAU;IAsCxB;;OAEG;YACW,WAAW;IAkBzB;;OAEG;YACW,kBAAkB;IAgDhC;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAoCtB;;OAEG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,OAAO,CAAC,aAAa;IA6BrB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA6BhC;;OAEG;IACH,OAAO,CAAC,aAAa;IA6BrB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAkClC;;OAEG;IACH,OAAO,CAAC,wBAAwB;CASjC"}