@spree/docs 0.1.0

package/dist/developer/sdk/quickstart.md

@@ -0,0 +1,82 @@
+---
+title: Quickstart
+description: Install and start using the Spree SDK in your project
+---
+
+## Installation
+
+```bash
+npm install @spree/sdk
+# or
+yarn add @spree/sdk
+# or
+pnpm add @spree/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from '@spree/sdk';
+
+// Initialize the client
+const client = createClient({
+  baseUrl: 'https://api.mystore.com',
+  publishableKey: 'spree_pk_xxx',   // Store API
+});
+
+// Browse products (Store API)
+const products = await client.products.list({
+  limit: 10,
+  expand: ['variants', 'media'],
+});
+
+// Get a single product
+const product = await client.products.get('spree-tote');
+
+// Authentication
+const { token, user } = await client.auth.login({
+  email: 'customer@example.com',
+  password: 'password123',
+});
+
+// Create a cart and add items
+const cart = await client.carts.create();
+await client.carts.items.create(cart.id, {
+  variant_id: 'var_abc123',
+  quantity: 2,
+}, { spreeToken: cart.token });
+
+// Checkout flow
+await client.carts.complete(cart.id, { spreeToken: cart.token });
+```
+
+## Nested Resources
+
+The SDK uses a resource builder pattern for nested resources:
+
+| Parent Resource | Nested Resource | Available Methods |
+|-----------------|-----------------|-------------------|
+| `carts` | `items` | `create`, `update`, `delete` |
+| `carts` | `payments` | `list`, `get`, `create` |
+| `carts` | `paymentMethods` | `list` |
+| `carts` | `paymentSessions` | `create`, `get`, `update`, `complete` |
+| `carts` | `fulfillments` | `list`, `update` |
+| `carts` | `couponCodes` | `apply`, `remove` |
+| `carts` | `storeCredits` | `apply`, `remove` |
+| `customer` | `addresses` | `list`, `get`, `create`, `update`, `delete`, `markAsDefault` |
+| `customer` | `creditCards` | `list`, `get`, `delete` |
+| `customer` | `giftCards` | `list`, `get` |
+| `customer` | `orders` | `list` |
+| `customer` | `paymentSetupSessions` | `create`, `get`, `complete` |
+| `categories` | `products` | `list` |
+| `wishlists` | `items` | `create`, `update`, `delete` |
+
+```typescript
+// Nested resources follow the pattern: client.parent.nested.method(parentId, ...)
+await client.carts.items.create(cartId, params, options);
+await client.carts.payments.list(cartId, options);
+await client.carts.fulfillments.update(cartId, fulfillmentId, params, options);
+await client.customer.addresses.list({}, options);
+await client.categories.products.list(categoryId, params, options);
+await client.wishlists.items.create(wishlistId, params, options);
+```

package/dist/developer/sdk/store/account.md

@@ -0,0 +1,67 @@
+---
+title: Customer Account
+description: Manage customer profiles, addresses, and credit cards with the Spree SDK
+---
+
+## Customer Profile
+
+```typescript
+const options = { token: jwtToken };
+
+// Get profile
+const profile = await client.customer.get(options);
+
+// Update profile
+await client.customer.update({
+  first_name: 'John',
+  last_name: 'Doe',
+}, options);
+```
+
+## 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({
+  first_name: 'John',
+  last_name: 'Doe',
+  address1: '123 Main St',
+  city: 'New York',
+  postal_code: '10001',
+  country_iso: 'US',
+  state_abbr: 'NY',
+}, options);
+
+// Update address
+await client.customer.addresses.update('addr_xxx', { city: 'Brooklyn' }, options);
+
+// Delete address
+await client.customer.addresses.delete('addr_xxx', options);
+
+// Mark as default billing or shipping address
+await client.customer.addresses.markAsDefault('addr_xxx', 'billing', options);
+await client.customer.addresses.markAsDefault('addr_xxx', 'shipping', options);
+```
+
+## 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);
+```

package/dist/developer/sdk/store/cart-checkout.md

@@ -0,0 +1,140 @@
+---
+title: Cart, Checkout & Orders
+description: Manage carts, line items, coupons, checkout flow, and completed orders with the Spree SDK
+---
+
+The Store API is split into two resource groups:
+
+- **Carts** — managing shopping carts, items, coupon codes, checkout flow (addresses, delivery, payments, completion)
+- **Orders** — retrieving completed orders
+
+All cart and checkout endpoints require a `cartId` as the first argument.
+
+## Carts
+
+### Create & Retrieve
+
+```typescript
+// Create a new cart
+const cart = await client.carts.create();
+
+// Get a specific cart
+const cart = await client.carts.get(cartId, { spreeToken: 'xxx' });
+
+// List carts
+const carts = await client.carts.list();
+
+// Delete a cart
+await client.carts.delete(cartId, { spreeToken: cart.token });
+
+// Associate guest cart with authenticated user
+// (after user logs in, merge their guest cart with their account)
+await client.carts.associate(cartId, {
+  token: jwtToken,         // User's JWT token
+  spreeToken: cart.token,  // Guest cart token
+});
+```
+
+### Items
+
+```typescript
+const options = { spreeToken: cart.token };
+
+// Add item
+await client.carts.items.create(cartId, {
+  variant_id: 'var_123',
+  quantity: 2,
+}, options);
+
+// Update item quantity
+await client.carts.items.update(cartId, lineItemId, {
+  quantity: 3,
+}, options);
+
+// Remove item
+await client.carts.items.delete(cartId, lineItemId, options);
+```
+
+### Coupon Codes
+
+```typescript
+const options = { spreeToken: cart.token };
+
+// Apply a coupon code
+await client.carts.couponCodes.apply(cartId, 'SAVE20', options);
+
+// Remove a coupon code
+await client.carts.couponCodes.remove(cartId, 'SUMMER20', options);
+```
+
+## Checkout
+
+### Update Cart
+
+```typescript
+await client.carts.update(cartId, {
+  email: 'customer@example.com',
+  shipping_address: {
+    first_name: 'John',
+    last_name: 'Doe',
+    address1: '123 Main St',
+    city: 'New York',
+    postal_code: '10001',
+    phone: '+1 555 123 4567',
+    country_iso: 'US',
+    state_abbr: 'NY',
+  },
+  billing_address_id: 'addr_xxx', // Or use existing address by ID
+}, { spreeToken: cart.token });
+```
+
+### Complete Checkout
+
+```typescript
+await client.carts.complete(cartId, { spreeToken: cart.token });
+```
+
+### Fulfillments
+
+```typescript
+const options = { spreeToken: cart.token };
+
+// List fulfillments
+const fulfillments = await client.carts.fulfillments.list(cartId, options);
+
+// Select a delivery rate
+await client.carts.fulfillments.update(cartId, fulfillmentId, {
+  selected_delivery_rate_id: 'rate_xxx',
+}, options);
+```
+
+### Store Credits
+
+```typescript
+const options = { spreeToken: cart.token };
+
+// Apply store credit (applies maximum available by default)
+await client.carts.storeCredits.apply(cartId, undefined, options);
+
+// Apply specific amount of store credit
+await client.carts.storeCredits.apply(cartId, 25.00, options);
+
+// Remove store credit from order
+await client.carts.storeCredits.remove(cartId, options);
+```
+
+## Orders
+
+### Get a Completed Order
+
+```typescript
+const order = await client.orders.get('R123456789', {
+  expand: ['items', 'fulfillments'],
+}, { spreeToken: cart.token });
+```
+
+### List Orders (Authenticated Customer)
+
+```typescript
+const orders = await client.customer.orders.list({}, { token });
+```

package/dist/developer/sdk/store/markets.md

@@ -0,0 +1,151 @@
+---
+title: Markets
+description: Fetch markets, resolve by country, and list market countries with the Spree SDK
+---
+
+## List Markets
+
+Returns all markets for the current store with their countries, currency, locales, and tax configuration.
+
+
+```typescript SDK
+const { data: markets } = await client.markets.list()
+
+markets.forEach(market => {
+  market.id               // "mkt_UkLWZg9DAJ"
+  market.name             // "North America"
+  market.currency         // "USD"
+  market.default_locale   // "en"
+  market.tax_inclusive    // false
+  market.default          // true
+  market.supported_locales // ["en", "es"]
+  market.countries        // [{ iso: "US", name: "United States of America", ... }]
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+**Response:**
+
+```json
+{
+  "data": [
+    {
+      "id": "mkt_UkLWZg9DAJ",
+      "name": "North America",
+      "currency": "USD",
+      "default_locale": "en",
+      "tax_inclusive": false,
+      "default": true,
+      "supported_locales": ["en", "es"],
+      "countries": [
+        { "iso": "US", "iso3": "USA", "name": "United States of America", "states_required": true, "zipcode_required": true }
+      ]
+    },
+    {
+      "id": "mkt_gbHJdmfrXB",
+      "name": "Europe",
+      "currency": "EUR",
+      "default_locale": "de",
+      "tax_inclusive": true,
+      "default": false,
+      "supported_locales": ["de", "en", "fr"],
+      "countries": [
+        { "iso": "DE", "iso3": "DEU", "name": "Germany", "states_required": false, "zipcode_required": true },
+        { "iso": "FR", "iso3": "FRA", "name": "France", "states_required": false, "zipcode_required": true }
+      ]
+    }
+  ]
+}
+```
+
+## Get a Market
+
+
+```typescript SDK
+const market = await client.markets.get('mkt_gbHJdmfrXB')
+
+market.name      // "Europe"
+market.currency  // "EUR"
+market.countries // [{ iso: "DE", ... }, { iso: "FR", ... }]
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Resolve Market by Country
+
+Determine which market applies for a given country ISO code. Useful for auto-selecting the correct currency and locale when a customer's location is known.
+
+
+```typescript SDK
+const market = await client.markets.resolve('DE')
+
+market.id       // "mkt_gbHJdmfrXB"
+market.name     // "Europe"
+market.currency // "EUR"
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+> **INFO:** If no market matches the given country, a `404` error is returned.
+
+## List Countries in a Market
+
+Returns countries belonging to a specific market. Use this for address form country dropdowns during checkout.
+
+
+```typescript SDK
+const { data: countries } = await client.markets.countries.list('mkt_gbHJdmfrXB')
+
+countries.forEach(country => {
+  country.iso              // "DE"
+  country.name             // "Germany"
+  country.states_required  // false
+  country.zipcode_required // true
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Get a Country in a Market
+
+Returns a single country by ISO code within a market. Use `expand: ['states']` for address forms that need state/province dropdowns.
+
+
+```typescript SDK
+const country = await client.markets.countries.get('mkt_gbHJdmfrXB', 'US', {
+  expand: ['states'],
+})
+
+country.iso    // "US"
+country.name   // "United States of America"
+country.states // [{ id: "st_xxx", name: "New York", abbr: "NY" }, ...]
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries/US?expand=states' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Related Documentation
+
+- [Markets](/developer/core-concepts/markets) — Market concepts, zones, and configuration
+- [Localization](/api-reference/store-api/localization) — Locale and currency headers
+- [Geography](/developer/sdk/store/products#geography) — Global country endpoints

package/dist/developer/sdk/store/payments.md

@@ -0,0 +1,96 @@
+---
+title: Payments & Delivery
+description: Handle payments, payment sessions, and delivery with the Spree SDK
+---
+
+All payment and delivery endpoints require a `cartId` as the first argument.
+
+## Payment Methods
+
+```typescript
+const options = { spreeToken: cart.token };
+
+// Get available payment methods for the current cart
+const methods = await client.carts.paymentMethods.list(cartId, options);
+
+// Each method includes a `session_required` flag:
+// - true  → use Payment Sessions (Stripe, Adyen, PayPal, etc.)
+// - false → use direct payment creation (Check, Cash on Delivery, Bank Transfer, etc.)
+```
+
+## Payments
+
+```typescript
+const options = { spreeToken: cart.token };
+
+// List payments on the current cart
+const payments = await client.carts.payments.list(cartId, options);
+
+// Get a specific payment
+const payment = await client.carts.payments.get(cartId, paymentId, options);
+
+// Create a payment for a non-session payment method
+// (e.g. Check, Cash on Delivery, Bank Transfer, Purchase Order)
+const payment = await client.carts.payments.create(cartId, {
+  payment_method_id: 'pm_xxx',
+  amount: '99.99',              // Optional, defaults to order total minus store credits
+  metadata: {                   // Optional, write-only metadata
+    purchase_order_number: 'PO-12345',
+  },
+}, options);
+```
+
+> **NOTE:** `payments.create()` only works with non-session payment methods (where `session_required` is `false`).
+>   For session-based gateways like Stripe or Adyen, use `paymentSessions.create()` instead.
+
+## 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 = { spreeToken: cart.token };
+
+// Create a payment session (initializes a session with the payment gateway)
+const session = await client.carts.paymentSessions.create(cartId, {
+  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.carts.paymentSessions.get(
+  cartId, session.id, options
+);
+
+// Update a payment session (e.g., after order total changes)
+await client.carts.paymentSessions.update(cartId, session.id, {
+  amount: '149.99',
+}, options);
+
+// Complete the payment session (after customer confirms payment on the frontend)
+const completed = await client.carts.paymentSessions.complete(
+  cartId, session.id,
+  { session_result: 'success' },
+  options
+);
+console.log(completed.status); // 'completed'
+```
+
+## Fulfillments
+
+```typescript
+const options = { spreeToken: cart.token };
+
+// List fulfillments for the current cart
+const fulfillments = await client.carts.fulfillments.list(cartId, options);
+
+// Select a delivery rate
+await client.carts.fulfillments.update(cartId, fulfillmentId, {
+  selected_delivery_rate_id: 'rate_xxx',
+}, options);
+```

package/dist/developer/sdk/store/products.md

@@ -0,0 +1,149 @@
+---
+title: Products & Categories
+description: Browse products and categories with the Spree SDK
+---
+
+## Products
+
+### List Products
+
+```typescript
+const products = await client.products.list({
+  page: 1,
+  limit: 25,
+  expand: ['variants', 'media', 'categories'],
+});
+```
+
+### Filtering Products
+
+Use flat param keys — the SDK wraps them in `q[...]` automatically:
+
+```typescript
+const products = await client.products.list({
+  name_cont: 'shirt',                                     // Name contains
+  price_gte: 20,                                           // Min price
+  price_lte: 100,                                          // Max price
+  with_option_value_ids: ['optval_abc', 'optval_def'], // By option values
+  in_stock: true,                                          // In stock only
+  search: 'blue shirt',                                     // Full-text search
+});
+```
+
+### Sorting Products
+
+Pass `sort` with one of the supported values. Prefix with `-` for descending order:
+
+```typescript
+const products = await client.products.list({
+  sort: 'price',        // price, -price, best_selling,
+                         // name, -name, -available_on, available_on
+});
+```
+
+### Field Selection
+
+Request only specific fields to reduce payload size:
+
+```typescript
+const products = await client.products.list({
+  fields: ['name', 'slug', 'price', 'display_price'],
+});
+
+const product = await client.products.get('spree-tote', {
+  fields: ['name', 'slug', 'price'],
+  expand: ['media'],  // expanded associations are always included
+});
+```
+
+`id` is always included. Omit `fields` to return all fields.
+
+### Nested Expand
+
+Use dot notation to expand nested associations (up to 4 levels):
+
+```typescript
+// Expand variants with their images in one request
+const product = await client.products.get('spree-tote', {
+  expand: ['variants.media', 'option_types'],
+});
+
+// Access nested data
+product.variants.forEach(variant => {
+  console.log(variant.media); // Media are included
+});
+```
+
+### Get a Product
+
+Fetch a single product by slug or prefix ID:
+
+```typescript
+const product = await client.products.get('spree-tote', {
+  expand: ['variants', 'media'],
+});
+```
+
+### Product Filters
+
+Get available filters (price range, availability, options, categories) and sort options for building filter UIs:
+
+```typescript
+const filters = await client.products.filters({
+  category_id: 'ctg_abc123', // Optional: scope filters to a category
+});
+
+// Response:
+// {
+//   filters: [
+//     { id: 'price', type: 'price_range', min: 9.99, max: 199.99, currency: 'USD' },
+//     { id: 'availability', type: 'availability', options: [{ id: 'in_stock', count: 42 }, ...] },
+//     { id: 'opttype_abc', type: 'option', name: 'color', presentation: 'Color', options: [...] },
+//     { id: 'categories', type: 'category', options: [{ id: 'ctg_abc', name: 'Shirts', permalink: '...', count: 12 }] },
+//   ],
+//   sort_options: [{ id: 'manual' }, { id: 'price' }, { id: 'best_selling' }, ...],
+//   default_sort: 'manual',
+//   total_count: 85,
+// }
+```
+
+## Categories
+
+### List Categories
+
+```typescript
+const categories = await client.categories.list({
+  depth_eq: 1,              // Top-level categories only
+});
+```
+
+### Get a Category
+
+Fetch by ID or permalink:
+
+```typescript
+const category = await client.categories.get('clothing/shirts', {
+  expand: ['ancestors', 'children'], // For breadcrumbs and subcategories
+});
+```
+
+### List Products in a Category
+
+```typescript
+const categoryProducts = await client.categories.products.list('clothing/shirts', {
+  page: 1,
+  limit: 12,
+  expand: ['media', 'default_variant'],
+});
+```
+
+## Geography
+
+```typescript
+// List countries available for checkout
+const { data: countries } = await client.countries.list();
+
+// Get country by ISO code (includes states)
+const usa = await client.countries.get('US');
+console.log(usa.states); // Array of states
+```