convex 1.40.0 → 1.42.0

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

@@ -101,6 +101,52 @@ export function readDeployKeyFromEnv(
   return fromDeployKey || fromToken || undefined;
 }
 
+// The prefix the backend's `require_operation` checks use when an identity
+// lacks a permission. The full message names the missing permission, e.g.
+// `You do not have permission to perform this operation (deployment:data:view).`
+const PERMISSION_DENIED_MESSAGE_PREFIX =
+  "You do not have permission to perform this operation";
+
+function deployKeyPermissionAdvice(): string | null {
+  // Name whichever env var is actually set. `CONVEX_DEPLOY_KEY` takes
+  // precedence over `CONVEX_DEPLOYMENT_TOKEN` when both are present.
+  const envVarName = process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME]
+    ? CONVEX_DEPLOY_KEY_ENV_VAR_NAME
+    : process.env[CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME]
+      ? CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME
+      : null;
+  if (envVarName === null) {
+    return null;
+  }
+  return `This is determined by the permissions granted to ${envVarName}.`;
+}
+
+/**
+ * Detects a server-side authorization failure (a `require_operation` error,
+ * surfaced both as an HTTP 403 and as an error from a system UDF query) and
+ * produces a clean, single-line message naming the missing permission. When a
+ * deploy key is in use, appends advice for configuring its permissions.
+ *
+ * Returns `null` if `errorMessage` is not a permission error, so callers can
+ * fall back to their normal error handling.
+ */
+export function permissionDeniedErrorMessage(
+  errorMessage: string,
+): string | null {
+  const index = errorMessage.indexOf(PERMISSION_DENIED_MESSAGE_PREFIX);
+  if (index === -1) {
+    return null;
+  }
+  // Drop any wrapping context (e.g. the `[CONVEX Q(...)]` prefix) and stack
+  // trace, keeping just the permission sentence.
+  let msg = errorMessage.slice(index).split("\n")[0].trim();
+  const advice = deployKeyPermissionAdvice();
+  if (advice) {
+    msg = `${msg}\n${advice}`;
+  }
+  return msg;
+}
+
 export function parsePositiveInteger(value: string) {
   const parsedValue = parseInteger(value);
   if (parsedValue <= 0) {
@@ -177,6 +223,16 @@ export class ThrowingFetchError extends Error {
     } else if (this.response.status === 401) {
       error_type = "fatal";
       msg = `${msg}\nAuthenticate with \`npx convex dev\``;
+    } else if (this.response.status === 403) {
+      error_type = "fatal";
+      // Surface the missing permission cleanly (e.g. the server includes the
+      // required action like `deployment:data:view`) instead of the noisy
+      // "Error fetching ..." wrapper.
+      msg = this.serverErrorData?.message ?? msg;
+      const advice = deployKeyPermissionAdvice();
+      if (advice) {
+        msg = `${msg}\n${advice}`;
+      }
     } else if (this.response.status === 404) {
       error_type = "fatal";
       msg = `${msg}: ${this.response.url}`;

package/src/cli/program.ts

@@ -21,6 +21,7 @@ import { logout } from "./logout.js";
 import { logs } from "./logs.js";
 import { mcp } from "./mcp.js";
 import { networkTest } from "./network_test.js";
+import { project } from "./project.js";
 import { reinit } from "./reinit.js";
 import { run } from "./run.js";
 import { typecheck } from "./typecheck.js";
@@ -51,6 +52,7 @@ export function buildProgram() {
       .addCommand(env)
       .addCommand(data)
       .addCommand(deployment)
+      .addCommand(project)
       .addCommand(codegen)
       .addCommand(update)
       .addCommand(logout)

package/src/cli/project.ts

@@ -0,0 +1,7 @@
+import { Command } from "@commander-js/extra-typings";
+import { projectCreate } from "./projectCreate.js";
+
+export const project = new Command("project")
+  .summary("Manage projects")
+  .description("Manage projects in your team.")
+  .addCommand(projectCreate);

package/src/cli/projectCreate.ts

@@ -0,0 +1,99 @@
+import { Command, Option } from "@commander-js/extra-typings";
+import { oneoffContext } from "../bundler/context.js";
+import { logFinishedStep, logMessage, showSpinner } from "../bundler/log.js";
+import { chalkStderr } from "chalk";
+import { createProject } from "./lib/api.js";
+import { ensureAuthCanCreateDeployment } from "./lib/deploymentSelection.js";
+import { validateOrSelectTeam } from "./lib/utils/utils.js";
+import { promptString } from "./lib/utils/prompts.js";
+import { projectDashboardUrl } from "./lib/dashboard.js";
+
+type ProjectCreateOptions = {
+  team?: string | undefined;
+};
+
+async function runProjectCreate(
+  nameArg: string | undefined,
+  options: ProjectCreateOptions,
+): Promise<void> {
+  const ctx = await oneoffContext({
+    url: undefined,
+    adminKey: undefined,
+    envFile: undefined,
+  });
+
+  // Creating a project goes through the platform API, which accepts personal
+  // access tokens and project keys but not deployment/preview deploy keys.
+  // Fail fast (and clearly) for the unsupported keys rather than surfacing an
+  // opaque error later.
+  await ensureAuthCanCreateDeployment(ctx);
+
+  const { team } = await validateOrSelectTeam(ctx, options.team, "Team:");
+
+  let projectName = nameArg;
+  if (!projectName) {
+    if (!process.stdin.isTTY) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage:
+          "Specify a project name:\n" + "  `npx convex project create my-app`",
+      });
+    }
+    projectName = await promptString(ctx, {
+      message: "Project name:",
+    });
+  }
+
+  showSpinner(`Creating project ${projectName}...`);
+  // `project create` only creates the project. Provisioning a deployment is a
+  // separate, explicit step (`npx convex deployment create`) so this command
+  // doesn't have to mirror every deployment setting (region, class, ...).
+  const { projectSlug } = await createProject(ctx, {
+    teamId: team.id,
+    projectName,
+    deploymentToProvision: null,
+  });
+
+  logFinishedStep(
+    `Created project ${chalkStderr.bold(projectSlug)} in team ` +
+      `${chalkStderr.bold(team.slug)}, manage it at ${chalkStderr.bold(
+        projectDashboardUrl(team.slug, projectSlug),
+      )}`,
+  );
+  logMessage(
+    chalkStderr.gray(
+      `Next, add a deployment with ` +
+        `\`npx convex deployment create ${team.slug}:${projectSlug}:dev --type dev\` ` +
+        `(pass \`--region us\` to choose a region).`,
+    ),
+  );
+}
+
+export const projectCreate = new Command("create")
+  .summary("Create a new project")
+  .description(
+    [
+      "Create a new project.",
+      "",
+      "Provisioning a deployment is a separate step — after creating the",
+      "project, run `npx convex deployment create` to add one.",
+      "",
+      "• Create a project in your only team: `npx convex project create my-app`",
+      "• Pick the team: `npx convex project create my-app --team my-team`",
+    ].join("\n"),
+  )
+  .allowExcessArguments(false)
+  .argument(
+    "[name]",
+    "The name of the new project. Prompted for when omitted in an " +
+      "interactive terminal; required otherwise.",
+  )
+  .addOption(
+    new Option(
+      "--team <team_slug>",
+      "The team to create the project in. Defaults to your only team, or " +
+        "prompts when you belong to several.",
+    ),
+  )
+  .action(runProjectCreate);

package/src/cli/run.ts

@@ -31,11 +31,11 @@ export const run = new Command("run")
     [
       "Run a function or evaluate an inline readonly query on your deployment.",
       "",
-      '- Run a function with JSON arguments: `npx convex run messages:send \'{"body": "hello", "author": "me"}\'`',
-      "- Run a function on prod: `npx convex run messages:list --prod`",
-      "- Live-update a query's result: `npx convex run messages:list --watch`",
-      "- Push local code before running: `npx convex run messages:send '{}' --push`",
-      "- Evaluate an inline readonly query: `npx convex run --inline-query 'await ctx.db.query(\"messages\").take(5)'`",
+      '• Run a function with JSON arguments: `npx convex run messages:send \'{"body": "hello", "author": "me"}\'`',
+      "• Run a function on prod: `npx convex run messages:list --prod`",
+      "• Live-update a query's result: `npx convex run messages:list --watch`",
+      "• Push local code before running: `npx convex run messages:send '{}' --push`",
+      "• Evaluate an inline readonly query: `npx convex run --inline-query 'await ctx.db.query(\"messages\").take(5)'`",
       "",
       "Arguments are specified as a JSON object. By default, this runs on your dev deployment.",
     ].join("\n"),

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.40.0";
+export const version = "1.42.0";

package/src/server/database.ts

@@ -14,7 +14,13 @@ import {
 
 interface BaseDatabaseReader<DataModel extends GenericDataModel> {
   /**
-   * Fetch a single document from the database by its {@link values.GenericId}.
+   * Fetch a single document from the database by table name and
+   * {@link values.GenericId}.
+   *
+   * @example
+   * ```typescript
+   * const user = await ctx.db.get("users", userId);
+   * ```
    *
    * @param table - The name of the table to fetch the document from.
    * @param id - The {@link values.GenericId} of the document to fetch from the database.
@@ -28,6 +34,9 @@ interface BaseDatabaseReader<DataModel extends GenericDataModel> {
   /**
    * Fetch a single document from the database by its {@link values.GenericId}.
    *
+   * Supported for backwards compatibility. Prefer `db.get(tableName, id)` in
+   * new code, or `db.system.get(tableName, id)` for system tables.
+   *
    * @param id - The {@link values.GenericId} of the document to fetch from the database.
    * @returns - The {@link GenericDocument} of the document at the given {@link values.GenericId}, or `null` if it no longer exists.
    */
@@ -55,7 +64,7 @@ interface BaseDatabaseReader<DataModel extends GenericDataModel> {
    * This accepts the string ID format as well as the `.toString()` representation
    * of the legacy class-based ID format.
    *
-   * This does not guarantee that the ID exists (i.e. `db.get(id)` may return `null`).
+   * This does not guarantee that the ID exists (i.e. `db.get(tableName, id)` may return `null`).
    *
    * @param tableName - The name of the table.
    * @param id - The ID string.
@@ -109,7 +118,7 @@ export interface BaseTableReader<
  *
  * The two entry points are:
  *   - {@link GenericDatabaseReader.get}, which fetches a single document
- *     by its {@link values.GenericId}.
+ *     by table name and {@link values.GenericId}.
  *   - {@link GenericDatabaseReader.query}, which starts building a query.
  *
  * @example
@@ -272,6 +281,9 @@ export interface GenericDatabaseWriter<DataModel extends GenericDataModel>
    *
    * This method will throw if the document does not exist.
    *
+   * Supported for backwards compatibility. Prefer `db.patch(tableName, id, value)`
+   * in new code.
+   *
    * @param id - The {@link values.GenericId} of the document to patch.
    * @param value - The partial document to merge into the existing document.
    */
@@ -316,6 +328,9 @@ export interface GenericDatabaseWriter<DataModel extends GenericDataModel>
    * Unlike `patch`, which does a shallow merge, `replace` overwrites the
    * entire document.
    *
+   * Supported for backwards compatibility. Prefer `db.replace(tableName, id, value)`
+   * in new code.
+   *
    * @param id - The {@link values.GenericId} of the document to replace.
    * @param value - The new document. System fields can be omitted.
    */
@@ -343,6 +358,9 @@ export interface GenericDatabaseWriter<DataModel extends GenericDataModel>
   /**
    * Delete an existing document.
    *
+   * Supported for backwards compatibility. Prefer `db.delete(tableName, id)` in
+   * new code.
+   *
    * **Note:** Convex queries do not support `.delete()` directly on query
    * results. To delete multiple documents, `.collect()` them first, then
    * delete each one individually.

package/src/server/impl/meta_impl.ts

@@ -34,7 +34,10 @@ async function getFunctionMetadata(): Promise<{
     "1.0/getFunctionMetadata",
     {},
   );
-  return { name, componentPath };
+  return {
+    name,
+    componentPath,
+  };
 }
 
 async function getDeploymentMetadata(): Promise<DeploymentMetadata> {
@@ -51,11 +54,9 @@ async function getDeploymentMetadata(): Promise<DeploymentMetadata> {
 }
 
 async function getRequestMetadata(): Promise<RequestMetadata> {
-  const { ip, userAgent, requestId } = await performAsyncSyscall(
-    "1.0/getRequestMetadata",
-    {},
-  );
-  return { ip, userAgent, requestId };
+  const { ip, userAgent, requestId, scheduledFunctionId } =
+    await performAsyncSyscall("1.0/getRequestMetadata", {});
+  return { ip, userAgent, requestId, scheduledFunctionId };
 }
 
 export function setupQueryMeta(

package/src/server/impl/registration_impl.ts

@@ -61,9 +61,9 @@ async function invokeMutation<
     meta: setupMutationMeta(visibility),
 
     runQuery: (reference: any, args?: any, options?: any) =>
-      runUdf("query", reference, args, options?.transactionLimits),
-    runSnapshotQuery: (reference: any, args?: any, options?: any) =>
-      runUdf("snapshotQuery", reference, args, options?.transactionLimits),
+      options?.useStaleSnapshot
+        ? runUdf("snapshotQuery", reference, args, options?.transactionLimits)
+        : runUdf("query", reference, args, options?.transactionLimits),
     runMutation: (reference: any, args?: any, options?: any) =>
       runUdf("mutation", reference, args, options?.transactionLimits),
   };
@@ -338,8 +338,14 @@ async function invokeQuery<
     auth: setupAuth(requestId),
     storage: setupStorageReader(requestId),
     meta: setupQueryMeta(visibility),
-    runQuery: (reference: any, args?: any, options?: any) =>
-      runUdf("query", reference, args, options?.transactionLimits),
+    runQuery: (reference: any, args?: any, options?: any) => {
+      if (options?.useStaleSnapshot) {
+        throw new Error(
+          "`useStaleSnapshot` is only supported in mutations, not queries.",
+        );
+      }
+      return runUdf("query", reference, args, options?.transactionLimits);
+    },
   };
   const result = await invokeFunction(func, queryCtx, args as any);
   validateReturnValue(result);

package/src/server/index.ts

@@ -106,6 +106,7 @@ export {
 export type {
   TransactionMetric,
   TransactionMetrics,
+  TransactionLimits,
   FunctionMetadata,
   DeploymentMetadata,
   RequestMetadata,
@@ -117,6 +118,7 @@ export type { IndexRange, IndexRangeBuilder } from "./index_range_builder.js";
 export * from "./pagination.js";
 export type { OrderedQuery, Query, QueryInitializer } from "./query.js";
 export type {
+  AdvancedRunQueryOptions,
   ArgsArray,
   DefaultFunctionArgs,
   FunctionVisibility,

package/src/server/meta.ts

@@ -28,6 +28,23 @@ export type TransactionMetrics = {
   scheduledFunctionArgsBytes: TransactionMetric;
 };
 
+/**
+ * Custom limits for a nested transaction. Each field specifies the absolute
+ * maximum allowed for the nested function call. Values are capped at the
+ * global transaction limits, so they can only lower limits, never raise them.
+ *
+ * @public
+ */
+export interface TransactionLimits {
+  bytesRead?: number;
+  bytesWritten?: number;
+  databaseQueries?: number;
+  documentsRead?: number;
+  documentsWritten?: number;
+  functionsScheduled?: number;
+  scheduledFunctionArgsBytes?: number;
+}
+
 /**
  * Metadata about the currently executing Convex function.
  *
@@ -87,6 +104,16 @@ export type RequestMetadata = {
   ip: string | null;
   userAgent: string | null;
   requestId: string;
+  /**
+   * The ID of the scheduled function document (in `_scheduled_functions`) that
+   * this execution belongs to, or `null` otherwise.
+   *
+   * This is set for the scheduled function itself and for any functions it
+   * calls (e.g. a mutation invoked via `runMutation` by a scheduled action),
+   * propagating the top-level scheduled function's ID down the call tree. It is
+   * `null` when the function was not scheduled.
+   */
+  scheduledFunctionId: string | null;
 };
 
 /**

package/src/server/query.ts

@@ -106,7 +106,7 @@ export interface QueryInitializer<TableInfo extends GenericTableInfo>
 /**
  * The {@link Query} interface allows functions to read values out of the database.
  *
- * **If you only need to load an object by ID, use `db.get(id)` instead.**
+ * **If you only need to load an object by ID, use `db.get(tableName, id)` instead.**
  *
  * Executing a query consists of calling
  * 1. (Optional) {@link Query.order} to define the order

package/src/server/registration.test.ts

@@ -6,19 +6,15 @@ import {
   ActionBuilder,
   ApiFromModules,
   DefaultFunctionArgs,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
   QueryBuilder,
   actionGeneric,
   mutationGeneric,
   queryGeneric,
 } from "./index.js";
-import {
-  EmptyObject,
-  GenericActionCtx,
-  GenericMutationCtx,
-  GenericQueryCtx,
-  MutationBuilder,
-} from "./registration.js";
-import { GenericDataModel } from "./data_model.js";
+import { EmptyObject, MutationBuilder } from "./registration.js";
 
 describe("argument inference", () => {
   // Test with mutation, but all the wrappers work the same way.
@@ -571,28 +567,23 @@ describe("argument and return value validators can be objects or validators", ()
   });
 });
 
-describe("runSnapshotQuery availability", () => {
-  test("available on mutation ctx", () => {
-    assert<
-      "runSnapshotQuery" extends keyof GenericMutationCtx<GenericDataModel>
-        ? true
-        : false
-    >();
-  });
+describe("useStaleSnapshot availability", () => {
+  type MutationRunQueryOptions = NonNullable<
+    Parameters<GenericMutationCtx<GenericDataModel>["runQuery"]>[2]
+  >;
+  type QueryRunQueryOptions = NonNullable<
+    Parameters<GenericQueryCtx<GenericDataModel>["runQuery"]>[2]
+  >;
 
-  test("not available on query ctx", () => {
-    assertFalse<
-      "runSnapshotQuery" extends keyof GenericQueryCtx<GenericDataModel>
-        ? true
-        : false
+  test("available on mutation ctx runQuery options", () => {
+    assert<
+      "useStaleSnapshot" extends keyof MutationRunQueryOptions ? true : false
     >();
   });
 
-  test("not available on action ctx", () => {
+  test("not available on query ctx runQuery options", () => {
     assertFalse<
-      "runSnapshotQuery" extends keyof GenericActionCtx<GenericDataModel>
-        ? true
-        : false
+      "useStaleSnapshot" extends keyof QueryRunQueryOptions ? true : false
     >();
   });
 });

package/src/server/registration.ts

@@ -8,8 +8,14 @@ import {
   StorageReader,
   StorageWriter,
 } from "./index.js";
-import { ActionMeta, MutationMeta, QueryMeta } from "./meta.js";
 import {
+  ActionMeta,
+  MutationMeta,
+  QueryMeta,
+  TransactionLimits,
+} from "./meta.js";
+import {
+  ArgsAndOptions,
   FunctionReference,
   FunctionReturnType,
   OptionalRestArgs,
@@ -129,22 +135,7 @@ export interface GenericMutationCtx<DataModel extends GenericDataModel> {
    */
   runQuery: <Query extends FunctionReference<"query", "public" | "internal">>(
     query: Query,
-    ...args: OptionalRestArgs<Query>
-  ) => Promise<FunctionReturnType<Query>>;
-
-  /**
-   * Experimental: call a query function in the same transaction that runs on a
-   * snapshot of the database without taking a read dependency.
-   *
-   * This is an unstable feature and its behavior may change in the future.
-   *
-   * @internal
-   */
-  runSnapshotQuery: <
-    Query extends FunctionReference<"query", "public" | "internal">,
-  >(
-    query: Query,
-    ...args: OptionalRestArgs<Query>
+    ...args: ArgsAndOptions<Query, AdvancedRunQueryOptions>
   ) => Promise<FunctionReturnType<Query>>;
 
   /**
@@ -161,7 +152,7 @@ export interface GenericMutationCtx<DataModel extends GenericDataModel> {
     Mutation extends FunctionReference<"mutation", "public" | "internal">,
   >(
     mutation: Mutation,
-    ...args: OptionalRestArgs<Mutation>
+    ...args: ArgsAndOptions<Mutation, { transactionLimits?: TransactionLimits }>
   ) => Promise<FunctionReturnType<Mutation>>;
 
   meta: MutationMeta;
@@ -254,7 +245,7 @@ export interface GenericQueryCtx<DataModel extends GenericDataModel> {
    */
   runQuery: <Query extends FunctionReference<"query", "public" | "internal">>(
     query: Query,
-    ...args: OptionalRestArgs<Query>
+    ...args: ArgsAndOptions<Query, { transactionLimits?: TransactionLimits }>
   ) => Promise<FunctionReturnType<Query>>;
 
   meta: QueryMeta;
@@ -1220,3 +1211,18 @@ export type ActionBuilder<
 export type HttpActionBuilder = (
   func: (ctx: GenericActionCtx<any>, request: Request) => Promise<Response>,
 ) => PublicHttpAction;
+
+export interface AdvancedRunQueryOptions {
+  transactionLimits?: TransactionLimits;
+  /**
+   * Run a query on a recent snapshot of the database that is not guaranteed
+   * to be up-to-date when this transaction commits.
+   *
+   * This is an advanced feature which can introduce subtle race conditions,
+   * so its use is generally discouraged except for specific use-cases where
+   * database read conflicts are expected, e.g. reading from an append-only
+   * table with immutable records where the only read conflicts are from
+   * concurrent appends.
+   */
+  useStaleSnapshot?: boolean;
+}

package/src/server/storage.ts

@@ -1,16 +1,28 @@
 import { GenericId } from "../values/index.js";
 
 /**
- * A reference to a file in storage.
+ * @deprecated This ID format is no longer returned by stable file storage APIs. Use `Id<"_storage">` instead.
  *
- * This is used in the {@link StorageReader} and {@link StorageWriter} which are accessible in
- * Convex queries and mutations via {@link QueryCtx} and {@link MutationCtx} respectively.
+ * The old ID format used by Convex file storage.
+ *
+ * ⚠️ Security warning: Anyone that has knows to this ID can download the underlying file
+ * from `https://<deployment>.convex.cloud/api/storage/<storageId>`.
+ * (Note that it’s safe to share the new ID format, `Id<"_storage">`, to anyone).
  *
  * @public
  */
 export type StorageId = string;
+
+/**
+ * @deprecated This type is only necessary for backwards compatibility with Convex versions that
+ * pre-date `convex@1.6.0`. Use `Id<"_storage">` instead.
+ */
 export type FileStorageId = GenericId<"_storage"> | StorageId;
+
 /**
+ * @deprecated This type is only returned by {@link StorageReader.getUrl | storage.getUrl}.
+ *   To get the details of a document, use `ctx.db.system.get("_storage", storageId)` instead.
+ *
  * Metadata for a single file as returned by {@link StorageReader.getMetadata | storage.getMetadata}.
  *
  * @public
@@ -18,6 +30,13 @@ export type FileStorageId = GenericId<"_storage"> | StorageId;
 export type FileMetadata = {
   /**
    * ID for referencing the file (eg. via {@link StorageReader.getUrl | storage.getUrl})
+   *
+   * This is an older ID format that is no longer returned by stable file storage APIs.
+   * Consider using `Id<"_storage">` instead.
+   *
+   * ⚠️ Security warning: Anyone that has knows to this ID can download the underlying file
+   * from `https://<deployment>.convex.cloud/api/storage/<storageId>`.
+   * (Note that it’s safe to share the new ID format, `Id<"_storage">`, to anyone).
    */
   storageId: StorageId;
   /**

package/src/server/system_fields.ts

@@ -46,7 +46,7 @@ export type WithOptionalSystemFields<Document extends GenericDocument> = Expand<
  * @public
  */
 export type SystemIndexes = {
-  // Note `db.get(id)` is simpler and equivalent to a query on `by_id`.
+  // Note `db.get(tableName, id)` is simpler and equivalent to a query on `by_id`.
   // Unless the query is being built dynamically, or doing manual pagination.
   by_id: ["_id"];