convex 1.47.0 → 1.48.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/get-convex/convex-backend.git",
+    "url": "git+https://github.com/convex/convex-backend.git",
     "directory": "npm-packages/convex"
   },
   "main": "./dist/cjs/index.js",
@@ -227,6 +227,7 @@
     "@types/semver": "^7.3.13",
     "@types/serve-handler": "~6.1.4",
     "@types/ws": "^8.5.13",
+    "@vercel/detect-agent": "^1.2.5",
     "@vitest/eslint-plugin": "~1.6.0",
     "adm-zip": "^0.6.1",
     "bufferutil": "^4.0.7",

package/schemas/convex.schema.json

@@ -123,8 +123,7 @@
         },
         "nodeVersion": {
           "type": "string",
-          "description": "The Node.js version to use for Node.js actions. The currently supported values are '20', '22', and '24'.\n\nDocumentation: https://docs.convex.dev/config/convex.json#configuring-the-nodejs-version",
-          "default": "20"
+          "description": "The Node.js version to use for Node.js actions. The currently supported values are '22' and '24'.\n\nAfter you push a new Node.js version, your functions may keep running on the previous version for a few minutes.\n\nDocumentation: https://docs.convex.dev/config/convex.json#configuring-the-nodejs-version"
         }
       }
     },

package/src/cli/aiFiles.ts

@@ -34,9 +34,22 @@ const aiInstall = new Command("install")
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir, convexDir, aiFilesConfig } =
+    const { ctx, projectDir, convexDir, aiFilesConfig } =
       await resolveProjectPaths();
-    await installAiFiles({ projectDir, convexDir, aiFilesConfig });
+
+    const result = await installAiFiles({
+      projectDir,
+      convexDir,
+      aiFilesConfig,
+    });
+
+    if (result.kind === "error") {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: result.message,
+      });
+    }
 
     logMessage(`${chalkStderr.green("✔")} Convex AI files installed.`);
   });
@@ -72,9 +85,22 @@ const aiUpdate = new Command("update")
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir, convexDir, aiFilesConfig } =
+    const { ctx, projectDir, convexDir, aiFilesConfig } =
       await resolveProjectPaths();
-    await installAiFiles({ projectDir, convexDir, aiFilesConfig });
+
+    const result = await installAiFiles({
+      projectDir,
+      convexDir,
+      aiFilesConfig,
+    });
+
+    if (result.kind === "error") {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: result.message,
+      });
+    }
 
     logMessage(`${chalkStderr.green("✔")} Convex AI files updated.`);
   });

package/src/cli/env.ts

@@ -171,6 +171,8 @@ const envListCmd = new Command("list")
       "• List all variables and their values: `npx convex env list --include-values`",
       "• Save all variables to a file: `npx convex env list --include-values > .env.convex`",
       "• Append to a file: `npx convex env list --include-values >> .env.convex`",
+      "",
+      "When an AI agent runs this command (detected from environment variables like AI_AGENT or CLAUDECODE), only names are listed unless --include-values is passed.",
     ].join("\n"),
   )
   .option(
@@ -180,7 +182,7 @@ const envListCmd = new Command("list")
   .addOption(
     new Option(
       "--include-values",
-      "Print each variable's value alongside its name, in .env format (the default). Pass it explicitly in scripts that rely on the values.",
+      "Print each variable's value alongside its name, in .env format. This is the default unless an AI agent is detected, so pass it explicitly in scripts that rely on the values.",
     ).conflicts("namesOnly"),
   )
   .configureHelp({ showGlobalOptions: true })
@@ -198,6 +200,7 @@ const envListCmd = new Command("list")
         const backend = deploymentEnvBackend(ctx, deployment);
         await envList(ctx, backend, {
           namesOnly: cmdOptions.namesOnly ?? false,
+          includeValues: cmdOptions.includeValues ?? false,
         });
       },
     });

package/src/cli/envDefault.ts

@@ -147,6 +147,8 @@ const envDefaultList = addEnvDefaultOptions(
         "• List only default variable names (no values): `npx convex env default list --names-only`",
         "• List all default variables and their values: `npx convex env default list --include-values`",
         "",
+        "When an AI agent runs this command (detected from environment variables like AI_AGENT or CLAUDECODE), only names are listed unless --include-values is passed.",
+        "",
         "The deployment type is determined by the current deployment (local maps to dev), or by --type if provided.",
       ].join("\n"),
     )
@@ -157,7 +159,7 @@ const envDefaultList = addEnvDefaultOptions(
     .addOption(
       new Option(
         "--include-values",
-        "Print each variable's value alongside its name, in .env format (the default). Pass it explicitly in scripts that rely on the values.",
+        "Print each variable's value alongside its name, in .env format. This is the default unless an AI agent is detected, so pass it explicitly in scripts that rely on the values.",
       ).conflicts("namesOnly"),
     )
     .configureHelp({ showGlobalOptions: true })
@@ -169,6 +171,7 @@ const envDefaultList = addEnvDefaultOptions(
   await ensureHasConvexDependency(ctx, "env default list");
   await envList(ctx, backend, {
     namesOnly: cmdOptions.namesOnly ?? false,
+    includeValues: cmdOptions.includeValues ?? false,
   });
 });
 

package/src/cli/lib/aiFiles/guidelinesmd.ts

@@ -21,6 +21,8 @@ export async function hasGuidelinesInstalled(
  * Download and write the guidelines file.
  * Guidelines live in `_generated/` so local edits are not expected and are
  * not preserved.
+ *
+ * Returns false if the guidelines could not be downloaded.
  */
 export async function installGuidelinesFile({
   convexDir,
@@ -28,15 +30,16 @@ export async function installGuidelinesFile({
 }: {
   convexDir: string;
   state: AiFilesState;
-}): Promise<void> {
+}): Promise<boolean> {
   const guidelines = await downloadGuidelines();
+
   if (guidelines === null) {
     logMessage(
       chalkStderr.yellow(
         "Could not download Convex AI guidelines right now. You can retry with: npx convex ai-files install",
       ),
     );
-    return;
+    return false;
   }
 
   await fs.mkdir(aiDirForConvexDir(convexDir), { recursive: true });
@@ -46,4 +49,6 @@ export async function installGuidelinesFile({
   logMessage(
     `${chalkStderr.green("✔")} ${guidelinesPathForConvexDir(convexDir)} written`,
   );
+
+  return true;
 }

package/src/cli/lib/aiFiles/index.ts

@@ -44,11 +44,18 @@ async function hasExistingAiFilesArtifacts({
   );
 }
 
+type InstallAiFilesResult =
+  | { kind: "success" }
+  | { kind: "error"; message: string };
+
 /**
  * Install or refresh all Convex AI files.
  *
  * Reads the existing state if present, or starts from a blank one for a
  * fresh install.
+ *
+ * Writes everything it can even when the guidelines download or the skills
+ * install fails, and returns an error if either of them failed.
  */
 export async function installAiFiles({
   projectDir,
@@ -56,16 +63,29 @@ export async function installAiFiles({
   aiFilesConfig,
 }: AiFilesPaths & {
   aiFilesConfig?: AiFilesProjectConfig | undefined;
-}): Promise<void> {
+}): Promise<InstallAiFilesResult> {
   const convexDirName = path.relative(projectDir, convexDir);
   const state = await readAiStateOrDefault(convexDir);
 
-  await installGuidelinesFile({ convexDir, state });
+  const guidelinesInstalled = await installGuidelinesFile({ convexDir, state });
   await applyAgentsMdSection({ projectDir, state, convexDirName });
   await applyClaudeMdSection({ projectDir, state, convexDirName });
-  await installSkills({ projectDir, state, aiFilesConfig });
+  const skillsInstalled = await installSkills({
+    projectDir,
+    state,
+    aiFilesConfig,
+  });
   await removeLegacyCursorRules(projectDir);
   await writeAiState({ state, convexDir });
+
+  if (!guidelinesInstalled || !skillsInstalled) {
+    return {
+      kind: "error",
+      message:
+        "Some Convex AI files could not be installed. See the messages above.",
+    };
+  }
+  return { kind: "success" };
 }
 
 async function attemptToInstallAiFiles(

package/src/cli/lib/aiFiles/skills.ts

@@ -23,11 +23,11 @@ function configuredSkillAgents(
 }
 
 /**
- * Runs `npx skills add get-convex/agent-skills --yes --copy` in the given directory.
+ * Runs `npx skills add convex/agent-skills --yes --copy` in the given directory.
  * Returns true on success, false if the process fails or cannot be started.
  */
 function runSkillsAdd(cwd: string, agents: string[]): Promise<boolean> {
-  const args = ["add", "get-convex/agent-skills", "--yes", "--copy"];
+  const args = ["add", "convex/agent-skills", "--yes", "--copy"];
   for (const agent of agents) {
     args.push("--agent", agent);
   }
@@ -116,6 +116,9 @@ async function removeSkillsLockIfEmpty({
 /**
  * Install Convex agent skills and record the SHA into the state.
  * Handles the kill-switch check and all logging internally.
+ *
+ * Returns false if the skills CLI failed. Skipping skills because no agents
+ * are configured or the kill switch is on counts as success.
  */
 export async function installSkills({
   projectDir,
@@ -125,26 +128,27 @@ export async function installSkills({
   projectDir: string;
   state: AiFilesState;
   aiFilesConfig?: AiFilesProjectConfig | undefined;
-}): Promise<void> {
+}): Promise<boolean> {
   const agents = configuredSkillAgents(aiFilesConfig);
-  if (agents.length === 0) return;
-  if (!(await shouldRunSkillsCli())) return;
+  if (agents.length === 0) return true;
+  if (!(await shouldRunSkillsCli())) return true;
 
   logMessage("Installing Convex agent skills...");
   const skillsOk = await runSkillsAdd(projectDir, agents);
   if (!skillsOk) {
     logMessage(
       chalkStderr.yellow(
-        "Could not install agent skills. You can retry manually with: npx skills add get-convex/agent-skills --copy",
+        "Could not install agent skills. You can retry manually with: npx skills add convex/agent-skills --copy",
       ),
     );
-    return;
+    return false;
   }
 
   const sha = await fetchAgentSkillsSha();
   if (sha) state.agentSkillsSha = sha;
 
   logMessage(`${chalkStderr.green("✔")} Skills installed`);
+  return true;
 }
 
 export type RemoveInstalledSkillsStatus = "unchanged" | "removed" | "failed";

package/src/cli/lib/aiFiles/state.ts

@@ -11,7 +11,7 @@ export const aiFilesStateSchema = z.object({
   guidelinesHash: z.string().nullable(),
   agentsMdSectionHash: z.string().nullable(),
   claudeMdHash: z.string().nullable(),
-  // Commit SHA from get-convex/agent-skills that was current when skills were
+  // Commit SHA from convex/agent-skills that was current when skills were
   // last installed. Used to detect when newer skills are available.
   agentSkillsSha: z.string().nullable(),
 });

package/src/cli/lib/components.ts

@@ -43,7 +43,12 @@ import { typeCheckFunctionsInMode, TypeCheckMode } from "./typecheck.js";
 import { withTmpDir } from "../../bundler/fs.js";
 import { handleDebugBundlePath } from "./debugBundlePath.js";
 import { chalkStderr } from "chalk";
-import { StartPushRequest, StartPushResponse } from "./deployApi/startPush.js";
+import {
+  startPushResponseForLogging,
+  redactEnvironmentVariableValues,
+  StartPushRequest,
+  StartPushResponse,
+} from "./deployApi/startPush.js";
 import { DetailedDeploymentCredentials } from "./api.js";
 import { FinishPushDiff } from "./deployApi/finishPush.js";
 import { Reporter, Span } from "./tracing.js";
@@ -548,7 +553,10 @@ async function startComponentsPushAndCodegen(
   );
 
   if (options.verbose) {
-    logMessage("startPush: " + JSON.stringify(startPushResponse, null, 2));
+    logMessage(
+      "startPush: " +
+        JSON.stringify(startPushResponseForLogging(startPushResponse), null, 2),
+    );
   }
 
   if (options.codegen) {
@@ -734,7 +742,14 @@ function printDiff(
   opts: { verbose: boolean; dryRun: boolean; deploymentName: string | null },
 ) {
   if (opts.verbose) {
-    const diffString = JSON.stringify(finishPushResponse, null, 2);
+    const diffString = JSON.stringify(
+      redactEnvironmentVariableValues(
+        finishPushResponse,
+        startPushResponse.environmentVariables,
+      ),
+      null,
+      2,
+    );
     logMessage(diffString);
     return;
   }

package/src/cli/lib/deployApi/startPush.ts

@@ -48,6 +48,70 @@ export const startPushResponse = looseObject({
 });
 export type StartPushResponse = z.infer<typeof startPushResponse>;
 
+// Values this short are rarely secrets, and replacing them everywhere would
+// garble unrelated strings in the output.
+const MIN_SCRUBBED_VALUE_LENGTH = 8;
+
+/**
+ * Replaces every occurrence of an environment variable's value in `node`'s
+ * strings with `<redacted>`. Values reappear in push responses wherever the
+ * code read them, such as auth providers built from `process.env` in
+ * `auth.config.ts`.
+ */
+export function redactEnvironmentVariableValues<T>(
+  node: T,
+  environmentVariables: Record<string, string>,
+): T {
+  const values = Object.values(environmentVariables)
+    .filter((value) => value.length >= MIN_SCRUBBED_VALUE_LENGTH)
+    // Strings that hold JSON, like `authDiff` entries, contain the escaped form.
+    .flatMap((value) => {
+      const escaped = JSON.stringify(value).slice(1, -1);
+      return escaped === value ? [value] : [value, escaped];
+    })
+    .sort((a, b) => b.length - a.length);
+  const scrub = (child: unknown): unknown => {
+    if (typeof child === "string") {
+      return values.reduce(
+        (scrubbed, value) => scrubbed.split(value).join("<redacted>"),
+        child,
+      );
+    }
+    if (Array.isArray(child)) {
+      return child.map(scrub);
+    }
+    if (child !== null && typeof child === "object") {
+      return Object.fromEntries(
+        Object.entries(child).map(([key, grandchild]) => [
+          key,
+          scrub(grandchild),
+        ]),
+      );
+    }
+    return child;
+  };
+  return scrub(node) as T;
+}
+
+/**
+ * A copy of the response that is safe to print. `environmentVariables` holds
+ * every value on the deployment so `finish_push` can detect concurrent changes,
+ * and those values are often secrets.
+ */
+export function startPushResponseForLogging(
+  response: StartPushResponse,
+): StartPushResponse {
+  return {
+    ...redactEnvironmentVariableValues(response, response.environmentVariables),
+    environmentVariables: Object.fromEntries(
+      Object.keys(response.environmentVariables).map((name) => [
+        name,
+        "<redacted>",
+      ]),
+    ),
+  };
+}
+
 export const evaluatePushResponse = looseObject({
   schemaChange,
 });

package/src/cli/lib/env.ts

@@ -11,6 +11,7 @@ import { runSystemQuery } from "./run.js";
 import { deploymentFetch, logAndHandleFetchError } from "./utils/utils.js";
 import { readFromStdin } from "./utils/stdin.js";
 import { promptSecret } from "./utils/prompts.js";
+import { detectAiAgent } from "./utils/aiAgent.js";
 import {
   EXPECTED_CONVEX_URL_NAMES,
   EXPECTED_SITE_URL_NAMES,
@@ -174,15 +175,20 @@ export async function envRemove(
 export async function envList(
   ctx: Context,
   backend: EnvVarBackend,
-  options?: { namesOnly?: boolean },
+  options?: { namesOnly?: boolean; includeValues?: boolean },
 ) {
   const envs = await backend.list();
   if (envs.length === 0) {
     logMessage(`No environment variables set${backend.notice}`);
     return;
   }
+  // Agents tend to run `env list` to check what is set, which copies every
+  // secret into their context. They get names unless they ask for values.
+  const agent =
+    options?.namesOnly || options?.includeValues ? null : await detectAiAgent();
+  const namesOnly = options?.namesOnly || agent !== null;
   for (const { name, value } of envs) {
-    if (options?.namesOnly) {
+    if (namesOnly) {
       logOutput(name);
       continue;
     }
@@ -192,6 +198,11 @@ export async function envList(
     }
     logOutput(`${name}=${formatted}`);
   }
+  if (agent !== null) {
+    logMessage(
+      `Listed names only because an AI agent (${agent}) appears to be running this command. Pass --include-values to print the values too.`,
+    );
+  }
 }
 
 async function getFileContents(

package/src/cli/lib/localDeployment/dashboard.ts

@@ -57,6 +57,12 @@ export async function handleDashboard(
     ctx,
     dashboardPort,
     async (request, response) => {
+      if (!isLoopbackHost(request.headers.host, dashboardPort)) {
+        response.statusCode = 403;
+        response.end();
+        return;
+      }
+
       const pathname = new URL(
         request.url ?? "/",
         // We only want to extract the pathname so the base doesn’t matter
@@ -96,6 +102,19 @@ export async function handleDashboard(
   };
 }
 
+/**
+ * The dashboard is only meant to be opened at the URL the CLI prints, so
+ * requests addressed to any other hostname are not served, even if that
+ * hostname resolves to 127.0.0.1.
+ */
+export function isLoopbackHost(host: string | undefined, port: number) {
+  const normalizedHost = host?.toLowerCase();
+  return (
+    normalizedHost === `127.0.0.1:${port}` ||
+    normalizedHost === `localhost:${port}`
+  );
+}
+
 async function reportSelfHostedEvent(
   ctx: Context,
   {

package/src/cli/lib/localDeployment/download.ts

@@ -27,6 +27,7 @@ import { recursivelyDelete, recursivelyCopy } from "../fsUtils.js";
 import { LocalDeploymentError } from "./errors.js";
 import type { ProgressBarInstance } from "../../../vendor/progress/index.js";
 import path from "path";
+import { isValidBackendVersion } from "./utils.js";
 
 async function makeExecutable(p: string) {
   switch (process.platform) {
@@ -67,6 +68,7 @@ async function _ensureBackendBinaryDownloaded(
   ctx: Context,
   version: string,
 ): Promise<{ binaryPath: string; version: string }> {
+  await assertValidBackendVersion(ctx, version);
   logVerbose(`Ensuring backend binary downloaded for version ${version}`);
   const existingDownload = await checkForExistingDownload(ctx, version);
   if (existingDownload !== null) {
@@ -80,6 +82,19 @@ async function _ensureBackendBinaryDownloaded(
   return { version, binaryPath };
 }
 
+async function assertValidBackendVersion(ctx: Context, version: string) {
+  if (!isValidBackendVersion(version)) {
+    return await ctx.crash({
+      exitCode: 1,
+      errorType: "fatal",
+      printedMessage: "Invalid local backend version",
+      errForSentry: new LocalDeploymentError(
+        `Invalid local backend version: ${JSON.stringify(version)}`,
+      ),
+    });
+  }
+}
+
 let cachedLatestVersion: string | null = null;
 
 /**
@@ -259,7 +274,7 @@ function getDownloadPath() {
 }
 
 function getGithubDownloadUrl(version: string, filename: string) {
-  return `https://github.com/get-convex/convex-backend/releases/download/${version}/${filename}`;
+  return `https://github.com/convex/convex-backend/releases/download/${version}/${filename}`;
 }
 
 async function downloadZipFile(
@@ -326,6 +341,7 @@ async function downloadZipFile(
 }
 
 export async function ensureDashboardDownloaded(ctx: Context, version: string) {
+  await assertValidBackendVersion(ctx, version);
   const config = loadGlobalDashboardConfig(ctx);
   if (config !== null && config.version === version) {
     return;

package/src/cli/lib/localDeployment/utils.ts

@@ -98,3 +98,7 @@ export const LOCAL_BACKEND_INSTANCE_SECRET =
 export function releaseDate(version: string): string | null {
   return /^precompiled-(\d{4}-\d{2}-\d{2})-/.exec(version)?.[1] ?? null;
 }
+
+export function isValidBackendVersion(version: string): boolean {
+  return /^precompiled-\d{4}-\d{2}-\d{2}-[\w.-]+$/.test(version);
+}

package/src/cli/lib/utils/aiAgent.ts

@@ -0,0 +1,15 @@
+import { determineAgent } from "@vercel/detect-agent";
+
+/**
+ * Returns the name of the AI agent running this process, or null if none is
+ * detected. `@vercel/detect-agent` recognizes the environment variables that
+ * agents like Claude Code, Codex and Cursor set; `CONVEX_AGENT_MODE` is
+ * Convex's own.
+ */
+export async function detectAiAgent(): Promise<string | null> {
+  if (process.env.CONVEX_AGENT_MODE) {
+    return "CONVEX_AGENT_MODE";
+  }
+  const result = await determineAgent();
+  return result.isAgent ? result.agent.name : null;
+}

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.47.0";
+export const version = "1.48.0";

package/src/server/authentication.ts

@@ -235,3 +235,82 @@ export interface Auth {
    */
   getUserIdentity(): Promise<UserIdentity | null>;
 }
+
+/**
+ * {@link Auth} for mutations, which can also sign JWTs with this deployment's
+ * key.
+ *
+ * @public
+ */
+export interface MutationAuth extends Auth {
+  /**
+   * Sign an ES256 JWT with this deployment's key.
+   *
+   * Pass the `claims` and `expiresInSeconds` values that match your use case.
+   *
+   * Convex populates the header and sets the `iss`, `iat` and `exp` claims.
+   *
+   * The `iss` is `process.env.CONVEX_CLOUD_URL` for the app and
+   * `${process.env.CONVEX_CLOUD_URL}/components/<name>` for a component.
+   *
+   * Anyone can verify these tokens against the public keys at
+   * `${process.env.CONVEX_CLOUD_URL}/.well-known/jwks.json`.
+   *
+   * Claims are signed but not encrypted, so anyone holding the token can read
+   * them.
+   *
+   * Prefer short token lifetimes: a token can't be revoked individually, and a
+   * mutation can always sign a fresh one to reassert the claims. This API
+   * allows a token to have a max expiration of 1 hour from issuance.
+   *
+   * Claims that start with `convex` or `cvx` (case insensitive) and the `nbf`
+   * claim are reserved and may not be set.
+   */
+  signJwt(options: SignJwtOptions): Promise<string>;
+}
+
+/**
+ * Claims that callers may not set on JWTs with {@link MutationAuth.signJwt}.
+ */
+export type ReservedJwtClaim = "iss" | "iat" | "exp" | "nbf";
+
+/**
+ * Every ASCII casing of `S`: `AnyCase<"cvx">` is `"cvx" | "cvX" | "cVx" | ...`.
+ */
+type AnyCase<S extends string> = S extends `${infer First}${infer Rest}`
+  ? `${Lowercase<First> | Uppercase<First>}${AnyCase<Rest>}`
+  : S;
+
+/**
+ * Claim names starting with `convex` or `cvx`, in any casing, are reserved
+ * for Convex. They may not be set on JWTs with {@link MutationAuth.signJwt}.
+ */
+// NOTE: only relatively short prefixes should ever be passed below. The AnyCase
+// type produces 2^length string literals which can get out of hand for anything
+// but short strings.
+export type ReservedJwtClaimPrefix = AnyCase<"convex" | "cvx">;
+
+/**
+ * Rejects claim names starting with a {@link ReservedJwtClaimPrefix}.
+ */
+// Kept as a named alias rather than inlined into SignJwtClaims: typedoc's
+// markdown renderer mangles template-literal index signatures into invalid
+// MDX, but renders a reference to a named type as plain text.
+type ReservedPrefixJwtClaims = {
+  [K: `${ReservedJwtClaimPrefix}${string}`]: never;
+};
+
+/**
+ * The claims a caller passes to {@link MutationAuth.signJwt}: any JSON value,
+ * except for the {@link ReservedJwtClaim}s and names starting with a
+ * {@link ReservedJwtClaimPrefix}.
+ */
+export type SignJwtClaims = Record<string, JSONValue> & {
+  [K in ReservedJwtClaim]?: never;
+} & ReservedPrefixJwtClaims;
+
+export type SignJwtOptions = {
+  claims?: SignJwtClaims;
+  /** How long the token stays valid, at least 1 second and at most 1 hour. */
+  expiresInSeconds: number;
+};

package/src/server/components/index.ts

@@ -49,6 +49,17 @@ export type FunctionHandle<
   ReturnType = any,
 > = string & FunctionReference<Type, "internal", Args, ReturnType>;
 
+/**
+ * A {@link FunctionHandle} with the type semantics of {@link FunctionReference_future}.
+ *
+ * @public
+ */
+export type FunctionHandle_future<
+  Type extends FunctionType,
+  Args extends DefaultFunctionArgs = any,
+  ReturnType = any,
+> = string & FunctionReference_future<Type, "internal", Args, ReturnType>;
+
 /**
  * Create a serializable reference to a Convex function.
  * Passing a this reference to another component allows that component to call this