@transloadit/convex 0.0.3 → 0.0.5

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,216 @@ describe("Transloadit component lib", () => {
     expect(results[0]?.stepName).toBe("resized");
   });
 
+  test("listAlbumResults returns album-scoped results", async () => {
+    const t = convexTest(schema, modules);
+
+    const payload = {
+      assembly_id: "asm_album",
+      ok: "ASSEMBLY_COMPLETED",
+      fields: {
+        album: "wedding-gallery",
+        userId: "user_123",
+      },
+      results: {
+        resized: [
+          {
+            id: "file_album",
+            ssl_url: "https://example.com/album.jpg",
+            name: "album.jpg",
+            size: 100,
+            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.listAlbumResults, {
+      album: "wedding-gallery",
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0]?.album).toBe("wedding-gallery");
+    expect(results[0]?.userId).toBe("user_123");
+  });
+
+  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,32 @@ const resolveAssemblyId = (payload: AssemblyStatus): string => {
   return "";
 };
 
+const getFieldString = (fields: unknown, key: string): string | undefined => {
+  if (!fields || typeof fields !== "object") return undefined;
+  const value = (fields as Record<string, unknown>)[key];
+  return typeof value === "string" ? value : undefined;
+};
+
+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 +104,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);
@@ -94,10 +123,15 @@ const applyAssemblyStatus = async (
       typeof payload.template_id === "string" ? payload.template_id : undefined,
     notifyUrl:
       typeof payload.notify_url === "string" ? payload.notify_url : undefined,
+    fields: payload.fields,
     uploads: payload.uploads,
     results: payload.results,
     error: payload.error,
     raw: payload,
+    userId:
+      typeof payload.user_id === "string"
+        ? payload.user_id
+        : getFieldString(payload.fields, "userId"),
   });
 
   await ctx.runMutation(internal.lib.replaceResultsForAssembly, {
@@ -139,6 +173,8 @@ export const vAssemblyResult = v.object({
   _id: v.id("results"),
   _creationTime: v.number(),
   assemblyId: v.string(),
+  album: v.optional(v.string()),
+  userId: v.optional(v.string()),
   stepName: v.string(),
   resultId: v.optional(v.string()),
   sslUrl: v.optional(v.string()),
@@ -185,6 +221,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 +283,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))
@@ -253,14 +296,27 @@ export const replaceResultsForAssembly = internalMutation({
       await ctx.db.delete(existing._id);
     }
 
+    const assembly = await ctx.db
+      .query("assemblies")
+      .withIndex("by_assemblyId", (q) => q.eq("assemblyId", args.assemblyId))
+      .unique();
+    const album = getFieldString(assembly?.fields, "album");
+    const userId =
+      typeof assembly?.userId === "string"
+        ? assembly.userId
+        : getFieldString(assembly?.fields, "userId");
+
     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,
+        album,
+        userId,
         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 +374,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 +388,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 +422,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 +438,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 +461,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 +489,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 +502,7 @@ export const handleWebhook = action({
 
 export const queueWebhook = action({
   args: {
-    ...vWebhookArgs,
+    ...vPublicWebhookArgs,
     config: v.optional(
       v.object({
         authSecret: v.string(),
@@ -433,17 +514,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 +590,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)}`,
       );
     }
 
@@ -557,6 +670,60 @@ export const listResults = query({
   },
 });
 
+export const listAlbumResults = query({
+  args: {
+    album: v.string(),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(vAssemblyResult),
+  handler: async (ctx, args) => {
+    return ctx.db
+      .query("results")
+      .withIndex("by_album", (q) => q.eq("album", args.album))
+      .order("desc")
+      .take(args.limit ?? 200);
+  },
+});
+
+export const purgeAlbum = mutation({
+  args: {
+    album: v.string(),
+    deleteAssemblies: v.optional(v.boolean()),
+  },
+  returns: v.object({
+    deletedResults: v.number(),
+    deletedAssemblies: v.number(),
+  }),
+  handler: async (ctx, args) => {
+    const results = await ctx.db
+      .query("results")
+      .withIndex("by_album", (q) => q.eq("album", args.album))
+      .collect();
+    const assemblyIds = new Set<string>();
+
+    for (const result of results) {
+      assemblyIds.add(result.assemblyId);
+      await ctx.db.delete(result._id);
+    }
+
+    let deletedAssemblies = 0;
+    if (args.deleteAssemblies ?? true) {
+      for (const assemblyId of assemblyIds) {
+        const assembly = await ctx.db
+          .query("assemblies")
+          .withIndex("by_assemblyId", (q) => q.eq("assemblyId", assemblyId))
+          .unique();
+        if (assembly) {
+          await ctx.db.delete(assembly._id);
+          deletedAssemblies += 1;
+        }
+      }
+    }
+
+    return { deletedResults: results.length, deletedAssemblies };
+  },
+});
+
 export const storeAssemblyMetadata = mutation({
   args: {
     assemblyId: v.string(),

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(),
@@ -34,6 +24,8 @@ export default defineSchema({
     .index("by_userId", ["userId"]),
   results: defineTable({
     assemblyId: v.string(),
+    album: v.optional(v.string()),
+    userId: v.optional(v.string()),
     stepName: v.string(),
     resultId: v.optional(v.string()),
     sslUrl: v.optional(v.string()),
@@ -44,5 +36,6 @@ export default defineSchema({
     createdAt: v.number(),
   })
     .index("by_assemblyId", ["assemblyId"])
-    .index("by_assemblyId_and_step", ["assemblyId", "stepName"]),
+    .index("by_assemblyId_and_step", ["assemblyId", "stepName"])
+    .index("by_album", ["album"]),
 });