@samebase/alchemy-convex 0.1.0

package/src/ManagementApi.ts

@@ -0,0 +1,193 @@
+// Effect wrapper around the official Convex platform client.
+//
+// `@convex-dev/platform` is an openapi-fetch client: every call resolves to
+// `{ data, error, response }`. This service turns that into an Effect with one
+// typed error, resolves credentials lazily, and validates the fields the
+// provider relies on at runtime.
+import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import { Credentials } from "./Credentials.ts";
+
+export type ManagementClient = ReturnType<typeof createManagementClient>;
+export type DeploymentClient = ReturnType<typeof createDeploymentClient>;
+
+/** Shape of every openapi-fetch result we consume. */
+export interface FetchResult<T> {
+  readonly data?: T;
+  readonly error?: unknown;
+  readonly response: Response;
+}
+
+/**
+ * One error for every control-plane and deployment call. Resources branch on
+ * `status` (404 means absent for read and delete), so the class is load
+ * bearing, not decorative.
+ */
+export class ConvexApiError extends Schema.TaggedError<ConvexApiError>()("ConvexApiError", {
+  operation: Schema.String,
+  status: Schema.Number,
+  code: Schema.optionalKey(Schema.String),
+  message: Schema.String,
+}) {}
+
+const ErrorBody = Schema.Struct({
+  code: Schema.optionalKey(Schema.String),
+  message: Schema.optionalKey(Schema.String),
+});
+
+const toApiError = (operation: string, result: FetchResult<unknown>) => {
+  const body = Schema.decodeUnknownSync(Schema.NullishOr(ErrorBody))(result.error ?? null);
+  const code = body?.code;
+  return new ConvexApiError({
+    operation,
+    status: result.response.status,
+    ...(code === undefined ? {} : { code }),
+    message: body?.message ?? `${operation} failed with HTTP ${result.response.status}`,
+  });
+};
+
+export 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>;
+  /** Run one management call whose success response has no body. */
+  readonly requestVoid: (
+    operation: string,
+    run: (client: ManagementClient) => Promise<FetchResult<unknown>>,
+  ) => Effect.Effect<void, ConvexApiError>;
+  /** Run one deployment-scoped call authenticated with a deploy key. */
+  readonly deploymentRequest: <T>(
+    operation: string,
+    deploymentUrlOrName: string,
+    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>;
+}
+
+export class ManagementApi extends Context.Service<ManagementApi, ManagementApiService>()(
+  "@samebase/alchemy-convex/ManagementApi",
+) {}
+
+const attempt = <T>(operation: string, run: () => Promise<FetchResult<T>>) =>
+  Effect.tryPromise({
+    try: run,
+    catch: (cause) =>
+      new ConvexApiError({
+        operation,
+        status: 0,
+        message: cause instanceof Error ? cause.message : String(cause),
+      }),
+  });
+
+/** Reads `data` or fails with the HTTP status and the API's own code and message. */
+export const settle = <T>(
+  operation: string,
+  run: () => Promise<FetchResult<T>>,
+): Effect.Effect<T, ConvexApiError> =>
+  attempt(operation, run).pipe(
+    Effect.flatMap((result) =>
+      result.response.ok && result.data !== undefined
+        ? Effect.succeed(result.data)
+        : Effect.fail(toApiError(operation, result)),
+    ),
+  );
+
+/** For endpoints that answer with an empty body, such as delete calls. */
+export const settleVoid = (
+  operation: string,
+  run: () => Promise<FetchResult<unknown>>,
+): Effect.Effect<void, ConvexApiError> =>
+  attempt(operation, run).pipe(
+    Effect.flatMap((result) =>
+      result.response.ok ? Effect.void : Effect.fail(toApiError(operation, result)),
+    ),
+  );
+
+/** Turns a 404 into `undefined` so read and delete stay idempotent. */
+export const absentAsUndefined = <A, R>(
+  effect: Effect.Effect<A, ConvexApiError, R>,
+): Effect.Effect<A | undefined, ConvexApiError, R> =>
+  effect.pipe(
+    Effect.catchIf(
+      (error) => error.status === 404,
+      () => Effect.succeed(undefined),
+    ),
+  );
+
+const TeamRow = Schema.Struct({ id: Schema.Number, slug: Schema.String });
+const TeamRows = Schema.Array(TeamRow);
+
+export const ManagementApiLive = (): Layer.Layer<ManagementApi, never, Credentials> =>
+  Layer.effect(
+    ManagementApi,
+    Effect.gen(function* () {
+      const credentials = yield* Credentials;
+      const client = Effect.cached(
+        credentials.pipe(
+          Effect.map((resolved) => createManagementClient(Redacted.value(resolved.accessToken))),
+        ),
+      ).pipe(Effect.flatten);
+
+      const request: ManagementApiService["request"] = (operation, run) =>
+        client.pipe(Effect.flatMap((c) => settle(operation, () => run(c))));
+
+      const requestVoid: ManagementApiService["requestVoid"] = (operation, run) =>
+        client.pipe(Effect.flatMap((c) => settleVoid(operation, () => run(c))));
+
+      const deploymentRequest: ManagementApiService["deploymentRequest"] = (
+        operation,
+        deploymentUrlOrName,
+        deployKey,
+        run,
+      ) =>
+        settle(operation, () =>
+          run(createDeploymentClient(deploymentUrlOrName, Redacted.value(deployKey))),
+        );
+
+      // 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);
+          const resolved = yield* credentials;
+          const rows = yield* Effect.tryPromise({
+            try: async () => {
+              const response = await fetch("https://api.convex.dev/api/dashboard/teams", {
+                headers: { Authorization: `Bearer ${Redacted.value(resolved.accessToken)}` },
+              });
+              if (!response.ok) {
+                throw new Error(`team lookup for "${team}" failed with HTTP ${response.status}`);
+              }
+              return Schema.decodeUnknownSync(TeamRows)(await response.json());
+            },
+            catch: (cause) =>
+              new ConvexApiError({
+                operation: "resolve team",
+                status: 0,
+                message: cause instanceof Error ? cause.message : String(cause),
+              }),
+          });
+          const match = rows.find((row) => row.slug === team);
+          if (match === undefined) {
+            return yield* new ConvexApiError({
+              operation: "resolve team",
+              status: 404,
+              message: `no team with slug "${team}" for this token`,
+            });
+          }
+          return match.id;
+        });
+
+      return { request, requestVoid, deploymentRequest, resolveTeamId };
+    }),
+  );

package/src/PreviewDeployKey.ts

@@ -0,0 +1,126 @@
+// Convex.PreviewDeployKey: a project key that creates and deploys preview
+// deployments, such as the key CI passes to `npx convex deploy` for a branch.
+//
+// Convex returns the secret only once, from create_preview_deploy_key. The
+// listing shows each key under a unique name, the requested name plus a short
+// id suffix, and delete_preview_deploy_key accepts that unique name. A key
+// cannot be changed after creation, so every property change is a replacement.
+import { Resource } from "alchemy";
+import { havePropsChanged, isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import { ListedKey, selectCreatedKey } from "./DeployKey.ts";
+import { absentAsUndefined, ManagementApi } from "./ManagementApi.ts";
+import type { Providers } from "./Providers.ts";
+
+/** GET /projects/{project_id}/list_preview_deploy_keys */
+export const PreviewDeployKeyList = Schema.Struct({ items: Schema.Array(ListedKey) });
+
+/** POST /projects/{project_id}/create_preview_deploy_key */
+export const CreatedPreviewDeployKey = Schema.Struct({ previewDeployKey: Schema.String });
+
+export interface PreviewDeployKeyProps {
+  /** Numeric project id, such as `project.projectId`. */
+  readonly projectId: number;
+  /** Requested key name. Convex appends a short id to make it unique. */
+  readonly name: string;
+}
+
+export interface PreviewDeployKeyAttributes {
+  /** The name Convex lists the key under, such as "ci (6308e666)". */
+  readonly uniqueName: string;
+  readonly projectId: number;
+  /** The secret, such as `preview:<team>:<project>|<token>`. Convex returns it only at creation. */
+  readonly previewDeployKey: Redacted.Redacted<string>;
+}
+
+export type PreviewDeployKey = Resource<
+  "Convex.PreviewDeployKey",
+  PreviewDeployKeyProps,
+  PreviewDeployKeyAttributes,
+  never,
+  Providers
+>;
+export const PreviewDeployKey = Resource<PreviewDeployKey>("Convex.PreviewDeployKey");
+
+export const PreviewDeployKeyProvider = () =>
+  Provider.effect(
+    PreviewDeployKey,
+    Effect.gen(function* () {
+      const api = yield* ManagementApi;
+
+      const listKeys = (projectId: number) =>
+        api
+          .request("list preview deploy keys", (client) =>
+            client.GET("/projects/{project_id}/list_preview_deploy_keys", {
+              params: { path: { project_id: projectId } },
+            }),
+          )
+          .pipe(Effect.map((body) => Schema.decodeUnknownSync(PreviewDeployKeyList)(body).items));
+
+      return {
+        stables: ["uniqueName", "projectId"],
+
+        diff: ({ olds, news, output }) => {
+          if (!isResolved(news)) return Effect.succeed(undefined);
+          // State written without the secret cannot hand a key to dependents,
+          // and Convex cannot return it again, so only a new key helps.
+          return Effect.succeed(
+            (output !== undefined && output.previewDeployKey === undefined) ||
+              havePropsChanged(olds, news)
+              ? ({ action: "replace" } as const)
+              : ({ action: "noop" } as const),
+          );
+        },
+
+        read: Effect.fn(function* ({ output }) {
+          // A key that is not in state has no known secret, so it is never adopted.
+          if (output === undefined) return undefined;
+          const entries = yield* absentAsUndefined(listKeys(output.projectId));
+          return entries?.some((entry) => entry.name === output.uniqueName) ? output : undefined;
+        }),
+
+        reconcile: Effect.fn(function* ({ news, output }) {
+          if (output !== undefined) {
+            // The secret cannot be read back. A key that still exists keeps the one in state.
+            const entries = yield* listKeys(news.projectId);
+            if (entries.some((entry) => entry.name === output.uniqueName)) return output;
+          }
+          const created = yield* api.request("create preview deploy key", (client) =>
+            client.POST("/projects/{project_id}/create_preview_deploy_key", {
+              params: { path: { project_id: news.projectId } },
+              body: { name: news.name },
+            }),
+          );
+          const { previewDeployKey } = Schema.decodeUnknownSync(CreatedPreviewDeployKey)(created);
+          const listed = selectCreatedKey(yield* listKeys(news.projectId), news.name);
+          if (listed === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `Convex created preview deploy key "${news.name}" in project ${news.projectId} but does not list it`,
+              ),
+            );
+          }
+          return {
+            uniqueName: listed.name,
+            projectId: news.projectId,
+            previewDeployKey: Redacted.make(previewDeployKey),
+          };
+        }),
+
+        delete: Effect.fn(function* ({ output }) {
+          // 404 PreviewDeployKeyNotFound: an earlier attempt or someone else deleted it.
+          yield* absentAsUndefined(
+            api.requestVoid("delete preview deploy key", (client) =>
+              client.POST("/projects/{project_id}/delete_preview_deploy_key", {
+                params: { path: { project_id: output.projectId } },
+                body: { id: output.uniqueName },
+              }),
+            ),
+          );
+        }),
+      };
+    }),
+  );

package/src/Project.ts

@@ -0,0 +1,191 @@
+// Convex.Project: a project in a Convex team, with its default production deployment.
+//
+// The Management API has no project update endpoint, so every property change
+// is a replacement. Deleting a project deletes all of its deployments and data.
+import { Resource } from "alchemy";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { components } from "@convex-dev/platform/managementApi";
+import { absentAsUndefined, ManagementApi } from "./ManagementApi.ts";
+import type { Providers } from "./Providers.ts";
+
+/** Region names the Management API accepts, from the generated schema. */
+export type DeploymentRegion = components["schemas"]["RegionName"];
+
+export interface ProjectProps {
+  /** Team slug or numeric team id. A slug costs one extra lookup per run. */
+  readonly team: string | number;
+  /** Display name. Convex derives the slug from it. */
+  readonly name: string;
+  /** Region of the deployment created with the project. Defaults to the team default. */
+  readonly deploymentRegion?: DeploymentRegion;
+  /** Deployment created with the project. Defaults to `prod`. */
+  readonly deploymentType?: "prod" | "dev";
+}
+
+export interface ProjectAttributes {
+  readonly projectId: number;
+  readonly slug: string;
+  readonly name: string;
+  readonly teamId: number;
+  readonly prodDeploymentName: string | undefined;
+  readonly prodDeploymentUrl: string | undefined;
+}
+
+export type Project = Resource<"Convex.Project", ProjectProps, ProjectAttributes, never, Providers>;
+export const Project = Resource<Project>("Convex.Project");
+
+/** Fields of GET /projects/{id} and GET /teams/{team}/projects that the provider uses. */
+const ProjectDetails = Schema.Struct({
+  id: Schema.Number,
+  name: Schema.String,
+  slug: Schema.String,
+  teamId: Schema.Number,
+  prodDeploymentName: Schema.NullOr(Schema.String),
+});
+const ProjectList = Schema.Struct({ items: Schema.Array(ProjectDetails) });
+
+const CreatedProject = Schema.Struct({
+  projectId: Schema.Number,
+  slug: Schema.String,
+  deploymentName: Schema.NullOr(Schema.String),
+  deploymentUrl: Schema.NullOr(Schema.String),
+});
+
+const DeploymentRow = Schema.Struct({
+  name: Schema.String,
+  deploymentType: Schema.String,
+  isDefault: Schema.Boolean,
+  deploymentUrl: Schema.String,
+});
+const DeploymentRows = Schema.Array(DeploymentRow);
+
+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: typeof ProjectDetails.Type) =>
+        prodDeployment(details.id).pipe(
+          Effect.map((prod): ProjectAttributes => ({
+            projectId: details.id,
+            slug: details.slug,
+            name: details.name,
+            teamId: details.teamId,
+            prodDeploymentName: prod?.name ?? details.prodDeploymentName ?? undefined,
+            prodDeploymentUrl: prod?.deploymentUrl,
+          })),
+        );
+
+      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 findByName = (team: string | number, name: string) =>
+        Effect.gen(function* () {
+          const teamId = yield* api.resolveTeamId(team);
+          const list = yield* api.request("list projects", (client) =>
+            client.GET("/teams/{team_id}/projects", { params: { path: { team_id: teamId } } }),
+          );
+          return Schema.decodeUnknownSync(ProjectList)(list).items.find(
+            (row) => row.name === name || row.slug === name,
+          );
+        });
+
+      return {
+        stables: ["projectId", "slug", "teamId"],
+
+        diff: ({ olds, news }) => {
+          if (!isResolved(news)) return Effect.succeed(undefined);
+          const changed =
+            olds.team !== news.team ||
+            olds.name !== news.name ||
+            olds.deploymentRegion !== news.deploymentRegion ||
+            olds.deploymentType !== news.deploymentType;
+          return Effect.succeed(
+            changed ? ({ action: "replace" } as const) : ({ action: "noop" } as const),
+          );
+        },
+
+        read: Effect.fn(function* ({ olds, output }) {
+          if (output !== undefined) {
+            const details = yield* getById(output.projectId);
+            return details === undefined ? undefined : yield* attributesOf(details);
+          }
+          // No state: an existing project with this name belongs to someone
+          // else until the user passes --adopt. Convex has no ownership tags.
+          const existing = yield* findByName(olds.team, olds.name);
+          return existing === undefined ? undefined : Unowned(yield* attributesOf(existing));
+        }),
+
+        reconcile: Effect.fn(function* ({ news, output }) {
+          if (output !== undefined) {
+            // Properties are all create-time; diff maps changes to replace.
+            const details = yield* getById(output.projectId);
+            if (details !== undefined) return yield* attributesOf(details);
+          }
+          // A crash after create and before state write is recovered by read;
+          // a project created by an earlier attempt is reused here too.
+          const existing = yield* findByName(news.team, news.name);
+          if (existing !== undefined) return yield* attributesOf(existing);
+          const teamId = yield* api.resolveTeamId(news.team);
+          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 }),
+              },
+            }),
+          );
+          const parsed = Schema.decodeUnknownSync(CreatedProject)(created);
+          const details = yield* getById(parsed.projectId);
+          if (details === undefined) {
+            return yield* Effect.die(
+              new Error(`Convex created project ${parsed.projectId} but it cannot be read back`),
+            );
+          }
+          return yield* attributesOf(details);
+        }),
+
+        delete: Effect.fn(function* ({ output }) {
+          yield* absentAsUndefined(
+            api.requestVoid("delete project", (client) =>
+              client.POST("/projects/{project_id}/delete", {
+                params: { path: { project_id: output.projectId } },
+              }),
+            ),
+          );
+        }),
+      };
+    }),
+  );

package/src/Providers.ts

@@ -0,0 +1,51 @@
+// The provider collection users merge into a stack:
+//   providers: Layer.mergeAll(Cloudflare.providers(), Convex.providers())
+import { CommandExecutorLive } from "alchemy/Command";
+import * as Provider from "alchemy/Provider";
+import * as Layer from "effect/Layer";
+import { type Credentials, fromConfig } from "./Credentials.ts";
+import {
+  DefaultEnvironmentVariable,
+  DefaultEnvironmentVariableProvider,
+} from "./DefaultEnvironmentVariable.ts";
+import { Deploy, DeployProvider } from "./Deploy.ts";
+import { DeployKey, DeployKeyProvider } from "./DeployKey.ts";
+import { EnvironmentVariable, EnvironmentVariableProvider } from "./EnvironmentVariable.ts";
+import { ManagementApiLive } from "./ManagementApi.ts";
+import { PreviewDeployKey, PreviewDeployKeyProvider } from "./PreviewDeployKey.ts";
+import { Project, ProjectProvider } from "./Project.ts";
+
+export class Providers extends Provider.ProviderCollection<Providers>()("Convex") {}
+
+/**
+ * All Convex resource providers. Pass a credentials layer to override the
+ * default lookup (`CONVEX_ACCESS_TOKEN`, then the Convex CLI login).
+ */
+export const providers = (credentials: Layer.Layer<Credentials> = fromConfig()) =>
+  Layer.effect(
+    Providers,
+    Provider.collection([
+      Project,
+      DeployKey,
+      PreviewDeployKey,
+      EnvironmentVariable,
+      DefaultEnvironmentVariable,
+      Deploy,
+    ]),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        ProjectProvider(),
+        DeployKeyProvider(),
+        PreviewDeployKeyProvider(),
+        EnvironmentVariableProvider(),
+        DefaultEnvironmentVariableProvider(),
+        DeployProvider(),
+      ),
+    ),
+    Layer.provide(ManagementApiLive()),
+    Layer.provide(credentials),
+    // Convex.Deploy runs the Convex CLI through Alchemy's command executor.
+    Layer.provide(CommandExecutorLive()),
+    Layer.orDie,
+  );

package/src/index.ts

@@ -0,0 +1,45 @@
+// @samebase/alchemy-convex: Convex resources for Alchemy v2.
+export {
+  ACCESS_TOKEN_ENV,
+  Credentials,
+  CredentialsError,
+  fromConfig,
+  fromToken,
+} from "./Credentials.ts";
+export {
+  DefaultEnvironmentVariable,
+  type DefaultEnvironmentVariableAttributes,
+  type DefaultEnvironmentVariableProps,
+  type DeploymentType,
+} from "./DefaultEnvironmentVariable.ts";
+export {
+  Deploy,
+  type DeployAttributes,
+  deployArgs,
+  type DeployProps,
+  parseDeployOutput,
+} from "./Deploy.ts";
+export {
+  DeployKey,
+  type DeployKeyAction,
+  type DeployKeyAttributes,
+  type DeployKeyProps,
+} from "./DeployKey.ts";
+export {
+  EnvironmentVariable,
+  type EnvironmentVariableAttributes,
+  type EnvironmentVariableProps,
+} from "./EnvironmentVariable.ts";
+export { ConvexApiError, ManagementApi } from "./ManagementApi.ts";
+export {
+  PreviewDeployKey,
+  type PreviewDeployKeyAttributes,
+  type PreviewDeployKeyProps,
+} from "./PreviewDeployKey.ts";
+export {
+  type DeploymentRegion,
+  Project,
+  type ProjectAttributes,
+  type ProjectProps,
+} from "./Project.ts";
+export { Providers, providers } from "./Providers.ts";