@distilled.cloud/core 0.30.3 → 1.0.0-rc.2

package/src/client.ts

@@ -1,1177 +0,0 @@
-/**
- * REST API Client
- *
- * Provides the core API.make() factory for building typed Effect-based API operations.
- * This is the shared client for REST/OpenAPI-style SDKs (PlanetScale, Neon, GCP).
- *
- * AWS and Cloudflare have their own more specialized client implementations,
- * but they share the same OperationMethod pattern.
- *
- * @example
- * ```ts
- * import { API } from "@distilled.cloud/core/client";
- *
- * const listDatabases = API.make(() => ({
- *   inputSchema: ListDatabasesInput,
- *   outputSchema: ListDatabasesOutput,
- *   errors: [NotFound, Forbidden] as const,
- * }));
- *
- * // Direct call
- * const result = yield* listDatabases({ organization: "my-org" });
- *
- * // Yield first for requirement-free function
- * const fn = yield* listDatabases;
- * const result = yield* fn({ organization: "my-org" });
- * ```
- */
-import * as Config from "effect/Config";
-import * as Context from "effect/Context";
-import * as Effect from "effect/Effect";
-import { pipe } from "effect/Function";
-import * as Option from "effect/Option";
-import { pipeArguments } from "effect/Pipeable";
-import * as Ref from "effect/Ref";
-import { MinimumLogLevel } from "effect/References";
-import * as Schema from "effect/Schema";
-import * as AST from "effect/SchemaAST";
-import * as Stream from "effect/Stream";
-import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
-import * as HttpBody from "effect/unstable/http/HttpBody";
-import * as HttpClient from "effect/unstable/http/HttpClient";
-import * as HttpClientError from "effect/unstable/http/HttpClientError";
-import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
-import { SingleShotGen } from "effect/Utils";
-import {
-  extractItems,
-  paginateWithDefaults,
-  type PaginatedTrait,
-  type PaginationStrategy,
-} from "./pagination.ts";
-import { makeDefault, type Policy as RetryPolicy } from "./retry.ts";
-import * as Traits from "./traits.ts";
-import { getPath } from "./traits.ts";
-
-// `DISTILLED_DEBUG=1` forces the MinimumLogLevel to Debug for SDK operations,
-// independent of the caller's logger config. Users who set `MinimumLogLevel`
-// to Debug themselves get the same logs without needing the env var.
-const distilledDebugConfig: Effect.Effect<boolean> = Config.string(
-  "DISTILLED_DEBUG",
-)
-  .pipe(Config.map((raw) => raw === "1"))
-  .pipe(Effect.orElseSucceed(() => false));
-
-// ============================================================================
-// Client Types
-// ============================================================================
-
-/**
- * An operation that can be used in two ways:
- * 1. Direct call: `yield* operation(input)` - returns Effect with requirements
- * 2. Yield first: `const fn = yield* operation` - captures services, returns requirement-free function
- */
-export type OperationMethod<I, A, E, R, RequestOptions = never> = Effect.Effect<
-  (input: I, requestOptions?: RequestOptions) => Effect.Effect<A, E, never>,
-  never,
-  R
-> &
-  ((input: I, requestOptions?: RequestOptions) => Effect.Effect<A, E, R>);
-
-/**
- * A paginated operation that additionally has `.pages()` and `.items()` methods.
- */
-type PaginatedItem<A> =
-  A extends ReadonlyArray<infer Item>
-    ? Item
-    : A extends { result: ReadonlyArray<infer Item> }
-      ? Item
-      : A extends { result?: ReadonlyArray<infer Item> | null | undefined }
-        ? Item
-        : A extends { result: { items: ReadonlyArray<infer Item> } }
-          ? Item
-          : A extends {
-                result?:
-                  | {
-                      items?: ReadonlyArray<infer Item> | null | undefined;
-                    }
-                  | null
-                  | undefined;
-              }
-            ? Item
-            : unknown;
-
-export type PaginatedOperationMethod<
-  I,
-  A,
-  E,
-  R,
-  RequestOptions = never,
-> = OperationMethod<I, A, E, R, RequestOptions> & {
-  pages: (input: I, requestOptions?: RequestOptions) => Stream.Stream<A, E, R>;
-  items: (
-    input: I,
-    requestOptions?: RequestOptions,
-  ) => Stream.Stream<PaginatedItem<A>, E, R>;
-};
-
-type ResolvedClientCredentials<Creds> =
-  Creds extends Effect.Effect<infer Resolved, any, any> ? Resolved : Creds;
-
-const isEffectLike = (value: unknown): value is Effect.Effect<unknown> =>
-  typeof value === "object" &&
-  value !== null &&
-  typeof (value as { pipe?: unknown }).pipe === "function" &&
-  typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] ===
-    "function";
-
-/**
- * Configuration for the API client factory.
- * SDKs provide this to customize how errors are matched and credentials are applied.
- */
-export interface ClientConfig<Creds, RequestOptions = never> {
-  /** The credentials service tag */
-  credentials: Context.ServiceClass<any, any, Effect.Effect<Creds>>;
-
-  /** Get the base URL from credentials */
-  getBaseUrl: (creds: ResolvedClientCredentials<Creds>) => string;
-
-  /** Get authorization header(s) from credentials */
-  getAuthHeaders: (
-    creds: ResolvedClientCredentials<Creds>,
-  ) => Record<string, string>;
-
-  /**
-   * Map provider-specific per-call request options into transport headers.
-   * Request options are intentionally separate from the operation input and
-   * are never passed through the body/query/path schema encoder.
-   */
-  getRequestHeaders?: (
-    requestOptions: RequestOptions | undefined,
-    context: {
-      input: Record<string, unknown>;
-      method: string;
-      pathTemplate: string;
-      parts: Traits.RequestParts;
-      credentials: ResolvedClientCredentials<Creds>;
-    },
-  ) => Record<string, string>;
-
-  /** Match an error response body to a typed error.
-   *  Should return Effect.fail(error) for known errors,
-   *  or Effect.fail(fallbackError) for unknown errors.
-   *  The optional `errors` parameter provides per-operation typed error classes.
-   *  The optional `headers` parameter is the response header bag (lowercase
-   *  keys) — for retryable status codes, pass `retryAfter: parseRetryAfterForStatus(status, headers)`
-   *  from `@distilled.cloud/core/retry-after` when a standard `Retry-After` /
-   *  `RateLimit` hint is present; omit `retryAfter` when there is no hint (the
-   *  default retry policy still uses exponential backoff). The status-gated
-   *  helper avoids attaching stale `retryAfter` to non-retryable classes
-   *  (BadRequest/401/404/etc.). The maximum honored hint is capped (default
-   *  60s) — override with \`DISTILLED_SERVER_RETRY_HINT_CAP_MS\` or provide
-   *  \`ServerRetryHintCapMs\` via \`Layer\` from \`@distilled.cloud/core/retry\`.
-   */
-  matchError: (
-    status: number,
-    body: unknown,
-    errors?: readonly ApiErrorClass[],
-    headers?: Record<string, string | undefined>,
-  ) => Effect.Effect<never, unknown>;
-
-  /** Parse error class for schema decode failures */
-  ParseError: new (props: { body: unknown; cause: unknown }) => unknown;
-
-  /**
-   * Optional transform applied to the response body before schema decoding.
-   * For example, Cloudflare wraps responses in `{ result: <data>, ... }`.
-   */
-  transformResponse?: (body: unknown) => unknown;
-
-  /**
-   * Optional predicate identifying a successful-status (2xx) response whose
-   * body is actually an error envelope. Some APIs (notably Cloudflare) return
-   * errors with HTTP 200 and a `success: false` flag instead of a 4xx status.
-   * When this returns `true`, the body is routed through {@link matchError}
-   * (with the operation's typed `errors`) exactly like a status>=400 response,
-   * so per-operation typed error matchers still apply. SDKs that always signal
-   * errors via status codes leave this unset (the default no-ops).
-   */
-  isErrorEnvelope?: (body: unknown) => boolean;
-
-  /**
-   * Optional transform applied to encoded request parts before building the
-   * outbound HTTP request.
-   */
-  transformRequestParts?: (input: {
-    input: Record<string, unknown>;
-    method: string;
-    pathTemplate: string;
-    parts: Traits.RequestParts;
-    requestOptions: RequestOptions | undefined;
-  }) => Traits.RequestParts;
-
-  /**
-   * The SDK's `Retry` Context.Service tag. Each per-SDK client wires its
-   * own tag here so callers can install a blanket policy at the layer
-   * level (e.g. `myEffect.pipe(Cloudflare.Retry.transient)`) and have
-   * every API call below it pick it up — same pattern as
-   * `packages/aws/src/client/api.ts`.
-   *
-   * `makeAPI` reads the policy via `Effect.serviceOption(retry)` on every
-   * call and falls back to `Retry.makeDefault` (transient/throttling/server
-   * with capped exponential backoff + jitter, 5 attempts) when no policy
-   * is provided.
-   */
-  retry: Context.Key<any, RetryPolicy>;
-}
-
-/**
- * Base API error type - any error class with at least a _tag and message.
- * Uses `new (...args: any[])` to accommodate error classes with extra fields (e.g. `code`).
- */
-export type ApiErrorClass = {
-  new (...args: any[]): {
-    readonly _tag: string;
-    readonly message: string;
-  };
-};
-
-/**
- * Operation configuration with optional operation-specific errors.
- * Supports both `inputSchema`/`outputSchema` and `input`/`output` aliases.
- */
-export interface OperationConfig<
-  I extends Schema.Top,
-  O extends Schema.Top,
-  E extends readonly ApiErrorClass[] = readonly ApiErrorClass[],
-> {
-  inputSchema?: I;
-  outputSchema?: O;
-  /** Alias for inputSchema (used by Cloudflare/GCP generators) */
-  input?: I;
-  /** Alias for outputSchema (used by Cloudflare/GCP generators) */
-  output?: O;
-  errors?: E;
-}
-
-/**
- * Paginated operation configuration.
- */
-export interface PaginatedOperationConfig<
-  I extends Schema.Top,
-  O extends Schema.Top,
-  E extends readonly ApiErrorClass[] = readonly ApiErrorClass[],
-> extends OperationConfig<I, O, E> {
-  pagination?: PaginatedTrait;
-}
-
-// ============================================================================
-// AST Helpers
-// ============================================================================
-
-/**
- * Check if a schema AST represents an array type.
- * Follows encoding chains and Suspend wrappers.
- */
-function isArrayAST(ast: AST.AST): boolean {
-  if (ast._tag === "Arrays") return true;
-  if (ast._tag === "Suspend") return isArrayAST(ast.thunk());
-  if (ast.encoding && ast.encoding.length > 0)
-    return isArrayAST(ast.encoding[0].to);
-  return false;
-}
-
-/**
- * Resolve a (possibly `Schema.suspend`-wrapped) AST down to the concrete
- * underlying node by forcing the memoized thunk. Generated SDK schemas may
- * wrap each request/response struct in `Schema.suspend(() => ...)` so the
- * (expensive) schema construction is deferred from module-load time to the
- * first time the operation is actually called. Trait extraction needs the
- * real node, so we force it here. `Suspend.thunk` memoizes, so this only
- * pays the construction cost once per operation. Returns the input AST
- * untouched when it isn't a Suspend (the common case for non-suspended SDKs).
- */
-function resolveAst(ast: AST.AST): AST.AST {
-  return ast._tag === "Suspend" ? resolveAst(ast.thunk()) : ast;
-}
-
-// ============================================================================
-// Form URL-Encoded Builder (Stripe deepObject style)
-// ============================================================================
-
-/**
- * Recursively flatten a nested object into Stripe-style bracket notation
- * for application/x-www-form-urlencoded encoding.
- *
- * Examples:
- *   { amount: 2000 } -> "amount=2000"
- *   { shipping: { address: { city: "SF" } } } -> "shipping[address][city]=SF"
- *   { expand: ["data"] } -> "expand[0]=data"
- *   { metadata: { key: "val" } } -> "metadata[key]=val"
- */
-function flattenToFormPairs(
-  obj: Record<string, unknown>,
-  prefix: string = "",
-): Array<[string, string]> {
-  const pairs: Array<[string, string]> = [];
-
-  for (const [key, value] of Object.entries(obj)) {
-    if (value === undefined || value === null) continue;
-
-    const fullKey = prefix ? `${prefix}[${key}]` : key;
-
-    if (Array.isArray(value)) {
-      for (let i = 0; i < value.length; i++) {
-        const item = value[i];
-        if (
-          item !== null &&
-          item !== undefined &&
-          typeof item === "object" &&
-          !Array.isArray(item)
-        ) {
-          pairs.push(
-            ...flattenToFormPairs(
-              item as Record<string, unknown>,
-              `${fullKey}[${i}]`,
-            ),
-          );
-        } else if (item !== undefined && item !== null) {
-          pairs.push([`${fullKey}[${i}]`, String(item)]);
-        }
-      }
-    } else if (typeof value === "object") {
-      pairs.push(
-        ...flattenToFormPairs(value as Record<string, unknown>, fullKey),
-      );
-    } else if (typeof value === "boolean") {
-      pairs.push([fullKey, value ? "true" : "false"]);
-    } else {
-      pairs.push([fullKey, String(value)]);
-    }
-  }
-
-  return pairs;
-}
-
-/**
- * Build a URLSearchParams from a nested object using Stripe deepObject encoding.
- */
-function buildFormUrlEncoded(body: Record<string, unknown>): string {
-  const pairs = flattenToFormPairs(body);
-  const params = new URLSearchParams();
-  for (const [key, value] of pairs) {
-    params.append(key, value);
-  }
-  return params.toString();
-}
-
-// ============================================================================
-// Multipart FormData Builder
-// ============================================================================
-
-/**
- * Check if a value is a File or Blob.
- */
-function isFileOrBlob(value: unknown): value is File | Blob {
-  return (
-    (typeof File !== "undefined" && value instanceof File) ||
-    (typeof Blob !== "undefined" && value instanceof Blob)
-  );
-}
-
-/**
- * Build a FormData from a record of body properties.
- * Handles files/blobs, arrays of files, objects (as JSON blobs), and primitives.
- *
- * This is used for multipart operations (e.g., Cloudflare Workers script uploads)
- * where the body contains a mix of metadata objects and file uploads.
- */
-function buildFormData(body: Record<string, unknown>): FormData {
-  const formData = new FormData();
-
-  for (const [key, value] of Object.entries(body)) {
-    if (value === undefined || value === null) continue;
-
-    if (isFileOrBlob(value)) {
-      // Single file/blob
-      formData.append(key, value, value instanceof File ? value.name : key);
-    } else if (
-      Array.isArray(value) &&
-      value.length > 0 &&
-      isFileOrBlob(value[0])
-    ) {
-      // Array of files/blobs — append each individually
-      for (const file of value) {
-        if (isFileOrBlob(file)) {
-          formData.append(
-            file instanceof File ? file.name : key,
-            file,
-            file instanceof File ? file.name : undefined,
-          );
-        }
-      }
-    } else if (typeof value === "object" && value !== null) {
-      // Object → append as JSON string (matches wrangler's formData.set(key, JSON.stringify(value)))
-      formData.append(key, JSON.stringify(value));
-    } else {
-      // Primitive → append as string
-      formData.append(key, String(value));
-    }
-  }
-
-  return formData;
-}
-
-/**
- * Set a raw binary HTTP request body.
- *
- * Used for `T.Http({ contentType: "binary" })` operations (e.g. R2 PutObject)
- * where `parts.body` is the value of the lone `T.HttpBody()` field — wide
- * input types are accepted: `Blob`, `Uint8Array`, `ArrayBuffer`, `string`,
- * web `ReadableStream<Uint8Array>`, or Effect `Stream.Stream<Uint8Array>`.
- * Stream-shaped inputs are sent as true streaming `HttpBody.stream(...)`
- * uploads.
- *
- * The `Content-Type` header is left untouched (the operation's
- * `content-type` header field already populated `parts.headers`).
- */
-function setBinaryBody(
-  request: HttpClientRequest.HttpClientRequest,
-  body: unknown,
-  contentType?: string,
-): Effect.Effect<HttpClientRequest.HttpClientRequest, HttpBody.HttpBodyError> {
-  // The body's own content-type is what the request ultimately sends — pass the
-  // resolved media type (e.g. application/x-ndjson) into the HttpBody so it is
-  // not clobbered back to the octet-stream default.
-  if (body instanceof Uint8Array) {
-    return Effect.succeed(
-      HttpClientRequest.setBody(HttpBody.uint8Array(body, contentType))(
-        request,
-      ),
-    );
-  }
-  if (typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer) {
-    return Effect.succeed(
-      HttpClientRequest.setBody(
-        HttpBody.uint8Array(new Uint8Array(body), contentType),
-      )(request),
-    );
-  }
-  if (typeof Blob !== "undefined" && body instanceof Blob) {
-    // Stream the Blob through `HttpBody.stream` rather than buffering — keeps
-    // memory bounded for large uploads.
-    const blob = body;
-    const blobStream = Stream.fromReadableStream({
-      evaluate: () => blob.stream(),
-      onError: (cause) =>
-        new HttpBody.HttpBodyError({ reason: { _tag: "JsonError" }, cause }),
-    });
-    return Effect.succeed(
-      HttpClientRequest.setBody(HttpBody.stream(blobStream, contentType))(
-        request,
-      ),
-    );
-  }
-  if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream) {
-    const rs = body as ReadableStream<Uint8Array>;
-    const rsStream = Stream.fromReadableStream({
-      evaluate: () => rs,
-      onError: (cause) =>
-        new HttpBody.HttpBodyError({ reason: { _tag: "JsonError" }, cause }),
-    });
-    return Effect.succeed(
-      HttpClientRequest.setBody(HttpBody.stream(rsStream, contentType))(
-        request,
-      ),
-    );
-  }
-  if (Stream.isStream(body as Stream.Stream<unknown, unknown, unknown>)) {
-    // Effect Stream — pass straight through to `HttpBody.stream`.
-    return Effect.succeed(
-      HttpClientRequest.setBody(
-        HttpBody.stream(
-          body as Stream.Stream<Uint8Array, unknown>,
-          contentType,
-        ),
-      )(request),
-    );
-  }
-  if (typeof body === "string") {
-    return Effect.succeed(
-      HttpClientRequest.setBody(HttpBody.text(body, contentType))(request),
-    );
-  }
-  return Effect.fail(
-    new HttpBody.HttpBodyError({
-      reason: { _tag: "JsonError" },
-      cause: new TypeError(
-        `Binary HTTP body must be a Blob, Uint8Array, ArrayBuffer, ReadableStream, Stream<Uint8Array>, or string; got ${
-          body === null ? "null" : typeof body
-        }`,
-      ),
-    }),
-  );
-}
-
-// ============================================================================
-// API Client Factory
-// ============================================================================
-
-/**
- * Creates an API namespace bound to a specific SDK's client configuration.
- *
- * @example
- * ```ts
- * // In planetscale-sdk/src/client.ts
- * export const API = makeAPI({
- *   credentials: Credentials,
- *   getBaseUrl: (c) => c.apiBaseUrl,
- *   getAuthHeaders: (c) => ({ Authorization: c.token }),
- *   matchError: matchPlanetScaleError,
- *   ParseError: PlanetScaleParseError,
- * });
- * ```
- */
-export const makeAPI = <Creds, RequestOptions = never>(
-  config: ClientConfig<Creds, RequestOptions>,
-) => {
-  type _ClientErrors = HttpClientError.HttpClientError | HttpBody.HttpBodyError;
-  type ResolvedCreds = ResolvedClientCredentials<Creds>;
-
-  return {
-    make: <
-      I extends Schema.Top,
-      O extends Schema.Top,
-      const E extends readonly ApiErrorClass[] = readonly [],
-    >(
-      configFn: () => OperationConfig<I, O, E>,
-    ): OperationMethod<
-      Schema.Schema.Type<I>,
-      Schema.Schema.Type<O>,
-      InstanceType<E[number]>,
-      Creds,
-      RequestOptions
-    > => {
-      type Input = Schema.Schema.Type<I>;
-
-      // Lazily resolve the operation config + schema traits on first use,
-      // not at module-load time. Generated SDKs may wrap each request/response
-      // schema in `Schema.suspend(() => ...)`; forcing them here (rather than
-      // when the `export const` is evaluated) keeps importing a service module
-      // cheap and only pays the schema-construction cost for operations that
-      // are actually called. The result is memoized so subsequent calls are
-      // free, and non-suspended SDKs are unaffected (resolveAst is a no-op).
-      type HttpTraitResolved = NonNullable<
-        ReturnType<typeof Traits.getHttpTrait>
-      >;
-      interface Prepared {
-        opConfig: OperationConfig<I, O, E>;
-        inputSchema: I;
-        outputSchema: O;
-        inputAst: AST.AST;
-        outputAst: AST.AST;
-        responsePath: string | undefined;
-        graphqlOp: ReturnType<typeof Traits.getGraphQLOp>;
-        noFollowRedirect: ReturnType<typeof Traits.getNoFollowRedirect>;
-        httpTrait: HttpTraitResolved;
-        method: HttpTraitResolved["method"];
-        spanName: string;
-      }
-      let prepared: Prepared | undefined;
-      const prepare = (): Prepared => {
-        if (prepared) return prepared;
-        const opConfig = configFn();
-        // Support both input/output and inputSchema/outputSchema aliases
-        const inputSchema = (opConfig.inputSchema ?? opConfig.input)!;
-        const outputSchema = (opConfig.outputSchema ?? opConfig.output)!;
-        const inputAst = resolveAst(inputSchema.ast);
-        const outputAst = resolveAst(outputSchema.ast);
-        // Read trait annotations from the *unresolved* schema ASTs. A trait
-        // applied to an already-suspended schema (e.g. `T.ResponsePath` on a
-        // shared, suspended response struct) lives on the Suspend node itself,
-        // which `resolveAst` descends past — so resolving first would drop it.
-        // `getAnnotation` follows Suspend thunks, so the unresolved ast finds
-        // annotations at any suspend depth.
-        const httpTrait = Traits.getHttpTrait(inputSchema.ast);
-        if (!httpTrait) {
-          throw new Error("Input schema must have Http trait");
-        }
-        const method = httpTrait.method;
-        prepared = {
-          opConfig,
-          inputSchema,
-          outputSchema,
-          inputAst,
-          outputAst,
-          responsePath: Traits.getResponsePath(outputSchema.ast),
-          graphqlOp: Traits.getGraphQLOp(inputSchema.ast),
-          noFollowRedirect: Traits.getNoFollowRedirect(inputSchema.ast),
-          httpTrait,
-          method,
-          spanName: `${method} ${httpTrait.path}`,
-        };
-        return prepared;
-      };
-
-      const innerFn = (
-        input: Input,
-        requestOptions?: RequestOptions,
-      ): Effect.Effect<any, any, any> =>
-        Effect.gen(function* () {
-          const {
-            opConfig,
-            inputSchema,
-            outputSchema,
-            inputAst,
-            outputAst,
-            responsePath,
-            graphqlOp,
-            noFollowRedirect,
-            httpTrait,
-            method,
-          } = prepare();
-          const credentials = yield* config.credentials;
-          const creds = isEffectLike(credentials)
-            ? yield* credentials
-            : credentials;
-          const client = yield* HttpClient.HttpClient;
-
-          // Fall back to the Service trait when the consumer leaves
-          // `getBaseUrl` empty (per-service hosts rather than per-credentials).
-          let baseUrl = config.getBaseUrl(creds as ResolvedCreds);
-          if (!baseUrl) {
-            const svcTrait = Traits.getServiceTrait(inputAst);
-            if (svcTrait?.rootUrl) {
-              baseUrl = svcTrait.rootUrl + (svcTrait.servicePath ?? "");
-            }
-          }
-          const authHeaders = config.getAuthHeaders(creds as ResolvedCreds);
-
-          // Use schema-aware request builder for proper camelCase → wire_name mapping
-          let parts = Traits.buildRequestParts(
-            inputAst,
-            httpTrait,
-            input as Record<string, unknown>,
-            inputSchema,
-          );
-
-          // GraphQL: wrap variables in the standard GraphQL request envelope.
-          // All input fields become `variables`; `query` and `operationName`
-          // come from the trait (baked in at generation time).
-          if (graphqlOp) {
-            parts = {
-              ...parts,
-              body: {
-                query: graphqlOp.query,
-                operationName: graphqlOp.operationName,
-                variables: parts.body ?? {},
-              },
-            };
-          }
-
-          if (config.transformRequestParts) {
-            parts = config.transformRequestParts({
-              input: input as Record<string, unknown>,
-              method,
-              pathTemplate: httpTrait.path,
-              parts,
-              requestOptions,
-            });
-          }
-
-          // Inject a baked-in `api-version` query param for versioned APIs
-          // (e.g. Azure ARM, where it is required on every call and differs per
-          // resource provider). Applied for all methods; a caller-supplied
-          // `api-version` already present in the query takes precedence.
-          if (
-            httpTrait.apiVersion &&
-            parts.query["api-version"] === undefined
-          ) {
-            parts = {
-              ...parts,
-              query: { ...parts.query, "api-version": httpTrait.apiVersion },
-            };
-          }
-
-          const requestHeaders =
-            config.getRequestHeaders?.(requestOptions, {
-              input: input as Record<string, unknown>,
-              method,
-              pathTemplate: httpTrait.path,
-              parts,
-              credentials: creds as ResolvedCreds,
-            }) ?? {};
-
-          let request = HttpClientRequest.make(method)(
-            baseUrl + parts.path,
-          ).pipe(
-            HttpClientRequest.setHeaders(authHeaders),
-            HttpClientRequest.setHeaders(parts.headers),
-            HttpClientRequest.setHeaders(requestHeaders),
-            HttpClientRequest.setHeader("Accept", "application/json"),
-          );
-
-          // Set Content-Type based on body type
-          // - Skip for FormData (multipart) — browser sets boundary
-          // - Skip for binary — `parts.headers` already carries a caller-supplied
-          //   `content-type` header (e.g. R2 PutObject's `content-type` field)
-          // - Use form-urlencoded for Stripe-style APIs
-          // - Default to JSON
-          const isFormUrlEncoded = httpTrait.contentType === "form-urlencoded";
-          const isBinaryBody = httpTrait.contentType === "binary";
-          if (parts.isMultipart) {
-            // browser/runtime sets Content-Type with boundary
-          } else if (isBinaryBody) {
-            // Content-Type is applied via the body below (setBinaryBody), so it
-            // is not clobbered back to octet-stream by `setBody`.
-          } else if (isFormUrlEncoded) {
-            request = HttpClientRequest.setHeader(
-              "Content-Type",
-              "application/x-www-form-urlencoded",
-            )(request);
-          } else {
-            request = HttpClientRequest.setHeader(
-              "Content-Type",
-              "application/json",
-            )(request);
-          }
-
-          if (Object.keys(parts.query).length > 0) {
-            request = HttpClientRequest.setUrlParams(request, parts.query);
-          }
-          if (method !== "GET" && parts.body !== undefined) {
-            if (parts.isMultipart) {
-              // Build FormData from body properties for multipart operations
-              const formData = buildFormData(
-                parts.body as Record<string, unknown>,
-              );
-              request = HttpClientRequest.setBody(HttpBody.formData(formData))(
-                request,
-              );
-            } else if (isBinaryBody) {
-              // Raw binary HTTP body — `parts.body` is the value of the lone
-              // `T.HttpBody()` field (e.g. a `Blob`, `Uint8Array`, or string),
-              // not a record of body fields. Caller's `content-type` header
-              // wins, then the op's `bodyMediaType`, else octet-stream.
-              const binaryContentType =
-                (parts.headers["content-type"] as string | undefined) ??
-                (parts.headers["Content-Type"] as string | undefined) ??
-                httpTrait.bodyMediaType ??
-                "application/octet-stream";
-              request = yield* setBinaryBody(
-                request,
-                parts.body,
-                binaryContentType,
-              );
-            } else if (isFormUrlEncoded) {
-              // Encode body as form-urlencoded with deepObject bracket notation
-              const encoded = buildFormUrlEncoded(
-                parts.body as Record<string, unknown>,
-              );
-              request = HttpClientRequest.setBody(
-                HttpBody.text(encoded, "application/x-www-form-urlencoded"),
-              )(request);
-            } else {
-              request = yield* HttpClientRequest.bodyJson(parts.body)(request);
-            }
-          } else if (method === "GET" && parts.body !== undefined) {
-            // For GET requests, remaining non-annotated fields go as query params
-            const extraQuery: Record<string, string> = {};
-            for (const [key, value] of Object.entries(
-              parts.body as Record<string, unknown>,
-            )) {
-              if (value !== undefined) {
-                extraQuery[key] = String(value);
-              }
-            }
-            if (Object.keys(extraQuery).length > 0) {
-              request = HttpClientRequest.setUrlParams(request, extraQuery);
-            }
-          }
-
-          const requestUrl = baseUrl + parts.path;
-          yield* Effect.logDebug(`→ ${method} ${requestUrl}`);
-
-          // For operations that opt out of following redirects, hand the
-          // underlying fetch a `redirect: "manual"` request init so the
-          // 3xx surfaces here instead of being chased to the IdP.
-          const executeRequest = noFollowRedirect
-            ? client.execute(request).pipe(
-                Effect.scoped,
-                Effect.provideService(FetchHttpClient.RequestInit, {
-                  redirect: "manual",
-                } as RequestInit),
-              )
-            : client.execute(request).pipe(Effect.scoped);
-
-          const response = yield* executeRequest;
-          yield* Effect.logDebug(
-            `← ${response.status} ${method} ${requestUrl}`,
-          );
-
-          // For ops that opted out of redirect-following, treat 3xx as
-          // success: synthesize a body containing the Location header
-          // value at `locationField` (default `"url"`) and feed that
-          // through the normal output schema decode below.
-          if (
-            noFollowRedirect &&
-            response.status >= 300 &&
-            response.status < 400
-          ) {
-            const location =
-              response.headers["location"] ?? response.headers["Location"];
-            if (location !== undefined) {
-              const synthBody = {
-                [noFollowRedirect.locationField ?? "url"]: location,
-              };
-              return yield* Schema.decodeUnknownEffect(outputSchema)(
-                synthBody,
-              ).pipe(
-                Effect.catchTag("SchemaError", (cause) =>
-                  Effect.fail(
-                    new config.ParseError({ body: synthBody, cause }),
-                  ),
-                ),
-              );
-            }
-          }
-
-          if (response.status >= 400) {
-            // Try to parse error body as JSON; fall back to text if not JSON
-            const errorBody = yield* response.json.pipe(
-              Effect.catchIf(
-                () => true,
-                () =>
-                  response.text.pipe(
-                    Effect.map(
-                      (text) =>
-                        ({ _nonJsonError: true, body: text }) as unknown,
-                    ),
-                    Effect.catchIf(
-                      () => true,
-                      () =>
-                        Effect.succeed({
-                          _nonJsonError: true,
-                          body: `HTTP ${response.status}`,
-                        } as unknown),
-                    ),
-                  ),
-              ),
-            );
-            return yield* config.matchError(
-              response.status,
-              errorBody,
-              opConfig.errors,
-              response.headers,
-            );
-          }
-
-          // For void-returning operations (e.g. DELETE 204 No Content)
-          if (AST.isVoid(outputAst)) {
-            return undefined;
-          }
-
-          // Raw octet-stream download (`responseContentType: "binary"`):
-          // bypass the JSON/text decode path entirely. The output schema is
-          // a Struct shaped like `{ body: Stream<Uint8Array>, ...headers }`
-          // (see `T.BinaryResponseBody()` / `T.HttpResponseHeader()`); we
-          // populate it by reading response headers and wrapping the body
-          // bytes in `Stream.succeed`. We buffer through
-          // `response.arrayBuffer` first so the resulting stream is
-          // scope-free — callers can consume it after the underlying scope
-          // has closed. (True chunked streaming would require threading a
-          // Scope through every operation's return type, which would break
-          // the uniform `OperationMethod<I, A, E, never>` shape.)
-          if (httpTrait.responseContentType === "binary") {
-            const bytes = yield* response.arrayBuffer;
-            const stream = Stream.succeed(new Uint8Array(bytes));
-            return Traits.buildBinaryResponse(
-              outputAst,
-              stream,
-              response.headers as Record<string, string>,
-            ) as unknown;
-          }
-
-          // For 204 No Content: if schema is not Unknown, return undefined.
-          // If schema IS Unknown, return empty string (so callers get a defined value).
-          if (response.status === 204) {
-            if (outputAst._tag === "Unknown") {
-              return "";
-            }
-            return undefined;
-          }
-
-          // Try to parse response as JSON; fall back to text for non-JSON responses
-          // (e.g., multipart/form-data worker scripts, raw KV values)
-          const rawBody = yield* response.json.pipe(
-            Effect.catchIf(
-              () => true,
-              () => response.text.pipe(Effect.map((text) => text as unknown)),
-            ),
-          );
-          let responseBody = config.transformResponse
-            ? config.transformResponse(rawBody)
-            : rawBody;
-
-          // GraphQL: surface errors[] (returned with HTTP 200) via matchError,
-          // then leave unwrap to the output schema's `T.ResponsePath` trait,
-          // which the generator emits with the field path from `data`. This
-          // handles namespaced ops (e.g. `data.channels.byId`) uniformly with
-          // top-level ones (e.g. `data.me`).
-          if (graphqlOp) {
-            const envelope = responseBody as
-              | { data?: Record<string, unknown> | null; errors?: unknown[] }
-              | null
-              | undefined;
-            if (
-              envelope &&
-              Array.isArray(envelope.errors) &&
-              envelope.errors.length > 0
-            ) {
-              return yield* config.matchError(
-                response.status,
-                envelope,
-                opConfig.errors,
-                response.headers,
-              );
-            }
-            responseBody = envelope?.data ?? null;
-          }
-
-          // Some APIs return a JSON *string* (double-encoded JSON). `response.json`
-          // then yields a string, `getPath` bails out, and we would decode the wrong
-          // shape (e.g. Cloudflare envelopes without unwrapping `result`).
-          if (typeof responseBody === "string") {
-            try {
-              responseBody = JSON.parse(responseBody) as unknown;
-            } catch {
-              // leave as string for callers that expect raw text
-            }
-          }
-
-          // Some APIs (Cloudflare) answer with a 2xx status but an error
-          // envelope (`success: false`) rather than a 4xx. Route those through
-          // `matchError` with the operation's typed `errors` so per-operation
-          // matchers fire — otherwise the envelope falls through to schema
-          // decoding and surfaces as an opaque ParseError.
-          if (config.isErrorEnvelope?.(responseBody)) {
-            return yield* config.matchError(
-              response.status,
-              responseBody,
-              opConfig.errors,
-              response.headers,
-            );
-          }
-
-          // Tracks a `result: null` success that we optimistically coerce to
-          // `{}` below. Some ops legitimately return `null` (e.g. a per-zone
-          // singleton that was never configured) and declare a nullable
-          // output schema — for those, decoding `{}` fails, so we retry the
-          // decode with `null` (see the decode block).
-          let resultWasNull = false;
-          if (responsePath) {
-            const nested = getPath(responseBody, responsePath);
-            if (nested !== undefined) {
-              if (responsePath === "result" && nested === null) {
-                responseBody = {};
-                resultWasNull = true;
-              } else {
-                responseBody = nested;
-              }
-            }
-          }
-
-          // Handle Cloudflare-style paginated responses where result is
-          // { items: [...] } but the schema expects an array
-          if (
-            isArrayAST(outputAst) &&
-            !Array.isArray(responseBody) &&
-            typeof responseBody === "object" &&
-            responseBody !== null &&
-            "items" in responseBody &&
-            Array.isArray((responseBody as Record<string, unknown>).items)
-          ) {
-            responseBody = (responseBody as Record<string, unknown>).items;
-          }
-
-          // A list operation whose schema is an array, but whose `result` came
-          // back `null` (coerced to `{}` above), is simply an empty collection:
-          // Cloudflare returns `result: null` instead of `[]` when there are
-          // zero items. Coerce to `[]` so the list decodes cleanly rather than
-          // failing the array decode and surfacing as a ParseError.
-          if (resultWasNull && isArrayAST(outputAst)) {
-            responseBody = [];
-            resultWasNull = false;
-          }
-
-          // Distinguish two very different decode failures:
-          //   1. NON-empty body that doesn't match the schema → a genuine
-          //      schema gap in the SDK. Surface as `ParseError` (NOT retryable)
-          //      so it gets patched (Typed Error Doctrine). Retrying it would
-          //      only mask the bug.
-          //   2. EMPTY / null body where a structured response was expected →
-          //      there is nothing to parse. This is a transient, incomplete
-          //      transport response (e.g. the edge answering a 2xx with a bare
-          //      `null`/empty body under load), NOT a schema bug. Surface it as
-          //      a retryable `TransportError` so the bounded retry policy
-          //      re-fetches the real body. (Void/204 and nullable-schema ops
-          //      decode an empty body successfully and never reach here.)
-          const bodyIsEmpty =
-            rawBody === null || rawBody === undefined || rawBody === "";
-          return yield* Schema.decodeUnknownEffect(outputSchema)(
-            responseBody,
-          ).pipe(
-            Effect.catchTag("SchemaError", (cause) =>
-              // A `result: null` success coerced to `{}` that the schema
-              // rejects: retry decoding the genuine `null` (the schema may be
-              // a nullable union). Only then surface the parse error.
-              resultWasNull
-                ? Schema.decodeUnknownEffect(outputSchema)(null).pipe(
-                    Effect.catchTag("SchemaError", () =>
-                      Effect.fail(
-                        new config.ParseError({ body: rawBody, cause }),
-                      ),
-                    ),
-                  )
-                : bodyIsEmpty
-                  ? Effect.fail(
-                      new HttpClientError.HttpClientError({
-                        reason: new HttpClientError.TransportError({
-                          request,
-                          cause,
-                          description:
-                            "Empty response body where a structured response was expected",
-                        }),
-                      }),
-                    )
-                  : Effect.fail(
-                      new config.ParseError({ body: rawBody, cause }),
-                    ),
-            ),
-          );
-        });
-
-      // Auto-retry every operation using the SDK's per-client `Retry`
-      // Context.Service. The policy is read with `Effect.serviceOption`
-      // and falls back to `Retry.makeDefault` (transient/throttling/server
-      // errors with capped exponential backoff + jitter, 5 attempts) when
-      // no policy has been provided in context. This mirrors the AWS
-      // pattern in `packages/aws/src/client/api.ts` and lets callers
-      // install a blanket policy at the layer level instead of wrapping
-      // every call site with `Effect.retry(...)`.
-      const retryTag = config.retry;
-      const fn = (
-        input: Input,
-        requestOptions?: RequestOptions,
-      ): Effect.Effect<any, any, any> => {
-        const { spanName, method, httpTrait } = prepare();
-        const withRetry = Effect.gen(function* () {
-          const lastError = yield* Ref.make<unknown>(undefined);
-          const policy = (yield* Effect.serviceOption(retryTag)).pipe(
-            Option.map((value) =>
-              typeof value === "function" ? value(lastError) : value,
-            ),
-            Option.getOrElse(() => makeDefault(lastError)),
-          );
-
-          return yield* pipe(
-            innerFn(input, requestOptions),
-            Effect.tapError((error) => Ref.set(lastError, error)),
-            policy.while
-              ? (eff) =>
-                  Effect.retry(eff, {
-                    while: policy.while,
-                    schedule: policy.schedule,
-                  })
-              : (eff) => eff,
-          );
-        });
-
-        const withSpan = withRetry.pipe(
-          Effect.withSpan(spanName, {
-            attributes: {
-              "http.method": method,
-              "http.route": httpTrait.path,
-            },
-          }),
-        );
-        return Effect.flatMap(distilledDebugConfig, (isDebug) =>
-          isDebug
-            ? Effect.provideService(withSpan, MinimumLogLevel, "Debug")
-            : withSpan,
-        );
-      };
-
-      const Proto = {
-        [Symbol.iterator](this: any) {
-          return new SingleShotGen(this.asEffect());
-        },
-        pipe(this: any) {
-          return pipeArguments(this.asEffect(), arguments);
-        },
-        asEffect() {
-          return Effect.map(
-            Effect.context(),
-            (context) => (input: Input, requestOptions?: RequestOptions) =>
-              Effect.provideContext(fn(input, requestOptions), context),
-          );
-        },
-      };
-
-      return Object.assign(fn, Proto) as any;
-    },
-
-    makePaginated: <
-      I extends Schema.Top,
-      O extends Schema.Top,
-      const E extends readonly ApiErrorClass[] = readonly [],
-    >(
-      configFn: () => PaginatedOperationConfig<I, O, E>,
-      paginateFn?: PaginationStrategy,
-    ): PaginatedOperationMethod<
-      Schema.Schema.Type<I>,
-      Schema.Schema.Type<O>,
-      InstanceType<E[number]>,
-      Creds,
-      RequestOptions
-    > => {
-      const opConfig = configFn();
-      const pagination = opConfig.pagination!;
-
-      // Create the base operation
-      const baseFn = makeAPI(config).make(() => ({
-        inputSchema: opConfig.inputSchema ?? opConfig.input,
-        outputSchema: opConfig.outputSchema ?? opConfig.output,
-        errors: opConfig.errors,
-      }));
-
-      type Input = Schema.Schema.Type<I>;
-
-      const paginate = paginateFn ?? paginateWithDefaults;
-
-      // Stream all pages
-      const pagesFn = (
-        input: Omit<Input, string>,
-        requestOptions?: RequestOptions,
-      ) => paginate(baseFn as any, input, pagination, requestOptions);
-
-      // Stream individual items
-      const itemsFn = (
-        input: Omit<Input, string>,
-        requestOptions?: RequestOptions,
-      ) =>
-        pagination.items
-          ? extractItems(pagesFn(input, requestOptions), pagination.items)
-          : pagesFn(input, requestOptions);
-
-      const result = baseFn as typeof baseFn & {
-        pages: typeof pagesFn;
-        items: typeof itemsFn;
-      };
-
-      result.pages = pagesFn;
-      result.items = itemsFn;
-
-      return result as any;
-    },
-  };
-};