@spree/docs 0.1.0

package/dist/developer/core-concepts/users.md

@@ -0,0 +1,299 @@
+---
+title: Users
+description: Customers and admin users — authentication, accounts, and permissions
+---
+
+## Overview
+
+Spree has two separate user types:
+
+- **Customers** — users who browse your store, manage their account, and purchase products via the Store API
+- **Admins** — users who manage the store via the Admin Panel
+
+| User type | Class | Default |
+|-----------|-------|---------|
+| Customers | `Spree.user_class` | `Spree::User` |
+| Admins | `Spree.admin_user_class` | `Spree::AdminUser` |
+
+> **INFO:** You can use your own user classes. See the [Customize Authentication guide](/developer/customization/authentication) for details.
+
+## Customers
+
+Customers interact with your store through the Store API. They can register, log in, manage their profile, and view order history.
+
+```mermaid
+erDiagram
+    Customer ||--o{ Order : "places"
+    Customer ||--o{ Address : "has many"
+    Customer ||--o{ Wishlist : "has many"
+    Customer ||--o{ StoreCredit : "has many"
+    Customer ||--o{ PaymentSource : "has many"
+
+    Customer {
+        string id
+        string email
+        string first_name
+        string last_name
+    }
+
+    Order {
+        string number
+        string state
+    }
+
+    Address {
+        string firstname
+        string lastname
+        string address1
+        string city
+    }
+
+    Wishlist {
+        string name
+        boolean is_default
+    }
+```
+
+### Registration
+
+
+```typescript SDK
+const { token, user } = await client.customers.create({
+  email: 'john@example.com',
+  password: 'password123',
+  password_confirmation: 'password123',
+  first_name: 'John',
+  last_name: 'Doe',
+})
+// token => JWT token for subsequent authenticated requests
+// user => { id: "usr_xxx", email: "john@example.com", first_name: "John", ... }
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/customers' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "email": "john@example.com",
+    "password": "password123",
+    "password_confirmation": "password123",
+    "first_name": "John",
+    "last_name": "Doe"
+  }'
+```
+
+
+### Login
+
+
+```typescript SDK
+const { token, user } = await client.auth.login({
+  email: 'john@example.com',
+  password: 'password123',
+})
+// Use the token for authenticated requests
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "email": "john@example.com",
+    "password": "password123"
+  }'
+```
+
+
+The response includes a JWT `token` and a `user` object. Pass the token in subsequent requests via the `Authorization: Bearer <token>` header.
+
+### Token Refresh
+
+Refresh an expiring token to keep the session alive:
+
+
+```typescript SDK
+const { token } = await client.auth.refresh({
+  token: existingToken,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
+  -H 'Authorization: Bearer <jwt_token>'
+```
+
+
+### Customer Profile
+
+
+```typescript SDK
+// Get current customer
+const customer = await client.customer.get()
+// {
+//   id: "usr_xxx",
+//   email: "john@example.com",
+//   first_name: "John",
+//   last_name: "Doe",
+//   default_shipping_address: { ... },
+//   default_billing_address: { ... },
+//   addresses: [{ ... }, { ... }],
+// }
+
+// Update profile
+const updated = await client.customer.update({
+  first_name: 'Jonathan',
+  accepts_email_marketing: true,
+})
+```
+
+```bash cURL
+# Get current customer
+curl 'https://api.mystore.com/api/v3/store/customer' \
+  -H 'Authorization: Bearer <jwt_token>'
+
+# Update profile
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customer' \
+  -H 'Authorization: Bearer <jwt_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "first_name": "Jonathan", "accepts_email_marketing": true }'
+```
+
+
+### Customer Resources
+
+Authenticated customers have access to these resources:
+
+| Resource | Description |
+|----------|-------------|
+| [**Addresses**](/developer/core-concepts/addresses#customer-address-book) | Billing and shipping addresses with default selection |
+| [**Orders**](/developer/core-concepts/orders#order-history) | Past order history |
+| **Credit Cards** | Saved credit cards for checkout |
+| **Payment Sources** | Other saved payment methods (PayPal, Klarna, etc.) |
+| **Store Credits** | Balance assigned by the store, usable at checkout |
+| **Gift Cards** | Gift cards owned by or assigned to the customer |
+| **Wishlists** | Saved product lists |
+
+### Guest Checkout
+
+Customers don't need to register to purchase. Guest checkout uses an order token (`X-Spree-Token`) to identify the cart. See [Orders — Cart](/developer/core-concepts/orders#cart) for details.
+
+## Admin Users
+
+Admin users manage the store via the Admin Panel. They have roles that control what they can access.
+
+```mermaid
+erDiagram
+    AdminUser ||--o{ RoleUser : "has many"
+    RoleUser }o--|| Role : "belongs to"
+    RoleUser }o--|| Store : "scoped to"
+    AdminUser ||--o{ Invitation : "invites"
+
+    AdminUser {
+        string id
+        string email
+    }
+
+    RoleUser {
+        string role_id
+        string resource_type
+        string resource_id
+    }
+
+    Role {
+        string name
+    }
+
+    Invitation {
+        string email
+        string status
+        string token
+        datetime expires_at
+    }
+```
+
+### Roles
+
+Admin users can have different roles that control their permissions:
+
+| Role | Description |
+|------|-------------|
+| `admin` | Full access to all Admin Panel features |
+
+> **INFO:** You can create custom roles with specific permissions. See the [Customize Permissions guide](/developer/customization/permissions) for details.
+
+### Creating Admin Users
+
+Use the Spree CLI to create admin users:
+
+```bash
+spree user create
+```
+
+The CLI will prompt you for the email and password. You can also pass them directly:
+
+```bash
+spree user create --email admin@example.com --password secret123
+```
+
+The created user gets the `admin` role on the default store.
+
+### Inviting Admin Users
+
+You can invite new admins through the Admin Panel or programmatically.
+
+**Via Admin Panel:**
+
+1. Navigate to **Settings → Users**
+2. Click **Invite User**
+3. Enter the email address and select a role
+4. Click **Send Invitation**
+
+The invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
+
+```mermaid
+flowchart TB
+    A[Admin creates invitation] --> B[Invitation email sent]
+    B --> C[Invitee clicks link]
+    C --> D{Has account?}
+    D -->|Yes| E[Log in]
+    D -->|No| F[Create account]
+    E --> G[Accept invitation]
+    F --> G
+    G --> H[Role assigned to store]
+```
+
+#### Invitation Details
+
+| Attribute | Description |
+|-----------|-------------|
+| `email` | Invitee's email address |
+| `token` | Secure token for the invitation link |
+| `status` | `pending` or `accepted` |
+| `expires_at` | Expiration date (default: 2 weeks) |
+| `resource` | The store being granted access to |
+| `role` | The role to assign upon acceptance |
+
+#### Invitation Events
+
+The invitation system publishes [events](/developer/core-concepts/events) you can subscribe to:
+
+| Event | Description |
+|-------|-------------|
+| `invitation.created` | Invitation was created (triggers email) |
+| `invitation.accepted` | Invitation was accepted and role assigned |
+| `invitation.resent` | Invitation was resent to the invitee |
+
+## Permissions
+
+Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. Permissions apply to both customers (Store API access) and admins (Admin Panel access).
+
+See the [Customize Permissions guide](/developer/customization/permissions) for details on creating custom roles and permission sets.
+
+## Related Documentation
+
+- [Addresses](/developer/core-concepts/addresses) — Customer address management
+- [Orders](/developer/core-concepts/orders) — Order history and checkout
+- [Authentication](/developer/customization/authentication) — Custom authentication setup
+- [Permissions](/developer/customization/permissions) — Roles and authorization
+- [Events](/developer/core-concepts/events) — Subscribe to user and invitation events

package/dist/developer/core-concepts/webhooks.md

@@ -0,0 +1,378 @@
+---
+title: Webhooks
+description: Send real-time HTTP notifications to external services when events occur in your store.
+---
+
+## Overview
+
+Webhooks allow your Spree store to send real-time HTTP POST notifications to external services when events occur. When an order is completed, a product is updated, or inventory changes, Spree can automatically notify your CRM, fulfillment service, analytics platform, or any other system.
+
+Webhooks are built on top of Spree's [event system](/developer/core-concepts/events), providing:
+
+- **Multi-store support** - Each store has its own webhook endpoints
+- **Event filtering** - Subscribe to specific events or patterns with wildcards
+- **Secure delivery** - HMAC-SHA256 signatures for payload verification
+- **Automatic retries** - Failed deliveries retry with exponential backoff
+- **Full audit trail** - Track every delivery attempt with response codes and timing
+
+## How Webhooks Work
+
+```mermaid
+flowchart LR
+    subgraph Spree Store
+        A[Event Published] --> B[WebhookEventSubscriber]
+        B --> C{Find Matching<br/>Endpoints}
+        C --> D[Create WebhookDelivery]
+        D --> E[Queue DeliveryJob]
+    end
+
+    subgraph Delivery
+        E --> F[Build JSON Payload]
+        F --> G[Sign with HMAC-SHA256]
+        G --> H[HTTP POST]
+    end
+
+    subgraph External Service
+        H --> I{Response}
+        I -->|2xx| J[Success]
+        I -->|Error| K[Retry with Backoff]
+        K -->|Max Retries| L[Mark Failed]
+        K -->|Retry| H
+    end
+```
+
+1. An event is published (e.g., `order.completed`)
+2. The `WebhookEventSubscriber` receives all events
+3. It finds active webhook endpoints subscribed to that event
+4. For each endpoint, it creates a `WebhookDelivery` record and queues a job
+5. The job sends an HTTP POST request with the event payload and HMAC signature
+
+## Creating Webhook Endpoints
+
+### Via Admin Panel
+
+Navigate to **Settings → Developers → Webhooks** in the admin panel to create and manage webhook endpoints.
+
+### Via Code
+
+```ruby
+endpoint = Spree::WebhookEndpoint.create!(
+  store: Spree::Store.default,
+  url: 'https://example.com/webhooks/spree',
+  subscriptions: ['order.*', 'product.created'],
+  active: true
+)
+
+# The secret_key is auto-generated
+endpoint.secret_key # => "a1b2c3d4e5f6..." (64-character hex string)
+```
+
+### Endpoint Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `url` | String | The HTTPS endpoint URL to receive webhooks |
+| `active` | Boolean | Enable/disable delivery to this endpoint |
+| `subscriptions` | Array | Event patterns to subscribe to |
+| `secret_key` | String | Auto-generated key for HMAC signature verification |
+| `store_id` | Integer | The store this endpoint belongs to |
+
+## Event Subscriptions
+
+The `subscriptions` attribute controls which events trigger webhooks to this endpoint.
+
+### Subscribe to Specific Events
+
+```ruby
+endpoint.subscriptions = ['order.completed', 'order.canceled']
+```
+
+### Subscribe to Event Patterns
+
+Use wildcards to subscribe to multiple related events:
+
+```ruby
+# All order events
+endpoint.subscriptions = ['order.*']
+
+# All creation events
+endpoint.subscriptions = ['*.created']
+
+# Multiple patterns
+endpoint.subscriptions = ['order.*', 'payment.*', 'shipment.shipped']
+```
+
+### Subscribe to All Events
+
+Leave subscriptions empty or use `*` to receive all events:
+
+```ruby
+endpoint.subscriptions = []    # All events
+endpoint.subscriptions = ['*'] # All events (explicit)
+```
+
+## Webhook Payload
+
+Each webhook delivery sends a JSON payload with the following structure. The `data` object uses the same [Store API V3 serializers](/api-reference/introduction) as the REST API, so webhook payloads and API responses share the same schema:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "order.completed",
+  "created_at": "2025-01-15T10:30:00Z",
+  "data": {
+    "id": "or_m3Rp9wXz",
+    "number": "R123456789",
+    "state": "complete",
+    "total": "99.99",
+    "display_total": "$99.99",
+    "item_count": 3,
+    "currency": "USD",
+    "items": [ ... ],
+    "shipments": [ ... ],
+    "payments": [ ... ]
+  },
+  "metadata": {
+    "spree_version": "5.1.0"
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique UUID for this event |
+| `name` | Event name (e.g., `order.completed`) |
+| `created_at` | ISO8601 timestamp when event occurred |
+| `data` | Serialized resource data (V3 API format with [prefixed IDs](/api-reference/introduction)) |
+| `metadata` | Additional context including Spree version |
+
+For complete payload schemas for each event type, see [Webhook Events & Payloads](/api-reference/webhooks-events).
+
+## HTTP Request Details
+
+### Headers
+
+Each webhook request includes these headers:
+
+| Header | Description |
+|--------|-------------|
+| `Content-Type` | `application/json` |
+| `User-Agent` | `Spree-Webhooks/1.0` |
+| `X-Spree-Webhook-Event` | Event name (e.g., `order.completed`) |
+| `X-Spree-Webhook-Signature` | HMAC-SHA256 signature for verification |
+
+### Verifying Webhook Signatures
+
+To ensure webhooks are genuinely from your Spree store, verify the signature:
+
+```ruby
+# In your webhook receiver
+def verify_webhook(request)
+  payload = request.body.read
+  signature = request.headers['X-Spree-Webhook-Signature']
+  secret_key = ENV['SPREE_WEBHOOK_SECRET'] # Your endpoint's secret_key
+
+  expected = OpenSSL::HMAC.hexdigest('SHA256', secret_key, payload)
+
+  ActiveSupport::SecurityUtils.secure_compare(signature, expected)
+end
+```
+
+Example in a Rails controller:
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def receive
+    unless verify_signature
+      head :unauthorized
+      return
+    end
+
+    event = JSON.parse(request.body.read)
+
+    case event['name']
+    when 'order.completed'
+      handle_order_completed(event['data'])
+    when 'product.updated'
+      handle_product_updated(event['data'])
+    end
+
+    head :ok
+  end
+
+  private
+
+  def verify_signature
+    payload = request.body.read
+    request.body.rewind
+
+    signature = request.headers['X-Spree-Webhook-Signature']
+    expected = OpenSSL::HMAC.hexdigest('SHA256', ENV['SPREE_WEBHOOK_SECRET'], payload)
+
+    ActiveSupport::SecurityUtils.secure_compare(signature.to_s, expected)
+  end
+end
+```
+
+## Delivery Status & Retries
+
+### Automatic Retries
+
+Failed webhook deliveries automatically retry up to 5 times with exponential backoff. This handles temporary network issues and endpoint downtime.
+
+### Checking Delivery Status
+
+```ruby
+endpoint = Spree::WebhookEndpoint.find(id)
+
+# Recent deliveries
+endpoint.webhook_deliveries.recent
+
+# Filter by status
+endpoint.webhook_deliveries.successful
+endpoint.webhook_deliveries.failed
+endpoint.webhook_deliveries.pending
+
+# Filter by event
+endpoint.webhook_deliveries.for_event('order.completed')
+```
+
+### Delivery Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `event_name` | Name of the event delivered |
+| `payload` | Complete webhook payload sent |
+| `response_code` | HTTP status code (nil if pending) |
+| `success` | Boolean indicating 2xx response |
+| `execution_time` | Delivery time in milliseconds |
+| `error_type` | `'timeout'`, `'connection_error'`, or nil |
+| `request_errors` | Error message details |
+| `response_body` | Response from endpoint (truncated) |
+| `delivered_at` | Timestamp of delivery attempt |
+
+## Configuration
+
+### Enabling/Disabling Webhooks
+
+Webhooks are enabled by default. To disable globally:
+
+```ruby
+# config/initializers/spree.rb
+Spree::Api::Config.webhooks_enabled = false
+```
+
+### SSL Verification
+
+SSL verification is enabled by default in production. In development, it's disabled to allow testing with self-signed certificates:
+
+```ruby
+# config/initializers/spree.rb
+Spree::Api::Config.webhooks_verify_ssl = true  # Force SSL verification
+Spree::Api::Config.webhooks_verify_ssl = false # Disable (not recommended for production)
+```
+
+## Available Events
+
+Webhooks can subscribe to any event in Spree's event system. See [Events](/developer/core-concepts/events#available-events) for a complete list.
+
+Common webhook events include:
+
+| Event | Description |
+|-------|-------------|
+| `order.completed` | Order checkout finished |
+| `order.canceled` | Order was canceled |
+| `order.paid` | Order is fully paid |
+| `shipment.shipped` | Shipment was shipped |
+| `payment.paid` | Payment was completed |
+| `product.created` | New product created |
+| `product.updated` | Product was modified |
+| `customer.created` | New customer registered |
+
+## Testing Webhooks
+
+### In Development
+
+Use tools like [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to test webhooks locally:
+
+```ruby
+# Create a test endpoint
+endpoint = Spree::WebhookEndpoint.create!(
+  store: Spree::Store.default,
+  url: 'https://your-ngrok-url.ngrok.io/webhooks',
+  subscriptions: ['order.*'],
+  active: true
+)
+
+# Trigger an event
+order = Spree::Order.complete.last
+order.publish_event('order.completed')
+
+# Check delivery
+endpoint.webhook_deliveries.last.success?
+```
+
+### In Tests
+
+```ruby
+RSpec.describe 'Webhook delivery' do
+  let(:store) { create(:store) }
+  let(:endpoint) { create(:webhook_endpoint, store: store, subscriptions: ['order.completed']) }
+  let(:order) { create(:completed_order_with_totals, store: store) }
+
+  it 'delivers webhook when order completes' do
+    stub_request(:post, endpoint.url).to_return(status: 200)
+
+    expect {
+      order.publish_event('order.completed')
+    }.to have_enqueued_job(Spree::WebhookDeliveryJob)
+  end
+end
+```
+
+## Best Practices
+
+
+  - **Respond quickly** — Return a 2xx response as fast as possible. Process webhook data asynchronously in a background job.
+
+  - **Verify signatures** — Always verify the `X-Spree-Webhook-Signature` header to ensure the webhook is authentic.
+
+  - **Handle duplicates** — Use the event `id` to detect and handle duplicate deliveries. Webhooks may be retried.
+
+  - **Subscribe selectively** — Only subscribe to events you need. Use specific patterns rather than `*` when possible.
+
+
+## Troubleshooting
+
+### Webhooks Not Delivering
+
+1. Check that webhooks are enabled: `Spree::Api::Config.webhooks_enabled`
+2. Verify the endpoint is active: `endpoint.active?`
+3. Confirm the endpoint subscribes to the event: `endpoint.subscribed_to?('order.completed')`
+4. Check the event has a `store_id` matching the endpoint's store
+
+### Signature Verification Failing
+
+1. Ensure you're using the raw request body (not parsed JSON)
+2. Verify you're using the correct `secret_key` for this endpoint
+3. Check that no middleware is modifying the request body
+
+### Deliveries Failing
+
+Check the delivery record for details:
+
+```ruby
+delivery = endpoint.webhook_deliveries.failed.last
+delivery.error_type      # => 'timeout' or 'connection_error'
+delivery.request_errors  # => Error message
+delivery.response_code   # => HTTP status code
+delivery.response_body   # => Response from your endpoint
+```
+
+## Related Documentation
+
+- [Events](/developer/core-concepts/events) - Understanding Spree's event system
+- [Customization Quickstart](/developer/customization/quickstart) - Overview of all customization options
+- [Dependencies](/developer/customization/dependencies) - Customizing Spree services