Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Update SDK README with comprehensive API documentation [Skip CI]
Damian Legawiec3e10aae08adc
diff --git a/sdk/README.md b/sdk/README.mdindex 252ac89f70..eba01481cc 100644--- a/sdk/README.md+++ b/sdk/README.md@@ -33,26 +33,26 @@ const products = await client.products.list({const product = await client.products.get('ruby-on-rails-tote');// Authentication-const tokens = await client.auth.login({+const { token, user } = await client.auth.login({email: '[email protected]',password: 'password123',});// Create a cart and add items-const cart = await client.orders.create();+const cart = await client.cart.create();await client.orders.lineItems.create(cart.id, {variant_id: 'var_abc123',quantity: 2,-}, { orderToken: cart.order_token });+}, { orderToken: cart.token });// Checkout flow-await client.orders.next(cart.id, { orderToken: cart.order_token });-await client.orders.complete(cart.id, { orderToken: cart.order_token });+await client.orders.next(cart.id, { orderToken: cart.token });+await client.orders.complete(cart.id, { orderToken: cart.token });```## Authentication-The SDK supports two authentication modes:+The SDK supports multiple authentication modes:### 1. API Key Only (Guest/Public Access)@@ -62,7 +62,7 @@ const client = createSpreeClient({apiKey: 'pk_your-publishable-key',});-// Public endpoints work without authentication+// Public endpoints work without user authenticationconst products = await client.products.list();```@@ -70,28 +70,40 @@ const products = await client.products.list();```typescript// Login to get tokens-const tokens = await client.auth.login({+const { token, user } = await client.auth.login({email: '[email protected]',password: 'password123',});// Use token for authenticated requests-const orders = await client.orders.list({}, { token: tokens.access_token });+const orders = await client.orders.list({}, { token });// Refresh token when needed-const newTokens = await client.auth.refresh(tokens.refresh_token);+const newTokens = await client.auth.refresh({ token });+```++### 3. Register New Customer++```typescript+const { token, user } = await client.auth.register({+ email: '[email protected]',+ password: 'password123',+ password_confirmation: 'password123',+ first_name: 'John',+ last_name: 'Doe',+});```## Guest Checkout-For guest checkout, use the `order_token` returned when creating an order:+For guest checkout, use the `token` (or `order_token`) returned when creating a cart:```typescript// Create a cart (guest)-const cart = await client.orders.create();+const cart = await client.cart.create();// Use orderToken for all cart operations-const options = { orderToken: cart.order_token };+const options = { orderToken: cart.token };// Add itemsawait client.orders.lineItems.create(cart.id, {@@ -110,6 +122,13 @@ await client.orders.complete(cart.id, options);## API Reference+### Store++```typescript+// Get current store information+const store = await client.store.get();+```+### Products```typescript@@ -125,6 +144,11 @@ const products = await client.products.list({const product = await client.products.get('ruby-on-rails-tote', {includes: 'variants,images',});++// Get available filters (price range, availability, options, taxons)+const filters = await client.products.filters({+ taxon_id: 'txn_abc123', // Optional: scope filters to a taxon+});```### Categories (Taxonomies & Taxons)@@ -159,31 +183,42 @@ const categoryProducts = await client.taxons.products.list('categories/clothing'});```-### Cart & Checkout+### Cart++```typescript+// Get current cart+const cart = await client.cart.get({ orderToken: 'xxx' });++// Create a new cart+const newCart = await client.cart.create();++// Associate guest cart with authenticated user+// (after user logs in, merge their guest cart with their account)+await client.cart.associate({+ token: jwtToken, // User's JWT token+ orderToken: cart.token, // Guest cart token+});+```++### Orders & Checkout```typescript-// Create cart+// List orders for authenticated customer+const orders = await client.orders.list({}, { token });++// Create a new order (cart)const cart = await client.orders.create();const options = { orderToken: cart.order_token };-// Add item-await client.orders.lineItems.create(cart.id, {- variant_id: 'var_123',- quantity: 2,+// Get order by ID or number+const order = await client.orders.get('R123456789', {+ includes: 'line_items,shipments',}, options);-// Update item quantity-await client.orders.lineItems.update(cart.id, lineItemId, {- quantity: 3,-}, options);--// Remove item-await client.orders.lineItems.delete(cart.id, lineItemId, options);-// Update order (email, addresses)await client.orders.update(cart.id, {email: '[email protected]',- bill_address_attributes: {+ ship_address: {firstname: 'John',lastname: 'Doe',address1: '123 Main St',@@ -191,7 +226,9 @@ await client.orders.update(cart.id, {zipcode: '10001',phone: '+1 555 123 4567',country_iso: 'US',+ state_abbr: 'NY',},+ bill_address_id: 'addr_xxx', // Or use existing address by ID}, options);// Checkout flow@@ -200,10 +237,71 @@ await client.orders.advance(cart.id, options); // Advance through all stepsawait client.orders.complete(cart.id, options); // Complete the order```+### Line Items++```typescript+const options = { orderToken: cart.token };++// Add item+await client.orders.lineItems.create(cart.id, {+ variant_id: 'var_123',+ quantity: 2,+}, options);++// Update item quantity+await client.orders.lineItems.update(cart.id, lineItemId, {+ quantity: 3,+}, options);++// Remove item+await client.orders.lineItems.delete(cart.id, lineItemId, options);+```++### Coupon Codes++```typescript+const options = { orderToken: cart.token };++// Apply a coupon code+await client.orders.couponCodes.apply(cart.id, 'SAVE20', options);++// Remove a coupon code+await client.orders.couponCodes.remove(cart.id, 'promo_xxx', options);+```++### Store Credits++```typescript+const options = { orderToken: cart.token };++// Apply store credit to order (applies maximum available by default)+await client.orders.addStoreCredit(cart.id, undefined, options);++// Apply specific amount of store credit+await client.orders.addStoreCredit(cart.id, 25.00, options);++// Remove store credit from order+await client.orders.removeStoreCredit(cart.id, options);+```++### Shipments++```typescript+const options = { orderToken: cart.token };++// List shipments for an order+const shipments = await client.orders.shipments.list(cart.id, options);++// Select a shipping rate+await client.orders.shipments.update(cart.id, shipmentId, {+ selected_shipping_rate_id: 'rate_xxx',+}, options);+```+### Payments```typescript-const options = { orderToken: cart.order_token };+const options = { orderToken: cart.token };// Get available payment methods for an orderconst methods = await client.orders.paymentMethods.list(cart.id, options);@@ -219,7 +317,7 @@ const payment = await client.orders.payments.get(cart.id, paymentId, options);```typescript// List countries available for checkout-const countries = await client.countries.list();+const { data: countries } = await client.countries.list();// Get country by ISO code (includes states)const usa = await client.countries.get('US');@@ -229,7 +327,7 @@ console.log(usa.states); // Array of states### Customer Account```typescript-const options = { token: tokens.access_token };+const options = { token: jwtToken };// Get profileconst profile = await client.customer.get(options);@@ -239,9 +337,20 @@ await client.customer.update({first_name: 'John',last_name: 'Doe',}, options);+```-// Manage addresses (nested under customer)-const addresses = await client.customer.addresses.list({}, options);+### Customer Addresses++```typescript+const options = { token: jwtToken };++// List addresses+const { data: addresses } = await client.customer.addresses.list({}, options);++// Get address by ID+const address = await client.customer.addresses.get('addr_xxx', options);++// Create addressawait client.customer.addresses.create({firstname: 'John',lastname: 'Doe',@@ -249,51 +358,92 @@ await client.customer.addresses.create({city: 'New York',zipcode: '10001',country_iso: 'US',+ state_abbr: 'NY',}, options);-await client.customer.addresses.update(addressId, { city: 'Brooklyn' }, options);-await client.customer.addresses.delete(addressId, options);++// Update address+await client.customer.addresses.update('addr_xxx', { city: 'Brooklyn' }, options);++// Delete address+await client.customer.addresses.delete('addr_xxx', options);+```++### Customer Credit Cards++```typescript+const options = { token: jwtToken };++// List saved credit cards+const { data: cards } = await client.customer.creditCards.list({}, options);++// Get credit card by ID+const card = await client.customer.creditCards.get('cc_xxx', options);++// Delete credit card+await client.customer.creditCards.delete('cc_xxx', options);```### Wishlists```typescript-const options = { token: tokens.access_token };+const options = { token: jwtToken };// List wishlists-const wishlists = await client.wishlists.list({}, options);+const { data: wishlists } = await client.wishlists.list({}, options);++// Get wishlist by ID+const wishlist = await client.wishlists.get('wl_xxx', {+ includes: 'wished_items',+}, options);// Create wishlist-const wishlist = await client.wishlists.create({+const newWishlist = await client.wishlists.create({name: 'Birthday Ideas',is_private: true,}, options);-// Manage wishlist items (nested under wishlists)-await client.wishlists.items.create(wishlist.id, {+// Update wishlist+await client.wishlists.update('wl_xxx', {+ name: 'Updated Name',+}, options);++// Delete wishlist+await client.wishlists.delete('wl_xxx', options);+```++### Wishlist Items++```typescript+const options = { token: jwtToken };++// Add item to wishlist+await client.wishlists.items.create('wl_xxx', {variant_id: 'var_123',quantity: 1,}, options);-await client.wishlists.items.update(wishlist.id, itemId, {+// Update item quantity+await client.wishlists.items.update('wl_xxx', 'wi_xxx', {quantity: 2,}, options);-await client.wishlists.items.delete(wishlist.id, itemId, options);--// Delete wishlist-await client.wishlists.delete(wishlist.id, options);+// Remove item from wishlist+await client.wishlists.items.delete('wl_xxx', 'wi_xxx', options);```## Nested Resources-The SDK uses a resource builder pattern (similar to Stripe) for nested resources:+The SDK uses a resource builder pattern for nested resources:| Parent Resource | Nested Resource | Available Methods ||-----------------|-----------------|-------------------|| `orders` | `lineItems` | `create`, `update`, `delete` || `orders` | `payments` | `list`, `get` || `orders` | `paymentMethods` | `list` |+| `orders` | `shipments` | `list`, `update` |+| `orders` | `couponCodes` | `apply`, `remove` || `customer` | `addresses` | `list`, `get`, `create`, `update`, `delete` |+| `customer` | `creditCards` | `list`, `get`, `delete` || `taxons` | `products` | `list` || `wishlists` | `items` | `create`, `update`, `delete` |@@ -302,7 +452,8 @@ Example:// Nested resources follow the pattern: client.parent.nested.method(parentId, ...)await client.orders.lineItems.create(orderId, params, options);await client.orders.payments.list(orderId, options);-await client.customer.addresses.list(options);+await client.orders.shipments.update(orderId, shipmentId, params, options);+await client.customer.addresses.list({}, options);await client.taxons.products.list(taxonId, params, options);await client.wishlists.items.create(wishlistId, params, options);```@@ -356,6 +507,8 @@ import type {StoreTaxon,StoreTaxonomy,StoreLineItem,+ StoreAddress,+ StoreUser,PaginatedResponse,} from '@spree/sdk';@@ -368,6 +521,7 @@ const taxon: StoreTaxon = await client.taxons.get('clothing');The SDK exports all Store API types:+### Core Types- `StoreProduct` - Product data- `StoreVariant` - Variant data- `StoreOrder` - Order/cart data@@ -375,15 +529,49 @@ The SDK exports all Store API types:- `StoreTaxonomy` - Category group- `StoreTaxon` - Individual category- `StoreCountry` - Country with states+- `StoreState` - State/province- `StoreAddress` - Customer address- `StoreUser` - Customer profile-- `StoreWishlist` - Wishlist-- `StoreWishedItem` - Wishlist item+- `StoreStore` - Store configuration++### Commerce Types- `StorePayment` - Payment record- `StorePaymentMethod` - Payment method-- `StoreStore` - Store configuration+- `StoreShipment` - Shipment record+- `StoreShippingRate` - Shipping rate option+- `StoreShippingMethod` - Shipping method+- `StoreCreditCard` - Saved credit card++### Product Types+- `StoreImage` - Product image+- `StorePrice` - Price data+- `StoreOptionType` - Option type (e.g., Size, Color)+- `StoreOptionValue` - Option value (e.g., Small, Red)+- `StoreDigitalLink` - Digital download link++### Wishlist Types+- `StoreWishlist` - Wishlist+- `StoreWishedItem` - Wishlist item++### Utility Types- `PaginatedResponse<T>` - Paginated API response- `AuthTokens` - JWT tokens from login+- `AddressParams` - Address input parameters+- `ProductFiltersResponse` - Product filters response++## Custom Fetch++You can provide a custom fetch implementation:++```typescript+import { createSpreeClient } from '@spree/sdk';++const client = createSpreeClient({+ baseUrl: 'https://api.mystore.com',+ apiKey: 'your-api-key',+ fetch: customFetchImplementation,+});+```## License