@transloadit/convex 0.0.3 → 0.0.5

package/src/client/index.ts

@@ -1,11 +1,71 @@
-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 { actionGeneric, mutationGeneric, queryGeneric } from "convex/server";
 import { type Infer, v } from "convex/values";
-import type { ComponentApi } from "../component/_generated/component.js";
-import type { RunActionCtx, RunMutationCtx, RunQueryCtx } from "./types.js";
+import type { ComponentApi } from "../component/_generated/component.ts";
+import type { RunActionCtx, RunMutationCtx, RunQueryCtx } from "./types.ts";
 
-export { parseTransloaditWebhook } from "../component/apiUtils.js";
+export {
+  assemblyStatusErrCodeSchema,
+  assemblyStatusOkCodeSchema,
+  assemblyStatusResultsSchema,
+  assemblyStatusSchema,
+  isAssemblyBusy,
+  isAssemblyBusyStatus,
+  isAssemblyErrorStatus,
+  isAssemblyOkStatus,
+  isAssemblySysError,
+  isAssemblyTerminal,
+  isAssemblyTerminalError,
+  isAssemblyTerminalOk,
+  isAssemblyTerminalOkStatus,
+} from "@transloadit/zod/v3/assemblyStatus";
+export type {
+  ParsedWebhookRequest,
+  VerifiedWebhookRequest,
+  WebhookActionArgs,
+} from "../component/apiUtils.ts";
+export {
+  buildWebhookQueueArgs,
+  handleWebhookRequest,
+  parseAndVerifyTransloaditWebhook,
+  parseTransloaditWebhook,
+} from "../component/apiUtils.ts";
+export type {
+  NormalizedAssemblyUrls,
+  TransloaditAssembly,
+} from "../shared/assemblyUrls.ts";
+export {
+  ASSEMBLY_STATUS_COMPLETED,
+  ASSEMBLY_STATUS_UPLOADING,
+  getAssemblyStage,
+  isAssemblyCompletedStatus,
+  isAssemblyUploadingStatus,
+  normalizeAssemblyUploadUrls,
+  parseAssemblyFields,
+  parseAssemblyResults,
+  parseAssemblyStatus,
+  parseAssemblyUrls,
+} from "../shared/assemblyUrls.ts";
+export { pollAssembly } from "../shared/pollAssembly.ts";
+export type {
+  ImageResizeResult,
+  ResultByRobot,
+  ResultForRobot,
+  StoreResult,
+  TransloaditResult,
+  VideoEncodeResult,
+  VideoThumbsResult,
+} from "../shared/resultTypes.ts";
+export {
+  getResultOriginalKey,
+  getResultUrl,
+} from "../shared/resultUtils.ts";
+export type {
+  TusMetadataOptions,
+  TusUploadConfig,
+} from "../shared/tusUpload.ts";
+export { buildTusUploadConfig } from "../shared/tusUpload.ts";
 export type { AssemblyStatus, AssemblyInstructionsInput };
 
 export interface TransloaditConfig {
@@ -51,6 +111,8 @@ export const vAssemblyResultResponse = v.object({
   _id: v.string(),
   _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()),
@@ -74,6 +136,9 @@ export const vCreateAssemblyArgs = v.object({
   userId: v.optional(v.string()),
 });
 
+/**
+ * @deprecated Prefer `makeTransloaditAPI` or `Transloadit` for new code.
+ */
 export class TransloaditClient {
   declare component: TransloaditComponent;
   declare config: TransloaditConfig;
@@ -158,6 +223,13 @@ export class TransloaditClient {
     return ctx.runQuery(this.component.lib.listResults, args);
   }
 
+  async listAlbumResults(
+    ctx: RunQueryCtx,
+    args: { album: string; limit?: number },
+  ) {
+    return ctx.runQuery(this.component.lib.listAlbumResults, args);
+  }
+
   async storeAssemblyMetadata(
     ctx: RunMutationCtx,
     args: { assemblyId: string; userId?: string; fields?: unknown },
@@ -172,6 +244,9 @@ export class TransloaditClient {
 
 export class Transloadit extends TransloaditClient {}
 
+/**
+ * @deprecated Prefer `new Transloadit(...)` or `makeTransloaditAPI(...)`.
+ */
 export function createTransloadit(
   component: TransloaditComponent,
   config?: Partial<TransloaditConfig>,
@@ -183,10 +258,10 @@ export function makeTransloaditAPI(
   component: TransloaditComponent,
   config?: Partial<TransloaditConfig>,
 ) {
-  const resolvedConfig: TransloaditConfig = {
+  const resolveConfig = (): TransloaditConfig => ({
     authKey: config?.authKey ?? requireEnv(["TRANSLOADIT_KEY"]),
     authSecret: config?.authSecret ?? requireEnv(["TRANSLOADIT_SECRET"]),
-  };
+  });
 
   return {
     createAssembly: actionGeneric({
@@ -196,6 +271,7 @@ export function makeTransloaditAPI(
         data: v.any(),
       }),
       handler: async (ctx, args) => {
+        const resolvedConfig = resolveConfig();
         return ctx.runAction(component.lib.createAssembly, {
           ...args,
           config: resolvedConfig,
@@ -207,13 +283,15 @@ export function makeTransloaditAPI(
         payload: v.any(),
         rawBody: v.optional(v.string()),
         signature: v.optional(v.string()),
-        verifySignature: v.optional(v.boolean()),
       },
       returns: v.object({
         assemblyId: v.string(),
         resultCount: v.number(),
+        ok: v.optional(v.string()),
+        status: v.optional(v.string()),
       }),
       handler: async (ctx, args) => {
+        const resolvedConfig = resolveConfig();
         return ctx.runAction(component.lib.handleWebhook, {
           ...args,
           config: { authSecret: resolvedConfig.authSecret },
@@ -225,13 +303,13 @@ export function makeTransloaditAPI(
         payload: v.any(),
         rawBody: v.optional(v.string()),
         signature: v.optional(v.string()),
-        verifySignature: v.optional(v.boolean()),
       },
       returns: v.object({
         assemblyId: v.string(),
         queued: v.boolean(),
       }),
       handler: async (ctx, args) => {
+        const resolvedConfig = resolveConfig();
         return ctx.runAction(component.lib.queueWebhook, {
           ...args,
           config: { authSecret: resolvedConfig.authSecret },
@@ -247,6 +325,7 @@ export function makeTransloaditAPI(
         status: v.optional(v.string()),
       }),
       handler: async (ctx, args) => {
+        const resolvedConfig = resolveConfig();
         return ctx.runAction(component.lib.refreshAssembly, {
           ...args,
           config: resolvedConfig,
@@ -282,6 +361,29 @@ export function makeTransloaditAPI(
         return ctx.runQuery(component.lib.listResults, args);
       },
     }),
+    listAlbumResults: queryGeneric({
+      args: {
+        album: v.string(),
+        limit: v.optional(v.number()),
+      },
+      returns: v.array(vAssemblyResultResponse),
+      handler: async (ctx, args) => {
+        return ctx.runQuery(component.lib.listAlbumResults, args);
+      },
+    }),
+    purgeAlbum: mutationGeneric({
+      args: {
+        album: v.string(),
+        deleteAssemblies: v.optional(v.boolean()),
+      },
+      returns: v.object({
+        deletedResults: v.number(),
+        deletedAssemblies: v.number(),
+      }),
+      handler: async (ctx, args) => {
+        return ctx.runMutation(component.lib.purgeAlbum, args);
+      },
+    }),
     storeAssemblyMetadata: mutationGeneric({
       args: {
         assemblyId: v.string(),

package/src/component/_generated/api.ts

@@ -8,8 +8,8 @@
  * @module
  */
 
-import type * as apiUtils from "../apiUtils.js";
-import type * as lib from "../lib.js";
+import type * as apiUtils from "../apiUtils.ts";
+import type * as lib from "../lib.ts";
 
 import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
 import { anyApi, componentsGeneric } from "convex/server";

package/src/component/_generated/component.ts

@@ -142,6 +142,20 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       Array<any>,
       Name
     >;
+    listAlbumResults: FunctionReference<
+      "query",
+      "internal",
+      { album: string; limit?: number },
+      Array<any>,
+      Name
+    >;
+    purgeAlbum: FunctionReference<
+      "mutation",
+      "internal",
+      { album: string; deleteAssemblies?: boolean },
+      { deletedResults: number; deletedAssemblies: number },
+      Name
+    >;
     storeAssemblyMetadata: FunctionReference<
       "mutation",
       "internal",

package/src/component/_generated/dataModel.ts

@@ -15,7 +15,7 @@ import type {
   SystemTableNames,
 } from "convex/server";
 import type { GenericId } from "convex/values";
-import schema from "../schema.js";
+import schema from "../schema.ts";
 
 export type TableNames = TableNamesInDataModel<DataModel>;
 

package/src/component/_generated/server.ts

@@ -28,7 +28,7 @@ import {
   internalMutationGeneric,
   internalQueryGeneric,
 } from "convex/server";
-import type { DataModel } from "./dataModel.js";
+import type { DataModel } from "./dataModel.ts";
 
 export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
 

package/src/component/apiUtils.test.ts

@@ -1,11 +1,14 @@
 import { createHmac } from "node:crypto";
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 import {
   buildTransloaditParams,
+  buildWebhookQueueArgs,
+  handleWebhookRequest,
+  parseAndVerifyTransloaditWebhook,
   parseTransloaditWebhook,
   signTransloaditParams,
   verifyWebhookSignature,
-} from "./apiUtils.js";
+} from "./apiUtils.ts";
 
 describe("apiUtils", () => {
   test("buildTransloaditParams requires templateId or steps", () => {
@@ -74,4 +77,165 @@ describe("apiUtils", () => {
       "Missing transloadit payload",
     );
   });
+
+  test("parseAndVerifyTransloaditWebhook verifies signature", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const secret = "webhook-secret";
+    const digest = createHmac("sha384", secret).update(rawBody).digest("hex");
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", `sha384:${digest}`);
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    const parsed = await parseAndVerifyTransloaditWebhook(request, {
+      authSecret: secret,
+    });
+
+    expect(parsed.payload).toEqual(payload);
+    expect(parsed.verified).toBe(true);
+  });
+
+  test("parseAndVerifyTransloaditWebhook rejects invalid signature", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const formData = new FormData();
+    formData.append("transloadit", JSON.stringify(payload));
+    formData.append("signature", "sha384:bad");
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    await expect(
+      parseAndVerifyTransloaditWebhook(request, {
+        authSecret: "secret",
+      }),
+    ).rejects.toThrow("Invalid Transloadit webhook signature");
+  });
+
+  test("buildWebhookQueueArgs returns webhook payload args", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const secret = "webhook-secret";
+    const digest = createHmac("sha384", secret).update(rawBody).digest("hex");
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", `sha384:${digest}`);
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    const args = await buildWebhookQueueArgs(request, { authSecret: secret });
+    expect(args.payload).toEqual(payload);
+    expect(args.rawBody).toBe(rawBody);
+    expect(args.signature).toBe(`sha384:${digest}`);
+  });
+
+  test("buildWebhookQueueArgs can skip verification", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    const args = await buildWebhookQueueArgs(request, {
+      authSecret: "secret",
+      requireSignature: false,
+    });
+    expect(args.payload).toEqual(payload);
+    expect(args.rawBody).toBe(rawBody);
+    expect(args.signature).toBeUndefined();
+  });
+
+  test("handleWebhookRequest queues webhook by default", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", "sha384:abc");
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+    const runAction = vi.fn().mockResolvedValue(null);
+
+    const response = await handleWebhookRequest(request, {
+      runAction,
+    });
+
+    expect(runAction).toHaveBeenCalledWith({
+      payload,
+      rawBody,
+      signature: "sha384:abc",
+    });
+    expect(response.status).toBe(202);
+  });
+
+  test("handleWebhookRequest supports sync mode with verification", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const secret = "webhook-secret";
+    const digest = createHmac("sha384", secret).update(rawBody).digest("hex");
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", `sha384:${digest}`);
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+    const runAction = vi.fn().mockResolvedValue(null);
+
+    const response = await handleWebhookRequest(request, {
+      mode: "sync",
+      runAction,
+      requireSignature: true,
+      authSecret: secret,
+    });
+
+    expect(runAction).toHaveBeenCalledWith({
+      payload,
+      rawBody,
+      signature: `sha384:${digest}`,
+    });
+    expect(response.status).toBe(204);
+  });
+
+  test("handleWebhookRequest honors a custom response status", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", "sha384:abc");
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+    const runAction = vi.fn().mockResolvedValue(null);
+
+    const response = await handleWebhookRequest(request, {
+      runAction,
+      responseStatus: 299,
+    });
+
+    expect(runAction).toHaveBeenCalledWith({
+      payload,
+      rawBody,
+      signature: "sha384:abc",
+    });
+    expect(response.status).toBe(299);
+  });
 });

package/src/component/apiUtils.ts

@@ -1,5 +1,7 @@
-import type { AssemblyStatusResults } from "@transloadit/types/assemblyStatus";
-import type { AssemblyInstructionsInput } from "@transloadit/types/template";
+import { signParams, verifyWebhookSignature } from "@transloadit/utils";
+import type { AssemblyStatusResults } from "@transloadit/zod/v3/assemblyStatus";
+import type { AssemblyInstructionsInput } from "@transloadit/zod/v3/template";
+import { transloaditError } from "../shared/errors.ts";
 
 export interface TransloaditAuthConfig {
   authKey: string;
@@ -26,7 +28,10 @@ export function buildTransloaditParams(
   options: BuildParamsOptions,
 ): BuildParamsResult {
   if (!options.templateId && !options.steps) {
-    throw new Error("Provide either templateId or steps to create an Assembly");
+    throw transloaditError(
+      "createAssembly",
+      "Provide either templateId or steps to create an Assembly",
+    );
   }
 
   const auth: Record<string, string> = {
@@ -62,40 +67,11 @@ export function buildTransloaditParams(
   };
 }
 
-async function hmacHex(
-  algorithm: "SHA-384" | "SHA-1",
-  key: string,
-  data: string,
-): Promise<string> {
-  if (!globalThis.crypto?.subtle) {
-    throw new Error("Web Crypto is required to sign Transloadit payloads");
-  }
-
-  const encoder = new TextEncoder();
-  const cryptoKey = await globalThis.crypto.subtle.importKey(
-    "raw",
-    encoder.encode(key),
-    { name: "HMAC", hash: { name: algorithm } },
-    false,
-    ["sign"],
-  );
-  const signature = await globalThis.crypto.subtle.sign(
-    "HMAC",
-    cryptoKey,
-    encoder.encode(data),
-  );
-  const bytes = new Uint8Array(signature);
-  return Array.from(bytes)
-    .map((byte) => byte.toString(16).padStart(2, "0"))
-    .join("");
-}
-
 export async function signTransloaditParams(
   paramsString: string,
   authSecret: string,
 ): Promise<string> {
-  const signature = await hmacHex("SHA-384", authSecret, paramsString);
-  return `sha384:${signature}`;
+  return signParams(paramsString, authSecret, "sha384");
 }
 
 export type ParsedWebhookRequest = {
@@ -104,6 +80,10 @@ export type ParsedWebhookRequest = {
   signature?: string;
 };
 
+export type VerifiedWebhookRequest = ParsedWebhookRequest & {
+  verified: boolean;
+};
+
 export async function parseTransloaditWebhook(
   request: Request,
 ): Promise<ParsedWebhookRequest> {
@@ -112,7 +92,7 @@ export async function parseTransloaditWebhook(
   const signature = formData.get("signature");
 
   if (typeof rawPayload !== "string") {
-    throw new Error("Missing transloadit payload");
+    throw transloaditError("webhook", "Missing transloadit payload");
   }
 
   return {
@@ -122,44 +102,96 @@ export async function parseTransloaditWebhook(
   };
 }
 
-function safeCompare(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let mismatch = 0;
-  for (let i = 0; i < a.length; i += 1) {
-    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+export async function parseAndVerifyTransloaditWebhook(
+  request: Request,
+  options: {
+    authSecret: string;
+    requireSignature?: boolean;
+  },
+): Promise<VerifiedWebhookRequest> {
+  const parsed = await parseTransloaditWebhook(request);
+  const authSecret = options.authSecret;
+  if (!authSecret) {
+    throw transloaditError(
+      "webhook",
+      "Missing authSecret for webhook verification",
+    );
+  }
+  const verified = await verifyWebhookSignature({
+    rawBody: parsed.rawBody,
+    signatureHeader: parsed.signature,
+    authSecret,
+  });
+
+  if (options.requireSignature ?? true) {
+    if (!verified) {
+      throw transloaditError(
+        "webhook",
+        "Invalid Transloadit webhook signature",
+      );
+    }
   }
-  return mismatch === 0;
-}
-
-export async function verifyWebhookSignature(options: {
-  rawBody: string;
-  signatureHeader?: string;
-  authSecret: string;
-}): Promise<boolean> {
-  if (!options.signatureHeader) return false;
 
-  const signatureHeader = options.signatureHeader.trim();
-  if (!signatureHeader) return false;
+  return { ...parsed, verified };
+}
 
-  const [prefix, sig] = signatureHeader.includes(":")
-    ? (signatureHeader.split(":") as [string, string])
-    : ["sha1", signatureHeader];
+export async function buildWebhookQueueArgs(
+  request: Request,
+  options: {
+    authSecret: string;
+    requireSignature?: boolean;
+  },
+): Promise<ParsedWebhookRequest> {
+  if (options.requireSignature === false) {
+    return parseTransloaditWebhook(request);
+  }
 
-  const normalized = prefix.toLowerCase();
-  const algorithm = normalized === "sha384" ? "SHA-384" : "SHA-1";
+  const parsed = await parseAndVerifyTransloaditWebhook(request, options);
+  return {
+    payload: parsed.payload,
+    rawBody: parsed.rawBody,
+    signature: parsed.signature,
+  };
+}
 
-  if (normalized !== "sha384" && normalized !== "sha1") {
-    return false;
-  }
+export type WebhookActionArgs = {
+  payload: unknown;
+  rawBody?: string;
+  signature?: string;
+};
 
-  const expected = await hmacHex(
-    algorithm,
-    options.authSecret,
-    options.rawBody,
-  );
-  return safeCompare(expected, sig);
+export async function handleWebhookRequest(
+  request: Request,
+  options: {
+    mode?: "queue" | "sync";
+    runAction: (args: WebhookActionArgs) => Promise<unknown>;
+    requireSignature?: boolean;
+    authSecret?: string;
+    responseStatus?: number;
+  },
+): Promise<Response> {
+  const mode = options.mode ?? "queue";
+  const requireSignature = options.requireSignature ?? false;
+
+  const parsed = requireSignature
+    ? await parseAndVerifyTransloaditWebhook(request, {
+        authSecret: options.authSecret ?? "",
+        requireSignature: true,
+      })
+    : await parseTransloaditWebhook(request);
+
+  await options.runAction({
+    payload: parsed.payload,
+    rawBody: parsed.rawBody,
+    signature: parsed.signature,
+  });
+
+  const status = options.responseStatus ?? (mode === "sync" ? 204 : 202);
+  return new Response(null, { status });
 }
 
+export { verifyWebhookSignature };
+
 export type AssemblyResult = AssemblyStatusResults[string][number];
 
 export type AssemblyResultRecord = {