@startsimpli/api 0.5.6 → 0.5.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/api",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "Type-safe Django REST API client for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

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

@@ -123,6 +123,31 @@ describe('JWT Refresh Flow', () => {
     expect(refreshCallback).toHaveBeenCalledTimes(1);
   });
 
+  it('should fire onUnauthorized at most once when many parallel 401s fail refresh', async () => {
+    const wrapper = new FetchWrapper({
+      baseUrl: 'http://localhost:8000',
+      getToken: () => 'old-token',
+      onTokenRefresh: refreshCallback,
+      onUnauthorized: unauthorizedCallback,
+    });
+
+    const mock401 = { status: 401, ok: false, headers: new Headers(), text: async () => '' };
+
+    // All five requests hit 401 and the retry is also 401 (refresh returned null)
+    mockFetch.mockResolvedValue(mock401);
+    refreshCallback.mockResolvedValue(null);
+
+    await Promise.allSettled([
+      wrapper.get('/api/v1/a/'),
+      wrapper.get('/api/v1/b/'),
+      wrapper.get('/api/v1/c/'),
+      wrapper.get('/api/v1/d/'),
+      wrapper.get('/api/v1/e/'),
+    ]);
+
+    expect(unauthorizedCallback).toHaveBeenCalledTimes(1);
+  });
+
   it('should work without refresh callback (backward compatible)', async () => {
     const wrapper = new FetchWrapper({
       baseUrl: 'http://localhost:8000',

package/src/constants/endpoints.ts

@@ -40,15 +40,24 @@ export const ENDPOINTS = {
   // Funnels
   FUNNELS: 'api/v1/funnels',
   FUNNEL: (id: string) => `api/v1/funnels/${id}`,
+  FUNNEL_PIPELINE: (id: string) => `api/v1/funnels/${id}/pipeline`,
+  FUNNEL_ADD_ENTITY: (id: string) => `api/v1/funnels/${id}/add_entity`,
+  FUNNEL_MOVE: (id: string) => `api/v1/funnels/${id}/move`,
+  FUNNEL_STATS: (id: string) => `api/v1/funnels/${id}/stats`,
   FUNNEL_RUN: (id: string) => `api/v1/funnels/${id}/run`,
   FUNNEL_RUNS: (id: string) => `api/v1/funnels/${id}/runs`,
   FUNNEL_RUN_ITEM: (funnelId: string, runId: string) => `api/v1/funnels/${funnelId}/runs/${runId}`,
   FUNNEL_PREVIEW: (id: string) => `api/v1/funnels/${id}/preview`,
   FUNNEL_RESULTS: (id: string) => `api/v1/funnels/${id}/results`,
   FUNNEL_TEMPLATES: 'api/v1/funnels/templates',
+  FUNNEL_FIELDS: 'api/v1/funnels/fields',
   FUNNEL_RUN_BY_ID: (runId: string) => `api/v1/funnel-runs/${runId}`,
   FUNNEL_RUN_CANCEL: (runId: string) => `api/v1/funnel-runs/${runId}/cancel`,
   FUNNEL_RUNS_GLOBAL: 'api/v1/funnel-runs',
+  // Enrichment
+  ENRICHMENT_QUEUE: 'api/v1/enrichment/start-processing',
+  CONTACT_ENRICH: (id: string) => `api/v1/contacts/${id}/enrich`,
+
   // Users
   USER_ME: 'api/v1/users/me',
   USER_CHANGE_PASSWORD: 'api/v1/users/me/change-password',

package/src/index.ts

@@ -9,17 +9,47 @@
 export { ApiClient, createApiClient } from './lib/api-client';
 export type { ApiClientConfig } from './lib/api-client';
 
+// Entity adapter factory
+export { createEntityAdapter } from './lib/entity-adapter';
+export type { EntityAdapterConfig, EntityAdapter } from './lib/entity-adapter';
+
 // API wrappers
 export { ContactsApi } from './lib/contacts-api';
 export { OrganizationsApi } from './lib/organizations-api';
 export { EntitiesApi } from './lib/entities-api';
 export { WorkflowsApi } from './lib/workflows-api';
 export { MessagesApi } from './lib/messages-api';
-export type { Message, MessageStatus as MessageApiStatus, MessageRecipient, MessagingChannel as MessagingChannelType } from './lib/messages-api';
+export type { Message, MessageStatus as MessageApiStatus, MessageRecipient, MessagingChannel as MessagingChannelType, MessageFilters, CreateMessageInput, ScheduleMessageInput, SendTestInput } from './lib/messages-api';
+export { calculateStatsFromMessages } from './lib/message-stats';
+export type { MessageStats } from './lib/message-stats';
+export { MessageTemplatesApi } from './lib/message-templates-api';
+export type { MessageTemplate, MessageTemplateFilters, CreateMessageTemplateInput } from './lib/message-templates-api';
 export { UsersApi } from './lib/users-api';
 export type { UserProfile, UpdateProfileRequest, ChangePasswordRequest, ChangePasswordResponse } from './types/user';
 export { FunnelsApi, isFunnelRunConflict, isFunnelValidationError } from './lib/funnels-api';
-export type { FunnelPreviewResult, FunnelRunFilters, FunnelTemplate } from './lib/funnels-api';
+export type {
+  FunnelPreviewResult,
+  FunnelRunFilters,
+  FunnelTemplate,
+  FunnelFieldDefinition,
+  FunnelFieldsResponse,
+} from './lib/funnels-api';
+export { EnrichmentApi } from './lib/enrichment-api';
+export { TargetListsApi } from './lib/target-lists-api';
+export type {
+  TargetList,
+  TargetListMember,
+  CreateTargetListInput,
+  UpdateTargetListInput,
+  TargetListFilters,
+  TargetListMemberFilters,
+  TargetType,
+  ListSourceType,
+  RefreshStrategy,
+  AddMembersResult,
+  RemoveMembersResult,
+  RefreshResult,
+} from './lib/target-lists-api';
 
 // Feature flags
 export { FeatureFlagsApi, FeatureFlagProvider, useFeatureFlags } from './lib/feature-flags';
@@ -129,6 +159,9 @@ import { MessagesApi } from './lib/messages-api';
 import { FunnelsApi } from './lib/funnels-api';
 import { FeatureFlagsApi } from './lib/feature-flags';
 import { UsersApi } from './lib/users-api';
+import { EnrichmentApi } from './lib/enrichment-api';
+import { TargetListsApi } from './lib/target-lists-api';
+import { MessageTemplatesApi } from './lib/message-templates-api';
 
 import type { ApiClientConfig } from './lib/api-client';
 
@@ -149,5 +182,8 @@ export function createStartSimpliApi(config: ApiClientConfig = {}) {
     funnels: new FunnelsApi(client),
     featureFlags: new FeatureFlagsApi(client),
     users: new UsersApi(client),
+    enrichment: new EnrichmentApi(client),
+    targetLists: new TargetListsApi(client),
+    messageTemplates: new MessageTemplatesApi(client),
   };
 }

package/src/lib/__tests__/entity-adapter.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createEntityAdapter } from '../entity-adapter';
+import type { EntityAdapterConfig } from '../entity-adapter';
+
+// --- Test types ---
+
+interface DomainUser {
+  id: string;
+  fullName: string;
+  email: string;
+}
+
+interface ApiUser {
+  id: string;
+  first_name: string;
+  last_name: string;
+  email_address: string;
+}
+
+function makeConfig(overrides: Partial<EntityAdapterConfig<DomainUser, ApiUser>> = {}) {
+  return {
+    list: vi.fn().mockResolvedValue({ results: [], count: 0 }),
+    get: vi.fn().mockResolvedValue({ id: '1', first_name: 'Jane', last_name: 'Doe', email_address: 'jane@example.com' }),
+    create: vi.fn().mockImplementation(async (data: Partial<ApiUser>) => ({
+      id: '2',
+      first_name: data.first_name ?? '',
+      last_name: data.last_name ?? '',
+      email_address: data.email_address ?? '',
+    })),
+    update: vi.fn().mockImplementation(async (_id: string, data: Partial<ApiUser>) => ({
+      id: _id,
+      first_name: data.first_name ?? 'Jane',
+      last_name: data.last_name ?? 'Doe',
+      email_address: data.email_address ?? 'jane@example.com',
+    })),
+    delete: vi.fn().mockResolvedValue(undefined),
+    toEntity: (api: ApiUser): DomainUser => ({
+      id: api.id,
+      fullName: `${api.first_name} ${api.last_name}`,
+      email: api.email_address,
+    }),
+    toApi: (input: Record<string, unknown>): Partial<ApiUser> => {
+      const result: Partial<ApiUser> = {};
+      if (input.fullName) {
+        const parts = (input.fullName as string).split(' ');
+        result.first_name = parts[0];
+        result.last_name = parts.slice(1).join(' ');
+      }
+      if (input.email) {
+        result.email_address = input.email as string;
+      }
+      return result;
+    },
+    ...overrides,
+  } satisfies EntityAdapterConfig<DomainUser, ApiUser>;
+}
+
+describe('createEntityAdapter', () => {
+  describe('list', () => {
+    it('maps API results through toEntity and preserves count', async () => {
+      const apiUsers: ApiUser[] = [
+        { id: '1', first_name: 'Jane', last_name: 'Doe', email_address: 'jane@example.com' },
+        { id: '2', first_name: 'John', last_name: 'Smith', email_address: 'john@example.com' },
+      ];
+      const config = makeConfig({
+        list: vi.fn().mockResolvedValue({ results: apiUsers, count: 42 }),
+      });
+      const adapter = createEntityAdapter(config);
+
+      const result = await adapter.list({ page: 1 });
+
+      expect(config.list).toHaveBeenCalledWith({ page: 1 });
+      expect(result.count).toBe(42);
+      expect(result.results).toEqual([
+        { id: '1', fullName: 'Jane Doe', email: 'jane@example.com' },
+        { id: '2', fullName: 'John Smith', email: 'john@example.com' },
+      ]);
+    });
+
+    it('passes undefined filters when called without arguments', async () => {
+      const config = makeConfig();
+      const adapter = createEntityAdapter(config);
+
+      await adapter.list();
+
+      expect(config.list).toHaveBeenCalledWith(undefined);
+    });
+
+    it('returns empty results for empty API response', async () => {
+      const config = makeConfig({
+        list: vi.fn().mockResolvedValue({ results: [], count: 0 }),
+      });
+      const adapter = createEntityAdapter(config);
+
+      const result = await adapter.list();
+
+      expect(result).toEqual({ results: [], count: 0 });
+    });
+  });
+
+  describe('get', () => {
+    it('maps a single API resource through toEntity', async () => {
+      const config = makeConfig();
+      const adapter = createEntityAdapter(config);
+
+      const result = await adapter.get('1');
+
+      expect(config.get).toHaveBeenCalledWith('1');
+      expect(result).toEqual({
+        id: '1',
+        fullName: 'Jane Doe',
+        email: 'jane@example.com',
+      });
+    });
+  });
+
+  describe('create', () => {
+    it('transforms input via toApi, calls config.create, maps result via toEntity', async () => {
+      const config = makeConfig();
+      const adapter = createEntityAdapter(config);
+
+      const result = await adapter.create({ fullName: 'Alice Wonder', email: 'alice@example.com' });
+
+      expect(config.create).toHaveBeenCalledWith({
+        first_name: 'Alice',
+        last_name: 'Wonder',
+        email_address: 'alice@example.com',
+      });
+      expect(result).toEqual({
+        id: '2',
+        fullName: 'Alice Wonder',
+        email: 'alice@example.com',
+      });
+    });
+  });
+
+  describe('update', () => {
+    it('transforms input via toApi, calls config.update with id, maps result via toEntity', async () => {
+      const config = makeConfig();
+      const adapter = createEntityAdapter(config);
+
+      const result = await adapter.update('1', { fullName: 'Jane Updated', email: 'new@example.com' });
+
+      expect(config.update).toHaveBeenCalledWith('1', {
+        first_name: 'Jane',
+        last_name: 'Updated',
+        email_address: 'new@example.com',
+      });
+      expect(result).toEqual({
+        id: '1',
+        fullName: 'Jane Updated',
+        email: 'new@example.com',
+      });
+    });
+  });
+
+  describe('delete', () => {
+    it('passes through to config.delete', async () => {
+      const config = makeConfig();
+      const adapter = createEntityAdapter(config);
+
+      await adapter.delete('1');
+
+      expect(config.delete).toHaveBeenCalledWith('1');
+    });
+
+    it('returns void', async () => {
+      const config = makeConfig();
+      const adapter = createEntityAdapter(config);
+
+      const result = await adapter.delete('1');
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('error propagation', () => {
+    it('propagates list errors', async () => {
+      const config = makeConfig({
+        list: vi.fn().mockRejectedValue(new Error('Network error')),
+      });
+      const adapter = createEntityAdapter(config);
+
+      await expect(adapter.list()).rejects.toThrow('Network error');
+    });
+
+    it('propagates get errors', async () => {
+      const config = makeConfig({
+        get: vi.fn().mockRejectedValue(new Error('Not found')),
+      });
+      const adapter = createEntityAdapter(config);
+
+      await expect(adapter.get('999')).rejects.toThrow('Not found');
+    });
+
+    it('propagates create errors', async () => {
+      const config = makeConfig({
+        create: vi.fn().mockRejectedValue(new Error('Validation failed')),
+      });
+      const adapter = createEntityAdapter(config);
+
+      await expect(adapter.create({ fullName: 'X' })).rejects.toThrow('Validation failed');
+    });
+
+    it('propagates update errors', async () => {
+      const config = makeConfig({
+        update: vi.fn().mockRejectedValue(new Error('Conflict')),
+      });
+      const adapter = createEntityAdapter(config);
+
+      await expect(adapter.update('1', { fullName: 'X' })).rejects.toThrow('Conflict');
+    });
+
+    it('propagates delete errors', async () => {
+      const config = makeConfig({
+        delete: vi.fn().mockRejectedValue(new Error('Forbidden')),
+      });
+      const adapter = createEntityAdapter(config);
+
+      await expect(adapter.delete('1')).rejects.toThrow('Forbidden');
+    });
+  });
+});

package/src/lib/enrichment-api.ts

@@ -0,0 +1,57 @@
+/**
+ * Enrichment API wrapper for /api/v1/enrichment/ and /api/v1/contacts/:id/enrich/
+ */
+
+import type { EnrichmentResult, QueueStatus } from '../types';
+import { ENDPOINTS } from '../constants/endpoints';
+import type { ApiClient } from './api-client';
+
+export class EnrichmentApi {
+  constructor(private client: ApiClient) {}
+
+  /**
+   * Enrich a single contact by ID
+   */
+  async enrich(contactId: string): Promise<EnrichmentResult> {
+    return this.client.fetch.post<EnrichmentResult>(
+      ENDPOINTS.CONTACT_ENRICH(contactId),
+      {}
+    );
+  }
+
+  /**
+   * Enrich multiple contacts. Calls the single-contact endpoint for each ID.
+   * Returns results in order, including failures.
+   */
+  async bulkEnrich(
+    contactIds: string[],
+    onProgress?: (completed: number, total: number) => void
+  ): Promise<EnrichmentResult[]> {
+    const results: EnrichmentResult[] = [];
+
+    for (let i = 0; i < contactIds.length; i++) {
+      try {
+        const result = await this.enrich(contactIds[i]);
+        results.push(result);
+      } catch (err: unknown) {
+        results.push({
+          contactId: contactIds[i],
+          contactName: '',
+          success: false,
+          fieldsUpdated: [],
+          error: err instanceof Error ? err.message : 'Enrichment failed',
+        });
+      }
+      onProgress?.(i + 1, contactIds.length);
+    }
+
+    return results;
+  }
+
+  /**
+   * Get the current enrichment queue status
+   */
+  async getQueueStatus(): Promise<QueueStatus> {
+    return this.client.fetch.get<QueueStatus>(ENDPOINTS.ENRICHMENT_QUEUE);
+  }
+}

package/src/lib/entity-adapter.ts

@@ -0,0 +1,66 @@
+/**
+ * Entity Adapter — thin mapping layer between domain entities and API resources.
+ *
+ * Creates a typed CRUD client that translates between a domain entity shape
+ * (used by the UI) and the raw API resource shape (returned by Django).
+ */
+
+export interface EntityAdapterConfig<TEntity, TApi> {
+  /** List API resources with optional filters. Returns paginated response. */
+  list: (filters?: Record<string, unknown>) => Promise<{ results: TApi[]; count: number }>;
+  /** Get a single API resource by ID. */
+  get: (id: string) => Promise<TApi>;
+  /** Create an API resource. */
+  create: (data: Partial<TApi>) => Promise<TApi>;
+  /** Update an API resource by ID. */
+  update: (id: string, data: Partial<TApi>) => Promise<TApi>;
+  /** Delete an API resource by ID. */
+  delete: (id: string) => Promise<void>;
+  /** Transform an API resource into the domain entity. */
+  toEntity: (api: TApi) => TEntity;
+  /** Transform domain input into the API shape for create/update. */
+  toApi: (input: Record<string, unknown>) => Partial<TApi>;
+}
+
+export interface EntityAdapter<TEntity> {
+  list: (filters?: Record<string, unknown>) => Promise<{ results: TEntity[]; count: number }>;
+  get: (id: string) => Promise<TEntity>;
+  create: (input: Record<string, unknown>) => Promise<TEntity>;
+  update: (id: string, input: Record<string, unknown>) => Promise<TEntity>;
+  delete: (id: string) => Promise<void>;
+}
+
+export function createEntityAdapter<TEntity, TApi>(
+  config: EntityAdapterConfig<TEntity, TApi>,
+): EntityAdapter<TEntity> {
+  return {
+    async list(filters?: Record<string, unknown>) {
+      const response = await config.list(filters);
+      return {
+        results: response.results.map(config.toEntity),
+        count: response.count,
+      };
+    },
+
+    async get(id: string) {
+      const raw = await config.get(id);
+      return config.toEntity(raw);
+    },
+
+    async create(input: Record<string, unknown>) {
+      const apiData = config.toApi(input);
+      const raw = await config.create(apiData);
+      return config.toEntity(raw);
+    },
+
+    async update(id: string, input: Record<string, unknown>) {
+      const apiData = config.toApi(input);
+      const raw = await config.update(id, apiData);
+      return config.toEntity(raw);
+    },
+
+    async delete(id: string) {
+      await config.delete(id);
+    },
+  };
+}

package/src/lib/fetch-wrapper.ts

@@ -25,11 +25,20 @@ export class FetchWrapper {
   private config: FetchWrapperConfig;
   private isRefreshing = false;
   private refreshPromise: Promise<string | null> | null = null;
+  private unauthorizedFiredAt = 0;
 
   constructor(config: FetchWrapperConfig) {
     this.config = config;
   }
 
+  private fireUnauthorizedOnce(): void {
+    if (!this.config.onUnauthorized) return;
+    const now = Date.now();
+    if (now - this.unauthorizedFiredAt < 5000) return;
+    this.unauthorizedFiredAt = now;
+    this.config.onUnauthorized();
+  }
+
   /**
    * Build headers with auth token
    */
@@ -117,13 +126,15 @@ export class FetchWrapper {
               credentials: 'include',
               ...fetchOptions,
             });
-          } else if (this.config.onUnauthorized) {
-            // Refresh failed - call unauthorized callback
-            this.config.onUnauthorized();
+
+            if (response.status === 401) {
+              this.fireUnauthorizedOnce();
+            }
+          } else {
+            this.fireUnauthorizedOnce();
           }
-        } else if (this.config.onUnauthorized) {
-          // No refresh callback - call unauthorized directly
-          this.config.onUnauthorized();
+        } else {
+          this.fireUnauthorizedOnce();
         }
       }
 

package/src/lib/funnels-api.ts

@@ -65,6 +65,21 @@ export interface FunnelTemplate {
   usageCount: number;
 }
 
+/** One entry in the field registry served by GET /api/v1/funnels/fields/ */
+export interface FunnelFieldDefinition {
+  key: string;
+  label: string;
+  category: string;
+  valueType: 'string' | 'number' | 'boolean' | 'enum' | 'date';
+  enumValues: string[];
+  allowedOperators: string[];
+}
+
+export interface FunnelFieldsResponse {
+  entityType: string | null;
+  fields: FunnelFieldDefinition[];
+}
+
 export class FunnelsApi {
   constructor(private client: ApiClient) {}
 
@@ -123,6 +138,44 @@ export class FunnelsApi {
     return this.client.delete<void>(ENDPOINTS.FUNNEL(id));
   }
 
+  // ── Generic pipeline actions (work with any funnel/profile) ──────────
+
+  /**
+   * Get entities grouped by stage (kanban view).
+   * Works for any funnel that has a membership run with entities in stages.
+   */
+  async pipeline(id: string): Promise<Record<string, FunnelResult[]>> {
+    return this.client.get<Record<string, FunnelResult[]>>(ENDPOINTS.FUNNEL_PIPELINE(id));
+  }
+
+  /**
+   * Add an entity to a funnel's membership run.
+   * Creates a FunnelResult with the entity + optional context (deal amount, notes, etc.)
+   */
+  async addEntity(
+    funnelId: string,
+    data: { entityId: string; stage?: string; context?: Record<string, unknown> }
+  ): Promise<FunnelResult> {
+    return this.client.post<FunnelResult>(ENDPOINTS.FUNNEL_ADD_ENTITY(funnelId), data);
+  }
+
+  /**
+   * Move an entity to a different stage within a funnel.
+   */
+  async move(
+    funnelId: string,
+    data: { entityId: string; newStage: string; context?: Record<string, unknown> }
+  ): Promise<FunnelResult> {
+    return this.client.post<FunnelResult>(ENDPOINTS.FUNNEL_MOVE(funnelId), data);
+  }
+
+  /**
+   * Get funnel statistics (stage counts, conversion rates, etc.)
+   */
+  async stats(funnelId: string): Promise<Record<string, unknown>> {
+    return this.client.get<Record<string, unknown>>(ENDPOINTS.FUNNEL_STATS(funnelId));
+  }
+
   /**
    * Execute a funnel run
    */
@@ -157,24 +210,26 @@ export class FunnelsApi {
     return this.client.get<FunnelRun>(ENDPOINTS.FUNNEL_RUN_BY_ID(runId));
   }
 
-  // BEAD: fund-your-startup-rgi4 - funnels/{id}/results endpoint missing from Django FunnelViewSet
+  /**
+   * Get results (entities) from a funnel's latest completed run.
+   */
   async getResults(
-    _funnelId: string,
-    _pagination?: PaginationParams
+    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);
+    const params = new URLSearchParams();
+    if (pagination?.page) params.append('page', String(pagination.page));
+    if (pagination?.pageSize) params.append('page_size', 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 });
+  /**
+   * Preview funnel execution without persisting results.
+   */
+  async preview(funnelId: string, stages?: Funnel['stages']): Promise<FunnelPreviewResult> {
+    return this.client.post<FunnelPreviewResult>(ENDPOINTS.FUNNEL_PREVIEW(funnelId), { stages });
   }
 
   /**
@@ -218,4 +273,17 @@ export class FunnelsApi {
       : ENDPOINTS.FUNNEL_TEMPLATES;
     return this.client.get<PaginatedResponse<FunnelTemplate>>(endpoint);
   }
+
+  /**
+   * Fetch the funnel rule field registry. Drives the generic rule editor UI.
+   */
+  async getFields(entityType?: string): Promise<FunnelFieldsResponse> {
+    // Trailing slash before the query string — Django's APPEND_SLASH does not
+    // redirect when a query string is present, so the URL must already end
+    // with a slash before '?entity_type='.
+    const endpoint = entityType
+      ? `${ENDPOINTS.FUNNEL_FIELDS}/?entity_type=${encodeURIComponent(entityType)}`
+      : `${ENDPOINTS.FUNNEL_FIELDS}/`;
+    return this.client.get<FunnelFieldsResponse>(endpoint);
+  }
 }

package/src/lib/message-stats.ts

@@ -0,0 +1,46 @@
+/**
+ * Message statistics utilities
+ *
+ * Calculates aggregate stats from an array of Message objects.
+ */
+
+import type { Message } from './messages-api';
+
+export interface MessageStats {
+  sent: number;
+  opened: number;
+  clicked: number;
+  replied: number;
+  bounced: number;
+  unsubscribed: number;
+  openRate: number;
+  clickRate: number;
+  replyRate: number;
+  bounceRate: number;
+}
+
+/**
+ * Calculate aggregate stats from an array of messages.
+ */
+export function calculateStatsFromMessages(messages: Message[]): MessageStats {
+  const sent = messages.length;
+  const opened = messages.filter((m) => (m.recipientsOpened ?? 0) > 0).length;
+  const clicked = messages.filter((m) => (m.recipientsClicked ?? 0) > 0).length;
+  const replied = messages.filter((m) => (m.recipientsReplied ?? 0) > 0).length;
+  const bounced = messages.filter((m) => (m.recipientsBounced ?? 0) > 0).length;
+  // recipientsUnsubscribed is not included in list endpoint responses; fall back to 0
+  const unsubscribed = messages.filter((m) => (m.recipientsUnsubscribed ?? 0) > 0).length;
+
+  return {
+    sent,
+    opened,
+    clicked,
+    replied,
+    bounced,
+    unsubscribed,
+    openRate: sent > 0 ? (opened / sent) * 100 : 0,
+    clickRate: sent > 0 ? (clicked / sent) * 100 : 0,
+    replyRate: sent > 0 ? (replied / sent) * 100 : 0,
+    bounceRate: sent > 0 ? (bounced / sent) * 100 : 0,
+  };
+}

package/src/lib/message-templates-api.ts

@@ -0,0 +1,95 @@
+/**
+ * Message Templates API wrapper
+ *
+ * Provides type-safe access to Django Message Templates API
+ */
+
+import type { ApiClient } from './api-client';
+
+export interface MessageTemplate {
+  id: string;
+  name: string;
+  description: string | null;
+  subjectTemplate: string;
+  bodyTemplate: string;
+  channel: string | null;
+  entityType: string | null;
+  category: string | null;
+  isDefault: boolean;
+  useCount: number;
+  blocks: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MessageTemplateFilters {
+  channel?: string;
+  entityType?: string;
+  category?: string;
+  search?: string;
+  page?: number;
+  pageSize?: number;
+  ordering?: string;
+}
+
+export interface CreateMessageTemplateInput {
+  name: string;
+  description?: string;
+  subjectTemplate: string;
+  bodyTemplate: string;
+  channel?: string;
+  entityType?: string;
+  category?: string;
+  blocks?: string | null;
+}
+
+export class MessageTemplatesApi {
+  constructor(private client: ApiClient) {}
+
+  /**
+   * List message templates with optional filters
+   */
+  async list(filters?: MessageTemplateFilters) {
+    const params = new URLSearchParams();
+
+    if (filters?.channel) params.append('channel', filters.channel);
+    if (filters?.entityType) params.append('entityType', filters.entityType);
+    if (filters?.category) params.append('category', filters.category);
+    if (filters?.search) params.append('search', filters.search);
+    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);
+
+    return this.client.get<{ results: MessageTemplate[]; count: number; next: string | null; previous: string | null }>(
+      `/api/v1/message-templates/?${params.toString()}`
+    );
+  }
+
+  /**
+   * Get message template by ID
+   */
+  async get(id: string) {
+    return this.client.get<MessageTemplate>(`/api/v1/message-templates/${id}/`);
+  }
+
+  /**
+   * Create a new message template
+   */
+  async create(data: CreateMessageTemplateInput) {
+    return this.client.post<MessageTemplate>('/api/v1/message-templates/', data);
+  }
+
+  /**
+   * Update message template
+   */
+  async update(id: string, data: Partial<CreateMessageTemplateInput>) {
+    return this.client.patch<MessageTemplate>(`/api/v1/message-templates/${id}/`, data);
+  }
+
+  /**
+   * Delete message template
+   */
+  async delete(id: string) {
+    return this.client.delete(`/api/v1/message-templates/${id}/`);
+  }
+}

package/src/lib/messages-api.ts

@@ -35,10 +35,12 @@ export interface Message {
   recipientsDelivered: number;
   recipientsOpened: number;
   recipientsClicked: number;
+  recipientsReplied: number;
   recipientsBounced: number;
   recipientsUnsubscribed: number;
   openRate: number;
   clickRate: number;
+  replyRate: number;
   bounceRate: number;
   errorMessage: string | null;
   createdAt: string;

package/src/lib/target-lists-api.ts

@@ -0,0 +1,190 @@
+/**
+ * Target Lists API wrapper for /api/v1/targets/lists/
+ *
+ * Shared across all StartSimpli apps for managing contact/organization lists.
+ * All types use camelCase — FetchWrapper auto-converts snake_case↔camelCase.
+ */
+
+import type { ApiClient } from './api-client';
+import type { PaginatedResponse } from '../types';
+
+// ── Types (camelCase — auto-converted from Django snake_case by FetchWrapper) ──
+
+export type TargetType = 'contact' | 'organization';
+export type ListSourceType = 'static' | 'funnel' | 'query';
+export type RefreshStrategy = 'manual' | 'on_funnel_run' | 'scheduled';
+
+export interface TargetList {
+  id: string;
+  name: string;
+  description: string;
+  targetType: TargetType;
+  sourceType: ListSourceType;
+  memberCount: number;
+  refreshStrategy: RefreshStrategy;
+  lastRefreshedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TargetListMember {
+  id: string;
+  objectId: string;
+  contentType: string;
+  addedAt: string;
+  metadata: Record<string, unknown>;
+  name?: string;
+  email?: string;
+  firm?: string;
+}
+
+export interface CreateTargetListInput {
+  name: string;
+  description?: string;
+  targetType?: TargetType;
+  sourceType?: ListSourceType;
+}
+
+export interface UpdateTargetListInput {
+  name?: string;
+  description?: string;
+}
+
+export interface TargetListFilters {
+  targetType?: TargetType;
+  search?: string;
+  page?: number;
+  pageSize?: number;
+  ordering?: string;
+}
+
+export interface TargetListMemberFilters {
+  search?: string;
+  page?: number;
+  pageSize?: number;
+  ordering?: string;
+}
+
+export interface AddMembersResult {
+  added: number;
+  alreadyExists: number;
+  total: number;
+}
+
+export interface RemoveMembersResult {
+  removed: number;
+  total: number;
+}
+
+export interface RefreshResult {
+  added: number;
+  removed: number;
+  total: number;
+}
+
+// ── Endpoints ────────────────────────────────────────────────────────────
+
+const LISTS_BASE = 'api/v1/targets/lists';
+const LIST = (id: string) => `${LISTS_BASE}/${id}`;
+const LIST_MEMBERS = (id: string) => `${LISTS_BASE}/${id}/members`;
+const LIST_ADD_MEMBERS = (id: string) => `${LISTS_BASE}/${id}/add_members`;
+const LIST_REMOVE_MEMBERS = (id: string) => `${LISTS_BASE}/${id}/remove_members`;
+const LIST_REFRESH = (id: string) => `${LISTS_BASE}/${id}/refresh`;
+
+// ── API Class ────────────────────────────────────────────────────────────
+
+export class TargetListsApi {
+  constructor(private client: ApiClient) {}
+
+  /** List all target lists with pagination and filters */
+  async list(filters?: TargetListFilters): Promise<PaginatedResponse<TargetList>> {
+    // Query params use snake_case (sent directly to Django as URL params)
+    const params: Record<string, string> = {};
+    if (filters?.targetType) params.target_type = filters.targetType;
+    if (filters?.search) params.search = filters.search;
+    if (filters?.page) params.page = String(filters.page);
+    if (filters?.pageSize) params.page_size = String(filters.pageSize);
+    if (filters?.ordering) params.ordering = filters.ordering;
+
+    const response = await this.client.fetch.get<PaginatedResponse<TargetList> | TargetList[]>(
+      LISTS_BASE,
+      { params }
+    );
+
+    if (Array.isArray(response)) {
+      return { count: response.length, results: response, next: null, previous: null };
+    }
+    return response as PaginatedResponse<TargetList>;
+  }
+
+  /** Get a single target list by ID */
+  async get(id: string): Promise<TargetList> {
+    return this.client.fetch.get<TargetList>(LIST(id));
+  }
+
+  /** Create a new target list (camelCase body → auto-converted to snake_case by serializeBody) */
+  async create(data: CreateTargetListInput): Promise<TargetList> {
+    return this.client.fetch.post<TargetList>(LISTS_BASE, {
+      name: data.name,
+      description: data.description || '',
+      targetType: data.targetType || 'contact',
+      sourceType: data.sourceType || 'static',
+    });
+  }
+
+  /** Update an existing target list */
+  async update(id: string, data: UpdateTargetListInput): Promise<TargetList> {
+    return this.client.fetch.patch<TargetList>(LIST(id), data);
+  }
+
+  /** Delete a target list */
+  async delete(id: string): Promise<void> {
+    return this.client.fetch.delete(LIST(id));
+  }
+
+  /** Get members of a target list with pagination */
+  async getMembers(
+    listId: string,
+    filters?: TargetListMemberFilters
+  ): Promise<PaginatedResponse<TargetListMember>> {
+    const params: Record<string, string> = {};
+    if (filters?.search) params.search = filters.search;
+    if (filters?.page) params.page = String(filters.page);
+    if (filters?.pageSize) params.page_size = String(filters.pageSize);
+    if (filters?.ordering) params.ordering = filters.ordering;
+
+    const response = await this.client.fetch.get<PaginatedResponse<TargetListMember> | TargetListMember[]>(
+      LIST_MEMBERS(listId),
+      { params }
+    );
+
+    if (Array.isArray(response)) {
+      return { count: response.length, results: response, next: null, previous: null };
+    }
+    return response as PaginatedResponse<TargetListMember>;
+  }
+
+  /** Add members (camelCase body → auto-converted to snake_case) */
+  async addMembers(
+    listId: string,
+    objectIds: string[],
+    metadata?: Record<string, unknown>
+  ): Promise<AddMembersResult> {
+    return this.client.fetch.post<AddMembersResult>(LIST_ADD_MEMBERS(listId), {
+      objectIds,
+      ...(metadata ? { metadata } : {}),
+    });
+  }
+
+  /** Remove members */
+  async removeMembers(listId: string, objectIds: string[]): Promise<RemoveMembersResult> {
+    return this.client.fetch.post<RemoveMembersResult>(LIST_REMOVE_MEMBERS(listId), {
+      objectIds,
+    });
+  }
+
+  /** Refresh a funnel/query-based list */
+  async refresh(listId: string): Promise<RefreshResult> {
+    return this.client.fetch.post<RefreshResult>(LIST_REFRESH(listId));
+  }
+}

package/src/types/enrichment.ts

@@ -0,0 +1,28 @@
+/**
+ * Enrichment types — shared across all StartSimpli apps
+ */
+
+export interface EnrichmentResult {
+  contactId: string;
+  contactName: string;
+  success: boolean;
+  fieldsUpdated: string[];
+  error?: string;
+}
+
+export interface QueueStatus {
+  pending: number;
+  processing: number;
+  completed: number;
+  failed: number;
+}
+
+export type EnrichmentProvider = 'apollo' | 'hunter';
+
+export interface IntegrationStatus {
+  name: string;
+  provider: EnrichmentProvider;
+  connected: boolean;
+  description: string;
+  lastSync?: string;
+}

package/src/types/index.ts

@@ -89,6 +89,14 @@ export type {
   ChangePasswordResponse,
 } from './user';
 
+// Enrichment types
+export type {
+  EnrichmentResult,
+  QueueStatus,
+  EnrichmentProvider,
+  IntegrationStatus,
+} from './enrichment';
+
 // Error types
 export type {
   FieldError,

package/src/types/user.ts

@@ -1,29 +1,30 @@
 /**
  * User types for /api/v1/users/ endpoints
+ * camelCase — FetchWrapper auto-converts snake_case↔camelCase at boundary
  */
 
 export interface UserProfile {
   id: string;
   email: string;
-  first_name: string;
-  last_name: string;
-  full_name: string;
-  is_email_verified: boolean;
+  firstName: string;
+  lastName: string;
+  fullName: string;
+  isEmailVerified: boolean;
   company: string | null;
-  is_active: boolean;
-  created_at: string;
-  updated_at: string;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
 }
 
 export interface UpdateProfileRequest {
-  first_name?: string;
-  last_name?: string;
+  firstName?: string;
+  lastName?: string;
 }
 
 export interface ChangePasswordRequest {
-  old_password: string;
-  new_password: string;
-  new_password_confirm: string;
+  oldPassword: string;
+  newPassword: string;
+  newPasswordConfirm: string;
 }
 
 export interface ChangePasswordResponse {