@fluid-app/api-client

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

Installation

# 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

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

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

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:

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

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:

# .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 and provide proper TypeScript types.

Local Development

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

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

You can create this file with:

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