@object-ui/data-objectstack 2.0.0 → 3.0.0

package/src/contracts.ts

@@ -0,0 +1,115 @@
+/**
+ * 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.
+ */
+
+export 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;
+}
+
+export interface PluginExport {
+  /** Export name */
+  name: string;
+  /** Export type */
+  type: 'component' | 'hook' | 'utility' | 'provider';
+  /** Description */
+  description?: string;
+}
+
+export interface PluginAPIContract {
+  /** Consumed data sources */
+  dataSources?: string[];
+  /** Required object schemas */
+  requiredSchemas?: string[];
+  /** Event subscriptions */
+  events?: string[];
+}
+
+export interface ContractValidationResult {
+  valid: boolean;
+  errors: ContractValidationError[];
+  warnings: string[];
+}
+
+export interface ContractValidationError {
+  field: string;
+  message: string;
+  code: string;
+}
+
+/**
+ * Validate a plugin contract against the ObjectStack spec.
+ */
+export function validatePluginContract(contract: PluginContract): ContractValidationResult {
+  const errors: ContractValidationError[] = [];
+  const warnings: string[] = [];
+
+  if (!contract.name || contract.name.trim().length === 0) {
+    errors.push({ field: 'name', message: 'Plugin name is required', code: 'MISSING_NAME' });
+  }
+
+  if (!contract.version || !/^\d+\.\d+\.\d+/.test(contract.version)) {
+    errors.push({ field: 'version', message: 'Valid semver version is required', code: 'INVALID_VERSION' });
+  }
+
+  if (!contract.exports || contract.exports.length === 0) {
+    errors.push({ field: 'exports', message: 'At least one export is required', code: 'NO_EXPORTS' });
+  }
+
+  if (contract.exports) {
+    const validTypes = ['component', 'hook', 'utility', 'provider'];
+    for (const exp of contract.exports) {
+      if (!exp.name) {
+        errors.push({ field: 'exports.name', message: 'Export name is required', code: 'MISSING_EXPORT_NAME' });
+      }
+      if (!validTypes.includes(exp.type)) {
+        errors.push({ field: 'exports.type', message: `Invalid export type: ${exp.type}`, code: 'INVALID_EXPORT_TYPE' });
+      }
+    }
+  }
+
+  if (!contract.permissions || contract.permissions.length === 0) {
+    warnings.push('No permissions declared — plugin will have minimal access');
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Generate a plugin contract manifest for marketplace publishing.
+ */
+export function generateContractManifest(contract: PluginContract): Record<string, unknown> {
+  return {
+    $schema: 'https://objectui.org/schemas/plugin-contract-v1.json',
+    name: contract.name,
+    version: contract.version,
+    peerDependencies: contract.peerDependencies ?? {},
+    exports: contract.exports.map(exp => ({
+      name: exp.name,
+      type: exp.type,
+      description: exp.description ?? '',
+    })),
+    permissions: contract.permissions ?? [],
+    api: contract.api ?? {},
+    generatedAt: new Date().toISOString(),
+  };
+}

package/src/index.ts

@@ -268,14 +268,16 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       };
     }
 
-    const resultObj = result as { value?: T[]; count?: number };
+    const resultObj = result as { records?: T[]; total?: number; value?: T[]; count?: number };
+    const records = resultObj.records || resultObj.value || [];
+    const total = resultObj.total ?? resultObj.count ?? records.length;
     return {
-      data: resultObj.value || [],
-      total: resultObj.count || (resultObj.value ? resultObj.value.length : 0),
+      data: records,
+      total,
       // Calculate page number safely
       page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
       pageSize: params?.$top,
-      hasMore: params?.$top ? (resultObj.value?.length || 0) === params.$top : false,
+      hasMore: params?.$top ? records.length === params.$top : false,
     };
   }
 
@@ -557,7 +559,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     try {
       // Use cache with automatic fetching
       const schema = await this.metadataCache.get(objectName, async () => {
-        const result: any = await this.client.meta.getObject(objectName);
+        const result: any = await this.client.meta.getItem('object', objectName);
         
         // Unwrap 'item' property if present (common API response wrapper)
         if (result && result.item) {
@@ -667,6 +669,56 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Get a page definition from ObjectStack.
+   * Uses the metadata API to fetch page layouts.
+   * Returns null if the server doesn't support page metadata.
+   */
+  async getPage(pageId: string): Promise<unknown | null> {
+    await this.connect();
+
+    try {
+      const cacheKey = `page:${pageId}`;
+      return await this.metadataCache.get(cacheKey, async () => {
+        const result: any = await this.client.meta.getItem('pages', pageId);
+        if (result && result.item) return result.item;
+        return result ?? null;
+      });
+    } catch {
+      // Server doesn't support page metadata — return null to fall back to static config
+      return null;
+    }
+  }
+
+  /**
+   * Get multiple metadata items from ObjectStack.
+   * Uses v3.0.0 metadata API pattern: getItems for batch retrieval.
+   */
+  async getItems(category: string, names: string[]): Promise<unknown[]> {
+    await this.connect();
+    
+    const results = await Promise.all(
+      names.map(async (name) => {
+        const cacheKey = `${category}:${name}`;
+        return this.metadataCache.get(cacheKey, async () => {
+          const result: any = await this.client.meta.getItem(category, name);
+          if (result && result.item) return result.item;
+          return result;
+        });
+      })
+    );
+    
+    return results;
+  }
+
+  /**
+   * 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 {
+    return this.metadataCache.getCachedSync(key);
+  }
+
   /**
    * Get cache statistics for monitoring performance.
    */
@@ -860,3 +912,19 @@ export {
 
 // Export cache types
 export type { CacheStats } from './cache/MetadataCache';
+
+// v3.0.0 Deep Integration modules
+export { CloudOperations } from './cloud';
+export type { CloudDeploymentConfig, CloudHostingConfig, CloudMarketplaceEntry } from './cloud';
+
+export { validatePluginContract, generateContractManifest } from './contracts';
+export type { PluginContract, PluginExport, PluginAPIContract, ContractValidationResult, ContractValidationError } from './contracts';
+
+export { IntegrationManager } from './integration';
+export type { IntegrationConfig, IntegrationTrigger, IntegrationProvider, SlackIntegrationConfig, EmailIntegrationConfig, WebhookIntegrationConfig } from './integration';
+
+export { SecurityManager } from './security';
+export type { SecurityPolicy, CSPConfig, AuditLogConfig, AuditEventType, DataMaskingConfig, DataMaskingRule, AuditLogEntry } from './security';
+
+export { createDefaultCanvasConfig, snapToGrid, calculateAutoLayout } from './studio';
+export type { StudioCanvasConfig, StudioPropertyEditor, StudioThemeBuilderConfig, StudioColorPalette, StudioTypographyPreset, StudioShadowPreset } from './studio';

package/src/integration.ts

@@ -0,0 +1,192 @@
+/**
+ * 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.
+ */
+
+export type IntegrationProvider = 'slack' | 'email' | 'webhook' | 'teams' | 'discord';
+
+export 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[];
+}
+
+export interface IntegrationTrigger {
+  /** Event name (e.g. 'record.created', 'record.updated') */
+  event: string;
+  /** Filter condition */
+  filter?: string;
+  /** Template for the message/payload */
+  template?: string;
+}
+
+export interface SlackIntegrationConfig extends IntegrationConfig {
+  provider: 'slack';
+  config: {
+    webhookUrl: string;
+    channel?: string;
+    username?: string;
+    iconEmoji?: string;
+  };
+}
+
+export interface EmailIntegrationConfig extends IntegrationConfig {
+  provider: 'email';
+  config: {
+    smtpHost: string;
+    smtpPort: number;
+    secure: boolean;
+    from: string;
+    to: string[];
+    subject?: string;
+  };
+}
+
+export 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.
+ */
+export class IntegrationManager {
+  private integrations: Map<string, IntegrationConfig> = new Map();
+
+  /**
+   * Register a new integration.
+   */
+  register(id: string, config: IntegrationConfig): void {
+    this.integrations.set(id, config);
+  }
+
+  /**
+   * Remove an integration.
+   */
+  unregister(id: string): void {
+    this.integrations.delete(id);
+  }
+
+  /**
+   * Get all registered integrations.
+   */
+  getAll(): Map<string, IntegrationConfig> {
+    return new Map(this.integrations);
+  }
+
+  /**
+   * Get integrations that match a specific event.
+   */
+  getForEvent(event: string): IntegrationConfig[] {
+    return Array.from(this.integrations.values()).filter(
+      (integration) =>
+        integration.enabled &&
+        integration.triggers?.some((t) => t.event === event)
+    );
+  }
+
+  /**
+   * Dispatch an event to all matching integrations.
+   * Returns results for each integration.
+   */
+  async dispatch(event: string, payload: Record<string, unknown>): Promise<Array<{ id: string; success: boolean; error?: string }>> {
+    const matching = this.getForEvent(event);
+    const results: Array<{ id: string; success: boolean; error?: string }> = [];
+
+    for (const [id, integration] of this.integrations) {
+      if (!matching.includes(integration)) continue;
+      
+      try {
+        await this.send(integration, payload);
+        results.push({ id, success: true });
+      } catch (err) {
+        results.push({ id, success: false, error: (err as Error).message });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Send payload to a specific integration.
+   */
+  private async send(integration: IntegrationConfig, payload: Record<string, unknown>): Promise<void> {
+    switch (integration.provider) {
+      case 'webhook': {
+        const cfg = integration.config as WebhookIntegrationConfig['config'];
+        const url = cfg.url;
+        // Validate URL - only allow http and https protocols
+        try {
+          const parsed = new URL(url);
+          if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            throw new Error(`Invalid URL protocol: ${parsed.protocol}`);
+          }
+        } catch (e) {
+          if (e instanceof TypeError) {
+            throw new Error(`Invalid webhook URL: ${url}`);
+          }
+          throw e;
+        }
+        await fetch(url, {
+          method: cfg.method,
+          headers: {
+            'Content-Type': 'application/json',
+            ...cfg.headers,
+          },
+          body: JSON.stringify(payload),
+        });
+        break;
+      }
+      case 'slack': {
+        const cfg = integration.config as SlackIntegrationConfig['config'];
+        const url = cfg.webhookUrl;
+        // Validate URL - only allow https protocol for Slack webhooks
+        try {
+          const parsed = new URL(url);
+          if (parsed.protocol !== 'https:') {
+            throw new Error(`Invalid Slack webhook URL protocol: ${parsed.protocol}`);
+          }
+        } catch (e) {
+          if (e instanceof TypeError) {
+            throw new Error(`Invalid Slack webhook URL: ${url}`);
+          }
+          throw e;
+        }
+        await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            channel: cfg.channel,
+            username: cfg.username,
+            icon_emoji: cfg.iconEmoji,
+            text: JSON.stringify(payload),
+          }),
+        });
+        break;
+      }
+      // Email and other providers would require server-side implementation
+      default:
+        break;
+    }
+  }
+}

package/src/security.ts

@@ -0,0 +1,230 @@
+/**
+ * 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.
+ */
+
+export interface SecurityPolicy {
+  /** Content Security Policy configuration */
+  csp?: CSPConfig;
+  /** Audit logging configuration */
+  auditLog?: AuditLogConfig;
+  /** Data masking rules */
+  dataMasking?: DataMaskingConfig;
+}
+
+export 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;
+}
+
+export 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';
+}
+
+export type AuditEventType =
+  | 'auth.login'
+  | 'auth.logout'
+  | 'auth.failed'
+  | 'data.create'
+  | 'data.read'
+  | 'data.update'
+  | 'data.delete'
+  | 'admin.config'
+  | 'admin.user'
+  | 'admin.role';
+
+export interface DataMaskingConfig {
+  /** Fields to mask */
+  rules: DataMaskingRule[];
+  /** Default masking character */
+  maskChar?: string;
+}
+
+export 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[];
+}
+
+export 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.
+ */
+export class SecurityManager {
+  private policy: SecurityPolicy;
+  private auditLog: AuditLogEntry[] = [];
+
+  constructor(policy: SecurityPolicy = {}) {
+    this.policy = policy;
+  }
+
+  /**
+   * Generate a CSP header string from the configuration.
+   */
+  generateCSPHeader(): string {
+    const csp = this.policy.csp;
+    if (!csp) return '';
+
+    const directives: string[] = [];
+    
+    if (csp.scriptSrc?.length) directives.push(`script-src ${csp.scriptSrc.join(' ')}`);
+    if (csp.styleSrc?.length) directives.push(`style-src ${csp.styleSrc.join(' ')}`);
+    if (csp.imgSrc?.length) directives.push(`img-src ${csp.imgSrc.join(' ')}`);
+    if (csp.connectSrc?.length) directives.push(`connect-src ${csp.connectSrc.join(' ')}`);
+    if (csp.fontSrc?.length) directives.push(`font-src ${csp.fontSrc.join(' ')}`);
+    if (csp.frameSrc?.length) directives.push(`frame-src ${csp.frameSrc.join(' ')}`);
+    if (csp.reportUri) directives.push(`report-uri ${csp.reportUri}`);
+
+    return directives.join('; ');
+  }
+
+  /**
+   * Record an audit log entry.
+   */
+  recordAudit(entry: Omit<AuditLogEntry, 'timestamp'>): void {
+    if (!this.policy.auditLog?.enabled) return;
+    if (this.policy.auditLog.events && !this.policy.auditLog.events.includes(entry.event)) return;
+
+    const fullEntry: AuditLogEntry = {
+      ...entry,
+      timestamp: new Date().toISOString(),
+    };
+
+    this.auditLog.push(fullEntry);
+
+    const dest = this.policy.auditLog.destination ?? 'console';
+    if (dest === 'console' || dest === 'both') {
+      console.info('[AUDIT]', fullEntry.event, fullEntry.userId, fullEntry.resource ?? '');
+    }
+  }
+
+  /**
+   * Get audit log entries.
+   */
+  getAuditLog(filter?: { event?: AuditEventType; userId?: string; since?: string }): AuditLogEntry[] {
+    let entries = [...this.auditLog];
+    if (filter?.event) entries = entries.filter(e => e.event === filter.event);
+    if (filter?.userId) entries = entries.filter(e => e.userId === filter.userId);
+    if (filter?.since) entries = entries.filter(e => e.timestamp >= filter.since!);
+    return entries;
+  }
+
+  /**
+   * Apply data masking to a record.
+   */
+  maskRecord(record: Record<string, unknown>, userRoles: string[] = []): Record<string, unknown> {
+    if (!this.policy.dataMasking?.rules?.length) return record;
+
+    const masked = { ...record };
+    const maskChar = this.policy.dataMasking.maskChar ?? '*';
+
+    for (const rule of this.policy.dataMasking.rules) {
+      if (!(rule.field in masked) || masked[rule.field] == null) continue;
+      
+      // Check role exemptions
+      if (rule.exemptRoles?.some(role => userRoles.includes(role))) continue;
+
+      const value = String(masked[rule.field]);
+      
+      switch (rule.strategy) {
+        case 'full':
+          masked[rule.field] = maskChar.repeat(value.length);
+          break;
+        case 'partial': {
+          const visible = rule.visibleChars ?? 4;
+          // Values shorter than visibleChars are fully masked for security
+          if (value.length <= visible) {
+            masked[rule.field] = maskChar.repeat(value.length);
+          } else {
+            masked[rule.field] = value.slice(0, visible) + maskChar.repeat(value.length - visible);
+          }
+          break;
+        }
+        case 'hash':
+          masked[rule.field] = `[HASHED:${simpleHash(value)}]`;
+          break;
+        case 'redact':
+          masked[rule.field] = '[REDACTED]';
+          break;
+      }
+    }
+
+    return masked;
+  }
+
+  /**
+   * Update the security policy.
+   */
+  updatePolicy(policy: Partial<SecurityPolicy>): void {
+    this.policy = { ...this.policy, ...policy };
+  }
+
+  /**
+   * Get current security policy.
+   */
+  getPolicy(): SecurityPolicy {
+    return { ...this.policy };
+  }
+}
+
+/**
+ * Simple hash function for data masking (not cryptographic).
+ */
+function simpleHash(str: string): string {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32-bit integer
+  }
+  return Math.abs(hash).toString(36);
+}