@coinbase-sample/prime-sdk-ts 0.6.1 → 0.6.3

package/README.md

@@ -1,10 +1,11 @@
 # Coinbase Prime API TypeScript SDK
 
-## Overview
+[![npm version](https://badge.fury.io/js/%40coinbase-sample%2Fprime-sdk-ts.svg)](https://badge.fury.io/js/%40coinbase-sample%2Fprime-sdk-ts)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-Welcome to the Coinbase Prime API TypeScript SDK. This TypeScript project was created to allow developers to easily plug into the [Coinbase Prime API](https://docs.cdp.coinbase.com/prime/docs/welcome).
+## Overview
 
----
+Welcome to the Coinbase Prime API TypeScript SDK. This TypeScript project provides a comprehensive, type-safe interface to the [Coinbase Prime API](https://docs.cdp.coinbase.com/prime/docs/welcome) with multiple consumption patterns optimized for different use cases.
 
 ## License
 
@@ -12,109 +13,248 @@ The _Prime Typescript SDK_ sample library is free and open source and released u
 
 The application and code are only available for demonstration purposes.
 
-## Pagination
+## 🚀 Quick Start
 
-When creating the client, you can now specify a maxItems and maxPages to help manage paginated responses.
+### Installation
 
-```
-const client = new CoinbasePrimeClient(credentials, undefined, { maxPages: 5, maxItems: 1000 });
+```bash
+npm install @coinbase-sample/prime-sdk-ts
 ```
 
-These values can also be added on a per paginated request, such as:
+### Basic Usage (Recommended)
 
-```
-const client = new CoinbasePrimeClient(credentials);
+The SDK provides a **modular client** with lazy-loaded services for the best developer experience:
+
+```typescript
+import { CoinbasePrimeClientWithServices } from '@coinbase-sample/prime-sdk-ts';
 
-const service = new TransactionsService(client);
+// Create client from environment variables
+const client = CoinbasePrimeClientWithServices.fromEnv();
 
-service
-  .listPortfolioTransactions(
-    { portfolioId, limit: 100 },
-    { maxPages: 20, maxItems: 1000 }
-  )
+// Access services directly - no manual instantiation needed!
+const portfolios = await client.portfolios.listPortfolios();
+const orders = await client.orders.listPortfolioOrders({ portfolioId: 'your-id' });
+const wallets = await client.wallets.listWallets({ portfolioId: 'your-id' });
 ```
 
-## Usage
+### Environment Setup
 
-Here are a few examples requests:
+Copy `env.example` to `.env` and populate with your values:
 
-**[List Portfolios](https://docs.cdp.coinbase.com/prime/reference/primerestapi_getportfolios)**
+```bash
+cp env.example .env
+```
+
+Then edit `.env` with your actual credentials:
+```env
+# API Credentials (JSON format)
+PRIME_CREDENTIALS={"AccessKey":"your-access-key","SecretKey":"your-secret-key","Passphrase":"your-passphrase"}
 
+# Required IDs
+ENTITY_ID=your-entity-id
+PORTFOLIO_ID=your-portfolio-id
+WALLET_ID=your-wallet-id
 ```
-client
-    .listPortfolios()
-    .then((result) => {
-        console.log(result);
-    })
-    .catch((error) => {
-        console.error(error.message);
-    });
+
+## 📚 Usage Examples
+
+### **List Portfolios**
+```typescript
+const portfolios = await client.portfolios.listPortfolios();
+console.log(portfolios.portfolios);
 ```
 
-**[Get Assets](https://docs.cdp.coinbase.com/prime/reference/primerestapi_getentityassets)**
+### **Get Assets**
+```typescript
+const assets = await client.assets.listAssets({ 
+  entityId: portfolioId 
+});
+console.log(assets.assets);
+```
 
+### **Create Order**
+```typescript
+import { OrderSide, OrderType } from '@coinbase-sample/prime-sdk-ts';
+
+const order = await client.orders.createOrder({
+  portfolioId: 'your-portfolio-id',
+  productId: 'BTC-USD',
+  side: OrderSide.BUY,
+  type: OrderType.MARKET,
+  baseQuantity: '0.001'
+});
+console.log(order.orderId);
 ```
-client
-    .listAssets({entityId: "somePortfolioId"})
-    .then((result) => {
-        console.log(result);
-    })
-    .catch((error) => {
-        console.error(error.message);
-    });
+
+See the example folder for more robust examples for many of the available services and endpoints. 
+
+## 🔧 Configuration Options
+
+### Pagination Control
+
+The SDK provides powerful pagination controls at both the client and request level:
+
+```typescript
+const client = CoinbasePrimeClientWithServices.fromEnv(undefined, {
+  maxPages: 5,        // Max pages to fetch automatically
+  maxItems: 1000,     // Max total items across all pages
+  defaultLimit: 100   // Items per page
+});
+
+// Or per-request
+const response = await client.transactions.listPortfolioTransactions(
+  { portfolioId, limit: 50 },
+  { maxPages: 10, maxItems: 500 }
+);
 ```
 
-**[Create Order](https://docs.cdp.coinbase.com/prime/reference/primerestapi_createorder)**
+### Advanced Pagination Methods
 
-_$10 Market Buy on BTC-USD_
+All paginated responses include powerful methods for manual pagination control:
 
+```typescript
+// Get the first page
+const firstPage = await client.transactions.listPortfolioTransactions({ portfolioId });
+
+// Check if there are more pages
+if (firstPage.hasNext()) {
+  console.log('More data available');
+}
+
+// Get the next page manually
+const secondPage = await firstPage.next();
+
+// Fetch ALL remaining pages and combine the data
+const allTransactions = await firstPage.fetchAll(
+  undefined,  // options
+  (page, totalItems) => console.log(`Fetched page ${page}, total items: ${totalItems}`)
+);
+
+// Example: Manual pagination loop
+let currentPage = firstPage;
+while (currentPage.hasNext()) {
+  console.log(`Processing ${currentPage.transactions.length} transactions`);
+  currentPage = await currentPage.next();
+}
 ```
-client
-    .createOrder({
-        portfolioId: "somePortfolioId",
-        productId: "BTC-USD",
-        side: OrderSide.BUY,
-        type: OrderType.Market,
-        baseQuantity: "0.0001"
-    })
-    .then((result) => {
-        console.log(result);
-    })
-    .catch((error) => {
-        console.error(error.message);
-    });
+
+#### Pagination Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| **`hasNext()`** | Check if more pages are available | `boolean` |
+| **`next()`** | Fetch the next page | `Promise<Response \| null>` |
+| **`fetchAll()`** | Fetch all remaining pages and combine data | `Promise<DataArray[]>` |
+| **`getNextCursor()`** | Get the next page cursor | `string \| undefined` |
+
+## 📦 Alternative Import Patterns
+
+While the **modular client** (`CoinbasePrimeClientWithServices`) is recommended for most use cases, the SDK provides additional import patterns optimized for specific scenarios:
+
+### 🎯 For Bundle Size Optimization
+
+#### **Manual Client** (`@coinbase-sample/prime-sdk-ts/manual`)
+When you need full control over service instantiation:
+
+```typescript
+import { CoinbasePrimeClient, OrdersService, WalletsService } from '@coinbase-sample/prime-sdk-ts/manual';
+
+const client = CoinbasePrimeClient.fromEnv();
+const orders = new OrdersService(client);
+const wallets = new WalletsService(client);
+
+// Only the services you import are included in your bundle
 ```
 
-## Development Installation
+#### **Ultra-Minimal Client** (`@coinbase-sample/prime-sdk-ts/client`)
+For services-only patterns (97% smaller bundles):
 
-```bash
-npm install
+```typescript
+import { CoinbasePrimeClient } from '@coinbase-sample/prime-sdk-ts/client';
+import { OrdersService } from '@coinbase-sample/prime-sdk-ts/services';
+
+const client = CoinbasePrimeClient.fromEnv();
+const orders = new OrdersService(client);
+// Total bundle: ~3kb (perfect for microservices)
 ```
 
----
+### 📊 Bundle Size Comparison
 
-## Build and Use
+| Import Pattern | Bundle Size | Use Case |
+|----------------|-------------|----------|
+| **Modular Client** (recommended) | ~30kb | Best developer experience |
+| **Manual Client** | ~90kb | Full control, all services available |
+| **Services + Client** | ~6kb | Custom implementations |
+| **Individual Service** | ~3kb | Microservices, Lambda functions |
 
-To build the project, run the following command:
+### 🎨 Type-Only Imports
 
-```bash
-npm run build
+For shared libraries or type definitions:
+
+```typescript
+import type { CreateOrderRequest, OrderSide } from '@coinbase-sample/prime-sdk-ts/types';
+// 0kb runtime - perfect for shared type libraries
 ```
 
-_Note: To avoid potential issues, do not forget to build your project again after making any changes to it._
+## 🤔 When to Use Which?
 
-After building the project, each `.ts` file will have its `.js` counterpart generated.
+- **🏆 Modular Client**: Default choice - best DX, good performance
+- **⚡ Manual Client**: Need all services, want explicit control
+- **🎯 Services-Only**: Microservices, custom clients, minimal bundles
+- **📦 Individual Services**: Lambda functions, single-purpose apps
+- **📝 Types-Only**: Shared libraries, type definitions
 
-To run a file, use the following command:
+## 🛠️ Development
 
+### Installation
+```bash
+git clone https://github.com/coinbase-samples/prime-sdk-ts.git
+cd prime-sdk-ts
+npm install
 ```
-node dist/{INSERT-FILENAME}.js
+
+### Build
+```bash
+npm run build
 ```
 
-For example, a `main.ts` file would be run like:
+### Run Examples
+The SDK includes comprehensive examples in the `example/` directory:
 
 ```bash
-node dist/main.js
+# Set up environment (copy env.example to .env first)
+cp env.example .env
+# Edit .env with your actual entityId, portfolioId, and walletId
+
+# Run examples
+node example/listPortfolios.js
+node example/createOrder.js
+node example/listWallets.js TRADING
 ```
 
----
+## 🧪 TypeScript Support
+
+The SDK is built with TypeScript and provides full type safety:
+
+```typescript
+import { 
+  CoinbasePrimeClientWithServices, 
+  OrderSide, 
+  OrderType,
+  CreateOrderRequest 
+} from '@coinbase-sample/prime-sdk-ts';
+
+const client = CoinbasePrimeClientWithServices.fromEnv();
+
+// Full IntelliSense and type checking
+const request: CreateOrderRequest = {
+  portfolioId: 'your-id',
+  productId: 'BTC-USD',
+  side: OrderSide.BUY,  // Enum with autocomplete
+  type: OrderType.MARKET,
+  baseQuantity: '0.001'
+};
+
+const order = await client.orders.createOrder(request);
+// Response is fully typed - no manual type assertions needed
+```

package/dist/activities/index.js

@@ -23,6 +23,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ActivitiesService = void 0;
 const paginatedResponse_1 = require("../shared/paginatedResponse");
@@ -50,28 +61,12 @@ class ActivitiesService {
     }
     listEntityActivities(request, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            let queryParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
-            if (request.startTime) {
-                queryParams.startTime = new Date(request.startTime).toISOString();
-            }
-            if (request.endTime) {
-                queryParams.endTime = new Date(request.endTime).toISOString();
-            }
-            if (request.statuses) {
-                queryParams.statuses = request.statuses;
-            }
-            if (request.categories) {
-                queryParams.categories = request.categories;
-            }
-            if (request.symbols) {
-                queryParams.symbols = request.symbols;
-            }
-            if (request.activityLevel) {
-                queryParams.activityLevel = request.activityLevel;
-            }
+            const paginationParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
+            const { limit, cursor, sortDirection, entityId } = request, queryParams = __rest(request, ["limit", "cursor", "sortDirection", "entityId"]);
+            const finalQueryParams = Object.assign(Object.assign({}, paginationParams), queryParams);
             const response = yield this.client.request({
-                url: `entities/${request.entityId}/activities`,
-                queryParams,
+                url: `entities/${entityId}/activities`,
+                queryParams: finalQueryParams,
                 callOptions: options,
             });
             const paginationOptions = (0, paginatedResponse_1.getDefaultPaginationOptions)(this.client, options);
@@ -80,25 +75,12 @@ class ActivitiesService {
     }
     listPortfolioActivities(request, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const queryParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
-            if (request.startTime) {
-                queryParams.startTime = new Date(request.startTime).toISOString();
-            }
-            if (request.endTime) {
-                queryParams.endTime = new Date(request.endTime).toISOString();
-            }
-            if (request.statuses) {
-                queryParams.statuses = request.statuses;
-            }
-            if (request.categories) {
-                queryParams.categories = request.categories;
-            }
-            if (request.symbols) {
-                queryParams.symbols = request.symbols;
-            }
+            const paginationParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
+            const { limit, cursor, sortDirection, portfolioId } = request, queryParams = __rest(request, ["limit", "cursor", "sortDirection", "portfolioId"]);
+            const finalQueryParams = Object.assign(Object.assign({}, paginationParams), queryParams);
             const response = yield this.client.request({
-                url: `portfolios/${request.portfolioId}/activities`,
-                queryParams,
+                url: `portfolios/${portfolioId}/activities`,
+                queryParams: finalQueryParams,
                 callOptions: options,
             });
             const paginationOptions = (0, paginatedResponse_1.getDefaultPaginationOptions)(this.client, options);

package/dist/addressBooks/index.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AddressBooksService = void 0;
 /**
@@ -25,7 +36,7 @@ exports.AddressBooksService = void 0;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-const core_ts_1 = require("@coinbase-sample/core-ts");
+const clients_1 = require("../clients");
 const paginatedResponse_1 = require("../shared/paginatedResponse");
 class AddressBooksService {
     constructor(client) {
@@ -33,10 +44,12 @@ class AddressBooksService {
     }
     listAddressBooks(request, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const queryParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
+            const paginationParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
+            const { limit, cursor, sortDirection, portfolioId } = request, queryParams = __rest(request, ["limit", "cursor", "sortDirection", "portfolioId"]);
+            const finalQueryParams = Object.assign(Object.assign({}, paginationParams), queryParams);
             const response = yield this.client.request({
-                url: `portfolios/${request.portfolioId}/address_book`,
-                queryParams,
+                url: `portfolios/${portfolioId}/address_book`,
+                queryParams: finalQueryParams,
                 callOptions: options,
             });
             const paginationOptions = (0, paginatedResponse_1.getDefaultPaginationOptions)(this.client, options);
@@ -49,7 +62,7 @@ class AddressBooksService {
             const response = yield this.client.request({
                 url: `portfolios/${request.portfolioId}/address_book`,
                 bodyParams,
-                method: core_ts_1.Method.POST,
+                method: clients_1.Method.POST,
                 callOptions: options,
             });
             return response.data;

package/dist/allocations/index.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AllocationService = void 0;
 /**
@@ -25,7 +36,7 @@ exports.AllocationService = void 0;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-const core_ts_1 = require("@coinbase-sample/core-ts");
+const clients_1 = require("../clients");
 const paginatedResponse_1 = require("../shared/paginatedResponse");
 class AllocationService {
     constructor(client) {
@@ -36,7 +47,7 @@ class AllocationService {
             const response = yield this.client.request({
                 url: `allocations`,
                 bodyParams: request,
-                method: core_ts_1.Method.POST,
+                method: clients_1.Method.POST,
                 callOptions: options,
             });
             return response.data;
@@ -47,7 +58,7 @@ class AllocationService {
             const response = yield this.client.request({
                 url: `allocations/net`,
                 bodyParams: request,
-                method: core_ts_1.Method.POST,
+                method: clients_1.Method.POST,
                 callOptions: options,
             });
             return response.data;
@@ -55,22 +66,12 @@ class AllocationService {
     }
     listPortfolioAllocations(request, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            let queryParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
-            if (request.startDate) {
-                queryParams.startDate = new Date(request.startDate).toISOString();
-            }
-            if (request.endDate) {
-                queryParams.endDate = new Date(request.endDate).toISOString();
-            }
-            if (request.productIds) {
-                queryParams.productIds = request.productIds;
-            }
-            if (request.orderSide) {
-                queryParams.orderSide = request.orderSide;
-            }
+            const paginationParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
+            const { limit, cursor, sortDirection, portfolioId } = request, queryParams = __rest(request, ["limit", "cursor", "sortDirection", "portfolioId"]);
+            const finalQueryParams = Object.assign(Object.assign({}, paginationParams), queryParams);
             const response = yield this.client.request({
-                url: `portfolios/${request.portfolioId}/allocations`,
-                queryParams,
+                url: `portfolios/${portfolioId}/allocations`,
+                queryParams: finalQueryParams,
                 callOptions: options,
             });
             const paginationOptions = (0, paginatedResponse_1.getDefaultPaginationOptions)(this.client, options);

package/dist/balances/index.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BalancesService = void 0;
 const paginatedResponse_1 = require("../shared/paginatedResponse");
@@ -17,9 +28,9 @@ class BalancesService {
     }
     listPortfolioBalances(request, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const queryParams = Object.assign(Object.assign({}, request), { portfolioId: undefined });
+            const { portfolioId } = request, queryParams = __rest(request, ["portfolioId"]);
             const response = yield this.client.request({
-                url: `portfolios/${request.portfolioId}/balances`,
+                url: `portfolios/${portfolioId}/balances`,
                 queryParams,
                 callOptions: options,
             });
@@ -37,13 +48,12 @@ class BalancesService {
     }
     listOnchainWalletBalances(request, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            let queryParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
-            if (request.visibilityStatuses) {
-                queryParams.visibilityStatuses = request.visibilityStatuses;
-            }
+            const paginationParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
+            const { limit, cursor, portfolioId, walletId } = request, queryParams = __rest(request, ["limit", "cursor", "portfolioId", "walletId"]);
+            const finalQueryParams = Object.assign(Object.assign({}, paginationParams), queryParams);
             const response = yield this.client.request({
-                url: `portfolios/${request.portfolioId}/wallets/${request.walletId}/web3_balances`,
-                queryParams,
+                url: `portfolios/${portfolioId}/wallets/${walletId}/web3_balances`,
+                queryParams: finalQueryParams,
                 callOptions: options,
             });
             const paginationOptions = (0, paginatedResponse_1.getDefaultPaginationOptions)(this.client, options);
@@ -52,16 +62,12 @@ class BalancesService {
     }
     listEntityBalances(request, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            let queryParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
-            if (request.symbols) {
-                queryParams.symbols = request.symbols;
-            }
-            if (request.aggregationType) {
-                queryParams.aggregationType = request.aggregationType;
-            }
+            const paginationParams = (0, paginatedResponse_1.getQueryParams)(this.client, request);
+            const { limit, cursor, entityId } = request, queryParams = __rest(request, ["limit", "cursor", "entityId"]);
+            const finalQueryParams = Object.assign(Object.assign({}, paginationParams), queryParams);
             const response = yield this.client.request({
-                url: `entities/${request.entityId}/balances`,
-                queryParams,
+                url: `entities/${entityId}/balances`,
+                queryParams: finalQueryParams,
                 callOptions: options,
             });
             const paginationOptions = (0, paginatedResponse_1.getDefaultPaginationOptions)(this.client, options);