# Creem 服务端 API 认证密钥
CREEM_API_KEY="creem_test_xxxxxxxxxxxxxxxxxxxxxxxx"

# Creem Webhook 原始请求体签名校验密钥
CREEM_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxxxxxx"

# 运行模式: test 或 live
CREEM_MODE="test"

ngrok http 3000

npm install creem

// app/lib/creem.server.ts
import { Creem } from "creem";
import crypto from "node:crypto";

export interface CreateProductParams {
  name: string;
  description: string;
  price: number;
}

export interface CreemProductResult {
  id: string;
}

export interface CreateCheckoutParams {
  productId: string;
  customerEmail?: string;
  successUrl: string;
  metadata: {
    userId: string;
    productId: string;
    [key: string]: any;
  };
}

export interface CreemCheckoutResult {
  id: string;
  checkoutUrl?: string;
  status?: string;
}

export interface CreemCheckoutEntity {
  id: string;
  status: "pending" | "processing" | "completed" | "expired" | string;
  checkoutUrl?: string;
  product?: string | { id: string };
  order?: { id: string } | null;
  customer?: string | { id: string } | null;
  metadata?: {
    userId?: string;
    productId?: string;
    [key: string]: any;
  };
  [key: string]: any;
}

export interface CreemClient {
  createProduct(params: CreateProductParams): Promise<CreemProductResult>;
  updateProductPrice(productId: string, price: number): Promise<void>;
  createCheckout(params: CreateCheckoutParams): Promise<CreemCheckoutResult>;
  getCheckout(checkoutId: string): Promise<CreemCheckoutEntity>;
  searchTransactions?(orderId: string): Promise<any[]>;
  refundPayment?(transactionId: string): Promise<{ status: string }>;
}

// app/lib/creem.server.ts (续)
class DefaultCreemClient implements CreemClient {
  private sdk: Creem;

  constructor(apiKey: string) {
    this.sdk = new Creem({
      apiKey,
      server: process.env.CREEM_MODE === "live" ? "production" : "test",
    });
  }

  async createProduct(params: CreateProductParams): Promise<CreemProductResult> {
    try {
      const product = await this.sdk.products.create({
        name: params.name,
        description: params.description,
        price: params.price,
        currency: "USD",
        billingType: "onetime",
        taxCategory: "digital-goods-service",
        taxMode: "exclusive",
      });
      return { id: product.id };
    } catch (err) {
      throw new Error(`Creem 创建商品失败：${err instanceof Error ? err.message : String(err)}`);
    }
  }

  async updateProductPrice(productId: string, price: number): Promise<void> {
    try {
      await this.sdk.products.update(productId, { price });
    } catch (err) {
      throw new Error(`Creem 更新价格失败：${err instanceof Error ? err.message : String(err)}`);
    }
  }

  async createCheckout(params: CreateCheckoutParams): Promise<CreemCheckoutResult> {
    try {
      const checkout = await this.sdk.checkouts.create({
        productId: params.productId,
        customer: params.customerEmail ? { email: params.customerEmail } : undefined,
        successUrl: params.successUrl,
        metadata: params.metadata,
      });
      return {
        id: checkout.id,
        checkoutUrl: checkout.checkoutUrl,
        status: checkout.status,
      };
    } catch (err) {
      throw new Error(`Creem 创建结账会话失败：${err instanceof Error ? err.message : String(err)}`);
    }
  }

  async getCheckout(checkoutId: string): Promise<CreemCheckoutEntity> {
    try {
      const checkout = await this.sdk.checkouts.retrieve(checkoutId);
      return checkout as CreemCheckoutEntity;
    } catch (err) {
      throw new Error(`Creem 查询结账信息失败：${err instanceof Error ? err.message : String(err)}`);
    }
  }

  async searchTransactions(orderId: string): Promise<any[]> {
    try {
      const response = await this.sdk.transactions.search(undefined, orderId);
      const items: any[] = [];
      for await (const page of response) {
        if (page.result?.items) {
          items.push(...page.result.items);
        }
      }
      return items;
    } catch (err) {
      throw new Error(`Creem 查询交易列表失败：${err instanceof Error ? err.message : String(err)}`);
    }
  }

  async refundPayment(transactionId: string): Promise<{ status: string }> {
    try {
      const res = await this.sdk.transactions.refund({ transactionId });
      return { status: res.status };
    } catch (err) {
      throw new Error(`Creem 发起退款失败：${err instanceof Error ? err.message : String(err)}`);
    }
  }
}

let activeClient: CreemClient | null = null;

export function setCreemClient(client: CreemClient | null) {
  activeClient = client;
}

export function getCreemClient(): CreemClient {
  if (activeClient) {
    return activeClient;
  }
  const apiKey = process.env.CREEM_API_KEY;
  if (!apiKey || !apiKey.trim()) {
    throw new Error("环境变量缺少 CREEM_API_KEY 配置");
  }
  return new DefaultCreemClient(apiKey.trim());
}

// app/services/creemProductService.ts
import { getCreemClient } from "~/lib/creem.server";

export interface SyncProductParams {
  id: number;
  title: string;
  description: string;
  price: number;
  creemProductId: string | null;
}

export async function syncProductOnPublish(
  product: SyncProductParams
): Promise<string | null> {
  // 免费产品无需在 Creem 上架
  if (product.price <= 0) {
    return null;
  }

  // 若已存在 Creem 商品映射则保持复用
  if (product.creemProductId) {
    return product.creemProductId;
  }

  const client = getCreemClient();
  const created = await client.createProduct({
    name: product.title,
    description: product.description,
    price: product.price,
  });

  return created.id;
}

// app/services/creemProductService.ts (续)
export async function syncProductOnPriceChange(
  product: SyncProductParams & { isPublished: boolean },
  newPrice: number
): Promise<{ creemProductId: string | null }> {
  if (newPrice <= 0) {
    return { creemProductId: product.creemProductId };
  }

  const client = getCreemClient();

  if (product.creemProductId) {
    await client.updateProductPrice(product.creemProductId, newPrice);
    return { creemProductId: product.creemProductId };
  }

  if (product.isPublished) {
    const created = await client.createProduct({
      name: product.title,
      description: product.description,
      price: newPrice,
    });
    return { creemProductId: created.id };
  }

  return { creemProductId: null };
}

// app/routes/products.$id.purchase.ts
import { redirect } from "react-router";
import { getCreemClient } from "~/lib/creem.server";
import { findProductById } from "~/services/productService";
import { hasUserAccess } from "~/services/entitlementService";

export async function action({ request, params }: { request: Request; params: { id: string } }) {
  const user = await requireAuth(request);
  const product = await findProductById(Number(params.id));

  if (!product || !product.creemProductId) {
    throw new Response("产品未就绪或未设置付费商品", { status: 400 });
  }

  // 幂等防御：已拥有产品权限的用户直接回跳产品交付页
  const alreadyPurchased = await hasUserAccess(user.id, product.id);
  if (alreadyPurchased) {
    return redirect(`/products/${product.id}`);
  }

  const client = getCreemClient();
  const url = new URL(request.url);
  const successUrl = `${url.origin}/products/${product.id}/payment-callback`;

  // 创建收银台 Session，并挂载业务元数据
  const checkout = await client.createCheckout({
    productId: product.creemProductId,
    customerEmail: user.email,
    successUrl,
    metadata: {
      userId: String(user.id),
      productId: String(product.id),
    },
  });

  if (!checkout.checkoutUrl) {
    throw new Error("无法获取结账跳转链接");
  }

  return redirect(checkout.checkoutUrl);
}

// app/lib/creem.server.ts (续)
export function computeReturnSignature(
  params: URLSearchParams | string,
  apiKey: string
): string {
  const rawParams = typeof params === "string" ? new URLSearchParams(params) : params;
  const entries = Array.from(rawParams.entries());

  // 剔除名为 signature 的参数项
  const nonSigEntries = entries.filter(([k]) => k.toLowerCase() !== "signature");
  const parts = nonSigEntries.map(([k, v]) => `${k}=${v}`);
  parts.push(`salt=${apiKey}`);
  
  const signString = parts.join("|");
  return crypto.createHash("sha256").update(signString).digest("hex");
}

export function verifyReturnSignature(
  params: URLSearchParams | string,
  signature: string,
  apiKey?: string
): boolean {
  const key = apiKey ?? process.env.CREEM_API_KEY;
  if (!key || !signature) {
    return false;
  }
  const expected = computeReturnSignature(params, key);
  if (expected.length !== signature.length) {
    return false;
  }
  // 采用时间恒定比较防止时序侧信道反推
  try {
    return crypto.timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(signature, "utf8"));
  } catch {
    return false;
  }
}

// app/routes/products.$id.payment-callback.ts
import { verifyReturnSignature, getCreemClient } from "~/lib/creem.server";
import { fulfillPersonalCheckout } from "~/services/purchaseService";

export async function loader({ request, params }: { request: Request; params: { id: string } }) {
  const url = new URL(request.url);
  const signature = url.searchParams.get("signature");
  const checkoutId = url.searchParams.get("checkout_id");

  if (!signature || !checkoutId) {
    return { status: "invalid", message: "缺少回跳校验参数" };
  }

  // 1. 验证签名完整性
  const isValid = verifyReturnSignature(url.searchParams, signature);
  if (!isValid) {
    return { status: "invalid", message: "回跳签名验证失败" };
  }

  // 2. 主动调用 API 查询结账状态
  const client = getCreemClient();
  const checkout = await client.getCheckout(checkoutId);

  if (checkout.status !== "completed") {
    return { status: "pending", message: "订单正在处理中，请稍候刷新" };
  }

  const userId = Number(checkout.metadata?.userId);
  const productId = Number(checkout.metadata?.productId);
  const orderId = typeof checkout.order === "string" ? checkout.order : checkout.order?.id;
  const customerId = typeof checkout.customer === "string" ? checkout.customer : checkout.customer?.id;

  if (!userId || !productId || !orderId) {
    return { status: "error", message: "元数据缺失，无法履约" };
  }

  // 3. 执行履约逻辑
  await fulfillPersonalCheckout({
    checkoutId: checkout.id,
    orderId,
    customerId: customerId ?? null,
    userId,
    productId,
  });

  return { status: "success", productId: params.id };
}

// app/lib/creem.server.ts (续)
export function verifyWebhookSignature(payload: string, signature: string, secret?: string): boolean {
  const signingSecret = secret ?? process.env.CREEM_WEBHOOK_SECRET;
  if (!signingSecret || !signature) {
    return false;
  }
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(payload)
    .digest("hex");

  if (expected.length !== signature.length) {
    return false;
  }
  try {
    return crypto.timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(signature, "utf8"));
  } catch {
    return false;
  }
}

// app/routes/api.webhooks.creem.ts
import { verifyWebhookSignature } from "~/lib/creem.server";
import { fulfillPersonalCheckout, processRefundSettlement } from "~/services/purchaseService";

export async function action({ request }: { request: Request }) {
  if (request.method !== "POST") {
    return new Response("Method not allowed", { status: 405 });
  }

  // 必须提取原始请求体文本
  const rawPayload = await request.text();
  const signature = request.headers.get("creem-signature");

  if (!signature || !verifyWebhookSignature(rawPayload, signature)) {
    return new Response("Invalid signature", { status: 400 });
  }

  let event: any;
  try {
    event = JSON.parse(rawPayload);
  } catch {
    return new Response("Bad request", { status: 400 });
  }

  const eventType = event.event_type || event.eventType;

  switch (eventType) {
    case "checkout.completed": {
      const checkout = event.object || event.data?.object || event;
      if (checkout.status !== "completed") {
        return new Response("OK", { status: 200 });
      }

      const metaUserId = Number(checkout.metadata?.userId);
      const metaProductId = Number(checkout.metadata?.productId);
      const orderId = typeof checkout.order === "string" ? checkout.order : checkout.order?.id;
      const customerId = typeof checkout.customer === "string" ? checkout.customer : checkout.customer?.id;

      if (!metaUserId || !metaProductId || !orderId) {
        return new Response("OK", { status: 200 });
      }

      await fulfillPersonalCheckout({
        checkoutId: checkout.id,
        orderId,
        customerId: customerId ?? undefined,
        userId: metaUserId,
        productId: metaProductId,
      });
      break;
    }

    case "refund.created": {
      const refund = event.object || event.data?.object || event;
      const orderId = typeof refund.order === "string" ? refund.order : refund.order?.id;
      if (!orderId) {
        return new Response("OK", { status: 200 });
      }

      // 判定是否已达成全额退款
      const tx = refund.transaction;
      const refundedAmount = tx?.refunded_amount;
      const txAmount = tx?.amount;
      const isFull = typeof refundedAmount === "number" && typeof txAmount === "number"
        ? refundedAmount >= txAmount
        : refund.status === "succeeded";

      await processRefundSettlement({ orderId, fullyRefunded: isFull });
      break;
    }

    case "dispute.created": {
      const dispute = event.object || event.data?.object || event;
      const orderId = typeof dispute.order === "string" ? dispute.order : dispute.order?.id;
      if (orderId) {
        // 银行争议事件视同全额撤回处理
        await processRefundSettlement({ orderId, fullyRefunded: true });
      }
      break;
    }

    default:
      // 未定义事件返回 200 防止平台不断重试投递
      break;
  }

  return new Response("OK", { status: 200 });
}

// app/services/purchaseService.ts
import { eq } from "drizzle-orm";
import { db } from "~/db";
import { purchases, products } from "~/db/schema";
import { hasUserAccess, grantUserAccess } from "~/services/entitlementService";

export interface FulfillPersonalCheckoutParams {
  checkoutId: string;
  orderId: string;
  customerId?: string | null;
  userId: number;
  productId: number;
}

export async function fulfillPersonalCheckout(params: FulfillPersonalCheckoutParams) {
  const { checkoutId, orderId, customerId, userId, productId } = params;

  // 1. 查询数据库记录是否已存在
  const [existing] = await db
    .select()
    .from(purchases)
    .where(eq(purchases.creemCheckoutId, checkoutId))
    .limit(1);

  if (existing) {
    // 已经履约过的订单直接补充确保权限状态
    const hasAccess = await hasUserAccess(userId, productId);
    if (!hasAccess) {
      await grantUserAccess(userId, productId);
    }
    return existing;
  }

  // 2. 获取当时产品基准价格
  const [product] = await db
    .select()
    .from(products)
    .where(eq(products.id, productId))
    .limit(1);

  if (!product) {
    throw new Error("关联产品不存在");
  }

  // 3. 写入购买记录（creemCheckoutId 具有唯一约束）
  try {
    await db.insert(purchases).values({
      userId,
      productId,
      pricePaid: product.price,
      creemCheckoutId: checkoutId,
      creemOrderId: orderId,
      creemCustomerId: customerId ?? null,
    });
  } catch (err: any) {
    // 捕获并发冲突，若已被另一通道写入则视为成功
    const [secondCheck] = await db
      .select()
      .from(purchases)
      .where(eq(purchases.creemCheckoutId, checkoutId))
      .limit(1);

    if (!secondCheck) {
      throw err;
    }
  }

  // 4. 激活用户产品使用权限
  const hasAccess = await hasUserAccess(userId, productId);
  if (!hasAccess) {
    await grantUserAccess(userId, productId);
  }
}

// app/services/purchaseService.ts (续)
export async function requestPersonalRefund(orderId: string): Promise<{ success: boolean; status: string }> {
  const client = getCreemClient();

  // 1. 获取购买单据并校验在途状态
  const [purchase] = await db
    .select()
    .from(purchases)
    .where(eq(purchases.creemOrderId, orderId))
    .limit(1);

  if (!purchase) {
    throw new Error("未找到关联购买单据");
  }

  if (purchase.refundedAt !== null) {
    throw new Error("该订单已完成退款，不可重复申请");
  }

  if (purchase.refundRequestedAt !== null) {
    throw new Error("退款申请正在处理中，请勿重复操作");
  }

  // 2. 标记退款在途并冻结权限，防范并发重复提交
  await db
    .update(purchases)
    .set({ refundRequestedAt: new Date() })
    .where(eq(purchases.id, purchase.id));

  // 临时冻结用户针对该产品的业务权益（置为暂停/只读状态）
  await freezeUserAccess(purchase.userId, purchase.productId);

  // 3. 根据 orderId 检索底层交易单据
  let transactions: any[];
  try {
    transactions = await client.searchTransactions(orderId);
  } catch (err: any) {
    // 接口异常时回滚申请标记并解冻权限
    await rollbackRefundRequest(purchase.id, purchase.userId, purchase.productId);
    throw new Error(`查询支付交易失败：${err.message || String(err)}`);
  }

  if (!transactions || transactions.length === 0) {
    await rollbackRefundRequest(purchase.id, purchase.userId, purchase.productId);
    throw new Error("未找到关联支付交易单据");
  }

  const transactionId = transactions[0].id;

  // 4. 调用 Creem 发起退款
  let result: { status: string };
  try {
    result = await client.refundPayment(transactionId);
  } catch (err: any) {
    await rollbackRefundRequest(purchase.id, purchase.userId, purchase.productId);
    throw new Error(`发起退款申请失败：${err.message || String(err)}`);
  }

  // 5. 根据网关响应状态进行流转分支
  if (result.status === "failed" || result.status === "canceled") {
    // 退款失败：回滚在途标记并解冻权益，恢复正常使用状态
    await rollbackRefundRequest(purchase.id, purchase.userId, purchase.productId);
    throw new Error("退款已被渠道拒绝，权益已恢复，可稍后重试");
  }

  if (result.status === "succeeded") {
    // 同步成功：直接执行最终结算与权益注销
    await processRefundSettlement({ orderId, fullyRefunded: true });
    return { success: true, status: "succeeded" };
  }

  // 保持 pending 在途冻结态，等待异步 Webhook 到达后执行最终结算
  return { success: true, status: result.status };
}

/**
 * 申请异常或失败时的回滚与解冻逻辑
 */
async function rollbackRefundRequest(purchaseId: number, userId: number, productId: number): Promise<void> {
  await db
    .update(purchases)
    .set({ refundRequestedAt: null })
    .where(eq(purchases.id, purchaseId));

  // 解除权益冻结，恢复正常访问
  await unfreezeUserAccess(userId, productId);
}

// app/services/purchaseService.ts (续)
import { purchases, userEntitlements } from "~/db/schema";
import { and, ne, isNull } from "drizzle-orm";

export async function processRefundSettlement(params: {
  orderId: string;
  fullyRefunded: boolean;
}): Promise<void> {
  const { orderId, fullyRefunded } = params;

  const [purchase] = await db
    .select()
    .from(purchases)
    .where(eq(purchases.creemOrderId, orderId))
    .limit(1);

  if (!purchase || purchase.refundedAt !== null) {
    return;
  }

  // 1. 写入终态退款时间，清除在途申请标记
  await db
    .update(purchases)
    .set({
      refundedAt: new Date(),
      refundRequestedAt: null,
    })
    .where(eq(purchases.id, purchase.id));

  // 2. 仅在退款金额达到整笔实付（全额退款）时收回权限
  if (fullyRefunded) {
    // 检查该用户针对该产品是否存在其他仍有效的购买记录
    const otherPurchases = await db
      .select()
      .from(purchases)
      .where(
        and(
          eq(purchases.userId, purchase.userId),
          eq(purchases.productId, purchase.productId),
          ne(purchases.id, purchase.id),
          isNull(purchases.refundedAt)
        )
      );

    // 无其他有效订单时移除产品使用权限
    if (otherPurchases.length === 0) {
      await db
        .delete(userEntitlements)
        .where(
          and(
            eq(userEntitlements.userId, purchase.userId),
            eq(userEntitlements.productId, purchase.productId)
          )
        );
    }
  }
}