@wordkey/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 Agostino Industries. All rights reserved.
+
+This SDK may be used solely to integrate with the WordKey platform
+(https://wordkey.app) under the terms of your WordKey partner or
+merchant agreement. Redistribution or modification outside those
+terms is not permitted.

package/README.md

@@ -0,0 +1,103 @@
+# @wordkey/sdk
+
+Add the **Word?** button to your site in one afternoon. One word. Every door.
+
+## Install
+
+```bash
+npm install @wordkey/sdk
+```
+
+## 1. Add the button
+
+```jsx
+import { WordKeyButton } from "@wordkey/sdk";
+
+export function LoginPage() {
+  return (
+    <WordKeyButton
+      publishableKey="wk_pub_xxxxxxxxxxxx"
+      onSuccess={(user) => console.log("Authenticated:", user)}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+### Request profile fields (optional)
+
+Ask for autofill data the user keeps on their device. After the word is
+verified, WordKey opens a small first-party consent window on
+`app.wordkey.app` (a full-page redirect if the popup is blocked) where the
+user sees exactly what your site will receive, fills in anything missing, and
+approves. The granted values are then handed to your page — directly, never
+through WordKey's servers. Approval is remembered per site, so repeat visits
+skip straight through.
+
+```jsx
+<WordKeyButton
+  publishableKey="wk_pub_xxxx"
+  requestedFields={[
+    "name",
+    "email",
+    "shipping_address",
+    { key: "height", label: "Height", type: "text", required: true },
+  ]}
+  onSuccess={(user) => {
+    // user.profile?.name, user.profile?.email,
+    // user.profile?.shippingAddress, user.profile?.custom?.height
+    // user.profile is undefined if the user declined to share.
+  }}
+/>
+```
+
+Standard fields: `name`, `email`, `phone`, `shipping_address`. Custom fields are
+`{ key, label, type: "text" | "date" | "number" | "select", required?, options? }`.
+Fields the user hasn't stored are offered as inline inputs in the consent
+window, with a "save for next time" option.
+
+Because the consent window is a top-level first-party page (not a third-party
+iframe), the flow works in Safari and Chrome even with third-party storage
+partitioning and cookie blocking fully enabled. If the popup is blocked, the
+SDK automatically falls back to a full-page redirect and resumes your
+`onSuccess` when the user returns — no extra integration work.
+
+## 2. Verify server-side
+
+```ts
+import { WordKey } from "@wordkey/sdk/server";
+
+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);
+  // user.id        — permanent unique id for this WordKey user
+  // user.isNewUser — true if this is their first authentication
+}
+```
+
+## Webhooks
+
+WordKey signs webhook deliveries with your secret key (HMAC-SHA256) in the
+`X-WordKey-Signature` header.
+
+```ts
+const ok = await wk.verifyWebhook(rawBody, req.headers.get("x-wordkey-signature")!);
+```
+
+Event types: `auth.success`, `auth.failed`, `user.word_changed`, `user.disconnected`.
+
+## Server API
+
+```ts
+wk.verify(token)            // → WordKeyUser
+wk.userExists(userId)       // → boolean
+wk.getUserEvents(userId)    // → AuthEvent[]
+wk.verifyWebhook(body, sig) // → boolean
+```
+
+## Testing against a local protocol host
+
+Both `WordKeyButton` and `WordKey` accept an `apiUrl` to point at a non-production
+host (e.g. `http://localhost:3001`).

package/dist/chunk-JWCQBSIQ.mjs

@@ -0,0 +1,13 @@
+// src/types.ts
+var FIELD_LABELS = {
+  name: "Full name",
+  email: "Email address",
+  phone: "Phone number",
+  shipping_address: "Shipping address"
+};
+var DEFAULT_API_URL = "https://app.wordkey.app";
+
+export {
+  FIELD_LABELS,
+  DEFAULT_API_URL
+};

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+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';
+
+interface WordKeyButtonProps {
+    publishableKey: string;
+    onSuccess: (user: WordKeyUser) => void;
+    onError?: (error: WordKeyError) => void;
+    theme?: "dark" | "light" | "auto";
+    size?: "sm" | "md" | "lg";
+    label?: string;
+    /** 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;
+
+export { RequestedField, WordKeyButton, type WordKeyButtonProps, WordKeyError, WordKeyUser };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+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';
+
+interface WordKeyButtonProps {
+    publishableKey: string;
+    onSuccess: (user: WordKeyUser) => void;
+    onError?: (error: WordKeyError) => void;
+    theme?: "dark" | "light" | "auto";
+    size?: "sm" | "md" | "lg";
+    label?: string;
+    /** 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;
+
+export { RequestedField, WordKeyButton, type WordKeyButtonProps, WordKeyError, WordKeyUser };