@startsimpli/api 0.1.0

package/src/lib/entities-api.ts

@@ -0,0 +1,123 @@
+/**
+ * Core entities API wrapper for /api/v1/core/
+ */
+
+import type {
+  Tag,
+  EntityTag,
+  Metric,
+  Profile,
+  Attribute,
+  Relationship,
+  PaginatedResponse,
+  PaginationParams,
+} from '../types';
+import { mergeQueryParams } from '../utils';
+import { ENDPOINTS } from '../constants/endpoints';
+import type { ApiClient } from './api-client';
+
+export class EntitiesApi {
+  constructor(private client: ApiClient) {}
+
+  /**
+   * Tags
+   */
+  async listTags(pagination?: PaginationParams): Promise<PaginatedResponse<Tag>> {
+    const params = mergeQueryParams(pagination);
+    return this.client.fetch.get<PaginatedResponse<Tag>>(ENDPOINTS.TAGS, { params });
+  }
+
+  async getTag(id: number): Promise<Tag> {
+    return this.client.fetch.get<Tag>(ENDPOINTS.TAG(String(id)));
+  }
+
+  async createTag(data: Partial<Tag>): Promise<Tag> {
+    return this.client.fetch.post<Tag>(ENDPOINTS.TAGS, data);
+  }
+
+  /**
+   * Entity Tags
+   */
+  async listEntityTags(
+    pagination?: PaginationParams,
+    filters?: { entityId?: string; tagId?: number; category?: string }
+  ): Promise<PaginatedResponse<EntityTag>> {
+    const params = mergeQueryParams(pagination, undefined, filters);
+    return this.client.fetch.get<PaginatedResponse<EntityTag>>(ENDPOINTS.ENTITY_TAGS, {
+      params,
+    });
+  }
+
+  async getEntityTag(id: number): Promise<EntityTag> {
+    return this.client.fetch.get<EntityTag>(ENDPOINTS.ENTITY_TAG(String(id)));
+  }
+
+  /**
+   * Metrics
+   */
+  async listMetrics(
+    pagination?: PaginationParams,
+    filters?: { entityId?: string; type?: string; subtype?: string }
+  ): Promise<PaginatedResponse<Metric>> {
+    const params = mergeQueryParams(pagination, undefined, filters);
+    return this.client.fetch.get<PaginatedResponse<Metric>>(ENDPOINTS.METRICS, { params });
+  }
+
+  async getMetric(id: number): Promise<Metric> {
+    return this.client.fetch.get<Metric>(ENDPOINTS.METRIC(String(id)));
+  }
+
+  /**
+   * Profiles
+   */
+  async listProfiles(
+    pagination?: PaginationParams,
+    filters?: { entityId?: string; type?: string; subtype?: string }
+  ): Promise<PaginatedResponse<Profile>> {
+    const params = mergeQueryParams(pagination, undefined, filters);
+    return this.client.fetch.get<PaginatedResponse<Profile>>(ENDPOINTS.PROFILES, { params });
+  }
+
+  async getProfile(id: number): Promise<Profile> {
+    return this.client.fetch.get<Profile>(ENDPOINTS.PROFILE(String(id)));
+  }
+
+  /**
+   * Attributes
+   */
+  async listAttributes(
+    pagination?: PaginationParams,
+    filters?: { entityId?: string; type?: string; subtype?: string; isCurrent?: boolean }
+  ): Promise<PaginatedResponse<Attribute>> {
+    const params = mergeQueryParams(pagination, undefined, filters);
+    return this.client.fetch.get<PaginatedResponse<Attribute>>(ENDPOINTS.ATTRIBUTES, {
+      params,
+    });
+  }
+
+  async getAttribute(id: number): Promise<Attribute> {
+    return this.client.fetch.get<Attribute>(ENDPOINTS.ATTRIBUTE(String(id)));
+  }
+
+  /**
+   * Relationships
+   */
+  async listRelationships(
+    pagination?: PaginationParams,
+    filters?: {
+      fromEntityId?: string;
+      toEntityId?: string;
+      type?: string;
+      isCurrent?: boolean;
+    }
+  ): Promise<PaginatedResponse<Relationship>> {
+    const params = mergeQueryParams(pagination, undefined, filters);
+    return this.client.fetch.get<PaginatedResponse<Relationship>>(ENDPOINTS.RELATIONSHIPS, {
+      params,
+    });
+  }
+
+  async getRelationship(id: number): Promise<Relationship> {
+    return this.client.fetch.get<Relationship>(ENDPOINTS.RELATIONSHIP(String(id)));
+  }
+}

package/src/lib/env.ts

@@ -0,0 +1,35 @@
+/**
+ * Environment variable utilities for server-side use.
+ *
+ * These are generic helpers for accessing process.env safely.
+ * App-specific schema validation (via zod) lives in each app's src/lib/env.ts.
+ */
+
+/**
+ * Returns the value of an environment variable, throwing if it is missing or empty.
+ */
+export function getRequiredEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+  return value;
+}
+
+/**
+ * Returns the value of an environment variable, or a default if it is missing.
+ */
+export function getOptionalEnv(key: string, defaultValue?: string): string | undefined {
+  return process.env[key] ?? defaultValue;
+}
+
+/**
+ * Asserts that all listed environment variable keys are present and non-empty.
+ * Throws a single error listing every missing variable instead of failing on the first one.
+ */
+export function validateEnvVars(required: string[]): void {
+  const missing = required.filter((key) => !process.env[key]);
+  if (missing.length > 0) {
+    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+  }
+}

package/src/lib/error-handler.ts

@@ -0,0 +1,138 @@
+/**
+ * API error handling and normalization
+ */
+
+import type { DRFApiError } from '../types';
+
+export class ApiException extends Error {
+  public status?: number;
+  public statusText?: string;
+  public errors?: Record<string, string[]>;
+  public detail?: string;
+
+  constructor(message: string, options?: Partial<DRFApiError>) {
+    super(message);
+    this.name = 'ApiException';
+    this.status = options?.status;
+    this.statusText = options?.statusText;
+    this.errors = options?.errors;
+    this.detail = options?.detail;
+  }
+
+  toJSON(): DRFApiError {
+    return {
+      message: this.message,
+      detail: this.detail,
+      status: this.status,
+      statusText: this.statusText,
+      errors: this.errors,
+    };
+  }
+}
+
+/**
+ * Parse Django REST Framework error response
+ */
+export async function parseErrorResponse(response: Response): Promise<DRFApiError> {
+  const contentType = response.headers.get('content-type');
+
+  // Try to parse JSON error
+  if (contentType?.includes('application/json')) {
+    try {
+      const data = await response.json();
+
+      // Django REST Framework error format
+      if (data.detail) {
+        return {
+          detail: data.detail,
+          message: data.detail,
+          status: response.status,
+          statusText: response.statusText,
+        };
+      }
+
+      // Validation errors format
+      if (typeof data === 'object') {
+        return {
+          errors: data,
+          message: 'Validation error',
+          status: response.status,
+          statusText: response.statusText,
+        };
+      }
+
+      return {
+        message: JSON.stringify(data),
+        status: response.status,
+        statusText: response.statusText,
+      };
+    } catch {
+      // JSON parse failed, fall through to text handling
+    }
+  }
+
+  // Fallback to text error
+  const text = await response.text().catch(() => response.statusText);
+
+  return {
+    message: text || response.statusText || 'Unknown error',
+    status: response.status,
+    statusText: response.statusText,
+  };
+}
+
+/**
+ * Handle fetch errors
+ */
+export function handleFetchError(error: unknown): never {
+  if (error instanceof ApiException) {
+    throw error;
+  }
+
+  if (error instanceof TypeError && error.message.includes('fetch')) {
+    throw new ApiException('Network error - please check your connection', {
+      status: 0,
+      statusText: 'Network Error',
+    });
+  }
+
+  if (error instanceof Error) {
+    throw new ApiException(error.message, {
+      status: 0,
+      statusText: 'Client Error',
+    });
+  }
+
+  throw new ApiException('Unknown error occurred', {
+    status: 0,
+    statusText: 'Unknown Error',
+  });
+}
+
+/**
+ * Check if error is an API exception
+ */
+export function isApiException(error: unknown): error is ApiException {
+  return error instanceof ApiException;
+}
+
+/**
+ * Check if error is a validation error
+ */
+export function isValidationError(error: unknown): error is ApiException {
+  return isApiException(error) && error.status === 400 && !!error.errors;
+}
+
+/**
+ * Check if error is an auth error
+ */
+export function isAuthError(error: unknown): error is ApiException {
+  return isApiException(error) && (error.status === 401 || error.status === 403);
+}
+
+/**
+ * Check if error is a not found error
+ */
+export function isNotFoundError(error: unknown): error is ApiException {
+  return isApiException(error) && error.status === 404;
+}

package/src/lib/errors.ts

@@ -0,0 +1,381 @@
+/**
+ * AppError hierarchy for StartSimpli apps
+ *
+ * Provides a standardized error hierarchy with:
+ * - Consistent error codes and messages
+ * - HTTP status code mapping
+ * - Serialization for API responses
+ *
+ * These are server-side application errors (not API client fetch errors).
+ * For API client errors see ./error-handler.ts (ApiException).
+ */
+
+/**
+ * Standard error codes used across the application
+ */
+export enum AppErrorCode {
+  // Client errors (4xx)
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  AUTHENTICATION_REQUIRED = 'AUTHENTICATION_REQUIRED',
+  INVALID_CREDENTIALS = 'INVALID_CREDENTIALS',
+  SESSION_EXPIRED = 'SESSION_EXPIRED',
+  FORBIDDEN = 'FORBIDDEN',
+  INSUFFICIENT_PERMISSIONS = 'INSUFFICIENT_PERMISSIONS',
+  NOT_FOUND = 'NOT_FOUND',
+  RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
+  CONFLICT = 'CONFLICT',
+  DUPLICATE_RESOURCE = 'DUPLICATE_RESOURCE',
+  RATE_LIMITED = 'RATE_LIMITED',
+  BAD_REQUEST = 'BAD_REQUEST',
+
+  // Server errors (5xx)
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  DATABASE_ERROR = 'DATABASE_ERROR',
+  EXTERNAL_SERVICE_ERROR = 'EXTERNAL_SERVICE_ERROR',
+  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+}
+
+/**
+ * Shape of the error envelope returned from AppError.toResponse()
+ */
+export interface AppErrorResponse {
+  error: {
+    code: AppErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Base application error class.
+ * All custom errors should extend this class.
+ */
+export class AppError extends Error {
+  public readonly code: AppErrorCode;
+  public readonly statusCode: number;
+  public readonly details?: Record<string, unknown>;
+  public readonly isOperational: boolean;
+
+  constructor(
+    message: string,
+    code: AppErrorCode = AppErrorCode.INTERNAL_ERROR,
+    statusCode: number = 500,
+    details?: Record<string, unknown>,
+    isOperational: boolean = true
+  ) {
+    super(message);
+    this.name = 'AppError';
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.isOperational = isOperational;
+
+    // Maintains proper stack trace for where our error was thrown
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  /**
+   * Serialize error for API response
+   */
+  toResponse(): AppErrorResponse {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.details && { details: this.details }),
+      },
+    };
+  }
+
+  /**
+   * Check if an error is an operational error (expected) vs programming error
+   */
+  static isOperationalError(error: unknown): error is AppError {
+    return error instanceof AppError && error.isOperational;
+  }
+}
+
+/**
+ * Validation error for invalid request data
+ * HTTP 400 Bad Request
+ */
+export class ValidationError extends AppError {
+  public readonly fieldErrors: Record<string, string[]>;
+
+  constructor(
+    message: string = 'Validation failed',
+    fieldErrors: Record<string, string[]> = {}
+  ) {
+    super(
+      message,
+      AppErrorCode.VALIDATION_ERROR,
+      400,
+      { fields: fieldErrors }
+    );
+    this.name = 'ValidationError';
+    this.fieldErrors = fieldErrors;
+  }
+
+  /**
+   * Create from Zod error
+   */
+  static fromZodError(zodError: { errors: Array<{ path: (string | number)[]; message: string }> }): ValidationError {
+    const fieldErrors: Record<string, string[]> = {};
+
+    for (const error of zodError.errors) {
+      const path = error.path.join('.');
+      if (!fieldErrors[path]) {
+        fieldErrors[path] = [];
+      }
+      fieldErrors[path].push(error.message);
+    }
+
+    const message = Object.entries(fieldErrors)
+      .map(([field, errors]) => `${field}: ${errors.join(', ')}`)
+      .join('; ');
+
+    return new ValidationError(`Validation failed: ${message}`, fieldErrors);
+  }
+}
+
+/**
+ * Authentication error for unauthenticated requests
+ * HTTP 401 Unauthorized
+ */
+export class AuthenticationError extends AppError {
+  constructor(
+    message: string = 'Authentication required',
+    code: AppErrorCode = AppErrorCode.AUTHENTICATION_REQUIRED
+  ) {
+    super(message, code, 401);
+    this.name = 'AuthenticationError';
+  }
+
+  /**
+   * Create for invalid credentials
+   */
+  static invalidCredentials(): AuthenticationError {
+    return new AuthenticationError('Invalid credentials', AppErrorCode.INVALID_CREDENTIALS);
+  }
+
+  /**
+   * Create for expired session
+   */
+  static sessionExpired(): AuthenticationError {
+    return new AuthenticationError('Session has expired', AppErrorCode.SESSION_EXPIRED);
+  }
+}
+
+/**
+ * Authorization error for forbidden access
+ * HTTP 403 Forbidden
+ */
+export class AuthorizationError extends AppError {
+  constructor(
+    message: string = 'Access denied',
+    code: AppErrorCode = AppErrorCode.FORBIDDEN
+  ) {
+    super(message, code, 403);
+    this.name = 'AuthorizationError';
+  }
+
+  /**
+   * Create for insufficient permissions
+   */
+  static insufficientPermissions(requiredPermission?: string): AuthorizationError {
+    const message = requiredPermission
+      ? `Insufficient permissions. Required: ${requiredPermission}`
+      : 'Insufficient permissions';
+    return new AuthorizationError(message, AppErrorCode.INSUFFICIENT_PERMISSIONS);
+  }
+}
+
+/**
+ * Not found error for missing resources
+ * HTTP 404 Not Found
+ */
+export class NotFoundError extends AppError {
+  public readonly resourceType?: string;
+  public readonly resourceId?: string;
+
+  constructor(
+    message: string = 'Resource not found',
+    resourceType?: string,
+    resourceId?: string
+  ) {
+    super(
+      message,
+      AppErrorCode.NOT_FOUND,
+      404,
+      resourceType || resourceId
+        ? { resourceType, resourceId }
+        : undefined
+    );
+    this.name = 'NotFoundError';
+    this.resourceType = resourceType;
+    this.resourceId = resourceId;
+  }
+
+  /**
+   * Create for a specific resource
+   */
+  static forResource(resourceType: string, resourceId?: string): NotFoundError {
+    const message = resourceId
+      ? `${resourceType} with ID '${resourceId}' not found`
+      : `${resourceType} not found`;
+    return new NotFoundError(message, resourceType, resourceId);
+  }
+}
+
+/**
+ * Conflict error for duplicate or conflicting resources
+ * HTTP 409 Conflict
+ */
+export class ConflictError extends AppError {
+  public readonly conflictingField?: string;
+
+  constructor(
+    message: string = 'Resource conflict',
+    conflictingField?: string
+  ) {
+    super(
+      message,
+      AppErrorCode.CONFLICT,
+      409,
+      conflictingField ? { field: conflictingField } : undefined
+    );
+    this.name = 'ConflictError';
+    this.conflictingField = conflictingField;
+  }
+
+  /**
+   * Create for duplicate resource
+   */
+  static duplicate(resourceType: string, field?: string): ConflictError {
+    const message = field
+      ? `A ${resourceType} with this ${field} already exists`
+      : `A ${resourceType} with these values already exists`;
+    return new ConflictError(message, field);
+  }
+}
+
+/**
+ * Rate limit error for too many requests
+ * HTTP 429 Too Many Requests
+ */
+export class RateLimitError extends AppError {
+  public readonly retryAfter?: number;
+
+  constructor(
+    message: string = 'Too many requests',
+    retryAfter?: number
+  ) {
+    super(
+      message,
+      AppErrorCode.RATE_LIMITED,
+      429,
+      retryAfter ? { retryAfter } : undefined
+    );
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+/**
+ * Database error for database-related failures
+ * HTTP 500 Internal Server Error
+ */
+export class DatabaseError extends AppError {
+  constructor(
+    message: string = 'Database operation failed',
+    details?: Record<string, unknown>
+  ) {
+    // Don't expose internal database details in production
+    const safeDetails = process.env.NODE_ENV === 'development' ? details : undefined;
+    super(message, AppErrorCode.DATABASE_ERROR, 500, safeDetails);
+    this.name = 'DatabaseError';
+  }
+
+  /**
+   * Create from Prisma error
+   */
+  static fromPrismaError(error: { code?: string; meta?: Record<string, unknown> }): DatabaseError {
+    const code = error.code;
+
+    // Map common Prisma error codes to user-friendly messages
+    switch (code) {
+      case 'P2002':
+        throw ConflictError.duplicate('record', (error.meta?.target as string[])?.[0]);
+      case 'P2025':
+        throw new NotFoundError('Record not found');
+      case 'P2003':
+        throw new ConflictError('Cannot perform operation due to related records');
+      default:
+        return new DatabaseError('Database operation failed', { code });
+    }
+  }
+}
+
+/**
+ * External service error for third-party API failures
+ * HTTP 502 Bad Gateway
+ */
+export class ExternalServiceError extends AppError {
+  public readonly serviceName: string;
+
+  constructor(
+    serviceName: string,
+    message: string = 'External service error',
+    details?: Record<string, unknown>
+  ) {
+    super(
+      message,
+      AppErrorCode.EXTERNAL_SERVICE_ERROR,
+      502,
+      { service: serviceName, ...details }
+    );
+    this.name = 'ExternalServiceError';
+    this.serviceName = serviceName;
+  }
+}
+
+/**
+ * Type guard to check if an error has a code property (like Prisma errors)
+ */
+export function isPrismaError(error: unknown): error is { code: string; meta?: Record<string, unknown> } {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    typeof (error as { code: unknown }).code === 'string'
+  );
+}
+
+/**
+ * Convert any error to an AppError.
+ * Useful for catch blocks to ensure consistent error handling.
+ */
+export function toAppError(error: unknown): AppError {
+  if (error instanceof AppError) {
+    return error;
+  }
+
+  if (isPrismaError(error)) {
+    return DatabaseError.fromPrismaError(error);
+  }
+
+  if (error instanceof Error) {
+    return new AppError(
+      error.message,
+      AppErrorCode.INTERNAL_ERROR,
+      500,
+      process.env.NODE_ENV === 'development' ? { stack: error.stack } : undefined
+    );
+  }
+
+  return new AppError(
+    'An unexpected error occurred',
+    AppErrorCode.INTERNAL_ERROR,
+    500
+  );
+}