@thorprovider/adapters 3.0.2

package/docs/multi-tenant-channel-scoping.md

@@ -0,0 +1,225 @@
+# Multi-Tenant Channel Scoping
+
+> Backend-agnostic pattern for isolating entities by sales channel using metadata.
+
+## Problem
+
+Thor Commerce deploys one V0 Starter per sales channel (multi-tenant).
+Products and carts are natively scoped by Medusa's `sales_channel_id`, but
+**customers, orders, and categories are not**. A dropshipper must only see
+their own customers — never those of another channel or the main store.
+
+## Solution: Metadata-Based Channel Scope
+
+Tag un-scoped entities with a well-known metadata key:
+
+```
+entity.metadata.sales_channel_id = "sc_01HXXX"
+```
+
+Then filter at the adapter level (L2) before data reaches L3–L5.
+
+### Why metadata?
+
+| Criteria              | Metadata          | Custom DB field       |
+|-----------------------|-------------------|-----------------------|
+| Zero migrations       | ✅                | ❌ per backend        |
+| Works across backends | ✅ (Medusa, Shopify metafields, WC meta) | ❌ vendor-specific |
+| Writable via SDK      | ✅ admin API      | ❌ requires backend deploy |
+| Type-safe             | ⚠️ runtime validation | ✅ DB schema |
+| Query-indexed         | ❌ in-memory filter | ✅ DB index |
+
+For most stores (<10k entities per type) in-memory filtering is acceptable.
+For larger catalogs, consider adding a DB index on
+`customer.metadata->>'sales_channel_id'` in your Medusa backend.
+
+## Architecture
+
+```
+L1 (@thorprovider/types)
+  └─ Customer.metadata, Order.metadata, GetCustomersOptions.salesChannelId
+
+L2 (@thorprovider/adapters)
+  ├─ metadata/channel-scope.ts        ← Pure helpers (build, read, filter)
+  ├─ metadata/channel-scope-validation.ts ← Validation (no external deps)
+  ├─ backend/MedusaMetadataAdapter    ← Read/write metadata per resource type
+  └─ providers/medusa/index.ts        ← assignCustomerToChannel(), filterByChannel()
+
+L5 (V0 Starter)
+  └─ API routes / server actions call assignCustomerToChannel() post-registration
+```
+
+## Usage
+
+### Assign a customer to a channel
+
+```typescript
+// In L5 API route (post-registration)
+const customer = await commerce.assignCustomerToChannel(
+  customerId,
+  process.env.NEXT_PUBLIC_SALES_CHANNEL_ID!,
+  'system',  // optional: who assigned
+);
+```
+
+### List customers scoped to a channel
+
+```typescript
+// Dropshipper view — only their customers
+const customers = await commerce.getCustomers({
+  salesChannelId: process.env.NEXT_PUBLIC_SALES_CHANNEL_ID,
+});
+
+// Admin view — all customers
+const allCustomers = await commerce.getCustomers();
+```
+
+### Assign an order to a channel
+
+```typescript
+await commerce.assignOrderToChannel(
+  orderId,
+  process.env.NEXT_PUBLIC_SALES_CHANNEL_ID!,
+  'checkout-flow',
+);
+```
+
+### Use helpers directly (any entity)
+
+```typescript
+import {
+  buildChannelScopeMetadata,
+  filterByChannel,
+  getChannelScope,
+  isScopedToChannel,
+  partitionByChannel,
+} from '@thorprovider/adapters';
+
+// Build metadata payload
+const meta = buildChannelScopeMetadata('sc_123', 'admin@store.com');
+// → { sales_channel_id: 'sc_123', channel_assigned_at: '2026-03-27T...', channel_assigned_by: 'admin@store.com' }
+
+// Filter an array of entities
+const myCustomers = filterByChannel(allCustomers, 'sc_123');
+
+// Check one entity
+if (isScopedToChannel(customer, 'sc_123')) { /* ... */ }
+
+// Partition into scoped + global
+const { scoped, global } = partitionByChannel(customers, 'sc_123');
+```
+
+### Validation
+
+```typescript
+import {
+  validateChannelScopeAssignment,
+  assertEntityBelongsToChannel,
+  ChannelScopeValidationError,
+} from '@thorprovider/adapters';
+
+// Validates all inputs before assignment
+validateChannelScopeAssignment(customerId, channelId, assignedBy);
+
+// Guard: ensure entity belongs to caller's channel
+try {
+  assertEntityBelongsToChannel(customer, myChannelId);
+} catch (e) {
+  if (e instanceof ChannelScopeValidationError) {
+    return res.status(403).json({ error: 'Access denied' });
+  }
+}
+```
+
+## Extending to New Entity Types
+
+The pattern is generic. To scope a new entity type:
+
+1. **Ensure** the entity type in `@thorprovider/types` has `metadata?: Record<string, unknown>`
+2. **Add** the resource type to `MedusaMetadataAdapter` (`getMetadata` / `setMetadata`)
+3. **Add** a `salesChannelId` filter option to the entity's query options type
+4. **Call** `filterByChannel()` in the provider's list method
+5. **Optionally** add an `assignXToChannel()` convenience method
+
+### Currently supported
+
+| Entity          | Native scoping (Medusa) | Metadata scoping (Thor) |
+|-----------------|------------------------|------------------------|
+| Products        | ✅ `sales_channel_id`   | N/A (native)           |
+| Carts           | ✅ `sales_channel_id`   | N/A (native)           |
+| Categories      | ❌                      | ⚠️ Via product cross-ref |
+| **Customers**   | ❌                      | ✅ `metadata.sales_channel_id` |
+| **Orders**      | ❌                      | ✅ `metadata.sales_channel_id` |
+| Collections     | ❌ (linked via products) | Planned                |
+
+## When to Assign Channel Scope
+
+| Event                      | Action                                      |
+|----------------------------|---------------------------------------------|
+| Customer registers         | `assignCustomerToChannel()` post-registration |
+| Dropshipper creates customer | `assignCustomerToChannel()` in admin flow   |
+| Order completed            | `assignOrderToChannel()` in checkout flow    |
+| Admin reassigns entity     | `assignXToChannel()` from admin UI           |
+
+## Backend-Specific Notes
+
+### Medusa v2
+
+- Uses `admin.customer.update(id, { metadata })` — requires admin JWT
+- Uses `admin.order.update(id, { metadata })` — requires admin JWT
+- Metadata is a JSONB column — no size limit in practice
+- **Not indexed** by default; add a GIN index if filtering >10k entities
+
+### Shopify (planned)
+
+- Would use Customer Metafields API
+- Key: `thor_commerce.sales_channel_id`
+- Namespace isolates Thor metadata from other apps
+
+### WooCommerce (planned)
+
+- Would use `wp_usermeta` table
+- Key: `_thor_sales_channel_id`
+- Prefix `_` hides from admin UI by convention
+
+## Optional: Custom Fetcher Callbacks
+
+For backends that implement custom scoping endpoints (e.g., Medusa Module Link or custom API routes), 
+use the optional `customFetcher` callback in query options:
+
+```typescript
+// Signature: override default SDK logic with custom endpoint
+const customFetcher = async (options: GetCustomersOptions) => {
+  const channelId = options.salesChannelId;
+  if (!channelId) throw new Error('Channel scoping required for custom fetcher');
+  
+  // Call custom endpoint instead of SDK
+  const response = await fetch(`/api/admin/sales-channels/${channelId}/customers`);
+  return response.json();
+};
+
+// Usage in L5 (V0 Starter)
+const customers = await commerce.getCustomers({
+  salesChannelId: 'sc_123',
+  customFetcher,  // ← Uses callback instead of Medusa SDK
+});
+```
+
+### Benefits
+
+| Scenario | Without callback | With callback |
+|----------|------------------|---------------|
+| Medusa Module Link | Requires wrapper function in L5 | `customFetcher` passed at query time |
+| Custom API endpoint | SDK → in-memory filter | Direct server-side filtering |
+| Shopify (future) | Would need separate method | Uniform interface across backends |
+
+The callback pattern defers implementation complexity while maintaining type safety.
+Backends can adopt it independently without changing L3–L5 code.
+
+## Security Considerations
+
+- Channel assignment requires **admin-level authentication**
+- `getCustomers({ salesChannelId })` filters in-memory after fetch (or via callback if provided)
+- Defense-in-depth: combine with JWT scope where available
+- `assertEntityBelongsToChannel()` provides explicit ownership checks
+- Custom fetchers should **validate `salesChannelId`** before calling backend

package/docs/profile-management.md

@@ -0,0 +1,147 @@
+# Profile Management
+
+---
+type: how-to
+tags: [profile, account, customer, metadata, avatar]
+related:
+  - authentication.md
+  - capabilities-system.md
+  - services-overview.md
+updated: 2026-02-28
+---
+
+Guide for managing customer profiles using capability-aware patterns for cross-backend compatibility.
+
+## Prerequisites
+
+- [Authentication set up](authentication.md)
+- User logged in to access profile features
+
+## Quick Example
+
+```typescript
+import { commerce } from '@/lib/commerce';
+
+// Simple profile update
+const updated = await commerce.auth.updateCustomer({
+  first_name: 'Thor',
+  last_name: 'Developer',
+});
+```
+
+## Step-by-Step Instructions
+
+### Step 1: Check Backend Capabilities
+
+Always verify what the backend supports before rendering forms or performing updates.
+
+```typescript
+const { updateEmail, updateProfile, deleteAccount } = commerce.capabilities;
+
+if (updateEmail) {
+  // Render email update field
+}
+```
+
+### Step 2: Retrieve Current Profile
+
+Fetch the customer object to populate your forms.
+
+```typescript
+const customer = await commerce.auth.getCurrentCustomer();
+```
+
+### Step 3: Implement Update Logic
+
+Handle updates carefully, checking for specific field support.
+
+```typescript
+async function handleUpdate(formData) {
+  const updateData = {};
+  
+  if (commerce.capabilities.updateProfile) {
+    updateData.first_name = formData.firstName;
+    updateData.last_name = formData.lastName;
+  }
+  
+  if (commerce.capabilities.updateEmail) {
+    updateData.email = formData.email;
+  }
+  
+  return await commerce.auth.updateCustomer(updateData);
+}
+```
+
+### Step 4: Manage Password & Security
+
+Handle password changes based on whether the backend supports direct or email-based resets.
+
+```typescript
+if (commerce.capabilities.changePasswordDirect) {
+  await commerce.auth.updateCustomer({
+    current_password: 'old',
+    password: 'new',
+  });
+}
+```
+
+## ✅ DO's
+
+1. **Check Capabilities First:** Avoid rendering buttons for features the backend doesn't support.
+2. **Use Metadata for Extensions:** Store extra info like `avatar_url` or `notifications` in `customer.metadata`.
+3. **Handle Errors explicitly:** Distinguish between `EMAIL_TAKEN` and generic update errors.
+4. **Validate on Client:** Use patterns/regex for phone and email before sending to the adapter.
+5. **Protect UI with Loading States:** Backend operations can take time; show a spinner.
+
+## ❌ DONT's
+
+1. **Don't assume all backends are equal:** Medusa v2 has different capabilities than Shopify or WooCommerce.
+2. **Don't hardcode profile fields:** Use the `Customer` interface from `@thorprovider/adapters`.
+3. **Don't ignore account deletion:** Provide a way for users to delete their account if `deleteAccount` is true.
+4. **Don't send sensitive data in metadata:** Metadata is often visible to the user and sometimes less secure.
+5. **Don't forget to re-fetch profile:** After a successful update, the local customer state should be refreshed.
+
+## Common Patterns
+
+### Metadata-based Avatar Management
+Since many backends don't support native avatars, use an external service (S3/Cloudinary) and store the URL in metadata.
+
+```typescript
+await commerce.auth.updateCustomer({
+  metadata: { avatar_url: 'https://...' }
+});
+```
+
+### Adaptive Profile Form
+Render only the fields supported by the current provider.
+
+## Common Errors & Solutions
+
+### Error: `OPERATION_NOT_SUPPORTED`
+**Cause:** Attempting to update a field (like email) on a backend that doesn't allow it.
+**Solution:** Check `commerce.capabilities` before calling the method.
+
+### Error: `EMAIL_TAKEN`
+**Cause:** User tried to change email to one already registered.
+**Solution:** Show a "This email is already in use" validation message.
+
+## Common Pitfalls
+
+> ⚠️ **Pitfall 1: Metadata Overwrites**
+> Some backends overwrite the entire metadata object instead of merging. Always fetch the current ones first if you want to preserve existing fields.
+
+> ⚠️ **Pitfall 2: Password Complexity**
+> Backends have different password requirements. Let the backend validate and handle the error message.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Profile data not saving | Check if the user session is still active |
+| Metadata field missing | Ensure the key exists in the backend's allowed metadata list |
+| 403 Forbidden | User might not have permission to update their own profile |
+
+## Next Steps
+
+- [Capabilities System](capabilities-system.md)
+- [Authentication](authentication.md)

package/docs/providers-overview.md

@@ -0,0 +1,85 @@
+# Providers Overview
+
+---
+type: guide
+tags: [architecture, providers, medusa, shopify, roadmap]
+related:
+  - capabilities-system.md
+  - services-overview.md
+  - getting-started.md
+updated: 2026-02-28
+---
+
+Overview of the e-commerce platforms supported by Thor Adapters and how they are abstracted into a unified interface.
+
+## Overview
+
+Thor Adapters use a "Provider" architecture to connect our application with different e-commerce backends. Each provider acts as a **full compatibility layer**, handling both:
+- **Inbound (Read)**: mapping vendor-specific API responses to the standardized Thor commerce types.
+- **Outbound (Write)**: transforming `@thorprovider/types` objects into the vendor-specific API payloads required for mutations (creating carts, updating addresses, placing orders, managing customers, etc.).
+
+## The Problem
+
+E-commerce backends vary wildly in their API architecture (REST vs GraphQL), authentication methods (JWT, Cookies, OAuth), and feature sets. 
+- **Vendor Lock-in:** Migrating from one backend to another usually requires a total rewrite of the frontend data layer.
+- **Maintenance Burden:** Supporting multiple backends often leads to fragmented codebases with many `if/else` checks for backend types.
+
+Thor Adapters eliminate these problems by wrapping the data layer in a consistent interface.
+
+## Current Support Matrix
+
+### Medusa (v2.0)
+**Status:** ✅ Production Ready
+Our primary integration, highly optimized for headless performance.
+
+### Shopify
+**Status:** 🚧 In Development (Phase 1)
+Focusing on Storefront API integration for product discovery and cart.
+
+### WooCommerce
+**Status:** 🗓️ Planned
+Targeting the REST API for hybrid headless setups.
+
+## Conceptual Foundation
+
+### 1. The Strategy Pattern
+We use the strategy pattern to swap implementation at runtime. Your application logic doesn't care if a product comes from Medusa or Shopify; it only sees the `Product` interface.
+
+### 2. Capabilities-Driven Development
+Instead of checking `if (provider === 'medusa')`, we check `if (commerce.capabilities.canAddMetadata)`. This makes the frontend future-proof as backends evolve.
+
+## Architecture & Relationships
+
+```mermaid
+graph TD
+  A[createProvider Factory] --> B{Configuration}
+  B --> C[Medusa Provider]
+  B --> D[Shopify Provider]
+  B --> E[Mock Provider]
+  C --> F[Unified Commerce Interface]
+  D --> F
+  E --> F
+```
+
+## Design Decisions
+
+- **Medusa-First:** Since Medusa v2 is our primary backend, our standardized types are heavily influenced by its structure (e.g., variant handling).
+- **Graceful Degradation:** If a provider doesn't support a feature (like "Gift Cards"), the corresponding service returns a standardized `NotSupportedError`.
+- **Statelessness:** Providers avoid local state to stay predictable in server-side contexts.
+
+## Common Misconceptions
+
+- **"All providers are identical"**: While the interface is identical, the *behavior* differs (e.g., login speed, pagination limits).
+- **"I can easily switch in production"**: While the code supports it, data migration between backends is still a separate, complex manual task.
+- **"Every provider uses GraphQL"**: We use whatever is most efficient for that backend (GraphQL for Shopify, REST for Medusa).
+
+## Anti-Patterns
+
+1. **Backend-Specific Logic in UI:** Avoid `if (commerce.name === 'medusa')` in your React components.
+2. **Hardcoding Search Syntax:** Search syntax differs across providers; use the standardized `getProducts({ query: '...' })` method.
+
+## Next Steps
+
+- [Reference: Capabilities System](capabilities-system.md)
+- [How-to: Getting Started](getting-started.md)
+- [Workflow: Add New Provider](../../../docs/workflows/legacy/add-provider.md)

package/docs/services-overview.md

@@ -0,0 +1,135 @@
+# Services Overview
+
+---
+type: guide
+tags: [architecture, services, commerce, api, architecture]
+related:
+  - getting-started.md
+  - capabilities-system.md
+  - providers-overview.md
+updated: 2026-02-28
+---
+
+Overview of the functional services provided by Thor adapters and how they interact to provide a unified e-commerce interface.
+
+## Overview
+
+Thor adapters organize commerce functionality into discrete services. This abstraction allows the rest of the application to remain backend-agnostic, interacting with a standardized set of methods regardless of whether the provider is Medusa, Shopify, or a custom backend.
+
+## The Problem
+
+Directly integrating with multiple commerce backends is difficult because:
+- **Inconsistent Schemas:** Every API has different nesting and field names for a "Product".
+- **Varied Authentication:** Some use JWT, some use Cookies, some use Oauth.
+- **Feature Disparity:** Not all backends support "Related Products" or "Gift Cards".
+
+Thor Adapters solve this by providing a unified service layer and a capabilities system to handle these differences gracefully.
+
+## Core Services
+
+### 1. Product Service
+Responsible for retrieving product data, searching, and obtaining recommendations.
+
+**Key capabilities:**
+- Multi-variant support
+- Standardized price ranges
+- Cross-sell/Upsell recommendations
+
+### 2. Collection Service
+Handles grouping of products into categories or collections.
+
+**Key capabilities:**
+- Collection hierarchies
+- Paginated results per collection
+
+### 3. Cart Service
+Manages the lifecycle of a shopping cart, from creation to checkout preparation.
+
+**Key capabilities:**
+- Unified line items
+- Dynamic tax and total calculations
+- Simple add/update/remove operations
+
+#### Medusa v2 note: line item totals
+In Medusa v2 Store API responses, cart line item totals such as `total`, `subtotal`, and `original_total` are only returned when you retrieve cart totals using the recommended query/expansions.
+
+Thor Adapters treat `unit_price` as the reliable baseline (always present) and will fall back to computing a line total as `unit_price × quantity` when totals fields are missing. This prevents `$0.00` line items in the UI while still allowing accurate totals when Medusa returns them.
+
+### 4. Authentication Service
+Handles customer account management and secure sessions.
+
+**Key capabilities:**
+- JWT & Session support
+- Profile and address management
+- Metadata extensions
+
+## Service Interactions
+
+```mermaid
+graph LR
+  A[App] --> B[Commerce Instance]
+  B --> C[Product Service]
+  B --> D[Cart Service]
+  B --> E[Auth Service]
+  C -.-> D
+  D -.-> E
+```
+
+1. **Discovery:** User explores products via Product Service.
+2. **Action:** User adds to cart via Cart Service (which might link to the Customer).
+3. **Checkout:** Cart Service redirects to the provider's checkout or prepares data for a custom one.
+
+## Design Decisions
+
+### Standardized Money Object
+All prices are returned as a `Money` object with `amount` (string) and `currencyCode` to avoid floating-point errors.
+
+### Universal Cursor-based Pagination
+We use cursor-based pagination whenever possible to maintain compatibility with modern backends like Shopify and Medusa v2.
+
+### Fail-fast with Typed Errors
+Instead of returning `null` on errors, we throw a `CommerceError` with a specific `code`, allowing the UI to react appropriately.
+
+## Common Misconceptions
+
+- **"All methods are always available"**: Some backends don't support specific features. Always check `commerce.can('feature')`.
+- **"Updates are immediate in the backend"**: Some providers use eventual consistency. Wait for the response before updating local state.
+- **"The adapter stores state"**: Outside of auth tokens, adapters are largely stateless.
+
+## Anti-Patterns
+
+1. **Hardcoding IDs:** Never hardcode product or variant IDs; always fetch them through the services.
+2. **Ignoring Capabilities:** Calling `auth.deleteAccount` without checking if it's supported will throw an error.
+3. **Direct API calls:** **NEVER** use `fetch` to talk to the backend directly from outside `@thorprovider/adapters`. If the adapter doesn't expose the method you need, add it to `@thorprovider/adapters` first, then consume it from L5. This is non-negotiable — there are no exceptions, not even for Admin API operations.
+
+## Next Steps
+
+- [Reference: Capabilities System](capabilities-system.md)
+- [How-to: Authentication](authentication.md)
+- [How-to: Profile Management](profile-management.md)
+
+## Type Safety
+
+All services are fully typed with TypeScript:
+
+```typescript
+// TypeScript knows the return type
+const products: Product[] = await commerce.getProducts();
+
+// TypeScript validates input
+await commerce.addToCart(cart.id!, [
+  { 
+    merchandiseId: 'variant_123',  // ✅ Required
+    quantity: 2,                    // ✅ Required
+    customAttribute: 'value',       // ❌ Error: invalid property
+  },
+]);
+```
+
+## Resources
+
+- [Capabilities System](./capabilities-system.md) - Feature detection
+- [Providers Overview](./providers-overview.md) - Backend support
+- [Authentication](./authentication.md) - Auth details
+- [Profile Management](./profile-management.md) - Customer operations
+- [TypeScript Types](../src/types/) - Full type definitions