@wix/agent-skills 1.26.0 → 1.28.0

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

@@ -0,0 +1,133 @@
+// Member session state — a module-scope store, deliberately NOT a React context.
+// A context can't span Astro islands (each island is its own React root); a module
+// singleton is shared by every island in the page bundle, and works identically in a
+// single-root SPA. Consume it through useMember() (hooks/), or subscribe directly.
+import { fetchCurrentMember } from "./members";
+import {
+  loggedInHint,
+  loginMember,
+  logoutMember,
+  registerMember,
+  verifyMemberEmail,
+  type LoginOptions,
+  type LoginResult,
+} from "./auth";
+import type { CurrentMember } from "./types";
+
+export interface MemberState {
+  member: CurrentMember | null;
+  /** True for a logged-in member — can be true with `member` null when the Members Area app is absent. */
+  loggedIn: boolean;
+  /** True until the first session read settles — render skeletons, not the logged-out state. */
+  loading: boolean;
+  /** Last failed operation's message — render it; a new operation clears it. */
+  error: string | null;
+}
+
+const EMPTY: MemberState = {
+  member: null,
+  loggedIn: false,
+  loading: true,
+  error: null,
+};
+
+let state: MemberState = EMPTY;
+const listeners = new Set<() => void>();
+let started = false;
+
+function setState(patch: Partial<MemberState>): void {
+  state = { ...state, ...patch };
+  for (const l of listeners) l();
+}
+
+export function getMemberState(): MemberState {
+  return state;
+}
+
+/** Adopt an SSR-resolved member (Astro island props) so no client re-fetch happens. */
+export function hydrateMember(member: CurrentMember | null): void {
+  if (started) return;
+  started = true;
+  state = { member, loggedIn: member !== null, loading: false, error: null };
+}
+
+export function subscribeMember(listener: () => void): () => void {
+  listeners.add(listener);
+  // First subscriber triggers the initial session read (browser only — SSR renders `loading`).
+  if (!started && typeof window !== "undefined") {
+    started = true;
+    void refreshMember();
+  }
+  return () => listeners.delete(listener);
+}
+
+/** Re-read the session — call after anything that may have changed it. */
+export async function refreshMember(): Promise<void> {
+  setState({ loading: true, error: null });
+  const hint = loggedInHint();
+  if (hint === false) {
+    setState({ member: null, loggedIn: false, loading: false });
+    return;
+  }
+  // hint true → read the profile (null = profile data missing, still logged in).
+  // hint null (ambient) → the member read IS the session check: null = anonymous.
+  const member = await fetchCurrentMember();
+  setState({ member, loggedIn: hint ?? member !== null, loading: false });
+}
+
+async function runLogin(
+  action: () => Promise<LoginResult>,
+): Promise<LoginResult> {
+  try {
+    const result = await action();
+    // Managed Astro: the session is written by the callback the browser is about to visit; navigate
+    // and do nothing else here (the page unloads). Manual: the tokens are already in place — re-read.
+    if (result.state === "SUCCESS" && result.redirectUrl) {
+      window.location.assign(result.redirectUrl);
+      return result;
+    }
+    if (result.state === "SUCCESS") await refreshMember();
+    if (result.state === "FAILURE")
+      setState({
+        error: result.error ?? result.errorCode ?? "Could not log in.",
+      });
+    return result;
+  } catch (e) {
+    setState({ error: e instanceof Error ? e.message : String(e) });
+    throw e;
+  }
+}
+
+/**
+ * Submit the branded in-app sign-in form. `returnTo` is where a SUCCESS lands (managed Astro: the
+ * callback's destination; the caller navigates itself otherwise).
+ */
+export function login(email: string, password: string, options?: LoginOptions): Promise<LoginResult> {
+  return runLogin(() => loginMember(email, password, options));
+}
+
+/** Submit the branded in-app sign-up form (names only where PROFILE_ON_SIGNUP is true). */
+export function register(
+  email: string,
+  password: string,
+  profile?: { firstName?: string; lastName?: string },
+  options?: LoginOptions,
+): Promise<LoginResult> {
+  return runLogin(() => registerMember(email, password, profile, options));
+}
+
+/** Finish an email-verification branch from the same in-app form. */
+export function verifyEmail(code: string): Promise<LoginResult> {
+  return runLogin(() => verifyMemberEmail(code));
+}
+
+/** Log out (navigates away); local state resets for the instant before the redirect lands. */
+export async function logout(returnTo?: string): Promise<void> {
+  setState({ member: null, loggedIn: false });
+  try {
+    await logoutMember(returnTo);
+  } catch (e) {
+    setState({ error: e instanceof Error ? e.message : String(e) });
+    throw e;
+  }
+}

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

@@ -0,0 +1,43 @@
+// Member rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./members.ts (the
+// SDK, managed Astro and React) and the REST twin in templates/members/rest/members.ts (fetch, a
+// static site or a port to another language). The one rule about who a member "is" on screen lives
+// HERE, once. A raw member comes from the SDK (`_id`, `_createdDate`) or from REST (`id`,
+// `createdDate`); the mapper accepts both. Imports are type-only so a strip to JS emits no imports.
+import type { CurrentMember } from "./types";
+
+/** A raw Members V1 member as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+// Requested on the current-member read. FULL → loginEmail, status, the contact's names, the profile
+// (nickname, photo), and the dates; the default PUBLIC fieldset has no login email and no names.
+export const MEMBER_FIELDSETS = ["FULL"] as const;
+
+/** The member's id on either transport; "" when the raw object isn't a member. */
+export const memberId = (raw: Raw | undefined): string => raw?._id ?? raw?.id ?? "";
+
+/**
+ * Raw member → CurrentMember. displayName is the first non-empty of nickname, "first last", the
+ * login email's local part, "Member". photoUrl is "" without a profile photo. memberSince is the
+ * creation date as "YYYY-MM-DD" ("" when unknown).
+ */
+export function toCurrentMember(raw: Raw, imgSrc: ImgSrc): CurrentMember {
+  const nickname: string = raw.profile?.nickname ?? "";
+  const firstName: string = raw.contact?.firstName ?? "";
+  const lastName: string = raw.contact?.lastName ?? "";
+  const loginEmail: string = raw.loginEmail ?? "";
+  const fullName = [firstName, lastName].filter(Boolean).join(" ");
+  const created = raw._createdDate ?? raw.createdDate;
+  return {
+    id: memberId(raw),
+    loginEmail,
+    displayName: nickname || fullName || loginEmail.split("@")[0] || "Member",
+    firstName,
+    lastName,
+    nickname,
+    photoUrl: imgSrc(raw.profile?.photo, 200, 200),
+    contactId: raw.contactId ?? "",
+    memberSince: created ? new Date(created).toISOString().slice(0, 10) : "",
+  };
+}

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

@@ -0,0 +1,29 @@
+// Current-member read (Wix Members) over the SDK — the only file that touches raw member entities
+// on this transport. The DTO mapper lives in ./members-core (shared with the REST twin in
+// templates/members/rest/members.ts); this file is the transport only. Identity vs. profile are
+// different layers: "is this caller logged in?" needs no app install, but getCurrentMember returns
+// profile DATA only once the Wix Members Area app is installed (the seed installs it). Copy as-is;
+// extend by adding functions, not by editing these.
+// docs: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members/get-my-member.md
+import { membersApi } from "./client";
+import { imgSrc } from "../media";
+import { MEMBER_FIELDSETS, memberId, toCurrentMember, type Raw } from "./members-core";
+import type { CurrentMember } from "./types";
+
+/**
+ * The current member, or null for an anonymous visitor — and null for a LOGGED-IN member
+ * when the Members Area app isn't installed (setup, not a code bug; the seed installs it).
+ * Never throws: anonymous is a normal state for the client-side custom-login gate.
+ * The SDK export is getCurrentMember — the REST name "Get My Member" does not exist on
+ * the module; getMyMember(...) throws `is not a function`, and only once a real member
+ * loads the page.
+ */
+export async function fetchCurrentMember(): Promise<CurrentMember | null> {
+  try {
+    const res = await membersApi.getCurrentMember({ fieldsets: [...MEMBER_FIELDSETS] as any });
+    const raw = res.member as Raw | undefined;
+    return raw && memberId(raw) ? toCurrentMember(raw, imgSrc) : null;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,21 @@
+// Members DTOs — the serializable shapes every hook, component, and page consumes.
+// Plain JSON: safe as Astro island props or across server/client boundaries. The photo is a
+// resolved https URL.
+
+/** The logged-in member as the header/account surfaces need it. */
+export interface CurrentMember {
+  id: string;
+  /** Email the member logs in with ("" when the fieldset hides it). */
+  loginEmail: string;
+  /** Best display name: nickname → first+last → the login email's local part. */
+  displayName: string;
+  firstName: string;
+  lastName: string;
+  nickname: string;
+  /** Resolved https URL ("" when the member has no photo). */
+  photoUrl: string;
+  /** Contact-list id — the key for member-owned CMS/content lookups. */
+  contactId: string;
+  /** "YYYY-MM-DD" the membership was created ("" when unknown). */
+  memberSince: string;
+}

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

@@ -0,0 +1,24 @@
+// Money formatting for API amounts that carry no formatted string. Copy as-is.
+//
+// Catalog prices come with a ready `formattedAmount` — use that directly. But eCom Cart V2
+// amounts are ConvertedMoney `{ amount, convertedAmount }` with NO formatted string, and the
+// currency lives on the cart, not on the money object. Never hardcode "$" or assume USD.
+export interface ConvertedMoneyLike {
+  amount?: string | null;
+  convertedAmount?: string | null;
+}
+
+/** Format a ConvertedMoney in the given currency, using the visitor's locale. */
+export function formatMoney(
+  money: ConvertedMoneyLike | null | undefined,
+  currencyCode: string | null | undefined,
+): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}

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

@@ -0,0 +1,89 @@
+// The one auth seam for every Wix SDK call in this app. Copy as-is; do not rewrite.
+//
+// Two modes, switched by WIX_CLIENT_ID in ./config:
+//   null (ambient)  — a Wix-managed Astro project: `@wix/astro` authenticates raw SDK module
+//                     calls automatically, server-side AND in client islands. `wixModule()`
+//                     returns the module untouched.
+//   string (manual) — any other React setup (Vite SPA, non-Astro): one shared client is built
+//                     with OAuthStrategy, and `wixModule()` returns the module bound to it.
+//                     The strategy self-manages visitor tokens on every call (mints on first
+//                     use, renews on expiry) and persists them through the storage below.
+//
+// The visitor token IS the identity of the current cart / member session, so in manual mode
+// tokens persist to localStorage — never re-minted per load (a fresh anonymous mint is a NEW
+// visitor and silently empties the cart).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md
+// docs: https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md
+import { createClient, OAuthStrategy, EMPTY_TOKENS } from "@wix/sdk";
+import { fetchWithAuth as ambientFetch } from "@wix/sdk/context";
+import type { IOAuthStrategy, TokenStorage, Tokens } from "@wix/sdk";
+import { WIX_CLIENT_ID } from "./config";
+
+const STORAGE_KEY = `wix-session-${WIX_CLIENT_ID ?? "ambient"}`;
+
+function browserTokenStorage(): TokenStorage {
+  return {
+    getTokens(): Tokens {
+      if (typeof window !== "undefined") {
+        try {
+          const raw = window.localStorage.getItem(STORAGE_KEY);
+          if (raw) return JSON.parse(raw) as Tokens;
+        } catch {
+          /* disabled/corrupt storage — fall through to empty */
+        }
+      }
+      return EMPTY_TOKENS;
+    },
+    setTokens(tokens: Tokens): void {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+      } catch {
+        /* storage full/disabled — the session just won't survive a reload */
+      }
+    },
+  };
+}
+
+const client = WIX_CLIENT_ID
+  ? createClient({
+      auth: OAuthStrategy({
+        clientId: WIX_CLIENT_ID,
+        tokenStorage: browserTokenStorage(),
+      }),
+    })
+  : null;
+
+/**
+ * Bind an SDK module to this app's auth. Usage (identical in both modes):
+ *   import { productsV3 } from "@wix/stores";
+ *   const products = wixModule(productsV3);
+ *   await products.queryProducts(...)
+ */
+export function wixModule<T>(module: T): T {
+  // The cast bridges the SDK's internal Descriptors constraint; the in/out type is identical.
+  return client
+    ? (client.use(module as unknown as Record<string, unknown>) as unknown as T)
+    : module;
+}
+
+/**
+ * An authenticated fetch of a Wix REST endpoint under the SAME auth as the SDK modules (ambient
+ * on managed Astro, the shared client elsewhere) — for the few APIs whose generated SDK module is
+ * too heavy to bundle (the Forms schema module alone is 15 MB: server-side it pushes a Wix
+ * deploy past its size limit, client-side every visitor downloads it). Same visitor identity,
+ * same token, no second mint. `path` is the wixapis.com path; returns the raw Response.
+ */
+export function wixFetch(path: string, init?: RequestInit): Promise<Response> {
+  const url = path.startsWith("http") ? path : `https://www.wixapis.com${path}`;
+  return client ? client.fetchWithAuth(url, init) : ambientFetch(url, init);
+}
+
+/**
+ * The shared data client's manual-mode auth strategy, or null under ambient auth. The
+ * Members vertical deliberately owns a separate explicit client for its custom in-app login;
+ * app code reads that session through the members hooks instead.
+ */
+export function wixAuth(): IOAuthStrategy | null {
+  return client ? client.auth : null;
+}

package/skills/wix-headless-templates/members/project/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/skills/wix-headless-templates/members/rest/auth.ts

@@ -0,0 +1,224 @@
+// Member authentication over REST — the twin of app/wix/members/auth.ts. Same exports, same
+// LoginResult; the state and error-code rules come from auth-core (the SAME file the SDK transport
+// uses). The custom credential flow, as the docs order it: login/register with the VISITOR token →
+// a one-shot sessionToken (5-minute life) → a redirect session that authorizes it (PKCE,
+// web_message) → an authorization code → POST /oauth2/token grantType authorization_code → MEMBER
+// tokens, adopted by ./client.js so every later call (the current-member read, a member's own
+// records) runs as the member and the refresh keeps the member. All from a page with the public
+// client id; nothing elevated. Porting: keep the paths and bodies; the exchange is three calls.
+// docs: https://dev.wix.com/docs/go-headless/authentication/members/custom-login-page/build-a-custom-login-page-rest.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { WIX_CLIENT_ID } from "./config.js";
+import { WixApiError, clearTokens, loadTokens, mintTokens, setTokens, wixRequest, type Tokens } from "./client.js";
+import {
+  NO_SESSION_ERROR,
+  authOutcome,
+  failure,
+  loginErrorCode,
+  registerErrorCode,
+  toLoginResult,
+  type LoginResult,
+  type LoginState,
+  type RawAuth,
+} from "./auth-core.js";
+
+export type { LoginResult, LoginState };
+
+/** Same shape as the SDK transport's; on REST a SUCCESS is a session at once, so `returnTo` is the caller's to navigate. */
+export interface LoginOptions {
+  returnTo?: string;
+}
+
+/** register() carries first/last name on this transport. */
+export const PROFILE_ON_SIGNUP = true;
+
+const REDIRECT_SESSION = "/headless/v1/redirect-session";
+/** The stateToken of a login/registration that stopped at email verification — verifyMemberEmail continues it. */
+let pendingStateToken: string | null = null;
+
+/** True when the persisted token set is a member's (no network) — the store skips the profile read when false. */
+export function loggedInHint(): boolean {
+  return loadTokens()?.role === "member";
+}
+
+// A SUCCESS carries the one-shot session token: exchange it for member tokens and adopt them. Other
+// states pass through; a verification state keeps its stateToken for verifyMemberEmail.
+async function finish(raw: RawAuth): Promise<LoginResult> {
+  const outcome = authOutcome(raw);
+  if (outcome.state === "SUCCESS") {
+    pendingStateToken = null;
+    if (!outcome.sessionToken) return failure(NO_SESSION_ERROR);
+    setTokens(await memberTokensForSession(outcome.sessionToken));
+    return { state: "SUCCESS" };
+  }
+  if (outcome.stateToken) pendingStateToken = outcome.stateToken;
+  return toLoginResult(outcome);
+}
+
+const message = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+/**
+ * Sign in with email + password. A wrong password or unknown email is a FAILURE result (errorCode
+ * invalidPassword / invalidEmail, Wix's message in `error`), never a throw.
+ * POST /_api/iam/authentication/v2/login  { loginId: { email }, password }  → { state, sessionToken?, stateToken? }
+ */
+export async function loginMember(email: string, password: string, _options: LoginOptions = {}): Promise<LoginResult> {
+  let raw: RawAuth;
+  try {
+    raw = await wixRequest<RawAuth>("/_api/iam/authentication/v2/login", { body: { loginId: { email }, password } });
+  } catch (e) {
+    return failure(message(e), e instanceof WixApiError ? loginErrorCode(e.code) : undefined);
+  }
+  return finish(raw);
+}
+
+/**
+ * Sign up with email + password (+ first/last name). An email already registered is a FAILURE with
+ * errorCode emailAlreadyExists. Whether the result is SUCCESS, EMAIL_VERIFICATION_REQUIRED, or
+ * OWNER_APPROVAL_REQUIRED is the site's signup policy (dashboard), not the caller's.
+ * POST /_api/iam/authentication/v2/register  { loginId: { email }, password, profile?: { firstName, lastName } }
+ */
+export async function registerMember(
+  email: string,
+  password: string,
+  profile?: { firstName?: string; lastName?: string },
+  _options: LoginOptions = {},
+): Promise<LoginResult> {
+  let raw: RawAuth;
+  try {
+    raw = await wixRequest<RawAuth>("/_api/iam/authentication/v2/register", {
+      body: { loginId: { email }, password, ...(profile ? { profile } : {}) },
+    });
+  } catch (e) {
+    return failure(message(e), e instanceof WixApiError ? registerErrorCode(e.code, e.details) : undefined);
+  }
+  return finish(raw);
+}
+
+/**
+ * Continue an EMAIL_VERIFICATION_REQUIRED flow with the code from the email; the state token of the
+ * last login/registration is kept here. A FAILURE when nothing is waiting or the code is wrong.
+ * POST /_api/iam/verification/v1/auth/verify  { code, stateToken }  → { state, sessionToken?, stateToken? }
+ */
+export async function verifyMemberEmail(verificationCode: string): Promise<LoginResult> {
+  if (!pendingStateToken) return failure("No sign-in is waiting for a verification code.");
+  let raw: RawAuth;
+  try {
+    raw = await wixRequest<RawAuth>("/_api/iam/verification/v1/auth/verify", { body: { code: verificationCode, stateToken: pendingStateToken } });
+  } catch (e) {
+    return failure(message(e));
+  }
+  return finish(raw);
+}
+
+/**
+ * The Wix logout URL for the current member — navigating the document there ends the Wix session
+ * and lands on `returnTo` (an absolute URL). Called with the MEMBER token.
+ * POST /headless/v1/redirect-session  { logout: { clientId }, callbacks: { postFlowUrl } }  → { redirectSession: { fullUrl } }
+ */
+export async function logoutUrl(returnTo: string): Promise<string> {
+  const res = await wixRequest<RawAuth>(REDIRECT_SESSION, { body: { logout: { clientId: WIX_CLIENT_ID }, callbacks: { postFlowUrl: returnTo } } });
+  const url = res?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Logout couldn't start: no redirect URL returned.");
+  return url;
+}
+
+/** Log out: drop the member tokens (the next call is a fresh visitor) and navigate to Wix's logout, which returns to `returnTo`. */
+export async function logoutMember(returnTo = "/"): Promise<void> {
+  const target = typeof window !== "undefined" ? new URL(returnTo, window.location.origin).href : returnTo;
+  const url = await logoutUrl(target);
+  clearTokens();
+  if (typeof window !== "undefined") window.location.assign(url);
+}
+
+/**
+ * sessionToken → member tokens. Three calls, as the docs order them:
+ *  1. POST /headless/v1/redirect-session
+ *       { auth: { authRequest: { clientId, codeChallenge, codeChallengeMethod: "S256", responseMode: "web_message",
+ *                                responseType: "code", scope: "offline_access", state, sessionToken }, prompt: "none" } }
+ *       → { redirectSession: { fullUrl } }   (with the visitor token)
+ *  2. fullUrl is a page whose script posts { code, state, error } to its parent — a hidden iframe in a
+ *     browser (its origin must be one of the OAuth app's allowed domains, or the message is dropped
+ *     and this times out); without a DOM (a server-side port, a Node check) the same page is fetched
+ *     and read.
+ *  3. POST /oauth2/token { clientId, grantType: "authorization_code", code, codeVerifier }
+ *       → member access + refresh tokens (role "member"); the code is single-use.
+ */
+export async function memberTokensForSession(sessionToken: string): Promise<Tokens> {
+  const { verifier, challenge } = await pkce();
+  const state = randomString();
+  const res = await wixRequest<RawAuth>(REDIRECT_SESSION, {
+    body: {
+      auth: {
+        authRequest: {
+          clientId: WIX_CLIENT_ID,
+          codeChallenge: challenge,
+          codeChallengeMethod: "S256",
+          responseMode: "web_message",
+          responseType: "code",
+          scope: "offline_access",
+          state,
+          sessionToken,
+        },
+        prompt: "none",
+      },
+    },
+  });
+  const url: string | undefined = res?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Login couldn't finish: no authorization URL returned.");
+  const code = await authorizationCode(url, state);
+  return mintTokens({ grantType: "authorization_code", code, codeVerifier: verifier }, "member");
+}
+
+// The authorize page posts { code, state, error }. Browser: a hidden iframe and a message listener
+// keyed on our state (the SDK's own mechanism). No DOM: fetch the page and read the same three values.
+async function authorizationCode(url: string, state: string): Promise<string> {
+  if (typeof document === "undefined") {
+    const html = await (await fetch(url)).text();
+    const field = (name: string) => html.match(new RegExp(`'${name}':\\s*'([^']*)'`))?.[1];
+    const error = field("error");
+    if (error) throw new Error(`Login was refused: ${error}`);
+    const code = field("code");
+    if (!code || field("state") !== state) throw new Error("Login couldn't finish: no authorization code.");
+    return code;
+  }
+  return new Promise<string>((resolve, reject) => {
+    const frame = document.createElement("iframe");
+    frame.style.display = "none";
+    const done = () => {
+      window.removeEventListener("message", onMessage);
+      clearTimeout(timer);
+      frame.remove();
+    };
+    const onMessage = (e: MessageEvent) => {
+      const data = e.data as { code?: string; state?: string; error?: string } | null;
+      if (!data || data.state !== state) return; // a message not meant for us
+      done();
+      if (data.error) reject(new Error(`Login was refused: ${data.error}`));
+      else if (data.code) resolve(data.code);
+      else reject(new Error("Login couldn't finish: no authorization code."));
+    };
+    const timer = setTimeout(() => {
+      done();
+      reject(new Error("Login timed out. Is this page's origin on the OAuth app's allowed domains?"));
+    }, 120_000);
+    window.addEventListener("message", onMessage);
+    frame.src = url;
+    document.body.appendChild(frame);
+  });
+}
+
+// PKCE: a 43-char base64url verifier, its SHA-256 as the S256 challenge. Web Crypto (browser + Node).
+function base64url(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomString(): string {
+  return base64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+async function pkce(): Promise<{ verifier: string; challenge: string }> {
+  const verifier = randomString();
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+}

package/skills/wix-headless-templates/members/rest/members.ts

@@ -0,0 +1,26 @@
+// Current-member read over REST — the twin of app/wix/members/members.ts. Same export, same DTO;
+// the mapper comes from members-core (the SAME file the SDK transport uses, deployed flat next to
+// this one by deploy.mjs --stack static), so this file is only the transport: one GET. It runs with
+// whatever token ./client.js holds — a member's after a rest/auth.ts login → the profile; a
+// visitor's → 403 → null. Porting: keep the path and the fieldsets, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members/get-my-member.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { MEMBER_FIELDSETS, memberId, toCurrentMember, type Raw } from "./members-core.js";
+import type { CurrentMember } from "./types.js";
+
+/**
+ * The current member, or null: for a visitor (the call is refused — "Missing site member id"), for
+ * a logged-in member whose site lacks the Members Area app (no profile), and on any failure —
+ * anonymous is a normal state, never an error.
+ * GET /members/v1/members/my?fieldsets=FULL  → { member: { id, loginEmail, contactId, contact: { firstName, lastName }, profile: { nickname, photo? }, createdDate, … } }
+ */
+export async function fetchCurrentMember(): Promise<CurrentMember | null> {
+  try {
+    const res = await wixRequest<Raw>("/members/v1/members/my", { method: "GET", query: { fieldsets: MEMBER_FIELDSETS } });
+    const raw: Raw | undefined = res?.member;
+    return raw && memberId(raw) ? toCurrentMember(raw, imgSrc) : null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-templates/members/seed/SEED.md

@@ -0,0 +1,39 @@
+# Members — seeding
+
+**Members self-register — there is no member content to seed.** The Wix login page registers
+or logs in members at runtime; creating members at build time is intentionally out of scope
+(a headless run must never stall on an interactive login, and Create Member needs an
+elevated credential).
+
+What `seed-members.mjs` does is the one build-time setup the vertical needs: **install the
+Wix Members Area app** — the *profile* layer. Identity (log in / log out / "logged-in vs
+not" gating) needs no install; profile data does: without the app, `getCurrentMember()`
+returns nothing for a logged-in member and the account page can't render who they are.
+
+```bash
+# from the project root (where wix.config.json lives) — the plan file is optional:
+node <SKILL_ROOT>/templates/members/seed/seed-members.mjs
+```
+
+```json
+{ "installMembersArea": true }
+```
+
+- `installMembersArea` — default `true`; set `false` only when the run needs pure
+  "logged-in vs not" gating and will never display member data.
+- Re-running is safe: an already-installed app is recorded in the result JSON
+  (`membersAreaInstall.note`), never thrown.
+
+**Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
+seems needed.
+
+## Escape hatch — individual functions
+`setupMembers` composes the exported steps — `installMembersAreaApp`, plus `makeCtx()` —
+import them for a partial re-run.
+
+## Reference
+The appDefId is the Members Area app's App Market id, hardcoded in the script; the
+identity/profile split is described beside it. Signup security (email verification, owner
+approval, reCAPTCHA) is dashboard-governed — never seeded. If a run's prompt explicitly needs
+a pre-created member (rare), the admin Create Member shape is in the live Wix API reference —
+read it via the `wix-docs` skill; don't guess it here.

package/skills/wix-headless-templates/members/seed/read-site.mjs

@@ -0,0 +1,15 @@
+// Whether the site has a members area, and how many members.
+//   node <SKILL_ROOT>/templates/members/seed/read-site.mjs [--site <siteId>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const MEMBERS_AREA_APP_ID = "14cc59bc-f0b7-15b8-e1c7-89ce41d0e0c9";
+const D = "https://dev.wix.com/docs/api-reference/crm/members-contacts/members/members";
+
+await runReader({
+  vertical: "members",
+  appId: MEMBERS_AREA_APP_ID,
+  async read(api) {
+    const r = await api.call({ method: "GET", path: "/members/v1/members?fieldsets=PUBLIC&paging.limit=1", docs: `${D}/list-members` });
+    return { memberCount: r.metadata?.total ?? r.pagingMetadata?.total ?? null };
+  },
+});