@object-ui/data-objectstack 0.5.0 → 3.0.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult } from '@object-ui/types';
+import { DataSource, QueryParams, QueryResult, FileUploadResult } from '@object-ui/types';
+export { FileUploadResult } from '@object-ui/types';
 
 /**
  * ObjectUI
@@ -158,6 +159,485 @@ interface CacheStats {
     hitRate: number;
 }
 
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Cloud namespace integration for @objectstack/spec v3.0.0
+ * Replaces the legacy Hub namespace for cloud deployment, hosting, and marketplace schemas.
+ */
+interface CloudDeploymentConfig {
+    /** Target environment */
+    environment: 'development' | 'staging' | 'production';
+    /** Cloud region */
+    region?: string;
+    /** Auto-scaling configuration */
+    scaling?: {
+        minInstances: number;
+        maxInstances: number;
+        targetCPU?: number;
+    };
+    /** Environment variables */
+    envVars?: Record<string, string>;
+}
+interface CloudHostingConfig {
+    /** Custom domain */
+    customDomain?: string;
+    /** SSL configuration */
+    ssl?: {
+        enabled: boolean;
+        autoRenew: boolean;
+    };
+    /** CDN configuration */
+    cdn?: {
+        enabled: boolean;
+        regions?: string[];
+    };
+}
+interface CloudMarketplaceEntry {
+    /** Plugin or app ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Version */
+    version: string;
+    /** Author */
+    author: string;
+    /** Category */
+    category: string;
+    /** Tags */
+    tags: string[];
+    /** Rating (1-5) */
+    rating?: number;
+    /** Install count */
+    installCount?: number;
+    /** Price (0 = free) */
+    price?: number;
+}
+/**
+ * Cloud operations helper for ObjectStack adapter.
+ * Provides methods for cloud deployment, hosting, and marketplace operations.
+ */
+declare class CloudOperations {
+    private getClient;
+    constructor(getClient: () => any);
+    /**
+     * Deploy an application to the cloud.
+     */
+    deploy(appId: string, config: CloudDeploymentConfig): Promise<{
+        deploymentId: string;
+        status: string;
+    }>;
+    /**
+     * Get deployment status.
+     */
+    getDeploymentStatus(deploymentId: string): Promise<{
+        status: string;
+        url?: string;
+    }>;
+    /**
+     * Search marketplace entries.
+     */
+    searchMarketplace(query?: string, category?: string): Promise<CloudMarketplaceEntry[]>;
+    /**
+     * Install a marketplace plugin.
+     */
+    installPlugin(pluginId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Contracts module integration for @objectstack/spec v3.0.0
+ * Provides plugin contract validation and marketplace publishing utilities.
+ */
+interface PluginContract {
+    /** Plugin name */
+    name: string;
+    /** Plugin version */
+    version: string;
+    /** Required peer dependencies */
+    peerDependencies?: Record<string, string>;
+    /** Exported component types */
+    exports: PluginExport[];
+    /** Required permissions */
+    permissions?: string[];
+    /** API surface contract */
+    api?: PluginAPIContract;
+}
+interface PluginExport {
+    /** Export name */
+    name: string;
+    /** Export type */
+    type: 'component' | 'hook' | 'utility' | 'provider';
+    /** Description */
+    description?: string;
+}
+interface PluginAPIContract {
+    /** Consumed data sources */
+    dataSources?: string[];
+    /** Required object schemas */
+    requiredSchemas?: string[];
+    /** Event subscriptions */
+    events?: string[];
+}
+interface ContractValidationResult {
+    valid: boolean;
+    errors: ContractValidationError[];
+    warnings: string[];
+}
+interface ContractValidationError {
+    field: string;
+    message: string;
+    code: string;
+}
+/**
+ * Validate a plugin contract against the ObjectStack spec.
+ */
+declare function validatePluginContract(contract: PluginContract): ContractValidationResult;
+/**
+ * Generate a plugin contract manifest for marketplace publishing.
+ */
+declare function generateContractManifest(contract: PluginContract): Record<string, unknown>;
+
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Integration module for @objectstack/spec v3.0.0
+ * Provides third-party service connectors for Slack, email, webhooks.
+ */
+type IntegrationProvider = 'slack' | 'email' | 'webhook' | 'teams' | 'discord';
+interface IntegrationConfig {
+    /** Integration provider type */
+    provider: IntegrationProvider;
+    /** Whether this integration is enabled */
+    enabled: boolean;
+    /** Provider-specific configuration */
+    config: Record<string, unknown>;
+    /** Event triggers */
+    triggers?: IntegrationTrigger[];
+}
+interface IntegrationTrigger {
+    /** Event name (e.g. 'record.created', 'record.updated') */
+    event: string;
+    /** Filter condition */
+    filter?: string;
+    /** Template for the message/payload */
+    template?: string;
+}
+interface SlackIntegrationConfig extends IntegrationConfig {
+    provider: 'slack';
+    config: {
+        webhookUrl: string;
+        channel?: string;
+        username?: string;
+        iconEmoji?: string;
+    };
+}
+interface EmailIntegrationConfig extends IntegrationConfig {
+    provider: 'email';
+    config: {
+        smtpHost: string;
+        smtpPort: number;
+        secure: boolean;
+        from: string;
+        to: string[];
+        subject?: string;
+    };
+}
+interface WebhookIntegrationConfig extends IntegrationConfig {
+    provider: 'webhook';
+    config: {
+        url: string;
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH';
+        headers?: Record<string, string>;
+        retryCount?: number;
+        retryDelay?: number;
+    };
+}
+/**
+ * Integration service manager.
+ * Manages third-party service connections and event dispatching.
+ */
+declare class IntegrationManager {
+    private integrations;
+    /**
+     * Register a new integration.
+     */
+    register(id: string, config: IntegrationConfig): void;
+    /**
+     * Remove an integration.
+     */
+    unregister(id: string): void;
+    /**
+     * Get all registered integrations.
+     */
+    getAll(): Map<string, IntegrationConfig>;
+    /**
+     * Get integrations that match a specific event.
+     */
+    getForEvent(event: string): IntegrationConfig[];
+    /**
+     * Dispatch an event to all matching integrations.
+     * Returns results for each integration.
+     */
+    dispatch(event: string, payload: Record<string, unknown>): Promise<Array<{
+        id: string;
+        success: boolean;
+        error?: string;
+    }>>;
+    /**
+     * Send payload to a specific integration.
+     */
+    private send;
+}
+
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Security module integration for @objectstack/spec v3.0.0
+ * Provides advanced security policies: CSP config, audit logging, data masking.
+ */
+interface SecurityPolicy {
+    /** Content Security Policy configuration */
+    csp?: CSPConfig;
+    /** Audit logging configuration */
+    auditLog?: AuditLogConfig;
+    /** Data masking rules */
+    dataMasking?: DataMaskingConfig;
+}
+interface CSPConfig {
+    /** Script sources */
+    scriptSrc: string[];
+    /** Style sources */
+    styleSrc: string[];
+    /** Image sources */
+    imgSrc: string[];
+    /** Connect sources (APIs, WebSockets) */
+    connectSrc: string[];
+    /** Font sources */
+    fontSrc: string[];
+    /** Frame sources */
+    frameSrc?: string[];
+    /** Report URI for violations */
+    reportUri?: string;
+}
+interface AuditLogConfig {
+    /** Whether audit logging is enabled */
+    enabled: boolean;
+    /** Events to audit */
+    events: AuditEventType[];
+    /** Log retention days */
+    retentionDays?: number;
+    /** External log destination */
+    destination?: 'console' | 'server' | 'both';
+}
+type AuditEventType = 'auth.login' | 'auth.logout' | 'auth.failed' | 'data.create' | 'data.read' | 'data.update' | 'data.delete' | 'admin.config' | 'admin.user' | 'admin.role';
+interface DataMaskingConfig {
+    /** Fields to mask */
+    rules: DataMaskingRule[];
+    /** Default masking character */
+    maskChar?: string;
+}
+interface DataMaskingRule {
+    /** Field name or pattern */
+    field: string;
+    /** Masking strategy */
+    strategy: 'full' | 'partial' | 'hash' | 'redact';
+    /** Number of visible characters (for partial masking) */
+    visibleChars?: number;
+    /** Roles that can see unmasked data */
+    exemptRoles?: string[];
+}
+interface AuditLogEntry {
+    /** Event timestamp */
+    timestamp: string;
+    /** Event type */
+    event: AuditEventType;
+    /** User who triggered the event */
+    userId: string;
+    /** Target resource */
+    resource?: string;
+    /** Record ID */
+    recordId?: string;
+    /** Additional details */
+    details?: Record<string, unknown>;
+    /** IP address */
+    ipAddress?: string;
+}
+/**
+ * Security policy manager.
+ * Handles CSP generation, audit logging, and data masking.
+ */
+declare class SecurityManager {
+    private policy;
+    private auditLog;
+    constructor(policy?: SecurityPolicy);
+    /**
+     * Generate a CSP header string from the configuration.
+     */
+    generateCSPHeader(): string;
+    /**
+     * Record an audit log entry.
+     */
+    recordAudit(entry: Omit<AuditLogEntry, 'timestamp'>): void;
+    /**
+     * Get audit log entries.
+     */
+    getAuditLog(filter?: {
+        event?: AuditEventType;
+        userId?: string;
+        since?: string;
+    }): AuditLogEntry[];
+    /**
+     * Apply data masking to a record.
+     */
+    maskRecord(record: Record<string, unknown>, userRoles?: string[]): Record<string, unknown>;
+    /**
+     * Update the security policy.
+     */
+    updatePolicy(policy: Partial<SecurityPolicy>): void;
+    /**
+     * Get current security policy.
+     */
+    getPolicy(): SecurityPolicy;
+}
+
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Studio module integration for @objectstack/spec v3.0.0
+ * Provides visual designer schema improvements: canvas, property editors, theme builder.
+ */
+interface StudioCanvasConfig {
+    /** Canvas width */
+    width: number;
+    /** Canvas height */
+    height: number;
+    /** Background type */
+    background: 'grid' | 'dots' | 'lines' | 'none';
+    /** Grid size in pixels */
+    gridSize: number;
+    /** Snap to grid */
+    snapToGrid: boolean;
+    /** Zoom range */
+    zoom: {
+        min: number;
+        max: number;
+        step: number;
+        current: number;
+    };
+    /** Pan offset */
+    panOffset: {
+        x: number;
+        y: number;
+    };
+    /** Show minimap */
+    showMinimap: boolean;
+    /** Minimap position */
+    minimapPosition: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+interface StudioPropertyEditor {
+    /** Property name */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Editor type */
+    type: 'text' | 'number' | 'boolean' | 'select' | 'color' | 'code' | 'expression';
+    /** Default value */
+    defaultValue?: unknown;
+    /** Options for select type */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Group/category */
+    group?: string;
+    /** Description */
+    description?: string;
+    /** Whether the property supports live preview */
+    livePreview?: boolean;
+}
+interface StudioThemeBuilderConfig {
+    /** Available color palettes */
+    palettes: StudioColorPalette[];
+    /** Typography presets */
+    typography: StudioTypographyPreset[];
+    /** Spacing scale */
+    spacing: number[];
+    /** Border radius options */
+    borderRadius: number[];
+    /** Shadow presets */
+    shadows: StudioShadowPreset[];
+}
+interface StudioColorPalette {
+    name: string;
+    colors: Record<string, string>;
+}
+interface StudioTypographyPreset {
+    name: string;
+    fontFamily: string;
+    fontSize: Record<string, string>;
+    fontWeight: Record<string, number>;
+    lineHeight: Record<string, string>;
+}
+interface StudioShadowPreset {
+    name: string;
+    value: string;
+}
+/**
+ * Default canvas configuration for designers.
+ */
+declare function createDefaultCanvasConfig(overrides?: Partial<StudioCanvasConfig>): StudioCanvasConfig;
+/**
+ * Snap a position to the grid.
+ */
+declare function snapToGrid(x: number, y: number, gridSize: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate auto-layout positions for a set of items.
+ * Uses a simple grid-based layout algorithm.
+ */
+declare function calculateAutoLayout(items: Array<{
+    id: string;
+    width: number;
+    height: number;
+}>, canvasWidth: number, padding?: number, gap?: number): Array<{
+    id: string;
+    x: number;
+    y: number;
+}>;
+
 /**
  * Connection state for monitoring
  */
@@ -188,6 +668,7 @@ type ConnectionStateListener = (event: ConnectionStateEvent) => void;
  * Event listener type for batch operation progress
  */
 type BatchProgressListener = (event: BatchProgressEvent) => void;
+
 /**
  * ObjectStack Data Source Adapter
  *
@@ -228,6 +709,8 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private maxReconnectAttempts;
     private reconnectDelay;
     private reconnectAttempts;
+    private baseUrl;
+    private token?;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -321,6 +804,53 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Get access to the underlying ObjectStack client for advanced operations.
      */
     getClient(): ObjectStackClient;
+    /**
+     * Get the discovery information from the connected server.
+     * Returns the capabilities and service status of the ObjectStack server.
+     *
+     * Note: This accesses an internal property of the ObjectStackClient.
+     * The discovery data is populated during client.connect() and cached.
+     *
+     * @returns Promise resolving to discovery data, or null if not connected
+     */
+    getDiscovery(): Promise<unknown | null>;
+    /**
+     * Get a view definition for an object.
+     * Attempts to fetch from the server metadata API.
+     * Falls back to null if the server doesn't provide view definitions,
+     * allowing the consumer to use static config.
+     *
+     * @param objectName - Object name
+     * @param viewId - View identifier
+     * @returns Promise resolving to the view definition or null
+     */
+    getView(objectName: string, viewId: string): Promise<unknown | null>;
+    /**
+     * Get an application definition by name or ID.
+     * Attempts to fetch from the server metadata API.
+     * Falls back to null if the server doesn't provide app definitions,
+     * allowing the consumer to use static config.
+     *
+     * @param appId - Application identifier
+     * @returns Promise resolving to the app definition or null
+     */
+    getApp(appId: string): Promise<unknown | null>;
+    /**
+     * Get a page definition from ObjectStack.
+     * Uses the metadata API to fetch page layouts.
+     * Returns null if the server doesn't support page metadata.
+     */
+    getPage(pageId: string): Promise<unknown | null>;
+    /**
+     * Get multiple metadata items from ObjectStack.
+     * Uses v3.0.0 metadata API pattern: getItems for batch retrieval.
+     */
+    getItems(category: string, names: string[]): Promise<unknown[]>;
+    /**
+     * Get cached metadata if available, without triggering a fetch.
+     * Uses v3.0.0 metadata API pattern: getCached for synchronous cache access.
+     */
+    getCached(key: string): unknown | undefined;
     /**
      * Get cache statistics for monitoring performance.
      */
@@ -335,6 +865,40 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Clear all cache entries and statistics.
      */
     clearCache(): void;
+    /**
+     * Upload a single file to a resource.
+     * Posts the file as multipart/form-data to the ObjectStack server.
+     *
+     * @param resource - The resource/object name to attach the file to
+     * @param file - File object or Blob to upload
+     * @param options - Additional upload options (recordId, fieldName, metadata)
+     * @returns Promise resolving to the upload result (file URL, metadata)
+     */
+    uploadFile(resource: string, file: File | Blob, options?: {
+        recordId?: string;
+        fieldName?: string;
+        metadata?: Record<string, unknown>;
+        onProgress?: (percent: number) => void;
+    }): Promise<FileUploadResult>;
+    /**
+     * Upload multiple files to a resource.
+     * Posts all files as a single multipart/form-data request.
+     *
+     * @param resource - The resource/object name to attach the files to
+     * @param files - Array of File objects or Blobs to upload
+     * @param options - Additional upload options
+     * @returns Promise resolving to array of upload results
+     */
+    uploadFiles(resource: string, files: (File | Blob)[], options?: {
+        recordId?: string;
+        fieldName?: string;
+        metadata?: Record<string, unknown>;
+        onProgress?: (percent: number) => void;
+    }): Promise<FileUploadResult[]>;
+    /**
+     * Get authorization headers from the adapter config.
+     */
+    private getAuthHeaders;
 }
 /**
  * Factory function to create an ObjectStack data source.
@@ -363,4 +927,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CacheStats, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, ValidationError, createErrorFromResponse, createObjectStackAdapter, isErrorType, isObjectStackError };
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, generateContractManifest, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };