@startsimpli/api 0.1.0

package/src/middleware/with-auth.ts

@@ -0,0 +1,90 @@
+/**
+ * Auth middleware for Next.js API routes
+ */
+
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+export interface AuthContext {
+  userId?: string;
+  token?: string;
+  isAuthenticated: boolean;
+}
+
+export type ApiHandler<T = unknown> = (
+  request: NextRequest,
+  context: AuthContext
+) => Promise<NextResponse<T>> | NextResponse<T>;
+
+export interface WithAuthOptions {
+  required?: boolean;
+  getToken?: (request: NextRequest) => Promise<string | null> | string | null;
+}
+
+/**
+ * Auth middleware for Next.js API routes
+ */
+export function withAuth<T = unknown>(
+  handler: ApiHandler<T>,
+  options: WithAuthOptions = {}
+): (request: NextRequest) => Promise<NextResponse<T>> {
+  return async (request: NextRequest) => {
+    const { required = true, getToken } = options;
+
+    try {
+      // Get token from request
+      let token: string | null = null;
+
+      if (getToken) {
+        token = await getToken(request);
+      } else {
+        // Default: extract from Authorization header
+        const authHeader = request.headers.get('authorization');
+        if (authHeader?.startsWith('Bearer ')) {
+          token = authHeader.substring(7);
+        }
+      }
+
+      // Build auth context
+      const context: AuthContext = {
+        token: token || undefined,
+        isAuthenticated: !!token,
+      };
+
+      // Check if auth is required
+      if (required && !context.isAuthenticated) {
+        return NextResponse.json(
+          { error: 'Unauthorized', message: 'Authentication required' },
+          { status: 401 }
+        ) as NextResponse<T>;
+      }
+
+      // Call handler with context
+      return await handler(request, context);
+    } catch (error) {
+      console.error('Auth middleware error:', error);
+      return NextResponse.json(
+        { error: 'Internal Server Error', message: 'Authentication failed' },
+        { status: 500 }
+      ) as NextResponse<T>;
+    }
+  };
+}
+
+/**
+ * Extract user ID from JWT token (without verification)
+ * NOTE: This is for convenience only - always verify tokens on the backend
+ */
+export function extractUserIdFromToken(token: string): string | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    const payload = JSON.parse(atob(parts[1]));
+    return payload.sub || payload.user_id || payload.userId || null;
+  } catch {
+    return null;
+  }
+}

package/src/middleware/with-error-handling.ts

@@ -0,0 +1,83 @@
+/**
+ * Error handling middleware for Next.js API routes
+ */
+
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { ApiException } from '../lib/error-handler';
+
+export type ErrorApiHandler<T = unknown> = (
+  request: NextRequest
+) => Promise<NextResponse<T>> | NextResponse<T>;
+
+export interface ErrorResponseBody {
+  error: string;
+  message: string;
+  errors?: Record<string, string[]>;
+  status?: number;
+}
+
+/**
+ * Error handling middleware for Next.js API routes
+ */
+export function withErrorHandling<T = unknown>(
+  handler: ErrorApiHandler<T>
+): (request: NextRequest) => Promise<NextResponse<T | ErrorResponseBody>> {
+  return async (request: NextRequest) => {
+    try {
+      return await handler(request);
+    } catch (error) {
+      console.error('API error:', error);
+
+      // Handle ApiException
+      if (error instanceof ApiException) {
+        return NextResponse.json(
+          {
+            error: error.name,
+            message: error.message,
+            errors: error.errors,
+            status: error.status,
+          },
+          { status: error.status || 500 }
+        ) as NextResponse<ErrorResponseBody>;
+      }
+
+      // Handle validation errors (Zod, etc.)
+      if (error && typeof error === 'object' && 'issues' in error) {
+        const issues = (error as { issues: Array<{ path: string[]; message: string }> })
+          .issues;
+
+        const errors: Record<string, string[]> = {};
+        issues.forEach((issue) => {
+          const field = issue.path.join('.');
+          if (!errors[field]) {
+            errors[field] = [];
+          }
+          errors[field].push(issue.message);
+        });
+
+        return NextResponse.json(
+          {
+            error: 'ValidationError',
+            message: 'Validation failed',
+            errors,
+            status: 400,
+          },
+          { status: 400 }
+        ) as NextResponse<ErrorResponseBody>;
+      }
+
+      // Handle generic errors
+      const message = error instanceof Error ? error.message : 'Unknown error';
+
+      return NextResponse.json(
+        {
+          error: 'InternalServerError',
+          message,
+          status: 500,
+        },
+        { status: 500 }
+      ) as NextResponse<ErrorResponseBody>;
+    }
+  };
+}

package/src/middleware/with-validation.ts

@@ -0,0 +1,110 @@
+/**
+ * Validation middleware for Next.js API routes using Zod
+ */
+
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { z, type ZodSchema } from 'zod';
+
+export type ValidatedApiHandler<TBody = unknown, TQuery = unknown> = (
+  request: NextRequest,
+  validated: { body?: TBody; query?: TQuery }
+) => Promise<NextResponse> | NextResponse;
+
+export interface ValidationSchemas {
+  body?: ZodSchema;
+  query?: ZodSchema;
+}
+
+/**
+ * Validation middleware for Next.js API routes
+ */
+export function withValidation<TBody = unknown, TQuery = unknown>(
+  handler: ValidatedApiHandler<TBody, TQuery>,
+  schemas: ValidationSchemas
+): (request: NextRequest) => Promise<NextResponse> {
+  return async (request: NextRequest) => {
+    try {
+      const validated: { body?: TBody; query?: TQuery } = {};
+
+      // Validate body
+      if (schemas.body) {
+        const contentType = request.headers.get('content-type');
+        if (!contentType?.includes('application/json')) {
+          return NextResponse.json(
+            { error: 'ValidationError', message: 'Content-Type must be application/json' },
+            { status: 400 }
+          );
+        }
+
+        const body = await request.json();
+        validated.body = schemas.body.parse(body) as TBody;
+      }
+
+      // Validate query params
+      if (schemas.query) {
+        const { searchParams } = new URL(request.url);
+        const query: Record<string, unknown> = {};
+
+        searchParams.forEach((value, key) => {
+          // Handle array params (key repeated multiple times)
+          if (key in query) {
+            if (Array.isArray(query[key])) {
+              (query[key] as unknown[]).push(value);
+            } else {
+              query[key] = [query[key], value];
+            }
+          } else {
+            query[key] = value;
+          }
+        });
+
+        validated.query = schemas.query.parse(query) as TQuery;
+      }
+
+      // Call handler with validated data
+      return await handler(request, validated);
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        const errors: Record<string, string[]> = {};
+        error.issues.forEach((issue) => {
+          const field = issue.path.join('.');
+          if (!errors[field]) {
+            errors[field] = [];
+          }
+          errors[field].push(issue.message);
+        });
+
+        return NextResponse.json(
+          {
+            error: 'ValidationError',
+            message: 'Validation failed',
+            errors,
+          },
+          { status: 400 }
+        );
+      }
+
+      throw error;
+    }
+  };
+}
+
+/**
+ * Combine validation with other middleware
+ */
+export function composeMiddleware<TBody = unknown, TQuery = unknown>(
+  handler: ValidatedApiHandler<TBody, TQuery>,
+  ...middlewares: Array<
+    (handler: ValidatedApiHandler<TBody, TQuery>) => ValidatedApiHandler<TBody, TQuery>
+  >
+): (request: NextRequest) => Promise<NextResponse> {
+  const composed = middlewares.reduce(
+    (acc, middleware) => middleware(acc),
+    handler
+  );
+
+  return async (request: NextRequest) => {
+    return composed(request, {});
+  };
+}

package/src/types/api.ts

@@ -0,0 +1,38 @@
+/**
+ * Common API types for Django REST Framework
+ */
+
+export interface PaginatedResponse<T> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  results: T[];
+}
+
+export interface ApiError {
+  detail?: string;
+  message?: string;
+  errors?: Record<string, string[]>;
+  status?: number;
+  statusText?: string;
+}
+
+export interface PaginationParams {
+  page?: number;
+  pageSize?: number;
+}
+
+export interface SortParams {
+  ordering?: string; // e.g., '-createdAt', 'name'
+}
+
+export interface ApiRequestConfig {
+  headers?: HeadersInit;
+  signal?: AbortSignal;
+}
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export interface FetchOptions extends RequestInit {
+  params?: Record<string, unknown>;
+}

package/src/types/contact.ts

@@ -0,0 +1,49 @@
+/**
+ * Contact types matching Django Contact model
+ */
+
+import type { Entity, WritableAssertions } from './entity';
+
+export interface Contact extends Entity {
+  name: string;
+  email?: string | null;
+  phone?: string | null;
+  title?: string | null;
+  companyName?: string | null;
+  location?: string | null;
+  notes?: string | null;
+
+  // Computed fields from assertions
+  tier?: number | null;
+  status?: string | null;
+  linkedin?: string | null;
+  twitter?: string | null;
+  website?: string | null;
+  firmId?: string | null;
+  firmName?: string | null;
+  enrichmentScore?: number | null;
+}
+
+export interface CreateContactRequest extends WritableAssertions {
+  name: string;
+  email?: string;
+  phone?: string;
+  title?: string;
+  companyName?: string;
+  location?: string;
+  notes?: string;
+}
+
+export interface UpdateContactRequest extends Partial<CreateContactRequest> {}
+
+export interface ContactFilters {
+  [key: string]: unknown;
+  search?: string;
+  tier?: number;
+  status?: string;
+  firmId?: string;
+  tagCategory?: string;
+  tagName?: string;
+  hasEmail?: boolean;
+  hasLinkedin?: boolean;
+}

package/src/types/entity.ts

@@ -0,0 +1,153 @@
+/**
+ * Entity system types matching Django core models
+ */
+
+export type EntityType = 'contact' | 'organization';
+
+export interface Entity {
+  id: string; // external_id (UUID)
+  entityType: EntityType;
+  createdAt: string;
+  updatedAt: string;
+  tags?: EntityTag[];
+  metrics?: Metric[];
+  profiles?: Profile[];
+  attributes?: Attribute[];
+  relationshipsFrom?: Relationship[];
+  relationshipsTo?: Relationship[];
+  roleAssignments?: RoleAssignment[];
+  events?: Event[];
+}
+
+export interface Tag {
+  id: number;
+  category: string;
+  name: string;
+  description?: string;
+  fullPath: string;
+}
+
+export interface EntityTag {
+  id: number;
+  category: string;
+  name: string;
+  tagDescription?: string;
+  confidence: number;
+  appliedAt: string;
+  appliedBy?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Metric {
+  id: number;
+  type: string;
+  subtype: string;
+  value: number | string | null;
+  valueNumeric?: number | null;
+  valueText?: string | null;
+  unit?: string;
+  asOfDate?: string;
+  periodStart?: string;
+  confidence: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Profile {
+  id: number;
+  type: string;
+  subtype: string;
+  identifier: string;
+  identifierType: string;
+  displayName: string;
+  verified: boolean;
+  verifiedAt?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Attribute {
+  id: number;
+  type: string;
+  subtype: string;
+  value: string | Record<string, unknown> | null;
+  valueText?: string | null;
+  valueJson?: Record<string, unknown> | null;
+  valueType: 'text' | 'json';
+  validFrom?: string;
+  validTo?: string;
+  isCurrent: boolean;
+  confidence: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Relationship {
+  id: number;
+  fromEntityId: string;
+  toEntityId: string;
+  type: string;
+  subtype?: string;
+  validFrom?: string;
+  validTo?: string;
+  isCurrent: boolean;
+  durationDays?: number;
+  strength?: number;
+  confidence: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RoleAssignment {
+  id: number;
+  contactId: string;
+  orgId: string;
+  type: string;
+  subtype?: string;
+  title?: string;
+  seniority?: string;
+  validFrom?: string;
+  validTo?: string;
+  isCurrent: boolean;
+  durationDays?: number;
+  confidence: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Event {
+  id: number;
+  type: string;
+  subtype?: string;
+  occurredAt?: string;
+  announcedAt?: string;
+  magnitude?: number;
+  confidence: number;
+  metadata?: Record<string, unknown>;
+  participants?: EventParticipant[];
+}
+
+export interface EventParticipant {
+  id: number;
+  entityId: string;
+  roleType: string;
+  roleSubtype?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Source {
+  id: number;
+  type: string;
+  subtype?: string;
+  identifier: string;
+  retrievedAt: string;
+  format: string;
+  confidence: number;
+  cost?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Writable assertion formats for POST/PATCH
+ */
+export interface WritableAssertions {
+  writeTags?: Array<string | { category: string; name: string; confidence?: number }>;
+  writeMetrics?: Record<string, number | string>;
+  writeProfiles?: Record<string, string>;
+  writeAttributes?: Record<string, string | Record<string, unknown>>;
+}

package/src/types/error.ts

@@ -0,0 +1,129 @@
+/**
+ * Standardized API error response types
+ *
+ * Provides consistent error handling across frontend and backend
+ */
+
+import { z } from 'zod';
+
+/**
+ * Field-level validation error
+ */
+export interface FieldError {
+  field: string;
+  messages: string[];
+  code?: string;
+}
+
+/**
+ * Standardized API error response
+ */
+export interface StandardErrorResponse {
+  /** Main error message (user-friendly) */
+  error: string;
+
+  /** Error type/code for programmatic handling */
+  code: string;
+
+  /** HTTP status code */
+  statusCode: number;
+
+  /** Field-level validation errors */
+  fieldErrors?: FieldError[];
+
+  /** Additional error details */
+  details?: Record<string, unknown>;
+
+  /** Request ID for debugging */
+  requestId?: string;
+
+  /** Timestamp of error */
+  timestamp?: string;
+}
+
+/**
+ * Zod schema for runtime validation
+ */
+export const FieldErrorSchema = z.object({
+  field: z.string(),
+  messages: z.array(z.string()),
+  code: z.string().optional(),
+});
+
+export const StandardErrorResponseSchema = z.object({
+  error: z.string(),
+  code: z.string(),
+  statusCode: z.number().int().min(400).max(599),
+  fieldErrors: z.array(FieldErrorSchema).optional(),
+  details: z.record(z.unknown()).optional(),
+  requestId: z.string().optional(),
+  timestamp: z.string().datetime().optional(),
+});
+
+/**
+ * Common error codes
+ */
+export enum ErrorCode {
+  // Client errors (4xx)
+  BAD_REQUEST = 'bad_request',
+  UNAUTHORIZED = 'unauthorized',
+  FORBIDDEN = 'forbidden',
+  NOT_FOUND = 'not_found',
+  METHOD_NOT_ALLOWED = 'method_not_allowed',
+  VALIDATION_ERROR = 'validation_error',
+  CONFLICT = 'conflict',
+  RATE_LIMITED = 'rate_limited',
+
+  // Server errors (5xx)
+  INTERNAL_ERROR = 'internal_error',
+  SERVICE_UNAVAILABLE = 'service_unavailable',
+  GATEWAY_TIMEOUT = 'gateway_timeout',
+
+  // Network errors
+  NETWORK_ERROR = 'network_error',
+  TIMEOUT = 'timeout',
+
+  // Unknown
+  UNKNOWN = 'unknown',
+}
+
+/**
+ * Map HTTP status codes to error codes
+ */
+export function getErrorCodeFromStatus(status: number): ErrorCode {
+  const codeMap: Record<number, ErrorCode> = {
+    400: ErrorCode.BAD_REQUEST,
+    401: ErrorCode.UNAUTHORIZED,
+    403: ErrorCode.FORBIDDEN,
+    404: ErrorCode.NOT_FOUND,
+    405: ErrorCode.METHOD_NOT_ALLOWED,
+    409: ErrorCode.CONFLICT,
+    422: ErrorCode.VALIDATION_ERROR,
+    429: ErrorCode.RATE_LIMITED,
+    500: ErrorCode.INTERNAL_ERROR,
+    503: ErrorCode.SERVICE_UNAVAILABLE,
+    504: ErrorCode.GATEWAY_TIMEOUT,
+  };
+
+  return codeMap[status] || ErrorCode.UNKNOWN;
+}
+
+/**
+ * User-friendly error messages
+ */
+export const ErrorMessages: Record<ErrorCode, string> = {
+  [ErrorCode.BAD_REQUEST]: 'The request was invalid. Please check your input.',
+  [ErrorCode.UNAUTHORIZED]: 'You need to log in to access this resource.',
+  [ErrorCode.FORBIDDEN]: "You don't have permission to access this resource.",
+  [ErrorCode.NOT_FOUND]: 'The requested resource was not found.',
+  [ErrorCode.METHOD_NOT_ALLOWED]: 'This operation is not allowed.',
+  [ErrorCode.VALIDATION_ERROR]: 'Please fix the errors in your form.',
+  [ErrorCode.CONFLICT]: 'This operation conflicts with existing data.',
+  [ErrorCode.RATE_LIMITED]: 'Too many requests. Please slow down.',
+  [ErrorCode.INTERNAL_ERROR]: 'An unexpected error occurred. Please try again.',
+  [ErrorCode.SERVICE_UNAVAILABLE]: 'The service is temporarily unavailable.',
+  [ErrorCode.GATEWAY_TIMEOUT]: 'The request took too long. Please try again.',
+  [ErrorCode.NETWORK_ERROR]: 'Network error. Please check your connection.',
+  [ErrorCode.TIMEOUT]: 'The request timed out. Please try again.',
+  [ErrorCode.UNKNOWN]: 'An unknown error occurred.',
+};