@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/members/project/src/hooks/members/useMember.ts

@@ -0,0 +1,67 @@
+// React binding for the member store. Works in any React root — Astro islands (several on
+// one page share the same session) and SPAs alike. SSR-friendly: pass a server-resolved
+// member as `initialMember` (Astro island props) and no client re-fetch happens.
+import { useRef, useSyncExternalStore } from "react";
+import {
+  getMemberState,
+  hydrateMember,
+  login,
+  register,
+  logout,
+  refreshMember,
+  subscribeMember,
+  verifyEmail,
+  type MemberState,
+} from "../../wix/members/member-store";
+import type { LoginOptions, LoginResult } from "../../wix/members/auth";
+import type { CurrentMember } from "../../wix/members/types";
+
+export interface UseMemberOptions {
+  /** Server-resolved member (null = a known-anonymous visitor); omit to resolve client-side. */
+  initialMember?: CurrentMember | null;
+}
+
+export interface UseMember extends MemberState {
+  /** Submit the shipped in-app credential form; `returnTo` is where a SUCCESS lands. */
+  login: (email: string, password: string, options?: LoginOptions) => Promise<LoginResult>;
+  register: (
+    email: string,
+    password: string,
+    profile?: { firstName?: string; lastName?: string },
+    options?: LoginOptions,
+  ) => Promise<LoginResult>;
+  verifyEmail: (code: string) => Promise<LoginResult>;
+  /** Log out through the Wix logout flow; navigates away. */
+  logout: (returnTo?: string) => Promise<void>;
+  refresh: () => Promise<void>;
+}
+
+export function useMember({ initialMember }: UseMemberOptions = {}): UseMember {
+  // Adopt SSR props into the shared store before the first subscription (a no-op once any
+  // island has settled the session).
+  if (typeof window !== "undefined" && initialMember !== undefined)
+    hydrateMember(initialMember);
+  const server = useRef<MemberState | null>(null);
+  server.current ??=
+    initialMember !== undefined
+      ? {
+          member: initialMember,
+          loggedIn: initialMember !== null,
+          loading: false,
+          error: null,
+        }
+      : getMemberState();
+  const state = useSyncExternalStore(
+    subscribeMember,
+    getMemberState,
+    () => server.current as MemberState,
+  );
+  return {
+    ...state,
+    login,
+    register,
+    verifyEmail,
+    logout,
+    refresh: refreshMember,
+  };
+}

package/skills/wix-headless-templates/members/project/src/layouts/Layout.astro

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Wix Astro Basics</title>
+	</head>
+	<body>
+		<slot />
+	</body>
+</html>
+
+<style>
+	html,
+	body {
+		margin: 0;
+		width: 100%;
+		height: 100%;
+	}
+</style>

package/skills/wix-headless-templates/members/project/src/layouts/SiteLayout.astro

@@ -0,0 +1,42 @@
+---
+// The site chrome for every members page — THIS file (header/footer/nav) plus the @theme
+// token block in src/styles/global.css are what you brand. Keep the <slot name="seo-tags" />
+// in <head>, the global.css import, and one <MemberMenu client:only="react"> in the header
+// (it reads browser session state and must not server-render). (If another vertical is also
+// deployed, its SiteLayout won — mount MemberMenu in that header instead.)
+import MemberMenu from "../components/members/MemberMenu";
+import "../styles/global.css";
+
+interface Props {
+  title: string;
+  description?: string;
+}
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <slot name="seo-tags" />
+  </head>
+  <body>
+    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
+      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
+        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
+        <nav class="flex items-center gap-6 text-sm">
+          <MemberMenu client:only="react" />
+        </nav>
+      </div>
+    </header>
+    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
+      <slot />
+    </main>
+    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
+      © Brand Name
+    </footer>
+  </body>
+</html>

package/skills/wix-headless-templates/members/project/src/pages/account.astro

@@ -0,0 +1,9 @@
+---
+import SiteLayout from "../layouts/SiteLayout.astro";
+import AccountPage from "../components/members/AccountPage";
+---
+
+<SiteLayout title="My account">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">My account</h1>
+  <AccountPage client:only="react" />
+</SiteLayout>

package/skills/wix-headless-templates/members/project/src/pages/index.astro

@@ -0,0 +1,8 @@
+---
+import Hero from '../components/Hero.astro';
+import Layout from '../layouts/Layout.astro';
+---
+
+<Layout>
+	<Hero />
+</Layout>

package/skills/wix-headless-templates/members/project/src/pages/login.astro

@@ -0,0 +1,11 @@
+---
+import SiteLayout from "../layouts/SiteLayout.astro";
+import LoginForm from "../components/members/LoginForm";
+---
+
+<SiteLayout title="Log in">
+  <section class="mx-auto max-w-md">
+    <h1 class="mb-6 text-2xl font-semibold">Welcome</h1>
+    <LoginForm client:only="react" />
+  </section>
+</SiteLayout>

package/skills/wix-headless-templates/members/project/src/styles/global.css

@@ -0,0 +1,57 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, text-destructive, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+  --color-destructive: hsl(0 72% 51%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+  /* Buttons, chips, labels, steppers and the progress bar. Follows --radius-md unless the brand
+     wants otherwise: 9999px is the pill, 0 is square. Genuine circles (swatches, avatars, dots)
+     stay rounded-full and do not read this. */
+  --radius-control: var(--radius-md);
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}

package/skills/wix-headless-templates/members/project/src/wix/config.ts

@@ -0,0 +1,16 @@
+// Wix connection config — written by the skill's deploy step (install/deploy.mjs).
+//
+// WIX_CLIENT_ID = null  → ambient auth (a Wix-managed Astro project: `@wix/astro` authenticates
+//                         every SDK call automatically; there is no client and nothing to set).
+// WIX_CLIENT_ID = "..." → manual visitor client (any other React setup): the public OAuth client id.
+//                         It is NOT a secret — it only mints anonymous visitor tokens — so
+//                         hardcoding and committing it is fine. deploy.mjs copies it from `.env.local`
+//                         (`WIX_CLIENT_ID`, what `wix env pull` writes): the CONTENT site's app — on a
+//                         migration preview the site being migrated, while wix.config.json names
+//                         only the deploy target.
+export const WIX_CLIENT_ID: string | null = null;
+
+// Kept for projects deployed before the Members vertical moved onto the shared seam; the shipped
+// members code no longer reads it (ambient Astro uses the built-in /api/auth routes, manual mode
+// uses the shared client above). deploy.mjs still fills it so older code keeps compiling.
+export const WIX_MEMBERS_CLIENT_ID: string | null = null;

package/skills/wix-headless-templates/members/project/src/wix/media.ts

@@ -0,0 +1,106 @@
+// Wix media resolution — define once, use on EVERY image render path. Copy as-is.
+//
+// SDK media fields come back either as an already-absolute https URL, or as a
+// `wix:image://v1/<hash>/<file>#originWidth=…` identifier that a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME). The wix:image:// form must go through the SDK media module;
+// never hand-build a static.wixstatic.com URL (wrong format → 403).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import { media } from "@wix/sdk";
+
+type MediaLike =
+  | string
+  | null
+  | undefined
+  | { image?: unknown; url?: string | null; id?: string | null };
+
+/** A bare Wix media file id (`e6a89e_06cf…~mv2.png`): what REST-shaped media objects carry as `url` and `id`. */
+const BARE_FILE_ID = /^[\w-]+~mv2\.[a-z0-9]+$/i;
+
+function rawOf(value: MediaLike): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (value.image != null && typeof value.image === "object") return rawOf(value.image as MediaLike); // { image: { id, url } }
+  return (typeof value.image === "string" ? value.image : null) ?? value.url ?? value.id ?? "";
+}
+
+/** Resolve any Wix media value to a browser-loadable URL ("" when absent). */
+export function imgSrc(value: MediaLike, width = 600, height = 600): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://")) {
+    return media.getScaledToFillImageUrl(v, width, height, {});
+  }
+  // A bare file id (what REST-shaped media objects carry) or an absolute Wix media URL (bare, or
+  // already carrying a /v1/fill/ segment at some other size): re-issue it through the scaler at the
+  // requested size, so every image path lands on one shape.
+  const file = BARE_FILE_ID.test(v) ? v : v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/)?.[1];
+  if (file) return `https://static.wixstatic.com/media/${file}/v1/fill/w_${width},h_${height},al_c,q_90/${file}`;
+  return v;
+}
+
+/**
+ * Responsive candidates for `srcset`: the same image at several widths through Wix's scaler, so a
+ * card never downloads a hero-sized file. Pair with `sizes`:
+ *   <img src={imgSrc(m, 640, 640)} srcSet={imgSrcSet(m)} sizes="(min-width: 1024px) 25vw, 50vw"
+ *        width={640} height={640} loading="lazy" alt={…} />
+ * Accepts every form an image reaches you in: a raw `wix:image://` id, an ALREADY-RESOLVED Wix URL
+ * (what the DTOs carry — `imageUrl`, `gallery[]`; its `/v1/fill/w_…,h_…` segment is rewritten per
+ * width), or any other https URL (returned as the single candidate). `ratio` is height/width
+ * (1 = square). "" only when there is no image at all — still set `src` as well.
+ */
+export function imgSrcSet(value: MediaLike, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const raw = rawOf(value);
+  if (!raw) return "";
+  if (raw.startsWith("wix:image://") || BARE_FILE_ID.test(raw)) {
+    return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  }
+  // A resolved Wix URL: …/v1/fill/w_800,h_800,al_c,… — swap the size for each width.
+  const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+  if (/static\.wixstatic\.com\//.test(raw) && FILL.test(raw)) {
+    return widths.map((w) => `${raw.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return raw; // one candidate, never an empty srcset for a real image
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcSet` without `src`:
+ *   <img {...imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw")} alt={p.name} />
+ * `sizes` is the width the image renders at (a CSS length or media-query list); `ratio` is
+ * height/width. Returns an empty object when there is no image — render your placeholder then.
+ */
+export function imgAttrs(value: MediaLike, sizes: string, ratio = 1): { src: string; srcSet: string; sizes: string; loading: "lazy"; decoding: "async" } | Record<string, never> {
+  const src = imgSrc(value, 640, Math.round(640 * ratio));
+  if (!src) return {};
+  return { src, srcSet: imgSrcSet(value, undefined, ratio), sizes, loading: "lazy", decoding: "async" };
+}
+
+/**
+ * Height/width of a Wix image when the value carries its size: a raw
+ * `wix:image://…#originWidth=W&originHeight=H` id (the natural size) or a resolved `/v1/fill/w_W,h_H/`
+ * URL (the size it was scaled to). null when neither is present. Pass it as `ratio` to keep a
+ * srcset at the image's own aspect instead of the square default:
+ *   <img {...imgAttrs(item.photo, "33vw", imgRatio(item.photo) ?? 1)} alt={…} />
+ */
+export function imgRatio(value: MediaLike): number | null {
+  const v = rawOf(value);
+  if (typeof v !== "string" || !v) return null;
+  const size = v.startsWith("wix:image://")
+    ? [v.match(/[#&]originWidth=(\d+)/)?.[1], v.match(/[#&]originHeight=(\d+)/)?.[1]]
+    : (v.match(/\/v1\/fill\/w_(\d+),h_(\d+)/)?.slice(1) ?? []);
+  const w = Number(size[0]);
+  const h = Number(size[1]);
+  return w > 0 && h > 0 ? h / w : null;
+}
+
+/**
+ * The identity of a media value BEFORE scaling — de-duplicate galleries on this, never on a
+ * resolved URL (two scaled URLs of one photo differ in their size parameters).
+ */
+export function mediaKey(value: MediaLike): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  // The file id, whichever form the value takes — a raw id and a resolved URL of one photo share it.
+  if (v.startsWith("wix:image://")) return v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  return m ? m[1] : v;
+}

package/skills/wix-headless-templates/members/project/src/wix/members/auth-core.ts

@@ -0,0 +1,160 @@
+// Authentication rules — transport-agnostic, imported by EVERY transport: ./auth.ts (the SDK's
+// OAuthStrategy, or the managed-Astro built-in auth routes) and the REST twin in
+// templates/members/rest/auth.ts (the IAM authentication API over fetch). What a login/registration
+// response MEANS — the four states, when a session token is expected, which Wix error code is which
+// failure — lives HERE, once. No imports: a strip to JS emits a plain module.
+
+/** The four outcomes every credential operation resolves to; the shipped LoginForm renders each. */
+export type LoginState = "SUCCESS" | "EMAIL_VERIFICATION_REQUIRED" | "OWNER_APPROVAL_REQUIRED" | "FAILURE";
+
+export interface LoginResult {
+  state: LoginState;
+  /** Continues an EMAIL_VERIFICATION_REQUIRED flow (the transport keeps it too — verifyMemberEmail needs no argument). */
+  stateToken?: string;
+  /** A stable name for a FAILURE: invalidPassword, invalidEmail, emailAlreadyExists, resetPassword, missingCaptchaToken, invalidCaptchaToken. */
+  errorCode?: string;
+  /** Wix's message for a FAILURE — render it. */
+  error?: string;
+  /**
+   * Managed Astro only: a SUCCESS is not a session yet — the browser must navigate here (the Wix
+   * authorization step), which returns through /api/auth/callback and lands on the requested page.
+   */
+  redirectUrl?: string;
+}
+
+/** A raw login/register/verify response as either transport returns it. */
+export type RawAuth = Record<string, any>;
+
+/** A LoginResult plus the one-shot session token a SUCCESS carries (5-minute life; exchanged, never shown). */
+export interface AuthOutcome extends LoginResult {
+  sessionToken: string | null;
+}
+
+// REST spells the states differently from the SDK; both map onto LoginState.
+const REST_STATES: Record<string, LoginState> = {
+  SUCCESS: "SUCCESS",
+  REQUIRE_EMAIL_VERIFICATION: "EMAIL_VERIFICATION_REQUIRED",
+  REQUIRE_OWNER_APPROVAL: "OWNER_APPROVAL_REQUIRED",
+};
+
+/**
+ * Normalize either transport's response — SDK `{ loginState, data: { sessionToken | stateToken },
+ * error?, errorCode? }` or REST `{ state, sessionToken?, stateToken? }`. Anything else is a FAILURE.
+ */
+export function authOutcome(raw: RawAuth | null | undefined): AuthOutcome {
+  const state: LoginState = raw?.loginState ?? REST_STATES[raw?.state ?? ""] ?? "FAILURE";
+  const stateToken: string | undefined = raw?.stateToken ?? raw?.data?.stateToken;
+  return {
+    state,
+    sessionToken: raw?.data?.sessionToken ?? raw?.sessionToken ?? null,
+    ...(stateToken ? { stateToken } : {}),
+    ...(raw?.errorCode ? { errorCode: raw.errorCode } : {}),
+    ...(raw?.error ? { error: raw.error } : {}),
+  };
+}
+
+/** The outcome as callers see it — without the session token, which the transport has consumed. */
+export function toLoginResult({ sessionToken: _consumed, ...result }: AuthOutcome): LoginResult {
+  return result;
+}
+
+export function failure(error: string, errorCode?: string): LoginResult {
+  return { state: "FAILURE", error, ...(errorCode ? { errorCode } : {}) };
+}
+
+/** A SUCCESS without a session token — the exchange can't run; surfaced as a FAILURE with this text. */
+export const NO_SESSION_ERROR = "Wix did not return a member session.";
+
+// The built-in auth routes' request-level error codes (body `{ error }`), in the words a form can show.
+const AUTH_ROUTE_ERRORS: Record<string, string> = {
+  ALREADY_LOGGED_IN: "You are already signed in.",
+  AUTH_SERVICE_ERROR: "Wix could not process the sign-in right now. Try again.",
+  VERIFICATION_FAILED: "That code did not match. Check the email and try again.",
+  VERIFICATION_STATE_EXPIRED: "The verification code expired. Sign in again to get a new one.",
+  INVALID_REQUEST: "The form sent something Wix did not accept.",
+  FORBIDDEN: "This request was refused.",
+};
+
+/**
+ * A managed-Astro auth route answer → LoginResult. Success: `{ loginState: "SUCCESS", redirectUrl }`
+ * (200). Challenges: `{ loginState }` with 403 — verification and owner approval pass through; a
+ * CAPTCHA challenge (the site owner turned reCAPTCHA on) is a FAILURE the form cannot clear without
+ * a widget. Failure: `{ loginState: "FAILURE", errorCode }` (422, or 403 for resetPassword). Request
+ * errors: `{ error: CODE }` without a loginState.
+ */
+export function fromAuthRoute(status: number, body: RawAuth | null): LoginResult {
+  const loginState: string | undefined = body?.loginState;
+  switch (loginState) {
+    case "SUCCESS":
+      return body?.redirectUrl ? { state: "SUCCESS", redirectUrl: body.redirectUrl } : failure(NO_SESSION_ERROR);
+    case "EMAIL_VERIFICATION_REQUIRED":
+    case "OWNER_APPROVAL_REQUIRED":
+      return { state: loginState };
+    case "SILENT_CAPTCHA_REQUIRED":
+    case "USER_CAPTCHA_REQUIRED":
+      return failure("This site requires a CAPTCHA to sign up; the form has no CAPTCHA widget yet.", "captchaRequired");
+    case "FAILURE":
+      return failure(body?.error ?? FAILURE_TEXT[body?.errorCode ?? ""] ?? "Could not sign in.", body?.errorCode ?? "unknown");
+    default: {
+      // No route at all: the project's @wix/astro predates the built-in credential routes (2.75).
+      if (status === 404 || status === 405) return failure("This site's @wix/astro has no /api/auth credential routes; update it to 2.75 or later.", "authRoutesMissing");
+      const code: string | undefined = body?.error;
+      return failure(AUTH_ROUTE_ERRORS[code ?? ""] ?? `Sign-in request failed (${status}).`, code);
+    }
+  }
+}
+
+/** Default wording per errorCode when the route sends none (the SDK sends none either). */
+const FAILURE_TEXT: Record<string, string> = {
+  invalidCredentials: "Wrong email or password.",
+  invalidEmail: "That email is not valid here.",
+  invalidPassword: "Wrong password.",
+  emailAlreadyExists: "An account with this email already exists. Sign in instead.",
+  resetPassword: "You need to reset your password before signing in.",
+  missingCaptchaToken: "This site requires a CAPTCHA to sign up.",
+  invalidCaptchaToken: "The CAPTCHA check failed. Try again.",
+};
+
+// Wix IAM application-error codes, named as the SDK names them.
+export const AUTH_ERROR_CODES = {
+  MISSING_CAPTCHA: "-19971",
+  INVALID_CAPTCHA: "-19970",
+  EMAIL_EXISTS: "-19995",
+  INVALID_PASSWORD: "-19976",
+  RESET_PASSWORD: "-19973",
+} as const;
+
+/** A failed login's applicationError code → the SDK's errorCode name (anything unrecognized is `invalidEmail`, as the SDK does). */
+export function loginErrorCode(code: string | undefined): string {
+  switch (code) {
+    case AUTH_ERROR_CODES.MISSING_CAPTCHA:
+      return "missingCaptchaToken";
+    case AUTH_ERROR_CODES.INVALID_CAPTCHA:
+      return "invalidCaptchaToken";
+    case AUTH_ERROR_CODES.INVALID_PASSWORD:
+      return "invalidPassword";
+    case AUTH_ERROR_CODES.RESET_PASSWORD:
+      return "resetPassword";
+    default:
+      return "invalidEmail";
+  }
+}
+
+/**
+ * A failed registration's applicationError code (+ the response `details`) → the SDK's errorCode
+ * name; undefined when the SDK would name none. A validation error on the EMAIL field is `invalidEmail`.
+ */
+export function registerErrorCode(code: string | undefined, details?: RawAuth): string | undefined {
+  const violations: RawAuth[] = details?.validationError?.fieldViolations ?? [];
+  if (violations.some((v) => v?.data?.type === "EMAIL")) return "invalidEmail";
+  switch (code) {
+    case AUTH_ERROR_CODES.MISSING_CAPTCHA:
+      return "missingCaptchaToken";
+    case AUTH_ERROR_CODES.EMAIL_EXISTS:
+      return "emailAlreadyExists";
+    case AUTH_ERROR_CODES.INVALID_CAPTCHA:
+      return "invalidCaptchaToken";
+    default:
+      return undefined;
+  }
+}

package/skills/wix-headless-templates/members/project/src/wix/members/auth.ts

@@ -0,0 +1,117 @@
+// Member authentication — the transport only; what a response MEANS lives in ./auth-core (shared
+// with the REST twin in templates/members/rest/auth.ts). Two transports behind one export list,
+// switched by AMBIENT_AUTH from ./client:
+//
+//   ambient (Wix-managed Astro): the integration's built-in auth routes. Credentials go to
+//     POST /api/auth/login or /api/auth/signup as JSON; a SUCCESS answers with `redirectUrl`, the
+//     Wix authorization step that the browser MUST navigate to — it bounces straight back through
+//     /api/auth/callback, which writes the member session cookie server-side (HttpOnly) and lands
+//     on `returnTo`. Email verification continues through POST /api/auth/verify-email (the pending
+//     state is a server cookie, nothing to keep here). Logout is a POST to /api/auth/logout.
+//     docs: @wix/astro docs/custom-login.md, docs/custom-signup.md, docs/email-verification.md
+//
+//   manual (any other React setup): the SDK's OAuthStrategy in the browser — login/register/verify,
+//     then the one-shot session token is exchanged for member tokens that the client persists.
+//     docs: https://dev.wix.com/docs/go-headless/authentication/members/custom-login-page/build-a-custom-login-page-js-sdk.md
+//
+// Copy as-is; extend by adding functions, never by editing the exchange.
+import { AMBIENT_AUTH, membersAuth } from "./client";
+import {
+  NO_SESSION_ERROR,
+  authOutcome,
+  failure,
+  fromAuthRoute,
+  toLoginResult,
+  type LoginResult,
+  type LoginState,
+  type RawAuth,
+} from "./auth-core";
+
+export type { LoginResult, LoginState };
+
+export interface LoginOptions {
+  /** Same-site path to land on after a SUCCESS (ambient: the callback's destination). Default "/". */
+  returnTo?: string;
+}
+
+/** Whether register() can carry first/last name. The built-in signup route takes credentials only. */
+export const PROFILE_ON_SIGNUP = !AMBIENT_AUTH;
+
+/**
+ * Session hint without a network call: manual mode knows from its tokens; ambient mode returns
+ * null — the current-member read IS the session check there (the store handles both).
+ */
+export function loggedInHint(): boolean | null {
+  return membersAuth ? membersAuth.loggedIn() : null;
+}
+
+// ---- ambient: the built-in routes ----------------------------------------------------------------
+
+function safeReturnTo(returnTo: string | undefined): string {
+  return returnTo && returnTo.startsWith("/") && !returnTo.startsWith("//") ? returnTo : "/";
+}
+
+async function postAuthRoute(path: string, body: Record<string, string>): Promise<LoginResult> {
+  const res = await fetch(path, {
+    method: "POST",
+    headers: { Accept: "application/json", "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    credentials: "same-origin",
+  });
+  const json = (await res.json().catch(() => null)) as RawAuth | null;
+  return fromAuthRoute(res.status, json);
+}
+
+// ---- manual: the SDK strategy ----------------------------------------------------------------------
+
+// A SUCCESS carries a one-shot session token; the strategy exchanges it for member tokens
+// (getMemberTokensForDirectLogin) and setTokens persists them, so every later call runs as the member.
+async function finish(raw: RawAuth): Promise<LoginResult> {
+  const outcome = authOutcome(raw);
+  if (outcome.state === "SUCCESS") {
+    if (!outcome.sessionToken || !membersAuth) return failure(NO_SESSION_ERROR);
+    const tokens = await membersAuth.getMemberTokensForDirectLogin(outcome.sessionToken);
+    membersAuth.setTokens(tokens);
+    return { state: "SUCCESS" };
+  }
+  return toLoginResult(outcome);
+}
+
+// ---- the exports (same on both transports) ---------------------------------------------------------
+
+export async function loginMember(email: string, password: string, options: LoginOptions = {}): Promise<LoginResult> {
+  if (!membersAuth) return postAuthRoute("/api/auth/login", { email, password, returnToUrl: safeReturnTo(options.returnTo) });
+  return finish((await membersAuth.login({ email, password })) as RawAuth);
+}
+
+export async function registerMember(
+  email: string,
+  password: string,
+  profile?: { firstName?: string; lastName?: string },
+  options: LoginOptions = {},
+): Promise<LoginResult> {
+  if (!membersAuth) return postAuthRoute("/api/auth/signup", { email, password, returnToUrl: safeReturnTo(options.returnTo) });
+  return finish((await membersAuth.register({ email, password, ...(profile ? { profile } : {}) })) as RawAuth);
+}
+
+/** Continue an EMAIL_VERIFICATION_REQUIRED flow with the code from the email; the transport holds the state. */
+export async function verifyMemberEmail(verificationCode: string): Promise<LoginResult> {
+  if (!membersAuth) return postAuthRoute("/api/auth/verify-email", { verificationCode });
+  return finish((await membersAuth.processVerification({ verificationCode })) as RawAuth);
+}
+
+/** Log out through Wix (clears the session) and land on `returnTo` — navigates away. */
+export async function logoutMember(returnTo = "/"): Promise<void> {
+  const target = safeReturnTo(returnTo);
+  if (!membersAuth) {
+    // The built-in logout is a POST that answers with a redirect; a real form submit navigates.
+    const form = document.createElement("form");
+    form.method = "post";
+    form.action = `/api/auth/logout?returnToUrl=${encodeURIComponent(target)}`;
+    document.body.appendChild(form);
+    form.submit();
+    return;
+  }
+  const { logoutUrl } = await membersAuth.logout(new URL(target, window.location.origin).href);
+  window.location.assign(logoutUrl);
+}

package/skills/wix-headless-templates/members/project/src/wix/members/client.ts

@@ -0,0 +1,27 @@
+// The members auth seam — no client of its own. It reuses the shared seam in ../sdk, so the member
+// identity and the app's data identity are the same thing:
+//
+//   ambient (WIX_CLIENT_ID null — a Wix-managed Astro project): `membersAuth` is null. The raw
+//     `members` module is authenticated by `@wix/astro` in islands and on the server, and the
+//     credential flow runs through the integration's built-in routes (/api/auth/login, /signup,
+//     /verify-email, /logout, /callback — see ./auth.ts), which write the member session cookie
+//     server-side (HttpOnly). Nothing here touches cookies or tokens.
+//
+//   manual (WIX_CLIENT_ID set — a Vite SPA, another framework): `membersAuth` is the shared
+//     client's OAuthStrategy. login/register/verify run on it in the browser and the one-shot
+//     session token is exchanged for member tokens that the SAME strategy persists — so the cart,
+//     the member's own records, everything the app reads, runs as the member from then on.
+//
+// Copy as-is; never instantiate another client, never one per component.
+import type { IOAuthStrategy } from "@wix/sdk";
+import { members } from "@wix/members";
+import { wixAuth, wixModule } from "../sdk";
+
+/** The manual-mode auth strategy (the shared client's); null under ambient auth, where the routes own the session. */
+export const membersAuth: IOAuthStrategy | null = wixAuth();
+
+/** True in a Wix-managed Astro project: the built-in auth routes carry the credential flow. */
+export const AMBIENT_AUTH = membersAuth === null;
+
+/** The members module under the app's auth, either mode. */
+export const membersApi: typeof members = wixModule(members);