@transloadit/convex 0.0.1

package/src/client/index.ts

@@ -0,0 +1,260 @@
+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 interface TransloaditConfig {
+  authKey: string;
+  authSecret: string;
+}
+
+export type TransloaditComponent = ComponentApi;
+
+function requireEnv(names: string[]): string {
+  for (const name of names) {
+    const value = process.env[name];
+    if (value) {
+      return value;
+    }
+  }
+  throw new Error(`Missing ${names.join(" or ")} environment variable`);
+}
+
+export const vAssemblyResponse = v.object({
+  _id: v.string(),
+  _creationTime: v.number(),
+  assemblyId: v.string(),
+  status: v.optional(v.string()),
+  ok: v.optional(v.string()),
+  message: v.optional(v.string()),
+  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()),
+  error: v.optional(v.any()),
+  raw: v.optional(v.any()),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+  userId: v.optional(v.string()),
+});
+
+export type AssemblyResponse = Infer<typeof vAssemblyResponse>;
+
+export const vAssemblyResultResponse = v.object({
+  _id: v.string(),
+  _creationTime: v.number(),
+  assemblyId: v.string(),
+  stepName: v.string(),
+  resultId: v.optional(v.string()),
+  sslUrl: v.optional(v.string()),
+  name: v.optional(v.string()),
+  size: v.optional(v.number()),
+  mime: v.optional(v.string()),
+  raw: v.any(),
+  createdAt: v.number(),
+});
+
+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()),
+  notifyUrl: v.optional(v.string()),
+  numExpectedUploadFiles: v.optional(v.number()),
+  expires: v.optional(v.string()),
+  additionalParams: v.optional(v.any()),
+  userId: v.optional(v.string()),
+});
+
+export class TransloaditClient {
+  declare component: TransloaditComponent;
+  declare config: TransloaditConfig;
+
+  constructor(
+    component: TransloaditComponent,
+    config?: Partial<TransloaditConfig>,
+  ) {
+    this.component = component;
+    this.config = {
+      authKey:
+        config?.authKey ??
+        requireEnv(["TRANSLOADIT_AUTH_KEY", "TRANSLOADIT_KEY"]),
+      authSecret:
+        config?.authSecret ??
+        requireEnv(["TRANSLOADIT_AUTH_SECRET", "TRANSLOADIT_SECRET"]),
+    };
+  }
+
+  static create(component: TransloaditComponent, config: TransloaditConfig) {
+    return new TransloaditClient(component, config);
+  }
+
+  async createAssembly(
+    ctx: RunActionCtx,
+    args: Infer<typeof vCreateAssemblyArgs>,
+  ) {
+    return ctx.runAction(this.component.lib.createAssembly, {
+      ...args,
+      config: this.config,
+    });
+  }
+
+  async generateUploadParams(
+    ctx: RunActionCtx,
+    args: Infer<typeof vCreateAssemblyArgs>,
+  ) {
+    return ctx.runAction(this.component.lib.generateUploadParams, {
+      ...args,
+      config: this.config,
+    });
+  }
+
+  async handleWebhook(
+    ctx: RunActionCtx,
+    args: {
+      payload: unknown;
+      rawBody?: string;
+      signature?: string;
+      verifySignature?: boolean;
+    },
+  ) {
+    return ctx.runAction(this.component.lib.handleWebhook, {
+      ...args,
+      config: { authSecret: this.config.authSecret },
+    });
+  }
+
+  async getAssemblyStatus(ctx: RunQueryCtx, assemblyId: string) {
+    return ctx.runQuery(this.component.lib.getAssemblyStatus, { assemblyId });
+  }
+
+  async listAssemblies(
+    ctx: RunQueryCtx,
+    args?: { status?: string; userId?: string; limit?: number },
+  ) {
+    return ctx.runQuery(this.component.lib.listAssemblies, args ?? {});
+  }
+
+  async listResults(
+    ctx: RunQueryCtx,
+    args: { assemblyId: string; stepName?: string; limit?: number },
+  ) {
+    return ctx.runQuery(this.component.lib.listResults, args);
+  }
+
+  async storeAssemblyMetadata(
+    ctx: RunMutationCtx,
+    args: { assemblyId: string; userId?: string; fields?: unknown },
+  ) {
+    return ctx.runMutation(this.component.lib.storeAssemblyMetadata, args);
+  }
+
+  api() {
+    return makeTransloaditAPI(this.component, this.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"]),
+  };
+
+  return {
+    createAssembly: actionGeneric({
+      args: vCreateAssemblyArgs,
+      returns: v.object({
+        assemblyId: v.string(),
+        data: v.any(),
+      }),
+      handler: async (ctx, args) => {
+        return ctx.runAction(component.lib.createAssembly, {
+          ...args,
+          config: resolvedConfig,
+        });
+      },
+    }),
+    generateUploadParams: actionGeneric({
+      args: vCreateAssemblyArgs,
+      returns: v.object({
+        params: v.string(),
+        signature: v.string(),
+        url: v.string(),
+      }),
+      handler: async (ctx, args) => {
+        return ctx.runAction(component.lib.generateUploadParams, {
+          ...args,
+          config: resolvedConfig,
+        });
+      },
+    }),
+    handleWebhook: actionGeneric({
+      args: {
+        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(),
+      }),
+      handler: async (ctx, args) => {
+        return ctx.runAction(component.lib.handleWebhook, {
+          ...args,
+          config: { authSecret: resolvedConfig.authSecret },
+        });
+      },
+    }),
+    getAssemblyStatus: queryGeneric({
+      args: { assemblyId: v.string() },
+      returns: v.union(vAssemblyResponse, v.null()),
+      handler: async (ctx, args) => {
+        return ctx.runQuery(component.lib.getAssemblyStatus, args);
+      },
+    }),
+    listAssemblies: queryGeneric({
+      args: {
+        status: v.optional(v.string()),
+        userId: v.optional(v.string()),
+        limit: v.optional(v.number()),
+      },
+      returns: v.array(vAssemblyResponse),
+      handler: async (ctx, args) => {
+        return ctx.runQuery(component.lib.listAssemblies, args);
+      },
+    }),
+    listResults: queryGeneric({
+      args: {
+        assemblyId: v.string(),
+        stepName: v.optional(v.string()),
+        limit: v.optional(v.number()),
+      },
+      returns: v.array(vAssemblyResultResponse),
+      handler: async (ctx, args) => {
+        return ctx.runQuery(component.lib.listResults, args);
+      },
+    }),
+    storeAssemblyMetadata: mutationGeneric({
+      args: {
+        assemblyId: v.string(),
+        userId: v.optional(v.string()),
+        fields: v.optional(v.any()),
+      },
+      returns: v.union(vAssemblyResponse, v.null()),
+      handler: async (ctx, args) => {
+        return ctx.runMutation(component.lib.storeAssemblyMetadata, args);
+      },
+    }),
+  };
+}

package/src/client/types.ts

@@ -0,0 +1,64 @@
+import type {
+  Expand,
+  FunctionArgs,
+  FunctionReference,
+  FunctionReturnType,
+  StorageActionWriter,
+  StorageReader,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+
+export type RunQueryCtx = {
+  runQuery: <Query extends FunctionReference<"query", "internal">>(
+    query: Query,
+    args: FunctionArgs<Query>,
+  ) => Promise<FunctionReturnType<Query>>;
+};
+export type RunMutationCtx = RunQueryCtx & {
+  runMutation: <Mutation extends FunctionReference<"mutation", "internal">>(
+    mutation: Mutation,
+    args: FunctionArgs<Mutation>,
+  ) => Promise<FunctionReturnType<Mutation>>;
+};
+export type RunActionCtx = RunMutationCtx & {
+  runAction: <Action extends FunctionReference<"action", "internal">>(
+    action: Action,
+    args: FunctionArgs<Action>,
+  ) => Promise<FunctionReturnType<Action>>;
+};
+export type ActionCtx = RunActionCtx & {
+  storage: StorageActionWriter;
+};
+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 UseApi<API> = Expand<{
+  [mod in keyof API]: API[mod] extends FunctionReference<
+    infer FType,
+    "public",
+    infer FArgs,
+    infer FReturnType,
+    infer FComponentPath
+  >
+    ? FunctionReference<
+        FType,
+        "internal",
+        OpaqueIds<FArgs>,
+        OpaqueIds<FReturnType>,
+        FComponentPath
+      >
+    : UseApi<API[mod]>;
+}>;

package/src/component/_generated/api.ts

@@ -0,0 +1,32 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as apiUtils from "../apiUtils.js";
+import type * as lib from "../lib.js";
+
+import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  apiUtils: typeof apiUtils;
+  lib: typeof lib;
+}> = anyApi as any;
+
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,122 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+export type ComponentApi<Name extends string | undefined = string | undefined> = {
+  lib: {
+    upsertAssembly: FunctionReference<
+      "mutation",
+      "internal",
+      {
+        assemblyId: string;
+        status?: string;
+        ok?: string;
+        message?: string;
+        templateId?: string;
+        notifyUrl?: string;
+        numExpectedUploadFiles?: number;
+        fields?: any;
+        uploads?: any;
+        results?: any;
+        error?: any;
+        raw?: any;
+        userId?: string;
+      },
+      string,
+      Name
+    >;
+    replaceResultsForAssembly: FunctionReference<
+      "mutation",
+      "internal",
+      {
+        assemblyId: string;
+        results: Array<{ stepName: string; result: any }>;
+      },
+      null,
+      Name
+    >;
+    createAssembly: FunctionReference<
+      "action",
+      "internal",
+      {
+        config: { authKey: string; authSecret: string };
+        templateId?: string;
+        steps?: any;
+        fields?: any;
+        notifyUrl?: string;
+        numExpectedUploadFiles?: number;
+        expires?: string;
+        additionalParams?: any;
+        userId?: string;
+      },
+      { assemblyId: string; data: any },
+      Name
+    >;
+    generateUploadParams: FunctionReference<
+      "action",
+      "internal",
+      {
+        config: { authKey: string; authSecret: string };
+        templateId?: string;
+        steps?: any;
+        fields?: any;
+        notifyUrl?: string;
+        numExpectedUploadFiles?: number;
+        expires?: string;
+        additionalParams?: any;
+        userId?: string;
+      },
+      { params: string; signature: string; url: string },
+      Name
+    >;
+    handleWebhook: FunctionReference<
+      "action",
+      "internal",
+      {
+        payload: any;
+        rawBody?: string;
+        signature?: string;
+        verifySignature?: boolean;
+        config?: { authSecret: string };
+      },
+      { assemblyId: string; resultCount: number },
+      Name
+    >;
+    getAssemblyStatus: FunctionReference<
+      "query",
+      "internal",
+      { assemblyId: string },
+      any,
+      Name
+    >;
+    listAssemblies: FunctionReference<
+      "query",
+      "internal",
+      { status?: string; userId?: string; limit?: number },
+      Array<any>,
+      Name
+    >;
+    listResults: FunctionReference<
+      "query",
+      "internal",
+      { assemblyId: string; stepName?: string; limit?: number },
+      Array<any>,
+      Name
+    >;
+    storeAssemblyMetadata: FunctionReference<
+      "mutation",
+      "internal",
+      { assemblyId: string; userId?: string; fields?: any },
+      any,
+      Name
+    >;
+  };
+};

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,30 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/component/_generated/server.ts

@@ -0,0 +1,72 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+type GenericCtx =
+  | GenericActionCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericQueryCtx<DataModel>;
+
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;
+
+export type DatabaseReaderWriter = GenericDatabaseWriter<DataModel> &
+  GenericDatabaseReader<DataModel>;
+
+export type FunctionCtx = GenericCtx & {
+  runQuery: GenericQueryCtx<DataModel>["runQuery"];
+  runMutation: GenericMutationCtx<DataModel>["runMutation"];
+  runAction: GenericActionCtx<DataModel>["runAction"];
+};

package/src/component/apiUtils.test.ts

@@ -0,0 +1,48 @@
+import { createHmac } from "node:crypto";
+import { describe, expect, test } from "vitest";
+import {
+  buildTransloaditParams,
+  signTransloaditParams,
+  verifyWebhookSignature,
+} from "./apiUtils.js";
+
+describe("apiUtils", () => {
+  test("buildTransloaditParams requires templateId or steps", () => {
+    expect(() =>
+      buildTransloaditParams({
+        authKey: "key",
+      }),
+    ).toThrow("Provide either templateId or steps");
+  });
+
+  test("signTransloaditParams uses sha384", async () => {
+    const { paramsString } = buildTransloaditParams({
+      authKey: "key",
+      templateId: "tmpl_123",
+      notifyUrl: "https://example.com/webhook",
+    });
+
+    const signature = await signTransloaditParams(paramsString, "secret");
+    expect(signature.startsWith("sha384:")).toBe(true);
+
+    const expected = createHmac("sha384", "secret")
+      .update(paramsString)
+      .digest("hex");
+    expect(signature).toBe(`sha384:${expected}`);
+  });
+
+  test("verifyWebhookSignature supports sha1 fallback", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const secret = "webhook-secret";
+    const digest = createHmac("sha1", secret).update(rawBody).digest("hex");
+
+    const verified = await verifyWebhookSignature({
+      rawBody,
+      signatureHeader: `sha1:${digest}`,
+      authSecret: secret,
+    });
+
+    expect(verified).toBe(true);
+  });
+});