@fluid-app/ api-客户端

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

安装

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

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

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

使用量

基本示例

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规格生成.

墨盒管理

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

公平分享分析

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函数都遵循一个一致的模式:

// 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支持,包括:

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 客户端行为 :

示例

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

所有环境变量都使用 T3 信封 ,并提供合适的类型脚本.

地方发展

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

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

您可以以 :

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

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

许可证

麻省理工学院