@objectql/types 1.4.0 → 1.6.0

package/dist/page.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Page Metadata Definition
+ *
+ * Defines the structure for pages in ObjectQL applications.
+ * Inspired by low-code platforms like Airtable, Retool, Appsmith, and Salesforce Lightning.
+ *
+ * Pages are composable UI containers that can render data from objects,
+ * display custom components, and orchestrate user interactions.
+ */
+/**
+ * Layout types for page arrangement
+ */
+export type PageLayoutType = 'single_column' | 'two_column' | 'three_column' | 'dashboard' | 'canvas' | 'tabs' | 'wizard' | 'custom';
+/**
+ * Component types that can be placed on a page
+ */
+export type PageComponentType = 'data_grid' | 'form' | 'detail_view' | 'chart' | 'metric' | 'list' | 'calendar' | 'kanban' | 'timeline' | 'text' | 'html' | 'iframe' | 'button' | 'tabs' | 'container' | 'divider' | 'image' | 'custom';
+/**
+ * Responsive breakpoint configuration
+ */
+export interface ResponsiveConfig {
+    /** Mobile viewport (< 640px) */
+    mobile?: {
+        columns?: number;
+        visible?: boolean;
+        order?: number;
+    };
+    /** Tablet viewport (640px - 1024px) */
+    tablet?: {
+        columns?: number;
+        visible?: boolean;
+        order?: number;
+    };
+    /** Desktop viewport (> 1024px) */
+    desktop?: {
+        columns?: number;
+        visible?: boolean;
+        order?: number;
+    };
+}
+/**
+ * Data source configuration for components
+ */
+export interface ComponentDataSource {
+    /** Object name to query */
+    object?: string;
+    /** Filter conditions */
+    filters?: any[];
+    /** Fields to display */
+    fields?: string[];
+    /** Sort configuration */
+    sort?: Array<[string, 'asc' | 'desc']>;
+    /** Maximum records to fetch */
+    limit?: number;
+    /** Enable pagination */
+    paginate?: boolean;
+    /** Related objects to expand */
+    expand?: Record<string, any>;
+    /** Custom query override */
+    query?: any;
+}
+/**
+ * Action triggered by component interaction
+ */
+export interface ComponentAction {
+    /** Action type */
+    type: 'navigate' | 'open_modal' | 'run_action' | 'submit_form' | 'refresh' | 'custom';
+    /** Navigation path (for type: navigate) */
+    path?: string;
+    /** Modal component to open (for type: open_modal) */
+    modal?: string;
+    /** Action name to execute (for type: run_action) */
+    action?: string;
+    /** Target object for action */
+    object?: string;
+    /** Custom handler function */
+    handler?: string;
+    /** Confirmation message before executing */
+    confirm?: string;
+    /** Success message after execution */
+    success_message?: string;
+    /** Error handling */
+    on_error?: 'show_toast' | 'show_modal' | 'ignore';
+}
+/**
+ * Styling configuration for components
+ */
+export interface ComponentStyle {
+    /** Width (e.g., '100%', '300px', 'auto') */
+    width?: string;
+    /** Height */
+    height?: string;
+    /** Minimum width */
+    min_width?: string;
+    /** Minimum height */
+    min_height?: string;
+    /** Background color */
+    background?: string;
+    /** Text color */
+    color?: string;
+    /** Border */
+    border?: string;
+    /** Border radius */
+    border_radius?: string;
+    /** Padding */
+    padding?: string;
+    /** Margin */
+    margin?: string;
+    /** Custom CSS classes */
+    class_name?: string;
+    /** Inline styles */
+    custom_css?: Record<string, any>;
+}
+/**
+ * Base component configuration
+ */
+export interface PageComponent {
+    /** Unique component identifier within the page */
+    id: string;
+    /** Component type */
+    type: PageComponentType;
+    /** Display label */
+    label?: string;
+    /** Component description */
+    description?: string;
+    /** Data source configuration */
+    data_source?: ComponentDataSource;
+    /** Component-specific configuration */
+    config?: Record<string, any>;
+    /** Actions triggered by this component */
+    actions?: {
+        on_click?: ComponentAction;
+        on_submit?: ComponentAction;
+        on_load?: ComponentAction;
+        on_change?: ComponentAction;
+        [key: string]: ComponentAction | undefined;
+    };
+    /** Visual styling */
+    style?: ComponentStyle;
+    /** Responsive behavior */
+    responsive?: ResponsiveConfig;
+    /** Visibility conditions */
+    visible_when?: Record<string, any>;
+    /** Access control */
+    permissions?: string[];
+    /** Nested components (for containers, tabs, etc.) */
+    components?: PageComponent[];
+    /** Grid position (for dashboard layout) */
+    grid?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Custom component reference */
+    component?: string;
+}
+/**
+ * Page section/region configuration
+ */
+export interface PageSection {
+    /** Section identifier */
+    id: string;
+    /** Section label */
+    label?: string;
+    /** Section type */
+    type?: 'header' | 'sidebar' | 'content' | 'footer' | 'custom';
+    /** Components in this section */
+    components: PageComponent[];
+    /** Section styling */
+    style?: ComponentStyle;
+    /** Collapsible section */
+    collapsible?: boolean;
+    /** Default collapsed state */
+    collapsed?: boolean;
+    /** Visibility conditions */
+    visible_when?: Record<string, any>;
+}
+/**
+ * Page metadata configuration
+ */
+export interface PageConfig {
+    /** Unique page identifier */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Page description */
+    description?: string;
+    /** Icon for navigation */
+    icon?: string;
+    /** Layout type */
+    layout: PageLayoutType;
+    /** Page sections */
+    sections?: PageSection[];
+    /** Components (alternative to sections for simple layouts) */
+    components?: PageComponent[];
+    /** Page-level data sources */
+    data_sources?: Record<string, ComponentDataSource>;
+    /** Page-level actions */
+    actions?: Record<string, ComponentAction>;
+    /** Page styling */
+    style?: ComponentStyle;
+    /** Access control */
+    permissions?: {
+        /** Roles allowed to view this page */
+        view?: string[];
+        /** Roles allowed to edit this page */
+        edit?: string[];
+    };
+    /** SEO and metadata */
+    meta?: {
+        title?: string;
+        description?: string;
+        keywords?: string[];
+    };
+    /** Page state management */
+    state?: {
+        /** Initial state values */
+        initial?: Record<string, any>;
+        /** State persistence */
+        persist?: boolean;
+        /** Storage key for persistence */
+        storage_key?: string;
+    };
+    /** Responsive configuration */
+    responsive?: ResponsiveConfig;
+    /** Custom page handler/controller */
+    handler?: string;
+    /** Enable real-time updates */
+    realtime?: boolean;
+    /** Refresh interval in seconds */
+    refresh_interval?: number;
+    /** AI context for page generation and understanding */
+    ai_context?: {
+        /** Purpose of the page */
+        intent?: string;
+        /** Target user persona */
+        persona?: string;
+        /** Key user tasks */
+        tasks?: string[];
+    };
+}
+/**
+ * Lightweight page reference (for menus, navigation, etc.)
+ *
+ * Used in application navigation menus and links to reference pages
+ * without loading the full page configuration. This is useful for:
+ * - Building navigation menus
+ * - Creating page links
+ * - Page selection dropdowns
+ *
+ * @example
+ * ```typescript
+ * // In navigation menu
+ * const menuItem: PageReference = {
+ *   name: 'dashboard',
+ *   label: 'Dashboard',
+ *   icon: 'dashboard',
+ *   path: '/dashboard'
+ * };
+ * ```
+ */
+export interface PageReference {
+    /** Page name/identifier */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Icon */
+    icon?: string;
+    /** Path/route */
+    path?: string;
+}

package/dist/page.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Page Metadata Definition
+ *
+ * Defines the structure for pages in ObjectQL applications.
+ * Inspired by low-code platforms like Airtable, Retool, Appsmith, and Salesforce Lightning.
+ *
+ * Pages are composable UI containers that can render data from objects,
+ * display custom components, and orchestrate user interactions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=page.js.map

package/dist/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}

package/dist/permission.d.ts

@@ -0,0 +1,391 @@
+/**
+ * Permission and Security Metadata Types
+ *
+ * This module defines the TypeScript interfaces for ObjectQL's permission system,
+ * implementing role-based access control (RBAC), field-level security, and
+ * record-level rules.
+ *
+ * Based on specification: docs/spec/permission.md
+ */
+/**
+ * Basic CRUD operations for object-level permissions
+ */
+export type ObjectOperation = 'create' | 'read' | 'update' | 'delete' | 'view_all' | 'modify_all';
+/**
+ * Field-level operations
+ */
+export type FieldOperation = 'read' | 'update';
+/**
+ * Comparison operators for permission conditions
+ */
+export type PermissionOperator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with';
+/**
+ * Object-level permissions controlling CRUD operations
+ */
+export interface ObjectPermissions {
+    /** Roles that can create new records */
+    create?: string[];
+    /** Roles that can view records */
+    read?: string[];
+    /** Roles that can update records */
+    update?: string[];
+    /** Roles that can delete records */
+    delete?: string[];
+    /** Roles that can view all records (bypass ownership rules) */
+    view_all?: string[];
+    /** Roles that can modify all records (bypass ownership rules) */
+    modify_all?: string[];
+}
+/**
+ * Field-level permissions for a specific field
+ */
+export interface FieldPermission {
+    /** Roles that can read this field */
+    read?: string[];
+    /** Roles that can update this field */
+    update?: string[];
+}
+/**
+ * Map of field names to their permissions
+ */
+export type FieldPermissions = Record<string, FieldPermission>;
+/**
+ * Condition type for record-level rules
+ */
+export type ConditionType = 'simple' | 'complex' | 'formula' | 'lookup';
+/**
+ * Simple condition for a single field comparison
+ */
+export interface SimpleCondition {
+    type?: 'simple';
+    /** Field to check */
+    field: string;
+    /** Comparison operator */
+    operator: PermissionOperator;
+    /** Value to compare against (can include variables like $current_user.id) */
+    value: any;
+}
+/**
+ * Simple condition element (inline form for complex expressions)
+ */
+export interface ConditionElement {
+    field: string;
+    operator: PermissionOperator;
+    value: any;
+}
+/**
+ * Expression element in complex conditions
+ */
+export type ConditionExpression = SimpleCondition | ConditionElement | 'and' | 'or';
+/**
+ * Complex condition with multiple clauses
+ */
+export interface ComplexCondition {
+    type: 'complex';
+    /** Array of conditions and logical operators */
+    expression: ConditionExpression[];
+}
+/**
+ * Formula-based condition using custom logic
+ */
+export interface FormulaCondition {
+    type: 'formula';
+    /** JavaScript expression or formula */
+    formula: string;
+}
+/**
+ * Lookup condition checking related record data
+ */
+export interface LookupCondition {
+    type: 'lookup';
+    /** Related object to check */
+    object: string;
+    /** Field linking to related object */
+    via: string;
+    /** Condition to check on related object */
+    condition: RecordRuleCondition;
+}
+/**
+ * Union type for all condition types
+ */
+export type RecordRuleCondition = SimpleCondition | ComplexCondition | FormulaCondition | LookupCondition;
+/**
+ * Permissions granted by a record rule
+ */
+export interface RecordRulePermissions {
+    /** Grant read permission */
+    read?: boolean;
+    /** Grant update permission */
+    update?: boolean;
+    /** Grant delete permission */
+    delete?: boolean;
+}
+/**
+ * Record-level rule for dynamic access control
+ */
+export interface RecordRule {
+    /** Unique name of the rule */
+    name: string;
+    /** Priority (higher priority rules take precedence, default: 0) */
+    priority?: number;
+    /** Human-readable description */
+    description?: string;
+    /** Condition for applying this rule */
+    condition: RecordRuleCondition;
+    /** Permissions granted when condition matches */
+    permissions: RecordRulePermissions;
+}
+/**
+ * Sharing rule type
+ */
+export type SharingRuleType = 'manual' | 'criteria' | 'team';
+/**
+ * Who to share with
+ */
+export interface SharedWith {
+    type: 'role' | 'team' | 'user' | 'group';
+    roles?: string[];
+    teams?: string[];
+    users?: string[];
+    groups?: string[];
+}
+/**
+ * Base sharing rule
+ */
+export interface BaseSharingRule {
+    /** Unique name of the rule */
+    name: string;
+    /** Type of sharing rule */
+    type: SharingRuleType;
+    /** Description */
+    description?: string;
+    /** Whether this rule is enabled */
+    enabled?: boolean;
+    /** Permissions granted through sharing */
+    permissions: RecordRulePermissions;
+}
+/**
+ * Manual sharing rule - users can manually share records
+ */
+export interface ManualSharingRule extends BaseSharingRule {
+    type: 'manual';
+}
+/**
+ * Criteria-based sharing rule - automatic sharing
+ */
+export interface CriteriaSharingRule extends BaseSharingRule {
+    type: 'criteria';
+    /** Condition for automatic sharing */
+    condition: RecordRuleCondition;
+    /** Who to share with */
+    shared_with: SharedWith;
+}
+/**
+ * Team-based sharing rule
+ */
+export interface TeamSharingRule extends BaseSharingRule {
+    type: 'team';
+    /** Field containing team ID */
+    team_field: string;
+}
+/**
+ * Union type for all sharing rules
+ */
+export type SharingRule = ManualSharingRule | CriteriaSharingRule | TeamSharingRule;
+/**
+ * Condition for action execution
+ */
+export interface ActionCondition {
+    /** Field to check */
+    field: string;
+    /** Comparison operator */
+    operator: PermissionOperator;
+    /** Value to compare */
+    value: any;
+}
+/**
+ * Rate limiting configuration for actions
+ */
+export interface ActionRateLimit {
+    /** Maximum requests per hour */
+    requests_per_hour?: number;
+    /** Maximum requests per day */
+    requests_per_day?: number;
+}
+/**
+ * Permission configuration for a specific action
+ */
+export interface ActionPermission {
+    /** Roles that can execute this action */
+    execute: string[];
+    /** Conditions that must be met for execution */
+    conditions?: ActionCondition[];
+    /** Rate limiting */
+    rate_limit?: ActionRateLimit;
+}
+/**
+ * Map of action names to their permissions
+ */
+export type ActionPermissions = Record<string, ActionPermission>;
+/**
+ * Field restrictions for a view
+ */
+export interface ViewFieldRestriction {
+    /** Field name */
+    [fieldName: string]: {
+        /** Roles that can see this field in the view */
+        visible_to: string[];
+    };
+}
+/**
+ * Permission configuration for a specific view
+ */
+export interface ViewPermission {
+    /** Roles that can access this view */
+    access: string[];
+    /** Field-level restrictions within the view */
+    field_restrictions?: ViewFieldRestriction;
+}
+/**
+ * Map of view names to their permissions
+ */
+export type ViewPermissions = Record<string, ViewPermission>;
+/**
+ * Row-level security configuration
+ */
+export interface RowLevelSecurity {
+    /** Whether RLS is enabled */
+    enabled: boolean;
+    /** Default rule applied to all users */
+    default_rule?: SimpleCondition;
+    /** Exceptions to the default rule */
+    exceptions?: Array<{
+        /** Role to apply exception to */
+        role: string;
+        /** Whether to bypass RLS entirely */
+        bypass?: boolean;
+        /** Custom condition for this role */
+        condition?: RecordRuleCondition;
+    }>;
+}
+/**
+ * Field masking configuration for a specific field
+ */
+export interface FieldMaskConfig {
+    /** Mask format (e.g., "****-****-****-{last4}") */
+    mask_format: string;
+    /** Roles that can see the unmasked value */
+    visible_to: string[];
+}
+/**
+ * Map of field names to their masking configuration
+ */
+export type FieldMasking = Record<string, FieldMaskConfig>;
+/**
+ * Audit event type
+ */
+export type AuditEventType = 'permission_grant' | 'permission_revoke' | 'access_denied' | 'sensitive_field_access';
+/**
+ * Alert configuration for suspicious activity
+ */
+export interface AuditAlert {
+    /** Event type to alert on */
+    event: AuditEventType;
+    /** Number of events to trigger alert */
+    threshold: number;
+    /** Time window in minutes */
+    window_minutes: number;
+    /** Who to notify (roles or user IDs) */
+    notify: string[];
+}
+/**
+ * Audit trail configuration
+ */
+export interface AuditConfig {
+    /** Whether auditing is enabled */
+    enabled: boolean;
+    /** Events to log */
+    events?: AuditEventType[];
+    /** Retention period in days */
+    retention_days?: number;
+    /** Alert configurations */
+    alerts?: AuditAlert[];
+}
+/**
+ * Complete permission configuration for an object
+ */
+export interface PermissionConfig {
+    /** Unique name of the permission configuration */
+    name: string;
+    /** Object this permission applies to */
+    object: string;
+    /** Description */
+    description?: string;
+    /**
+     * Roles referenced in this permission configuration.
+     *
+     * Best Practice: Define roles centrally in ApplicationConfig and reference them here.
+     * This field serves to:
+     * 1. Document which roles apply to this object
+     * 2. Validate that only defined roles are used
+     * 3. Support standalone usage without application context
+     *
+     * Example:
+     * - Define in app: permissions.roles: [admin, manager, user]
+     * - Reference here: roles: [admin, manager, user]
+     */
+    roles?: string[];
+    /** Object-level permissions */
+    object_permissions?: ObjectPermissions;
+    /** Field-level security */
+    field_permissions?: FieldPermissions;
+    /** Record-level access rules */
+    record_rules?: RecordRule[];
+    /** Sharing rules */
+    sharing_rules?: SharingRule[];
+    /** Action permissions */
+    action_permissions?: ActionPermissions;
+    /** View permissions */
+    view_permissions?: ViewPermissions;
+    /** Row-level security */
+    row_level_security?: RowLevelSecurity;
+    /** Field masking */
+    field_masking?: FieldMasking;
+    /** Audit configuration */
+    audit?: AuditConfig;
+}
+/**
+ * Context for permission checks
+ */
+export interface PermissionCheckContext {
+    /** Current user */
+    user: {
+        id: string;
+        /** User roles (array for consistency, single role represented as one-element array) */
+        roles?: string[];
+        department_id?: string;
+        team_id?: string;
+        [key: string]: any;
+    };
+    /** Object name */
+    object: string;
+    /** Operation to check */
+    operation: ObjectOperation | FieldOperation;
+    /** Record ID (for record-level checks) */
+    recordId?: string;
+    /** Field name (for field-level checks) */
+    field?: string;
+    /** Record data (for condition evaluation) */
+    record?: any;
+}
+/**
+ * Result of a permission check
+ */
+export interface PermissionCheckResult {
+    /** Whether permission is granted */
+    granted: boolean;
+    /** Reason if denied */
+    reason?: string;
+    /** Rule that granted/denied access */
+    rule?: string;
+}

package/dist/permission.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Permission and Security Metadata Types
+ *
+ * This module defines the TypeScript interfaces for ObjectQL's permission system,
+ * implementing role-based access control (RBAC), field-level security, and
+ * record-level rules.
+ *
+ * Based on specification: docs/spec/permission.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=permission.js.map

package/dist/permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}