@nikkory/vibe-engine 4.0.0

package/dist/types/section-storage.types.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Section Storage Types
+ * Type definitions for hybrid storage (JSON + Cloud)
+ *
+ * @packageDocumentation
+ * @module types/section-storage
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { SectionTemplate, TemplateVisibility } from './section-template.types';
+/**
+ * Storage configuration based on visibility
+ *
+ * @remarks
+ * Storage location is determined by template visibility:
+ * - private: JSON file only (local machine, never synced)
+ * - team: JSON + Cloud sync to team workspace
+ * - public: JSON + Cloud sync + Marketplace listing
+ *
+ * @example
+ * ```typescript
+ * const config: StorageConfig = {
+ *   visibility: 'team',
+ *   localPath: '~/.nikkory/templates/hero-team-001.json',
+ *   cloudSyncEnabled: true,
+ *   lastSyncedAt: new Date('2024-01-15T10:30:00Z')
+ * };
+ * ```
+ */
+export interface StorageConfig {
+    /** Template visibility (determines storage behavior) */
+    readonly visibility: TemplateVisibility;
+    /** Local file path for JSON storage */
+    readonly localPath: string;
+    /** Whether cloud sync is enabled */
+    readonly cloudSyncEnabled: boolean;
+    /** Last successful sync timestamp */
+    readonly lastSyncedAt?: Date;
+}
+/**
+ * Local storage metadata
+ */
+export interface LocalStorageMetadata {
+    /** File path */
+    readonly path: string;
+    /** File size in bytes */
+    readonly size: number;
+    /** Created timestamp */
+    readonly createdAt: Date;
+    /** Modified timestamp */
+    readonly modifiedAt: Date;
+    /** File checksum (MD5) */
+    readonly checksum: string;
+}
+/**
+ * Local storage entry
+ */
+export interface LocalStorageEntry {
+    /** Template data */
+    readonly template: SectionTemplate;
+    /** Storage metadata */
+    readonly metadata: LocalStorageMetadata;
+    /** Whether file is dirty (unsaved changes) */
+    readonly isDirty: boolean;
+}
+/**
+ * Local storage directory configuration
+ */
+export interface LocalStorageConfig {
+    /** Base directory for templates */
+    readonly baseDir: string;
+    /** Subdirectory for private templates */
+    readonly privateDir: string;
+    /** Subdirectory for team templates */
+    readonly teamDir: string;
+    /** Subdirectory for public templates */
+    readonly publicDir: string;
+    /** Maximum storage size in bytes */
+    readonly maxStorageSize: number;
+    /** Whether to auto-backup on save */
+    readonly autoBackup: boolean;
+}
+/**
+ * Cloud sync status
+ */
+export type SyncStatus = 'idle' | 'syncing' | 'synced' | 'error' | 'conflict';
+/**
+ * Cloud sync metadata
+ */
+export interface CloudSyncMetadata {
+    /** Cloud storage ID */
+    readonly cloudId: string;
+    /** Sync status */
+    readonly status: SyncStatus;
+    /** Last sync attempt timestamp */
+    readonly lastAttemptAt?: Date;
+    /** Last successful sync timestamp */
+    readonly lastSuccessAt?: Date;
+    /** Sync error message (if status is 'error') */
+    readonly errorMessage?: string;
+    /** Server version (for conflict detection) */
+    readonly serverVersion?: number;
+    /** Local version */
+    readonly localVersion: number;
+}
+/**
+ * Sync conflict information
+ */
+export interface SyncConflict {
+    /** Template ID with conflict */
+    readonly templateId: string;
+    /** Local version */
+    readonly localTemplate: SectionTemplate;
+    /** Server version */
+    readonly serverTemplate: SectionTemplate;
+    /** Conflict detected timestamp */
+    readonly detectedAt: Date;
+    /** Resolution status */
+    readonly resolved: boolean;
+    /** Resolution choice (if resolved) */
+    readonly resolution?: 'keep-local' | 'keep-server' | 'merge';
+}
+/**
+ * Cloud sync configuration
+ */
+export interface CloudSyncConfig {
+    /** API endpoint for sync */
+    readonly apiEndpoint: string;
+    /** Sync interval in milliseconds */
+    readonly syncIntervalMs: number;
+    /** Whether auto-sync is enabled */
+    readonly autoSyncEnabled: boolean;
+    /** Retry count on failure */
+    readonly maxRetries: number;
+    /** Retry delay in milliseconds */
+    readonly retryDelayMs: number;
+}
+/**
+ * Save template input
+ */
+export interface SaveTemplateInput {
+    /** Template to save */
+    readonly template: SectionTemplate;
+    /** Whether to force overwrite */
+    readonly overwrite?: boolean;
+    /** Whether to sync to cloud immediately */
+    readonly syncImmediately?: boolean;
+}
+/**
+ * Save template result
+ */
+export interface SaveTemplateResult {
+    /** Whether save was successful */
+    readonly success: boolean;
+    /** Saved template ID */
+    readonly templateId: string;
+    /** Local file path */
+    readonly localPath: string;
+    /** Whether cloud sync was triggered */
+    readonly syncTriggered: boolean;
+    /** Error message (if not successful) */
+    readonly error?: string;
+}
+/**
+ * Load template input
+ */
+export interface LoadTemplateInput {
+    /** Template ID to load */
+    readonly templateId: string;
+    /** Whether to prefer cloud version */
+    readonly preferCloud?: boolean;
+    /** Whether to validate after load */
+    readonly validate?: boolean;
+}
+/**
+ * Load template result
+ */
+export interface LoadTemplateResult {
+    /** Whether load was successful */
+    readonly success: boolean;
+    /** Loaded template (if successful) */
+    readonly template?: SectionTemplate;
+    /** Source of loaded template */
+    readonly source: 'local' | 'cloud';
+    /** Storage metadata */
+    readonly metadata?: LocalStorageMetadata;
+    /** Error message (if not successful) */
+    readonly error?: string;
+}
+/**
+ * Delete template input
+ */
+export interface DeleteTemplateInput {
+    /** Template ID to delete */
+    readonly templateId: string;
+    /** Whether to delete from cloud as well */
+    readonly deleteFromCloud?: boolean;
+}
+/**
+ * Delete template result
+ */
+export interface DeleteTemplateResult {
+    /** Whether delete was successful */
+    readonly success: boolean;
+    /** Template ID deleted */
+    readonly templateId: string;
+    /** Whether cloud deletion was successful */
+    readonly cloudDeleted?: boolean;
+    /** Error message (if not successful) */
+    readonly error?: string;
+}
+/**
+ * Storage event types
+ */
+export type StorageEventType = 'template-saved' | 'template-loaded' | 'template-deleted' | 'sync-started' | 'sync-completed' | 'sync-failed' | 'conflict-detected' | 'conflict-resolved';
+/**
+ * Storage event
+ */
+export interface StorageEvent {
+    /** Event type */
+    readonly type: StorageEventType;
+    /** Template ID (if applicable) */
+    readonly templateId?: string;
+    /** Timestamp */
+    readonly timestamp: Date;
+    /** Event payload */
+    readonly payload?: Record<string, unknown>;
+}
+/**
+ * Storage manager interface
+ *
+ * @remarks
+ * Main interface for hybrid storage operations.
+ * Implementations handle visibility-based routing automatically.
+ */
+export interface IStorageManager {
+    /**
+     * Save template to storage
+     * @param input Save input
+     * @returns Save result
+     */
+    saveTemplate(input: SaveTemplateInput): Promise<SaveTemplateResult>;
+    /**
+     * Load template from storage
+     * @param input Load input
+     * @returns Load result
+     */
+    loadTemplate(input: LoadTemplateInput): Promise<LoadTemplateResult>;
+    /**
+     * Delete template from storage
+     * @param input Delete input
+     * @returns Delete result
+     */
+    deleteTemplate(input: DeleteTemplateInput): Promise<DeleteTemplateResult>;
+    /**
+     * List all templates matching criteria
+     * @param visibility Filter by visibility (optional)
+     * @returns Array of template IDs
+     */
+    listTemplates(visibility?: TemplateVisibility): Promise<readonly string[]>;
+    /**
+     * Trigger cloud sync for all pending changes
+     * @returns Sync result
+     */
+    syncToCloud(): Promise<{
+        synced: number;
+        failed: number;
+        conflicts: number;
+    }>;
+    /**
+     * Get storage statistics
+     * @returns Storage statistics
+     */
+    getStats(): Promise<StorageStats>;
+}
+/**
+ * Storage statistics
+ */
+export interface StorageStats {
+    /** Total templates count */
+    readonly totalTemplates: number;
+    /** Private templates count */
+    readonly privateCount: number;
+    /** Team templates count */
+    readonly teamCount: number;
+    /** Public templates count */
+    readonly publicCount: number;
+    /** Total storage size in bytes */
+    readonly totalSize: number;
+    /** Last sync timestamp */
+    readonly lastSyncAt?: Date;
+    /** Pending sync count */
+    readonly pendingSyncCount: number;
+    /** Unresolved conflicts count */
+    readonly conflictCount: number;
+}
+//# sourceMappingURL=section-storage.types.d.ts.map

package/dist/types/section-template.types.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Section Template Types
+ * Type definitions for section templates with metadata
+ *
+ * @packageDocumentation
+ * @module types/section-template
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { SectionConfig, SectionFactors } from './section.types';
+/**
+ * Template visibility determines storage location and sharing
+ *
+ * @remarks
+ * - private: JSON file only (local machine)
+ * - team: JSON + Cloud sync to team workspace
+ * - public: JSON + Cloud sync + Marketplace listing
+ */
+export type TemplateVisibility = 'private' | 'team' | 'public';
+/**
+ * Template Metadata - 8 Fields
+ *
+ * @remarks
+ * Metadata for section templates, enabling discovery, versioning,
+ * and proper attribution.
+ *
+ * @example
+ * ```typescript
+ * const metadata: TemplateMetadata = {
+ *   templateId: 'hero-gradient-001',
+ *   templateName: 'Gradient Hero Section',
+ *   description: 'A hero section with gradient background and CTA',
+ *   author: 'nikkory-team',
+ *   version: '1.0.0',
+ *   tags: ['hero', 'gradient', 'cta', 'landing'],
+ *   visibility: 'public',
+ *   thumbnail: 'https://cdn.nikkory.com/templates/hero-gradient.png'
+ * };
+ * ```
+ */
+export interface TemplateMetadata {
+    /** Unique template identifier (e.g., 'hero-gradient-001') */
+    readonly templateId: string;
+    /** Human-readable template name */
+    readonly templateName: string;
+    /** Template description for discovery */
+    readonly description: string;
+    /** Template author (username or organization) */
+    readonly author: string;
+    /** Semantic version (e.g., '1.0.0') */
+    readonly version: string;
+    /** Search tags for discovery */
+    readonly tags: readonly string[];
+    /** Visibility: private (local only), team, public */
+    readonly visibility: TemplateVisibility;
+    /** Preview thumbnail URL (optional) */
+    readonly thumbnail?: string;
+}
+/**
+ * Complete SectionTemplate - SectionConfig + 8 Metadata fields
+ *
+ * @remarks
+ * Extends SectionConfig with TemplateMetadata for complete template definition.
+ * Total fields: 14 (SectionConfig) + 8 (TemplateMetadata) = 22 fields
+ *
+ * @example
+ * ```typescript
+ * const template: SectionTemplate = {
+ *   // SectionConfig (14 fields)
+ *   sectionId: 'hero-1',
+ *   sectionType: 'hero',
+ *   title: 'Welcome to Our Platform',
+ *   subtitle: 'Build amazing experiences',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   layout: 'flex',
+ *   columns: 2,
+ *   spacing: 'lg',
+ *   slots: [],
+ *   itemCount: 1,
+ *   showCta: true,
+ *   showMedia: true,
+ *   styleOverrides: undefined,
+ *
+ *   // TemplateMetadata (8 fields)
+ *   templateId: 'hero-material-001',
+ *   templateName: 'Material Hero',
+ *   description: 'Material Design 3 hero section',
+ *   author: 'nikkory-team',
+ *   version: '1.0.0',
+ *   tags: ['hero', 'material', 'enterprise'],
+ *   visibility: 'public',
+ *   thumbnail: 'https://cdn.nikkory.com/templates/hero-material.png'
+ * };
+ * ```
+ */
+export interface SectionTemplate extends SectionConfig, TemplateMetadata {
+}
+/**
+ * Section template with factors included
+ *
+ * @remarks
+ * Complete template definition including styling factors.
+ * Use this when saving templates with their factor configuration.
+ */
+export interface SectionTemplateWithFactors extends SectionTemplate {
+    /** Section styling factors */
+    readonly factors: SectionFactors;
+}
+/**
+ * Collection of templates grouped by category
+ */
+export interface TemplateCollection {
+    /** Collection identifier */
+    readonly collectionId: string;
+    /** Collection name */
+    readonly name: string;
+    /** Collection description */
+    readonly description: string;
+    /** Collection author */
+    readonly author: string;
+    /** Templates in collection */
+    readonly templates: readonly SectionTemplate[];
+    /** Collection visibility */
+    readonly visibility: TemplateVisibility;
+    /** Created timestamp */
+    readonly createdAt: Date;
+    /** Last updated timestamp */
+    readonly updatedAt: Date;
+}
+/**
+ * Template search criteria
+ */
+export interface TemplateSearchCriteria {
+    /** Search query (matches name, description, tags) */
+    readonly query?: string;
+    /** Filter by section type */
+    readonly sectionType?: string;
+    /** Filter by design system */
+    readonly designSystem?: string;
+    /** Filter by tier */
+    readonly tier?: string;
+    /** Filter by author */
+    readonly author?: string;
+    /** Filter by visibility */
+    readonly visibility?: TemplateVisibility;
+    /** Filter by tags */
+    readonly tags?: readonly string[];
+    /** Pagination offset */
+    readonly offset?: number;
+    /** Pagination limit */
+    readonly limit?: number;
+}
+/**
+ * Template search result
+ */
+export interface TemplateSearchResult {
+    /** Matching templates */
+    readonly templates: readonly SectionTemplate[];
+    /** Total count (before pagination) */
+    readonly totalCount: number;
+    /** Applied offset */
+    readonly offset: number;
+    /** Applied limit */
+    readonly limit: number;
+    /** Has more results */
+    readonly hasMore: boolean;
+}
+//# sourceMappingURL=section-template.types.d.ts.map