@wix/agent-skills 1.20.1 → 1.22.0

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

@@ -1,215 +0,0 @@
-// 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

@@ -1,26 +0,0 @@
-// 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-fast/references/members/seed/SEED.md

@@ -1,39 +0,0 @@
-# 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>/references/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 and the identity/profile split come from
-`wix-headless/references/SETUP.md` (§ members). 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-fast/references/members/seed/seed-members.mjs

@@ -1,94 +0,0 @@
-// Members seed — a BUILD-TIME script, never shipped in the app. Run from the project root
-// (where wix.config.json lives); the plan file is optional:
-//
-//   node <SKILL_ROOT>/references/members/seed/seed-members.mjs [plan.json]
-//
-// Members SELF-REGISTER — there is no member content to create (see SEED.md). The one
-// build-time setup this vertical needs is installing the Wix Members Area app, which serves
-// member PROFILE data: without it getCurrentMember() returns nothing for a logged-in member,
-// so the account page can't render who they are. Identity alone (log in / log out / gating)
-// needs no install. Prints a JSON result to stdout.
-//
-// Plan shape (see SEED.md): { "installMembersArea": true }   // default true
-//
-// Seeding is ADDITIVE — never deletes or overwrites existing content. Authoritative source:
-// wix-headless/references/SETUP.md § members (the appDefId and the identity/profile split).
-import { execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-
-const API = "https://www.wixapis.com";
-// The Wix Members Area app (the profile layer). Not in the "Apps Created by Wix" table —
-// the GUID comes from the App Market listing; recorded in wix-headless/references/SETUP.md.
-// Installing it pulls in its Site-Members dependency automatically.
-const MEMBERS_AREA_APP_ID = "14cc59bc-f0b7-15b8-e1c7-89ce41d0e0c9";
-
-export function makeCtx({ cwd = process.cwd() } = {}) {
-  const config = JSON.parse(readFileSync(`${cwd}/wix.config.json`, "utf8"));
-  const siteId = config.siteId ?? config.projectId;
-  if (!siteId) throw new Error("wix.config.json has no siteId — is this a Wix CLI project?");
-  const token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
-    encoding: "utf8",
-    cwd,
-  }).trim();
-  if (!token) throw new Error("The Wix CLI returned no token — run `npx @wix/cli@latest login` first.");
-  return { token, siteId };
-}
-
-async function req(ctx, path, { method = "POST", body } = {}) {
-  const res = await fetch(API + path, {
-    method,
-    headers: {
-      Authorization: `Bearer ${ctx.token}`,
-      "wix-site-id": ctx.siteId,
-      "Content-Type": "application/json",
-    },
-    body: body ? JSON.stringify(body) : undefined,
-  });
-  const json = await res.json().catch(() => ({}));
-  if (!res.ok) throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
-  return json;
-}
-
-// ---- operations ----------------------------------------------------------------------------------
-
-/**
- * Install the Wix Members Area app (idempotent in effect: re-running against a site that
- * already has it errors — recorded in the result, not thrown, since "already installed" and
- * a real failure aren't distinguishable from the response).
- * docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
- */
-export async function installMembersAreaApp(ctx) {
-  try {
-    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
-      tenant: { tenantType: "SITE", id: ctx.siteId },
-      appInstance: { appDefId: MEMBERS_AREA_APP_ID, enabled: true },
-    } });
-    return { requested: true, note: null };
-  } catch (e) {
-    return { requested: false, note: String(e.message).slice(0, 300) };
-  }
-}
-
-/** ONE-CALL seed: install the Members Area app (the profile layer). The default path. */
-export async function setupMembers(ctx, { installMembersArea = true } = {}) {
-  return {
-    membersAreaAppId: MEMBERS_AREA_APP_ID,
-    membersAreaInstall: installMembersArea ? await installMembersAreaApp(ctx) : { skipped: true },
-    membersCreated: 0, // members self-register — never created at build time
-  };
-}
-
-// ---- CLI entry ----------------------------------------------------------------------------------
-
-const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
-if (invokedDirectly) {
-  const planPath = process.argv[2];
-  const plan = planPath ? JSON.parse(readFileSync(planPath, "utf8")) : {};
-  const ctx = makeCtx();
-  setupMembers(ctx, plan)
-    .then((result) => console.log(JSON.stringify(result, null, 2)))
-    .catch((e) => {
-      console.error(e.message);
-      process.exit(1);
-    });
-}