convex-mux-component 0.1.6

package/README.md

@@ -0,0 +1,268 @@
+# Convex Mux Component
+
+Yo! 
+
+We made a reusable Convex component for apps that use Mux for video and Convex for backend data. We hear from devs and want to make it easier for you to build video apps with a database. Think about it, if you want to build the next TikTok, Instagram, or YouTube, you can use this component to get you started or even migrate your existing data from Mux to Convex and go from there! 
+
+Here's what this component provides:
+
+- Convex tables for Mux `assets`, `uploads`, `liveStreams`, and `events`
+- Upsert/delete mutations to keep those tables in sync
+- App-level `videoMetadata` storage (`userId`, title, visibility, tags, custom fields)
+- Query helpers for catalog and user-facing video data
+
+## Runtime Model (important info!)
+
+This package follows Convex component best practices:
+
+- The component package contains only component code (`convex.config.ts`, schema, queries, mutations)
+- Node runtime integration code (Mux SDK calls, webhook verification, backfills) lives in the consuming app
+- No CLI `bin` is shipped in the component package itself
+
+This is intentional and avoids bundling/runtime friction in consumer projects.
+
+
+## End-to-End Setup (From Scratch)
+
+## 1) Create a Convex app
+
+```sh
+npx create-convex@latest my-video-app
+cd my-video-app
+```
+
+If you use Bun:
+
+```sh
+bun install
+```
+
+Then start Convex once to provision/select your deployment:
+
+```sh
+npx convex dev
+```
+
+(You can use `bunx convex dev` if you prefer.)
+
+## 2) Install this component
+
+```sh
+npm i convex-mux-component
+```
+
+## 3) Mount the component
+
+Create or update `convex/convex.config.ts`:
+
+```ts
+import { defineApp } from "convex/server";
+import mux from "convex-mux-component/convex.config.js";
+
+const app = defineApp();
+app.use(mux, { name: "mux" });
+
+export default app;
+```
+
+`mux` is your mounted component name. If you use a different name, update all `components.mux...` calls accordingly. So basically if you want your table to be named `muxVideos`, you should mount it as `mux` and use `components.muxVideos` in your code.
+
+## 4) Add app-level wrappers (backfill + webhook)
+
+Use the scaffolder package we provided for you.This is a really fast way to migrate your data from Mux to Convex:
+
+```sh
+npx convex-mux-init --component-name mux
+```
+
+If `convex-mux-init` is not published yet, use the local tarball flow in
+`Optional: Scaffold Package In This Repo`.
+
+This creates:
+
+- `convex/migrations.ts`
+- `convex/muxWebhook.node.ts`
+
+Install Mux SDK in your app (required by generated files):
+
+```sh
+npm i @mux/mux-node
+```
+
+## 5) Add HTTP route for Mux webhook
+
+Create or update `convex/http.ts`:
+
+```ts
+import { httpRouter } from "convex/server";
+import { httpAction } from "./_generated/server";
+import { internal } from "./_generated/api";
+
+const http = httpRouter();
+
+http.route({
+  path: "/mux/webhook",
+  method: "POST",
+  handler: httpAction(async (ctx, request) => {
+    const rawBody = await request.text();
+    const headers = Object.fromEntries(request.headers.entries());
+    const result = await ctx.runAction(internal.muxWebhook.ingestMuxWebhook, {
+      rawBody,
+      headers,
+    });
+    return new Response(JSON.stringify(result), {
+      headers: { "content-type": "application/json" },
+    });
+  }),
+});
+
+export default http;
+```
+
+## 6) Add Mux credentials to Convex env
+
+You can set env vars from the Convex dashboard or CLI.
+
+Dashboard:
+
+- Open your project in Convex dashboard
+- Go to project/deployment settings for environment variables
+- Add:
+  - `MUX_TOKEN_ID`
+  - `MUX_TOKEN_SECRET`
+
+CLI equivalent:
+
+```sh
+npx convex env set MUX_TOKEN_ID <your_mux_token_id>
+npx convex env set MUX_TOKEN_SECRET <your_mux_token_secret>
+```
+
+## 7) Generate/apply schema and functions
+
+```sh
+npx convex dev
+```
+
+This applies component schema and generates `convex/_generated/*`.
+
+## 8) Backfill Mux assets into Convex
+
+Run the generated migration action:
+
+```sh
+npx convex run migrations:backfillMux '{}'
+```
+
+With options:
+
+```sh
+npx convex run migrations:backfillMux '{"maxAssets":500,"defaultUserId":"dev-user-1","includeVideoMetadata":true}'
+```
+
+For production deployment:
+
+```sh
+npx convex run --prod migrations:backfillMux '{"maxAssets":500}'
+```
+
+## Why Webhook URL Is Required
+
+Backfill is a one-time catch-up. It does not keep data fresh.
+
+Mux webhooks are how your app receives ongoing changes in near real time, such as:
+
+- asset status updates (for example `preparing` to `ready`)
+- deletions
+- upload and live stream lifecycle events
+
+Without the webhook URL:
+
+- component tables only update when you run backfill/manual sync
+- video state in Convex will drift from Mux over time
+
+## 9) Configure Mux webhook endpoint
+
+In Mux dashboard:
+
+- Create webhook endpoint
+- URL:
+  - Local testing (with tunnel): `https://<your-tunnel-domain>/mux/webhook`
+  - Deployed Convex app: `https://<your-deployment>.convex.site/mux/webhook`
+- Select desired video events (asset, upload, live stream)
+- Copy signing secret into `MUX_WEBHOOK_SECRET`
+Add through Convex dashboard:
+- Open your project in Convex dashboard
+- Go to project/deployment settings for environment variables
+- Add:
+  - `MUX_WEBHOOK_SECRET`
+  
+Set it via CLI(equivalent):
+
+```sh
+npx convex env set MUX_WEBHOOK_SECRET <your_mux_webhook_secret>
+```
+
+
+Note:
+
+- If you use deployed Convex URL, you do not need ngrok or any other tunneling services.
+- If your app is only local and not publicly reachable, use ngrok/cloudflare.
+
+## 10) Verify data
+
+In Convex dashboard data tables, you should see:
+
+- `assets`
+- `uploads`
+- `liveStreams`
+- `events`
+- `videoMetadata`
+
+## Local Testing This Package Before Publish
+
+From this component repo:
+
+```sh
+npm pack --cache /tmp/npm-cache
+```
+
+In a separate consumer app:
+
+```sh
+npm i /absolute/path/to/convex-mux-component-0.1.6.tgz
+npx convex dev
+```
+
+## Optional: Scaffold Package In This Repo
+
+The separate scaffolder lives in `scaffold/` and should be published as its own package (`convex-mux-init`).
+
+Build/test locally:
+
+```sh
+cd scaffold
+npm pack --cache /tmp/npm-cache
+```
+
+Then run in consumer app:
+
+```sh
+npm exec --yes --package /absolute/path/to/convex-mux-init-<version>.tgz convex-mux-init -- --component-name mux
+```
+
+## Troubleshooting
+
+- `Could not find function for 'migrations:backfillMux'`
+  - Ensure `convex/migrations.ts` exists and exports `backfillMux`
+  - Run `npx convex dev` again
+
+- `InvalidReference ... does not export [mux_node.backfillAssets]`
+  - Do not call `components.<name>.mux_node.*`
+  - Use app-level Node actions (`convex/migrations.ts`, `convex/muxWebhook.node.ts`) and call `components.<name>.sync.*Public`
+
+- `TypeScript ... webhooks.unwrap ... Record<string, unknown>`
+  - Use `const event = mux.webhooks.unwrap(...) as unknown as Record<string, unknown>;`
+
+- `It looks like you are using Node APIs from a file without the "use node" directive`
+  - Add `"use node";` at the top of files that use Mux SDK/Node APIs

package/_generated/api.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { AnyApi, AnyComponents } from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+export const api: AnyApi = anyApi;
+export const internal: AnyApi = anyApi;
+export const components: AnyComponents = componentsGeneric();

package/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* 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";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/_generated/server.ts

@@ -0,0 +1,156 @@
+/* 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";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/catalog.ts

@@ -0,0 +1,78 @@
+import { query } from "./_generated/server";
+import { v } from "convex/values";
+
+export const getAssetByMuxId = query({
+  args: { muxAssetId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("assets")
+      .withIndex("by_mux_asset_id", (q) => q.eq("muxAssetId", args.muxAssetId))
+      .unique();
+  },
+});
+
+export const getLiveStreamByMuxId = query({
+  args: { muxLiveStreamId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("liveStreams")
+      .withIndex("by_mux_live_stream_id", (q) =>
+        q.eq("muxLiveStreamId", args.muxLiveStreamId)
+      )
+      .unique();
+  },
+});
+
+export const getUploadByMuxId = query({
+  args: { muxUploadId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("uploads")
+      .withIndex("by_mux_upload_id", (q) => q.eq("muxUploadId", args.muxUploadId))
+      .unique();
+  },
+});
+
+export const listAssets = query({
+  args: { limit: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("assets")
+      .withIndex("by_updated_at")
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+export const listLiveStreams = query({
+  args: { limit: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("liveStreams")
+      .withIndex("by_updated_at")
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+export const listUploads = query({
+  args: { limit: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("uploads")
+      .withIndex("by_updated_at")
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+export const listRecentEvents = query({
+  args: { limit: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("events")
+      .withIndex("by_received_at")
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});

package/convex.config.ts

@@ -0,0 +1,5 @@
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("mux");
+
+export default component;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "convex-mux-component",
+  "version": "0.1.6",
+  "description": "Convex Component for syncing Mux video data and app metadata.",
+  "type": "module",
+  "keywords": [
+    "convex",
+    "mux",
+    "component",
+    "video"
+  ],
+  "files": [
+    "README.md",
+    "convex.config.ts",
+    "schema.ts",
+    "sync.ts",
+    "videos.ts",
+    "catalog.ts",
+    "_generated/api.ts",
+    "_generated/server.ts",
+    "_generated/dataModel.ts"
+  ],
+  "exports": {
+    "./convex.config": "./convex.config.ts",
+    "./convex.config.js": "./convex.config.ts",
+    "./schema": "./schema.ts",
+    "./schema.js": "./schema.ts",
+    "./sync": "./sync.ts",
+    "./sync.js": "./sync.ts",
+    "./videos": "./videos.ts",
+    "./videos.js": "./videos.ts",
+    "./catalog": "./catalog.ts",
+    "./catalog.js": "./catalog.ts",
+    "./_generated/api": "./_generated/api.ts",
+    "./_generated/api.js": "./_generated/api.ts",
+    "./_generated/server": "./_generated/server.ts",
+    "./_generated/server.js": "./_generated/server.ts",
+    "./_generated/dataModel": "./_generated/dataModel.ts",
+    "./_generated/dataModel.js": "./_generated/dataModel.ts"
+  },
+  "scripts": {
+    "codegen": "convex codegen --component-dir .",
+    "typecheck": "convex codegen --component-dir . && tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mux/mux-node": "^9.0.0",
+    "convex": "^1.20.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/schema.ts

@@ -0,0 +1,106 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+const playbackId = v.object({
+  id: v.string(),
+  policy: v.optional(v.string()),
+});
+
+const videoTrack = v.object({
+  id: v.optional(v.string()),
+  type: v.optional(v.string()),
+  textType: v.optional(v.string()),
+  languageCode: v.optional(v.string()),
+  status: v.optional(v.string()),
+  name: v.optional(v.string()),
+});
+
+const genericObject = v.record(v.string(), v.any());
+
+export default defineSchema({
+  assets: defineTable({
+    muxAssetId: v.string(),
+    status: v.optional(v.string()),
+    playbackIds: v.optional(v.array(playbackId)),
+    durationSeconds: v.optional(v.number()),
+    aspectRatio: v.optional(v.string()),
+    maxStoredResolution: v.optional(v.string()),
+    maxStoredFrameRate: v.optional(v.number()),
+    passthrough: v.optional(v.string()),
+    uploadId: v.optional(v.string()),
+    liveStreamId: v.optional(v.string()),
+    tracks: v.optional(v.array(videoTrack)),
+    createdAtMs: v.number(),
+    updatedAtMs: v.number(),
+    deletedAtMs: v.optional(v.number()),
+    raw: genericObject,
+  })
+    .index("by_mux_asset_id", ["muxAssetId"])
+    .index("by_status", ["status"])
+    .index("by_updated_at", ["updatedAtMs"]),
+
+  liveStreams: defineTable({
+    muxLiveStreamId: v.string(),
+    status: v.optional(v.string()),
+    playbackIds: v.optional(v.array(playbackId)),
+    reconnectWindowSeconds: v.optional(v.number()),
+    recentAssetIds: v.optional(v.array(v.string())),
+    createdAtMs: v.number(),
+    updatedAtMs: v.number(),
+    deletedAtMs: v.optional(v.number()),
+    raw: genericObject,
+  })
+    .index("by_mux_live_stream_id", ["muxLiveStreamId"])
+    .index("by_status", ["status"])
+    .index("by_updated_at", ["updatedAtMs"]),
+
+  uploads: defineTable({
+    muxUploadId: v.string(),
+    status: v.optional(v.string()),
+    uploadUrl: v.optional(v.string()),
+    timeoutSeconds: v.optional(v.number()),
+    corsOrigin: v.optional(v.string()),
+    assetId: v.optional(v.string()),
+    error: v.optional(genericObject),
+    createdAtMs: v.number(),
+    updatedAtMs: v.number(),
+    deletedAtMs: v.optional(v.number()),
+    raw: genericObject,
+  })
+    .index("by_mux_upload_id", ["muxUploadId"])
+    .index("by_status", ["status"])
+    .index("by_updated_at", ["updatedAtMs"]),
+
+  events: defineTable({
+    muxEventId: v.optional(v.string()),
+    type: v.string(),
+    objectType: v.optional(v.string()),
+    objectId: v.optional(v.string()),
+    occurredAtMs: v.optional(v.number()),
+    receivedAtMs: v.number(),
+    verified: v.boolean(),
+    raw: genericObject,
+  })
+    .index("by_mux_event_id", ["muxEventId"])
+    .index("by_type", ["type"])
+    .index("by_object", ["objectType", "objectId"])
+    .index("by_received_at", ["receivedAtMs"]),
+
+  videoMetadata: defineTable({
+    muxAssetId: v.string(),
+    userId: v.string(),
+    title: v.optional(v.string()),
+    description: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    visibility: v.optional(
+      v.union(v.literal("private"), v.literal("unlisted"), v.literal("public"))
+    ),
+    custom: v.optional(genericObject),
+    createdAtMs: v.number(),
+    updatedAtMs: v.number(),
+  })
+    .index("by_mux_asset_id", ["muxAssetId"])
+    .index("by_user_id", ["userId"])
+    .index("by_asset_and_user", ["muxAssetId", "userId"])
+    .index("by_updated_at", ["updatedAtMs"]),
+});

package/sync.ts

@@ -0,0 +1,430 @@
+import { internalMutation, mutation, type MutationCtx } from "./_generated/server";
+import { v } from "convex/values";
+
+function omitUndefined<T extends Record<string, unknown>>(doc: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(doc).filter(([, value]) => value !== undefined)
+  ) as Partial<T>;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function asTimestamp(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    if (!Number.isNaN(parsed)) {
+      return parsed;
+    }
+  }
+  return undefined;
+}
+
+function asPlaybackIds(value: unknown): Array<{ id: string; policy?: string }> | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const mapped = value
+    .map((entry) => {
+      const id = asString((entry as { id?: unknown }).id);
+      if (!id) return null;
+      const policy = asString((entry as { policy?: unknown }).policy);
+      return policy ? { id, policy } : { id };
+    })
+    .filter((entry): entry is { id: string; policy?: string } => entry !== null);
+  return mapped.length > 0 ? mapped : undefined;
+}
+
+function asTracks(
+  value: unknown
+):
+  | Array<{
+      id?: string;
+      type?: string;
+      textType?: string;
+      languageCode?: string;
+      status?: string;
+      name?: string;
+    }>
+  | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const tracks = value.map((entry) => {
+    const track = entry as {
+      id?: unknown;
+      type?: unknown;
+      text_type?: unknown;
+      language_code?: unknown;
+      status?: unknown;
+      name?: unknown;
+    };
+    return {
+      id: asString(track.id),
+      type: asString(track.type),
+      textType: asString(track.text_type),
+      languageCode: asString(track.language_code),
+      status: asString(track.status),
+      name: asString(track.name),
+    };
+  });
+  return tracks.length > 0 ? tracks : undefined;
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const items = value.filter((item): item is string => typeof item === "string");
+  return items.length > 0 ? items : undefined;
+}
+
+const upsertAssetFromPayloadHandler = async (
+  ctx: MutationCtx,
+  args: { asset: Record<string, unknown> }
+) => {
+  const now = Date.now();
+  const asset = args.asset as {
+    id?: unknown;
+    status?: unknown;
+    playback_ids?: unknown;
+    duration?: unknown;
+    aspect_ratio?: unknown;
+    max_stored_resolution?: unknown;
+    max_stored_frame_rate?: unknown;
+    passthrough?: unknown;
+    upload_id?: unknown;
+    live_stream_id?: unknown;
+    tracks?: unknown;
+  };
+  const muxAssetId = asString(asset.id);
+  if (!muxAssetId) {
+    throw new Error("Mux asset payload is missing an id.");
+  }
+
+  const existing = await ctx.db
+    .query("assets")
+    .withIndex("by_mux_asset_id", (q) => q.eq("muxAssetId", muxAssetId))
+    .unique();
+
+  const patchDoc = omitUndefined({
+    status: asString(asset.status),
+    playbackIds: asPlaybackIds(asset.playback_ids),
+    durationSeconds: asNumber(asset.duration),
+    aspectRatio: asString(asset.aspect_ratio),
+    maxStoredResolution: asString(asset.max_stored_resolution),
+    maxStoredFrameRate: asNumber(asset.max_stored_frame_rate),
+    passthrough: asString(asset.passthrough),
+    uploadId: asString(asset.upload_id),
+    liveStreamId: asString(asset.live_stream_id),
+    tracks: asTracks(asset.tracks),
+    updatedAtMs: now,
+    deletedAtMs: asString(asset.status) === "deleted" ? now : undefined,
+    raw: args.asset,
+  });
+
+  if (existing) {
+    await ctx.db.patch(existing._id, patchDoc);
+    return existing._id;
+  }
+
+  return await ctx.db.insert("assets", {
+    muxAssetId,
+    createdAtMs: now,
+    ...patchDoc,
+    updatedAtMs: now,
+    raw: args.asset,
+  });
+};
+
+export const upsertAssetFromPayload = internalMutation({
+  args: { asset: v.record(v.string(), v.any()) },
+  handler: upsertAssetFromPayloadHandler,
+});
+
+export const upsertAssetFromPayloadPublic = mutation({
+  args: { asset: v.record(v.string(), v.any()) },
+  handler: upsertAssetFromPayloadHandler,
+});
+
+const markAssetDeletedHandler = async (
+  ctx: MutationCtx,
+  args: { muxAssetId: string }
+) => {
+  const existing = await ctx.db
+    .query("assets")
+    .withIndex("by_mux_asset_id", (q) => q.eq("muxAssetId", args.muxAssetId))
+    .unique();
+  if (!existing) return null;
+  await ctx.db.patch(existing._id, {
+    status: "deleted",
+    deletedAtMs: Date.now(),
+    updatedAtMs: Date.now(),
+  });
+  return existing._id;
+};
+
+export const markAssetDeleted = internalMutation({
+  args: { muxAssetId: v.string() },
+  handler: markAssetDeletedHandler,
+});
+
+export const markAssetDeletedPublic = mutation({
+  args: { muxAssetId: v.string() },
+  handler: markAssetDeletedHandler,
+});
+
+const upsertLiveStreamFromPayloadHandler = async (
+  ctx: MutationCtx,
+  args: { liveStream: Record<string, unknown> }
+) => {
+  const now = Date.now();
+  const liveStream = args.liveStream as {
+    id?: unknown;
+    status?: unknown;
+    playback_ids?: unknown;
+    reconnect_window?: unknown;
+    recent_asset_ids?: unknown;
+  };
+  const muxLiveStreamId = asString(liveStream.id);
+  if (!muxLiveStreamId) {
+    throw new Error("Mux live stream payload is missing an id.");
+  }
+
+  const existing = await ctx.db
+    .query("liveStreams")
+    .withIndex("by_mux_live_stream_id", (q) =>
+      q.eq("muxLiveStreamId", muxLiveStreamId)
+    )
+    .unique();
+
+  const patchDoc = omitUndefined({
+    status: asString(liveStream.status),
+    playbackIds: asPlaybackIds(liveStream.playback_ids),
+    reconnectWindowSeconds: asNumber(liveStream.reconnect_window),
+    recentAssetIds: asStringArray(liveStream.recent_asset_ids),
+    updatedAtMs: now,
+    raw: args.liveStream,
+  });
+
+  if (existing) {
+    await ctx.db.patch(existing._id, patchDoc);
+    return existing._id;
+  }
+
+  return await ctx.db.insert("liveStreams", {
+    muxLiveStreamId,
+    createdAtMs: now,
+    ...patchDoc,
+    updatedAtMs: now,
+    raw: args.liveStream,
+  });
+};
+
+export const upsertLiveStreamFromPayload = internalMutation({
+  args: { liveStream: v.record(v.string(), v.any()) },
+  handler: upsertLiveStreamFromPayloadHandler,
+});
+
+export const upsertLiveStreamFromPayloadPublic = mutation({
+  args: { liveStream: v.record(v.string(), v.any()) },
+  handler: upsertLiveStreamFromPayloadHandler,
+});
+
+const markLiveStreamDeletedHandler = async (
+  ctx: MutationCtx,
+  args: { muxLiveStreamId: string }
+) => {
+  const existing = await ctx.db
+    .query("liveStreams")
+    .withIndex("by_mux_live_stream_id", (q) =>
+      q.eq("muxLiveStreamId", args.muxLiveStreamId)
+    )
+    .unique();
+  if (!existing) return null;
+  await ctx.db.patch(existing._id, {
+    status: "deleted",
+    deletedAtMs: Date.now(),
+    updatedAtMs: Date.now(),
+  });
+  return existing._id;
+};
+
+export const markLiveStreamDeleted = internalMutation({
+  args: { muxLiveStreamId: v.string() },
+  handler: markLiveStreamDeletedHandler,
+});
+
+export const markLiveStreamDeletedPublic = mutation({
+  args: { muxLiveStreamId: v.string() },
+  handler: markLiveStreamDeletedHandler,
+});
+
+const upsertUploadFromPayloadHandler = async (
+  ctx: MutationCtx,
+  args: { upload: Record<string, unknown> }
+) => {
+  const now = Date.now();
+  const upload = args.upload as {
+    id?: unknown;
+    status?: unknown;
+    url?: unknown;
+    timeout?: unknown;
+    cors_origin?: unknown;
+    asset_id?: unknown;
+    error?: unknown;
+  };
+  const muxUploadId = asString(upload.id);
+  if (!muxUploadId) {
+    throw new Error("Mux upload payload is missing an id.");
+  }
+
+  const existing = await ctx.db
+    .query("uploads")
+    .withIndex("by_mux_upload_id", (q) => q.eq("muxUploadId", muxUploadId))
+    .unique();
+
+  const patchDoc = omitUndefined({
+    status: asString(upload.status),
+    uploadUrl: asString(upload.url),
+    timeoutSeconds: asNumber(upload.timeout),
+    corsOrigin: asString(upload.cors_origin),
+    assetId: asString(upload.asset_id),
+    error: asObject(upload.error),
+    updatedAtMs: now,
+    raw: args.upload,
+  });
+
+  if (existing) {
+    await ctx.db.patch(existing._id, patchDoc);
+    return existing._id;
+  }
+
+  return await ctx.db.insert("uploads", {
+    muxUploadId,
+    createdAtMs: now,
+    ...patchDoc,
+    updatedAtMs: now,
+    raw: args.upload,
+  });
+};
+
+export const upsertUploadFromPayload = internalMutation({
+  args: { upload: v.record(v.string(), v.any()) },
+  handler: upsertUploadFromPayloadHandler,
+});
+
+export const upsertUploadFromPayloadPublic = mutation({
+  args: { upload: v.record(v.string(), v.any()) },
+  handler: upsertUploadFromPayloadHandler,
+});
+
+const markUploadDeletedHandler = async (
+  ctx: MutationCtx,
+  args: { muxUploadId: string }
+) => {
+  const existing = await ctx.db
+    .query("uploads")
+    .withIndex("by_mux_upload_id", (q) => q.eq("muxUploadId", args.muxUploadId))
+    .unique();
+  if (!existing) return null;
+  await ctx.db.patch(existing._id, {
+    status: "deleted",
+    deletedAtMs: Date.now(),
+    updatedAtMs: Date.now(),
+  });
+  return existing._id;
+};
+
+export const markUploadDeleted = internalMutation({
+  args: { muxUploadId: v.string() },
+  handler: markUploadDeletedHandler,
+});
+
+export const markUploadDeletedPublic = mutation({
+  args: { muxUploadId: v.string() },
+  handler: markUploadDeletedHandler,
+});
+
+function inferObjectTypeFromEventType(eventType: string): string | undefined {
+  if (eventType.startsWith("video.asset.")) return "asset";
+  if (eventType.startsWith("video.live_stream.")) return "live_stream";
+  if (eventType.startsWith("video.upload.")) return "upload";
+  return undefined;
+}
+
+const recordWebhookEventHandler = async (
+  ctx: MutationCtx,
+  args: {
+    event: Record<string, unknown>;
+    verified: boolean;
+  }
+) => {
+  const now = Date.now();
+  const event = args.event as {
+    id?: unknown;
+    type?: unknown;
+    data?: { id?: unknown };
+    created_at?: unknown;
+  };
+
+  const eventType = asString(event.type) ?? "unknown";
+  const muxEventId = asString(event.id);
+  const objectId = asString(event.data?.id);
+  const objectType = inferObjectTypeFromEventType(eventType);
+  const occurredAtMs = asTimestamp(event.created_at);
+
+  if (muxEventId) {
+    const existing = await ctx.db
+      .query("events")
+      .withIndex("by_mux_event_id", (q) => q.eq("muxEventId", muxEventId))
+      .unique();
+    if (existing) {
+      return { eventDocId: existing._id, alreadyProcessed: true };
+    }
+  }
+
+  const eventDocId = await ctx.db.insert("events", {
+    type: eventType,
+    receivedAtMs: now,
+    verified: args.verified,
+    raw: args.event,
+    ...(muxEventId ? { muxEventId } : {}),
+    ...(objectType ? { objectType } : {}),
+    ...(objectId ? { objectId } : {}),
+    ...(occurredAtMs !== undefined ? { occurredAtMs } : {}),
+  });
+
+  return { eventDocId, alreadyProcessed: false };
+};
+
+export const recordWebhookEvent = internalMutation({
+  args: {
+    event: v.record(v.string(), v.any()),
+    verified: v.boolean(),
+  },
+  handler: recordWebhookEventHandler,
+});
+
+export const recordWebhookEventPublic = mutation({
+  args: {
+    event: v.record(v.string(), v.any()),
+    verified: v.boolean(),
+  },
+  handler: recordWebhookEventHandler,
+});

package/videos.ts

@@ -0,0 +1,111 @@
+import { mutation, query } from "./_generated/server";
+import { v } from "convex/values";
+
+function omitUndefined<T extends Record<string, unknown>>(doc: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(doc).filter(([, value]) => value !== undefined)
+  ) as Partial<T>;
+}
+
+export const upsertVideoMetadata = mutation({
+  args: {
+    muxAssetId: v.string(),
+    userId: v.string(),
+    title: v.optional(v.string()),
+    description: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    visibility: v.optional(
+      v.union(v.literal("private"), v.literal("unlisted"), v.literal("public"))
+    ),
+    custom: v.optional(v.record(v.string(), v.any())),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const existing = await ctx.db
+      .query("videoMetadata")
+      .withIndex("by_asset_and_user", (q) =>
+        q.eq("muxAssetId", args.muxAssetId).eq("userId", args.userId)
+      )
+      .unique();
+
+    const patchDoc = omitUndefined({
+      title: args.title,
+      description: args.description,
+      tags: args.tags,
+      visibility: args.visibility,
+      custom: args.custom,
+      updatedAtMs: now,
+    });
+
+    if (existing) {
+      await ctx.db.patch(existing._id, patchDoc);
+      return existing._id;
+    }
+
+    return await ctx.db.insert("videoMetadata", {
+      muxAssetId: args.muxAssetId,
+      userId: args.userId,
+      createdAtMs: now,
+      ...patchDoc,
+      updatedAtMs: now,
+    });
+  },
+});
+
+export const getVideoByMuxAssetId = query({
+  args: {
+    muxAssetId: v.string(),
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const asset = await ctx.db
+      .query("assets")
+      .withIndex("by_mux_asset_id", (q) => q.eq("muxAssetId", args.muxAssetId))
+      .unique();
+
+    if (!asset) return null;
+
+    if (args.userId) {
+      const userId = args.userId;
+      const metadata = await ctx.db
+        .query("videoMetadata")
+        .withIndex("by_asset_and_user", (q) =>
+          q.eq("muxAssetId", args.muxAssetId).eq("userId", userId)
+        )
+        .unique();
+      return { asset, metadata };
+    }
+
+    const metadata = await ctx.db
+      .query("videoMetadata")
+      .withIndex("by_mux_asset_id", (q) => q.eq("muxAssetId", args.muxAssetId))
+      .collect();
+    return { asset, metadata };
+  },
+});
+
+export const listVideosForUser = query({
+  args: {
+    userId: v.string(),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const metadataRows = await ctx.db
+      .query("videoMetadata")
+      .withIndex("by_user_id", (q) => q.eq("userId", args.userId))
+      .order("desc")
+      .take(args.limit ?? 25);
+
+    const joinedRows = await Promise.all(
+      metadataRows.map(async (metadata) => {
+        const asset = await ctx.db
+          .query("assets")
+          .withIndex("by_mux_asset_id", (q) => q.eq("muxAssetId", metadata.muxAssetId))
+          .unique();
+        return { metadata, asset };
+      })
+    );
+
+    return joinedRows;
+  },
+});