Context

Documentation from context-dot-dev/convex-component, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.

Context.dev Convex Component

Use the Context.dev API from Convex actions through an isolated Convex component.

This package is generated against openapispec.json and exposes thin wrappers for the Context.dev REST API. It does not persist data in Convex; Context.dev caching behavior is controlled through the API parameters such as maxAgeMs.

Install

Copy codenpm install @context-dot-dev/convex

Add the component to your Convex app:

Copy codeimport contextDev from "@context-dot-dev/convex/convex.config";
import { defineApp } from "convex/server";
import { v } from "convex/values";

const app = defineApp({
  env: {
    CONTEXT_DEV_API_KEY: v.string(),
  },
});

app.use(contextDev, {
  env: {
    CONTEXT_DEV_API_KEY: app.env.CONTEXT_DEV_API_KEY,
  },
});

export default app;

Set CONTEXT_DEV_API_KEY on the Convex deployment, then run:

Copy codenpx convex dev

Usage

You can call the component API directly from Convex actions:

Copy codeimport { v } from "convex/values";

import { components } from "./_generated/api.js";
import { action } from "./_generated/server.js";

export const brand = action({
  args: { domain: v.string() },
  handler: async (ctx, args) => {
    return await ctx.runAction(components.contextDev.brand.retrieve, {
      params: { domain: args.domain },
    });
  },
});

Or use the typed helper client:

Copy codeimport { ContextDev } from "@context-dot-dev/convex";
import { v } from "convex/values";

import { components } from "./_generated/api.js";
import { action } from "./_generated/server.js";

const contextDev = new ContextDev(components.contextDev);

export const scrape = action({
  args: { url: v.string() },
  handler: async (ctx, args) => {
    return await contextDev.scrapeMarkdown(ctx, {
      params: { url: args.url },
    });
  },
});

API Shape

GET endpoints take params; POST endpoints take body and may also take params if the OpenAPI operation defines query parameters.

The helper client types params, body, and returned data from openapispec.json:

• contextDev.retrieveBrand(ctx, { params: { domain } })
• contextDev.retrieveBrandByName(ctx, { params: { company_name } })
• contextDev.retrieveBrandByEmail(ctx, { params: { email } })
• contextDev.identifyBrandFromTransaction(ctx, { params: { transaction_info } })
• contextDev.scrapeMarkdown(ctx, { params: { url } })
• contextDev.crawl(ctx, { body: { url, maxPages } })
• contextDev.extract(ctx, { body: { url, schema } })
• contextDev.search(ctx, { body: { query } })
• contextDev.aiQuery(ctx, { body: { domain, data_to_extract } })
• contextDev.extractProducts(ctx, { body: { domain } })
• contextDev.retrieveNaics(ctx, { params: { input } })

The component actions also validate their runtime argument shapes with Convex validators. For example, components.contextDev.web.scrapeMarkdown requires params.url, while components.contextDev.web.search requires body.query. API responses are validated as JSON objects before they are returned to your Convex function.

Raw component action groups are available under:

• components.contextDev.brand
• components.contextDev.web
• components.contextDev.ai
• components.contextDev.industry
• components.contextDev.people

Testing

The package includes a convex-test registration helper so app tests can mount the component without duplicating component internals:

Copy codeimport { convexTest } from "convex-test";
import { describe, expect, it } from "vitest";

import schema from "./schema.js";
import { api } from "./_generated/api.js";
import contextDevTest from "@context-dot-dev/convex/test";

describe("Context.dev usage", () => {
  it("registers the Context.dev component", async () => {
    const t = convexTest(schema);
    contextDevTest.register(t);

    // Call your app functions that use components.contextDev here.
    // await t.action(api.myModule.myAction, { domain: "context.dev" });
  });
});

The test entrypoint also exports schema and modules for tests that need to customize component registration.

Development

Copy codenpm install
npm run build
npm run typecheck

npm run build regenerates TypeScript types from openapispec.json and compiles the package.

After configuring a real Convex deployment, run npm run codegen to refresh the component generated files from Convex itself.