@distilled.cloud/coinbase 0.30.3 → 1.0.0-rc.10

package/src/{client.ts → protocol.ts}

@@ -1,20 +1,25 @@
 /**
- * Coinbase CDP API Client.
+ * CoinbaseProtocol — hand-written.
  *
- * Wraps the shared REST client from sdk-core with Coinbase CDP-specific
- * error matching, JWT authentication, and credential handling.
+ * Speaks the Coinbase CDP JSON protocol. The generic request/response
+ * machinery (trait-driven request building, recursive wire-name mapping)
+ * lives in `@distilled.cloud/core/protocol-http`; this module supplies what
+ * is Coinbase's own:
  *
  * ## Authentication
  *
- * The Coinbase CDP API uses JWT bearer tokens for authentication. The JWT is
- * signed using your CDP API Key Secret (ES256 or Ed25519) and includes:
+ * The Coinbase CDP API uses per-request JWT bearer tokens. The JWT is signed
+ * with your CDP API Key Secret (ES256 or Ed25519) and includes:
  *
  * - `sub`: Your CDP API Key ID
  * - `iss`: "cdp"
+ * - `aud`: ["cdp_service"]
  * - `exp`: Current time + 120 seconds
+ * - `uri`: "METHOD host/path"
  *
- * Some sensitive wallet operations additionally require an `X-Wallet-Auth`
- * header signed with your Wallet Secret.
+ * Some sensitive wallet operations additionally document an `X-Wallet-Auth`
+ * header signed with your Wallet Secret (`Config.walletSecret`); like the
+ * distilled v0 client, this module does not generate that header.
  *
  * ## Error Handling
  *
@@ -28,28 +33,60 @@
  * }
  * ```
  *
- * Errors are dispatched first by `errorType`, then by HTTP status code.
+ * Errors are handled globally (no per-operation error lists), dispatched
+ * first by `errorType`, then by HTTP status code.
  */
-import { makeAPI } from "@distilled.cloud/core/client";
-import { parseRetryAfterForStatus } from "@distilled.cloud/core/retry-after";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
+import type * as AST from "effect/SchemaAST";
 import * as crypto from "node:crypto";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type * as HttpClientError from "effect/unstable/http/HttpClientError";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import * as API from "@distilled.cloud/core/api";
+import { buildRequest, mapKeys } from "@distilled.cloud/core/protocol-http";
+import {
+  unwrapRedactedDeep,
+  wrapSensitive,
+} from "@distilled.cloud/core/protocol-rest";
+import {
+  type ConfigError,
+  HTTP_STATUS_MAP,
+} from "@distilled.cloud/core/errors";
+import { parseRetryAfterForStatus } from "@distilled.cloud/core/retry-after";
 import type { Config } from "./credentials.ts";
 import { Credentials } from "./credentials.ts";
 import {
   COINBASE_HTTP_STATUS_MAP,
-  CoinbaseParseError,
+  type DefaultErrors,
   ERROR_TYPE_MAP,
-  HTTP_STATUS_MAP,
   STANDARD_ERROR_TYPE_MAP,
   UnknownCoinbaseError,
 } from "./errors.ts";
-import { Retry } from "./retry.ts";
 
-// Re-export for convenience
-export { UnknownCoinbaseError } from "./errors.ts";
+/**
+ * Error channel shared by every generated Coinbase operation. Generated
+ * service files annotate operations with `API.OperationMethod<I, O,
+ * CoinbaseOpError, CoinbaseOpContext>` explicitly so the compiler never
+ * infers these back out of the schema generics.
+ */
+export type CoinbaseOpError =
+  | DefaultErrors
+  | ConfigError
+  | HttpClientError.HttpClientError;
+
+/** Context (requirements) shared by every generated Coinbase operation. */
+export type CoinbaseOpContext = Credentials | HttpClient.HttpClient;
+
+// Bridge: Protocol.decode is typed as Effect<unknown> (no error channel), but
+// Coinbase failures are real typed errors that the operation's explicit
+// `CoinbaseOpError` annotation re-surfaces. Fail with the instance and erase
+// the error type here.
+const fail = (e: unknown): Effect.Effect<never> =>
+  Effect.fail(e) as Effect.Effect<never>;
 
 // ============================================================================
 // JWT generation for Coinbase CDP API authentication
@@ -210,7 +247,8 @@ const CoinbaseErrorResponse = Schema.Struct({
 });
 
 /**
- * Match a Coinbase CDP API error response to the appropriate typed error class.
+ * Match a Coinbase CDP API error response to the appropriate typed error
+ * class. Ported from the distilled v0 client's `matchError`.
  *
  * Dispatches errors by:
  * 1. The `errorType` field for Coinbase-specific errors (e.g., "already_exists", "policy_violation")
@@ -218,13 +256,16 @@ const CoinbaseErrorResponse = Schema.Struct({
  * 3. Standard HTTP status codes mapped from core (400, 401, 403, 404, etc.)
  * 4. Coinbase-specific HTTP status codes (402)
  * 5. Falls back to UnknownCoinbaseError for unrecognized errors
+ *
+ * Error bodies carrying `isValid`/`success` keys are policy-validation
+ * results delivered with an error status — treated as success values
+ * (`Effect.succeed`) like the v0 client did.
  */
 const matchError = (
   status: number,
   errorBody: unknown,
-  _errors?: readonly unknown[],
   headers?: Record<string, string | undefined>,
-): Effect.Effect<unknown, unknown> => {
+): Effect.Effect<unknown> => {
   if (
     errorBody &&
     typeof errorBody === "object" &&
@@ -245,16 +286,16 @@ const matchError = (
     // 1. Match by Coinbase-specific error type first
     const TypedErrorClass = ERROR_TYPE_MAP[parsed.errorType];
     if (TypedErrorClass) {
-      return Effect.fail(new TypedErrorClass(errorProps));
+      return fail(new TypedErrorClass(errorProps));
     }
 
     // 2. Match standard error types to core HTTP error classes
-    // Maps error types like "not_found", "forbidden", "unauthorized", "invalid_request",
-    // "rate_limit_exceeded", "internal_server_error", "bad_gateway", "service_unavailable"
-    // to their corresponding core HTTP error classes.
+    // Maps error types like "not_found", "forbidden", "unauthorized",
+    // "invalid_request", "rate_limit_exceeded", "internal_server_error",
+    // "bad_gateway", "service_unavailable" to core HTTP error classes.
     const StandardErrorClass = STANDARD_ERROR_TYPE_MAP[parsed.errorType];
     if (StandardErrorClass) {
-      return Effect.fail(
+      return fail(
         new StandardErrorClass({
           message: parsed.errorMessage ?? "",
           retryAfter: parseRetryAfterForStatus(status, headers),
@@ -265,7 +306,7 @@ const matchError = (
     // 3. Fall back to HTTP status code mapping from core
     const CoreErrorClass = (HTTP_STATUS_MAP as any)[status];
     if (CoreErrorClass) {
-      return Effect.fail(
+      return fail(
         new CoreErrorClass({
           message: parsed.errorMessage ?? "",
           retryAfter: parseRetryAfterForStatus(status, headers),
@@ -276,49 +317,119 @@ const matchError = (
     // 4. Coinbase-specific HTTP status codes (402)
     const CoinbaseErrorClass = (COINBASE_HTTP_STATUS_MAP as any)[status];
     if (CoinbaseErrorClass) {
-      return Effect.fail(new CoinbaseErrorClass(errorProps));
+      return fail(new CoinbaseErrorClass(errorProps));
     }
 
     // 5. Fall back to unknown error
-    return Effect.fail(
+    return fail(
       new UnknownCoinbaseError({
         ...errorProps,
         body: errorBody,
       }),
     );
   } catch {
-    return Effect.fail(new UnknownCoinbaseError({ body: errorBody }));
+    return fail(new UnknownCoinbaseError({ body: errorBody }));
   }
 };
 
 // ============================================================================
-// API client factory
+// Protocol
 // ============================================================================
 
+// The protocol layer is memoized per process by `API.make`, so the build must
+// not capture credentials — `encode` resolves Credentials from the calling
+// fiber's context on every request instead. Like the error channel above,
+// the requirement is erased at this boundary (Protocol effects are typed with
+// no requirements) and reintroduced for callers by the generated
+// `CoinbaseOpContext` annotations.
+const encode = ({
+  input,
+  inputAst,
+}: {
+  readonly input: unknown;
+  readonly inputAst: AST.AST;
+}) =>
+  Effect.gen(function* () {
+    // The Credentials service holds an effect — resolving it here (per
+    // request) picks up rotations. Its error channel is erased at this
+    // boundary; CoinbaseOpError reintroduces it for callers.
+    const resolveCredentials = yield* Credentials;
+    const creds =
+      (yield* resolveCredentials as Effect.Effect<Config>) as Config;
+
+    // Sensitive input members accept string | Redacted<string>; the wire
+    // wants the raw string.
+    const request = buildRequest({
+      input: unwrapRedactedDeep(input),
+      inputAst,
+      baseUrl: creds.apiBaseUrl,
+    });
+
+    // JWT `uri` claim: "METHOD host/path" — label-substituted path, no query
+    // string (matches the v0 client: baseUrl.host + baseUrl.pathname +
+    // parts.path).
+    const url = new URL(request.url);
+    const jwt = generateJwt(
+      creds.apiKeyId,
+      Redacted.value(creds.apiKeySecret),
+      request.method,
+      `${url.host}${url.pathname}`,
+    );
+    return request.pipe(
+      HttpClientRequest.setHeader("Authorization", `Bearer ${jwt}`),
+    );
+  });
+
+const decode = ({
+  response,
+  outputAst,
+}: {
+  readonly response: HttpClientResponse.HttpClientResponse;
+  readonly outputAst: AST.AST;
+  readonly errors: ReadonlyArray<unknown>;
+}) =>
+  Effect.gen(function* () {
+    const text = (yield* response.text.pipe(Effect.orDie)) ?? "";
+    if (process.env.DISTILLED_DEBUG_HTTP) {
+      console.error(`[distilled] <- ${response.status} ${text.slice(0, 400)}`);
+    }
+    let json: unknown;
+    if (text.trim().length > 0) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = text;
+      }
+    }
+    const status = response.status;
+    const headers = response.headers as Record<string, string | undefined>;
+
+    if (status >= 400) {
+      const result = yield* matchError(status, json, headers);
+      // isValid/success bodies are success values delivered with an error
+      // status — map them onto the output schema like a normal response.
+      return wrapSensitive(outputAst, mapKeys(outputAst, result, "decode"));
+    }
+
+    // No envelope: the response body IS the payload, mapped onto the output
+    // schema (wire names → TS names), with members marked T.SensitiveValue
+    // delivered as Redacted.
+    const body = json === undefined ? {} : json;
+    return wrapSensitive(outputAst, mapKeys(outputAst, body, "decode"));
+  });
+
 /**
- * Coinbase CDP API client.
+ * Coinbase CDP protocol layer.
  *
- * Uses JWT bearer token authentication signed with your CDP API Key Secret.
+ * Uses JWT bearer token authentication signed per request with your CDP API
+ * Key Secret.
  */
-export const API = makeAPI<Credentials>({
-  credentials: Credentials as any,
-  getBaseUrl: (creds: any) => (creds as Config).apiBaseUrl,
-  getAuthHeaders: () => ({}),
-  getRequestHeaders: (_requestOptions, { method, parts, credentials }) => {
-    const c = credentials as any;
-    const baseUrl = new URL(c.apiBaseUrl);
-    const uri = `${baseUrl.host}${baseUrl.pathname}${parts.path}`;
-    const jwt = generateJwt(
-      c.apiKeyId,
-      Redacted.value(c.apiKeySecret),
-      method,
-      uri,
-    );
-    return {
-      Authorization: `Bearer ${jwt}`,
-    };
-  },
-  matchError: matchError as any,
-  ParseError: CoinbaseParseError as any,
-  retry: Retry as any,
-});
+export const CoinbaseProtocol: Layer.Layer<API.Protocol> = Layer.succeed(
+  API.Protocol,
+  API.Protocol.of({
+    // Erase encode's Credentials requirement (see comment above).
+    encode: (args) =>
+      encode(args) as Effect.Effect<HttpClientRequest.HttpClientRequest>,
+    decode,
+  }),
+);

package/src/retry.ts

@@ -1,10 +1,10 @@
 /**
  * Coinbase retry configuration.
  *
- * Defines the per-SDK `Retry` Context.Service tag that
- * `packages/coinbase/src/client.ts` wires into `makeAPI`. Callers can
- * install a blanket retry policy at the layer level and have every
- * Coinbase API call below it pick it up:
+ * Defines the per-SDK `Retry` Context.Service tag that generated operations
+ * wire into `API.make({ retry: Retry.Retry })`. Callers can install a
+ * blanket retry policy at the layer level and have every Coinbase API call
+ * below it pick it up:
  *
  * @example
  * ```ts