@transloadit/convex 0.0.1 → 0.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@transloadit/convex",
   "description": "Transloadit component for Convex",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "packageManager": "yarn@4.5.0",
   "repository": {
@@ -25,16 +25,18 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run --typecheck",
     "test:watch": "vitest --typecheck",
+    "test:browser": "dotenv -q -- node scripts/run-browser.ts",
     "lint": "biome check .",
     "format": "biome format . --write",
+    "check": "yarn format && yarn lint && yarn typecheck && yarn test",
     "prepack": "yarn build",
-    "smoke": "dotenv -q -- node scripts/smoke-test.ts",
     "template:ensure": "dotenv -q -- node scripts/ensure-template.ts",
-    "tunnel": "node scripts/start-webhook-tunnel.ts",
-    "qa:full": "dotenv -q -- node scripts/qa-full.ts",
-    "qa:full:verbose": "dotenv -q -- node scripts/qa-full.ts --verbose"
+    "tunnel": "node scripts/start-webhook-tunnel.ts"
   },
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -52,6 +54,10 @@
       "types": "./dist/component/lib.d.ts",
       "default": "./dist/component/lib.js"
     },
+    "./test": {
+      "types": "./dist/test/index.d.ts",
+      "default": "./dist/test/index.js"
+    },
     "./convex.config": {
       "@convex-dev/component-source": "./src/component/convex.config.ts",
       "types": "./dist/component/convex.config.d.ts",
@@ -68,19 +74,25 @@
     }
   },
   "dependencies": {
-    "tus-js-client": "^4.1.0"
+    "@transloadit/types": "^4.1.3",
+    "tus-js-client": "^4.3.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
+    "@biomejs/biome": "^2.3.11",
     "@edge-runtime/vm": "^5.0.0",
-    "@types/node": "^20.19.0",
-    "@types/react": "^19.1.10",
-    "convex": "^1.24.8",
-    "convex-test": "0.0.37",
-    "dotenv-cli": "^8.0.0",
+    "@playwright/test": "^1.57.0",
+    "@types/node": "^25.0.8",
+    "@types/react": "^19.2.8",
+    "@types/react-dom": "^19",
+    "convex": "^1.31.4",
+    "convex-test": "^0.0.41",
+    "dotenv-cli": "^11.0.0",
+    "esbuild": "^0.27.2",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "typescript": "^5.9.3",
-    "vitest": "3.2.4"
+    "vitest": "^4.0.17"
   },
   "types": "./dist/client/index.d.ts",
   "module": "./dist/client/index.js"
-}
+}

package/src/client/index.ts

@@ -1,8 +1,13 @@
+import type { AssemblyStatus } from "@transloadit/types/assemblyStatus";
+import type { AssemblyInstructionsInput } from "@transloadit/types/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";
 
+export { parseTransloaditWebhook } from "../component/apiUtils.js";
+export type { AssemblyStatus, AssemblyInstructionsInput };
+
 export interface TransloaditConfig {
   authKey: string;
   authSecret: string;
@@ -30,9 +35,9 @@ export const vAssemblyResponse = v.object({
   templateId: v.optional(v.string()),
   notifyUrl: v.optional(v.string()),
   numExpectedUploadFiles: v.optional(v.number()),
-  fields: v.optional(v.any()),
-  uploads: v.optional(v.any()),
-  results: v.optional(v.any()),
+  fields: v.optional(v.record(v.string(), v.any())),
+  uploads: v.optional(v.array(v.any())),
+  results: v.optional(v.record(v.string(), v.array(v.any()))),
   error: v.optional(v.any()),
   raw: v.optional(v.any()),
   createdAt: v.number(),
@@ -60,12 +65,12 @@ export type AssemblyResultResponse = Infer<typeof vAssemblyResultResponse>;
 
 export const vCreateAssemblyArgs = v.object({
   templateId: v.optional(v.string()),
-  steps: v.optional(v.any()),
-  fields: v.optional(v.any()),
+  steps: v.optional(v.record(v.string(), v.any())),
+  fields: v.optional(v.record(v.string(), v.any())),
   notifyUrl: v.optional(v.string()),
   numExpectedUploadFiles: v.optional(v.number()),
   expires: v.optional(v.string()),
-  additionalParams: v.optional(v.any()),
+  additionalParams: v.optional(v.record(v.string(), v.any())),
   userId: v.optional(v.string()),
 });
 
@@ -79,12 +84,8 @@ export class TransloaditClient {
   ) {
     this.component = component;
     this.config = {
-      authKey:
-        config?.authKey ??
-        requireEnv(["TRANSLOADIT_AUTH_KEY", "TRANSLOADIT_KEY"]),
-      authSecret:
-        config?.authSecret ??
-        requireEnv(["TRANSLOADIT_AUTH_SECRET", "TRANSLOADIT_SECRET"]),
+      authKey: config?.authKey ?? requireEnv(["TRANSLOADIT_KEY"]),
+      authSecret: config?.authSecret ?? requireEnv(["TRANSLOADIT_SECRET"]),
     };
   }
 
@@ -102,17 +103,22 @@ export class TransloaditClient {
     });
   }
 
-  async generateUploadParams(
+  async handleWebhook(
     ctx: RunActionCtx,
-    args: Infer<typeof vCreateAssemblyArgs>,
+    args: {
+      payload: unknown;
+      rawBody?: string;
+      signature?: string;
+      verifySignature?: boolean;
+    },
   ) {
-    return ctx.runAction(this.component.lib.generateUploadParams, {
+    return ctx.runAction(this.component.lib.handleWebhook, {
       ...args,
-      config: this.config,
+      config: { authSecret: this.config.authSecret },
     });
   }
 
-  async handleWebhook(
+  async queueWebhook(
     ctx: RunActionCtx,
     args: {
       payload: unknown;
@@ -121,12 +127,19 @@ export class TransloaditClient {
       verifySignature?: boolean;
     },
   ) {
-    return ctx.runAction(this.component.lib.handleWebhook, {
+    return ctx.runAction(this.component.lib.queueWebhook, {
       ...args,
       config: { authSecret: this.config.authSecret },
     });
   }
 
+  async refreshAssembly(ctx: RunActionCtx, assemblyId: string) {
+    return ctx.runAction(this.component.lib.refreshAssembly, {
+      assemblyId,
+      config: this.config,
+    });
+  }
+
   async getAssemblyStatus(ctx: RunQueryCtx, assemblyId: string) {
     return ctx.runQuery(this.component.lib.getAssemblyStatus, { assemblyId });
   }
@@ -157,17 +170,22 @@ export class TransloaditClient {
   }
 }
 
+export class Transloadit extends TransloaditClient {}
+
+export function createTransloadit(
+  component: TransloaditComponent,
+  config?: Partial<TransloaditConfig>,
+) {
+  return new Transloadit(component, config);
+}
+
 export function makeTransloaditAPI(
   component: TransloaditComponent,
   config?: Partial<TransloaditConfig>,
 ) {
   const resolvedConfig: TransloaditConfig = {
-    authKey:
-      config?.authKey ??
-      requireEnv(["TRANSLOADIT_AUTH_KEY", "TRANSLOADIT_KEY"]),
-    authSecret:
-      config?.authSecret ??
-      requireEnv(["TRANSLOADIT_AUTH_SECRET", "TRANSLOADIT_SECRET"]),
+    authKey: config?.authKey ?? requireEnv(["TRANSLOADIT_KEY"]),
+    authSecret: config?.authSecret ?? requireEnv(["TRANSLOADIT_SECRET"]),
   };
 
   return {
@@ -184,21 +202,25 @@ export function makeTransloaditAPI(
         });
       },
     }),
-    generateUploadParams: actionGeneric({
-      args: vCreateAssemblyArgs,
+    handleWebhook: actionGeneric({
+      args: {
+        payload: v.any(),
+        rawBody: v.optional(v.string()),
+        signature: v.optional(v.string()),
+        verifySignature: v.optional(v.boolean()),
+      },
       returns: v.object({
-        params: v.string(),
-        signature: v.string(),
-        url: v.string(),
+        assemblyId: v.string(),
+        resultCount: v.number(),
       }),
       handler: async (ctx, args) => {
-        return ctx.runAction(component.lib.generateUploadParams, {
+        return ctx.runAction(component.lib.handleWebhook, {
           ...args,
-          config: resolvedConfig,
+          config: { authSecret: resolvedConfig.authSecret },
         });
       },
     }),
-    handleWebhook: actionGeneric({
+    queueWebhook: actionGeneric({
       args: {
         payload: v.any(),
         rawBody: v.optional(v.string()),
@@ -207,15 +229,30 @@ export function makeTransloaditAPI(
       },
       returns: v.object({
         assemblyId: v.string(),
-        resultCount: v.number(),
+        queued: v.boolean(),
       }),
       handler: async (ctx, args) => {
-        return ctx.runAction(component.lib.handleWebhook, {
+        return ctx.runAction(component.lib.queueWebhook, {
           ...args,
           config: { authSecret: resolvedConfig.authSecret },
         });
       },
     }),
+    refreshAssembly: actionGeneric({
+      args: { assemblyId: v.string() },
+      returns: v.object({
+        assemblyId: v.string(),
+        resultCount: v.number(),
+        ok: v.optional(v.string()),
+        status: v.optional(v.string()),
+      }),
+      handler: async (ctx, args) => {
+        return ctx.runAction(component.lib.refreshAssembly, {
+          ...args,
+          config: resolvedConfig,
+        });
+      },
+    }),
     getAssemblyStatus: queryGeneric({
       args: { assemblyId: v.string() },
       returns: v.union(vAssemblyResponse, v.null()),
@@ -249,7 +286,7 @@ export function makeTransloaditAPI(
       args: {
         assemblyId: v.string(),
         userId: v.optional(v.string()),
-        fields: v.optional(v.any()),
+        fields: v.optional(v.record(v.string(), v.any())),
       },
       returns: v.union(vAssemblyResponse, v.null()),
       handler: async (ctx, args) => {

package/src/client/types.ts

@@ -33,17 +33,18 @@ export type QueryCtx = RunQueryCtx & {
   storage: StorageReader;
 };
 
-export type OpaqueIds<T> = T extends GenericId<infer _T>
-  ? string
-  : T extends (infer U)[]
-    ? OpaqueIds<U>[]
-    : T extends ArrayBuffer
-      ? ArrayBuffer
-      : T extends object
-        ? {
-            [K in keyof T]: OpaqueIds<T[K]>;
-          }
-        : T;
+export type OpaqueIds<T> =
+  T extends GenericId<infer _T>
+    ? string
+    : T extends (infer U)[]
+      ? OpaqueIds<U>[]
+      : T extends ArrayBuffer
+        ? ArrayBuffer
+        : T extends object
+          ? {
+              [K in keyof T]: OpaqueIds<T[K]>;
+            }
+          : T;
 
 export type UseApi<API> = Expand<{
   [mod in keyof API]: API[mod] extends FunctionReference<

package/src/component/_generated/component.ts

@@ -60,24 +60,43 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       { assemblyId: string; data: any },
       Name
     >;
-    generateUploadParams: FunctionReference<
+    handleWebhook: FunctionReference<
       "action",
       "internal",
       {
-        config: { authKey: string; authSecret: string };
-        templateId?: string;
-        steps?: any;
-        fields?: any;
-        notifyUrl?: string;
-        numExpectedUploadFiles?: number;
-        expires?: string;
-        additionalParams?: any;
-        userId?: string;
+        payload: any;
+        rawBody?: string;
+        signature?: string;
+        verifySignature?: boolean;
+        config?: { authSecret: string };
+      },
+      {
+        assemblyId: string;
+        resultCount: number;
+        ok?: string;
+        status?: string;
       },
-      { params: string; signature: string; url: string },
       Name
     >;
-    handleWebhook: FunctionReference<
+    processWebhook: FunctionReference<
+      "action",
+      "internal",
+      {
+        payload: any;
+        rawBody?: string;
+        signature?: string;
+        verifySignature?: boolean;
+        authSecret?: string;
+      },
+      {
+        assemblyId: string;
+        resultCount: number;
+        ok?: string;
+        status?: string;
+      },
+      Name
+    >;
+    queueWebhook: FunctionReference<
       "action",
       "internal",
       {
@@ -87,7 +106,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         verifySignature?: boolean;
         config?: { authSecret: string };
       },
-      { assemblyId: string; resultCount: number },
+      { assemblyId: string; queued: boolean },
+      Name
+    >;
+    refreshAssembly: FunctionReference<
+      "action",
+      "internal",
+      { assemblyId: string; config?: { authKey: string; authSecret: string } },
+      {
+        assemblyId: string;
+        resultCount: number;
+        ok?: string;
+        status?: string;
+      },
       Name
     >;
     getAssemblyStatus: FunctionReference<

package/src/component/apiUtils.test.ts

@@ -2,6 +2,7 @@ import { createHmac } from "node:crypto";
 import { describe, expect, test } from "vitest";
 import {
   buildTransloaditParams,
+  parseTransloaditWebhook,
   signTransloaditParams,
   verifyWebhookSignature,
 } from "./apiUtils.js";
@@ -45,4 +46,32 @@ describe("apiUtils", () => {
 
     expect(verified).toBe(true);
   });
+
+  test("parseTransloaditWebhook returns payload and 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:abc");
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    const result = await parseTransloaditWebhook(request);
+    expect(result.payload).toEqual(payload);
+    expect(result.rawBody).toBe(JSON.stringify(payload));
+    expect(result.signature).toBe("sha384:abc");
+  });
+
+  test("parseTransloaditWebhook throws on missing payload", async () => {
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: new FormData(),
+    });
+
+    await expect(parseTransloaditWebhook(request)).rejects.toThrow(
+      "Missing transloadit payload",
+    );
+  });
 });

package/src/component/apiUtils.ts

@@ -1,3 +1,6 @@
+import type { AssemblyStatusResults } from "@transloadit/types/assemblyStatus";
+import type { AssemblyInstructionsInput } from "@transloadit/types/template";
+
 export interface TransloaditAuthConfig {
   authKey: string;
   authSecret: string;
@@ -6,8 +9,8 @@ export interface TransloaditAuthConfig {
 export interface BuildParamsOptions {
   authKey: string;
   templateId?: string;
-  steps?: Record<string, unknown>;
-  fields?: Record<string, unknown>;
+  steps?: AssemblyInstructionsInput["steps"];
+  fields?: AssemblyInstructionsInput["fields"];
   notifyUrl?: string;
   numExpectedUploadFiles?: number;
   expires?: string;
@@ -64,30 +67,27 @@ async function hmacHex(
   key: string,
   data: string,
 ): Promise<string> {
-  if (globalThis.crypto?.subtle) {
-    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("");
+  if (!globalThis.crypto?.subtle) {
+    throw new Error("Web Crypto is required to sign Transloadit payloads");
   }
 
-  const { createHmac } = await import("node:crypto");
-  return createHmac(algorithm.replace("-", "").toLowerCase(), key)
-    .update(data)
-    .digest("hex");
+  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(
@@ -98,6 +98,30 @@ export async function signTransloaditParams(
   return `sha384:${signature}`;
 }
 
+export type ParsedWebhookRequest = {
+  payload: unknown;
+  rawBody: string;
+  signature?: string;
+};
+
+export async function parseTransloaditWebhook(
+  request: Request,
+): Promise<ParsedWebhookRequest> {
+  const formData = await request.formData();
+  const rawPayload = formData.get("transloadit");
+  const signature = formData.get("signature");
+
+  if (typeof rawPayload !== "string") {
+    throw new Error("Missing transloadit payload");
+  }
+
+  return {
+    payload: JSON.parse(rawPayload),
+    rawBody: rawPayload,
+    signature: typeof signature === "string" ? signature : undefined,
+  };
+}
+
 function safeCompare(a: string, b: string): boolean {
   if (a.length !== b.length) return false;
   let mismatch = 0;
@@ -136,13 +160,15 @@ export async function verifyWebhookSignature(options: {
   return safeCompare(expected, sig);
 }
 
+export type AssemblyResult = AssemblyStatusResults[string][number];
+
 export type AssemblyResultRecord = {
   stepName: string;
-  result: Record<string, unknown>;
+  result: AssemblyResult;
 };
 
 export function flattenResults(
-  results: Record<string, Array<Record<string, unknown>>> | undefined,
+  results: AssemblyStatusResults | undefined,
 ): AssemblyResultRecord[] {
   if (!results) return [];
   const output: AssemblyResultRecord[] = [];

package/src/component/lib.test.ts

@@ -2,13 +2,13 @@
 
 import { createHmac } from "node:crypto";
 import { convexTest } from "convex-test";
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 import { api } from "./_generated/api.js";
 import schema from "./schema.js";
 import { modules } from "./setup.test.js";
 
-process.env.TRANSLOADIT_AUTH_KEY = "test-key";
-process.env.TRANSLOADIT_AUTH_SECRET = "test-secret";
+process.env.TRANSLOADIT_KEY = "test-key";
+process.env.TRANSLOADIT_SECRET = "test-secret";
 
 describe("Transloadit component lib", () => {
   test("handleWebhook stores assembly and results", async () => {
@@ -60,4 +60,74 @@ describe("Transloadit component lib", () => {
     expect(results).toHaveLength(1);
     expect(results[0]?.stepName).toBe("resized");
   });
+
+  test("refreshAssembly fetches status and stores results", async () => {
+    const t = convexTest(schema, modules);
+
+    const payload = {
+      assembly_id: "asm_456",
+      ok: "ASSEMBLY_COMPLETED",
+      message: "Assembly complete",
+      results: {
+        resized: [
+          {
+            id: "file_2",
+            ssl_url: "https://example.com/file-2.jpg",
+            name: "file-2.jpg",
+            size: 54321,
+            mime: "image/jpeg",
+          },
+        ],
+      },
+    };
+
+    const fetchMock = vi.fn<typeof fetch>(async () => {
+      return new Response(JSON.stringify(payload), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    });
+
+    vi.stubGlobal("fetch", fetchMock);
+
+    try {
+      const result = await t.action(api.lib.refreshAssembly, {
+        assemblyId: "asm_456",
+        config: { authKey: "test-key", authSecret: "test-secret" },
+      });
+
+      expect(result.assemblyId).toBe("asm_456");
+      expect(result.ok).toBe("ASSEMBLY_COMPLETED");
+
+      const requestInfo = fetchMock.mock.calls[0]?.[0];
+      const requestUrl =
+        typeof requestInfo === "string"
+          ? requestInfo
+          : requestInfo instanceof URL
+            ? requestInfo.toString()
+            : requestInfo instanceof Request
+              ? requestInfo.url
+              : "";
+      if (!requestUrl) {
+        throw new Error("Expected fetch to be called with a URL string");
+      }
+      const url = new URL(requestUrl);
+      expect(url.origin).toBe("https://api2.transloadit.com");
+      expect(url.searchParams.get("signature")).toBeTruthy();
+      expect(url.searchParams.get("params")).toBeTruthy();
+
+      const assembly = await t.query(api.lib.getAssemblyStatus, {
+        assemblyId: "asm_456",
+      });
+      expect(assembly?.ok).toBe("ASSEMBLY_COMPLETED");
+
+      const results = await t.query(api.lib.listResults, {
+        assemblyId: "asm_456",
+      });
+      expect(results).toHaveLength(1);
+      expect(results[0]?.stepName).toBe("resized");
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
 });