riverbankcms 0.20.0 → 0.22.0

package/dist/cli/init-docs/content/getting-started.md

@@ -166,3 +166,46 @@ If local content includes unrelated differences, see `workflows/agent-safe-sync.
 1. Read `cli-reference.md` for detailed command documentation
 2. Review `schema.md` to understand this site's content model
 3. Check `workflows/` for step-by-step guides
+
+
+## Customer portal routes
+
+When portal auth is enabled, `riverbankcms init` generates these reserved routes:
+
+| Route | SDK helper | Scaffold template |
+| --- | --- | --- |
+| `/portal` | `createPortalPage` from `@riverbankcms/sdk/next` | `portalPageTemplates` |
+| `/portal/tickets/[registrationId]` | `createPortalTicketPage` | `portalPageTemplates` |
+| `/portal/digital-products/[entitlementId]` | `createPortalDigitalProductPage` | `portalPageTemplates` |
+| `/portal/digital-products/[entitlementId]/files/[assetId]` | `createPortalDigitalProductFilePage` | `portalPageTemplates` |
+| `/redeem` | `createRedeemPage` | `portalPageTemplates` |
+| `/api/portal/callback` (GET + POST) | `handlePortalCallback` from `@riverbankcms/sdk/portal` | `portalCallbackRouteTemplate` |
+| `/api/portal/logout` (POST) | `handlePortalLogout` | `portalLogoutRouteTemplate` |
+
+Existing sites should add these files after upgrading the SDK. Import
+`@riverbankcms/sdk/styles.css` globally. The page helpers provide the site theme
+scope automatically; sites with `themeSource: 'local'` pass the same `theme`,
+`themes`/`themeSwitch`, or `getTheme` options used by their catch-all. A custom
+resolver receives `content.type === 'portal'` and `content.site` on these routes. The callback and logout routes own the HTTP-only cookie.
+The file route authenticates before redirecting to a signed download URL.
+
+For a custom host, `CustomerPortal` from `@riverbankcms/sdk/portal/client` takes
+`siteId`, `apiBaseUrl`, `portalToken` (nullable), `demoEmailSuppressed`, plus optional `callbackPath`, `logoutPath` and `bookPath`
+(defaults `/api/portal/callback`, `/api/portal/logout`, `/book`). Wrap it in the
+site's `ThemeScope`. This is a reserved route component, not a CMS block.
+`@riverbankcms/sdk/portal` remains the server helper entry.
+
+
+Gift delivery needs `/redeem`, the portal routes and the callback POST handler
+in place before the site sends gifts. Upgrade the SDK and add the scaffolded
+routes together. The redeem helper accepts the same theme options as the portal.
+Add `Referrer-Policy: no-referrer` to `/redeem` in your Next config (the scaffold
+includes it); this protects emailed gift tokens in outbound referrers.
+
+For a custom host, `RedeemGiftCard` from `@riverbankcms/sdk/gifting/client` takes
+`siteId`, `apiBaseUrl`, `siteTitle`, `publicContactEmail` (nullable), optional
+`token` and `code`, and optional `callbackPath`, `portalPath`, `homePath` (defaults
+`/api/portal/callback`, `/portal`, `/`). Its `onSignedIn` callback refreshes host
+chrome after sign-in; the Next helper supplies that callback. Wrap the shared
+component in the site's `ThemeScope`. The callback POST expects JSON
+`{ portalCode }` from the same origin and returns JSON without redirecting.