@coinbase/cdp-sdk 0.0.0 → 1.0.1

package/dist/analytics.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendEvent = sendEvent;
+const md5_1 = __importDefault(require("md5"));
+const cdp_1 = require("./client/cdp");
+const evm_1 = require("./client/evm");
+const solana_1 = require("./client/solana");
+/**
+ * Sends an analytics event to the default endpoint
+ *
+ * @param event - The event data containing event-specific fields
+ * @returns Promise that resolves when the event is sent
+ */
+async function sendEvent(event) {
+    const timestamp = Date.now();
+    const enhancedEvent = {
+        event_type: event.name,
+        platform: "server",
+        event_properties: {
+            platform: "server",
+            project_name: "cdp-sdk",
+            time_start: timestamp,
+            cdp_sdk_language: "typescript",
+            ...event,
+        },
+    };
+    const events = [enhancedEvent];
+    const stringifiedEventData = JSON.stringify(events);
+    const uploadTime = timestamp.toString();
+    const checksum = (0, md5_1.default)(stringifiedEventData + uploadTime);
+    const analyticsServiceData = {
+        e: stringifiedEventData,
+        checksum,
+    };
+    const apiEndpoint = "https://cca-lite.coinbase.com";
+    const eventPath = "/amp";
+    const eventEndPoint = `${apiEndpoint}${eventPath}`;
+    const response = await fetch(eventEndPoint, {
+        method: "POST",
+        mode: "no-cors",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(analyticsServiceData),
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+    }
+}
+/**
+ * Wraps all methods of a class with error tracking.
+ *
+ * @param ClassToWrap - The class whose prototype methods should be wrapped.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function wrapClassWithErrorTracking(ClassToWrap) {
+    const methodNames = Object.getOwnPropertyNames(ClassToWrap.prototype).filter(name => name !== "constructor" && typeof ClassToWrap.prototype[name] === "function");
+    for (const methodName of methodNames) {
+        const originalMethod = ClassToWrap.prototype[methodName];
+        ClassToWrap.prototype[methodName] = async function (...args) {
+            try {
+                return await originalMethod.apply(this, args);
+            }
+            catch (error) {
+                if (!(error instanceof Error)) {
+                    return;
+                }
+                const { message, stack } = error;
+                if (process.env.DISABLE_CDP_ERROR_REPORTING !== "true") {
+                    sendEvent({
+                        method: String(methodName),
+                        message,
+                        stack,
+                        name: "error",
+                    }).catch(() => {
+                        // ignore error
+                    });
+                }
+                throw error;
+            }
+        };
+    }
+}
+wrapClassWithErrorTracking(cdp_1.CdpClient);
+wrapClassWithErrorTracking(evm_1.EvmClient);
+wrapClassWithErrorTracking(solana_1.SolanaClient);

package/dist/auth/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A class of errors for capturing stack traces.
+ */
+declare class BaseError extends Error {
+    /**
+     * Base error constructor.
+     *
+     * @param message - The message to display.
+     */
+    constructor(message: string);
+}
+/**
+ * An error for invalid API key format.
+ */
+export declare class InvalidAPIKeyFormatError extends BaseError {
+    /**
+     * Invalid API key format error constructor.
+     *
+     * @param message - The message to display.
+     */
+    constructor(message: string);
+}
+/**
+ * An error for invalid Wallet Secret format.
+ */
+export declare class InvalidWalletSecretFormatError extends BaseError {
+    /**
+     * Invalid Wallet Secret format error constructor.
+     *
+     * @param message - The message to display.
+     */
+    constructor(message: string);
+}
+/**
+ * An error for an undefined Wallet Secret.
+ */
+export declare class UndefinedWalletSecretError extends BaseError {
+    /**
+     * Undefined Wallet Secret error constructor.
+     *
+     * @param message - The message to display.
+     */
+    constructor(message: string);
+}
+export {};

package/dist/auth/errors.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UndefinedWalletSecretError = exports.InvalidWalletSecretFormatError = exports.InvalidAPIKeyFormatError = void 0;
+/**
+ * A class of errors for capturing stack traces.
+ */
+class BaseError extends Error {
+    /**
+     * Base error constructor.
+     *
+     * @param message - The message to display.
+     */
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * An error for invalid API key format.
+ */
+class InvalidAPIKeyFormatError extends BaseError {
+    /**
+     * Invalid API key format error constructor.
+     *
+     * @param message - The message to display.
+     */
+    constructor(message) {
+        super("Invalid API key format: " + message);
+    }
+}
+exports.InvalidAPIKeyFormatError = InvalidAPIKeyFormatError;
+/**
+ * An error for invalid Wallet Secret format.
+ */
+class InvalidWalletSecretFormatError extends BaseError {
+    /**
+     * Invalid Wallet Secret format error constructor.
+     *
+     * @param message - The message to display.
+     */
+    constructor(message) {
+        super("Invalid Wallet Secret format: " + message);
+    }
+}
+exports.InvalidWalletSecretFormatError = InvalidWalletSecretFormatError;
+/**
+ * An error for an undefined Wallet Secret.
+ */
+class UndefinedWalletSecretError extends BaseError {
+    /**
+     * Undefined Wallet Secret error constructor.
+     *
+     * @param message - The message to display.
+     */
+    constructor(message) {
+        super("Undefined Wallet Secret: " + message);
+    }
+}
+exports.UndefinedWalletSecretError = UndefinedWalletSecretError;

package/dist/auth/hooks/axios/index.d.ts

@@ -0,0 +1 @@
+export * from "./withAuth";

package/dist/auth/hooks/axios/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./withAuth"), exports);

package/dist/auth/hooks/axios/withAuth.d.ts

@@ -0,0 +1,37 @@
+import { AxiosInstance } from "axios";
+export interface AuthInterceptorOptions {
+    /**
+     * The API key ID
+     *
+     * Examples:
+     *  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+     *  'organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/apiKeys/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+     */
+    apiKeyId: string;
+    /**
+     * The API key secret
+     *
+     * Examples:
+     *  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==' (Edwards key (Ed25519))
+     *  '-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n' (EC key (ES256))
+     */
+    apiKeySecret: string;
+    /** The Wallet Secret */
+    walletSecret?: string;
+    /** The source of the request */
+    source?: string;
+    /** The version of the source of the request */
+    sourceVersion?: string;
+    /** Optional expiration time in seconds (defaults to 120) */
+    expiresIn?: number;
+    /** Whether to log request/response details */
+    debug?: boolean;
+}
+/**
+ * Axios interceptor for adding the JWT to the Authorization header.
+ *
+ * @param axiosClient - The Axios client instance to add the interceptor to
+ * @param options - Options for the request including API keys and debug flag
+ * @returns The modified request configuration with the Authorization header added
+ */
+export declare function withAuth(axiosClient: AxiosInstance, options: AuthInterceptorOptions): AxiosInstance;

package/dist/auth/hooks/axios/withAuth.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAuth = withAuth;
+const axios_1 = require("axios");
+const http_1 = require("../../utils/http");
+/**
+ * Axios interceptor for adding the JWT to the Authorization header.
+ *
+ * @param axiosClient - The Axios client instance to add the interceptor to
+ * @param options - Options for the request including API keys and debug flag
+ * @returns The modified request configuration with the Authorization header added
+ */
+function withAuth(axiosClient, options) {
+    axiosClient.interceptors.request.use(async (axiosConfig) => {
+        const method = axiosConfig.method?.toString().toUpperCase() || "GET";
+        if (!axiosConfig.url) {
+            throw new Error("URL is required for authentication");
+        }
+        const fullyQualifiedURL = axiosClient.getUri() + axiosConfig.url;
+        // Parse URL to get host and path
+        const url = new URL(fullyQualifiedURL);
+        // Get authentication headers
+        const headers = await (0, http_1.getAuthHeaders)({
+            apiKeyId: options.apiKeyId,
+            apiKeySecret: options.apiKeySecret,
+            requestMethod: method,
+            requestHost: url.host,
+            requestPath: url.pathname,
+            requestBody: axiosConfig.data,
+            walletSecret: options.walletSecret,
+            source: options.source,
+            sourceVersion: options.sourceVersion,
+            expiresIn: options.expiresIn,
+        });
+        // Add headers to request config
+        axiosConfig.headers = new axios_1.AxiosHeaders({
+            ...axiosConfig.headers,
+            ...headers,
+        });
+        if (options.debug) {
+            console.log("Request:", {
+                method,
+                url: fullyQualifiedURL,
+                headers: axiosConfig.headers,
+                data: axiosConfig.data,
+            });
+        }
+        return axiosConfig;
+    });
+    if (options.debug) {
+        axiosClient.interceptors.response.use(response => {
+            console.log("Response:", {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+                data: response.data,
+            });
+            return response;
+        }, error => {
+            // Ensure we have access to the error response details
+            const errorDetails = {
+                status: error.response?.status,
+                statusText: error.response?.statusText,
+                headers: error.response?.headers,
+                data: error.response?.data,
+                message: error.message,
+            };
+            console.error("Response Error:", errorDetails);
+            return Promise.reject(error);
+        });
+    }
+    return axiosClient;
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,4 @@
+import * as axiosHooks from "./hooks/axios";
+export * from "./utils/http";
+export * from "./utils/jwt";
+export { axiosHooks };

package/dist/auth/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.axiosHooks = void 0;
+const axiosHooks = __importStar(require("./hooks/axios"));
+exports.axiosHooks = axiosHooks;
+__exportStar(require("./utils/http"), exports);
+__exportStar(require("./utils/jwt"), exports);

package/dist/auth/utils/http.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Options for generating authentication headers for API requests.
+ */
+export interface GetAuthHeadersOptions {
+    /**
+     * The API key ID
+     *
+     * Examples:
+     *  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+     *  'organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/apiKeys/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+     */
+    apiKeyId: string;
+    /**
+     * The API key secret
+     *
+     * Examples:
+     *  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==' (Edwards key (Ed25519))
+     *  '-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n' (EC key (ES256))
+     */
+    apiKeySecret: string;
+    /**
+     * The HTTP method for the request (e.g. 'GET', 'POST')
+     */
+    requestMethod: string;
+    /**
+     * The host for the request (e.g. 'api.cdp.coinbase.com')
+     */
+    requestHost: string;
+    /**
+     * The path for the request (e.g. '/platform/v1/wallets')
+     */
+    requestPath: string;
+    /**
+     * Optional request body data
+     */
+    requestBody?: unknown;
+    /**
+     * The Wallet Secret for wallet authentication
+     */
+    walletSecret?: string;
+    /**
+     * The source identifier for the request
+     */
+    source?: string;
+    /**
+     * The version of the source making the request
+     */
+    sourceVersion?: string;
+    /**
+     * Optional expiration time in seconds (defaults to 120)
+     */
+    expiresIn?: number;
+}
+/**
+ * Gets authentication headers for a request.
+ *
+ * @param options - The configuration options for generating auth headers
+ * @returns Object containing the authentication headers
+ */
+export declare function getAuthHeaders(options: GetAuthHeadersOptions): Promise<Record<string, string>>;

package/dist/auth/utils/http.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAuthHeaders = getAuthHeaders;
+const jwt_1 = require("./jwt");
+const package_json_1 = require("../../../package.json");
+/**
+ * Gets authentication headers for a request.
+ *
+ * @param options - The configuration options for generating auth headers
+ * @returns Object containing the authentication headers
+ */
+async function getAuthHeaders(options) {
+    const headers = {};
+    // Generate and add JWT token
+    const jwt = await (0, jwt_1.generateJwt)({
+        apiKeyId: options.apiKeyId,
+        apiKeySecret: options.apiKeySecret,
+        requestMethod: options.requestMethod,
+        requestHost: options.requestHost,
+        requestPath: options.requestPath,
+        expiresIn: options.expiresIn,
+    });
+    headers["Authorization"] = `Bearer ${jwt}`;
+    headers["Content-Type"] = "application/json";
+    // Add wallet auth if needed
+    if (requiresWalletAuth(options.requestMethod, options.requestPath)) {
+        if (!options.walletSecret) {
+            throw new Error("Wallet Secret not configured. Call configure() first.");
+        }
+        const walletAuthToken = await (0, jwt_1.generateWalletJwt)({
+            walletSecret: options.walletSecret,
+            requestMethod: options.requestMethod,
+            requestHost: options.requestHost,
+            requestPath: options.requestPath,
+            requestData: options.requestBody || {},
+        });
+        headers["X-Wallet-Auth"] = walletAuthToken;
+    }
+    // Add correlation data
+    headers["Correlation-Context"] = getCorrelationData(options.source, options.sourceVersion);
+    return headers;
+}
+/**
+ * Returns true if the request indicated by the method and URL requires wallet authentication.
+ *
+ * @param requestMethod - The HTTP method of the request
+ * @param requestPath - The URL path of the request
+ * @returns True if the request requires wallet authentication, false otherwise
+ */
+function requiresWalletAuth(requestMethod, requestPath) {
+    return (requestPath?.includes("/accounts") && (requestMethod === "POST" || requestMethod === "DELETE"));
+}
+/**
+ * Returns encoded correlation data including the SDK version and language.
+ *
+ * @param source - The source identifier for the request
+ * @param sourceVersion - The version of the source making the request
+ * @returns Encoded correlation data as a query string
+ */
+function getCorrelationData(source, sourceVersion) {
+    const data = {
+        sdk_version: package_json_1.version,
+        sdk_language: "typescript",
+        source: source || "sdk-auth",
+    };
+    if (sourceVersion) {
+        data["source_version"] = sourceVersion;
+    }
+    return Object.keys(data)
+        .map(key => `${key}=${encodeURIComponent(data[key])}`)
+        .join(",");
+}

package/dist/auth/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./http";
+export * from "./jwt";

package/dist/auth/utils/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./http"), exports);
+__exportStar(require("./jwt"), exports);

package/dist/auth/utils/jwt.d.ts

@@ -0,0 +1,88 @@
+/**
+ * JwtOptions contains configuration for JWT generation.
+ *
+ * This interface holds all necessary parameters for generating a JWT token
+ * for authenticating with Coinbase's REST APIs. It supports both EC (ES256)
+ * and Ed25519 (EdDSA) keys.
+ */
+export interface JwtOptions {
+    /**
+     * The API key ID
+     *
+     * Examples:
+     *  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+     *  'organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/apiKeys/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+     */
+    apiKeyId: string;
+    /**
+     * The API key secret
+     *
+     * Examples:
+     *  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==' (Edwards key (Ed25519))
+     *  '-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n' (EC key (ES256))
+     */
+    apiKeySecret: string;
+    /**
+     * The HTTP method for the request (e.g. 'GET', 'POST')
+     */
+    requestMethod: string;
+    /**
+     * The host for the request (e.g. 'api.cdp.coinbase.com')
+     */
+    requestHost: string;
+    /**
+     * The path for the request (e.g. '/platform/v1/wallets')
+     */
+    requestPath: string;
+    /**
+     * Optional expiration time in seconds (defaults to 120)
+     */
+    expiresIn?: number;
+}
+/**
+ * WalletJwtOptions contains configuration for Wallet Auth JWT generation.
+ *
+ * This interface holds all necessary parameters for generating a Wallet Auth JWT
+ * for authenticating with endpoints that require wallet authentication.
+ */
+export interface WalletJwtOptions {
+    /**
+     * - The Wallet Secret
+     */
+    walletSecret: string;
+    /**
+     * - The HTTP method for the request (e.g. 'GET', 'POST')
+     */
+    requestMethod: string;
+    /**
+     * - The host for the request (e.g. 'api.cdp.coinbase.com')
+     */
+    requestHost: string;
+    /**
+     * - The path for the request (e.g. '/platform/v1/wallets/{wallet_id}/addresses')
+     */
+    requestPath: string;
+    /**
+     * - The request data for the request (e.g. { "wallet_id": "1234567890" })
+     */
+    requestData: Record<string, any>;
+}
+/**
+ * Generates a JWT (also known as a Bearer token) for authenticating with Coinbase's REST APIs.
+ * Supports both EC (ES256) and Ed25519 (EdDSA) keys.
+ *
+ * @param options - The configuration options for generating the JWT
+ * @returns The generated JWT (Bearer token) string
+ * @throws {Error} If required parameters are missing, invalid, or if JWT signing fails
+ */
+export declare function generateJwt(options: JwtOptions): Promise<string>;
+/**
+ * Generates a wallet authentication JWT for the given API endpoint URL.
+ * Used for authenticating with specific endpoints that require wallet authentication.
+ *
+ * @param options - The configuration options for generating the JWT
+ * @returns The generated JWT (Bearer token) string
+ * @throws {UndefinedWalletSecretError} If the Wallet Secret is not defined.
+ * @throws {InvalidWalletSecretFormatError} If the private key is not in the correct format or signing fails.
+ */
+export declare function generateWalletJwt(options: WalletJwtOptions): Promise<string>;