@startsimpli/api 0.5.7 → 0.5.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/api",
-  "version": "0.5.7",
+  "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

@@ -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
    */
@@ -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) {}
 
@@ -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;