convex 1.46.0 → 1.48.0-alpha.0

package/src/cli/logout.ts

@@ -1,24 +1,149 @@
 import { Command } from "@commander-js/extra-typings";
 import { oneoffContext } from "../bundler/context.js";
-import { logFinishedStep } from "../bundler/log.js";
+import { logFinishedStep, logMessage, logWarning } from "../bundler/log.js";
 import { recursivelyDelete } from "./lib/fsUtils.js";
 import { globalConfigPath } from "./lib/utils/globalConfig.js";
+import {
+  getProfileSelection,
+  profileConfigPath,
+  readProfileToken,
+  readProfileSettings,
+  updateProfileSettings,
+  savedProfileNames,
+} from "./lib/profiles.js";
+import path from "path";
+import { rootDirectory } from "./lib/utils/utils.js";
+import { promptOptions } from "./lib/utils/prompts.js";
 
-export const logout = new Command("logout")
-  .description("Log out of Convex on this machine")
-  .allowExcessArguments(false)
-  .action(async () => {
-    const ctx = await oneoffContext({
-      url: undefined,
-      adminKey: undefined,
-      envFile: undefined,
-    });
+export function createLogoutCommand() {
+  return new Command("logout")
+    .description(
+      "Log out of the selected account. Directory selections are preserved.",
+    )
+    .option("--account <name>", "Remove only this account's saved credentials")
+    .option(
+      "--all",
+      "Remove all saved account credentials, preserving account selections",
+    )
+    .allowExcessArguments(false)
+    .action(async (options, cmd) => {
+      if (options.all && options.account !== undefined)
+        cmd.error("Pass either --account or --all, not both.");
+      const ctx = await oneoffContext({
+        url: undefined,
+        adminKey: undefined,
+        envFile: undefined,
+        skipAuth: true,
+      });
+
+      let all = !!options.all;
+      let profile = all
+        ? null
+        : await getProfileSelection(ctx, { name: options.account });
+      if (
+        !all &&
+        options.account === undefined &&
+        process.stdin.isTTY &&
+        profile !== null
+      ) {
+        const token = readProfileToken(ctx, profile.name);
+        const settings = await readProfileSettings(ctx);
+        const selectedName = profile.name;
+        // A matching compatibility token is another copy of this account's login.
+        const hasOtherLogins =
+          savedProfileNames(ctx).some((name) => name !== selectedName) ||
+          (typeof settings.accessToken === "string" &&
+            settings.accessToken.length > 0 &&
+            settings.accessToken !== token);
+        if (hasOtherLogins) {
+          const scope = await promptOptions(ctx, {
+            message: "Which saved logins would you like to log out of?",
+            choices: [
+              { name: `Only account "${profile.name}"`, value: "profile" },
+              { name: "All saved logins on this device", value: "all" },
+            ],
+            default: "profile",
+          });
+          if (scope === "all") {
+            profile = null;
+            all = true;
+          }
+        }
+      }
 
-    if (ctx.fs.exists(globalConfigPath())) {
-      recursivelyDelete(ctx, globalConfigPath());
-    }
+      let warnAboutLegacyCredentials = false;
+      if (profile !== null) {
+        const selectedName = profile.name;
+        await updateProfileSettings(
+          ctx,
+          (settings) => {
+            const token = readProfileToken(ctx, selectedName);
+            // A migrated account can share its token with old CLI versions.
+            if (token !== null && settings.accessToken === token) {
+              delete settings.accessToken;
+            } else if (
+              settings.defaultProfile === selectedName &&
+              typeof settings.accessToken === "string" &&
+              settings.accessToken.length > 0
+            ) {
+              // Editing the default or logging in with an older CLI can leave this
+              // token belonging to a different account.
+              warnAboutLegacyCredentials = true;
+            }
+          },
+          () => {
+            const configPath = profileConfigPath(selectedName);
+            recursivelyDelete(ctx, configPath, {
+              force: true,
+              followSymlinks: false,
+            });
+          },
+        );
+      } else {
+        await updateProfileSettings(
+          ctx,
+          async (settings) => {
+            if (
+              !all &&
+              savedProfileNames(ctx).length > 0 &&
+              settings.accessToken === undefined
+            ) {
+              return await ctx.crash({
+                exitCode: 1,
+                errorType: "fatal",
+                printedMessage:
+                  "No account is selected. Use `npx convex logout --account <name>` or `npx convex logout --all`.",
+              });
+            }
+            delete settings.accessToken;
+          },
+          () => {
+            const profilesDir = path.join(rootDirectory(), "profiles");
+            if (all)
+              recursivelyDelete(ctx, profilesDir, {
+                force: true,
+                followSymlinks: false,
+              });
+          },
+        );
+      }
+
+      logFinishedStep(
+        profile !== null
+          ? `Removed credentials for account "${profile.name}".\n  Run \`npx convex login --account ${profile.name}\` to log in.`
+          : `${all ? "Removed all saved Convex account credentials." : "Removed your saved Convex login credentials."}\n  Run \`npx convex login\` to log in.`,
+      );
+      if (warnAboutLegacyCredentials) {
+        logWarning(
+          `Saved credentials remain in ${globalConfigPath()} for older CLI versions. To remove all saved account credentials, run \`npx convex logout --all\`.`,
+        );
+      }
+      if (process.env.CONVEX_OVERRIDE_ACCESS_TOKEN) {
+        logMessage(
+          "CONVEX_OVERRIDE_ACCESS_TOKEN still supplies credentials. Unset it to stop using that token.",
+        );
+      }
+    });
+}
 
-    logFinishedStep(
-      "You have been logged out of Convex.\n  Run `npx convex dev` to log in.",
-    );
-  });
+export const logout = createLogoutCommand();

package/src/cli/mcp.ts

@@ -1,3 +1,4 @@
+import path from "path";
 import { Command, Option } from "@commander-js/extra-typings";
 import { oneoffContext } from "../bundler/context.js";
 import { logError } from "../bundler/log.js";
@@ -6,6 +7,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { actionDescription } from "./lib/command.js";
 import { checkAuthorization } from "./lib/login.js";
 import {
+  encodeDeploymentSelector,
   McpOptions,
   RequestContext,
   RequestCrash,
@@ -115,6 +117,14 @@ function enabledTools(
 export function makeServer(options: McpOptions) {
   const enabledToolsByName = enabledTools(options);
   const mutex = new Mutex();
+  const serverDirectory = process.cwd();
+  options = {
+    ...options,
+    envFile:
+      options.envFile === undefined
+        ? undefined
+        : path.resolve(serverDirectory, options.envFile),
+  };
   const server = new Server(
     {
       name: "Convex MCP Server",
@@ -128,17 +138,7 @@ export function makeServer(options: McpOptions) {
   );
   server.setRequestHandler("tools/call", async (request: CallToolRequest) => {
     const ctx = new RequestContext(options);
-    await initializeBigBrainAuth(ctx, options);
     try {
-      const authorized = await checkAuthorization(ctx, false);
-      if (!authorized) {
-        await ctx.crash({
-          exitCode: 1,
-          errorType: "fatal",
-          printedMessage:
-            "Not Authorized: Run `npx convex dev` to login to your Convex project.",
-        });
-      }
       if (!request.params.arguments) {
         await ctx.crash({
           exitCode: 1,
@@ -158,7 +158,44 @@ export function makeServer(options: McpOptions) {
 
       // Serialize tool handlers since they're mutating the current working directory.
       const result = await mutex.runExclusive(async () => {
-        return await convexTool.handler(ctx, input);
+        const projectDir =
+          "deploymentSelector" in input
+            ? ctx.decodeDeploymentSelectorUnchecked(input.deploymentSelector)
+                .projectDir
+            : (("projectDir" in input ? input.projectDir : undefined) ??
+              options.projectDir);
+        const previousDirectory = process.cwd();
+        try {
+          if (projectDir !== undefined)
+            process.chdir(path.resolve(serverDirectory, projectDir));
+          await initializeBigBrainAuth(ctx, options);
+          if (!(await checkAuthorization(ctx, false))) {
+            await ctx.crash({
+              exitCode: 1,
+              errorType: "fatal",
+              printedMessage:
+                "Not Authorized: Run `npx convex dev` to login to your Convex project.",
+            });
+          }
+          const absoluteDirectory = process.cwd();
+          const resolvedInput =
+            "deploymentSelector" in input
+              ? {
+                  ...input,
+                  deploymentSelector: encodeDeploymentSelector(
+                    absoluteDirectory,
+                    ctx.decodeDeploymentSelectorUnchecked(
+                      input.deploymentSelector,
+                    ).deployment,
+                  ),
+                }
+              : projectDir === undefined
+                ? input
+                : { ...input, projectDir: absoluteDirectory };
+          return await convexTool.handler(ctx, resolvedInput);
+        } finally {
+          process.chdir(previousDirectory);
+        }
       });
       return {
         content: [

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 { account } from "./account.js";
 import { project } from "./project.js";
 import { reinit } from "./reinit.js";
 import { run } from "./run.js";
@@ -56,6 +57,7 @@ export function buildProgram() {
       .addCommand(codegen)
       .addCommand(update)
       .addCommand(logout)
+      .addCommand(account)
       .addCommand(networkTest, { hidden: true })
       .addCommand(integration, { hidden: true })
       .addCommand(functionSpec)

package/src/cli/projectCreate.ts

@@ -64,7 +64,7 @@ async function runProjectCreate(
   logMessage(
     chalkStderr.gray(
       `Next, add a deployment with ` +
-        `\`npx convex deployment create ${team.slug}:${projectSlug}:dev --type dev\` ` +
+        `\`npx convex deployment create ${team.slug}:${projectSlug}:dev/my-feature --type dev --select\` ` +
         `(pass \`--region us\` to choose a region).`,
     ),
   );

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.46.0";
+export const version = "1.48.0-alpha.0";

package/src/server/impl/actions_impl.ts

@@ -64,26 +64,46 @@ export function setupActionCalls(requestId: string) {
   };
 }
 
+/**
+ * A Convex-managed service. The backend decides which names it accepts; this
+ * type lists the ones the current release knows about.
+ */
+export type ServiceName = "ai-gateway";
+
 /**
  * Get a short-lived credential for calling a Convex-managed service.
  *
  * This function can only be called while an action is running. The credential
  * is scoped to the current deployment and should be sent as a bearer token.
- * Repeated calls in the same action reuse one token; a failed mint is not
- * cached, so a later call retries.
+ * The action runtime caches and refreshes credentials as needed, so call
+ * this function whenever making a service request.
  *
  * @param service - The service the credential may access.
  * @returns A JWT to send as `Authorization: Bearer <token>`. Keep it inside
  * the action: don't return it to clients or store it in environment
  * variables.
  */
-export async function getServiceToken(service: "ai-gateway"): Promise<string> {
+export async function getServiceToken(service: ServiceName): Promise<string> {
   validateArg(service, 1, "getServiceToken", "service");
-  if (service !== "ai-gateway") {
-    throw new Error(`Unsupported service "${String(service)}"`);
-  }
   return await performAsyncSyscall("1.0/createServiceToken", {
     service,
     version,
   });
 }
+
+/**
+ * Get the base URL of a Convex-managed service.
+ *
+ * This function can only be called while an action is running. Pair it with
+ * {@link getServiceToken} to reach the service.
+ *
+ * @param service - The service to address.
+ * @returns The service's origin, without a trailing slash.
+ */
+export async function getServiceUrl(service: ServiceName): Promise<string> {
+  validateArg(service, 1, "getServiceUrl", "service");
+  return await performAsyncSyscall("1.0/getServiceUrl", {
+    service,
+    version,
+  });
+}

package/src/server/impl/storage_impl.ts

@@ -6,6 +6,7 @@ import {
   StorageWriter,
 } from "../storage.js";
 import { version } from "../../index.js";
+import { fromByteArray, toByteArray } from "../../values/base64.js";
 import { performAsyncSyscall, performJsSyscall } from "./syscall.js";
 import { validateArg } from "./validate.js";
 
@@ -45,6 +46,35 @@ export function setupStorageWriter(requestId: string): StorageWriter {
         storageId,
       });
     },
+    store: async (blob: Blob, options?: { sha256?: string }) => {
+      if (!(blob instanceof Blob)) {
+        throw new Error(
+          "store() expects a Blob. If you are trying to store a Request, `await request.blob()` will give you the correct input.",
+        );
+      }
+      const bytes = new Uint8Array(await blob.arrayBuffer());
+      return await performAsyncSyscall("1.0/storageStore", {
+        requestId,
+        version,
+        blob: fromByteArray(bytes),
+        contentType: blob.type,
+        sha256: options?.sha256,
+      });
+    },
+    get: async (storageId: FileStorageId) => {
+      const result: { blob: string; contentType: string | null } | null =
+        await performAsyncSyscall("1.0/storageGet", {
+          requestId,
+          version,
+          storageId,
+        });
+      if (result === null) {
+        return null;
+      }
+      return new Blob([toByteArray(result.blob)], {
+        type: result.contentType ?? "",
+      });
+    },
     getUrl: reader.getUrl,
     getMetadata: reader.getMetadata,
   };

package/src/server/index.ts

@@ -103,7 +103,11 @@ export {
   internalMutationGeneric,
   internalQueryGeneric,
 } from "./impl/registration_impl.js";
-export { getServiceToken } from "./impl/actions_impl.js";
+export {
+  getServiceToken,
+  getServiceUrl,
+  type ServiceName,
+} from "./impl/actions_impl.js";
 export type {
   TransactionMetric,
   TransactionMetrics,

package/src/server/meta.ts

@@ -26,6 +26,14 @@ export type TransactionMetrics = {
   documentsWritten: TransactionMetric;
   functionsScheduled: TransactionMetric;
   scheduledFunctionArgsBytes: TransactionMetric;
+  /** @internal */
+  filesWritten: TransactionMetric;
+  /** @internal */
+  fileWriteBytes: TransactionMetric;
+  /** @internal */
+  filesRead: TransactionMetric;
+  /** @internal */
+  fileReadBytes: TransactionMetric;
 };
 
 /**
@@ -43,6 +51,14 @@ export interface TransactionLimits {
   documentsWritten?: number;
   functionsScheduled?: number;
   scheduledFunctionArgsBytes?: number;
+  /** @internal */
+  filesWritten?: number;
+  /** @internal */
+  fileWriteBytes?: number;
+  /** @internal */
+  filesRead?: number;
+  /** @internal */
+  fileReadBytes?: number;
 }
 
 /**
@@ -130,18 +146,30 @@ export type RequestMetadata = {
  * @public
  */
 export interface QueryMeta {
+  /**
+   * Metadata about the currently executing Convex function.
+   */
   getFunctionMetadata(): Promise<FunctionMetadata>;
+  /**
+   * The remaining headroom for a transaction before hitting limits.
+   *
+   * See https://docs.convex.dev/production/state/limits
+   */
   getTransactionMetrics(): Promise<TransactionMetrics>;
+  /**
+   * Metadata about the deployment this function is running on.
+   */
   getDeploymentMetadata(): Promise<DeploymentMetadata>;
   /**
-   * @internal
    * Returns the timestamp of the database snapshot this transaction reads
    * from, in nanoseconds.
    *
    * All commits at or before this timestamp are observable within the
    * transaction, and no later commits are. The value is fixed for the
    * lifetime of the transaction and shared with all nested `runMutation` and
-   * `runQuery` calls.
+   * non-stale `runQuery` calls. If a nested query is called with
+   * `useStaleSnapshot: true`, then the nested query may in a future backend
+   * version choose an older snapshotTs.
    *
    * It is on the same clock as `db.vars.commitTs`: documents observable in
    * this transaction have `commitTs` values at or before this timestamp, and
@@ -156,6 +184,8 @@ export interface QueryMeta {
    * Note: this should not be compared to `_creationTime` or `Date.now()`, as
    * those are based on wall-clock time rather than the database clock, and
    * aren't guaranteed to follow commit order.
+   *
+   * Docs: https://docs.convex.dev/database/advanced/commit-timestamp
    */
   getSnapshotTs(): bigint;
 }
@@ -166,6 +196,15 @@ export interface QueryMeta {
  * @public
  */
 export interface MutationMeta extends QueryMeta {
+  /**
+   * Metadata about the HTTP request that triggered the current function execution.
+   *
+   * `ip` and `userAgent` are `null` when the function was not triggered by an
+   * HTTP request (e.g. scheduled jobs or cron jobs).
+   *
+   * Functions called from within a function (i.e. using `runMutation`) will have
+   * the same request metadata as the parent function.
+   */
   getRequestMetadata(): Promise<RequestMetadata>;
 }
 
@@ -175,7 +214,22 @@ export interface MutationMeta extends QueryMeta {
  * @public
  */
 export interface ActionMeta {
+  /**
+   * Metadata about the currently executing Convex function.
+   */
   getFunctionMetadata(): Promise<FunctionMetadata>;
+  /**
+   * Metadata about the deployment this function is running on.
+   */
   getDeploymentMetadata(): Promise<DeploymentMetadata>;
+  /**
+   * Metadata about the HTTP request that triggered the current function execution.
+   *
+   * `ip` and `userAgent` are `null` when the function was not triggered by an
+   * HTTP request (e.g. scheduled jobs or cron jobs).
+   *
+   * Functions called from within a function (i.e. using `runMutation` or
+   * `runAction`) will have the same request metadata as the parent function.
+   */
   getRequestMetadata(): Promise<RequestMetadata>;
 }

package/src/server/registration.ts

@@ -1234,6 +1234,11 @@ export type HttpActionBuilder = (
 ) => PublicHttpAction;
 
 export interface AdvancedRunQueryOptions {
+  /**
+   * 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.
+   */
   transactionLimits?: TransactionLimits;
   /**
    * Run a query on a recent snapshot of the database that is not guaranteed
@@ -1244,6 +1249,11 @@ export interface AdvancedRunQueryOptions {
    * 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.
+   *
+   * To determine the snapshot of the nested query, you can call
+   * `ctx.meta.getSnapshotTs()` from within the stale snapshot query. To
+   * compare to the parent mutation's snapshot timestamp, you can return that
+   * value from the query and call `ctx.meta.getSnapshotTs()` from the parent.
    */
   useStaleSnapshot?: boolean;
 }

package/src/server/schema.ts

@@ -561,41 +561,63 @@ export class TableDefinition<
   }
 
   /**
-   * Stage a new document validator for this table.
+   * Stage changes to this table's document validator.
    *
    * Convex validates the staged validator against the table's existing
    * documents in the background, while the validator passed to
-   * {@link defineTable} remains the one enforced on reads and writes. Once
-   * the background validation succeeds, make the staged validator the
-   * table's validator and remove `.staged()`.
+   * {@link defineTable} remains the one enforced on writes. Once
+   * the background validation succeeds, apply the staged changes
+   * and remove `.staged()`.
+   *
+   * For an object validator, pass only the fields to add or replace. Fields
+   * omitted from the changes keep their enforced validators.
+   * Set a field to `undefined` to remove it from the staged validator.
+   * For nested objects, you must specify the full object validator.
    *
    * ```ts
    * defineTable({
-   *   author: v.string(),
+   *   apple: v.string(),
+   *   banana: v.number(),
+   *   legacy: v.optional(v.string()),
    * }).staged({
-   *   author: v.array(v.string()),
+   *   banana: v.union(v.string(), v.number()),
+   *   legacy: undefined,
    * })
    * ```
    *
-   * TODO: link a worked staged-schema example from the docs once one exists.
+   * See [Staged validators](https://docs.convex.dev/database/schemas#staged-validators).
    *
-   * @param documentSchema - The proposed next type of documents stored in
-   * this table, as an object of field validators or a schema validator.
+   * @param documentSchema - Field changes for a table defined as an object or
+   * `v.any()`, or a full schema validator specifying the proposed next document
+   * type. Use a full schema validator for a table defined as a union.
    * @returns A {@link TableDefinition} with the staged validator attached.
-   *
-   * @internal
    */
   staged(
     documentSchema:
       | Validator<Record<string, any>, "required", any>
-      | Record<string, GenericValidator>,
+      | Record<string, GenericValidator | undefined>,
   ): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes> {
     if (this.stagedValidator !== undefined) {
       throw new Error("Table cannot have more than one staged validator.");
     }
-    this.stagedValidator = isValidator(documentSchema)
-      ? documentSchema
-      : v.object(documentSchema);
+    if (isValidator(documentSchema)) {
+      this.stagedValidator = documentSchema;
+    } else {
+      if (this.validator.kind !== "object" && this.validator.kind !== "any") {
+        throw new Error(
+          "Specifying top-level field changes is only supported for simple table definitions. For a table defined with a union or record validator, you must stage a fully defined object or union validator.",
+        );
+      }
+      const enforcedFields =
+        this.validator.kind === "object" ? this.validator.fields : {};
+      const fields: Record<string, GenericValidator> = Object.fromEntries(
+        Object.entries({ ...enforcedFields, ...documentSchema }).filter(
+          (entry): entry is [string, GenericValidator] =>
+            entry[1] !== undefined,
+        ),
+      );
+      this.stagedValidator = v.object(fields);
+    }
     return this.self();
   }
 

package/src/server/storage.ts

@@ -194,6 +194,23 @@ export interface StorageWriter extends StorageReader {
   delete<T extends StorageId>(
     storageId: T extends { __tableName: any } ? never : T,
   ): Promise<void>;
+
+  /**
+   * @internal
+   */
+  // TODO: move `store` from StorageActionWriter to StorageWriter when mutation
+  // file storage access is ready for release
+  store(
+    blob: Blob,
+    options?: { sha256?: string },
+  ): Promise<GenericId<"_storage">>;
+
+  /**
+   * @internal
+   */
+  // TODO: move `get` from StorageActionWriter to StorageWriter when mutation
+  // file storage access is ready for release
+  get(storageId: GenericId<"_storage">): Promise<Blob | null>;
 }
 
 /**

package/src/values/validators.ts

@@ -641,7 +641,7 @@ export class VRecord<
       throw new Error("Record validator cannot have optional values");
     }
     if (!key.isConvexValidator || !value.isConvexValidator) {
-      throw new Error("Key and value of v.record() but be validators");
+      throw new Error("Key and value of v.record() must be validators");
     }
     this.key = key;
     this.value = value;

package/src/values/value.ts

@@ -311,13 +311,17 @@ const MAX_VALUE_FOR_ERROR_LEN = 16384;
 export function stringifyValueForError(value: any) {
   const str = JSON.stringify(value, (_key, value) => {
     if (value === undefined) {
-      // By default `JSON.stringify` converts undefined, functions, symbols,
-      // Infinity, and NaN to null which produces a confusing error message.
-      // We deal with `undefined` specifically because it's the most common.
-      // Ideally we'd use a pretty-printing library that prints `undefined`
-      // (no quotes), but it might not be worth the bundle size cost.
+      // JSON.stringify omits undefined object properties and converts undefined
+      // array elements to null. Preserve them in error messages.
       return "undefined";
     }
+    if (typeof value === "function") {
+      // A fixed placeholder also works for functions with custom string coercion.
+      return "[Function]";
+    }
+    if (typeof value === "symbol") {
+      return String(value);
+    }
     if (typeof value === "bigint") {
       // `JSON.stringify` throws on bigints by default.
       return `${value.toString()}n`;