用途
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 章节)