@transloadit/convex 0.0.3 → 0.0.4

package/src/react/uploadWithTus.test.tsx

@@ -0,0 +1,192 @@
+/// <reference types="vite/client" />
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+import type { UploadState } from "./index.tsx";
+
+vi.mock("tus-js-client", () => {
+  type UploadOptions = {
+    onUploadUrlAvailable?: () => void;
+    onProgress?: (bytesUploaded: number, bytesTotal: number) => void;
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+  };
+
+  class Upload {
+    url: string;
+    options: UploadOptions;
+    file: File;
+    aborted = false;
+
+    constructor(file: File, options: UploadOptions) {
+      this.file = file;
+      this.options = options;
+      this.url = `https://upload.example.com/${encodeURIComponent(file.name)}`;
+    }
+
+    start() {
+      const shouldFail = this.file.name.includes("fail");
+      const delay = this.file.name.includes("slow") ? 25 : 0;
+      this.options.onUploadUrlAvailable?.();
+      this.options.onProgress?.(10, 10);
+      setTimeout(() => {
+        if (this.aborted) return;
+        if (shouldFail) {
+          this.options.onError?.(new Error("Upload failed"));
+          return;
+        }
+        this.options.onSuccess?.();
+      }, delay);
+    }
+
+    abort() {
+      this.aborted = true;
+    }
+  }
+
+  return { Upload };
+});
+
+import {
+  uploadFilesWithTransloaditTus,
+  uploadWithTransloaditTus,
+} from "./index.tsx";
+
+describe("uploadWithTransloaditTus", () => {
+  it("uploads with tus and emits progress", async () => {
+    const createAssembly = vi.fn(async () => ({
+      assemblyId: "asm_123",
+      data: {
+        tus_url: "https://tus.transloadit.com",
+        assembly_ssl_url: "https://transloadit.com/assembly",
+      },
+    }));
+    const file = new File(["hello"], "hello.txt", { type: "text/plain" });
+    const states: UploadState[] = [];
+    const progress: number[] = [];
+
+    const result = await uploadWithTransloaditTus(
+      createAssembly,
+      file,
+      {
+        numExpectedUploadFiles: 1,
+        onProgress: (value) => progress.push(value),
+      },
+      {
+        onStateChange: (state) => states.push(state),
+      },
+    );
+
+    expect(createAssembly).toHaveBeenCalledWith(
+      expect.objectContaining({ numExpectedUploadFiles: 1 }),
+    );
+    expect(result.assemblyId).toBe("asm_123");
+    expect(progress).toContain(100);
+    expect(states[0]).toEqual({ isUploading: true, progress: 0, error: null });
+    expect(states[states.length - 1]).toEqual({
+      isUploading: false,
+      progress: 100,
+      error: null,
+    });
+  });
+
+  it("fails when tus_url is missing", async () => {
+    const createAssembly = vi.fn(async () => ({
+      assemblyId: "asm_456",
+      data: {},
+    }));
+    const file = new File(["hello"], "hello.txt", { type: "text/plain" });
+    const states: UploadState[] = [];
+
+    await expect(
+      uploadWithTransloaditTus(
+        createAssembly,
+        file,
+        { numExpectedUploadFiles: 1 },
+        { onStateChange: (state) => states.push(state) },
+      ),
+    ).rejects.toThrow("tus_url");
+
+    const lastState = states[states.length - 1];
+    expect(lastState?.error).toBeInstanceOf(Error);
+    expect(lastState?.isUploading).toBe(false);
+  });
+});
+
+describe("uploadFilesWithTransloaditTus", () => {
+  const createAssembly = vi.fn(async () => ({
+    assemblyId: "asm_multi",
+    data: {
+      tus_url: "https://tus.transloadit.com",
+      assembly_ssl_url: "https://transloadit.com/assembly",
+    },
+  }));
+
+  it("uploads multiple files with overall progress", async () => {
+    const files = [
+      new File(["one"], "one.txt", { type: "text/plain" }),
+      new File(["two"], "two.txt", { type: "text/plain" }),
+    ];
+    const overall: number[] = [];
+    const perFile: Array<{ name: string; progress: number }> = [];
+
+    const controller = uploadFilesWithTransloaditTus(createAssembly, files, {
+      numExpectedUploadFiles: files.length,
+      onOverallProgress: (progress) => overall.push(progress),
+      onFileProgress: (file, progress) =>
+        perFile.push({ name: file.name, progress }),
+    });
+    const result = await controller.promise;
+
+    expect(result.assemblyId).toBe("asm_multi");
+    expect(result.files.every((file) => file.status === "success")).toBe(true);
+    expect(overall[overall.length - 1]).toBe(100);
+    expect(perFile.map((entry) => entry.name)).toEqual(
+      expect.arrayContaining(["one.txt", "two.txt"]),
+    );
+  });
+
+  it("does not reach 100% before all files start", async () => {
+    const files = [
+      new File(["slow"], "slow.txt", { type: "text/plain" }),
+      new File(["two"], "two.txt", { type: "text/plain" }),
+    ];
+    const overall: number[] = [];
+
+    const controller = uploadFilesWithTransloaditTus(createAssembly, files, {
+      numExpectedUploadFiles: files.length,
+      concurrency: 1,
+      onOverallProgress: (progress) => overall.push(progress),
+    });
+    await controller.promise;
+
+    expect(overall[0]).toBeLessThan(100);
+  });
+
+  it("returns results on partial failure when failFast is false", async () => {
+    const files = [
+      new File(["ok"], "ok.txt", { type: "text/plain" }),
+      new File(["bad"], "fail.txt", { type: "text/plain" }),
+    ];
+
+    await expect(
+      uploadFilesWithTransloaditTus(createAssembly, files, {
+        failFast: false,
+      }).promise,
+    ).rejects.toThrow("Failed to upload");
+  });
+
+  it("cancels uploads and surfaces results", async () => {
+    const files = [
+      new File(["slow"], "slow.txt", { type: "text/plain" }),
+      new File(["slow"], "slow-2.txt", { type: "text/plain" }),
+    ];
+    const controller = uploadFilesWithTransloaditTus(createAssembly, files, {
+      failFast: true,
+    });
+
+    controller.cancel();
+
+    await expect(controller.promise).rejects.toThrow("Upload canceled");
+  });
+});

package/src/shared/assemblyUrls.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+  ASSEMBLY_STATUS_COMPLETED,
+  ASSEMBLY_STATUS_UPLOADING,
+  getAssemblyStage,
+  isAssemblyCompletedStatus,
+  isAssemblyUploadingStatus,
+  parseAssemblyFields,
+  parseAssemblyResults,
+  parseAssemblyStatus,
+  parseAssemblyUrls,
+} from "./assemblyUrls.ts";
+
+describe("assembly helpers", () => {
+  it("parses tus and assembly URLs with fallbacks", () => {
+    const parsed = parseAssemblyUrls({
+      tus_url: "https://tus.transloadit.com",
+      assembly_ssl_url: "https://ssl.transloadit.com/assembly",
+      assembly_url: "https://transloadit.com/assembly",
+    });
+
+    expect(parsed).toEqual({
+      tusUrl: "https://tus.transloadit.com",
+      assemblyUrl: "https://ssl.transloadit.com/assembly",
+    });
+
+    const fallback = parseAssemblyUrls({
+      tusUrl: "https://tus.example.com",
+      assemblyUrl: "https://assembly.example.com",
+    });
+
+    expect(fallback).toEqual({
+      tusUrl: "https://tus.example.com",
+      assemblyUrl: "https://assembly.example.com",
+    });
+  });
+
+  it("parses assembly status, fields, and results safely", () => {
+    const status = {
+      ok: "ASSEMBLY_COMPLETED",
+      fields: { album: "wedding-gallery" },
+      results: {
+        images_output: [
+          {
+            id: "result-1",
+            ssl_url: "https://cdn.example.com/image.jpg",
+          },
+        ],
+      },
+    };
+
+    expect(parseAssemblyStatus(status)?.ok).toBe("ASSEMBLY_COMPLETED");
+    expect(parseAssemblyFields(status)).toEqual({ album: "wedding-gallery" });
+    expect(Object.keys(parseAssemblyResults(status))).toEqual([
+      "images_output",
+    ]);
+
+    expect(parseAssemblyStatus("nope")).toBeNull();
+    expect(parseAssemblyFields("nope")).toEqual({});
+    expect(parseAssemblyResults("nope")).toEqual({});
+  });
+
+  it("exposes canonical status helpers", () => {
+    expect(isAssemblyCompletedStatus(ASSEMBLY_STATUS_COMPLETED)).toBe(true);
+    expect(isAssemblyCompletedStatus(ASSEMBLY_STATUS_UPLOADING)).toBe(false);
+    expect(isAssemblyUploadingStatus(ASSEMBLY_STATUS_UPLOADING)).toBe(true);
+    expect(getAssemblyStage({ ok: ASSEMBLY_STATUS_COMPLETED })).toBe(
+      "complete",
+    );
+  });
+});

package/src/shared/assemblyUrls.ts

@@ -0,0 +1,59 @@
+import {
+  ASSEMBLY_STATUS_COMPLETED,
+  ASSEMBLY_STATUS_UPLOADING,
+  type AssemblyStatus,
+  type AssemblyStatusResults,
+  assemblyStatusSchema,
+  getAssemblyStage,
+  isAssemblyCompletedStatus,
+  isAssemblyUploadingStatus,
+  normalizeAssemblyUploadUrls,
+  parseAssemblyUrls,
+  type AssemblyStage as ZodAssemblyStage,
+  type AssemblyUrls as ZodAssemblyUrls,
+  type NormalizedAssemblyUrls as ZodNormalizedAssemblyUrls,
+} from "@transloadit/zod/v3";
+
+export type AssemblyUrls = ZodAssemblyUrls;
+export type NormalizedAssemblyUrls = ZodNormalizedAssemblyUrls;
+export type AssemblyStage = ZodAssemblyStage;
+export type TransloaditAssembly = AssemblyStatus;
+export {
+  ASSEMBLY_STATUS_COMPLETED,
+  ASSEMBLY_STATUS_UPLOADING,
+  getAssemblyStage,
+  isAssemblyCompletedStatus,
+  isAssemblyUploadingStatus,
+  normalizeAssemblyUploadUrls,
+  parseAssemblyUrls,
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+export const parseAssemblyStatus = (
+  data: unknown,
+): TransloaditAssembly | null => {
+  const parsed = assemblyStatusSchema.safeParse(data);
+  return parsed.success ? parsed.data : null;
+};
+
+export const parseAssemblyFields = (data: unknown): Record<string, unknown> => {
+  const status = parseAssemblyStatus(data);
+  const fields = status?.fields;
+  return isRecord(fields) ? fields : {};
+};
+
+export const parseAssemblyResults = (data: unknown): AssemblyStatusResults => {
+  const status = parseAssemblyStatus(data);
+  const results = status?.results;
+  if (!isRecord(results)) return {};
+
+  const output: AssemblyStatusResults = {};
+  for (const [key, value] of Object.entries(results)) {
+    if (Array.isArray(value)) {
+      output[key] = value as AssemblyStatusResults[string];
+    }
+  }
+  return output;
+};

package/src/shared/errors.ts

@@ -0,0 +1,23 @@
+export type TransloaditErrorContext =
+  | "createAssembly"
+  | "upload"
+  | "polling"
+  | "status"
+  | "webhook"
+  | "payload"
+  | "config";
+
+export class TransloaditError extends Error {
+  readonly context: TransloaditErrorContext;
+
+  constructor(context: TransloaditErrorContext, message: string) {
+    super(`Transloadit ${context}: ${message}`);
+    this.name = "TransloaditError";
+    this.context = context;
+  }
+}
+
+export const transloaditError = (
+  context: TransloaditErrorContext,
+  message: string,
+): TransloaditError => new TransloaditError(context, message);

package/src/shared/pollAssembly.ts

@@ -0,0 +1,65 @@
+import { transloaditError } from "./errors.ts";
+
+export type PollAssemblyOptions = {
+  intervalMs: number;
+  refresh: () => Promise<void>;
+  isTerminal?: () => boolean;
+  shouldContinue?: () => boolean;
+  onError?: (error: Error) => void;
+};
+
+export type PollAssemblyController = {
+  stop: () => void;
+};
+
+export const pollAssembly = (
+  options: PollAssemblyOptions,
+): PollAssemblyController => {
+  const intervalMs = Math.max(0, options.intervalMs);
+  let cancelled = false;
+  let intervalId: ReturnType<typeof setInterval> | null = null;
+  let inFlight = false;
+
+  const shouldKeepPolling = () => {
+    if (!options.isTerminal?.()) return true;
+    return options.shouldContinue?.() ?? false;
+  };
+
+  const stop = () => {
+    cancelled = true;
+    if (intervalId) clearInterval(intervalId);
+    intervalId = null;
+  };
+
+  if (intervalMs <= 0) {
+    return { stop };
+  }
+
+  const poll = async () => {
+    if (cancelled) return;
+    if (!shouldKeepPolling()) {
+      stop();
+      return;
+    }
+    if (inFlight) return;
+    inFlight = true;
+    try {
+      await options.refresh();
+    } catch (error) {
+      const resolved =
+        error instanceof Error
+          ? error
+          : transloaditError("polling", "Refresh failed");
+      options.onError?.(resolved);
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  void poll();
+  intervalId = setInterval(() => {
+    void poll();
+  }, intervalMs);
+
+  return { stop };
+};

package/src/shared/resultTypes.ts

@@ -0,0 +1,44 @@
+import type { AssemblyStatusResult } from "@transloadit/zod/v3/assemblyStatus";
+
+export type TransloaditResult = AssemblyStatusResult;
+
+export type ImageResizeResult = AssemblyStatusResult & {
+  ssl_url?: string | null;
+  url?: string | null;
+  width?: number | null;
+  height?: number | null;
+  mime?: string | null;
+  size?: number | null;
+};
+
+export type VideoEncodeResult = AssemblyStatusResult & {
+  ssl_url?: string | null;
+  url?: string | null;
+  duration?: number | null;
+  streaming_url?: string;
+  hls_url?: string;
+};
+
+export type VideoThumbsResult = AssemblyStatusResult & {
+  ssl_url?: string | null;
+  url?: string | null;
+  width?: number | null;
+  height?: number | null;
+};
+
+export type StoreResult = AssemblyStatusResult & {
+  ssl_url?: string | null;
+  url?: string | null;
+  storage_url?: string;
+};
+
+export type ResultByRobot = {
+  "/image/resize": ImageResizeResult;
+  "/video/encode": VideoEncodeResult;
+  "/video/thumbs": VideoThumbsResult;
+  "/r2/store": StoreResult;
+  "/s3/store": StoreResult;
+};
+
+export type ResultForRobot<Robot extends keyof ResultByRobot> =
+  ResultByRobot[Robot];

package/src/shared/resultUtils.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { getResultOriginalKey, getResultUrl } from "./resultUtils.ts";
+
+describe("result utils", () => {
+  it("extracts result URLs with common fallbacks", () => {
+    expect(getResultUrl({ ssl_url: "https://cdn.example.com/file.jpg" })).toBe(
+      "https://cdn.example.com/file.jpg",
+    );
+    expect(
+      getResultUrl({
+        meta: { url: "https://cdn.example.com/meta.jpg" },
+      }),
+    ).toBe("https://cdn.example.com/meta.jpg");
+  });
+
+  it("derives original keys from raw metadata", () => {
+    expect(
+      getResultOriginalKey({
+        raw: { original_id: "orig_1" },
+      }),
+    ).toBe("orig_1");
+    expect(
+      getResultOriginalKey({
+        raw: { original_basename: "photo.jpg" },
+      }),
+    ).toBe("photo.jpg");
+    expect(getResultOriginalKey({ name: "fallback.jpg" })).toBe("fallback.jpg");
+  });
+});

package/src/shared/resultUtils.ts

@@ -0,0 +1,71 @@
+import type { TransloaditResult } from "./resultTypes.ts";
+
+const extractUrlFromContainer = (container: Record<string, unknown>) => {
+  const candidates = [
+    container.ssl_url,
+    container.sslUrl,
+    container.url,
+    container.cdn_url,
+    container.cdnUrl,
+    container.storage_url,
+    container.storageUrl,
+    container.result_url,
+    container.resultUrl,
+    container.signed_url,
+    container.signedUrl,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.length > 0) {
+      return candidate;
+    }
+  }
+  return undefined;
+};
+
+const extractNestedUrl = (value: unknown) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return extractUrlFromContainer(value as Record<string, unknown>);
+};
+
+export const getResultUrl = (result: TransloaditResult) => {
+  const direct = extractUrlFromContainer(result as Record<string, unknown>);
+  if (direct) return direct;
+
+  const nestedKeys = ["meta", "metadata", "result", "results", "file", "data"];
+  for (const key of nestedKeys) {
+    const nested = extractNestedUrl((result as Record<string, unknown>)[key]);
+    if (nested) return nested;
+  }
+
+  const urlsValue = (result as Record<string, unknown>).urls;
+  const urlsNested = extractNestedUrl(urlsValue);
+  if (urlsNested) return urlsNested;
+
+  const urlValue = (result as Record<string, unknown>).url;
+  const urlNested = extractNestedUrl(urlValue);
+  if (urlNested) return urlNested;
+
+  return undefined;
+};
+
+export const getResultOriginalKey = (result: TransloaditResult) => {
+  const raw = (result as TransloaditResult & { raw?: unknown }).raw;
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const rawRecord = raw as Record<string, unknown>;
+    const originalId = rawRecord.original_id;
+    if (typeof originalId === "string" && originalId.length > 0) {
+      return originalId;
+    }
+    const originalBase = rawRecord.original_basename;
+    if (typeof originalBase === "string" && originalBase.length > 0) {
+      return originalBase;
+    }
+  }
+
+  if (result.name) return result.name;
+  if (result.resultId) return result.resultId;
+  if (result._id) return result._id;
+  return null;
+};

package/src/shared/tusUpload.ts

@@ -0,0 +1,59 @@
+import { parseAssemblyUrls } from "./assemblyUrls.ts";
+import { transloaditError } from "./errors.ts";
+
+export type TusUploadConfig = {
+  endpoint: string;
+  metadata: Record<string, string>;
+  addRequestId: boolean;
+  tusUrl: string;
+  assemblyUrl: string;
+};
+
+export type TusMetadataOptions = {
+  fieldName?: string;
+  metadata?: Record<string, string>;
+};
+
+export const buildTusUploadConfig = (
+  assemblyData: unknown,
+  file: File,
+  options: TusMetadataOptions = {},
+): TusUploadConfig => {
+  const { tusUrl, assemblyUrl } = parseAssemblyUrls(assemblyData);
+
+  if (!tusUrl) {
+    throw transloaditError(
+      "upload",
+      "Transloadit response missing tus_url for resumable upload",
+    );
+  }
+
+  if (!assemblyUrl) {
+    throw transloaditError(
+      "upload",
+      "Transloadit response missing assembly_url for resumable upload",
+    );
+  }
+
+  const metadata: Record<string, string> = {
+    filename: file.name,
+    ...options.metadata,
+  };
+  if (file.type) {
+    metadata.filetype = file.type;
+  }
+  if (!metadata.fieldname) {
+    metadata.fieldname = options.fieldName ?? "file";
+  }
+  if (!metadata.assembly_url) {
+    metadata.assembly_url = assemblyUrl;
+  }
+
+  return {
+    endpoint: tusUrl,
+    metadata,
+    addRequestId: true,
+    tusUrl,
+    assemblyUrl,
+  };
+};

package/src/test/index.ts

@@ -1,7 +1,7 @@
 /// <reference types="vite/client" />
 
 import { convexTest } from "convex-test";
-import schema from "../component/schema.js";
+import schema from "../component/schema.ts";
 
 export const modules = import.meta.glob("../component/**/*.*s");
 

package/src/test/nodeModules.ts

@@ -0,0 +1,19 @@
+import * as apiModule from "../component/_generated/api.ts";
+import * as componentModule from "../component/_generated/component.ts";
+import * as dataModelModule from "../component/_generated/dataModel.ts";
+import * as serverModule from "../component/_generated/server.ts";
+import * as apiUtilsModule from "../component/apiUtils.ts";
+import * as convexConfigModule from "../component/convex.config.ts";
+import * as libModule from "../component/lib.ts";
+import * as schemaModule from "../component/schema.ts";
+
+export const modules: Record<string, () => Promise<unknown>> = {
+  "../component/apiUtils.ts": async () => apiUtilsModule,
+  "../component/lib.ts": async () => libModule,
+  "../component/convex.config.ts": async () => convexConfigModule,
+  "../component/schema.ts": async () => schemaModule,
+  "../component/_generated/api.ts": async () => apiModule,
+  "../component/_generated/component.ts": async () => componentModule,
+  "../component/_generated/dataModel.ts": async () => dataModelModule,
+  "../component/_generated/server.ts": async () => serverModule,
+};