Billing Client SDK

安全的支付订阅 SDK，区分服务端和客户端使用。

安全架构

客户端 (浏览器) ↓ (不带 Secret) 你的应用 API (/api/billing/*) ↓ (带 Secret) Billing Platform

Text

Installation

npm install billing-client-sdk

## 使用方式

### 1. 服务端使用（Node.js / Edge Functions）

import { BillingServerClient } from 'billing-client-sdk/server';

// 在 API Route 中使用
const billing = new BillingServerClient({
  baseUrl: process.env.BILLING_PLATFORM_URL!,
  appKey: process.env.BILLING_APP_KEY!,
  appSecret: process.env.BILLING_APP_SECRET!, // 只在服务端
});

// 检查订阅
const hasSubscription = await billing.checkSubscription(userId);

// 消费积分
await billing.consumeCredits(userId, 10, 'Feature usage');

2. 创建代理 API（必需）

在你的应用中创建以下 API 路由：

// app/api/billing/products/route.ts
import { BillingServerClient } from 'billing-client-sdk/server';

const billing = new BillingServerClient({
  baseUrl: process.env.BILLING_PLATFORM_URL!,
  appKey: process.env.BILLING_APP_KEY!,
  appSecret: process.env.BILLING_APP_SECRET!,
});

export async function GET() {
  const data = await billing.getProducts();
  return Response.json(data);
}

// app/api/billing/orders/route.ts
export async function POST(req: Request) {
  const userId = await getUserId(req); // 你的认证逻辑
  const { productId, returnUrl } = await req.json();
  
  const order = await billing.createOrder(userId, productId, returnUrl);
  return Response.json(order);
}

// app/api/billing/entitlements/route.ts
export async function GET(req: Request) {
  const userId = await getUserId(req);
  const entitlements = await billing.getUserEntitlements(userId);
  return Response.json(entitlements);
}

// app/api/billing/credits/consume/route.ts
export async function POST(req: Request) {
  const userId = await getUserId(req);
  const { amount, description } = await req.json();
  
  const result = await billing.consumeCredits(userId, amount, description);
  return Response.json(result);
}

3. 前端使用（React）

// app/layout.tsx
import { BillingProvider } from 'billing-client-sdk/react';

export default function RootLayout({ children }) {
  return (
    <BillingProvider
      config={{
        apiPrefix: '/api/billing', // 你的代理 API 前缀
      }}
    >
      {children}
    </BillingProvider>
  );
}

// components/PricingPage.tsx
'use client';

import { useBilling } from 'billing-client-sdk/react';

export function PricingPage() {
  const { 
    hasSubscription, 
    creditsBalance, 
    purchaseProduct,
    loading 
  } = useBilling();

  async function handlePurchase(productId: string) {
    const paymentUrl = await purchaseProduct(
      productId,
      `${window.location.origin}/success`
    );
    window.location.href = paymentUrl;
  }

  return (
    <div>
      <p>会员: {hasSubscription ? '已激活' : '未激活'}</p>
      <p>积分: {creditsBalance}</p>
    </div>
  );
}

环境变量

# .env (服务端，不要暴露)
BILLING_PLATFORM_URL=https://billing.yourdomain.com
BILLING_APP_KEY=your_app_key
BILLING_APP_SECRET=your_app_secret  # 只在服务端使用

API 说明

服务端 API

BillingServerClient

• getProducts(type?) - 获取产品列表
• createOrder(userId, productId, returnUrl) - 创建订单
• getUserEntitlements(userId) - 获取用户权益
• consumeCredits(userId, amount, description) - 消费积分
• checkSubscription(userId) - 检查订阅状态
• getCreditsBalance(userId) - 获取积分余额
• checkFeatureAccess(userId, featureKey) - 检查功能权限

客户端 API

BillingClient (通过 useBilling hook)

• purchaseProduct(productId, returnUrl) - 购买产品
• consumeCredits(amount, description) - 消费积分
• refresh() - 刷新数据

React Hooks

useBilling()

返回:

• entitlements - 用户权益信息
• loading - 加载状态
• error - 错误信息
• hasSubscription - 是否有订阅
• creditsBalance - 积分余额
• purchaseProduct(productId, returnUrl) - 购买函数
• consumeCredits(amount, description) - 消费积分函数
• refresh() - 刷新函数