@startsimpli/api 0.1.0

package/src/lib/messages-api.ts.backup

@@ -0,0 +1,273 @@
+/**
+ * Messages API wrapper
+ *
+ * Provides type-safe access to Django Messages API
+ */
+
+import type { ApiClient } from './api-client';
+
+export type MessageStatus = 'draft' | 'scheduled' | 'sending' | 'sent' | 'failed';
+export type MessageContentType = 'text/plain' | 'text/markdown' | 'text/html';
+export type RecipientStatus = 'pending' | 'sent' | 'delivered' | 'bounced' | 'opened' | 'clicked';
+
+export interface Message {
+  id: string;
+  team: string;
+  channel: string;
+  channel_details?: {
+    key: string;
+    name: string;
+    description: string;
+    icon: string;
+  };
+  subject: string;
+  body: string;
+  content_type: MessageContentType;
+  from_name: string | null;
+  from_email: string | null;
+  reply_to: string | null;
+  status: MessageStatus;
+  scheduled_at: string | null;
+  sent_at: string | null;
+  metadata: Record<string, any>;
+  total_recipients: number;
+  recipients_sent: number;
+  recipients_delivered: number;
+  recipients_opened: number;
+  recipients_clicked: number;
+  recipients_bounced: number;
+  recipients_unsubscribed: number;
+  open_rate: number;
+  click_rate: number;
+  bounce_rate: number;
+  error_message: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface MessageRecipient {
+  id: string;
+  recipient_type: string;
+  recipient_id: string | null;
+  recipient_email: string;
+  recipient_name: string | null;
+  channel_identifier: string | null;
+  channel_profiles: Record<string, any>;
+  status: RecipientStatus;
+  sent_at: string | null;
+  delivered_at: string | null;
+  bounced_at: string | null;
+  first_opened_at: string | null;
+  last_opened_at: string | null;
+  first_clicked_at: string | null;
+  last_clicked_at: string | null;
+  open_count: number;
+  click_count: number;
+  is_unsubscribed: boolean;
+  unsubscribed_at: string | null;
+  error_message: string | null;
+  created_at: string;
+}
+
+export interface MessagingChannel {
+  id: string;
+  key: string;
+  name: string;
+  description: string;
+  icon: string;
+  capabilities: {
+    max_content_length: number;
+    supports_html: boolean;
+    supports_markdown: boolean;
+    supports_attachments: boolean;
+    max_attachments: number;
+    max_attachment_size: number;
+  };
+  requirements: {
+    requires_connection: boolean;
+    requires_opt_in: boolean;
+    auth_requirements: Record<string, any>;
+  };
+  rate_limit: {
+    messages: number;
+    seconds: number;
+    scope: string;
+    description: string;
+  };
+  metadata: Record<string, any>;
+}
+
+export interface MessageFilters {
+  status?: MessageStatus;
+  content_type?: MessageContentType;
+  scheduled_after?: string;
+  scheduled_before?: string;
+  sent_after?: string;
+  sent_before?: string;
+  search?: string;
+  page?: number;
+  page_size?: number;
+  ordering?: string;
+}
+
+export interface CreateMessageInput {
+  channel: string;
+  subject: string;
+  body: string;
+  content_type?: MessageContentType;
+  from_name?: string;
+  from_email?: string;
+  reply_to?: string;
+  scheduled_at?: string;
+  metadata?: Record<string, any>;
+  recipients?: Array<{
+    recipient_type: string;
+    recipient_email: string;
+    recipient_name?: string;
+    channel_identifier?: string;
+  }>;
+}
+
+export interface ScheduleMessageInput {
+  scheduled_at: string;
+}
+
+export interface SendTestInput {
+  test_email?: string;
+}
+
+export class MessagesApi {
+  constructor(private client: ApiClient) {}
+
+  /**
+   * List messages with optional filters
+   */
+  async list(filters?: MessageFilters) {
+    const params = new URLSearchParams();
+
+    if (filters?.status) params.append('status', filters.status);
+    if (filters?.content_type) params.append('content_type', filters.content_type);
+    if (filters?.scheduled_after) params.append('scheduled_after', filters.scheduled_after);
+    if (filters?.scheduled_before) params.append('scheduled_before', filters.scheduled_before);
+    if (filters?.sent_after) params.append('sent_after', filters.sent_after);
+    if (filters?.sent_before) params.append('sent_before', filters.sent_before);
+    if (filters?.search) params.append('search', filters.search);
+    if (filters?.page) params.append('page', String(filters.page));
+    if (filters?.page_size) params.append('page_size', String(filters.page_size));
+    if (filters?.ordering) params.append('ordering', filters.ordering);
+
+    return this.client.get<{ results: Message[]; count: number; next: string | null; previous: string | null }>(
+      `/api/v1/messages/?${params.toString()}`
+    );
+  }
+
+  /**
+   * Get message by ID
+   */
+  async get(id: string) {
+    return this.client.get<Message>(`/api/v1/messages/${id}/`);
+  }
+
+  /**
+   * Create a new message
+   */
+  async create(data: CreateMessageInput) {
+    return this.client.post<Message>('/api/v1/messages/', data);
+  }
+
+  /**
+   * Update message (draft only)
+   */
+  async update(id: string, data: Partial<CreateMessageInput>) {
+    return this.client.patch<Message>(`/api/v1/messages/${id}/`, data);
+  }
+
+  /**
+   * Delete message (draft only)
+   */
+  async delete(id: string) {
+    return this.client.delete(`/api/v1/messages/${id}/`);
+  }
+
+  /**
+   * Schedule message for future sending
+   */
+  async schedule(id: string, input: ScheduleMessageInput) {
+    return this.client.post<{ id: string; status: MessageStatus; scheduled_at: string; message: string }>(
+      `/api/v1/messages/${id}/schedule/`,
+      input
+    );
+  }
+
+  /**
+   * Send message immediately
+   */
+  async sendNow(id: string) {
+    return this.client.post<{ id: string; status: MessageStatus; message: string }>(
+      `/api/v1/messages/${id}/send_now/`,
+      {}
+    );
+  }
+
+  /**
+   * Send test message
+   */
+  async sendTest(id: string, input?: SendTestInput) {
+    return this.client.post<{ id: string; test_email: string; message: string }>(
+      `/api/v1/messages/${id}/send_test/`,
+      input || {}
+    );
+  }
+
+  /**
+   * Preview message rendering
+   */
+  async preview(id: string) {
+    return this.client.get<{
+      subject: string;
+      body: string;
+      preview_html: string;
+      from_name: string;
+      from_email: string;
+    }>(`/api/v1/messages/${id}/preview/`);
+  }
+
+  /**
+   * List recipients for a message
+   */
+  async getRecipients(id: string, page?: number, pageSize?: number) {
+    const params = new URLSearchParams();
+    if (page) params.append('page', String(page));
+    if (pageSize) params.append('page_size', String(pageSize));
+
+    return this.client.get<{ results: MessageRecipient[]; count: number }>(
+      `/api/v1/messages/${id}/recipients/?${params.toString()}`
+    );
+  }
+
+  /**
+   * Add recipients to a message
+   */
+  async addRecipients(
+    id: string,
+    recipients: Array<{
+      recipient_type: string;
+      recipient_email: string;
+      recipient_name?: string;
+      channel_identifier?: string;
+    }>
+  ) {
+    return this.client.post<{
+      message: string;
+      total_recipients: number;
+      recipients: MessageRecipient[];
+    }>(`/api/v1/messages/${id}/add_recipients/`, { recipients });
+  }
+
+  /**
+   * Get available messaging channels
+   */
+  async getChannels() {
+    return this.client.get<{ channels: MessagingChannel[]; count: number }>('/api/v1/messages/channels/');
+  }
+}

package/src/lib/organizations-api.ts

@@ -0,0 +1,132 @@
+/**
+ * Organizations API wrapper for /api/v1/organizations/
+ */
+
+import type {
+  Organization,
+  CreateOrganizationRequest,
+  UpdateOrganizationRequest,
+  OrganizationFilters,
+  PaginatedResponse,
+  PaginationParams,
+  SortParams,
+} from '../types';
+import { buildFilterParams, mergeQueryParams } from '../utils';
+import { ENDPOINTS } from '../constants/endpoints';
+import type { ApiClient } from './api-client';
+
+export class OrganizationsApi {
+  constructor(private client: ApiClient) {}
+
+  /**
+   * List organizations with pagination and filters
+   */
+  async list(
+    filters?: OrganizationFilters,
+    pagination?: PaginationParams,
+    sorting?: SortParams
+  ): Promise<PaginatedResponse<Organization>> {
+    const params = mergeQueryParams(
+      pagination,
+      sorting,
+      filters ? buildFilterParams(filters) : undefined
+    );
+
+    return this.client.fetch.get<PaginatedResponse<Organization>>(ENDPOINTS.ORGANIZATIONS, {
+      params,
+    });
+  }
+
+  /**
+   * Get organization by ID
+   */
+  async get(id: string): Promise<Organization> {
+    return this.client.fetch.get<Organization>(ENDPOINTS.ORGANIZATION(id));
+  }
+
+  /**
+   * Create new organization
+   */
+  async create(data: CreateOrganizationRequest): Promise<Organization> {
+    return this.client.fetch.post<Organization>(ENDPOINTS.ORGANIZATIONS, data);
+  }
+
+  /**
+   * Update organization
+   */
+  async update(id: string, data: UpdateOrganizationRequest): Promise<Organization> {
+    return this.client.fetch.patch<Organization>(ENDPOINTS.ORGANIZATION(id), data);
+  }
+
+  /**
+   * Delete organization
+   */
+  async delete(id: string): Promise<void> {
+    return this.client.fetch.delete<void>(ENDPOINTS.ORGANIZATION(id));
+  }
+
+  /**
+   * Bulk create organizations
+   */
+  async bulkCreate(data: CreateOrganizationRequest[]): Promise<Organization[]> {
+    return this.client.fetch.post<Organization[]>(ENDPOINTS.ORGANIZATIONS_BULK, data);
+  }
+
+  /**
+   * Search organizations by name, domain, or location
+   */
+  async search(
+    query: string,
+    pagination?: PaginationParams
+  ): Promise<PaginatedResponse<Organization>> {
+    return this.list({ search: query }, pagination);
+  }
+
+  /**
+   * Get organizations by tier
+   */
+  async getByTier(
+    tier: number,
+    pagination?: PaginationParams
+  ): Promise<PaginatedResponse<Organization>> {
+    return this.list({ tier }, pagination);
+  }
+
+  /**
+   * Get organizations by stage
+   */
+  async getByStage(
+    stage: string,
+    pagination?: PaginationParams
+  ): Promise<PaginatedResponse<Organization>> {
+    return this.list({ stage }, pagination);
+  }
+
+  /**
+   * Get organizations by focus area
+   */
+  async getByFocusArea(
+    focusArea: string,
+    pagination?: PaginationParams
+  ): Promise<PaginatedResponse<Organization>> {
+    return this.list({ focusArea }, pagination);
+  }
+
+  /**
+   * Get organizations by check size range
+   */
+  async getByCheckSizeRange(
+    min?: number,
+    max?: number,
+    pagination?: PaginationParams
+  ): Promise<PaginatedResponse<Organization>> {
+    const filters: OrganizationFilters = {};
+    if (min !== undefined) {
+      filters.checkSizeMinGte = min;
+    }
+    if (max !== undefined) {
+      filters.checkSizeMaxLte = max;
+    }
+    return this.list(filters, pagination);
+  }
+}

package/src/lib/rate-limit.ts

@@ -0,0 +1,91 @@
+/**
+ * In-memory rate limiter for Next.js API routes.
+ *
+ * Fixed-window counter with periodic cleanup.
+ * Resets on server restart and does not share state across multiple instances.
+ * For multi-instance production use, back the store with Redis/Upstash instead.
+ */
+
+export interface RateLimitOptions {
+  /** Duration of the rate limit window in milliseconds */
+  windowMs: number;
+  /** Maximum number of requests allowed per window */
+  maxRequests: number;
+  /** Optional prefix for keys (useful when sharing a single limiter across routes) */
+  keyPrefix?: string;
+}
+
+export interface RateLimitResult {
+  /** Whether the request is within the allowed limit */
+  success: boolean;
+  /** Requests remaining in the current window */
+  remaining: number;
+  /** Timestamp (ms since epoch) when the current window resets */
+  resetAt: number;
+  /** Seconds to wait before retrying, present only when success is false */
+  retryAfter?: number;
+}
+
+interface RateLimitEntry {
+  count: number;
+  resetAt: number;
+}
+
+const CLEANUP_INTERVAL_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Factory that returns a rate-check function backed by an isolated in-memory store.
+ *
+ * @example
+ * const check = createRateLimiter({ windowMs: 60_000, maxRequests: 10 });
+ * const result = check('user:123');
+ * if (!result.success) { // respond 429 }
+ */
+export function createRateLimiter(options: RateLimitOptions): (key: string) => RateLimitResult {
+  const { windowMs, maxRequests, keyPrefix = '' } = options;
+  const store = new Map<string, RateLimitEntry>();
+  let lastCleanup = Date.now();
+
+  function cleanup(): void {
+    const now = Date.now();
+    if (now - lastCleanup < CLEANUP_INTERVAL_MS) return;
+    lastCleanup = now;
+    for (const [key, entry] of store.entries()) {
+      if (now > entry.resetAt) store.delete(key);
+    }
+  }
+
+  return function check(key: string): RateLimitResult {
+    cleanup();
+
+    const storeKey = keyPrefix ? `${keyPrefix}:${key}` : key;
+    const now = Date.now();
+    const entry = store.get(storeKey);
+
+    if (!entry || now > entry.resetAt) {
+      const resetAt = now + windowMs;
+      store.set(storeKey, { count: 1, resetAt });
+      return { success: true, remaining: maxRequests - 1, resetAt };
+    }
+
+    if (entry.count >= maxRequests) {
+      const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
+      return { success: false, remaining: 0, resetAt: entry.resetAt, retryAfter };
+    }
+
+    entry.count++;
+    return { success: true, remaining: maxRequests - entry.count, resetAt: entry.resetAt };
+  };
+}
+
+/**
+ * Extract the client IP address from a Web API Request or NextRequest.
+ * Respects x-forwarded-for and x-real-ip proxy headers.
+ */
+export function getClientIP(request: Request): string {
+  const forwarded = request.headers.get('x-forwarded-for');
+  if (forwarded) return forwarded.split(',')[0].trim();
+  const real = request.headers.get('x-real-ip');
+  if (real) return real;
+  return 'unknown';
+}

package/src/lib/sanitize.ts

@@ -0,0 +1,39 @@
+import DOMPurify from 'isomorphic-dompurify';
+
+/**
+ * XSS Protection - sanitize HTML content
+ *
+ * Strips all tags except a safe allowlist and removes dangerous attributes.
+ */
+export function sanitizeHtml(input: string): string {
+  return DOMPurify.sanitize(input, {
+    ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p', 'br'],
+    ALLOWED_ATTR: ['href'],
+    ALLOW_DATA_ATTR: false,
+  });
+}
+
+/**
+ * Validate and sanitize a search query string.
+ *
+ * Trims whitespace, escapes regex special characters, and limits length to 100 chars.
+ */
+export function sanitizeSearchQuery(query: string): string {
+  if (!query || typeof query !== 'string') {
+    return '';
+  }
+
+  return query
+    .trim()
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars
+    .substring(0, 100); // Limit length
+}
+
+/**
+ * Validate that a string is a safe SQL/API identifier.
+ *
+ * Only allows alphanumeric characters, underscores, and hyphens.
+ */
+export function validateIdentifier(input: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(input);
+}

package/src/lib/workflows-api.ts

@@ -0,0 +1,159 @@
+/**
+ * Workflows API wrapper
+ *
+ * Provides type-safe access to Django Workflows API
+ */
+
+import type { ApiClient } from './api-client';
+
+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 class WorkflowsApi {
+  constructor(private client: ApiClient) {}
+
+  /**
+   * List workflows with optional filters
+   */
+  async list(filters?: WorkflowFilters) {
+    const params = new URLSearchParams();
+
+    if (filters?.team) params.append('team', filters.team);
+    if (filters?.isActive !== undefined) params.append('isActive', String(filters.isActive));
+    if (filters?.isTemplate !== undefined) params.append('isTemplate', String(filters.isTemplate));
+    if (filters?.page) params.append('page', String(filters.page));
+    if (filters?.pageSize) params.append('pageSize', String(filters.pageSize));
+    if (filters?.ordering) params.append('ordering', filters.ordering);
+
+    return this.client.get<{ results: Workflow[]; count: number; next: string | null; previous: string | null }>(
+      `/api/v1/workflows/?${params.toString()}`
+    );
+  }
+
+  /**
+   * Get workflow by ID
+   */
+  async get(id: string) {
+    return this.client.get<Workflow>(`/api/v1/workflows/${id}/`);
+  }
+
+  /**
+   * Create a new workflow
+   */
+  async create(data: CreateWorkflowInput) {
+    return this.client.post<Workflow>('/api/v1/workflows/', data);
+  }
+
+  /**
+   * Update workflow
+   */
+  async update(id: string, data: Partial<CreateWorkflowInput>) {
+    return this.client.patch<Workflow>(`/api/v1/workflows/${id}/`, data);
+  }
+
+  /**
+   * Delete workflow
+   */
+  async delete(id: string) {
+    return this.client.delete(`/api/v1/workflows/${id}/`);
+  }
+
+  /**
+   * Execute workflow
+   */
+  async execute(id: string, input?: ExecuteWorkflowInput) {
+    return this.client.post<WorkflowExecution>(
+      `/api/v1/workflows/${id}/execute/`,
+      input || {}
+    );
+  }
+
+  /**
+   * Get workflow templates
+   */
+  async templates() {
+    return this.client.get<Workflow[]>('/api/v1/workflows/templates/');
+  }
+
+  /**
+   * List workflow executions
+   */
+  async listExecutions(filters?: { workflow?: string; status?: string; page?: number; pageSize?: number }) {
+    const params = new URLSearchParams();
+
+    if (filters?.workflow) params.append('workflow', filters.workflow);
+    if (filters?.status) params.append('status', filters.status);
+    if (filters?.page) params.append('page', String(filters.page));
+    if (filters?.pageSize) params.append('pageSize', String(filters.pageSize));
+
+    return this.client.get<{ results: WorkflowExecution[]; count: number }>(
+      `/api/v1/workflow-executions/?${params.toString()}`
+    );
+  }
+
+  /**
+   * Get workflow execution details
+   */
+  async getExecution(id: string) {
+    return this.client.get<WorkflowExecution>(`/api/v1/workflow-executions/${id}/`);
+  }
+}

package/src/middleware/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Middleware exports for @startsimpli/api
+ */
+
+export { withAuth, extractUserIdFromToken } from './with-auth';
+export type { AuthContext, ApiHandler, WithAuthOptions } from './with-auth';
+
+export { withErrorHandling } from './with-error-handling';
+export type { ErrorApiHandler, ErrorResponseBody } from './with-error-handling';
+
+export { withValidation, composeMiddleware } from './with-validation';
+export type { ValidatedApiHandler, ValidationSchemas } from './with-validation';