@insureco/bio 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { B as BioAuthConfig, A as AuthorizeOptions, a as AuthorizeResult, T as TokenResponse, b as BioUser, I as IntrospectResult, c as BioAdminConfig, U as UserFilters, d as UpdateUserData, e as BioDepartment, C as CreateDepartmentData, f as BioRole, g as CreateRoleData, h as BioOAuthClient, i as CreateClientData, j as BioTokenPayload, V as VerifyOptions, J as JWKSVerifyOptions } from './types-Dkb-drHZ.mjs';
-export { k as AdminResponse, l as BioAddress, m as BioClientTokenPayload, n as BioMessaging, o as BioUsersConfig, O as OrgMember, p as OrgMemberFilters, q as OrgMembersResult } from './types-Dkb-drHZ.mjs';
+import { B as BioAuthConfig, A as AuthorizeOptions, a as AuthorizeResult, T as TokenResponse, b as BioUser, I as IntrospectResult, c as BioAdminConfig, U as UserFilters, d as UpdateUserData, e as BioDepartment, C as CreateDepartmentData, f as BioRole, g as CreateRoleData, h as BioOAuthClient, i as CreateClientData, E as EmbedClientConfig, j as EmbedLoginParams, k as EmbedAuthResult, l as EmbedSignupParams, m as EmbedMagicLinkParams, n as EmbedVerifyParams, o as EmbedRefreshParams, p as EmbedLogoutParams, q as BioTokenPayload, V as VerifyOptions, J as JWKSVerifyOptions } from './types-CJe1FP61.mjs';
+export { r as AdminResponse, s as BioAddress, t as BioClientTokenPayload, u as BioMessaging, v as BioUsersConfig, w as EmbedBranding, x as EmbedUser, O as OrgMember, y as OrgMemberFilters, z as OrgMembersResult } from './types-CJe1FP61.mjs';
 export { AgencyProfile, AgencyProgram, AgencyStaffMember, AgentEmployer, AgentProfile, AppetiteMatchInput, AppetiteMatchProgram, AppetiteMatchResult, CarrierProfile, CarrierProgram, GraphClient, GraphClientConfig, ProgramProfile } from './graph.mjs';
 
 /**
@@ -105,6 +105,91 @@ declare class BioAdmin {
     private request;
 }
 
+/**
+ * Client for Bio-ID headless embed endpoints.
+ *
+ * Use this when building custom login/signup UIs that authenticate
+ * directly against Bio-ID without redirects (no OAuth flow).
+ *
+ * All endpoints use X-Client-Id / X-Client-Secret header auth.
+ *
+ * @example
+ * ```typescript
+ * import { EmbedClient } from '@insureco/bio'
+ *
+ * const embed = EmbedClient.fromEnv()
+ *
+ * // Login
+ * const result = await embed.login({ email: 'user@example.com', password: 'secret' })
+ * console.log(result.accessToken, result.user.bioId)
+ *
+ * // Refresh
+ * const refreshed = await embed.refresh({ refreshToken: result.refreshToken })
+ *
+ * // Logout
+ * await embed.logout({ refreshToken: result.refreshToken })
+ * ```
+ */
+declare class EmbedClient {
+    private readonly bioIdUrl;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly retries;
+    private readonly timeoutMs;
+    constructor(config: EmbedClientConfig);
+    /**
+     * Create an EmbedClient from environment variables.
+     *
+     * Reads: BIO_CLIENT_ID, BIO_CLIENT_SECRET, BIO_ID_URL
+     */
+    static fromEnv(overrides?: Partial<EmbedClientConfig>): EmbedClient;
+    /**
+     * Authenticate a user with email and password.
+     *
+     * @param params - Email and password
+     * @returns Access token, refresh token, user profile, and optional branding
+     */
+    login(params: EmbedLoginParams): Promise<EmbedAuthResult>;
+    /**
+     * Create a new user account.
+     *
+     * @param params - Email, password, name, and optional invite token
+     * @returns Access token, refresh token, user profile, and optional branding
+     */
+    signup(params: EmbedSignupParams): Promise<EmbedAuthResult>;
+    /**
+     * Send a magic link email to the user.
+     *
+     * The user clicks the link to authenticate without a password.
+     * After sending, use `verify()` with the token from the link.
+     *
+     * @param params - Email address to send the magic link to
+     */
+    sendMagicLink(params: EmbedMagicLinkParams): Promise<void>;
+    /**
+     * Verify a magic link token and exchange it for auth tokens.
+     *
+     * @param params - The token from the magic link
+     * @returns Access token, refresh token, user profile, and optional branding
+     */
+    verify(params: EmbedVerifyParams): Promise<EmbedAuthResult>;
+    /**
+     * Refresh an expired access token using a refresh token.
+     *
+     * @param params - The refresh token to exchange
+     * @returns New access token, rotated refresh token, user profile, and optional branding
+     */
+    refresh(params: EmbedRefreshParams): Promise<EmbedAuthResult>;
+    /**
+     * Revoke a refresh token (logout).
+     *
+     * @param params - The refresh token to revoke
+     */
+    logout(params: EmbedLogoutParams): Promise<void>;
+    private embedRequest;
+    private fetchWithRetry;
+}
+
 /** Error thrown by Bio SDK operations */
 declare class BioError extends Error {
     /** HTTP status code (if from an API response) */
@@ -155,4 +240,4 @@ declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
  */
 declare function verifyTokenJWKS(token: string, options?: JWKSVerifyOptions): Promise<BioTokenPayload>;
 
-export { AuthorizeOptions, AuthorizeResult, BioAdmin, BioAdminConfig, BioAuth, BioAuthConfig, BioDepartment, BioError, BioOAuthClient, BioRole, BioTokenPayload, BioUser, CreateClientData, CreateDepartmentData, CreateRoleData, IntrospectResult, JWKSVerifyOptions, TokenResponse, UpdateUserData, UserFilters, VerifyOptions, decodeToken, generatePKCE, isTokenExpired, verifyToken, verifyTokenJWKS };
+export { AuthorizeOptions, AuthorizeResult, BioAdmin, BioAdminConfig, BioAuth, BioAuthConfig, BioDepartment, BioError, BioOAuthClient, BioRole, BioTokenPayload, BioUser, CreateClientData, CreateDepartmentData, CreateRoleData, EmbedAuthResult, EmbedClient, EmbedClientConfig, EmbedLoginParams, EmbedLogoutParams, EmbedMagicLinkParams, EmbedRefreshParams, EmbedSignupParams, EmbedVerifyParams, IntrospectResult, JWKSVerifyOptions, TokenResponse, UpdateUserData, UserFilters, VerifyOptions, decodeToken, generatePKCE, isTokenExpired, verifyToken, verifyTokenJWKS };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BioAuthConfig, A as AuthorizeOptions, a as AuthorizeResult, T as TokenResponse, b as BioUser, I as IntrospectResult, c as BioAdminConfig, U as UserFilters, d as UpdateUserData, e as BioDepartment, C as CreateDepartmentData, f as BioRole, g as CreateRoleData, h as BioOAuthClient, i as CreateClientData, j as BioTokenPayload, V as VerifyOptions, J as JWKSVerifyOptions } from './types-Dkb-drHZ.js';
-export { k as AdminResponse, l as BioAddress, m as BioClientTokenPayload, n as BioMessaging, o as BioUsersConfig, O as OrgMember, p as OrgMemberFilters, q as OrgMembersResult } from './types-Dkb-drHZ.js';
+import { B as BioAuthConfig, A as AuthorizeOptions, a as AuthorizeResult, T as TokenResponse, b as BioUser, I as IntrospectResult, c as BioAdminConfig, U as UserFilters, d as UpdateUserData, e as BioDepartment, C as CreateDepartmentData, f as BioRole, g as CreateRoleData, h as BioOAuthClient, i as CreateClientData, E as EmbedClientConfig, j as EmbedLoginParams, k as EmbedAuthResult, l as EmbedSignupParams, m as EmbedMagicLinkParams, n as EmbedVerifyParams, o as EmbedRefreshParams, p as EmbedLogoutParams, q as BioTokenPayload, V as VerifyOptions, J as JWKSVerifyOptions } from './types-CJe1FP61.js';
+export { r as AdminResponse, s as BioAddress, t as BioClientTokenPayload, u as BioMessaging, v as BioUsersConfig, w as EmbedBranding, x as EmbedUser, O as OrgMember, y as OrgMemberFilters, z as OrgMembersResult } from './types-CJe1FP61.js';
 export { AgencyProfile, AgencyProgram, AgencyStaffMember, AgentEmployer, AgentProfile, AppetiteMatchInput, AppetiteMatchProgram, AppetiteMatchResult, CarrierProfile, CarrierProgram, GraphClient, GraphClientConfig, ProgramProfile } from './graph.js';
 
 /**
@@ -105,6 +105,91 @@ declare class BioAdmin {
     private request;
 }
 
+/**
+ * Client for Bio-ID headless embed endpoints.
+ *
+ * Use this when building custom login/signup UIs that authenticate
+ * directly against Bio-ID without redirects (no OAuth flow).
+ *
+ * All endpoints use X-Client-Id / X-Client-Secret header auth.
+ *
+ * @example
+ * ```typescript
+ * import { EmbedClient } from '@insureco/bio'
+ *
+ * const embed = EmbedClient.fromEnv()
+ *
+ * // Login
+ * const result = await embed.login({ email: 'user@example.com', password: 'secret' })
+ * console.log(result.accessToken, result.user.bioId)
+ *
+ * // Refresh
+ * const refreshed = await embed.refresh({ refreshToken: result.refreshToken })
+ *
+ * // Logout
+ * await embed.logout({ refreshToken: result.refreshToken })
+ * ```
+ */
+declare class EmbedClient {
+    private readonly bioIdUrl;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly retries;
+    private readonly timeoutMs;
+    constructor(config: EmbedClientConfig);
+    /**
+     * Create an EmbedClient from environment variables.
+     *
+     * Reads: BIO_CLIENT_ID, BIO_CLIENT_SECRET, BIO_ID_URL
+     */
+    static fromEnv(overrides?: Partial<EmbedClientConfig>): EmbedClient;
+    /**
+     * Authenticate a user with email and password.
+     *
+     * @param params - Email and password
+     * @returns Access token, refresh token, user profile, and optional branding
+     */
+    login(params: EmbedLoginParams): Promise<EmbedAuthResult>;
+    /**
+     * Create a new user account.
+     *
+     * @param params - Email, password, name, and optional invite token
+     * @returns Access token, refresh token, user profile, and optional branding
+     */
+    signup(params: EmbedSignupParams): Promise<EmbedAuthResult>;
+    /**
+     * Send a magic link email to the user.
+     *
+     * The user clicks the link to authenticate without a password.
+     * After sending, use `verify()` with the token from the link.
+     *
+     * @param params - Email address to send the magic link to
+     */
+    sendMagicLink(params: EmbedMagicLinkParams): Promise<void>;
+    /**
+     * Verify a magic link token and exchange it for auth tokens.
+     *
+     * @param params - The token from the magic link
+     * @returns Access token, refresh token, user profile, and optional branding
+     */
+    verify(params: EmbedVerifyParams): Promise<EmbedAuthResult>;
+    /**
+     * Refresh an expired access token using a refresh token.
+     *
+     * @param params - The refresh token to exchange
+     * @returns New access token, rotated refresh token, user profile, and optional branding
+     */
+    refresh(params: EmbedRefreshParams): Promise<EmbedAuthResult>;
+    /**
+     * Revoke a refresh token (logout).
+     *
+     * @param params - The refresh token to revoke
+     */
+    logout(params: EmbedLogoutParams): Promise<void>;
+    private embedRequest;
+    private fetchWithRetry;
+}
+
 /** Error thrown by Bio SDK operations */
 declare class BioError extends Error {
     /** HTTP status code (if from an API response) */
@@ -155,4 +240,4 @@ declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
  */
 declare function verifyTokenJWKS(token: string, options?: JWKSVerifyOptions): Promise<BioTokenPayload>;
 
-export { AuthorizeOptions, AuthorizeResult, BioAdmin, BioAdminConfig, BioAuth, BioAuthConfig, BioDepartment, BioError, BioOAuthClient, BioRole, BioTokenPayload, BioUser, CreateClientData, CreateDepartmentData, CreateRoleData, IntrospectResult, JWKSVerifyOptions, TokenResponse, UpdateUserData, UserFilters, VerifyOptions, decodeToken, generatePKCE, isTokenExpired, verifyToken, verifyTokenJWKS };
+export { AuthorizeOptions, AuthorizeResult, BioAdmin, BioAdminConfig, BioAuth, BioAuthConfig, BioDepartment, BioError, BioOAuthClient, BioRole, BioTokenPayload, BioUser, CreateClientData, CreateDepartmentData, CreateRoleData, EmbedAuthResult, EmbedClient, EmbedClientConfig, EmbedLoginParams, EmbedLogoutParams, EmbedMagicLinkParams, EmbedRefreshParams, EmbedSignupParams, EmbedVerifyParams, IntrospectResult, JWKSVerifyOptions, TokenResponse, UpdateUserData, UserFilters, VerifyOptions, decodeToken, generatePKCE, isTokenExpired, verifyToken, verifyTokenJWKS };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   BioAdmin: () => BioAdmin,
   BioAuth: () => BioAuth,
   BioError: () => BioError,
+  EmbedClient: () => EmbedClient,
   GraphClient: () => GraphClient,
   decodeToken: () => decodeToken,
   generatePKCE: () => generatePKCE,
@@ -586,6 +587,257 @@ var BioAdmin = class _BioAdmin {
   }
 };
 
+// src/embed.ts
+var DEFAULT_BIO_URL = "https://bio.tawa.pro";
+var DEFAULT_TIMEOUT_MS3 = 1e4;
+var EmbedClient = class _EmbedClient {
+  bioIdUrl;
+  clientId;
+  clientSecret;
+  retries;
+  timeoutMs;
+  constructor(config) {
+    if (!config.clientId) {
+      throw new BioError("clientId is required", "config_error");
+    }
+    if (!config.clientSecret) {
+      throw new BioError("clientSecret is required", "config_error");
+    }
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    this.bioIdUrl = (config.bioIdUrl ?? DEFAULT_BIO_URL).replace(/\/$/, "");
+    this.retries = config.retries ?? 2;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS3;
+  }
+  /**
+   * Create an EmbedClient from environment variables.
+   *
+   * Reads: BIO_CLIENT_ID, BIO_CLIENT_SECRET, BIO_ID_URL
+   */
+  static fromEnv(overrides) {
+    const clientId = overrides?.clientId ?? process.env.BIO_CLIENT_ID;
+    const clientSecret = overrides?.clientSecret ?? process.env.BIO_CLIENT_SECRET;
+    if (!clientId) {
+      throw new BioError(
+        "BIO_CLIENT_ID environment variable is required",
+        "config_error"
+      );
+    }
+    if (!clientSecret) {
+      throw new BioError(
+        "BIO_CLIENT_SECRET environment variable is required",
+        "config_error"
+      );
+    }
+    return new _EmbedClient({
+      clientId,
+      clientSecret,
+      bioIdUrl: overrides?.bioIdUrl ?? process.env.BIO_ID_URL,
+      retries: overrides?.retries,
+      timeoutMs: overrides?.timeoutMs
+    });
+  }
+  /**
+   * Authenticate a user with email and password.
+   *
+   * @param params - Email and password
+   * @returns Access token, refresh token, user profile, and optional branding
+   */
+  async login(params) {
+    if (!params.email) throw new BioError("email is required", "validation_error");
+    if (!params.password) throw new BioError("password is required", "validation_error");
+    return this.embedRequest("/api/embed/login", {
+      email: params.email,
+      password: params.password
+    });
+  }
+  /**
+   * Create a new user account.
+   *
+   * @param params - Email, password, name, and optional invite token
+   * @returns Access token, refresh token, user profile, and optional branding
+   */
+  async signup(params) {
+    if (!params.email) throw new BioError("email is required", "validation_error");
+    if (!params.password) throw new BioError("password is required", "validation_error");
+    if (!params.name) throw new BioError("name is required", "validation_error");
+    const body = {
+      email: params.email,
+      password: params.password,
+      name: params.name
+    };
+    if (params.inviteToken) {
+      body.inviteToken = params.inviteToken;
+    }
+    return this.embedRequest("/api/embed/signup", body);
+  }
+  /**
+   * Send a magic link email to the user.
+   *
+   * The user clicks the link to authenticate without a password.
+   * After sending, use `verify()` with the token from the link.
+   *
+   * @param params - Email address to send the magic link to
+   */
+  async sendMagicLink(params) {
+    if (!params.email) throw new BioError("email is required", "validation_error");
+    const response = await this.fetchWithRetry(
+      "POST",
+      `${this.bioIdUrl}/api/embed/magic-link`,
+      JSON.stringify({ email: params.email })
+    );
+    const json = await parseJsonResponse(response);
+    if (!response.ok) {
+      throw new BioError(
+        extractErrorMessage(json, response.status),
+        extractErrorCode(json),
+        response.status,
+        json
+      );
+    }
+  }
+  /**
+   * Verify a magic link token and exchange it for auth tokens.
+   *
+   * @param params - The token from the magic link
+   * @returns Access token, refresh token, user profile, and optional branding
+   */
+  async verify(params) {
+    if (!params.token) throw new BioError("token is required", "validation_error");
+    return this.embedRequest("/api/embed/verify", {
+      token: params.token
+    });
+  }
+  /**
+   * Refresh an expired access token using a refresh token.
+   *
+   * @param params - The refresh token to exchange
+   * @returns New access token, rotated refresh token, user profile, and optional branding
+   */
+  async refresh(params) {
+    if (!params.refreshToken) throw new BioError("refreshToken is required", "validation_error");
+    return this.embedRequest("/api/embed/refresh", {
+      refreshToken: params.refreshToken
+    });
+  }
+  /**
+   * Revoke a refresh token (logout).
+   *
+   * @param params - The refresh token to revoke
+   */
+  async logout(params) {
+    if (!params.refreshToken) throw new BioError("refreshToken is required", "validation_error");
+    const response = await this.fetchWithRetry(
+      "POST",
+      `${this.bioIdUrl}/api/embed/logout`,
+      JSON.stringify({ refreshToken: params.refreshToken })
+    );
+    const json = await parseJsonResponse(response);
+    if (!response.ok) {
+      throw new BioError(
+        extractErrorMessage(json, response.status),
+        extractErrorCode(json),
+        response.status,
+        json
+      );
+    }
+  }
+  // ── Private helpers ──────────────────────────────────────────────────────
+  async embedRequest(path, body) {
+    const response = await this.fetchWithRetry(
+      "POST",
+      `${this.bioIdUrl}${path}`,
+      JSON.stringify(body)
+    );
+    const json = await parseJsonResponse(response);
+    if (!response.ok) {
+      throw new BioError(
+        extractErrorMessage(json, response.status),
+        extractErrorCode(json),
+        response.status,
+        json
+      );
+    }
+    return mapEmbedResponse(json);
+  }
+  async fetchWithRetry(method, url, body, attempt = 0) {
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "X-Client-Id": this.clientId,
+          "X-Client-Secret": this.clientSecret
+        },
+        body,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+      if (response.status >= 500 && attempt < this.retries) {
+        await sleep(retryDelay(attempt));
+        return this.fetchWithRetry(method, url, body, attempt + 1);
+      }
+      return response;
+    } catch (err) {
+      if (attempt < this.retries) {
+        await sleep(retryDelay(attempt));
+        return this.fetchWithRetry(method, url, body, attempt + 1);
+      }
+      const isTimeout = err instanceof DOMException && err.name === "TimeoutError";
+      throw new BioError(
+        isTimeout ? `Request timed out after ${this.timeoutMs}ms` : err instanceof Error ? err.message : "Network error",
+        isTimeout ? "timeout" : "network_error"
+      );
+    }
+  }
+};
+function mapEmbedResponse(raw) {
+  const data = raw.data ?? raw;
+  const rawUser = data.user ?? {};
+  const rawBranding = data.branding;
+  const user = {
+    bioId: rawUser.bioId,
+    email: rawUser.email,
+    name: rawUser.name,
+    orgSlug: rawUser.orgSlug
+  };
+  const result = {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    tokenType: data.token_type ?? "Bearer",
+    expiresIn: data.expires_in,
+    user
+  };
+  if (rawBranding) {
+    result.branding = {
+      displayName: rawBranding.displayName,
+      logoUrl: rawBranding.logoUrl,
+      logoMarkUrl: rawBranding.logoMarkUrl,
+      primaryColor: rawBranding.primaryColor,
+      secondaryColor: rawBranding.secondaryColor,
+      verified: rawBranding.verified,
+      whiteLabelApproved: rawBranding.whiteLabelApproved
+    };
+  }
+  return result;
+}
+function extractErrorMessage(json, status) {
+  const error = json.error;
+  if (typeof error === "object" && error !== null) {
+    return error.message ?? `Embed API returned ${status}`;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return `Embed API returned ${status}`;
+}
+function extractErrorCode(json) {
+  const error = json.error;
+  if (typeof error === "object" && error !== null) {
+    return error.code ?? "embed_error";
+  }
+  return "embed_error";
+}
+
 // src/jwt.ts
 var import_node_crypto3 = __toESM(require("crypto"));
 var DEFAULT_ISSUERS = [
@@ -740,7 +992,7 @@ async function verifyTokenJWKS(token, options) {
 }
 
 // src/graph.ts
-var DEFAULT_TIMEOUT_MS3 = 1e4;
+var DEFAULT_TIMEOUT_MS4 = 1e4;
 var BIO_GRAPH_URL = "https://bio-graph.tawa.pro";
 var GraphClient = class _GraphClient {
   graphUrl;
@@ -749,7 +1001,7 @@ var GraphClient = class _GraphClient {
   constructor(config = {}) {
     this.graphUrl = (config.graphUrl ?? process.env.BIO_GRAPH_URL ?? BIO_GRAPH_URL).replace(/\/$/, "");
     this.accessToken = config.accessToken;
-    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS3;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS4;
   }
   /**
    * Create a GraphClient from environment variables.
@@ -902,6 +1154,7 @@ var GraphClient = class _GraphClient {
   BioAdmin,
   BioAuth,
   BioError,
+  EmbedClient,
   GraphClient,
   decodeToken,
   generatePKCE,

package/dist/index.mjs

@@ -515,6 +515,257 @@ var BioAdmin = class _BioAdmin {
   }
 };
 
+// src/embed.ts
+var DEFAULT_BIO_URL = "https://bio.tawa.pro";
+var DEFAULT_TIMEOUT_MS3 = 1e4;
+var EmbedClient = class _EmbedClient {
+  bioIdUrl;
+  clientId;
+  clientSecret;
+  retries;
+  timeoutMs;
+  constructor(config) {
+    if (!config.clientId) {
+      throw new BioError("clientId is required", "config_error");
+    }
+    if (!config.clientSecret) {
+      throw new BioError("clientSecret is required", "config_error");
+    }
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    this.bioIdUrl = (config.bioIdUrl ?? DEFAULT_BIO_URL).replace(/\/$/, "");
+    this.retries = config.retries ?? 2;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS3;
+  }
+  /**
+   * Create an EmbedClient from environment variables.
+   *
+   * Reads: BIO_CLIENT_ID, BIO_CLIENT_SECRET, BIO_ID_URL
+   */
+  static fromEnv(overrides) {
+    const clientId = overrides?.clientId ?? process.env.BIO_CLIENT_ID;
+    const clientSecret = overrides?.clientSecret ?? process.env.BIO_CLIENT_SECRET;
+    if (!clientId) {
+      throw new BioError(
+        "BIO_CLIENT_ID environment variable is required",
+        "config_error"
+      );
+    }
+    if (!clientSecret) {
+      throw new BioError(
+        "BIO_CLIENT_SECRET environment variable is required",
+        "config_error"
+      );
+    }
+    return new _EmbedClient({
+      clientId,
+      clientSecret,
+      bioIdUrl: overrides?.bioIdUrl ?? process.env.BIO_ID_URL,
+      retries: overrides?.retries,
+      timeoutMs: overrides?.timeoutMs
+    });
+  }
+  /**
+   * Authenticate a user with email and password.
+   *
+   * @param params - Email and password
+   * @returns Access token, refresh token, user profile, and optional branding
+   */
+  async login(params) {
+    if (!params.email) throw new BioError("email is required", "validation_error");
+    if (!params.password) throw new BioError("password is required", "validation_error");
+    return this.embedRequest("/api/embed/login", {
+      email: params.email,
+      password: params.password
+    });
+  }
+  /**
+   * Create a new user account.
+   *
+   * @param params - Email, password, name, and optional invite token
+   * @returns Access token, refresh token, user profile, and optional branding
+   */
+  async signup(params) {
+    if (!params.email) throw new BioError("email is required", "validation_error");
+    if (!params.password) throw new BioError("password is required", "validation_error");
+    if (!params.name) throw new BioError("name is required", "validation_error");
+    const body = {
+      email: params.email,
+      password: params.password,
+      name: params.name
+    };
+    if (params.inviteToken) {
+      body.inviteToken = params.inviteToken;
+    }
+    return this.embedRequest("/api/embed/signup", body);
+  }
+  /**
+   * Send a magic link email to the user.
+   *
+   * The user clicks the link to authenticate without a password.
+   * After sending, use `verify()` with the token from the link.
+   *
+   * @param params - Email address to send the magic link to
+   */
+  async sendMagicLink(params) {
+    if (!params.email) throw new BioError("email is required", "validation_error");
+    const response = await this.fetchWithRetry(
+      "POST",
+      `${this.bioIdUrl}/api/embed/magic-link`,
+      JSON.stringify({ email: params.email })
+    );
+    const json = await parseJsonResponse(response);
+    if (!response.ok) {
+      throw new BioError(
+        extractErrorMessage(json, response.status),
+        extractErrorCode(json),
+        response.status,
+        json
+      );
+    }
+  }
+  /**
+   * Verify a magic link token and exchange it for auth tokens.
+   *
+   * @param params - The token from the magic link
+   * @returns Access token, refresh token, user profile, and optional branding
+   */
+  async verify(params) {
+    if (!params.token) throw new BioError("token is required", "validation_error");
+    return this.embedRequest("/api/embed/verify", {
+      token: params.token
+    });
+  }
+  /**
+   * Refresh an expired access token using a refresh token.
+   *
+   * @param params - The refresh token to exchange
+   * @returns New access token, rotated refresh token, user profile, and optional branding
+   */
+  async refresh(params) {
+    if (!params.refreshToken) throw new BioError("refreshToken is required", "validation_error");
+    return this.embedRequest("/api/embed/refresh", {
+      refreshToken: params.refreshToken
+    });
+  }
+  /**
+   * Revoke a refresh token (logout).
+   *
+   * @param params - The refresh token to revoke
+   */
+  async logout(params) {
+    if (!params.refreshToken) throw new BioError("refreshToken is required", "validation_error");
+    const response = await this.fetchWithRetry(
+      "POST",
+      `${this.bioIdUrl}/api/embed/logout`,
+      JSON.stringify({ refreshToken: params.refreshToken })
+    );
+    const json = await parseJsonResponse(response);
+    if (!response.ok) {
+      throw new BioError(
+        extractErrorMessage(json, response.status),
+        extractErrorCode(json),
+        response.status,
+        json
+      );
+    }
+  }
+  // ── Private helpers ──────────────────────────────────────────────────────
+  async embedRequest(path, body) {
+    const response = await this.fetchWithRetry(
+      "POST",
+      `${this.bioIdUrl}${path}`,
+      JSON.stringify(body)
+    );
+    const json = await parseJsonResponse(response);
+    if (!response.ok) {
+      throw new BioError(
+        extractErrorMessage(json, response.status),
+        extractErrorCode(json),
+        response.status,
+        json
+      );
+    }
+    return mapEmbedResponse(json);
+  }
+  async fetchWithRetry(method, url, body, attempt = 0) {
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "X-Client-Id": this.clientId,
+          "X-Client-Secret": this.clientSecret
+        },
+        body,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+      if (response.status >= 500 && attempt < this.retries) {
+        await sleep(retryDelay(attempt));
+        return this.fetchWithRetry(method, url, body, attempt + 1);
+      }
+      return response;
+    } catch (err) {
+      if (attempt < this.retries) {
+        await sleep(retryDelay(attempt));
+        return this.fetchWithRetry(method, url, body, attempt + 1);
+      }
+      const isTimeout = err instanceof DOMException && err.name === "TimeoutError";
+      throw new BioError(
+        isTimeout ? `Request timed out after ${this.timeoutMs}ms` : err instanceof Error ? err.message : "Network error",
+        isTimeout ? "timeout" : "network_error"
+      );
+    }
+  }
+};
+function mapEmbedResponse(raw) {
+  const data = raw.data ?? raw;
+  const rawUser = data.user ?? {};
+  const rawBranding = data.branding;
+  const user = {
+    bioId: rawUser.bioId,
+    email: rawUser.email,
+    name: rawUser.name,
+    orgSlug: rawUser.orgSlug
+  };
+  const result = {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    tokenType: data.token_type ?? "Bearer",
+    expiresIn: data.expires_in,
+    user
+  };
+  if (rawBranding) {
+    result.branding = {
+      displayName: rawBranding.displayName,
+      logoUrl: rawBranding.logoUrl,
+      logoMarkUrl: rawBranding.logoMarkUrl,
+      primaryColor: rawBranding.primaryColor,
+      secondaryColor: rawBranding.secondaryColor,
+      verified: rawBranding.verified,
+      whiteLabelApproved: rawBranding.whiteLabelApproved
+    };
+  }
+  return result;
+}
+function extractErrorMessage(json, status) {
+  const error = json.error;
+  if (typeof error === "object" && error !== null) {
+    return error.message ?? `Embed API returned ${status}`;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return `Embed API returned ${status}`;
+}
+function extractErrorCode(json) {
+  const error = json.error;
+  if (typeof error === "object" && error !== null) {
+    return error.code ?? "embed_error";
+  }
+  return "embed_error";
+}
+
 // src/jwt.ts
 import crypto3 from "crypto";
 var DEFAULT_ISSUERS = [
@@ -671,6 +922,7 @@ export {
   BioAdmin,
   BioAuth,
   BioError,
+  EmbedClient,
   GraphClient,
   decodeToken,
   generatePKCE,

package/dist/{types-Dkb-drHZ.d.mts → types-CJe1FP61.d.mts}

@@ -298,5 +298,99 @@ interface AdminResponse<T> {
         limit: number;
     };
 }
+/** Configuration for EmbedClient (headless embed auth) */
+interface EmbedClientConfig {
+    /** OAuth client ID (env: BIO_CLIENT_ID) */
+    clientId: string;
+    /** OAuth client secret (env: BIO_CLIENT_SECRET) */
+    clientSecret: string;
+    /** Bio-ID base URL (env: BIO_ID_URL, default: https://bio.tawa.pro) */
+    bioIdUrl?: string;
+    /** Number of retry attempts on transient failures (default: 2) */
+    retries?: number;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeoutMs?: number;
+}
+/** Parameters for embed login */
+interface EmbedLoginParams {
+    /** User email address */
+    email: string;
+    /** User password */
+    password: string;
+}
+/** Parameters for embed signup */
+interface EmbedSignupParams {
+    /** User email address */
+    email: string;
+    /** User password */
+    password: string;
+    /** Display name */
+    name: string;
+    /** Optional invite token for org-scoped signups */
+    inviteToken?: string;
+}
+/** Parameters for sending a magic link */
+interface EmbedMagicLinkParams {
+    /** Email address to send the magic link to */
+    email: string;
+}
+/** Parameters for verifying a magic link token */
+interface EmbedVerifyParams {
+    /** Magic link token from the email */
+    token: string;
+}
+/** Parameters for refreshing an access token */
+interface EmbedRefreshParams {
+    /** Refresh token from a previous login/signup/verify/refresh */
+    refreshToken: string;
+}
+/** Parameters for logout (token revocation) */
+interface EmbedLogoutParams {
+    /** Refresh token to revoke */
+    refreshToken: string;
+}
+/** User profile returned by embed endpoints */
+interface EmbedUser {
+    /** Unique Bio-ID identifier */
+    bioId: string;
+    /** User email address */
+    email: string;
+    /** Display name */
+    name: string;
+    /** Organization slug (if the user belongs to an org) */
+    orgSlug?: string;
+}
+/** Branding data returned by embed endpoints */
+interface EmbedBranding {
+    /** Organization display name */
+    displayName?: string;
+    /** Full logo URL */
+    logoUrl?: string;
+    /** Logo mark (icon) URL */
+    logoMarkUrl?: string;
+    /** Primary brand color (hex) */
+    primaryColor?: string;
+    /** Secondary brand color (hex) */
+    secondaryColor?: string;
+    /** Whether the org is verified */
+    verified?: boolean;
+    /** Whether white-label is approved for this org */
+    whiteLabelApproved?: boolean;
+}
+/** Auth result from embed login, signup, verify, or refresh */
+interface EmbedAuthResult {
+    /** JWT access token */
+    accessToken: string;
+    /** Refresh token (use with refresh() or logout()) */
+    refreshToken: string;
+    /** Token type (always 'Bearer') */
+    tokenType: 'Bearer';
+    /** Access token lifetime in seconds */
+    expiresIn: number;
+    /** Authenticated user profile */
+    user: EmbedUser;
+    /** Optional org branding (present when the user belongs to a branded org) */
+    branding?: EmbedBranding;
+}
 
-export type { AuthorizeOptions as A, BioAuthConfig as B, CreateDepartmentData as C, IntrospectResult as I, JWKSVerifyOptions as J, OrgMember as O, TokenResponse as T, UserFilters as U, VerifyOptions as V, AuthorizeResult as a, BioUser as b, BioAdminConfig as c, UpdateUserData as d, BioDepartment as e, BioRole as f, CreateRoleData as g, BioOAuthClient as h, CreateClientData as i, BioTokenPayload as j, AdminResponse as k, BioAddress as l, BioClientTokenPayload as m, BioMessaging as n, BioUsersConfig as o, OrgMemberFilters as p, OrgMembersResult as q };
+export type { AuthorizeOptions as A, BioAuthConfig as B, CreateDepartmentData as C, EmbedClientConfig as E, IntrospectResult as I, JWKSVerifyOptions as J, OrgMember as O, TokenResponse as T, UserFilters as U, VerifyOptions as V, AuthorizeResult as a, BioUser as b, BioAdminConfig as c, UpdateUserData as d, BioDepartment as e, BioRole as f, CreateRoleData as g, BioOAuthClient as h, CreateClientData as i, EmbedLoginParams as j, EmbedAuthResult as k, EmbedSignupParams as l, EmbedMagicLinkParams as m, EmbedVerifyParams as n, EmbedRefreshParams as o, EmbedLogoutParams as p, BioTokenPayload as q, AdminResponse as r, BioAddress as s, BioClientTokenPayload as t, BioMessaging as u, BioUsersConfig as v, EmbedBranding as w, EmbedUser as x, OrgMemberFilters as y, OrgMembersResult as z };

package/dist/{types-Dkb-drHZ.d.ts → types-CJe1FP61.d.ts}

@@ -298,5 +298,99 @@ interface AdminResponse<T> {
         limit: number;
     };
 }
+/** Configuration for EmbedClient (headless embed auth) */
+interface EmbedClientConfig {
+    /** OAuth client ID (env: BIO_CLIENT_ID) */
+    clientId: string;
+    /** OAuth client secret (env: BIO_CLIENT_SECRET) */
+    clientSecret: string;
+    /** Bio-ID base URL (env: BIO_ID_URL, default: https://bio.tawa.pro) */
+    bioIdUrl?: string;
+    /** Number of retry attempts on transient failures (default: 2) */
+    retries?: number;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeoutMs?: number;
+}
+/** Parameters for embed login */
+interface EmbedLoginParams {
+    /** User email address */
+    email: string;
+    /** User password */
+    password: string;
+}
+/** Parameters for embed signup */
+interface EmbedSignupParams {
+    /** User email address */
+    email: string;
+    /** User password */
+    password: string;
+    /** Display name */
+    name: string;
+    /** Optional invite token for org-scoped signups */
+    inviteToken?: string;
+}
+/** Parameters for sending a magic link */
+interface EmbedMagicLinkParams {
+    /** Email address to send the magic link to */
+    email: string;
+}
+/** Parameters for verifying a magic link token */
+interface EmbedVerifyParams {
+    /** Magic link token from the email */
+    token: string;
+}
+/** Parameters for refreshing an access token */
+interface EmbedRefreshParams {
+    /** Refresh token from a previous login/signup/verify/refresh */
+    refreshToken: string;
+}
+/** Parameters for logout (token revocation) */
+interface EmbedLogoutParams {
+    /** Refresh token to revoke */
+    refreshToken: string;
+}
+/** User profile returned by embed endpoints */
+interface EmbedUser {
+    /** Unique Bio-ID identifier */
+    bioId: string;
+    /** User email address */
+    email: string;
+    /** Display name */
+    name: string;
+    /** Organization slug (if the user belongs to an org) */
+    orgSlug?: string;
+}
+/** Branding data returned by embed endpoints */
+interface EmbedBranding {
+    /** Organization display name */
+    displayName?: string;
+    /** Full logo URL */
+    logoUrl?: string;
+    /** Logo mark (icon) URL */
+    logoMarkUrl?: string;
+    /** Primary brand color (hex) */
+    primaryColor?: string;
+    /** Secondary brand color (hex) */
+    secondaryColor?: string;
+    /** Whether the org is verified */
+    verified?: boolean;
+    /** Whether white-label is approved for this org */
+    whiteLabelApproved?: boolean;
+}
+/** Auth result from embed login, signup, verify, or refresh */
+interface EmbedAuthResult {
+    /** JWT access token */
+    accessToken: string;
+    /** Refresh token (use with refresh() or logout()) */
+    refreshToken: string;
+    /** Token type (always 'Bearer') */
+    tokenType: 'Bearer';
+    /** Access token lifetime in seconds */
+    expiresIn: number;
+    /** Authenticated user profile */
+    user: EmbedUser;
+    /** Optional org branding (present when the user belongs to a branded org) */
+    branding?: EmbedBranding;
+}
 
-export type { AuthorizeOptions as A, BioAuthConfig as B, CreateDepartmentData as C, IntrospectResult as I, JWKSVerifyOptions as J, OrgMember as O, TokenResponse as T, UserFilters as U, VerifyOptions as V, AuthorizeResult as a, BioUser as b, BioAdminConfig as c, UpdateUserData as d, BioDepartment as e, BioRole as f, CreateRoleData as g, BioOAuthClient as h, CreateClientData as i, BioTokenPayload as j, AdminResponse as k, BioAddress as l, BioClientTokenPayload as m, BioMessaging as n, BioUsersConfig as o, OrgMemberFilters as p, OrgMembersResult as q };
+export type { AuthorizeOptions as A, BioAuthConfig as B, CreateDepartmentData as C, EmbedClientConfig as E, IntrospectResult as I, JWKSVerifyOptions as J, OrgMember as O, TokenResponse as T, UserFilters as U, VerifyOptions as V, AuthorizeResult as a, BioUser as b, BioAdminConfig as c, UpdateUserData as d, BioDepartment as e, BioRole as f, CreateRoleData as g, BioOAuthClient as h, CreateClientData as i, EmbedLoginParams as j, EmbedAuthResult as k, EmbedSignupParams as l, EmbedMagicLinkParams as m, EmbedVerifyParams as n, EmbedRefreshParams as o, EmbedLogoutParams as p, BioTokenPayload as q, AdminResponse as r, BioAddress as s, BioClientTokenPayload as t, BioMessaging as u, BioUsersConfig as v, EmbedBranding as w, EmbedUser as x, OrgMemberFilters as y, OrgMembersResult as z };

package/dist/users.d.mts

@@ -1,4 +1,4 @@
-import { o as BioUsersConfig, p as OrgMemberFilters, q as OrgMembersResult } from './types-Dkb-drHZ.mjs';
+import { v as BioUsersConfig, y as OrgMemberFilters, z as OrgMembersResult } from './types-CJe1FP61.mjs';
 
 /**
  * Client for Bio-ID user access endpoints.

package/dist/users.d.ts

@@ -1,4 +1,4 @@
-import { o as BioUsersConfig, p as OrgMemberFilters, q as OrgMembersResult } from './types-Dkb-drHZ.js';
+import { v as BioUsersConfig, y as OrgMemberFilters, z as OrgMembersResult } from './types-CJe1FP61.js';
 
 /**
  * Client for Bio-ID user access endpoints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insureco/bio",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "SDK for Bio-ID SSO integration on the Tawa platform",
   "main": "dist/index.js",
   "module": "dist/index.mjs",