@startsimpli/api 0.1.0 → 0.2.1

package/src/hooks/use-server-detail.ts

@@ -0,0 +1,71 @@
+'use client'
+
+import { useState, useEffect, useCallback } from 'react'
+
+export interface ServerDetailOptions {
+  /** Custom fetch function. Use authFetch from @startsimpli/auth for authenticated calls. */
+  fetcher?: typeof fetch
+  /** Pass null to skip fetching (e.g., when ID is not yet known) */
+  disabled?: boolean
+}
+
+export interface ServerDetailResult<T> {
+  data: T | null
+  loading: boolean
+  error: string | null
+  refresh: () => void
+}
+
+/**
+ * Hook for fetching a single resource.
+ *
+ * @example
+ * import { useServerDetail } from '@startsimpli/api'
+ * import { authFetch } from '@startsimpli/auth'
+ *
+ * const { data, loading, error } = useServerDetail<User>(
+ *   '/api/v1/users/',
+ *   userId,
+ *   { fetcher: authFetch }
+ * )
+ */
+export function useServerDetail<T>(
+  endpoint: string,
+  id?: string | number | null,
+  options: ServerDetailOptions = {}
+): ServerDetailResult<T> {
+  const { fetcher = fetch, disabled = false } = options
+
+  const [data, setData] = useState<T | null>(null)
+  const [loading, setLoading] = useState(!disabled && id !== null && id !== undefined)
+  const [error, setError] = useState<string | null>(null)
+
+  const fetchData = useCallback(async () => {
+    if (disabled || id === null) return
+
+    const url =
+      id !== undefined
+        ? `${endpoint}${endpoint.endsWith('/') ? '' : '/'}${id}/`
+        : endpoint
+
+    setLoading(true)
+    setError(null)
+    try {
+      const response = await fetcher(url)
+      if (!response.ok) {
+        throw new Error(`Request failed: ${response.status} ${response.statusText}`)
+      }
+      setData(await response.json())
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load data')
+    } finally {
+      setLoading(false)
+    }
+  }, [endpoint, id, disabled, fetcher])
+
+  useEffect(() => {
+    fetchData()
+  }, [fetchData])
+
+  return { data, loading, error, refresh: fetchData }
+}

package/src/hooks/use-server-list.ts

@@ -0,0 +1,169 @@
+'use client'
+
+import { useState, useEffect, useCallback, useRef } from 'react'
+
+export interface ServerListOptions {
+  pageSize?: number
+  initialPage?: number
+  initialSearch?: string
+  initialSortField?: string
+  initialSortDir?: 'asc' | 'desc'
+  /** Extra static query params to append on every request */
+  params?: Record<string, string | number | boolean>
+  /** Disable auto-fetch on mount */
+  disabled?: boolean
+  /** Custom fetch function (defaults to global fetch). Use authFetch from @startsimpli/auth for authenticated calls. */
+  fetcher?: typeof fetch
+}
+
+export interface ServerListResult<T> {
+  data: T[]
+  total: number
+  loading: boolean
+  error: string | null
+  page: number
+  pageSize: number
+  search: string
+  sortField: string
+  sortDir: 'asc' | 'desc'
+  setPage: (page: number) => void
+  setPageSize: (size: number) => void
+  setSearch: (search: string) => void
+  setSort: (field: string, dir?: 'asc' | 'desc') => void
+  refresh: () => void
+}
+
+/**
+ * Hook for server-side paginated list fetching.
+ * Sends ?page=N&pageSize=Y&sortField=Z&sortDirection=asc|desc&search=Q
+ * to the provided endpoint.
+ *
+ * @example
+ * import { useServerList } from '@startsimpli/api'
+ * import { authFetch } from '@startsimpli/auth'
+ *
+ * const { data, total, loading, page, setPage, setSearch } = useServerList<Email>(
+ *   '/api/v1/emails/',
+ *   { fetcher: authFetch, pageSize: 25 }
+ * )
+ */
+export function useServerList<T>(
+  endpoint: string,
+  options: ServerListOptions = {}
+): ServerListResult<T> {
+  const {
+    pageSize: initialPageSize = 25,
+    initialPage = 1,
+    initialSearch = '',
+    initialSortField = '',
+    initialSortDir = 'asc',
+    params: extraParams = {},
+    disabled = false,
+    fetcher = fetch,
+  } = options
+
+  const [page, setPage] = useState(initialPage)
+  const [pageSize, setPageSize] = useState(initialPageSize)
+  const [search, setSearchState] = useState(initialSearch)
+  const [sortField, setSortField] = useState(initialSortField)
+  const [sortDir, setSortDir] = useState<'asc' | 'desc'>(initialSortDir)
+  const [data, setData] = useState<T[]>([])
+  const [total, setTotal] = useState(0)
+  const [loading, setLoading] = useState(!disabled)
+  const [error, setError] = useState<string | null>(null)
+  const refreshCountRef = useRef(0)
+
+  const fetchData = useCallback(async () => {
+    if (disabled) return
+
+    setLoading(true)
+    setError(null)
+
+    const searchParams = new URLSearchParams()
+    searchParams.set('page', String(page))
+    searchParams.set('pageSize', String(pageSize))
+    if (sortField) {
+      searchParams.set('sortField', sortField)
+      searchParams.set('sortDirection', sortDir)
+    }
+    if (search) searchParams.set('search', search)
+    for (const [k, v] of Object.entries(extraParams)) {
+      searchParams.set(k, String(v))
+    }
+
+    const sep = endpoint.includes('?') ? '&' : '?'
+    const url = `${endpoint}${sep}${searchParams.toString()}`
+
+    try {
+      const response = await fetcher(url)
+      if (!response.ok) {
+        throw new Error(`Request failed: ${response.status} ${response.statusText}`)
+      }
+      const json = await response.json()
+      // Support { results: T[], count: N } (DRF default), { data: T[], total: N }, or plain array
+      if (Array.isArray(json)) {
+        setData(json)
+        setTotal(json.length)
+      } else if (json.results !== undefined) {
+        setData(json.results)
+        setTotal(json.count ?? json.results.length)
+      } else if (json.data !== undefined) {
+        setData(json.data)
+        setTotal(json.total ?? json.data.length)
+      } else {
+        setData([])
+        setTotal(0)
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load data')
+      setData([])
+    } finally {
+      setLoading(false)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [endpoint, page, pageSize, search, sortField, sortDir, disabled, fetcher, refreshCountRef.current])
+
+  useEffect(() => {
+    fetchData()
+  }, [fetchData])
+
+  const setSearch = useCallback((value: string) => {
+    setPage(1)
+    setSearchState(value)
+  }, [])
+
+  const setSort = useCallback(
+    (field: string, dir?: 'asc' | 'desc') => {
+      if (field === sortField && !dir) {
+        setSortDir((prev) => (prev === 'asc' ? 'desc' : 'asc'))
+      } else {
+        setSortField(field)
+        setSortDir(dir ?? 'asc')
+      }
+      setPage(1)
+    },
+    [sortField]
+  )
+
+  const refresh = useCallback(() => {
+    refreshCountRef.current += 1
+    fetchData()
+  }, [fetchData])
+
+  return {
+    data,
+    total,
+    loading,
+    error,
+    page,
+    pageSize,
+    search,
+    sortField,
+    sortDir,
+    setPage,
+    setPageSize,
+    setSearch,
+    setSort,
+    refresh,
+  }
+}

package/src/index.ts

@@ -16,6 +16,8 @@ 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 { FunnelsApi, isFunnelRunConflict, isFunnelValidationError } from './lib/funnels-api';
+export type { FunnelPreviewResult, FunnelRunFilters, FunnelTemplate } from './lib/funnels-api';
 
 // Fetch wrapper
 export { FetchWrapper } from './lib/fetch-wrapper';
@@ -74,11 +76,40 @@ export * from './types';
 export { createRateLimiter, getClientIP } from './lib/rate-limit';
 export type { RateLimitOptions, RateLimitResult } from './lib/rate-limit';
 
+// In-memory cache (server-side only)
+export { CacheStore } from './lib/cache-store';
+export type { CacheStoreConfig } from './lib/cache-store';
+export { CacheManager, getCacheManager, resetCacheManager } from './lib/cache-manager';
+export type { CacheManagerConfig } from './lib/cache-manager';
+
 // Utils
 export * from './utils';
 
 // Constants
 export { ENDPOINTS } from './constants/endpoints';
+export {
+  COMPANY_SIZE_OPTIONS,
+  LIFECYCLE_STAGE_OPTIONS,
+  REVENUE_RANGE_OPTIONS,
+  ACTIVITY_TYPE_OPTIONS,
+  ACTIVITY_OUTCOME_OPTIONS,
+  LOSS_REASON_OPTIONS,
+  DEAL_STAGE_OPTIONS,
+} from './constants/options';
+export type {
+  SelectOption,
+  CompanySize,
+  LifecycleStage,
+  RevenueRange,
+  ActivityType,
+  ActivityOutcome,
+  LossReason,
+  DealStage,
+} from './constants/options';
+
+// React hooks for server-side data fetching
+export { useServerList, useServerDetail } from './hooks';
+export type { ServerListOptions, ServerListResult, ServerDetailResult } from './hooks';
 
 // Environment variable utilities
 export { getRequiredEnv, getOptionalEnv, validateEnvVars } from './lib/env';
@@ -89,13 +120,15 @@ import { OrganizationsApi } from './lib/organizations-api';
 import { EntitiesApi } from './lib/entities-api';
 import { WorkflowsApi } from './lib/workflows-api';
 import { MessagesApi } from './lib/messages-api';
+import { FunnelsApi } from './lib/funnels-api';
 
 import type { ApiClientConfig } from './lib/api-client';
 
 /**
- * Create a complete API client with all endpoints
+ * Create a complete API client with all endpoints.
+ * All config fields are optional — baseUrl defaults to '' (relative URLs via Next.js proxy).
  */
-export function createStartSimpliApi(config: ApiClientConfig) {
+export function createStartSimpliApi(config: ApiClientConfig = {}) {
   const client = createApiClient(config);
 
   return {
@@ -105,5 +138,6 @@ export function createStartSimpliApi(config: ApiClientConfig) {
     entities: new EntitiesApi(client),
     workflows: new WorkflowsApi(client),
     messages: new MessagesApi(client),
+    funnels: new FunnelsApi(client),
   };
 }

package/src/lib/api-client.ts

@@ -2,10 +2,11 @@
  * Main API client for Django REST API
  */
 
-import { FetchWrapper, type FetchWrapperConfig } from './fetch-wrapper';
+import { FetchWrapper } from './fetch-wrapper';
+import type { FetchOptions } from '../types';
 
 export interface ApiClientConfig {
-  baseUrl: string;
+  baseUrl?: string;
   getToken?: () => Promise<string | null> | string | null;
   onUnauthorized?: () => void;
   onTokenRefresh?: () => Promise<string | null>;
@@ -16,7 +17,7 @@ export class ApiClient {
   public readonly baseUrl: string;
 
   constructor(config: ApiClientConfig) {
-    this.baseUrl = config.baseUrl;
+    this.baseUrl = config.baseUrl ?? '';
 
     this.fetcher = new FetchWrapper({
       baseUrl: config.baseUrl,
@@ -41,42 +42,32 @@ export class ApiClient {
    * Update auth token getter
    */
   setTokenGetter(getToken: () => Promise<string | null> | string | null): void {
-    this.fetcher = new FetchWrapper({
-      baseUrl: this.baseUrl,
-      getToken,
-      onUnauthorized: this.fetcher['config'].onUnauthorized,
-      defaultHeaders: this.fetcher['config'].defaultHeaders,
-    });
+    this.fetcher = this.fetcher.reconfigure({ getToken });
   }
 
   /**
    * Update unauthorized handler
    */
   setUnauthorizedHandler(onUnauthorized: () => void): void {
-    this.fetcher = new FetchWrapper({
-      baseUrl: this.baseUrl,
-      getToken: this.fetcher['config'].getToken,
-      onUnauthorized,
-      defaultHeaders: this.fetcher['config'].defaultHeaders,
-    });
+    this.fetcher = this.fetcher.reconfigure({ onUnauthorized });
   }
 
   /**
    * Convenience HTTP methods that delegate to FetchWrapper
    */
-  async get<T>(endpoint: string, options?: any): Promise<T> {
+  async get<T>(endpoint: string, options?: FetchOptions): Promise<T> {
     return this.fetcher.get<T>(endpoint, options);
   }
 
-  async post<T, D = unknown>(endpoint: string, data?: D, options?: any): Promise<T> {
+  async post<T, D = unknown>(endpoint: string, data?: D, options?: FetchOptions): Promise<T> {
     return this.fetcher.post<T, D>(endpoint, data, options);
   }
 
-  async patch<T, D = unknown>(endpoint: string, data?: D, options?: any): Promise<T> {
+  async patch<T, D = unknown>(endpoint: string, data?: D, options?: FetchOptions): Promise<T> {
     return this.fetcher.patch<T, D>(endpoint, data, options);
   }
 
-  async delete<T>(endpoint: string, options?: any): Promise<T> {
+  async delete<T>(endpoint: string, options?: FetchOptions): Promise<T> {
     return this.fetcher.delete<T>(endpoint, options);
   }
 }

package/src/lib/cache-manager.ts

@@ -0,0 +1,103 @@
+/**
+ * Cache manager built on top of CacheStore.
+ *
+ * Provides a cache-aside pattern (getOrSet), pattern-based invalidation,
+ * and separate entity/query stores — ready for use in Next.js API routes
+ * and server-side data fetching.
+ */
+
+import { CacheStore } from './cache-store'
+import type { CacheStoreConfig } from './cache-store'
+
+export interface CacheManagerConfig {
+  entity?: Partial<CacheStoreConfig>
+  query?: Partial<CacheStoreConfig>
+}
+
+const DEFAULT_CONFIG: CacheManagerConfig = {
+  entity: { maxSize: 500, defaultTTL: 5 * 60 * 1000 },
+  query: { maxSize: 200, defaultTTL: 60 * 1000 },
+}
+
+export class CacheManager {
+  readonly entity: CacheStore
+  readonly query: CacheStore
+  private enabled: boolean
+
+  constructor(enabled = true, config: CacheManagerConfig = {}) {
+    this.entity = new CacheStore({ ...DEFAULT_CONFIG.entity, ...config.entity })
+    this.query = new CacheStore({ ...DEFAULT_CONFIG.query, ...config.query })
+    this.enabled = enabled
+  }
+
+  /**
+   * Cache-aside: return the cached value if present, otherwise call fetchFn,
+   * store the result, and return it.
+   */
+  async getOrSet<T>(key: string, ttlMs: number, fetchFn: () => Promise<T>): Promise<T> {
+    if (this.enabled) {
+      const cached = this.query.get(key) as T | undefined
+      if (cached !== undefined) return cached
+    }
+    const value = await fetchFn()
+    if (this.enabled) this.query.set(key, value, ttlMs)
+    return value
+  }
+
+  /** Invalidate a specific key in the query cache */
+  invalidateKey(key: string): void {
+    this.query.delete(key)
+  }
+
+  /** Invalidate all query cache keys matching a string prefix or RegExp */
+  invalidatePattern(pattern: string | RegExp): void {
+    this.query.deletePattern(pattern)
+  }
+
+  /** Invalidate all entity and query cache entries for the given prefix */
+  invalidateAll(prefix: string): void {
+    this.entity.deletePattern(prefix)
+    this.query.deletePattern(prefix)
+  }
+
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled
+  }
+
+  isEnabled(): boolean {
+    return this.enabled
+  }
+
+  /** Remove expired entries from both stores */
+  maintenance(): { entityRemoved: number; queryRemoved: number } {
+    return {
+      entityRemoved: this.entity.cleanup(),
+      queryRemoved: this.query.cleanup(),
+    }
+  }
+
+  clear(): void {
+    this.entity.clear()
+    this.query.clear()
+  }
+
+  getStats(): {
+    entity: ReturnType<CacheStore['getStats']>
+    query: ReturnType<CacheStore['getStats']>
+  } {
+    return { entity: this.entity.getStats(), query: this.query.getStats() }
+  }
+}
+
+// Singleton factory
+let _cacheManager: CacheManager | null = null
+
+export function getCacheManager(config?: CacheManagerConfig): CacheManager {
+  if (!_cacheManager) _cacheManager = new CacheManager(true, config)
+  return _cacheManager
+}
+
+export function resetCacheManager(): void {
+  _cacheManager?.clear()
+  _cacheManager = null
+}

package/src/lib/cache-store.ts

@@ -0,0 +1,113 @@
+/**
+ * In-memory LRU cache store with TTL expiry.
+ *
+ * A minimal, zero-dependency cache for server-side caching in Next.js apps.
+ * State is in-memory and resets on server restart — not suitable for
+ * multi-instance production deployments without a shared backend (e.g. Redis).
+ */
+
+interface CacheEntry<T> {
+  value: T
+  expiresAt: number
+  accessOrder: number
+}
+
+export interface CacheStoreConfig {
+  /** Maximum number of entries before LRU eviction (default: 1000) */
+  maxSize: number
+  /** Default TTL in milliseconds (default: 60 seconds) */
+  defaultTTL: number
+}
+
+const DEFAULT_CONFIG: CacheStoreConfig = {
+  maxSize: 1000,
+  defaultTTL: 60 * 1000,
+}
+
+export class CacheStore<T = unknown> {
+  private cache = new Map<string, CacheEntry<T>>()
+  private config: CacheStoreConfig
+  private hits = 0
+  private misses = 0
+  private accessCounter = 0
+
+  constructor(config: Partial<CacheStoreConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key)
+    if (!entry) { this.misses++; return undefined }
+    if (Date.now() > entry.expiresAt) { this.cache.delete(key); this.misses++; return undefined }
+    entry.accessOrder = ++this.accessCounter
+    this.hits++
+    return entry.value
+  }
+
+  set(key: string, value: T, ttl?: number): void {
+    if (this.cache.size >= this.config.maxSize) this.evictLRU()
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + (ttl ?? this.config.defaultTTL),
+      accessOrder: ++this.accessCounter,
+    })
+  }
+
+  has(key: string): boolean {
+    const entry = this.cache.get(key)
+    if (!entry) return false
+    if (Date.now() > entry.expiresAt) { this.cache.delete(key); return false }
+    return true
+  }
+
+  delete(key: string): boolean {
+    return this.cache.delete(key)
+  }
+
+  /** Delete all keys matching a string prefix or RegExp pattern */
+  deletePattern(pattern: string | RegExp): number {
+    const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern
+    let deleted = 0
+    for (const key of this.cache.keys()) {
+      if (regex.test(key)) { this.cache.delete(key); deleted++ }
+    }
+    return deleted
+  }
+
+  clear(): void {
+    this.cache.clear()
+    this.hits = 0
+    this.misses = 0
+    this.accessCounter = 0
+  }
+
+  /** Remove expired entries and return count removed */
+  cleanup(): number {
+    const now = Date.now()
+    let removed = 0
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiresAt) { this.cache.delete(key); removed++ }
+    }
+    return removed
+  }
+
+  getStats(): { size: number; maxSize: number; hits: number; misses: number; hitRate: number } {
+    const total = this.hits + this.misses
+    return {
+      size: this.cache.size,
+      maxSize: this.config.maxSize,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? this.hits / total : 0,
+    }
+  }
+
+  private evictLRU(): void {
+    let oldestKey: string | null = null
+    let oldestOrder = Infinity
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.accessOrder < oldestOrder) { oldestOrder = entry.accessOrder; oldestKey = key }
+    }
+    if (oldestKey) this.cache.delete(oldestKey)
+  }
+}

package/src/lib/error-handler.ts

@@ -34,7 +34,7 @@ export class ApiException extends Error {
  * Parse Django REST Framework error response
  */
 export async function parseErrorResponse(response: Response): Promise<DRFApiError> {
-  const contentType = response.headers.get('content-type');
+  const contentType = response.headers?.get('content-type');
 
   // Try to parse JSON error
   if (contentType?.includes('application/json')) {