@wordkey/sdk 1.0.0 → 1.1.0

package/README.md

@@ -10,16 +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={(user) => console.log("Authenticated:", user)}
-      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}
+      />
+    </>
   );
 }
 ```
@@ -64,6 +125,10 @@ SDK automatically falls back to a full-page redirect and resumes your
 
 ## 2. Verify server-side
 
+The token your page received in `onSuccess` is single-use and business-bound:
+your server exchanges it with WordKey exactly once, over an authenticated
+server-to-server call. A replayed, expired, or foreign-business token throws.
+
 ```ts
 import { WordKey } from "@wordkey/sdk/server";
 
@@ -71,9 +136,10 @@ const wk = new WordKey({ secretKey: process.env.WORDKEY_SECRET_KEY! });
 
 export async function POST(req: Request) {
   const { token } = await req.json();
-  const user = await wk.verify(token);
+  const user = await wk.verify(token); // throws if invalid, reused, or expired
   // user.id        — permanent unique id for this WordKey user
   // user.isNewUser — true if this is their first authentication
+  // Safe to create your session for user.id now.
 }
 ```
 

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-Be6QFOjD.mjs';
-export { A as Address, b as AuthEvent, C as CustomField, P as ProfileField, c as WordKeyProfile } from './types-Be6QFOjD.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-Be6QFOjD.js';
-export { A as Address, b as AuthEvent, C as CustomField, P as ProfileField, c as WordKeyProfile } from './types-Be6QFOjD.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 };