@wix/agent-skills 1.17.0 → 1.18.1

package/skills/wix-headless-fast/references/members/app/components/members/LoginForm.tsx

@@ -0,0 +1,155 @@
+// Shipped custom login form. The member stays on this site: credential calls exchange
+// directly into member tokens; only logout leaves the app.
+import { FormEvent, useState } from "react";
+import { useMember } from "../../hooks/members/useMember";
+
+export interface LoginFormProps {
+  onSuccess?: () => void;
+}
+
+export default function LoginForm({ onSuccess }: LoginFormProps) {
+  const { login, register, verifyEmail, error } = useMember();
+  const [mode, setMode] = useState<"login" | "register">("login");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [firstName, setFirstName] = useState("");
+  const [lastName, setLastName] = useState("");
+  const [code, setCode] = useState("");
+  const [verification, setVerification] = useState(false);
+  const [pending, setPending] = useState(false);
+  const [busy, setBusy] = useState(false);
+
+  function done() {
+    if (onSuccess) return onSuccess();
+    const returnTo = new URLSearchParams(window.location.search).get(
+      "returnTo",
+    );
+    window.location.assign(returnTo?.startsWith("/") ? returnTo : "/account");
+  }
+
+  async function submit(event: FormEvent) {
+    event.preventDefault();
+    setBusy(true);
+    try {
+      const result =
+        mode === "login"
+          ? await login(email, password)
+          : await register(email, password, { firstName, lastName });
+      if (result.state === "SUCCESS") done();
+      if (result.state === "EMAIL_VERIFICATION_REQUIRED") setVerification(true);
+      if (result.state === "OWNER_APPROVAL_REQUIRED") setPending(true);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function submitCode(event: FormEvent) {
+    event.preventDefault();
+    setBusy(true);
+    try {
+      const result = await verifyEmail(code);
+      if (result.state === "SUCCESS") done();
+      if (result.state === "OWNER_APPROVAL_REQUIRED") setPending(true);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  if (pending)
+    return (
+      <p className="rounded-lg border border-border p-4 text-sm">
+        Your account is awaiting approval.
+      </p>
+    );
+  if (verification) {
+    return (
+      <form onSubmit={submitCode} className="space-y-4">
+        <label className="block text-sm">
+          Verification code
+          <input
+            required
+            value={code}
+            onChange={(event) => setCode(event.target.value)}
+            className="mt-1 w-full rounded border border-border bg-background p-2"
+          />
+        </label>
+        {error && <p className="text-sm text-red-600">{error}</p>}
+        <button
+          disabled={busy}
+          className="rounded bg-primary px-4 py-2 text-primary-foreground"
+        >
+          {busy ? "Verifying…" : "Verify"}
+        </button>
+      </form>
+    );
+  }
+  return (
+    <form onSubmit={submit} className="space-y-4">
+      <div className="flex gap-2">
+        <button
+          type="button"
+          onClick={() => setMode("login")}
+          className="text-sm underline"
+        >
+          Sign in
+        </button>
+        <button
+          type="button"
+          onClick={() => setMode("register")}
+          className="text-sm underline"
+        >
+          Sign up
+        </button>
+      </div>
+      {mode === "register" && (
+        <div className="grid gap-3 sm:grid-cols-2">
+          <label className="text-sm">
+            First name
+            <input
+              value={firstName}
+              onChange={(event) => setFirstName(event.target.value)}
+              className="mt-1 w-full rounded border border-border bg-background p-2"
+            />
+          </label>
+          <label className="text-sm">
+            Last name
+            <input
+              value={lastName}
+              onChange={(event) => setLastName(event.target.value)}
+              className="mt-1 w-full rounded border border-border bg-background p-2"
+            />
+          </label>
+        </div>
+      )}
+      <label className="block text-sm">
+        Email
+        <input
+          required
+          type="email"
+          autoComplete="email"
+          value={email}
+          onChange={(event) => setEmail(event.target.value)}
+          className="mt-1 w-full rounded border border-border bg-background p-2"
+        />
+      </label>
+      <label className="block text-sm">
+        Password
+        <input
+          required
+          type="password"
+          autoComplete={mode === "login" ? "current-password" : "new-password"}
+          value={password}
+          onChange={(event) => setPassword(event.target.value)}
+          className="mt-1 w-full rounded border border-border bg-background p-2"
+        />
+      </label>
+      {error && <p className="text-sm text-red-600">{error}</p>}
+      <button
+        disabled={busy}
+        className="rounded bg-primary px-4 py-2 text-primary-foreground"
+      >
+        {busy ? "Working…" : mode === "login" ? "Sign in" : "Create account"}
+      </button>
+    </form>
+  );
+}

package/skills/wix-headless-fast/references/members/app/components/members/MemberMenu.tsx

@@ -0,0 +1,78 @@
+// REFERENCE header account control on the @theme tokens: "Log in" for a visitor; account
+// link + log-out for a member. Correct and complete; per the skill's model you design your
+// own on useMember. Mount client:only="react" — it reads browser session state.
+import type { ComponentType, ReactNode } from "react";
+import { useMember } from "../../hooks/members/useMember";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+export interface MemberMenuProps {
+  accountHref?: string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+export default function MemberMenu({
+  accountHref = "/account",
+  LinkComponent = PlainLink,
+}: MemberMenuProps) {
+  const { member, loggedIn, loading, logout } = useMember();
+
+  if (loading) {
+    return (
+      <span
+        className="inline-block h-8 w-16 animate-pulse rounded-full bg-secondary"
+        aria-hidden="true"
+      />
+    );
+  }
+
+  if (!loggedIn) {
+    return (
+      <a
+        href="/login"
+        className="rounded-full bg-primary px-4 py-1.5 text-sm font-medium text-primary-foreground transition-opacity hover:opacity-90"
+      >
+        Log in
+      </a>
+    );
+  }
+
+  return (
+    <span className="flex items-center gap-3">
+      <LinkComponent
+        href={accountHref}
+        className="flex items-center gap-2 text-sm font-medium text-foreground no-underline transition-colors hover:text-muted-foreground"
+      >
+        {member?.photoUrl ? (
+          <img
+            src={member.photoUrl}
+            alt=""
+            className="h-7 w-7 rounded-full object-cover"
+          />
+        ) : (
+          <span className="flex h-7 w-7 items-center justify-center rounded-full bg-secondary text-xs font-semibold">
+            {(member?.displayName ?? "M").slice(0, 1).toUpperCase()}
+          </span>
+        )}
+        {member?.displayName ?? "My account"}
+      </LinkComponent>
+      <button
+        type="button"
+        onClick={() => void logout()}
+        className="text-sm text-muted-foreground transition-colors hover:text-foreground"
+      >
+        Log out
+      </button>
+    </span>
+  );
+}

package/skills/wix-headless-fast/references/members/app/components/members/RequireAuth.tsx

@@ -0,0 +1,47 @@
+// REFERENCE gate for member-only surfaces on the REACT stack — on Astro, gate server-side
+// in frontmatter instead (pages/account.astro shows the shape); a client-side check there
+// flashes gated UI. Renders children only for a logged-in member; a visitor gets a login
+// prompt in place (routing-free — no router or redirect assumptions).
+import type { ReactNode } from "react";
+import { useMember } from "../../hooks/members/useMember";
+
+export interface RequireAuthProps {
+  children: ReactNode;
+  /** Rendered for an anonymous visitor instead of the default login prompt. */
+  fallback?: ReactNode;
+}
+
+export default function RequireAuth({ children, fallback }: RequireAuthProps) {
+  const { loggedIn, loading } = useMember();
+
+  // Wait for the initial session read — deciding early bounces a logged-in member on first paint.
+  if (loading) {
+    return (
+      <div className="py-16 text-center text-muted-foreground" aria-busy="true">
+        Loading…
+      </div>
+    );
+  }
+
+  if (!loggedIn) {
+    return (
+      <>
+        {fallback ?? (
+          <div className="mx-auto max-w-md rounded-lg border border-border p-8 text-center">
+            <p className="text-sm text-muted-foreground">
+              This page is for members.
+            </p>
+            <a
+              href={`/login?returnTo=${encodeURIComponent(window.location.pathname)}`}
+              className="mt-4 rounded-full bg-primary px-5 py-2 text-sm font-medium text-primary-foreground transition-opacity hover:opacity-90"
+            >
+              Log in / Sign up
+            </a>
+          </div>
+        )}
+      </>
+    );
+  }
+
+  return <>{children}</>;
+}

package/skills/wix-headless-fast/references/members/app/hooks/members/useMember.ts

@@ -0,0 +1,66 @@
+// 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 { 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. */
+  login: (email: string, password: string) => Promise<LoginResult>;
+  register: (
+    email: string,
+    password: string,
+    profile?: { firstName?: string; lastName?: string },
+  ) => 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-fast/references/members/app/wix/members/auth.ts

@@ -0,0 +1,88 @@
+// Custom, in-app member authentication. Credentials are submitted from the branded
+// LoginForm; there is no Wix-hosted login-page redirect or callback route.
+import { membersAuth } from "./client";
+
+export type LoginState =
+  | "SUCCESS"
+  | "EMAIL_VERIFICATION_REQUIRED"
+  | "OWNER_APPROVAL_REQUIRED"
+  | "FAILURE";
+
+export interface LoginResult {
+  state: LoginState;
+  stateToken?: string;
+  errorCode?: string;
+  error?: string;
+}
+
+type AuthResponse = {
+  loginState?: LoginState;
+  data?: { sessionToken?: string };
+  stateToken?: string;
+  errorCode?: string;
+  error?: string;
+};
+
+export function loggedInHint(): boolean {
+  return membersAuth.loggedIn();
+}
+
+async function finish(response: AuthResponse): Promise<LoginResult> {
+  const state = response.loginState ?? "FAILURE";
+  if (state === "SUCCESS") {
+    const sessionToken = response.data?.sessionToken;
+    if (!sessionToken)
+      return {
+        state: "FAILURE",
+        error: "Wix did not return a member session.",
+      };
+    const tokens =
+      await membersAuth.getMemberTokensForDirectLogin(sessionToken);
+    membersAuth.setTokens(tokens);
+    return { state };
+  }
+  return {
+    state,
+    ...(response.stateToken ? { stateToken: response.stateToken } : {}),
+    ...(response.errorCode ? { errorCode: response.errorCode } : {}),
+    ...(response.error ? { error: response.error } : {}),
+  };
+}
+
+export async function loginMember(
+  email: string,
+  password: string,
+): Promise<LoginResult> {
+  return finish((await membersAuth.login({ email, password })) as AuthResponse);
+}
+
+export async function registerMember(
+  email: string,
+  password: string,
+  profile?: { firstName?: string; lastName?: string },
+): Promise<LoginResult> {
+  return finish(
+    (await membersAuth.register({
+      email,
+      password,
+      ...(profile ? { profile } : {}),
+    })) as AuthResponse,
+  );
+}
+
+export async function verifyMemberEmail(
+  verificationCode: string,
+): Promise<LoginResult> {
+  return finish(
+    (await membersAuth.processVerification({
+      verificationCode,
+    })) as AuthResponse,
+  );
+}
+
+export async function logoutMember(returnTo = "/"): Promise<void> {
+  const { logoutUrl } = await membersAuth.logout(
+    new URL(returnTo, window.location.origin).href,
+  );
+  window.location.assign(logoutUrl);
+}

package/skills/wix-headless-fast/references/members/app/wix/members/client.ts

@@ -0,0 +1,53 @@
+// Explicit custom-login client for the Members vertical. Unlike the shared SDK seam,
+// this client is used in a browser island even on managed Astro: direct credential login
+// cannot use the Wix-hosted /api/auth redirect flow.
+import { createClient, EMPTY_TOKENS, OAuthStrategy } from "@wix/sdk";
+import type { TokenStorage, Tokens } from "@wix/sdk";
+import { members } from "@wix/members";
+import { WIX_MEMBERS_CLIENT_ID } from "../../config";
+
+// `@wix/astro` uses this cookie as the session source for both browser islands
+// and the next server render. Direct login must write the exact same contract,
+// so the member identity becomes the managed Astro identity too.
+const SESSION_COOKIE_NAME = "wixSession";
+
+const tokenStorage: TokenStorage = {
+  getTokens(): Tokens {
+    try {
+      const raw = document.cookie
+        .split("; ")
+        .find((cookie) => cookie.startsWith(`${SESSION_COOKIE_NAME}=`));
+      if (!raw) return EMPTY_TOKENS;
+      const session = JSON.parse(
+        decodeURIComponent(raw.slice(SESSION_COOKIE_NAME.length + 1)),
+      ) as { clientId?: string; tokens?: Tokens };
+      return session.clientId === WIX_MEMBERS_CLIENT_ID && session.tokens
+        ? session.tokens
+        : EMPTY_TOKENS;
+    } catch {
+      return EMPTY_TOKENS;
+    }
+  },
+  setTokens(tokens: Tokens): void {
+    try {
+      const value = encodeURIComponent(
+        JSON.stringify({ clientId: WIX_MEMBERS_CLIENT_ID, tokens }),
+      );
+      document.cookie = `${SESSION_COOKIE_NAME}=${value}; path=/; secure; samesite=none`;
+    } catch {
+      // A blocked cookie only prevents the member session from surviving navigation.
+    }
+  },
+};
+
+if (!WIX_MEMBERS_CLIENT_ID) {
+  throw new Error("Custom member login needs WIX_MEMBERS_CLIENT_ID.");
+}
+
+const client = createClient({
+  modules: { members },
+  auth: OAuthStrategy({ clientId: WIX_MEMBERS_CLIENT_ID, tokenStorage }),
+});
+
+export const membersAuth = client.auth;
+export const membersApi = client.members;

package/skills/wix-headless-fast/references/members/app/wix/members/member-store.ts

@@ -0,0 +1,122 @@
+// 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 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();
+    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. No Wix-hosted login redirect is used. */
+export function login(email: string, password: string): Promise<LoginResult> {
+  return runLogin(() => loginMember(email, password));
+}
+
+/** Submit the branded in-app sign-up form. */
+export function register(
+  email: string,
+  password: string,
+  profile?: { firstName?: string; lastName?: string },
+): Promise<LoginResult> {
+  return runLogin(() => registerMember(email, password, profile));
+}
+
+/** 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-fast/references/members/app/wix/members/members.ts

@@ -0,0 +1,50 @@
+// Current-member read (Wix Members) — the only file that touches raw member entities.
+// 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/members/get-my-member.md
+import { membersApi } from "./client";
+import { imgSrc } from "../media";
+import type { CurrentMember } from "./types";
+
+type Raw = Record<string, any>;
+
+function toCurrentMember(raw: Raw): CurrentMember {
+  const nickname = raw.profile?.nickname ?? "";
+  const firstName = raw.contact?.firstName ?? "";
+  const lastName = raw.contact?.lastName ?? "";
+  const loginEmail = raw.loginEmail ?? "";
+  const fullName = [firstName, lastName].filter(Boolean).join(" ");
+  return {
+    id: raw._id ?? "",
+    loginEmail,
+    displayName: nickname || fullName || loginEmail.split("@")[0] || "Member",
+    firstName,
+    lastName,
+    nickname,
+    photoUrl: imgSrc(raw.profile?.photo, 200, 200),
+    contactId: raw.contactId ?? "",
+    memberSince: raw._createdDate
+      ? new Date(raw._createdDate).toISOString().slice(0, 10)
+      : "",
+  };
+}
+
+/**
+ * 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: ["FULL"] });
+    const raw = res.member as Raw | undefined;
+    return raw?._id ? toCurrentMember(raw) : null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-fast/references/members/app/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;
+}