@wix/agent-skills 1.20.0 → 1.20.1

package/skills/wix-headless-fast/references/members/app/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 references/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-fast/references/members/app/wix/members/members.ts

@@ -1,49 +1,28 @@
-// 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
+// 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
+// references/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";
 
-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 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 res = await membersApi.getCurrentMember({ fieldsets: [...MEMBER_FIELDSETS] as any });
     const raw = res.member as Raw | undefined;
-    return raw?._id ? toCurrentMember(raw) : null;
+    return raw && memberId(raw) ? toCurrentMember(raw, imgSrc) : null;
   } catch {
     return null;
   }

package/skills/wix-headless-fast/references/members/rest/auth.ts

@@ -0,0 +1,215 @@
+// 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 };
+
+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): 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 },
+): 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-fast/references/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;
+  }
+}