@wordkey/sdk 1.0.0

package/dist/server.d.mts

@@ -0,0 +1,48 @@
+import { W as WordKeyUser, b as AuthEvent } from './types-Be6QFOjD.mjs';
+export { A as Address, a as WordKeyError, c as WordKeyProfile } from './types-Be6QFOjD.mjs';
+
+interface WordKeyConfig {
+    /** Your SECRET key (wk_sec_...). Server-only — never ship it to a browser. */
+    secretKey: string;
+    /** Override the protocol host (defaults to app.wordkey.app). */
+    apiUrl?: string;
+}
+/**
+ * Server-side WordKey client. Businesses use this in their backend to verify
+ * tokens received from the WordKeyButton and to check webhook signatures.
+ * Authenticated with the SECRET key — keep it out of client bundles.
+ */
+declare class WordKey {
+    private secretKey;
+    private apiUrl;
+    constructor(config: WordKeyConfig);
+    private post;
+    /** Verify a single-use token from the client. Throws if invalid/expired/used. */
+    verify(token: string): Promise<WordKeyUser>;
+    /** Check whether a WordKey user id exists. */
+    userExists(userId: string): Promise<boolean>;
+    /** Recent authentication events for a user at this business. */
+    getUserEvents(userId: string): Promise<AuthEvent[]>;
+    /**
+     * Verify a webhook signature. `signature` is the X-WordKey-Signature header;
+     * `payload` is the raw request body. Signed with your SECRET key (HMAC-SHA256).
+     */
+    verifyWebhook(payload: string, signature: string): Promise<boolean>;
+}
+
+type WordKeyWebhookEvent = {
+    type: "auth.success";
+    user: WordKeyUser;
+    isNewUser: boolean;
+} | {
+    type: "auth.failed";
+    reason: string;
+} | {
+    type: "user.word_changed";
+    userId: string;
+} | {
+    type: "user.disconnected";
+    userId: string;
+};
+
+export { AuthEvent, WordKey, type WordKeyConfig, WordKeyUser, type WordKeyWebhookEvent };

package/dist/server.d.ts

@@ -0,0 +1,48 @@
+import { W as WordKeyUser, b as AuthEvent } from './types-Be6QFOjD.js';
+export { A as Address, a as WordKeyError, c as WordKeyProfile } from './types-Be6QFOjD.js';
+
+interface WordKeyConfig {
+    /** Your SECRET key (wk_sec_...). Server-only — never ship it to a browser. */
+    secretKey: string;
+    /** Override the protocol host (defaults to app.wordkey.app). */
+    apiUrl?: string;
+}
+/**
+ * Server-side WordKey client. Businesses use this in their backend to verify
+ * tokens received from the WordKeyButton and to check webhook signatures.
+ * Authenticated with the SECRET key — keep it out of client bundles.
+ */
+declare class WordKey {
+    private secretKey;
+    private apiUrl;
+    constructor(config: WordKeyConfig);
+    private post;
+    /** Verify a single-use token from the client. Throws if invalid/expired/used. */
+    verify(token: string): Promise<WordKeyUser>;
+    /** Check whether a WordKey user id exists. */
+    userExists(userId: string): Promise<boolean>;
+    /** Recent authentication events for a user at this business. */
+    getUserEvents(userId: string): Promise<AuthEvent[]>;
+    /**
+     * Verify a webhook signature. `signature` is the X-WordKey-Signature header;
+     * `payload` is the raw request body. Signed with your SECRET key (HMAC-SHA256).
+     */
+    verifyWebhook(payload: string, signature: string): Promise<boolean>;
+}
+
+type WordKeyWebhookEvent = {
+    type: "auth.success";
+    user: WordKeyUser;
+    isNewUser: boolean;
+} | {
+    type: "auth.failed";
+    reason: string;
+} | {
+    type: "user.word_changed";
+    userId: string;
+} | {
+    type: "user.disconnected";
+    userId: string;
+};
+
+export { AuthEvent, WordKey, type WordKeyConfig, WordKeyUser, type WordKeyWebhookEvent };

package/dist/server.js

@@ -0,0 +1,106 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  WordKey: () => WordKey
+});
+module.exports = __toCommonJS(server_exports);
+
+// src/types.ts
+var DEFAULT_API_URL = "https://app.wordkey.app";
+
+// src/server.ts
+var WordKey = class {
+  secretKey;
+  apiUrl;
+  constructor(config) {
+    if (!config.secretKey) throw new Error("WordKey: secretKey is required");
+    this.secretKey = config.secretKey;
+    this.apiUrl = config.apiUrl ?? DEFAULT_API_URL;
+  }
+  async post(path, body) {
+    const res = await fetch(`${this.apiUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.secretKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    const json = await res.json();
+    if (!res.ok) {
+      throw new Error(json?.error?.message ?? `WordKey request failed (${res.status})`);
+    }
+    return json;
+  }
+  /** Verify a single-use token from the client. Throws if invalid/expired/used. */
+  async verify(token) {
+    const res = await this.post("/api/auth/token-verify", { token });
+    return {
+      id: res.userId,
+      isNewUser: res.isNewUser,
+      authenticatedAt: res.authenticatedAt
+    };
+  }
+  /** Check whether a WordKey user id exists. */
+  async userExists(userId) {
+    const res = await this.post("/api/sdk/user-exists", {
+      userId
+    });
+    return res.exists;
+  }
+  /** Recent authentication events for a user at this business. */
+  async getUserEvents(userId) {
+    const res = await this.post("/api/sdk/user-events", {
+      userId
+    });
+    return res.events;
+  }
+  /**
+   * Verify a webhook signature. `signature` is the X-WordKey-Signature header;
+   * `payload` is the raw request body. Signed with your SECRET key (HMAC-SHA256).
+   */
+  async verifyWebhook(payload, signature) {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      new TextEncoder().encode(this.secretKey),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const sig = await crypto.subtle.sign(
+      "HMAC",
+      key,
+      new TextEncoder().encode(payload)
+    );
+    const expected = Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    if (expected.length !== signature.length) return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++) {
+      diff |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+    }
+    return diff === 0;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WordKey
+});

package/dist/server.mjs

@@ -0,0 +1,80 @@
+import {
+  DEFAULT_API_URL
+} from "./chunk-JWCQBSIQ.mjs";
+
+// src/server.ts
+var WordKey = class {
+  secretKey;
+  apiUrl;
+  constructor(config) {
+    if (!config.secretKey) throw new Error("WordKey: secretKey is required");
+    this.secretKey = config.secretKey;
+    this.apiUrl = config.apiUrl ?? DEFAULT_API_URL;
+  }
+  async post(path, body) {
+    const res = await fetch(`${this.apiUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.secretKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    const json = await res.json();
+    if (!res.ok) {
+      throw new Error(json?.error?.message ?? `WordKey request failed (${res.status})`);
+    }
+    return json;
+  }
+  /** Verify a single-use token from the client. Throws if invalid/expired/used. */
+  async verify(token) {
+    const res = await this.post("/api/auth/token-verify", { token });
+    return {
+      id: res.userId,
+      isNewUser: res.isNewUser,
+      authenticatedAt: res.authenticatedAt
+    };
+  }
+  /** Check whether a WordKey user id exists. */
+  async userExists(userId) {
+    const res = await this.post("/api/sdk/user-exists", {
+      userId
+    });
+    return res.exists;
+  }
+  /** Recent authentication events for a user at this business. */
+  async getUserEvents(userId) {
+    const res = await this.post("/api/sdk/user-events", {
+      userId
+    });
+    return res.events;
+  }
+  /**
+   * Verify a webhook signature. `signature` is the X-WordKey-Signature header;
+   * `payload` is the raw request body. Signed with your SECRET key (HMAC-SHA256).
+   */
+  async verifyWebhook(payload, signature) {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      new TextEncoder().encode(this.secretKey),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const sig = await crypto.subtle.sign(
+      "HMAC",
+      key,
+      new TextEncoder().encode(payload)
+    );
+    const expected = Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    if (expected.length !== signature.length) return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++) {
+      diff |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+    }
+    return diff === 0;
+  }
+};
+export {
+  WordKey
+};

package/dist/types-Be6QFOjD.d.mts

@@ -0,0 +1,49 @@
+interface Address {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+}
+interface WordKeyProfile {
+    name?: string;
+    email?: string;
+    phone?: string;
+    shippingAddress?: Address;
+    /** Site-defined custom fields, keyed by the field key the site requested. */
+    custom?: Record<string, string>;
+}
+/** Standard profile fields a business may request via `requestedFields`. */
+type ProfileField = "name" | "email" | "phone" | "shipping_address";
+/** A site-defined custom field. Stored on device keyed by `key`, reusable. */
+interface CustomField {
+    key: string;
+    label: string;
+    type: "text" | "date" | "number" | "select";
+    required?: boolean;
+    /** Options for `type: "select"`. */
+    options?: string[];
+}
+/** Each requested field is either a standard field name or a custom descriptor. */
+type RequestedField = ProfileField | CustomField;
+interface WordKeyUser {
+    /** Permanent unique WordKey user id. */
+    id: string;
+    /** True on the user's first-ever authentication (i.e. account creation). */
+    isNewUser: boolean;
+    authenticatedAt: string;
+    /** Present only when requestedFields were granted; unfilled fields omitted. */
+    profile?: WordKeyProfile;
+}
+interface WordKeyError {
+    code: string;
+    message: string;
+}
+interface AuthEvent {
+    type: string;
+    deviceType: string | null;
+    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 };

package/dist/types-Be6QFOjD.d.ts

@@ -0,0 +1,49 @@
+interface Address {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+}
+interface WordKeyProfile {
+    name?: string;
+    email?: string;
+    phone?: string;
+    shippingAddress?: Address;
+    /** Site-defined custom fields, keyed by the field key the site requested. */
+    custom?: Record<string, string>;
+}
+/** Standard profile fields a business may request via `requestedFields`. */
+type ProfileField = "name" | "email" | "phone" | "shipping_address";
+/** A site-defined custom field. Stored on device keyed by `key`, reusable. */
+interface CustomField {
+    key: string;
+    label: string;
+    type: "text" | "date" | "number" | "select";
+    required?: boolean;
+    /** Options for `type: "select"`. */
+    options?: string[];
+}
+/** Each requested field is either a standard field name or a custom descriptor. */
+type RequestedField = ProfileField | CustomField;
+interface WordKeyUser {
+    /** Permanent unique WordKey user id. */
+    id: string;
+    /** True on the user's first-ever authentication (i.e. account creation). */
+    isNewUser: boolean;
+    authenticatedAt: string;
+    /** Present only when requestedFields were granted; unfilled fields omitted. */
+    profile?: WordKeyProfile;
+}
+interface WordKeyError {
+    code: string;
+    message: string;
+}
+interface AuthEvent {
+    type: string;
+    deviceType: string | null;
+    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 };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@wordkey/sdk",
+  "version": "1.0.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",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.mts",
+        "default": "./dist/server.mjs"
+      },
+      "require": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://wordkey.app",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@types/qrcode": "^1.5.5",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4"
+  }
+}