@cycomdatasystems/mackinac-sdk 1.3.7

package/README.md

@@ -0,0 +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).

package/dist/core/customFetch.d.ts

@@ -0,0 +1,6 @@
+export type MackinacConfig = {
+    baseUrl: string;
+    headersProvider?: () => Record<string, string> | Promise<Record<string, string>>;
+};
+export declare function configureMackinac(partial: Partial<MackinacConfig>): void;
+export declare function customFetch<TResponse>(url: string, init?: RequestInit): Promise<TResponse>;

package/dist/core/customFetch.js

@@ -0,0 +1,67 @@
+// src/core/customFetch.ts
+let config = {
+    baseUrl: '',
+};
+export function configureMackinac(partial) {
+    config = {
+        ...config,
+        ...partial,
+    };
+}
+function normalizeHeaders(input) {
+    if (!input)
+        return {};
+    if (input instanceof Headers) {
+        const obj = {};
+        input.forEach((value, key) => {
+            obj[key] = value;
+        });
+        return obj;
+    }
+    if (Array.isArray(input)) {
+        const obj = {};
+        for (const [key, value] of input) {
+            obj[key] = value;
+        }
+        return obj;
+    }
+    // Plain object case
+    return { ...input };
+}
+export async function customFetch(url, init) {
+    if (!config.baseUrl) {
+        throw new Error('Mackinac baseUrl is not configured. Call configureMackinac() first.');
+    }
+    const fullUrl = url.startsWith('http')
+        ? url
+        : `${config.baseUrl.replace(/\/$/, '')}/${url.replace(/^\//, '')}`;
+    // Get headers from provider if configured
+    let providerHeaders = {};
+    if (config.headersProvider) {
+        try {
+            providerHeaders = await config.headersProvider();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Headers provider failed: ${message}`);
+        }
+    }
+    // Merge headers: default < provider < request options (call-site overrides take precedence)
+    const headers = {
+        'Content-Type': 'application/json',
+        ...providerHeaders,
+        ...normalizeHeaders(init?.headers),
+    };
+    const res = await fetch(fullUrl, {
+        ...init,
+        headers,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`Mackinac ${res.status}: ${text || res.statusText}`);
+    }
+    if (res.status === 204) {
+        return undefined;
+    }
+    return (await res.json());
+}