@voltom/contracts 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,464 @@
+import { z } from 'zod';
+
+/**
+ * Universal primitive type builders for voltom contracts.
+ * Every field in every contract is built using these.
+ * They wrap Zod schemas with cleaner names and consistent validation.
+ *
+ * All validators are designed for production use:
+ * - Security (no injection vectors)
+ * - Performance (fast validation)
+ * - Clarity (error messages are useful)
+ */
+declare const t: {
+    /** UUID string (v4 or v5) */
+    readonly uuid: () => z.ZodString;
+    /** String with optional min/max length and pattern constraints */
+    readonly string: (opts?: {
+        min?: number;
+        max?: number;
+        pattern?: RegExp | string;
+        description?: string;
+    }) => z.ZodString;
+    /** Email address (RFC 5322 compliant) */
+    readonly email: () => z.ZodString;
+    /** Phone number (international format: +[country code][number], or 7+ digits) */
+    readonly phone: () => z.ZodString;
+    /** URL (HTTP, HTTPS, or custom protocol) */
+    readonly url: () => z.ZodString;
+    /** URL slug (lowercase alphanumeric, hyphens, underscores) */
+    readonly slug: (opts?: {
+        min?: number;
+        max?: number;
+    }) => z.ZodString;
+    /** Strong password (min 8 chars, mixed case, number, special char) */
+    readonly password: () => z.ZodString;
+    /** IPv4 or IPv6 address */
+    readonly ipAddress: () => z.ZodUnion<[z.ZodString, z.ZodString]>;
+    /** Hexadecimal string (colors, hashes) */
+    readonly hex: (opts?: {
+        length?: number;
+    }) => z.ZodString;
+    /** Alphanumeric identifier (no special chars) */
+    readonly id: () => z.ZodString;
+    /** Country code (ISO 3166-1 alpha-2) */
+    readonly countryCode: () => z.ZodString;
+    /** Currency code (ISO 4217) */
+    readonly currencyCode: () => z.ZodString;
+    /** Number with optional min/max bounds */
+    readonly number: (opts?: {
+        min?: number;
+        max?: number;
+        multipleOf?: number;
+    }) => z.ZodNumber;
+    /** Integer with optional min/max bounds */
+    readonly int: (opts?: {
+        min?: number;
+        max?: number;
+        positive?: boolean;
+        negative?: boolean;
+    }) => z.ZodNumber;
+    /** Percentage (0-100) */
+    readonly percent: () => z.ZodNumber;
+    /** Boolean */
+    readonly boolean: () => z.ZodBoolean;
+    /** ISO 8601 datetime (e.g., "2024-01-15T10:30:00Z") */
+    readonly datetime: () => z.ZodString;
+    /** ISO 8601 date (e.g., "2024-01-15") */
+    readonly date: () => z.ZodString;
+    /** ISO 8601 time (e.g., "14:30:00") */
+    readonly time: () => z.ZodString;
+    /** Unix timestamp (seconds since epoch) */
+    readonly timestamp: () => z.ZodNumber;
+    /** Enum with fixed string values */
+    readonly enum: <T extends readonly [string, ...string[]]>(values: T) => z.ZodEnum<z.Writeable<T>>;
+    /** Arbitrary JSON value (object, array, primitive) */
+    readonly json: () => z.ZodAny;
+    /** Make a schema optional (allows undefined) */
+    readonly optional: <S extends z.ZodTypeAny>(schema: S) => z.ZodOptional<S>;
+    /** Make a schema nullable (allows null) */
+    readonly nullable: <S extends z.ZodTypeAny>(schema: S) => z.ZodNullable<S>;
+    /** Array of a schema with optional length constraints */
+    readonly array: <S extends z.ZodTypeAny>(schema: S, opts?: {
+        min?: number;
+        max?: number;
+        nonempty?: boolean;
+    }) => any;
+};
+
+/**
+ * Canonical error codes for voltom APIs.
+ * These are the ONLY error codes that should be used across all products.
+ * Maps to HTTP status codes via ERROR_STATUS_MAP.
+ *
+ * Do NOT add product-specific codes. Keep these universal.
+ * If you need product logic, handle it in the backend with additional data.
+ */
+type ErrorCode = 'VALIDATION_ERROR' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'UNPROCESSABLE' | 'RATE_LIMITED' | 'INTERNAL_ERROR';
+/**
+ * Map each ErrorCode to its HTTP status code.
+ * Use this in backend exception filters and middleware.
+ */
+declare const ERROR_STATUS_MAP: Record<ErrorCode, number>;
+/**
+ * Default error messages for each code.
+ * Use these as fallback or customize with domain-specific context.
+ */
+declare const ERROR_MESSAGES: Record<ErrorCode, string>;
+
+/**
+ * Pagination metadata included in PaginatedResponse.
+ */
+interface PaginationMeta {
+    /** Total number of items across all pages */
+    total: number;
+    /** Current page number (1-indexed) */
+    page: number;
+    /** Items per page */
+    per_page: number;
+    /** Whether more pages exist after this one */
+    has_more: boolean;
+}
+/**
+ * Cursor-based pagination (for very large datasets).
+ * Use when total count is unknown or for streaming data.
+ */
+interface CursorPaginationMeta {
+    /** Cursor to fetch next page (null if no more pages) */
+    next_cursor: string | null;
+    /** Whether more pages exist */
+    has_more: boolean;
+    /** Items returned on this page (for client-side counting) */
+    count: number;
+}
+/**
+ * Validation error details for a specific field.
+ */
+interface FieldError {
+    /** Field name (dot-notation for nested: "user.email") */
+    field: string;
+    /** Error code/type (e.g., "required", "min_length", "invalid_format") */
+    code: string;
+    /** Human-readable message */
+    message: string;
+}
+/**
+ * Response for a single item fetch (GET /:id, POST, PATCH, PUT).
+ * The only valid envelope for single-item responses.
+ */
+interface SingleResponse<T> {
+    /** The item */
+    data: T;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Optional: unique request identifier for tracing */
+    request_id?: string;
+}
+/**
+ * Response for a paginated list (GET with pagination).
+ * The only valid envelope for list responses.
+ */
+interface PaginatedResponse<T> {
+    /** Array of items */
+    data: T[];
+    /** Pagination metadata */
+    meta: PaginationMeta;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Optional: unique request identifier for tracing */
+    request_id?: string;
+}
+/**
+ * Response for cursor-based pagination (streaming, infinite scroll).
+ * Use for large datasets where total count is unavailable or expensive.
+ */
+interface CursorPaginatedResponse<T> {
+    /** Array of items */
+    data: T[];
+    /** Cursor pagination metadata */
+    meta: CursorPaginationMeta;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Optional: unique request identifier for tracing */
+    request_id?: string;
+}
+/**
+ * Response for a resource deletion (DELETE /:id).
+ * The only valid envelope for delete responses.
+ */
+interface DeletedResponse {
+    /** Always true, confirms deletion */
+    deleted: true;
+    /** ID of the deleted resource */
+    id: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Optional: unique request identifier for tracing */
+    request_id?: string;
+}
+/**
+ * Response for bulk/batch operations (POST /batch, DELETE /batch).
+ * Allows partial success with per-item error tracking.
+ */
+interface BulkResponse<T> {
+    /** Successfully created/updated items */
+    data: T[];
+    /** Items that failed with per-item error details */
+    errors: Array<{
+        /** Original request index or item ID */
+        key: string | number;
+        /** The error */
+        error: {
+            code: ErrorCode;
+            message: string;
+            details?: unknown;
+        };
+    }>;
+    /** Summary statistics */
+    meta: {
+        /** Total items processed */
+        total: number;
+        /** Successfully processed */
+        succeeded: number;
+        /** Failed items */
+        failed: number;
+    };
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Optional: unique request identifier for tracing */
+    request_id?: string;
+}
+/**
+ * Error response (any HTTP error status).
+ * The only valid envelope for errors.
+ */
+interface ApiError {
+    error: {
+        /** Canonical error code from @voltom/contracts */
+        code: ErrorCode;
+        /** Human-readable error message (safe for client display) */
+        message: string;
+        /** Optional: field name if error maps to a specific field */
+        field?: string;
+        /** Optional: validation details (only for VALIDATION_ERROR) */
+        validation_errors?: FieldError[];
+        /** Optional: safe, non-sensitive extra context */
+        details?: unknown;
+        /** Optional: hint for client-side retry/recovery */
+        hint?: string;
+    };
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Optional: unique request identifier for tracing */
+    request_id?: string;
+}
+
+/**
+ * Defines a single API endpoint within a contract.
+ */
+interface EndpointDef {
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** URL path (e.g., "/" or "/:id") */
+    path: string;
+    /** Response shape type */
+    response?: 'single' | 'paginated' | 'deleted' | 'file';
+    /** Key into bodies map for request body */
+    body?: string;
+    /** Query parameters (Zod schema) */
+    query?: Record<string, z.ZodTypeAny>;
+    /** Possible error codes */
+    errors?: ErrorCode[];
+}
+/**
+ * Defines an action — a special endpoint that requires a body.
+ * Actions are like custom endpoints that extend the standard CRUD.
+ * Body is required and can be either a string (reference to bodies map) or inline Zod schema.
+ */
+type ActionDef = Omit<EndpointDef, 'body'> & {
+    body: Record<string, z.ZodTypeAny> | string;
+};
+/**
+ * Complete contract definition for a resource.
+ * This is the source of truth for a resource's API shape.
+ */
+interface ContractConfig {
+    /** Resource name (e.g., "users", "teams") */
+    resource: string;
+    /** Base API path (e.g., "/api/v1/users") */
+    basePath: string;
+    /** The main entity shape (Zod schema fields) */
+    entity: Record<string, z.ZodTypeAny>;
+    /** CRUD and standard endpoints */
+    endpoints?: Record<string, EndpointDef>;
+    /** Request body definitions */
+    bodies?: Record<string, Record<string, z.ZodTypeAny>>;
+    /** Query filter definitions */
+    filters?: Record<string, z.ZodTypeAny>;
+    /** Custom action endpoints */
+    actions?: Record<string, ActionDef>;
+    /** Permission hints for access control */
+    permissions?: Record<string, string>;
+}
+/**
+ * The Contract type after defineContract() validation.
+ * In practice, this is identical to ContractConfig, but the function
+ * ensures type correctness and enables inference.
+ */
+type Contract = ContractConfig;
+
+/**
+ * Define a contract for a resource in your product.
+ *
+ * This function validates the contract shape and returns it for use throughout
+ * your product (backend, frontend, codegen). The real power is in TypeScript's
+ * type inference — once you call defineContract(), every property is typed
+ * and all downstream consumers know exactly what to expect.
+ *
+ * @param config The contract configuration
+ * @returns The same contract config (validated)
+ *
+ * @example
+ * ```typescript
+ * const usersContract = defineContract({
+ *   resource: 'users',
+ *   basePath: '/api/v1/users',
+ *   entity: {
+ *     id: t.uuid(),
+ *     email: t.email(),
+ *     name: t.string({ min: 1, max: 255 }),
+ *   },
+ *   endpoints: {
+ *     list: { method: 'GET', path: '/', response: 'paginated' },
+ *     show: { method: 'GET', path: '/:id', response: 'single' },
+ *     create: { method: 'POST', path: '/', body: 'CreateUser' },
+ *   },
+ *   bodies: {
+ *     CreateUser: {
+ *       email: t.email(),
+ *       name: t.string({ min: 1, max: 255 }),
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function defineContract<T extends ContractConfig>(config: T): T & Contract;
+
+/**
+ * Standard fields that most entities should have.
+ * Use these to ensure consistency across products.
+ */
+/**
+ * Audit trail fields (who, when)
+ * Include on entities that track ownership or modification history.
+ */
+declare const auditFields: {
+    readonly created_at: z.ZodString;
+    readonly created_by: z.ZodString;
+    readonly updated_at: z.ZodString;
+    readonly updated_by: z.ZodString;
+};
+/**
+ * Soft delete fields (mark as deleted without removing data)
+ * Use when you need to preserve data for compliance or recovery.
+ */
+declare const softDeleteFields: {
+    readonly is_active: z.ZodBoolean;
+    readonly deleted_at: z.ZodNullable<z.ZodString>;
+    readonly deleted_by: z.ZodNullable<z.ZodString>;
+};
+/**
+ * Timestamp fields only (no user tracking)
+ * Minimum audit trail for systems that don't track users.
+ */
+declare const timestampFields: {
+    readonly created_at: z.ZodString;
+    readonly updated_at: z.ZodString;
+};
+/**
+ * Standard metadata for multi-tenant systems
+ * Use when entities belong to organizations or accounts.
+ */
+declare const tenantFields: {
+    readonly tenant_id: z.ZodString;
+    readonly organization_id: z.ZodString;
+};
+/**
+ * Status enum commonly used across products
+ * Extend in product-specific contracts if needed.
+ */
+declare const StandardStatus: {
+    readonly DRAFT: "draft";
+    readonly ACTIVE: "active";
+    readonly INACTIVE: "inactive";
+    readonly ARCHIVED: "archived";
+    readonly DELETED: "deleted";
+};
+type StandardStatus = (typeof StandardStatus)[keyof typeof StandardStatus];
+/**
+ * Sort direction for list queries
+ */
+type SortDirection = 'asc' | 'desc';
+/**
+ * Standard query filters for list endpoints
+ * Use when your contract needs search/filter capabilities.
+ */
+declare const listQueryFilters: {
+    readonly search: z.ZodOptional<z.ZodString>;
+    readonly status: z.ZodOptional<z.ZodString>;
+    readonly sort_by: z.ZodOptional<z.ZodString>;
+    readonly sort_direction: z.ZodOptional<z.ZodEnum<["asc", "desc"]>>;
+    readonly limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    readonly offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+};
+/**
+ * Standard pagination query parameters
+ */
+declare const paginationQuery: {
+    readonly page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    readonly per_page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+};
+/**
+ * Create a consistent 'create' body type from an entity
+ *
+ * @example
+ * ```typescript
+ * const userEntity = { id: t.uuid(), email: t.email(), name: t.string() }
+ * type CreateUserBody = OmitFields<typeof userEntity, 'id'> // email, name
+ * ```
+ *
+ * Note: In your contract, you can also just define bodies explicitly:
+ * bodies: { CreateUser: { email: t.email(), name: t.string() } }
+ */
+/**
+ * Create a consistent 'update' body type from an entity
+ * (all fields optional except id)
+ */
+declare const makeUpdateFields: <T extends Record<string, z.ZodTypeAny>>(entity: T, excludeFields?: (keyof T)[]) => Record<string, z.ZodTypeAny>;
+/**
+ * Standard HTTP header hints for backend/frontend coordination
+ * Not part of contract, but useful metadata for documentation
+ */
+declare const ResponseHeaders: {
+    /** Cache-Control header value */
+    readonly CACHE: {
+        readonly NO_CACHE: "no-cache, no-store, must-revalidate";
+        readonly SHORT: "public, max-age=300";
+        readonly MEDIUM: "public, max-age=3600";
+        readonly LONG: "public, max-age=86400";
+        readonly NEVER: "no-store";
+    };
+};
+/**
+ * Security hints for contract fields
+ * Mark sensitive fields so frontend/backend handle them carefully
+ */
+declare const FieldSensitivity: {
+    readonly PUBLIC: "public";
+    readonly INTERNAL: "internal";
+    readonly CONFIDENTIAL: "confidential";
+    readonly SECRET: "secret";
+};
+type FieldSensitivity = (typeof FieldSensitivity)[keyof typeof FieldSensitivity];
+
+export { type ActionDef, type ApiError, type BulkResponse, type Contract, type ContractConfig, type CursorPaginatedResponse, type CursorPaginationMeta, type DeletedResponse, ERROR_MESSAGES, ERROR_STATUS_MAP, type EndpointDef, type ErrorCode, type FieldError, FieldSensitivity, type PaginatedResponse, type PaginationMeta, ResponseHeaders, type SingleResponse, type SortDirection, StandardStatus, auditFields, defineContract, listQueryFilters, makeUpdateFields, paginationQuery, softDeleteFields, t, tenantFields, timestampFields };