Update SPP integration docs to reflect completed implementation

Mark all docs as Implemented, fix route paths (spp_publish not publish),
correct authentication code samples, add content management endpoint
spec, update cache TTL references, and mark checklists as done.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: etewiah

docs/api/spp/README.md

@@ -1,5 +1,7 @@
 # SPP–PWB Integration
 
+**Status:** Implemented (Phases 1–6 complete)
+
 SinglePropertyPages (SPP) is an Astro.js application that generates standalone marketing microsites for individual property listings. It integrates with PropertyWebBuilder (PWB) as a data backend.
 
 **Deployment model:** Option B — SPP serves pages independently on its own domain. PWB is a data API. See [Architecture](#architecture) below.
@@ -10,14 +12,14 @@ SinglePropertyPages (SPP) is an Astro.js application that generates standalone m
 
 ## Documents
 
-| Document | What It Covers |
-|----------|---------------|
-| [SppListing Model](./spp-listing-model.md) | Data model, migration, model definition, relationship to existing listings |
-| [Endpoints](./endpoints.md) | Publish, unpublish, leads API specs + enquiry linking + response conventions |
-| [Authentication](./authentication.md) | API key auth via `X-API-Key` header and `WebsiteIntegration` |
-| [CORS](./cors.md) | `rack-cors` configuration for SPP origins |
-| [SEO](./seo.md) | Canonical URLs, sitemaps, JSON-LD coordination between PWB and SPP |
-| [Data Freshness](./data-freshness.md) | Cache headers (phase 1) and webhooks (phase 2) |
+| Document | What It Covers | Status |
+|----------|---------------|--------|
+| [SppListing Model](./spp-listing-model.md) | Data model, migration, model definition, relationship to existing listings | Implemented |
+| [Endpoints](./endpoints.md) | Publish, unpublish, leads, content management API specs + enquiry linking | Implemented |
+| [Authentication](./authentication.md) | API key auth via `X-API-Key` header and `WebsiteIntegration` | Implemented |
+| [CORS](./cors.md) | `rack-cors` configuration for SPP origins | Implemented |
+| [SEO](./seo.md) | Canonical URLs, sitemaps, JSON-LD coordination between PWB and SPP | Implemented |
+| [Data Freshness](./data-freshness.md) | Cache headers (phase 1) and webhooks (phase 2, future) | Phase 1 done |
 
 ---
 
@@ -113,16 +115,29 @@ CORS is required for this cross-origin POST. See [CORS](./cors.md).
 
 ---
 
-## Key Reference Files
+## Provisioning
+
+Use the rake task to create an SPP integration for a tenant:
+
+```bash
+rails spp:provision[my-subdomain]
+```
+
+This creates a `WebsiteIntegration` (category: `spp`) with an encrypted API key and outputs the environment variables SPP needs.
+
+## Key Implementation Files
 
 | File | Relevance |
 |------|-----------|
-| `app/models/pwb/sale_listing.rb` | Listing model pattern that SppListing mirrors |
-| `app/models/concerns/listing_stateable.rb` | Shared state management |
-| `app/controllers/api_manage/v1/base_controller.rb` | API key authentication |
-| `app/controllers/api_public/v1/enquiries_controller.rb` | Enquiry endpoint |
+| `app/models/pwb/spp_listing.rb` | SppListing model with Mobility translations, monetize, curated photos |
+| `app/controllers/api_manage/v1/spp_listings_controller.rb` | Publish, unpublish, leads, and content management endpoints |
+| `app/controllers/api_manage/v1/base_controller.rb` | API key authentication (iterates encrypted credentials) |
+| `app/controllers/api_public/v1/enquiries_controller.rb` | Enquiry endpoint (links messages to properties) |
+| `app/controllers/api_public/v1/base_controller.rb` | Cache headers (`expires_in 1.hour`) |
 | `app/controllers/concerns/subdomain_tenant.rb` | Tenant resolution via `X-Website-Slug` |
-| `config/initializers/cors.rb` | CORS configuration |
-| `app/helpers/seo_helper.rb` | SEO meta tags, JSON-LD, canonical URLs |
-| `app/controllers/sitemaps_controller.rb` | Sitemap generation |
+| `app/helpers/seo_helper.rb` | `spp_live_url_for` helper, SEO meta tags, JSON-LD, canonical URLs |
+| `app/controllers/sitemaps_controller.rb` | Sitemap generation (uses SPP URLs when available) |
+| `app/views/sitemaps/index.xml.erb` | Sitemap template with SPP URL support |
+| `config/initializers/cors.rb` | CORS configuration with SPP origin patterns |
+| `lib/tasks/spp.rake` | SPP provisioning rake task |
 | `docs/architecture/per_tenant_astro_url_routing.md` | Per-tenant URL config pattern |

docs/api/spp/authentication.md

@@ -1,6 +1,6 @@
 # SPP Authentication for api_manage Endpoints
 
-**Status:** Proposed
+**Status:** Implemented
 **Related:** [SPP–PWB Integration](./README.md) | [CORS](./cors.md)
 
 ---
@@ -43,9 +43,10 @@ Request with X-API-Key header
   ▼
 api_manage BaseController#authenticate_from_api_key
   │
-  ├── Look up: current_website.integrations.find_by(api_key: key, active: true)
+  ├── Iterate: current_website.integrations.enabled.find { |i| i.credential('api_key') == key }
+  │   (API keys are stored in encrypted credentials, so each must be decrypted and compared)
   │
-  ├── If found: Return website's owner or first admin as acting user
+  ├── If found: Call integration.record_usage!, return website's owner or first admin
   │
   └── If not found: Return nil (authentication fails)
 ```
@@ -62,8 +63,20 @@ In `app/models/pwb/website_integration.rb`, add `:spp` to the categories enum if
 
 ### Provisioning the API Key
 
+Use the provisioning rake task:
+
+```bash
+rails spp:provision[my-subdomain]
+```
+
+This is idempotent — running it again for the same subdomain outputs the existing key. The task:
+1. Finds the website by subdomain
+2. Creates a `WebsiteIntegration` (category: `spp`, provider: `single_property_pages`) with an encrypted API key
+3. Outputs the API key and environment variables for SPP
+
+Alternatively, via Rails console:
+
 ```ruby
-# Via Rails console or admin interface:
 website = Pwb::Website.find_by(subdomain: 'my-tenant')
 
 integration = website.integrations.create!(
@@ -74,8 +87,7 @@ integration = website.integrations.create!(
   enabled: true
 )
 
-# Retrieve the key to configure in SPP:
-integration.credential(:api_key)
+integration.credential('api_key')
 # => "a1b2c3d4e5f6..."
 ```
 
@@ -166,34 +178,20 @@ The API key grants the permissions of the website's owner/admin. This is appropr
 
 ### Audit Trail
 
-PWB should log API key usage for auditing. The `api_manage` base controller could log:
-
-```ruby
-def authenticate_from_api_key
-  api_key = request.headers['X-API-Key']
-  return nil if api_key.blank?
-
-  integration = current_website&.integrations&.find_by(api_key: api_key, active: true)
-  if integration
-    integration.touch(:last_used_at)  # Already supported by the model
-    # ... return acting user
-  end
-end
-```
-
-The `last_used_at` field already exists on `WebsiteIntegration`.
+The `api_manage` base controller calls `integration.record_usage!` on successful API key authentication, which updates `last_used_at` on the `WebsiteIntegration` record. This is already implemented.
 
 ## Enquiry Submissions: No Auth Needed
 
 The enquiry endpoint (`POST /api_public/v1/enquiries`) is under `api_public`, which has **no authentication requirement**. This is correct — enquiries are submitted by anonymous visitors. SPP's client-side form can POST directly to PWB with just `X-Website-Slug` (no API key).
 
 ## Implementation Checklist
 
-1. Ensure the `api_manage` base controller's `authenticate_from_api_key` method works with `WebsiteIntegration` records
-2. Create an SPP integration for each tenant that uses SPP
-3. Provide the API key and website slug to SPP's deployment configuration
-4. Verify that `api_manage` endpoints return 401 without a valid key and 200 with one
-5. Confirm `last_used_at` is updated on successful authentication
+- [x] `authenticate_from_api_key` iterates encrypted `WebsiteIntegration` credentials
+- [x] `:spp` category added to `WebsiteIntegration::CATEGORIES`
+- [x] Provisioning rake task: `rails spp:provision[subdomain]`
+- [x] API key auth returns 401 without valid key, 200 with one (6 specs)
+- [x] `record_usage!` updates `last_used_at` on authentication
+- [x] Cross-website key isolation tested
 
 ## Reference Files
 

docs/api/spp/cors.md

@@ -1,6 +1,6 @@
 # SPP CORS Configuration (Option B)
 
-**Status:** Proposed
+**Status:** Implemented (Approach A — regex patterns)
 **Related:** [SPP–PWB Integration](./README.md) | [Authentication](./authentication.md)
 
 ---
@@ -21,9 +21,9 @@ All blocks use `headers: :any`, which already permits custom headers like `X-Web
 
 ## What Needs to Change
 
-### Development: Already Covered
+### Development: Covered
 
-`localhost:4322` is already in the development origins block. If SPP runs on a different port locally, add it to the same block.
+`localhost:4321`, `localhost:4322`, and `localhost:4323` are in the development origins block. Port 4323 was added for SPP local development.
 
 ### Production: Add Per-Tenant SPP Origins
 
@@ -83,7 +83,7 @@ end
 | Performance | No DB lookup | Cached DB lookup (5-min TTL) |
 | Security | Allows all matching domains | Only allows configured domains |
 
-**Recommendation:** Start with Approach A. Move to Approach B only if tenants need fully custom SPP domains.
+**Decision:** Approach A was implemented. Move to Approach B only if tenants need fully custom SPP domains.
 
 ### Scoping: Which Resources?
 
@@ -124,11 +124,12 @@ SPP uses API key authentication (not cookies), so `credentials: true` is **not n
 
 ## Implementation Checklist
 
-1. Decide on Approach A or B based on whether tenants will have custom SPP domains
-2. Update `config/initializers/cors.rb` with the chosen approach
-3. Add `max_age: 3600` to the production origins block
-4. Test preflight (`OPTIONS`) requests from an SPP origin to both `/api_public/v1/*` and `/api_manage/v1/*`
-5. Verify `X-Website-Slug` and `X-API-Key` headers pass through
+- [x] Approach A (regex patterns) implemented in `config/initializers/cors.rb`
+- [x] Added `/.*\.spp\.propertywebbuilder\.com/` origin pattern
+- [x] Added `max_age: 3600` to the production origins block
+- [x] Added `localhost:4323` for SPP local dev
+- [ ] Test preflight (`OPTIONS`) from an SPP origin (manual/E2E)
+- [ ] Verify `X-Website-Slug` and `X-API-Key` headers pass through (manual/E2E)
 
 ## Reference Files
 

docs/api/spp/data-freshness.md

@@ -1,6 +1,6 @@
 # SPP Data Freshness Strategy
 
-**Status:** Proposed
+**Status:** Phase 1 Implemented (cache headers), Phase 2 planned (webhooks)
 **Related:** [SPP–PWB Integration](./README.md) | [SppListing Model](./spp-listing-model.md)
 
 ---
@@ -35,15 +35,15 @@ These callbacks are the natural hook points for notifying SPP.
 
 ### Current API Caching
 
-`ApiPublic::V1::BaseController` sets `expires_in 5.hours, public: true` on all responses. SPP can use these cache headers if 5-hour staleness is acceptable.
+`ApiPublic::V1::BaseController` sets `expires_in 1.hour, public: true` on all responses (reduced from 5 hours as part of Phase 1).
 
 ## Strategy Evaluation
 
 ### Option 1: Cache Headers (Passive)
 
 **How:** SPP respects the `Cache-Control` and `Last-Modified` headers from PWB's API. Astro's server-side data fetching can cache responses and re-validate with conditional GET (`If-Modified-Since`).
 
-**Staleness:** Up to 5 hours (current `expires_in` value). Could be reduced to 1 hour for property detail endpoints.
+**Staleness:** Up to 1 hour (current `expires_in` value after Phase 1 reduction).
 
 **Pros:**
 - Zero implementation on PWB — already works
@@ -183,16 +183,16 @@ These callbacks are the natural hook points for notifying SPP.
 
 ## Recommended Approach: Phase 1 Now, Phase 2 Later
 
-### Phase 1: Reduce Cache TTL (Immediate)
+### Phase 1: Reduce Cache TTL (Done)
 
-Reduce the `api_public` cache TTL for property detail endpoints from 5 hours to 1 hour:
+The `api_public` base controller cache TTL was reduced from 5 hours to 1 hour:
 
 ```ruby
-# In the properties show endpoint:
+# app/controllers/api_public/v1/base_controller.rb
 expires_in 1.hour, public: true
 ```
 
-This is a one-line change. SPP will see updates within an hour with no new infrastructure.
+SPP sees updates within an hour with no new infrastructure. Covered by 3 specs in `spec/requests/api_public/v1/cache_headers_spec.rb`.
 
 ### Phase 2: Add Webhooks (When Real-Time Matters)
 
@@ -212,10 +212,11 @@ SPP can choose which events to act on. For most cases, `property.updated` as a c
 
 ## Implementation Checklist
 
-### Phase 1 (Now)
-1. Reduce cache TTL on property detail API endpoint to 1 hour
-2. Ensure `Last-Modified` headers are set correctly on property responses
-3. SPP: Use conditional GET (`If-Modified-Since`) to avoid re-downloading unchanged data
+### Phase 1 (Done)
+- [x] Reduced cache TTL on all `api_public` endpoints to 1 hour
+- [x] `Vary` header set for `Accept-Language, X-Website-Slug` for proper edge caching
+- [x] Conditional GET (`If-Modified-Since`) supported via `fresh_when` in base controller
+- [ ] SPP: Use conditional GET headers to avoid re-downloading unchanged data
 
 ### Phase 2 (Later)
 1. Add `spp_webhook_url` and `spp_webhook_secret` to `client_theme_config` schema