@spree/sdk 0.1.8 → 0.2.1

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,61 @@ 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);
+```
+
+### Payment Sessions
+
+Payment sessions provide a unified, provider-agnostic interface for payment processing. They work with any payment gateway (Stripe, Adyen, PayPal, etc.) through a single API.
+
+```typescript
+const options = { orderToken: cart.token };
+
+// Create a payment session (initializes a session with the payment gateway)
+const session = await client.store.orders.paymentSessions.create(cart.id, {
+  payment_method_id: 'pm_xxx',
+  amount: '99.99',             // Optional, defaults to order total
+  external_data: {              // Optional, provider-specific data
+    return_url: 'https://mystore.com/checkout/complete',
+  },
+}, options);
+
+// The session contains provider-specific data (e.g., Stripe client_secret)
+console.log(session.external_data.client_secret);
+
+// Get a payment session
+const existing = await client.store.orders.paymentSessions.get(
+  cart.id, session.id, options
+);
+
+// Update a payment session (e.g., after order total changes)
+await client.store.orders.paymentSessions.update(cart.id, session.id, {
+  amount: '149.99',
+}, options);
+
+// Complete the payment session (after customer confirms payment on the frontend)
+const completed = await client.store.orders.paymentSessions.complete(
+  cart.id, session.id,
+  { session_result: 'success' },
+  options
+);
+console.log(completed.status); // 'completed'
 ```
 
 ### 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 +380,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 +395,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 +412,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 +428,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 +443,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 +471,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 +491,27 @@ 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` | `paymentSessions` | `create`, `get`, `update`, `complete` |
+| `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 +520,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 +540,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 +569,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
@@ -537,10 +593,12 @@ The SDK exports all Store API types:
 ### Commerce Types
 - `StorePayment` - Payment record
 - `StorePaymentMethod` - Payment method
+- `StorePaymentSession` - Provider-agnostic payment session
 - `StoreShipment` - Shipment record
 - `StoreShippingRate` - Shipping rate option
 - `StoreShippingMethod` - Shipping method
 - `StoreCreditCard` - Saved credit card
+- `StoreGiftCard` - Gift card
 
 ### Product Types
 - `StoreImage` - Product image
@@ -553,10 +611,21 @@ 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
 - `AddressParams` - Address input parameters
+- `CreatePaymentSessionParams` - Payment session creation parameters
+- `UpdatePaymentSessionParams` - Payment session update parameters
+- `CompletePaymentSessionParams` - Payment session completion parameters
 - `ProductFiltersResponse` - Product filters response
 
 ## Custom Fetch
@@ -568,7 +637,7 @@ import { createSpreeClient } from '@spree/sdk';
 
 const client = createSpreeClient({
   baseUrl: 'https://api.mystore.com',
-  apiKey: 'your-api-key',
+  publishableKey: 'spree_pk_xxx',
   fetch: customFetchImplementation,
 });
 ```