@cycomdatasystems/mackinac-sdk 1.3.7 → 3.1.0

package/README.md

@@ -1,239 +1,239 @@
-# Mackinac SDK
-
-A shared TypeScript client for the Mackinac API.  
-Generated from the Mackinac OpenAPI specification, this SDK provides strongly typed models and a unified fetch-based client for web and mobile applications. It ensures consistent API usage, reduces duplication, and keeps all consumers aligned with the latest API contract.
-
----
-
-## Installation
-
-```bash
-npm install @cycom/mackinac-sdk
-# or
-yarn add @cycom/mackinac-sdk
-# or
-pnpm add @cycom/mackinac-sdk
-```
-
----
-
-## Usage
-
-### Configure the SDK once at application startup
-
-```ts
-import { configureMackinac } from '@cycom/mackinac-sdk';
-
-configureMackinac({
-  baseUrl: process.env.MACKINAC_API_URL!,
-});
-```
-
-For applications that need to attach authorization headers or other request-specific headers to SDK calls, you can provide a `headersProvider` function:
-
-```ts
-import { configureMackinac } from '@cycom/mackinac-sdk';
-
-configureMackinac({
-  baseUrl: process.env.MACKINAC_API_URL!,
-  headersProvider: () => ({
-    'Authorization': `Bearer ${getToken()}`,
-    'X-Org-Id': getCurrentOrgId(),
-  }),
-});
-```
-
-The `headersProvider` can also be async to support token retrieval from async sources:
-
-```ts
-configureMackinac({
-  baseUrl: process.env.MACKINAC_API_URL!,
-  headersProvider: async () => {
-    const token = await getAccessToken();
-    return {
-      'Authorization': `Bearer ${token}`,
-    };
-  },
-});
-```
-
-### Authentication
-
-#### Using Headers Provider (Recommended)
-
-The SDK provides a `headersProvider` function for request-scoped authentication. This is the recommended approach for applications that need to attach `Authorization` headers or other dynamic headers to each SDK call.
-
-**Benefits:**
-- Centralized header management for all SDK calls
-- Support for async token retrieval
-- Automatically merges with per-call headers
-- Per-request invocation prevents token leakage across requests
-
-**Example: Next.js Route Handler with Auth0**
-
-```ts
-// app/api/finance/payments/route.ts
-import { getSession } from '@auth0/nextjs-auth0';
-import { configureMackinac } from '@cycom/mackinac-sdk';
-import { getApiV1MattersMatterIdFinancePayments } from '@cycom/mackinac-sdk';
-
-export async function GET(request: Request) {
-  const session = await getSession();
-  
-  // Configure SDK with token provider for this request
-  configureMackinac({
-    baseUrl: process.env.MACKINAC_API_URL!,
-    headersProvider: () => ({
-      'Authorization': `Bearer ${session.accessToken}`,
-    }),
-  });
-  
-  // All SDK calls now include Authorization header
-  const payments = await getApiV1MattersMatterIdFinancePayments(123);
-  
-  return Response.json(payments);
-}
-```
-
-Or, if you need async token retrieval:
-
-```ts
-// src/server/mackinac/config.ts
-import { configureMackinac } from '@cycom/mackinac-sdk';
-
-export function configureMackinacForRequest(getToken: () => Promise<string>) {
-  configureMackinac({
-    baseUrl: process.env.MACKINAC_API_URL!,
-    headersProvider: async () => {
-      const token = await getToken();
-      return {
-        'Authorization': `Bearer ${token}`,
-      };
-    },
-  });
-}
-```
-
-```ts
-// app/api/finance/payments/route.ts
-import { configureMackinacForRequest } from '@/server/mackinac/config';
-import { getApiV1MattersMatterIdFinancePayments } from '@cycom/mackinac-sdk';
-
-export async function GET(request: Request) {
-  // Configure SDK with async token provider for this request
-  configureMackinacForRequest(async () => {
-    // Simulate async token retrieval
-    return await fetchTokenFromAuthService();
-  });
-  
-  // All SDK calls now include Authorization header
-  const payments = await getApiV1MattersMatterIdFinancePayments(123);
-  
-  return Response.json(payments);
-}
-```
-
-**Example: Synchronous Headers Provider**
-
-```ts
-import { configureMackinac } from '@cycom/mackinac-sdk';
-
-configureMackinac({
-  baseUrl: process.env.MACKINAC_API_URL!,
-  headersProvider: () => ({
-    'Authorization': `Bearer ${process.env.API_TOKEN}`,
-    'X-Org-Id': 'org-123',
-  }),
-});
-```
-
-**Header Merge Priority**
-
-Headers are merged in the following order (later overrides earlier):
-1. Default headers (`Content-Type: application/json`)
-2. Headers from `headersProvider()`
-3. Per-call headers passed to individual endpoint functions
-
-```ts
-// Example of per-call override
-const payments = await getApiV1MattersMatterIdFinancePayments(
-  123,
-  {
-    headers: {
-      'X-Request-Id': 'custom-id', // Merges with provider headers
-      'Authorization': 'Bearer override-token', // Overrides provider's Authorization
-    }
-  }
-);
-```
-
-#### Middleware-Based Authentication (Legacy)
-
-This SDK **does not handle authentication internally**.
-
-If your application uses Auth0 (or another IdP), and access tokens are added to outbound requests by middleware or framework-level fetch interception, **you should not supply tokens to this SDK directly**.
-
-The SDK simply calls `fetch()`. Any middleware or runtime environment that injects the `Authorization` header will continue to work as expected.
-
----
-
-## Example
-
-```ts
-import { getApiV1MattersMyOpen } from '@cycom/mackinac-sdk';
-
-// Fetch "My Open Matters" for the current user
-const matters = await getApiV1MattersMyOpen({ moduleCode: 'Claims' });
-
-console.log('Open matters:', matters);
-```
-
-All generated functions return response bodies directly (not wrapped objects), following the configured Orval output.
-
----
-
-## Code Generation
-
-This SDK is generated from the Mackinac OpenAPI spec using **Orval**.
-
-### Regenerate the SDK
-
-```bash
-npm run orval
-```
-
-Ensure the latest `swagger.json` from the Mackinac API is located in the `/contracts` directory or at the configured URL.
-
----
-
-## Development
-
-- Requires Node.js 18+
-- Install dependencies:
-
-```bash
-npm install
-```
-
-- Run codegen + build:
-
-```bash
-npm run orval && npm run build
-```
-
----
-
-## Versioning
-
-This package follows semantic versioning:
-
-- **PATCH:** Regenerated SDK with no API contract changes  
-- **MINOR:** New endpoints or non-breaking additions  
-- **MAJOR:** Breaking API contract changes
-
----
-
-## License
-
-This package is intended for internal use within Cycom.  
-If distributed externally, add an appropriate open-source license (e.g., MIT).
+# Mackinac SDK
+
+A shared TypeScript client for the Mackinac API.  
+Generated from the Mackinac OpenAPI specification, this SDK provides strongly typed models and a unified fetch-based client for web and mobile applications. It ensures consistent API usage, reduces duplication, and keeps all consumers aligned with the latest API contract.
+
+---
+
+## Installation
+
+```bash
+npm install @cycom/mackinac-sdk
+# or
+yarn add @cycom/mackinac-sdk
+# or
+pnpm add @cycom/mackinac-sdk
+```
+
+---
+
+## Usage
+
+### Configure the SDK once at application startup
+
+```ts
+import { configureMackinac } from '@cycom/mackinac-sdk';
+
+configureMackinac({
+  baseUrl: process.env.MACKINAC_API_URL!,
+});
+```
+
+For applications that need to attach authorization headers or other request-specific headers to SDK calls, you can provide a `headersProvider` function:
+
+```ts
+import { configureMackinac } from '@cycom/mackinac-sdk';
+
+configureMackinac({
+  baseUrl: process.env.MACKINAC_API_URL!,
+  headersProvider: () => ({
+    'Authorization': `Bearer ${getToken()}`,
+    'X-Org-Id': getCurrentOrgId(),
+  }),
+});
+```
+
+The `headersProvider` can also be async to support token retrieval from async sources:
+
+```ts
+configureMackinac({
+  baseUrl: process.env.MACKINAC_API_URL!,
+  headersProvider: async () => {
+    const token = await getAccessToken();
+    return {
+      'Authorization': `Bearer ${token}`,
+    };
+  },
+});
+```
+
+### Authentication
+
+#### Using Headers Provider (Recommended)
+
+The SDK provides a `headersProvider` function for request-scoped authentication. This is the recommended approach for applications that need to attach `Authorization` headers or other dynamic headers to each SDK call.
+
+**Benefits:**
+- Centralized header management for all SDK calls
+- Support for async token retrieval
+- Automatically merges with per-call headers
+- Per-request invocation prevents token leakage across requests
+
+**Example: Next.js Route Handler with Auth0**
+
+```ts
+// app/api/finance/payments/route.ts
+import { getSession } from '@auth0/nextjs-auth0';
+import { configureMackinac } from '@cycom/mackinac-sdk';
+import { getApiV1MattersMatterIdFinancePayments } from '@cycom/mackinac-sdk';
+
+export async function GET(request: Request) {
+  const session = await getSession();
+  
+  // Configure SDK with token provider for this request
+  configureMackinac({
+    baseUrl: process.env.MACKINAC_API_URL!,
+    headersProvider: () => ({
+      'Authorization': `Bearer ${session.accessToken}`,
+    }),
+  });
+  
+  // All SDK calls now include Authorization header
+  const payments = await getApiV1MattersMatterIdFinancePayments(123);
+  
+  return Response.json(payments);
+}
+```
+
+Or, if you need async token retrieval:
+
+```ts
+// src/server/mackinac/config.ts
+import { configureMackinac } from '@cycom/mackinac-sdk';
+
+export function configureMackinacForRequest(getToken: () => Promise<string>) {
+  configureMackinac({
+    baseUrl: process.env.MACKINAC_API_URL!,
+    headersProvider: async () => {
+      const token = await getToken();
+      return {
+        'Authorization': `Bearer ${token}`,
+      };
+    },
+  });
+}
+```
+
+```ts
+// app/api/finance/payments/route.ts
+import { configureMackinacForRequest } from '@/server/mackinac/config';
+import { getApiV1MattersMatterIdFinancePayments } from '@cycom/mackinac-sdk';
+
+export async function GET(request: Request) {
+  // Configure SDK with async token provider for this request
+  configureMackinacForRequest(async () => {
+    // Simulate async token retrieval
+    return await fetchTokenFromAuthService();
+  });
+  
+  // All SDK calls now include Authorization header
+  const payments = await getApiV1MattersMatterIdFinancePayments(123);
+  
+  return Response.json(payments);
+}
+```
+
+**Example: Synchronous Headers Provider**
+
+```ts
+import { configureMackinac } from '@cycom/mackinac-sdk';
+
+configureMackinac({
+  baseUrl: process.env.MACKINAC_API_URL!,
+  headersProvider: () => ({
+    'Authorization': `Bearer ${process.env.API_TOKEN}`,
+    'X-Org-Id': 'org-123',
+  }),
+});
+```
+
+**Header Merge Priority**
+
+Headers are merged in the following order (later overrides earlier):
+1. Default headers (`Content-Type: application/json`)
+2. Headers from `headersProvider()`
+3. Per-call headers passed to individual endpoint functions
+
+```ts
+// Example of per-call override
+const payments = await getApiV1MattersMatterIdFinancePayments(
+  123,
+  {
+    headers: {
+      'X-Request-Id': 'custom-id', // Merges with provider headers
+      'Authorization': 'Bearer override-token', // Overrides provider's Authorization
+    }
+  }
+);
+```
+
+#### Middleware-Based Authentication (Legacy)
+
+This SDK **does not handle authentication internally**.
+
+If your application uses Auth0 (or another IdP), and access tokens are added to outbound requests by middleware or framework-level fetch interception, **you should not supply tokens to this SDK directly**.
+
+The SDK simply calls `fetch()`. Any middleware or runtime environment that injects the `Authorization` header will continue to work as expected.
+
+---
+
+## Example
+
+```ts
+import { getApiV1MattersMyOpen } from '@cycom/mackinac-sdk';
+
+// Fetch "My Open Matters" for the current user
+const matters = await getApiV1MattersMyOpen({ moduleCode: 'Claims' });
+
+console.log('Open matters:', matters);
+```
+
+All generated functions return response bodies directly (not wrapped objects), following the configured Orval output.
+
+---
+
+## Code Generation
+
+This SDK is generated from the Mackinac OpenAPI spec using **Orval**.
+
+### Regenerate the SDK
+
+```bash
+npm run orval
+```
+
+Ensure the latest `swagger.json` from the Mackinac API is located in the `/contracts` directory or at the configured URL.
+
+---
+
+## Development
+
+- Requires Node.js 18+
+- Install dependencies:
+
+```bash
+npm install
+```
+
+- Run codegen + build:
+
+```bash
+npm run orval && npm run build
+```
+
+---
+
+## Versioning
+
+This package follows semantic versioning:
+
+- **PATCH:** Regenerated SDK with no API contract changes  
+- **MINOR:** New endpoints or non-breaking additions  
+- **MAJOR:** Breaking API contract changes
+
+---
+
+## License
+
+This package is intended for internal use within Cycom.  
+If distributed externally, add an appropriate open-source license (e.g., MIT).