@vantageos/convex-doc-forge 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog — @vantageos/convex-doc-forge
+
+All notable changes to this package follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) + [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-06-19 (P1 data layer)
+
+### Added
+
+- `convex.config.ts` — `defineComponent("docForge")`, install via `app.use(docForge)`.
+- `schema.ts` — 3 tables: `templates`, `render_jobs`, `render_audit` with full indexes (`by_tenant`, `by_tenant_team`, `by_tenant_type`, `by_template`, `by_job`, `by_tenant_status`).
+- `queries.ts` — `list_templates`, `get_template`, `list_render_history` (all with `returns` validators).
+- `mutations.ts` — `upsert_template`, `queue_render` (public); `_set_job_rendering`, `_complete_render_job`, `_fail_render_job`, `_write_audit` (internal).
+- `actions.ts` — `render_now` (`"use node"`) — fetches Railway renderer, stores output in Convex storage, writes audit row, returns signed URL TTL 7 days. Env: `CONVEX_DOC_FORGE_RENDERER_URL` + `CONVEX_DOC_FORGE_RENDERER_KEY`.
+- `src/__tests__/` — 30 vitest tests covering all queries, mutations, and the action with mocked fetch (0 network calls).
+- `src/_generated/` — generated stubs (`dataModel.ts`, `server.ts`, `api.ts`) compatible with Convex 1.41.
+
+### Notes
+
+- tsc: 0 errors (`npx tsc --noEmit`).
+- Test ratio: 30/30 PASS (`npm test`).
+- No secrets in source. All renderer credentials via env vars.
+- `v.any()` used only for `input_schema` and `context` fields (JSON Schema + render context are unbounded by design — documented trade-off).

package/LICENSE

@@ -0,0 +1,110 @@
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+Abbreviation
+
+FSL-1.1-Apache-2.0
+
+Notice
+
+Copyright 2026 VantageOS (ElPi Corp)
+
+Terms and Conditions
+
+Licensor:             VantageOS (ElPi Corp)
+
+Licensed Work:        VantagePeers
+                      The Licensed Work is (c) 2026 VantageOS (ElPi Corp)
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided Your use does not include offering the Licensed
+                      Work to third parties as a hosted or managed service
+                      where the service provides users with access to any
+                      substantial set of the features or functionality of the
+                      Licensed Work.
+
+Change Date:          2028-04-03 (two years from publication)
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: contact@vantageos.com
+
+License text below is provided for informational purposes only.
+
+---
+
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+1. Purpose
+
+This license gives you broad permission to use, modify, and share this
+software, with one important condition: you may not use it to compete with us.
+
+2. Acceptance
+
+To use the software, you must agree to these terms. If you do not agree, you
+may not use the software.
+
+3. Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-
+sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+4. Limitations
+
+You may not make the functionality of the software available to third parties
+as a service, or otherwise use the software to provide a service to third
+parties that competes with the licensor.
+
+5. Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license or becomes able to license, to make, have made, use, sell, offer for
+sale, import, and have imported the software, in each case subject to the
+limitations and conditions in this license.
+
+6. Fair Use
+
+This license is not intended to limit any rights you may have under applicable
+fair use or other laws.
+
+7. No Other Rights
+
+These terms do not grant any other rights. The licensor reserves all rights not
+expressly granted.
+
+8. Termination
+
+Your license is automatically terminated if you violate the terms. However, if
+you cure the violation within 30 days of discovering it, your license is
+reinstated retroactively.
+
+9. Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED.
+
+10. Limitation of Liability
+
+TO THE EXTENT PERMITTED BY LAW, THE LICENSOR IS NOT LIABLE FOR ANY DAMAGES
+ARISING FROM THE USE OF THE SOFTWARE.
+
+11. Change Date and License
+
+After the Change Date, the licensor grants you the rights under the Change
+License.
+
+12. Definitions
+
+"Compete" means providing a product or service that is substantially similar
+to, or a replacement for, all or a significant portion of the Licensed Work.
+
+---
+
+Apache License, Version 2.0
+
+After the Change Date (2028-04-03), this software will be available under the
+Apache License, Version 2.0. See https://www.apache.org/licenses/LICENSE-2.0
+for full text.

package/README.md

@@ -0,0 +1,169 @@
+# @vantageos/convex-doc-forge
+
+Convex component — **data layer** for the VantageDocForge trinity.
+
+Stores templates, render jobs, and audit records. Calls the Railway renderer sidecar (`vantage-doc-forge-renderer`) via a Convex action over HTTP. Pattern: `@convex-dev/rag` (Convex handles data; external service handles compute).
+
+---
+
+## Architecture
+
+```
+Consumer (vantage-immo / vCRM / MCP server)
+        │
+        ▼  ctx.runAction(components.docForge.actions.render_now, {...})
+@vantageos/convex-doc-forge (this package)
+  - templates table    ← template metadata + asset_storage_id
+  - render_jobs table  ← job status machine (queued → rendering → done|failed)
+  - render_audit table ← immutable audit log per render
+  - render_now action  → HTTP POST /v1/render  →  Railway renderer sidecar
+        │
+        ▼
+vantage-doc-forge-renderer (Python Railway)
+  docxtpl + python-pptx + LibreOffice headless
+```
+
+---
+
+## Install
+
+```bash
+npm install @vantageos/convex-doc-forge
+```
+
+In your Convex deployment's `convex/convex.config.ts`:
+
+```ts
+import { defineApp } from "convex/server";
+import docForge from "@vantageos/convex-doc-forge/convex.config";
+
+const app = defineApp();
+app.use(docForge);
+export default app;
+```
+
+---
+
+## Required env vars (set in Convex dashboard)
+
+| Variable | Description |
+|---|---|
+| `CONVEX_DOC_FORGE_RENDERER_URL` | Base URL of the Railway renderer (e.g. `https://doc-forge.railway.app`) |
+| `CONVEX_DOC_FORGE_RENDERER_KEY` | Bearer token for renderer auth |
+
+---
+
+## Schema
+
+### `templates`
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | string | Template name (unique per tenant+team) |
+| `team` | string | Logical group (e.g. `iris-rh`, `pujol`) |
+| `tenant_id` | string | Clerk org ID |
+| `template_type` | `"doc-binary"` | Always `doc-binary` (V1) |
+| `renderer_kind` | `"docxtpl" \| "python-pptx" \| "jinja2-html"` | Which renderer to use |
+| `input_schema` | object | JSON Schema for context validation |
+| `asset_storage_id` | Id<"_storage"> | Convex file storage reference to the .docx/.pptx asset |
+| `output_formats` | string[] | e.g. `["docx", "pdf"]` |
+| `version` | string | SemVer |
+
+### `render_jobs`
+
+Status machine: `queued` → `rendering` → `done` | `failed`
+
+### `render_audit`
+
+Immutable log. One row per successful render. `context_hash` = SHA-256 of `JSON.stringify(context)`.
+
+---
+
+## Functions
+
+### Queries (public)
+
+```ts
+// List templates for a tenant (optionally filter by team or type)
+docForge.queries.list_templates({ tenant_id, team?, type? })
+
+// Get a single template by ID
+docForge.queries.get_template({ template_id })
+
+// Audit history for a tenant (optionally filter by template or timestamp)
+docForge.queries.list_render_history({ tenant_id, template_id?, since? })
+```
+
+### Mutations (public)
+
+```ts
+// Insert or update a template (upsert by name+team+tenant_id)
+docForge.mutations.upsert_template({
+  name, team, tenant_id, renderer_kind,
+  input_schema, asset_storage_id, output_formats, version, createdBy
+})
+
+// Queue an async render job (returns job ID, use list_render_history to poll)
+docForge.mutations.queue_render({ template_id, context, output_format, createdBy })
+```
+
+### Actions (public)
+
+```ts
+// Synchronous render: calls Railway renderer, stores output, writes audit
+// Returns signed URL (TTL 7 days)
+docForge.actions.render_now({
+  template_id, context, output_format,
+  actor,           // Clerk subject
+  source?          // "manual" | "workflow" | "agent"  (default "manual")
+})
+// → { output_url, render_job_id, duration_ms, pages? }
+```
+
+---
+
+## Renderer contract
+
+`render_now` calls the sidecar:
+
+```
+POST {CONVEX_DOC_FORGE_RENDERER_URL}/v1/render
+Authorization: Bearer {CONVEX_DOC_FORGE_RENDERER_KEY}
+Content-Type: application/json
+
+{
+  "template_url": "<Convex signed URL for the .docx asset>",
+  "context": { ...JSON data matching input_schema... },
+  "output_format": "pdf" | "docx" | "pptx" | "doc"
+}
+
+→ {
+    "output_bytes": "<base64>",   // OR
+    "output_url": "<url>",
+    "duration_ms": 420,
+    "pages": 3
+  }
+```
+
+---
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run (30 tests, no network)
+```
+
+---
+
+## Open decisions (see `decisions/rfc-rendering-engine.md`)
+
+1. **npm scope**: `@vantageos/convex-doc-forge` (internal) — migrate to `@convex-dev/doc-forge` if submitted upstream.
+2. **Asset storage**: Convex `_storage` (default) — hook for R2/S3 when volume justifies.
+3. **Sync vs async**: `render_now` is sync (<10s); `queue_render` + subscription for async flows.
+4. **Consumer install**: pnpm workspace monorepo (fleet) vs npm public (external).
+
+---
+
+Orchestrator: Hephaistos — VantageOS Team | 2026-06-19

package/convex.config.ts

@@ -0,0 +1,22 @@
+import { defineComponent } from "convex/server";
+
+/**
+ * @vantageos/convex-doc-forge — data layer component.
+ *
+ * Install in a consumer Convex deployment:
+ *
+ * ```ts
+ * // convex/convex.config.ts (consumer app)
+ * import { defineApp } from "convex/server";
+ * import docForge from "@vantageos/convex-doc-forge/convex.config";
+ *
+ * const app = defineApp();
+ * app.use(docForge);
+ * export default app;
+ * ```
+ *
+ * Then reference via `components.docForge` in consumer functions.
+ */
+const docForge = defineComponent("docForge");
+
+export default docForge;

package/dist/_generated/api.d.ts

@@ -0,0 +1,3 @@
+export declare const api: any;
+export declare const internal: any;
+//# sourceMappingURL=api.d.ts.map

package/dist/_generated/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/_generated/api.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,GAAG,EAAE,GAAY,CAAC;AAG/B,eAAO,MAAM,QAAQ,EAAE,GAAY,CAAC"}

package/dist/_generated/api.js

@@ -0,0 +1,13 @@
+/* eslint-disable */
+/**
+ * Generated API utility for @vantageos/convex-doc-forge.
+ *
+ * In a real deployment, regenerate with `npx convex dev`.
+ */
+import { anyApi } from "convex/server";
+// anyApi is typed as `any` at runtime so it satisfies all function reference lookups.
+// This mirrors the canonical Convex generated pattern.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const api = anyApi;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const internal = anyApi;

package/dist/_generated/dataModel.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generated data model types for @vantageos/convex-doc-forge.
+ *
+ * In a real deployment, regenerate with `npx convex dev`.
+ */
+import type { DataModelFromSchemaDefinition, DocumentByName, TableNamesInDataModel, SystemTableNames } from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+export type TableNames = TableNamesInDataModel<DataModel>;
+export type Doc<TableName extends TableNames> = DocumentByName<DataModel, TableName>;
+export type Id<TableName extends TableNames | SystemTableNames> = GenericId<TableName>;
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;
+//# sourceMappingURL=dataModel.d.ts.map

package/dist/_generated/dataModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataModel.d.ts","sourceRoot":"","sources":["../../src/_generated/dataModel.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,OAAO,KAAK,EACV,6BAA6B,EAC7B,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,MAAM,MAAM,cAAc,CAAC;AAElC,MAAM,MAAM,UAAU,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;AAE1D,MAAM,MAAM,GAAG,CAAC,SAAS,SAAS,UAAU,IAAI,cAAc,CAC5D,SAAS,EACT,SAAS,CACV,CAAC;AAEF,MAAM,MAAM,EAAE,CAAC,SAAS,SAAS,UAAU,GAAG,gBAAgB,IAC5D,SAAS,CAAC,SAAS,CAAC,CAAC;AAEvB,MAAM,MAAM,SAAS,GAAG,6BAA6B,CAAC,OAAO,MAAM,CAAC,CAAC"}

package/dist/_generated/dataModel.js

@@ -0,0 +1 @@
+export {};

package/dist/_generated/server.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generated server utilities for @vantageos/convex-doc-forge.
+ *
+ * In a real deployment, regenerate with `npx convex dev`.
+ */
+import type { ActionBuilder, HttpActionBuilder, MutationBuilder, QueryBuilder, GenericActionCtx, GenericMutationCtx, GenericQueryCtx, GenericDatabaseReader, GenericDatabaseWriter } from "convex/server";
+import type { DataModel } from "./dataModel.js";
+export declare const query: QueryBuilder<DataModel, "public">;
+export declare const internalQuery: QueryBuilder<DataModel, "internal">;
+export declare const mutation: MutationBuilder<DataModel, "public">;
+export declare const internalMutation: MutationBuilder<DataModel, "internal">;
+export declare const action: ActionBuilder<DataModel, "public">;
+export declare const internalAction: ActionBuilder<DataModel, "internal">;
+export declare const httpAction: HttpActionBuilder;
+export type QueryCtx = GenericQueryCtx<DataModel>;
+export type MutationCtx = GenericMutationCtx<DataModel>;
+export type ActionCtx = GenericActionCtx<DataModel>;
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;
+//# sourceMappingURL=server.d.ts.map

package/dist/_generated/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/_generated/server.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAUvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,eAAO,MAAM,KAAK,EAAE,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAgB,CAAC;AACrE,eAAO,MAAM,aAAa,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,CACxC,CAAC;AACvB,eAAO,MAAM,QAAQ,EAAE,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAmB,CAAC;AAC9E,eAAO,MAAM,gBAAgB,EAAE,eAAe,CAAC,SAAS,EAAE,UAAU,CAC3C,CAAC;AAC1B,eAAO,MAAM,MAAM,EAAE,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAiB,CAAC;AACxE,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,SAAS,EAAE,UAAU,CACzC,CAAC;AACxB,eAAO,MAAM,UAAU,EAAE,iBAAqC,CAAC;AAE/D,MAAM,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;AACxD,MAAM,MAAM,SAAS,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC"}

package/dist/_generated/server.js

@@ -0,0 +1,8 @@
+import { actionGeneric, httpActionGeneric, queryGeneric, mutationGeneric, internalActionGeneric, internalMutationGeneric, internalQueryGeneric, } from "convex/server";
+export const query = queryGeneric;
+export const internalQuery = internalQueryGeneric;
+export const mutation = mutationGeneric;
+export const internalMutation = internalMutationGeneric;
+export const action = actionGeneric;
+export const internalAction = internalActionGeneric;
+export const httpAction = httpActionGeneric;

package/dist/actions.d.ts

@@ -0,0 +1,20 @@
+export declare function renderNowHandler(ctx: any, args: {
+    template_id: string;
+    context: unknown;
+    output_format: string;
+    actor: string;
+    source?: "manual" | "workflow" | "agent";
+}): Promise<{
+    output_url: string;
+    render_job_id: string;
+    duration_ms: number;
+    pages?: number;
+}>;
+export declare const render_now: import("convex/server").RegisteredAction<"public", {
+    source?: "manual" | "workflow" | "agent" | undefined;
+    template_id: import("convex/values").GenericId<"templates">;
+    context: any;
+    output_format: string;
+    actor: string;
+}, any>;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAgCA,wBAAsB,gBAAgB,CAEpC,GAAG,EAAE,GAAG,EACR,IAAI,EAAE;IACJ,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;CAC1C,GACA,OAAO,CAAC;IACT,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAoID;AAMD,eAAO,MAAM,UAAU;;;;;;OAsBrB,CAAC"}

package/dist/actions.js

@@ -0,0 +1,176 @@
+"use node";
+import { v } from "convex/values";
+import { action } from "./_generated/server";
+import { internal } from "./_generated/api";
+// ---------------------------------------------------------------------------
+// SHA-256 helper (Node built-in crypto)
+// ---------------------------------------------------------------------------
+async function sha256hex(input) {
+    const { createHash } = await import("node:crypto");
+    return createHash("sha256").update(input).digest("hex");
+}
+// ---------------------------------------------------------------------------
+// renderNowHandler — exported for unit testing
+// ---------------------------------------------------------------------------
+const SIGNED_URL_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export async function renderNowHandler(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ctx, args) {
+    const rendererUrl = process.env.CONVEX_DOC_FORGE_RENDERER_URL;
+    const rendererKey = process.env.CONVEX_DOC_FORGE_RENDERER_KEY;
+    if (!rendererUrl)
+        throw new Error("CONVEX_DOC_FORGE_RENDERER_URL not set");
+    if (!rendererKey)
+        throw new Error("CONVEX_DOC_FORGE_RENDERER_KEY not set");
+    // 1. Load template
+    const template = await ctx.runQuery(internal.queries.get_template, {
+        template_id: args.template_id,
+    });
+    if (template === null)
+        throw new Error("Template not found");
+    if (!template.output_formats.includes(args.output_format)) {
+        throw new Error(`output_format '${args.output_format}' not supported. ` +
+            `Supported: ${template.output_formats.join(", ")}`);
+    }
+    // 2. Get signed URL for the binary asset
+    const assetUrl = await ctx.storage.getUrl(template.asset_storage_id);
+    if (!assetUrl)
+        throw new Error("Asset storage URL unavailable");
+    // 3. Create a queued job
+    const jobId = await ctx.runMutation(internal.mutations.queue_render, {
+        template_id: args.template_id,
+        context: args.context,
+        output_format: args.output_format,
+        createdBy: args.actor,
+    });
+    // 4. Transition to rendering
+    await ctx.runMutation(internal.mutations._set_job_rendering, {
+        job_id: jobId,
+    });
+    const contextHash = await sha256hex(JSON.stringify(args.context));
+    const startTs = Date.now();
+    try {
+        // 5. Call renderer Railway
+        const rendererRes = await fetch(`${rendererUrl}/v1/render`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${rendererKey}`,
+            },
+            body: JSON.stringify({
+                template_url: assetUrl,
+                context: args.context,
+                output_format: args.output_format,
+            }),
+        });
+        if (!rendererRes.ok) {
+            const errText = await rendererRes.text().catch(() => "<no body>");
+            throw new Error(`Renderer returned ${rendererRes.status}: ${errText}`);
+        }
+        const rendererJson = (await rendererRes.json());
+        const duration_ms = rendererJson.duration_ms ?? Date.now() - startTs;
+        // 6. Store output in Convex storage
+        let outputStorageId;
+        let signedUrl;
+        if (rendererJson.output_bytes) {
+            const binaryStr = atob(rendererJson.output_bytes);
+            const bytes = new Uint8Array(binaryStr.length);
+            for (let i = 0; i < binaryStr.length; i++) {
+                bytes[i] = binaryStr.charCodeAt(i);
+            }
+            const mimeType = mimeForFormat(args.output_format);
+            const blob = new Blob([bytes], { type: mimeType });
+            outputStorageId = await ctx.storage.store(blob);
+            const url = await ctx.storage.getUrl(outputStorageId);
+            if (!url)
+                throw new Error("Failed to get signed URL after storage");
+            signedUrl = url;
+        }
+        else if (rendererJson.output_url) {
+            const downloadRes = await fetch(rendererJson.output_url);
+            if (!downloadRes.ok)
+                throw new Error(`Failed to download output from renderer URL: ${downloadRes.status}`);
+            const mimeType = mimeForFormat(args.output_format);
+            const blob = new Blob([await downloadRes.arrayBuffer()], {
+                type: mimeType,
+            });
+            outputStorageId = await ctx.storage.store(blob);
+            const url = await ctx.storage.getUrl(outputStorageId);
+            if (!url)
+                throw new Error("Failed to get signed URL after storage");
+            signedUrl = url;
+        }
+        else {
+            throw new Error("Renderer response missing both output_bytes and output_url");
+        }
+        // 7. Mark job done
+        await ctx.runMutation(internal.mutations._complete_render_job, {
+            job_id: jobId,
+            output_storage_id: outputStorageId,
+        });
+        // 8. Write audit record
+        const expiresAt = Date.now() + SIGNED_URL_TTL_MS;
+        await ctx.runMutation(internal.mutations._write_audit, {
+            render_job_id: jobId,
+            tenant_id: template.tenant_id,
+            template_id: args.template_id,
+            template_version: template.version,
+            context_hash: contextHash,
+            output_signed_url: signedUrl,
+            expires_at: expiresAt,
+            actor: args.actor,
+            source: args.source ?? "manual",
+        });
+        return {
+            output_url: signedUrl,
+            render_job_id: jobId,
+            duration_ms,
+            pages: rendererJson.pages,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        await ctx.runMutation(internal.mutations._fail_render_job, {
+            job_id: jobId,
+            error: message,
+        });
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Convex registration
+// ---------------------------------------------------------------------------
+export const render_now = action({
+    args: {
+        template_id: v.id("templates"),
+        context: v.any(),
+        output_format: v.string(),
+        actor: v.string(),
+        source: v.optional(v.union(v.literal("manual"), v.literal("workflow"), v.literal("agent"))),
+    },
+    returns: v.object({
+        output_url: v.string(),
+        render_job_id: v.id("render_jobs"),
+        duration_ms: v.number(),
+        pages: v.optional(v.number()),
+    }),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handler: renderNowHandler,
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function mimeForFormat(format) {
+    switch (format.toLowerCase()) {
+        case "pdf":
+            return "application/pdf";
+        case "docx":
+            return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+        case "pptx":
+            return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+        case "doc":
+            return "application/msword";
+        default:
+            return "application/octet-stream";
+    }
+}

package/dist/convex.config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @vantageos/convex-doc-forge — data layer component.
+ *
+ * Install in a consumer Convex deployment:
+ *
+ * ```ts
+ * // convex/convex.config.ts (consumer app)
+ * import { defineApp } from "convex/server";
+ * import docForge from "@vantageos/convex-doc-forge/convex.config";
+ *
+ * const app = defineApp();
+ * app.use(docForge);
+ * export default app;
+ * ```
+ *
+ * Then reference via `components.docForge` in consumer functions.
+ */
+declare const docForge: import("convex/server").ComponentDefinition<any, {}>;
+export default docForge;
+//# sourceMappingURL=convex.config.d.ts.map

package/dist/convex.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex.config.d.ts","sourceRoot":"","sources":["../convex.config.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,QAAQ,sDAA8B,CAAC;AAE7C,eAAe,QAAQ,CAAC"}

package/dist/convex.config.js

@@ -0,0 +1,20 @@
+import { defineComponent } from "convex/server";
+/**
+ * @vantageos/convex-doc-forge — data layer component.
+ *
+ * Install in a consumer Convex deployment:
+ *
+ * ```ts
+ * // convex/convex.config.ts (consumer app)
+ * import { defineApp } from "convex/server";
+ * import docForge from "@vantageos/convex-doc-forge/convex.config";
+ *
+ * const app = defineApp();
+ * app.use(docForge);
+ * export default app;
+ * ```
+ *
+ * Then reference via `components.docForge` in consumer functions.
+ */
+const docForge = defineComponent("docForge");
+export default docForge;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @vantageos/convex-doc-forge — public re-exports.
+ *
+ * Consumer apps import functions via the component API object, not directly.
+ * This barrel is provided for type-only imports.
+ */
+export * from "./queries";
+export * from "./mutations";
+export * from "./actions";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}