@optare/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Optare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @optare/client
+
+Headless, framework-agnostic client SDK for Optare. The entire integration
+contract is one string — a publishable key (`pk_live_…`).
+
+```ts
+import { createOptareClient } from "@optare/client";
+
+const { auth, config } = await createOptareClient({
+  publishableKey: "pk_live_xxx",
+  // baseURL / configURL optional — defaults to the hosted Optare API
+});
+
+// `auth` is a better-auth client
+await auth.signIn.email({ email, password });
+const { data: session } = await auth.getSession();
+
+// `config` is the resolved endpoint + white-label branding
+config.baseURL;          // where the auth API lives
+config.branding.name;    // customer's org name
+config.branding.logoUrl; // customer's logo
+```
+
+## What it does
+
+1. `resolveOptareConfig()` calls `GET /api/public/config?pk=…` and learns the
+   auth API origin and the project's branding. `pk_live_` is not a secret, so
+   this is safe from a browser.
+2. `createOptareClient()` builds a better-auth client pointed at that origin
+   with the Optare plugin set (organization, 2FA, email OTP, magic link,
+   multi-session, JWT) and the publishable key attached to every request.
+
+For SSR, call `resolveOptareConfig()` on the server and pass the result back as
+`bootstrap` to skip the client-side fetch.
+
+## Server-side use
+
+For `sk_live_` management calls or offline JWT verification, use
+[`@optare/node`](../node) instead — this package is for the front end.

package/dist/index.cjs

@@ -0,0 +1,147 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_AUTH_METHODS: () => DEFAULT_AUTH_METHODS,
+  DEFAULT_OPTARE_ORIGIN: () => DEFAULT_OPTARE_ORIGIN,
+  OptareConfigError: () => OptareConfigError,
+  createOptareClient: () => createOptareClient,
+  resolveOptareConfig: () => resolveOptareConfig
+});
+module.exports = __toCommonJS(index_exports);
+var import_client = require("better-auth/client");
+var import_plugins = require("better-auth/client/plugins");
+var DEFAULT_OPTARE_ORIGIN = "https://id.optare.one";
+var DEFAULT_AUTH_METHODS = {
+  emailPassword: true,
+  magicLink: false,
+  emailOtp: false,
+  sso: false,
+  passkey: false,
+  social: []
+};
+var PUBLISHABLE_KEY_PREFIX = "pk_live_";
+var OptareConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OptareConfigError";
+  }
+};
+function assertPublishableKey(key) {
+  if (!key || !key.startsWith(PUBLISHABLE_KEY_PREFIX)) {
+    throw new OptareConfigError(
+      `Invalid publishable key \u2014 expected a "${PUBLISHABLE_KEY_PREFIX}\u2026" string`
+    );
+  }
+}
+async function resolveOptareConfig(config) {
+  assertPublishableKey(config.publishableKey);
+  if (config.bootstrap) {
+    return {
+      ...config.bootstrap,
+      authMethods: normalizeAuthMethods(config.bootstrap.authMethods)
+    };
+  }
+  const doFetch = config.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    throw new OptareConfigError(
+      "No fetch implementation available \u2014 pass `fetch` in the config"
+    );
+  }
+  const origin = (config.configURL ?? config.baseURL ?? DEFAULT_OPTARE_ORIGIN).replace(/\/+$/, "");
+  const url = `${origin}/api/public/config?pk=${encodeURIComponent(config.publishableKey)}`;
+  let res;
+  try {
+    res = await doFetch(url, { headers: { accept: "application/json" } });
+  } catch (cause) {
+    throw new OptareConfigError(
+      `Could not reach the Optare config endpoint at ${origin}: ${cause.message}`
+    );
+  }
+  if (res.status === 404) {
+    throw new OptareConfigError("Publishable key was not recognised by the server");
+  }
+  if (!res.ok) {
+    throw new OptareConfigError(
+      `Config endpoint returned ${res.status} ${res.statusText}`
+    );
+  }
+  const body = await res.json();
+  if (!body.baseURL || !body.branding || !body.project) {
+    throw new OptareConfigError("Config endpoint returned an unexpected shape");
+  }
+  return {
+    baseURL: config.baseURL ?? body.baseURL,
+    project: body.project,
+    branding: body.branding,
+    authMethods: normalizeAuthMethods(body.authMethods)
+  };
+}
+function normalizeAuthMethods(raw) {
+  const known = [
+    "google",
+    "github",
+    "microsoft",
+    "facebook",
+    "twitter"
+  ];
+  return {
+    emailPassword: raw?.emailPassword ?? DEFAULT_AUTH_METHODS.emailPassword,
+    magicLink: raw?.magicLink ?? DEFAULT_AUTH_METHODS.magicLink,
+    emailOtp: raw?.emailOtp ?? DEFAULT_AUTH_METHODS.emailOtp,
+    sso: raw?.sso ?? DEFAULT_AUTH_METHODS.sso,
+    passkey: raw?.passkey ?? DEFAULT_AUTH_METHODS.passkey,
+    social: Array.isArray(raw?.social) ? known.filter((p) => raw.social.includes(p)) : DEFAULT_AUTH_METHODS.social
+  };
+}
+function optarePlugins() {
+  return [
+    (0, import_plugins.organizationClient)(),
+    (0, import_plugins.twoFactorClient)(),
+    (0, import_plugins.emailOTPClient)(),
+    (0, import_plugins.magicLinkClient)(),
+    (0, import_plugins.multiSessionClient)(),
+    (0, import_plugins.jwtClient)()
+  ];
+}
+async function createOptareClient(config) {
+  const bootstrap = await resolveOptareConfig(config);
+  const auth = (0, import_client.createAuthClient)({
+    baseURL: bootstrap.baseURL,
+    fetchOptions: {
+      ...config.fetch ? { customFetchImpl: config.fetch } : {},
+      headers: {
+        "x-optare-publishable-key": config.publishableKey,
+        ...config.headers
+      }
+    },
+    plugins: optarePlugins()
+  });
+  return { auth, config: bootstrap };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_AUTH_METHODS,
+  DEFAULT_OPTARE_ORIGIN,
+  OptareConfigError,
+  createOptareClient,
+  resolveOptareConfig
+});

package/dist/index.d.cts

@@ -0,0 +1,115 @@
+import { createAuthClient } from 'better-auth/client';
+
+/**
+ * `@optare/client` — E1.
+ *
+ * Headless, framework-agnostic. The entire integration contract is one string:
+ * a publishable key (`pk_live_…`). The key is *not* a secret — it ships in
+ * browser bundles — so the SDK can safely use it to look up, from a public
+ * endpoint, (a) which origin the auth API lives on and (b) the project's
+ * white-label branding. Everything else is a thin, fully-typed wrapper around
+ * better-auth's client with the same plugin set the Optare backend runs.
+ *
+ * `@optare/react` builds its provider/hooks/components on top of this; a Node
+ * service that only needs `sk_live_` management calls or offline JWT checks
+ * uses `@optare/node` instead.
+ */
+/** The hosted Optare API origin used when neither `baseURL` nor `configURL` is given. */
+declare const DEFAULT_OPTARE_ORIGIN = "https://id.optare.one";
+interface OptareBranding {
+    name: string;
+    logoUrl: string | null;
+    primaryColor: string | null;
+    radius: string | null;
+}
+interface OptareProjectInfo {
+    id: string;
+    name: string;
+    slug: string;
+    plan: string;
+}
+/** Social providers Optare can broker, in a stable display order. */
+type OptareSocialProvider = "google" | "github" | "microsoft" | "facebook" | "twitter";
+/**
+ * Which sign-in methods the Optare instance has enabled. The SDK components use
+ * this to decide what to render — a project can't turn individual methods on or
+ * off in v1 (they're instance-wide), but the deployment can, so the components
+ * must not assume e.g. social buttons exist.
+ */
+interface OptareAuthMethods {
+    emailPassword: boolean;
+    magicLink: boolean;
+    emailOtp: boolean;
+    sso: boolean;
+    passkey: boolean;
+    social: OptareSocialProvider[];
+}
+/**
+ * Safe default for a server that predates the `authMethods` field — email +
+ * password only, so a `<SignIn>` still renders something usable.
+ */
+declare const DEFAULT_AUTH_METHODS: OptareAuthMethods;
+interface OptareBootstrap {
+    /** Origin the auth API (`/api/auth/*`) is served from. */
+    baseURL: string;
+    project: OptareProjectInfo;
+    branding: OptareBranding;
+    /** Enabled sign-in methods for this deployment. */
+    authMethods: OptareAuthMethods;
+}
+interface OptareClientConfig {
+    /** `pk_live_…` — identifies the project. Required. */
+    publishableKey: string;
+    /**
+     * Skip endpoint discovery: if set, this is used as the auth API origin and
+     * only branding is fetched (from `${baseURL}/api/public/config`).
+     */
+    baseURL?: string;
+    /**
+     * Where `GET /api/public/config` lives. Defaults to `baseURL`, then to the
+     * hosted Optare origin. Set this for self-hosted / preview deployments.
+     */
+    configURL?: string;
+    /**
+     * Pre-resolved bootstrap — skips the network call entirely. Useful for SSR,
+     * tests, or when the host app already fetched the config.
+     */
+    bootstrap?: OptareBootstrap;
+    /** `fetch` implementation (Node < 18, tests, custom agents). */
+    fetch?: typeof fetch;
+    /** Extra headers to attach to every auth request. */
+    headers?: Record<string, string>;
+}
+declare class OptareConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve a publishable key to its endpoint + branding via the public config
+ * endpoint. Framework-agnostic; call it directly for SSR or to warm a cache.
+ */
+declare function resolveOptareConfig(config: OptareClientConfig): Promise<OptareBootstrap>;
+type OptareAuthClient = ReturnType<typeof createAuthClient>;
+type Session = OptareAuthClient["$Infer"]["Session"];
+type User = Session["user"];
+interface OptareClient {
+    /**
+     * The better-auth client — `signIn`, `signUp`, `getSession`, `signOut`,
+     * `organization.*`, `twoFactor.*`, etc. A drop-in better-auth client; every
+     * request carries the publishable key.
+     */
+    auth: OptareAuthClient;
+    /** Resolved endpoint + white-label branding for this publishable key. */
+    config: OptareBootstrap;
+}
+/**
+ * Build a fully-configured Optare client. Async because it resolves the
+ * endpoint + branding from the publishable key first (unless `baseURL` +
+ * `bootstrap` let it skip the network).
+ *
+ * The better-auth client is a dynamic RPC proxy — arbitrary property access is
+ * meaningful — so the resolved config is returned *alongside* it, never
+ * attached to it.
+ */
+declare function createOptareClient(config: OptareClientConfig): Promise<OptareClient>;
+
+export { DEFAULT_AUTH_METHODS, DEFAULT_OPTARE_ORIGIN, type OptareAuthClient, type OptareAuthMethods, type OptareBootstrap, type OptareBranding, type OptareClient, type OptareClientConfig, OptareConfigError, type OptareProjectInfo, type OptareSocialProvider, type Session, type User, createOptareClient, resolveOptareConfig };

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+import { createAuthClient } from 'better-auth/client';
+
+/**
+ * `@optare/client` — E1.
+ *
+ * Headless, framework-agnostic. The entire integration contract is one string:
+ * a publishable key (`pk_live_…`). The key is *not* a secret — it ships in
+ * browser bundles — so the SDK can safely use it to look up, from a public
+ * endpoint, (a) which origin the auth API lives on and (b) the project's
+ * white-label branding. Everything else is a thin, fully-typed wrapper around
+ * better-auth's client with the same plugin set the Optare backend runs.
+ *
+ * `@optare/react` builds its provider/hooks/components on top of this; a Node
+ * service that only needs `sk_live_` management calls or offline JWT checks
+ * uses `@optare/node` instead.
+ */
+/** The hosted Optare API origin used when neither `baseURL` nor `configURL` is given. */
+declare const DEFAULT_OPTARE_ORIGIN = "https://id.optare.one";
+interface OptareBranding {
+    name: string;
+    logoUrl: string | null;
+    primaryColor: string | null;
+    radius: string | null;
+}
+interface OptareProjectInfo {
+    id: string;
+    name: string;
+    slug: string;
+    plan: string;
+}
+/** Social providers Optare can broker, in a stable display order. */
+type OptareSocialProvider = "google" | "github" | "microsoft" | "facebook" | "twitter";
+/**
+ * Which sign-in methods the Optare instance has enabled. The SDK components use
+ * this to decide what to render — a project can't turn individual methods on or
+ * off in v1 (they're instance-wide), but the deployment can, so the components
+ * must not assume e.g. social buttons exist.
+ */
+interface OptareAuthMethods {
+    emailPassword: boolean;
+    magicLink: boolean;
+    emailOtp: boolean;
+    sso: boolean;
+    passkey: boolean;
+    social: OptareSocialProvider[];
+}
+/**
+ * Safe default for a server that predates the `authMethods` field — email +
+ * password only, so a `<SignIn>` still renders something usable.
+ */
+declare const DEFAULT_AUTH_METHODS: OptareAuthMethods;
+interface OptareBootstrap {
+    /** Origin the auth API (`/api/auth/*`) is served from. */
+    baseURL: string;
+    project: OptareProjectInfo;
+    branding: OptareBranding;
+    /** Enabled sign-in methods for this deployment. */
+    authMethods: OptareAuthMethods;
+}
+interface OptareClientConfig {
+    /** `pk_live_…` — identifies the project. Required. */
+    publishableKey: string;
+    /**
+     * Skip endpoint discovery: if set, this is used as the auth API origin and
+     * only branding is fetched (from `${baseURL}/api/public/config`).
+     */
+    baseURL?: string;
+    /**
+     * Where `GET /api/public/config` lives. Defaults to `baseURL`, then to the
+     * hosted Optare origin. Set this for self-hosted / preview deployments.
+     */
+    configURL?: string;
+    /**
+     * Pre-resolved bootstrap — skips the network call entirely. Useful for SSR,
+     * tests, or when the host app already fetched the config.
+     */
+    bootstrap?: OptareBootstrap;
+    /** `fetch` implementation (Node < 18, tests, custom agents). */
+    fetch?: typeof fetch;
+    /** Extra headers to attach to every auth request. */
+    headers?: Record<string, string>;
+}
+declare class OptareConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve a publishable key to its endpoint + branding via the public config
+ * endpoint. Framework-agnostic; call it directly for SSR or to warm a cache.
+ */
+declare function resolveOptareConfig(config: OptareClientConfig): Promise<OptareBootstrap>;
+type OptareAuthClient = ReturnType<typeof createAuthClient>;
+type Session = OptareAuthClient["$Infer"]["Session"];
+type User = Session["user"];
+interface OptareClient {
+    /**
+     * The better-auth client — `signIn`, `signUp`, `getSession`, `signOut`,
+     * `organization.*`, `twoFactor.*`, etc. A drop-in better-auth client; every
+     * request carries the publishable key.
+     */
+    auth: OptareAuthClient;
+    /** Resolved endpoint + white-label branding for this publishable key. */
+    config: OptareBootstrap;
+}
+/**
+ * Build a fully-configured Optare client. Async because it resolves the
+ * endpoint + branding from the publishable key first (unless `baseURL` +
+ * `bootstrap` let it skip the network).
+ *
+ * The better-auth client is a dynamic RPC proxy — arbitrary property access is
+ * meaningful — so the resolved config is returned *alongside* it, never
+ * attached to it.
+ */
+declare function createOptareClient(config: OptareClientConfig): Promise<OptareClient>;
+
+export { DEFAULT_AUTH_METHODS, DEFAULT_OPTARE_ORIGIN, type OptareAuthClient, type OptareAuthMethods, type OptareBootstrap, type OptareBranding, type OptareClient, type OptareClientConfig, OptareConfigError, type OptareProjectInfo, type OptareSocialProvider, type Session, type User, createOptareClient, resolveOptareConfig };

package/dist/index.js

@@ -0,0 +1,125 @@
+// src/index.ts
+import { createAuthClient } from "better-auth/client";
+import {
+  organizationClient,
+  twoFactorClient,
+  emailOTPClient,
+  magicLinkClient,
+  multiSessionClient,
+  jwtClient
+} from "better-auth/client/plugins";
+var DEFAULT_OPTARE_ORIGIN = "https://id.optare.one";
+var DEFAULT_AUTH_METHODS = {
+  emailPassword: true,
+  magicLink: false,
+  emailOtp: false,
+  sso: false,
+  passkey: false,
+  social: []
+};
+var PUBLISHABLE_KEY_PREFIX = "pk_live_";
+var OptareConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OptareConfigError";
+  }
+};
+function assertPublishableKey(key) {
+  if (!key || !key.startsWith(PUBLISHABLE_KEY_PREFIX)) {
+    throw new OptareConfigError(
+      `Invalid publishable key \u2014 expected a "${PUBLISHABLE_KEY_PREFIX}\u2026" string`
+    );
+  }
+}
+async function resolveOptareConfig(config) {
+  assertPublishableKey(config.publishableKey);
+  if (config.bootstrap) {
+    return {
+      ...config.bootstrap,
+      authMethods: normalizeAuthMethods(config.bootstrap.authMethods)
+    };
+  }
+  const doFetch = config.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    throw new OptareConfigError(
+      "No fetch implementation available \u2014 pass `fetch` in the config"
+    );
+  }
+  const origin = (config.configURL ?? config.baseURL ?? DEFAULT_OPTARE_ORIGIN).replace(/\/+$/, "");
+  const url = `${origin}/api/public/config?pk=${encodeURIComponent(config.publishableKey)}`;
+  let res;
+  try {
+    res = await doFetch(url, { headers: { accept: "application/json" } });
+  } catch (cause) {
+    throw new OptareConfigError(
+      `Could not reach the Optare config endpoint at ${origin}: ${cause.message}`
+    );
+  }
+  if (res.status === 404) {
+    throw new OptareConfigError("Publishable key was not recognised by the server");
+  }
+  if (!res.ok) {
+    throw new OptareConfigError(
+      `Config endpoint returned ${res.status} ${res.statusText}`
+    );
+  }
+  const body = await res.json();
+  if (!body.baseURL || !body.branding || !body.project) {
+    throw new OptareConfigError("Config endpoint returned an unexpected shape");
+  }
+  return {
+    baseURL: config.baseURL ?? body.baseURL,
+    project: body.project,
+    branding: body.branding,
+    authMethods: normalizeAuthMethods(body.authMethods)
+  };
+}
+function normalizeAuthMethods(raw) {
+  const known = [
+    "google",
+    "github",
+    "microsoft",
+    "facebook",
+    "twitter"
+  ];
+  return {
+    emailPassword: raw?.emailPassword ?? DEFAULT_AUTH_METHODS.emailPassword,
+    magicLink: raw?.magicLink ?? DEFAULT_AUTH_METHODS.magicLink,
+    emailOtp: raw?.emailOtp ?? DEFAULT_AUTH_METHODS.emailOtp,
+    sso: raw?.sso ?? DEFAULT_AUTH_METHODS.sso,
+    passkey: raw?.passkey ?? DEFAULT_AUTH_METHODS.passkey,
+    social: Array.isArray(raw?.social) ? known.filter((p) => raw.social.includes(p)) : DEFAULT_AUTH_METHODS.social
+  };
+}
+function optarePlugins() {
+  return [
+    organizationClient(),
+    twoFactorClient(),
+    emailOTPClient(),
+    magicLinkClient(),
+    multiSessionClient(),
+    jwtClient()
+  ];
+}
+async function createOptareClient(config) {
+  const bootstrap = await resolveOptareConfig(config);
+  const auth = createAuthClient({
+    baseURL: bootstrap.baseURL,
+    fetchOptions: {
+      ...config.fetch ? { customFetchImpl: config.fetch } : {},
+      headers: {
+        "x-optare-publishable-key": config.publishableKey,
+        ...config.headers
+      }
+    },
+    plugins: optarePlugins()
+  });
+  return { auth, config: bootstrap };
+}
+export {
+  DEFAULT_AUTH_METHODS,
+  DEFAULT_OPTARE_ORIGIN,
+  OptareConfigError,
+  createOptareClient,
+  resolveOptareConfig
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@optare/client",
+  "version": "0.1.0",
+  "description": "Headless, framework-agnostic client SDK for Optare. Takes a pk_live_ key and resolves endpoint + branding.",
+  "author": "Optare Team <admin@optare.one>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "better-auth": "^1.7.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  }
+}