@samebase/alchemy-convex 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samebase/alchemy-convex",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "The Convex plane for Alchemy v2: projects, deployments, environment variables, and the push of the functions",
   "keywords": [
     "alchemy",
@@ -31,8 +31,7 @@
     ".": {
       "types": "./lib/index.d.ts",
       "import": "./lib/index.js"
-    },
-    "./convex.config": "./src/component/convex.config.ts"
+    }
   },
   "publishConfig": {
     "access": "public"

package/src/Deployment.ts

@@ -69,6 +69,7 @@ import {
   type EnvValue,
   keyTargetOf,
   push,
+  PUSH_KEY_ACTIONS,
   pushHash,
   type Source,
   withPushKey,
@@ -681,8 +682,14 @@ export const DeploymentProvider = () =>
               ? push(spawner, access.key, { ...options, previewName: undefined })
               : access.kind === "previewKey"
                 ? push(spawner, access.key, { ...options, previewName: target.previewName })
-                : withPushKey(access.api, target.name, news.source, (key) =>
-                    push(spawner, key, { ...options, previewName: undefined }),
+                : withPushKey(
+                    access.api,
+                    target.name,
+                    // A push command gets every action; `convex deploy` only its own.
+                    typeof news.source === "object" && news.source.command !== undefined
+                      ? undefined
+                      : PUSH_KEY_ACTIONS,
+                    (key) => push(spawner, key, { ...options, previewName: undefined }),
                   );
           yield* pushed.pipe(
             // A deployment that this reconcile created and could not push to

package/src/ManagementApi.ts

@@ -69,8 +69,16 @@ export interface ManagementApiService {
     deployKey: Redacted.Redacted<string>,
     run: (client: DeploymentClient) => Promise<FetchResult<T>>,
   ) => Effect.Effect<T, ConvexApiError>;
-  /** Team id for a slug or numeric id. */
-  readonly resolveTeamId: (team: string | number) => Effect.Effect<number, ConvexApiError>;
+  /**
+   * Team id for a numeric id, a slug, or nothing. A team access token names
+   * its team (`GET /token_details`); a slug is then checked against the
+   * `teamSlug` of the team's projects, so a token of another team fails. The
+   * Convex CLI login and a personal token answer 403 there, so a slug goes to
+   * the dashboard's team list, and nothing is an error.
+   */
+  readonly resolveTeamId: (
+    team: string | number | undefined,
+  ) => Effect.Effect<number, ConvexApiError>;
   /**
    * True when a deploy key that Convex returned carries the token of the
    * Management API credential itself. With an OAuth token, create_deploy_key
@@ -179,6 +187,17 @@ export const absentAsUndefined = <A, R>(
 const TeamRow = Schema.Struct({ id: Schema.Number, slug: Schema.String });
 const TeamRows = Schema.Array(TeamRow);
 
+/** The first page of GET /teams/{team_id}/projects: every row carries the slug of the team. */
+const ProjectSlugRows = Schema.Struct({
+  items: Schema.Array(Schema.Struct({ teamSlug: Schema.String })),
+});
+
+/** GET /token_details: the team of a team token, or the project of a project token. */
+const TokenDetails = Schema.Union([
+  Schema.Struct({ type: Schema.Literal("teamToken"), teamId: Schema.Number }),
+  Schema.Struct({ type: Schema.Literal("projectToken"), projectId: Schema.Number }),
+]);
+
 /** The service for one way to get the bearer token. */
 const makeService = (credentials: Effect.Effect<ResolvedCredentials>): ManagementApiService => {
   const client = Effect.cached(
@@ -203,13 +222,76 @@ const makeService = (credentials: Effect.Effect<ResolvedCredentials>): Managemen
       run(createDeploymentClient(deploymentUrlOrName, Redacted.value(deployKey))),
     );
 
+  // Measured: a team access token answers `GET /token_details` with its
+  // team id and gets HTTP 403 from the dashboard's team list; the Convex CLI
+  // login answers the team list and gets HTTP 403 `NotOAuthTeamToken` from
+  // token_details. Read once for each service.
+  // `Effect.cached` only allocates the cache, so runSync makes one for this service.
+  const tokenDetails = Effect.runSync(
+    Effect.cached(
+      request("get token details", (c) => c.GET("/token_details")).pipe(
+        Effect.map((body) => Schema.decodeUnknownSync(TokenDetails)(body)),
+        Effect.catchIf(
+          (error) => error.status === 403,
+          () => Effect.succeed(undefined),
+        ),
+      ),
+    ),
+  );
+
+  /** The slug of the team, from the first project of its listing, or undefined for a team without one. Read once. */
+  const teamSlug = (teamId: number) =>
+    request("list projects", (c) =>
+      c.GET("/teams/{team_id}/projects", { params: { path: { team_id: teamId } } }),
+    ).pipe(
+      Effect.map((body) => Schema.decodeUnknownSync(ProjectSlugRows)(body).items[0]?.teamSlug),
+    );
+
   // The Management API addresses teams by numeric id. The only slug lookup
   // it offers is per project, so a slug falls back to the dashboard's team
   // list, which is unofficial. Pass the numeric team id to skip this.
   const resolveTeamId: ManagementApiService["resolveTeamId"] = (team) =>
     Effect.gen(function* () {
       if (typeof team === "number") return team;
-      if (/^\d+$/.test(team)) return Number(team);
+      if (team !== undefined && /^\d+$/.test(team)) return Number(team);
+      const details = yield* tokenDetails;
+      if (details?.type === "teamToken") {
+        if (team === undefined) return details.teamId;
+        // The Management API has no team-by-id call, so the slug of the
+        // team comes from any of its projects. A team without a project
+        // cannot be checked: the numeric id, or no team, is the fix.
+        const slug = yield* teamSlug(details.teamId);
+        if (slug === undefined) {
+          return yield* new ConvexApiError({
+            operation: "resolve team",
+            status: 0,
+            message: `team "${team}" cannot be checked against the access token: team ${details.teamId} has no project yet. Set team to ${details.teamId}, or leave it out.`,
+          });
+        }
+        if (slug !== team) {
+          return yield* new ConvexApiError({
+            operation: "resolve team",
+            status: 403,
+            message: `the access token belongs to team ${details.teamId} ("${slug}"), and team is "${team}". Use a token of "${team}", or set team to ${details.teamId}.`,
+          });
+        }
+        return details.teamId;
+      }
+      if (details?.type === "projectToken") {
+        return yield* new ConvexApiError({
+          operation: "resolve team",
+          status: 403,
+          message: `the access token belongs to project ${details.projectId}, and a project token cannot create projects. Use a team access token.`,
+        });
+      }
+      if (team === undefined) {
+        return yield* new ConvexApiError({
+          operation: "resolve team",
+          status: 0,
+          message:
+            "set team to the slug or the id of the Convex team: this access token does not name a team.",
+        });
+      }
       const resolved = yield* credentials;
       const rows = yield* Effect.tryPromise({
         try: async () => {

package/src/Project.ts

@@ -25,7 +25,12 @@ import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import type { components } from "@convex-dev/platform/managementApi";
 import { shouldAdopt } from "./Adoption.ts";
-import { absentAsUndefined, ConvexApiError, ManagementApi } from "./ManagementApi.ts";
+import {
+  absentAsUndefined,
+  ConvexApiError,
+  ManagementApi,
+  type ManagementApiService,
+} from "./ManagementApi.ts";
 import type { Providers } from "./Providers.ts";
 
 /** Region names the Management API accepts, from the generated schema. */
@@ -159,6 +164,8 @@ const DeploymentRow = Schema.Struct({
   deploymentType: Schema.String,
   isDefault: Schema.Boolean,
   deploymentUrl: Schema.String,
+  /** Absent or null until the first push. */
+  lastDeployTime: Schema.optionalKey(Schema.NullOr(Schema.Number)),
 });
 const DeploymentRows = Schema.Array(DeploymentRow);
 
@@ -202,29 +209,123 @@ const isTeamOf = (details: ProjectDetails, team: string | number) =>
     ? details.teamId === Number(team)
     : details.teamSlug === team;
 
+/** The row of the project's default production deployment, or undefined. */
+export const prodDeploymentOf = (api: ManagementApiService, projectId: number) =>
+  api
+    .request("list deployments", (client) =>
+      client.GET("/projects/{project_id}/list_deployments", {
+        params: { path: { project_id: projectId } },
+      }),
+    )
+    .pipe(
+      Effect.map((rows) =>
+        Schema.decodeUnknownSync(DeploymentRows)(rows).find(
+          (row) => row.deploymentType === "prod" && row.isDefault,
+        ),
+      ),
+    );
+
+/** GET /projects/{id}, or undefined after a 404. */
+export const getProjectById = (api: ManagementApiService, projectId: number) =>
+  absentAsUndefined(
+    api.request("get project", (client) =>
+      client.GET("/projects/{project_id}", { params: { path: { project_id: projectId } } }),
+    ),
+  ).pipe(
+    Effect.map((body) =>
+      body === undefined ? undefined : Schema.decodeUnknownSync(ProjectDetails)(body),
+    ),
+  );
+
+/**
+ * Every project in the team with exactly this name, in the order of the
+ * listing. Reads every page. `q` narrows the listing on the server, and the
+ * exact match here decides. Pattern from Confect
+ * `packages/alchemy/src/ConvexClient.ts` and `Project.ts`
+ * (https://github.com/rjdellecese/confect, ISC license).
+ */
+export const listProjectsByName = (api: ManagementApiService, teamId: number, name: string) =>
+  Effect.gen(function* () {
+    const matches: ProjectDetails[] = [];
+    const seenCursors = new Set<string>();
+    let cursor: string | undefined;
+    while (true) {
+      const body = yield* api.request("list projects", (client) =>
+        client.GET("/teams/{team_id}/projects", {
+          params: {
+            path: { team_id: teamId },
+            query: { q: name, ...(cursor === undefined ? {} : { cursor }) },
+          },
+        }),
+      );
+      const page = Schema.decodeUnknownSync(ProjectPage)(body);
+      matches.push(...page.items.filter((row) => row.name === name));
+      if (!page.pagination.hasMore) break;
+      const next = page.pagination.nextCursor;
+      if (next === undefined || next === null || seenCursors.has(next)) {
+        return yield* new ConvexApiError({
+          operation: "list projects",
+          status: 0,
+          code: "InvalidPagination",
+          message: `The project listing of team ${teamId} reports more pages but gives no new cursor. Convex.Project stops so that it does not miss a project named "${name}".`,
+        });
+      }
+      seenCursors.add(next);
+      cursor = next;
+    }
+    return matches;
+  });
+
+/** The one project in the team with exactly this name, or undefined. More than one is an error. */
+export const findProjectByName = (api: ManagementApiService, teamId: number, name: string) =>
+  listProjectsByName(api, teamId, name).pipe(
+    Effect.flatMap((matches) =>
+      matches.length > 1
+        ? new AmbiguousProject({ teamId, name, projectIds: matches.map((row) => row.id) })
+        : Effect.succeed(matches[0]),
+    ),
+  );
+
+/**
+ * POST /teams/{team_id}/create_project, then GET /projects/{id}. The identity
+ * comes from the create response, never from a name lookup.
+ */
+export const createProject = (
+  api: ManagementApiService,
+  teamId: number,
+  props: {
+    readonly name: string;
+    readonly deploymentType: "prod" | "dev";
+    readonly deploymentRegion: DeploymentRegion | undefined;
+  },
+) =>
+  Effect.gen(function* () {
+    const created = yield* api.request("create project", (client) =>
+      client.POST("/teams/{team_id}/create_project", {
+        params: { path: { team_id: teamId } },
+        body: {
+          projectName: props.name,
+          deploymentType: props.deploymentType,
+          ...(props.deploymentRegion === undefined
+            ? {}
+            : { deploymentRegion: props.deploymentRegion }),
+        },
+      }),
+    );
+    const { projectId } = Schema.decodeUnknownSync(CreatedProject)(created);
+    const details = yield* getProjectById(api, projectId);
+    if (details === undefined) return yield* new CreatedProjectNotFound({ projectId });
+    return details;
+  });
+
 export const ProjectProvider = () =>
   Provider.effect(
     Project,
     Effect.gen(function* () {
       const api = yield* ManagementApi;
 
-      const prodDeployment = (projectId: number) =>
-        api
-          .request("list deployments", (client) =>
-            client.GET("/projects/{project_id}/list_deployments", {
-              params: { path: { project_id: projectId } },
-            }),
-          )
-          .pipe(
-            Effect.map((rows) =>
-              Schema.decodeUnknownSync(DeploymentRows)(rows).find(
-                (row) => row.deploymentType === "prod" && row.isDefault,
-              ),
-            ),
-          );
-
       const attributesOf = (details: ProjectDetails) =>
-        prodDeployment(details.id).pipe(
+        prodDeploymentOf(api, details.id).pipe(
           Effect.map((prod): ProjectAttributes => ({
             projectId: details.id,
             slug: details.slug,
@@ -235,16 +336,7 @@ export const ProjectProvider = () =>
           })),
         );
 
-      const getById = (projectId: number) =>
-        absentAsUndefined(
-          api.request("get project", (client) =>
-            client.GET("/projects/{project_id}", { params: { path: { project_id: projectId } } }),
-          ),
-        ).pipe(
-          Effect.map((body) =>
-            body === undefined ? undefined : Schema.decodeUnknownSync(ProjectDetails)(body),
-          ),
-        );
+      const getById = (projectId: number) => getProjectById(api, projectId);
 
       /** The project with this slug in the team, or undefined. Official endpoint; the team can be a slug. */
       const getBySlug = (team: string | number, slug: string) =>
@@ -260,51 +352,7 @@ export const ProjectProvider = () =>
           ),
         );
 
-      /**
-       * The one project in the team with exactly this name, or undefined.
-       * Reads every page. `q` narrows the listing on the server, and the
-       * exact match here decides. Pattern from Confect
-       * `packages/alchemy/src/ConvexClient.ts` and `Project.ts`
-       * (https://github.com/rjdellecese/confect, ISC license).
-       */
-      const findByName = (teamId: number, name: string) =>
-        Effect.gen(function* () {
-          const matches: ProjectDetails[] = [];
-          const seenCursors = new Set<string>();
-          let cursor: string | undefined;
-          while (true) {
-            const body = yield* api.request("list projects", (client) =>
-              client.GET("/teams/{team_id}/projects", {
-                params: {
-                  path: { team_id: teamId },
-                  query: { q: name, ...(cursor === undefined ? {} : { cursor }) },
-                },
-              }),
-            );
-            const page = Schema.decodeUnknownSync(ProjectPage)(body);
-            matches.push(...page.items.filter((row) => row.name === name));
-            if (!page.pagination.hasMore) break;
-            const next = page.pagination.nextCursor;
-            if (next === undefined || next === null || seenCursors.has(next)) {
-              return yield* new ConvexApiError({
-                operation: "list projects",
-                status: 0,
-                code: "InvalidPagination",
-                message: `The project listing of team ${teamId} reports more pages but gives no new cursor. Convex.Project stops so that it does not miss a project named "${name}".`,
-              });
-            }
-            seenCursors.add(next);
-            cursor = next;
-          }
-          if (matches.length > 1) {
-            return yield* new AmbiguousProject({
-              teamId,
-              name,
-              projectIds: matches.map((row) => row.id),
-            });
-          }
-          return matches[0];
-        });
+      const findByName = (teamId: number, name: string) => findProjectByName(api, teamId, name);
 
       /**
        * Brings an existing project to the desired name. The team cannot
@@ -458,22 +506,11 @@ export const ProjectProvider = () =>
               return yield* converge(existing, teamId, news.name);
             }
           }
-          const created = yield* api.request("create project", (client) =>
-            client.POST("/teams/{team_id}/create_project", {
-              params: { path: { team_id: teamId } },
-              body: {
-                projectName: news.name,
-                deploymentType: news.deploymentType ?? "prod",
-                ...(news.deploymentRegion === undefined
-                  ? {}
-                  : { deploymentRegion: news.deploymentRegion }),
-              },
-            }),
-          );
-          // Identity comes from the create response, never from a name lookup.
-          const { projectId } = Schema.decodeUnknownSync(CreatedProject)(created);
-          const details = yield* getById(projectId);
-          if (details === undefined) return yield* new CreatedProjectNotFound({ projectId });
+          const details = yield* createProject(api, teamId, {
+            name: news.name,
+            deploymentType: news.deploymentType ?? "prod",
+            deploymentRegion: news.deploymentRegion,
+          });
           return yield* converge(details, teamId, news.name);
         }),
 

package/src/Push.ts

@@ -27,6 +27,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import { createDeploymentClient } from "@convex-dev/platform";
+import type { paths } from "@convex-dev/platform/managementApi";
 import { hashDirectory } from "alchemy/Command/Memo";
 import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
@@ -80,12 +81,19 @@ const sourceOf = (source: Source) =>
 /** Lifetime of a push key. Long enough for a slow push with index backfills. */
 export const PUSH_KEY_LIFETIME_MS = 2 * 60 * 60 * 1000;
 
-/** The only actions a push key gets. */
-const PUSH_KEY_ACTIONS = [
+/** An action of a deploy key, such as `deployment:deploy`, from the generated schema. */
+export type DeployKeyAction = NonNullable<
+  NonNullable<
+    paths["/deployments/{deployment_name}/create_deploy_key"]["post"]["requestBody"]
+  >["content"]["application/json"]["allowedActions"]
+>[number];
+
+/** The only actions a key for `convex deploy` gets. */
+export const PUSH_KEY_ACTIONS = [
   "deployment:deploy",
   "deployment:env:view",
   "deployment:env:write",
-] as const;
+] as const satisfies readonly DeployKeyAction[];
 
 /** POST /deployments/{deployment_name}/create_deploy_key */
 const CreatedDeployKey = Schema.Struct({ deployKey: Schema.String });
@@ -271,7 +279,7 @@ const CliManifest = Schema.Struct({
 });
 
 /** `[node, <convex bin>]` for the `convex` package that `cwd` resolves. Never downloads. */
-const installedCli = (cwd: string) =>
+export const installedCli = (cwd: string) =>
   Effect.tryPromise({
     try: async (): Promise<readonly [string, ...string[]]> => {
       const manifestPath = createRequire(join(cwd, "package.json")).resolve("convex/package.json");
@@ -360,58 +368,78 @@ const cliEnvironment = (home: string): Record<string, string | undefined> => ({
   XDG_CONFIG_HOME: home,
 });
 
+/**
+ * A deploy key of `deployment` that expires after PUSH_KEY_LIFETIME_MS, with
+ * only `allowedActions`, or every action when that is undefined. Delete it
+ * with {@link deleteDeployKey} when the work is done.
+ */
+export const createDeployKey = (
+  api: ManagementApiService,
+  deployment: string,
+  name: string,
+  allowedActions: readonly DeployKeyAction[] | undefined,
+) =>
+  Effect.gen(function* () {
+    const now = yield* Clock.currentTimeMillis;
+    const created = yield* api.request("create deploy key", (client) =>
+      client.POST("/deployments/{deployment_name}/create_deploy_key", {
+        params: { path: { deployment_name: deployment } },
+        body: {
+          name,
+          ...(allowedActions === undefined ? {} : { allowedActions: [...allowedActions] }),
+          expiresAt: now + PUSH_KEY_LIFETIME_MS,
+        },
+      }),
+    );
+    return Redacted.make(Schema.decodeUnknownSync(CreatedDeployKey)(created).deployKey);
+  });
+
+/**
+ * Deletes a key that {@link createDeployKey} made. The delete is skipped for
+ * a key that is the OAuth credential. A failed delete is logged: the key
+ * expires anyway.
+ */
+export const deleteDeployKey = (
+  api: ManagementApiService,
+  deployment: string,
+  key: Redacted.Redacted<string>,
+) =>
+  Effect.gen(function* () {
+    if (yield* api.isCredentialToken(Redacted.value(key))) return;
+    yield* absentAsUndefined(
+      retryIdempotentWrite(
+        api.requestVoid("delete deploy key", (client) =>
+          client.POST("/deployments/{deployment_name}/delete_deploy_key", {
+            params: { path: { deployment_name: deployment } },
+            body: { id: Redacted.value(key) },
+          }),
+        ),
+      ),
+    );
+  }).pipe(
+    Effect.catch((error) =>
+      Effect.logWarning(
+        `Convex.Deployment could not delete its key on ${deployment} (${error.message}). The key expires on its own within ${PUSH_KEY_LIFETIME_MS / 60_000} minutes.`,
+      ),
+    ),
+  );
+
 /**
  * Creates a deploy key for one push, runs `use` with it, and deletes it
- * afterwards. Without a push command, the key can only deploy and read and
- * write variables. The delete is skipped for a key that is the OAuth credential.
- * A failed delete is logged: the key expires anyway.
+ * afterwards, also after a failure. `allowedActions` is PUSH_KEY_ACTIONS for
+ * `convex deploy`, or undefined for a push command, which can do more than a
+ * push, such as the uploads of convex-hosting through `convex run`.
  */
 export const withPushKey = <A, E, R>(
   api: ManagementApiService,
   deployment: string,
-  source: Source | undefined,
+  allowedActions: readonly DeployKeyAction[] | undefined,
   use: (key: Redacted.Redacted<string>) => Effect.Effect<A, E, R>,
 ) =>
   Effect.acquireUseRelease(
-    Effect.gen(function* () {
-      const now = yield* Clock.currentTimeMillis;
-      const created = yield* api.request("create deploy key", (client) =>
-        client.POST("/deployments/{deployment_name}/create_deploy_key", {
-          params: { path: { deployment_name: deployment } },
-          body: {
-            name: "alchemy-push",
-            // A push command can do more than a push, such as the uploads of
-            // convex-hosting through `convex run`, so its key has every action.
-            ...(source === undefined || sourceOf(source).command === undefined
-              ? { allowedActions: [...PUSH_KEY_ACTIONS] }
-              : {}),
-            expiresAt: now + PUSH_KEY_LIFETIME_MS,
-          },
-        }),
-      );
-      return Redacted.make(Schema.decodeUnknownSync(CreatedDeployKey)(created).deployKey);
-    }),
+    createDeployKey(api, deployment, "alchemy-push", allowedActions),
     use,
-    (key) =>
-      Effect.gen(function* () {
-        if (yield* api.isCredentialToken(Redacted.value(key))) return;
-        yield* absentAsUndefined(
-          retryIdempotentWrite(
-            api.requestVoid("delete deploy key", (client) =>
-              client.POST("/deployments/{deployment_name}/delete_deploy_key", {
-                params: { path: { deployment_name: deployment } },
-                body: { id: Redacted.value(key) },
-              }),
-            ),
-          ),
-        );
-      }).pipe(
-        Effect.catch((error) =>
-          Effect.logWarning(
-            `Convex.Deployment could not delete its push key on ${deployment} (${error.message}). The key expires on its own within ${PUSH_KEY_LIFETIME_MS / 60_000} minutes.`,
-          ),
-        ),
-      ),
+    (key) => deleteDeployKey(api, deployment, key),
   );
 
 /** Every variable of the deployment with its value. */