@startsimpli/api 0.5.7 → 0.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/api",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Type-safe Django REST API client for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -23,14 +23,13 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@types/dompurify": "^3.0.5",
-    "isomorphic-dompurify": "^2.36.0",
-    "zod": "^3.22.4"
+    "isomorphic-dompurify": "^3.10.0",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
     "next": ">=14.0.0",
-    "react": ">=18.0.0",
-    "@tanstack/react-query": ">=5.0.0"
+    "react": ">=18.0.0"
   },
   "peerDependenciesMeta": {
     "next": {
@@ -44,13 +43,13 @@
     }
   },
   "devDependencies": {
-    "@tanstack/react-query": "^5.0.0",
-    "@types/node": "^20.11.0",
-    "@types/react": "^18.2.0",
-    "next": "^15.5.12",
-    "react": "^18.2.0",
+    "@tanstack/react-query": "^5.99.2",
+    "@types/node": "^20.19.39",
+    "@types/react": "^19.2.14",
+    "next": "^15.5.15",
+    "react": "^19.2.5",
     "tsup": "^8.5.1",
-    "typescript": "^5.3.3",
-    "vitest": "^1.2.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   }
 }

package/src/__tests__/funnels-api.test.ts

@@ -72,7 +72,7 @@ describe('FunnelsApi', () => {
     it('calls GET funnels with no params when no filters given', async () => {
       vi.mocked(client.get).mockResolvedValue(mockPaginated([mockFunnel]));
       await api.list();
-      expect(client.get).toHaveBeenCalledWith('funnels');
+      expect(client.get).toHaveBeenCalledWith('api/v1/funnels');
     });
 
     it('passes status filter as query param', async () => {
@@ -102,7 +102,7 @@ describe('FunnelsApi', () => {
     it('calls GET funnels/:id', async () => {
       vi.mocked(client.get).mockResolvedValue(mockFunnel);
       const result = await api.get('funnel-1');
-      expect(client.get).toHaveBeenCalledWith('funnels/funnel-1');
+      expect(client.get).toHaveBeenCalledWith('api/v1/funnels/funnel-1');
       expect(result).toEqual(mockFunnel);
     });
   });
@@ -112,7 +112,7 @@ describe('FunnelsApi', () => {
       vi.mocked(client.post).mockResolvedValue(mockFunnel);
       const input = { name: 'New Funnel', entityType: 'contact' as const, tags: ['campaign:abc'] };
       await api.create(input);
-      expect(client.post).toHaveBeenCalledWith('funnels', input);
+      expect(client.post).toHaveBeenCalledWith('api/v1/funnels', input);
     });
   });
 
@@ -120,7 +120,7 @@ describe('FunnelsApi', () => {
     it('calls PATCH funnels/:id with data', async () => {
       vi.mocked(client.patch).mockResolvedValue(mockFunnel);
       await api.update('funnel-1', { name: 'Renamed' });
-      expect(client.patch).toHaveBeenCalledWith('funnels/funnel-1', { name: 'Renamed' });
+      expect(client.patch).toHaveBeenCalledWith('api/v1/funnels/funnel-1', { name: 'Renamed' });
     });
   });
 
@@ -128,7 +128,7 @@ describe('FunnelsApi', () => {
     it('calls DELETE funnels/:id', async () => {
       vi.mocked(client.delete).mockResolvedValue(undefined);
       await api.delete('funnel-1');
-      expect(client.delete).toHaveBeenCalledWith('funnels/funnel-1');
+      expect(client.delete).toHaveBeenCalledWith('api/v1/funnels/funnel-1');
     });
   });
 
@@ -136,13 +136,13 @@ describe('FunnelsApi', () => {
     it('calls POST funnels/:id/run with empty body by default', async () => {
       vi.mocked(client.post).mockResolvedValue(mockRun);
       await api.run('funnel-1');
-      expect(client.post).toHaveBeenCalledWith('funnels/funnel-1/run', {});
+      expect(client.post).toHaveBeenCalledWith('api/v1/funnels/funnel-1/run', {});
     });
 
     it('passes entityIds in body when provided', async () => {
       vi.mocked(client.post).mockResolvedValue(mockRun);
       await api.run('funnel-1', { entityIds: ['e1', 'e2'] });
-      expect(client.post).toHaveBeenCalledWith('funnels/funnel-1/run', { entityIds: ['e1', 'e2'] });
+      expect(client.post).toHaveBeenCalledWith('api/v1/funnels/funnel-1/run', { entityIds: ['e1', 'e2'] });
     });
   });
 
@@ -150,7 +150,7 @@ describe('FunnelsApi', () => {
     it('calls GET funnels/:id/runs', async () => {
       vi.mocked(client.get).mockResolvedValue(mockPaginated([mockRun]));
       await api.getRuns('funnel-1');
-      expect(client.get).toHaveBeenCalledWith('funnels/funnel-1/runs');
+      expect(client.get).toHaveBeenCalledWith('api/v1/funnels/funnel-1/runs');
     });
 
     it('passes page and pageSize filters', async () => {
@@ -166,14 +166,15 @@ describe('FunnelsApi', () => {
     it('calls GET funnel-runs/:runId (global endpoint, funnelId ignored)', async () => {
       vi.mocked(client.get).mockResolvedValue(mockRun);
       await api.getRun('funnel-1', 'run-1');
-      expect(client.get).toHaveBeenCalledWith('funnel-runs/run-1');
+      expect(client.get).toHaveBeenCalledWith('api/v1/funnel-runs/run-1');
     });
   });
 
   describe('preview', () => {
-    it('throws Not implemented (endpoint missing in Django)', async () => {
-      // BEAD: fund-your-startup-rgi4 - funnels/{id}/preview does not exist in Django
-      await expect(api.preview('funnel-1', [])).rejects.toThrow('Not implemented');
+    it('calls POST funnels/:id/preview with stages', async () => {
+      vi.mocked(client.post).mockResolvedValue({} as never);
+      await api.preview('funnel-1', []);
+      expect(client.post).toHaveBeenCalledWith('api/v1/funnels/funnel-1/preview', { stages: [] });
     });
   });
 
@@ -181,7 +182,7 @@ describe('FunnelsApi', () => {
     it('calls POST funnel-runs/:runId/cancel', async () => {
       vi.mocked(client.post).mockResolvedValue(mockRun);
       await api.cancelRun('run-1');
-      expect(client.post).toHaveBeenCalledWith('funnel-runs/run-1/cancel', {});
+      expect(client.post).toHaveBeenCalledWith('api/v1/funnel-runs/run-1/cancel', {});
     });
   });
 
@@ -189,7 +190,7 @@ describe('FunnelsApi', () => {
     it('calls GET funnel-runs with no params when no filters given', async () => {
       vi.mocked(client.get).mockResolvedValue(mockPaginated([mockRun]));
       await api.listRunsGlobal();
-      expect(client.get).toHaveBeenCalledWith('funnel-runs');
+      expect(client.get).toHaveBeenCalledWith('api/v1/funnel-runs');
     });
 
     it('passes funnel filter as query param', async () => {
@@ -203,7 +204,7 @@ describe('FunnelsApi', () => {
     it('calls GET funnels/templates', async () => {
       vi.mocked(client.get).mockResolvedValue(mockPaginated([]));
       await api.listTemplates();
-      expect(client.get).toHaveBeenCalledWith('funnels/templates');
+      expect(client.get).toHaveBeenCalledWith('api/v1/funnels/templates');
     });
 
     it('passes category filter', async () => {

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

@@ -123,6 +123,58 @@ describe('JWT Refresh Flow', () => {
     expect(refreshCallback).toHaveBeenCalledTimes(1);
   });
 
+  it('does NOT fire onUnauthorized when onTokenRefresh THROWS (transient 5xx / network)', async () => {
+    // This is the "backend is down, not session expired" case. If refresh
+    // throws (TransientRefreshError), we must surface the original 401 as an
+    // API error WITHOUT logging the user out.
+    const wrapper = new FetchWrapper({
+      baseUrl: 'http://localhost:8000',
+      getToken: () => 'stale-token',
+      onTokenRefresh: refreshCallback,
+      onUnauthorized: unauthorizedCallback,
+    });
+
+    mockFetch.mockResolvedValueOnce({
+      status: 401,
+      ok: false,
+      headers: new Headers(),
+      text: async () => '',
+    });
+    refreshCallback.mockRejectedValueOnce(new Error('transient 5xx'));
+
+    await expect(wrapper.get('/api/v1/messages/')).rejects.toBeTruthy();
+
+    expect(refreshCallback).toHaveBeenCalledTimes(1);
+    // CRITICAL: a transient refresh failure must NOT call onUnauthorized.
+    // Backend being down should not log users out.
+    expect(unauthorizedCallback).not.toHaveBeenCalled();
+  });
+
+  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

@@ -50,6 +50,7 @@ export const ENDPOINTS = {
   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',

package/src/index.ts

@@ -9,6 +9,10 @@
 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';
@@ -16,12 +20,20 @@ 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, 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 {

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/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
    */
@@ -104,26 +113,42 @@ export class FetchWrapper {
             });
           }
 
-          const newToken = await this.refreshPromise;
-
-          if (newToken) {
-            // Retry original request with new token
-            const retryHeaders = new Headers(headers);
-            retryHeaders.set('Authorization', `Bearer ${newToken}`);
+          // A throw from onTokenRefresh means transient (5xx/network) — surface
+          // the original 401 as a normal API error rather than treating it as
+          // session-dead. Callers (components doing a fetch) will see an
+          // ApiException they can retry; the user stays logged in.
+          let newToken: string | null = null;
+          let refreshThrew = false;
+          try {
+            newToken = await this.refreshPromise;
+          } catch {
+            refreshThrew = true;
+          }
 
-            response = await fetch(url, {
-              method,
-              headers: retryHeaders,
-              credentials: 'include',
-              ...fetchOptions,
-            });
-          } else if (this.config.onUnauthorized) {
-            // Refresh failed - call unauthorized callback
-            this.config.onUnauthorized();
+          if (!refreshThrew) {
+            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) {
+                this.fireUnauthorizedOnce();
+              }
+            } else {
+              // newToken=null is the "session is dead" signal from the refresh
+              // implementation. Only this path should log the user out.
+              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) {}
 
@@ -258,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/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/types/error.ts

@@ -55,7 +55,7 @@ export const StandardErrorResponseSchema = z.object({
   code: z.string(),
   statusCode: z.number().int().min(400).max(599),
   fieldErrors: z.array(FieldErrorSchema).optional(),
-  details: z.record(z.unknown()).optional(),
+  details: z.record(z.string(), z.unknown()).optional(),
   requestId: z.string().optional(),
   timestamp: z.string().datetime().optional(),
 });