npm package: @fluid-app/api-client
Description: Fluid Commerce API client for JavaScript applications
Author: Fluid Commerce
Latest version: 0.1.19

# @fluid-app/api-client

A JavaScript client for the Fluid Commerce API, providing typed access to all API endpoints.

## Installation

```bash
# Using npm
npm install @fluid-app/api-client

# Using yarn
yarn add @fluid-app/api-client

# Using pnpm
pnpm add @fluid-app/api-client
```

## Usage

### Basic Example

```typescript
import { createCart, getCart } from "@fluid-app/api-client";

// Create a new cart
const newCart = await createCart({
  request: {
    fluid_shop: "your-shop-id", // Replace with your shop ID
    country_code: "US",
    items: [
      {
        variant_id: 11601, // Replace with your variant ID
        quantity: 1,
      },
    ],
  },
});

// Get cart details
const cartDetails = await getCart({
  params: {
    cart_token: newCart.cart.cart_token,
  },
});
```

### Available API Functions

The client provides typed functions for all Fluid Commerce API endpoints, automatically generated from the OpenAPI specification.

#### Cart Management

```typescript
import {
  addCartItem,
  createCart,
  getCart,
  removeCartItem,
} from "@fluid-app/api-client";

// Create a cart
const cart = await createCart({
  request: {
    fluid_shop: "your-shop-id",
    country_code: "US",
  },
});

// Add an item to cart
await addCartItem({
  params: {
    cart_token: cart.cart.cart_token,
  },
  request: {
    variant_id: 12345,
    quantity: 1,
  },
});

// Remove an item from cart
await removeCartItem({
  params: {
    cart_token: cart.cart.cart_token,
    item_id: "123", // ID of the cart item (not the variant ID)
  },
});
```

#### FairShare Analytics

```typescript
import { registerSession, trackCheckoutStarted } from "@fluid-app/api-client";

// Register a new session
const session = await registerSession({
  request: {
    fluid_shop: "your-shop-id",
  },
});

// Track checkout started event
await trackCheckoutStarted({
  request: {
    cart_token: "cart_abc123",
    metadata: {
      fluid_shop: "your-shop-id",
      fluid_session: session.session_token,
      attribution: {
        username: "influencer-name",
      },
    },
  },
});
```

### Function Patterns

All API functions follow a consistent pattern:

```typescript
// For endpoints with path parameters and request body
functionName({
  params: {
    /* path parameters */
  },
  request: {
    /* request body */
  },
});

// For endpoints with only path parameters
functionName({
  params: {
    /* path parameters */
  },
});

// For endpoints with only request body
functionName({
  request: {
    /* request body */
  },
});

// For endpoints with no parameters
functionName();
```

All functions return a Promise with the typed response from the API.

### TypeScript Support

The client provides full TypeScript support, including:

```typescript
import type { ApiTypes, Schemas } from "@fluid-app/api-client";

// Access request types
type CreateCartRequest = ApiTypes["cart-create"]["request"];

// Access response types
type CartResponse = ApiTypes["cart-get"]["response"];

// Access schema types
type CartItem = Schemas["CartItem"];
```

## Integration with Other Packages

This package is used by:

- **@fluid-app/fluid**: The main SDK that provides a high-level interface for cart management and checkout
- **@fluid-app/fairshare**: The tracking SDK that uses the API client to send events and manage sessions

Most applications should use the higher-level `@fluid-app/fluid` package instead of using this API client directly.

## Features

- ✅ Full TypeScript support with accurate types for requests and responses
- ✅ Automatic error handling with helpful error messages
- ✅ Requests automatically use the correct HTTP methods and paths
- ✅ Generated from the official Fluid Commerce API specification
- ✅ Configurable environment variables with validation

## Environment Configuration

You can configure the API client behavior by setting the following environment variables:

| Variable             | Default                 | Description                                    |
| -------------------- | ----------------------- | ---------------------------------------------- |
| `FLUID_API_BASE_URL` | `https://api.fluid.app` | The base URL for the Fluid API                 |
| `FLUID_API_TIMEOUT`  | `30000`                 | Request timeout in milliseconds                |
| `FLUID_API_DEBUG`    | `false`                 | Enable debug logging (set to `true` to enable) |

Example:

```bash
# .env file or environment variables
FLUID_API_BASE_URL=https://api.staging.fluid.app
FLUID_API_TIMEOUT=60000
FLUID_API_DEBUG=true
```

All environment variables are validated using [T3 Env](https://github.com/t3-oss/t3-env) and provide proper TypeScript types.

## Local Development

For local development, create a `.env` file in the package root with the following content:

```bash
# Local development configuration
FLUID_API_BASE_URL=http://localhost:3000
FLUID_API_TIMEOUT=60000
FLUID_API_DEBUG=true
```

You can create this file with:

```bash
echo 'FLUID_API_BASE_URL=http://localhost:3000
FLUID_API_TIMEOUT=60000
FLUID_API_DEBUG=true' > .env
```

This will configure the client to use your local API server with extended timeout and debug logging enabled.

## License

MIT