@distilled.cloud/vercel 0.0.0 → 1.0.0-rc.4

package/package.json

@@ -1,15 +1,85 @@
 {
   "name": "@distilled.cloud/vercel",
-  "version": "0.0.0",
-  "module": "index.ts",
+  "version": "1.0.0-rc.4",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alchemy-run/distilled",
+    "directory": "packages/vercel"
+  },
+  "license": "Apache-2.0",
   "type": "module",
+  "sideEffects": false,
+  "module": "src/index.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "bun": "./src/index.ts",
+      "worker": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./Credentials": {
+      "types": "./lib/credentials.d.ts",
+      "bun": "./src/credentials.ts",
+      "worker": "./src/credentials.ts",
+      "default": "./lib/credentials.js"
+    },
+    "./Errors": {
+      "types": "./lib/errors.d.ts",
+      "bun": "./src/errors.ts",
+      "worker": "./src/errors.ts",
+      "default": "./lib/errors.js"
+    },
+    "./Protocol": {
+      "types": "./lib/protocol.d.ts",
+      "bun": "./src/protocol.ts",
+      "worker": "./src/protocol.ts",
+      "default": "./lib/protocol.js"
+    },
+    "./Retry": {
+      "types": "./lib/retry.d.ts",
+      "bun": "./src/retry.ts",
+      "worker": "./src/retry.ts",
+      "default": "./lib/retry.js"
+    },
+    "./Traits": {
+      "types": "./lib/traits.d.ts",
+      "bun": "./src/traits.ts",
+      "worker": "./src/traits.ts",
+      "default": "./lib/traits.js"
+    },
+    "./Services": {
+      "types": "./lib/services/index.d.ts",
+      "bun": "./src/services/index.ts",
+      "worker": "./src/services/index.ts",
+      "default": "./lib/services/index.js"
+    },
+    "./*": {
+      "types": "./lib/services/*.d.ts",
+      "bun": "./src/services/*.ts",
+      "worker": "./src/services/*.ts",
+      "default": "./lib/services/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "convert": "bun scripts/convert.ts",
+    "generate": "bun scripts/generate.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "spec:download": "bun scripts/download-spec.ts"
+  },
+  "dependencies": {
+    "@distilled.cloud/core": "1.0.0-rc.4"
+  },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "@effect/platform-bun": ">=4.0.0-beta.104 || >=4.0.0"
   },
   "peerDependencies": {
-    "typescript": "^5"
-  },
-  "repository": {
-    "type": "git"
+    "effect": ">=4.0.0-beta.104 || >=4.0.0"
   }
 }

package/src/credentials.ts

@@ -0,0 +1,70 @@
+/**
+ * Vercel credentials — hand-written.
+ *
+ * The `Credentials` service resolves `{ token, apiBaseUrl }` per request; the
+ * protocol layer formats the `Authorization: Bearer <token>` header from it.
+ * The token is a Vercel access token — personal, team, or an OAuth
+ * integration's — the REST API accepts all of them as bearer tokens.
+ *
+ * Vercel scopes most requests to a team via the `teamId`/`slug` QUERY
+ * parameters, which the spec declares per operation; they stay ordinary input
+ * fields rather than credential state, because a single token routinely spans
+ * several teams.
+ */
+import * as EffectConfig from "effect/Config";
+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 { ConfigError } from "@distilled.cloud/core/errors";
+
+/** Vercel's REST API root. */
+export const DEFAULT_API_BASE_URL = "https://api.vercel.com";
+
+export interface Config {
+  readonly token: Redacted.Redacted<string>;
+  readonly apiBaseUrl: string;
+}
+
+export class Credentials extends Context.Service<
+  Credentials,
+  Effect.Effect<Config>
+>()("VercelCredentials") {}
+
+const envConfig = EffectConfig.all({
+  // `VERCEL_TOKEN` is what the Vercel CLI and the official SDK read.
+  token: EffectConfig.string("VERCEL_TOKEN"),
+  apiBaseUrl: EffectConfig.string("VERCEL_API_URL").pipe(
+    EffectConfig.withDefault(DEFAULT_API_BASE_URL),
+  ),
+});
+
+export const CredentialsFromEnv = Layer.succeed(
+  Credentials,
+  envConfig.pipe(
+    Effect.mapError(
+      () =>
+        new ConfigError({
+          message: "VERCEL_TOKEN environment variable is required",
+        }),
+    ),
+    Effect.map(({ token, apiBaseUrl }) => ({
+      token: Redacted.make(token),
+      apiBaseUrl,
+    })),
+    Effect.orDie,
+  ),
+);
+
+/** Convenience layer from a plain token + optional base URL. */
+export const credentials = (config: {
+  readonly token: string;
+  readonly apiBaseUrl?: string;
+}): Layer.Layer<Credentials> =>
+  Layer.succeed(
+    Credentials,
+    Effect.succeed({
+      token: Redacted.make(config.token),
+      apiBaseUrl: config.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+    }),
+  );

package/src/errors.ts

@@ -0,0 +1,93 @@
+/**
+ * Vercel-specific error types.
+ *
+ * Re-exports the common HTTP errors from core and adds the two statuses
+ * Vercel uses that core's shared map has no entry for, plus the
+ * unknown-error and parse-error wrappers.
+ */
+export {
+  BadGateway,
+  BadRequest,
+  Conflict,
+  ConfigError,
+  Forbidden,
+  GatewayTimeout,
+  InternalServerError,
+  Locked,
+  NotFound,
+  ServiceUnavailable,
+  TooManyRequests,
+  Unauthorized,
+  UnprocessableEntity,
+  HTTP_STATUS_MAP,
+  DEFAULT_ERRORS,
+  API_ERRORS,
+} from "@distilled.cloud/core/errors";
+import type { DefaultErrors as CoreDefaultErrors } from "@distilled.cloud/core/errors";
+
+import * as Schema from "effect/Schema";
+import * as Category from "@distilled.cloud/core/category";
+
+/**
+ * HTTP 402 — the account cannot be billed for the request: a missing payment
+ * method, an unpaid invoice, or a spend cap the team has already hit (Vercel
+ * pauses the account at the cap until an owner disables it). Declared on the
+ * ~95 operations that provision billable resources; the rest reach it through
+ * the protocol's status map.
+ */
+export class PaymentRequired extends Schema.TaggedError<PaymentRequired>()(
+  "PaymentRequired",
+  {
+    message: Schema.String,
+  },
+).pipe(Category.withQuotaError) {}
+
+/**
+ * HTTP 410 — Vercel's "Invalid API version": the versioned path segment
+ * (`/v5/domains`, `/v9/projects`) is no longer served. The spec declares it on
+ * nearly every operation as boilerplate, so it rides the common error channel
+ * instead of every generated operation's error list — a 410 means the SDK's
+ * pinned path version was retired and needs a regeneration, not something a
+ * caller can branch on per operation.
+ */
+export class Gone extends Schema.TaggedError<Gone>()("Gone", {
+  message: Schema.String,
+}).pipe(Category.withNotFoundError) {}
+
+/**
+ * Unknown Vercel error — returned when a failed response's HTTP status has no
+ * mapped error class. Carries the raw body for later cataloging.
+ */
+export class UnknownVercelError extends Schema.TaggedError<UnknownVercelError>()(
+  "UnknownVercelError",
+  {
+    code: Schema.optional(Schema.String),
+    message: Schema.optional(Schema.String),
+    body: Schema.Unknown,
+  },
+).pipe(Category.withServerError) {}
+
+/** Schema parse error wrapper. */
+export class VercelParseError extends Schema.TaggedError<VercelParseError>()(
+  "VercelParseError",
+  {
+    body: Schema.Unknown,
+    cause: Schema.Unknown,
+  },
+).pipe(Category.withParseError) {}
+
+/**
+ * Errors any Vercel operation may surface in addition to the per-operation
+ * typed status errors.
+ */
+export type ClientErrors =
+  | UnknownVercelError
+  | VercelParseError
+  | PaymentRequired
+  | Gone;
+
+/**
+ * Default Vercel operation errors: the shared HTTP status errors from core
+ * plus the client-level fallback/decode errors.
+ */
+export type DefaultErrors = CoreDefaultErrors | ClientErrors;

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @distilled.cloud/vercel — Vercel REST API SDK for Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy models in
+ * `.generated-specs` (written by `scripts/convert.ts` from the OpenAPI
+ * document `scripts/download-spec.ts` downloads into `specs/`). Everything
+ * else in this folder is hand-written.
+ */
+export * from "./credentials.ts";
+export * from "./errors.ts";
+export * as T from "./traits.ts";
+export {
+  VercelProtocol,
+  type VercelOpError,
+  type VercelOpContext,
+} from "./protocol.ts";
+export * as Retry from "./retry.ts";
+export * as Services from "./services/index.ts";

package/src/protocol.ts

@@ -0,0 +1,98 @@
+/**
+ * VercelProtocol — the shared bearer-REST protocol instantiated for Vercel.
+ *
+ * Vercel speaks plain JSON with no success envelope: a list endpoint returns
+ * its collection object (`{ projects: [...], pagination: {...} }`), a single
+ * resource returns the object itself. FAILURES are enveloped, and uniformly
+ * so — `{ "error": { "code": "forbidden", "message": "Not authorized" } }` —
+ * with `code` a machine-readable string that error matchers can key on.
+ *
+ * The API version is part of the PATH (`/v9/projects`, `/v5/domains`), not a
+ * header, so each generated operation carries the version it was generated
+ * from; a retired version answers 410 (see `Gone` in errors.ts).
+ */
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type * as HttpClientError from "effect/unstable/http/HttpClientError";
+import type * as API from "@distilled.cloud/core/api";
+import type { ConfigError } from "@distilled.cloud/core/errors";
+import { HTTP_STATUS_MAP } from "@distilled.cloud/core/errors";
+import {
+  makeRestProtocol,
+  type RestErrorEnvelope,
+} from "@distilled.cloud/core/protocol-rest";
+import { Credentials, type Config } from "./credentials.ts";
+import {
+  Gone,
+  PaymentRequired,
+  UnknownVercelError,
+  type DefaultErrors,
+} from "./errors.ts";
+
+/**
+ * Error channel shared by every generated Vercel operation. Generated service
+ * files annotate operations with `API.OperationMethod<I, O, VercelOpError,
+ * VercelOpContext>` explicitly so the compiler never infers these back out of
+ * the schema generics.
+ */
+export type VercelOpError =
+  | DefaultErrors
+  | ConfigError
+  | HttpClientError.HttpClientError;
+
+/** Context (requirements) shared by every generated Vercel operation. */
+export type VercelOpContext = Credentials | HttpClient.HttpClient;
+
+/**
+ * Vercel error bodies nest under `error`: `{ error: { code, message } }`.
+ * A handful of edge paths (proxy 502s, HTML error pages) answer without that
+ * envelope — those fall through to the protocol's `HTTP <status>` default.
+ */
+const errorEnvelope = (body: unknown): RestErrorEnvelope | undefined => {
+  if (body === null || typeof body !== "object") return undefined;
+  const err = (body as Record<string, unknown>).error;
+  if (err === null || typeof err !== "object") return undefined;
+  const e = err as Record<string, unknown>;
+  return {
+    code: typeof e.code === "string" ? e.code : undefined,
+    message: typeof e.message === "string" ? e.message : undefined,
+  };
+};
+
+export const VercelProtocol: Layer.Layer<API.Protocol> =
+  makeRestProtocol<Config>({
+    // Resolved on the CALLING fiber per request (the layer is memoized per
+    // process); the Credentials service holds an effect, so a token rotated
+    // between calls is picked up without rebuilding the layer.
+    credentials: Effect.gen(function* () {
+      const resolve = yield* Credentials;
+      return yield* resolve;
+    }),
+    baseUrl: (creds) => creds.apiBaseUrl,
+    headers: (creds) => ({
+      Authorization: `Bearer ${Redacted.value(creds.token)}`,
+    }),
+    errorEnvelope,
+    // Core's shared map plus the two statuses Vercel uses that it doesn't
+    // cover: 402 (billing) and 410 (retired path version). Both are declared
+    // so broadly in the spec that leaving them unmapped would funnel routine
+    // failures into UnknownVercelError.
+    statusMap: {
+      ...HTTP_STATUS_MAP,
+      402: PaymentRequired,
+      410: Gone,
+    },
+    unknownError: ({ code, message, body }) =>
+      new UnknownVercelError({
+        code:
+          typeof code === "string"
+            ? code
+            : code !== undefined
+              ? String(code)
+              : undefined,
+        message,
+        body,
+      }),
+  });

package/src/retry.ts

@@ -0,0 +1,78 @@
+/**
+ * Vercel retry surface — a veneer over `@distilled.cloud/core/retry`.
+ *
+ * The `Retry` service tag is threaded into every generated operation via
+ * `API.make({ retry: Retry })`, so a caller-installed policy applies to all
+ * Vercel calls below it and core's `makeDefault` is the fallback when none is
+ * provided.
+ *
+ * Vercel answers a tripped rate limit with `429` plus `Retry-After`; the REST
+ * protocol stamps that onto the retryable error classes, and the default
+ * policy honors it ahead of its own backoff.
+ *
+ * @example
+ * ```ts
+ * import * as Vercel from "@distilled.cloud/vercel";
+ *
+ * myEffect.pipe(Vercel.Retry.transient);
+ * ```
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Retries from "@distilled.cloud/core/retry";
+
+export type Options = Retries.Options;
+export type Factory = Retries.Factory;
+export type Policy = Retries.Policy;
+
+/** Context tag for configuring retry behavior of Vercel API calls. */
+export class Retry extends Context.Service<Retry, Policy>()("VercelRetry") {}
+
+/** Provides a custom retry policy to every Vercel API call below it. */
+export const policy: {
+  (
+    options: Options,
+  ): <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, Exclude<R, Retry>>;
+  (
+    factory: Factory,
+  ): <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, Exclude<R, Retry>>;
+} = (optionsOrFactory: Options | Factory) =>
+  Effect.provide(Layer.succeed(Retry, optionsOrFactory));
+
+/** Disables all automatic retries. */
+export const none: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = Effect.provide(
+  Layer.succeed(Retry, { while: () => false }),
+);
+
+/**
+ * The default retry policy (core's): transient/throttling/retryable errors,
+ * capped exponential backoff with jitter, server `retryAfter` hints honored
+ * with precedence.
+ */
+export const makeDefault: Factory = Retries.makeDefault;
+
+export const jittered = Retries.jittered;
+export const capped = Retries.capped;
+
+/** Retry options that retry all throttling errors indefinitely. */
+export const throttlingOptions: Options = Retries.throttlingOptions;
+
+/** Retries all throttling errors indefinitely (honoring server hints). */
+export const throttling: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = policy(Retries.throttlingFactory);
+
+/** Retry options that retry all transient errors indefinitely. */
+export const transientOptions: Options = Retries.transientOptions;
+
+/** Retries all transient errors indefinitely (honoring server hints). */
+export const transient: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = policy(Retries.transientFactory);