@spree/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vendo Connect Inc., Vendo Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,649 @@
+# @spree/sdk
+
+Official TypeScript SDK for Spree Commerce API v3.
+
+## Installation
+
+```bash
+npm install @spree/sdk
+# or
+yarn add @spree/sdk
+# or
+pnpm add @spree/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createSpreeClient } from '@spree/sdk';
+
+// Initialize the client
+const client = createSpreeClient({
+  baseUrl: 'https://api.mystore.com',
+  apiKey: 'your-publishable-api-key',
+});
+
+// Browse products
+const products = await client.products.list({
+  per_page: 10,
+  includes: 'variants,images',
+});
+
+// Get a single product
+const product = await client.products.get('ruby-on-rails-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.cart.create();
+await client.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 });
+```
+
+## Authentication
+
+The SDK supports multiple authentication modes:
+
+### 1. API Key Only (Guest/Public Access)
+
+```typescript
+const client = createSpreeClient({
+  baseUrl: 'https://api.mystore.com',
+  apiKey: 'pk_your-publishable-key',
+});
+
+// Public endpoints work without user authentication
+const products = await client.products.list();
+```
+
+### 2. API Key + JWT (Authenticated Customer)
+
+```typescript
+// Login to get tokens
+const { token, user } = await client.auth.login({
+  email: 'customer@example.com',
+  password: 'password123',
+});
+
+// Use token for authenticated requests
+const orders = await client.orders.list({}, { token });
+
+// Refresh token when needed
+const newTokens = await client.auth.refresh({ token });
+```
+
+### 3. Register New Customer
+
+```typescript
+const { token, user } = await client.auth.register({
+  email: 'new@example.com',
+  password: 'password123',
+  password_confirmation: 'password123',
+  first_name: 'John',
+  last_name: 'Doe',
+});
+```
+
+## Guest Checkout
+
+For guest checkout, use the `token` (or `order_token`) returned when creating a cart:
+
+```typescript
+// Create a cart (guest)
+const cart = await client.cart.create();
+
+// Use orderToken for all cart operations
+const options = { orderToken: cart.token };
+
+// Add items
+await client.orders.lineItems.create(cart.id, {
+  variant_id: 'var_abc123',
+  quantity: 1,
+}, options);
+
+// Update order with email
+await client.orders.update(cart.id, {
+  email: 'guest@example.com',
+}, options);
+
+// Complete checkout
+await client.orders.complete(cart.id, options);
+```
+
+## API Reference
+
+### Store
+
+```typescript
+// Get current store information
+const store = await client.store.get();
+```
+
+### Products
+
+```typescript
+// List products with filtering
+const products = await client.products.list({
+  page: 1,
+  per_page: 25,
+  'q[name_cont]': 'shirt',
+  includes: 'variants,images,taxons',
+});
+
+// Get single product by ID or slug
+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)
+
+```typescript
+// List taxonomies
+const taxonomies = await client.taxonomies.list({
+  includes: 'taxons',
+});
+
+// Get taxonomy with taxons
+const categories = await client.taxonomies.get('tax_123', {
+  includes: 'root,taxons',
+});
+
+// List taxons with filtering
+const taxons = await client.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', {
+  includes: 'ancestors,children', // For breadcrumbs and subcategories
+});
+
+// List products in a category
+const categoryProducts = await client.taxons.products.list('categories/clothing', {
+  page: 1,
+  per_page: 12,
+  includes: 'images,default_variant',
+});
+```
+
+### 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
+// 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 };
+
+// Get order by ID or number
+const order = await client.orders.get('R123456789', {
+  includes: 'line_items,shipments',
+}, options);
+
+// Update order (email, addresses)
+await client.orders.update(cart.id, {
+  email: 'customer@example.com',
+  ship_address: {
+    firstname: 'John',
+    lastname: 'Doe',
+    address1: '123 Main St',
+    city: 'New York',
+    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
+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
+```
+
+### 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.token };
+
+// Get available payment methods for an order
+const methods = await client.orders.paymentMethods.list(cart.id, options);
+
+// List payments on an order
+const payments = await client.orders.payments.list(cart.id, options);
+
+// Get a specific payment
+const payment = await client.orders.payments.get(cart.id, paymentId, options);
+```
+
+### 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
+```
+
+### Customer Account
+
+```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);
+```
+
+### 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',
+  address1: '123 Main St',
+  city: 'New York',
+  zipcode: '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);
+```
+
+### 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: jwtToken };
+
+// List wishlists
+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 newWishlist = await client.wishlists.create({
+  name: 'Birthday Ideas',
+  is_private: true,
+}, options);
+
+// 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);
+
+// Update item quantity
+await client.wishlists.items.update('wl_xxx', 'wi_xxx', {
+  quantity: 2,
+}, options);
+
+// Remove item from wishlist
+await client.wishlists.items.delete('wl_xxx', 'wi_xxx', options);
+```
+
+## 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` |
+
+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);
+```
+
+## Localization & Currency
+
+Pass locale and currency headers with any request:
+
+```typescript
+// Set locale and currency per request
+const products = await client.products.list({}, {
+  locale: 'fr',
+  currency: 'EUR',
+});
+
+// Works with all endpoints
+const taxon = await client.taxons.get('categories/clothing', {
+  includes: 'ancestors',
+}, {
+  locale: 'de',
+  currency: 'EUR',
+});
+```
+
+## Error Handling
+
+```typescript
+import { SpreeError } from '@spree/sdk';
+
+try {
+  await client.products.get('non-existent');
+} catch (error) {
+  if (error instanceof SpreeError) {
+    console.log(error.code);    // 'record_not_found'
+    console.log(error.message); // 'Product not found'
+    console.log(error.status);  // 404
+    console.log(error.details); // Validation errors (if any)
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK includes full TypeScript support with generated types from the API serializers:
+
+```typescript
+import type {
+  StoreProduct,
+  StoreOrder,
+  StoreVariant,
+  StoreTaxon,
+  StoreTaxonomy,
+  StoreLineItem,
+  StoreAddress,
+  StoreUser,
+  PaginatedResponse,
+} from '@spree/sdk';
+
+// All responses are fully typed
+const products: PaginatedResponse<StoreProduct> = await client.products.list();
+const taxon: StoreTaxon = await client.taxons.get('clothing');
+```
+
+## Available Types
+
+The SDK exports all Store API types:
+
+### Core Types
+- `StoreProduct` - Product data
+- `StoreVariant` - Variant data
+- `StoreOrder` - Order/cart data
+- `StoreLineItem` - Line item in cart
+- `StoreTaxonomy` - Category group
+- `StoreTaxon` - Individual category
+- `StoreCountry` - Country with states
+- `StoreState` - State/province
+- `StoreAddress` - Customer address
+- `StoreUser` - Customer profile
+- `StoreStore` - Store configuration
+
+### Commerce Types
+- `StorePayment` - Payment record
+- `StorePaymentMethod` - Payment method
+- `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,
+});
+```
+
+## Development
+
+### Setup
+
+```bash
+cd sdk
+npm install
+```
+
+### Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm test` | Run tests once |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run test:coverage` | Run tests with coverage report |
+| `npm run typecheck` | Type-check with `tsc --noEmit` |
+| `npm run build` | Build CJS + ESM bundles with `tsup` |
+| `npm run dev` | Build in watch mode |
+| `npm run console` | Interactive REPL for testing the SDK |
+
+### Testing
+
+Tests use [Vitest](https://vitest.dev/) with [MSW](https://mswjs.io/) (Mock Service Worker) for API mocking at the network level.
+
+```bash
+# Run all tests
+npm test
+
+# Run in watch mode during development
+npm run test:watch
+
+# Run with coverage
+npm run test:coverage
+```
+
+Test files live in `tests/` and follow the structure:
+
+- `tests/mocks/handlers.ts` - MSW request handlers with fixture data
+- `tests/mocks/server.ts` - MSW server instance
+- `tests/setup.ts` - Server lifecycle (listen/reset/close)
+- `tests/helpers.ts` - `createTestClient()` and constants
+- `tests/*.test.ts` - Test suites per resource (auth, products, orders, etc.)
+
+To add tests for a new endpoint, add an MSW handler in `handlers.ts` and create a corresponding test file.
+
+### Releasing
+
+This package uses [Changesets](https://github.com/changesets/changesets) for version management and publishing.
+
+**After making changes:**
+
+```bash
+npx changeset
+```
+
+This prompts you to select a semver bump type (patch/minor/major) and write a summary. A changeset file is created in `.changeset/`.
+
+**How releases work:**
+
+1. Changeset files are committed with your PR
+2. When merged to `main`, a GitHub Action creates a "Version Packages" PR that bumps the version and updates the CHANGELOG
+3. When that PR is merged, the package is automatically published to npm
+
+**Manual release (if needed):**
+
+```bash
+npm run version   # Apply changesets and bump version
+npm run release   # Build and publish to npm
+```
+
+## License
+
+BSD-3-Clause