@startsimpli/funnels 0.1.4 → 0.1.6

package/src/api/client.ts

@@ -0,0 +1,385 @@
+/**
+ * FunnelApiClient - Generic API client for funnel operations
+ *
+ * Adapter-based client that works with any HTTP implementation.
+ * Consumers inject their own ApiAdapter for custom auth, headers, error handling.
+ *
+ * @packageDocumentation
+ */
+
+import type { ApiAdapter } from './adapter';
+import type {
+  Funnel,
+  FunnelStage,
+  FunnelRun,
+  FunnelResult,
+  CreateFunnelInput,
+  UpdateFunnelInput,
+  CreateStageInput,
+  UpdateStageInput,
+} from '../types';
+
+/**
+ * List filters for funnels
+ */
+export interface FunnelListFilters {
+  /** Filter by status */
+  status?: 'draft' | 'active' | 'paused' | 'archived';
+
+  /** Filter by input type */
+  input_type?: string;
+
+  /** Filter by owner */
+  owner_id?: string;
+
+  /** Filter by team */
+  team_id?: string;
+
+  /** Search by name */
+  search?: string;
+
+  /** Pagination: page number (1-indexed) */
+  page?: number;
+
+  /** Pagination: page size */
+  page_size?: number;
+
+  /** Ordering: field name (prefix with - for descending) */
+  ordering?: string;
+}
+
+/**
+ * List response with pagination
+ */
+export interface PaginatedResponse<T> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  results: T[];
+}
+
+/**
+ * Preview result (client-side evaluation)
+ */
+export interface PreviewResult<TEntity = any> {
+  /** Sample entities that would match */
+  matched_entities: TEntity[];
+
+  /** Sample entities that would be excluded */
+  excluded_entities: TEntity[];
+
+  /** Stage-by-stage breakdown */
+  stage_breakdown: {
+    stage_id: string;
+    stage_name: string;
+    input_count: number;
+    matched_count: number;
+    excluded_count: number;
+  }[];
+
+  /** Total counts */
+  total_input: number;
+  total_matched: number;
+  total_excluded: number;
+}
+
+/**
+ * Generic API client for funnel operations
+ *
+ * Usage:
+ * ```ts
+ * const adapter = new FetchAdapter({ headers: { 'Authorization': 'Bearer token' } });
+ * const client = new FunnelApiClient(adapter, 'https://api.example.com');
+ *
+ * const funnels = await client.listFunnels({ status: 'active' });
+ * const funnel = await client.getFunnel('funnel-123');
+ * const run = await client.runFunnel('funnel-123');
+ * ```
+ */
+export class FunnelApiClient {
+  constructor(
+    private adapter: ApiAdapter,
+    private baseUrl: string
+  ) {
+    // Remove trailing slash
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+  }
+
+  /**
+   * Build full URL for endpoint
+   */
+  private url(path: string): string {
+    return `${this.baseUrl}${path}`;
+  }
+
+  // ============================================================================
+  // Funnel CRUD
+  // ============================================================================
+
+  /**
+   * List funnels with optional filters
+   *
+   * @param filters - Optional filters (status, owner, pagination, etc)
+   * @returns Paginated list of funnels
+   */
+  async listFunnels<TEntity = any>(
+    filters?: FunnelListFilters
+  ): Promise<PaginatedResponse<Funnel<TEntity>>> {
+    return this.adapter.get<PaginatedResponse<Funnel<TEntity>>>(
+      this.url('/api/v1/funnels/'),
+      filters
+    );
+  }
+
+  /**
+   * Get single funnel by ID
+   *
+   * @param id - Funnel ID
+   * @returns Funnel detail
+   * @throws ApiError with status 404 if not found
+   */
+  async getFunnel<TEntity = any>(id: string): Promise<Funnel<TEntity>> {
+    return this.adapter.get<Funnel<TEntity>>(this.url(`/api/v1/funnels/${id}/`));
+  }
+
+  /**
+   * Create new funnel
+   *
+   * @param data - Funnel creation data
+   * @returns Created funnel
+   * @throws ApiError with status 400 if validation fails
+   */
+  async createFunnel<TEntity = any>(
+    data: CreateFunnelInput<TEntity>
+  ): Promise<Funnel<TEntity>> {
+    return this.adapter.post<Funnel<TEntity>>(this.url('/api/v1/funnels/'), data);
+  }
+
+  /**
+   * Update existing funnel
+   *
+   * @param id - Funnel ID
+   * @param data - Funnel update data
+   * @returns Updated funnel
+   * @throws ApiError with status 404 if not found, 400 if validation fails
+   */
+  async updateFunnel<TEntity = any>(
+    id: string,
+    data: Partial<UpdateFunnelInput<TEntity>>
+  ): Promise<Funnel<TEntity>> {
+    return this.adapter.patch<Funnel<TEntity>>(
+      this.url(`/api/v1/funnels/${id}/`),
+      data
+    );
+  }
+
+  /**
+   * Delete funnel
+   *
+   * @param id - Funnel ID
+   * @throws ApiError with status 404 if not found
+   */
+  async deleteFunnel(id: string): Promise<void> {
+    return this.adapter.delete<void>(this.url(`/api/v1/funnels/${id}/`));
+  }
+
+  // ============================================================================
+  // Stage CRUD
+  // ============================================================================
+
+  /**
+   * Create stage in funnel
+   *
+   * @param funnelId - Funnel ID
+   * @param data - Stage creation data
+   * @returns Created stage
+   * @throws ApiError with status 404 if funnel not found, 400 if validation fails
+   */
+  async createStage<TEntity = any>(
+    funnelId: string,
+    data: CreateStageInput<TEntity>
+  ): Promise<FunnelStage<TEntity>> {
+    return this.adapter.post<FunnelStage<TEntity>>(
+      this.url(`/api/v1/funnels/${funnelId}/stages/`),
+      data
+    );
+  }
+
+  /**
+   * Update stage
+   *
+   * @param funnelId - Funnel ID
+   * @param stageId - Stage ID
+   * @param data - Stage update data
+   * @returns Updated stage
+   * @throws ApiError with status 404 if not found, 400 if validation fails
+   */
+  async updateStage<TEntity = any>(
+    funnelId: string,
+    stageId: string,
+    data: Partial<UpdateStageInput<TEntity>>
+  ): Promise<FunnelStage<TEntity>> {
+    return this.adapter.patch<FunnelStage<TEntity>>(
+      this.url(`/api/v1/funnels/${funnelId}/stages/${stageId}/`),
+      data
+    );
+  }
+
+  /**
+   * Delete stage
+   *
+   * @param funnelId - Funnel ID
+   * @param stageId - Stage ID
+   * @throws ApiError with status 404 if not found
+   */
+  async deleteStage(funnelId: string, stageId: string): Promise<void> {
+    return this.adapter.delete<void>(
+      this.url(`/api/v1/funnels/${funnelId}/stages/${stageId}/`)
+    );
+  }
+
+  // ============================================================================
+  // Run Operations
+  // ============================================================================
+
+  /**
+   * Trigger funnel run
+   *
+   * @param funnelId - Funnel ID
+   * @param options - Optional run configuration (trigger_type, metadata, etc)
+   * @returns Created funnel run (status: pending or running)
+   * @throws ApiError with status 404 if funnel not found, 400 if validation fails
+   */
+  async runFunnel(
+    funnelId: string,
+    options?: {
+      trigger_type?: 'manual' | 'scheduled' | 'webhook' | 'api';
+      metadata?: Record<string, any>;
+    }
+  ): Promise<FunnelRun> {
+    return this.adapter.post<FunnelRun>(
+      this.url(`/api/v1/funnels/${funnelId}/run/`),
+      options || {}
+    );
+  }
+
+  /**
+   * Get funnel run history
+   *
+   * @param funnelId - Funnel ID
+   * @param filters - Optional filters (status, pagination, etc)
+   * @returns List of funnel runs
+   * @throws ApiError with status 404 if funnel not found
+   */
+  async getFunnelRuns(
+    funnelId: string,
+    filters?: {
+      status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+      page?: number;
+      page_size?: number;
+      ordering?: string;
+    }
+  ): Promise<PaginatedResponse<FunnelRun>> {
+    return this.adapter.get<PaginatedResponse<FunnelRun>>(
+      this.url(`/api/v1/funnels/${funnelId}/runs/`),
+      filters
+    );
+  }
+
+  /**
+   * Get single run detail
+   *
+   * @param runId - Run ID
+   * @returns Funnel run detail
+   * @throws ApiError with status 404 if not found
+   */
+  async getFunnelRun(runId: string): Promise<FunnelRun> {
+    return this.adapter.get<FunnelRun>(this.url(`/api/v1/funnel-runs/${runId}/`));
+  }
+
+  /**
+   * Get run results (entities that were processed)
+   *
+   * @param runId - Run ID
+   * @param filters - Optional filters (matched, pagination, etc)
+   * @returns Paginated list of results
+   * @throws ApiError with status 404 if run not found
+   */
+  async getFunnelResults<TEntity = any>(
+    runId: string,
+    filters?: {
+      matched?: boolean;
+      page?: number;
+      page_size?: number;
+    }
+  ): Promise<PaginatedResponse<FunnelResult<TEntity>>> {
+    return this.adapter.get<PaginatedResponse<FunnelResult<TEntity>>>(
+      this.url(`/api/v1/funnel-runs/${runId}/results/`),
+      filters
+    );
+  }
+
+  /**
+   * Cancel running funnel
+   *
+   * @param runId - Run ID
+   * @returns Updated run with status 'cancelled'
+   * @throws ApiError with status 404 if not found, 400 if already completed
+   */
+  async cancelFunnelRun(runId: string): Promise<FunnelRun> {
+    return this.adapter.post<FunnelRun>(
+      this.url(`/api/v1/funnel-runs/${runId}/cancel/`),
+      {}
+    );
+  }
+
+  // ============================================================================
+  // Client-Side Preview (Local Evaluation)
+  // ============================================================================
+
+  /**
+   * Preview funnel with sample entities (client-side evaluation)
+   *
+   * Useful for testing funnel logic before running on full dataset.
+   * Does NOT hit the server - evaluates locally.
+   *
+   * Note: This requires the evaluation engine to be available client-side.
+   * If not available, this will throw an error.
+   *
+   * @param funnel - Funnel definition
+   * @param sampleEntities - Sample entities to test
+   * @returns Preview results showing which entities would match/exclude
+   */
+  async previewFunnel<TEntity = any>(
+    funnel: Funnel<TEntity>,
+    sampleEntities: TEntity[]
+  ): Promise<PreviewResult<TEntity>> {
+    // This is client-side only - would require evaluation engine
+    // Throwing for now until we implement the evaluator
+    throw new Error(
+      'Client-side preview requires evaluation engine. ' +
+        'Use server-side preview endpoint instead: POST /api/v1/funnels/{id}/preview/'
+    );
+  }
+
+  /**
+   * Server-side preview (recommended)
+   *
+   * Send sample entities to server for evaluation.
+   * Useful for testing funnel logic before running on full dataset.
+   *
+   * @param funnelId - Funnel ID
+   * @param sampleEntities - Sample entities to test
+   * @returns Preview results
+   * @throws ApiError with status 404 if funnel not found
+   */
+  async previewFunnelServer<TEntity = any>(
+    funnelId: string,
+    sampleEntities: TEntity[]
+  ): Promise<PreviewResult<TEntity>> {
+    return this.adapter.post<PreviewResult<TEntity>>(
+      this.url(`/api/v1/funnels/${funnelId}/preview/`),
+      { entities: sampleEntities }
+    );
+  }
+}

package/src/api/default-adapter.ts

@@ -0,0 +1,243 @@
+/**
+ * FetchAdapter - Default fetch-based implementation
+ *
+ * Simple adapter using standard fetch API.
+ * Suitable for apps that don't need custom authentication.
+ *
+ * @packageDocumentation
+ */
+
+import { ApiAdapter, createApiError } from './adapter';
+
+/**
+ * Configuration options for FetchAdapter
+ */
+export interface FetchAdapterConfig {
+  /** Optional headers to include in all requests */
+  headers?: Record<string, string>;
+
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+
+  /**
+   * Handle response parsing
+   * Default: response.json()
+   */
+  parseResponse?: (response: Response) => Promise<any>;
+
+  /**
+   * Transform error before throwing
+   * Useful for logging, monitoring, etc.
+   */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Default fetch-based adapter
+ *
+ * Features:
+ * - JSON request/response handling
+ * - Configurable headers
+ * - Request timeout
+ * - Error transformation
+ *
+ * Example:
+ * ```ts
+ * const adapter = new FetchAdapter({
+ *   headers: { 'X-API-Key': 'secret' },
+ *   timeout: 10000
+ * });
+ * ```
+ */
+export class FetchAdapter implements ApiAdapter {
+  private config: Required<FetchAdapterConfig>;
+
+  constructor(config: FetchAdapterConfig = {}) {
+    this.config = {
+      headers: config.headers || {},
+      timeout: config.timeout || 30000,
+      parseResponse: config.parseResponse || ((res) => res.json()),
+      onError: config.onError || (() => {}),
+    };
+  }
+
+  /**
+   * Build fetch options
+   */
+  private buildOptions(
+    method: string,
+    data?: any,
+    params?: Record<string, any>
+  ): RequestInit {
+    const options: RequestInit = {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...this.config.headers,
+      },
+    };
+
+    if (data !== undefined) {
+      options.body = JSON.stringify(data);
+    }
+
+    return options;
+  }
+
+  /**
+   * Build URL with query params
+   */
+  private buildUrl(url: string, params?: Record<string, any>): string {
+    if (!params || Object.keys(params).length === 0) {
+      return url;
+    }
+
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== undefined && value !== null) {
+        // Handle arrays
+        if (Array.isArray(value)) {
+          value.forEach((v) => searchParams.append(key, String(v)));
+        } else {
+          searchParams.append(key, String(value));
+        }
+      }
+    });
+
+    const queryString = searchParams.toString();
+    return queryString ? `${url}?${queryString}` : url;
+  }
+
+  /**
+   * Fetch with timeout
+   */
+  private async fetchWithTimeout(
+    url: string,
+    options: RequestInit
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      return response;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw createApiError(
+          `Request timeout after ${this.config.timeout}ms`,
+          undefined,
+          undefined,
+          error
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Handle response
+   */
+  private async handleResponse<T>(response: Response): Promise<T> {
+    // Success
+    if (response.ok) {
+      // Handle 204 No Content
+      if (response.status === 204) {
+        return undefined as T;
+      }
+
+      try {
+        return await this.config.parseResponse(response);
+      } catch (error) {
+        throw createApiError(
+          'Failed to parse response',
+          response.status,
+          undefined,
+          error as Error
+        );
+      }
+    }
+
+    // Error
+    let errorBody: any;
+    try {
+      errorBody = await response.json();
+    } catch {
+      errorBody = { detail: response.statusText };
+    }
+
+    const error = createApiError(
+      errorBody.detail || errorBody.message || `HTTP ${response.status}`,
+      response.status,
+      errorBody
+    );
+
+    this.config.onError(error);
+    throw error;
+  }
+
+  /**
+   * Execute request
+   */
+  private async request<T>(
+    method: string,
+    url: string,
+    data?: any,
+    params?: Record<string, any>
+  ): Promise<T> {
+    const fullUrl = this.buildUrl(url, params);
+    const options = this.buildOptions(method, data, params);
+
+    try {
+      const response = await this.fetchWithTimeout(fullUrl, options);
+      return await this.handleResponse<T>(response);
+    } catch (error) {
+      // Already an ApiError
+      if ((error as any).name === 'ApiError') {
+        throw error;
+      }
+
+      // Network or other error
+      const apiError = createApiError(
+        'Network request failed',
+        undefined,
+        undefined,
+        error as Error
+      );
+      this.config.onError(apiError);
+      throw apiError;
+    }
+  }
+
+  /**
+   * HTTP GET
+   */
+  async get<T>(url: string, params?: Record<string, any>): Promise<T> {
+    return this.request<T>('GET', url, undefined, params);
+  }
+
+  /**
+   * HTTP POST
+   */
+  async post<T>(url: string, data: any): Promise<T> {
+    return this.request<T>('POST', url, data);
+  }
+
+  /**
+   * HTTP PATCH
+   */
+  async patch<T>(url: string, data: any): Promise<T> {
+    return this.request<T>('PATCH', url, data);
+  }
+
+  /**
+   * HTTP DELETE
+   */
+  async delete<T>(url: string): Promise<T> {
+    return this.request<T>('DELETE', url);
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @startsimpli/funnels - API Client Module
+ *
+ * Generic API client for funnel operations.
+ * Uses adapter pattern for flexible HTTP integration.
+ *
+ * @packageDocumentation
+ */
+
+// Adapter interface
+export type { ApiAdapter, ApiError } from './adapter';
+export { createApiError, isApiError } from './adapter';
+
+// Default adapter
+export { FetchAdapter } from './default-adapter';
+export type { FetchAdapterConfig } from './default-adapter';
+
+// Client
+export { FunnelApiClient } from './client';
+export type {
+  FunnelListFilters,
+  PaginatedResponse,
+  PreviewResult,
+} from './client';