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

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

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:

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:

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

// 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:

// 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}`,
      };
    },
  });
}

// 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

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

// 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

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

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:

npm install

• Run codegen + build:

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).