@skillrecordings/sdk 0.2.0 → 0.2.2

package/dist/adapter.d.ts

@@ -0,0 +1,43 @@
+import { Customer, Purchase, RefundRequest, RefundResult } from './types.js';
+
+/**
+ * Base adapter interface that apps must implement to integrate with the support platform.
+ *
+ * @deprecated Use SupportIntegration interface from './integration' instead.
+ * This interface is kept for backwards compatibility during migration.
+ *
+ * Migration path:
+ * - Replace AppAdapter with SupportIntegration
+ * - Rename getCustomer to lookupUser
+ * - Replace processRefund with revokeAccess
+ * - Add required methods: transferPurchase, generateMagicLink
+ *
+ * @see {@link SupportIntegration} for the new interface
+ *
+ * Each app (egghead, Total TypeScript, etc.) provides:
+ * - Customer lookup by email
+ * - Purchase history retrieval
+ * - Refund processing capabilities
+ */
+interface AppAdapter {
+    /**
+     * Fetch customer by email address
+     * @deprecated Use lookupUser from SupportIntegration
+     * @returns Customer if found, null otherwise
+     */
+    getCustomer(email: string): Promise<Customer | null>;
+    /**
+     * Fetch all purchases for a given customer
+     * @deprecated Use getPurchases from SupportIntegration (same signature)
+     * @returns Array of purchases, empty if none found
+     */
+    getPurchases(customerId: string): Promise<Purchase[]>;
+    /**
+     * Process a refund for a purchase
+     * @deprecated Use revokeAccess from SupportIntegration instead
+     * @returns RefundResult indicating success/failure
+     */
+    processRefund(request: RefundRequest): Promise<RefundResult>;
+}
+
+export type { AppAdapter };

package/dist/adapter.js

@@ -0,0 +1 @@
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+import { SupportIntegration } from './integration.js';
+import { User, Purchase, Subscription, ActionResult, ClaimedSeat } from './types.js';
+
+/**
+ * Client for calling app integration endpoints with HMAC-signed requests.
+ *
+ * Used by core to call app-specific support actions (lookupUser, getPurchases, etc.)
+ * with Stripe-style HMAC-SHA256 signature verification.
+ *
+ * @example
+ * ```typescript
+ * import { IntegrationClient } from '@skillrecordings/sdk/client'
+ *
+ * const client = new IntegrationClient({
+ *   baseUrl: 'https://totaltypescript.com',
+ *   webhookSecret: 'whsec_abc123',
+ * })
+ *
+ * const user = await client.lookupUser('test@example.com')
+ * ```
+ */
+declare class IntegrationClient implements SupportIntegration {
+    private readonly baseUrl;
+    private readonly webhookSecret;
+    constructor(config: {
+        baseUrl: string;
+        webhookSecret: string;
+    });
+    /**
+     * Generate HMAC-SHA256 signature for request body.
+     * Format: `t=<timestamp>,v1=<signature>`
+     *
+     * Signature is computed as: HMAC-SHA256(timestamp + "." + body, secret)
+     */
+    private generateSignature;
+    /**
+     * Make signed POST request to app integration endpoint.
+     */
+    private request;
+    lookupUser(email: string): Promise<User | null>;
+    getPurchases(userId: string): Promise<Purchase[]>;
+    getSubscriptions(userId: string): Promise<Subscription[]>;
+    revokeAccess(params: {
+        purchaseId: string;
+        reason: string;
+        refundId: string;
+    }): Promise<ActionResult>;
+    transferPurchase(params: {
+        purchaseId: string;
+        fromUserId: string;
+        toEmail: string;
+    }): Promise<ActionResult>;
+    generateMagicLink(params: {
+        email: string;
+        expiresIn: number;
+    }): Promise<{
+        url: string;
+    }>;
+    updateEmail(params: {
+        userId: string;
+        newEmail: string;
+    }): Promise<ActionResult>;
+    updateName(params: {
+        userId: string;
+        newName: string;
+    }): Promise<ActionResult>;
+    getClaimedSeats(bulkCouponId: string): Promise<ClaimedSeat[]>;
+}
+
+export { IntegrationClient };

package/dist/client.js

@@ -0,0 +1,85 @@
+// src/client.ts
+import { createHmac } from "crypto";
+var IntegrationClient = class {
+  baseUrl;
+  webhookSecret;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.webhookSecret = config.webhookSecret;
+  }
+  /**
+   * Generate HMAC-SHA256 signature for request body.
+   * Format: `t=<timestamp>,v1=<signature>`
+   *
+   * Signature is computed as: HMAC-SHA256(timestamp + "." + body, secret)
+   */
+  generateSignature(body) {
+    const timestamp = Math.floor(Date.now() / 1e3);
+    const signedPayload = `${timestamp}.${body}`;
+    const signature = createHmac("sha256", this.webhookSecret).update(signedPayload).digest("hex");
+    return `t=${timestamp},v1=${signature}`;
+  }
+  /**
+   * Make signed POST request to app integration endpoint.
+   */
+  async request(endpoint, payload) {
+    const body = JSON.stringify(payload);
+    const signature = this.generateSignature(body);
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Support-Signature": signature
+      },
+      body
+    });
+    if (!response.ok) {
+      let errorMessage;
+      try {
+        const errorBody = await response.json();
+        if (errorBody?.error) {
+          errorMessage = errorBody.error;
+        }
+      } catch {
+      }
+      if (errorMessage) {
+        throw new Error(errorMessage);
+      }
+      throw new Error(
+        `Integration request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    return await response.json();
+  }
+  async lookupUser(email) {
+    return this.request("/api/support/lookup-user", { email });
+  }
+  async getPurchases(userId) {
+    return this.request("/api/support/get-purchases", { userId });
+  }
+  async getSubscriptions(userId) {
+    return this.request("/api/support/get-subscriptions", { userId });
+  }
+  async revokeAccess(params) {
+    return this.request("/api/support/revoke-access", params);
+  }
+  async transferPurchase(params) {
+    return this.request("/api/support/transfer-purchase", params);
+  }
+  async generateMagicLink(params) {
+    return this.request("/api/support/generate-magic-link", params);
+  }
+  async updateEmail(params) {
+    return this.request("/api/support/update-email", params);
+  }
+  async updateName(params) {
+    return this.request("/api/support/update-name", params);
+  }
+  async getClaimedSeats(bulkCouponId) {
+    return this.request("/api/support/get-claimed-seats", { bulkCouponId });
+  }
+};
+export {
+  IntegrationClient
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import { createHmac } from 'node:crypto'\nimport type {\n  ActionResult,\n  ClaimedSeat,\n  Purchase,\n  Subscription,\n  SupportIntegration,\n  User,\n} from './integration'\n\n/**\n * Client for calling app integration endpoints with HMAC-signed requests.\n *\n * Used by core to call app-specific support actions (lookupUser, getPurchases, etc.)\n * with Stripe-style HMAC-SHA256 signature verification.\n *\n * @example\n * ```typescript\n * import { IntegrationClient } from '@skillrecordings/sdk/client'\n *\n * const client = new IntegrationClient({\n *   baseUrl: 'https://totaltypescript.com',\n *   webhookSecret: 'whsec_abc123',\n * })\n *\n * const user = await client.lookupUser('test@example.com')\n * ```\n */\nexport class IntegrationClient implements SupportIntegration {\n  private readonly baseUrl: string\n  private readonly webhookSecret: string\n\n  constructor(config: { baseUrl: string; webhookSecret: string }) {\n    // Strip trailing slash for consistent URL construction\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '')\n    this.webhookSecret = config.webhookSecret\n  }\n\n  /**\n   * Generate HMAC-SHA256 signature for request body.\n   * Format: `t=<timestamp>,v1=<signature>`\n   *\n   * Signature is computed as: HMAC-SHA256(timestamp + \".\" + body, secret)\n   */\n  private generateSignature(body: string): string {\n    const timestamp = Math.floor(Date.now() / 1000)\n    const signedPayload = `${timestamp}.${body}`\n    const signature = createHmac('sha256', this.webhookSecret)\n      .update(signedPayload)\n      .digest('hex')\n\n    return `t=${timestamp},v1=${signature}`\n  }\n\n  /**\n   * Make signed POST request to app integration endpoint.\n   */\n  private async request<T>(endpoint: string, payload: unknown): Promise<T> {\n    const body = JSON.stringify(payload)\n    const signature = this.generateSignature(body)\n\n    const response = await fetch(`${this.baseUrl}${endpoint}`, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        'X-Support-Signature': signature,\n      },\n      body,\n    })\n\n    if (!response.ok) {\n      // Try to extract error message from response body\n      let errorMessage: string | undefined\n      try {\n        const errorBody = (await response.json()) as { error?: string }\n        if (errorBody?.error) {\n          errorMessage = errorBody.error\n        }\n      } catch {\n        // If JSON parsing fails, ignore and use status text\n      }\n\n      if (errorMessage) {\n        throw new Error(errorMessage)\n      }\n      throw new Error(\n        `Integration request failed: ${response.status} ${response.statusText}`\n      )\n    }\n\n    return (await response.json()) as T\n  }\n\n  async lookupUser(email: string): Promise<User | null> {\n    return this.request('/api/support/lookup-user', { email })\n  }\n\n  async getPurchases(userId: string): Promise<Purchase[]> {\n    return this.request('/api/support/get-purchases', { userId })\n  }\n\n  async getSubscriptions(userId: string): Promise<Subscription[]> {\n    return this.request('/api/support/get-subscriptions', { userId })\n  }\n\n  async revokeAccess(params: {\n    purchaseId: string\n    reason: string\n    refundId: string\n  }): Promise<ActionResult> {\n    return this.request('/api/support/revoke-access', params)\n  }\n\n  async transferPurchase(params: {\n    purchaseId: string\n    fromUserId: string\n    toEmail: string\n  }): Promise<ActionResult> {\n    return this.request('/api/support/transfer-purchase', params)\n  }\n\n  async generateMagicLink(params: {\n    email: string\n    expiresIn: number\n  }): Promise<{ url: string }> {\n    return this.request('/api/support/generate-magic-link', params)\n  }\n\n  async updateEmail(params: {\n    userId: string\n    newEmail: string\n  }): Promise<ActionResult> {\n    return this.request('/api/support/update-email', params)\n  }\n\n  async updateName(params: {\n    userId: string\n    newName: string\n  }): Promise<ActionResult> {\n    return this.request('/api/support/update-name', params)\n  }\n\n  async getClaimedSeats(bulkCouponId: string): Promise<ClaimedSeat[]> {\n    return this.request('/api/support/get-claimed-seats', { bulkCouponId })\n  }\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AA4BpB,IAAM,oBAAN,MAAsD;AAAA,EAC1C;AAAA,EACA;AAAA,EAEjB,YAAY,QAAoD;AAE9D,SAAK,UAAU,OAAO,QAAQ,QAAQ,OAAO,EAAE;AAC/C,SAAK,gBAAgB,OAAO;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQQ,kBAAkB,MAAsB;AAC9C,UAAM,YAAY,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AAC9C,UAAM,gBAAgB,GAAG,SAAS,IAAI,IAAI;AAC1C,UAAM,YAAY,WAAW,UAAU,KAAK,aAAa,EACtD,OAAO,aAAa,EACpB,OAAO,KAAK;AAEf,WAAO,KAAK,SAAS,OAAO,SAAS;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAc,QAAW,UAAkB,SAA8B;AACvE,UAAM,OAAO,KAAK,UAAU,OAAO;AACnC,UAAM,YAAY,KAAK,kBAAkB,IAAI;AAE7C,UAAM,WAAW,MAAM,MAAM,GAAG,KAAK,OAAO,GAAG,QAAQ,IAAI;AAAA,MACzD,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,uBAAuB;AAAA,MACzB;AAAA,MACA;AAAA,IACF,CAAC;AAED,QAAI,CAAC,SAAS,IAAI;AAEhB,UAAI;AACJ,UAAI;AACF,cAAM,YAAa,MAAM,SAAS,KAAK;AACvC,YAAI,WAAW,OAAO;AACpB,yBAAe,UAAU;AAAA,QAC3B;AAAA,MACF,QAAQ;AAAA,MAER;AAEA,UAAI,cAAc;AAChB,cAAM,IAAI,MAAM,YAAY;AAAA,MAC9B;AACA,YAAM,IAAI;AAAA,QACR,+BAA+B,SAAS,MAAM,IAAI,SAAS,UAAU;AAAA,MACvE;AAAA,IACF;AAEA,WAAQ,MAAM,SAAS,KAAK;AAAA,EAC9B;AAAA,EAEA,MAAM,WAAW,OAAqC;AACpD,WAAO,KAAK,QAAQ,4BAA4B,EAAE,MAAM,CAAC;AAAA,EAC3D;AAAA,EAEA,MAAM,aAAa,QAAqC;AACtD,WAAO,KAAK,QAAQ,8BAA8B,EAAE,OAAO,CAAC;AAAA,EAC9D;AAAA,EAEA,MAAM,iBAAiB,QAAyC;AAC9D,WAAO,KAAK,QAAQ,kCAAkC,EAAE,OAAO,CAAC;AAAA,EAClE;AAAA,EAEA,MAAM,aAAa,QAIO;AACxB,WAAO,KAAK,QAAQ,8BAA8B,MAAM;AAAA,EAC1D;AAAA,EAEA,MAAM,iBAAiB,QAIG;AACxB,WAAO,KAAK,QAAQ,kCAAkC,MAAM;AAAA,EAC9D;AAAA,EAEA,MAAM,kBAAkB,QAGK;AAC3B,WAAO,KAAK,QAAQ,oCAAoC,MAAM;AAAA,EAChE;AAAA,EAEA,MAAM,YAAY,QAGQ;AACxB,WAAO,KAAK,QAAQ,6BAA6B,MAAM;AAAA,EACzD;AAAA,EAEA,MAAM,WAAW,QAGS;AACxB,WAAO,KAAK,QAAQ,4BAA4B,MAAM;AAAA,EACxD;AAAA,EAEA,MAAM,gBAAgB,cAA8C;AAClE,WAAO,KAAK,QAAQ,kCAAkC,EAAE,aAAa,CAAC;AAAA,EACxE;AACF;","names":[]}

package/dist/handler.d.ts

@@ -0,0 +1,32 @@
+import { SupportIntegration } from './integration.js';
+import './types.js';
+
+/**
+ * Configuration for createSupportHandler
+ */
+interface SupportHandlerConfig {
+    integration: SupportIntegration;
+    webhookSecret: string;
+}
+/**
+ * Creates a Next.js API route handler for SupportIntegration.
+ * Verifies HMAC-SHA256 signature and routes actions to integration methods.
+ *
+ * Signature format: timestamp=1234567890,v1=hex_signature
+ * Payload to sign: timestamp.JSON.stringify(body)
+ * Replay protection: 5 minute window
+ *
+ * @example
+ * ```typescript
+ * import { createSupportHandler } from '@skillrecordings/sdk/handler'
+ * import { integration } from './integration'
+ *
+ * export const POST = createSupportHandler({
+ *   integration,
+ *   webhookSecret: process.env.SUPPORT_WEBHOOK_SECRET!,
+ * })
+ * ```
+ */
+declare function createSupportHandler(config: SupportHandlerConfig): (request: Request) => Promise<Response>;
+
+export { type SupportHandlerConfig, createSupportHandler };

package/dist/handler.js

@@ -0,0 +1,172 @@
+// src/handler.ts
+import { timingSafeEqual } from "crypto";
+function createSupportHandler(config) {
+  const { integration, webhookSecret } = config;
+  return async function handler(request) {
+    try {
+      const signatureHeader = request.headers.get("x-support-signature");
+      if (!signatureHeader) {
+        return jsonResponse({ error: "Missing signature header" }, 401);
+      }
+      const parts = signatureHeader.split(",");
+      const timestampPart = parts.find((p) => p.startsWith("timestamp="));
+      const signaturePart = parts.find((p) => p.startsWith("v1="));
+      if (!timestampPart || !signaturePart) {
+        return jsonResponse({ error: "Invalid signature format" }, 401);
+      }
+      const timestampValue = timestampPart.split("=")[1];
+      const signatureValue = signaturePart.split("=")[1];
+      if (!timestampValue || !signatureValue) {
+        return jsonResponse({ error: "Invalid signature format" }, 401);
+      }
+      const timestamp = parseInt(timestampValue, 10);
+      const receivedSignature = signatureValue;
+      const now = Math.floor(Date.now() / 1e3);
+      const maxAge = 300;
+      if (now - timestamp > maxAge) {
+        return jsonResponse({ error: "Signature expired" }, 401);
+      }
+      const bodyText = await request.text();
+      let body;
+      try {
+        body = JSON.parse(bodyText);
+      } catch (err) {
+        return jsonResponse({ error: "Invalid JSON body" }, 400);
+      }
+      const crypto = await import("crypto");
+      const payload = `${timestamp}.${bodyText}`;
+      const expectedSignature = crypto.createHmac("sha256", webhookSecret).update(payload).digest("hex");
+      if (!timingSafeEqual(
+        Buffer.from(receivedSignature),
+        Buffer.from(expectedSignature)
+      )) {
+        return jsonResponse({ error: "Invalid signature" }, 401);
+      }
+      const { action } = body;
+      if (!action || typeof action !== "string") {
+        return jsonResponse({ error: "Missing action field" }, 400);
+      }
+      const result = await routeAction(integration, action, body);
+      return jsonResponse(result.data, result.status);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return jsonResponse({ error: `Internal error: ${message}` }, 500);
+    }
+  };
+}
+async function routeAction(integration, action, body) {
+  try {
+    switch (action) {
+      case "lookupUser": {
+        const email = body.email;
+        const result = await integration.lookupUser(email);
+        return { data: result, status: 200 };
+      }
+      case "getPurchases": {
+        const userId = body.userId;
+        const result = await integration.getPurchases(userId);
+        return { data: result, status: 200 };
+      }
+      case "revokeAccess": {
+        const params = body;
+        const result = await integration.revokeAccess({
+          purchaseId: params.purchaseId,
+          reason: params.reason,
+          refundId: params.refundId
+        });
+        return { data: result, status: 200 };
+      }
+      case "transferPurchase": {
+        const params = body;
+        const result = await integration.transferPurchase({
+          purchaseId: params.purchaseId,
+          fromUserId: params.fromUserId,
+          toEmail: params.toEmail
+        });
+        return { data: result, status: 200 };
+      }
+      case "generateMagicLink": {
+        const params = body;
+        const result = await integration.generateMagicLink({
+          email: params.email,
+          expiresIn: params.expiresIn
+        });
+        return { data: result, status: 200 };
+      }
+      // Optional methods
+      case "getSubscriptions": {
+        if (!integration.getSubscriptions) {
+          return {
+            data: { error: "Method not implemented: getSubscriptions" },
+            status: 501
+          };
+        }
+        const userId = body.userId;
+        const result = await integration.getSubscriptions(userId);
+        return { data: result, status: 200 };
+      }
+      case "updateEmail": {
+        if (!integration.updateEmail) {
+          return {
+            data: { error: "Method not implemented: updateEmail" },
+            status: 501
+          };
+        }
+        const params = body;
+        const result = await integration.updateEmail({
+          userId: params.userId,
+          newEmail: params.newEmail
+        });
+        return { data: result, status: 200 };
+      }
+      case "updateName": {
+        if (!integration.updateName) {
+          return {
+            data: { error: "Method not implemented: updateName" },
+            status: 501
+          };
+        }
+        const params = body;
+        const result = await integration.updateName({
+          userId: params.userId,
+          newName: params.newName
+        });
+        return { data: result, status: 200 };
+      }
+      case "getClaimedSeats": {
+        if (!integration.getClaimedSeats) {
+          return {
+            data: { error: "Method not implemented: getClaimedSeats" },
+            status: 501
+          };
+        }
+        const bulkCouponId = body.bulkCouponId;
+        const result = await integration.getClaimedSeats(bulkCouponId);
+        return { data: result, status: 200 };
+      }
+      default:
+        return {
+          data: { error: `Unknown action: ${action}` },
+          status: 400
+        };
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown error";
+    return {
+      data: { error: message },
+      status: 500
+    };
+  }
+}
+function jsonResponse(data, status) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      "content-type": "application/json"
+    }
+  });
+}
+export {
+  createSupportHandler
+};
+//# sourceMappingURL=handler.js.map

package/dist/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/handler.ts"],"sourcesContent":["import { timingSafeEqual } from 'crypto';\nimport type { SupportIntegration } from './integration';\n\n/**\n * Configuration for createSupportHandler\n */\nexport interface SupportHandlerConfig {\n  integration: SupportIntegration;\n  webhookSecret: string;\n}\n\n/**\n * Request body for webhook actions\n */\ninterface WebhookRequest {\n  action: string;\n  [key: string]: unknown;\n}\n\n/**\n * Creates a Next.js API route handler for SupportIntegration.\n * Verifies HMAC-SHA256 signature and routes actions to integration methods.\n *\n * Signature format: timestamp=1234567890,v1=hex_signature\n * Payload to sign: timestamp.JSON.stringify(body)\n * Replay protection: 5 minute window\n *\n * @example\n * ```typescript\n * import { createSupportHandler } from '@skillrecordings/sdk/handler'\n * import { integration } from './integration'\n *\n * export const POST = createSupportHandler({\n *   integration,\n *   webhookSecret: process.env.SUPPORT_WEBHOOK_SECRET!,\n * })\n * ```\n */\nexport function createSupportHandler(\n  config: SupportHandlerConfig,\n): (request: Request) => Promise<Response> {\n  const { integration, webhookSecret } = config;\n\n  return async function handler(request: Request): Promise<Response> {\n    try {\n      // 1. Extract signature header\n      const signatureHeader = request.headers.get('x-support-signature');\n      if (!signatureHeader) {\n        return jsonResponse({ error: 'Missing signature header' }, 401);\n      }\n\n      // 2. Parse signature header (format: timestamp=1234567890,v1=hex_signature)\n      const parts = signatureHeader.split(',');\n      const timestampPart = parts.find((p) => p.startsWith('timestamp='));\n      const signaturePart = parts.find((p) => p.startsWith('v1='));\n\n      if (!timestampPart || !signaturePart) {\n        return jsonResponse({ error: 'Invalid signature format' }, 401);\n      }\n\n      const timestampValue = timestampPart.split('=')[1];\n      const signatureValue = signaturePart.split('=')[1];\n\n      if (!timestampValue || !signatureValue) {\n        return jsonResponse({ error: 'Invalid signature format' }, 401);\n      }\n\n      const timestamp = parseInt(timestampValue, 10);\n      const receivedSignature = signatureValue;\n\n      // 3. Verify timestamp (replay protection - 5 minute window)\n      const now = Math.floor(Date.now() / 1000);\n      const maxAge = 300; // 5 minutes in seconds\n      if (now - timestamp > maxAge) {\n        return jsonResponse({ error: 'Signature expired' }, 401);\n      }\n\n      // 4. Read and parse body\n      const bodyText = await request.text();\n      let body: WebhookRequest;\n\n      try {\n        body = JSON.parse(bodyText);\n      } catch (err) {\n        return jsonResponse({ error: 'Invalid JSON body' }, 400);\n      }\n\n      // 5. Compute expected signature\n      const crypto = await import('crypto');\n      const payload = `${timestamp}.${bodyText}`;\n      const expectedSignature = crypto\n        .createHmac('sha256', webhookSecret)\n        .update(payload)\n        .digest('hex');\n\n      // 6. Timing-safe comparison to prevent timing attacks\n      if (\n        !timingSafeEqual(\n          Buffer.from(receivedSignature),\n          Buffer.from(expectedSignature),\n        )\n      ) {\n        return jsonResponse({ error: 'Invalid signature' }, 401);\n      }\n\n      // 7. Extract action field\n      const { action } = body;\n      if (!action || typeof action !== 'string') {\n        return jsonResponse({ error: 'Missing action field' }, 400);\n      }\n\n      // 8. Route to integration method\n      const result = await routeAction(integration, action, body);\n      return jsonResponse(result.data, result.status);\n    } catch (err) {\n      const message = err instanceof Error ? err.message : 'Unknown error';\n      return jsonResponse({ error: `Internal error: ${message}` }, 500);\n    }\n  };\n}\n\n/**\n * Routes action to appropriate integration method\n */\nasync function routeAction(\n  integration: SupportIntegration,\n  action: string,\n  body: WebhookRequest,\n): Promise<{ data: unknown; status: number }> {\n  try {\n    switch (action) {\n      case 'lookupUser': {\n        const email = (body as unknown as { email: string }).email;\n        const result = await integration.lookupUser(email);\n        return { data: result, status: 200 };\n      }\n\n      case 'getPurchases': {\n        const userId = (body as unknown as { userId: string }).userId;\n        const result = await integration.getPurchases(userId);\n        return { data: result, status: 200 };\n      }\n\n      case 'revokeAccess': {\n        const params = body as unknown as {\n          purchaseId: string;\n          reason: string;\n          refundId: string;\n        };\n        const result = await integration.revokeAccess({\n          purchaseId: params.purchaseId,\n          reason: params.reason,\n          refundId: params.refundId,\n        });\n        return { data: result, status: 200 };\n      }\n\n      case 'transferPurchase': {\n        const params = body as unknown as {\n          purchaseId: string;\n          fromUserId: string;\n          toEmail: string;\n        };\n        const result = await integration.transferPurchase({\n          purchaseId: params.purchaseId,\n          fromUserId: params.fromUserId,\n          toEmail: params.toEmail,\n        });\n        return { data: result, status: 200 };\n      }\n\n      case 'generateMagicLink': {\n        const params = body as unknown as {\n          email: string;\n          expiresIn: number;\n        };\n        const result = await integration.generateMagicLink({\n          email: params.email,\n          expiresIn: params.expiresIn,\n        });\n        return { data: result, status: 200 };\n      }\n\n      // Optional methods\n      case 'getSubscriptions': {\n        if (!integration.getSubscriptions) {\n          return {\n            data: { error: 'Method not implemented: getSubscriptions' },\n            status: 501,\n          };\n        }\n        const userId = (body as unknown as { userId: string }).userId;\n        const result = await integration.getSubscriptions(userId);\n        return { data: result, status: 200 };\n      }\n\n      case 'updateEmail': {\n        if (!integration.updateEmail) {\n          return {\n            data: { error: 'Method not implemented: updateEmail' },\n            status: 501,\n          };\n        }\n        const params = body as unknown as {\n          userId: string;\n          newEmail: string;\n        };\n        const result = await integration.updateEmail({\n          userId: params.userId,\n          newEmail: params.newEmail,\n        });\n        return { data: result, status: 200 };\n      }\n\n      case 'updateName': {\n        if (!integration.updateName) {\n          return {\n            data: { error: 'Method not implemented: updateName' },\n            status: 501,\n          };\n        }\n        const params = body as unknown as {\n          userId: string;\n          newName: string;\n        };\n        const result = await integration.updateName({\n          userId: params.userId,\n          newName: params.newName,\n        });\n        return { data: result, status: 200 };\n      }\n\n      case 'getClaimedSeats': {\n        if (!integration.getClaimedSeats) {\n          return {\n            data: { error: 'Method not implemented: getClaimedSeats' },\n            status: 501,\n          };\n        }\n        const bulkCouponId = (body as unknown as { bulkCouponId: string })\n          .bulkCouponId;\n        const result = await integration.getClaimedSeats(bulkCouponId);\n        return { data: result, status: 200 };\n      }\n\n      default:\n        return {\n          data: { error: `Unknown action: ${action}` },\n          status: 400,\n        };\n    }\n  } catch (err) {\n    const message = err instanceof Error ? err.message : 'Unknown error';\n    return {\n      data: { error: message },\n      status: 500,\n    };\n  }\n}\n\n/**\n * Helper to create JSON responses\n */\nfunction jsonResponse(data: unknown, status: number): Response {\n  return new Response(JSON.stringify(data), {\n    status,\n    headers: {\n      'content-type': 'application/json',\n    },\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SupportIntegration } from './integration.js';
+export { ActionResult, ClaimedSeat, Customer, Purchase, RefundRequest, RefundResult, Subscription, User } from './types.js';
+export { AppAdapter } from './adapter.js';

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/integration.d.ts

@@ -0,0 +1,145 @@
+import { User, Purchase, Subscription, ActionResult, ClaimedSeat } from './types.js';
+
+/**
+ * SupportIntegration interface that apps must implement.
+ *
+ * Each app (egghead, Total TypeScript, etc.) implements this interface
+ * to provide user lookup, purchase/subscription management, and support actions.
+ *
+ * The support platform calls these methods via IntegrationClient with HMAC auth.
+ *
+ * @example
+ * ```typescript
+ * 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 }
+ *     })
+ *     return { success: true }
+ *   },
+ *   async generateMagicLink({ email, expiresIn }) {
+ *     const token = await createMagicToken(email, expiresIn)
+ *     return { url: `${APP_URL}/auth/magic?token=${token}` }
+ *   },
+ * }
+ * ```
+ */
+interface SupportIntegration {
+    /**
+     * Look up user by email address.
+     * Called by the agent to fetch user context at conversation start.
+     *
+     * @param email - User's email address
+     * @returns User if found, null otherwise
+     */
+    lookupUser(email: string): Promise<User | null>;
+    /**
+     * Fetch all purchases for a given user.
+     * Used by agent to display purchase history and validate refund eligibility.
+     *
+     * @param userId - User's unique identifier
+     * @returns Array of purchases, empty if none found
+     */
+    getPurchases(userId: string): Promise<Purchase[]>;
+    /**
+     * Fetch active subscriptions for a user.
+     * Optional method - only implement if app supports recurring billing.
+     *
+     * @param userId - User's unique identifier
+     * @returns Array of subscriptions, empty if none found
+     */
+    getSubscriptions?(userId: string): Promise<Subscription[]>;
+    /**
+     * Revoke access to a product after refund.
+     * Called after Stripe refund succeeds to remove product access.
+     *
+     * @param params.purchaseId - Purchase to revoke
+     * @param params.reason - Refund reason for audit trail
+     * @param params.refundId - Stripe refund ID
+     * @returns ActionResult indicating success/failure
+     */
+    revokeAccess(params: {
+        purchaseId: string;
+        reason: string;
+        refundId: string;
+    }): Promise<ActionResult>;
+    /**
+     * Transfer purchase to a different user.
+     * Updates purchase ownership and moves product access.
+     *
+     * @param params.purchaseId - Purchase to transfer
+     * @param params.fromUserId - Current owner's ID
+     * @param params.toEmail - New owner's email address
+     * @returns ActionResult indicating success/failure
+     */
+    transferPurchase(params: {
+        purchaseId: string;
+        fromUserId: string;
+        toEmail: string;
+    }): Promise<ActionResult>;
+    /**
+     * Generate a magic link for passwordless login.
+     * Used by agent to send login links during support conversations.
+     *
+     * @param params.email - User's email address
+     * @param params.expiresIn - Expiration time in seconds (default 3600)
+     * @returns Object with magic link URL
+     */
+    generateMagicLink(params: {
+        email: string;
+        expiresIn: number;
+    }): Promise<{
+        url: string;
+    }>;
+    /**
+     * Update user's email address.
+     * Optional method - not all apps support email changes.
+     *
+     * @param params.userId - User's unique identifier
+     * @param params.newEmail - New email address
+     * @returns ActionResult indicating success/failure
+     */
+    updateEmail?(params: {
+        userId: string;
+        newEmail: string;
+    }): Promise<ActionResult>;
+    /**
+     * Update user's display name.
+     * Optional method - not all apps support name changes.
+     *
+     * @param params.userId - User's unique identifier
+     * @param params.newName - New display name
+     * @returns ActionResult indicating success/failure
+     */
+    updateName?(params: {
+        userId: string;
+        newName: string;
+    }): Promise<ActionResult>;
+    /**
+     * Get all claimed seats for a team/bulk purchase.
+     * Optional method - only implement for apps with team features.
+     *
+     * @param bulkCouponId - Bulk coupon/license identifier
+     * @returns Array of claimed seats with user info
+     */
+    getClaimedSeats?(bulkCouponId: string): Promise<ClaimedSeat[]>;
+}
+
+export { ActionResult, ClaimedSeat, Purchase, Subscription, type SupportIntegration, User };

package/dist/integration.js

@@ -0,0 +1 @@
+//# sourceMappingURL=integration.js.map

package/dist/integration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}