@startsimpli/api 0.1.0

package/src/__tests__/url-builder.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Tests for URL builder utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildUrl, buildQueryString, normalizeId } from '../utils/url-builder';
+
+describe('buildUrl', () => {
+  it('should build URL with base and endpoint', () => {
+    const url = buildUrl({
+      baseUrl: 'http://localhost:8000/api/v1',
+      endpoint: 'contacts',
+    });
+
+    expect(url).toBe('http://localhost:8000/api/v1/contacts/');
+  });
+
+  it('should handle trailing slashes correctly', () => {
+    const url = buildUrl({
+      baseUrl: 'http://localhost:8000/api/v1/',
+      endpoint: '/contacts/',
+    });
+
+    expect(url).toBe('http://localhost:8000/api/v1/contacts/');
+  });
+
+  it('should build URL with ID', () => {
+    const url = buildUrl({
+      baseUrl: 'http://localhost:8000/api/v1',
+      endpoint: 'contacts',
+      id: '123',
+    });
+
+    expect(url).toBe('http://localhost:8000/api/v1/contacts/123/');
+  });
+
+  it('should build URL with query params', () => {
+    const url = buildUrl({
+      baseUrl: 'http://localhost:8000/api/v1',
+      endpoint: 'contacts',
+      params: { page: 1, page_size: 20, tier: 1 },
+    });
+
+    expect(url).toContain('http://localhost:8000/api/v1/contacts/?');
+    expect(url).toContain('page=1');
+    expect(url).toContain('page_size=20');
+    expect(url).toContain('tier=1');
+  });
+
+  it('should build URL with ID and params', () => {
+    const url = buildUrl({
+      baseUrl: 'http://localhost:8000/api/v1',
+      endpoint: 'contacts',
+      id: '123',
+      params: { include_tags: true },
+    });
+
+    expect(url).toContain('http://localhost:8000/api/v1/contacts/123/?');
+    expect(url).toContain('include_tags=true');
+  });
+});
+
+describe('buildQueryString', () => {
+  it('should build query string from params', () => {
+    const query = buildQueryString({
+      page: 1,
+      page_size: 20,
+      search: 'test',
+    });
+
+    expect(query).toContain('page=1');
+    expect(query).toContain('page_size=20');
+    expect(query).toContain('search=test');
+  });
+
+  it('should skip undefined and null values', () => {
+    const query = buildQueryString({
+      page: 1,
+      search: undefined,
+      filter: null,
+    });
+
+    expect(query).toBe('page=1');
+  });
+
+  it('should handle array params', () => {
+    const query = buildQueryString({
+      tags: ['tag1', 'tag2', 'tag3'],
+    });
+
+    expect(query).toContain('tags=tag1');
+    expect(query).toContain('tags=tag2');
+    expect(query).toContain('tags=tag3');
+  });
+
+  it('should serialize object params as JSON', () => {
+    const query = buildQueryString({
+      filter: { tier: 1, status: 'active' },
+    });
+
+    const decoded = decodeURIComponent(query);
+    expect(decoded).toContain('filter=');
+    expect(decoded).toContain('"tier":1');
+    expect(decoded).toContain('"status":"active"');
+  });
+});
+
+describe('normalizeId', () => {
+  it('should return number ID as-is', () => {
+    expect(normalizeId(123)).toBe(123);
+  });
+
+  it('should return string ID as-is', () => {
+    expect(normalizeId('abc-123')).toBe('abc-123');
+  });
+
+  it('should extract ID from URL', () => {
+    expect(normalizeId('/api/v1/contacts/123/')).toBe('123');
+    expect(normalizeId('http://localhost/api/v1/contacts/abc-123/')).toBe('abc-123');
+  });
+});

package/src/constants/endpoints.ts

@@ -0,0 +1,39 @@
+/**
+ * Django REST API endpoint constants
+ */
+
+export const ENDPOINTS = {
+  // Contacts
+  CONTACTS: 'contacts',
+  CONTACTS_BULK: 'contacts/bulk',
+  CONTACT: (id: string) => `contacts/${id}`,
+
+  // Organizations
+  ORGANIZATIONS: 'organizations',
+  ORGANIZATIONS_BULK: 'organizations/bulk',
+  ORGANIZATION: (id: string) => `organizations/${id}`,
+
+  // Core entities
+  TAGS: 'core/tags',
+  TAG: (id: string) => `core/tags/${id}`,
+  ENTITY_TAGS: 'core/entity-tags',
+  ENTITY_TAG: (id: string) => `core/entity-tags/${id}`,
+  METRICS: 'core/metrics',
+  METRIC: (id: string) => `core/metrics/${id}`,
+  PROFILES: 'core/profiles',
+  PROFILE: (id: string) => `core/profiles/${id}`,
+  ATTRIBUTES: 'core/attributes',
+  ATTRIBUTE: (id: string) => `core/attributes/${id}`,
+  RELATIONSHIPS: 'core/relationships',
+  RELATIONSHIP: (id: string) => `core/relationships/${id}`,
+
+  // Workflows
+  WORKFLOWS: 'workflows',
+  WORKFLOW: (id: string) => `workflows/${id}`,
+  WORKFLOW_EXECUTE: (id: string) => `workflows/${id}/execute`,
+
+  // Messages
+  MESSAGES: 'messages',
+  MESSAGE: (id: string) => `messages/${id}`,
+  MESSAGE_SEND: (id: string) => `messages/${id}/send`,
+} as const;

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * @startsimpli/api - Type-safe Django REST API client
+ *
+ * This package provides type-safe access to the Django backend API.
+ * NO Prisma, NO database code - all data lives in Django.
+ */
+
+// Core client
+export { ApiClient, createApiClient } from './lib/api-client';
+export type { ApiClientConfig } from './lib/api-client';
+
+// 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';
+
+// Fetch wrapper
+export { FetchWrapper } from './lib/fetch-wrapper';
+export type { FetchWrapperConfig } from './lib/fetch-wrapper';
+
+// Error handling (API client errors — fetch/HTTP layer)
+export {
+  ApiException,
+  parseErrorResponse,
+  handleFetchError,
+  isApiException,
+  isValidationError,
+  isAuthError,
+  isNotFoundError,
+} from './lib/error-handler';
+
+// Application error hierarchy (server-side domain errors)
+export {
+  AppErrorCode,
+  AppError,
+  ValidationError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  DatabaseError,
+  ExternalServiceError,
+  isPrismaError,
+  toAppError,
+} from './lib/errors';
+export type { AppErrorResponse } from './lib/errors';
+
+// Sanitization utilities
+export { sanitizeHtml, sanitizeSearchQuery, validateIdentifier } from './lib/sanitize';
+
+// LLM prompt sanitization
+export {
+  sanitizeUserInput,
+  sanitizeChatMessage,
+  MAX_PROMPT_LENGTH,
+  MAX_CHAT_MESSAGE_LENGTH,
+} from './lib/llm-sanitize';
+
+// CORS utilities (framework-agnostic, safe to import anywhere)
+export { getCorsHeaders, applyCorsHeaders, createCorsMiddleware } from './lib/cors';
+export type { CorsOptions } from './lib/cors';
+
+// NOTE: Middleware is NOT exported from main entry to avoid Next.js server dependencies in tests
+// Import middleware explicitly via '@startsimpli/api/middleware'
+
+// Types
+export * from './types';
+
+// Rate limiting
+export { createRateLimiter, getClientIP } from './lib/rate-limit';
+export type { RateLimitOptions, RateLimitResult } from './lib/rate-limit';
+
+// Utils
+export * from './utils';
+
+// Constants
+export { ENDPOINTS } from './constants/endpoints';
+
+// Environment variable utilities
+export { getRequiredEnv, getOptionalEnv, validateEnvVars } from './lib/env';
+
+import { createApiClient } from './lib/api-client';
+import { ContactsApi } from './lib/contacts-api';
+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 type { ApiClientConfig } from './lib/api-client';
+
+/**
+ * Create a complete API client with all endpoints
+ */
+export function createStartSimpliApi(config: ApiClientConfig) {
+  const client = createApiClient(config);
+
+  return {
+    client,
+    contacts: new ContactsApi(client),
+    organizations: new OrganizationsApi(client),
+    entities: new EntitiesApi(client),
+    workflows: new WorkflowsApi(client),
+    messages: new MessagesApi(client),
+  };
+}

package/src/lib/api-client.ts

@@ -0,0 +1,89 @@
+/**
+ * Main API client for Django REST API
+ */
+
+import { FetchWrapper, type FetchWrapperConfig } from './fetch-wrapper';
+
+export interface ApiClientConfig {
+  baseUrl: string;
+  getToken?: () => Promise<string | null> | string | null;
+  onUnauthorized?: () => void;
+  onTokenRefresh?: () => Promise<string | null>;
+}
+
+export class ApiClient {
+  private fetcher: FetchWrapper;
+  public readonly baseUrl: string;
+
+  constructor(config: ApiClientConfig) {
+    this.baseUrl = config.baseUrl;
+
+    this.fetcher = new FetchWrapper({
+      baseUrl: config.baseUrl,
+      getToken: config.getToken,
+      onUnauthorized: config.onUnauthorized,
+      onTokenRefresh: config.onTokenRefresh,
+      defaultHeaders: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+    });
+  }
+
+  /**
+   * Get the fetch wrapper instance for direct access
+   */
+  get fetch(): FetchWrapper {
+    return this.fetcher;
+  }
+
+  /**
+   * 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,
+    });
+  }
+
+  /**
+   * 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,
+    });
+  }
+
+  /**
+   * Convenience HTTP methods that delegate to FetchWrapper
+   */
+  async get<T>(endpoint: string, options?: any): Promise<T> {
+    return this.fetcher.get<T>(endpoint, options);
+  }
+
+  async post<T, D = unknown>(endpoint: string, data?: D, options?: any): Promise<T> {
+    return this.fetcher.post<T, D>(endpoint, data, options);
+  }
+
+  async patch<T, D = unknown>(endpoint: string, data?: D, options?: any): Promise<T> {
+    return this.fetcher.patch<T, D>(endpoint, data, options);
+  }
+
+  async delete<T>(endpoint: string, options?: any): Promise<T> {
+    return this.fetcher.delete<T>(endpoint, options);
+  }
+}
+
+/**
+ * Create API client instance
+ */
+export function createApiClient(config: ApiClientConfig): ApiClient {
+  return new ApiClient(config);
+}

package/src/lib/contacts-api.ts

@@ -0,0 +1,111 @@
+/**
+ * Contacts API wrapper for /api/v1/contacts/
+ */
+
+import type {
+  Contact,
+  CreateContactRequest,
+  UpdateContactRequest,
+  ContactFilters,
+  PaginatedResponse,
+  PaginationParams,
+  SortParams,
+} from '../types';
+import { buildFilterParams, mergeQueryParams } from '../utils';
+import { ENDPOINTS } from '../constants/endpoints';
+import type { ApiClient } from './api-client';
+
+export class ContactsApi {
+  constructor(private client: ApiClient) {}
+
+  /**
+   * List contacts with pagination and filters
+   */
+  async list(
+    filters?: ContactFilters,
+    pagination?: PaginationParams,
+    sorting?: SortParams
+  ): Promise<PaginatedResponse<Contact>> {
+    const params = mergeQueryParams(
+      pagination,
+      sorting,
+      filters ? buildFilterParams(filters) : undefined
+    );
+
+    return this.client.fetch.get<PaginatedResponse<Contact>>(ENDPOINTS.CONTACTS, { params });
+  }
+
+  /**
+   * Get contact by ID
+   */
+  async get(id: string): Promise<Contact> {
+    return this.client.fetch.get<Contact>(ENDPOINTS.CONTACT(id));
+  }
+
+  /**
+   * Create new contact
+   */
+  async create(data: CreateContactRequest): Promise<Contact> {
+    return this.client.fetch.post<Contact>(ENDPOINTS.CONTACTS, data);
+  }
+
+  /**
+   * Update contact
+   */
+  async update(id: string, data: UpdateContactRequest): Promise<Contact> {
+    return this.client.fetch.patch<Contact>(ENDPOINTS.CONTACT(id), data);
+  }
+
+  /**
+   * Delete contact
+   */
+  async delete(id: string): Promise<void> {
+    return this.client.fetch.delete<void>(ENDPOINTS.CONTACT(id));
+  }
+
+  /**
+   * Bulk create contacts
+   */
+  async bulkCreate(data: CreateContactRequest[]): Promise<Contact[]> {
+    return this.client.fetch.post<Contact[]>(ENDPOINTS.CONTACTS_BULK, data);
+  }
+
+  /**
+   * Search contacts by name, email, or company
+   */
+  async search(
+    query: string,
+    pagination?: PaginationParams
+  ): Promise<PaginatedResponse<Contact>> {
+    return this.list({ search: query }, pagination);
+  }
+
+  /**
+   * Get contacts by tier
+   */
+  async getByTier(
+    tier: number,
+    pagination?: PaginationParams
+  ): Promise<PaginatedResponse<Contact>> {
+    return this.list({ tier }, pagination);
+  }
+
+  /**
+   * Get contacts by firm
+   */
+  async getByFirm(
+    firmId: string,
+    pagination?: PaginationParams
+  ): Promise<PaginatedResponse<Contact>> {
+    return this.list({ firmId }, pagination);
+  }
+
+  /**
+   * Get contacts with LinkedIn profiles
+   */
+  async getWithLinkedIn(
+    pagination?: PaginationParams
+  ): Promise<PaginatedResponse<Contact>> {
+    return this.list({ hasLinkedin: true }, pagination);
+  }
+}

package/src/lib/cors.ts

@@ -0,0 +1,122 @@
+/**
+ * CORS utilities for Next.js API routes
+ *
+ * Framework-agnostic header generation with an optional Next.js
+ * middleware wrapper for apps that need it.
+ */
+
+export interface CorsOptions {
+  /** Allowed origins. Use '*' for wildcard. */
+  origins: string[] | '*';
+  /** Allowed HTTP methods. Defaults to common REST methods. */
+  methods?: string[];
+  /** Allowed request headers. Defaults to common headers. */
+  headers?: string[];
+  /** Whether to allow credentials. Defaults to true when origins is a list. */
+  credentials?: boolean;
+  /** Preflight cache duration in seconds. Defaults to 86400 (24h). */
+  maxAge?: number;
+}
+
+const DEFAULT_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+const DEFAULT_HEADERS = ['Content-Type', 'Authorization', 'X-Requested-With', 'Accept', 'X-CSRF-Token'];
+
+/**
+ * Determine whether an incoming origin is permitted under the given options.
+ */
+function isAllowed(origin: string | null | undefined, options: CorsOptions): boolean {
+  if (!origin) return false;
+  if (options.origins === '*') return true;
+  return options.origins.includes(origin);
+}
+
+/**
+ * Build the CORS headers for a given request origin.
+ *
+ * Returns an empty object when the origin is not permitted so callers
+ * can decide whether to reject or silently omit the headers.
+ */
+export function getCorsHeaders(
+  origin: string | null | undefined,
+  options: CorsOptions
+): Record<string, string> {
+  if (!isAllowed(origin, options)) {
+    return {};
+  }
+
+  const methods = options.methods ?? DEFAULT_METHODS;
+  const headers = options.headers ?? DEFAULT_HEADERS;
+  // credentials only make sense with an explicit origin list
+  const credentials = options.credentials ?? options.origins !== '*';
+  const maxAge = options.maxAge ?? 86400;
+
+  const result: Record<string, string> = {
+    'Access-Control-Allow-Origin': options.origins === '*' ? '*' : (origin as string),
+    'Access-Control-Allow-Methods': methods.join(', '),
+    'Access-Control-Allow-Headers': headers.join(', '),
+    'Access-Control-Max-Age': String(maxAge),
+  };
+
+  if (credentials && options.origins !== '*') {
+    result['Access-Control-Allow-Credentials'] = 'true';
+  }
+
+  return result;
+}
+
+/**
+ * Apply CORS headers to an existing Headers object in-place.
+ */
+export function applyCorsHeaders(
+  responseHeaders: Headers,
+  origin: string | null | undefined,
+  options: CorsOptions
+): void {
+  const corsHeaders = getCorsHeaders(origin, options);
+  for (const [key, value] of Object.entries(corsHeaders)) {
+    responseHeaders.set(key, value);
+  }
+}
+
+/**
+ * Create a CORS middleware function for use in Next.js middleware.ts files.
+ *
+ * Returns a function that accepts a Request and returns a Response (for
+ * preflight OPTIONS) or null (for all other requests, letting the chain
+ * continue after headers are applied via getCorsHeaders).
+ *
+ * Usage in middleware.ts:
+ *
+ * ```ts
+ * import { createCorsMiddleware } from '@startsimpli/api';
+ * import { NextResponse } from 'next/server';
+ *
+ * const corsMiddleware = createCorsMiddleware({
+ *   origins: [process.env.NEXT_PUBLIC_BASE_URL ?? 'http://localhost:3000'],
+ * });
+ *
+ * export function middleware(request: Request) {
+ *   const preflightResponse = corsMiddleware(request);
+ *   if (preflightResponse) return preflightResponse;
+ *
+ *   const response = NextResponse.next();
+ *   const origin = request.headers.get('origin');
+ *   applyCorsHeaders(response.headers, origin, corsOptions);
+ *   return response;
+ * }
+ * ```
+ */
+export function createCorsMiddleware(options: CorsOptions) {
+  return function corsMiddleware(request: Request): Response | null {
+    const origin = request.headers.get('origin');
+
+    // Preflight: respond immediately with CORS headers and 204
+    if (request.method === 'OPTIONS') {
+      const corsHeaders = getCorsHeaders(origin, options);
+      return new Response(null, { status: 204, headers: corsHeaders });
+    }
+
+    // Non-preflight: caller is responsible for attaching headers via getCorsHeaders
+    return null;
+  };
+}