@startsimpli/funnels 0.1.4 → 0.1.6

package/package.json

@@ -1,41 +1,19 @@
 {
   "name": "@startsimpli/funnels",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Brutally generic filtering pipeline package for any Simpli product",
   "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js",
-      "require": "./dist/core/index.cjs"
-    },
-    "./components": {
-      "types": "./dist/components/index.d.ts",
-      "import": "./dist/components/index.js",
-      "require": "./dist/components/index.cjs"
-    },
-    "./components.css": "./dist/components/index.css",
-    "./hooks": {
-      "types": "./dist/hooks/index.d.ts",
-      "import": "./dist/hooks/index.js",
-      "require": "./dist/hooks/index.cjs"
-    },
-    "./store": {
-      "types": "./dist/store/index.d.ts",
-      "import": "./dist/store/index.js",
-      "require": "./dist/store/index.cjs"
-    }
+    ".": "./src/index.ts",
+    "./core": "./src/core/index.ts",
+    "./components": "./src/components/index.ts",
+    "./hooks": "./src/hooks/index.ts",
+    "./store": "./src/store/index.ts"
   },
   "files": [
-    "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],

package/src/api/README.md

@@ -0,0 +1,507 @@
+# @simpli/funnels - API Client
+
+Generic API client for funnel operations using the adapter pattern for flexible HTTP integration.
+
+## Overview
+
+The API client provides:
+- **Adapter Pattern**: Inject your own HTTP client with custom auth, headers, error handling
+- **Type Safety**: Full TypeScript support with generics for entity types
+- **Comprehensive Coverage**: All funnel CRUD operations, stage management, run operations
+- **Error Handling**: Standardized error types with status codes
+- **Testing Support**: Mock adapter for easy unit testing
+
+## Quick Start
+
+### Basic Usage (Default Adapter)
+
+```typescript
+import { FunnelApiClient, FetchAdapter } from '@simpli/funnels';
+
+// Create adapter with default fetch
+const adapter = new FetchAdapter({
+  headers: {
+    'Authorization': 'Bearer your-jwt-token',
+  },
+  timeout: 10000, // 10 seconds
+});
+
+// Create client
+const client = new FunnelApiClient(adapter, 'https://api.example.com');
+
+// List funnels
+const funnels = await client.listFunnels({ status: 'active' });
+
+// Get funnel
+const funnel = await client.getFunnel('funnel-123');
+
+// Run funnel
+const run = await client.runFunnel('funnel-123', { trigger_type: 'manual' });
+```
+
+### Custom Adapter (Advanced)
+
+For apps with custom auth or request handling:
+
+```typescript
+import { ApiAdapter, createApiError } from '@simpli/funnels';
+
+class CustomAdapter implements ApiAdapter {
+  constructor(private authToken: string) {}
+
+  async get<T>(url: string, params?: Record<string, any>): Promise<T> {
+    const response = await fetch(url, {
+      headers: {
+        'Authorization': `Bearer ${this.authToken}`,
+        'X-Tenant-ID': 'my-tenant',
+      },
+    });
+
+    if (!response.ok) {
+      throw createApiError('Request failed', response.status);
+    }
+
+    return response.json();
+  }
+
+  async post<T>(url: string, data: any): Promise<T> {
+    // Custom implementation
+  }
+
+  async patch<T>(url: string, data: any): Promise<T> {
+    // Custom implementation
+  }
+
+  async delete<T>(url: string): Promise<T> {
+    // Custom implementation
+  }
+}
+
+// Use custom adapter
+const adapter = new CustomAdapter('your-token');
+const client = new FunnelApiClient(adapter, 'https://api.example.com');
+```
+
+## API Reference
+
+### Funnel Operations
+
+#### List Funnels
+
+```typescript
+const funnels = await client.listFunnels({
+  status: 'active',
+  page: 1,
+  page_size: 20,
+  ordering: '-created_at',
+});
+
+// Response
+interface PaginatedResponse<Funnel> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  results: Funnel[];
+}
+```
+
+#### Get Funnel
+
+```typescript
+const funnel = await client.getFunnel('funnel-123');
+// Returns: Funnel<TEntity>
+// Throws: ApiError with status 404 if not found
+```
+
+#### Create Funnel
+
+```typescript
+const newFunnel = await client.createFunnel({
+  name: 'Investor Qualification',
+  status: 'draft',
+  input_type: 'contacts',
+  stages: [
+    {
+      id: 'stage-1',
+      order: 0,
+      name: 'Check Firm Stage',
+      filter_logic: 'AND',
+      rules: [
+        { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+      ],
+      match_action: 'continue',
+      no_match_action: 'exclude',
+    },
+  ],
+});
+```
+
+#### Update Funnel
+
+```typescript
+const updated = await client.updateFunnel('funnel-123', {
+  name: 'Updated Name',
+  status: 'active',
+});
+```
+
+#### Delete Funnel
+
+```typescript
+await client.deleteFunnel('funnel-123');
+```
+
+### Stage Operations
+
+#### Create Stage
+
+```typescript
+const stage = await client.createStage('funnel-123', {
+  order: 1,
+  name: 'Geography Check',
+  filter_logic: 'AND',
+  rules: [
+    { field_path: 'firm.location', operator: 'eq', value: 'San Francisco' },
+  ],
+  match_action: 'tag_continue',
+  match_tags: ['sf_based'],
+  no_match_action: 'continue',
+});
+```
+
+#### Update Stage
+
+```typescript
+const updated = await client.updateStage('funnel-123', 'stage-1', {
+  name: 'Updated Stage Name',
+});
+```
+
+#### Delete Stage
+
+```typescript
+await client.deleteStage('funnel-123', 'stage-1');
+```
+
+### Run Operations
+
+#### Trigger Run
+
+```typescript
+const run = await client.runFunnel('funnel-123', {
+  trigger_type: 'manual',
+  metadata: { source: 'dashboard' },
+});
+
+// Returns: FunnelRun
+// {
+//   id: 'run-456',
+//   funnel_id: 'funnel-123',
+//   status: 'pending' | 'running',
+//   ...
+// }
+```
+
+#### Get Run History
+
+```typescript
+const runs = await client.getFunnelRuns('funnel-123', {
+  status: 'completed',
+  page: 1,
+  page_size: 10,
+  ordering: '-started_at',
+});
+```
+
+#### Get Single Run
+
+```typescript
+const run = await client.getFunnelRun('run-456');
+```
+
+#### Get Run Results
+
+```typescript
+// All results
+const results = await client.getFunnelResults('run-456');
+
+// Only matched entities
+const matched = await client.getFunnelResults('run-456', { matched: true });
+
+// Response
+interface FunnelResult<TEntity> {
+  entity: TEntity;
+  matched: boolean;
+  excluded_at_stage?: string;
+  accumulated_tags: string[];
+  context: Record<string, any>;
+  stage_results?: StageResult[];
+}
+```
+
+#### Cancel Run
+
+```typescript
+const cancelled = await client.cancelFunnelRun('run-456');
+// Returns: FunnelRun with status 'cancelled'
+```
+
+### Preview Operations
+
+#### Server-Side Preview
+
+```typescript
+const preview = await client.previewFunnelServer('funnel-123', [
+  { id: 'entity-1', firm: { stage: 'Series A' } },
+  { id: 'entity-2', firm: { stage: 'Seed' } },
+]);
+
+// Returns: PreviewResult
+// {
+//   matched_entities: TEntity[],
+//   excluded_entities: TEntity[],
+//   stage_breakdown: [...],
+//   total_input: 2,
+//   total_matched: 1,
+//   total_excluded: 1,
+// }
+```
+
+## Error Handling
+
+All methods throw `ApiError` on failure:
+
+```typescript
+import { isApiError } from '@simpli/funnels';
+
+try {
+  const funnel = await client.getFunnel('invalid');
+} catch (error) {
+  if (isApiError(error)) {
+    console.error('Status:', error.status); // 404
+    console.error('Message:', error.message); // 'Not found'
+    console.error('Response:', error.response); // Full response body
+  }
+}
+```
+
+## Testing
+
+Use `MockAdapter` for unit tests:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { FunnelApiClient } from '@simpli/funnels';
+import type { ApiAdapter } from '@simpli/funnels';
+
+class MockAdapter implements ApiAdapter {
+  private responses = new Map<string, any>();
+
+  mockResponse(url: string, response: any): void {
+    this.responses.set(url, response);
+  }
+
+  async get<T>(url: string): Promise<T> {
+    return this.responses.get(url);
+  }
+
+  // Implement other methods...
+}
+
+describe('MyFunnelComponent', () => {
+  it('should fetch funnels', async () => {
+    const adapter = new MockAdapter();
+    const client = new FunnelApiClient(adapter, 'https://api.test.com');
+
+    adapter.mockResponse('https://api.test.com/api/v1/funnels/', {
+      count: 1,
+      results: [{ id: 'funnel-1', name: 'Test' }],
+    });
+
+    const funnels = await client.listFunnels();
+    expect(funnels.count).toBe(1);
+  });
+});
+```
+
+## Type Safety with Generics
+
+Use type generics for entity-specific types:
+
+```typescript
+interface Investor {
+  id: string;
+  name: string;
+  firm: {
+    stage: string;
+    location: string;
+  };
+}
+
+// Type-safe client
+const client = new FunnelApiClient(adapter, baseUrl);
+
+// Type-safe operations
+const funnel = await client.getFunnel<Investor>('funnel-123');
+// funnel.stages[0] knows about Investor type
+
+const results = await client.getFunnelResults<Investor>('run-456');
+// results.results[0].entity is typed as Investor
+```
+
+## Backend API Endpoints
+
+The client expects these endpoints on the backend:
+
+```
+GET    /api/v1/funnels/                     - List funnels
+GET    /api/v1/funnels/{id}/                - Get funnel detail
+POST   /api/v1/funnels/                     - Create funnel
+PATCH  /api/v1/funnels/{id}/                - Update funnel
+DELETE /api/v1/funnels/{id}/                - Delete funnel
+
+POST   /api/v1/funnels/{id}/stages/         - Create stage
+PATCH  /api/v1/funnels/{id}/stages/{sid}/   - Update stage
+DELETE /api/v1/funnels/{id}/stages/{sid}/   - Delete stage
+
+POST   /api/v1/funnels/{id}/run/            - Trigger run
+GET    /api/v1/funnels/{id}/runs/           - Get run history
+GET    /api/v1/funnel-runs/{id}/            - Get run detail
+GET    /api/v1/funnel-runs/{id}/results/    - Get run results
+POST   /api/v1/funnel-runs/{id}/cancel/     - Cancel run
+
+POST   /api/v1/funnels/{id}/preview/        - Preview with sample data
+```
+
+## Advanced Configuration
+
+### FetchAdapter Options
+
+```typescript
+const adapter = new FetchAdapter({
+  // Custom headers (auth, tenant, etc)
+  headers: {
+    'Authorization': 'Bearer token',
+    'X-Tenant-ID': 'tenant-123',
+  },
+
+  // Request timeout (default: 30000ms)
+  timeout: 10000,
+
+  // Custom response parser
+  parseResponse: async (response) => {
+    const data = await response.json();
+    return data.data; // Unwrap nested response
+  },
+
+  // Error callback (logging, monitoring)
+  onError: (error) => {
+    console.error('API error:', error);
+    // Send to monitoring service
+  },
+});
+```
+
+### URL Handling
+
+The client automatically:
+- Removes trailing slashes from `baseUrl`
+- Builds full URLs with `baseUrl + path`
+- Serializes query parameters (arrays, nulls, etc)
+
+```typescript
+// All equivalent
+const client1 = new FunnelApiClient(adapter, 'https://api.example.com');
+const client2 = new FunnelApiClient(adapter, 'https://api.example.com/');
+
+await client1.listFunnels({ page: 1, page_size: 10 });
+// GET https://api.example.com/api/v1/funnels/?page=1&page_size=10
+```
+
+## Best Practices
+
+1. **Reuse Client Instances**: Create one client per API and reuse it
+2. **Use Type Generics**: Type your entities for better autocomplete and type safety
+3. **Handle Errors**: Always wrap API calls in try/catch
+4. **Mock for Tests**: Use MockAdapter for unit tests, avoid hitting real API
+5. **Configure Timeouts**: Set appropriate timeouts for your use case
+6. **Add Error Callbacks**: Use `onError` for logging and monitoring
+
+## Examples
+
+### Complete Example: Investor Qualification
+
+```typescript
+import { FunnelApiClient, FetchAdapter } from '@simpli/funnels';
+
+interface Investor {
+  id: string;
+  name: string;
+  firm: { stage: string; location: string };
+}
+
+// Setup
+const adapter = new FetchAdapter({
+  headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` },
+});
+const client = new FunnelApiClient(adapter, 'https://api.startsimpli.com');
+
+// Create funnel
+const funnel = await client.createFunnel<Investor>({
+  name: 'Series A Investor Qualification',
+  status: 'active',
+  input_type: 'contacts',
+  stages: [
+    {
+      order: 0,
+      name: 'Check Firm Stage',
+      filter_logic: 'AND',
+      rules: [
+        { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+      ],
+      match_action: 'continue',
+      no_match_action: 'exclude',
+    },
+    {
+      order: 1,
+      name: 'Check Geography',
+      filter_logic: 'OR',
+      rules: [
+        { field_path: 'firm.location', operator: 'eq', value: 'San Francisco' },
+        { field_path: 'firm.location', operator: 'eq', value: 'New York' },
+      ],
+      match_action: 'tag_continue',
+      match_tags: ['target_geography'],
+      no_match_action: 'continue',
+    },
+    {
+      order: 2,
+      name: 'Final Output',
+      filter_logic: 'AND',
+      rules: [],
+      match_action: 'output',
+      no_match_action: 'output',
+    },
+  ],
+});
+
+// Run funnel
+const run = await client.runFunnel(funnel.id, { trigger_type: 'manual' });
+
+// Poll for completion
+let completed = false;
+while (!completed) {
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  const status = await client.getFunnelRun(run.id);
+  if (status.status === 'completed' || status.status === 'failed') {
+    completed = true;
+  }
+}
+
+// Get results
+const results = await client.getFunnelResults<Investor>(run.id, { matched: true });
+console.log(`Matched ${results.count} investors`);
+results.results.forEach((result) => {
+  console.log(`- ${result.entity.name} (tags: ${result.accumulated_tags.join(', ')})`);
+});
+```

package/src/api/adapter.ts

@@ -0,0 +1,106 @@
+/**
+ * ApiAdapter Interface
+ *
+ * Generic HTTP adapter for flexible API integration.
+ * Consumers can provide their own implementation to handle:
+ * - Custom authentication (JWT, API keys, OAuth)
+ * - Custom headers (tenant IDs, correlation IDs)
+ * - Custom error handling
+ * - Request/response transformation
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Generic API adapter interface
+ *
+ * Allows applications to inject their own HTTP client
+ * with custom auth, headers, error handling, etc.
+ */
+export interface ApiAdapter {
+  /**
+   * HTTP GET request
+   *
+   * @param url - Full or relative URL to fetch
+   * @param params - Optional query parameters
+   * @returns Parsed response data
+   * @throws ApiError on HTTP error or network failure
+   */
+  get<T>(url: string, params?: Record<string, any>): Promise<T>;
+
+  /**
+   * HTTP POST request
+   *
+   * @param url - Full or relative URL
+   * @param data - Request body (will be JSON serialized)
+   * @returns Parsed response data
+   * @throws ApiError on HTTP error or network failure
+   */
+  post<T>(url: string, data: any): Promise<T>;
+
+  /**
+   * HTTP PATCH request
+   *
+   * @param url - Full or relative URL
+   * @param data - Request body (will be JSON serialized)
+   * @returns Parsed response data
+   * @throws ApiError on HTTP error or network failure
+   */
+  patch<T>(url: string, data: any): Promise<T>;
+
+  /**
+   * HTTP DELETE request
+   *
+   * @param url - Full or relative URL
+   * @returns Parsed response data (often empty)
+   * @throws ApiError on HTTP error or network failure
+   */
+  delete<T>(url: string): Promise<T>;
+}
+
+/**
+ * Standard API error structure
+ */
+export interface ApiError extends Error {
+  /** HTTP status code (404, 500, etc) */
+  status?: number;
+
+  /** Error code from API */
+  code?: string;
+
+  /** Response body (if available) */
+  response?: any;
+
+  /** Original error (network, parse, etc) */
+  cause?: Error;
+}
+
+/**
+ * Create ApiError from response
+ */
+export function createApiError(
+  message: string,
+  status?: number,
+  response?: any,
+  cause?: Error
+): ApiError {
+  const error = new Error(message) as ApiError;
+  error.name = 'ApiError';
+  error.status = status;
+  error.response = response;
+  error.cause = cause;
+
+  // Extract code from response if available
+  if (response?.code) {
+    error.code = response.code;
+  }
+
+  return error;
+}
+
+/**
+ * Type guard for ApiError
+ */
+export function isApiError(error: unknown): error is ApiError {
+  return error instanceof Error && error.name === 'ApiError';
+}