Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Update SDK README with comprehensive API documentation [Skip CI]

Damian Legawiec3e10aae08adc
diff --git a/sdk/README.md b/sdk/README.md
index 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({
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 authentication
const 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({
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 items
await 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, {
- 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 steps
await 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 order
const 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 profile
const 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 address
await 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