@skillrecordings/sdk 0.2.0 → 0.2.1

package/src/client.ts

@@ -1,146 +0,0 @@
-import { createHmac } from 'node:crypto'
-import type {
-  ActionResult,
-  ClaimedSeat,
-  Purchase,
-  Subscription,
-  SupportIntegration,
-  User,
-} from './integration'
-
-/**
- * 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')
- * ```
- */
-export class IntegrationClient implements SupportIntegration {
-  private readonly baseUrl: string
-  private readonly webhookSecret: string
-
-  constructor(config: { baseUrl: string; webhookSecret: string }) {
-    // Strip trailing slash for consistent URL construction
-    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)
-   */
-  private generateSignature(body: string): string {
-    const timestamp = Math.floor(Date.now() / 1000)
-    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.
-   */
-  private async request<T>(endpoint: string, payload: unknown): Promise<T> {
-    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) {
-      // Try to extract error message from response body
-      let errorMessage: string | undefined
-      try {
-        const errorBody = (await response.json()) as { error?: string }
-        if (errorBody?.error) {
-          errorMessage = errorBody.error
-        }
-      } catch {
-        // If JSON parsing fails, ignore and use status text
-      }
-
-      if (errorMessage) {
-        throw new Error(errorMessage)
-      }
-      throw new Error(
-        `Integration request failed: ${response.status} ${response.statusText}`
-      )
-    }
-
-    return (await response.json()) as T
-  }
-
-  async lookupUser(email: string): Promise<User | null> {
-    return this.request('/api/support/lookup-user', { email })
-  }
-
-  async getPurchases(userId: string): Promise<Purchase[]> {
-    return this.request('/api/support/get-purchases', { userId })
-  }
-
-  async getSubscriptions(userId: string): Promise<Subscription[]> {
-    return this.request('/api/support/get-subscriptions', { userId })
-  }
-
-  async revokeAccess(params: {
-    purchaseId: string
-    reason: string
-    refundId: string
-  }): Promise<ActionResult> {
-    return this.request('/api/support/revoke-access', params)
-  }
-
-  async transferPurchase(params: {
-    purchaseId: string
-    fromUserId: string
-    toEmail: string
-  }): Promise<ActionResult> {
-    return this.request('/api/support/transfer-purchase', params)
-  }
-
-  async generateMagicLink(params: {
-    email: string
-    expiresIn: number
-  }): Promise<{ url: string }> {
-    return this.request('/api/support/generate-magic-link', params)
-  }
-
-  async updateEmail(params: {
-    userId: string
-    newEmail: string
-  }): Promise<ActionResult> {
-    return this.request('/api/support/update-email', params)
-  }
-
-  async updateName(params: {
-    userId: string
-    newName: string
-  }): Promise<ActionResult> {
-    return this.request('/api/support/update-name', params)
-  }
-
-  async getClaimedSeats(bulkCouponId: string): Promise<ClaimedSeat[]> {
-    return this.request('/api/support/get-claimed-seats', { bulkCouponId })
-  }
-}

package/src/handler.ts

@@ -1,271 +0,0 @@
-import { timingSafeEqual } from 'crypto';
-import type { SupportIntegration } from './integration';
-
-/**
- * Configuration for createSupportHandler
- */
-export interface SupportHandlerConfig {
-  integration: SupportIntegration;
-  webhookSecret: string;
-}
-
-/**
- * Request body for webhook actions
- */
-interface WebhookRequest {
-  action: string;
-  [key: string]: unknown;
-}
-
-/**
- * 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!,
- * })
- * ```
- */
-export function createSupportHandler(
-  config: SupportHandlerConfig,
-): (request: Request) => Promise<Response> {
-  const { integration, webhookSecret } = config;
-
-  return async function handler(request: Request): Promise<Response> {
-    try {
-      // 1. Extract signature header
-      const signatureHeader = request.headers.get('x-support-signature');
-      if (!signatureHeader) {
-        return jsonResponse({ error: 'Missing signature header' }, 401);
-      }
-
-      // 2. Parse signature header (format: timestamp=1234567890,v1=hex_signature)
-      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;
-
-      // 3. Verify timestamp (replay protection - 5 minute window)
-      const now = Math.floor(Date.now() / 1000);
-      const maxAge = 300; // 5 minutes in seconds
-      if (now - timestamp > maxAge) {
-        return jsonResponse({ error: 'Signature expired' }, 401);
-      }
-
-      // 4. Read and parse body
-      const bodyText = await request.text();
-      let body: WebhookRequest;
-
-      try {
-        body = JSON.parse(bodyText);
-      } catch (err) {
-        return jsonResponse({ error: 'Invalid JSON body' }, 400);
-      }
-
-      // 5. Compute expected signature
-      const crypto = await import('crypto');
-      const payload = `${timestamp}.${bodyText}`;
-      const expectedSignature = crypto
-        .createHmac('sha256', webhookSecret)
-        .update(payload)
-        .digest('hex');
-
-      // 6. Timing-safe comparison to prevent timing attacks
-      if (
-        !timingSafeEqual(
-          Buffer.from(receivedSignature),
-          Buffer.from(expectedSignature),
-        )
-      ) {
-        return jsonResponse({ error: 'Invalid signature' }, 401);
-      }
-
-      // 7. Extract action field
-      const { action } = body;
-      if (!action || typeof action !== 'string') {
-        return jsonResponse({ error: 'Missing action field' }, 400);
-      }
-
-      // 8. Route to integration method
-      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);
-    }
-  };
-}
-
-/**
- * Routes action to appropriate integration method
- */
-async function routeAction(
-  integration: SupportIntegration,
-  action: string,
-  body: WebhookRequest,
-): Promise<{ data: unknown; status: number }> {
-  try {
-    switch (action) {
-      case 'lookupUser': {
-        const email = (body as unknown as { email: string }).email;
-        const result = await integration.lookupUser(email);
-        return { data: result, status: 200 };
-      }
-
-      case 'getPurchases': {
-        const userId = (body as unknown as { userId: string }).userId;
-        const result = await integration.getPurchases(userId);
-        return { data: result, status: 200 };
-      }
-
-      case 'revokeAccess': {
-        const params = body as unknown as {
-          purchaseId: string;
-          reason: string;
-          refundId: string;
-        };
-        const result = await integration.revokeAccess({
-          purchaseId: params.purchaseId,
-          reason: params.reason,
-          refundId: params.refundId,
-        });
-        return { data: result, status: 200 };
-      }
-
-      case 'transferPurchase': {
-        const params = body as unknown as {
-          purchaseId: string;
-          fromUserId: string;
-          toEmail: string;
-        };
-        const result = await integration.transferPurchase({
-          purchaseId: params.purchaseId,
-          fromUserId: params.fromUserId,
-          toEmail: params.toEmail,
-        });
-        return { data: result, status: 200 };
-      }
-
-      case 'generateMagicLink': {
-        const params = body as unknown as {
-          email: string;
-          expiresIn: number;
-        };
-        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 as unknown as { userId: string }).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 as unknown as {
-          userId: string;
-          newEmail: string;
-        };
-        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 as unknown as {
-          userId: string;
-          newName: string;
-        };
-        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 as unknown as { bulkCouponId: string })
-          .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,
-    };
-  }
-}
-
-/**
- * Helper to create JSON responses
- */
-function jsonResponse(data: unknown, status: number): Response {
-  return new Response(JSON.stringify(data), {
-    status,
-    headers: {
-      'content-type': 'application/json',
-    },
-  });
-}

package/src/index.ts

@@ -1,19 +0,0 @@
-// New SupportIntegration interface (primary)
-export type { SupportIntegration } from './integration';
-
-// Core types
-export type {
-  User,
-  Purchase,
-  Subscription,
-  ActionResult,
-  ClaimedSeat,
-} from './types';
-
-// Deprecated exports (backwards compatibility)
-export type { AppAdapter } from './adapter';
-export type {
-  Customer,
-  RefundRequest,
-  RefundResult,
-} from './types';

package/src/integration.ts

@@ -1,164 +0,0 @@
-import type {
-  User,
-  Purchase,
-  Subscription,
-  ActionResult,
-  ClaimedSeat,
-} from './types';
-
-// Re-export types for convenience
-export type {
-  User,
-  Purchase,
-  Subscription,
-  ActionResult,
-  ClaimedSeat,
-};
-
-/**
- * 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}` }
- *   },
- * }
- * ```
- */
-export 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[]>;
-}

package/src/types.ts

@@ -1,82 +0,0 @@
-/**
- * User entity returned by app integration.
- * Replaces Customer for consistency with SupportIntegration interface.
- */
-export interface User {
-  id: string;
-  email: string;
-  name?: string;
-  createdAt: Date;
-}
-
-/**
- * @deprecated Use User instead. Kept for backwards compatibility.
- */
-export type Customer = User;
-
-/**
- * Purchase record with product and payment details.
- * Used by agent tools to display purchase history.
- */
-export interface Purchase {
-  id: string;
-  productId: string;
-  productName: string;
-  purchasedAt: Date;
-  amount: number;
-  currency: string;
-  stripeChargeId?: string;
-  status: 'active' | 'refunded' | 'transferred';
-}
-
-/**
- * Subscription entity for recurring billing.
- * Optional method - apps may not support subscriptions.
- */
-export interface Subscription {
-  id: string;
-  productId: string;
-  productName: string;
-  status: 'active' | 'cancelled' | 'expired' | 'paused';
-  currentPeriodStart: Date;
-  currentPeriodEnd: Date;
-  cancelAtPeriodEnd: boolean;
-}
-
-/**
- * Generic result type for mutations (refund, transfer, updates).
- */
-export interface ActionResult {
-  success: boolean;
-  error?: string;
-}
-
-/**
- * Claimed seat for team/bulk purchases.
- * Used by getClaimedSeats optional method.
- */
-export interface ClaimedSeat {
-  userId: string;
-  email: string;
-  claimedAt: Date;
-}
-
-/**
- * Refund request payload.
- * @deprecated Use revokeAccess via SupportIntegration instead.
- */
-export interface RefundRequest {
-  purchaseId: string;
-  reason: string;
-  amount?: number;
-}
-
-/**
- * Refund result.
- * @deprecated Use ActionResult instead.
- */
-export interface RefundResult {
-  success: boolean;
-  refundId?: string;
-  error?: string;
-}

package/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "@repo/typescript-config/base.json",
-  "compilerOptions": {
-    "outDir": "dist"
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"]
-}

package/vitest.config.ts

@@ -1,10 +0,0 @@
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-    include: ['src/**/*.test.ts'],
-    passWithNoTests: true,
-  },
-})