@vitable-inc/vitable-connect 0.3.0 → 2.0.0

package/README.md

@@ -1,58 +1,66 @@
-# Vitable Connect TypeScript API Library
-
-[![NPM version](<https://img.shields.io/npm/v/@vitable-inc/vitable-connect.svg?label=npm%20(stable)>)](https://npmjs.org/package/@vitable-inc/vitable-connect) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@vitable-inc/vitable-connect)
-
-This library provides convenient access to the Vitable Connect REST API from server-side TypeScript or JavaScript.
-
-The REST API documentation can be found on [vitablehealth.com](https://vitablehealth.com/support). The full API of this library can be found in [api.md](api.md).
-
-It is generated with [Stainless](https://www.stainless.com/).
+# Vitable Connect TypeScript Library
+
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2FVitable-Inc%2Fvitable-connect-typescript)
+[![npm shield](https://img.shields.io/npm/v/@vitable-inc/vitable-connect)](https://www.npmjs.com/package/@vitable-inc/vitable-connect)
+
+The Vitable Connect TypeScript library provides convenient access to the Vitable Connect APIs from TypeScript.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Reference](#reference)
+- [Usage](#usage)
+- [Handling Errors](#handling-errors)
+- [Auto Pagination](#auto-pagination)
+- [Advanced Usage](#advanced-usage)
+- [Frequently Asked Questions](#frequently-asked-questions)
+- [Semantic Versioning](#semantic-versioning)
+- [Requirements](#requirements)
+- [Environments](#environments)
+- [Request and Response Types](#request-and-response-types)
+- [Exception Handling](#exception-handling)
+- [Pagination](#pagination)
+- [Advanced](#advanced)
+  - [Subpackage Exports](#subpackage-exports)
+  - [Additional Headers](#additional-headers)
+  - [Additional Query String Parameters](#additional-query-string-parameters)
+  - [Retries](#retries)
+  - [Timeouts](#timeouts)
+  - [Aborting Requests](#aborting-requests)
+  - [Access Raw Response Data](#access-raw-response-data)
+  - [Logging](#logging)
+  - [Custom Fetch](#custom-fetch)
+  - [Custom Fetcher](#custom-fetcher)
+  - [Runtime Compatibility](#runtime-compatibility)
+- [Contributing](#contributing)
 
 ## Installation
 
 ```sh
-npm install @vitable-inc/vitable-connect
+npm i -s @vitable-inc/vitable-connect
 ```
 
-## Usage
-
-The full API of this library can be found in [api.md](api.md).
+## Reference
 
-<!-- prettier-ignore -->
-```js
-import VitableConnect from '@vitable-inc/vitable-connect';
+A full reference for this library is available [here](https://github.com/Vitable-Inc/vitable-connect-typescript/blob/HEAD/./reference.md).
 
-const client = new VitableConnect({
-  apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted
-  environment: 'environment_1', // defaults to 'production'
-});
-
-const response = await client.auth.issueAccessToken({ grant_type: 'client_credentials' });
-
-console.log(response.access_token);
-```
+## Usage
 
-### Request & Response types
+Instantiate and use the client with the following:
 
-This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
+```typescript
+import { VitableConnectClient } from "@vitable-inc/vitable-connect";
 
-<!-- prettier-ignore -->
-```ts
-import VitableConnect from '@vitable-inc/vitable-connect';
-
-const client = new VitableConnect({
-  apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted
-  environment: 'environment_1', // defaults to 'production'
+const client = new VitableConnectClient({ apiKey: "YOUR_API_KEY" });
+await client.auth.issueAccessToken({
+    grant_type: "client_credentials",
+    bound_entity: {
+        id: "empr_SGVsbG8gV29ybGQ",
+        type: "employer"
+    }
 });
-
-const params: VitableConnect.AuthIssueAccessTokenParams = { grant_type: 'client_credentials' };
-const response: VitableConnect.AuthIssueAccessTokenResponse = await client.auth.issueAccessToken(
-  params,
-);
 ```
 
-Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
-
 ## Handling errors
 
 When the library is unable to connect to the API,
@@ -395,6 +403,307 @@ Note that React Native is not supported at this time.
 
 If you are interested in other runtime environments, please open or upvote an issue on GitHub.
 
+## Environments
+
+This SDK allows you to configure different environments for API requests.
+
+```typescript
+import { VitableConnectClient, VitableConnectEnvironment } from "@vitable-inc/vitable-connect";
+
+const client = new VitableConnectClient({
+    environment: VitableConnectEnvironment.Production,
+});
+```
+
+## Request and Response Types
+
+The SDK exports all request and response types as TypeScript interfaces. Simply import them with the
+following namespace:
+
+```typescript
+import { VitableConnect } from "@vitable-inc/vitable-connect";
+
+const request: VitableConnect.IssueAccessTokenRequest = {
+    ...
+};
+```
+
+## Exception Handling
+
+When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
+will be thrown.
+
+```typescript
+import { VitableConnectError } from "@vitable-inc/vitable-connect";
+
+try {
+    await client.auth.issueAccessToken(...);
+} catch (err) {
+    if (err instanceof VitableConnectError) {
+        console.log(err.statusCode);
+        console.log(err.message);
+        console.log(err.body);
+        console.log(err.rawResponse);
+    }
+}
+```
+
+## Pagination
+
+List endpoints are paginated. The SDK provides an iterator so that you can simply loop over the items:
+
+```typescript
+import { VitableConnectClient } from "@vitable-inc/vitable-connect";
+
+const client = new VitableConnectClient({ apiKey: "YOUR_API_KEY" });
+const pageableResponse = await client.employees.listEnrollments({
+    employee_id: "empl_abc123def456",
+    limit: 20,
+    page: 1
+});
+for await (const item of pageableResponse) {
+    console.log(item);
+}
+
+// Or you can manually iterate page-by-page
+let page = await client.employees.listEnrollments({
+    employee_id: "empl_abc123def456",
+    limit: 20,
+    page: 1
+});
+while (page.hasNextPage()) {
+    page = page.getNextPage();
+}
+
+// You can also access the underlying response
+const response = page.response;
+```
+
+## Advanced
+
+### Subpackage Exports
+
+This SDK supports direct imports of subpackage clients, which allows JavaScript bundlers to tree-shake and include only the imported subpackage code. This results in much smaller bundle sizes.
+
+```typescript
+import { AuthClient } from '@vitable-inc/vitable-connect/auth';
+
+const client = new AuthClient({...});
+```
+
+### Additional Headers
+
+If you would like to send additional headers as part of the request, use the `headers` request option.
+
+```typescript
+import { VitableConnectClient } from "@vitable-inc/vitable-connect";
+
+const client = new VitableConnectClient({
+    ...
+    headers: {
+        'X-Custom-Header': 'custom value'
+    }
+});
+
+const response = await client.auth.issueAccessToken(..., {
+    headers: {
+        'X-Custom-Header': 'custom value'
+    }
+});
+```
+
+### Additional Query String Parameters
+
+If you would like to send additional query string parameters as part of the request, use the `queryParams` request option.
+
+```typescript
+const response = await client.auth.issueAccessToken(..., {
+    queryParams: {
+        'customQueryParamKey': 'custom query param value'
+    }
+});
+```
+
+### Retries
+
+The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
+as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
+retry limit (default: 2).
+
+Which status codes are retried depends on the `retryStatusCodes` generator configuration:
+
+**`legacy`** (current default): retries on
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (All server errors, including 500)
+
+**`recommended`**: retries on
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) (Bad Gateway)
+- [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) (Service Unavailable)
+- [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) (Gateway Timeout)
+
+Use the `maxRetries` request option to configure this behavior.
+
+```typescript
+const response = await client.auth.issueAccessToken(..., {
+    maxRetries: 0 // override maxRetries at the request level
+});
+```
+
+### Timeouts
+
+The SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior.
+
+```typescript
+const response = await client.auth.issueAccessToken(..., {
+    timeoutInSeconds: 30 // override timeout to 30s
+});
+```
+
+### Aborting Requests
+
+The SDK allows users to abort requests at any point by passing in an abort signal.
+
+```typescript
+const controller = new AbortController();
+const response = await client.auth.issueAccessToken(..., {
+    abortSignal: controller.signal
+});
+controller.abort(); // aborts the request
+```
+
+### Access Raw Response Data
+
+The SDK provides access to raw response data, including headers, through the `.withRawResponse()` method.
+The `.withRawResponse()` method returns a promise that results to an object with a `data` and a `rawResponse` property.
+
+```typescript
+const { data, rawResponse } = await client.auth.issueAccessToken(...).withRawResponse();
+
+console.log(data);
+console.log(rawResponse.headers['X-My-Header']);
+```
+
+### Logging
+
+The SDK supports logging. You can configure the logger by passing in a `logging` object to the client options.
+
+```typescript
+import { VitableConnectClient, logging } from "@vitable-inc/vitable-connect";
+
+const client = new VitableConnectClient({
+    ...
+    logging: {
+        level: logging.LogLevel.Debug, // defaults to logging.LogLevel.Info
+        logger: new logging.ConsoleLogger(), // defaults to ConsoleLogger
+        silent: false, // defaults to true, set to false to enable logging
+    }
+});
+```
+The `logging` object can have the following properties:
+- `level`: The log level to use. Defaults to `logging.LogLevel.Info`.
+- `logger`: The logger to use. Defaults to a `logging.ConsoleLogger`.
+- `silent`: Whether to silence the logger. Defaults to `true`.
+
+The `level` property can be one of the following values:
+- `logging.LogLevel.Debug`
+- `logging.LogLevel.Info`
+- `logging.LogLevel.Warn`
+- `logging.LogLevel.Error`
+
+To provide a custom logger, you can pass in an object that implements the `logging.ILogger` interface.
+
+<details>
+<summary>Custom logger examples</summary>
+
+Here's an example using the popular `winston` logging library.
+```ts
+import winston from 'winston';
+
+const winstonLogger = winston.createLogger({...});
+
+const logger: logging.ILogger = {
+    debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
+    info: (msg, ...args) => winstonLogger.info(msg, ...args),
+    warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+    error: (msg, ...args) => winstonLogger.error(msg, ...args),
+};
+```
+
+Here's an example using the popular `pino` logging library.
+
+```ts
+import pino from 'pino';
+
+const pinoLogger = pino({...});
+
+const logger: logging.ILogger = {
+  debug: (msg, ...args) => pinoLogger.debug(args, msg),
+  info: (msg, ...args) => pinoLogger.info(args, msg),
+  warn: (msg, ...args) => pinoLogger.warn(args, msg),
+  error: (msg, ...args) => pinoLogger.error(args, msg),
+};
+```
+</details>
+
+
+### Custom Fetch
+
+The SDK provides a low-level `fetch` method for making custom HTTP requests while still
+benefiting from SDK-level configuration like authentication, retries, timeouts, and logging.
+This is useful for calling API endpoints not yet supported in the SDK.
+
+```typescript
+const response = await client.fetch("/v1/custom/endpoint", {
+    method: "GET",
+}, {
+    timeoutInSeconds: 30,
+    maxRetries: 3,
+    headers: {
+        "X-Custom-Header": "custom-value",
+    },
+});
+
+const data = await response.json();
+```
+
+### Custom Fetcher
+
+The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an
+unsupported environment, this provides a way for you to break glass and ensure the SDK works.
+
+```typescript
+import { VitableConnectClient } from "@vitable-inc/vitable-connect";
+
+const client = new VitableConnectClient({
+    ...
+    fetcher: // provide your implementation here
+});
+```
+
+### Runtime Compatibility
+
+
+The SDK works in the following runtimes:
+
+
+
+- Node.js 18+
+- Vercel
+- Cloudflare Workers
+- Deno v1.25+
+- Bun 1.0+
+- React Native
+
+
 ## Contributing
 
-See [the contributing documentation](./CONTRIBUTING.md).
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!

package/dist/cjs/BaseClient.d.ts

@@ -0,0 +1,56 @@
+import { AnyAuthProvider } from "./auth/AnyAuthProvider.js";
+import { BearerAuthProvider } from "./auth/BearerAuthProvider.js";
+import * as core from "./core/index.js";
+import type * as environments from "./environments.js";
+export type AuthOption = false | core.AuthProvider["getAuthRequest"] | core.AuthProvider | AnyAuthProvider.AuthOptions<[BearerAuthProvider.AuthOptions]>;
+export type BaseClientOptions = {
+    environment?: core.Supplier<environments.VitableConnectEnvironment | string>;
+    /** Specify a custom URL to connect the client to. */
+    baseUrl?: core.Supplier<string>;
+    /** Additional headers to include in requests. */
+    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
+    /** The default maximum time to wait for a response in seconds. */
+    timeoutInSeconds?: number;
+    /** The default number of times to retry the request. Defaults to 2. */
+    maxRetries?: number;
+    /** Provide a custom fetch implementation. Useful for platforms that don't have a built-in fetch or need a custom implementation. */
+    fetch?: typeof fetch;
+    fetcher?: core.FetchFunction;
+    /** Configure logging for the client. */
+    logging?: core.logging.LogConfig | core.logging.Logger;
+    /** Default options for SSE stream reconnection behavior. Has no effect on non-resumable endpoints. */
+    stream?: {
+        reconnectionEnabled?: boolean;
+        maxReconnectionAttempts?: number;
+    };
+    /** Override auth. Pass false to disable, a function returning auth headers, an AuthProvider, or auth options. */
+    auth?: AuthOption;
+} & AnyAuthProvider.AuthOptions<[BearerAuthProvider.AuthOptions]>;
+export interface BaseRequestOptions {
+    /** The maximum time to wait for a response in seconds. */
+    timeoutInSeconds?: number;
+    /** The number of times to retry the request. Defaults to 2. */
+    maxRetries?: number;
+    /** A hook to abort the request. */
+    abortSignal?: AbortSignal;
+    /** Additional query string parameters to include in the request. */
+    queryParams?: Record<string, unknown>;
+    /** A dictionary containing additional parameters to spread into the request's body. */
+    additionalBodyParameters?: Record<string, unknown>;
+    /** Additional headers to include in the request. */
+    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
+    /** Options for SSE stream reconnection behavior. Has no effect on non-resumable endpoints. */
+    stream?: {
+        reconnectionEnabled?: boolean;
+        maxReconnectionAttempts?: number;
+    };
+}
+export type NormalizedClientOptions<T extends BaseClientOptions = BaseClientOptions> = T & {
+    logging: core.logging.Logger;
+    authProvider?: core.AuthProvider;
+};
+export type NormalizedClientOptionsWithAuth<T extends BaseClientOptions = BaseClientOptions> = NormalizedClientOptions<T> & {
+    authProvider: core.AuthProvider;
+};
+export declare function normalizeClientOptions<T extends BaseClientOptions = BaseClientOptions>(options: T): NormalizedClientOptions<T>;
+export declare function normalizeClientOptionsWithAuth<T extends BaseClientOptions = BaseClientOptions>(options: T): NormalizedClientOptionsWithAuth<T>;

package/dist/cjs/BaseClient.js

@@ -0,0 +1,78 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeClientOptions = normalizeClientOptions;
+exports.normalizeClientOptionsWithAuth = normalizeClientOptionsWithAuth;
+const AnyAuthProvider_js_1 = require("./auth/AnyAuthProvider.js");
+const BearerAuthProvider_js_1 = require("./auth/BearerAuthProvider.js");
+const headers_js_1 = require("./core/headers.js");
+const core = __importStar(require("./core/index.js"));
+function normalizeClientOptions(options) {
+    const headers = (0, headers_js_1.mergeHeaders)({
+        "X-Fern-Language": "JavaScript",
+        "X-Fern-SDK-Name": "@vitable-inc/vitable-connect",
+        "X-Fern-SDK-Version": "2.0.0",
+        "User-Agent": "@vitable-inc/vitable-connect/2.0.0",
+        "X-Fern-Runtime": core.RUNTIME.type,
+        "X-Fern-Runtime-Version": core.RUNTIME.version,
+    }, options === null || options === void 0 ? void 0 : options.headers);
+    return Object.assign(Object.assign({}, options), { logging: core.logging.createLogger(options === null || options === void 0 ? void 0 : options.logging), headers });
+}
+function normalizeClientOptionsWithAuth(options) {
+    var _a;
+    const normalized = normalizeClientOptions(options);
+    if (options.auth === false) {
+        normalized.authProvider = new core.NoOpAuthProvider();
+        return normalized;
+    }
+    if (options.auth != null) {
+        if (typeof options.auth === "function") {
+            normalized.authProvider = { getAuthRequest: options.auth };
+            return normalized;
+        }
+        if (core.isAuthProvider(options.auth)) {
+            normalized.authProvider = options.auth;
+            return normalized;
+        }
+        Object.assign(normalized, options.auth);
+    }
+    const normalizedWithNoOpAuthProvider = withNoOpAuthProvider(normalized);
+    (_a = normalized.authProvider) !== null && _a !== void 0 ? _a : (normalized.authProvider = AnyAuthProvider_js_1.AnyAuthProvider.createInstance(normalizedWithNoOpAuthProvider, [BearerAuthProvider_js_1.BearerAuthProvider]));
+    return normalized;
+}
+function withNoOpAuthProvider(options) {
+    return Object.assign(Object.assign({}, options), { authProvider: new core.NoOpAuthProvider() });
+}

package/dist/cjs/Client.d.ts

@@ -0,0 +1,50 @@
+import { AuthClient } from "./api/resources/auth/client/Client.js";
+import { EmployeesClient } from "./api/resources/employees/client/Client.js";
+import { EmployersClient } from "./api/resources/employers/client/Client.js";
+import { EnrollmentsClient } from "./api/resources/enrollments/client/Client.js";
+import { GroupsClient } from "./api/resources/groups/client/Client.js";
+import { MembersClient } from "./api/resources/members/client/Client.js";
+import { OrganizationsClient } from "./api/resources/organizations/client/Client.js";
+import { PlansClient } from "./api/resources/plans/client/Client.js";
+import { WebhookEventsClient } from "./api/resources/webhookEvents/client/Client.js";
+import type { BaseClientOptions, BaseRequestOptions } from "./BaseClient.js";
+import { type NormalizedClientOptionsWithAuth } from "./BaseClient.js";
+import * as core from "./core/index.js";
+export declare namespace VitableConnectClient {
+    type Options = BaseClientOptions;
+    interface RequestOptions extends BaseRequestOptions {
+    }
+}
+export declare class VitableConnectClient {
+    protected readonly _options: NormalizedClientOptionsWithAuth<VitableConnectClient.Options>;
+    protected _auth: AuthClient | undefined;
+    protected _employees: EmployeesClient | undefined;
+    protected _employers: EmployersClient | undefined;
+    protected _enrollments: EnrollmentsClient | undefined;
+    protected _groups: GroupsClient | undefined;
+    protected _members: MembersClient | undefined;
+    protected _organizations: OrganizationsClient | undefined;
+    protected _plans: PlansClient | undefined;
+    protected _webhookEvents: WebhookEventsClient | undefined;
+    constructor(options?: VitableConnectClient.Options);
+    get auth(): AuthClient;
+    get employees(): EmployeesClient;
+    get employers(): EmployersClient;
+    get enrollments(): EnrollmentsClient;
+    get groups(): GroupsClient;
+    get members(): MembersClient;
+    get organizations(): OrganizationsClient;
+    get plans(): PlansClient;
+    get webhookEvents(): WebhookEventsClient;
+    /**
+     * Make a passthrough request using the SDK's configured auth, retry, logging, etc.
+     * This is useful for making requests to endpoints not yet supported in the SDK.
+     * The input can be a URL string, URL object, or Request object. Relative paths are resolved against the configured base URL.
+     *
+     * @param {Request | string | URL} input - The URL, path, or Request object.
+     * @param {RequestInit} init - Standard fetch RequestInit options.
+     * @param {core.PassthroughRequest.RequestOptions} requestOptions - Per-request overrides (timeout, retries, headers, abort signal).
+     * @returns {Promise<Response>} A standard Response object.
+     */
+    fetch(input: Request | string | URL, init?: RequestInit, requestOptions?: core.PassthroughRequest.RequestOptions): Promise<Response>;
+}