@startsimpli/api 0.1.0 → 0.2.2

package/src/lib/fetch-wrapper.ts

@@ -7,7 +7,7 @@ import { buildUrl, buildQueryString } from '../utils';
 import { ApiException, parseErrorResponse, handleFetchError } from './error-handler';
 
 export interface FetchWrapperConfig {
-  baseUrl: string;
+  baseUrl?: string;
   getToken?: () => Promise<string | null> | string | null;
   onUnauthorized?: () => void;
   onTokenRefresh?: () => Promise<string | null>;
@@ -66,7 +66,7 @@ export class FetchWrapper {
 
       // Build URL
       const url = buildUrl({
-        baseUrl: this.config.baseUrl,
+        baseUrl: this.config.baseUrl ?? '',
         endpoint,
         params,
       });
@@ -83,31 +83,36 @@ export class FetchWrapper {
       });
 
       // Handle 401 Unauthorized - attempt token refresh
-      if (response.status === 401 && this.config.onTokenRefresh) {
-        // Prevent multiple simultaneous refresh attempts
-        if (!this.isRefreshing) {
-          this.isRefreshing = true;
-          this.refreshPromise = this.config.onTokenRefresh().finally(() => {
-            this.isRefreshing = false;
-            this.refreshPromise = null;
-          });
-        }
-
-        const newToken = await this.refreshPromise;
-
-        if (newToken) {
-          // Retry original request with new token
-          const retryHeaders = new Headers(headers);
-          retryHeaders.set('Authorization', `Bearer ${newToken}`);
-
-          response = await fetch(url, {
-            method,
-            headers: retryHeaders,
-            credentials: 'include',
-            ...fetchOptions,
-          });
+      if (response.status === 401) {
+        if (this.config.onTokenRefresh) {
+          // Prevent multiple simultaneous refresh attempts
+          if (!this.isRefreshing) {
+            this.isRefreshing = true;
+            this.refreshPromise = this.config.onTokenRefresh().finally(() => {
+              this.isRefreshing = false;
+              this.refreshPromise = null;
+            });
+          }
+
+          const newToken = await this.refreshPromise;
+
+          if (newToken) {
+            // Retry original request with new token
+            const retryHeaders = new Headers(headers);
+            retryHeaders.set('Authorization', `Bearer ${newToken}`);
+
+            response = await fetch(url, {
+              method,
+              headers: retryHeaders,
+              credentials: 'include',
+              ...fetchOptions,
+            });
+          } else if (this.config.onUnauthorized) {
+            // Refresh failed - call unauthorized callback
+            this.config.onUnauthorized();
+          }
         } else if (this.config.onUnauthorized) {
-          // Refresh failed - call unauthorized callback
+          // No refresh callback - call unauthorized directly
           this.config.onUnauthorized();
         }
       }
@@ -130,6 +135,13 @@ export class FetchWrapper {
     }
   }
 
+  /**
+   * Return a new FetchWrapper with selected config fields overridden.
+   */
+  reconfigure(partial: Partial<FetchWrapperConfig>): FetchWrapper {
+    return new FetchWrapper({ ...this.config, ...partial });
+  }
+
   /**
    * GET request
    */

package/src/lib/funnels-api.ts

@@ -0,0 +1,221 @@
+/**
+ * Funnels API wrapper for /api/v1/funnels/
+ */
+
+import type {
+  Funnel,
+  FunnelFilters,
+  FunnelRun,
+  FunnelResult,
+  CreateFunnelInput,
+  UpdateFunnelInput,
+  ExecuteFunnelInput,
+  PaginatedResponse,
+  PaginationParams,
+} from '../types';
+import { ENDPOINTS } from '../constants/endpoints';
+import type { ApiClient } from './api-client';
+import { isApiException } from './error-handler';
+
+/**
+ * Returns true when the error is a 409 Conflict from trying to run a funnel that's already running.
+ */
+export function isFunnelRunConflict(error: unknown): boolean {
+  return isApiException(error) && error.status === 409;
+}
+
+/**
+ * Returns true when the error is a 400 with validation errors (bad stage rules, missing entityType, etc.)
+ */
+export function isFunnelValidationError(error: unknown): boolean {
+  return isApiException(error) && error.status === 400 && !!error.errors;
+}
+
+export interface FunnelPreviewResult {
+  total: number;
+  matched: number;
+  stages: Array<{
+    stageId: string;
+    stageName: string;
+    inputCount: number;
+    outputCount: number;
+    excluded: number;
+  }>;
+}
+
+export interface FunnelRunFilters {
+  page?: number;
+  pageSize?: number;
+  status?: FunnelRun['status'];
+  ordering?: string;
+  funnel?: string;
+  startedAfter?: string;
+  startedBefore?: string;
+}
+
+export interface FunnelTemplate {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  category: string;
+  icon: string;
+  isFeatured: boolean;
+  stageCount: number;
+  usageCount: number;
+}
+
+export class FunnelsApi {
+  constructor(private client: ApiClient) {}
+
+  /**
+   * List funnels with optional filters.
+   * Tags are passed as repeated query params: ?tags=campaign:abc&tags=product:market-simpli
+   */
+  async list(filters?: FunnelFilters): Promise<PaginatedResponse<Funnel>> {
+    const params = new URLSearchParams();
+
+    if (filters?.status) params.append('status', filters.status);
+    if (filters?.entityType) params.append('entityType', filters.entityType);
+    if (filters?.search) params.append('search', filters.search);
+    if (filters?.createdBy) params.append('createdBy', filters.createdBy);
+    if (filters?.page) params.append('page', String(filters.page));
+    if (filters?.pageSize) params.append('pageSize', String(filters.pageSize));
+    if (filters?.ordering) params.append('ordering', filters.ordering);
+
+    // tags is a multi-value param
+    if (filters?.tags?.length) {
+      for (const tag of filters.tags) {
+        params.append('tags', tag);
+      }
+    }
+
+    const query = params.toString();
+    const endpoint = query ? `${ENDPOINTS.FUNNELS}?${query}` : ENDPOINTS.FUNNELS;
+    return this.client.get<PaginatedResponse<Funnel>>(endpoint);
+  }
+
+  /**
+   * Get funnel by ID
+   */
+  async get(id: string): Promise<Funnel> {
+    return this.client.get<Funnel>(ENDPOINTS.FUNNEL(id));
+  }
+
+  /**
+   * Create a new funnel
+   */
+  async create(data: CreateFunnelInput): Promise<Funnel> {
+    return this.client.post<Funnel>(ENDPOINTS.FUNNELS, data);
+  }
+
+  /**
+   * Update funnel (partial)
+   */
+  async update(id: string, data: UpdateFunnelInput): Promise<Funnel> {
+    return this.client.patch<Funnel>(ENDPOINTS.FUNNEL(id), data);
+  }
+
+  /**
+   * Delete funnel
+   */
+  async delete(id: string): Promise<void> {
+    return this.client.delete<void>(ENDPOINTS.FUNNEL(id));
+  }
+
+  /**
+   * Execute a funnel run
+   */
+  async run(id: string, input?: ExecuteFunnelInput): Promise<FunnelRun> {
+    return this.client.post<FunnelRun>(ENDPOINTS.FUNNEL_RUN(id), input ?? {});
+  }
+
+  /**
+   * List run history for a funnel
+   */
+  async getRuns(
+    funnelId: string,
+    filters?: FunnelRunFilters
+  ): Promise<PaginatedResponse<FunnelRun>> {
+    const params = new URLSearchParams();
+    if (filters?.page) params.append('page', String(filters.page));
+    if (filters?.pageSize) params.append('pageSize', String(filters.pageSize));
+    if (filters?.status) params.append('status', filters.status);
+    if (filters?.ordering) params.append('ordering', filters.ordering);
+
+    const query = params.toString();
+    const endpoint = query
+      ? `${ENDPOINTS.FUNNEL_RUNS(funnelId)}?${query}`
+      : ENDPOINTS.FUNNEL_RUNS(funnelId);
+    return this.client.get<PaginatedResponse<FunnelRun>>(endpoint);
+  }
+
+  /**
+   * Get a specific run by ID. funnelId param is ignored (runs are accessed globally).
+   */
+  async getRun(_funnelId: string, runId: string): Promise<FunnelRun> {
+    return this.client.get<FunnelRun>(ENDPOINTS.FUNNEL_RUN_BY_ID(runId));
+  }
+
+  // BEAD: fund-your-startup-rgi4 - funnels/{id}/results endpoint missing from Django FunnelViewSet
+  async getResults(
+    _funnelId: string,
+    _pagination?: PaginationParams
+  ): Promise<PaginatedResponse<FunnelResult>> {
+    throw new Error('Not implemented - BEAD: fund-your-startup-rgi4. funnels/{id}/results action does not exist in Django.');
+    // const params = new URLSearchParams();
+    // if (_pagination?.page) params.append('page', String(_pagination.page));
+    // if (_pagination?.pageSize) params.append('pageSize', String(_pagination.pageSize));
+    // const query = params.toString();
+    // const endpoint = query ? `${ENDPOINTS.FUNNEL_RESULTS(_funnelId)}?${query}` : ENDPOINTS.FUNNEL_RESULTS(_funnelId);
+    // return this.client.get<PaginatedResponse<FunnelResult>>(endpoint);
+  }
+
+  // BEAD: fund-your-startup-rgi4 - funnels/{id}/preview endpoint missing. Django has /funnels/preview-icp/ (different signature).
+  async preview(_funnelId: string, _stages?: Funnel['stages']): Promise<FunnelPreviewResult> {
+    throw new Error('Not implemented - BEAD: fund-your-startup-rgi4. funnels/{id}/preview action does not exist in Django.');
+    // return this.client.post<FunnelPreviewResult>(ENDPOINTS.FUNNEL_PREVIEW(_funnelId), { stages: _stages });
+  }
+
+  /**
+   * List all funnel runs globally (across all funnels, scoped to current user)
+   */
+  async listRunsGlobal(filters?: FunnelRunFilters): Promise<PaginatedResponse<FunnelRun>> {
+    const params = new URLSearchParams();
+    if (filters?.funnel) params.append('funnel', filters.funnel);
+    if (filters?.status) params.append('status', filters.status);
+    if (filters?.page) params.append('page', String(filters.page));
+    if (filters?.pageSize) params.append('pageSize', String(filters.pageSize));
+    if (filters?.startedAfter) params.append('startedAfter', filters.startedAfter);
+    if (filters?.startedBefore) params.append('startedBefore', filters.startedBefore);
+
+    const query = params.toString();
+    const endpoint = query
+      ? `${ENDPOINTS.FUNNEL_RUNS_GLOBAL}?${query}`
+      : ENDPOINTS.FUNNEL_RUNS_GLOBAL;
+    return this.client.get<PaginatedResponse<FunnelRun>>(endpoint);
+  }
+
+  /**
+   * Cancel a running funnel run.
+   */
+  async cancelRun(runId: string): Promise<FunnelRun> {
+    return this.client.post<FunnelRun>(ENDPOINTS.FUNNEL_RUN_CANCEL(runId), {});
+  }
+
+  /**
+   * List available funnel templates
+   */
+  async listTemplates(filters?: { category?: string; page?: number; pageSize?: number }): Promise<PaginatedResponse<FunnelTemplate>> {
+    const params = new URLSearchParams();
+    if (filters?.category) params.append('category', filters.category);
+    if (filters?.page) params.append('page', String(filters.page));
+    if (filters?.pageSize) params.append('pageSize', String(filters.pageSize));
+
+    const query = params.toString();
+    const endpoint = query
+      ? `${ENDPOINTS.FUNNEL_TEMPLATES}?${query}`
+      : ENDPOINTS.FUNNEL_TEMPLATES;
+    return this.client.get<PaginatedResponse<FunnelTemplate>>(endpoint);
+  }
+}

package/src/middleware/index.ts

@@ -10,3 +10,6 @@ export type { ErrorApiHandler, ErrorResponseBody } from './with-error-handling';
 
 export { withValidation, composeMiddleware } from './with-validation';
 export type { ValidatedApiHandler, ValidationSchemas } from './with-validation';
+
+export { withRateLimit } from './with-rate-limit';
+export type { RateLimitCheckFn, WithRateLimitOptions } from './with-rate-limit';

package/src/middleware/with-rate-limit.ts

@@ -0,0 +1,54 @@
+/**
+ * Rate limit middleware for Next.js API routes.
+ *
+ * Accepts a pre-configured rate-limiter function (from createRateLimiter)
+ * and a key extractor. Returns 429 when the limit is exceeded.
+ */
+
+import type { NextRequest } from 'next/server'
+import { NextResponse } from 'next/server'
+import type { RateLimitResult } from '../lib/rate-limit'
+
+export type RateLimitCheckFn = (key: string) => RateLimitResult
+
+export interface WithRateLimitOptions {
+  /** Extract the rate limit key from the request (e.g. user ID or IP) */
+  getKey: (request: NextRequest) => string | Promise<string>
+  /** Human-readable message returned in the 429 error body */
+  message?: string
+}
+
+export function withRateLimit<T = unknown>(
+  handler: (request: NextRequest) => Promise<NextResponse<T>> | NextResponse<T>,
+  limiter: RateLimitCheckFn,
+  options: WithRateLimitOptions
+): (request: NextRequest) => Promise<NextResponse<T>> {
+  return async (request: NextRequest) => {
+    const key = await options.getKey(request)
+    const result = limiter(key)
+
+    if (!result.success) {
+      const retryAfter = result.retryAfter ?? Math.ceil((result.resetAt - Date.now()) / 1000)
+      return NextResponse.json(
+        {
+          success: false,
+          error: {
+            code: 'RATE_LIMITED',
+            message: options.message ?? 'Rate limit exceeded. Please try again later.',
+            retryable: true,
+          },
+        },
+        {
+          status: 429,
+          headers: {
+            'Retry-After': String(retryAfter),
+            'X-RateLimit-Remaining': '0',
+            'X-RateLimit-Reset': String(Math.ceil(result.resetAt / 1000)),
+          },
+        }
+      ) as NextResponse<T>
+    }
+
+    return handler(request)
+  }
+}

package/src/utils/drf-transforms.ts

@@ -0,0 +1,64 @@
+/**
+ * Django REST Framework response transformations
+ *
+ * Normalizes DRF paginated responses into a frontend-friendly shape.
+ */
+
+/**
+ * Raw DRF paginated response shape
+ */
+export interface DRFPaginatedResponse<T> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  results: T[];
+}
+
+/**
+ * Normalized paginated response for frontend consumption
+ */
+export interface NormalizedPaginatedResponse<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+/**
+ * Normalize a DRF paginated response into a frontend-friendly format.
+ *
+ * @param response - Raw DRF paginated response
+ * @param page - Current page number (1-based)
+ * @param pageSize - Items per page
+ */
+export function normalizePaginated<T>(
+  response: DRFPaginatedResponse<T>,
+  page: number,
+  pageSize: number
+): NormalizedPaginatedResponse<T> {
+  const total = response.count || 0;
+  return {
+    items: response.results || [],
+    total,
+    page,
+    pageSize,
+    hasNext: response.next !== null,
+    hasPrev: response.previous !== null,
+  };
+}
+
+/**
+ * Check if a response is a DRF paginated response
+ */
+export function isDRFPaginatedResponse<T = unknown>(
+  response: unknown
+): response is DRFPaginatedResponse<T> {
+  return (
+    typeof response === 'object' &&
+    response !== null &&
+    'results' in response &&
+    'count' in response
+  );
+}

package/src/utils/entity-query-builder.ts

@@ -0,0 +1,174 @@
+/**
+ * Generic Entity Query Builder
+ *
+ * Builds server-side query parameters for entity filtering.
+ * Supports tags, metrics, profiles, attributes, pagination, search, sorting, and date ranges.
+ *
+ * Usage:
+ *   const params = new EntityQueryBuilder()
+ *     .withTags('quality:tier_1', 'status:prospect')
+ *     .withMetrics('financial:aum__gte:100000000')
+ *     .paginate(1, 25)
+ *     .search('acme')
+ *     .sort('name', 'asc')
+ *     .build()
+ */
+
+export class EntityQueryBuilder {
+  private params: Map<string, string> = new Map();
+
+  /**
+   * Filter by entity type
+   */
+  entityType(type: 'CONTACT' | 'ORGANIZATION'): this {
+    this.params.set('entity_type', type);
+    return this;
+  }
+
+  /**
+   * Add tag filters (compact format: "category:name")
+   *
+   * @example
+   * .withTags('quality:tier_1', 'status:prospect')
+   * // produces: tags=quality:tier_1,status:prospect
+   */
+  withTags(...tags: string[]): this {
+    if (tags.length > 0) {
+      const existing = this.params.get('tags');
+      const combined = existing ? `${existing},${tags.join(',')}` : tags.join(',');
+      this.params.set('tags', combined);
+    }
+    return this;
+  }
+
+  /**
+   * Add metric filters (compact format: "type:subtype__operator:value")
+   *
+   * @example
+   * .withMetrics('financial:aum__gte:100000000', 'check_size:min__gte:1000000')
+   */
+  withMetrics(...metrics: string[]): this {
+    if (metrics.length > 0) {
+      const existing = this.params.get('metrics');
+      const combined = existing ? `${existing},${metrics.join(',')}` : metrics.join(',');
+      this.params.set('metrics', combined);
+    }
+    return this;
+  }
+
+  /**
+   * Add profile filters (compact format: "type:subtype")
+   *
+   * @example
+   * .withProfiles('professional:linkedin', 'social:twitter')
+   */
+  withProfiles(...profiles: string[]): this {
+    if (profiles.length > 0) {
+      const existing = this.params.get('profiles');
+      const combined = existing ? `${existing},${profiles.join(',')}` : profiles.join(',');
+      this.params.set('profiles', combined);
+    }
+    return this;
+  }
+
+  /**
+   * Add attribute filters (compact format: "type:subtype:value")
+   *
+   * @example
+   * .withAttributes('demographic:location:san_francisco')
+   */
+  withAttributes(...attrs: string[]): this {
+    if (attrs.length > 0) {
+      const existing = this.params.get('attributes');
+      const combined = existing ? `${existing},${attrs.join(',')}` : attrs.join(',');
+      this.params.set('attributes', combined);
+    }
+    return this;
+  }
+
+  /**
+   * Set pagination parameters
+   */
+  paginate(page: number, pageSize: number): this {
+    this.params.set('page', String(page));
+    this.params.set('page_size', String(pageSize));
+    return this;
+  }
+
+  /**
+   * Set search query
+   */
+  search(query: string): this {
+    const trimmed = query.trim();
+    if (trimmed) {
+      this.params.set('search', trimmed);
+    }
+    return this;
+  }
+
+  /**
+   * Set sort field and direction (maps to Django's `ordering` param)
+   */
+  sort(field: string, direction: 'asc' | 'desc' = 'asc'): this {
+    const prefix = direction === 'desc' ? '-' : '';
+    this.params.set('ordering', `${prefix}${field}`);
+    return this;
+  }
+
+  /**
+   * Add a date range filter on a given field
+   *
+   * @example
+   * .withDateRange('created', new Date('2024-01-01'), new Date('2024-12-31'))
+   * // produces: created_after=2024-01-01&created_before=2024-12-31
+   */
+  withDateRange(field: string, from?: Date, to?: Date): this {
+    if (from) {
+      this.params.set(`${field}_after`, from.toISOString().split('T')[0]);
+    }
+    if (to) {
+      this.params.set(`${field}_before`, to.toISOString().split('T')[0]);
+    }
+    return this;
+  }
+
+  /**
+   * Set an arbitrary query parameter
+   */
+  param(key: string, value: string): this {
+    this.params.set(key, value);
+    return this;
+  }
+
+  /**
+   * Build as a plain object (suitable for URLSearchParams or fetch helpers)
+   */
+  build(): Record<string, string> {
+    const result: Record<string, string> = {};
+    this.params.forEach((value, key) => {
+      result[key] = value;
+    });
+    return result;
+  }
+
+  /**
+   * Build as a query string (includes leading `?`)
+   * Returns empty string if no params.
+   */
+  toQueryString(): string {
+    if (this.params.size === 0) return '';
+    const searchParams = new URLSearchParams();
+    this.params.forEach((value, key) => {
+      searchParams.set(key, value);
+    });
+    return `?${searchParams.toString()}`;
+  }
+
+  /**
+   * Reset all parameters
+   */
+  clear(): this {
+    this.params.clear();
+    return this;
+  }
+}

package/src/utils/index.ts

@@ -2,7 +2,7 @@
  * Utility exports for @startsimpli/api
  */
 
-export { buildUrl, buildQueryString, normalizeId } from './url-builder';
+export { buildUrl, buildQueryString, normalizeId, resolveApiUrl } from './url-builder';
 export type { UrlBuilderOptions } from './url-builder';
 
 export {
@@ -11,3 +11,13 @@ export {
   mergeQueryParams,
 } from './query-params';
 export type { DjangoFilterParams } from './query-params';
+
+export { validateApiResponse } from './validate-response';
+
+export { EntityQueryBuilder } from './entity-query-builder';
+
+export { normalizePaginated, isDRFPaginatedResponse } from './drf-transforms';
+export type {
+  DRFPaginatedResponse,
+  NormalizedPaginatedResponse,
+} from './drf-transforms';

package/src/utils/url-builder.ts

@@ -66,6 +66,33 @@ export function buildQueryString(params: Record<string, unknown>): string {
   return searchParams.toString();
 }
 
+/**
+ * Resolve a full or partial API path to a final URL.
+ *
+ * Handles four cases:
+ * - Absolute input URL → returned unchanged
+ * - Absolute baseUrl  → joined via URL constructor
+ * - Relative baseUrl  → string concatenation
+ * - Empty / undefined baseUrl → path returned as-is (suits Next.js proxy pattern)
+ */
+export function resolveApiUrl(path: string, baseUrl: string = ''): string {
+  // Already a full URL — pass through unchanged
+  if (/^https?:\/\//i.test(path)) return path;
+
+  const normalized = path.startsWith('/') ? path : `/${path}`;
+
+  if (!baseUrl) return normalized;
+
+  // Absolute base: use URL constructor for correct joining
+  if (/^https?:\/\//i.test(baseUrl)) {
+    return new URL(normalized, baseUrl).toString();
+  }
+
+  // Relative base: strip trailing slash, prepend
+  const cleanBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+  return `${cleanBase}${normalized}`;
+}
+
 /**
  * Extract ID from URL or return as-is
  */