@transloadit/convex 0.0.3 → 0.0.4

package/src/component/lib.test.ts

@@ -3,9 +3,9 @@
 import { createHmac } from "node:crypto";
 import { convexTest } from "convex-test";
 import { describe, expect, test, vi } from "vitest";
-import { api } from "./_generated/api.js";
-import schema from "./schema.js";
-import { modules } from "./setup.test.js";
+import { api } from "./_generated/api.ts";
+import schema from "./schema.ts";
+import { modules } from "./setup.test.ts";
 
 process.env.TRANSLOADIT_KEY = "test-key";
 process.env.TRANSLOADIT_SECRET = "test-secret";
@@ -40,7 +40,6 @@ describe("Transloadit component lib", () => {
       payload,
       rawBody,
       signature: `sha1:${signature}`,
-      verifySignature: true,
     });
 
     expect(result.assemblyId).toBe("asm_123");
@@ -61,6 +60,173 @@ describe("Transloadit component lib", () => {
     expect(results[0]?.stepName).toBe("resized");
   });
 
+  test("handleWebhook stores url when ssl_url missing", async () => {
+    const t = convexTest(schema, modules);
+
+    const payload = {
+      assembly_id: "asm_url",
+      ok: "ASSEMBLY_COMPLETED",
+      results: {
+        stored: [
+          {
+            id: "file_3",
+            url: "https://example.com/file-3.jpg",
+            name: "file-3.jpg",
+            size: 42,
+            mime: "image/jpeg",
+          },
+        ],
+      },
+    };
+
+    const rawBody = JSON.stringify(payload);
+    const signature = createHmac("sha1", "test-secret")
+      .update(rawBody)
+      .digest("hex");
+
+    await t.action(api.lib.handleWebhook, {
+      payload,
+      rawBody,
+      signature: `sha1:${signature}`,
+    });
+
+    const results = await t.query(api.lib.listResults, {
+      assemblyId: "asm_url",
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0]?.sslUrl).toBe("https://example.com/file-3.jpg");
+  });
+
+  test("listResults exposes expected fields for common robot outputs", async () => {
+    const t = convexTest(schema, modules);
+
+    const payload = {
+      assembly_id: "asm_schema",
+      ok: "ASSEMBLY_COMPLETED",
+      results: {
+        images_resized: [
+          {
+            id: "img_1",
+            ssl_url: "https://example.com/img.jpg",
+            name: "img.jpg",
+            mime: "image/jpeg",
+            width: 1600,
+            height: 1200,
+          },
+        ],
+        videos_encoded: [
+          {
+            id: "vid_1",
+            ssl_url: "https://example.com/vid.mp4",
+            name: "vid.mp4",
+            mime: "video/mp4",
+            duration: 12.5,
+          },
+        ],
+        videos_thumbs_output: [
+          {
+            id: "thumb_1",
+            ssl_url: "https://example.com/thumb.jpg",
+            name: "thumb.jpg",
+            mime: "image/jpeg",
+            original_id: "vid_1",
+          },
+        ],
+      },
+    };
+
+    const rawBody = JSON.stringify(payload);
+    const signature = createHmac("sha1", "test-secret")
+      .update(rawBody)
+      .digest("hex");
+
+    await t.action(api.lib.handleWebhook, {
+      payload,
+      rawBody,
+      signature: `sha1:${signature}`,
+    });
+
+    const results = await t.query(api.lib.listResults, {
+      assemblyId: "asm_schema",
+    });
+
+    expect(results).toHaveLength(3);
+
+    const byStep = new Map(results.map((result) => [result.stepName, result]));
+    const image = byStep.get("images_resized");
+    const video = byStep.get("videos_encoded");
+    const thumb = byStep.get("videos_thumbs_output");
+
+    expect(image?.sslUrl).toBe("https://example.com/img.jpg");
+    expect(image?.mime).toBe("image/jpeg");
+    expect(image?.raw?.width).toBe(1600);
+    expect(image?.raw?.height).toBe(1200);
+
+    expect(video?.sslUrl).toBe("https://example.com/vid.mp4");
+    expect(video?.mime).toBe("video/mp4");
+    expect(video?.raw?.duration).toBe(12.5);
+
+    expect(thumb?.sslUrl).toBe("https://example.com/thumb.jpg");
+    expect(thumb?.raw?.original_id).toBe("vid_1");
+  });
+
+  test("handleWebhook requires rawBody when verifying signature", async () => {
+    const t = convexTest(schema, modules);
+    const payload = { assembly_id: "asm_missing" };
+    const signature = createHmac("sha1", "test-secret")
+      .update(JSON.stringify(payload))
+      .digest("hex");
+
+    await expect(
+      t.action(api.lib.handleWebhook, {
+        payload,
+        signature: `sha1:${signature}`,
+      }),
+    ).rejects.toThrow("Missing rawBody for webhook verification");
+  });
+
+  test("handleWebhook can skip verification when configured", async () => {
+    const t = convexTest(schema, modules);
+    const payload = {
+      assembly_id: "asm_skip",
+      ok: "ASSEMBLY_COMPLETED",
+      results: {
+        resized: [
+          {
+            id: "file_skip",
+            ssl_url: "https://example.com/skip.jpg",
+            name: "skip.jpg",
+            size: 123,
+            mime: "image/jpeg",
+          },
+        ],
+      },
+    };
+
+    const result = await t.action(api.lib.handleWebhook, {
+      payload,
+      verifySignature: false,
+    });
+
+    expect(result.assemblyId).toBe("asm_skip");
+    expect(result.resultCount).toBe(1);
+  });
+
+  test("queueWebhook rejects invalid signature", async () => {
+    const t = convexTest(schema, modules);
+    const payload = { assembly_id: "asm_bad" };
+    const rawBody = JSON.stringify(payload);
+
+    await expect(
+      t.action(api.lib.queueWebhook, {
+        payload,
+        rawBody,
+        signature: "sha1:bad",
+      }),
+    ).rejects.toThrow("Invalid Transloadit webhook signature");
+  });
+
   test("refreshAssembly fetches status and stores results", async () => {
     const t = convexTest(schema, modules);
 

package/src/component/lib.ts

@@ -1,20 +1,23 @@
-import type { AssemblyStatus } from "@transloadit/types/assemblyStatus";
-import type { AssemblyInstructionsInput } from "@transloadit/types/template";
+import type { AssemblyStatus } from "@transloadit/zod/v3/assemblyStatus";
+import type { AssemblyInstructionsInput } from "@transloadit/zod/v3/template";
 import { anyApi, type FunctionReference } from "convex/server";
 import { type Infer, v } from "convex/values";
+import { parseAssemblyStatus } from "../shared/assemblyUrls.ts";
+import { transloaditError } from "../shared/errors.ts";
+import { getResultUrl } from "../shared/resultUtils.ts";
 import {
   action,
   internalAction,
   internalMutation,
   mutation,
   query,
-} from "./_generated/server.js";
+} from "./_generated/server.ts";
 import {
   buildTransloaditParams,
   flattenResults,
   signTransloaditParams,
   verifyWebhookSignature,
-} from "./apiUtils.js";
+} from "./apiUtils.ts";
 
 const TRANSLOADIT_ASSEMBLY_URL = "https://api2.transloadit.com/assemblies";
 
@@ -56,6 +59,26 @@ const resolveAssemblyId = (payload: AssemblyStatus): string => {
   return "";
 };
 
+const parseAssemblyPayload = (payload: unknown): AssemblyStatus => {
+  const parsed = parseAssemblyStatus(payload);
+  if (!parsed) {
+    throw transloaditError("payload", "Invalid Transloadit payload");
+  }
+  return parsed;
+};
+
+const resolveWebhookRawBody = (args: {
+  payload: unknown;
+  rawBody?: string;
+  verifySignature?: boolean;
+}) => {
+  if (typeof args.rawBody === "string") return args.rawBody;
+  if (args.verifySignature === false) {
+    return JSON.stringify(args.payload ?? {});
+  }
+  return null;
+};
+
 const buildSignedAssemblyUrl = async (
   assemblyId: string,
   authKey: string,
@@ -75,12 +98,12 @@ const buildSignedAssemblyUrl = async (
 };
 
 const applyAssemblyStatus = async (
-  ctx: Pick<import("./_generated/server.js").FunctionCtx, "runMutation">,
+  ctx: Pick<import("./_generated/server.ts").FunctionCtx, "runMutation">,
   payload: AssemblyStatus,
 ) => {
   const assemblyId = resolveAssemblyId(payload);
   if (!assemblyId) {
-    throw new Error("Webhook payload missing assembly_id");
+    throw transloaditError("webhook", "Webhook payload missing assembly_id");
   }
 
   const results = flattenResults(payload.results ?? undefined);
@@ -185,6 +208,9 @@ export const upsertAssembly = internalMutation({
   },
   returns: v.id("assemblies"),
   handler: async (ctx, args) => {
+    // Note: we persist full `raw` + `results` for debugging/fidelity. Large
+    // assemblies can hit Convex document size limits; trim or externalize
+    // payloads if this becomes an issue for your workload.
     const existing = await ctx.db
       .query("assemblies")
       .withIndex("by_assemblyId", (q) => q.eq("assemblyId", args.assemblyId))
@@ -244,6 +270,10 @@ export const replaceResultsForAssembly = internalMutation({
   },
   returns: v.null(),
   handler: async (ctx, args) => {
+    // We store raw result payloads for fidelity. For very large assemblies,
+    // consider trimming or externalizing these fields to avoid size limits.
+    // This mutation replaces all results in one transaction; extremely large
+    // result sets may need batching or external storage to avoid Convex limits.
     const existingResults = await ctx.db
       .query("results")
       .withIndex("by_assemblyId", (q) => q.eq("assemblyId", args.assemblyId))
@@ -256,11 +286,12 @@ export const replaceResultsForAssembly = internalMutation({
     const now = Date.now();
     for (const entry of args.results) {
       const raw = entry.result as Record<string, unknown>;
+      const sslUrl = getResultUrl(entry.result);
       await ctx.db.insert("results", {
         assemblyId: args.assemblyId,
         stepName: entry.stepName,
         resultId: typeof raw.id === "string" ? raw.id : undefined,
-        sslUrl: typeof raw.ssl_url === "string" ? raw.ssl_url : undefined,
+        sslUrl,
         name: typeof raw.name === "string" ? raw.name : undefined,
         size: typeof raw.size === "number" ? raw.size : undefined,
         mime: typeof raw.mime === "string" ? raw.mime : undefined,
@@ -318,8 +349,9 @@ export const createAssembly = action({
 
     const data = (await response.json()) as Record<string, unknown>;
     if (!response.ok) {
-      throw new Error(
-        `Transloadit error ${response.status}: ${JSON.stringify(data)}`,
+      throw transloaditError(
+        "createAssembly",
+        `HTTP ${response.status}: ${JSON.stringify(data)}`,
       );
     }
 
@@ -331,7 +363,10 @@ export const createAssembly = action({
           : "";
 
     if (!assemblyId) {
-      throw new Error("Transloadit response missing assembly_id");
+      throw transloaditError(
+        "createAssembly",
+        "Transloadit response missing assembly_id",
+      );
     }
 
     await ctx.runMutation(internal.lib.upsertAssembly, {
@@ -362,6 +397,13 @@ const vWebhookArgs = {
   authSecret: v.optional(v.string()),
 };
 
+const vPublicWebhookArgs = {
+  payload: v.any(),
+  rawBody: v.optional(v.string()),
+  signature: v.optional(v.string()),
+  verifySignature: v.optional(v.boolean()),
+};
+
 export const processWebhook = internalAction({
   args: vWebhookArgs,
   returns: v.object({
@@ -371,13 +413,22 @@ export const processWebhook = internalAction({
     status: v.optional(v.string()),
   }),
   handler: async (ctx, args) => {
-    const rawBody = args.rawBody ?? JSON.stringify(args.payload ?? {});
+    const rawBody = resolveWebhookRawBody(args);
     const shouldVerify = args.verifySignature ?? true;
     const authSecret = args.authSecret ?? process.env.TRANSLOADIT_SECRET;
 
     if (shouldVerify) {
+      if (!rawBody) {
+        throw transloaditError(
+          "webhook",
+          "Missing rawBody for webhook verification",
+        );
+      }
       if (!authSecret) {
-        throw new Error("Missing TRANSLOADIT_SECRET for webhook validation");
+        throw transloaditError(
+          "webhook",
+          "Missing TRANSLOADIT_SECRET for webhook validation",
+        );
       }
       const verified = await verifyWebhookSignature({
         rawBody,
@@ -385,17 +436,21 @@ export const processWebhook = internalAction({
         authSecret,
       });
       if (!verified) {
-        throw new Error("Invalid Transloadit webhook signature");
+        throw transloaditError(
+          "webhook",
+          "Invalid Transloadit webhook signature",
+        );
       }
     }
 
-    return applyAssemblyStatus(ctx, args.payload as AssemblyStatus);
+    const parsed = parseAssemblyPayload(args.payload);
+    return applyAssemblyStatus(ctx, parsed);
   },
 });
 
 export const handleWebhook = action({
   args: {
-    ...vWebhookArgs,
+    ...vPublicWebhookArgs,
     config: v.optional(
       v.object({
         authSecret: v.string(),
@@ -409,11 +464,12 @@ export const handleWebhook = action({
     status: v.optional(v.string()),
   }),
   handler: async (ctx, args) => {
+    const verifySignature = args.verifySignature ?? true;
     return ctx.runAction(internal.lib.processWebhook, {
       payload: args.payload,
       rawBody: args.rawBody,
       signature: args.signature,
-      verifySignature: args.verifySignature,
+      verifySignature,
       authSecret: args.config?.authSecret,
     });
   },
@@ -421,7 +477,7 @@ export const handleWebhook = action({
 
 export const queueWebhook = action({
   args: {
-    ...vWebhookArgs,
+    ...vPublicWebhookArgs,
     config: v.optional(
       v.object({
         authSecret: v.string(),
@@ -433,17 +489,48 @@ export const queueWebhook = action({
     queued: v.boolean(),
   }),
   handler: async (ctx, args) => {
-    const payload = args.payload as AssemblyStatus;
-    const assemblyId = resolveAssemblyId(payload);
+    const rawBody = resolveWebhookRawBody(args);
+    const shouldVerify = args.verifySignature ?? true;
+    const authSecret =
+      args.config?.authSecret ?? process.env.TRANSLOADIT_SECRET;
+
+    if (shouldVerify) {
+      if (!rawBody) {
+        throw transloaditError(
+          "webhook",
+          "Missing rawBody for webhook verification",
+        );
+      }
+      if (!authSecret) {
+        throw transloaditError(
+          "webhook",
+          "Missing TRANSLOADIT_SECRET for webhook validation",
+        );
+      }
+      const verified = await verifyWebhookSignature({
+        rawBody,
+        signatureHeader: args.signature,
+        authSecret,
+      });
+      if (!verified) {
+        throw transloaditError(
+          "webhook",
+          "Invalid Transloadit webhook signature",
+        );
+      }
+    }
+
+    const parsed = parseAssemblyPayload(args.payload);
+    const assemblyId = resolveAssemblyId(parsed);
     if (!assemblyId) {
-      throw new Error("Webhook payload missing assembly_id");
+      throw transloaditError("webhook", "Webhook payload missing assembly_id");
     }
 
     await ctx.scheduler.runAfter(0, internal.lib.processWebhook, {
-      payload: args.payload,
+      payload: parsed,
       rawBody: args.rawBody,
       signature: args.signature,
-      verifySignature: args.verifySignature,
+      verifySignature: true,
       authSecret: args.config?.authSecret,
     });
 
@@ -478,10 +565,11 @@ export const refreshAssembly = action({
         : `${TRANSLOADIT_ASSEMBLY_URL}/${assemblyId}`;
 
     const response = await fetch(url);
-    const payload = (await response.json()) as AssemblyStatus;
+    const payload = parseAssemblyPayload(await response.json());
     if (!response.ok) {
-      throw new Error(
-        `Transloadit status error ${response.status}: ${JSON.stringify(payload)}`,
+      throw transloaditError(
+        "status",
+        `HTTP ${response.status}: ${JSON.stringify(payload)}`,
       );
     }
 

package/src/component/schema.ts

@@ -1,16 +1,6 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
 
-export const assemblyStatusValues = [
-  "ASSEMBLY_UPLOADING",
-  "ASSEMBLY_EXECUTING",
-  "ASSEMBLY_COMPLETED",
-  "ASSEMBLY_CANCELED",
-  "ASSEMBLY_FAILED",
-] as const;
-
-export type AssemblyStatus = (typeof assemblyStatusValues)[number];
-
 export default defineSchema({
   assemblies: defineTable({
     assemblyId: v.string(),

package/src/debug/index.ts

@@ -0,0 +1,84 @@
+type ConsoleSink = Pick<Console, "log" | "info" | "warn" | "error">;
+
+export type DebugLogger = {
+  enabled: boolean;
+  log: (message: string, meta?: Record<string, unknown>) => void;
+  info: (message: string, meta?: Record<string, unknown>) => void;
+  warn: (message: string, meta?: Record<string, unknown>) => void;
+  error: (message: string, meta?: Record<string, unknown>) => void;
+  event: (name: string, meta?: Record<string, unknown>) => void;
+  child: (namespace: string) => DebugLogger;
+};
+
+export type DebugLoggerOptions = {
+  namespace?: string;
+  enabled?: boolean;
+  sink?: ConsoleSink;
+  clock?: () => Date;
+};
+
+const resolveEnv = (): Record<string, string | undefined> => {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env;
+  }
+  return {};
+};
+
+const parseEnabled = (value: string | undefined) => {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+};
+
+const formatLine = (
+  timestamp: string,
+  prefix: string,
+  message: string,
+  meta?: Record<string, unknown>,
+) => {
+  if (!meta || Object.keys(meta).length === 0) {
+    return `${timestamp} ${prefix} ${message}`;
+  }
+  return `${timestamp} ${prefix} ${message} ${JSON.stringify(meta)}`;
+};
+
+export const createDebugLogger = (
+  options: DebugLoggerOptions = {},
+): DebugLogger => {
+  const env = resolveEnv();
+  const enabled =
+    options.enabled ??
+    (parseEnabled(env.TRANSLOADIT_DEBUG) ||
+      parseEnabled(env.CONVEX_TRANSLOADIT_DEBUG));
+  const namespace = options.namespace ?? "convex";
+  const prefix = `[transloadit:${namespace}]`;
+  const sink: ConsoleSink = options.sink ?? console;
+  const clock = options.clock ?? (() => new Date());
+
+  const emit = (
+    level: "log" | "info" | "warn" | "error",
+    message: string,
+    meta?: Record<string, unknown>,
+  ) => {
+    if (!enabled) return;
+    const line = formatLine(clock().toISOString(), prefix, message, meta);
+    sink[level](line);
+  };
+
+  const logger: DebugLogger = {
+    enabled,
+    log: (message, meta) => emit("log", message, meta),
+    info: (message, meta) => emit("info", message, meta),
+    warn: (message, meta) => emit("warn", message, meta),
+    error: (message, meta) => emit("error", message, meta),
+    event: (name, meta) => emit("info", `event:${name}`, meta),
+    child: (childNamespace) =>
+      createDebugLogger({
+        ...options,
+        namespace: `${namespace}:${childNamespace}`,
+        enabled,
+      }),
+  };
+
+  return logger;
+};