feat(vultr): new @distilled.cloud/vultr SDK

[zeyuri]

Adds an Effect-native Vultr v2 SDK. 510 typed operations generated from the live Vultr OpenAPI 3.0 spec (mirror: zeyuri/openapi-vultr, 330 paths / 161 schemas, fetched from www.vultr.com/api/ on 2026-05-12). Full Compute + Managed Databases + IAM + OIDC + SCIM + CDN + Inference + Marketplace + VFS + Storage Gateways + Tickets surface.

import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
import {
  CredentialsFromEnv,
  listPlans,
  listInstances,
  getInstance,
} from "@distilled.cloud/vultr";

const program = Effect.gen(function* () {
  const { plans = [] } = yield* listPlans({ type: "vc2" });
  const { instances = [] } = yield* listInstances({});
  return { planCount: plans.length, instanceCount: instances.length };
});

Effect.runPromise(
  program.pipe(
    Effect.provide(Layer.merge(CredentialsFromEnv, FetchHttpClient.layer)),
  ),
);

Verified live against the production Vultr API via packages/vultr/test/smoke.ts — credentials, query-string param encoding, response decoding, and typed error matching (404 → Errors.NotFound) all green.

Error modeling in the upstream spec

Asked by the maintainers — answer is "essentially zero":

0 component schemas named with Error / Failure / etc. (out of 161 total)
0 reusable responses in components.responses
1665 4xx/5xx response declarations across all operations
0 of them attach a content.application/json.schema — every single one is description-only:

    "404": { "description": "Not Found" }

The error envelope shape ({ error: string }) lives only in the spec's top-level prose intro, never as a Schema. The agent therefore hand-wrote the entire error matcher in src/client.ts against the prose shape and falls back to the standard status-code error classes from @distilled.cloud/sdk-core/errors (BadRequest, Unauthorized, Forbidden, NotFound, Conflict, TooManyRequests, etc.):

const ApiErrorResponse = Schema.Struct({
  error: Schema.String,
  status: Schema.optional(Schema.Number),
});

const matchError = (status, errorBody, _errors, headers) => {
  const parsed = Schema.decodeUnknownSync(ApiErrorResponse)(errorBody);
  const ErrorClass = HTTP_STATUS_MAP[status];
  return Effect.fail(new ErrorClass({
    message: parsed.error,
    retryAfter: parseRetryAfterForStatus(status, headers),
  }));
};

Practical implication: we get correct status-class errors on every operation, but no granular per-operation typed errors (InstanceLocked, PlanNotAvailableInRegion, QuotaExceeded, …) the way the Neon / PlanetScale SDKs do via JSON Patch. The patches/ directory is wired up — adding typed errors as we encounter them in tests is the planned follow-up.

Two generator bugs surfaced while testing

• Name collisions: /regions and /vfs/regions both generated as listRegions; same with two pushzone endpoints colliding on getPushzone. src/operations/index.ts even has duplicate export * from "./listRegions.ts" lines. The OpenAPI generator's name derivation needs a path-based tiebreaker. 2 collisions across 510 operations — the 508 non-colliding ones all generate cleanly.
• database.status not enum'd in the spec: documents values as Configuring | Rebuilding | Rebalancing | Running in the description, but types the field as plain string. Trivial patch but the kind of thing that causes a real downstream bug (a consumer of mine was comparing against lowercase "running" until I noticed the spec returns capitalized).

Notes / open items

• Spec source is a community-style mirror (zeyuri/openapi-vultr). Vultr doesn't publish the OpenAPI at a stable URL — their docs page generates a blob: URL on demand. The mirror is a 1:1 copy from the docs site as of 2026-05-12. If you'd rather we live under alchemy-run/distilled-spec-vultr, I can move it; a daily fetch-specs.ts against the docs page would keep it fresh.
• scripts/generate.ts has a pre-processing pass that camelCases hyphenated path parameter names ({baremetal-id} → baremetalId) — the shared generator emits unquoted property keys, which is invalid for hyphenated names. Could probably lift into sdk-core/openapi/generate if other vendors hit it.
• Downstream consumer ready: alchemy-run/alchemy-effect#307 builds Vultr.Compute.Instance and Vultr.Database.Postgres resources. Currently uses a hand-rolled HTTP wrapper since this SDK didn't exist yet; once this lands I'd port it to consume @distilled.cloud/vultr.

Reject as-is, scope it down, or ask for the spec source / generator collision fix first — happy to follow whichever direction makes review easiest.

[sam-goodwin]

The main kinds of errors we care about:

1. NotFound
2. Unauthroized
3. Throttling
4. Conflict
5. Transient errors (internal error)

We also use categories to tag errors as retryable so that a blanket retry policy can be applied across multiple calls (see core and cloudflare for examples of how this works with an openapi schema)

[zeyuri]

Looked at this carefully — we're already aligned on the wiring. NotFound / Unauthorized / Conflict / BadRequest / UnprocessableEntity are typed per-op via patches/001-add-422-responses.patch.json and patches/002-add-missing-status-codes.patch.json.

TooManyRequests (Throttling) and the 5xx classes (Transient) intentionally aren't in per-op errors arrays — defaultErrorStatuses in packages/core/scripts/generate-openapi.ts:1153 strips them as cross-cutting:

const defaultErrorStatuses =
  config.defaultErrorStatuses ?? new Set(["401", "429", "500", "503"]);
// ...
for (const status of Object.keys(operation.responses)) {
  if (status.startsWith("2") || defaultErrorStatuses.has(status)) continue;
  // ↑ 401/429/5xx never get added to per-op `errors`

They surface at runtime through packages/vultr/src/client.ts matchError → HTTP_STATUS_MAP[status], with categories pre-attached on the sdk-core base classes:

• TooManyRequests → withThrottlingError + withRetryable({ throttling: true })
• InternalServerError / BadGateway / ServiceUnavailable / GatewayTimeout → withServerError + withRetryable()

So Vultr.Retry.throttling and Vultr.Retry.transient fire uniformly across the whole SDK without per-op type changes.

Just pushed 298422d with packages/vultr/test/retry.test.ts — 7 tests covering the category attachments and the retry policies as happy-path identities. Tried to also assert against a real live 429 by bursting 200 parallel listRegions, but Vultr's actual limiter is way looser than the documented 30 req/s and never fired — fell back to synthetic class checks.

[sam-goodwin]

This should be a paginated API. Take a look at core, cloudflare, and shared open api generator to see how we do this kind of thing. Need to identify cursor/next token/etc.

distilled paginated APIs replace manual pagination with an Effect Stream

listDatabases.pages({..}).pipe(Stream.map(..))
listDatabases.items({..}).pipe(Stream.map(..))

"items" vs "pages" are API specific.

[Mkassabov]

@zeyuri

From our experience ai isn't great at generating distilled SDKs when operating outside of the harness we have for it (create-sdk-full script). One example is that test coverage is not per operation and the pr comment implies that error discovery wasn't run meaning there could be a lot of missing errors.

Can we please redo this with the create-sdk-full script we have in the repo; manually repairing it is a really deep rabbit hole.

[zeyuri]

@zeyuri

From our experience ai isn't great at generating distilled SDKs when operating outside of the harness we have for it (create-sdk-full script). One example is that test coverage is not per operation and the pr comment implies that error discovery wasn't run meaning there could be a lot of missing errors.

Can we please redo this with the create-sdk-full script we have in the repo; manually repairing it is a really deep rabbit hole.

will do