@bunny.net/api-client-effect-v4-runtime 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @bunny.net/api-client-effect-v4-runtime
+
+## 1.1.0
+
+### Minor Changes
+
+- 1baeec8: `BunnyCredentials.fromEnv()` without a name now reads `BUNNYNET_API_KEY`. The
+  previous default, `BUNNY_API_KEY`, is still read when `BUNNYNET_API_KEY` is
+  unset, and is deprecated: the fallback goes away in the next major. A name
+  passed explicitly is read as before.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bunny.net
+
+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,86 @@
-# Temporary Holding Version
+<div align="center">
+  <a href="https://bunny.net">
+    <img src="https://github.com/BunnyWay/bunnynet-typescript/blob/main/asset/bunny.png?raw=true" width="500" height="auto" alt="Bunny"/>
+  </a>
+</div>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Bunny API client runtime for Effect 4
+
+This package contains `@bunny.net/api-client-effect-v4-runtime`, what every
+`@bunny.net/api-client-effect-v4-*` client shares: the `BunnyCredentials`
+service, the error types and the operation executor. You get it with any client;
+import it directly for the credential layers and to match on errors. It is the
+Effect 4 flavour; on Effect 3, use `@bunny.net/api-client-effect-runtime` and
+the `@bunny.net/api-client-effect-*` clients instead.
+
+## 🥕 Usage
+
+It comes as a peer dependency of each client, so one copy serves every Bunny
+client in an app and their service tags and error classes are the same objects:
+
+```sh
+npm install @bunny.net/api-client-effect-v4-core @bunny.net/api-client-effect-v4-runtime effect
+```
+
+### Handling a documented error
+
+```typescript
+import { Effect, Layer } from "effect";
+import { FetchHttpClient } from "effect/http";
+import { BunnyCore } from "@bunny.net/api-client-effect-v4-core";
+import { BunnyCredentials } from "@bunny.net/api-client-effect-v4-runtime";
+
+const program = Effect.gen(function* () {
+  const core = yield* BunnyCore;
+  const zone = yield* core.pullZonePublicIndex({ path: { id: 123 } });
+  return zone.value.Name;
+}).pipe(
+  Effect.catchTag(
+    "BunnyResponseError",
+    (error) =>
+      Effect.succeed(`pull zone 123 answered HTTP ${error.response.status}`),
+  ),
+);
+
+const Live = BunnyCore.Default.pipe(
+  Layer.provide(BunnyCredentials.layer(process.env.BUNNYNET_API_KEY!)),
+  Layer.provide(FetchHttpClient.layer),
+);
+
+console.log(await Effect.runPromise(program.pipe(Effect.provide(Live))));
+```
+
+`BunnyCredentials.layer(key)` holds one key, as a string or an existing
+`Redacted`; `BunnyCredentials.fromEnv(name)` reads it from configuration,
+`BUNNYNET_API_KEY` by default, falling back to the deprecated `BUNNY_API_KEY`
+when it is unset. The key is kept `Redacted`, so it never shows up through
+`toString`, `JSON.stringify` or inspection, and it is revealed at one place
+only: when the auth header is set on the outgoing request.
+
+The errors are all `Data.TaggedError`, so `Effect.catchTag` narrows them:
+
+- `BunnyInputError`: the input was rejected by the operation's schema and
+  nothing was sent.
+- `BunnyResponseError`: a documented error status, with `response` holding the
+  status and the body decoded by that status's schema.
+- `BunnyDecodeError`: a documented status whose body the schema rejects. This is
+  the signal that the live API drifted from its spec.
+- `BunnyUnexpectedStatusError`: a status the spec doesn't document, with the raw
+  body attached.
+
+Transport failures are Effect's own `HttpClientError` from `effect/http`: one
+class, tagged `"HttpClientError"`, whose `reason` says what happened
+(`TransportError`, `StatusCodeError`, …). Coming from the Effect 3 client,
+`Effect.catchTag("RequestError", …)` becomes
+`Effect.catchTag("HttpClientError", …)` with a match on `error.reason._tag`.
+Generated clients contain no transport code: retries, timeouts, tracing and
+request rewriting are whatever your `HttpClient` layer does, and every operation
+runs inside a span named after its operation id.
+
+The `/testing` subpath has `stubHttpClient()`, `fetchHttpClient()` and
+`serviceContract()`, the behaviours every generated client is checked against.
+
+## 🔧 Contributing
+
+The development setup, the commands and how releases are made are described in
+[docs/human_development.md](https://github.com/BunnyWay/bunnynet-typescript/blob/main/docs/human_development.md).

package/dist/mod.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @bunny.net/api-client-effect-v4-runtime
+ *
+ * The shared runtime every generated Bunny.net Effect 4 client depends on:
+ *
+ * - `BunnyCredentials` — the service that carries the API key (a
+ *   `Redacted` string). Provide it with `BunnyCredentials.layer(key)` or
+ *   `BunnyCredentials.fromEnv()`.
+ * - The error taxonomy — tagged errors on the Effect error channel
+ *   (`BunnyInputError`, `BunnyResponseError`, `BunnyDecodeError`,
+ *   `BunnyUnexpectedStatusError`); transport failures surface as
+ *   Effect's own `HttpClientError` from `effect/http`.
+ * - `executeOperation` — runs one generated operation descriptor
+ *   against the `HttpClient` from context. Generated clients never
+ *   touch `fetch`: whichever `HttpClient` layer the caller provides
+ *   (`FetchHttpClient.layer`, `NodeHttpClient.layer`, a test stub) is
+ *   what sends the request, and retry / timeout / tracing are the
+ *   caller's `HttpClient` combinators, not generated code.
+ */
+export * from "./src/credentials.js";
+export * from "./src/errors.js";
+export * from "./src/operation.js";

package/dist/mod.js

@@ -0,0 +1,23 @@
+/**
+ * @bunny.net/api-client-effect-v4-runtime
+ *
+ * The shared runtime every generated Bunny.net Effect 4 client depends on:
+ *
+ * - `BunnyCredentials` — the service that carries the API key (a
+ *   `Redacted` string). Provide it with `BunnyCredentials.layer(key)` or
+ *   `BunnyCredentials.fromEnv()`.
+ * - The error taxonomy — tagged errors on the Effect error channel
+ *   (`BunnyInputError`, `BunnyResponseError`, `BunnyDecodeError`,
+ *   `BunnyUnexpectedStatusError`); transport failures surface as
+ *   Effect's own `HttpClientError` from `effect/http`.
+ * - `executeOperation` — runs one generated operation descriptor
+ *   against the `HttpClient` from context. Generated clients never
+ *   touch `fetch`: whichever `HttpClient` layer the caller provides
+ *   (`FetchHttpClient.layer`, `NodeHttpClient.layer`, a test stub) is
+ *   what sends the request, and retry / timeout / tracing are the
+ *   caller's `HttpClient` combinators, not generated code.
+ */
+export * from "./src/credentials.js";
+export * from "./src/errors.js";
+export * from "./src/operation.js";
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC","sourcesContent":["/**\n * @bunny.net/api-client-effect-v4-runtime\n *\n * The shared runtime every generated Bunny.net Effect 4 client depends on:\n *\n * - `BunnyCredentials` — the service that carries the API key (a\n *   `Redacted` string). Provide it with `BunnyCredentials.layer(key)` or\n *   `BunnyCredentials.fromEnv()`.\n * - The error taxonomy — tagged errors on the Effect error channel\n *   (`BunnyInputError`, `BunnyResponseError`, `BunnyDecodeError`,\n *   `BunnyUnexpectedStatusError`); transport failures surface as\n *   Effect's own `HttpClientError` from `effect/http`.\n * - `executeOperation` — runs one generated operation descriptor\n *   against the `HttpClient` from context. Generated clients never\n *   touch `fetch`: whichever `HttpClient` layer the caller provides\n *   (`FetchHttpClient.layer`, `NodeHttpClient.layer`, a test stub) is\n *   what sends the request, and retry / timeout / tracing are the\n *   caller's `HttpClient` combinators, not generated code.\n */\nexport * from \"./src/credentials.ts\";\nexport * from \"./src/errors.ts\";\nexport * from \"./src/operation.ts\";\n"]}

package/dist/src/credentials.d.ts

@@ -0,0 +1,26 @@
+import { Config, Context, Layer, Redacted } from "effect";
+/** What a Bunny.net client needs to authenticate: the API key (or, for the Edge Storage API, the zone password). */
+export interface BunnyCredentialsShape {
+    readonly accessKey: Redacted.Redacted<string>;
+}
+declare const BunnyCredentials_base: Context.ServiceClass<BunnyCredentials, "@bunny.net/api-client-effect-v4-runtime/BunnyCredentials", BunnyCredentialsShape>;
+/**
+ * The credential service every generated client reads from context.
+ *
+ * The key is held as `Redacted` so it never appears through
+ * `toString`/`JSON.stringify`/inspection; it is revealed at exactly one
+ * place, when the auth header is set on the outgoing request.
+ */
+export declare class BunnyCredentials extends BunnyCredentials_base {
+    /** A layer holding one key. Accepts a raw string (wrapped immediately) or an existing `Redacted`. */
+    static readonly layer: (accessKey: string | Redacted.Redacted<string>) => Layer.Layer<BunnyCredentials>;
+    /**
+     * A layer reading the key from configuration (the environment by default).
+     *
+     * With a name, it reads that name only. Without one, it reads
+     * `BUNNYNET_API_KEY`, then the deprecated `BUNNY_API_KEY` when that is
+     * unset; the fallback goes away in the next major.
+     */
+    static readonly fromEnv: (name?: string) => Layer.Layer<BunnyCredentials, Config.ConfigError>;
+}
+export {};

package/dist/src/credentials.js

@@ -0,0 +1,27 @@
+import { Config, Context, Effect, Layer, Redacted } from "effect";
+/**
+ * The credential service every generated client reads from context.
+ *
+ * The key is held as `Redacted` so it never appears through
+ * `toString`/`JSON.stringify`/inspection; it is revealed at exactly one
+ * place, when the auth header is set on the outgoing request.
+ */
+export class BunnyCredentials extends Context.Service()("@bunny.net/api-client-effect-v4-runtime/BunnyCredentials") {
+    /** A layer holding one key. Accepts a raw string (wrapped immediately) or an existing `Redacted`. */
+    static layer = (accessKey) => Layer.succeed(BunnyCredentials, {
+        accessKey: Redacted.isRedacted(accessKey)
+            ? accessKey
+            : Redacted.make(accessKey),
+    });
+    /**
+     * A layer reading the key from configuration (the environment by default).
+     *
+     * With a name, it reads that name only. Without one, it reads
+     * `BUNNYNET_API_KEY`, then the deprecated `BUNNY_API_KEY` when that is
+     * unset; the fallback goes away in the next major.
+     */
+    static fromEnv = (name) => Layer.effect(BunnyCredentials, (name === undefined
+        ? Config.Redacted("BUNNYNET_API_KEY").pipe(Config.orElse(() => Config.Redacted("BUNNY_API_KEY")))
+        : Config.Redacted(name)).pipe(Effect.map((accessKey) => ({ accessKey }))));
+}
+//# sourceMappingURL=credentials.js.map

package/dist/src/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAOlE;;;;;;GAMG;AACH,MAAM,OAAO,gBACX,SAAQ,OAAO,CAAC,OAAO,EAA2C,CAChE,0DAA0D,CAC3D;IACD,qGAAqG;IACrG,MAAM,CAAU,KAAK,GAAG,CACtB,SAA6C,EACd,EAAE,CACjC,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE;QAC9B,SAAS,EAAE,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC;YACvC,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC;KAC7B,CAAC,CAAC;IAEL;;;;;;OAMG;IACH,MAAM,CAAU,OAAO,GAAG,CACxB,IAAa,EACsC,EAAE,CACrD,KAAK,CAAC,MAAM,CACV,gBAAgB,EAChB,CAAC,IAAI,KAAK,SAAS;QACjB,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC,IAAI,CACxC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CACtD;QACD,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAC3B,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAC3C,CACJ,CAAC","sourcesContent":["import { Config, Context, Effect, Layer, Redacted } from \"effect\";\n\n/** What a Bunny.net client needs to authenticate: the API key (or, for the Edge Storage API, the zone password). */\nexport interface BunnyCredentialsShape {\n  readonly accessKey: Redacted.Redacted<string>;\n}\n\n/**\n * The credential service every generated client reads from context.\n *\n * The key is held as `Redacted` so it never appears through\n * `toString`/`JSON.stringify`/inspection; it is revealed at exactly one\n * place, when the auth header is set on the outgoing request.\n */\nexport class BunnyCredentials\n  extends Context.Service<BunnyCredentials, BunnyCredentialsShape>()(\n    \"@bunny.net/api-client-effect-v4-runtime/BunnyCredentials\",\n  ) {\n  /** A layer holding one key. Accepts a raw string (wrapped immediately) or an existing `Redacted`. */\n  static readonly layer = (\n    accessKey: string | Redacted.Redacted<string>,\n  ): Layer.Layer<BunnyCredentials> =>\n    Layer.succeed(BunnyCredentials, {\n      accessKey: Redacted.isRedacted(accessKey)\n        ? accessKey\n        : Redacted.make(accessKey),\n    });\n\n  /**\n   * A layer reading the key from configuration (the environment by default).\n   *\n   * With a name, it reads that name only. Without one, it reads\n   * `BUNNYNET_API_KEY`, then the deprecated `BUNNY_API_KEY` when that is\n   * unset; the fallback goes away in the next major.\n   */\n  static readonly fromEnv = (\n    name?: string,\n  ): Layer.Layer<BunnyCredentials, Config.ConfigError> =>\n    Layer.effect(\n      BunnyCredentials,\n      (name === undefined\n        ? Config.Redacted(\"BUNNYNET_API_KEY\").pipe(\n          Config.orElse(() => Config.Redacted(\"BUNNY_API_KEY\")),\n        )\n        : Config.Redacted(name)).pipe(\n          Effect.map((accessKey) => ({ accessKey })),\n        ),\n    );\n}\n"]}

package/dist/src/errors.d.ts

@@ -0,0 +1,64 @@
+import { type Schema } from "effect";
+import type { HttpClientError } from "effect/http";
+declare const BunnyInputError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BunnyInputError";
+} & Readonly<A>;
+/** The caller's input did not satisfy the operation's input schema. */
+export declare class BunnyInputError extends BunnyInputError_base<{
+    readonly operation: string;
+    readonly cause: Schema.SchemaError;
+}> {
+    get message(): string;
+}
+declare const BunnyResponseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BunnyResponseError";
+} & Readonly<A>;
+/**
+ * The API answered with a status the spec documents as an error. `response`
+ * is `{ status, value }` with `value` decoded by that status's schema, so
+ * the error channel is as typed as the success channel.
+ */
+export declare class BunnyResponseError<R = {
+    readonly status: number;
+    readonly value: unknown;
+}> extends BunnyResponseError_base<{
+    readonly operation: string;
+    readonly response: R;
+}> {
+    get message(): string;
+}
+declare const BunnyDecodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BunnyDecodeError";
+} & Readonly<A>;
+/**
+ * The API answered with a documented status but a body the schema rejects.
+ * This is the spec-drift signal: the fix belongs in a `patches.ts` next to
+ * the surface's barrel, not in the caller.
+ */
+export declare class BunnyDecodeError extends BunnyDecodeError_base<{
+    readonly operation: string;
+    readonly status: number;
+    readonly cause: Schema.SchemaError;
+}> {
+    get message(): string;
+}
+declare const BunnyUnexpectedStatusError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BunnyUnexpectedStatusError";
+} & Readonly<A>;
+/** The API answered with a status the spec does not document at all. `body` is the raw payload (JSON-parsed when possible). */
+export declare class BunnyUnexpectedStatusError extends BunnyUnexpectedStatusError_base<{
+    readonly operation: string;
+    readonly status: number;
+    readonly body: unknown;
+}> {
+    get message(): string;
+}
+/**
+ * Everything an operation can fail with besides its own typed
+ * `BunnyResponseError`. `HttpClientError` covers transport failures
+ * (connection, timeout, malformed body) and comes straight from Effect's
+ * `effect/http`: one class, tagged `"HttpClientError"`, whose `reason`
+ * (`TransportError`, `StatusCodeError`, …) says what happened.
+ */
+export type BunnyClientError = BunnyInputError | BunnyDecodeError | BunnyUnexpectedStatusError | HttpClientError.HttpClientError;
+export {};

package/dist/src/errors.js

@@ -0,0 +1,35 @@
+import { Data } from "effect";
+/** The caller's input did not satisfy the operation's input schema. */
+export class BunnyInputError extends Data.TaggedError("BunnyInputError") {
+    get message() {
+        return `${this.operation}: invalid input — ${this.cause.message}`;
+    }
+}
+/**
+ * The API answered with a status the spec documents as an error. `response`
+ * is `{ status, value }` with `value` decoded by that status's schema, so
+ * the error channel is as typed as the success channel.
+ */
+export class BunnyResponseError extends Data.TaggedError("BunnyResponseError") {
+    get message() {
+        const status = this.response.status;
+        return `${this.operation}: HTTP ${status ?? "?"}`;
+    }
+}
+/**
+ * The API answered with a documented status but a body the schema rejects.
+ * This is the spec-drift signal: the fix belongs in a `patches.ts` next to
+ * the surface's barrel, not in the caller.
+ */
+export class BunnyDecodeError extends Data.TaggedError("BunnyDecodeError") {
+    get message() {
+        return `${this.operation}: HTTP ${this.status} body does not match the spec — ${this.cause.message}`;
+    }
+}
+/** The API answered with a status the spec does not document at all. `body` is the raw payload (JSON-parsed when possible). */
+export class BunnyUnexpectedStatusError extends Data.TaggedError("BunnyUnexpectedStatusError") {
+    get message() {
+        return `${this.operation}: unexpected HTTP ${this.status}`;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAe,MAAM,QAAQ,CAAC;AAG3C,uEAAuE;AACvE,MAAM,OAAO,eAAgB,SAAQ,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAGrE;IACA,IAAa,OAAO;QAClB,OAAO,GAAG,IAAI,CAAC,SAAS,qBAAqB,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IACpE,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAEX,SAAQ,IAAI,CAAC,WAAW,CAAC,oBAAoB,CAG7C;IACA,IAAa,OAAO;QAClB,MAAM,MAAM,GAAI,IAAI,CAAC,QAAgC,CAAC,MAAM,CAAC;QAC7D,OAAO,GAAG,IAAI,CAAC,SAAS,UAAU,MAAM,IAAI,GAAG,EAAE,CAAC;IACpD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAIvE;IACA,IAAa,OAAO;QAClB,OAAO,GAAG,IAAI,CAAC,SAAS,UAAU,IAAI,CAAC,MAAM,mCAAmC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IACvG,CAAC;CACF;AAED,+HAA+H;AAC/H,MAAM,OAAO,0BACX,SAAQ,IAAI,CAAC,WAAW,CAAC,4BAA4B,CAInD;IACF,IAAa,OAAO;QAClB,OAAO,GAAG,IAAI,CAAC,SAAS,qBAAqB,IAAI,CAAC,MAAM,EAAE,CAAC;IAC7D,CAAC;CACF","sourcesContent":["import { Data, type Schema } from \"effect\";\nimport type { HttpClientError } from \"effect/http\";\n\n/** The caller's input did not satisfy the operation's input schema. */\nexport class BunnyInputError extends Data.TaggedError(\"BunnyInputError\")<{\n  readonly operation: string;\n  readonly cause: Schema.SchemaError;\n}> {\n  override get message(): string {\n    return `${this.operation}: invalid input — ${this.cause.message}`;\n  }\n}\n\n/**\n * The API answered with a status the spec documents as an error. `response`\n * is `{ status, value }` with `value` decoded by that status's schema, so\n * the error channel is as typed as the success channel.\n */\nexport class BunnyResponseError<\n  R = { readonly status: number; readonly value: unknown },\n> extends Data.TaggedError(\"BunnyResponseError\")<{\n  readonly operation: string;\n  readonly response: R;\n}> {\n  override get message(): string {\n    const status = (this.response as { status?: number }).status;\n    return `${this.operation}: HTTP ${status ?? \"?\"}`;\n  }\n}\n\n/**\n * The API answered with a documented status but a body the schema rejects.\n * This is the spec-drift signal: the fix belongs in a `patches.ts` next to\n * the surface's barrel, not in the caller.\n */\nexport class BunnyDecodeError extends Data.TaggedError(\"BunnyDecodeError\")<{\n  readonly operation: string;\n  readonly status: number;\n  readonly cause: Schema.SchemaError;\n}> {\n  override get message(): string {\n    return `${this.operation}: HTTP ${this.status} body does not match the spec — ${this.cause.message}`;\n  }\n}\n\n/** The API answered with a status the spec does not document at all. `body` is the raw payload (JSON-parsed when possible). */\nexport class BunnyUnexpectedStatusError\n  extends Data.TaggedError(\"BunnyUnexpectedStatusError\")<{\n    readonly operation: string;\n    readonly status: number;\n    readonly body: unknown;\n  }> {\n  override get message(): string {\n    return `${this.operation}: unexpected HTTP ${this.status}`;\n  }\n}\n\n/**\n * Everything an operation can fail with besides its own typed\n * `BunnyResponseError`. `HttpClientError` covers transport failures\n * (connection, timeout, malformed body) and comes straight from Effect's\n * `effect/http`: one class, tagged `\"HttpClientError\"`, whose `reason`\n * (`TransportError`, `StatusCodeError`, …) says what happened.\n */\nexport type BunnyClientError =\n  | BunnyInputError\n  | BunnyDecodeError\n  | BunnyUnexpectedStatusError\n  | HttpClientError.HttpClientError;\n"]}

package/dist/src/operation.d.ts

@@ -0,0 +1,99 @@
+import { Effect, Schema } from "effect";
+import { type HttpClient } from "effect/http";
+import type { BunnyCredentialsShape } from "./credentials.js";
+import { type BunnyClientError, BunnyResponseError } from "./errors.js";
+/** How a response body is read before (or instead of) schema decoding. `stream` is read fully, like `binary`. */
+export type ResponseKind = "json" | "text" | "empty" | "binary" | "stream";
+/**
+ * Any schema with no decoding and no encoding services: `Codec` is covariant
+ * in its type parameters, so every concrete schema is assignable here, and
+ * the `never` services pin every operation to `R = never`, whatever schema the
+ * generator emits (`Schema.Top` would widen the services to `unknown`).
+ */
+export type ServiceFreeCodec = Schema.Codec<unknown, unknown, never, never>;
+export interface ResponseEntry {
+    readonly schema: ServiceFreeCodec;
+    readonly kind: ResponseKind;
+}
+/** Status code (or `"default"`) → how to read + decode that response. */
+export type ResponseSpec = Record<string, ResponseEntry>;
+export type ResponseValue<T extends ResponseEntry> = T["kind"] extends "stream" | "binary" ? ArrayBuffer : T["schema"]["Type"];
+/** The `{ status, value }` union an operation resolves (or fails) with, one member per documented status. */
+export type ResponseUnion<T extends ResponseSpec> = {
+    [K in keyof T]: K extends "default" ? {
+        readonly status: number;
+        readonly value: ResponseValue<T[K]>;
+    } : K extends `${infer N extends number}` ? {
+        readonly status: N;
+        readonly value: ResponseValue<T[K]>;
+    } : K extends number ? {
+        readonly status: K;
+        readonly value: ResponseValue<T[K]>;
+    } : {
+        readonly status: number;
+        readonly value: ResponseValue<T[K]>;
+    };
+}[keyof T];
+/** The typed failure for an operation's documented error statuses (`never` when the spec documents none). */
+export type OperationFailure<E extends ResponseSpec | undefined> = E extends ResponseSpec ? BunnyResponseError<ResponseUnion<E>> : never;
+export type SecurityScheme = {
+    readonly type: "http";
+    readonly scheme: "bearer" | "basic";
+    readonly description?: string;
+} | {
+    readonly type: "apiKey";
+    readonly in: "header" | "query" | "cookie";
+    readonly name: string;
+    readonly description?: string;
+} | {
+    readonly type: "oauth2";
+    readonly flows: unknown;
+    readonly description?: string;
+} | {
+    readonly type: "openIdConnect";
+    readonly openIdConnectUrl: string;
+    readonly description?: string;
+};
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+export interface OperationDescriptor<S extends ResponseSpec, E extends ResponseSpec | undefined = undefined> {
+    /** Operation id, used in error messages and the tracing span name. */
+    readonly name: string;
+    readonly method: HttpMethod;
+    /** Path template with `{param}` placeholders. */
+    readonly path: string;
+    /** The spec's server URL for this operation; `ClientOptions.baseUrl` overrides it. */
+    readonly baseUrl?: string;
+    /** How the credential is sent. Omit for unauthenticated operations. */
+    readonly security?: SecurityScheme;
+    /** `{ path?, query?, headers?, body? }` schema; omit when the operation takes no input. Its encoded side is checked against `DecodedInput`. */
+    readonly input?: Schema.Codec<unknown, DecodedInput, never, never>;
+    /** Request body content type; defaults to JSON. */
+    readonly contentType?: string;
+    readonly success: S;
+    readonly error?: E;
+}
+/** Per-client options every generated `layer(options)` accepts. */
+export interface ClientOptions {
+    /** Overrides the spec's server URL — e.g. to point a client at a staging host. */
+    readonly baseUrl?: string;
+}
+/** What a generated service captures once at layer construction. */
+export interface ClientContext {
+    readonly http: HttpClient.HttpClient;
+    readonly credentials: BunnyCredentialsShape;
+    readonly options: ClientOptions;
+}
+/** The encoded form of an operation's input: what the generated input schema must encode to. */
+export type DecodedInput = {
+    readonly path?: Record<string, unknown>;
+    readonly query?: Record<string, unknown>;
+    readonly headers?: Record<string, unknown>;
+    readonly body?: unknown;
+};
+/**
+ * Run one operation: decode the input, build the request, send it through
+ * the caller's `HttpClient`, and decode the response by status. Resolves
+ * with `{ status, value }` for documented success statuses, fails with a
+ * typed `BunnyResponseError` for documented error statuses.
+ */
+export declare const executeOperation: <S extends ResponseSpec, E extends ResponseSpec | undefined>(ctx: ClientContext, op: OperationDescriptor<S, E>, input: unknown) => Effect.Effect<ResponseUnion<S>, BunnyClientError | OperationFailure<E>, never>;