> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Track new features, improvements, and fixes across Alana Shopping B2B releases.

## May 2026

### Canvas FAQ Action {/* 2026-05-15 — Phase 185 */}

**New action**

* **Dedicated `faq` Canvas action** — promoted from a sub-output of `semantic` to a first-class content action. Each FAQ now carries a `category` (`uso`, `cuidado`, `tamanho`, `envio`, `trocas`, `material`, `estilo`, `outro`) and a `confidence` score in `[0, 1]`. The `/api/ai/generate` route post-filters at `confidence ≥ 0.7`; requests that produce fewer than 5 high-confidence FAQs return 400 with a clear retry suggestion.
* **Forbidden topics** baked into the prompt: color/size/availability/price questions are rejected because those answers live in structured product fields and risking hallucination there is unacceptable. The prompt steers toward caimento, cuidado/lavagem, uso/ocasião, material/composição, estilo, envio, trocas.
* **`SemanticResult.faqs` remains untouched** for backward compatibility — existing integrations keep working. New surfaces should adopt the dedicated `faq` action for higher-quality, category-aware output.

**API**

* `POST /api/ai/generate` accepts `action: "faq"`; response shape: `{ faqs: Array<{ question, answer, category, confidence }> }`.
* New `FaqResult` and `FaqCategory` types exported from `@/types/optimization`.

### Image-Edit Tier Routing Fix {/* 2026-05-14 — Phase 184 */}

**Production fix**

* **`POST /api/workspace/{workspaceId}/ai-media/image-edit` now respects the `tier` parameter.** Previously the route hardcoded `provider: "together_ai"` and always called FLUX Kontext via LiteLLM regardless of tier — `tier: "high"` was effectively non-functional.
* After Phase 184 the route resolves provider+model through `resolveProvider(action, tier)`:
  * `tier: "high"` + reshoot/backdrop → **RunwayML Gen4 Image Turbo** (submit + poll up to 120s)
  * `tier: "balanced"` → FLUX Kontext Pro via Together AI (existing behavior)
  * `tier: "economic"` → FLUX.1-schnell via Together AI
  * `relight_product` / `image_upscale` → RunPod (IC-Light v2 / Real-ESRGAN); still wires the route warning + FLUX fallback when the direct RunPod path is not configured locally
* Job records now reflect the **actual resolved provider and model** (no more cosmetic `together_ai` on every job). Downstream observability gains correctness immediately.
* `submitImageJobAndWait` helper added to `src/lib/providers/runwayml.ts` — synchronous wrapper around `submitImageJob` + `getImageJobStatus` for routes that want a single-shot response.

## April 2026

### v2.8.1 — Brand-Scoping Enforcement {/* 2026-04-23 */}

**Architecture**

* **Operational data is now scoped to teams/brands, not just workspaces.** Every catalog, canvas asset, feed, visibility snapshot, and distribution config belongs to exactly one brand within a workspace. See ADR 028 for the full design.
* **`BrandContext` and `BrandSwitcher` are now operational** across 10 pages — dashboard, intelligence, catalog, canvas, import, and the full `/visibility/*` surface. Switching the active brand in the header filters every dashboard, list, and creation flow. Admins with "all brands" selected get cross-brand aggregation views; members are pinned to their assigned brands.
* **49 DB tables gained `brand_id`**: catalogs, products, versions, releases, Canvas (presets, workflows, compositions, content packages, publish history, AI media jobs, look compositions, model images), import jobs (URL, dataset), prompt assets, visibility (snapshots, monitoring, impact, perception, narrative), distribution (serving configs, query expansions, webhooks, API keys). Row Level Security enforces the `brand_id` filter via the new `get_user_brand_ids()` helper.

**Data model**

* **Brand Style Profile (BSP) moved from workspaces to brands.** `workspaces.brand_style_profile` is dropped; `brand_ai_specs` now carries `visual_style`, `color_palette`, `default_ai_tier` per brand. Multi-brand workspaces can maintain distinct identities per brand.
* **Default brand per workspace**: every workspace auto-creates a `main` brand on signup, so all brand-scoped tables always resolve.
* **API keys gained an optional brand scope**: `brand_id = NULL` = workspace-wide admin key; `brand_id = <uuid>` = brand-scoped key (used by MCP and feed access).

**API surface**

* Operational endpoints honor an `X-Active-Brand` header when present; RLS enforces access regardless. Writes require explicit `brand_id` in the request body.
* Anonymous search (`/api/search`) requires `brand_id` as a query parameter.

**Deferred**

* Full `openapi.json` sync and milestone E2E scenarios remain open. The brand-scoping contract is enforced at the database layer regardless.

## March 2026

### v1.8.1 — Pipeline Hardening + Marketplace Hub {/* 2026-03-17 */}

**Data Pipeline**

* **Bronze idempotency**: duplicate imports from the same source are silently de-duplicated via `source_identifier` hash key — re-running an import no longer creates duplicate products
* **Unified optimization score**: `optimization_score` is now a top-level field on the product object; `score_history` tracks the full progression from 0 to 100 across pipeline runs
* **Pipeline settings API**: `GET/PUT /api/workspace/{workspaceId}/settings/pipeline` — configure Silver field mappings, Gold rubric weights, and auto-trigger behavior per workspace

**Marketplace Hub**

* **Pagination**: `GET /api/hub/catalogs` now returns cursor-based pagination (`after`, `limit` params); first page defaults to 20 catalogs
* **Preview endpoint**: `GET /api/hub/catalogs/{catalogId}/preview` — inspect catalog metadata and a sample of products before cloning or subscribing
* **Subscribe + sync**: `POST /api/hub/catalogs/{catalogId}/subscribe` creates a live subscription; `POST /api/hub/subscriptions/{subscriptionId}/sync` triggers manual refresh
* **Conflict resolution**: `GET /api/hub/subscriptions/{subscriptionId}/conflicts` lists field-level conflicts; `PATCH` resolves individual conflicts with `keep_local`, `accept_remote`, or `manual_review`
* **Publisher analytics**: `GET /api/hub/catalogs/{catalogId}/analytics` returns subscriber count, clone count, and weekly view trends (up to 90 days)
* **Versioning**: publishing a new version of a subscribed catalog triggers `catalog.version.published` webhooks to all active subscribers

**Bright Data — Production**

* Bright Data integration promoted from beta to GA; real billing API wired (usage billed per scrape credit consumed)
* URL import webhooks: `url_import.completed` and `url_import.failed` events now delivered with full product payload on success
* Dataset delivery endpoint: `POST /api/workspace/{workspaceId}/datasets/ingest` accepts Bright Data bulk dataset payloads directly

**Distribution DX**

* `llms.txt` published at `https://docs.alana.shopping/llms.txt` — machine-readable platform summary for LLM context windows
* Feed API: NDJSON streaming now supported via `Accept: application/x-ndjson` header on `GET /api/mcp/feed/{platform}`
* Unified error catalog: all API errors now include `error_code` (e.g., `CATALOG_NOT_PUBLISHED`, `RATE_LIMIT_EXCEEDED`) — see [Error Reference](/api-reference/overview#error-codes)
* MCP Tools: tool filtering via `?tools=` query param on SSE connect — subscribe to only the tool categories you need
* Platform quickstarts added for Shopify, WooCommerce, and custom storefronts
* Feed webhooks: `POST /api/v1/feeds/{platform}/webhooks` — register endpoints to receive `feed.updated` events
* Feed analytics: `GET /api/v1/feeds/{platform}/analytics` — consumption metrics (requests, cache hit rate, error rate, top consumers)
* Postman collection published: import via `https://docs.alana.shopping/postman.json`

***

### v1.8.0 — Bright Data Integration + Bronze/Silver/Gold Pipeline {/* 2026-03-10 */}

<Info>
  This release introduces the ADR-015 medallion data pipeline and production Bright Data integration for automated product data acquisition.
</Info>

**Bright Data Integration**

* Five Bright Data clients integrated: `ProductScraper`, `WebUnlocker`, `DatasetDelivery`, `ProxyManager`, `SearchScraper`
* URL import: `POST /api/workspace/{workspaceId}/url-import/jobs` — submit a product page URL; Bright Data scrapes and extracts structured data
* Web scraping with automatic CAPTCHA bypass, residential proxy rotation, and JavaScript rendering
* Async job status polling and webhook delivery on completion

**Bronze/Silver/Gold Pipeline (ADR-015)**

* **Bronze stage**: raw product ingest with idempotency key (`source_identifier`) — prevents duplicate imports from the same source in repeated runs
* **Silver stage**: field normalization (maps arbitrary column names to Alana schema), duplicate detection across catalog, image URL validation
* **Gold stage**: 7-stage optimization rubric scoring (0–100) across identity, content, media, pricing, availability, SEO, and compliance dimensions; returns score + gap list per product
* Pipeline stages run automatically after import (configurable) or on-demand via Batch Actions

**Batch Actions UI**

* New **Batch Actions** panel in catalog view: run Silver normalization or Gold scoring on a selection or entire catalog
* Real-time progress indicator with per-product status updates
* Error summary with row-level detail export (CSV)

**Pipeline Settings**

* New **Pipeline Settings** panel in workspace settings:
  * **Silver mappings**: map custom column names to standard Alana fields
  * **Gold weights**: adjust per-dimension rubric weights (identity, content, media, pricing, availability, SEO, compliance)
  * **Auto-trigger**: configure whether Silver runs automatically after Bronze, and whether Gold runs after Silver

***

### v1.7.0 — Distribution Excellence {/* 2026-03-16 */}

<Warning>
  **Breaking change**: The `?key=` query parameter for API key authentication has been removed from all Canal 2 (Search API) endpoints. Use the `x-api-key` header exclusively.
</Warning>

**Canal 2 — Search API**

* **BREAKING**: `?key=` query parameter removed from all `/api/v1/*` endpoints. API keys must be passed via the `x-api-key` request header. Keys in URLs are visible in logs, Referer headers, and browser history — this change improves security for all Search API consumers.
  * **Migration**: Replace `GET /api/v1/search?key=ak_xxx` with `GET /api/v1/search` + `x-api-key: ak_xxx` header.
  * Affected endpoints: `/api/v1/search`, `/api/v1/autocomplete`, `/api/v1/browse`, `/api/v1/recommend`, `/api/v1/recommendations/*`, `/api/v1/events`, `/api/v1/analytics/*`, `/api/v1/serving-configs/*`, `/api/v1/facets/*`, `/api/v1/synonyms/*`, `/api/v1/boost-rules/*`, `/api/v1/language`, `/api/v1/pipeline/status`, `/api/v1/bandit/state`, `/api/v1/cache/metrics`

**Canal 1 — Feed API**

* Input validation hardening on `GET /api/mcp/feed/[platform]`:
  * `?q=` parameter: control characters stripped, max 500 characters enforced (400 on violation)
  * `?catalog_id=` parameter: UUID format validated (400 on invalid format)

**Canal 1 + Canal 3 — Legacy API Key Deprecation**

* Responses authenticated with legacy API keys now include deprecation headers:
  * `X-Api-Key-Deprecated: true`
  * `X-Deprecation-Info: https://docs.alana.shopping/en/authentication#m2m-migration`
  * `Deprecation: true` (RFC 8594)
* Migrate to Auth0 M2M tokens: [see migration guide](https://docs.alana.shopping/en/authentication#m2m-migration)

**Rate Limiting + Observability**

* All API responses include `X-Request-Id` for distributed tracing
* `X-Request-Id` echoed from upstream when client sends it; generated (UUID v4) otherwise
* Canal 1: 60 req/min per API key; 429 includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`
* Canal 3: 200 req/min per key + 50 req/min per key+IP; dual-level enforcement

***

## February 2026

### v1.0.0 — General Availability {/* 2026-02-15 */}

<Info>
  Alana Shopping B2B v1.0 is live. This is the first production release of the platform.
</Info>

**Platform**

* Workspace management with full RBAC (owner, admin, editor, viewer)
* Row-level security across all resources
* Onboarding wizard with sample data loading
* Custom domain support and workspace branding
* GDPR-compliant data export and account deletion
* Comprehensive audit logging (38+ action types)

**Catalog Engine**

* Create, publish, fork, and merge catalogs
* Product CRUD with optimization scoring (0–100)
* Feed readiness validation for Google Shopping and Meta Commerce
* Bulk import from CSV and Excel files
* Public product feed endpoint for published catalogs

**AI Services**

* Brand-aware content generation via LiteLLM abstraction
* Canvas AI chat with RAG (brand specs + product context)
* Text generation for descriptions, titles, and bullet points
* Content enhancement with grammar, tone, and keyword alignment
* Per-brand AI specifications: tone, keywords, policies, audience

**Billing & Subscriptions**

* Four plans: Standard, Pro, Business, Enterprise
* Stripe-powered checkout, subscriptions, and customer portal
* Usage tracking with configurable alerts
* Invoice history and PDF download

**Integrations**

* OAuth-based platform connections
* Bidirectional product sync with e-commerce platforms
* MCP protocol support (inbound batches, feed subscriptions, search)
* Intercom customer support integration

**Developer Experience**

* REST API with 90+ endpoints and interactive playground
* API key management with granular permissions
* Cursor-based pagination across all list endpoints
* Structured error responses with error codes
* Health and readiness endpoints for monitoring

**Security**

* Supabase Auth with email/password, magic links, and OAuth
* Configurable session timeouts and 2FA enforcement
* IP allowlisting for API access
* Stripe webhook signature verification
* Workspace-level force logout