@startsimpli/api 0.1.0

package/README.md

@@ -0,0 +1,329 @@
+# @startsimpli/api
+
+Type-safe Django REST API client for StartSimpli Next.js applications.
+
+## Overview
+
+This package provides a type-safe TypeScript client for the Django REST API backend (`start-simpli-api`). It handles authentication, error normalization, pagination, and provides endpoint wrappers for all Django models.
+
+**IMPORTANT**: This is a Django REST API client - NO Prisma, NO database code. All data lives in the Django backend.
+
+## Installation
+
+```bash
+npm install @startsimpli/api
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { createStartSimpliApi } from '@startsimpli/api';
+
+const api = createStartSimpliApi({
+  baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000/api/v1',
+  getToken: async () => {
+    // Get token from your auth provider
+    const session = await getServerSession();
+    return session?.accessToken || null;
+  },
+});
+
+// Use API endpoints
+const contacts = await api.contacts.list({ tier: 1 });
+const orgs = await api.organizations.getByStage('seed');
+```
+
+### Contacts API
+
+```typescript
+// List contacts with filters
+const contacts = await api.contacts.list(
+  { tier: 1, has_linkedin: true }, // filters
+  { page: 1, page_size: 20 },      // pagination
+  { ordering: '-created_at' }       // sorting
+);
+
+// Get single contact
+const contact = await api.contacts.get('contact-uuid');
+
+// Create contact with assertions
+const newContact = await api.contacts.create({
+  name: 'John Doe',
+  email: 'john@example.com',
+  title: 'Partner',
+  write_tags: ['tier_1', 'focus:fintech'],
+  write_metrics: { enrichment_score: 0.95 },
+  write_profiles: { linkedin: 'https://linkedin.com/in/johndoe' },
+});
+
+// Update contact
+const updated = await api.contacts.update('contact-uuid', {
+  title: 'Managing Partner',
+  write_tags: ['tier_1', 'vip'],
+});
+
+// Search contacts
+const results = await api.contacts.search('john');
+
+// Get contacts by firm
+const firmContacts = await api.contacts.getByFirm('firm-uuid');
+```
+
+### Organizations API
+
+```typescript
+// List organizations with filters
+const orgs = await api.organizations.list(
+  {
+    tier: 1,
+    stage: 'seed',
+    check_size_min_gte: 100000,
+    check_size_max_lte: 1000000,
+  },
+  { page: 1, page_size: 20 },
+  { ordering: '-aum' }
+);
+
+// Get single organization
+const org = await api.organizations.get('org-uuid');
+
+// Create organization with assertions
+const newOrg = await api.organizations.create({
+  name: 'Acme Ventures',
+  domain: 'acmevc.com',
+  location: 'San Francisco, CA',
+  write_tags: ['tier_1', 'stage:seed', 'focus:fintech'],
+  write_metrics: {
+    check_size_min: 500000,
+    check_size_max: 2000000,
+    aum: 100000000,
+  },
+  write_profiles: {
+    linkedin: 'https://linkedin.com/company/acme-ventures',
+    website: 'https://acmevc.com',
+  },
+});
+
+// Get by check size range
+const firms = await api.organizations.getByCheckSizeRange(100000, 1000000);
+```
+
+### Entities API (Low-level)
+
+```typescript
+// Tags
+const tags = await api.entities.listTags();
+
+// Entity Tags
+const entityTags = await api.entities.listEntityTags(
+  { page: 1, page_size: 50 },
+  { entity_id: 'some-uuid', category: 'focus' }
+);
+
+// Metrics
+const metrics = await api.entities.listMetrics(
+  undefined,
+  { entity_id: 'some-uuid', type: 'financial' }
+);
+
+// Profiles
+const profiles = await api.entities.listProfiles(
+  undefined,
+  { entity_id: 'some-uuid', type: 'professional' }
+);
+```
+
+### Using Direct Client
+
+For custom endpoints not covered by wrappers:
+
+```typescript
+import { createApiClient } from '@startsimpli/api';
+
+const client = createApiClient({
+  baseUrl: 'http://localhost:8000/api/v1',
+  getToken: async () => getAccessToken(),
+});
+
+// Direct fetch calls
+const data = await client.fetch.get('/custom-endpoint/', {
+  params: { key: 'value' }
+});
+
+const created = await client.fetch.post('/custom-endpoint/', {
+  name: 'test'
+});
+```
+
+## Next.js API Routes Middleware
+
+### With Auth
+
+```typescript
+import { withAuth } from '@startsimpli/api/middleware';
+
+export const GET = withAuth(async (request, context) => {
+  const { userId, token, isAuthenticated } = context;
+
+  if (!isAuthenticated) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  // Use token to call Django API
+  return NextResponse.json({ userId, token });
+});
+```
+
+### With Validation
+
+```typescript
+import { withValidation } from '@startsimpli/api/middleware';
+import { z } from 'zod';
+
+const createContactSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email().optional(),
+  tier: z.number().int().min(1).max(3).optional(),
+});
+
+export const POST = withValidation(
+  async (request, { body }) => {
+    // body is typed and validated
+    const contact = await createContact(body);
+    return NextResponse.json(contact);
+  },
+  { body: createContactSchema }
+);
+```
+
+### With Error Handling
+
+```typescript
+import { withErrorHandling } from '@startsimpli/api/middleware';
+
+export const GET = withErrorHandling(async (request) => {
+  // Errors are automatically caught and formatted
+  const data = await somethingThatMightThrow();
+  return NextResponse.json(data);
+});
+```
+
+### Composing Middleware
+
+```typescript
+import { withAuth, withErrorHandling, withValidation } from '@startsimpli/api/middleware';
+import { z } from 'zod';
+
+const schema = z.object({ name: z.string() });
+
+export const POST = withErrorHandling(
+  withAuth(
+    withValidation(
+      async (request, { body }, authContext) => {
+        // Fully typed, validated, and authenticated
+        return NextResponse.json({ success: true });
+      },
+      { body: schema }
+    )
+  )
+);
+```
+
+## Error Handling
+
+```typescript
+import {
+  isApiException,
+  isValidationError,
+  isAuthError,
+  isNotFoundError,
+} from '@startsimpli/api';
+
+try {
+  const contact = await api.contacts.get('invalid-id');
+} catch (error) {
+  if (isValidationError(error)) {
+    console.log('Validation errors:', error.errors);
+  } else if (isAuthError(error)) {
+    console.log('Auth error:', error.status);
+  } else if (isNotFoundError(error)) {
+    console.log('Contact not found');
+  } else if (isApiException(error)) {
+    console.log('API error:', error.message);
+  }
+}
+```
+
+## TypeScript Types
+
+All types are exported for use in your application:
+
+```typescript
+import type {
+  Contact,
+  Organization,
+  Entity,
+  Tag,
+  Metric,
+  Profile,
+  Attribute,
+  PaginatedResponse,
+  ApiError,
+  CreateContactRequest,
+  UpdateContactRequest,
+  ContactFilters,
+} from '@startsimpli/api';
+```
+
+## Architecture
+
+### Django Integration
+
+This package is designed to work with the Django REST API:
+
+- **Base URL**: `http://localhost:8000/api/v1/` (configurable)
+- **Auth**: Bearer token from `@startsimpli/auth`
+- **Pagination**: Django REST Framework format (`page`, `page_size`)
+- **Filtering**: Django-filter query params (`field__gte=100`, `field__in=1,2,3`)
+
+### Entity System
+
+Django uses a generic Entity model with assertions (Tags, Metrics, Profiles, Attributes):
+
+```typescript
+// Entity with assertions
+{
+  id: 'uuid',
+  entity_type: 'contact',
+
+  // Canonical fields
+  name: 'John Doe',
+  email: 'john@example.com',
+
+  // Computed from assertions
+  tier: 1,  // from tags
+  linkedin: 'https://...', // from profiles
+  enrichment_score: 0.95, // from metrics
+
+  // Full assertions
+  tags: [{ category: 'quality', name: 'tier_1', ... }],
+  metrics: [{ type: 'quality', subtype: 'enrichment_score', value: 0.95 }],
+  profiles: [{ type: 'professional', subtype: 'linkedin', identifier: '...' }],
+}
+```
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Type check
+npm run type-check
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@startsimpli/api",
+  "version": "0.1.0",
+  "description": "Type-safe Django REST API client for StartSimpli apps",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": ["src"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/lib/api-client.ts",
+    "./middleware": "./src/middleware/index.ts",
+    "./types": "./src/types/index.ts",
+    "./utils": "./src/utils/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@types/dompurify": "^3.0.5",
+    "isomorphic-dompurify": "^2.36.0",
+    "zod": "^3.22.4"
+  },
+  "peerDependencies": {
+    "next": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "next": "^15.5.12",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  }
+}

package/src/__tests__/jwt-refresh.test.ts

@@ -0,0 +1,195 @@
+/**
+ * JWT Refresh Token Flow Tests
+ *
+ * Tests the automatic token refresh interceptor that prevents
+ * users from being logged out every 30 minutes.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { FetchWrapper } from '../lib/fetch-wrapper';
+
+describe('JWT Refresh Flow', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+  let refreshCallback: ReturnType<typeof vi.fn>;
+  let unauthorizedCallback: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    refreshCallback = vi.fn();
+    unauthorizedCallback = vi.fn();
+    global.fetch = mockFetch;
+  });
+
+  it('should retry request after successful token refresh on 401', async () => {
+    const wrapper = new FetchWrapper({
+      baseUrl: 'http://localhost:8000',
+      getToken: () => 'old-token',
+      onTokenRefresh: refreshCallback,
+      onUnauthorized: unauthorizedCallback,
+    });
+
+    // First call returns 401
+    mockFetch.mockResolvedValueOnce({
+      status: 401,
+      ok: false,
+    });
+
+    // Refresh returns new token
+    refreshCallback.mockResolvedValueOnce('new-token');
+
+    // Retry with new token succeeds
+    mockFetch.mockResolvedValueOnce({
+      status: 200,
+      ok: true,
+      json: async () => ({ data: 'success' }),
+    });
+
+    await wrapper.get('/api/v1/messages/');
+
+    // Should have called refresh
+    expect(refreshCallback).toHaveBeenCalledTimes(1);
+
+    // Should have made 2 fetch calls (original + retry)
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+
+    // Second call should have new token
+    const retryCall = mockFetch.mock.calls[1];
+    const retryHeaders = retryCall[1]?.headers;
+    expect(retryHeaders.get('Authorization')).toBe('Bearer new-token');
+
+    // Should NOT have called unauthorized callback
+    expect(unauthorizedCallback).not.toHaveBeenCalled();
+  });
+
+  it('should call onUnauthorized if refresh fails', async () => {
+    const wrapper = new FetchWrapper({
+      baseUrl: 'http://localhost:8000',
+      getToken: () => 'old-token',
+      onTokenRefresh: refreshCallback,
+      onUnauthorized: unauthorizedCallback,
+    });
+
+    // First call returns 401
+    mockFetch.mockResolvedValueOnce({
+      status: 401,
+      ok: false,
+    });
+
+    // Refresh fails (returns null)
+    refreshCallback.mockResolvedValueOnce(null);
+
+    try {
+      await wrapper.get('/api/v1/messages/');
+    } catch (error) {
+      // Expected to throw
+    }
+
+    // Should have called refresh
+    expect(refreshCallback).toHaveBeenCalledTimes(1);
+
+    // Should have called unauthorized callback
+    expect(unauthorizedCallback).toHaveBeenCalledTimes(1);
+  });
+
+  it('should prevent multiple simultaneous refresh attempts', async () => {
+    const wrapper = new FetchWrapper({
+      baseUrl: 'http://localhost:8000',
+      getToken: () => 'old-token',
+      onTokenRefresh: refreshCallback,
+    });
+
+    // Both calls return 401
+    mockFetch.mockResolvedValue({
+      status: 401,
+      ok: false,
+    });
+
+    // Refresh returns new token (with delay)
+    refreshCallback.mockImplementation(
+      () => new Promise((resolve) => setTimeout(() => resolve('new-token'), 100))
+    );
+
+    // Retry succeeds
+    mockFetch.mockResolvedValueOnce({
+      status: 200,
+      ok: true,
+      json: async () => ({ data: 'success' }),
+    });
+
+    // Make 2 concurrent requests
+    const promise1 = wrapper.get('/api/v1/messages/');
+    const promise2 = wrapper.get('/api/v1/contacts/');
+
+    await Promise.all([promise1, promise2]);
+
+    // Should only have called refresh ONCE (shared promise)
+    expect(refreshCallback).toHaveBeenCalledTimes(1);
+  });
+
+  it('should work without refresh callback (backward compatible)', async () => {
+    const wrapper = new FetchWrapper({
+      baseUrl: 'http://localhost:8000',
+      getToken: () => 'token',
+      // No onTokenRefresh provided
+      onUnauthorized: unauthorizedCallback,
+    });
+
+    mockFetch.mockResolvedValueOnce({
+      status: 401,
+      ok: false,
+    });
+
+    try {
+      await wrapper.get('/api/v1/messages/');
+    } catch (error) {
+      // Expected to throw
+    }
+
+    // Should NOT have attempted refresh (no callback)
+    // Should still call unauthorized callback
+    expect(unauthorizedCallback).toHaveBeenCalledTimes(1);
+  });
+});
+
+/**
+ * Integration Example: market-simpli
+ *
+ * This is how market-simpli implements JWT refresh:
+ *
+ * ```typescript
+ * // src/shared/lib/api/client.ts
+ * import { createStartSimpliApi } from '@startsimpli/api';
+ *
+ * async function refreshToken(): Promise<string | null> {
+ *   const response = await fetch('/api/v1/auth/token/refresh/', {
+ *     method: 'POST',
+ *     credentials: 'include', // Sends refresh token cookie
+ *   });
+ *
+ *   if (!response.ok) return null;
+ *
+ *   const data = await response.json();
+ *   const access = data.access;
+ *
+ *   localStorage.setItem('auth_token', access);
+ *   return access;
+ * }
+ *
+ * export const api = createStartSimpliApi({
+ *   baseUrl: process.env.NEXT_PUBLIC_API_URL,
+ *   getToken: () => localStorage.getItem('auth_token'),
+ *   onTokenRefresh: refreshToken,
+ *   onUnauthorized: () => {
+ *     localStorage.removeItem('auth_token');
+ *     window.location.href = '/login';
+ *   },
+ * });
+ * ```
+ *
+ * Now when any API call gets 401:
+ * 1. Interceptor calls refreshToken()
+ * 2. Gets new access token from /api/v1/auth/token/refresh/
+ * 3. Stores new token in localStorage
+ * 4. Retries original request with new token
+ * 5. User never sees "logged out" error
+ */

package/src/__tests__/query-params.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Tests for query parameter utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildFilterParams, buildOrderingParam, mergeQueryParams } from '../utils/query-params';
+
+describe('buildFilterParams', () => {
+  it('should convert filters to Django query params', () => {
+    const filters = {
+      tier: 1,
+      status: 'active',
+      search: 'test',
+    };
+
+    const params = buildFilterParams(filters);
+
+    expect(params).toEqual({
+      tier: 1,
+      status: 'active',
+      search: 'test',
+    });
+  });
+
+  it('should skip undefined and null values', () => {
+    const filters = {
+      tier: 1,
+      status: undefined,
+      search: null,
+    };
+
+    const params = buildFilterParams(filters);
+
+    expect(params).toEqual({ tier: 1 });
+  });
+
+  it('should handle boolean filters', () => {
+    const filters = {
+      has_email: true,
+      has_linkedin: false,
+    };
+
+    const params = buildFilterParams(filters);
+
+    expect(params).toEqual({
+      has_email: true,
+      has_linkedin: false,
+    });
+  });
+
+  it('should handle array filters with __in suffix', () => {
+    const filters = {
+      tier: [1, 2, 3],
+      status: ['active', 'pending'],
+    };
+
+    const params = buildFilterParams(filters);
+
+    expect(params).toEqual({
+      tier__in: '1,2,3',
+      status__in: 'active,pending',
+    });
+  });
+
+  it('should skip empty arrays', () => {
+    const filters = {
+      tier: [],
+      status: 'active',
+    };
+
+    const params = buildFilterParams(filters);
+
+    expect(params).toEqual({ status: 'active' });
+  });
+
+  it('should handle range filters', () => {
+    const filters = {
+      check_size_min_gte: 100000,
+      check_size_max_lte: 1000000,
+      created_at_gt: '2024-01-01',
+    };
+
+    const params = buildFilterParams(filters);
+
+    expect(params).toEqual({
+      check_size_min_gte: 100000,
+      check_size_max_lte: 1000000,
+      created_at_gt: '2024-01-01',
+    });
+  });
+});
+
+describe('buildOrderingParam', () => {
+  it('should build ascending ordering', () => {
+    expect(buildOrderingParam('name', 'asc')).toBe('name');
+    expect(buildOrderingParam('createdAt', 'asc')).toBe('createdAt');
+  });
+
+  it('should build descending ordering', () => {
+    expect(buildOrderingParam('name', 'desc')).toBe('-name');
+    expect(buildOrderingParam('createdAt', 'desc')).toBe('-createdAt');
+  });
+
+  it('should default to ascending', () => {
+    expect(buildOrderingParam('name')).toBe('name');
+  });
+
+  it('should return undefined for empty field', () => {
+    expect(buildOrderingParam(undefined)).toBeUndefined();
+    expect(buildOrderingParam('')).toBeUndefined();
+  });
+});
+
+describe('mergeQueryParams', () => {
+  it('should merge pagination, sorting, and filters', () => {
+    const pagination = { page: 2, pageSize: 50 };
+    const sorting = { ordering: '-createdAt' };
+    const filters = { tier: 1, status: 'active' };
+
+    const merged = mergeQueryParams(pagination, sorting, filters);
+
+    expect(merged).toEqual({
+      page: 2,
+      pageSize: 50,
+      ordering: '-createdAt',
+      tier: 1,
+      status: 'active',
+    });
+  });
+
+  it('should handle undefined params', () => {
+    const pagination = { page: 1 };
+
+    const merged = mergeQueryParams(pagination, undefined, undefined);
+
+    expect(merged).toEqual({ page: 1 });
+  });
+
+  it('should handle all undefined', () => {
+    const merged = mergeQueryParams();
+
+    expect(merged).toEqual({});
+  });
+});