@soulcraft/sdk 1.6.2 → 2.0.0

package/dist/server/handlers/commerce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commerce.js","sourceRoot":"","sources":["../../../src/server/handlers/commerce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAsFH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgC;IACpE,MAAM,QAAQ,GAAG,OAAO,EAAE,eAAe,CAAA;IAEzC,SAAS,eAAe;QACtB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAA;QACH,CAAC;QACD,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,aAAa,CAAC,cAAmB,EAAE,GAAmB;YAC1D,OAAO,eAAe,EAAE,CAAC,aAAa,CAAC,cAAc,CAAC,CAAA;QACxD,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,WAAgB;YACjC,OAAO,eAAe,EAAE,CAAC,YAAY,CAAC,WAAW,CAAC,CAAA;QACpD,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,SAAiB;YAChC,OAAO,eAAe,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;QAChD,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,eAAoB,EAAE,GAAmB;YACtD,OAAO,eAAe,EAAE,CAAC,QAAQ,CAAC;gBAChC,GAAG,eAAe;gBAClB,aAAa,EAAE,eAAe,CAAC,aAAa,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK;aAC/D,CAAC,CAAA;QACJ,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,SAAiB;YAChC,OAAO,eAAe,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;QAChD,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,WAAgB,EAAE,GAAmB;YACtD,OAAO,eAAe,EAAE,CAAC,YAAY,CAAC;gBACpC,GAAG,WAAW;gBACd,aAAa,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;aAC9B,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/server/handlers/config.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @module server/handlers/config
+ * @description Config namespace handler — platform configuration, plans, models,
+ * maintenance mode, and announcements.
+ *
+ * Absorbs Workshop `routes/config.ts`. The handler delegates to an injected
+ * `ConfigService` interface so products can plug in their own configuration
+ * source (Firestore, env vars, static JSON, etc.).
+ *
+ * Methods:
+ * - `get` — Full platform config (features, limits, maintenance, announcements)
+ * - `getUser` — User-specific configuration (plan, effective limits, models)
+ * - `getAnnouncements` — Active announcements for the user's plan
+ * - `isMaintenanceMode` — Whether the platform is in maintenance mode
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+/**
+ * Configuration service interface injected into the handler factory.
+ *
+ * Products implement this to connect to their configuration source. Workshop
+ * uses Firestore-backed config with plan-based overrides; Venue might use
+ * static env vars.
+ */
+export interface ConfigService {
+    /** Get the full platform configuration. */
+    getConfig(): Promise<{
+        global: {
+            freeTierEnabled: boolean;
+            maintenanceMode: boolean;
+            defaultModel: string;
+            soulcraftAccountUrl: string;
+        };
+        plans: Record<string, {
+            id: string;
+            displayName: string;
+            price: {
+                monthly: number;
+                yearly: number;
+            };
+            limits: Record<string, number>;
+            features: Record<string, unknown>;
+        }>;
+        models: Record<string, {
+            id: string;
+            name: string;
+            shortName: string;
+            pricing: {
+                input: number;
+                output: number;
+            };
+            maxTokens: number;
+            tiers: string[];
+            supportsThinking?: boolean;
+            bestFor?: string;
+        }>;
+    }>;
+    /** Get user-specific configuration (plan limits, available models). */
+    getUserConfig(userId: string, planId: string): Promise<{
+        plan: Record<string, unknown>;
+        effectiveLimits: Record<string, number>;
+        effectiveFeatures: Record<string, boolean>;
+        availableModels: Array<{
+            id: string;
+            name: string;
+            shortName: string;
+            maxTokens: number;
+            bestFor?: string;
+        }>;
+        hasOverrides: boolean;
+    }>;
+    /** Get active announcements, optionally filtered by plan. */
+    getAnnouncements(planId?: string): Promise<Array<{
+        id: string;
+        message: string;
+        type: string;
+    }>>;
+    /** Check if maintenance mode is active. */
+    isMaintenanceMode(): Promise<boolean>;
+    /** Invalidate the configuration cache (admin only). */
+    invalidateCache?(): void;
+}
+/**
+ * Billing service subset needed by the config handler to resolve the user's plan.
+ */
+export interface ConfigBillingService {
+    /** Get the user's subscription to determine their plan. */
+    getSubscription(billingId: string): Promise<{
+        plan?: string;
+    } | null>;
+}
+/**
+ * Options for {@link createConfigHandler}.
+ */
+export interface ConfigHandlerOptions {
+    /** Configuration service instance. */
+    configService: ConfigService;
+    /** Billing service for plan resolution. */
+    billing: ConfigBillingService;
+    /**
+     * Admin email check — returns `true` if the email belongs to a platform admin.
+     * Defaults to checking the `ADMIN_EMAILS` env var, falling back to `@soulcraft.com`.
+     */
+    isAdmin?: (email: string) => boolean;
+}
+/**
+ * Creates the `config` namespace handler.
+ *
+ * @param options - Config handler dependencies.
+ * @returns A {@link NamespaceProvider} implementing {@link ConfigNamespace}.
+ */
+export declare function createConfigHandler(options: ConfigHandlerOptions): NamespaceProvider;
+//# sourceMappingURL=config.d.ts.map

package/dist/server/handlers/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/config.ts"],"names":[],"mappings":"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"}

package/dist/server/handlers/config.js

@@ -0,0 +1,122 @@
+/**
+ * @module server/handlers/config
+ * @description Config namespace handler — platform configuration, plans, models,
+ * maintenance mode, and announcements.
+ *
+ * Absorbs Workshop `routes/config.ts`. The handler delegates to an injected
+ * `ConfigService` interface so products can plug in their own configuration
+ * source (Firestore, env vars, static JSON, etc.).
+ *
+ * Methods:
+ * - `get` — Full platform config (features, limits, maintenance, announcements)
+ * - `getUser` — User-specific configuration (plan, effective limits, models)
+ * - `getAnnouncements` — Active announcements for the user's plan
+ * - `isMaintenanceMode` — Whether the platform is in maintenance mode
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Default admin check
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Default admin check: uses `ADMIN_EMAILS` env var (comma-separated), falls
+ * back to `@soulcraft.com` domain.
+ *
+ * @param email - User email to check.
+ * @returns `true` if the user is a platform admin.
+ */
+function defaultIsAdmin(email) {
+    const adminEmails = process.env.ADMIN_EMAILS;
+    if (adminEmails) {
+        return adminEmails.split(',').map(e => e.trim().toLowerCase()).includes(email.toLowerCase());
+    }
+    return email.toLowerCase().endsWith('@soulcraft.com');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates the `config` namespace handler.
+ *
+ * @param options - Config handler dependencies.
+ * @returns A {@link NamespaceProvider} implementing {@link ConfigNamespace}.
+ */
+export function createConfigHandler(options) {
+    const { configService, billing, isAdmin = defaultIsAdmin } = options;
+    return {
+        /**
+         * Get the full platform configuration for the current user.
+         *
+         * Resolves the user's plan via billing, then assembles global config,
+         * user-specific limits/features, plan definitions, and model pricing.
+         *
+         * @param ctx - Handler context with authenticated user.
+         * @returns Complete config payload.
+         */
+        async get(ctx) {
+            const userId = ctx.user.emailHash;
+            const billingId = ctx.user.email;
+            const subscription = await billing.getSubscription(billingId);
+            const planId = subscription?.plan || 'free';
+            const appConfig = await configService.getConfig();
+            const userConfig = await configService.getUserConfig(userId, planId);
+            const announcements = await configService.getAnnouncements(planId);
+            return {
+                features: {
+                    freeTierEnabled: appConfig.global.freeTierEnabled,
+                    maintenanceMode: appConfig.global.maintenanceMode,
+                    ...userConfig.effectiveFeatures,
+                },
+                limits: {
+                    ...userConfig.effectiveLimits,
+                },
+                maintenance: appConfig.global.maintenanceMode
+                    ? { active: true }
+                    : undefined,
+                announcements: announcements.length > 0 ? announcements : undefined,
+            };
+        },
+        /**
+         * Get user-specific configuration overrides.
+         *
+         * Returns the user's effective plan, limits, features, and available models.
+         *
+         * @param ctx - Handler context with authenticated user.
+         * @returns User-level config overrides.
+         */
+        async getUser(ctx) {
+            const userId = ctx.user.emailHash;
+            const billingId = ctx.user.email;
+            const subscription = await billing.getSubscription(billingId);
+            const planId = subscription?.plan || 'free';
+            const userConfig = await configService.getUserConfig(userId, planId);
+            return {
+                planId,
+                plan: userConfig.plan,
+                effectiveLimits: userConfig.effectiveLimits,
+                effectiveFeatures: userConfig.effectiveFeatures,
+                availableModels: userConfig.availableModels,
+                hasOverrides: userConfig.hasOverrides,
+            };
+        },
+        /**
+         * Get active platform announcements.
+         *
+         * @param ctx - Handler context with authenticated user.
+         * @returns Array of active announcements.
+         */
+        async getAnnouncements(ctx) {
+            const billingId = ctx.user.email;
+            const subscription = await billing.getSubscription(billingId);
+            const planId = subscription?.plan || 'free';
+            return configService.getAnnouncements(planId);
+        },
+        /**
+         * Check if maintenance mode is active.
+         *
+         * @returns `true` if the platform is in maintenance mode.
+         */
+        async isMaintenanceMode() {
+            return configService.isMaintenanceMode();
+        },
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/server/handlers/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/server/handlers/config.ts"],"names":[],"mappings":"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"}

package/dist/server/handlers/export.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @module server/handlers/export
+ * @description Export namespace handler — project download, knowledge graph
+ * export, and PDF generation.
+ *
+ * Absorbs Workshop `routes/export.ts` and `routes/knowledge-graph.ts`. The
+ * handler delegates format serialization to an injected `ExportPipeline`
+ * interface, allowing products to register exporters for their supported formats.
+ *
+ * Methods:
+ * - `getExporters` — List available export formats
+ * - `downloadProject` — Download full project as zip/tar
+ * - `exportKnowledgeGraph` — Export graph in standard interchange formats
+ * - `exportPdf` — Generate a PDF from selected entities
+ * - `downloadPdf` — Download a previously generated PDF
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+import type { ExportFormat } from '../../namespaces.js';
+/**
+ * Export pipeline interface for serializing workspace data.
+ *
+ * Products implement this to register exporters for their supported formats.
+ * Workshop supports JSON, CSV, GraphML, GEXF, DOT, and PDF.
+ */
+export interface ExportPipeline {
+    /**
+     * List available export formats.
+     *
+     * @returns Array of format descriptors.
+     */
+    getFormats(): ExportFormat[];
+    /**
+     * Export the knowledge graph in a standard format.
+     *
+     * @param format - Target format ID.
+     * @param brain - Brainy instance to read from.
+     * @param options - Export options (type filters, etc.).
+     * @returns Serialized graph data.
+     */
+    exportGraph(format: string, brain: any, options?: {
+        types?: string[];
+    }): Promise<string | ArrayBuffer>;
+    /**
+     * Generate a PDF from selected entities.
+     *
+     * @param entityIds - Entities to include.
+     * @param brain - Brainy instance to read from.
+     * @param options - PDF options.
+     * @returns The PDF as binary data.
+     */
+    exportPdf?(entityIds: string[], brain: any, options?: {
+        template?: string;
+    }): Promise<ArrayBuffer>;
+}
+/**
+ * Options for {@link createExportHandler}.
+ */
+export interface ExportHandlerOptions {
+    /**
+     * Export pipeline implementation.
+     * If not provided, basic JSON/CSV export is available; other formats throw.
+     */
+    pipeline?: ExportPipeline;
+}
+/**
+ * Creates the `export` namespace handler.
+ *
+ * @param options - Optional export handler dependencies.
+ * @returns A {@link NamespaceProvider} implementing {@link ExportNamespace}.
+ */
+export declare function createExportHandler(options?: ExportHandlerOptions): NamespaceProvider;
+//# sourceMappingURL=export.d.ts.map

package/dist/server/handlers/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,wBAAwB,CAAA;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAMvD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,UAAU,IAAI,YAAY,EAAE,CAAA;IAE5B;;;;;;;OAOG;IACH,WAAW,CACT,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,GAAG,EACV,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC7B,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC,CAAA;IAEhC;;;;;;;OAOG;IACH,SAAS,CAAC,CACR,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,EAAE,GAAG,EACV,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9B,OAAO,CAAC,WAAW,CAAC,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AAmED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,iBAAiB,CA0HrF"}

package/dist/server/handlers/export.js

@@ -0,0 +1,175 @@
+/**
+ * @module server/handlers/export
+ * @description Export namespace handler — project download, knowledge graph
+ * export, and PDF generation.
+ *
+ * Absorbs Workshop `routes/export.ts` and `routes/knowledge-graph.ts`. The
+ * handler delegates format serialization to an injected `ExportPipeline`
+ * interface, allowing products to register exporters for their supported formats.
+ *
+ * Methods:
+ * - `getExporters` — List available export formats
+ * - `downloadProject` — Download full project as zip/tar
+ * - `exportKnowledgeGraph` — Export graph in standard interchange formats
+ * - `exportPdf` — Generate a PDF from selected entities
+ * - `downloadPdf` — Download a previously generated PDF
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Built-in minimal exporters
+// ─────────────────────────────────────────────────────────────────────────────
+/** Built-in export formats available without an external pipeline. */
+const BUILTIN_FORMATS = [
+    { id: 'json', name: 'JSON', extension: '.json', mimeType: 'application/json' },
+    { id: 'csv', name: 'CSV', extension: '.csv', mimeType: 'text/csv' },
+];
+/**
+ * Built-in JSON export — serializes all entities as a JSON array.
+ *
+ * @param brain - Brainy instance.
+ * @param options - Export options.
+ * @returns JSON string.
+ */
+async function exportJson(brain, options) {
+    let entities = await brain.find({ limit: 50000, excludeVFS: true });
+    if (options?.types && options.types.length > 0) {
+        const typeSet = new Set(options.types.map((t) => t.toLowerCase()));
+        entities = entities.filter((e) => typeSet.has((e.type || '').toLowerCase()));
+    }
+    return JSON.stringify(entities, null, 2);
+}
+/**
+ * Built-in CSV export — serializes entities as CSV with id, type, name, description columns.
+ *
+ * @param brain - Brainy instance.
+ * @param options - Export options.
+ * @returns CSV string.
+ */
+async function exportCsv(brain, options) {
+    let entities = await brain.find({ limit: 50000, excludeVFS: true });
+    if (options?.types && options.types.length > 0) {
+        const typeSet = new Set(options.types.map((t) => t.toLowerCase()));
+        entities = entities.filter((e) => typeSet.has((e.type || '').toLowerCase()));
+    }
+    const header = 'id,type,name,description';
+    const rows = entities.map((e) => {
+        const meta = e.metadata || {};
+        const name = (meta.name || e.data || '').toString().replace(/"/g, '""');
+        const desc = (meta.description || '').toString().replace(/"/g, '""');
+        return `"${e.id}","${e.type || ''}","${name}","${desc}"`;
+    });
+    return [header, ...rows].join('\n');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// PDF download cache
+// ─────────────────────────────────────────────────────────────────────────────
+/** Temporary cache for generated PDFs. */
+const pdfCache = new Map();
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates the `export` namespace handler.
+ *
+ * @param options - Optional export handler dependencies.
+ * @returns A {@link NamespaceProvider} implementing {@link ExportNamespace}.
+ */
+export function createExportHandler(options) {
+    const pipeline = options?.pipeline;
+    return {
+        /**
+         * List all available export formats.
+         *
+         * Merges built-in formats (JSON, CSV) with any formats from the pipeline.
+         *
+         * @returns Array of export format descriptors.
+         */
+        async getExporters() {
+            if (pipeline)
+                return pipeline.getFormats();
+            return BUILTIN_FORMATS;
+        },
+        /**
+         * Download the entire project as a zip or tar archive.
+         *
+         * This requires binary streaming — the actual archive assembly happens at
+         * the transport/route layer. The handler collects the data.
+         *
+         * @param downloadOptions - Archive format options.
+         * @param ctx - Handler context.
+         * @returns Archive as binary data.
+         */
+        async downloadProject(downloadOptions, ctx) {
+            // Project download requires zip/tar assembly at the transport layer.
+            // For now, return the project data as a JSON blob that the Hono adapter
+            // can wrap in a zip.
+            const { brain } = ctx;
+            const entities = await brain.find({ limit: 50000, excludeVFS: true });
+            const manifest = {
+                version: 1,
+                format: 'workshop-export',
+                createdAt: new Date().toISOString(),
+                entityCount: entities.length,
+            };
+            const json = JSON.stringify({ manifest, entities }, null, 2);
+            const encoder = new TextEncoder();
+            return encoder.encode(json).buffer;
+        },
+        /**
+         * Export the knowledge graph in a standard interchange format.
+         *
+         * Uses the external pipeline for formats like GraphML, GEXF, DOT.
+         * Falls back to built-in JSON/CSV for basic formats.
+         *
+         * @param format - Target format ID.
+         * @param exportOptions - Type filters.
+         * @param ctx - Handler context.
+         * @returns Serialized graph data.
+         */
+        async exportKnowledgeGraph(format, exportOptions, ctx) {
+            const { brain } = ctx;
+            // Built-in formats
+            if (format === 'json')
+                return exportJson(brain, exportOptions);
+            if (format === 'csv')
+                return exportCsv(brain, exportOptions);
+            // Delegate to pipeline for advanced formats
+            if (pipeline)
+                return pipeline.exportGraph(format, brain, exportOptions);
+            throw new Error(`Export format "${format}" is not supported. Available formats: json, csv`);
+        },
+        /**
+         * Generate a PDF from selected entities.
+         *
+         * @param entityIds - Entities to include.
+         * @param pdfOptions - PDF template options.
+         * @param ctx - Handler context.
+         * @returns Download URL for the generated PDF.
+         */
+        async exportPdf(entityIds, pdfOptions, ctx) {
+            if (!pipeline?.exportPdf) {
+                throw new Error('PDF export is not configured — provide an ExportPipeline with exportPdf support');
+            }
+            const pdfData = await pipeline.exportPdf(entityIds, ctx.brain, pdfOptions);
+            const exportId = `pdf-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            pdfCache.set(exportId, pdfData);
+            // Auto-cleanup after 10 minutes
+            setTimeout(() => pdfCache.delete(exportId), 10 * 60 * 1000);
+            return { downloadUrl: `__pdf__:${exportId}` };
+        },
+        /**
+         * Download a previously generated PDF.
+         *
+         * @param exportId - The export ID from `exportPdf`.
+         * @returns PDF as binary data.
+         */
+        async downloadPdf(exportId) {
+            const data = pdfCache.get(exportId);
+            if (!data) {
+                throw new Error(`PDF export "${exportId}" not found or expired`);
+            }
+            pdfCache.delete(exportId); // One-time download
+            return data;
+        },
+    };
+}
+//# sourceMappingURL=export.js.map

package/dist/server/handlers/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../../src/server/handlers/export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA+DH,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAEhF,sEAAsE;AACtE,MAAM,eAAe,GAAmB;IACtC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE;IAC9E,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE;CACpE,CAAA;AAED;;;;;;GAMG;AACH,KAAK,UAAU,UAAU,CAAC,KAAU,EAAE,OAA8B;IAClE,IAAI,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;IAEnE,IAAI,OAAO,EAAE,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;QAC1E,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;IACnF,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,SAAS,CAAC,KAAU,EAAE,OAA8B;IACjE,IAAI,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;IAEnE,IAAI,OAAO,EAAE,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;QAC1E,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;IACnF,CAAC;IAED,MAAM,MAAM,GAAG,0BAA0B,CAAA;IACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE;QACnC,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAA;QAC7B,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACvE,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACpE,OAAO,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,IAAI,EAAE,MAAM,IAAI,MAAM,IAAI,GAAG,CAAA;IAC1D,CAAC,CAAC,CAAA;IAEF,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACrC,CAAC;AAED,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF,0CAA0C;AAC1C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAA;AAE/C,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA8B;IAChE,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,CAAA;IAElC,OAAO;QACL;;;;;;WAMG;QACH,KAAK,CAAC,YAAY;YAChB,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAC,UAAU,EAAE,CAAA;YAC1C,OAAO,eAAe,CAAA;QACxB,CAAC;QAED;;;;;;;;;WASG;QACH,KAAK,CAAC,eAAe,CACnB,eAAuD,EACvD,GAAmB;YAEnB,qEAAqE;YACrE,wEAAwE;YACxE,qBAAqB;YACrB,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAA;YAErB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;YACrE,MAAM,QAAQ,GAAG;gBACf,OAAO,EAAE,CAAC;gBACV,MAAM,EAAE,iBAAiB;gBACzB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,WAAW,EAAE,QAAQ,CAAC,MAAM;aAC7B,CAAA;YAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;YAC5D,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;YACjC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAqB,CAAA;QACnD,CAAC;QAED;;;;;;;;;;WAUG;QACH,KAAK,CAAC,oBAAoB,CACxB,MAAc,EACd,aAA+C,EAC/C,GAAmB;YAEnB,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAA;YAErB,mBAAmB;YACnB,IAAI,MAAM,KAAK,MAAM;gBAAE,OAAO,UAAU,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;YAC9D,IAAI,MAAM,KAAK,KAAK;gBAAE,OAAO,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;YAE5D,4CAA4C;YAC5C,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,CAAA;YAEvE,MAAM,IAAI,KAAK,CACb,kBAAkB,MAAM,kDAAkD,CAC3E,CAAA;QACH,CAAC;QAED;;;;;;;WAOG;QACH,KAAK,CAAC,SAAS,CACb,SAAmB,EACnB,UAA6C,EAC7C,GAAmB;YAEnB,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAA;YACH,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;YAC1E,MAAM,QAAQ,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAA;YAC9E,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;YAE/B,gCAAgC;YAChC,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;YAE3D,OAAO,EAAE,WAAW,EAAE,WAAW,QAAQ,EAAE,EAAE,CAAA;QAC/C,CAAC;QAED;;;;;WAKG;QACH,KAAK,CAAC,WAAW,CAAC,QAAgB;YAChC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACnC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,eAAe,QAAQ,wBAAwB,CAAC,CAAA;YAClE,CAAC;YACD,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA,CAAC,oBAAoB;YAC9C,OAAO,IAAI,CAAA;QACb,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/server/handlers/formats.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @module server/handlers/formats
+ * @description Formats namespace handler — server-side format conversion and
+ * validation for Soulcraft portable formats (wdoc, wslide, wviz, wquiz).
+ *
+ * Data transformation only — visual rendering lives in `@soulcraft/views`.
+ * This handler delegates to an injected `FormatConverter` interface so products
+ * can register converters for different source→output format pairs.
+ *
+ * Methods:
+ * - `convert` — Convert a Soulcraft format document to an output format
+ * - `validate` — Validate a document against its format schema
+ * - `getOutputFormats` — List available output formats
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+/**
+ * Format converter interface.
+ *
+ * Products register converters for different source→output format pairs.
+ * For example, Workshop might register a puppeteer-based wdoc→pdf converter.
+ */
+export interface FormatConverter {
+    /**
+     * Convert a document from one format to another.
+     *
+     * @param sourceFormat - Source format ID (e.g. 'wdoc', 'wslide').
+     * @param outputFormat - Target format ID (e.g. 'pdf', 'html', 'markdown').
+     * @param content - The source document (JSON or string).
+     * @param options - Format-specific conversion options.
+     * @returns Converted content (string for text, ArrayBuffer for binary).
+     */
+    convert(sourceFormat: string, outputFormat: string, content: unknown, options?: Record<string, unknown>): Promise<string | ArrayBuffer>;
+    /**
+     * Validate a document against its format schema.
+     *
+     * @param format - Format ID (e.g. 'wdoc', 'wviz').
+     * @param document - The document to validate.
+     * @returns Validation result.
+     */
+    validate(format: string, document: unknown): Promise<{
+        valid: boolean;
+        errors: Array<{
+            path: string;
+            message: string;
+        }>;
+    }>;
+    /**
+     * List available output formats and their supported source formats.
+     *
+     * @returns Array of output format descriptors.
+     */
+    getOutputFormats(): Promise<Array<{
+        id: string;
+        name: string;
+        extension: string;
+        mimeType: string;
+        sourceFormats: string[];
+    }>>;
+}
+/**
+ * Options for {@link createFormatsHandler}.
+ */
+export interface FormatsHandlerOptions {
+    /**
+     * Format converter implementation.
+     * If not provided, all methods throw with a "not configured" error.
+     */
+    converter: FormatConverter;
+}
+/**
+ * Creates the `formats` namespace handler.
+ *
+ * @param options - Formats handler dependencies. If omitted, all methods throw.
+ * @returns A {@link NamespaceProvider} implementing {@link FormatsNamespace}.
+ */
+export declare function createFormatsHandler(options?: FormatsHandlerOptions): NamespaceProvider;
+//# sourceMappingURL=formats.d.ts.map

package/dist/server/handlers/formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/formats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAM/D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,OAAO,CACL,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC,CAAA;IAEhC;;;;;;OAMG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAA;IAEhF;;;;OAIG;IACH,gBAAgB,IAAI,OAAO,CAAC,KAAK,CAAC;QAChC,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,QAAQ,EAAE,MAAM,CAAA;QAChB,aAAa,EAAE,MAAM,EAAE,CAAA;KACxB,CAAC,CAAC,CAAA;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,SAAS,EAAE,eAAe,CAAA;CAC3B;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,iBAAiB,CA0DvF"}

package/dist/server/handlers/formats.js

@@ -0,0 +1,65 @@
+/**
+ * @module server/handlers/formats
+ * @description Formats namespace handler — server-side format conversion and
+ * validation for Soulcraft portable formats (wdoc, wslide, wviz, wquiz).
+ *
+ * Data transformation only — visual rendering lives in `@soulcraft/views`.
+ * This handler delegates to an injected `FormatConverter` interface so products
+ * can register converters for different source→output format pairs.
+ *
+ * Methods:
+ * - `convert` — Convert a Soulcraft format document to an output format
+ * - `validate` — Validate a document against its format schema
+ * - `getOutputFormats` — List available output formats
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates the `formats` namespace handler.
+ *
+ * @param options - Formats handler dependencies. If omitted, all methods throw.
+ * @returns A {@link NamespaceProvider} implementing {@link FormatsNamespace}.
+ */
+export function createFormatsHandler(options) {
+    const converter = options?.converter;
+    function requireConverter() {
+        if (!converter) {
+            throw new Error('formats namespace is not configured — provide a FormatConverter via providers.formats. ' +
+                'Install @soulcraft/formats for schema validation or register custom converters.');
+        }
+        return converter;
+    }
+    return {
+        /**
+         * Convert a Soulcraft format document to an output format.
+         *
+         * @param sourceFormat - Source format ID.
+         * @param outputFormat - Target format ID.
+         * @param convertOptions - Content and conversion options.
+         * @returns Converted content.
+         */
+        async convert(sourceFormat, outputFormat, convertOptions) {
+            return requireConverter().convert(sourceFormat, outputFormat, convertOptions.content, convertOptions.options);
+        },
+        /**
+         * Validate a document against its format schema.
+         *
+         * @param format - Format ID (e.g. 'wdoc', 'wviz').
+         * @param document - The document to validate.
+         * @returns Validation result with errors.
+         */
+        async validate(format, document) {
+            return requireConverter().validate(format, document);
+        },
+        /**
+         * List available output formats and supported conversions.
+         *
+         * @returns Array of output format descriptors.
+         */
+        async getOutputFormats() {
+            return requireConverter().getOutputFormats();
+        },
+    };
+}
+//# sourceMappingURL=formats.js.map