# @fluid-app/api-client 中文文档

规范地址：https://npmcn.com/package/%40fluid-app/api-client/

版本：0\.1\.19
npm 元数据更新时间：2026-09-16T21:41:37.591Z
中文译文更新时间：2026-11-15T01:30:35.965Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fluid-app/api-client
原文对照：https://npmcn.com/package/%40fluid-app/api-client/?lang=original
项目主页：https://fluid.app/
源码仓库：https://github.com/fluid-app/fluid-npm

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-03-19T19:18:28.506Z
- 最新版本发布：2025-07-15T23:27:09.193Z
- 近 30 天下载量：21263（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 0 个）

## 中文简介

JavaScript 应用程序的 Fluid Commerce API 客户端

## 安装

```sh
npm install @fluid-app/api-client
```

也可以使用：`pnpm add @fluid-app/api-client`、`yarn add @fluid-app/api-client`、`bun add @fluid-app/api-client`

## README

# @fluid-app/ api-客户端

一个用于Fluid Commerce API的JavaScript客户端,提供了对所有API端点的打入.

## 安装

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

## 使用量

### 基本示例

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

### 可用的 API 函数

客户端为所有Fluid Commerce API端点提供打入函数,自动由OpenAPI规格生成.

#### 墨盒管理

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

#### 公平分享分析

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

### 函数模式

所有API函数都遵循一个一致的模式:

```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();
```

所有函数返回带有 API 输入的响应的保证 .

### 类型脚本支持

该客户端提供了完整的TypeScript支持,包括:

```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"];
```

## 与其他软件包的整合

此软件包由 :

-   **@ fluid-app/ fluid (英语)**:主要SDK为手推车管理和取出提供高级接口
-   **@fluid-app/公平分享**: 使用 API 客户端发送事件并管理会话的跟踪 SDK

大多数应用程序应使用更高层次 `@fluid-app/fluid` 软件包,而不是直接使用此 API 客户端.

## 特征

-   QQ 完整类型脚本支持, 包含请求和回复的准确类型
-   QQ 用有帮助的错误信息自动处理错误
-   QQ 请求自动使用正确的 HTTP 方法和路径
-   源于官方的流体商业API规格
-   QQ 可配置的环境变量与验证

## 环境配置

您可以通过设置以下环境变量来配置 API 客户端行为 :

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `FLUID_API_BASE_URL` | `https://api.fluid.app` | Fluid API 的基础 URL |
| `FLUID_API_TIMEOUT` | `30000` | 请求超时( 毫秒) |
| `FLUID_API_DEBUG` | `false` | 启用调试记录( 设置为) `true` 页:1 |

示例

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

所有环境变量都使用 [T3 信封](https://github.com/t3-oss/t3-env) ,并提供合适的类型脚本.

## 地方发展

为地方发展建立一个 `.env` 在软件包根中包含以下内容的文件:

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

您可以以 :

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

这将配置客户端使用您的本地 API 服务器, 并启用延长超时和调试日志 .

## 许可证

麻省理工学院

## 常见问题

### @fluid-app/api-client 是什么？

JavaScript 应用程序的 Fluid Commerce API 客户端

### 如何安装 @fluid-app/api-client？

在项目目录运行 npm install @fluid-app/api-client，或使用 pnpm add / yarn add / bun add。

### @fluid-app/api-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fluid-app/api-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @fluid-app/api-client 可以商用吗？

@fluid-app/api-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fluid-app/api-client 的下载量有多少？

根据 npm 官方下载统计，@fluid-app/api-client 在 2026/10/15 – 2026/11/13 这 30 天内被下载 21,263 次，日均约 709 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fluid-app/api-client 还在维护吗？

最新版本 0\.1\.19 发布于 2025/07/16（1\.3 年前）；至今共发布 20 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/03/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。