@startsimpli/api 0.1.0

package/src/types/funnel.ts

@@ -0,0 +1,133 @@
+/**
+ * Funnel types matching Django Funnel models
+ *
+ * Funnels are brutally generic - they can represent:
+ * - Lead scoring funnels
+ * - Investor qualification stages
+ * - Customer segmentation
+ * - Any multi-stage entity classification
+ */
+
+export type FunnelStatus = 'draft' | 'active' | 'archived';
+export type EntityType = 'contact' | 'organization';
+
+/**
+ * Filter rule for funnel stage
+ */
+export interface FunnelStageRule {
+  id: number;
+  fieldPath: string;
+  operator: 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'notContains' | 'startswith' | 'endswith' | 'in' | 'notIn' | 'isnull' | 'isnotnull' | 'arrayContains' | 'arrayOverlaps';
+  value: string | number | boolean | null;
+  logic?: 'AND' | 'OR';
+}
+
+/**
+ * Funnel stage with rules
+ */
+export interface FunnelStage {
+  id: number;
+  name: string;
+  description?: string;
+  order: number;
+  rules: FunnelStageRule[];
+  entityCount?: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Funnel - brutally generic entity classification system
+ */
+export interface Funnel {
+  id: string;
+  name: string;
+  description: string;
+  status: FunnelStatus;
+  tags?: string[];
+  entityType: EntityType;
+  /**
+   * @deprecated Legacy field for backward compatibility
+   */
+  inputType?: 'contacts' | 'organizations' | 'both' | 'any';
+  stages: FunnelStage[];
+  stageCount: number;
+  totalRuns: number;
+  lastRunAt: string | null;
+  createdBy: string;
+  createdByName: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Funnel result for a specific entity
+ */
+export interface FunnelResult {
+  id: number;
+  funnel: string;
+  entity: string;
+  entityType: EntityType;
+  stage: number | null;
+  stageName: string | null;
+  score: number | null;
+  metadata: Record<string, any>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Funnel execution run
+ */
+export interface FunnelRun {
+  id: string;
+  funnel: string;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  totalEntities: number;
+  processedEntities: number;
+  resultsByStage: Record<string, number>;
+  startedAt: string | null;
+  completedAt: string | null;
+  errorMessage: string | null;
+  createdBy: string;
+  createdAt: string;
+}
+
+/**
+ * Filters for listing funnels
+ */
+export interface FunnelFilters {
+  status?: FunnelStatus;
+  entityType?: EntityType;
+  search?: string;
+  tags?: string[];
+  createdBy?: string;
+  page?: number;
+  pageSize?: number;
+  ordering?: string;
+}
+
+/**
+ * Input for creating a funnel
+ */
+export interface CreateFunnelInput {
+  name: string;
+  description?: string;
+  status?: FunnelStatus;
+  tags?: string[];
+  entityType: EntityType;
+  stages?: Omit<FunnelStage, 'id' | 'createdAt' | 'updatedAt' | 'entityCount'>[];
+}
+
+/**
+ * Input for updating a funnel
+ */
+export interface UpdateFunnelInput extends Partial<CreateFunnelInput> {}
+
+/**
+ * Input for executing a funnel
+ */
+export interface ExecuteFunnelInput {
+  entityIds?: string[];
+  filters?: Record<string, any>;
+}

package/src/types/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Type exports for @startsimpli/api
+ */
+
+// API types
+export type {
+  PaginatedResponse,
+  PaginationParams,
+  SortParams,
+  ApiRequestConfig,
+  HttpMethod,
+  FetchOptions,
+} from './api';
+// DRF-specific ApiError (aliased to avoid conflict with canonical ApiError below)
+export type { ApiError as DRFApiError } from './api';
+
+// Canonical response envelope types (used by all StartSimpli apps)
+export type {
+  ApiError,
+  ApiResponse,
+  AsyncState,
+  AsyncStatus,
+} from './response';
+export { ErrorCodes } from './response';
+
+// Entity types
+export type {
+  EntityType,
+  Entity,
+  Tag,
+  EntityTag,
+  Metric,
+  Profile,
+  Attribute,
+  Relationship,
+  RoleAssignment,
+  Event,
+  EventParticipant,
+  Source,
+  WritableAssertions,
+} from './entity';
+
+// Contact types
+export type {
+  Contact,
+  CreateContactRequest,
+  UpdateContactRequest,
+  ContactFilters,
+} from './contact';
+
+// Organization types
+export type {
+  Organization,
+  CreateOrganizationRequest,
+  UpdateOrganizationRequest,
+  OrganizationFilters,
+} from './organization';
+
+// Funnel types
+export type {
+  FunnelStatus,
+  FunnelStageRule,
+  FunnelStage,
+  Funnel,
+  FunnelResult,
+  FunnelRun,
+  FunnelFilters,
+  CreateFunnelInput,
+  UpdateFunnelInput,
+  ExecuteFunnelInput,
+} from './funnel';
+
+// Workflow types
+export type {
+  WorkflowStatus,
+  Workflow,
+  WorkflowExecution,
+  WorkflowFilters,
+  ExecuteWorkflowInput,
+  CreateWorkflowInput,
+  UpdateWorkflowInput,
+} from './workflow';
+
+// Error types
+export type {
+  FieldError,
+  StandardErrorResponse,
+} from './error';
+export {
+  ErrorCode,
+  ErrorMessages,
+  getErrorCodeFromStatus,
+  FieldErrorSchema,
+  StandardErrorResponseSchema,
+} from './error';

package/src/types/organization.ts

@@ -0,0 +1,49 @@
+/**
+ * Organization types matching Django Organization model
+ */
+
+import type { Entity, WritableAssertions } from './entity';
+
+export interface Organization extends Entity {
+  name: string;
+  domain?: string | null;
+  description?: string | null;
+  location?: string | null;
+
+  // Computed fields from assertions
+  tier?: number | null;
+  stage?: string | null;
+  focusAreas?: string[];
+  checkSizeMin?: number | null;
+  checkSizeMax?: number | null;
+  aum?: number | string | null;
+  portfolioCount?: number | null;
+  linkedin?: string | null;
+  twitter?: string | null;
+  crunchbase?: string | null;
+  website?: string | null;
+  foundedYear?: number | null;
+}
+
+export interface CreateOrganizationRequest extends WritableAssertions {
+  name: string;
+  domain?: string;
+  description?: string;
+  location?: string;
+}
+
+export interface UpdateOrganizationRequest extends Partial<CreateOrganizationRequest> {}
+
+export interface OrganizationFilters {
+  [key: string]: unknown;
+  search?: string;
+  tier?: number;
+  stage?: string;
+  focusArea?: string;
+  checkSizeMinGte?: number;
+  checkSizeMaxLte?: number;
+  aumGte?: number;
+  location?: string;
+  tagCategory?: string;
+  tagName?: string;
+}

package/src/types/response.ts

@@ -0,0 +1,44 @@
+// Canonical API response envelope used by all StartSimpli apps
+export interface ApiError {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+export interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: ApiError;
+}
+
+// Standard error codes (apps may define additional domain-specific codes)
+export enum ErrorCodes {
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+  NOT_FOUND = 'NOT_FOUND',
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  CONFLICT = 'CONFLICT',
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+  RATE_LIMITED = 'RATE_LIMITED',
+}
+
+export interface PaginationParams {
+  page?: number;
+  pageSize?: number;
+}
+
+export interface PaginatedResponse<T> {
+  results: T[];
+  count: number;
+  next: string | null;
+  previous: string | null;
+}
+
+// Async state pattern for React components
+export type AsyncStatus = 'idle' | 'loading' | 'success' | 'error';
+export interface AsyncState<T> {
+  status: AsyncStatus;
+  data: T | null;
+  error: string | null;
+}

package/src/types/workflow.ts

@@ -0,0 +1,69 @@
+/**
+ * Workflow types matching Django Workflow models
+ *
+ * Workflows are n8n-style node-based automation flows
+ */
+
+export type WorkflowStatus = 'draft' | 'active' | 'paused';
+
+export interface Workflow {
+  id: string;
+  name: string;
+  description: string;
+  team: string;
+  createdBy: string | null;
+  nodes: any[];
+  connections: Record<string, any>;
+  settings: Record<string, any>;
+  staticData: Record<string, any>;
+  isActive: boolean;
+  version: number;
+  isTemplate: boolean;
+  templateSource: string | null;
+  executionsCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WorkflowExecution {
+  id: string;
+  workflow: string;
+  workflowVersion: number;
+  triggeredBy: string;
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'paused';
+  mode: 'manual' | 'trigger' | 'webhook';
+  contextData: Record<string, any>;
+  state: Record<string, any>;
+  startedAt: string | null;
+  completedAt: string | null;
+  waitUntil: string | null;
+  errorMessage: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WorkflowFilters {
+  team?: string;
+  isActive?: boolean;
+  isTemplate?: boolean;
+  page?: number;
+  pageSize?: number;
+  ordering?: string;
+}
+
+export interface ExecuteWorkflowInput {
+  contextData?: Record<string, any>;
+  mode?: 'manual' | 'trigger' | 'webhook';
+}
+
+export interface CreateWorkflowInput {
+  name: string;
+  description?: string;
+  team: string;
+  nodes?: any[];
+  connections?: Record<string, any>;
+  settings?: Record<string, any>;
+  isActive?: boolean;
+}
+
+export interface UpdateWorkflowInput extends Partial<CreateWorkflowInput> {}

package/src/utils/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility exports for @startsimpli/api
+ */
+
+export { buildUrl, buildQueryString, normalizeId } from './url-builder';
+export type { UrlBuilderOptions } from './url-builder';
+
+export {
+  buildFilterParams,
+  buildOrderingParam,
+  mergeQueryParams,
+} from './query-params';
+export type { DjangoFilterParams } from './query-params';

package/src/utils/query-params.ts

@@ -0,0 +1,79 @@
+/**
+ * Django query parameter helpers
+ */
+
+import type { PaginationParams, SortParams } from '../types';
+
+export interface DjangoFilterParams extends PaginationParams, SortParams {
+  search?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Build Django filter params from filters object
+ */
+export function buildFilterParams<T extends Record<string, unknown>>(
+  filters: T
+): Record<string, unknown> {
+  const params: Record<string, unknown> = {};
+
+  Object.entries(filters).forEach(([key, value]) => {
+    if (value === undefined || value === null) {
+      return;
+    }
+
+    // Handle boolean filters (e.g., has_email=true)
+    if (typeof value === 'boolean') {
+      params[key] = value;
+      return;
+    }
+
+    // Handle array filters (e.g., tier__in=[1,2,3])
+    if (Array.isArray(value)) {
+      if (value.length > 0) {
+        params[`${key}__in`] = value.join(',');
+      }
+      return; // Skip empty arrays
+    }
+
+    // Handle range filters (e.g., check_size_min__gte=100000)
+    if (key.endsWith('_gte') || key.endsWith('_lte') || key.endsWith('_gt') || key.endsWith('_lt')) {
+      params[key] = value;
+      return;
+    }
+
+    // Default: exact match
+    params[key] = value;
+  });
+
+  return params;
+}
+
+/**
+ * Build Django ordering param from sort config
+ */
+export function buildOrderingParam(
+  field?: string,
+  direction: 'asc' | 'desc' = 'asc'
+): string | undefined {
+  if (!field) {
+    return undefined;
+  }
+
+  return direction === 'desc' ? `-${field}` : field;
+}
+
+/**
+ * Merge pagination, sorting, and filter params
+ */
+export function mergeQueryParams(
+  pagination?: PaginationParams,
+  sorting?: SortParams,
+  filters?: Record<string, unknown>
+): Record<string, unknown> {
+  return {
+    ...filters,
+    ...pagination,
+    ...sorting,
+  };
+}

package/src/utils/url-builder.ts

@@ -0,0 +1,78 @@
+/**
+ * URL construction utilities for Django REST API
+ */
+
+export interface UrlBuilderOptions {
+  baseUrl: string;
+  endpoint: string;
+  params?: Record<string, unknown>;
+  id?: string | number;
+}
+
+/**
+ * Build API URL with query parameters
+ */
+export function buildUrl({ baseUrl, endpoint, params, id }: UrlBuilderOptions): string {
+  // Remove trailing slash from baseUrl, leading slash from endpoint
+  const cleanBase = baseUrl.replace(/\/$/, '');
+  const cleanEndpoint = endpoint.replace(/^\//, '');
+
+  // Build path with optional ID
+  let path = `${cleanBase}/${cleanEndpoint}`;
+  if (id !== undefined) {
+    path += `/${id}`;
+  }
+
+  // Add trailing slash (Django convention)
+  if (!path.endsWith('/')) {
+    path += '/';
+  }
+
+  // Add query parameters
+  if (params && Object.keys(params).length > 0) {
+    const queryString = buildQueryString(params);
+    if (queryString) {
+      path += `?${queryString}`;
+    }
+  }
+
+  return path;
+}
+
+/**
+ * Build query string from params object
+ */
+export function buildQueryString(params: Record<string, unknown>): string {
+  const searchParams = new URLSearchParams();
+
+  Object.entries(params).forEach(([key, value]) => {
+    if (value === undefined || value === null) {
+      return;
+    }
+
+    if (Array.isArray(value)) {
+      // Django handles arrays with comma-separated values
+      value.forEach((item) => {
+        searchParams.append(key, String(item));
+      });
+    } else if (typeof value === 'object') {
+      // Serialize objects as JSON
+      searchParams.append(key, JSON.stringify(value));
+    } else {
+      searchParams.append(key, String(value));
+    }
+  });
+
+  return searchParams.toString();
+}
+
+/**
+ * Extract ID from URL or return as-is
+ */
+export function normalizeId(id: string | number): string | number {
+  if (typeof id === 'string' && id.includes('/')) {
+    const parts = id.split('/').filter(Boolean);
+    return parts[parts.length - 1];
+  }
+  return id;
+}