@spree/sdk 0.1.8 → 0.2.0

package/README.md

@@ -20,72 +20,84 @@ import { createSpreeClient } from '@spree/sdk';
 // Initialize the client
 const client = createSpreeClient({
   baseUrl: 'https://api.mystore.com',
-  apiKey: 'your-publishable-api-key',
+  publishableKey: 'spree_pk_xxx',   // Store API
+  secretKey: 'spree_sk_xxx',        // Admin API (optional)
 });
 
-// Browse products
-const products = await client.products.list({
+// Browse products (Store API)
+const products = await client.store.products.list({
   per_page: 10,
   includes: 'variants,images',
 });
 
 // Get a single product
-const product = await client.products.get('ruby-on-rails-tote');
+const product = await client.store.products.get('ruby-on-rails-tote');
 
 // Authentication
-const { token, user } = await client.auth.login({
+const { token, user } = await client.store.auth.login({
   email: 'customer@example.com',
   password: 'password123',
 });
 
 // Create a cart and add items
-const cart = await client.cart.create();
-await client.orders.lineItems.create(cart.id, {
+const cart = await client.store.cart.create();
+await client.store.orders.lineItems.create(cart.id, {
   variant_id: 'var_abc123',
   quantity: 2,
 }, { orderToken: cart.token });
 
 // Checkout flow
-await client.orders.next(cart.id, { orderToken: cart.token });
-await client.orders.complete(cart.id, { orderToken: cart.token });
+await client.store.orders.next(cart.id, { orderToken: cart.token });
+await client.store.orders.complete(cart.id, { orderToken: cart.token });
 ```
 
+## Client Architecture
+
+The SDK exposes two API namespaces:
+
+```typescript
+client.store   // Store API — customer-facing (products, cart, checkout, account)
+client.admin   // Admin API — administrative (coming soon)
+```
+
+All Store API endpoints live under `client.store.*`. The Admin API namespace is ready for future endpoints.
+
 ## Authentication
 
 The SDK supports multiple authentication modes:
 
-### 1. API Key Only (Guest/Public Access)
+### 1. Publishable Key Only (Guest/Public Access)
 
 ```typescript
 const client = createSpreeClient({
   baseUrl: 'https://api.mystore.com',
-  apiKey: 'pk_your-publishable-key',
+  publishableKey: 'spree_pk_xxx',
 });
 
 // Public endpoints work without user authentication
-const products = await client.products.list();
+const products = await client.store.products.list();
 ```
 
-### 2. API Key + JWT (Authenticated Customer)
+### 2. Publishable Key + JWT (Authenticated Customer)
 
 ```typescript
 // Login to get tokens
-const { token, user } = await client.auth.login({
+const { token, user } = await client.store.auth.login({
   email: 'customer@example.com',
   password: 'password123',
 });
 
 // Use token for authenticated requests
-const orders = await client.orders.list({}, { token });
+const orders = await client.store.orders.list({}, { token });
 
 // Refresh token when needed
-const newTokens = await client.auth.refresh({ token });
+const newTokens = await client.store.auth.refresh({ token });
 ```
 
 ### 3. Register New Customer
 
 ```typescript
-const { token, user } = await client.auth.register({
+const { token, user } = await client.store.auth.register({
   email: 'new@example.com',
   password: 'password123',
   password_confirmation: 'password123',
@@ -100,24 +112,24 @@ For guest checkout, use the `token` (or `order_token`) returned when creating a
 
 ```typescript
 // Create a cart (guest)
-const cart = await client.cart.create();
+const cart = await client.store.cart.create();
 
 // Use orderToken for all cart operations
 const options = { orderToken: cart.token };
 
 // Add items
-await client.orders.lineItems.create(cart.id, {
+await client.store.orders.lineItems.create(cart.id, {
   variant_id: 'var_abc123',
   quantity: 1,
 }, options);
 
 // Update order with email
-await client.orders.update(cart.id, {
+await client.store.orders.update(cart.id, {
   email: 'guest@example.com',
 }, options);
 
 // Complete checkout
-await client.orders.complete(cart.id, options);
+await client.store.orders.complete(cart.id, options);
 ```
 
 ## API Reference
@@ -126,14 +138,14 @@ await client.orders.complete(cart.id, options);
 
 ```typescript
 // Get current store information
-const store = await client.store.get();
+const store = await client.store.store.get();
 ```
 
 ### Products
 
 ```typescript
 // List products with filtering
-const products = await client.products.list({
+const products = await client.store.products.list({
   page: 1,
   per_page: 25,
   'q[name_cont]': 'shirt',
@@ -141,12 +153,12 @@ const products = await client.products.list({
 });
 
 // Get single product by ID or slug
-const product = await client.products.get('ruby-on-rails-tote', {
+const product = await client.store.products.get('ruby-on-rails-tote', {
   includes: 'variants,images',
 });
 
 // Get available filters (price range, availability, options, taxons)
-const filters = await client.products.filters({
+const filters = await client.store.products.filters({
   taxon_id: 'txn_abc123', // Optional: scope filters to a taxon
 });
 ```
@@ -155,28 +167,28 @@ const filters = await client.products.filters({
 
 ```typescript
 // List taxonomies
-const taxonomies = await client.taxonomies.list({
+const taxonomies = await client.store.taxonomies.list({
   includes: 'taxons',
 });
 
 // Get taxonomy with taxons
-const categories = await client.taxonomies.get('tax_123', {
+const categories = await client.store.taxonomies.get('tax_123', {
   includes: 'root,taxons',
 });
 
 // List taxons with filtering
-const taxons = await client.taxons.list({
+const taxons = await client.store.taxons.list({
   'q[depth_eq]': 1,           // Top-level categories only
   'q[taxonomy_id_eq]': '123', // Filter by taxonomy
 });
 
 // Get single taxon by ID or permalink
-const taxon = await client.taxons.get('categories/clothing', {
+const taxon = await client.store.taxons.get('categories/clothing', {
   includes: 'ancestors,children', // For breadcrumbs and subcategories
 });
 
 // List products in a category
-const categoryProducts = await client.taxons.products.list('categories/clothing', {
+const categoryProducts = await client.store.taxons.products.list('categories/clothing', {
   page: 1,
   per_page: 12,
   includes: 'images,default_variant',
@@ -187,14 +199,14 @@ const categoryProducts = await client.taxons.products.list('categories/clothing'
 
 ```typescript
 // Get current cart
-const cart = await client.cart.get({ orderToken: 'xxx' });
+const cart = await client.store.cart.get({ orderToken: 'xxx' });
 
 // Create a new cart
-const newCart = await client.cart.create();
+const newCart = await client.store.cart.create();
 
 // Associate guest cart with authenticated user
 // (after user logs in, merge their guest cart with their account)
-await client.cart.associate({
+await client.store.cart.associate({
   token: jwtToken,        // User's JWT token
   orderToken: cart.token, // Guest cart token
 });
@@ -204,19 +216,19 @@ await client.cart.associate({
 
 ```typescript
 // List orders for authenticated customer
-const orders = await client.orders.list({}, { token });
+const orders = await client.store.orders.list({}, { token });
 
 // Create a new order (cart)
-const cart = await client.orders.create();
+const cart = await client.store.orders.create();
 const options = { orderToken: cart.order_token };
 
 // Get order by ID or number
-const order = await client.orders.get('R123456789', {
+const order = await client.store.orders.get('R123456789', {
   includes: 'line_items,shipments',
 }, options);
 
 // Update order (email, addresses)
-await client.orders.update(cart.id, {
+await client.store.orders.update(cart.id, {
   email: 'customer@example.com',
   ship_address: {
     firstname: 'John',
@@ -232,9 +244,9 @@ await client.orders.update(cart.id, {
 }, options);
 
 // Checkout flow
-await client.orders.next(cart.id, options);     // Move to next step
-await client.orders.advance(cart.id, options);  // Advance through all steps
-await client.orders.complete(cart.id, options); // Complete the order
+await client.store.orders.next(cart.id, options);     // Move to next step
+await client.store.orders.advance(cart.id, options);  // Advance through all steps
+await client.store.orders.complete(cart.id, options); // Complete the order
 ```
 
 ### Line Items
@@ -243,18 +255,18 @@ await client.orders.complete(cart.id, options); // Complete the order
 const options = { orderToken: cart.token };
 
 // Add item
-await client.orders.lineItems.create(cart.id, {
+await client.store.orders.lineItems.create(cart.id, {
   variant_id: 'var_123',
   quantity: 2,
 }, options);
 
 // Update item quantity
-await client.orders.lineItems.update(cart.id, lineItemId, {
+await client.store.orders.lineItems.update(cart.id, lineItemId, {
   quantity: 3,
 }, options);
 
 // Remove item
-await client.orders.lineItems.delete(cart.id, lineItemId, options);
+await client.store.orders.lineItems.delete(cart.id, lineItemId, options);
 ```
 
 ### Coupon Codes
@@ -263,10 +275,10 @@ await client.orders.lineItems.delete(cart.id, lineItemId, options);
 const options = { orderToken: cart.token };
 
 // Apply a coupon code
-await client.orders.couponCodes.apply(cart.id, 'SAVE20', options);
+await client.store.orders.couponCodes.apply(cart.id, 'SAVE20', options);
 
 // Remove a coupon code
-await client.orders.couponCodes.remove(cart.id, 'promo_xxx', options);
+await client.store.orders.couponCodes.remove(cart.id, 'promo_xxx', options);
 ```
 
 ### Store Credits
@@ -275,13 +287,13 @@ await client.orders.couponCodes.remove(cart.id, 'promo_xxx', options);
 const options = { orderToken: cart.token };
 
 // Apply store credit to order (applies maximum available by default)
-await client.orders.addStoreCredit(cart.id, undefined, options);
+await client.store.orders.addStoreCredit(cart.id, undefined, options);
 
 // Apply specific amount of store credit
-await client.orders.addStoreCredit(cart.id, 25.00, options);
+await client.store.orders.addStoreCredit(cart.id, 25.00, options);
 
 // Remove store credit from order
-await client.orders.removeStoreCredit(cart.id, options);
+await client.store.orders.removeStoreCredit(cart.id, options);
 ```
 
 ### Shipments
@@ -290,10 +302,10 @@ await client.orders.removeStoreCredit(cart.id, options);
 const options = { orderToken: cart.token };
 
 // List shipments for an order
-const shipments = await client.orders.shipments.list(cart.id, options);
+const shipments = await client.store.orders.shipments.list(cart.id, options);
 
 // Select a shipping rate
-await client.orders.shipments.update(cart.id, shipmentId, {
+await client.store.orders.shipments.update(cart.id, shipmentId, {
   selected_shipping_rate_id: 'rate_xxx',
 }, options);
 ```
@@ -304,23 +316,23 @@ await client.orders.shipments.update(cart.id, shipmentId, {
 const options = { orderToken: cart.token };
 
 // Get available payment methods for an order
-const methods = await client.orders.paymentMethods.list(cart.id, options);
+const methods = await client.store.orders.paymentMethods.list(cart.id, options);
 
 // List payments on an order
-const payments = await client.orders.payments.list(cart.id, options);
+const payments = await client.store.orders.payments.list(cart.id, options);
 
 // Get a specific payment
-const payment = await client.orders.payments.get(cart.id, paymentId, options);
+const payment = await client.store.orders.payments.get(cart.id, paymentId, options);
 ```
 
 ### Geography
 
 ```typescript
 // List countries available for checkout
-const { data: countries } = await client.countries.list();
+const { data: countries } = await client.store.countries.list();
 
 // Get country by ISO code (includes states)
-const usa = await client.countries.get('US');
+const usa = await client.store.countries.get('US');
 console.log(usa.states); // Array of states
 ```
 
@@ -330,10 +342,10 @@ console.log(usa.states); // Array of states
 const options = { token: jwtToken };
 
 // Get profile
-const profile = await client.customer.get(options);
+const profile = await client.store.customer.get(options);
 
 // Update profile
-await client.customer.update({
+await client.store.customer.update({
   first_name: 'John',
   last_name: 'Doe',
 }, options);
@@ -345,13 +357,13 @@ await client.customer.update({
 const options = { token: jwtToken };
 
 // List addresses
-const { data: addresses } = await client.customer.addresses.list({}, options);
+const { data: addresses } = await client.store.customer.addresses.list({}, options);
 
 // Get address by ID
-const address = await client.customer.addresses.get('addr_xxx', options);
+const address = await client.store.customer.addresses.get('addr_xxx', options);
 
 // Create address
-await client.customer.addresses.create({
+await client.store.customer.addresses.create({
   firstname: 'John',
   lastname: 'Doe',
   address1: '123 Main St',
@@ -362,10 +374,14 @@ await client.customer.addresses.create({
 }, options);
 
 // Update address
-await client.customer.addresses.update('addr_xxx', { city: 'Brooklyn' }, options);
+await client.store.customer.addresses.update('addr_xxx', { city: 'Brooklyn' }, options);
 
 // Delete address
-await client.customer.addresses.delete('addr_xxx', options);
+await client.store.customer.addresses.delete('addr_xxx', options);
+
+// Mark as default billing or shipping address
+await client.store.customer.addresses.markAsDefault('addr_xxx', 'billing', options);
+await client.store.customer.addresses.markAsDefault('addr_xxx', 'shipping', options);
 ```
 
 ### Customer Credit Cards
@@ -374,13 +390,13 @@ await client.customer.addresses.delete('addr_xxx', options);
 const options = { token: jwtToken };
 
 // List saved credit cards
-const { data: cards } = await client.customer.creditCards.list({}, options);
+const { data: cards } = await client.store.customer.creditCards.list({}, options);
 
 // Get credit card by ID
-const card = await client.customer.creditCards.get('cc_xxx', options);
+const card = await client.store.customer.creditCards.get('cc_xxx', options);
 
 // Delete credit card
-await client.customer.creditCards.delete('cc_xxx', options);
+await client.store.customer.creditCards.delete('cc_xxx', options);
 ```
 
 ### Wishlists
@@ -389,26 +405,26 @@ await client.customer.creditCards.delete('cc_xxx', options);
 const options = { token: jwtToken };
 
 // List wishlists
-const { data: wishlists } = await client.wishlists.list({}, options);
+const { data: wishlists } = await client.store.wishlists.list({}, options);
 
 // Get wishlist by ID
-const wishlist = await client.wishlists.get('wl_xxx', {
+const wishlist = await client.store.wishlists.get('wl_xxx', {
   includes: 'wished_items',
 }, options);
 
 // Create wishlist
-const newWishlist = await client.wishlists.create({
+const newWishlist = await client.store.wishlists.create({
   name: 'Birthday Ideas',
   is_private: true,
 }, options);
 
 // Update wishlist
-await client.wishlists.update('wl_xxx', {
+await client.store.wishlists.update('wl_xxx', {
   name: 'Updated Name',
 }, options);
 
 // Delete wishlist
-await client.wishlists.delete('wl_xxx', options);
+await client.store.wishlists.delete('wl_xxx', options);
 ```
 
 ### Wishlist Items
@@ -417,18 +433,18 @@ await client.wishlists.delete('wl_xxx', options);
 const options = { token: jwtToken };
 
 // Add item to wishlist
-await client.wishlists.items.create('wl_xxx', {
+await client.store.wishlists.items.create('wl_xxx', {
   variant_id: 'var_123',
   quantity: 1,
 }, options);
 
 // Update item quantity
-await client.wishlists.items.update('wl_xxx', 'wi_xxx', {
+await client.store.wishlists.items.update('wl_xxx', 'wi_xxx', {
   quantity: 2,
 }, options);
 
 // Remove item from wishlist
-await client.wishlists.items.delete('wl_xxx', 'wi_xxx', options);
+await client.store.wishlists.items.delete('wl_xxx', 'wi_xxx', options);
 ```
 
 ## Nested Resources
@@ -437,25 +453,26 @@ 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` |
+| `store.orders` | `lineItems` | `create`, `update`, `delete` |
+| `store.orders` | `payments` | `list`, `get` |
+| `store.orders` | `paymentMethods` | `list` |
+| `store.orders` | `shipments` | `list`, `update` |
+| `store.orders` | `couponCodes` | `apply`, `remove` |
+| `store.customer` | `addresses` | `list`, `get`, `create`, `update`, `delete`, `markAsDefault` |
+| `store.customer` | `creditCards` | `list`, `get`, `delete` |
+| `store.customer` | `giftCards` | `list`, `get` |
+| `store.taxons` | `products` | `list` |
+| `store.wishlists` | `items` | `create`, `update`, `delete` |
 
 Example:
 ```typescript
-// 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.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);
+// Nested resources follow the pattern: client.store.parent.nested.method(parentId, ...)
+await client.store.orders.lineItems.create(orderId, params, options);
+await client.store.orders.payments.list(orderId, options);
+await client.store.orders.shipments.update(orderId, shipmentId, params, options);
+await client.store.customer.addresses.list({}, options);
+await client.store.taxons.products.list(taxonId, params, options);
+await client.store.wishlists.items.create(wishlistId, params, options);
 ```
 
 ## Localization & Currency
@@ -464,13 +481,13 @@ Pass locale and currency headers with any request:
 
 ```typescript
 // Set locale and currency per request
-const products = await client.products.list({}, {
+const products = await client.store.products.list({}, {
   locale: 'fr',
   currency: 'EUR',
 });
 
 // Works with all endpoints
-const taxon = await client.taxons.get('categories/clothing', {
+const taxon = await client.store.taxons.get('categories/clothing', {
   includes: 'ancestors',
 }, {
   locale: 'de',
@@ -484,7 +501,7 @@ const taxon = await client.taxons.get('categories/clothing', {
 import { SpreeError } from '@spree/sdk';
 
 try {
-  await client.products.get('non-existent');
+  await client.store.products.get('non-existent');
 } catch (error) {
   if (error instanceof SpreeError) {
     console.log(error.code);    // 'record_not_found'
@@ -513,8 +530,8 @@ import type {
 } from '@spree/sdk';
 
 // All responses are fully typed
-const products: PaginatedResponse<StoreProduct> = await client.products.list();
-const taxon: StoreTaxon = await client.taxons.get('clothing');
+const products: PaginatedResponse<StoreProduct> = await client.store.products.list();
+const taxon: StoreTaxon = await client.store.taxons.get('clothing');
 ```
 
 ## Available Types
@@ -541,6 +558,7 @@ The SDK exports all Store API types:
 - `StoreShippingRate` - Shipping rate option
 - `StoreShippingMethod` - Shipping method
 - `StoreCreditCard` - Saved credit card
+- `StoreGiftCard` - Gift card
 
 ### Product Types
 - `StoreImage` - Product image
@@ -553,6 +571,14 @@ The SDK exports all Store API types:
 - `StoreWishlist` - Wishlist
 - `StoreWishedItem` - Wishlist item
 
+### Client Types
+- `SpreeClient` - Main client class
+- `StoreClient` - Store API client
+- `AdminClient` - Admin API client
+- `SpreeClientConfig` - Client configuration
+- `RequestOptions` - Per-request options
+- `RetryConfig` - Retry behavior configuration
+
 ### Utility Types
 - `PaginatedResponse<T>` - Paginated API response
 - `AuthTokens` - JWT tokens from login
@@ -568,7 +594,7 @@ import { createSpreeClient } from '@spree/sdk';
 
 const client = createSpreeClient({
   baseUrl: 'https://api.mystore.com',
-  apiKey: 'your-api-key',
+  publishableKey: 'spree_pk_xxx',
   fetch: customFetchImplementation,
 });
 ```