@thomasfosterau/effect-connect-alchemy-cloudflare 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Foster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# @thomasfosterau/effect-connect-alchemy-cloudflare
+# `@thomasfosterau/effect-connect-alchemy-cloudflare`
 
-Placeholder reserved for npm trusted publishing; the first real release is 0.1.0, from https://github.com/thomasfosterau/effect-connect.
+Deploy-time bindings for [`@thomasfosterau/effect-connect`](https://github.com/thomasfosterau/effect-connect/tree/trunk/packages/core#readme) on Cloudflare Workers deployed with [Alchemy](https://alchemy.run)'s Cloudflare provider, [`@alchemy.run/cloudflare`](https://www.npmjs.com/package/@alchemy.run/cloudflare). Each builder returns the record of Worker `env` bindings one provider reads, under that provider's own keys (`RESEND_API_KEY` for Resend, the one provider today). Secrets are `Redacted` values, which Alchemy deploys as secret bindings. Spread the record into your Worker's `env`, and the provider's `resolveTransport(env)` (or `layerConfig`) finds its credentials at runtime.
+
+It binds credentials only. It provisions nothing on the vendor's side (domains, API keys). Its types are the Cloudflare provider's: every bindings record is a `WorkerBindings` (each value a `Cloudflare.WorkerBindingResource`), and `Deployed<B>` is `Cloudflare.InferEnv<B>`. At runtime the builders need only `effect`.
+
+This package was created using Claude Code, and its API is in flux: expect churn and breaking changes.
+
+## Install
+
+```bash
+pnpm add -D @thomasfosterau/effect-connect-alchemy-cloudflare @alchemy.run/cloudflare@2.0.0-beta.85 alchemy@2.0.0-beta.85 effect
+```
+
+Its peer dependencies are all required: `@alchemy.run/cloudflare` and `alchemy`, exactly `2.0.0-beta.85` (the provider peers on that exact `alchemy`), and `effect` `^4.1.0`, the range both of them require. Node.js 22 or newer is required. The package runs on the deploy machine, inside your `alchemy.run.ts`, never in the Worker.
+
+## Usage
+
+On the deploy machine, build the bindings and pass them into the Worker's `env`:
+
+```ts skip-type-checking
+import * as Redacted from "effect/Redacted";
+import { resendBindings } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+
+const env = {
+  ...resendBindings({ apiKey: Redacted.make(process.env.RESEND_API_KEY!) }),
+};
+// …then `env` in your Worker resource's props.
+```
+
+Or read the same names through `effect/Config` on the deploy machine, with the `…BindingsConfig` forms. Each one is a `Config` of the whole record, and fails when a required value is missing:
+
+```ts skip-type-checking
+import * as Effect from "effect/Effect";
+import { resendBindingsConfig } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+
+const env = Effect.gen(function* () {
+  return { ...(yield* resendBindingsConfig) };
+});
+```
+
+In the Worker, the provider reads them back:
+
+```ts skip-type-checking
+import * as Resend from "@thomasfosterau/effect-connect-resend";
+
+const EmailLive = Resend.resolveTransport(env); // the live sender: RESEND_API_KEY is bound
+```
+
+## API
+
+| Export | Binds | Read at runtime by |
+| --- | --- | --- |
+| `resendBindings`, `resendBindingsConfig`, `ResendBindings`, `ResendBindingsInput` | `RESEND_API_KEY` (secret) | `effect-connect-resend`'s `resolveTransport(env)` (`ResendEnv`) |
+| `WorkerBindings<B>` | — | The constraint every bindings record meets: each value a `Cloudflare.WorkerBindingResource`, so the record spreads into a `Cloudflare.Worker`'s `env`. |
+| `Deployed<B>` | — | `Cloudflare.InferEnv<B>`: the `env` a Worker receives for a bindings record `B`, every value a plain string. Each provider's env type accepts it. |
+
+`Deployed<B>` is defined as the provider's own `Cloudflare.InferEnv<B>`, so a Worker typed with it is checked against the env Alchemy actually deploys; the package's tests assert, for every builder against `@alchemy.run/cloudflare` 2.0.0-beta.85, that it is also what `InferEnv` gives a `Cloudflare.Worker` whose `env` is `B`, and that the provider's env type accepts it.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import * as Config from "effect/Config";
+import * as Cloudflare from "@alchemy.run/cloudflare";
+import * as Redacted from "effect/Redacted";
+/**
+ * A record Alchemy's Cloudflare provider accepts as a Worker's `env`: every
+ * value is a `Cloudflare.WorkerBindingResource` (a `Redacted` deploys as a
+ * secret binding, a string as a plain one). Every builder's record satisfies
+ * it, so it spreads into a `Cloudflare.Worker`'s `env` prop as is.
+ *
+ * @example
+ * ```ts
+ * import type { ResendBindings, WorkerBindings } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+ *
+ * const check = <B extends WorkerBindings<B>>(bindings: B): B => bindings;
+ * const accept = (bindings: ResendBindings): ResendBindings => check(bindings);
+ * console.log(typeof accept); // "function"
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type WorkerBindings<B> = { readonly [K in keyof B]: Cloudflare.WorkerBindingResource; };
+/**
+ * The `env` a Worker receives for a bindings record: the provider's own
+ * `Cloudflare.InferEnv` of it. Alchemy deploys a `Redacted` value as a secret
+ * binding and a string as a plain one, and the Worker reads both back as
+ * plain strings; optional keys stay optional.
+ *
+ * A provider's env contract (`ResendEnv`, …) accepts this type, which is
+ * what the package's tests assert for every builder.
+ *
+ * @example
+ * ```ts
+ * import type { Deployed, ResendBindings } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+ *
+ * const env: Deployed<ResendBindings> = { RESEND_API_KEY: "re_123" };
+ * console.log(env.RESEND_API_KEY); // "re_123"
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type Deployed<B extends WorkerBindings<B>> = Cloudflare.InferEnv<B>;
+/**
+ * What {@link resendBindings} takes.
+ *
+ * @since 0.1.0
+ */
+export interface ResendBindingsInput {
+  /** The Resend API key. */
+  readonly apiKey: Redacted.Redacted;
+}
+/**
+ * The Resend bindings for a Worker's `env`: `RESEND_API_KEY`, deployed as a
+ * secret because it is `Redacted`.
+ *
+ * @since 0.1.0
+ */
+export interface ResendBindings {
+  readonly RESEND_API_KEY: Redacted.Redacted;
+}
+/**
+ * The Resend bindings from literal values, to spread into a Worker's `env`.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert";
+ * import * as Redacted from "effect/Redacted";
+ * import { resendBindings } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+ *
+ * const env = resendBindings({ apiKey: Redacted.make("re_123") });
+ * assert.strictEqual(Redacted.value(env.RESEND_API_KEY), "re_123");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const resendBindings: (input: ResendBindingsInput) => ResendBindings;
+/**
+ * The Resend bindings read through `effect/Config` on the deploy machine:
+ * `RESEND_API_KEY` (required, redacted). Fails with a `ConfigError` when it
+ * is unset or empty, so a deploy never ships a Worker without its key.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert";
+ * import * as ConfigProvider from "effect/ConfigProvider";
+ * import * as Effect from "effect/Effect";
+ * import * as Redacted from "effect/Redacted";
+ * import { resendBindingsConfig } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+ *
+ * const env = Effect.runSync(
+ *   resendBindingsConfig.parse(ConfigProvider.fromEnv({ env: { RESEND_API_KEY: "re_123" } })),
+ * );
+ * assert.strictEqual(Redacted.value(env.RESEND_API_KEY), "re_123");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const resendBindingsConfig: Config.Config<ResendBindings>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,50 @@
+import * as Config from "effect/Config";
+// src/Resend.ts
+/**
+* The Worker bindings `@thomasfosterau/effect-connect-resend` reads
+* (`ResendEnv`): the API key, as a secret.
+*
+* @module Resend
+* @since 0.1.0
+*/
+/**
+* The Resend bindings from literal values, to spread into a Worker's `env`.
+*
+* @example
+* ```ts
+* import * as assert from "node:assert";
+* import * as Redacted from "effect/Redacted";
+* import { resendBindings } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+*
+* const env = resendBindings({ apiKey: Redacted.make("re_123") });
+* assert.strictEqual(Redacted.value(env.RESEND_API_KEY), "re_123");
+* ```
+*
+* @since 0.1.0
+*/
+const resendBindings = (input) => ({ RESEND_API_KEY: input.apiKey });
+/**
+* The Resend bindings read through `effect/Config` on the deploy machine:
+* `RESEND_API_KEY` (required, redacted). Fails with a `ConfigError` when it
+* is unset or empty, so a deploy never ships a Worker without its key.
+*
+* @example
+* ```ts
+* import * as assert from "node:assert";
+* import * as ConfigProvider from "effect/ConfigProvider";
+* import * as Effect from "effect/Effect";
+* import * as Redacted from "effect/Redacted";
+* import { resendBindingsConfig } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+*
+* const env = Effect.runSync(
+*   resendBindingsConfig.parse(ConfigProvider.fromEnv({ env: { RESEND_API_KEY: "re_123" } })),
+* );
+* assert.strictEqual(Redacted.value(env.RESEND_API_KEY), "re_123");
+* ```
+*
+* @since 0.1.0
+*/
+const resendBindingsConfig = Config.all({ RESEND_API_KEY: Config.Redacted("RESEND_API_KEY") });
+export { resendBindings, resendBindingsConfig };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/Resend.ts"],"sourcesContent":["/**\n * The Worker bindings `@thomasfosterau/effect-connect-resend` reads\n * (`ResendEnv`): the API key, as a secret.\n *\n * @module Resend\n * @since 0.1.0\n */\n\nimport * as Config from \"effect/Config\";\nimport type * as Redacted from \"effect/Redacted\";\n\n/**\n * What {@link resendBindings} takes.\n *\n * @since 0.1.0\n */\nexport interface ResendBindingsInput {\n  /** The Resend API key. */\n  readonly apiKey: Redacted.Redacted;\n}\n\n/**\n * The Resend bindings for a Worker's `env`: `RESEND_API_KEY`, deployed as a\n * secret because it is `Redacted`.\n *\n * @since 0.1.0\n */\nexport interface ResendBindings {\n  readonly RESEND_API_KEY: Redacted.Redacted;\n}\n\n/**\n * The Resend bindings from literal values, to spread into a Worker's `env`.\n *\n * @example\n * ```ts\n * import * as assert from \"node:assert\";\n * import * as Redacted from \"effect/Redacted\";\n * import { resendBindings } from \"@thomasfosterau/effect-connect-alchemy-cloudflare\";\n *\n * const env = resendBindings({ apiKey: Redacted.make(\"re_123\") });\n * assert.strictEqual(Redacted.value(env.RESEND_API_KEY), \"re_123\");\n * ```\n *\n * @since 0.1.0\n */\nexport const resendBindings = (input: ResendBindingsInput): ResendBindings => ({\n  RESEND_API_KEY: input.apiKey,\n});\n\n/**\n * The Resend bindings read through `effect/Config` on the deploy machine:\n * `RESEND_API_KEY` (required, redacted). Fails with a `ConfigError` when it\n * is unset or empty, so a deploy never ships a Worker without its key.\n *\n * @example\n * ```ts\n * import * as assert from \"node:assert\";\n * import * as ConfigProvider from \"effect/ConfigProvider\";\n * import * as Effect from \"effect/Effect\";\n * import * as Redacted from \"effect/Redacted\";\n * import { resendBindingsConfig } from \"@thomasfosterau/effect-connect-alchemy-cloudflare\";\n *\n * const env = Effect.runSync(\n *   resendBindingsConfig.parse(ConfigProvider.fromEnv({ env: { RESEND_API_KEY: \"re_123\" } })),\n * );\n * assert.strictEqual(Redacted.value(env.RESEND_API_KEY), \"re_123\");\n * ```\n *\n * @since 0.1.0\n */\nexport const resendBindingsConfig: Config.Config<ResendBindings> = Config.all({\n  RESEND_API_KEY: Config.Redacted(\"RESEND_API_KEY\"),\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA8CA,MAAa,kBAAkB,WAAgD,EAC7E,gBAAgB,MAAM,OACxB;;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,uBAAsD,OAAO,IAAI,EAC5E,gBAAgB,OAAO,SAAS,gBAAgB,EAClD,CAAC"}

package/package.json

@@ -1,14 +1,60 @@
 {
   "name": "@thomasfosterau/effect-connect-alchemy-cloudflare",
-  "version": "0.0.0",
-  "description": "Placeholder reserved for npm trusted publishing; the first real release of @thomasfosterau/effect-connect-alchemy-cloudflare is 0.1.0.",
+  "version": "0.1.0",
+  "description": "Alchemy Cloudflare deploy-time bindings for @thomasfosterau/effect-connect: per-provider builders whose keys match each provider's Worker env contract, with secrets as Redacted values, so a Cloudflare Worker deployed with Alchemy's Cloudflare provider gets exactly the bindings resolveTransport(env) reads, typed by the provider's own InferEnv.",
+  "keywords": [
+    "alchemy",
+    "cloudflare",
+    "effect",
+    "email",
+    "sms",
+    "typescript",
+    "workers"
+  ],
+  "homepage": "https://github.com/thomasfosterau/effect-connect#readme",
+  "bugs": {
+    "url": "https://github.com/thomasfosterau/effect-connect/issues"
+  },
   "license": "MIT",
+  "author": "Thomas Foster <me@thomasfoster.au>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/thomasfosterau/effect-connect.git",
+    "url": "https://github.com/thomasfosterau/effect-connect.git",
     "directory": "packages/alchemy-cloudflare"
   },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@alchemy.run/cloudflare": "2.0.0-beta.85",
+    "@effect/language-service": "^0.87.5",
+    "@effect/vitest": "4.1.2",
+    "@types/node": "^26.6.6",
+    "alchemy": "2.0.0-beta.85",
+    "effect": "4.1.2",
+    "@thomasfosterau/effect-connect-resend": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@alchemy.run/cloudflare": "2.0.0-beta.85",
+    "alchemy": "2.0.0-beta.85",
+    "effect": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=22"
   }
-}
+}

package/src/Bindings.ts

@@ -0,0 +1,52 @@
+/**
+ * The types that tie a bindings record to Alchemy's Cloudflare provider
+ * (`@alchemy.run/cloudflare`): what a record may hold, and what a Worker
+ * receives once Alchemy has deployed it.
+ *
+ * @module Bindings
+ * @since 0.1.0
+ */
+
+import type * as Cloudflare from "@alchemy.run/cloudflare";
+
+/**
+ * A record Alchemy's Cloudflare provider accepts as a Worker's `env`: every
+ * value is a `Cloudflare.WorkerBindingResource` (a `Redacted` deploys as a
+ * secret binding, a string as a plain one). Every builder's record satisfies
+ * it, so it spreads into a `Cloudflare.Worker`'s `env` prop as is.
+ *
+ * @example
+ * ```ts
+ * import type { ResendBindings, WorkerBindings } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+ *
+ * const check = <B extends WorkerBindings<B>>(bindings: B): B => bindings;
+ * const accept = (bindings: ResendBindings): ResendBindings => check(bindings);
+ * console.log(typeof accept); // "function"
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type WorkerBindings<B> = {
+  readonly [K in keyof B]: Cloudflare.WorkerBindingResource;
+};
+
+/**
+ * The `env` a Worker receives for a bindings record: the provider's own
+ * `Cloudflare.InferEnv` of it. Alchemy deploys a `Redacted` value as a secret
+ * binding and a string as a plain one, and the Worker reads both back as
+ * plain strings; optional keys stay optional.
+ *
+ * A provider's env contract (`ResendEnv`, …) accepts this type, which is
+ * what the package's tests assert for every builder.
+ *
+ * @example
+ * ```ts
+ * import type { Deployed, ResendBindings } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+ *
+ * const env: Deployed<ResendBindings> = { RESEND_API_KEY: "re_123" };
+ * console.log(env.RESEND_API_KEY); // "re_123"
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type Deployed<B extends WorkerBindings<B>> = Cloudflare.InferEnv<B>;

package/src/Resend.ts

@@ -0,0 +1,74 @@
+/**
+ * The Worker bindings `@thomasfosterau/effect-connect-resend` reads
+ * (`ResendEnv`): the API key, as a secret.
+ *
+ * @module Resend
+ * @since 0.1.0
+ */
+
+import * as Config from "effect/Config";
+import type * as Redacted from "effect/Redacted";
+
+/**
+ * What {@link resendBindings} takes.
+ *
+ * @since 0.1.0
+ */
+export interface ResendBindingsInput {
+  /** The Resend API key. */
+  readonly apiKey: Redacted.Redacted;
+}
+
+/**
+ * The Resend bindings for a Worker's `env`: `RESEND_API_KEY`, deployed as a
+ * secret because it is `Redacted`.
+ *
+ * @since 0.1.0
+ */
+export interface ResendBindings {
+  readonly RESEND_API_KEY: Redacted.Redacted;
+}
+
+/**
+ * The Resend bindings from literal values, to spread into a Worker's `env`.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert";
+ * import * as Redacted from "effect/Redacted";
+ * import { resendBindings } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+ *
+ * const env = resendBindings({ apiKey: Redacted.make("re_123") });
+ * assert.strictEqual(Redacted.value(env.RESEND_API_KEY), "re_123");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const resendBindings = (input: ResendBindingsInput): ResendBindings => ({
+  RESEND_API_KEY: input.apiKey,
+});
+
+/**
+ * The Resend bindings read through `effect/Config` on the deploy machine:
+ * `RESEND_API_KEY` (required, redacted). Fails with a `ConfigError` when it
+ * is unset or empty, so a deploy never ships a Worker without its key.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert";
+ * import * as ConfigProvider from "effect/ConfigProvider";
+ * import * as Effect from "effect/Effect";
+ * import * as Redacted from "effect/Redacted";
+ * import { resendBindingsConfig } from "@thomasfosterau/effect-connect-alchemy-cloudflare";
+ *
+ * const env = Effect.runSync(
+ *   resendBindingsConfig.parse(ConfigProvider.fromEnv({ env: { RESEND_API_KEY: "re_123" } })),
+ * );
+ * assert.strictEqual(Redacted.value(env.RESEND_API_KEY), "re_123");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const resendBindingsConfig: Config.Config<ResendBindings> = Config.all({
+  RESEND_API_KEY: Config.Redacted("RESEND_API_KEY"),
+});

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * `@thomasfosterau/effect-connect-alchemy-cloudflare` — deploy-time bindings
+ * for `@thomasfosterau/effect-connect` on Cloudflare Workers deployed with
+ * [Alchemy](https://alchemy.run)'s Cloudflare provider
+ * (`@alchemy.run/cloudflare`). One builder per provider (Resend today)
+ * produces the record of `env` bindings that provider's
+ * `resolveTransport(env)` (or `layerConfig`) reads, under the same keys, with
+ * secrets as `Redacted` values (Alchemy deploys those as secret bindings) and
+ * unset optional values left out. Each also has a `…BindingsConfig` form
+ * that reads the values on the deploy machine through `effect/Config`.
+ *
+ * Its types are the Cloudflare provider's: every record is a
+ * `WorkerBindings` (each value a `Cloudflare.WorkerBindingResource`), and
+ * `Deployed<B>` is `Cloudflare.InferEnv<B>`, the `env` a Worker bound with
+ * it receives. `@alchemy.run/cloudflare` is a required peer for those types
+ * alone: nothing imports it at runtime.
+ *
+ * It binds credentials only: it provisions nothing on the vendor's side
+ * (domains, API keys).
+ *
+ * @module index
+ * @since 0.1.0
+ */
+
+/**
+ * The Cloudflare provider's view of a bindings record (`WorkerBindings`,
+ * `Deployed`).
+ *
+ * @since 0.1.0
+ */
+export * from "./Bindings.ts";
+/**
+ * The Resend bindings (`RESEND_API_KEY`).
+ *
+ * @since 0.1.0
+ */
+export * from "./Resend.ts";