@genex-ai/embed-sdk 0.2.0 → 0.3.1

package/dist/{chunk-KXUDNW6P.js → chunk-S7JLPCNE.js}

@@ -1,6 +1,7 @@
 // src/index.ts
 var PROTOCOL_VERSION = 1;
 var RETRY_FLAG = "genex:embed:retry";
+var POPOVER_DISMISSED_FLAG = "genex:guest:popover-dismissed";
 var config = null;
 var state = "pending";
 var user = null;
@@ -9,6 +10,7 @@ var colyseusUrl;
 var parentOrigin = null;
 var initialized = false;
 var redeeming = false;
+var requestingGuest = false;
 var handshakeTimeoutMs = 1e4;
 var refreshDelayMs = 10 * 6e4;
 var refreshRetryMs = 6e4;
@@ -17,7 +19,9 @@ var refreshTimer;
 var messageHandler;
 var listeners = /* @__PURE__ */ new Map();
 var authWaiters = [];
+var playerWaiters = [];
 var overlayEl = null;
+var popoverEl = null;
 function win() {
   return globalThis.window;
 }
@@ -46,6 +50,19 @@ function clearRetryFlag() {
   } catch {
   }
 }
+function readPopoverDismissed() {
+  try {
+    return win()?.sessionStorage?.getItem(POPOVER_DISMISSED_FLAG) === "1";
+  } catch {
+    return false;
+  }
+}
+function writePopoverDismissed() {
+  try {
+    win()?.sessionStorage?.setItem(POPOVER_DISMISSED_FLAG, "1");
+  } catch {
+  }
+}
 function initEmbed(cfg) {
   const w = win();
   if (!w) return;
@@ -92,6 +109,15 @@ function waitForAuth() {
     authWaiters.push({ resolve, reject });
   });
 }
+function waitForPlayer() {
+  if ((state === "authenticated" || state === "guest") && user) {
+    return Promise.resolve({ user, guest: state === "guest" });
+  }
+  if (state === "blocked") return Promise.reject(new Error("genex embed auth: blocked"));
+  return new Promise((resolve, reject) => {
+    playerWaiters.push({ resolve, reject });
+  });
+}
 function on(event, cb) {
   let set = listeners.get(event);
   if (!set) {
@@ -120,21 +146,33 @@ function startEmbeddedHandshake(w) {
   w.addEventListener("message", messageHandler);
   w.parent.postMessage({ type: "genex:embed:ready", v: PROTOCOL_VERSION }, "*");
   handshakeTimer = setTimeout(() => {
-    enterBlocked();
+    void requestGuestSession();
   }, handshakeTimeoutMs);
 }
+function acceptsTicket() {
+  return (state === "pending" || state === "guest") && !redeeming;
+}
 async function handleParentMessage(event) {
-  if (!config || state !== "pending" || redeeming) return;
+  if (!config) return;
   const data = event.data;
-  if (!data || data.type !== "genex:embed:ticket" || data.v !== PROTOCOL_VERSION) return;
-  if (typeof data.ticket !== "string" || !data.ticket) return;
+  if (!data || data.v !== PROTOCOL_VERSION) return;
+  const isTicket = data.type === "genex:embed:ticket";
+  const isGuest = data.type === "genex:embed:guest";
+  if (!isTicket && !isGuest) return;
+  if (isTicket && (!acceptsTicket() || typeof data.ticket !== "string" || !data.ticket)) return;
+  if (isGuest && (state !== "pending" || redeeming || requestingGuest)) return;
   if (!config.dashboardOrigins.includes(event.origin)) {
     const fresh = await fetchDashboardOrigins();
-    if (state !== "pending" || redeeming) return;
+    if (isTicket && !acceptsTicket()) return;
+    if (isGuest && (state !== "pending" || redeeming || requestingGuest)) return;
     if (!fresh.includes(event.origin)) return;
   }
   if (handshakeTimer !== void 0) clearTimeout(handshakeTimer);
   parentOrigin = event.origin;
+  if (isGuest) {
+    await requestGuestSession();
+    return;
+  }
   await redeemTicket(data.ticket);
 }
 function postToParent(message, targetOrigin) {
@@ -146,41 +184,52 @@ function postToParent(message, targetOrigin) {
   }
 }
 async function startStandaloneFlow(w) {
-  const ticket = readTicketFromFragment(w);
-  if (ticket) {
-    try {
-      w.history.replaceState(null, "", w.location.pathname + w.location.search);
-    } catch {
-    }
-    await redeemTicket(ticket);
+  const frag = readFragment(w);
+  if (frag.ticket) {
+    await redeemTicket(frag.ticket);
+    return;
+  }
+  if (frag.guest) {
+    await requestGuestSession();
     return;
   }
   showOverlay("redirecting");
-  await redirectToAuthorize(w);
+  await redirectToAuthorize(w, { guestOk: true });
 }
 var stashedTicketHash = null;
 function _stashTicketFromUrl() {
   const w = win();
   if (!w) return;
   const hash = w.location.hash;
-  if (!hash || !hash.includes("genex_ticket")) return;
+  if (!hash || !hash.includes("genex_")) return;
   stashedTicketHash = hash;
   try {
     w.history.replaceState(null, "", w.location.pathname + w.location.search);
   } catch {
   }
 }
-function readTicketFromFragment(w) {
+function readFragment(w) {
   const hash = stashedTicketHash ?? w.location.hash;
   stashedTicketHash = null;
-  if (!hash || hash.length < 2) return null;
+  if (!hash || hash.length < 2) return { ticket: null, guest: false };
+  let ticket = null;
+  let guest = false;
   try {
-    return new URLSearchParams(hash.slice(1)).get("genex_ticket");
+    const params = new URLSearchParams(hash.slice(1));
+    ticket = params.get("genex_ticket");
+    guest = params.get("genex_guest") === "1";
   } catch {
-    return null;
+    return { ticket: null, guest: false };
+  }
+  if (ticket || guest) {
+    try {
+      w.history.replaceState(null, "", w.location.pathname + w.location.search);
+    } catch {
+    }
   }
+  return { ticket, guest };
 }
-async function redirectToAuthorize(w) {
+async function redirectToAuthorize(w, opts) {
   if (!config) return;
   const origins = await fetchDashboardOrigins();
   const origin = origins[0] ?? config.dashboardOrigins[0];
@@ -189,7 +238,8 @@ async function redirectToAuthorize(w) {
     return;
   }
   const returnTo = w.location.origin + w.location.pathname;
-  const url = `${origin}/play/authorize?returnTo=${encodeURIComponent(returnTo)}&slug=${encodeURIComponent(config.slug)}`;
+  const guestParam = opts?.guestOk ? "&guest=ok" : "";
+  const url = `${origin}/play/authorize?returnTo=${encodeURIComponent(returnTo)}&slug=${encodeURIComponent(config.slug)}${guestParam}`;
   w.location.replace(url);
 }
 async function fetchDashboardOrigins() {
@@ -206,7 +256,8 @@ async function fetchDashboardOrigins() {
   return config.dashboardOrigins;
 }
 async function redeemTicket(ticket) {
-  if (!config || redeeming || state !== "pending") return;
+  if (!config || redeeming || state !== "pending" && state !== "guest") return;
+  const upgradingFromGuest = state === "guest";
   redeeming = true;
   try {
     const res = await doFetch(`${config.apiUrl}/api/embed/session`, {
@@ -216,7 +267,7 @@ async function redeemTicket(ticket) {
     });
     if (!res.ok) {
       emit("error", { error: new Error(`ticket redemption failed (${res.status})`) });
-      await handleRedeemFailure();
+      if (!upgradingFromGuest) await handleRedeemFailure();
       return;
     }
     const body = await res.json();
@@ -227,26 +278,75 @@ async function redeemTicket(ticket) {
     state = "authenticated";
     clearRetryFlag();
     removeOverlay();
+    removeGuestPopover();
     scheduleRefresh();
     if (isEmbedded() && parentOrigin) {
       postToParent({ type: "genex:embed:authenticated", v: PROTOCOL_VERSION }, parentOrigin);
     }
     const ctx = { user };
     for (const waiter of authWaiters.splice(0)) waiter.resolve(ctx);
+    for (const waiter of playerWaiters.splice(0)) waiter.resolve({ user, guest: false });
     emit("authenticated", ctx);
   } catch (error) {
     emit("error", { error });
-    await handleRedeemFailure();
+    if (!upgradingFromGuest) await handleRedeemFailure();
   } finally {
     redeeming = false;
   }
 }
+async function requestGuestSession() {
+  if (!config || requestingGuest || redeeming) return;
+  if (state !== "pending" && state !== "guest") return;
+  requestingGuest = true;
+  try {
+    const res = await doFetch(`${config.apiUrl}/api/embed/guest-session`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ slug: config.slug })
+    });
+    if (!res.ok) {
+      emit("error", { error: new Error(`guest session failed (${res.status})`) });
+      enterBlocked();
+      return;
+    }
+    const body = await res.json();
+    embedToken = body.embedToken;
+    user = body.user;
+    colyseusUrl = body.colyseus?.url;
+    enterGuest();
+  } catch (error) {
+    emit("error", { error });
+    enterBlocked();
+  } finally {
+    requestingGuest = false;
+  }
+}
+function enterGuest() {
+  const firstEntry = state !== "guest";
+  state = "guest";
+  if (handshakeTimer !== void 0) clearTimeout(handshakeTimer);
+  removeOverlay();
+  scheduleRefresh();
+  if (isEmbedded()) {
+    postToParent(
+      { type: "genex:embed:authenticated", v: PROTOCOL_VERSION, guest: true },
+      parentOrigin ?? "*"
+    );
+  } else if (firstEntry && !readPopoverDismissed()) {
+    showGuestPopover();
+  }
+  if (user) {
+    const ctx = { user };
+    for (const waiter of playerWaiters.splice(0)) waiter.resolve({ user, guest: true });
+    emit("guest", ctx);
+  }
+}
 async function handleRedeemFailure() {
   const w = win();
   if (w && !isEmbedded() && !readRetryFlag()) {
     writeRetryFlag();
     showOverlay("redirecting");
-    await redirectToAuthorize(w);
+    await redirectToAuthorize(w, { guestOk: true });
     return;
   }
   enterBlocked();
@@ -258,7 +358,7 @@ function scheduleRefresh() {
   }, refreshDelayMs);
 }
 async function refreshToken() {
-  if (!config || state !== "authenticated" || !embedToken) return;
+  if (!config || state !== "authenticated" && state !== "guest" || !embedToken) return;
   let status;
   try {
     const res = await doFetch(`${config.apiUrl}/api/embed/session/refresh`, {
@@ -279,6 +379,10 @@ async function refreshToken() {
     status = void 0;
   }
   if (status === 401) {
+    if (state === "guest") {
+      void requestGuestSession();
+      return;
+    }
     emit("error", { error: new Error("embed session expired") });
     enterBlocked();
     return;
@@ -295,17 +399,21 @@ function enterBlocked() {
   embedToken = void 0;
   if (handshakeTimer !== void 0) clearTimeout(handshakeTimer);
   if (refreshTimer !== void 0) clearTimeout(refreshTimer);
+  removeGuestPopover();
   showOverlay(isEmbedded() ? "blocked-embedded" : "blocked-standalone");
   if (isEmbedded()) {
     postToParent({ type: "genex:embed:blocked", v: PROTOCOL_VERSION }, parentOrigin ?? "*");
   }
   const err = new Error("genex embed auth: blocked");
   for (const waiter of authWaiters.splice(0)) waiter.reject(err);
+  for (const waiter of playerWaiters.splice(0)) waiter.reject(err);
   emit("blocked");
 }
 var OVERLAY_TEXT = {
   connecting: { title: "Connecting to Genex\u2026" },
-  redirecting: { title: "Signing you in\u2026" },
+  // Neutral on purpose: the automatic bounce precedes GUEST play as often as
+  // sign-in — "signing you in" would be wrong for most visitors.
+  redirecting: { title: "Loading\u2026" },
   "blocked-standalone": { title: "Sign in to play", button: "Sign in" },
   "blocked-embedded": { title: "Sign in on the Genex dashboard to continue" }
 };
@@ -359,6 +467,56 @@ function buildOverlay(d) {
     }
   };
 }
+function showGuestPopover() {
+  const d = doc();
+  if (!d?.createElement || popoverEl) return;
+  try {
+    popoverEl = buildGuestPopover(d);
+  } catch {
+  }
+}
+function removeGuestPopover() {
+  try {
+    const root = popoverEl?.root;
+    root?.remove?.();
+  } catch {
+  }
+  popoverEl = null;
+}
+function buildGuestPopover(d) {
+  const root = d.createElement("div");
+  root.setAttribute("data-genex-guest-popover", "");
+  root.style.cssText = "position:fixed;top:12px;right:12px;z-index:2147483646;display:flex;align-items:center;gap:12px;padding:10px 12px 10px 16px;border-radius:12px;background:rgba(8,10,20,0.85);color:#fff;font-family:system-ui,-apple-system,sans-serif;font-size:13px;box-shadow:0 4px 24px rgba(0,0,0,0.4);pointer-events:auto;user-select:none";
+  const text = d.createElement("span");
+  text.textContent = user?.name ? `Playing as ${user.name} \u2014 sign in to save progress` : "Sign in to save progress";
+  root.appendChild(text);
+  const signIn = d.createElement("button");
+  signIn.textContent = "Sign in";
+  signIn.style.cssText = "font-size:13px;font-weight:600;padding:6px 16px;border-radius:999px;border:none;cursor:pointer;background:#fff;color:#111";
+  signIn.addEventListener("click", () => {
+    const w = win();
+    if (!w) return;
+    signIn.disabled = true;
+    clearRetryFlag();
+    void redirectToAuthorize(w);
+  });
+  root.appendChild(signIn);
+  const dismiss = d.createElement("button");
+  dismiss.textContent = "\xD7";
+  dismiss.setAttribute("aria-label", "Dismiss");
+  dismiss.style.cssText = "font-size:16px;line-height:1;padding:6px 8px;border:none;cursor:pointer;background:transparent;color:rgba(255,255,255,0.6)";
+  dismiss.addEventListener("click", () => {
+    writePopoverDismissed();
+    removeGuestPopover();
+  });
+  root.appendChild(dismiss);
+  const mount = () => {
+    if (d.body && !root.isConnected) d.body.appendChild(root);
+  };
+  if (d.body) mount();
+  else d.addEventListener?.("DOMContentLoaded", mount);
+  return { root };
+}
 function __resetForTests(overrides) {
   const w = win();
   if (w && messageHandler) w.removeEventListener("message", messageHandler);
@@ -368,6 +526,7 @@ function __resetForTests(overrides) {
   handshakeTimer = void 0;
   refreshTimer = void 0;
   removeOverlay();
+  removeGuestPopover();
   config = null;
   state = "pending";
   user = null;
@@ -376,8 +535,11 @@ function __resetForTests(overrides) {
   parentOrigin = null;
   initialized = false;
   redeeming = false;
+  requestingGuest = false;
   listeners.clear();
   authWaiters = [];
+  playerWaiters = [];
+  stashedTicketHash = null;
   handshakeTimeoutMs = overrides?.handshakeTimeoutMs ?? 1e4;
   refreshDelayMs = overrides?.refreshDelayMs ?? 10 * 6e4;
   refreshRetryMs = overrides?.refreshRetryMs ?? 6e4;
@@ -391,6 +553,7 @@ export {
   getEmbedToken,
   getColyseusAuth,
   waitForAuth,
+  waitForPlayer,
   on,
   _stashTicketFromUrl,
   __resetForTests

package/dist/index.d.ts

@@ -15,8 +15,8 @@ interface EmbedUser {
     name: string;
     image?: string;
 }
-type AuthState = 'pending' | 'authenticated' | 'blocked';
-type EmbedEvent = 'authenticated' | 'blocked' | 'error';
+type AuthState = 'pending' | 'authenticated' | 'guest' | 'blocked';
+type EmbedEvent = 'authenticated' | 'guest' | 'blocked' | 'error';
 interface EventContext {
     user?: EmbedUser;
     error?: unknown;
@@ -24,12 +24,14 @@ interface EventContext {
 /**
  * Initialize embed auth. Call ONCE, first thing in the boot sequence — before
  * connect() and before any /state call. Scene/asset boot may proceed
- * immediately (the gate overlay blocks interaction, not execution); await
- * waitForAuth() before anything identity-dependent.
+ * immediately; await waitForPlayer() for anything that needs a player
+ * identity (multiplayer connect, name UI) and waitForAuth() for anything that
+ * needs a signed-in ACCOUNT (/state saves).
  *
- * Standalone (not in an iframe) with no return-trip ticket present, this
- * navigates away to the dashboard sign-in — by design, there is no anonymous
- * play.
+ * Standalone (not in an iframe) with no return-trip fragment present, this
+ * bounces once through the dashboard's /play/authorize and comes straight
+ * back — signed-in visitors arrive authenticated (zero clicks, any game),
+ * everyone else arrives as a guest (published games; no login wall).
  */
 declare function initEmbed(cfg: EmbedConfig): void;
 /**
@@ -37,14 +39,23 @@ declare function initEmbed(cfg: EmbedConfig): void;
  * "is authenticated". True even before the handshake resolves.
  */
 declare function isEmbedded(): boolean;
-/** Current auth state. Synchronous; starts 'pending', ends 'authenticated' or 'blocked'. */
+/**
+ * Current auth state. Synchronous; starts 'pending', ends 'authenticated',
+ * 'guest' (accountless guest play) or 'blocked'. A 'guest' session may still
+ * upgrade to 'authenticated' live (dashboard sign-in mid-play).
+ */
 declare function getAuthState(): AuthState;
-/** The signed-in user — non-null only once getAuthState() === 'authenticated'. */
+/**
+ * The current player — non-null once 'authenticated' OR 'guest'. Guests have
+ * an `id` prefixed `guest:` and a server-assigned name like "Guest-1234".
+ */
 declare function getUser(): EmbedUser | null;
 /**
  * The raw scoped embedToken, for Authorization: Bearer calls the game makes
- * itself (GET/PUT /api/projects/:slug/state — which REQUIRES it; there is no
- * anonymous save path). undefined unless authenticated.
+ * itself (GET/PUT /api/projects/:slug/state). undefined unless authenticated
+ * or guest. In GUEST state this is the guest token: the relay accepts it, but
+ * /state rejects it with 403 { error: "guest_no_save" } — gate saves on
+ * waitForAuth(), not on this being defined.
  *
  * NEVER log this value or pass it to crash-reporting/analytics breadcrumb
  * capture. It is bounded (15 minutes, one project, one scope), but third-party
@@ -53,26 +64,39 @@ declare function getUser(): EmbedUser | null;
 declare function getEmbedToken(): string | undefined;
 /**
  * The credential for multiplayer: pass as `connect({ ..., auth: getColyseusAuth() })`
- * AFTER `await waitForAuth()` — the relay rejects tokenless joins. Read it
- * fresh at every connect() call (tokens rotate ~every 10 minutes).
- * NEVER log this value.
+ * AFTER `await waitForPlayer()` — the relay rejects tokenless joins, but
+ * accepts guest tokens. Read it fresh at every connect() call (tokens rotate
+ * ~every 10 minutes). NEVER log this value.
  */
 declare function getColyseusAuth(): {
     embedToken: string;
 } | undefined;
 /**
- * Resolves with the signed-in user once authenticated; rejects if the session
- * ends up blocked. THE gate for connect() and /state calls.
+ * Resolves with the signed-in ACCOUNT once authenticated; rejects if the
+ * session ends up blocked. THE gate for /state saves and any account-bound
+ * feature. In a guest session this stays PENDING (it is not rejected —
+ * a live upgrade resolves it), so never gate scene boot or connect() on it:
+ * use waitForPlayer() for those.
  */
 declare function waitForAuth(): Promise<{
     user: EmbedUser;
 }>;
+/**
+ * Resolves with the current player — guest OR signed-in — as soon as either
+ * identity exists; rejects only if the session ends up blocked. THE gate for
+ * multiplayer connect() and player-name UI.
+ */
+declare function waitForPlayer(): Promise<{
+    user: EmbedUser;
+    guest: boolean;
+}>;
 /** Subscribe to auth lifecycle events. Returns an unsubscribe function. */
 declare function on(event: EmbedEvent, cb: (ctx?: EventContext) => void): () => void;
 /**
  * @internal — for ./sentry.ts ONLY, not public API (games never call this).
- * If the URL fragment carries a genex ticket, move it out of the URL (so no
- * recorder/logger ever sees it) into a stash the standalone flow reads.
+ * If the URL fragment carries any genex marker (`genex_ticket` — a secret —
+ * or the inert `genex_guest`), move it out of the URL (so no recorder/logger
+ * ever sees it) into a stash the standalone flow reads.
  */
 declare function _stashTicketFromUrl(): void;
 declare function __resetForTests(overrides?: {
@@ -81,4 +105,4 @@ declare function __resetForTests(overrides?: {
     refreshRetryMs?: number;
 }): void;
 
-export { type AuthState, type EmbedConfig, type EmbedEvent, type EmbedUser, __resetForTests, _stashTicketFromUrl, getAuthState, getColyseusAuth, getEmbedToken, getUser, initEmbed, isEmbedded, on, waitForAuth };
+export { type AuthState, type EmbedConfig, type EmbedEvent, type EmbedUser, __resetForTests, _stashTicketFromUrl, getAuthState, getColyseusAuth, getEmbedToken, getUser, initEmbed, isEmbedded, on, waitForAuth, waitForPlayer };

package/dist/index.js

@@ -8,8 +8,9 @@ import {
   initEmbed,
   isEmbedded,
   on,
-  waitForAuth
-} from "./chunk-KXUDNW6P.js";
+  waitForAuth,
+  waitForPlayer
+} from "./chunk-S7JLPCNE.js";
 export {
   __resetForTests,
   _stashTicketFromUrl,
@@ -20,5 +21,6 @@ export {
   initEmbed,
   isEmbedded,
   on,
-  waitForAuth
+  waitForAuth,
+  waitForPlayer
 };

package/dist/sentry.js

@@ -2,7 +2,7 @@ import {
   _stashTicketFromUrl,
   getUser,
   on
-} from "./chunk-KXUDNW6P.js";
+} from "./chunk-S7JLPCNE.js";
 
 // src/sentry.ts
 import * as Sentry from "@sentry/browser";
@@ -94,6 +94,10 @@ function initGameSentry(opts) {
     const u = ctx?.user ?? getUser();
     if (u) Sentry.setUser({ id: u.id, username: u.name });
   });
+  on("guest", (ctx) => {
+    const u = ctx?.user ?? getUser();
+    if (u) Sentry.setUser({ id: u.id, username: u.name });
+  });
   on("blocked", () => Sentry.setUser(null));
   on("error", (ctx) => {
     if (ctx?.error) Sentry.captureException(ctx.error);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genex-ai/embed-sdk",
-  "version": "0.2.0",
-  "description": "Signed-in identity for genex games — embedded (dashboard iframe postMessage handshake) or standalone (sign-in redirect). No anonymous play.",
+  "version": "0.3.1",
+  "description": "Player identity for genex games — signed-in (dashboard iframe postMessage handshake or sign-in redirect) or guest (accountless play for published games, sign in to save).",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",