跳转到主要内容

​
SDKs 和库

Waffo Pancake 提供官方 TypeScript SDK 和直接 API 访问。

​
TypeScript SDK

@waffo/pancake-ts

npm 上的官方 TypeScript SDK

​
安装

npm install @waffo/pancake-ts

​
特性

  • 零运行时依赖，ESM + CJS，Node >= 20
  • 自动请求签名和确定性幂等键
  • 完整的 TypeScript 类型定义（15 个枚举，40+ 接口）
  • 内置公钥的 Webhook 签名验证（测试/生产）

​
快速开始

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

// 创建商店
const { store } = await client.stores.create({ name: "My Store" });

// 创建一次性商品
const { product } = await client.onetimeProducts.create({
  storeId: store.id,
  name: "E-Book: TypeScript Handbook",
  prices: {
    USD: { amount: 2900, taxIncluded: false, taxCategory: "digital_goods" },
  },
});

// 创建结账会话
const session = await client.checkout.createSession({
  storeId: store.id,
  productId: product.id,
  productType: "onetime",
  currency: "USD",
});
// => 将买家重定向到 session.checkoutUrl

​
配置

参数类型必填说明
merchantIdstring是您的商户 ID
privateKeystring是RSA 私钥（PEM、base64 或原始格式 — 自动标准化）
baseUrlstring否API 基础 URL（默认：生产环境）
fetchtypeof fetch否自定义 fetch 实现

​
可用资源

命名空间方法说明
client.storescreate() update() delete()商店管理
client.onetimeProductscreate() update() publish() updateStatus()一次性商品 CRUD
client.subscriptionProductscreate() update() publish() updateStatus()订阅商品 CRUD
client.subscriptionProductGroupscreate() update() delete() publish()商品分组（共享试用）
client.orderscancelSubscription()订单管理
client.checkoutcreateSession()创建结账会话
client.graphqlquery<T>()类型化 GraphQL 查询

​
结账集成

import { WaffoPancake, CheckoutSessionProductType } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

// 第一步：为买家签发会话令牌
const { token } = await client.auth.issueSessionToken({
  storeId: "store_xxx",
  buyerIdentity: "customer@example.com",
});

// 第二步：创建结账会话
const session = await client.checkout.createSession({
  storeId: "store_xxx",
  productId: "prod_xxx",
  productType: CheckoutSessionProductType.Onetime,
  currency: "USD",
  buyerEmail: "customer@example.com",
  successUrl: "https://example.com/thank-you",
});

// 第三步：在新标签页打开结账（推荐）
// 前端：window.open(session.checkoutUrl, "_blank", "noopener,noreferrer");

​
Webhook 验证

import { verifyWebhook, WebhookEventType } from "@waffo/pancake-ts";

// Express（使用原始 body — 解析后的 JSON 会破坏签名验证）
app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = verifyWebhook(
      req.body.toString("utf-8"),
      req.headers["x-waffo-signature"] as string,
    );
    res.status(200).send("OK");

    switch (event.eventType) {
      case WebhookEventType.OrderCompleted:
        // 处理订单完成
        break;
      case WebhookEventType.SubscriptionActivated:
        // 处理订阅激活
        break;
    }
  } catch {
    res.status(401).send("Invalid signature");
  }
});

// Next.js App Router
export async function POST(request: Request) {
  const body = await request.text();
  const sig = request.headers.get("x-waffo-signature");
  try {
    const event = verifyWebhook(body, sig);
    // 处理事件 ...
    return new Response("OK");
  } catch {
    return new Response("Invalid signature", { status: 401 });
  }
}

​
错误处理

import { WaffoPancakeError } from "@waffo/pancake-ts";

try {
  await client.stores.create({ name: "" });
} catch (err) {
  if (err instanceof WaffoPancakeError) {
    console.log(err.status);  // 400
    console.log(err.errors);  // [{ message: "...", layer: "store" }, ...]
  }
}

​
直接 API 访问

你也可以直接使用 REST 和 GraphQL API。API Key 认证由 SDK 自动处理，无需手动设置请求头。 
// 创建商品
const { product } = await client.onetimeProducts.create({
  storeId: "your-store-uuid",
  name: "My Product",
  prices: {
    USD: { amount: 2900, taxIncluded: false, taxCategory: "saas" },
  },
});

// 通过 GraphQL 查询数据
const data = await client.graphql.query<{ stores: Array<{ id: string; name: string; status: string }> }>(
  `{ stores { id name status } }`
);

​
SDK 路线图

语言状态
Node.js / TypeScript已发布 — @waffo/pancake-ts
Python计划中
Go计划中
PHP计划中

​
框架指南

Next.js

使用 Next.js 和 Server Actions 构建。

结账会话

通过编程方式创建结账流程。

订阅

实现周期性计费。

Webhooks

接收实时事件通知。

​
API 参考

完整的端点文档：

API 参考

完整的 REST 和 GraphQL API 文档。