@objectql/types 1.8.3 → 1.8.4

package/dist/report.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Report Metadata Definition
+ *
+ * Defines the structure for reports, data summaries, and analytics in ObjectQL.
+ * Reports aggregate and visualize data from objects with grouping, filtering, and calculations.
+ *
+ * Based on patterns from Salesforce Reports, Tableau, and similar BI platforms.
+ */
+import { ViewFilter, ViewFilterGroup, ViewColumn } from './view';
+/**
+ * Types of reports supported by ObjectQL
+ */
+export type ReportType = 'tabular' | 'summary' | 'matrix' | 'chart' | 'dashboard' | 'custom';
+/**
+ * Chart types for visualization
+ */
+export type ChartType = 'bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'scatter' | 'bubble' | 'funnel' | 'gauge' | 'radar' | 'heatmap' | 'treemap' | 'waterfall' | 'custom';
+/**
+ * Aggregation functions for report calculations
+ */
+export type AggregationFunction = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'median' | 'mode' | 'stddev' | 'variance' | 'distinct_count' | 'first' | 'last' | 'custom';
+/**
+ * Grouping configuration for reports
+ */
+export interface ReportGrouping {
+    /** Field to group by */
+    field: string;
+    /** Display label */
+    label?: string;
+    /** Sort order for groups */
+    sort?: 'asc' | 'desc';
+    /** Group by date interval (for date fields) */
+    date_interval?: 'day' | 'week' | 'month' | 'quarter' | 'year';
+    /** Group by numeric range (for numeric fields) */
+    numeric_range?: {
+        /** Range size */
+        size: number;
+        /** Starting value */
+        start?: number;
+    };
+    /** Show subtotals for this grouping */
+    show_subtotals?: boolean;
+    /** Limit number of groups */
+    limit?: number;
+}
+/**
+ * Aggregation/calculation configuration
+ */
+export interface ReportAggregation {
+    /** Field to aggregate */
+    field: string;
+    /** Aggregation function */
+    function: AggregationFunction;
+    /** Display label */
+    label?: string;
+    /** Display format */
+    format?: string;
+    /** Custom aggregation expression */
+    expression?: string;
+    /** Show in totals row */
+    show_in_total?: boolean;
+}
+/**
+ * Formula field for calculated columns
+ */
+export interface ReportFormula {
+    /** Formula name */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Formula expression */
+    expression: string;
+    /** Data type of result */
+    type?: 'number' | 'text' | 'date' | 'boolean';
+    /** Display format */
+    format?: string;
+    /** Description of what this formula calculates */
+    description?: string;
+}
+/**
+ * Chart configuration for report visualization
+ */
+export interface ReportChartConfig {
+    /** Chart type */
+    type: ChartType;
+    /** Chart title */
+    title?: string;
+    /** Field for X-axis */
+    x_axis?: string;
+    /** Field(s) for Y-axis */
+    y_axis?: string | string[];
+    /** Field for chart series/legend */
+    series_field?: string;
+    /** Chart colors */
+    colors?: string[];
+    /** Show legend */
+    show_legend?: boolean;
+    /** Legend position */
+    legend_position?: 'top' | 'bottom' | 'left' | 'right';
+    /** Show data labels */
+    show_data_labels?: boolean;
+    /** Chart height in pixels */
+    height?: number;
+    /** Chart width in pixels */
+    width?: number;
+    /** Enable drill-down */
+    enable_drill_down?: boolean;
+    /** Custom chart configuration */
+    custom_config?: Record<string, any>;
+}
+/**
+ * Matrix report dimension configuration
+ */
+export interface MatrixDimension {
+    /** Field for this dimension */
+    field: string;
+    /** Display label */
+    label?: string;
+    /** Sort order */
+    sort?: 'asc' | 'desc';
+    /** Show totals */
+    show_totals?: boolean;
+}
+/**
+ * Export configuration for reports
+ */
+export interface ReportExportConfig {
+    /** Enabled export formats */
+    formats?: ('pdf' | 'xlsx' | 'csv' | 'json' | 'html')[];
+    /** Include charts in export */
+    include_charts?: boolean;
+    /** Export filename template */
+    filename_template?: string;
+    /** Page orientation for PDF */
+    page_orientation?: 'portrait' | 'landscape';
+    /** Paper size for PDF */
+    paper_size?: 'A4' | 'Letter' | 'Legal';
+}
+/**
+ * Scheduling configuration for automated reports
+ */
+export interface ReportScheduleConfig {
+    /** Enable scheduled execution */
+    enabled: boolean;
+    /** Cron expression for schedule */
+    cron?: string;
+    /** Timezone for schedule */
+    timezone?: string;
+    /** Email recipients for scheduled reports */
+    recipients?: string[];
+    /** Email subject template */
+    email_subject?: string;
+    /** Email body template */
+    email_body?: string;
+    /** Export format for scheduled report */
+    format?: 'pdf' | 'xlsx' | 'csv';
+}
+/**
+ * Complete report configuration
+ */
+export interface ReportConfig {
+    /** Unique report identifier */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Report type */
+    type: ReportType;
+    /** Primary object for the report */
+    object: string;
+    /** Report description */
+    description?: string;
+    /** Icon for the report */
+    icon?: string;
+    /** Columns to display */
+    columns?: ViewColumn[];
+    /** Filters to apply */
+    filters?: (ViewFilter | ViewFilterGroup)[];
+    /** Grouping configuration */
+    groupings?: ReportGrouping[];
+    /** Aggregations/calculations */
+    aggregations?: ReportAggregation[];
+    /** Formula fields */
+    formulas?: ReportFormula[];
+    /** Chart configuration */
+    chart?: ReportChartConfig;
+    /** Matrix report row dimension */
+    row_dimension?: MatrixDimension;
+    /** Matrix report column dimension */
+    column_dimension?: MatrixDimension;
+    /** Limit number of rows */
+    limit?: number;
+    /** Enable drill-down to records */
+    enable_drill_down?: boolean;
+    /** Show record count */
+    show_record_count?: boolean;
+    /** Show grand totals */
+    show_grand_total?: boolean;
+    /** Export configuration */
+    export?: ReportExportConfig;
+    /** Scheduling configuration */
+    schedule?: ReportScheduleConfig;
+    /** Cache configuration */
+    cache?: {
+        /** Enable caching */
+        enabled?: boolean;
+        /** Cache duration in seconds */
+        duration?: number;
+    };
+    /** Access control */
+    permissions?: {
+        /** Roles that can view this report */
+        view?: string[];
+        /** Roles that can edit report configuration */
+        edit?: string[];
+        /** Roles that can export */
+        export?: string[];
+    };
+    /** Whether this report is shared with all users */
+    is_public?: boolean;
+    /** Owner of the report (for personal reports) */
+    owner?: string;
+    /** Folder/category for organization */
+    folder?: string;
+    /** Custom report configuration */
+    config?: Record<string, any>;
+    /** AI context for report generation */
+    ai_context?: {
+        /** Business question this report answers */
+        intent?: string;
+        /** Target audience */
+        audience?: string;
+        /** Key insights to highlight */
+        insights?: string[];
+        /** Recommended visualizations */
+        visualizations?: string[];
+    };
+}
+/**
+ * Report execution result
+ */
+export interface ReportResult {
+    /** Report name */
+    report_name: string;
+    /** Execution timestamp */
+    executed_at: string;
+    /** Data rows */
+    rows: any[];
+    /** Total record count */
+    total_count: number;
+    /** Aggregation results */
+    aggregations?: Record<string, any>;
+    /** Grand totals */
+    grand_total?: Record<string, any>;
+    /** Chart data */
+    chart_data?: any;
+    /** Execution time in milliseconds */
+    execution_time?: number;
+    /** Whether result was from cache */
+    from_cache?: boolean;
+}
+/**
+ * Lightweight report reference
+ * Used in navigation, dropdowns, and report selectors
+ */
+export interface ReportReference {
+    /** Report name/identifier */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Icon */
+    icon?: string;
+    /** Report type */
+    type?: ReportType;
+    /** Folder/category */
+    folder?: string;
+}

package/dist/report.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Report Metadata Definition
+ *
+ * Defines the structure for reports, data summaries, and analytics in ObjectQL.
+ * Reports aggregate and visualize data from objects with grouping, filtering, and calculations.
+ *
+ * Based on patterns from Salesforce Reports, Tableau, and similar BI platforms.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

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

package/dist/view.d.ts

@@ -0,0 +1,304 @@
+/**
+ * View Metadata Definition
+ *
+ * Defines the structure for list views, grid views, and other data visualization views
+ * in ObjectQL applications. Views define how data from objects is displayed to users
+ * including columns, filters, sorting, and available actions.
+ *
+ * Based on common patterns from Salesforce List Views, Airtable Views, and similar platforms.
+ */
+import { ValidationOperator } from './validation';
+/**
+ * Types of views supported by ObjectQL
+ */
+export type ViewType = 'list' | 'kanban' | 'calendar' | 'timeline' | 'gallery' | 'map' | 'pivot' | 'custom';
+/**
+ * Column configuration for a view
+ */
+export interface ViewColumn {
+    /** Field name to display */
+    field: string;
+    /** Display label (defaults to field label) */
+    label?: string;
+    /** Column width in pixels */
+    width?: number;
+    /** Whether this column is visible by default */
+    visible?: boolean;
+    /** Whether this column is sortable */
+    sortable?: boolean;
+    /** Whether this column is filterable */
+    filterable?: boolean;
+    /** Display format (date, currency, percent, etc.) */
+    format?: string;
+    /** Whether to display as a badge/chip */
+    badge?: boolean;
+    /** Custom template for rendering */
+    template?: string;
+    /** Alignment (left, center, right) */
+    align?: 'left' | 'center' | 'right';
+    /** Whether this column is frozen/pinned */
+    frozen?: boolean;
+    /** Truncate text after N characters */
+    truncate?: number;
+    /** Tooltip configuration */
+    tooltip?: string | {
+        field?: string;
+        template?: string;
+    };
+}
+/**
+ * Filter condition for a view
+ */
+export interface ViewFilter {
+    /** Field to filter on */
+    field: string;
+    /** Comparison operator */
+    operator: ValidationOperator | 'is_null' | 'is_not_null';
+    /** Value to compare against */
+    value?: any;
+    /** Multiple values (for 'in' operator) */
+    values?: any[];
+    /** Label for this filter (for UI) */
+    label?: string;
+}
+/**
+ * Logical grouping of filters
+ */
+export interface ViewFilterGroup {
+    /** Logical operator */
+    operator: 'and' | 'or';
+    /** Filters in this group */
+    filters: (ViewFilter | ViewFilterGroup)[];
+}
+/**
+ * Sort configuration for a view
+ */
+export interface ViewSort {
+    /** Field to sort by */
+    field: string;
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+}
+/**
+ * Action available in the view
+ */
+export interface ViewAction {
+    /** Action name/identifier */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Icon */
+    icon?: string;
+    /** Action type */
+    type?: 'standard' | 'custom';
+    /** Confirmation message before executing */
+    confirm?: string;
+    /** Visibility condition */
+    visible_when?: string;
+    /** Enabled condition */
+    enabled_when?: string;
+}
+/**
+ * Grouping configuration for a view
+ */
+export interface ViewGrouping {
+    /** Field to group by */
+    field: string;
+    /** Display label for the group */
+    label?: string;
+    /** Sort order within groups */
+    sort?: 'asc' | 'desc';
+    /** Whether groups are collapsed by default */
+    collapsed?: boolean;
+}
+/**
+ * Pagination configuration
+ */
+export interface ViewPagination {
+    /** Enable pagination */
+    enabled: boolean;
+    /** Default page size */
+    page_size?: number;
+    /** Available page size options */
+    page_size_options?: number[];
+}
+/**
+ * Kanban view specific configuration
+ */
+export interface KanbanViewConfig {
+    /** Field to use for columns (status field) */
+    column_field: string;
+    /** Field to use for card title */
+    title_field: string;
+    /** Field to use for card subtitle */
+    subtitle_field?: string;
+    /** Additional fields to display on card */
+    card_fields?: string[];
+    /** Field to use for card color */
+    color_field?: string;
+    /** Field to use for card avatar/image */
+    avatar_field?: string;
+    /** Enable drag and drop */
+    enable_drag_drop?: boolean;
+}
+/**
+ * Calendar view specific configuration
+ */
+export interface CalendarViewConfig {
+    /** Field to use for event start date */
+    start_date_field: string;
+    /** Field to use for event end date */
+    end_date_field?: string;
+    /** Field to use for event title */
+    title_field: string;
+    /** Field to use for event color */
+    color_field?: string;
+    /** Default view mode (day, week, month) */
+    default_mode?: 'day' | 'week' | 'month' | 'year';
+    /** Enable all-day events */
+    all_day_field?: string;
+}
+/**
+ * Timeline view specific configuration
+ */
+export interface TimelineViewConfig {
+    /** Field to use for task start */
+    start_field: string;
+    /** Field to use for task end */
+    end_field: string;
+    /** Field to use for task name */
+    name_field: string;
+    /** Field to use for progress percentage */
+    progress_field?: string;
+    /** Field to use for dependencies */
+    dependencies_field?: string;
+    /** Enable drag to resize */
+    enable_resize?: boolean;
+    /** Enable drag to move */
+    enable_move?: boolean;
+}
+/**
+ * Gallery view specific configuration
+ */
+export interface GalleryViewConfig {
+    /** Field to use for card image */
+    image_field: string;
+    /** Field to use for card title */
+    title_field: string;
+    /** Field to use for card description */
+    description_field?: string;
+    /** Number of columns */
+    columns?: number;
+    /** Card aspect ratio */
+    aspect_ratio?: string;
+}
+/**
+ * Map view specific configuration
+ */
+export interface MapViewConfig {
+    /** Field containing location data */
+    location_field: string;
+    /** Field to use for marker title */
+    title_field: string;
+    /** Field to use for marker description */
+    description_field?: string;
+    /** Default map center [latitude, longitude] */
+    center?: [number, number];
+    /** Default zoom level */
+    zoom?: number;
+    /** Enable clustering */
+    enable_clustering?: boolean;
+}
+/**
+ * Complete view configuration
+ */
+export interface ViewConfig {
+    /** Unique view identifier */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Object this view applies to */
+    object: string;
+    /** View description */
+    description?: string;
+    /** View type */
+    type?: ViewType;
+    /** Icon for the view */
+    icon?: string;
+    /** Columns to display (for list views) */
+    columns?: ViewColumn[];
+    /** Default filters */
+    filters?: (ViewFilter | ViewFilterGroup)[];
+    /** Default sorting */
+    sort?: ViewSort[];
+    /** Grouping configuration */
+    grouping?: ViewGrouping;
+    /** Pagination configuration */
+    pagination?: ViewPagination;
+    /** Maximum number of records to fetch */
+    limit?: number;
+    /** Available actions */
+    actions?: ViewAction[];
+    /** Enable search */
+    enable_search?: boolean;
+    /** Searchable fields */
+    search_fields?: string[];
+    /** Enable inline editing */
+    enable_inline_edit?: boolean;
+    /** Enable bulk selection */
+    enable_bulk_select?: boolean;
+    /** Enable export */
+    enable_export?: boolean;
+    /** Export formats */
+    export_formats?: ('csv' | 'xlsx' | 'pdf' | 'json')[];
+    /** Kanban-specific config */
+    kanban?: KanbanViewConfig;
+    /** Calendar-specific config */
+    calendar?: CalendarViewConfig;
+    /** Timeline-specific config */
+    timeline?: TimelineViewConfig;
+    /** Gallery-specific config */
+    gallery?: GalleryViewConfig;
+    /** Map-specific config */
+    map?: MapViewConfig;
+    /** Whether this is the default view */
+    is_default?: boolean;
+    /** Access control */
+    permissions?: {
+        /** Roles allowed to view */
+        view?: string[];
+        /** Roles allowed to edit view configuration */
+        edit?: string[];
+    };
+    /** Whether the view is shared with all users */
+    is_public?: boolean;
+    /** Owner of the view (for personal views) */
+    owner?: string;
+    /** Custom view configuration */
+    config?: Record<string, any>;
+    /** AI context for view generation */
+    ai_context?: {
+        /** Purpose of this view */
+        intent?: string;
+        /** Target user role */
+        persona?: string;
+        /** Key insights to display */
+        insights?: string[];
+    };
+}
+/**
+ * Lightweight view reference
+ * Used in navigation, dropdowns, and view selectors
+ */
+export interface ViewReference {
+    /** View name/identifier */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Icon */
+    icon?: string;
+    /** View type */
+    type?: ViewType;
+    /** Whether this is the default view */
+    is_default?: boolean;
+}

package/dist/view.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * View Metadata Definition
+ *
+ * Defines the structure for list views, grid views, and other data visualization views
+ * in ObjectQL applications. Views define how data from objects is displayed to users
+ * including columns, filters, sorting, and available actions.
+ *
+ * Based on common patterns from Salesforce List Views, Airtable Views, and similar platforms.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=view.js.map

package/dist/view.js.map

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