@skillrecordings/sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @skillrecordings/sdk
+
+## 0.2.0
+
+### Minor Changes
+
+- 91c7136: Initial public release of the Skill Recordings Support SDK.
+
+  Provides the integration contract for apps to connect to the support platform:
+  - `IntegrationClient` for querying user data and purchases
+  - Webhook handler utilities for SDK-to-platform communication
+  - Type definitions for the integration interface

package/README.md

@@ -0,0 +1,14 @@
+# @skillrecordings/sdk
+
+Integration contract + adapters for external apps.
+
+## Purpose
+- Define the SDK surface for app integrations
+- Provide adapters for supported platforms
+
+## Key paths
+- `packages/sdk/src/`
+
+## Do / Don’t
+- Do keep adapters thin
+- Don’t embed app-specific logic in core

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@skillrecordings/sdk",
+  "version": "0.2.0",
+  "private": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./integration": "./src/integration.ts",
+    "./adapter": "./src/adapter.ts",
+    "./client": "./src/client.ts",
+    "./handler": "./src/handler.ts"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "test": "vitest --run"
+  },
+  "devDependencies": {
+    "@repo/typescript-config": "*",
+    "@types/node": "^22.15.3",
+    "typescript": "5.9.2"
+  }
+}

package/src/__tests__/client.test.ts

@@ -0,0 +1,351 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { User, Purchase, ActionResult } from '../integration';
+
+// Import will fail until we create the client
+import { IntegrationClient } from '../client';
+
+describe('IntegrationClient', () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let client: IntegrationClient;
+  const baseUrl = 'https://app.example.com';
+  const webhookSecret = 'whsec_test123';
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    global.fetch = fetchMock;
+
+    client = new IntegrationClient({
+      baseUrl,
+      webhookSecret,
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('constructor', () => {
+    it('creates client with baseUrl and secret', () => {
+      expect(client).toBeInstanceOf(IntegrationClient);
+    });
+
+    it('strips trailing slash from baseUrl', () => {
+      const clientWithSlash = new IntegrationClient({
+        baseUrl: 'https://app.example.com/',
+        webhookSecret: 'secret',
+      });
+      expect(clientWithSlash).toBeInstanceOf(IntegrationClient);
+    });
+  });
+
+  describe('HMAC signature', () => {
+    it('signs requests with X-Support-Signature header', async () => {
+      const user: User = {
+        id: 'usr_123',
+        email: 'test@example.com',
+        name: 'Test User',
+        createdAt: new Date(),
+      };
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => user,
+      });
+
+      await client.lookupUser('test@example.com');
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/lookup-user`,
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            'X-Support-Signature': expect.stringMatching(/^t=\d+,v1=[a-f0-9]+$/),
+          }),
+        }),
+      );
+    });
+
+    it('includes timestamp in signature', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => null,
+      });
+
+      const now = Date.now();
+      await client.lookupUser('test@example.com');
+
+      const call = fetchMock.mock.calls[0];
+      const signature = call?.[1]?.headers?.['X-Support-Signature'];
+      expect(signature).toBeDefined();
+      const timestampPart = (signature as string).split('t=')[1]?.split(',')[0];
+      expect(timestampPart).toBeDefined();
+      const timestamp = parseInt(timestampPart as string);
+
+      // Timestamp should be within 1 second of now
+      expect(Math.abs(timestamp - now / 1000)).toBeLessThan(1);
+    });
+  });
+
+  describe('lookupUser', () => {
+    it('calls /api/support/lookup-user endpoint', async () => {
+      const user: User = {
+        id: 'usr_123',
+        email: 'test@example.com',
+        name: 'Test User',
+        createdAt: new Date(),
+      };
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => user,
+      });
+
+      const result = await client.lookupUser('test@example.com');
+
+      expect(result).toEqual(user);
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/lookup-user`,
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({ email: 'test@example.com' }),
+        }),
+      );
+    });
+
+    it('returns null when user not found', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => null,
+      });
+
+      const result = await client.lookupUser('notfound@example.com');
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('getPurchases', () => {
+    it('calls /api/support/get-purchases endpoint', async () => {
+      const purchases: Purchase[] = [
+        {
+          id: 'pur_123',
+          productId: 'prod_123',
+          productName: 'Test Product',
+          purchasedAt: new Date(),
+          amount: 10000,
+          currency: 'usd',
+          status: 'active',
+        },
+      ];
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => purchases,
+      });
+
+      const result = await client.getPurchases('usr_123');
+
+      expect(result).toEqual(purchases);
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/get-purchases`,
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({ userId: 'usr_123' }),
+        }),
+      );
+    });
+
+    it('returns empty array when no purchases', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => [],
+      });
+
+      const result = await client.getPurchases('usr_123');
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('revokeAccess', () => {
+    it('calls /api/support/revoke-access endpoint', async () => {
+      const actionResult: ActionResult = { success: true };
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => actionResult,
+      });
+
+      const result = await client.revokeAccess({
+        purchaseId: 'pur_123',
+        reason: 'Customer requested refund',
+        refundId: 're_123',
+      });
+
+      expect(result).toEqual(actionResult);
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/revoke-access`,
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({
+            purchaseId: 'pur_123',
+            reason: 'Customer requested refund',
+            refundId: 're_123',
+          }),
+        }),
+      );
+    });
+  });
+
+  describe('transferPurchase', () => {
+    it('calls /api/support/transfer-purchase endpoint', async () => {
+      const actionResult: ActionResult = { success: true };
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => actionResult,
+      });
+
+      const result = await client.transferPurchase({
+        purchaseId: 'pur_123',
+        fromUserId: 'usr_123',
+        toEmail: 'new@example.com',
+      });
+
+      expect(result).toEqual(actionResult);
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/transfer-purchase`,
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({
+            purchaseId: 'pur_123',
+            fromUserId: 'usr_123',
+            toEmail: 'new@example.com',
+          }),
+        }),
+      );
+    });
+  });
+
+  describe('generateMagicLink', () => {
+    it('calls /api/support/generate-magic-link endpoint', async () => {
+      const magicLink = { url: 'https://app.example.com/auth/magic?token=abc123' };
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => magicLink,
+      });
+
+      const result = await client.generateMagicLink({
+        email: 'test@example.com',
+        expiresIn: 3600,
+      });
+
+      expect(result).toEqual(magicLink);
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/generate-magic-link`,
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({
+            email: 'test@example.com',
+            expiresIn: 3600,
+          }),
+        }),
+      );
+    });
+  });
+
+  describe('error handling', () => {
+    it('throws when response is not ok', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+      });
+
+      await expect(client.lookupUser('test@example.com')).rejects.toThrow(
+        'Integration request failed: 500 Internal Server Error',
+      );
+    });
+
+    it('includes error message from response when available', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        json: async () => ({ error: 'Invalid email format' }),
+      });
+
+      await expect(client.lookupUser('invalid')).rejects.toThrow('Invalid email format');
+    });
+
+    it('handles network errors', async () => {
+      fetchMock.mockRejectedValueOnce(new Error('Network error'));
+
+      await expect(client.lookupUser('test@example.com')).rejects.toThrow('Network error');
+    });
+  });
+
+  describe('optional methods', () => {
+    it('calls getSubscriptions when implemented', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => [],
+      });
+
+      const result = await client.getSubscriptions?.('usr_123');
+      expect(result).toEqual([]);
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/get-subscriptions`,
+        expect.any(Object),
+      );
+    });
+
+    it('calls updateEmail when implemented', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true }),
+      });
+
+      const result = await client.updateEmail?.({
+        userId: 'usr_123',
+        newEmail: 'new@example.com',
+      });
+
+      expect(result).toEqual({ success: true });
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/update-email`,
+        expect.any(Object),
+      );
+    });
+
+    it('calls updateName when implemented', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true }),
+      });
+
+      const result = await client.updateName?.({
+        userId: 'usr_123',
+        newName: 'New Name',
+      });
+
+      expect(result).toEqual({ success: true });
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/update-name`,
+        expect.any(Object),
+      );
+    });
+
+    it('calls getClaimedSeats when implemented', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => [],
+      });
+
+      const result = await client.getClaimedSeats?.('bulk_123');
+      expect(result).toEqual([]);
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${baseUrl}/api/support/get-claimed-seats`,
+        expect.any(Object),
+      );
+    });
+  });
+});