Distilled

Effect-native SDKs for cloud providers with exhaustive error typing, retry policies, and streaming pagination.

import * as Effect from "effect/Effect"
import * as Stream from "effect/Stream"
import * as Lambda from "@distilled.cloud/aws/lambda"
import * as S3 from "@distilled.cloud/aws/s3"

const bucket = yield* S3.getBucket({
  Bucket: "my-bucket"
}).pipe(
  Effect.catch("NoSuchBucket", () =>
    Effect.void
  )
)

const functions = yield* Lambda.listFunctions
  .items({})
  .pipe(Stream.take(10), Stream.runCollect)

Packages

Package	Description
@distilled.cloud/core	Shared client, traits, errors, and categories
@distilled.cloud/aws	AWS SDK from Smithy models (S3, Lambda, DynamoDB, 200+ services)
@distilled.cloud/cloudflare	Cloudflare SDK (Workers, R2, KV, D1, Queues, DNS)
@distilled.cloud/coinbase	Coinbase CDP SDK (EVM/Solana wallets, swaps, faucets, onramp)
@distilled.cloud/fly-io	Fly.io SDK from OpenAPI spec
@distilled.cloud/gcp	GCP SDK from Discovery Documents
@distilled.cloud/mongodb-atlas	MongoDB Atlas SDK from OpenAPI spec
@distilled.cloud/neon	Neon serverless Postgres SDK from OpenAPI spec
@distilled.cloud/planetscale	PlanetScale MySQL SDK from OpenAPI spec
@distilled.cloud/prisma-postgres	Prisma Postgres SDK from OpenAPI spec
@distilled.cloud/stripe	Stripe SDK from OpenAPI spec
@distilled.cloud/supabase	Supabase Management API SDK from OpenAPI spec
@distilled.cloud/turso	Turso SDK from OpenAPI spec

Getting Started

# Clone with submodules (needed for aws tests and code generation)
git clone --recurse-submodules https://github.com/alchemy-run/distilled.git

# Or if already cloned without submodules
git submodule update --init --recursive

# Install dependencies
bun install

# Build (core first, then all packages)
bun run build

# Run all tests
bun run test

Git Config for Submodules

These settings make working with submodules much less painful:

# Automatically fetch submodules when pulling/cloning
git config submodule.recurse true

# Automatically push submodule changes when pushing
git config push.recurseSubmodules on-demand

Submodules

Vendor API specifications are stored as git submodules under each package's specs/ directory. They are not needed for building or typechecking — only for code generation (bun run generate). The exception is aws, which also needs submodules for testing.

# Fetch specs for a specific package
bun run specs:fetch    # run inside a package directory

# Update specs to latest upstream
bun run specs:update   # run inside a package directory

Package	Submodules
aws	api-models-aws, aws-sdk-js-v3, smithy, smithy-typescript
cloudflare	cloudflare-typescript
coinbase	cdp-sdk
fly-io	distilled-spec-fly-io
gcp	distilled-spec-gcp
mongodb-atlas	distilled-spec-mongodb-atlas
neon	distilled-spec-neon
planetscale	distilled-spec-planetscale
prisma-postgres	distilled-spec-prisma-postgres
stripe	stripe-openapi
supabase	distilled-spec-supabase
turso	turso-docs

Scripts

Script	Description
bun run build	Build core, then all packages
bun run typecheck	Type check all packages
bun run check	Full check (types + lint + format)
bun run test	Run all tests
bun run fmt	Format all packages
bun run lint	Lint all packages
bun run generate	Regenerate all SDKs from specs
bun run create-sdk <name> --specs <url>...	Scaffold a new SDK package

Deployment

Preview Packages

Preview packages are automatically published on every PR and push to main via pkg-pr-new (.github/workflows/pkg-pr.yml).

NPM Releases

To publish a release to npm, manually trigger the Release NPM Packages workflow from the GitHub Actions UI:

1. Go to Actions → Release NPM Packages → Run workflow
2. Choose a bump type (patch or minor) or provide an exact version override
3. The workflow will bump all package versions, commit, tag, create a GitHub release, build, and publish to npm

The release workflow uses npm's OIDC trusted publishing — no npm tokens needed.

CI

The CI workflow (.github/workflows/test.yml) runs typecheck + lint + format + tests for each package that has changed files.

Contributing

The TDD workflow for discovering and patching missing errors:

1. Write a test that triggers an error
2. Run with DEBUG=1 to see the raw response
3. Add the error to the patch file (see package READMEs for format)
4. Regenerate: bun run generate
5. Import the typed error and handle it

See AGENTS.md for detailed development guidelines.