@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-vibe-headless/references/members/INSTRUCTIONS.md

@@ -0,0 +1,211 @@
+
+# Wix Members — custom login (client-only REST)
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this
+> vertical's `references/members/wix-members-auth.js`. Copy **both** into your app's `src/rest/` side by
+> side — the helper does `import { … } from "./wix-client.js"`, so they must land in the same folder.
+
+Adds real **member accounts** to a client-only headless front end: sign up, log in, log out, and
+member-gated surfaces — all from the browser over the public `WIX_CLIENT_ID`, no SDK, no backend.
+
+**This is *custom* login: the front owns its login UI.** The member types credentials in **your own
+form on your own page** (or clicks your own social button) — they are **never redirected to a
+Wix-hosted login page**. This is the REST equivalent of the SDK `OAuthStrategy` recipe; the older
+"redirect the user to a Wix login page" flow is deliberately **not** used here.
+
+## When to use
+- User wants members to **sign up / log in** on a page they built (email+password, "Continue with
+  Google/Facebook", or custom SSO), with the login UI living in their own app.
+- User wants **member-gated** content, an **account / profile** page, or a "my orders / my bookings /
+  my plans" view (those reads need a logged-in member).
+- **Pricing-plans is present.** Buying/reading a member's plans is members-only — pair this vertical
+  with `pricing-plans` so the member can log in *before* the subscribe / "my subscription" surface.
+
+## Two mechanisms — pick by the brief (a page may use both)
+
+| | **(A) Direct-credential** | **(B) Social / SSO** |
+| :-- | :-- | :-- |
+| **Use when** | your own email+password form, or custom sign-up fields | "Sign in with Google / Facebook", or enterprise SSO |
+| **User leaves your page?** | **No** — silent iframe token exchange | **Yes** — full-page redirect to the provider, back to your `/callback` |
+| **Kick-off** | `register()` / `login()` | `startSocialLogin(idp, callbackUri)` |
+| **Finish** | automatic on `SUCCESS` | `completeSocialLogin()` on the `/callback` page |
+| **Custom sign-up fields?** | Yes (`register`'s `profile`) | No — the provider owns the identity |
+| **Needs an allow-listed origin/URI?** | **Yes** — your app **origin** (postMessage target) | **Yes** — your `/callback` **URL** |
+
+Both converge on the **same end state**: member tokens written onto the shared client, so **every
+later `wixApiRequest` runs as the member** (login just swaps the token set on the client you already
+have). Don't blend their exchange calls — the helper handles each internally.
+
+## Prerequisites
+1. A Wix site with the **Members Area app installed** if you need member *profile* data (name, photo,
+   roles) or custom field definitions. Pure "logged-in vs. not" gating needs no app — see the
+   identity-vs-profile split below.
+2. The site's public headless **`WIX_CLIENT_ID`** (from the handoff prompt), pasted into
+   `src/rest/wix-client.js`. Public, buyer-facing credential — safe to hardcode/commit.
+3. **OAuth-app allow-listing — the #1 gotcha. Two *different* fields gate the two mechanisms:**
+
+   | Mechanism | What must be allow-listed | OAuth-app field | On `localhost:4321`? |
+   | :-- | :-- | :-- | :-- |
+   | **(A) direct-credential** | your app **origin** (the hidden iframe `postMessage`s the code back to it) | `allowedRedirectDomains` | ✅ allowed by default |
+   | **(B) social / SSO** | the **exact `/callback` URL** (full-page redirect target) | `allowedRedirectUris` | ❌ **must be added** |
+
+   - `localhost:4321` is Wix's default-allowed dev **origin**, so **credential login works there with zero
+     setup**. But social **still fails on `localhost:4321`** until you add `http://localhost:4321/callback`
+     to `allowedRedirectUris` — the default covers the origin, not the callback URI. (These are genuinely
+     two separate fields; matching Oz's SDK `wix-headless` `managed/DEPLOYMENT.md`.)
+   - **Any non-default origin** — your deployed domain, a different localhost port —
+     must be registered too: the origin (for A) and the `<origin>/callback` (for B).
+   - **Symptoms:** (A) unregistered origin → login hangs, then `MemberAuthError('timeout')` + a console
+     *"Failed to execute 'postMessage'… target origin … does not match"*. (B) unregistered callback →
+     the Wix authorize page shows *"Invalid redirect URI. Please add an allowed URI to your OAuth App"*
+     **before** returning — so the client can't catch it; you must register it up front.
+   - Google & Facebook are enabled by default; **custom SSO** also needs an IDP connection created in
+     the Business Manager, whose **connection id** you pass as `idp` (see "Custom SSO" below).
+
+   > **⚠️ AGENT: this is a manual, owner-only step you cannot do from client-only code — surface it
+   > proactively.** As soon as a run uses social/SSO (or deploys credential login to a non-`4321`
+   > origin), **tell the user** the exact URIs to add and where, and note that **social login stays
+   > dead until they do it** (a client-only front has no account token to register it via the API).
+   > See "Point the user to their dashboard" below for the deep link and the exact values.
+
+## The API (copy as-is; do not re-derive it)
+Copy `wix-client.js` + `wix-members-auth.js` into `src/rest/` and set `WIX_CLIENT_ID`. Exports of
+`wix-members-auth.js`:
+- **Direct-credential:** `register(email, password, profile?)`, `login(email, password)`,
+  `verifyEmail(code, stateToken)`, `sendPasswordResetEmail(email, redirectUri)`
+- **Social / SSO:** `startSocialLogin(idp, callbackUri, returnTo?)`, `completeSocialLogin()`, `IDP`
+- **Session:** `isLoggedIn()`, `getCurrentMember()`, `logout(returnTo?)`
+- **Errors:** `MemberAuthError` (`.code` + `.message`)
+
+The full state-machine, `profile`, and error semantics are documented as JSDoc at the top of
+`wix-members-auth.js`. **Read it before wiring the UI.**
+
+> **⚠️ Copy `wix-members-auth.js` verbatim — do NOT rewrite its internals.** Wire the UI to the
+> exported functions, but leave the helper's bodies alone. The OAuth request shapes are **exact and
+> unforgiving** — the `createRedirectSession` body in particular needs the `auth.authRequest` wrapper,
+> flat PKCE fields, and `responseType`/`scope`; "simplifying" it into a spread of the input object
+> returns **400 Bad Request** and login dies. Extend by *calling* the exports, not by editing them.
+
+## How to wire it (UI is the project's choice — the skill ships the REST layer only)
+
+### (A) Credential form + the state machine — handle every branch (not just SUCCESS)
+`register()` / `login()` / `verifyEmail()` resolve to `{ state, member?, stateToken? }`:
+- **`"SUCCESS"`** → logged in; `member` is populated (or `null` if the Members Area app isn't
+  installed). Render the account UI / navigate.
+- **`"REQUIRE_EMAIL_VERIFICATION"`** → a 6-digit code was emailed. Collect it and call
+  `verifyEmail(code, stateToken)`. (Fires when a new registrant's email already exists as a contact,
+  or when email verification is enabled in Member Settings.)
+- **`"REQUIRE_OWNER_APPROVAL"`** → show a "pending approval" notice; not an error.
+
+Hard failures **throw** a `MemberAuthError` — catch it and show `err.message` (`.code` is stable:
+`invalidCredentials`, `emailAlreadyExists`, …). `emailAlreadyExists` on register → route to log in.
+
+```js
+import { login, register, verifyEmail, isLoggedIn, getCurrentMember, logout, MemberAuthError } from "./rest/wix-members-auth.js";
+try {
+  const res = await login(email, password);
+  if (res.state === "SUCCESS") showAccount(res.member);
+  else if (res.state === "REQUIRE_EMAIL_VERIFICATION") promptForCode(res.stateToken);
+  else if (res.state === "REQUIRE_OWNER_APPROVAL") showPending();
+} catch (e) {
+  if (e instanceof MemberAuthError) showError(e.message); else throw e;
+}
+```
+
+Custom sign-up fields go in `register`'s `profile` (`{ firstName, lastName, nickname, addresses, … }`).
+Standard fields work as-is; arbitrary `customFields` keys must first be defined in the Members Area
+app or they're silently dropped.
+
+### (B) Social / SSO — your button + a `/callback` route
+```js
+// on your login page:
+import { startSocialLogin, IDP } from "./rest/wix-members-auth.js";
+const callbackUri = new URL("/callback", window.location.origin).href; // must be allow-listed
+onGoogleClick   = () => startSocialLogin(IDP.GOOGLE,   callbackUri, window.location.pathname);
+onFacebookClick = () => startSocialLogin(IDP.FACEBOOK, callbackUri, window.location.pathname);
+
+// on the /callback page (a route/page at exactly that path):
+import { completeSocialLogin } from "./rest/wix-members-auth.js";
+const { member, returnTo } = await completeSocialLogin();
+window.location.replace(returnTo || "/");
+```
+**Custom SSO:** identical call — pass your connection id as `idp` instead of `IDP.GOOGLE`:
+`startSocialLogin("<connectionId>", callbackUri)`. The connection id comes from an IDP connection you
+create in the Business Manager (dashboard link below).
+
+### Session, account area, logout
+- **Gate UI** on `isLoggedIn()`. Read the member with `await getCurrentMember()` (name / photo / roles
+  / custom fields) — returns `null` for a visitor or when the Members Area app isn't installed.
+- **Logout:** `await logout()` — clears local tokens and redirects through the Wix logout URL; the
+  client is a clean anonymous visitor afterward.
+- **Persistence is automatic.** Member tokens live in the same `localStorage` the visitor token used,
+  so a reload stays logged in and tokens auto-refresh via `wix-client.js` — do **not** add your own.
+
+## Identity vs. profile — don't conflate them
+- **Identity / auth** — sign up, log in, log out, "is this caller a member?". Native to the headless
+  OAuth app. **No app install needed** — every login mechanism here runs on this layer alone.
+- **Member profile / Members Area** — name / photo / roles, an account page, and custom-field
+  definitions. Served by the **Members Area app**, which must be installed. If `getCurrentMember()`
+  returns `null` while `isLoggedIn()` is `true`, suspect the app isn't installed — not a code bug.
+
+## Hard rules (do not violate)
+- ✅ **Custom login only.** The member logs in on **your** UI; never redirect them to a Wix-hosted
+  login page, and never use a Wix login-page redirect for member auth.
+- ✅ **One shared client.** Member login swaps the token set on `wix-client.js` — reuse the same
+  transport for everything so the member identity (and their cart) carries across the app. Never mint
+  a second client or re-mint anonymously after login (it drops the member).
+- ✅ **For a Wix-backed feature, use the Wix member as the identity — keep it consistent.** When the
+  feature is about **Wix members** (the user gave you a `WIX_CLIENT_ID`), log in and gate on the
+  **Wix member** (`getCurrentMember()` / the Wix member token), and key member-owned Wix rows on
+  `_owner` (see the `cms` vertical). Don't identify one feature's user from two different sessions —
+  the ids won't match.
+- ❌ **Don't blend the two exchanges.** Credential login finishes via the hidden iframe; social
+  finishes via `/callback`. The helper keeps them separate — don't cross-wire.
+- ❌ **Never fake a member.** No mock "logged-in" state, no invented profile, roles, or member counts.
+  Render the real member or the logged-out state.
+- ✅ **Fail loudly.** The helper throws `MemberAuthError` on bad credentials, state mismatch, timeout,
+  and token-exchange failure — surface them; don't swallow.
+- ⛔ **No `elevate` / admin scope.** A member reading their **own** data (profile, own orders /
+  bookings / plans) is authorized by the member token alone. There is no admin elevation on a
+  client-only front, and own-data reads don't need it.
+- ⛔ **MFA / TOTP is not available headless.** The security layers are password + email verification +
+  reCAPTCHA, all **dashboard-governed** — document them as host-configurable, don't set them from code.
+
+## Beyond the snippets
+The helper covers sign-up / login / social / SSO / logout / current-member. For a genuine gap, extend
+with `wixApiRequest` — but confirm the endpoint, method, and body in the API reference first (or via
+the co-installed **`wix-docs`** skill). Never guess.
+- Custom login (JS SDK, concepts mirror the REST calls): https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/members/custom-login-page/custom-login/custom-login-using-the-js-sdk.md
+- External / social login (REST): https://dev.wix.com/docs/rest/business-management/headless-authentication/redirects/create-redirect-session
+- Retrieve Tokens (REST): https://dev.wix.com/docs/rest/business-management/headless-authentication/authentication/retrieve-tokens
+- Members API (read/update profile, query members): https://dev.wix.com/docs/api-reference/members/members/members-v1/introduction
+
+## Point the user to their dashboard
+Some setup only happens in the Wix dashboard — always give the user the deep links:
+- **Members Area app** (for profile data + custom fields) — `https://manage.wix.com/dashboard/{metaSiteId}/member-permissions`
+- **Signup security** (email verification, owner approval, reCAPTCHA) — `Dashboard → Settings → Login & Security` / member signup settings
+- **Allowed authorization redirect URIs** — the OAuth-app / **Headless Settings** for the project:
+  `https://manage.wix.com/dashboard/{metaSiteId}/oauth-apps-settings`. Add:
+  - the **app origin** (e.g. `https://myapp.example.com`) — needed for direct-credential login from a
+    non-default origin (`localhost:4321` is pre-allowed);
+  - the **exact `/callback` URL** (e.g. `https://myapp.example.com/callback`) — required for social/SSO;
+  - also add password-reset / logout return URLs if you use them.
+  Tell the user these exact values; the callback URL must match your `startSocialLogin` `callbackUri`
+  character-for-character.
+- **Custom SSO connection** (to obtain a `connectionId`) — created under the project's IAM / SSO
+  settings in the Business Manager.
+
+Substitute the site's `metaSiteId` (from the handoff / `ListWixSites`).
+
+## Verification checklist (before declaring done)
+- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+- [ ] Sign-up: `register()` returns `SUCCESS` (or `REQUIRE_EMAIL_VERIFICATION` handled via `verifyEmail`)
+- [ ] Log-in: `login()` reaches `SUCCESS`; wrong password shows `invalidCredentials`, not a crash
+- [ ] After login `isLoggedIn()` is `true` and `getCurrentMember()` returns the member (or `null` with
+      the Members Area app not installed — documented, not a bug)
+- [ ] A member-scoped read (e.g. pricing-plans "my plans") now returns the member's data via the same client
+- [ ] Social: the button redirects to the provider and `/callback` logs the member in (callback URL
+      allow-listed); custom SSO works with its `connectionId` (or is flagged as pending host setup)
+- [ ] Logout clears the session and the next load is a clean anonymous visitor
+- [ ] No mocked member state, profile, or roles anywhere
+- [ ] Told the user about any required dashboard setup (Members Area app, allowed redirect URIs) with deep links

package/skills/wix-vibe-headless/references/members/wix-members-auth.js

@@ -0,0 +1,387 @@
+import {
+  wixApiRequest,
+  WIX_API_BASE,
+  WIX_CLIENT_ID,
+  setSessionTokens,
+  clearSession,
+  isMember,
+} from "./wix-client.js";
+
+/**
+ * Custom member login for a client-only headless front end — the REST analog of
+ * the SDK `OAuthStrategy` (`register`/`login`/`getMemberTokensForDirectLogin`/
+ * `getAuthUrl`/`getMemberTokens`/`logout`). **The front owns its login UI**; the
+ * member never bounces to a Wix-hosted login page.
+ *
+ * Two mechanisms — pick by the brief (a page can use both):
+ *   (A) DIRECT-CREDENTIAL — your own email+password form. `register()` / `login()`
+ *       → on SUCCESS an INVISIBLE iframe (`web_message`) mints member tokens. No
+ *       navigation. Supports custom sign-up fields via `profile`.
+ *   (B) SOCIAL / SSO — your own "Continue with Google/Facebook" (or custom SSO)
+ *       button. Full-page redirect to the provider → back to YOUR `/callback` →
+ *       token exchange. `idp` is always a connection id (see `IDP`).
+ *
+ * All paths converge on ONE end state: member tokens written onto the shared
+ * client via `setSessionTokens` (wix-client.js). Member tokens are the SAME shape
+ * as visitor tokens, so EVERY later `wixApiRequest` (cart, orders, "my …" reads)
+ * now runs as the member — login just swaps the token set on the client you have.
+ *
+ * State machine — `register()`/`login()`/`verifyEmail()` return `{ state, ... }`:
+ *   - "SUCCESS"                    → logged in; `{ state, member }`.
+ *   - "REQUIRE_EMAIL_VERIFICATION" → a 6-digit code was emailed; `{ state, stateToken }`.
+ *                                    Collect the code, call `verifyEmail(code, stateToken)`.
+ *   - "REQUIRE_OWNER_APPROVAL"     → membership pending owner approval; `{ state }`.
+ * Hard failures throw a `MemberAuthError` with a `.code` (invalidCredentials,
+ * emailAlreadyExists, …) — surface `.message` in your form.
+ *
+ * `profile` (register, all optional): firstName, lastName, nickname, picture,
+ * language, privacyStatus ("PUBLIC"|"PRIVATE"), labels[], phonesV2[], addresses[],
+ * company, position, birthdate, and `customFields` (name→value map). Standard
+ * fields work as-is; arbitrary `customFields` keys must first be DEFINED in the
+ * Members Area app or they're silently dropped. Social (B) can't collect any of
+ * these — that's the reason to pick direct-credential.
+ *
+ * Docs (curl the .md): custom login <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/members/custom-login-page/custom-login/custom-login-using-the-js-sdk.md>
+ * · external/social login <https://dev.wix.com/docs/rest/business-management/headless-authentication/redirects/create-redirect-session>
+ * · Retrieve Tokens <https://dev.wix.com/docs/rest/business-management/headless-authentication/authentication/retrieve-tokens>
+ */
+
+const AUTH_BASE = "/_api/iam/authentication/v2";
+const VERIFY_URL = "/_api/iam/verification/v1/auth/verify";
+const RECOVERY_URL = "/_api/iam/recovery/v1/send-email";
+const REDIRECT_SESSION_URL = "/_api/redirects-api/v1/redirect-session";
+const CURRENT_MEMBER_URL = "/members/v1/members/my";
+const OAUTH_STASH_KEY = `wix-oauth-data-${WIX_CLIENT_ID}`;
+
+/**
+ * `idp` connection ids for social login. Google & Facebook are enabled by default
+ * on every headless client. For custom SSO / OIDC (Okta, Auth0, …) pass the
+ * connection id of a connection you created in the Business Manager instead.
+ */
+export const IDP = {
+  GOOGLE: "0e6a50f5-b523-4e29-990d-f37fa2ffdd69",
+  FACEBOOK: "3ecad13f-52c3-483d-911f-31dbcf2a6d23",
+};
+
+/** Auth outcome you can show the user. `.code` is stable; `.message` is human text. */
+export class MemberAuthError extends Error {
+  constructor(code, message) {
+    super(message || code);
+    this.name = "MemberAuthError";
+    this.code = code;
+  }
+}
+
+// ─────────────────────────── (A) direct-credential ───────────────────────────
+
+/**
+ * Sign up a new member with email + password (+ optional custom `profile`).
+ * On SUCCESS the member is logged in (member tokens written to the shared client).
+ *
+ * @param {string} email
+ * @param {string} password
+ * @param {object} [profile] see the `profile` note in the file header
+ * @returns {Promise<{ state: string, member?: object|null, stateToken?: string }>}
+ */
+export async function register(email, password, profile) {
+  return runCredentialFlow(`${AUTH_BASE}/register`, {
+    loginId: { email },
+    password,
+    ...(profile ? { profile } : {}),
+  });
+}
+
+/**
+ * Log an existing member in with email + password.
+ * @param {string} email
+ * @param {string} password
+ * @returns {Promise<{ state: string, member?: object|null, stateToken?: string }>}
+ */
+export async function login(email, password) {
+  return runCredentialFlow(`${AUTH_BASE}/login`, { loginId: { email }, password });
+}
+
+/**
+ * Continue a "REQUIRE_EMAIL_VERIFICATION" flow with the 6-digit code from the email.
+ * @param {string} code verification code the member received by email
+ * @param {string} stateToken the `stateToken` returned alongside REQUIRE_EMAIL_VERIFICATION
+ * @returns {Promise<{ state: string, member?: object|null, stateToken?: string }>}
+ */
+export async function verifyEmail(code, stateToken) {
+  let res;
+  try {
+    res = await wixApiRequest(VERIFY_URL, { body: { code, stateToken } });
+  } catch (e) {
+    throw mapAuthError(e);
+  }
+  return resolveState(res);
+}
+
+/**
+ * Email the member a password-reset link. Wix hosts the reset page and returns
+ * them to `redirectUri`, which MUST be an allow-listed authorization redirect URI
+ * on the OAuth app (see INSTRUCTIONS.md → dashboard links).
+ * @param {string} email
+ * @param {string} redirectUri full URL to return to after reset
+ */
+export async function sendPasswordResetEmail(email, redirectUri) {
+  await wixApiRequest(RECOVERY_URL, {
+    body: { email, redirect: { url: redirectUri, clientId: WIX_CLIENT_ID } },
+  });
+}
+
+async function runCredentialFlow(path, body) {
+  let res;
+  try {
+    res = await wixApiRequest(path, { body });
+  } catch (e) {
+    throw mapAuthError(e);
+  }
+  return resolveState(res);
+}
+
+// On SUCCESS, finish login and return the member; otherwise hand the state (and
+// stateToken, if any) back to the UI so it can prompt for verification etc.
+async function resolveState(res) {
+  if (res.state === "SUCCESS") {
+    const member = await completeDirectLogin(res.sessionToken);
+    return { state: res.state, member };
+  }
+  return { state: res.state, stateToken: res.stateToken };
+}
+
+// The `getMemberTokensForDirectLogin` analog: turn a session token into member
+// tokens via an INVISIBLE iframe (responseMode: web_message, prompt: none). The
+// member never sees a page — this is the silent plumbing behind your own form.
+async function completeDirectLogin(sessionToken) {
+  const pkce = await generatePkce();
+  const { fullUrl } = await createRedirectSession({
+    authRequest: { responseMode: "web_message", sessionToken, pkce },
+  });
+  const { code } = await authorizeViaHiddenIframe(fullUrl, pkce.state);
+  const tokens = await exchangeCode(code, pkce.codeVerifier);
+  setSessionTokens(tokens);
+  return getCurrentMember();
+}
+
+// ─────────────────────────── (B) social / SSO ───────────────────────────
+
+/**
+ * Start a social / SSO login. Redirects the whole page to the provider; returns
+ * through YOUR `callbackUri`, where you must call `completeSocialLogin()`.
+ *
+ * @param {string} idp `IDP.GOOGLE` / `IDP.FACEBOOK`, or a custom SSO connection id
+ * @param {string} callbackUri your `/callback` URL — MUST be an allow-listed
+ *   authorization redirect URI on the OAuth app (see INSTRUCTIONS.md)
+ * @param {string} [returnTo="/"] where to send the member after login completes
+ */
+export async function startSocialLogin(idp, callbackUri, returnTo = "/") {
+  const pkce = await generatePkce();
+  const { fullUrl } = await createRedirectSession({
+    authRequest: { responseMode: "fragment", idp, redirectUri: callbackUri, pkce },
+  });
+  // The callback runs on a separate page load — carry what the exchange needs.
+  window.localStorage.setItem(
+    OAUTH_STASH_KEY,
+    JSON.stringify({ codeVerifier: pkce.codeVerifier, state: pkce.state, redirectUri: callbackUri, returnTo }),
+  );
+  window.location.href = fullUrl;
+}
+
+/**
+ * Finish a social / SSO login on the `/callback` page: reads `#code`/`#state`
+ * from the URL, verifies state, exchanges the code, logs the member in.
+ * @returns {Promise<{ member: object|null, returnTo: string }>}
+ */
+export async function completeSocialLogin() {
+  const raw = window.localStorage.getItem(OAUTH_STASH_KEY);
+  if (!raw) throw new MemberAuthError("missingOAuthData", "No pending login found — start the login again.");
+  window.localStorage.removeItem(OAUTH_STASH_KEY);
+  const stash = JSON.parse(raw);
+
+  const params = new URLSearchParams(window.location.hash.replace(/^#/, ""));
+  const error = params.get("error");
+  if (error) throw new MemberAuthError(error, params.get("error_description") || error);
+  const code = params.get("code");
+  const state = params.get("state");
+  if (!code || !state) throw new MemberAuthError("missingCode", "No authorization code returned.");
+  if (state !== stash.state) throw new MemberAuthError("stateMismatch", "OAuth state mismatch — possible CSRF; login aborted.");
+
+  const tokens = await exchangeCode(code, stash.codeVerifier, stash.redirectUri);
+  setSessionTokens(tokens);
+  return { member: await getCurrentMember(), returnTo: stash.returnTo || "/" };
+}
+
+// ─────────────────────────── session ───────────────────────────
+
+/** True once a member is logged in on this client. Gate account UI on it. */
+export function isLoggedIn() {
+  return isMember();
+}
+
+/**
+ * Read the logged-in member (name / photo / roles / custom fields). Needs the
+ * **Members Area app** installed; returns `null` for an anonymous visitor or when
+ * the app isn't installed (that's setup, not a code bug — see INSTRUCTIONS.md).
+ * @returns {Promise<object|null>}
+ */
+export async function getCurrentMember() {
+  try {
+    const res = await wixApiRequest(CURRENT_MEMBER_URL, { method: "GET", query: { fieldSet: "FULL" } });
+    return res?.member || null;
+  } catch (e) {
+    if (e.status === 401 || e.status === 403 || e.status === 404) return null;
+    throw e;
+  }
+}
+
+/**
+ * Log the member out: clears the local session immediately, then redirects
+ * through the Wix logout URL so the server session is dropped too. After this the
+ * client is a clean anonymous visitor again.
+ * @param {string} [returnTo] where to land after logout (defaults to the origin)
+ */
+export async function logout(returnTo) {
+  const postFlowUrl = returnTo || (typeof window !== "undefined" ? window.location.origin : "/");
+  let logoutUrl;
+  try {
+    const { redirectSession } = await wixApiRequest(REDIRECT_SESSION_URL, {
+      body: { logout: { clientId: WIX_CLIENT_ID }, callbacks: { postFlowUrl } },
+    });
+    logoutUrl = redirectSession?.fullUrl;
+  } finally {
+    clearSession(); // drop local tokens even if building the logout URL failed
+  }
+  if (logoutUrl && typeof window !== "undefined") window.location.href = logoutUrl;
+}
+
+// ─────────────────────────── internals ───────────────────────────
+
+async function createRedirectSession({ authRequest }) {
+  const { responseMode, sessionToken, idp, redirectUri, pkce } = authRequest;
+  // ⚠️ EXACT Wix wire shape — do NOT simplify or inline this. It is NOT the input
+  // object: the request needs the `auth.authRequest` wrapper, the PKCE fields FLAT
+  // (`codeChallenge` + `codeChallengeMethod`, not a nested `pkce` object; the
+  // `codeVerifier` is NOT sent here — it's kept for the token exchange), and
+  // `responseType`/`scope` present. Spreading the input straight onto the body →
+  // 400 Bad Request.
+  const { redirectSession } = await wixApiRequest(REDIRECT_SESSION_URL, {
+    body: {
+      auth: {
+        authRequest: {
+          clientId: WIX_CLIENT_ID,
+          codeChallenge: pkce.codeChallenge,
+          codeChallengeMethod: "S256",
+          responseMode,
+          responseType: "code",
+          scope: "offline_access",
+          state: pkce.state,
+          ...(redirectUri ? { redirectUri } : {}),
+          ...(sessionToken ? { sessionToken } : {}),
+          ...(idp ? { idp } : {}),
+        },
+      },
+    },
+  });
+  if (!redirectSession?.fullUrl) throw new MemberAuthError("noRedirectSession", "Wix did not return an authorization URL.");
+  return { fullUrl: redirectSession.fullUrl };
+}
+
+// Open the authorize URL in a hidden iframe and wait for the web_message postMessage
+// carrying { code, state }. Matches @wix/sdk iframeUtils.addPostMessageListener.
+function authorizeViaHiddenIframe(authUrl, expectedState) {
+  return new Promise((resolve, reject) => {
+    const iframe = document.createElement("iframe");
+    iframe.style.display = "none";
+    let settled = false;
+    const cleanup = () => {
+      window.removeEventListener("message", onMessage);
+      clearTimeout(timer);
+      if (iframe.parentNode) iframe.parentNode.removeChild(iframe);
+    };
+    const onMessage = (e) => {
+      if (!e.data || e.data.state !== expectedState) return; // not our message
+      settled = true;
+      cleanup();
+      if (e.data.error) reject(new MemberAuthError(e.data.error, e.data.error_description || e.data.error));
+      else resolve({ code: e.data.code, state: e.data.state });
+    };
+    window.addEventListener("message", onMessage);
+    const timer = setTimeout(() => {
+      if (!settled) {
+        cleanup();
+        // The overwhelmingly common cause: this app's ORIGIN is not an allowed
+        // authorization redirect URI on the OAuth app, so the browser silently
+        // blocks the iframe's postMessage (check the console for a "target origin
+        // … does not match" error). Register the origin — see INSTRUCTIONS.md.
+        reject(new MemberAuthError(
+          "timeout",
+          `Login timed out. Most likely this app's origin (${typeof window !== "undefined" ? window.location.origin : "?"}) ` +
+            `is not an allowed authorization redirect URI on the Wix OAuth app — register it in the site's Headless Settings.`,
+        ));
+      }
+    }, 120000);
+    iframe.src = authUrl;
+    document.body.appendChild(iframe);
+  });
+}
+
+// Exchange an authorization code for member tokens. No Authorization header — this
+// is the token-minting endpoint (mirrors the SDK's fetchTokens). `redirectUri` is
+// sent only for social (it must match the redirect-session's redirectUri).
+async function exchangeCode(code, codeVerifier, redirectUri) {
+  if (!code) throw new MemberAuthError("missingCode", "No authorization code to exchange.");
+  const res = await fetch(`${WIX_API_BASE}/oauth2/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      clientId: WIX_CLIENT_ID,
+      grantType: "authorization_code",
+      code,
+      codeVerifier,
+      ...(redirectUri ? { redirectUri } : {}),
+    }),
+  });
+  if (!res.ok) {
+    let body;
+    try { body = await res.json(); } catch { /* ignore */ }
+    throw new MemberAuthError(body?.error || "tokenExchangeFailed", `Token exchange failed: ${res.status}${body ? ` ${JSON.stringify(body)}` : ""}`);
+  }
+  const data = await res.json();
+  return { accessToken: data.access_token, refreshToken: data.refresh_token, expiresIn: data.expires_in };
+}
+
+function mapAuthError(e) {
+  const code = e?.body?.details?.applicationError?.code;
+  // Email already exists (register) — route them to log in.
+  if (code === "-19995" || e?.status === 409) {
+    return new MemberAuthError("emailAlreadyExists", "An account with this email already exists — try logging in instead.");
+  }
+  // Bad credentials: -19999 identity-not-found (404), -19976 wrong-password (401).
+  if (code === "-19999" || code === "-19976" || e?.status === 404 || e?.status === 401) {
+    return new MemberAuthError("invalidCredentials", "Incorrect email or password.");
+  }
+  if (e instanceof MemberAuthError) return e;
+  return e; // unknown — bubble the raw transport error (fail loudly)
+}
+
+// ── PKCE (RFC 7636, S256) — browser Web Crypto, dependency-free ──
+async function generatePkce() {
+  const codeVerifier = randomUnreserved(43);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(codeVerifier));
+  return { codeVerifier, codeChallenge: base64Url(new Uint8Array(digest)), state: randomUnreserved(24) };
+}
+
+function randomUnreserved(length) {
+  const mask = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~";
+  const bytes = crypto.getRandomValues(new Uint8Array(length));
+  let out = "";
+  for (let i = 0; i < length; i++) out += mask[bytes[i] % mask.length];
+  return out;
+}
+
+function base64Url(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}