@samebase/alchemy-convex 0.3.0 → 0.4.1

package/lib/index.d.ts

@@ -1,14 +1,12 @@
-import { Resource } from "alchemy";
-import * as Provider from "alchemy/Provider";
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
-import "effect/process/ChildProcessSpawner";
+import * as Layer from "effect/Layer";
 import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
+import { Resource } from "alchemy";
+import * as Provider from "alchemy/Provider";
+import "effect/process/ChildProcessSpawner";
 import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
-import * as Context from "effect/Context";
-import * as Layer from "effect/Layer";
-import { CommandExecutor, CommandRunProps } from "alchemy/Command";
-import { MemoOptions } from "alchemy/Command/Memo";
 import { components } from "@convex-dev/platform/managementApi";
 //#region src/Credentials.d.ts
 interface ResolvedCredentials {
@@ -17,23 +15,38 @@ interface ResolvedCredentials {
   /** Where the token came from, for error messages only. */
   readonly source: "env" | "explicit" | "convex-cli-login";
 }
-declare const Credentials_base: Context.ServiceClass<Credentials, "@samebase/alchemy-convex/Credentials", Effect.Effect<ResolvedCredentials, never, never>>;
-declare class Credentials extends Credentials_base {}
-/** Environment variable read by {@link fromConfig}. */
-declare const ACCESS_TOKEN_ENV = "CONVEX_ACCESS_TOKEN";
+interface CredentialsService {
+  /** The Management API token. Dies when there is none. */
+  readonly accessToken: Effect.Effect<ResolvedCredentials>;
+  /** True when there is a Management API token. */
+  readonly hasAccessToken: Effect.Effect<boolean>;
+  /** A deploy key or a preview deploy key, or undefined. */
+  readonly deployKey: Effect.Effect<Redacted.Redacted<string> | undefined>;
+}
+declare const Credentials_base: Context.ServiceClass<Credentials, "@samebase/alchemy-convex/Credentials", CredentialsService>;
+export declare class Credentials extends Credentials_base {}
+/** Environment variable for the access token, read by {@link fromConfig}. */
+export declare const ACCESS_TOKEN_ENV = "CONVEX_ACCESS_TOKEN";
+/** Environment variable for the deploy key, read by {@link fromConfig}. The Convex CLI reads the same name. */
+export declare const DEPLOY_KEY_ENV = "CONVEX_DEPLOY_KEY";
 declare const CredentialsError_base: Schema.Class<CredentialsError, Schema.TaggedStruct<"CredentialsError", {
   readonly reason: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-declare class CredentialsError extends CredentialsError_base {}
+export declare class CredentialsError extends CredentialsError_base {}
 /**
- * Default resolution: `CONVEX_ACCESS_TOKEN` from the stack ConfigProvider
- * (process env, `.env`, stack secrets), then the Convex CLI login on this
- * machine. CI sets the variable; a developer who ran `npx convex login` needs
- * nothing.
+ * Default resolution through the stack ConfigProvider (process env, `.env`,
+ * stack secrets): `CONVEX_ACCESS_TOKEN`, then the Convex CLI login on this
+ * machine, for the access token; `CONVEX_DEPLOY_KEY` for the deploy key. A
+ * developer who ran `npx convex login` needs nothing. CI sets only the
+ * deploy key when the stack pushes to deployments that exist, and the access
+ * token when the stack also creates projects or deployments.
  */
-declare const fromConfig: () => Layer.Layer<Credentials>;
-/** Explicit token, for tests or callers that already hold a value. */
-declare const fromToken: (accessToken: Redacted.Redacted<string>) => Layer.Layer<Credentials>;
+export declare const fromConfig: () => Layer.Layer<Credentials>;
+/** Explicit values, for tests or callers that already hold them. */
+export declare const fromValues: (values: {
+  readonly accessToken?: Redacted.Redacted<string>;
+  readonly deployKey?: Redacted.Redacted<string>;
+}) => Layer.Layer<Credentials>;
 //#endregion
 //#region src/ManagementApi.d.ts
 type ManagementClient = ReturnType<typeof createManagementClient>;
@@ -55,7 +68,7 @@ declare const ConvexApiError_base: Schema.Class<ConvexApiError, Schema.TaggedStr
  * `status` (404 means absent for read and delete), so the class is load
  * bearing, not decorative.
  */
-declare class ConvexApiError extends ConvexApiError_base {}
+export declare class ConvexApiError extends ConvexApiError_base {}
 interface ManagementApiService {
   /** Run one management call with the resolved credentials. */
   readonly request: <T>(operation: string, run: (client: ManagementClient) => Promise<FetchResult<T>>) => Effect.Effect<T, ConvexApiError>;
@@ -73,154 +86,63 @@ interface ManagementApiService {
    * that key would revoke the credential.
    */
   readonly isCredentialToken: (secret: string) => Effect.Effect<boolean>;
+  /**
+   * The same calls with another bearer token, such as a preview deploy key,
+   * which the Management API takes for the preview deployments of its project.
+   */
+  readonly withToken: (token: Redacted.Redacted<string>) => ManagementApiService;
 }
 declare const ManagementApi_base: Context.ServiceClass<ManagementApi, "@samebase/alchemy-convex/ManagementApi", ManagementApiService>;
-declare class ManagementApi extends ManagementApi_base {}
+export declare class ManagementApi extends ManagementApi_base {}
 //#endregion
 //#region src/Providers.d.ts
 declare const Providers_base: Provider.ProviderCollection<Providers, "Convex">;
-declare class Providers extends Providers_base {}
+export declare class Providers extends Providers_base {}
 /**
- * All Convex resource providers. Pass a credentials layer to override the
- * default lookup (`CONVEX_ACCESS_TOKEN`, then the Convex CLI login).
+ * The Convex resource providers. Pass a credentials layer to override the
+ * default lookup (`CONVEX_ACCESS_TOKEN`, then the Convex CLI login, and
+ * `CONVEX_DEPLOY_KEY`).
  */
-declare const providers: (credentials?: Layer.Layer<Credentials>) => Layer.Layer<Providers, never, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | import("effect/Path").Path>;
-//#endregion
-//#region src/Deployment.d.ts
-type DeploymentProps = {
-  /** Numeric project id, such as `project.projectId`. Cannot change. */
-  readonly projectId: number;
-  /** The project's default production deployment. Cannot change. */
-  readonly type: "prod";
-} | {
-  /** Numeric project id, such as `project.projectId`. Cannot change. */
-  readonly projectId: number;
-  /** A dev deployment or a preview deployment that this resource creates. Cannot change. */
-  readonly type: "dev" | "preview";
-  /**
-   * The dev reference, such as `staging`, or the preview name, such as a
-   * pull request or stage name. Unique in the project. Cannot change.
-   */
-  readonly name: string;
-};
-interface DeploymentAttributes {
-  readonly projectId: number;
-  readonly type: DeploymentProps["type"];
-  /** Deployment name, such as `happy-animal-123`. */
-  readonly name: string;
-  /** The reference that Convex lists, such as `production`, `staging`, or `preview/pr-42`. */
-  readonly reference: string;
-  /** The preview name of a preview deployment. Undefined for prod and dev. */
-  readonly previewName: string | undefined;
-  /** Client URL, such as `https://happy-animal-123.convex.cloud`. */
-  readonly url: string;
-  /** HTTP actions URL, such as `https://happy-animal-123.convex.site`. */
-  readonly siteUrl: string;
-}
-type Deployment = Resource<"Convex.Deployment", DeploymentProps, DeploymentAttributes, never, Providers>;
-declare const Deployment: import("alchemy").ResourceClass<Deployment>;
-declare const DeploymentIdentityChange_base: Schema.Class<DeploymentIdentityChange, Schema.TaggedStruct<"DeploymentIdentityChange", {
-  /** Name of the deployment in state, such as `happy-animal-123`. */
-  readonly deployment: Schema.String;
-  readonly field: Schema.Literals<readonly ["projectId", "type", "name"]>;
-  readonly current: Schema.String;
-  readonly requested: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/** The props name another deployment than the one in state. */
-declare class DeploymentIdentityChange extends DeploymentIdentityChange_base {
-  get message(): string;
-}
-declare const ProductionDeploymentNotFound_base: Schema.Class<ProductionDeploymentNotFound, Schema.TaggedStruct<"ProductionDeploymentNotFound", {
-  readonly projectId: Schema.Number;
-}>, import("effect/Cause").YieldableError>;
-/** The project has no default production deployment for a `prod` resource to take over. */
-declare class ProductionDeploymentNotFound extends ProductionDeploymentNotFound_base {
-  get message(): string;
-}
-declare const AmbiguousDeployment_base: Schema.Class<AmbiguousDeployment, Schema.TaggedStruct<"AmbiguousDeployment", {
-  readonly projectId: Schema.Number;
-  readonly type: Schema.Literals<readonly ["dev", "preview"]>;
-  readonly name: Schema.String;
-  readonly deployments: Schema.$Array<Schema.String>;
-}>, import("effect/Cause").YieldableError>;
-/** More than one deployment of the project has the name, so the lookup cannot choose one. */
-declare class AmbiguousDeployment extends AmbiguousDeployment_base {
-  get message(): string;
-}
+export declare const providers: (credentials?: Layer.Layer<Credentials>) => Layer.Layer<Providers, never, import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("effect/process/ChildProcessSpawner").ChildProcessSpawner>;
 //#endregion
-//#region src/Code.d.ts
-/** The attributes of a Convex.Deployment that a push needs. Pass the resource itself. */
-type CodeDeployment = Pick<DeploymentAttributes, "name" | "type" | "url" | "previewName">;
-interface CodeProps {
-  /**
-   * The deployment that receives the push: a Convex.Deployment resource, or a
-   * deployment name such as `happy-animal-123`. A preview deploy key needs the
-   * resource. For `env` on a deployment outside US East, pass the resource.
-   */
-  readonly deployment: string | CodeDeployment;
+//#region src/Push.d.ts
+/** A value of the `env` prop: a string, or a secret such as `Config.Redacted("AUTH_SECRET")`. */
+type EnvValue = string | Redacted.Redacted<string>;
+/**
+ * The `source` prop: the Convex functions directory, such as `./convex`, or
+ * that directory with a push command and more files for the content identity.
+ */
+type Source = string | {
+  /** The Convex functions directory, such as `./convex`. */
+  readonly path: string;
   /**
-   * A deploy key of `deployment` (Convex.DeployKey), or, for a preview
-   * deployment, a preview deploy key of its project (Convex.PreviewDeployKey).
+   * Replaces `convex deploy`: a program and its arguments, run in the app
+   * directory with CONVEX_DEPLOY_KEY in its environment, such as
+   * `["pnpm", "exec", "convex-hosting", "deploy", "--build", "pnpm run build", "--dist", "dist"]`.
+   * It must push with `convex deploy`, such as through `--cmd`, so that
+   * its output has the CLI's "Deployed Convex functions to" line.
    */
-  readonly deployKey: Redacted.Redacted<string>;
-  /** The Convex app directory: the one with `convex/` and the `convex` package installed. */
-  readonly cwd: string;
+  readonly command?: readonly [string, ...string[]];
   /**
-   * The program and first arguments that run the Convex CLI, such as
-   * `["pnpm", "exec", "convex"]`. Code adds `deploy` and its flags. By
-   * default, the `convex` package that `cwd` resolves, run with this Node.js.
+   * The files of the content identity, as globs relative to the app
+   * directory, next to `path`, package.json, convex.json, and the
+   * lockfile, such as the build inputs `["src/**", "vite.config.ts"]`.
+   * By default, every file of the app that git does not ignore.
    */
-  readonly command?: readonly [string, ...string[]];
-  /** Environment variables to set on the deployment before the push. Needs a deploy key of the deployment. */
-  readonly env?: Readonly<Record<string, string | Redacted.Redacted<string>>>;
-  /** `convex deploy --typecheck`. The CLI default is `try`. */
-  readonly typecheck?: "enable" | "try" | "disable";
-  /** `convex deploy --codegen`. The CLI default is `enable`. */
-  readonly codegen?: "enable" | "disable";
-}
-interface CodeAttributes {
-  /** The deployment that received the push, such as `happy-animal-123`. */
-  readonly deploymentName: string;
-  /** Client URL, such as `https://happy-animal-123.convex.cloud`. */
-  readonly url: string;
-  /** HTTP actions URL, such as `https://happy-animal-123.convex.site`. */
-  readonly siteUrl: string;
-  /** When the push finished, in milliseconds since the Unix epoch. */
-  readonly deployedAt: number;
-  /** The names of the `env` variables that this resource set on the deployment, sorted. */
-  readonly envNames: readonly string[];
-}
-type Code = Resource<"Convex.Code", CodeProps, CodeAttributes, never, Providers>;
-declare const Code: import("alchemy").ResourceClass<Code>;
-/** Reads the deployment URL from `convex deploy` output. ANSI escape codes are removed first. */
-declare const parseDeployOutput: (text: string) => {
-  url: string;
-  deploymentName: string;
-} | undefined;
-declare const DeployKeyMismatch_base: Schema.Class<DeployKeyMismatch, Schema.TaggedStruct<"DeployKeyMismatch", {
-  /** The deployment that should receive the push. */
-  readonly deployment: Schema.String;
-  /** What the key targets. */
-  readonly key: Schema.Literals<readonly ["deployment", "preview", "project", "unknown"]>;
-  /** For a deployment key: the deployment in the key prefix. Never the secret. */
-  readonly keyDeployment: Schema.UndefinedOr<Schema.String>;
-}>, import("effect/Cause").YieldableError>;
-/** The deploy key does not fit the deployment. Checked before the push. */
-declare class DeployKeyMismatch extends DeployKeyMismatch_base {
-  get message(): string;
-}
-declare const EnvironmentNeedsDeployKey_base: Schema.Class<EnvironmentNeedsDeployKey, Schema.TaggedStruct<"EnvironmentNeedsDeployKey", {
-  readonly deployment: Schema.String;
+  readonly include?: readonly string[];
+};
+declare const ConvexCliNotFound_base: Schema.Class<ConvexCliNotFound, Schema.TaggedStruct<"ConvexCliNotFound", {
+  readonly cwd: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-/** `env` needs the deployment API, which takes only a deploy key of the deployment. */
-declare class EnvironmentNeedsDeployKey extends EnvironmentNeedsDeployKey_base {
+/** No `convex` package resolves from the app directory. */
+export declare class ConvexCliNotFound extends ConvexCliNotFound_base {
   get message(): string;
 }
-declare const ConvexCliNotFound_base: Schema.Class<ConvexCliNotFound, Schema.TaggedStruct<"ConvexCliNotFound", {
-  readonly cwd: Schema.String;
+declare const ConvexAppNotFound_base: Schema.Class<ConvexAppNotFound, Schema.TaggedStruct<"ConvexAppNotFound", {
+  readonly source: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-/** No `convex` package resolves from `cwd`. */
-declare class ConvexCliNotFound extends ConvexCliNotFound_base {
+/** No directory at or above the parent of `source` has a package.json. */
+export declare class ConvexAppNotFound extends ConvexAppNotFound_base {
   get message(): string;
 }
 declare const CodePushFailed_base: Schema.Class<CodePushFailed, Schema.TaggedStruct<"CodePushFailed", {
@@ -230,225 +152,122 @@ declare const CodePushFailed_base: Schema.Class<CodePushFailed, Schema.TaggedStr
   readonly outputTail: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** The Convex CLI failed, or exited 0 without the deployment URL. The output tail never contains the key. */
-declare class CodePushFailed extends CodePushFailed_base {
+export declare class CodePushFailed extends CodePushFailed_base {
   get message(): string;
 }
 declare const PushTargetMismatch_base: Schema.Class<PushTargetMismatch, Schema.TaggedStruct<"PushTargetMismatch", {
   readonly expected: Schema.String;
   readonly actual: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-/** The CLI pushed to another deployment than the one in the props. Checked after the push. */
-declare class PushTargetMismatch extends PushTargetMismatch_base {
+/** The CLI pushed to another deployment than the one of the resource. Checked after the push. */
+export declare class PushTargetMismatch extends PushTargetMismatch_base {
   get message(): string;
 }
-//#endregion
-//#region src/DefaultEnvironmentVariable.d.ts
-/** Deployment types a default can target, from the generated schema. */
-type DeploymentType = components["schemas"]["DeploymentType"];
-interface DefaultEnvironmentVariableProps {
-  /** Numeric project id, such as `project.projectId`. */
-  readonly projectId: number;
-  readonly name: string;
-  readonly value: string | Redacted.Redacted<string>;
-  /** Deployments of this type that Convex creates from now on get the variable. */
-  readonly deploymentType: DeploymentType;
-}
-interface DefaultEnvironmentVariableAttributes {
-  readonly projectId: number;
-  readonly name: string;
-  readonly deploymentType: DeploymentType;
-}
-type DefaultEnvironmentVariable = Resource<"Convex.DefaultEnvironmentVariable", DefaultEnvironmentVariableProps, DefaultEnvironmentVariableAttributes, never, Providers>;
-declare const DefaultEnvironmentVariable: import("alchemy").ResourceClass<DefaultEnvironmentVariable>;
-//#endregion
-//#region src/Deploy.d.ts
-interface DeployProps extends Pick<CommandRunProps, "cwd" | "env" | "timeout"> {
-  /**
-   * Deploy key that selects the target deployment: a production, development,
-   * project, or preview deploy key. The CLI receives it as `CONVEX_DEPLOY_KEY`,
-   * and Alchemy removes its value from the logged output.
-   */
-  readonly deployKey: Redacted.Redacted<string>;
-  /**
-   * Preview deployment name for a preview deploy key. The CLI reuses an
-   * existing preview deployment with this name.
-   */
-  readonly previewName?: string;
-  /**
-   * Like {@link previewName}, but the CLI deletes and recreates an existing
-   * preview deployment with this name, so every run gets a new URL.
-   */
-  readonly previewCreate?: string;
-  /**
-   * Function to run after the push, such as `init:seed`. The CLI runs it only
-   * when the push created a new preview deployment.
-   */
-  readonly previewRun?: string;
-  /**
-   * More `convex deploy` flags, added after the preview flags. Alchemy splits
-   * the command on whitespace, so an argument cannot contain whitespace: use
-   * `--typecheck=disable`, not `--typecheck disable` as one argument.
-   */
-  readonly extraArgs?: readonly string[];
-  /**
-   * Files hashed to skip an unchanged push. By default every non-gitignored
-   * file under `cwd` and the nearest lockfile. Use
-   * `{ include: ["convex/**"], lockfile: true }` to ignore frontend changes,
-   * or `false` to push on every deploy. A preview deploy (`previewName` or
-   * `previewCreate`) pushes on every deploy: Convex can delete an expired
-   * preview deployment, and the hash cannot show that.
-   * @default true
-   */
-  readonly memo?: MemoOptions | boolean;
-}
-interface DeployAttributes {
-  /** Client URL of the deployment that received the push, such as `https://happy-otter-123.convex.cloud`. */
-  readonly url: string;
-  /** First label of the URL host, such as `happy-otter-123`. */
-  readonly deploymentName: string;
-  /** Hash of the memoized input files after the push, or `undefined` when `memo` is `false`. */
-  readonly hash: string | undefined;
-}
-type Deploy = Resource<"Convex.Deploy", DeployProps, DeployAttributes, never, Providers>;
-/**
- * @deprecated Since 0.3.0. Use Convex.Code with a Convex.Deployment: it
- * runs the installed Convex CLI, keeps the deploy key out of the process
- * environment, checks that the key fits the deployment, and outputs the site
- * URL. Removing a Deploy resource changes nothing in Convex.
- */
-declare const Deploy: import("alchemy").ResourceClass<Deploy>;
-/** The `convex deploy` argv, starting with `npx`. */
-declare const deployArgs: (props: Pick<DeployProps, "previewName" | "previewCreate" | "previewRun" | "extraArgs">) => readonly string[];
-declare const DeployArgumentError_base: Schema.Class<DeployArgumentError, Schema.TaggedStruct<"DeployArgumentError", {
-  readonly argument: Schema.String;
+declare const VariablesOwnedBySomeoneElse_base: Schema.Class<VariablesOwnedBySomeoneElse, Schema.TaggedStruct<"VariablesOwnedBySomeoneElse", {
+  readonly deployment: Schema.String;
+  readonly names: Schema.$Array<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
-/** A `convex deploy` argument contains whitespace, which Alchemy's command runner splits on. */
-declare class DeployArgumentError extends DeployArgumentError_base {
+/** Variables in `env` exist on the deployment with other values, and adoption is off. */
+export declare class VariablesOwnedBySomeoneElse extends VariablesOwnedBySomeoneElse_base {
   get message(): string;
 }
-declare const DeployOutputError_base: Schema.Class<DeployOutputError, Schema.TaggedStruct<"DeployOutputError", {
-  readonly outputTail: Schema.String;
+declare const EnvironmentNeedsDeployKey_base: Schema.Class<EnvironmentNeedsDeployKey, Schema.TaggedStruct<"EnvironmentNeedsDeployKey", {
+  readonly deployment: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-/** `npx convex deploy` exited 0 but did not print the deployment URL. */
-declare class DeployOutputError extends DeployOutputError_base {
+/** A preview deploy key cannot set variables: the deployment API takes only a deploy key of the deployment. */
+export declare class EnvironmentNeedsDeployKey extends EnvironmentNeedsDeployKey_base {
   get message(): string;
 }
+/** Reads the deployment URL from `convex deploy` output. ANSI escape codes are removed first. */
+export declare const parseDeployOutput: (text: string) => {
+  url: string;
+  deploymentName: string;
+} | undefined;
 //#endregion
-//#region src/DeployKey.d.ts
-/** Actions a deploy key can be limited to, from the generated schema. */
-type DeployKeyAction = NonNullable<components["schemas"]["PlatformCreateDeployKeyArgs"]["allowedActions"]>[number];
-declare const DeployKeyRecoveryRequired_base: Schema.Class<DeployKeyRecoveryRequired, Schema.TaggedStruct<"DeployKeyRecoveryRequired", {
-  /** Where the keys live, such as `deployment happy-otter-123` or `project 3145389`. */
-  readonly target: Schema.String;
-  /** The requested name. */
-  readonly name: Schema.String;
-  /** The listed keys with the requested name. */
-  readonly keys: Schema.$Array<Schema.Struct<{
-    readonly id: Schema.Number;
-    readonly name: Schema.String;
-  }>>;
-  /** True when this run created a key before the listing check failed. */
-  readonly afterCreate: Schema.Boolean;
-}>, import("effect/Cause").YieldableError>;
-/**
- * A key cannot be tied to one resource: before the create, listed keys
- * already have the requested name, or after the create, not exactly one has it.
- */
-declare class DeployKeyRecoveryRequired extends DeployKeyRecoveryRequired_base {
-  get message(): string;
-}
-declare const DeployKeyIsCredential_base: Schema.Class<DeployKeyIsCredential, Schema.TaggedStruct<"DeployKeyIsCredential", {
-  readonly target: Schema.String;
-  readonly name: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Convex returned the Management API credential itself as the new key. This
- * happens with an OAuth token: Convex creates no key. A delete of the
- * returned secret would revoke the credential, so the resource does not keep it.
- */
-declare class DeployKeyIsCredential extends DeployKeyIsCredential_base {
-  get message(): string;
+//#region src/Deployment.d.ts
+interface DeploymentInputs {
+  /** The project: a Convex.Project resource, or `{ projectId }`. Cannot change. */
+  readonly project: {
+    readonly projectId: number;
+  };
+  /**
+   * The Convex functions directory, such as `./convex`, or that directory
+   * with a push command and more hashed files. The push runs in the nearest
+   * directory above it with a package.json. Without `source`, the resource
+   * pushes nothing.
+   */
+  readonly source?: Source;
+  /** Environment variables to set on the deployment before the push. */
+  readonly env?: Readonly<Record<string, EnvValue>>;
 }
-interface DeployKeyProps {
-  /** Deployment name, such as `project.prodDeploymentName`. */
-  readonly deployment: string;
+type DeploymentProps = (DeploymentInputs & {
+  /** The project's default production deployment. Cannot change. */
+  readonly type: "prod";
+}) | (DeploymentInputs & {
+  /** A dev deployment or a preview deployment that this resource creates. Cannot change. */
+  readonly type: "dev" | "preview";
   /**
-   * Key name. The provider requests this name, a dash, and a hash of the
-   * resource identity, so two resources with one `name` get different keys.
+   * The dev reference, such as `staging`, or the preview name, such as
+   * the stage name. Unique in the project. Cannot change.
    */
   readonly name: string;
-  /** Limits the key to these actions. Convex grants every deployment action when omitted. */
-  readonly allowedActions?: readonly DeployKeyAction[];
-}
-interface DeployKeyAttributes {
-  /** The name Convex lists the key under, such as "ci-3f2a1b0c9d8e". */
-  readonly uniqueName: string;
-  /** Numeric id of the key in the listing. Undefined in state written by 0.1.x. */
-  readonly keyId: number | undefined;
-  readonly deployment: string;
-  /** The secret, such as `prod:<deployment>|<token>`. Convex returns it only at creation. */
-  readonly deployKey: Redacted.Redacted<string>;
-}
-type DeployKey = Resource<"Convex.DeployKey", DeployKeyProps, DeployKeyAttributes, never, Providers>;
-declare const DeployKey: import("alchemy").ResourceClass<DeployKey>;
-//#endregion
-//#region src/EnvironmentVariable.d.ts
-interface EnvironmentVariableProps {
-  /** Deployment name, or its URL for deployments outside US East. */
-  readonly deployment: string;
-  /** Deploy key for `deployment`, such as `deployKey.deployKey`. */
-  readonly deployKey: Redacted.Redacted<string>;
+});
+/** The deployment itself, without the state of the push. */
+interface DeploymentTarget {
+  readonly projectId: number;
+  readonly type: DeploymentProps["type"];
+  /** Deployment name, such as `happy-animal-123`. */
   readonly name: string;
-  readonly value: string | Redacted.Redacted<string>;
+  /** The reference that Convex lists, such as `production`, `staging`, or `preview/pr-42`. */
+  readonly reference: string;
+  /** The preview name of a preview deployment. Undefined for prod and dev. */
+  readonly previewName: string | undefined;
+  /** Client URL, such as `https://happy-animal-123.convex.cloud`. */
+  readonly url: string;
+  /** HTTP actions URL, such as `https://happy-animal-123.convex.site`. */
+  readonly siteUrl: string;
 }
-interface EnvironmentVariableAttributes {
-  readonly deployment: string;
-  readonly name: string;
-  /** Deploy key for `deployment`, for read and delete. Undefined in state from 0.1.x. */
-  readonly deployKey: Redacted.Redacted<string> | undefined;
+interface DeploymentAttributes extends DeploymentTarget {
+  /** Content identity of the last push and `env`. Undefined when the resource pushed nothing. */
+  readonly hash: string | undefined;
+  /** The names of the `env` variables that this resource set on the deployment, sorted. */
+  readonly envNames: readonly string[];
 }
-type EnvironmentVariable = Resource<"Convex.EnvironmentVariable", EnvironmentVariableProps, EnvironmentVariableAttributes, never, Providers>;
-declare const EnvironmentVariable: import("alchemy").ResourceClass<EnvironmentVariable>;
-declare const VariableIdentityChange_base: Schema.Class<VariableIdentityChange, Schema.TaggedStruct<"VariableIdentityChange", {
-  readonly resourceType: Schema.String;
-  readonly field: Schema.Literals<readonly ["name", "deployment", "projectId", "deploymentType"]>;
+export type Deployment = Resource<"Convex.Deployment", DeploymentProps, DeploymentAttributes, never, Providers>;
+export declare const Deployment: import("alchemy").ResourceClass<Deployment>;
+declare const DeploymentIdentityChange_base: Schema.Class<DeploymentIdentityChange, Schema.TaggedStruct<"DeploymentIdentityChange", {
+  /** Name of the deployment in state, such as `happy-animal-123`. */
+  readonly deployment: Schema.String;
+  readonly field: Schema.Literals<readonly ["projectId", "type", "name"]>;
   readonly current: Schema.String;
   readonly requested: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-/**
- * The props name another variable than the one in state. Used by
- * Convex.EnvironmentVariable and Convex.DefaultEnvironmentVariable.
- */
-declare class VariableIdentityChange extends VariableIdentityChange_base {
+/** The props name another deployment than the one in state. */
+export declare class DeploymentIdentityChange extends DeploymentIdentityChange_base {
   get message(): string;
 }
-//#endregion
-//#region src/PreviewDeployKey.d.ts
-interface PreviewDeployKeyProps {
-  /** Numeric project id, such as `project.projectId`. */
-  readonly projectId: number;
-  /**
-   * Key name. The provider requests this name, a dash, and a hash of the
-   * resource identity, so two resources with one `name` get different keys.
-   */
-  readonly name: string;
+declare const ProductionDeploymentNotFound_base: Schema.Class<ProductionDeploymentNotFound, Schema.TaggedStruct<"ProductionDeploymentNotFound", {
+  readonly projectId: Schema.Number;
+}>, import("effect/Cause").YieldableError>;
+/** The project has no default production deployment for a `prod` resource to take over. */
+export declare class ProductionDeploymentNotFound extends ProductionDeploymentNotFound_base {
+  get message(): string;
 }
-interface PreviewDeployKeyAttributes {
-  /** The name Convex lists the key under, such as "ci-3f2a1b0c9d8e". */
-  readonly uniqueName: string;
-  /** Numeric id of the key in the listing. Undefined in state written by 0.1.x. */
-  readonly keyId: number | undefined;
-  readonly projectId: number;
-  /** The secret, such as `preview:<team>:<project>|<token>`. Convex returns it only at creation. */
-  readonly previewDeployKey: Redacted.Redacted<string>;
+declare const AmbiguousDeployment_base: Schema.Class<AmbiguousDeployment, Schema.TaggedStruct<"AmbiguousDeployment", {
+  readonly projectId: Schema.Number;
+  readonly type: Schema.Literals<readonly ["dev", "preview"]>;
+  readonly name: Schema.String;
+  readonly deployments: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** More than one deployment of the project has the name, so the lookup cannot choose one. */
+export declare class AmbiguousDeployment extends AmbiguousDeployment_base {
+  get message(): string;
 }
-type PreviewDeployKey = Resource<"Convex.PreviewDeployKey", PreviewDeployKeyProps, PreviewDeployKeyAttributes, never, Providers>;
-declare const PreviewDeployKey: import("alchemy").ResourceClass<PreviewDeployKey>;
 //#endregion
 //#region src/Project.d.ts
 /** Region names the Management API accepts, from the generated schema. */
 type DeploymentRegion = components["schemas"]["RegionName"];
-interface ProjectProps {
+type ProjectProps = {
   /** Team slug or numeric team id. A slug costs one extra lookup per run. Cannot change. */
   readonly team: string | number;
   /** Display name. Convex derives the slug from it at creation. A change renames the project. */
@@ -457,7 +276,12 @@ interface ProjectProps {
   readonly deploymentRegion?: DeploymentRegion;
   /** Deployment created with the project. Defaults to `prod`. Cannot change. */
   readonly deploymentType?: "prod" | "dev";
-}
+} | {
+  /** Team slug or numeric team id. Cannot change. */
+  readonly team: string | number;
+  /** Slug of an existing project, such as `score-four`. The resource never creates a project. Cannot change. */
+  readonly slug: string;
+};
 interface ProjectAttributes {
   readonly projectId: number;
   readonly slug: string;
@@ -466,15 +290,15 @@ interface ProjectAttributes {
   readonly prodDeploymentName: string | undefined;
   readonly prodDeploymentUrl: string | undefined;
 }
-type Project = Resource<"Convex.Project", ProjectProps, ProjectAttributes, never, Providers>;
-declare const Project: import("alchemy").ResourceClass<Project>;
+export type Project = Resource<"Convex.Project", ProjectProps, ProjectAttributes, never, Providers>;
+export declare const Project: import("alchemy").ResourceClass<Project>;
 declare const ProjectTeamChange_base: Schema.Class<ProjectTeamChange, Schema.TaggedStruct<"ProjectTeamChange", {
   readonly projectId: Schema.Number;
   readonly teamId: Schema.Number;
   readonly requestedTeamId: Schema.Number;
 }>, import("effect/Cause").YieldableError>;
 /** The props change the team of an existing project. Convex cannot move a project. */
-declare class ProjectTeamChange extends ProjectTeamChange_base {
+export declare class ProjectTeamChange extends ProjectTeamChange_base {
   get message(): string;
 }
 declare const ProjectDeploymentChange_base: Schema.Class<ProjectDeploymentChange, Schema.TaggedStruct<"ProjectDeploymentChange", {
@@ -487,7 +311,7 @@ declare const ProjectDeploymentChange_base: Schema.Class<ProjectDeploymentChange
  * The props change `deploymentType` or `deploymentRegion` of an existing
  * project. Convex uses them only when it creates the project.
  */
-declare class ProjectDeploymentChange extends ProjectDeploymentChange_base {
+export declare class ProjectDeploymentChange extends ProjectDeploymentChange_base {
   get message(): string;
 }
 declare const AmbiguousProject_base: Schema.Class<AmbiguousProject, Schema.TaggedStruct<"AmbiguousProject", {
@@ -496,16 +320,24 @@ declare const AmbiguousProject_base: Schema.Class<AmbiguousProject, Schema.Tagge
   readonly projectIds: Schema.$Array<Schema.Number>;
 }>, import("effect/Cause").YieldableError>;
 /** More than one project in the team has the name, so the lookup cannot choose one. */
-declare class AmbiguousProject extends AmbiguousProject_base {
+export declare class AmbiguousProject extends AmbiguousProject_base {
   get message(): string;
 }
 declare const CreatedProjectNotFound_base: Schema.Class<CreatedProjectNotFound, Schema.TaggedStruct<"CreatedProjectNotFound", {
   readonly projectId: Schema.Number;
 }>, import("effect/Cause").YieldableError>;
 /** Convex answered a create call but then did not return the project. */
-declare class CreatedProjectNotFound extends CreatedProjectNotFound_base {
+export declare class CreatedProjectNotFound extends CreatedProjectNotFound_base {
+  get message(): string;
+}
+declare const ProjectNotFound_base: Schema.Class<ProjectNotFound, Schema.TaggedStruct<"ProjectNotFound", {
+  readonly team: Schema.String;
+  readonly slug: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** No project in the team has the slug. A `slug` resource never creates one. */
+export declare class ProjectNotFound extends ProjectNotFound_base {
   get message(): string;
 }
 //#endregion
-export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, Code, type CodeAttributes, type CodeDeployment, type CodeProps, CodePushFailed, ConvexApiError, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DefaultEnvironmentVariable, type DefaultEnvironmentVariableAttributes, type DefaultEnvironmentVariableProps, Deploy, DeployArgumentError, type DeployAttributes, DeployKey, type DeployKeyAction, type DeployKeyAttributes, DeployKeyIsCredential, DeployKeyMismatch, type DeployKeyProps, DeployKeyRecoveryRequired, DeployOutputError, type DeployProps, Deployment, type DeploymentAttributes, DeploymentIdentityChange, type DeploymentProps, type DeploymentRegion, type DeploymentType, EnvironmentNeedsDeployKey, EnvironmentVariable, type EnvironmentVariableAttributes, type EnvironmentVariableProps, ManagementApi, PreviewDeployKey, type PreviewDeployKeyAttributes, type PreviewDeployKeyProps, ProductionDeploymentNotFound, Project, type ProjectAttributes, ProjectDeploymentChange, type ProjectProps, ProjectTeamChange, Providers, PushTargetMismatch, VariableIdentityChange, deployArgs, fromConfig, fromToken, parseDeployOutput, providers };
+export type { DeploymentAttributes, DeploymentProps, DeploymentRegion, EnvValue, ProjectAttributes, ProjectProps, Source };
 //# sourceMappingURL=index.d.ts.map