@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-headless/references/inline-recipes/how-to-code-members-astro.md

@@ -1,124 +0,0 @@
----
-name: "How to Code Members (Astro)"
-description: "The frontend contract for member sign-up / log-in / log-out and member-gated surfaces on a Wix-managed **Astro** frontend — the built-in `/api/auth/login` + `/api/auth/logout` routes that `@wix/astro` ships, the `returnToUrl` param, gating a page by resolving the member in SSR / a backend route, reading the current member with `@wix/members` `getCurrentMember`, and the two rules that keep this path from breaking: **no `OAuthStrategy`/no client** (that 500s under auto-auth) and **no `auth.elevate`** for a member reading their own data. Specifies the *how* for the Astro axis only — read `how-to-code-members-non-astro.md` for any non-Astro frontend."
----
-**RECIPE**: How to Code Member Auth on a Wix-managed **Astro** Frontend (built-in `/api/auth/*`, `@wix/members`)
-
-A concise contract for wiring **login / sign-up / logout and member-gated surfaces** into an Astro frontend. **This is the *how* (which routes, which module, which failure modes), not the *what*** — which pages are gated, what the account page shows, and the design come from the request you're fulfilling.
-
-> **⚠️ AXIS GUARD — this recipe is for Astro only.** On managed-Astro authentication is ambient and login ships as built-in routes. If the frontend is **not** Astro (Vite/React/Vue SPA, static HTML, self-managed), **stop and read `how-to-code-members-non-astro.md`** — that path builds a manual `OAuthStrategy` handshake, which is the opposite of what this recipe says. Cross-contaminating them is a real failure: building an `OAuthStrategy` client on Astro **500s at SSR** (`astro.md` — "no client" is the whole point of the integration).
-
-> **One mechanism, not three.** Sign-up, log-in and log-out are the *same* flow. The Wix login page **logs in an existing member or registers a new one** in the same step; you never build a separate "sign up" call. Log-out is the inverse of the same flow.
-
-> **Login surface — this recipe is the Wix-hosted login page (the default).** If the brief **explicitly** asks for a **custom/branded in-app login form or custom sign-up fields** (full name / username / address / arbitrary fields), that's the *custom login page* surface — **read `how-to-code-members-custom-login.md`**. Note custom login is a client-driven `OAuthStrategy` flow with **no client** under Astro auto-auth, so on Astro it means instantiating an explicit `OAuthStrategy` client in a backend route or a client island (never in SSR frontmatter) — take it on only on real intent; otherwise the built-in routes below are the default. The choice is **intent, not project type**.
-
-Pinned docs (read before wiring — `curl` the `.md` directly):
-- Member login on Astro: <https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/handle-member-login-using-wix-s-astro-integration.md>
-- The integration keystone (auto-auth, "no client"): <https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md>
-- Current member (SDK): <https://dev.wix.com/docs/sdk/frontend-modules/members/current-member/introduction> (open with `?apiView=SDK`)
-
----
-
-## Identity vs. profile — two layers, don't conflate them (read this first)
-
-The docs draw a hard line, and so must the code:
-
-- **Identity / auth** — *"is this caller a logged-in member?"*, log in, log out. Native to the headless OAuth app. **No app install needed.** Everything in "Log in / sign up / log out" and "Gate a surface" below runs on this layer alone.
-- **Member profile / Members Area** — reading the member's name / photo / roles / badges, an editable my-account page. Served by the **Wix Members Area app**, which **must be installed** on the site (see `SETUP.md`). `@wix/members` `getCurrentMember()` returns member data only once that app is present.
-
-So a paywall that only needs "logged-in vs not" runs on identity alone; anything that **displays or edits member data** needs the Members Area app installed. If `getCurrentMember()` returns empty/errors on a site where login clearly worked, suspect the **Members Area app isn't installed** — not a code bug.
-
----
-
-## Log in / sign up / log out — built-in routes, zero wiring
-
-`@wix/astro` ships the endpoints; you only render links/actions. **Do not build a login page or an OAuth handshake** — that's the non-Astro path.
-
-```astro
-<!-- log in OR sign up — same route, redirects to the Wix login page -->
-<a href="/api/auth/login">Log in / Sign up</a>
-
-<!-- land the member somewhere specific afterward -->
-<a href="/api/auth/login?returnToUrl=/account">Log in</a>
-```
-
-Logout is a **POST** to `/api/auth/logout` (optionally with `?returnToUrl=`):
-
-```astro
-<form method="POST" action="/api/auth/logout"><button>Log out</button></form>
-```
-
-- **The param is `returnToUrl` — not `returnUrl`.** The routes validate their query with a strict schema that silently DROPS unknown params, so a misspelled param doesn't error — the member just lands on `/`. The value must be a **relative path** (the callback refuses absolute URLs).
-- After login the member identity **rides on every subsequent SDK call automatically** — no client, no token handling. That's auto-auth (`astro.md`).
-
----
-
-## Gate a surface — resolve identity in SSR or a backend route
-
-Gating is just *"do I have a member session?"*, decided **server-side** (SSR frontmatter or a `src/pages/api/*.ts` route), then bounce anonymous visitors to the built-in login route. This is the exact shape already used for blog comments (`SDK_HANDOFF.md` §5).
-
-```astro
----
-// src/pages/account.astro — gate the page in SSR frontmatter
-import { members } from '@wix/members';
-let me = null;
-try {
-  const res = await members.getCurrentMember({ fieldsets: ['FULL'] });
-  me = res.member ?? null;
-} catch { /* not a member / not installed — treat as anonymous */ }
-
-if (!me) return Astro.redirect('/api/auth/login?returnToUrl=/account');
----
-<h1>Welcome, {me.profile?.nickname ?? me.loginEmail}</h1>
-```
-
-- **Guard the SSR call in `try/catch`** — an unguarded throw truncates the response mid-stream (white screen; `astro.md` A3). An anonymous visitor is a normal state, not an error: catch → treat as logged-out → redirect to login.
-- **Don't render account/gated UI as a client island that checks auth in the browser.** Resolve identity server-side and gate the route; render only what a member should see. (Same reasoning as the blog-comment API-endpoint path — avoid the browser-auth detour.)
-- For an **action** that only *some* callers may take (post a comment, place a member order), don't gate the whole page: render the control always, and on submit POST to a `src/pages/api/*.ts` endpoint that resolves the session and, if the caller isn't a member, redirects to `/api/auth/login?returnToUrl=…`.
-
----
-
-## Read the current member — `@wix/members`, not the dev-preview package
-
-```astro
-import { members } from '@wix/members';
-const { member } = await members.getCurrentMember({ fieldsets: ['FULL'] });
-// member.profile?.nickname, member.profile?.photo, member.loginEmail, member.contactId, member.roles
-```
-
-- **⚠️ The SDK export is `getCurrentMember`, NOT `getMyMember`.** The REST method is named *Get My Member* and the SDK docs page may show `GetMyMember`, but `@wix/members` exports it as **`members.getCurrentMember`** — calling `members.getMyMember(...)` throws `is not a function` at runtime. This bites because a logged-out smoke test never reaches the call; it only fails once a real member loads the page.
-- **⚠️ Use `@wix/members` (`members.getCurrentMember` / `getMember` / `updateMember`).** It needs only **visitor/member auth** and is production-ready. **Do NOT reach for `@wix/site-members`** (`wixSiteMembers`, frontend "Current Member" `getMember`/`getRoles`/`makeProfilePublic`) — it's in **Developer Preview** ("not intended for production"). Use it only if a profile-privacy toggle is *specifically* requested.
-- The member's **photo** field is a `wix:image://` identifier — resolve it with `media.getScaledToFillImageUrl` like any other Wix image (`astro.md` A6); never hand-build the CDN URL.
-- **Reading another member by id returns only their PUBLIC fieldset**, and a **private** profile returns nothing to a visitor/member identity. This is why the blog-comment author lookup (`SDK_HANDOFF.md` §5) quietly assumes the author's profile is public — the same caveat applies to any "look up a member by id" here.
-
----
-
-## ⚠️ Do NOT `auth.elevate()` for member features (the most likely wrong turn)
-
-Member login and elevation are **different axes**:
-
-- **Login** moves you along the **identity** axis: anonymous visitor → a specific member.
-- **`auth.elevate()`** moves you along the **permission** axis: caller → *app/admin* scope.
-
-A logged-in member reading **their own** data — own orders, own bookings, own subscriptions, plan-gated content, their profile — is authorized for it under the **member token, with no elevation**. Reaching for `auth.elevate()` to "make member data work" is the classic mistake: it's the wrong axis, and it doesn't grant a member access to their own data (they already have it).
-
-`auth.elevate()` is only for **site-wide/admin** reads (everyone's orders, listing all members). On Astro that goes in a **backend route** (`src/pages/api/*.ts` wrapping `auth.elevate()`, `astro.md` §2) — never inline in a page. If you're gating content by the member's own plan, that's a member-token read; listing *all* plans/orders as admin is the elevate read. Keep them separate.
-
----
-
-## pricing-plans is a HARD dependency on members
-
-If the site has pricing-plans (membership / subscription / paid tiers), **login is required, not optional**. Ordering a plan (`orders.createOnlineOrder(planId)`) orders it **for a logged-in member**; if none is logged in the Wix flow forces sign-up. `orders.memberListOrders()` and "my subscription" reads return **nothing** for an anonymous visitor.
-
-So: browsing the plans grid is public, but the **subscribe** button and the **my-subscription** surface both need the login mechanism above. A logged-in member calling `orders.createOnlineOrder` needs **no `onBehalf`** — the order is created on their behalf from the member session. (Everywhere else — stores "my orders", bookings "my bookings", events "my registrations" — member login is a *soft* add-on: the purchase/RSVP/book action itself runs fine as an anonymous visitor; only the account view of it needs a member.)
-
----
-
-## Conclusion
-Correct member auth on an Astro frontend:
-- uses the **built-in `/api/auth/login`** (login *and* sign-up) and **POST `/api/auth/logout`** routes with an allow-listed `returnToUrl` — the login handshake **never** builds an `OAuthStrategy` client, and one must never be built in **SSR frontmatter** (the public-env `clientId` is `undefined` at server render → 500). (The one exception is the custom-login surface — `how-to-code-members-custom-login.md` — which builds an explicit client in a backend route or client island, never in SSR frontmatter.)
-- gates surfaces **server-side** (SSR frontmatter or a `src/pages/api/*.ts` route), guarded in `try/catch`, bouncing anonymous visitors to `/api/auth/login?returnToUrl=…`;
-- reads the current member via **`@wix/members` `getCurrentMember`** (not the dev-preview `@wix/site-members`), resolving the photo `wix:image://` URI and expecting only PUBLIC fields for other members;
-- does **no `auth.elevate`** for a member reading their own data (elevation is a different, admin-only axis that lives in a backend route);
-- treats **login as required** whenever pricing-plans is present (subscribe + my-subscription), and as a soft add-on for the "my …" surfaces of the other verticals;
-- needs the **Wix Members Area app installed** only for profile *data* (name/photo/roles) — pure "logged-in vs not" gating runs on the identity layer with no install.

package/skills/wix-headless/references/inline-recipes/how-to-code-members-custom-login.md

@@ -1,160 +0,0 @@
----
-name: "How to Code Members (custom login page)"
-description: The frontend contract for a **custom, branded login/sign-up page** — you build the UI and drive Wix's auth service directly with the `OAuthStrategy` SDK (`register` / `login` / `processVerification` / `getMemberTokensForDirectLogin` / `setTokens` / `sendPasswordResetEmail` / `logout`), instead of redirecting to the Wix-hosted login page. This is the surface to use **only when the brief asks for a custom/in-app login form or custom sign-up fields** (name, address, username, arbitrary fields); otherwise use the Wix login page (`how-to-code-members-*.md`). Covers the `loginState` state machine (SUCCESS / EMAIL_VERIFICATION_REQUIRED / OWNER_APPROVAL_REQUIRED / FAILURE), custom `profile` fields at sign-up, token persistence, reading the member with `@wix/members`, and the no-`auth.elevate` rule. Works on **any** headless project (managed or self-managed) — the choice is intent, not project type.
----
-**RECIPE**: How to Code a **Custom Login Page** (branded in-app auth, `OAuthStrategy` `register`/`login`, `@wix/members`)
-
-A concise contract for building your **own** login / sign-up / logout UI and driving Wix's authentication service directly — instead of bouncing the visitor to the Wix-hosted login page. **This is the *how* (which SDK calls, which states, which failure modes), not the *what*** — the form design, which pages are gated, and what the account page shows come from the request you're fulfilling.
-
-> **⚠️ WHEN TO USE THIS RECIPE — intent, not project type.** Reach for custom login **only when the brief explicitly asks for it**: a **branded / in-app login form** (the visitor never leaves your UI) *or* **custom sign-up fields** (full name, username/nickname, address, arbitrary fields). If the brief just says "let members log in / sign up / have an account" with no mention of a custom form or extra fields, **use the Wix login page instead** — `how-to-code-members-astro.md` (Astro) or `how-to-code-members-non-astro.md` (non-Astro). The Wix login page needs zero UI and is the deterministic default; custom login is more code and more failure modes, so take it on only on real intent.
-
-> **Works on any headless project.** The Wix docs frame custom login pages as "self-managed only," but that's positioning, not a technical lockout — the `register`/`login` SDK methods (and their `Register V2`/`Login V2` IAM endpoints) authenticate against the same Wix auth service and **work on managed projects too**. So **do not branch on project type** — if the intent is custom login, build it; the flow below is identical on managed and self-managed.
-
-> **One client, one flow — sign-up and log-in are the same machine.** Both `register()` and `login()` return the **same** `StateMachine` shape and both end at `getMemberTokensForDirectLogin` → `setTokens`. Member tokens are the **same shape** as visitor tokens (`role: member`); logging in just swaps the token set on the visitor client you already have.
-
-> **⚠️ This is a client-driven (`OAuthStrategy`) flow — it is the non-Astro shape.** `register`/`login` live on `client.auth`, i.e. the manual visitor client `non-astro.md` builds. Astro's auto-auth ships **no client** to call them on. So: on a **non-Astro** frontend (SPA / static), this is the natural path. On **Astro**, custom login means stepping *outside* auto-auth — instantiate an explicit `OAuthStrategy` client (in a backend route or a client island) to run these calls; do **not** expect the built-in `/api/auth/*` routes to do custom login (they only drive the Wix login page). If the brief is Astro *and* doesn't demand a custom form, prefer the Wix login page (`how-to-code-members-astro.md`).
-
-Pinned docs (read before wiring — `curl` the `.md` directly):
-- Custom login via the JS SDK: <https://dev.wix.com/docs/go-headless/authentication/members/custom-login-page/build-a-custom-login-page-js-sdk.md>
-- `OAuthStrategy` reference (`register`/`login`/`processVerification`/`getMemberTokensForDirectLogin`/`sendPasswordResetEmail`, the `StateMachine` + `IdentityProfile` objects): <https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md>
-- Current member (SDK): <https://dev.wix.com/docs/sdk/frontend-modules/members/current-member/introduction> (open with `?apiView=SDK`)
-
----
-
-## Preconditions
-
-- **`clientId` only, never the secret.** Custom login uses the same **public** OAuth client id as the visitor client (`non-astro.md` N6). No `client_secret` in the frontend, ever.
-- **No redirect / no allow-listed callback for login itself.** Unlike the Wix login page, `register`/`login` are **direct API calls** — the visitor never leaves your page, so there is **no `redirectUri` to allow-list** for the login round-trip. (Two side flows *do* redirect and need an allow-listed URI: `sendPasswordResetEmail(email, redirectUri)` and `logout(originalUrl)`'s `logoutUrl`. Allow-list those URLs on the OAuth app if you wire password reset / logout return.)
-- **The visitor session is automatic.** The client mints an anonymous visitor token on first use, and `register`/`login` run under it — you do **not** hand-mint a visitor token first. (That manual step only exists in the raw-REST version of this flow.)
-- **Profile data still needs the Members Area app.** Reading the member back (`getCurrentMember`) and **defining `customFields`** need the **Wix Members Area app** installed (`SETUP.md`) — see the identity-vs-profile split below.
-
----
-
-## Identity vs. profile — two layers, 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** — the whole `register`/`login`/`loggedIn()` flow below runs on this layer alone.
-- **Member profile / Members Area** — reading name / photo / roles, an editable my-account page, **and any custom field definitions**. Served by the **Wix Members Area app**, which **must be installed** (`SETUP.md`). `@wix/members` `getCurrentMember()` returns data only once that app is present.
-
-If `getCurrentMember()` is empty on a site where `loggedIn()` is `true`, suspect the **Members Area app isn't installed** — not a code bug.
-
----
-
-## The flow — build a form, call the SDK, handle the state machine
-
-Reuse the one visitor client `non-astro.md` builds (`createClient({ modules: { members }, auth: OAuthStrategy({ clientId }) })`) — don't make a second client.
-
-```js
-// Sign up — register() takes a `profile` for custom fields (this is why you'd pick custom login)
-const res = await client.auth.register({
-  email, password,
-  profile: {                       // all optional; include what the brief's sign-up form collects
-    firstName, lastName,
-    nickname,                      // ≈ username
-    addresses: [{ address: { /* … */ } }],
-    // customFields: { <fieldName>: <value> }   // ⚠️ see note below — needs field defs
-  },
-});
-
-// Log in — same StateMachine shape, no profile
-// const res = await client.auth.login({ email, password });
-
-// Handle the result (both register and login return this)
-switch (res.loginState) {
-  case 'SUCCESS': {
-    const tokens = await client.auth.getMemberTokensForDirectLogin(res.data.sessionToken);
-    client.auth.setTokens(tokens);   // subsequent SDK calls now run as the member
-    persistTokens(tokens);           // see persistence below
-    break;                           // now render the member UI / navigate
-  }
-  case 'EMAIL_VERIFICATION_REQUIRED': {
-    // Wix has emailed a 6-digit code. Collect it in your UI, then:
-    const v = await client.auth.processVerification({ verificationCode });
-    if (v.loginState === 'SUCCESS') {
-      const tokens = await client.auth.getMemberTokensForDirectLogin(v.data.sessionToken);
-      client.auth.setTokens(tokens); persistTokens(tokens);
-    }
-    break;
-  }
-  case 'OWNER_APPROVAL_REQUIRED':
-    // Membership is pending owner approval — show a "pending" notice; they can log in once approved.
-    break;
-  case 'FAILURE':
-    // Surface a message keyed off res.errorCode:
-    //   invalidEmail | invalidPassword | emailAlreadyExists | resetPassword
-    //   | missingCaptchaToken | invalidCaptchaToken
-    // 'resetPassword' → call sendPasswordResetEmail (below), don't retry login.
-    break;
-}
-```
-
-- **`loggedIn()` gates everything.** `client.auth.loggedIn()` → `false` = anonymous, `true` = member. Render the account UI only when `true`; otherwise show your login form.
-- **Logout** is a redirect (same as the Wix-login path): `const { logoutUrl } = await client.auth.logout(window.location.href); clearPersistedTokens(); window.location.href = logoutUrl;`
-- **Password reset**: `await client.auth.sendPasswordResetEmail(email, redirectUri)` — `redirectUri` **must be an allow-listed** authorization redirect URI; Wix hosts the reset page and returns the member to it.
-
----
-
-## The `loginState` state machine — handle every branch (don't assume SUCCESS)
-
-`register()` / `login()` / `processVerification()` all return a `StateMachine` (`{ loginState, data: { sessionToken }, errorCode, error }`). The trap is coding only the happy path:
-
-- **`SUCCESS`** — exchange `data.sessionToken` for tokens (above). Only here do you get a session.
-- **`EMAIL_VERIFICATION_REQUIRED`** — fires when a brand-new registrant's email **already exists as a contact**, or when **email verification is enabled** in the site's Member Settings. You must build the code-entry step (`processVerification`) or login silently dead-ends. With default settings + a fresh email, you'll usually get `SUCCESS` straight away — but code the branch anyway; it's site-setting-dependent, not code-dependent.
-- **`OWNER_APPROVAL_REQUIRED`** — signup policy is manual-approval; show "pending", don't treat as an error.
-- **`FAILURE`** — branch on `errorCode` (`invalidEmail` / `invalidPassword` / `emailAlreadyExists` / `resetPassword` / captcha codes). `emailAlreadyExists` on register = route them to log in; `resetPassword` = send a reset email.
-
-**Signup security (email verification, owner approval, reCAPTCHA) is dashboard-governed, not code.** These are Site-Member-Settings toggles — document them as host-configurable, don't try to set them from a headless run. There is **no headless TOTP/SMS 2FA**; the security layers are password + email verification + reCAPTCHA. If reCAPTCHA is enabled in settings, pass `captchaTokens` to `register`/`login` (`OAuthStrategy` exposes `captchaVisibleSiteKey`/`captchaInvisibleSiteKey`).
-
----
-
-## Custom sign-up fields — the whole reason to pick this surface
-
-`register`'s `profile` (`IdentityProfile`) accepts `firstName`, `lastName`, `nickname` (≈ username), `picture`, `phones`, `addresses`, `labels`, `language`, `privacyStatus`, and **`customFields`** (an arbitrary `name → value` map). So "username + email + full name + address + password" maps straight onto `profile`.
-
-- **⚠️ Standard fields work as-is; arbitrary `customFields` need field definitions.** `firstName`/`lastName`/`nickname`/`addresses`/`phones` are accepted directly. But keys inside `customFields` must first be **defined** via the Members Custom Fields API (which needs the **Members Area app**) — an undefined custom field is silently dropped. If the brief's extra fields are the standard ones, you need no field defs; only truly custom keys do.
-- The Wix login page **cannot** collect any of these — that's the capability custom login uniquely unlocks, and the reason to take on the extra code.
-
----
-
-## Token persistence & renewal — treat member tokens like visitor tokens
-
-Member tokens are the **same token set** the visitor session machinery already handles; login just swaps them in.
-
-- **Persist** the token set (localStorage or a cookie) after `setTokens` so a reload stays logged in. On boot, if you have a stored set, `client.auth.setTokens(stored)` before first render — or pass `tokens` into `OAuthStrategy({ clientId, tokens })` at client creation.
-- **Renew** with `client.auth.renewToken(refreshToken)` (or the SDK's automatic renewal when you re-hydrate via `setTokens`). A member session expiring is normal — refresh, don't force a re-login unless the refresh token is gone.
-- On logout, **clear** the persisted set so the next boot is a clean anonymous visitor.
-- **Keep one shared client instance** — creating a new client per component drops the session (a documented custom-login pitfall).
-
----
-
-## Read the current member — `@wix/members`, not the dev-preview package
-
-```js
-import { members } from '@wix/members';
-const { member } = await client.members.getCurrentMember({ fieldsets: ['FULL'] });
-// member.profile?.nickname, member.profile?.photo, member.loginEmail, member.contactId, member.roles
-```
-
-- **⚠️ The SDK export is `getCurrentMember`, NOT `getMyMember`.** The REST method is named *Get My Member* and the SDK docs page may show `GetMyMember`, but `@wix/members` exports it as **`client.members.getCurrentMember`** — calling `getMyMember(...)` throws `is not a function` at runtime. Silent trap: a logged-out smoke test never reaches the call.
-- **⚠️ Use `@wix/members`**, not the Developer-Preview `@wix/site-members`.
-- The **photo** is a `wix:image://` identifier — resolve with `media.getScaledToFillImageUrl` (`non-astro.md` N7); never hand-build the CDN URL.
-
----
-
-## ⚠️ Do NOT `auth.elevate()` — wrong axis (and unavailable on a SPA)
-
-**Login** is the **identity** axis (anonymous → a specific member). **`auth.elevate()`** is the **permission** axis (→ app/admin scope). A member reading **their own** data (own profile, own orders/bookings/subscriptions, plan-gated or member-scoped content) is authorized under the **member token, no elevation** — reaching for elevate to "make member data work" is the wrong axis. A pure SPA has no server, so there is no `auth.elevate` at all (`non-astro.md` N5) — and member features don't need it.
-
----
-
-## Conclusion
-Correct custom-login auth:
-- is taken on **only when the brief asks for a branded/in-app login form or custom sign-up fields** — otherwise the Wix login page (`how-to-code-members-{astro,non-astro}.md`) is the default;
-- works on **any** headless project (managed or self-managed) — **no project-type branch**;
-- reuses the **one visitor `OAuthStrategy` client** and drives `register` / `login` / `processVerification` → `getMemberTokensForDirectLogin` → `setTokens`, with `logout` and `loggedIn()`;
-- **handles the full `loginState` machine** (SUCCESS / EMAIL_VERIFICATION_REQUIRED / OWNER_APPROVAL_REQUIRED / FAILURE+`errorCode`), not just SUCCESS;
-- collects custom fields via `register`'s `profile` — standard fields directly, arbitrary `customFields` only after defining them (needs the Members Area app);
-- treats signup security (verification / approval / reCAPTCHA) as **dashboard-governed**, sets none from the run, and states MFA is unsupported headless;
-- **persists and renews** member tokens like visitor tokens, on **one shared client**;
-- reads the member via **`@wix/members` `getCurrentMember`** (not the dev-preview package);
-- does **no `auth.elevate`** for own-data reads;
-- needs the **Wix Members Area app** only for profile *data* and custom-field definitions — pure "logged-in vs not" gating runs on the identity layer with no install.

package/skills/wix-headless/references/inline-recipes/how-to-code-members-non-astro.md

@@ -1,118 +0,0 @@
----
-name: "How to Code Members (non-Astro)"
-description: The frontend contract for member sign-up / log-in / log-out and member-gated surfaces on a **non-Astro** frontend (Vite/React/Vue SPA or static HTML, managed-non-Astro or self-managed) — the manual `OAuthStrategy` handshake off the *same* visitor client non-astro.md already builds (`generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()`), token persistence + `renewToken`, the published-site and allow-listed-redirectUri preconditions, defaulting to the Wix login page, reading the current member with `@wix/members`, and the no-`auth.elevate` rule. Specifies the *how* for the non-Astro axis only — read `how-to-code-members-astro.md` for an Astro frontend.
----
-**RECIPE**: How to Code Member Auth on a **non-Astro** Frontend (manual `OAuthStrategy`, `@wix/members`)
-
-A concise contract for wiring **login / sign-up / logout and member-gated surfaces** into a non-Astro frontend — a Vite/React/Vue SPA or plain static HTML, whether managed-non-Astro or self-managed. **This is the *how* (which calls, which preconditions, which failure modes), not the *what*** — which pages are gated, what the account page shows, and the design come from the request you're fulfilling.
-
-> **⚠️ AXIS GUARD — this recipe is for non-Astro only.** Here you drive the OAuth handshake yourself on the same manual client `non-astro.md` builds for visitors. If the frontend **is** Astro, **stop and read `how-to-code-members-astro.md`** — Astro ships built-in `/api/auth/login` routes and auto-auth, and building the `OAuthStrategy` handshake below on Astro is wrong (and 500s at SSR). Don't cross the streams.
-
-> **One mechanism, not three.** Sign-up, log-in and log-out are the *same* flow — the Wix login page **logs in an existing member or registers a new one** in one step; you never build a separate "sign up" call. Member tokens are the **same shape** as visitor tokens, just `role: member`: login just swaps the token set on the client you already have.
-
-Pinned docs (read before wiring — `curl` the `.md` directly):
-- Wix-managed login via the JS SDK: <https://dev.wix.com/docs/go-headless/authentication/members/wix-login-page/add-a-wix-login-page-js-sdk.md>
-- `OAuthStrategy` reference (member flows, token/session methods): <https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md>
-- Handle visitors & members via the JS SDK: <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/visitors/handle-visitors-using-the-js-sdk.md>
-- Current member (SDK): <https://dev.wix.com/docs/sdk/frontend-modules/members/current-member/introduction> (open with `?apiView=SDK`)
-
----
-
-## Preconditions — get these right or `getAuthUrl` fails (read first)
-
-- **`clientId` only, never the secret.** Member auth uses the same **public** OAuth client id as the visitor client (`non-astro.md` N6). No `client_secret` in the frontend, ever.
-- **The connected site must be PUBLISHED.** `getAuthUrl` serves the Wix login page; against an unpublished site it fails the redirect with a non-obvious error. Publish before testing login (like the events payment-method precondition).
-- **The `redirectUri` must be in the OAuth app's allowed redirect URIs — exact match, and YOU must register it (it is not automatic).** A mismatch (or a missing entry) is the classic login 4xx — login is dead until it's registered. `wix release` auto-registers the deployed **origin** (`allowedRedirectDomains`), but **not** this member-login **callback** (`allowedRedirectUris`) — that's a separate field and a separate, manual step. Because the callback embeds the deployed origin, it's a **post-deploy** step: register it right after release. **⚠️ Do not conclude `allowedRedirectUris` is read-only/dashboard-only** — the `UpdateOAuthApp` doc may not list it prominently, but a **masked `PATCH`** sets it (the field mask is required or it silently no-ops). **Mechanics: `managed/DEPLOYMENT.md` → "Member login on a non-Astro frontend".** Register both the exact callback (`window.location.origin + '/callback'`) and the `https://*-<host>/callback` wildcard; don't rely on trailing-slash/path variants matching.
-- **Default to the Wix login page** — the sub-type this recipe uses. Three login sub-types exist (Wix login page / custom login page / externally-managed); the Wix page needs **no UI to build** and is deterministic. **If the brief explicitly asks for a custom/branded in-app login form or custom sign-up fields** (full name / username / address / arbitrary fields), **stop and read `how-to-code-members-custom-login.md`** — that path builds the form and drives `client.auth.register`/`login` directly (works on any project type). Use externally-managed only when specifically requested. When no custom form or extra fields are named, the Wix login page below is the default — don't build a custom form unprompted.
-
----
-
-## Identity vs. profile — two layers, don't conflate them
-
-- **Identity / auth** — *"is this caller a logged-in member?"*, log in, log out. Native to the headless OAuth app. **No app install needed** — everything in "The login flow" and `loggedIn()`-based gating below runs on this layer alone.
-- **Member profile / Members Area** — reading name / photo / roles / badges, an editable my-account page. Served by the **Wix Members Area app**, which **must be installed** (see `SETUP.md`). `@wix/members` `getCurrentMember()` returns data only once that app is present.
-
-If `getCurrentMember()` returns empty/errors on a site where `loggedIn()` is `true`, suspect the **Members Area app isn't installed** — not a code bug.
-
----
-
-## The login flow — the same client, plus a round-trip
-
-Reuse the one visitor client `non-astro.md` builds (`createClient({ modules, auth: OAuthStrategy({ clientId }) })`) — don't make a second client. Login is three steps across a redirect.
-
-```js
-// 1 · start login (sign-up is the SAME call) — from a "Log in" button
-const redirectUri  = window.location.origin + '/callback';   // MUST be allow-listed, exact match
-const originalUri   = window.location.href;                    // where to send the member back after
-const oAuthData = client.auth.generateOAuthData(redirectUri, originalUri); // PKCE: state + codeVerifier
-localStorage.setItem('wixOAuthData', JSON.stringify(oAuthData));           // survive the redirect
-const { authUrl } = await client.auth.getAuthUrl(oAuthData);
-window.location.href = authUrl;                                // → Wix login page (login or register)
-
-// 2 · on the callback page (/callback)
-const oAuthData = JSON.parse(localStorage.getItem('wixOAuthData'));
-const returned  = client.auth.parseFromUrl();                  // { code, state } or { error }
-if (returned.error) { /* surface returned.errorDescription; do NOT loop back into getAuthUrl */ }
-const tokens = await client.auth.getMemberTokens(returned.code, returned.state, oAuthData);
-client.auth.setTokens(tokens);                                 // subsequent SDK calls now run as the member
-persistTokens(tokens);                                         // see persistence below
-window.location.href = returned.originalUri ?? '/';            // back to where login started
-
-// 3 · logout
-const { logoutUrl } = await client.auth.logout(window.location.href);
-clearPersistedTokens();
-window.location.href = logoutUrl;
-```
-
-Check auth state anywhere: **`client.auth.loggedIn()`** — `false` = anonymous visitor, `true` = logged-in member. Gate a view on it (render the account UI only when `true`; otherwise show a "Log in" control that runs step 1).
-
----
-
-## Token persistence & renewal — treat member tokens like visitor tokens
-
-Member tokens are the **same token set** the visitor session machinery already handles; login just swaps them in.
-
-- **Persist** the token set (localStorage or a cookie) after `setTokens` so a reload stays logged in. On app boot, if you have a stored set, `client.auth.setTokens(stored)` before first render.
-- **Renew** with `client.auth.renewToken(refreshToken)` (or the SDK's automatic renewal when you re-hydrate via `setTokens`) — same as the visitor refresh flow. A member session expiring is a normal state; refresh, don't force a re-login unless the refresh token is gone.
-- On logout, **clear** the persisted set so the next boot is a clean anonymous visitor.
-
----
-
-## Read the current member — `@wix/members`, not the dev-preview package
-
-```js
-import { members } from '@wix/members';
-// with the member tokens set on the client:
-const { member } = await client.members.getCurrentMember({ fieldsets: ['FULL'] });
-// member.profile?.nickname, member.profile?.photo, member.loginEmail, member.contactId, member.roles
-```
-
-- **⚠️ The SDK export is `getCurrentMember`, NOT `getMyMember`.** The REST method is named *Get My Member* and the SDK docs page may show `GetMyMember`, but `@wix/members` exports it as **`client.members.getCurrentMember`** — calling `getMyMember(...)` throws `is not a function` at runtime. It's a silent trap: a logged-out smoke test never reaches the call, so it only fails once a real member loads the account page.
-- **⚠️ Use `@wix/members`** (`getCurrentMember` / `getMember` / `updateMember`) — visitor/member auth, production-ready. **Do NOT use `@wix/site-members`** (`wixSiteMembers`, "Current Member") — it's in **Developer Preview** ("not for production"). Only if a profile-privacy toggle is specifically requested.
-- The **photo** is a `wix:image://` identifier — resolve with `media.getScaledToFillImageUrl` (`non-astro.md` N7); never hand-build the CDN URL.
-- **Another member by id → PUBLIC fieldset only**; a **private** profile returns nothing to a member/visitor identity (relevant to any "look up author by id" lookup).
-
----
-
-## ⚠️ Do NOT `auth.elevate()` — and on a SPA you can't anyway
-
-- **Login** is the **identity** axis (anonymous → a specific member). **`auth.elevate()`** is the **permission** axis (→ app/admin scope). A member reading **their own** data (own orders/bookings/subscriptions, plan-gated content, their profile) is authorized under the **member token, no elevation** — reaching for elevate to "make member data work" is the wrong axis and doesn't help.
-- A pure SPA / static site has **no server, so there is no `auth.elevate` at all** (`non-astro.md` N5). Admin/site-wide reads (everyone's orders, all members) genuinely can't run on this path — that's a real limitation, but **member features don't need it**, so it does not block login / account / gated content. If a feature truly needs an admin read, it needs a server (out of scope for a static SPA).
-
----
-
-## pricing-plans is a HARD dependency on members
-
-If the site has pricing-plans, **login is required, not optional**. Ordering a plan (`orders.createOnlineOrder(planId)`) orders it **for a logged-in member**; anonymous → the Wix flow forces sign-up. `orders.memberListOrders()` and "my subscription" reads return **nothing** for an anonymous visitor. So the plans grid is public, but the **subscribe** button and the **my-subscription** surface both need the login flow above; a logged-in member calling `orders.createOnlineOrder` needs **no `onBehalf`**. Everywhere else (stores "my orders", bookings "my bookings", events "my registrations"), login is a *soft* add-on — the purchase/RSVP/book action runs fine as an anonymous visitor; only the account view of it needs a member.
-
----
-
-## Conclusion
-Correct member auth on a non-Astro frontend:
-- reuses the **one visitor `OAuthStrategy` client** and drives the handshake — `generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()` — **never** an Astro `/api/auth/*` route;
-- gets the preconditions right up front: **`clientId` only**, **site published**, **`redirectUri` allow-listed exact-match**, **default to the Wix login page**;
-- **persists and renews** member tokens like visitor tokens (`renewToken`), re-hydrating with `setTokens` on boot and clearing them on logout;
-- reads the current member via **`@wix/members` `getCurrentMember`** (not the dev-preview `@wix/site-members`), resolving the photo `wix:image://` URI, expecting PUBLIC-only fields for other members;
-- does **no `auth.elevate`** (wrong axis for own-data reads; unavailable on a serverless SPA anyway);
-- treats **login as required** whenever pricing-plans is present, and as a soft add-on for the "my …" surfaces of the other verticals;
-- needs the **Wix Members Area app installed** only for profile *data* — pure "logged-in vs not" gating runs on the identity layer with no install.

package/skills/wix-headless/references/inline-recipes/how-to-code-portfolio.md

@@ -1,132 +0,0 @@
----
-name: "How to Code Portfolio"
-description: The frontend read contract for a Wix Portfolio backend — which @wix/portfolio modules, the exact list/query/detail calls, and the failure modes the docs omit (`_id` not `id`, object-param query NOT a builder, cover-image `.url` vs project-item `wix:image://` string). The *how*; which projects/collections to render come from the request.
----
-**RECIPE**: How to Code a Portfolio Frontend (Wix Portfolio v1 — display-only, no eCommerce)
-
-A contract for the **frontend code** of a portfolio/showcase site. The *how* (modules, calls, fields), not the *what* (which projects to show, the page design, the framework — those come from the request).
-
-> **This recipe is for CODING, not seeding.** It assumes the backend already exists — collections and projects were created by `setup-portfolio.md`. It says nothing about creating data; it only reads and renders it. Portfolio is **display-only**: there is no cart, checkout, or eCommerce — do **not** pull in `@wix/ecom`/`@wix/redirects`.
-
-> **⚠️ Reading rule — append `?apiView=SDK` to every doc link below.** Wix renders two views of each page: the bare/REST view shows `id`; the `?apiView=SDK` view shows **`_id`**. The SDK is what the frontend calls, so the REST view will actively mislead you (reading `project.id` yields `undefined` and detonates every downstream key/route). Always read the SDK view.
-
----
-
-## The modules and the client (read this first)
-
-**No app-id constant is needed** — Portfolio has no `catalogReference`/eCommerce surface. Everything is a plain read from `@wix/portfolio`.
-
-**Module table** — import only what the site uses:
-
-| Need | Package | Module | Key methods |
-|---|---|---|---|
-| Collections (groupings) | `@wix/portfolio` | `collections` | `listCollections(options?)`, `queryCollections(query, options?)`, `getCollection(id, options?)` |
-| Projects (the showcased work) | `@wix/portfolio` | `projects` | `listProjects(options?)`, `queryProjects(query, options?)`, `getProject(id, options?)` |
-| A project's media items (deeper project-page gallery) | `@wix/portfolio` | `projectItems` | `listProjectItems(projectId, options?)` |
-| Resolve image media strings (covers **and** project items) | `@wix/sdk` | `media` | `getScaledToFillImageUrl(id, w, h, {})` |
-| Build the client (non-Astro only) | `@wix/sdk` | `createClient`, `OAuthStrategy` | — |
-
-- **There is one Portfolio API version (v1)** — no V1-vs-V3 trap like Stores.
-- **`queryX` accepts BOTH an object-param and a builder overload** — `queryProjects({ filter, cursorPaging })` **and** `queryProjects().eq(…).find()` both type-check (unlike Stores/Bookings, whose object-param shape was removed). Either compiles; this recipe prefers a **client-side filter** (see Filtering) so you needn't pick.
-- **Public read — no `auth.elevate`.** Portfolio content is public on the live site, so a visitor client reads collections/projects/items with **no elevation**. (The docs show `auth.elevate(...)` examples — those are for backend/admin jobs; a visitor-facing read does not need them. Elevation is the separate admin axis.)
-
-**Auth / client — the framework split:**
-
-- **Astro (Wix-managed, the default):** auth is **ambient**. Import the modules and call them directly from server components / `src/pages/api/*` — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
-  ```ts
-  import { collections, projects } from '@wix/portfolio';
-  const { collections: cols } = await collections.listCollections();
-  const { projects: projs } = await projects.listProjects();
-  ```
-- **Non-Astro (Vite/React/Vue/static):** build **one** manual visitor client and reuse it. The `clientId` is the app's **public** OAuth id (not a secret; `client_secret` never reaches the frontend).
-  ```ts
-  import { createClient, OAuthStrategy } from '@wix/sdk';
-  import { collections, projects, projectItems } from '@wix/portfolio';
-  const wixClient = createClient({
-    modules: { collections, projects, projectItems },
-    auth: OAuthStrategy({ clientId: import.meta.env.PUBLIC_WIX_CLIENT_ID }),
-  });
-  // then: await wixClient.projects.listProjects()
-  ```
-  A mis-wired public env var inlines as `undefined` and 400s **every** call — after building, confirm the actual `clientId` value is in the bundle.
-
----
-
-## The features (build the ones the site needs)
-
-Each subsection is self-contained — implement only what the site uses, in any order. Ordering matters only *within* a feature (resolve the collection/project before you filter/render by it).
-
-### Listing the gallery (projects + collections) — and the `_id` rule
-
-The gallery is two reads: **all projects** and **all collections**. Prefer the **`list*` methods** — they take an optional `options` (`{ paging: { limit, cursor }, includePageUrl }`) and need no query object:
-
-```ts
-const { projects: projs = [] } = await projects.listProjects();        // Astro: module; non-Astro: wixClient.projects…
-const { collections: cols = [] } = await collections.listCollections();
-```
-Docs (read `?apiView=SDK`):
-- <https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/list-projects?apiView=SDK>
-- <https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/list-collections?apiView=SDK>
-
-**⚠️ CRITICAL — the id field is `_id`, never `id`.** Under `?apiView=SDK`, both `Project` and `Collection` expose **`_id`** (a GUID), `title`, `description`, `slug`, `hidden`, `coverImage`; `Project` also has `collectionIds: string[]` and `details`. Reading `.id` returns `undefined` — every `key={p.id}` and every `/[slug]` route built from it breaks silently. If you find yourself reading `id`, you're looking at the REST doc view.
-
-**⚠️ The list arrays and `_id` are nullable under `strict`.** `listProjects()`/`listCollections()`/`listProjectItems()` return the array as `T[] | undefined` (default it with `= []` as above, or `?? []`), and `_id`/`slug` are `string | null | undefined`. So narrow before you key/route on them (`if (!p._id) continue`, `p.slug === params.slug`) — a bare `.filter`/`.includes(col._id)` won't type-check without the guard.
-
-**⚠️ Only `Collection` has `sortOrder` — `Project` does not.** Sort **collections** by their numeric `sortOrder` for the owner's intended order (`[...cols].sort((a,b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))`). **`Project` exposes no `sortOrder`** (reading it is `TS2339`) — render projects in the list-response order, or sort by a field they *do* have (`title`, `_createdDate`) if you need a stable one. Don't sort projects by `sortOrder`.
-
-**⚠️ Respect `hidden`.** An entity with `hidden: true` should not appear publicly. Filter it out client-side (`projs.filter(p => !p.hidden)`) — and remember an *omitted* `hidden` comes back **absent** (proto3), so test `!p.hidden` (absent ⇒ falsy ⇒ shown), never `p.hidden === false`.
-
-### Grouping / filtering by collection
-
-A project links to its collections via **`project.collectionIds: string[]`** (a project can be in several). To show a collection's projects, the **default is a client-side filter** over the already-listed projects (avoids a second round-trip; narrow the nullable `_id` first):
-
-```ts
-const colId = collection._id;
-const inCollection = colId ? projs.filter(p => p.collectionIds?.includes(colId)) : [];
-```
-This avoids the server-filter fragility and one extra round-trip; portfolios are small.
-
-**If you filter server-side, `queryProjects`/`queryCollections` accepts EITHER shape — both compile.** The installed SDK exposes two overloads: an object-param `queryProjects({ filter, cursorPaging, sort })` (e.g. `projects.queryProjects({ cursorPaging: { limit: 100 } })`) **and** a fluent builder `queryProjects().eq('…', …).find()`. Either type-checks — pick one and confirm the filter matches before shipping. (Client-side filtering above sidesteps the choice.)
-- <https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/query-projects?apiView=SDK>
-
-### Project detail page (resolve by slug, then its media)
-
-Detail routes resolve a **`slug`** from the URL (the site is SSR — resolve at request time, no `getStaticPaths`). Resolve the project **client-side from the list** (reliable), then optionally load its media items:
-
-```ts
-const project = projs.find(p => p.slug === params.slug);        // from listProjects()
-const { items } = await projectItems.listProjectItems(project._id);   // media gallery (owner-added)
-```
-- `projectItems.listProjectItems(projectId, options?)` — first arg is the **project `_id`** (positional), not an options object.
-- <https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/list-project-items?apiView=SDK>
-
-Render `project.details` — an array of **`{ label, text }`** pairs (Role, Year, Client…) the seed may have set; it can be `[]`, so guard before mapping.
-
-### Rendering images — ONE `Image` shape, always a media STRING
-
-**⚠️ CRITICAL — `imageInfo` is a bare media STRING, for covers AND project items alike. There is no ready `.url`.** The installed SDK types **one** `Image { imageInfo?: string; focalPoint? }`, reused by `Project.coverImage`, `Collection.coverImage`, **and** `Item.image`. So `coverImage.imageInfo` and `item.image?.imageInfo` are both **strings** (a `wix:image://…` identifier) — reading `.url` on either is a type error (`TS2339: Property 'url' does not exist on type 'string'`). (The *REST* API returns `coverImage.imageInfo` as an object with a populated `url`, but the **SDK** — what the frontend calls — types it as a string; the package wins.) Resolve every portfolio image through the same `@wix/sdk` media helper — never drop a `wix:image://` value straight into `<img src>` (→ `ERR_UNKNOWN_URL_SCHEME`), never hand-build a `static.wixstatic.com` URL from it (→ 403):
-
-```ts
-import { media } from '@wix/sdk';
-
-// cover (project or collection) — optional, guard it
-const coverId = project.coverImage?.imageInfo;                 // string | undefined
-const cover = coverId ? media.getScaledToFillImageUrl(coverId, 1200, 900, {}) : undefined;
-
-// project-item media (same shape, same helper)
-const itemId = item.image?.imageInfo;                          // string | undefined
-const src = itemId ? media.getScaledToFillImageUrl(itemId, 1200, 900, {}) : undefined;
-```
-
-- **`media.getScaledToFillImageUrl` takes FOUR arguments** — `(wixMediaIdentifier, width, height, options)`; the `options` object is **required** (pass `{}`). A 3-arg call fails `TS2554`.
-- **Covers are optional.** A text-only-seeded project/collection has **no** `coverImage` (absent), so the resolved value is `undefined` → render the **themed-block fallback** (`IMAGE_GENERATION.md`), never a broken `<img>`.
-
----
-
-## Conclusion
-- **Modules:** `collections`, `projects`, `projectItems` from `@wix/portfolio`; `media` + `createClient`/`OAuthStrategy` from `@wix/sdk`. **No** `@wix/ecom`/`@wix/redirects` — portfolio is display-only.
-- **`_id`, never `id`** — read entities under `?apiView=SDK`; `.id` is `undefined`. List arrays are `T[] | undefined` (default `= []`); `_id`/`slug` are nullable — narrow before keying/routing.
-- **Query has both overloads** — `queryProjects({ filter, cursorPaging })` **and** `queryProjects().eq().find()` compile; prefer client-side filtering by `collectionIds`/`slug`.
-- **Only collections have `sortOrder`** (sort collections by it); projects don't — render in list order. **Respect `hidden`** (test `!hidden` — an omitted `hidden` is absent).
-- **One `Image` shape:** `coverImage.imageInfo` and `item.image.imageInfo` are both bare media **strings** (no `.url`) → resolve every image via `media.getScaledToFillImageUrl(id, w, h, {})` (4 args); covers are optional → themed block. Never hand-build wixstatic URLs.
-- **Public read, no `auth.elevate`** — visitor client reads all content; elevation is the separate admin axis.