SuperAPI AI 工具集

sdk-adapter

编程与开发

查看项目

更新于 10-16 11:29

技能介绍

用途

sdk-adapter 用于为新应用创建 SDK 适配器,完成与支持平台的集成。当需要接入新的 Skill Recordings 产品、实现 SupportIntegration 接口或搭建适配器脚手架时使用。设计目标是让新增应用“一个 skill init 即可接入”:每个应用只要实现 SupportIntegration 接口即可完成对接。

架构概览

支持平台与应用集成之间通过 HTTPS + HMAC-SHA256 通信:

  • 支持平台侧:Agent Tool(lookupUser、processRefund 等)与 IntegrationClient(负责签名请求)。
  • 应用集成侧:createSupportHandler(验证签名)与 SupportIntegration(你的实现)。
  • 请求携带 x-signature 头。

SupportIntegration 接口

从 @skillrecordings/sdk/integration 导入:

import type { SupportIntegration } from '@skillrecordings/sdk/integration'

export interface SupportIntegration {
  // Required: User lookup
  lookupUser(email: string): Promise<User | null>
  getPurchases(userId: string): Promise<Purchase[]>

  // Optional: Subscriptions
  getSubscriptions?(userId: string): Promise<Subscription[]>

  // Required: Access management
  revokeAccess(params: {
    purchaseId: string
    reason: string
    refundId: string
  }): Promise<ActionResult>

  transferPurchase(params: {
    purchaseId: string
    fromUserId: string
    toEmail: string
  }): Promise<ActionResult>

  // Required: Auth
  generateMagicLink(params: {
    email: string
    expiresIn: number
  }): Promise<{ url: string }>

  // Optional: Profile updates
  updateEmail?(params: { userId: string; newEmail: string }): Promise<ActionResult>
  updateName?(params: { userId: string; newName: string }): Promise<ActionResult>

  // Optional: Team features
  getClaimedSeats?(bulkCouponId: string): Promise<ClaimedSeat[]>
}

类型定义

从 @skillrecordings/sdk/types 导入:

export interface User {
  id: string
  email: string
  name?: string
  createdAt?: Date
}

export interface Purchase {
  id: string
  userId: string
  productId: string
  productName?: string
  purchasedAt: Date
  amount: number
  currency?: string
  stripeChargeId?: string
  status: 'active' | 'refunded' | 'transferred'
}

export interface Subscription {
  id: string
  userId: string
  productId: string
  status: 'active' | 'canceled' | 'past_due' | 'trialing'
  currentPeriodEnd: Date
  cancelAtPeriodEnd: boolean
}

export interface ActionResult {
  success: boolean
  message?: string
}

HMAC 签名验证

来自支持平台的请求包含 x-signature 头:

x-signature: timestamp=[PHONE],v1=<hex_signature>

待签名载荷:${timestamp}.${JSON.stringify(body)}

处理器负责验证:

  • 签名等于 HMAC-SHA256(payload, webhook_secret)
  • 时间戳在 5 分钟以内(防重放)

Next.js 路由处理器

// app/api/support/route.ts
import { createSupportHandler } from '@skillrecordings/sdk/handler'
import type { SupportIntegration } from '@skillrecordings/sdk/integration'

const integration: SupportIntegration = {
  async lookupUser(email) {
    return db.user.findUnique({ where: { email } })
  },
  async getPurchases(userId) {
    return db.purchase.findMany({ where: { userId } })
  },
  async revokeAccess({ purchaseId, reason, refundId }) {
    await db.purchase.update({
      where: { id: purchaseId },
      data: { status: 'refunded', refundReason: reason, stripeRefundId: refundId }
    })
    return { success: true }
  },
  async transferPurchase({ purchaseId, fromUserId, toEmail }) {
    const toUser = await db.user.findUnique({ where: { email: toEmail } })
    await db.purchase.update({
      where: { id: purchaseId },
      data: { userId: toUser.id, status: 'transferred' }
    })
    return { success: true }
  },
  async generateMagicLink({ email, expiresIn }) {
    const token = await createMagicToken(email, expiresIn)
    return { url: `${APP_URL}/auth/magic?token=${token}` }
  },
}

// Create handler - handles signature verification automatically
const handler = createSupportHandler(integration, {
  webhookSecret: process.env.SUPPORT_WEBHOOK_SECRET!,
})

export async function POST(request: Request) {
  return handler(request)
}

应用注册

每个应用需要在 apps 表中有一条记录:

{
  slug: 'total-typescript',
  name: 'Total TypeScript',
  front_inbox_id: 'inb_xxx',
  stripe_account_id: 'acct_xxx',
  integration_base_url: 'https://totaltypescript.com/api/support',
  webhook_secret: 'whsec_xxx',  // Shared secret for HMAC signing
  capabilities: ['refund', 'transfer', 'magic_link'],
  auto_approve_refund_days: 30,
  auto_approve_transfer_days: 14,
  escalation_slack_channel: 'C0XXXXXXX',
}

文件位置

文件 用途
packages/sdk/src/types.ts User、Purchase、Subscription、ActionResult 类型
packages/sdk/src/integration.ts SupportIntegration 接口
packages/sdk/src/handler.ts createSupportHandler 工厂
packages/sdk/src/client.ts IntegrationClient(供 core 使用)
packages/core/src/services/app-registry.ts 应用配置查询,带 5 分钟 TTL 缓存

包导出

// Types
import type { User, Purchase, ActionResult } from '@skillrecordings/sdk/types'

// Interface
import type { SupportIntegration } from '@skillrecordings/sdk/integration'

// Handler (for app implementations)
import { createSupportHandler } from '@skillrecordings/sdk/handler'

// Client (used internally by core)
import { IntegrationClient } from '@skillrecordings/sdk/client'

参考文档

完整细节参见:

  • docs/support-app-prd/67-sdk.md
  • docs/ARCHITECTURE.md(SDK Integration Flow 章节)