@vantageos/convex-doc-forge 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.2] - 2026-06-19
+
+### Added
+
+- `mutations.ts`: public `generate_upload_url` mutation — enables host apps / consumers to upload a template binary into the component storage namespace, then register it via `upsert_template`. Unblocks `render_now` E2E and template upload (Marie/Iris RH critical path).
+  - Takes no args, returns `v.string()` (signed upload URL).
+  - Pure addition, no breaking change, `peerDependencies.convex` unchanged (`>=1.17.0`).
+  - V8-pure: no `"use node"`, no `node:*` imports (component constraint).
+- `scripts/smoke-render.md`: canonical, reusable fleet smoke harness documenting the full upload→upsert→render CLI sequence.
+
+### Notes
+
+- Discovered via consumer-1 dogfood (Omega install on vibrant-ibex-858): `upsert_template` required `asset_storage_id: v.id("_storage")` but there was no public path for a consumer to obtain a storage ID in the component namespace.
+- tsc: 0 errors. Test ratio: 31/31 PASS.
+
 ## [0.1.1] - 2026-06-19
 
 ### Fixed

package/README.md

@@ -122,6 +122,66 @@ docForge.actions.render_now({
 
 ---
 
+## Asset ingestion
+
+Before calling `upsert_template`, the host app must upload the `.docx`/`.pptx` binary into the component's isolated storage namespace and obtain a `storageId`. The three-step flow:
+
+**Step 1 — get a signed upload URL** (from a host app action):
+
+```ts
+// convex/myActions.ts
+import { action } from "./_generated/server";
+import { components } from "./_generated/api";
+
+export const getDocForgeUploadUrl = action({
+  args: {},
+  handler: async (ctx) =>
+    await ctx.runMutation(components.docForge.mutations.generate_upload_url, {}),
+});
+```
+
+**Step 2 — POST the raw bytes to the signed URL**:
+
+```bash
+curl -X POST "<uploadUrl>" \
+  -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
+  --data-binary @template.docx
+# → { "storageId": "kg2abc..." }
+```
+
+**Step 3 — register the asset as a template** and then render:
+
+```ts
+const templateId = await ctx.runMutation(
+  components.docForge.mutations.upsert_template,
+  {
+    name: "proposition-audit",
+    team: "iris-rh",
+    tenant_id: "org_clerk_abc",
+    renderer_kind: "docxtpl",
+    input_schema: { type: "object", properties: { client_name: { type: "string" } } },
+    asset_storage_id: storageId,   // from step 2
+    output_formats: ["pdf", "docx"],
+    version: "1.0.0",
+    createdBy: "clerk_user_id",
+  },
+);
+
+// Now render_now works end-to-end:
+const result = await ctx.runAction(components.docForge.actions.render_now, {
+  template_id: templateId,
+  context: { client_name: "Iris RH" },
+  output_format: "pdf",
+  actor: "clerk_user_id",
+  source: "manual",
+});
+// → { output_url, render_job_id, duration_ms }
+```
+
+See `scripts/smoke-render.md` in this repo for the full copy-paste fleet smoke harness.
+
+---
+
 ## Renderer contract
 
 `render_now` calls the sidecar:

package/dist/mutations.d.ts

@@ -29,6 +29,7 @@ export declare function failRenderJobHandler(ctx: AnyCtx, args: {
     job_id: Id<"render_jobs">;
     error: string;
 }): Promise<null>;
+export declare function generateUploadUrlHandler(ctx: AnyCtx): Promise<string>;
 export declare function writeAuditHandler(ctx: AnyCtx, args: {
     render_job_id: Id<"render_jobs">;
     tenant_id: string;
@@ -40,6 +41,7 @@ export declare function writeAuditHandler(ctx: AnyCtx, args: {
     actor: string;
     source: "manual" | "workflow" | "agent";
 }): Promise<Id<"render_audit">>;
+export declare const generate_upload_url: import("convex/server").RegisteredMutation<"public", {}, Promise<string>>;
 export declare const upsert_template: import("convex/server").RegisteredMutation<"public", {
     name: string;
     team: string;

package/dist/mutations.d.ts.map

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

package/dist/mutations.js

@@ -93,6 +93,9 @@ export async function failRenderJobHandler(ctx, args) {
     });
     return null;
 }
+export async function generateUploadUrlHandler(ctx) {
+    return await ctx.storage.generateUploadUrl();
+}
 export async function writeAuditHandler(ctx, args) {
     return await ctx.db.insert("render_audit", {
         ...args,
@@ -102,6 +105,11 @@ export async function writeAuditHandler(ctx, args) {
 // ---------------------------------------------------------------------------
 // Convex registrations
 // ---------------------------------------------------------------------------
+export const generate_upload_url = mutation({
+    args: {},
+    returns: v.string(),
+    handler: generateUploadUrlHandler,
+});
 export const upsert_template = mutation({
     args: {
         name: v.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/convex-doc-forge",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Convex component — data layer for VantageDocForge (templates, render jobs, audit)",
   "type": "module",
   "main": "./dist/index.js",