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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@distilled.cloud/coinbase",
-  "version": "0.30.3",
+  "version": "1.0.0-rc.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/alchemy-run/distilled",
@@ -9,7 +9,6 @@
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
-  "module": "src/index.ts",
   "files": [
     "lib",
     "src"
@@ -18,73 +17,61 @@
     ".": {
       "types": "./lib/index.d.ts",
       "bun": "./src/index.ts",
+      "worker": "./src/index.ts",
       "default": "./lib/index.js"
     },
-    "./Category": {
-      "types": "./lib/category.d.ts",
-      "bun": "./src/category.ts",
-      "default": "./lib/category.js"
-    },
-    "./Client": {
-      "types": "./lib/client.d.ts",
-      "bun": "./src/client.ts",
-      "default": "./lib/client.js"
-    },
     "./Credentials": {
       "types": "./lib/credentials.d.ts",
       "bun": "./src/credentials.ts",
+      "worker": "./src/credentials.ts",
       "default": "./lib/credentials.js"
     },
     "./Errors": {
       "types": "./lib/errors.d.ts",
       "bun": "./src/errors.ts",
+      "worker": "./src/errors.ts",
       "default": "./lib/errors.js"
     },
-    "./Operations": {
-      "types": "./lib/operations/index.d.ts",
-      "bun": "./src/operations/index.ts",
-      "default": "./lib/operations/index.js"
+    "./Traits": {
+      "types": "./lib/traits.d.ts",
+      "bun": "./src/traits.ts",
+      "worker": "./src/traits.ts",
+      "default": "./lib/traits.js"
+    },
+    "./Protocol": {
+      "types": "./lib/protocol.d.ts",
+      "bun": "./src/protocol.ts",
+      "worker": "./src/protocol.ts",
+      "default": "./lib/protocol.js"
     },
     "./Retry": {
       "types": "./lib/retry.d.ts",
       "bun": "./src/retry.ts",
+      "worker": "./src/retry.ts",
       "default": "./lib/retry.js"
     },
-    "./Sensitive": {
-      "types": "./lib/sensitive.d.ts",
-      "bun": "./src/sensitive.ts",
-      "default": "./lib/sensitive.js"
-    },
-    "./Traits": {
-      "types": "./lib/traits.d.ts",
-      "bun": "./src/traits.ts",
-      "default": "./lib/traits.js"
+    "./*": {
+      "types": "./lib/services/*.d.ts",
+      "bun": "./src/services/*.ts",
+      "worker": "./src/services/*.ts",
+      "default": "./lib/services/*.js"
     }
   },
   "scripts": {
-    "typecheck": "tsc",
     "build": "tsc -b",
-    "fmt": "oxfmt --write src",
-    "lint": "oxlint --fix src",
-    "check": "tsc && oxlint src && oxfmt --check src",
-    "test": "bunx vitest run test --exclude specs --passWithNoTests",
-    "publish:npm": "bun run build && bun publish --access public",
-    "generate": "bun run scripts/generate.ts && oxlint --fix src && oxfmt --write src && oxfmt --write src",
+    "convert": "bun scripts/convert.ts",
+    "generate": "bun scripts/convert.ts && bun scripts/generate.ts",
+    "typecheck": "tsc -p tsconfig.json",
     "specs:fetch": "git submodule update --force --init --recursive --depth=1 specs/cdp-sdk && git -C specs/cdp-sdk checkout -- .",
     "specs:update": "git -C specs/cdp-sdk fetch && git -C specs/cdp-sdk checkout main && git -C specs/cdp-sdk pull"
   },
   "dependencies": {
-    "@distilled.cloud/core": "0.30.3"
+    "@distilled.cloud/core": "1.0.0-rc.2",
+    "@effect/platform-bun": ">=4.0.0-beta.102 || >=4.0.0",
+    "effect": ">=4.0.0-beta.102 || >=4.0.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.0",
-    "@types/node": "^25.3.5",
-    "dotenv": "^16.5.0",
-    "rolldown": "^1.2.0",
-    "vitest": "^3.2.3",
-    "yaml": "^2.8.2"
-  },
-  "peerDependencies": {
-    "effect": ">=4.0.0-beta.100 || >=4.0.0"
+    "@types/bun": "latest",
+    "@types/node": "latest"
   }
 }

package/src/credentials.ts

@@ -1,3 +1,11 @@
+/**
+ * Coinbase CDP credentials — hand-written.
+ *
+ * API-compatible port of the distilled repo's coinbase credentials module:
+ * the `Credentials` service holds an *effect* that resolves the current
+ * credentials on every request. The protocol layer resolves it per request
+ * and signs a fresh JWT bearer token from the API Key Secret.
+ */
 import { ConfigError } from "@distilled.cloud/core/errors";
 import * as EffectConfig from "effect/Config";
 import * as Context from "effect/Context";

package/src/errors.ts

@@ -32,7 +32,15 @@ export {
   DEFAULT_ERRORS,
   API_ERRORS,
 } from "@distilled.cloud/core/errors";
-export type { DefaultErrors } from "@distilled.cloud/core/errors";
+import type {
+  BadRequest as CoreBadRequest,
+  Conflict as CoreConflict,
+  DefaultErrors as CoreDefaultErrors,
+  Forbidden as CoreForbidden,
+  Locked as CoreLocked,
+  NotFound as CoreNotFound,
+  UnprocessableEntity as CoreUnprocessableEntity,
+} from "@distilled.cloud/core/errors";
 
 import {
   BadGateway,
@@ -579,7 +587,7 @@ export const STANDARD_ERROR_TYPE_MAP: Record<
 
 /**
  * Maps Coinbase-specific `errorType` values to their corresponding error classes.
- * Used by the client's matchError function for type-based error dispatching.
+ * Used by the protocol's matchError function for type-based error dispatching.
  */
 export const ERROR_TYPE_MAP: Record<string, new (props: any) => unknown> = {
   // Resource conflicts
@@ -692,3 +700,85 @@ export class CoinbaseParseError extends Schema.TaggedErrorClass<CoinbaseParseErr
     cause: Schema.Unknown,
   },
 ).pipe(Category.withParseError) {}
+
+// ============================================================================
+// Error unions (the error channel of every generated operation)
+// ============================================================================
+
+/**
+ * All Coinbase CDP typed errors that `errorType` dispatch can produce.
+ */
+export type CoinbaseTypedErrors =
+  | PaymentRequired
+  | IdempotencyError
+  | AlreadyExists
+  | FaucetLimitExceeded
+  | InvalidSqlQuery
+  | InvalidSignature
+  | MalformedTransaction
+  | SettlementFailed
+  | TimedOut
+  | ClientClosedRequest
+  | RequestCanceled
+  | PolicyViolation
+  | PolicyInUse
+  | AccountLimitExceeded
+  | InsufficientBalance
+  | AccountNotReady
+  | MfaRequired
+  | MfaAlreadyEnrolled
+  | MfaInvalidCode
+  | MfaFlowExpired
+  | MfaNotEnrolled
+  | NetworkNotTradable
+  | GuestPermissionDenied
+  | GuestRegionForbidden
+  | GuestTransactionLimit
+  | GuestTransactionCount
+  | PhoneNumberVerificationExpired
+  | DocumentVerificationFailed
+  | RecipientAllowlistViolation
+  | RecipientAllowlistPending
+  | TravelRulesRecipientViolation
+  | TravelRulesFieldMissing
+  | SourceAccountInvalid
+  | TargetAccountInvalid
+  | SourceAccountNotFound
+  | TargetAccountNotFound
+  | SourceAssetNotSupported
+  | TargetAssetNotSupported
+  | TransferAssetNotSupported
+  | AssetMismatch
+  | TargetEmailInvalid
+  | TargetOnchainAddressInvalid
+  | TransferAmountInvalid
+  | MetadataTooManyEntries
+  | MetadataKeyTooLong
+  | MetadataValueTooLong
+  | OrderQuoteExpired
+  | OrderAlreadyFilled
+  | OrderAlreadyCanceled;
+
+/**
+ * Errors any Coinbase operation may surface beyond the core HTTP defaults:
+ * the typed CDP errors plus the client-level fallback/decode errors.
+ */
+export type ClientErrors =
+  | CoinbaseTypedErrors
+  | UnknownCoinbaseError
+  | CoinbaseParseError;
+
+/**
+ * Default Coinbase operation errors: the shared HTTP status errors from core
+ * (both the always-possible defaults and the status-mapped 4xx classes the
+ * global matcher can produce) plus the Coinbase client errors.
+ */
+export type DefaultErrors =
+  | CoreDefaultErrors
+  | CoreBadRequest
+  | CoreForbidden
+  | CoreNotFound
+  | CoreConflict
+  | CoreUnprocessableEntity
+  | CoreLocked
+  | ClientErrors;

package/src/index.ts

@@ -1,5 +1,9 @@
 /**
- * Coinbase SDK for Effect
+ * @distilled.cloud/coinbase — Coinbase CDP SDK for Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy model in
+ * `.generated-specs` (converted from the CDP OpenAPI spec by
+ * `scripts/convert.ts`). Everything else in this folder is hand-written.
  *
  * @example
  * ```ts
@@ -7,10 +11,12 @@
  * ```
  */
 export * from "./credentials.ts";
-export * as Category from "./category.ts";
+export * from "./errors.ts";
 export * as T from "./traits.ts";
+export {
+  CoinbaseProtocol,
+  type CoinbaseOpError,
+  type CoinbaseOpContext,
+} from "./protocol.ts";
 export * as Retry from "./retry.ts";
-export { API } from "./client.ts";
-export * from "./errors.ts";
-export * from "./operations/index.ts";
-export { SensitiveString, SensitiveNullableString } from "./sensitive.ts";
+export * as Services from "./services/index.ts";

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