Cart-Checkout API SDK

This directory contains generated TypeScript SDKs for the Cart-Checkout API.

NextJS SDK

The NextJS SDK is located in ./nextjs and provides type-safe API client functions optimized for Next.js applications.

Generating the SDK

The SDK is generated from the OpenAPI specification served by the running API server:

# Make sure the API server is running on http://localhost:3001
bun run start:dev

# In another terminal, generate the SDK
bun run sdk:generate

Configuration

SDK generation is configured in openapi-ts.config.ts at the project root. It:

• Fetches the OpenAPI spec from http://localhost:3001/api/docs-json
• Generates type-safe Next.js client code
• Outputs to ./sdk/nextjs
• Applies Biome linting and Prettier formatting

Usage in Next.js Applications

The SDK comes with built-in runtime configuration that automatically reads from environment variables.

Step 1: Install the SDK in Your Next.js Project

# Option A: If using a monorepo with workspaces
# Add to your Next.js package.json:
{
  "dependencies": {
    "@mp/cart-sdk": "workspace:*"  // or "file:../mp_cart/sdk/nextjs"
  }
}

# Option B: Direct file reference
npm install file:../mp_cart/sdk/nextjs

Step 2: Set Environment Variables

Create or update your .env.local file in your Next.js project:

# .env.local
NEXT_PUBLIC_CART_API_BASE_URL=http://localhost:3001
CART_API_KEY=your-api-key-here

That's it! The SDK will automatically use these environment variables.

Step 3: Use the SDK

// app/page.tsx or any component
import { getHealth, createCart, addItem } from '@mp/cart-sdk';

export default async function Page() {
  // No configuration needed - automatically uses env vars!
  const health = await getHealth();

  return <div>API Status: {health.data?.status}</div>;
}

Advanced: Customizing Runtime Config

If you need to customize the configuration logic (e.g., different env var names, custom headers, timeout settings), edit sdk/config.ts:

// sdk/config.ts
export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl: process.env.NEXT_PUBLIC_CART_API_BASE_URL || 'http://localhost:3001',
  headers: {
    'X-API-Key': process.env.CART_API_KEY || '',
    // Add custom headers here
  },
  // Add other fetch options
  // timeout: 30000,
  // credentials: 'include',
});

Then regenerate the SDK:

bun run sdk:generate

Note: The sdk/config.ts file is not regenerated, so your changes persist. Only the sdk/nextjs/ directory gets regenerated.

Generated Files

• index.ts - Main entry point, exports types and SDK functions
• sdk.gen.ts - All API endpoint functions
• types.gen.ts - TypeScript type definitions for requests/responses
• client.gen.ts - HTTP client configuration
• transformers.gen.ts - Data transformation utilities
• core/ - Core utilities for serialization, auth, etc.
• client/ - Next.js specific client implementation

Type Safety

All API calls are fully type-safe:

import type { CreateCartDto, AddItemDto } from '@/sdk/nextjs';

// TypeScript will enforce correct request structure
const cart: CreateCartDto = {
  currency: 'USD', // Required
  metadata: {}, // Optional
};

Error Handling

try {
  const result = await getCart({
    path: { cartSessionId: 'abc123' },
  });

  if (result.error) {
    console.error('API Error:', result.error);
  } else {
    console.log('Cart:', result.data);
  }
} catch (error) {
  console.error('Network error:', error);
}

Regenerating After API Changes

Whenever you make changes to the API (controllers, DTOs, routes):

1. Ensure your changes are reflected in the Swagger documentation
2. Start the development server if not already running
3. Run bun run sdk:generate to regenerate the SDK
4. The generated files in sdk/nextjs will be updated automatically

Notes

• The sdk/nextjs directory is gitignored and should be regenerated as needed
• Always regenerate the SDK after API changes to maintain type safety
• The SDK uses the Next.js fetch implementation under the hood