知识库首页 模版 creem.ts.md

creem.ts

本地来源：模版/template/模版文档对比说明/07-类型定义/creem.ts.md

Creem类型定义 (types/creem.ts) 逐行分析

文件概述

这个文件定义了与 Creem 支付系统相关的所有 TypeScript 类型。它涵盖了事件类型、客户信息、产品信息、订阅管理、订单处理和 Webhook 事件等完整的支付流程类型定义。

事件类型定义分析

export type CreemEventType =
  | "checkout.completed"
  | "refund.created"
  | "subscription.active"
  | "subscription.trialing"
  | "subscription.canceled"
  | "subscription.paid"
  | "subscription.expired"
  | "subscription.unpaid"
  | "subscription.update";

支付相关事件

  • "checkout.completed": 结账流程完成
  • "refund.created": 退款创建

订阅状态事件

  • "subscription.active": 订阅激活
  • "subscription.trialing": 订阅试用期
  • "subscription.canceled": 订阅取消
  • "subscription.paid": 订阅付费
  • "subscription.expired": 订阅过期
  • "subscription.unpaid": 订阅未付费
  • "subscription.update": 订阅更新

这些事件类型用于 Webhook 处理，确保系统能够响应 Creem 支付系统的各种状态变化。

客户信息类型分析

export interface CreemCustomer {
  id: string;
  object: "customer";
  email: string;
  name: string;
  country: string;
  created_at: string;
  updated_at: string;
  mode: string;
}

字段说明

  • id: 客户唯一标识符
  • object: 类型标识，固定为 "customer"
  • email: 客户邮箱地址
  • name: 客户姓名
  • country: 客户所在国家
  • created_at: 创建时间（ISO 字符串）
  • updated_at: 更新时间（ISO 字符串）
  • mode: 运行模式（测试或生产）

产品信息类型分析

export interface CreemProduct {
  id: string;
  name: string;
  description: string;
  image_url: string | null;
  price: number;
  currency: string;
  billing_type: "recurring" | "one_time";
  billing_period?: string;
  status: "active" | "inactive";
  tax_mode: "inclusive" | "exclusive";
  tax_category: string;
  default_success_url: string;
  created_at: string;
  updated_at: string;
  mode: string;
  metadata?: {
    credits?: number; // Number of credits this product provides
    product_type?: "subscription" | "credits"; // Type of the product
  };
}

基础信息

  • id: 产品唯一标识符
  • name: 产品名称
  • description: 产品描述
  • image_url: 产品图片URL（可选）

价格信息

  • price: 产品价格
  • currency: 货币类型
  • billing_type: 计费类型（订阅或一次性）
  • billing_period: 计费周期（可选）

状态和税务

  • status: 产品状态（活跃或不活跃）
  • tax_mode: 税务模式（含税或不含税）
  • tax_category: 税务类别

元数据

  • metadata.credits: 产品提供的积分数量
  • metadata.product_type: 产品类型（订阅或积分）

订阅信息类型分析

export interface CreemSubscription {
  id: string;
  object: "subscription";
  product: string | CreemProduct;
  customer: string | CreemCustomer;
  collection_method: "charge_automatically";
  status: "active" | "canceled" | "expired";
  canceled_at: string | null;
  current_period_start_date?: string;
  current_period_end_date?: string;
  created_at: string;
  updated_at: string;
  metadata?: Record<string, any>;
  mode: string;
}

关联关系

  • product: 产品信息（可以是ID或完整对象）
  • customer: 客户信息（可以是ID或完整对象）

订阅状态

  • status: 订阅状态（活跃、取消、过期）
  • canceled_at: 取消时间（可选）
  • current_period_start_date: 当前周期开始日期
  • current_period_end_date: 当前周期结束日期

付费方式

  • collection_method: 收款方式（自动扣费）

订单信息类型分析

export interface CreemOrder {
  id: string;
  customer: string;
  product: string;
  amount: number;
  currency: string;
  status: "paid" | "pending" | "failed";
  type: "recurring" | "one_time";
  created_at: string;
  updated_at: string;
  mode: string;
  metadata: {
    user_id: string; // User ID of the customer
    product_type: "subscription" | "credits"; // Type of the product
    credits?: number; // Number of credits this order provides
  };
}

订单基础信息

  • id: 订单唯一标识符
  • customer: 客户ID
  • product: 产品ID
  • amount: 订单金额
  • currency: 货币类型

订单状态

  • status: 订单状态（已付费、待处理、失败）
  • type: 订单类型（订阅或一次性）

元数据

  • metadata.user_id: 用户ID
  • metadata.product_type: 产品类型
  • metadata.credits: 积分数量

结账流程类型分析

export interface CreemCheckout {
  id: string;
  object: "checkout";
  request_id: string;
  order: CreemOrder;
  product: CreemProduct;
  customer: CreemCustomer;
  subscription?: CreemSubscription;
  custom_fields: any[];
  status: "completed" | "pending" | "failed";
  metadata?: Record<string, any>;
  mode: string;
}

结账信息

  • id: 结账会话ID
  • object: 对象类型标识
  • request_id: 请求ID
  • status: 结账状态

关联数据

  • order: 订单信息
  • product: 产品信息
  • customer: 客户信息
  • subscription: 订阅信息（可选）
  • custom_fields: 自定义字段

Webhook事件类型分析

export interface CreemWebhookEvent {
  id: string;
  eventType: CreemEventType;
  created_at: number;
  object: CreemCheckout | CreemSubscription | any;
  mode: string;
}

事件信息

  • id: 事件唯一标识符
  • eventType: 事件类型（使用前面定义的联合类型）
  • created_at: 事件创建时间（时间戳）
  • object: 事件相关对象（可以是结账或订阅等）
  • mode: 运行模式

积分交易类型分析

export interface CreditTransaction {
  id: string;
  customer_id: string;
  amount: number;
  type: "add" | "subtract";
  description?: string;
  creem_order_id?: string;
  created_at: string;
  metadata?: Record<string, any>;
}

交易信息

  • id: 交易唯一标识符
  • customer_id: 客户ID
  • amount: 交易金额
  • type: 交易类型（增加或减少）
  • description: 交易描述（可选）
  • creem_order_id: 关联的 Creem 订单ID（可选）

设计模式分析

联合类型模式

  • 使用联合类型定义有限的选择集合
  • 提供类型安全的枚举值
  • 便于编译时检查

接口继承模式

  • 使用接口定义数据结构
  • 提供清晰的数据契约
  • 支持类型检查和智能提示

可选属性模式

  • 使用 ? 标记可选属性
  • 处理不同场景下的数据变化
  • 提供灵活的数据结构

泛型和Record类型

  • 使用 Record<string, any> 处理动态数据
  • 提供类型安全的键值对结构
  • 支持元数据扩展

最佳实践总结

  1. 类型安全：完整的 TypeScript 类型定义
  2. 可扩展性：使用元数据字段支持扩展
  3. 一致性：统一的命名规范和结构
  4. 灵活性：支持ID引用和完整对象两种模式
  5. 文档化：详细的注释说明字段用途
  6. 错误处理：明确的状态类型定义
  7. 集成友好：与 Creem API 保持一致

使用示例

// 处理 Webhook 事件
function handleWebhookEvent(event: CreemWebhookEvent) {
  switch (event.eventType) {
    case "checkout.completed":
      // 处理结账完成
      break;
    case "subscription.active":
      // 处理订阅激活
      break;
    default:
      // 处理其他事件
  }
}

// 创建积分交易
const transaction: CreditTransaction = {
  id: "txn_123",
  customer_id: "cust_456",
  amount: 100,
  type: "add",
  description: "购买积分包",
  created_at: new Date().toISOString(),
};

这个类型定义文件是整个支付系统的基础，它确保了类型安全、数据一致性和良好的开发体验。通过详细的类型定义，开发者可以更好地理解和使用 Creem 支付系统的各种功能。

本文档为站内渲染。原始文件本地路径：saas/source/templates/模版-template-模版文档对比说明-07-类型定义-creem-ts-a4e92b.md（仅本地保留，不入库不部署）