@objectql/types 1.8.1 → 1.8.2

package/dist/api.d.ts

@@ -0,0 +1,427 @@
+/**
+ * API Type Definitions for ObjectQL
+ *
+ * This file contains TypeScript interfaces for Data API and Metadata API endpoints.
+ * These types enable frontend applications to make type-safe API calls.
+ */
+import { UnifiedQuery, FilterExpression } from './query';
+import { ObjectConfig } from './object';
+import { FieldConfig } from './field';
+import { ActionConfig } from './action';
+/**
+ * Standardized error codes for ObjectQL API responses
+ */
+export declare enum ApiErrorCode {
+    INVALID_REQUEST = "INVALID_REQUEST",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    FORBIDDEN = "FORBIDDEN",
+    NOT_FOUND = "NOT_FOUND",
+    CONFLICT = "CONFLICT",
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    DATABASE_ERROR = "DATABASE_ERROR",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+}
+/**
+ * Error details structure with optional field-specific information
+ */
+export interface ApiErrorDetails {
+    field?: string;
+    reason?: string;
+    fields?: Record<string, string>;
+    required_permission?: string;
+    user_roles?: string[];
+    retry_after?: number;
+    [key: string]: unknown;
+}
+/**
+ * Standard error response structure
+ */
+export interface ApiError {
+    code: ApiErrorCode | string;
+    message: string;
+    details?: ApiErrorDetails;
+}
+/**
+ * ObjectQL Error class for throwing structured errors
+ */
+export declare class ObjectQLError extends Error {
+    code: ApiErrorCode | string;
+    details?: ApiErrorDetails;
+    constructor(error: {
+        code: ApiErrorCode | string;
+        message: string;
+        details?: ApiErrorDetails;
+    });
+}
+/**
+ * Pagination metadata for list responses
+ */
+export interface PaginationMeta {
+    /** Total number of records */
+    total: number;
+    /** Current page number (1-indexed) */
+    page?: number;
+    /** Number of items per page */
+    size?: number;
+    /** Total number of pages */
+    pages?: number;
+    /** Whether there is a next page */
+    has_next?: boolean;
+}
+/**
+ * Base response structure for Data API operations
+ */
+export interface DataApiResponse<T = unknown> {
+    /** Error information if the operation failed */
+    error?: ApiError;
+    /** Additional response fields for successful operations */
+    [key: string]: unknown;
+}
+/**
+ * Response for list operations (find)
+ */
+export interface DataApiListResponse<T = unknown> extends DataApiResponse<T> {
+    /** Array of retrieved items */
+    items?: T[];
+    /** Pagination metadata */
+    meta?: PaginationMeta;
+}
+/**
+ * Response for single item operations (findOne, create, update)
+ */
+export interface DataApiItemResponse<T = unknown> extends DataApiResponse<T> {
+    /** The item ID */
+    _id?: string | number;
+    /** Object type identifier */
+    '@type'?: string;
+    /** Timestamp when created */
+    created_at?: string | Date;
+    /** Timestamp when last updated */
+    updated_at?: string | Date;
+}
+/**
+ * Query parameters for GET /api/data/:object (list records)
+ */
+export interface DataApiListParams {
+    /** Filter expression (can be FilterExpression array or JSON string) */
+    filter?: FilterExpression | string;
+    /** Fields to return (array or comma-separated string) */
+    fields?: string[] | string;
+    /** Sort criteria - array of [field, direction] tuples */
+    sort?: [string, 'asc' | 'desc'][] | string;
+    /** Maximum number of records to return */
+    limit?: number;
+    /** Number of records to skip (for pagination) */
+    skip?: number;
+    /** Offset alias for skip */
+    offset?: number;
+    /** OData-style top parameter (alias for limit) */
+    top?: number;
+    /** Expand related records */
+    expand?: Record<string, UnifiedQuery>;
+}
+/**
+ * Request body for POST /api/data/:object (create single record)
+ */
+export interface DataApiCreateRequest {
+    [key: string]: unknown;
+}
+/**
+ * Request body for POST /api/data/:object (create multiple records)
+ */
+export type DataApiCreateManyRequest = Array<Record<string, unknown>>;
+/**
+ * Request body for PUT /api/data/:object/:id (update record)
+ */
+export interface DataApiUpdateRequest {
+    [key: string]: unknown;
+}
+/**
+ * Request body for POST /api/data/:object/bulk-update (update many records)
+ */
+export interface DataApiBulkUpdateRequest {
+    /** Filter criteria to select records to update */
+    filters: FilterExpression;
+    /** Data to update */
+    data: Record<string, unknown>;
+}
+/**
+ * Request body for POST /api/data/:object/bulk-delete (delete many records)
+ */
+export interface DataApiBulkDeleteRequest {
+    /** Filter criteria to select records to delete */
+    filters: FilterExpression;
+}
+/**
+ * Response for count operations
+ */
+export interface DataApiCountResponse extends DataApiResponse {
+    /** Number of records matching the criteria */
+    count?: number;
+}
+/**
+ * Response for delete operations
+ */
+export interface DataApiDeleteResponse extends DataApiResponse {
+    /** Whether the operation was successful */
+    success?: boolean;
+    /** Number of deleted records (for bulk operations) */
+    deleted_count?: number;
+}
+/**
+ * Base response structure for Metadata API operations
+ */
+export interface MetadataApiResponse<T = unknown> {
+    /** Error information if the operation failed */
+    error?: ApiError;
+    /** Additional response fields */
+    [key: string]: unknown;
+}
+/**
+ * Response for list metadata operations
+ */
+export interface MetadataApiListResponse<T = unknown> extends MetadataApiResponse<T> {
+    /** Array of metadata items */
+    items: T[];
+}
+/**
+ * Simplified object metadata for list views
+ */
+export interface ObjectMetadataSummary {
+    /** Object name (internal identifier) */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Icon identifier */
+    icon?: string;
+    /** Object description */
+    description?: string;
+    /** Field definitions (simplified) */
+    fields?: Record<string, FieldConfig>;
+}
+/**
+ * Detailed object metadata for single object view
+ */
+export interface ObjectMetadataDetail extends ObjectConfig {
+    /** Formatted fields with name property populated */
+    fields: Record<string, FieldConfig & {
+        name: string;
+    }>;
+}
+/**
+ * Response for GET /api/metadata/objects (list all objects)
+ */
+export interface MetadataApiObjectListResponse extends MetadataApiListResponse<ObjectMetadataSummary> {
+    items: ObjectMetadataSummary[];
+}
+/**
+ * Response for GET /api/metadata/object/:name (get single object)
+ */
+export interface MetadataApiObjectDetailResponse extends MetadataApiResponse<ObjectMetadataDetail> {
+    /** Object name */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Icon identifier */
+    icon?: string;
+    /** Description */
+    description?: string;
+    /** Field definitions with populated names */
+    fields: Record<string, FieldConfig & {
+        name: string;
+    }>;
+    /** Available actions */
+    actions?: Record<string, ActionConfig>;
+    /** Validation rules */
+    validation?: ObjectConfig['validation'];
+    /** AI configuration */
+    ai?: ObjectConfig['ai'];
+}
+/**
+ * Field metadata response
+ */
+export interface FieldMetadataResponse extends MetadataApiResponse<FieldConfig> {
+    /** Field name */
+    name: string;
+    /** Field type */
+    type: string;
+    /** Display label */
+    label?: string;
+    /** Whether field is required */
+    required?: boolean;
+    /** Whether field must be unique */
+    unique?: boolean;
+    /** Default value */
+    defaultValue?: unknown;
+    /** Options for select/radio fields */
+    options?: unknown[];
+    /** Minimum value (for number fields) */
+    min?: number;
+    /** Maximum value (for number fields) */
+    max?: number;
+    /** Minimum length (for text fields) */
+    min_length?: number;
+    /** Maximum length (for text fields) */
+    max_length?: number;
+    /** Regular expression pattern */
+    regex?: string;
+}
+/**
+ * Action metadata summary
+ */
+export interface ActionMetadataSummary {
+    /** Action name (internal identifier) */
+    name: string;
+    /** Action type (record or global) */
+    type: 'record' | 'global';
+    /** Display label */
+    label?: string;
+    /** Action parameters */
+    params?: Record<string, unknown>;
+    /** Action description */
+    description?: string;
+}
+/**
+ * Response for GET /api/metadata/object/:name/actions (list object actions)
+ */
+export interface MetadataApiActionsResponse extends MetadataApiListResponse<ActionMetadataSummary> {
+    items: ActionMetadataSummary[];
+}
+/**
+ * Generic metadata entry
+ */
+export interface MetadataEntry {
+    /** Metadata type (e.g., 'object', 'view', 'form', 'page') */
+    type: string;
+    /** Unique identifier */
+    id: string;
+    /** File path (if loaded from file) */
+    path?: string;
+    /** Package name (if from a plugin) */
+    package?: string;
+    /** Actual metadata content */
+    content: unknown;
+}
+/**
+ * Configuration for Data API client
+ */
+export interface DataApiClientConfig {
+    /** Base URL of the ObjectQL server */
+    baseUrl: string;
+    /** Optional authentication token */
+    token?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Configuration for Metadata API client
+ */
+export interface MetadataApiClientConfig {
+    /** Base URL of the ObjectQL server */
+    baseUrl: string;
+    /** Optional authentication token */
+    token?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Interface for Data API client operations
+ */
+export interface IDataApiClient {
+    /**
+     * List records from an object
+     * @param objectName - Name of the object
+     * @param params - Query parameters
+     */
+    list<T = unknown>(objectName: string, params?: DataApiListParams): Promise<DataApiListResponse<T>>;
+    /**
+     * Get a single record by ID
+     * @param objectName - Name of the object
+     * @param id - Record ID
+     */
+    get<T = unknown>(objectName: string, id: string | number): Promise<DataApiItemResponse<T>>;
+    /**
+     * Create a new record
+     * @param objectName - Name of the object
+     * @param data - Record data
+     */
+    create<T = unknown>(objectName: string, data: DataApiCreateRequest): Promise<DataApiItemResponse<T>>;
+    /**
+     * Create multiple records
+     * @param objectName - Name of the object
+     * @param data - Array of record data
+     */
+    createMany<T = unknown>(objectName: string, data: DataApiCreateManyRequest): Promise<DataApiListResponse<T>>;
+    /**
+     * Update a record
+     * @param objectName - Name of the object
+     * @param id - Record ID
+     * @param data - Updated data
+     */
+    update<T = unknown>(objectName: string, id: string | number, data: DataApiUpdateRequest): Promise<DataApiItemResponse<T>>;
+    /**
+     * Update multiple records
+     * @param objectName - Name of the object
+     * @param request - Bulk update request
+     */
+    updateMany(objectName: string, request: DataApiBulkUpdateRequest): Promise<DataApiResponse>;
+    /**
+     * Delete a record
+     * @param objectName - Name of the object
+     * @param id - Record ID
+     */
+    delete(objectName: string, id: string | number): Promise<DataApiDeleteResponse>;
+    /**
+     * Delete multiple records
+     * @param objectName - Name of the object
+     * @param request - Bulk delete request
+     */
+    deleteMany(objectName: string, request: DataApiBulkDeleteRequest): Promise<DataApiDeleteResponse>;
+    /**
+     * Count records
+     * @param objectName - Name of the object
+     * @param filters - Filter criteria
+     */
+    count(objectName: string, filters?: FilterExpression): Promise<DataApiCountResponse>;
+}
+/**
+ * Interface for Metadata API client operations
+ */
+export interface IMetadataApiClient {
+    /**
+     * List all objects
+     */
+    listObjects(): Promise<MetadataApiObjectListResponse>;
+    /**
+     * Get detailed metadata for a specific object
+     * @param objectName - Name of the object
+     */
+    getObject(objectName: string): Promise<MetadataApiObjectDetailResponse>;
+    /**
+     * Get field metadata for a specific object field
+     * @param objectName - Name of the object
+     * @param fieldName - Name of the field
+     */
+    getField(objectName: string, fieldName: string): Promise<FieldMetadataResponse>;
+    /**
+     * List actions for a specific object
+     * @param objectName - Name of the object
+     */
+    listActions(objectName: string): Promise<MetadataApiActionsResponse>;
+    /**
+     * List metadata entries by type
+     * @param metadataType - Type of metadata (e.g., 'view', 'form', 'page')
+     */
+    listByType<T = unknown>(metadataType: string): Promise<MetadataApiListResponse<T>>;
+    /**
+     * Get a specific metadata entry
+     * @param metadataType - Type of metadata
+     * @param id - Unique identifier
+     */
+    getMetadata<T = unknown>(metadataType: string, id: string): Promise<MetadataApiResponse<T>>;
+}

package/dist/api.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * API Type Definitions for ObjectQL
+ *
+ * This file contains TypeScript interfaces for Data API and Metadata API endpoints.
+ * These types enable frontend applications to make type-safe API calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectQLError = exports.ApiErrorCode = void 0;
+// ============================================================================
+// Error Handling Types
+// ============================================================================
+/**
+ * Standardized error codes for ObjectQL API responses
+ */
+var ApiErrorCode;
+(function (ApiErrorCode) {
+    ApiErrorCode["INVALID_REQUEST"] = "INVALID_REQUEST";
+    ApiErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    ApiErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    ApiErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    ApiErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    ApiErrorCode["CONFLICT"] = "CONFLICT";
+    ApiErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    ApiErrorCode["DATABASE_ERROR"] = "DATABASE_ERROR";
+    ApiErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+})(ApiErrorCode || (exports.ApiErrorCode = ApiErrorCode = {}));
+/**
+ * ObjectQL Error class for throwing structured errors
+ */
+class ObjectQLError extends Error {
+    constructor(error) {
+        super(error.message);
+        this.name = 'ObjectQLError';
+        this.code = error.code;
+        this.details = error.details;
+        // Preserve proper stack traces in Node.js environments
+        const ErrorConstructor = Error;
+        if (typeof ErrorConstructor.captureStackTrace === 'function') {
+            ErrorConstructor.captureStackTrace(this, ObjectQLError);
+        }
+    }
+}
+exports.ObjectQLError = ObjectQLError;
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAOH,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;GAEG;AACH,IAAY,YAUX;AAVD,WAAY,YAAY;IACpB,mDAAmC,CAAA;IACnC,qDAAqC,CAAA;IACrC,6CAA6B,CAAA;IAC7B,uCAAuB,CAAA;IACvB,uCAAuB,CAAA;IACvB,qCAAqB,CAAA;IACrB,iDAAiC,CAAA;IACjC,iDAAiC,CAAA;IACjC,2DAA2C,CAAA;AAC/C,CAAC,EAVW,YAAY,4BAAZ,YAAY,QAUvB;AAwBD;;GAEG;AACH,MAAa,aAAc,SAAQ,KAAK;IAIpC,YAAY,KAAkF;QAC1F,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAE7B,uDAAuD;QACvD,MAAM,gBAAgB,GAAG,KAA2F,CAAC;QACrH,IAAI,OAAO,gBAAgB,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;YAC3D,gBAAgB,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;CACJ;AAhBD,sCAgBC"}

package/dist/driver.d.ts

@@ -1,3 +1,55 @@
+/**
+ * Column metadata from database introspection.
+ */
+export interface IntrospectedColumn {
+    /** Column name */
+    name: string;
+    /** Native database type (e.g., 'varchar', 'integer', 'timestamp') */
+    type: string;
+    /** Whether the column is nullable */
+    nullable: boolean;
+    /** Default value if any */
+    defaultValue?: any;
+    /** Whether this is a primary key */
+    isPrimary?: boolean;
+    /** Whether this column has a unique constraint */
+    isUnique?: boolean;
+    /** Maximum length for string types */
+    maxLength?: number;
+}
+/**
+ * Foreign key relationship metadata.
+ */
+export interface IntrospectedForeignKey {
+    /** Column name in the source table */
+    columnName: string;
+    /** Referenced table name */
+    referencedTable: string;
+    /** Referenced column name */
+    referencedColumn: string;
+    /** Constraint name */
+    constraintName?: string;
+}
+/**
+ * Table metadata from database introspection.
+ */
+export interface IntrospectedTable {
+    /** Table name */
+    name: string;
+    /** List of columns */
+    columns: IntrospectedColumn[];
+    /** List of foreign key relationships */
+    foreignKeys: IntrospectedForeignKey[];
+    /** Primary key columns */
+    primaryKeys: string[];
+}
+/**
+ * Complete database schema introspection result.
+ */
+export interface IntrospectedSchema {
+    /** Map of table name to table metadata */
+    tables: Record<string, IntrospectedTable>;
+}
 export interface Driver {
     find(objectName: string, query: any, options?: any): Promise<any[]>;
     findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any>;
@@ -6,6 +58,12 @@ export interface Driver {
     delete(objectName: string, id: string | number, options?: any): Promise<any>;
     count(objectName: string, filters: any, options?: any): Promise<number>;
     init?(objects: any[]): Promise<void>;
+    /**
+     * Introspect the database schema to discover existing tables, columns, and relationships.
+     * This allows connecting to an existing database without defining metadata.
+     * @returns Complete schema information including tables, columns, and foreign keys
+     */
+    introspectSchema?(): Promise<IntrospectedSchema>;
     aggregate?(objectName: string, query: any, options?: any): Promise<any>;
     distinct?(objectName: string, field: string, filters?: any, options?: any): Promise<any[]>;
     createMany?(objectName: string, data: any[], options?: any): Promise<any>;

package/dist/index.d.ts

@@ -16,3 +16,4 @@ export * from './page';
 export * from './loader';
 export * from './application';
 export * from './menu';
+export * from './api';

package/dist/index.js

@@ -32,4 +32,5 @@ __exportStar(require("./page"), exports);
 __exportStar(require("./loader"), exports);
 __exportStar(require("./application"), exports);
 __exportStar(require("./menu"), exports);
+__exportStar(require("./api"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,+CAA6B;AAC7B,yCAAuB;AACvB,2CAAyB;AACzB,gDAA8B;AAC9B,yCAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,+CAA6B;AAC7B,yCAAuB;AACvB,2CAAyB;AACzB,gDAA8B;AAC9B,yCAAuB;AACvB,wCAAsB"}

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@objectql/types",
-  "version": "1.8.1",
+  "version": "1.8.2",
+  "description": "Pure TypeScript type definitions and interfaces for the ObjectQL protocol - The Contract",
+  "keywords": [
+    "objectql",
+    "types",
+    "typescript",
+    "interfaces",
+    "protocol",
+    "schema",
+    "metadata",
+    "ai-native",
+    "orm",
+    "database"
+  ],
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",