@wordkey/sdk 1.0.1 → 1.1.0

package/README.md

@@ -10,25 +10,77 @@ npm install @wordkey/sdk
 
 ## 1. Add the button
 
+Signup and login are different user moments, so the SDK gives you both:
+
+- **`mode="signup"`** — *Get your word*: a brand-new user gets a word in
+  WordKey's onboarding window, this device is enrolled, and they come back
+  signed in to your site — one flow.
+- **`mode="login"`** (default) — *Word?*: a returning user types the word
+  they already have.
+
+Both deliver the identical `onSuccess` user, so your backend handles one
+contract.
+
 ```jsx
 import { WordKeyButton } from "@wordkey/sdk";
 
+const handleUser = async (user) => {
+  // user.token is a single-use proof of authentication. Hand it to
+  // YOUR backend and verify it there (step 2) before creating a
+  // session — never trust user.id straight from the browser.
+  await fetch("/api/wordkey-login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ token: user.token }),
+  });
+};
+
 export function LoginPage() {
   return (
-    <WordKeyButton
-      publishableKey="wk_pub_xxxxxxxxxxxx"
-      onSuccess={async (user) => {
-        // user.token is a single-use proof of authentication. Hand it to
-        // YOUR backend and verify it there (step 2) before creating a
-        // session — never trust user.id straight from the browser.
-        await fetch("/api/wordkey-login", {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ token: user.token }),
-        });
-      }}
-      onError={(err) => console.error(err)}
-    />
+    <>
+      <WordKeyButton
+        publishableKey="wk_pub_xxxxxxxxxxxx"
+        mode="signup"
+        onSuccess={handleUser}
+      />
+      <WordKeyButton
+        publishableKey="wk_pub_xxxxxxxxxxxx"
+        onSuccess={handleUser}
+        onError={(err) => console.error(err)}
+      />
+    </>
+  );
+}
+```
+
+### Use your own buttons (WordKeyModal)
+
+`WordKeyButton` is sugar over the controlled `WordKeyModal`. Render the modal
+once, unconditionally, and open either flow from any UI you like:
+
+```jsx
+import { WordKeyModal } from "@wordkey/sdk";
+import { useState } from "react";
+
+export function AuthButtons() {
+  const [flow, setFlow] = useState(null); // null | "signup" | "login"
+  return (
+    <>
+      <button className="cta" onClick={() => setFlow("signup")}>
+        Get Your Word
+      </button>
+      <a onClick={() => setFlow("login")}>Already have a word?</a>
+
+      {/* Always mounted — toggle `open`, don't conditionally render: the
+          modal also resumes the popup-blocked redirect fallback on mount. */}
+      <WordKeyModal
+        publishableKey="wk_pub_xxxxxxxxxxxx"
+        open={flow !== null}
+        mode={flow ?? "login"}
+        onClose={() => setFlow(null)}
+        onSuccess={handleUser}
+      />
+    </>
   );
 }
 ```

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { W as WordKeyUser, a as WordKeyError, R as RequestedField } from './types-B4z3Zton.mjs';
-export { A as Address, b as AuthEvent, C as CustomField, P as ProfileField, c as WordKeyProfile } from './types-B4z3Zton.mjs';
+import { W as WordKeyUser, a as WordKeyError, b as WordKeyMode, R as RequestedField } from './types-WFjkfsy6.mjs';
+export { A as Address, c as AuthEvent, C as CustomField, P as ProfileField, d as WordKeyProfile } from './types-WFjkfsy6.mjs';
 
 interface WordKeyButtonProps {
     publishableKey: string;
@@ -9,11 +9,48 @@ interface WordKeyButtonProps {
     theme?: "dark" | "light" | "auto";
     size?: "sm" | "md" | "lg";
     label?: string;
+    /**
+     * Which flow this button opens. "login" (default, the 1.0.x behavior)
+     * renders the Word? mark for returning users; "signup" renders
+     * "Get your word" and opens WordKey onboarding for brand-new users.
+     * Render one button of each mode for the two user moments — or drive
+     * WordKeyModal yourself from any UI you like.
+     */
+    mode?: WordKeyMode;
     /** Profile fields to request. Standard names or custom field descriptors. */
     requestedFields?: RequestedField[];
     /** Override the protocol host (defaults to app.wordkey.app). */
     apiUrl?: string;
 }
-declare function WordKeyButton({ publishableKey, onSuccess, onError, size, label, requestedFields, apiUrl, }: WordKeyButtonProps): react.JSX.Element;
+declare function WordKeyButton({ publishableKey, onSuccess, onError, size, label, mode, requestedFields, apiUrl, }: WordKeyButtonProps): react.JSX.Element;
 
-export { RequestedField, WordKeyButton, type WordKeyButtonProps, WordKeyError, WordKeyUser };
+/**
+ * The controlled WordKey flow. Render it ONCE, unconditionally (toggle `open`,
+ * don't conditionally mount it): the redirect-fallback return leg is consumed
+ * in this component's mount effect, and a conditionally rendered modal would
+ * miss it on the page load that carries the result fragment.
+ *
+ * mode "login"  — the Word? flow for returning users (the 1.0.x behavior).
+ * mode "signup" — the Get-your-word flow: opens WordKey's first-party
+ * onboarding page in a popup, which assigns a word, enrolls this device, and
+ * hands back the same single-use token login yields — so `onSuccess` has ONE
+ * contract across both modes and every WordKeyButton stays a thin wrapper.
+ */
+interface WordKeyModalProps {
+    publishableKey: string;
+    /** Controlled visibility. The modal calls `onClose` when it dismisses itself
+     *  (cancel, overlay click, or right before delivering `onSuccess`). */
+    open: boolean;
+    onClose: () => void;
+    onSuccess: (user: WordKeyUser) => void;
+    /** Which flow to open. Defaults to "login". */
+    mode?: WordKeyMode;
+    onError?: (error: WordKeyError) => void;
+    /** Profile fields to request. Standard names or custom field descriptors. */
+    requestedFields?: RequestedField[];
+    /** Override the protocol host (defaults to app.wordkey.app). */
+    apiUrl?: string;
+}
+declare function WordKeyModal({ publishableKey, open, onClose, onSuccess, mode, onError, requestedFields, apiUrl, }: WordKeyModalProps): react.JSX.Element | null;
+
+export { RequestedField, WordKeyButton, type WordKeyButtonProps, WordKeyError, WordKeyModal, type WordKeyModalProps, WordKeyMode, WordKeyUser };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { W as WordKeyUser, a as WordKeyError, R as RequestedField } from './types-B4z3Zton.js';
-export { A as Address, b as AuthEvent, C as CustomField, P as ProfileField, c as WordKeyProfile } from './types-B4z3Zton.js';
+import { W as WordKeyUser, a as WordKeyError, b as WordKeyMode, R as RequestedField } from './types-WFjkfsy6.js';
+export { A as Address, c as AuthEvent, C as CustomField, P as ProfileField, d as WordKeyProfile } from './types-WFjkfsy6.js';
 
 interface WordKeyButtonProps {
     publishableKey: string;
@@ -9,11 +9,48 @@ interface WordKeyButtonProps {
     theme?: "dark" | "light" | "auto";
     size?: "sm" | "md" | "lg";
     label?: string;
+    /**
+     * Which flow this button opens. "login" (default, the 1.0.x behavior)
+     * renders the Word? mark for returning users; "signup" renders
+     * "Get your word" and opens WordKey onboarding for brand-new users.
+     * Render one button of each mode for the two user moments — or drive
+     * WordKeyModal yourself from any UI you like.
+     */
+    mode?: WordKeyMode;
     /** Profile fields to request. Standard names or custom field descriptors. */
     requestedFields?: RequestedField[];
     /** Override the protocol host (defaults to app.wordkey.app). */
     apiUrl?: string;
 }
-declare function WordKeyButton({ publishableKey, onSuccess, onError, size, label, requestedFields, apiUrl, }: WordKeyButtonProps): react.JSX.Element;
+declare function WordKeyButton({ publishableKey, onSuccess, onError, size, label, mode, requestedFields, apiUrl, }: WordKeyButtonProps): react.JSX.Element;
 
-export { RequestedField, WordKeyButton, type WordKeyButtonProps, WordKeyError, WordKeyUser };
+/**
+ * The controlled WordKey flow. Render it ONCE, unconditionally (toggle `open`,
+ * don't conditionally mount it): the redirect-fallback return leg is consumed
+ * in this component's mount effect, and a conditionally rendered modal would
+ * miss it on the page load that carries the result fragment.
+ *
+ * mode "login"  — the Word? flow for returning users (the 1.0.x behavior).
+ * mode "signup" — the Get-your-word flow: opens WordKey's first-party
+ * onboarding page in a popup, which assigns a word, enrolls this device, and
+ * hands back the same single-use token login yields — so `onSuccess` has ONE
+ * contract across both modes and every WordKeyButton stays a thin wrapper.
+ */
+interface WordKeyModalProps {
+    publishableKey: string;
+    /** Controlled visibility. The modal calls `onClose` when it dismisses itself
+     *  (cancel, overlay click, or right before delivering `onSuccess`). */
+    open: boolean;
+    onClose: () => void;
+    onSuccess: (user: WordKeyUser) => void;
+    /** Which flow to open. Defaults to "login". */
+    mode?: WordKeyMode;
+    onError?: (error: WordKeyError) => void;
+    /** Profile fields to request. Standard names or custom field descriptors. */
+    requestedFields?: RequestedField[];
+    /** Override the protocol host (defaults to app.wordkey.app). */
+    apiUrl?: string;
+}
+declare function WordKeyModal({ publishableKey, open, onClose, onSuccess, mode, onError, requestedFields, apiUrl, }: WordKeyModalProps): react.JSX.Element | null;
+
+export { RequestedField, WordKeyButton, type WordKeyButtonProps, WordKeyError, WordKeyModal, type WordKeyModalProps, WordKeyMode, WordKeyUser };

package/dist/index.js

@@ -30,12 +30,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  WordKeyButton: () => WordKeyButton
+  WordKeyButton: () => WordKeyButton,
+  WordKeyModal: () => WordKeyModal
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/WordKeyButton.tsx
-var import_react = require("react");
+var import_react2 = require("react");
 
 // src/types.ts
 var FIELD_LABELS = {
@@ -46,6 +47,9 @@ var FIELD_LABELS = {
 };
 var DEFAULT_API_URL = "https://app.wordkey.app";
 
+// src/WordKeyModal.tsx
+var import_react = require("react");
+
 // src/fields.ts
 var STANDARD = {
   name: { key: "name", label: FIELD_LABELS.name, type: "text", isStandard: true },
@@ -110,6 +114,17 @@ var DeviceApprovalRequiredError = class extends Error {
     this.name = "DeviceApprovalRequiredError";
   }
 };
+function decodeToken(token) {
+  try {
+    const part = token.split(".")[1];
+    if (!part) return null;
+    const b64 = part.replace(/-/g, "+").replace(/_/g, "/");
+    const json = typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("utf8");
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
 async function verifyWord(apiUrl = DEFAULT_API_URL, publishableKey, word) {
   const wordHash = await hashWord(word);
   const res = await fetch(`${apiUrl}/api/auth/verify`, {
@@ -244,6 +259,7 @@ async function beginRedirectShare(input2) {
   const publicJwk = await crypto.subtle.exportKey("jwk", pair.publicKey);
   const privateKeyJwk = await crypto.subtle.exportKey("jwk", pair.privateKey);
   const pending = {
+    kind: "login",
     requestId: input2.requestId,
     userId: input2.userId,
     isNewUser: input2.isNewUser,
@@ -283,10 +299,12 @@ async function consumePendingRedirect() {
   }
   if (envelope.requestId !== pending.requestId) return null;
   sessionStorage.removeItem(PENDING_STORE);
-  if (envelope.granted !== true) {
-    return { pending, result: { granted: false, values: {} } };
+  if (!envelope.epk || !envelope.iv || !envelope.ct) {
+    if (envelope.granted !== true) {
+      return { pending, result: { granted: false, values: {} } };
+    }
+    return null;
   }
-  if (!envelope.epk || !envelope.iv || !envelope.ct) return null;
   try {
     const privateKey = await crypto.subtle.importKey(
       "jwk",
@@ -317,13 +335,135 @@ async function consumePendingRedirect() {
     const parsed = JSON.parse(new TextDecoder().decode(plain));
     return {
       pending,
-      result: { granted: true, values: parsed.values ?? {} }
+      result: {
+        granted: envelope.granted === true,
+        values: parsed.values ?? {}
+      },
+      signup: typeof parsed.signup?.token === "string" ? { token: parsed.signup.token } : void 0
     };
   } catch {
     return null;
   }
 }
 
+// src/signup-popup.ts
+var SIGNUP_TIMEOUT_MS = 20 * 60 * 1e3;
+function openSignupWindow(apiUrl, publishableKey) {
+  const w = 440;
+  const h = 700;
+  const left = Math.max(0, (window.screenX ?? 0) + (window.outerWidth - w) / 2);
+  const top = Math.max(0, (window.screenY ?? 0) + (window.outerHeight - h) / 3);
+  try {
+    return window.open(
+      `${apiUrl}/welcome?wk_sdk=1&business=${encodeURIComponent(publishableKey)}`,
+      "wordkey-signup",
+      `popup=yes,width=${w},height=${h},left=${left},top=${top}`
+    );
+  } catch {
+    return null;
+  }
+}
+function runSignupHandshake(input2) {
+  const { popup, apiOrigin, requestId, signal } = input2;
+  return new Promise((resolve) => {
+    let settled = false;
+    const cleanup = () => {
+      window.removeEventListener("message", onMsg);
+      clearInterval(closedPoll);
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const finish = (r) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(r);
+    };
+    const onAbort = () => {
+      try {
+        popup.close();
+      } catch {
+      }
+      finish({ ok: false, cancelled: true });
+    };
+    const onMsg = (e) => {
+      if (e.origin !== apiOrigin || e.source !== popup) return;
+      const data = e.data;
+      if (!data || typeof data !== "object") return;
+      if (data.type === "wordkey:signup:ready") {
+        popup.postMessage(
+          {
+            type: "wordkey:signup:init",
+            requestId,
+            publishableKey: input2.publishableKey,
+            sdkDeviceId: input2.sdkDeviceId,
+            fields: input2.fields
+          },
+          apiOrigin
+        );
+      }
+      if (data.type === "wordkey:signup:result" && data.requestId === requestId) {
+        finish({
+          ok: data.ok === true && typeof data.token === "string",
+          token: typeof data.token === "string" ? data.token : void 0,
+          profileTicket: typeof data.profileTicket === "string" ? data.profileTicket : void 0
+        });
+      }
+    };
+    window.addEventListener("message", onMsg);
+    const closedPoll = setInterval(() => {
+      if (popup.closed) finish({ ok: false, closed: true });
+    }, 400);
+    const timer = setTimeout(
+      () => finish({ ok: false, closed: true }),
+      SIGNUP_TIMEOUT_MS
+    );
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort);
+    }
+  });
+}
+async function beginSignupRedirect(input2) {
+  const pair = await crypto.subtle.generateKey(
+    { name: "ECDH", namedCurve: "P-256" },
+    true,
+    ["deriveKey"]
+  );
+  const publicJwk = await crypto.subtle.exportKey("jwk", pair.publicKey);
+  const privateKeyJwk = await crypto.subtle.exportKey("jwk", pair.privateKey);
+  const pending = {
+    kind: "signup",
+    requestId: input2.requestId,
+    fields: input2.fields,
+    privateKeyJwk
+  };
+  sessionStorage.setItem(PENDING_STORE, JSON.stringify(pending));
+  const returnUrl = window.location.href.split("#")[0];
+  const request = {
+    v: 1,
+    requestId: input2.requestId,
+    publishableKey: input2.publishableKey,
+    origin: window.location.origin,
+    returnUrl,
+    sdkPub: publicJwk,
+    sdkDeviceId: input2.sdkDeviceId,
+    fields: input2.fields
+  };
+  const b64 = encodeSignupRequest(request);
+  window.location.assign(
+    `${input2.apiUrl}/welcome?wk_sdk=1&business=${encodeURIComponent(
+      input2.publishableKey
+    )}#wksignup=${b64}`
+  );
+}
+function encodeSignupRequest(value) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
 // src/fonts.ts
 var loaded = false;
 function ensureFont() {
@@ -420,19 +560,18 @@ var ghostBtn = {
   fontFamily: FONT_BODY
 };
 
-// src/WordKeyButton.tsx
+// src/WordKeyModal.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
-var sizePx = { sm: 20, md: 28, lg: 38 };
-function WordKeyButton({
+function WordKeyModal({
   publishableKey,
+  open,
+  onClose,
   onSuccess,
+  mode = "login",
   onError,
-  size = "md",
-  label = "Word?",
   requestedFields,
   apiUrl = DEFAULT_API_URL
 }) {
-  const [open, setOpen] = (0, import_react.useState)(false);
   (0, import_react.useEffect)(() => {
     ensureFont();
   }, []);
@@ -442,56 +581,151 @@ function WordKeyButton({
     resumed.current = true;
     void consumePendingRedirect().then((r) => {
       if (!r) return;
+      if (r.pending.kind === "signup") {
+        const token = r.signup?.token;
+        if (!token) {
+          onError?.({
+            code: "signup_incomplete",
+            message: "Signup did not complete. Please try again."
+          });
+          return;
+        }
+        const claims = decodeToken(token);
+        onSuccess({
+          id: claims?.userId ?? "",
+          isNewUser: claims?.isNewUser ?? true,
+          authenticatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          token,
+          profile: r.pending.fields.length ? buildProfile(r.pending.fields, r.result.granted ? r.result.values : {}) : void 0
+        });
+        return;
+      }
       const profile = buildProfile(
         r.pending.fields,
         r.result.granted ? r.result.values : {}
       );
       onSuccess({
-        id: r.pending.userId,
-        isNewUser: r.pending.isNewUser,
+        id: r.pending.userId ?? "",
+        isNewUser: r.pending.isNewUser ?? false,
         authenticatedAt: (/* @__PURE__ */ new Date()).toISOString(),
         token: r.pending.token,
         profile
       });
     });
   }, []);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
-    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
-      "button",
-      {
-        onClick: () => setOpen(true),
-        style: {
-          background: "transparent",
-          border: "none",
-          padding: 0,
-          cursor: "pointer",
-          fontFamily: FONT_DISPLAY,
-          fontWeight: 600,
-          fontSize: sizePx[size],
-          lineHeight: 1
-        },
-        "aria-label": label,
-        children: [
-          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: { color: C.purple }, children: "Word" }),
-          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: { color: C.purpleL }, children: "?" })
-        ]
-      }
-    ),
-    open && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-      AuthModal,
-      {
-        publishableKey,
+  if (!open) return null;
+  const common = {
+    publishableKey,
+    apiUrl,
+    requestedFields,
+    onClose,
+    onSuccess: (u) => {
+      onClose();
+      onSuccess(u);
+    },
+    onError: (e) => onError?.(e)
+  };
+  return mode === "signup" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SignupModal, { ...common }) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AuthModal, { ...common });
+}
+function SignupModal({
+  publishableKey,
+  apiUrl,
+  requestedFields,
+  onClose,
+  onSuccess,
+  onError
+}) {
+  const fields = (0, import_react.useMemo)(
+    () => requestedFields ? resolveFields(requestedFields) : [],
+    [requestedFields]
+  );
+  const apiOrigin = (0, import_react.useMemo)(() => {
+    try {
+      return new URL(apiUrl).origin;
+    } catch {
+      return apiUrl;
+    }
+  }, [apiUrl]);
+  const [failed, setFailed] = (0, import_react.useState)(null);
+  const abortRef = (0, import_react.useRef)(null);
+  if (!abortRef.current) abortRef.current = new AbortController();
+  (0, import_react.useEffect)(() => () => abortRef.current?.abort(), []);
+  const started = (0, import_react.useRef)(false);
+  (0, import_react.useEffect)(() => {
+    if (started.current) return;
+    started.current = true;
+    const popup = openSignupWindow(apiUrl, publishableKey);
+    if (!popup) {
+      void beginSignupRedirect({
         apiUrl,
-        requestedFields,
-        onClose: () => setOpen(false),
-        onSuccess: (u) => {
-          setOpen(false);
-          onSuccess(u);
-        },
-        onError: (e) => onError?.(e)
+        requestId: newRequestId(),
+        publishableKey,
+        sdkDeviceId: getDeviceId(),
+        fields
+      });
+      return;
+    }
+    const requestId = newRequestId();
+    void (async () => {
+      const hs = await runSignupHandshake({
+        popup,
+        apiOrigin,
+        requestId,
+        publishableKey,
+        sdkDeviceId: getDeviceId(),
+        fields,
+        signal: abortRef.current?.signal
+      });
+      if (hs.cancelled) return;
+      if (hs.closed) {
+        onClose();
+        return;
       }
-    )
-  ] });
+      if (!hs.ok || !hs.token) {
+        setFailed("Signup could not be completed. Please try again.");
+        onError({
+          code: "signup_failed",
+          message: "Signup could not be completed"
+        });
+        return;
+      }
+      const claims = decodeToken(hs.token);
+      const finish = (profile) => onSuccess({
+        id: claims?.userId ?? "",
+        isNewUser: claims?.isNewUser ?? true,
+        authenticatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        token: hs.token,
+        profile
+      });
+      if (fields.length === 0) {
+        finish();
+        return;
+      }
+      const share = await runPopupFlow({
+        popup,
+        apiOrigin,
+        requestId,
+        publishableKey,
+        ticket: hs.profileTicket,
+        fields,
+        signal: abortRef.current?.signal
+      });
+      if (share.cancelled) return;
+      finish(buildProfile(fields, share.granted ? share.values : {}));
+    })();
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: overlay, role: "dialog", "aria-modal": "true", onClick: onClose, children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: panel, onClick: (e) => e.stopPropagation(), children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Header, {}),
+    failed ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ErrorText, { children: failed }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Row, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { style: ghostBtn, onClick: onClose, children: "Close" }) })
+    ] }) : /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { textAlign: "center", padding: "12px 0" }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {}),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("h3", { style: { fontFamily: FONT_DISPLAY, fontSize: 22, margin: "4px 0" }, children: "Get your word in the WordKey window" }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: { color: C.muted, fontSize: 13 }, children: "Finish setting up in the window that just opened. Closing it cancels \u2014 nothing is created without you." }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Row, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { style: ghostBtn, onClick: onClose, children: "Cancel" }) })
+    ] })
+  ] }) });
 }
 function AuthModal({
   publishableKey,
@@ -808,17 +1042,6 @@ function valuePresent(v) {
   if (typeof v === "string") return v.trim().length > 0;
   return Object.values(v).some((x) => x && String(x).trim().length > 0);
 }
-function decodeToken(token) {
-  try {
-    const part = token.split(".")[1];
-    if (!part) return null;
-    const b64 = part.replace(/-/g, "+").replace(/_/g, "/");
-    const json = typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("utf8");
-    return JSON.parse(json);
-  } catch {
-    return null;
-  }
-}
 function buildProfile(fields, granted) {
   const profile = {};
   const custom = {};
@@ -867,7 +1090,66 @@ function Spinner() {
     }
   );
 }
+
+// src/WordKeyButton.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var sizePx = { sm: 20, md: 28, lg: 38 };
+function WordKeyButton({
+  publishableKey,
+  onSuccess,
+  onError,
+  size = "md",
+  label,
+  mode = "login",
+  requestedFields,
+  apiUrl = DEFAULT_API_URL
+}) {
+  const [open, setOpen] = (0, import_react2.useState)(false);
+  (0, import_react2.useEffect)(() => {
+    ensureFont();
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "button",
+      {
+        onClick: () => setOpen(true),
+        style: {
+          background: "transparent",
+          border: "none",
+          padding: 0,
+          cursor: "pointer",
+          fontFamily: FONT_DISPLAY,
+          fontWeight: 600,
+          fontSize: sizePx[size],
+          lineHeight: 1
+        },
+        "aria-label": label ?? (mode === "signup" ? "Get your word" : "Word?"),
+        children: mode === "signup" ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { style: { color: C.purple }, children: "Get your " }),
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { style: { color: C.purpleL }, children: "word" })
+        ] }) : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { style: { color: C.purple }, children: "Word" }),
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { style: { color: C.purpleL }, children: "?" })
+        ] })
+      }
+    ),
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      WordKeyModal,
+      {
+        publishableKey,
+        open,
+        mode,
+        onClose: () => setOpen(false),
+        onSuccess,
+        onError,
+        requestedFields,
+        apiUrl
+      }
+    )
+  ] });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  WordKeyButton
+  WordKeyButton,
+  WordKeyModal
 });

package/dist/index.mjs

@@ -4,6 +4,9 @@ import {
 } from "./chunk-JWCQBSIQ.mjs";
 
 // src/WordKeyButton.tsx
+import { useEffect as useEffect2, useState as useState2 } from "react";
+
+// src/WordKeyModal.tsx
 import { useEffect, useMemo, useRef, useState } from "react";
 
 // src/fields.ts
@@ -70,6 +73,17 @@ var DeviceApprovalRequiredError = class extends Error {
     this.name = "DeviceApprovalRequiredError";
   }
 };
+function decodeToken(token) {
+  try {
+    const part = token.split(".")[1];
+    if (!part) return null;
+    const b64 = part.replace(/-/g, "+").replace(/_/g, "/");
+    const json = typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("utf8");
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
 async function verifyWord(apiUrl = DEFAULT_API_URL, publishableKey, word) {
   const wordHash = await hashWord(word);
   const res = await fetch(`${apiUrl}/api/auth/verify`, {
@@ -204,6 +218,7 @@ async function beginRedirectShare(input2) {
   const publicJwk = await crypto.subtle.exportKey("jwk", pair.publicKey);
   const privateKeyJwk = await crypto.subtle.exportKey("jwk", pair.privateKey);
   const pending = {
+    kind: "login",
     requestId: input2.requestId,
     userId: input2.userId,
     isNewUser: input2.isNewUser,
@@ -243,10 +258,12 @@ async function consumePendingRedirect() {
   }
   if (envelope.requestId !== pending.requestId) return null;
   sessionStorage.removeItem(PENDING_STORE);
-  if (envelope.granted !== true) {
-    return { pending, result: { granted: false, values: {} } };
+  if (!envelope.epk || !envelope.iv || !envelope.ct) {
+    if (envelope.granted !== true) {
+      return { pending, result: { granted: false, values: {} } };
+    }
+    return null;
   }
-  if (!envelope.epk || !envelope.iv || !envelope.ct) return null;
   try {
     const privateKey = await crypto.subtle.importKey(
       "jwk",
@@ -277,13 +294,135 @@ async function consumePendingRedirect() {
     const parsed = JSON.parse(new TextDecoder().decode(plain));
     return {
       pending,
-      result: { granted: true, values: parsed.values ?? {} }
+      result: {
+        granted: envelope.granted === true,
+        values: parsed.values ?? {}
+      },
+      signup: typeof parsed.signup?.token === "string" ? { token: parsed.signup.token } : void 0
     };
   } catch {
     return null;
   }
 }
 
+// src/signup-popup.ts
+var SIGNUP_TIMEOUT_MS = 20 * 60 * 1e3;
+function openSignupWindow(apiUrl, publishableKey) {
+  const w = 440;
+  const h = 700;
+  const left = Math.max(0, (window.screenX ?? 0) + (window.outerWidth - w) / 2);
+  const top = Math.max(0, (window.screenY ?? 0) + (window.outerHeight - h) / 3);
+  try {
+    return window.open(
+      `${apiUrl}/welcome?wk_sdk=1&business=${encodeURIComponent(publishableKey)}`,
+      "wordkey-signup",
+      `popup=yes,width=${w},height=${h},left=${left},top=${top}`
+    );
+  } catch {
+    return null;
+  }
+}
+function runSignupHandshake(input2) {
+  const { popup, apiOrigin, requestId, signal } = input2;
+  return new Promise((resolve) => {
+    let settled = false;
+    const cleanup = () => {
+      window.removeEventListener("message", onMsg);
+      clearInterval(closedPoll);
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const finish = (r) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(r);
+    };
+    const onAbort = () => {
+      try {
+        popup.close();
+      } catch {
+      }
+      finish({ ok: false, cancelled: true });
+    };
+    const onMsg = (e) => {
+      if (e.origin !== apiOrigin || e.source !== popup) return;
+      const data = e.data;
+      if (!data || typeof data !== "object") return;
+      if (data.type === "wordkey:signup:ready") {
+        popup.postMessage(
+          {
+            type: "wordkey:signup:init",
+            requestId,
+            publishableKey: input2.publishableKey,
+            sdkDeviceId: input2.sdkDeviceId,
+            fields: input2.fields
+          },
+          apiOrigin
+        );
+      }
+      if (data.type === "wordkey:signup:result" && data.requestId === requestId) {
+        finish({
+          ok: data.ok === true && typeof data.token === "string",
+          token: typeof data.token === "string" ? data.token : void 0,
+          profileTicket: typeof data.profileTicket === "string" ? data.profileTicket : void 0
+        });
+      }
+    };
+    window.addEventListener("message", onMsg);
+    const closedPoll = setInterval(() => {
+      if (popup.closed) finish({ ok: false, closed: true });
+    }, 400);
+    const timer = setTimeout(
+      () => finish({ ok: false, closed: true }),
+      SIGNUP_TIMEOUT_MS
+    );
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort);
+    }
+  });
+}
+async function beginSignupRedirect(input2) {
+  const pair = await crypto.subtle.generateKey(
+    { name: "ECDH", namedCurve: "P-256" },
+    true,
+    ["deriveKey"]
+  );
+  const publicJwk = await crypto.subtle.exportKey("jwk", pair.publicKey);
+  const privateKeyJwk = await crypto.subtle.exportKey("jwk", pair.privateKey);
+  const pending = {
+    kind: "signup",
+    requestId: input2.requestId,
+    fields: input2.fields,
+    privateKeyJwk
+  };
+  sessionStorage.setItem(PENDING_STORE, JSON.stringify(pending));
+  const returnUrl = window.location.href.split("#")[0];
+  const request = {
+    v: 1,
+    requestId: input2.requestId,
+    publishableKey: input2.publishableKey,
+    origin: window.location.origin,
+    returnUrl,
+    sdkPub: publicJwk,
+    sdkDeviceId: input2.sdkDeviceId,
+    fields: input2.fields
+  };
+  const b64 = encodeSignupRequest(request);
+  window.location.assign(
+    `${input2.apiUrl}/welcome?wk_sdk=1&business=${encodeURIComponent(
+      input2.publishableKey
+    )}#wksignup=${b64}`
+  );
+}
+function encodeSignupRequest(value) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
 // src/fonts.ts
 var loaded = false;
 function ensureFont() {
@@ -380,19 +519,18 @@ var ghostBtn = {
   fontFamily: FONT_BODY
 };
 
-// src/WordKeyButton.tsx
+// src/WordKeyModal.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-var sizePx = { sm: 20, md: 28, lg: 38 };
-function WordKeyButton({
+function WordKeyModal({
   publishableKey,
+  open,
+  onClose,
   onSuccess,
+  mode = "login",
   onError,
-  size = "md",
-  label = "Word?",
   requestedFields,
   apiUrl = DEFAULT_API_URL
 }) {
-  const [open, setOpen] = useState(false);
   useEffect(() => {
     ensureFont();
   }, []);
@@ -402,56 +540,151 @@ function WordKeyButton({
     resumed.current = true;
     void consumePendingRedirect().then((r) => {
       if (!r) return;
+      if (r.pending.kind === "signup") {
+        const token = r.signup?.token;
+        if (!token) {
+          onError?.({
+            code: "signup_incomplete",
+            message: "Signup did not complete. Please try again."
+          });
+          return;
+        }
+        const claims = decodeToken(token);
+        onSuccess({
+          id: claims?.userId ?? "",
+          isNewUser: claims?.isNewUser ?? true,
+          authenticatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          token,
+          profile: r.pending.fields.length ? buildProfile(r.pending.fields, r.result.granted ? r.result.values : {}) : void 0
+        });
+        return;
+      }
       const profile = buildProfile(
         r.pending.fields,
         r.result.granted ? r.result.values : {}
       );
       onSuccess({
-        id: r.pending.userId,
-        isNewUser: r.pending.isNewUser,
+        id: r.pending.userId ?? "",
+        isNewUser: r.pending.isNewUser ?? false,
         authenticatedAt: (/* @__PURE__ */ new Date()).toISOString(),
         token: r.pending.token,
         profile
       });
     });
   }, []);
-  return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsxs(
-      "button",
-      {
-        onClick: () => setOpen(true),
-        style: {
-          background: "transparent",
-          border: "none",
-          padding: 0,
-          cursor: "pointer",
-          fontFamily: FONT_DISPLAY,
-          fontWeight: 600,
-          fontSize: sizePx[size],
-          lineHeight: 1
-        },
-        "aria-label": label,
-        children: [
-          /* @__PURE__ */ jsx("span", { style: { color: C.purple }, children: "Word" }),
-          /* @__PURE__ */ jsx("span", { style: { color: C.purpleL }, children: "?" })
-        ]
-      }
-    ),
-    open && /* @__PURE__ */ jsx(
-      AuthModal,
-      {
-        publishableKey,
+  if (!open) return null;
+  const common = {
+    publishableKey,
+    apiUrl,
+    requestedFields,
+    onClose,
+    onSuccess: (u) => {
+      onClose();
+      onSuccess(u);
+    },
+    onError: (e) => onError?.(e)
+  };
+  return mode === "signup" ? /* @__PURE__ */ jsx(SignupModal, { ...common }) : /* @__PURE__ */ jsx(AuthModal, { ...common });
+}
+function SignupModal({
+  publishableKey,
+  apiUrl,
+  requestedFields,
+  onClose,
+  onSuccess,
+  onError
+}) {
+  const fields = useMemo(
+    () => requestedFields ? resolveFields(requestedFields) : [],
+    [requestedFields]
+  );
+  const apiOrigin = useMemo(() => {
+    try {
+      return new URL(apiUrl).origin;
+    } catch {
+      return apiUrl;
+    }
+  }, [apiUrl]);
+  const [failed, setFailed] = useState(null);
+  const abortRef = useRef(null);
+  if (!abortRef.current) abortRef.current = new AbortController();
+  useEffect(() => () => abortRef.current?.abort(), []);
+  const started = useRef(false);
+  useEffect(() => {
+    if (started.current) return;
+    started.current = true;
+    const popup = openSignupWindow(apiUrl, publishableKey);
+    if (!popup) {
+      void beginSignupRedirect({
         apiUrl,
-        requestedFields,
-        onClose: () => setOpen(false),
-        onSuccess: (u) => {
-          setOpen(false);
-          onSuccess(u);
-        },
-        onError: (e) => onError?.(e)
+        requestId: newRequestId(),
+        publishableKey,
+        sdkDeviceId: getDeviceId(),
+        fields
+      });
+      return;
+    }
+    const requestId = newRequestId();
+    void (async () => {
+      const hs = await runSignupHandshake({
+        popup,
+        apiOrigin,
+        requestId,
+        publishableKey,
+        sdkDeviceId: getDeviceId(),
+        fields,
+        signal: abortRef.current?.signal
+      });
+      if (hs.cancelled) return;
+      if (hs.closed) {
+        onClose();
+        return;
       }
-    )
-  ] });
+      if (!hs.ok || !hs.token) {
+        setFailed("Signup could not be completed. Please try again.");
+        onError({
+          code: "signup_failed",
+          message: "Signup could not be completed"
+        });
+        return;
+      }
+      const claims = decodeToken(hs.token);
+      const finish = (profile) => onSuccess({
+        id: claims?.userId ?? "",
+        isNewUser: claims?.isNewUser ?? true,
+        authenticatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        token: hs.token,
+        profile
+      });
+      if (fields.length === 0) {
+        finish();
+        return;
+      }
+      const share = await runPopupFlow({
+        popup,
+        apiOrigin,
+        requestId,
+        publishableKey,
+        ticket: hs.profileTicket,
+        fields,
+        signal: abortRef.current?.signal
+      });
+      if (share.cancelled) return;
+      finish(buildProfile(fields, share.granted ? share.values : {}));
+    })();
+  }, []);
+  return /* @__PURE__ */ jsx("div", { style: overlay, role: "dialog", "aria-modal": "true", onClick: onClose, children: /* @__PURE__ */ jsxs("div", { style: panel, onClick: (e) => e.stopPropagation(), children: [
+    /* @__PURE__ */ jsx(Header, {}),
+    failed ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(ErrorText, { children: failed }),
+      /* @__PURE__ */ jsx(Row, { children: /* @__PURE__ */ jsx("button", { style: ghostBtn, onClick: onClose, children: "Close" }) })
+    ] }) : /* @__PURE__ */ jsxs("div", { style: { textAlign: "center", padding: "12px 0" }, children: [
+      /* @__PURE__ */ jsx(Spinner, {}),
+      /* @__PURE__ */ jsx("h3", { style: { fontFamily: FONT_DISPLAY, fontSize: 22, margin: "4px 0" }, children: "Get your word in the WordKey window" }),
+      /* @__PURE__ */ jsx("p", { style: { color: C.muted, fontSize: 13 }, children: "Finish setting up in the window that just opened. Closing it cancels \u2014 nothing is created without you." }),
+      /* @__PURE__ */ jsx(Row, { children: /* @__PURE__ */ jsx("button", { style: ghostBtn, onClick: onClose, children: "Cancel" }) })
+    ] })
+  ] }) });
 }
 function AuthModal({
   publishableKey,
@@ -768,17 +1001,6 @@ function valuePresent(v) {
   if (typeof v === "string") return v.trim().length > 0;
   return Object.values(v).some((x) => x && String(x).trim().length > 0);
 }
-function decodeToken(token) {
-  try {
-    const part = token.split(".")[1];
-    if (!part) return null;
-    const b64 = part.replace(/-/g, "+").replace(/_/g, "/");
-    const json = typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("utf8");
-    return JSON.parse(json);
-  } catch {
-    return null;
-  }
-}
 function buildProfile(fields, granted) {
   const profile = {};
   const custom = {};
@@ -827,6 +1049,65 @@ function Spinner() {
     }
   );
 }
+
+// src/WordKeyButton.tsx
+import { Fragment as Fragment2, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var sizePx = { sm: 20, md: 28, lg: 38 };
+function WordKeyButton({
+  publishableKey,
+  onSuccess,
+  onError,
+  size = "md",
+  label,
+  mode = "login",
+  requestedFields,
+  apiUrl = DEFAULT_API_URL
+}) {
+  const [open, setOpen] = useState2(false);
+  useEffect2(() => {
+    ensureFont();
+  }, []);
+  return /* @__PURE__ */ jsxs2(Fragment2, { children: [
+    /* @__PURE__ */ jsx2(
+      "button",
+      {
+        onClick: () => setOpen(true),
+        style: {
+          background: "transparent",
+          border: "none",
+          padding: 0,
+          cursor: "pointer",
+          fontFamily: FONT_DISPLAY,
+          fontWeight: 600,
+          fontSize: sizePx[size],
+          lineHeight: 1
+        },
+        "aria-label": label ?? (mode === "signup" ? "Get your word" : "Word?"),
+        children: mode === "signup" ? /* @__PURE__ */ jsxs2(Fragment2, { children: [
+          /* @__PURE__ */ jsx2("span", { style: { color: C.purple }, children: "Get your " }),
+          /* @__PURE__ */ jsx2("span", { style: { color: C.purpleL }, children: "word" })
+        ] }) : /* @__PURE__ */ jsxs2(Fragment2, { children: [
+          /* @__PURE__ */ jsx2("span", { style: { color: C.purple }, children: "Word" }),
+          /* @__PURE__ */ jsx2("span", { style: { color: C.purpleL }, children: "?" })
+        ] })
+      }
+    ),
+    /* @__PURE__ */ jsx2(
+      WordKeyModal,
+      {
+        publishableKey,
+        open,
+        mode,
+        onClose: () => setOpen(false),
+        onSuccess,
+        onError,
+        requestedFields,
+        apiUrl
+      }
+    )
+  ] });
+}
 export {
-  WordKeyButton
+  WordKeyButton,
+  WordKeyModal
 };

package/dist/server.d.mts

@@ -1,5 +1,5 @@
-import { W as WordKeyUser, b as AuthEvent } from './types-B4z3Zton.mjs';
-export { A as Address, a as WordKeyError, c as WordKeyProfile } from './types-B4z3Zton.mjs';
+import { W as WordKeyUser, c as AuthEvent } from './types-WFjkfsy6.mjs';
+export { A as Address, a as WordKeyError, d as WordKeyProfile } from './types-WFjkfsy6.mjs';
 
 interface WordKeyConfig {
     /** Your SECRET key (wk_sec_...). Server-only — never ship it to a browser. */

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { W as WordKeyUser, b as AuthEvent } from './types-B4z3Zton.js';
-export { A as Address, a as WordKeyError, c as WordKeyProfile } from './types-B4z3Zton.js';
+import { W as WordKeyUser, c as AuthEvent } from './types-WFjkfsy6.js';
+export { A as Address, a as WordKeyError, d as WordKeyProfile } from './types-WFjkfsy6.js';
 
 interface WordKeyConfig {
     /** Your SECRET key (wk_sec_...). Server-only — never ship it to a browser. */

package/dist/{types-B4z3Zton.d.mts → types-WFjkfsy6.d.mts}

@@ -45,6 +45,13 @@ interface WordKeyUser {
     /** Present only when requestedFields were granted; unfilled fields omitted. */
     profile?: WordKeyProfile;
 }
+/**
+ * The two entry points of the protocol. "login" is Word? — a returning user
+ * types the word they already have. "signup" is Get-your-word — WordKey's
+ * first-party onboarding assigns a word, enrolls the device, and signs the
+ * new user in to your site in one flow. Both deliver the same WordKeyUser.
+ */
+type WordKeyMode = "login" | "signup";
 interface WordKeyError {
     code: string;
     message: string;
@@ -55,4 +62,4 @@ interface AuthEvent {
     at: string | null;
 }
 
-export type { Address as A, CustomField as C, ProfileField as P, RequestedField as R, WordKeyUser as W, WordKeyError as a, AuthEvent as b, WordKeyProfile as c };
+export type { Address as A, CustomField as C, ProfileField as P, RequestedField as R, WordKeyUser as W, WordKeyError as a, WordKeyMode as b, AuthEvent as c, WordKeyProfile as d };

package/dist/{types-B4z3Zton.d.ts → types-WFjkfsy6.d.ts}

@@ -45,6 +45,13 @@ interface WordKeyUser {
     /** Present only when requestedFields were granted; unfilled fields omitted. */
     profile?: WordKeyProfile;
 }
+/**
+ * The two entry points of the protocol. "login" is Word? — a returning user
+ * types the word they already have. "signup" is Get-your-word — WordKey's
+ * first-party onboarding assigns a word, enrolls the device, and signs the
+ * new user in to your site in one flow. Both deliver the same WordKeyUser.
+ */
+type WordKeyMode = "login" | "signup";
 interface WordKeyError {
     code: string;
     message: string;
@@ -55,4 +62,4 @@ interface AuthEvent {
     at: string | null;
 }
 
-export type { Address as A, CustomField as C, ProfileField as P, RequestedField as R, WordKeyUser as W, WordKeyError as a, AuthEvent as b, WordKeyProfile as c };
+export type { Address as A, CustomField as C, ProfileField as P, RequestedField as R, WordKeyUser as W, WordKeyError as a, WordKeyMode as b, AuthEvent as c, WordKeyProfile as d };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wordkey/sdk",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Add the Word? button to your site in one afternoon. One word. Every door.",
   "license": "SEE LICENSE IN LICENSE",
   "main": "./dist/index.js",