@billkit-eu/react 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -16,10 +16,12 @@ package's changelog.
 First public release.
 
 ### Added
-- `<BillKitProvider>`: holds the publishable key and shared element
-  configuration for the tree below it, so individual elements take only the
-  props that vary. Shaped after `@stripe/react-stripe-js` `<Elements>`, which
-  is the API most teams are migrating from.
+- `<BillKitProvider>`: holds the shared element configuration (origin
+  overrides, logger) for the tree below it, so individual elements take only
+  the props that vary. Shaped after `@stripe/react-stripe-js` `<Elements>`,
+  which is the API most teams are migrating from — but with **no
+  `publishableKey`**: BillKit has no publishable-key concept, and elements
+  authenticate with the session's ephemeral `client_secret` instead.
 - `<CheckoutElement/>` and `<PaymentMethodElement/>`: React wrappers over the
   corresponding `@billkit-eu/js` mounts, with the iframe's lifecycle tied to
   the component's.

package/README.md

@@ -67,7 +67,7 @@ Both components are SSR-safe. They render `null` on the server and on the first
 | `onReady` | `() => void` | The iframe booted and loaded the session. |
 | `onChange` | `(e: ChangeEvent) => void` | `e.complete` drives an external pay button. |
 | `onSuccess` | `(e: SuccessEvent) => void` | Terminal success with no redirect. |
-| `onError` | `(e: BillKitElementError) => void` | Any element or payment error. |
+| `onError` | `(e: BillKitElementError) => void` | Any element or payment error. Codes: `payment_declined`, `load_timeout`, `unsafe_redirect`. |
 | `onRedirect` | `(url: string) => boolean \| void` | Before the top window navigates for 3DS or iDEAL. Return `false` to navigate yourself. |
 
 `<PaymentMethodElement/>` also requires `customerId`.
@@ -78,7 +78,47 @@ Both components are SSR-safe. They render `null` on the server and on the first
 
 Pass inline arrow functions freely. Callbacks are read through a ref at event time, so a fresh closure on every render does not tear down a live payment iframe. The same holds for `logger`: an inline `logger={{...}}`, or switching one on mid-session, never triggers a remount.
 
-Only `clientSecret`, `locale` and the origin overrides remount the element. That is deliberate, because a remount destroys an in-progress payment.
+Only `clientSecret`, `customerId`, `locale` and the origin overrides remount the element. That is deliberate, because a remount destroys an in-progress payment — but `customerId` has to be in that list: the wallet's "set default" and "remove" actions act on whichever customer the iframe was initialised with, so a stale frame would point them at the wrong person.
+
+## Your own pay button
+
+Take a `ref` and call `submit()`. Gate the button on `onChange`'s `complete`, and re-enable it from `onError` — a declined card fires `onError({ code: "payment_declined" })` while the element shows its own retry panel, so it is the only signal that the attempt is over.
+
+```tsx
+import { useRef, useState } from "react";
+import { BillKitProvider, CheckoutElement, type BillKitElementRef } from "@billkit-eu/react";
+
+function Checkout({ clientSecret }: { clientSecret: string }) {
+  const element = useRef<BillKitElementRef>(null);
+  const [complete, setComplete] = useState(false);
+  const [submitting, setSubmitting] = useState(false);
+
+  return (
+    <BillKitProvider>
+      <CheckoutElement
+        ref={element}
+        clientSecret={clientSecret}
+        onChange={({ complete }) => setComplete(complete)}
+        onError={() => setSubmitting(false)}
+        onSuccess={({ sessionId }) => router.push(`/thanks?cs=${sessionId}`)}
+      />
+      <button
+        disabled={!complete || submitting}
+        onClick={() => {
+          setSubmitting(true);
+          element.current?.submit();
+        }}
+      >
+        Pay
+      </button>
+    </BillKitProvider>
+  );
+}
+```
+
+The ref also exposes `updateTheme(tokens)` for imperative restyling; the declarative `theme` prop is hot-applied without a remount and is usually what you want.
+
+`<PaymentMethodElement/>`'s ref exposes `updateTheme()` only — that element has no form to submit; its actions are per-row buttons inside the iframe.
 
 ## Content Security Policy
 
@@ -104,7 +144,7 @@ Never logged: the `clientSecret`, message payloads, or full redirect URLs. Only
 
 The shapes line up, with one difference worth calling out.
 
-`publishableKey` on `<BillKitProvider>` is **deprecated, optional and ignored**. BillKit has no publishable-key concept; the API only mints secret keys, which must never reach a browser. The prop was required in 0.1.0 by analogy with Stripe, but nothing ever read it. Pass nothing. It will be removed in the next major.
+There is **no `publishableKey`**. BillKit has no publishable-key concept; the API only mints secret keys (`sk_live_...` / `sk_test_...`), which must never reach a browser. Elements authenticate with the ephemeral `client_secret` your server gets from `POST /v1/checkout/sessions` with `ui_mode: "embedded"` — `<BillKitProvider>` takes no credential at all.
 
 See the [migration guide](https://docs.billkit.eu/migration/elements/) for the full comparison.
 
@@ -118,6 +158,8 @@ import type {
   ChangeEvent,
   SuccessEvent,
   BillKitElementError,
+  BillKitElementRef, // the imperative handle: { submit, updateTheme }
+  ThemeableElementRef, // <PaymentMethodElement/>'s: { updateTheme }
 } from "@billkit-eu/react";
 ```
 

package/dist/index.cjs

@@ -7,15 +7,14 @@ var js = require('@billkit-eu/js');
 // src/BillKitProvider.tsx
 var BillKitContext = react.createContext(null);
 function BillKitProvider({
-  publishableKey,
   iframeOrigin,
   apiBase,
   logger,
   children
 }) {
   const value = react.useMemo(
-    () => ({ publishableKey, iframeOrigin, apiBase, logger }),
-    [publishableKey, iframeOrigin, apiBase, logger]
+    () => ({ iframeOrigin, apiBase, logger }),
+    [iframeOrigin, apiBase, logger]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(BillKitContext.Provider, { value, children });
 }
@@ -65,26 +64,43 @@ function useElement(mount, props) {
       handle.destroy();
       handleRef.current = null;
     };
-  }, [isClient, props.clientSecret, props.locale, iframeOrigin, apiBase]);
+  }, [isClient, props.clientSecret, props.customerId, props.locale, iframeOrigin, apiBase]);
   react.useEffect(() => {
     if (themeKey && handleRef.current && props.theme) {
       handleRef.current.updateTheme(props.theme);
     }
   }, [themeKey]);
-  return { isClient, containerRef };
+  return { isClient, containerRef, handleRef };
 }
-function CheckoutElement(props) {
-  const { isClient, containerRef } = useElement(js.mountCheckoutElement, props);
-  if (!isClient) return null;
-  return /* @__PURE__ */ jsxRuntime.jsx("div", { ref: containerRef, className: props.className, style: props.style });
+function checkoutElementRef(handleRef) {
+  return {
+    submit: () => handleRef.current?.submit(),
+    updateTheme: (theme) => handleRef.current?.updateTheme(theme)
+  };
 }
-function PaymentMethodElement(props) {
-  const { customerId } = props;
-  const mount = (target, options) => js.mountPaymentMethodElement(target, { ...options, customerId });
-  const { isClient, containerRef } = useElement(mount, props);
-  if (!isClient) return null;
-  return /* @__PURE__ */ jsxRuntime.jsx("div", { ref: containerRef, className: props.className, style: props.style });
+function themeableElementRef(handleRef) {
+  return {
+    updateTheme: (theme) => handleRef.current?.updateTheme(theme)
+  };
 }
+var CheckoutElement = react.forwardRef(
+  function CheckoutElement2(props, ref) {
+    const { isClient, containerRef, handleRef } = useElement(js.mountCheckoutElement, props);
+    react.useImperativeHandle(ref, () => checkoutElementRef(handleRef), []);
+    if (!isClient) return null;
+    return /* @__PURE__ */ jsxRuntime.jsx("div", { ref: containerRef, className: props.className, style: props.style });
+  }
+);
+var PaymentMethodElement = react.forwardRef(
+  function PaymentMethodElement2(props, ref) {
+    const { customerId } = props;
+    const mount = (target, options) => js.mountPaymentMethodElement(target, { ...options, customerId });
+    const { isClient, containerRef, handleRef } = useElement(mount, props);
+    react.useImperativeHandle(ref, () => themeableElementRef(handleRef), []);
+    if (!isClient) return null;
+    return /* @__PURE__ */ jsxRuntime.jsx("div", { ref: containerRef, className: props.className, style: props.style });
+  }
+);
 
 exports.BillKitProvider = BillKitProvider;
 exports.CheckoutElement = CheckoutElement;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/BillKitProvider.tsx","../src/useElement.ts","../src/CheckoutElement.tsx","../src/PaymentMethodElement.tsx"],"names":["createContext","useMemo","jsx","useContext","useState","useRef","useEffect","mountCheckoutElement","mountPaymentMethodElement"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { BillKitElementLogger } from \"@billkit-eu/js\";\nimport { createContext, type ReactNode, useContext, useMemo } from \"react\";\n\n/**\n * Config shared by every BillKit element on the page. Mirrors\n * `@stripe/react-stripe-js`'s `<Elements>` provider: put your public key\n * (and any origin overrides) here once, then render elements freely\n * beneath it.\n */\nexport interface BillKitContextValue {\n  /**\n   * @deprecated Not required, not used, and not something BillKit issues.\n   *\n   * BillKit has no publishable-key concept; the API only mints secret\n   * keys (`sk_live_...` / `sk_test_...`), which must never reach a browser.\n   * Elements authenticate with the ephemeral `client_secret` your server\n   * gets from `POST /v1/checkout/sessions` with `ui_mode: \"embedded\"`,\n   * and that secret already names the tenant, the mode, and the session.\n   *\n   * The prop was accepted (and required) in 0.1.0 by analogy with\n   * `@stripe/react-stripe-js`, but nothing ever read it, and a tenant\n   * following the docs went looking for a `pk_...` value that does not\n   * exist. It is now optional and ignored; pass nothing. It will be\n   * removed in the next major.\n   */\n  publishableKey?: string;\n  /** Origin the element iframe is served from. Defaults to js.billkit.eu. */\n  iframeOrigin?: string;\n  /** API origin the iframe calls. Defaults to api.billkit.eu. */\n  apiBase?: string;\n  /**\n   * Where every element beneath this provider sends its lifecycle\n   * diagnostics: iframe boot, dropped `postMessage`s, refused\n   * redirects, load timeouts. Omitted (the default) means silence: the\n   * elements never write to `console` on their own.\n   *\n   * `console` works as-is. An individual element can override this with\n   * its own `logger` prop. The `clientSecret` is never passed to it.\n   */\n  logger?: BillKitElementLogger;\n}\n\nconst BillKitContext = createContext<BillKitContextValue | null>(null);\n\nexport interface BillKitProviderProps extends BillKitContextValue {\n  children: ReactNode;\n}\n\n/**\n * Wrap the part of your tree that renders BillKit elements.\n *\n * No credential is needed here; the element authenticates with the\n * ephemeral `client_secret` your server minted for the session:\n *\n * ```tsx\n * <BillKitProvider>\n *   <CheckoutElement clientSecret={clientSecret} onSuccess={done} />\n * </BillKitProvider>\n * ```\n */\nexport function BillKitProvider({\n  publishableKey,\n  iframeOrigin,\n  apiBase,\n  logger,\n  children,\n}: BillKitProviderProps): JSX.Element {\n  const value = useMemo<BillKitContextValue>(\n    () => ({ publishableKey, iframeOrigin, apiBase, logger }),\n    [publishableKey, iframeOrigin, apiBase, logger],\n  );\n  return <BillKitContext.Provider value={value}>{children}</BillKitContext.Provider>;\n}\n\n/**\n * Read the nearest {@link BillKitProvider}. Throws a clear error when an\n * element is rendered outside a provider, the most common integration\n * mistake.\n */\nexport function useBillKit(): BillKitContextValue {\n  const ctx = useContext(BillKitContext);\n  if (ctx === null) {\n    throw new Error(\n      \"BillKit: a <CheckoutElement/> must be rendered inside a <BillKitProvider>.\",\n    );\n  }\n  return ctx;\n}\n","import type {\n  BaseElementOptions,\n  BillKitElementError,\n  BillKitElementHandle,\n  BillKitElementLogger,\n  BillKitThemeTokens,\n  ChangeEvent,\n  SuccessEvent,\n} from \"@billkit-eu/js\";\nimport { useEffect, useRef, useState } from \"react\";\nimport { useBillKit } from \"./BillKitProvider\";\n\n/** Callback + presentational props common to the React element components. */\nexport interface ReactElementProps {\n  /** Ephemeral checkout `client_secret` (`<sessionId>_secret_...`). */\n  clientSecret: string;\n  theme?: BillKitThemeTokens;\n  locale?: string;\n  /** Load-watchdog timeout (ms) before `onError({code:\"load_timeout\"})`. */\n  loadTimeoutMs?: number;\n  /**\n   * Overrides the provider's `logger` for this element only. Omitted,\n   * the provider's is used; with neither, the element is silent.\n   */\n  logger?: BillKitElementLogger;\n  /** Applied to the container `<div>` the iframe mounts into. */\n  className?: string;\n  style?: React.CSSProperties;\n  onReady?: () => void;\n  onChange?: (event: ChangeEvent) => void;\n  onSuccess?: (event: SuccessEvent) => void;\n  onError?: (error: BillKitElementError) => void;\n  onRedirect?: (url: string) => boolean | void;\n}\n\ntype MountFn = (\n  target: HTMLElement,\n  options: BaseElementOptions,\n) => BillKitElementHandle;\n\n/**\n * SSR-safe mount hook shared by `<CheckoutElement/>` and\n * `<PaymentMethodElement/>`.\n *\n * - Returns `isClient = false` on the server and on the first client\n *   render, so the component renders `null` and hydration matches. The\n *   `useEffect` then flips it true and the real mount happens, with no\n *   hydration mismatch, no `window` access during render.\n * - Callbacks are read through a ref, so a parent passing fresh closures\n *   every render never forces a costly iframe remount. Only the identity\n *   inputs (secret, origins) remount; theme changes hot-update in place.\n */\nexport function useElement(\n  mount: MountFn,\n  props: ReactElementProps,\n): { isClient: boolean; containerRef: React.RefObject<HTMLDivElement> } {\n  const { iframeOrigin, apiBase, logger: providerLogger } = useBillKit();\n  const [isClient, setIsClient] = useState(false);\n  const containerRef = useRef<HTMLDivElement>(null);\n  const handleRef = useRef<BillKitElementHandle | null>(null);\n\n  // Latest callbacks, read at event time and decoupled from remount inputs.\n  const callbacks = useRef(props);\n  callbacks.current = props;\n\n  // Same trick for the logger: resolve it at call time through a ref so\n  // an inline `logger={{...}}` (or switching one on mid-session) never\n  // tears down and rebuilds the payment iframe. The element always\n  // receives this one stable object; it forwards to whatever is current,\n  // or drops the line when neither prop nor provider supplies one.\n  const activeLogger = useRef<BillKitElementLogger | undefined>(undefined);\n  activeLogger.current = props.logger ?? providerLogger;\n  const stableLogger = useRef<BillKitElementLogger>({\n    debug: (message, context) => activeLogger.current?.debug(message, context),\n    warn: (message, context) => activeLogger.current?.warn(message, context),\n  }).current;\n\n  useEffect(() => setIsClient(true), []);\n\n  const themeKey = props.theme ? JSON.stringify(props.theme) : \"\";\n\n  useEffect(() => {\n    if (!isClient || containerRef.current === null) return;\n    const options: BaseElementOptions = {\n      clientSecret: props.clientSecret,\n      ...(props.theme ? { theme: props.theme } : {}),\n      ...(props.locale ? { locale: props.locale } : {}),\n      ...(iframeOrigin ? { iframeOrigin } : {}),\n      ...(apiBase ? { apiBase } : {}),\n      ...(props.loadTimeoutMs !== undefined ? { loadTimeoutMs: props.loadTimeoutMs } : {}),\n      logger: stableLogger,\n      onReady: () => callbacks.current.onReady?.(),\n      onChange: (e) => callbacks.current.onChange?.(e),\n      onSuccess: (e) => callbacks.current.onSuccess?.(e),\n      onError: (e) => callbacks.current.onError?.(e),\n      onRedirect: (url) => callbacks.current.onRedirect?.(url),\n    };\n    const handle = mount(containerRef.current, options);\n    handleRef.current = handle;\n    return () => {\n      handle.destroy();\n      handleRef.current = null;\n    };\n    // Remount only on identity inputs (secret / origins); callbacks are\n    // read through a ref and theme is hot-applied in the effect below, so\n    // neither belongs in this dependency list.\n  }, [isClient, props.clientSecret, props.locale, iframeOrigin, apiBase]);\n\n  // Hot-apply theme changes without tearing down the iframe.\n  useEffect(() => {\n    if (themeKey && handleRef.current && props.theme) {\n      handleRef.current.updateTheme(props.theme);\n    }\n  }, [themeKey]);\n\n  return { isClient, containerRef };\n}\n","import { mountCheckoutElement } from \"@billkit-eu/js\";\nimport { type ReactElementProps, useElement } from \"./useElement\";\n\nexport type CheckoutElementProps = ReactElementProps;\n\n/**\n * Embedded checkout, as a React component. SSR-safe: renders `null` on the\n * server and the first client render, then mounts the js.billkit.eu iframe\n * after hydration.\n *\n * ```tsx\n * <BillKitProvider>\n *   <CheckoutElement\n *     clientSecret={clientSecret}\n *     theme={{ colorPrimary: \"#6d28d9\", borderRadius: \"10px\" }}\n *     onSuccess={({ sessionId }) => router.push(`/thanks?cs=${sessionId}`)}\n *   />\n * </BillKitProvider>\n * ```\n */\nexport function CheckoutElement(props: CheckoutElementProps): JSX.Element | null {\n  const { isClient, containerRef } = useElement(mountCheckoutElement, props);\n  if (!isClient) return null;\n  return <div ref={containerRef} className={props.className} style={props.style} />;\n}\n","import { type BaseElementOptions, type BillKitElementHandle, mountPaymentMethodElement } from \"@billkit-eu/js\";\nimport { type ReactElementProps, useElement } from \"./useElement\";\n\nexport interface PaymentMethodElementProps extends ReactElementProps {\n  /** The customer whose saved payment methods to render + manage. */\n  customerId: string;\n}\n\n/**\n * The customer's saved payment methods (\"Visa •••• 4242 · Update\"), as a\n * React component. Same SSR-safe mounting as {@link CheckoutElement}.\n */\nexport function PaymentMethodElement(props: PaymentMethodElementProps): JSX.Element | null {\n  const { customerId } = props;\n  const mount = (target: HTMLElement, options: BaseElementOptions): BillKitElementHandle =>\n    mountPaymentMethodElement(target, { ...options, customerId });\n  const { isClient, containerRef } = useElement(mount, props);\n  if (!isClient) return null;\n  return <div ref={containerRef} className={props.className} style={props.style} />;\n}\n"]}
+{"version":3,"sources":["../src/BillKitProvider.tsx","../src/useElement.ts","../src/CheckoutElement.tsx","../src/PaymentMethodElement.tsx"],"names":["createContext","useMemo","jsx","useContext","useState","useRef","useEffect","forwardRef","CheckoutElement","mountCheckoutElement","useImperativeHandle","PaymentMethodElement","mountPaymentMethodElement"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { BillKitElementLogger } from \"@billkit-eu/js\";\nimport { createContext, type ReactNode, useContext, useMemo } from \"react\";\n\n/**\n * Config shared by every BillKit element on the page. Mirrors\n * `@stripe/react-stripe-js`'s `<Elements>` provider — minus the key:\n * BillKit has no publishable-key concept. The API only mints secret keys\n * (`sk_live_...` / `sk_test_...`), which must never reach a browser;\n * elements authenticate with the ephemeral `client_secret` your server\n * gets from `POST /v1/checkout/sessions` with `ui_mode: \"embedded\"`, and\n * that secret already names the tenant, the mode, and the session. So the\n * provider carries origin overrides and a logger, nothing credential-shaped.\n */\nexport interface BillKitContextValue {\n  /** Origin the element iframe is served from. Defaults to js.billkit.eu. */\n  iframeOrigin?: string;\n  /** API origin the iframe calls. Defaults to api.billkit.eu. */\n  apiBase?: string;\n  /**\n   * Where every element beneath this provider sends its lifecycle\n   * diagnostics: iframe boot, dropped `postMessage`s, refused\n   * redirects, load timeouts. Omitted (the default) means silence: the\n   * elements never write to `console` on their own.\n   *\n   * `console` works as-is. An individual element can override this with\n   * its own `logger` prop. The `clientSecret` is never passed to it.\n   */\n  logger?: BillKitElementLogger;\n}\n\nconst BillKitContext = createContext<BillKitContextValue | null>(null);\n\nexport interface BillKitProviderProps extends BillKitContextValue {\n  children: ReactNode;\n}\n\n/**\n * Wrap the part of your tree that renders BillKit elements.\n *\n * No credential is needed here; the element authenticates with the\n * ephemeral `client_secret` your server minted for the session:\n *\n * ```tsx\n * <BillKitProvider>\n *   <CheckoutElement clientSecret={clientSecret} onSuccess={done} />\n * </BillKitProvider>\n * ```\n */\nexport function BillKitProvider({\n  iframeOrigin,\n  apiBase,\n  logger,\n  children,\n}: BillKitProviderProps): JSX.Element {\n  const value = useMemo<BillKitContextValue>(\n    () => ({ iframeOrigin, apiBase, logger }),\n    [iframeOrigin, apiBase, logger],\n  );\n  return <BillKitContext.Provider value={value}>{children}</BillKitContext.Provider>;\n}\n\n/**\n * Read the nearest {@link BillKitProvider}. Throws a clear error when an\n * element is rendered outside a provider, the most common integration\n * mistake.\n */\nexport function useBillKit(): BillKitContextValue {\n  const ctx = useContext(BillKitContext);\n  if (ctx === null) {\n    throw new Error(\n      \"BillKit: a <CheckoutElement/> must be rendered inside a <BillKitProvider>.\",\n    );\n  }\n  return ctx;\n}\n","import type {\n  BaseElementOptions,\n  BillKitElementError,\n  BillKitElementHandle,\n  BillKitElementLogger,\n  BillKitThemeTokens,\n  ChangeEvent,\n  SuccessEvent,\n} from \"@billkit-eu/js\";\nimport { useEffect, useRef, useState } from \"react\";\nimport { useBillKit } from \"./BillKitProvider\";\n\n/** Callback + presentational props common to the React element components. */\nexport interface ReactElementProps {\n  /** Ephemeral checkout `client_secret` (`<sessionId>_secret_...`). */\n  clientSecret: string;\n  theme?: BillKitThemeTokens;\n  locale?: string;\n  /** Load-watchdog timeout (ms) before `onError({code:\"load_timeout\"})`. */\n  loadTimeoutMs?: number;\n  /**\n   * Overrides the provider's `logger` for this element only. Omitted,\n   * the provider's is used; with neither, the element is silent.\n   */\n  logger?: BillKitElementLogger;\n  /** Applied to the container `<div>` the iframe mounts into. */\n  className?: string;\n  style?: React.CSSProperties;\n  onReady?: () => void;\n  onChange?: (event: ChangeEvent) => void;\n  onSuccess?: (event: SuccessEvent) => void;\n  onError?: (error: BillKitElementError) => void;\n  onRedirect?: (url: string) => boolean | void;\n}\n\ntype MountFn = (\n  target: HTMLElement,\n  options: BaseElementOptions,\n) => BillKitElementHandle;\n\n/**\n * SSR-safe mount hook shared by `<CheckoutElement/>` and\n * `<PaymentMethodElement/>`.\n *\n * - Returns `isClient = false` on the server and on the first client\n *   render, so the component renders `null` and hydration matches. The\n *   `useEffect` then flips it true and the real mount happens, with no\n *   hydration mismatch, no `window` access during render.\n * - Callbacks are read through a ref, so a parent passing fresh closures\n *   every render never forces a costly iframe remount. Only the identity\n *   inputs (secret, origins) remount; theme changes hot-update in place.\n */\nexport function useElement(\n  mount: MountFn,\n  // `customerId` is not part of the public `ReactElementProps` (only the\n  // payment-method element has one), but the hook still has to *see* it:\n  // it is a remount input, and leaving it out of the dependency list\n  // meant switching customers kept the previous customer's wallet — and\n  // its \"set default\" / \"remove\" actions — on screen.\n  props: ReactElementProps & { customerId?: string },\n): {\n  isClient: boolean;\n  containerRef: React.RefObject<HTMLDivElement>;\n  handleRef: React.RefObject<BillKitElementHandle | null>;\n} {\n  const { iframeOrigin, apiBase, logger: providerLogger } = useBillKit();\n  const [isClient, setIsClient] = useState(false);\n  const containerRef = useRef<HTMLDivElement>(null);\n  const handleRef = useRef<BillKitElementHandle | null>(null);\n\n  // Latest callbacks, read at event time and decoupled from remount inputs.\n  const callbacks = useRef(props);\n  callbacks.current = props;\n\n  // Same trick for the logger: resolve it at call time through a ref so\n  // an inline `logger={{...}}` (or switching one on mid-session) never\n  // tears down and rebuilds the payment iframe. The element always\n  // receives this one stable object; it forwards to whatever is current,\n  // or drops the line when neither prop nor provider supplies one.\n  const activeLogger = useRef<BillKitElementLogger | undefined>(undefined);\n  activeLogger.current = props.logger ?? providerLogger;\n  const stableLogger = useRef<BillKitElementLogger>({\n    debug: (message, context) => activeLogger.current?.debug(message, context),\n    warn: (message, context) => activeLogger.current?.warn(message, context),\n  }).current;\n\n  useEffect(() => setIsClient(true), []);\n\n  const themeKey = props.theme ? JSON.stringify(props.theme) : \"\";\n\n  useEffect(() => {\n    if (!isClient || containerRef.current === null) return;\n    const options: BaseElementOptions = {\n      clientSecret: props.clientSecret,\n      ...(props.theme ? { theme: props.theme } : {}),\n      ...(props.locale ? { locale: props.locale } : {}),\n      ...(iframeOrigin ? { iframeOrigin } : {}),\n      ...(apiBase ? { apiBase } : {}),\n      ...(props.loadTimeoutMs !== undefined ? { loadTimeoutMs: props.loadTimeoutMs } : {}),\n      logger: stableLogger,\n      onReady: () => callbacks.current.onReady?.(),\n      onChange: (e) => callbacks.current.onChange?.(e),\n      onSuccess: (e) => callbacks.current.onSuccess?.(e),\n      onError: (e) => callbacks.current.onError?.(e),\n      onRedirect: (url) => callbacks.current.onRedirect?.(url),\n    };\n    const handle = mount(containerRef.current, options);\n    handleRef.current = handle;\n    return () => {\n      handle.destroy();\n      handleRef.current = null;\n    };\n    // Remount only on identity inputs (secret / customer / origins);\n    // callbacks are read through a ref and theme is hot-applied in the\n    // effect below, so neither belongs in this dependency list.\n  }, [isClient, props.clientSecret, props.customerId, props.locale, iframeOrigin, apiBase]);\n\n  // Hot-apply theme changes without tearing down the iframe.\n  useEffect(() => {\n    if (themeKey && handleRef.current && props.theme) {\n      handleRef.current.updateTheme(props.theme);\n    }\n  }, [themeKey]);\n\n  return { isClient, containerRef, handleRef };\n}\n\n/**\n * The imperative handle `<CheckoutElement/>` and\n * `<PaymentMethodElement/>` expose through `ref`.\n *\n * Everything else about these components is declarative, but submitting\n * is genuinely an *event*, not a state: a merchant's own pay button\n * lives outside the iframe (that is the point of `onChange.complete`),\n * and it has to be able to say \"go\" exactly once. A `submit` prop would\n * have to be a toggling boolean, which is the classic React smell for an\n * action modelled as state, so this follows the\n * `useImperativeHandle` path that `<input>`'s `focus()` set.\n *\n * Calls made before the iframe has mounted are no-ops rather than\n * throwing — on the server, and on the first client render, there is no\n * element yet.\n */\nexport interface ThemeableElementRef {\n  /** Push new theme tokens in without remounting. */\n  updateTheme(theme: BillKitThemeTokens): void;\n}\n\nexport interface BillKitElementRef extends ThemeableElementRef {\n  /** Submit the form from your own pay button. */\n  submit(): void;\n}\n\n/** Build the ref `<CheckoutElement/>` exposes. */\nexport function checkoutElementRef(\n  handleRef: React.RefObject<BillKitElementHandle | null>,\n): BillKitElementRef {\n  return {\n    submit: () => handleRef.current?.submit(),\n    updateTheme: (theme) => handleRef.current?.updateTheme(theme),\n  };\n}\n\n/**\n * Build the ref `<PaymentMethodElement/>` exposes.\n *\n * Deliberately no `submit`: the wallet element drops `billkit:submit` on\n * the floor (there is no form to submit — its actions are per-row \"set\n * default\" / \"remove\" buttons inside the iframe). Exposing a method that\n * silently does nothing would be worse than not having one.\n */\nexport function themeableElementRef(\n  handleRef: React.RefObject<BillKitElementHandle | null>,\n): ThemeableElementRef {\n  return {\n    updateTheme: (theme) => handleRef.current?.updateTheme(theme),\n  };\n}\n","import { mountCheckoutElement } from \"@billkit-eu/js\";\nimport { forwardRef, useImperativeHandle } from \"react\";\nimport {\n  type BillKitElementRef,\n  checkoutElementRef,\n  type ReactElementProps,\n  useElement,\n} from \"./useElement\";\n\nexport type CheckoutElementProps = ReactElementProps;\n\n/**\n * Embedded checkout, as a React component. SSR-safe: renders `null` on the\n * server and the first client render, then mounts the js.billkit.eu iframe\n * after hydration.\n *\n * ```tsx\n * <BillKitProvider>\n *   <CheckoutElement\n *     clientSecret={clientSecret}\n *     theme={{ colorPrimary: \"#6d28d9\", borderRadius: \"10px\" }}\n *     onSuccess={({ sessionId }) => router.push(`/thanks?cs=${sessionId}`)}\n *   />\n * </BillKitProvider>\n * ```\n *\n * Driving your own pay button: take a `ref` and call `submit()`. Gate the\n * button on `onChange`'s `complete`, and re-enable it from `onError` —\n * a declined card fires `onError({ code: \"payment_declined\" })` and the\n * element shows its own retry panel.\n *\n * ```tsx\n * const element = useRef<BillKitElementRef>(null);\n * const [ready, setReady] = useState(false);\n * <>\n *   <CheckoutElement\n *     ref={element}\n *     clientSecret={clientSecret}\n *     onChange={({ complete }) => setReady(complete)}\n *     onError={() => setSubmitting(false)}\n *   />\n *   <button disabled={!ready} onClick={() => element.current?.submit()}>Pay</button>\n * </>\n * ```\n */\nexport const CheckoutElement = forwardRef<BillKitElementRef, CheckoutElementProps>(\n  function CheckoutElement(props, ref) {\n    const { isClient, containerRef, handleRef } = useElement(mountCheckoutElement, props);\n    // No dependency list: `handleRef` is a stable ref object, and the\n    // closures read `.current` at call time, so the imperative handle\n    // never goes stale across remounts.\n    useImperativeHandle(ref, () => checkoutElementRef(handleRef), []);\n    if (!isClient) return null;\n    return <div ref={containerRef} className={props.className} style={props.style} />;\n  },\n);\n","import { type BaseElementOptions, type BillKitElementHandle, mountPaymentMethodElement } from \"@billkit-eu/js\";\nimport { forwardRef, useImperativeHandle } from \"react\";\nimport {\n  type ReactElementProps,\n  type ThemeableElementRef,\n  themeableElementRef,\n  useElement,\n} from \"./useElement\";\n\nexport interface PaymentMethodElementProps extends ReactElementProps {\n  /** The customer whose saved payment methods to render + manage. */\n  customerId: string;\n}\n\n/**\n * The customer's saved payment methods (\"Visa •••• 4242 · Update\"), as a\n * React component. Same SSR-safe mounting as {@link CheckoutElement}.\n *\n * Changing `customerId` remounts the element, so the wallet on screen\n * always belongs to the customer named in the props.\n *\n * The `ref` exposes `updateTheme()` only — this element has no form to\n * submit; its actions are per-row buttons inside the iframe.\n */\nexport const PaymentMethodElement = forwardRef<ThemeableElementRef, PaymentMethodElementProps>(\n  function PaymentMethodElement(props, ref) {\n    const { customerId } = props;\n    const mount = (target: HTMLElement, options: BaseElementOptions): BillKitElementHandle =>\n      mountPaymentMethodElement(target, { ...options, customerId });\n    const { isClient, containerRef, handleRef } = useElement(mount, props);\n    useImperativeHandle(ref, () => themeableElementRef(handleRef), []);\n    if (!isClient) return null;\n    return <div ref={containerRef} className={props.className} style={props.style} />;\n  },\n);\n"]}

package/dist/index.d.cts

@@ -1,30 +1,19 @@
 import { BillKitElementLogger, BillKitThemeTokens, ChangeEvent, SuccessEvent, BillKitElementError } from '@billkit-eu/js';
 export { BillKitElementError, BillKitElementHandle, BillKitElementLogger, BillKitThemeTokens, ChangeEvent, ElementLogContext, SuccessEvent } from '@billkit-eu/js';
+import * as react from 'react';
 import { ReactNode } from 'react';
 
 /**
  * Config shared by every BillKit element on the page. Mirrors
- * `@stripe/react-stripe-js`'s `<Elements>` provider: put your public key
- * (and any origin overrides) here once, then render elements freely
- * beneath it.
+ * `@stripe/react-stripe-js`'s `<Elements>` provider — minus the key:
+ * BillKit has no publishable-key concept. The API only mints secret keys
+ * (`sk_live_...` / `sk_test_...`), which must never reach a browser;
+ * elements authenticate with the ephemeral `client_secret` your server
+ * gets from `POST /v1/checkout/sessions` with `ui_mode: "embedded"`, and
+ * that secret already names the tenant, the mode, and the session. So the
+ * provider carries origin overrides and a logger, nothing credential-shaped.
  */
 interface BillKitContextValue {
-    /**
-     * @deprecated Not required, not used, and not something BillKit issues.
-     *
-     * BillKit has no publishable-key concept; the API only mints secret
-     * keys (`sk_live_...` / `sk_test_...`), which must never reach a browser.
-     * Elements authenticate with the ephemeral `client_secret` your server
-     * gets from `POST /v1/checkout/sessions` with `ui_mode: "embedded"`,
-     * and that secret already names the tenant, the mode, and the session.
-     *
-     * The prop was accepted (and required) in 0.1.0 by analogy with
-     * `@stripe/react-stripe-js`, but nothing ever read it, and a tenant
-     * following the docs went looking for a `pk_...` value that does not
-     * exist. It is now optional and ignored; pass nothing. It will be
-     * removed in the next major.
-     */
-    publishableKey?: string;
     /** Origin the element iframe is served from. Defaults to js.billkit.eu. */
     iframeOrigin?: string;
     /** API origin the iframe calls. Defaults to api.billkit.eu. */
@@ -55,7 +44,7 @@ interface BillKitProviderProps extends BillKitContextValue {
  * </BillKitProvider>
  * ```
  */
-declare function BillKitProvider({ publishableKey, iframeOrigin, apiBase, logger, children, }: BillKitProviderProps): JSX.Element;
+declare function BillKitProvider({ iframeOrigin, apiBase, logger, children, }: BillKitProviderProps): JSX.Element;
 /**
  * Read the nearest {@link BillKitProvider}. Throws a clear error when an
  * element is rendered outside a provider, the most common integration
@@ -85,6 +74,30 @@ interface ReactElementProps {
     onError?: (error: BillKitElementError) => void;
     onRedirect?: (url: string) => boolean | void;
 }
+/**
+ * The imperative handle `<CheckoutElement/>` and
+ * `<PaymentMethodElement/>` expose through `ref`.
+ *
+ * Everything else about these components is declarative, but submitting
+ * is genuinely an *event*, not a state: a merchant's own pay button
+ * lives outside the iframe (that is the point of `onChange.complete`),
+ * and it has to be able to say "go" exactly once. A `submit` prop would
+ * have to be a toggling boolean, which is the classic React smell for an
+ * action modelled as state, so this follows the
+ * `useImperativeHandle` path that `<input>`'s `focus()` set.
+ *
+ * Calls made before the iframe has mounted are no-ops rather than
+ * throwing — on the server, and on the first client render, there is no
+ * element yet.
+ */
+interface ThemeableElementRef {
+    /** Push new theme tokens in without remounting. */
+    updateTheme(theme: BillKitThemeTokens): void;
+}
+interface BillKitElementRef extends ThemeableElementRef {
+    /** Submit the form from your own pay button. */
+    submit(): void;
+}
 
 type CheckoutElementProps = ReactElementProps;
 /**
@@ -101,8 +114,27 @@ type CheckoutElementProps = ReactElementProps;
  *   />
  * </BillKitProvider>
  * ```
+ *
+ * Driving your own pay button: take a `ref` and call `submit()`. Gate the
+ * button on `onChange`'s `complete`, and re-enable it from `onError` —
+ * a declined card fires `onError({ code: "payment_declined" })` and the
+ * element shows its own retry panel.
+ *
+ * ```tsx
+ * const element = useRef<BillKitElementRef>(null);
+ * const [ready, setReady] = useState(false);
+ * <>
+ *   <CheckoutElement
+ *     ref={element}
+ *     clientSecret={clientSecret}
+ *     onChange={({ complete }) => setReady(complete)}
+ *     onError={() => setSubmitting(false)}
+ *   />
+ *   <button disabled={!ready} onClick={() => element.current?.submit()}>Pay</button>
+ * </>
+ * ```
  */
-declare function CheckoutElement(props: CheckoutElementProps): JSX.Element | null;
+declare const CheckoutElement: react.ForwardRefExoticComponent<ReactElementProps & react.RefAttributes<BillKitElementRef>>;
 
 interface PaymentMethodElementProps extends ReactElementProps {
     /** The customer whose saved payment methods to render + manage. */
@@ -111,7 +143,13 @@ interface PaymentMethodElementProps extends ReactElementProps {
 /**
  * The customer's saved payment methods ("Visa •••• 4242 · Update"), as a
  * React component. Same SSR-safe mounting as {@link CheckoutElement}.
+ *
+ * Changing `customerId` remounts the element, so the wallet on screen
+ * always belongs to the customer named in the props.
+ *
+ * The `ref` exposes `updateTheme()` only — this element has no form to
+ * submit; its actions are per-row buttons inside the iframe.
  */
-declare function PaymentMethodElement(props: PaymentMethodElementProps): JSX.Element | null;
+declare const PaymentMethodElement: react.ForwardRefExoticComponent<PaymentMethodElementProps & react.RefAttributes<ThemeableElementRef>>;
 
-export { type BillKitContextValue, BillKitProvider, type BillKitProviderProps, CheckoutElement, type CheckoutElementProps, PaymentMethodElement, type PaymentMethodElementProps, type ReactElementProps, useBillKit };
+export { type BillKitContextValue, type BillKitElementRef, BillKitProvider, type BillKitProviderProps, CheckoutElement, type CheckoutElementProps, PaymentMethodElement, type PaymentMethodElementProps, type ReactElementProps, type ThemeableElementRef, useBillKit };

package/dist/index.d.ts

@@ -1,30 +1,19 @@
 import { BillKitElementLogger, BillKitThemeTokens, ChangeEvent, SuccessEvent, BillKitElementError } from '@billkit-eu/js';
 export { BillKitElementError, BillKitElementHandle, BillKitElementLogger, BillKitThemeTokens, ChangeEvent, ElementLogContext, SuccessEvent } from '@billkit-eu/js';
+import * as react from 'react';
 import { ReactNode } from 'react';
 
 /**
  * Config shared by every BillKit element on the page. Mirrors
- * `@stripe/react-stripe-js`'s `<Elements>` provider: put your public key
- * (and any origin overrides) here once, then render elements freely
- * beneath it.
+ * `@stripe/react-stripe-js`'s `<Elements>` provider — minus the key:
+ * BillKit has no publishable-key concept. The API only mints secret keys
+ * (`sk_live_...` / `sk_test_...`), which must never reach a browser;
+ * elements authenticate with the ephemeral `client_secret` your server
+ * gets from `POST /v1/checkout/sessions` with `ui_mode: "embedded"`, and
+ * that secret already names the tenant, the mode, and the session. So the
+ * provider carries origin overrides and a logger, nothing credential-shaped.
  */
 interface BillKitContextValue {
-    /**
-     * @deprecated Not required, not used, and not something BillKit issues.
-     *
-     * BillKit has no publishable-key concept; the API only mints secret
-     * keys (`sk_live_...` / `sk_test_...`), which must never reach a browser.
-     * Elements authenticate with the ephemeral `client_secret` your server
-     * gets from `POST /v1/checkout/sessions` with `ui_mode: "embedded"`,
-     * and that secret already names the tenant, the mode, and the session.
-     *
-     * The prop was accepted (and required) in 0.1.0 by analogy with
-     * `@stripe/react-stripe-js`, but nothing ever read it, and a tenant
-     * following the docs went looking for a `pk_...` value that does not
-     * exist. It is now optional and ignored; pass nothing. It will be
-     * removed in the next major.
-     */
-    publishableKey?: string;
     /** Origin the element iframe is served from. Defaults to js.billkit.eu. */
     iframeOrigin?: string;
     /** API origin the iframe calls. Defaults to api.billkit.eu. */
@@ -55,7 +44,7 @@ interface BillKitProviderProps extends BillKitContextValue {
  * </BillKitProvider>
  * ```
  */
-declare function BillKitProvider({ publishableKey, iframeOrigin, apiBase, logger, children, }: BillKitProviderProps): JSX.Element;
+declare function BillKitProvider({ iframeOrigin, apiBase, logger, children, }: BillKitProviderProps): JSX.Element;
 /**
  * Read the nearest {@link BillKitProvider}. Throws a clear error when an
  * element is rendered outside a provider, the most common integration
@@ -85,6 +74,30 @@ interface ReactElementProps {
     onError?: (error: BillKitElementError) => void;
     onRedirect?: (url: string) => boolean | void;
 }
+/**
+ * The imperative handle `<CheckoutElement/>` and
+ * `<PaymentMethodElement/>` expose through `ref`.
+ *
+ * Everything else about these components is declarative, but submitting
+ * is genuinely an *event*, not a state: a merchant's own pay button
+ * lives outside the iframe (that is the point of `onChange.complete`),
+ * and it has to be able to say "go" exactly once. A `submit` prop would
+ * have to be a toggling boolean, which is the classic React smell for an
+ * action modelled as state, so this follows the
+ * `useImperativeHandle` path that `<input>`'s `focus()` set.
+ *
+ * Calls made before the iframe has mounted are no-ops rather than
+ * throwing — on the server, and on the first client render, there is no
+ * element yet.
+ */
+interface ThemeableElementRef {
+    /** Push new theme tokens in without remounting. */
+    updateTheme(theme: BillKitThemeTokens): void;
+}
+interface BillKitElementRef extends ThemeableElementRef {
+    /** Submit the form from your own pay button. */
+    submit(): void;
+}
 
 type CheckoutElementProps = ReactElementProps;
 /**
@@ -101,8 +114,27 @@ type CheckoutElementProps = ReactElementProps;
  *   />
  * </BillKitProvider>
  * ```
+ *
+ * Driving your own pay button: take a `ref` and call `submit()`. Gate the
+ * button on `onChange`'s `complete`, and re-enable it from `onError` —
+ * a declined card fires `onError({ code: "payment_declined" })` and the
+ * element shows its own retry panel.
+ *
+ * ```tsx
+ * const element = useRef<BillKitElementRef>(null);
+ * const [ready, setReady] = useState(false);
+ * <>
+ *   <CheckoutElement
+ *     ref={element}
+ *     clientSecret={clientSecret}
+ *     onChange={({ complete }) => setReady(complete)}
+ *     onError={() => setSubmitting(false)}
+ *   />
+ *   <button disabled={!ready} onClick={() => element.current?.submit()}>Pay</button>
+ * </>
+ * ```
  */
-declare function CheckoutElement(props: CheckoutElementProps): JSX.Element | null;
+declare const CheckoutElement: react.ForwardRefExoticComponent<ReactElementProps & react.RefAttributes<BillKitElementRef>>;
 
 interface PaymentMethodElementProps extends ReactElementProps {
     /** The customer whose saved payment methods to render + manage. */
@@ -111,7 +143,13 @@ interface PaymentMethodElementProps extends ReactElementProps {
 /**
  * The customer's saved payment methods ("Visa •••• 4242 · Update"), as a
  * React component. Same SSR-safe mounting as {@link CheckoutElement}.
+ *
+ * Changing `customerId` remounts the element, so the wallet on screen
+ * always belongs to the customer named in the props.
+ *
+ * The `ref` exposes `updateTheme()` only — this element has no form to
+ * submit; its actions are per-row buttons inside the iframe.
  */
-declare function PaymentMethodElement(props: PaymentMethodElementProps): JSX.Element | null;
+declare const PaymentMethodElement: react.ForwardRefExoticComponent<PaymentMethodElementProps & react.RefAttributes<ThemeableElementRef>>;
 
-export { type BillKitContextValue, BillKitProvider, type BillKitProviderProps, CheckoutElement, type CheckoutElementProps, PaymentMethodElement, type PaymentMethodElementProps, type ReactElementProps, useBillKit };
+export { type BillKitContextValue, type BillKitElementRef, BillKitProvider, type BillKitProviderProps, CheckoutElement, type CheckoutElementProps, PaymentMethodElement, type PaymentMethodElementProps, type ReactElementProps, type ThemeableElementRef, useBillKit };

package/dist/index.js

@@ -1,19 +1,18 @@
-import { createContext, useMemo, useContext, useState, useRef, useEffect } from 'react';
+import { createContext, forwardRef, useImperativeHandle, useState, useRef, useEffect, useContext, useMemo } from 'react';
 import { jsx } from 'react/jsx-runtime';
 import { mountCheckoutElement, mountPaymentMethodElement } from '@billkit-eu/js';
 
 // src/BillKitProvider.tsx
 var BillKitContext = createContext(null);
 function BillKitProvider({
-  publishableKey,
   iframeOrigin,
   apiBase,
   logger,
   children
 }) {
   const value = useMemo(
-    () => ({ publishableKey, iframeOrigin, apiBase, logger }),
-    [publishableKey, iframeOrigin, apiBase, logger]
+    () => ({ iframeOrigin, apiBase, logger }),
+    [iframeOrigin, apiBase, logger]
   );
   return /* @__PURE__ */ jsx(BillKitContext.Provider, { value, children });
 }
@@ -63,26 +62,43 @@ function useElement(mount, props) {
       handle.destroy();
       handleRef.current = null;
     };
-  }, [isClient, props.clientSecret, props.locale, iframeOrigin, apiBase]);
+  }, [isClient, props.clientSecret, props.customerId, props.locale, iframeOrigin, apiBase]);
   useEffect(() => {
     if (themeKey && handleRef.current && props.theme) {
       handleRef.current.updateTheme(props.theme);
     }
   }, [themeKey]);
-  return { isClient, containerRef };
+  return { isClient, containerRef, handleRef };
 }
-function CheckoutElement(props) {
-  const { isClient, containerRef } = useElement(mountCheckoutElement, props);
-  if (!isClient) return null;
-  return /* @__PURE__ */ jsx("div", { ref: containerRef, className: props.className, style: props.style });
+function checkoutElementRef(handleRef) {
+  return {
+    submit: () => handleRef.current?.submit(),
+    updateTheme: (theme) => handleRef.current?.updateTheme(theme)
+  };
 }
-function PaymentMethodElement(props) {
-  const { customerId } = props;
-  const mount = (target, options) => mountPaymentMethodElement(target, { ...options, customerId });
-  const { isClient, containerRef } = useElement(mount, props);
-  if (!isClient) return null;
-  return /* @__PURE__ */ jsx("div", { ref: containerRef, className: props.className, style: props.style });
+function themeableElementRef(handleRef) {
+  return {
+    updateTheme: (theme) => handleRef.current?.updateTheme(theme)
+  };
 }
+var CheckoutElement = forwardRef(
+  function CheckoutElement2(props, ref) {
+    const { isClient, containerRef, handleRef } = useElement(mountCheckoutElement, props);
+    useImperativeHandle(ref, () => checkoutElementRef(handleRef), []);
+    if (!isClient) return null;
+    return /* @__PURE__ */ jsx("div", { ref: containerRef, className: props.className, style: props.style });
+  }
+);
+var PaymentMethodElement = forwardRef(
+  function PaymentMethodElement2(props, ref) {
+    const { customerId } = props;
+    const mount = (target, options) => mountPaymentMethodElement(target, { ...options, customerId });
+    const { isClient, containerRef, handleRef } = useElement(mount, props);
+    useImperativeHandle(ref, () => themeableElementRef(handleRef), []);
+    if (!isClient) return null;
+    return /* @__PURE__ */ jsx("div", { ref: containerRef, className: props.className, style: props.style });
+  }
+);
 
 export { BillKitProvider, CheckoutElement, PaymentMethodElement, useBillKit };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/BillKitProvider.tsx","../src/useElement.ts","../src/CheckoutElement.tsx","../src/PaymentMethodElement.tsx"],"names":["jsx"],"mappings":"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","file":"index.js","sourcesContent":["import type { BillKitElementLogger } from \"@billkit-eu/js\";\nimport { createContext, type ReactNode, useContext, useMemo } from \"react\";\n\n/**\n * Config shared by every BillKit element on the page. Mirrors\n * `@stripe/react-stripe-js`'s `<Elements>` provider: put your public key\n * (and any origin overrides) here once, then render elements freely\n * beneath it.\n */\nexport interface BillKitContextValue {\n  /**\n   * @deprecated Not required, not used, and not something BillKit issues.\n   *\n   * BillKit has no publishable-key concept; the API only mints secret\n   * keys (`sk_live_...` / `sk_test_...`), which must never reach a browser.\n   * Elements authenticate with the ephemeral `client_secret` your server\n   * gets from `POST /v1/checkout/sessions` with `ui_mode: \"embedded\"`,\n   * and that secret already names the tenant, the mode, and the session.\n   *\n   * The prop was accepted (and required) in 0.1.0 by analogy with\n   * `@stripe/react-stripe-js`, but nothing ever read it, and a tenant\n   * following the docs went looking for a `pk_...` value that does not\n   * exist. It is now optional and ignored; pass nothing. It will be\n   * removed in the next major.\n   */\n  publishableKey?: string;\n  /** Origin the element iframe is served from. Defaults to js.billkit.eu. */\n  iframeOrigin?: string;\n  /** API origin the iframe calls. Defaults to api.billkit.eu. */\n  apiBase?: string;\n  /**\n   * Where every element beneath this provider sends its lifecycle\n   * diagnostics: iframe boot, dropped `postMessage`s, refused\n   * redirects, load timeouts. Omitted (the default) means silence: the\n   * elements never write to `console` on their own.\n   *\n   * `console` works as-is. An individual element can override this with\n   * its own `logger` prop. The `clientSecret` is never passed to it.\n   */\n  logger?: BillKitElementLogger;\n}\n\nconst BillKitContext = createContext<BillKitContextValue | null>(null);\n\nexport interface BillKitProviderProps extends BillKitContextValue {\n  children: ReactNode;\n}\n\n/**\n * Wrap the part of your tree that renders BillKit elements.\n *\n * No credential is needed here; the element authenticates with the\n * ephemeral `client_secret` your server minted for the session:\n *\n * ```tsx\n * <BillKitProvider>\n *   <CheckoutElement clientSecret={clientSecret} onSuccess={done} />\n * </BillKitProvider>\n * ```\n */\nexport function BillKitProvider({\n  publishableKey,\n  iframeOrigin,\n  apiBase,\n  logger,\n  children,\n}: BillKitProviderProps): JSX.Element {\n  const value = useMemo<BillKitContextValue>(\n    () => ({ publishableKey, iframeOrigin, apiBase, logger }),\n    [publishableKey, iframeOrigin, apiBase, logger],\n  );\n  return <BillKitContext.Provider value={value}>{children}</BillKitContext.Provider>;\n}\n\n/**\n * Read the nearest {@link BillKitProvider}. Throws a clear error when an\n * element is rendered outside a provider, the most common integration\n * mistake.\n */\nexport function useBillKit(): BillKitContextValue {\n  const ctx = useContext(BillKitContext);\n  if (ctx === null) {\n    throw new Error(\n      \"BillKit: a <CheckoutElement/> must be rendered inside a <BillKitProvider>.\",\n    );\n  }\n  return ctx;\n}\n","import type {\n  BaseElementOptions,\n  BillKitElementError,\n  BillKitElementHandle,\n  BillKitElementLogger,\n  BillKitThemeTokens,\n  ChangeEvent,\n  SuccessEvent,\n} from \"@billkit-eu/js\";\nimport { useEffect, useRef, useState } from \"react\";\nimport { useBillKit } from \"./BillKitProvider\";\n\n/** Callback + presentational props common to the React element components. */\nexport interface ReactElementProps {\n  /** Ephemeral checkout `client_secret` (`<sessionId>_secret_...`). */\n  clientSecret: string;\n  theme?: BillKitThemeTokens;\n  locale?: string;\n  /** Load-watchdog timeout (ms) before `onError({code:\"load_timeout\"})`. */\n  loadTimeoutMs?: number;\n  /**\n   * Overrides the provider's `logger` for this element only. Omitted,\n   * the provider's is used; with neither, the element is silent.\n   */\n  logger?: BillKitElementLogger;\n  /** Applied to the container `<div>` the iframe mounts into. */\n  className?: string;\n  style?: React.CSSProperties;\n  onReady?: () => void;\n  onChange?: (event: ChangeEvent) => void;\n  onSuccess?: (event: SuccessEvent) => void;\n  onError?: (error: BillKitElementError) => void;\n  onRedirect?: (url: string) => boolean | void;\n}\n\ntype MountFn = (\n  target: HTMLElement,\n  options: BaseElementOptions,\n) => BillKitElementHandle;\n\n/**\n * SSR-safe mount hook shared by `<CheckoutElement/>` and\n * `<PaymentMethodElement/>`.\n *\n * - Returns `isClient = false` on the server and on the first client\n *   render, so the component renders `null` and hydration matches. The\n *   `useEffect` then flips it true and the real mount happens, with no\n *   hydration mismatch, no `window` access during render.\n * - Callbacks are read through a ref, so a parent passing fresh closures\n *   every render never forces a costly iframe remount. Only the identity\n *   inputs (secret, origins) remount; theme changes hot-update in place.\n */\nexport function useElement(\n  mount: MountFn,\n  props: ReactElementProps,\n): { isClient: boolean; containerRef: React.RefObject<HTMLDivElement> } {\n  const { iframeOrigin, apiBase, logger: providerLogger } = useBillKit();\n  const [isClient, setIsClient] = useState(false);\n  const containerRef = useRef<HTMLDivElement>(null);\n  const handleRef = useRef<BillKitElementHandle | null>(null);\n\n  // Latest callbacks, read at event time and decoupled from remount inputs.\n  const callbacks = useRef(props);\n  callbacks.current = props;\n\n  // Same trick for the logger: resolve it at call time through a ref so\n  // an inline `logger={{...}}` (or switching one on mid-session) never\n  // tears down and rebuilds the payment iframe. The element always\n  // receives this one stable object; it forwards to whatever is current,\n  // or drops the line when neither prop nor provider supplies one.\n  const activeLogger = useRef<BillKitElementLogger | undefined>(undefined);\n  activeLogger.current = props.logger ?? providerLogger;\n  const stableLogger = useRef<BillKitElementLogger>({\n    debug: (message, context) => activeLogger.current?.debug(message, context),\n    warn: (message, context) => activeLogger.current?.warn(message, context),\n  }).current;\n\n  useEffect(() => setIsClient(true), []);\n\n  const themeKey = props.theme ? JSON.stringify(props.theme) : \"\";\n\n  useEffect(() => {\n    if (!isClient || containerRef.current === null) return;\n    const options: BaseElementOptions = {\n      clientSecret: props.clientSecret,\n      ...(props.theme ? { theme: props.theme } : {}),\n      ...(props.locale ? { locale: props.locale } : {}),\n      ...(iframeOrigin ? { iframeOrigin } : {}),\n      ...(apiBase ? { apiBase } : {}),\n      ...(props.loadTimeoutMs !== undefined ? { loadTimeoutMs: props.loadTimeoutMs } : {}),\n      logger: stableLogger,\n      onReady: () => callbacks.current.onReady?.(),\n      onChange: (e) => callbacks.current.onChange?.(e),\n      onSuccess: (e) => callbacks.current.onSuccess?.(e),\n      onError: (e) => callbacks.current.onError?.(e),\n      onRedirect: (url) => callbacks.current.onRedirect?.(url),\n    };\n    const handle = mount(containerRef.current, options);\n    handleRef.current = handle;\n    return () => {\n      handle.destroy();\n      handleRef.current = null;\n    };\n    // Remount only on identity inputs (secret / origins); callbacks are\n    // read through a ref and theme is hot-applied in the effect below, so\n    // neither belongs in this dependency list.\n  }, [isClient, props.clientSecret, props.locale, iframeOrigin, apiBase]);\n\n  // Hot-apply theme changes without tearing down the iframe.\n  useEffect(() => {\n    if (themeKey && handleRef.current && props.theme) {\n      handleRef.current.updateTheme(props.theme);\n    }\n  }, [themeKey]);\n\n  return { isClient, containerRef };\n}\n","import { mountCheckoutElement } from \"@billkit-eu/js\";\nimport { type ReactElementProps, useElement } from \"./useElement\";\n\nexport type CheckoutElementProps = ReactElementProps;\n\n/**\n * Embedded checkout, as a React component. SSR-safe: renders `null` on the\n * server and the first client render, then mounts the js.billkit.eu iframe\n * after hydration.\n *\n * ```tsx\n * <BillKitProvider>\n *   <CheckoutElement\n *     clientSecret={clientSecret}\n *     theme={{ colorPrimary: \"#6d28d9\", borderRadius: \"10px\" }}\n *     onSuccess={({ sessionId }) => router.push(`/thanks?cs=${sessionId}`)}\n *   />\n * </BillKitProvider>\n * ```\n */\nexport function CheckoutElement(props: CheckoutElementProps): JSX.Element | null {\n  const { isClient, containerRef } = useElement(mountCheckoutElement, props);\n  if (!isClient) return null;\n  return <div ref={containerRef} className={props.className} style={props.style} />;\n}\n","import { type BaseElementOptions, type BillKitElementHandle, mountPaymentMethodElement } from \"@billkit-eu/js\";\nimport { type ReactElementProps, useElement } from \"./useElement\";\n\nexport interface PaymentMethodElementProps extends ReactElementProps {\n  /** The customer whose saved payment methods to render + manage. */\n  customerId: string;\n}\n\n/**\n * The customer's saved payment methods (\"Visa •••• 4242 · Update\"), as a\n * React component. Same SSR-safe mounting as {@link CheckoutElement}.\n */\nexport function PaymentMethodElement(props: PaymentMethodElementProps): JSX.Element | null {\n  const { customerId } = props;\n  const mount = (target: HTMLElement, options: BaseElementOptions): BillKitElementHandle =>\n    mountPaymentMethodElement(target, { ...options, customerId });\n  const { isClient, containerRef } = useElement(mount, props);\n  if (!isClient) return null;\n  return <div ref={containerRef} className={props.className} style={props.style} />;\n}\n"]}
+{"version":3,"sources":["../src/BillKitProvider.tsx","../src/useElement.ts","../src/CheckoutElement.tsx","../src/PaymentMethodElement.tsx"],"names":["CheckoutElement","jsx","forwardRef","PaymentMethodElement","useImperativeHandle"],"mappings":"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","file":"index.js","sourcesContent":["import type { BillKitElementLogger } from \"@billkit-eu/js\";\nimport { createContext, type ReactNode, useContext, useMemo } from \"react\";\n\n/**\n * Config shared by every BillKit element on the page. Mirrors\n * `@stripe/react-stripe-js`'s `<Elements>` provider — minus the key:\n * BillKit has no publishable-key concept. The API only mints secret keys\n * (`sk_live_...` / `sk_test_...`), which must never reach a browser;\n * elements authenticate with the ephemeral `client_secret` your server\n * gets from `POST /v1/checkout/sessions` with `ui_mode: \"embedded\"`, and\n * that secret already names the tenant, the mode, and the session. So the\n * provider carries origin overrides and a logger, nothing credential-shaped.\n */\nexport interface BillKitContextValue {\n  /** Origin the element iframe is served from. Defaults to js.billkit.eu. */\n  iframeOrigin?: string;\n  /** API origin the iframe calls. Defaults to api.billkit.eu. */\n  apiBase?: string;\n  /**\n   * Where every element beneath this provider sends its lifecycle\n   * diagnostics: iframe boot, dropped `postMessage`s, refused\n   * redirects, load timeouts. Omitted (the default) means silence: the\n   * elements never write to `console` on their own.\n   *\n   * `console` works as-is. An individual element can override this with\n   * its own `logger` prop. The `clientSecret` is never passed to it.\n   */\n  logger?: BillKitElementLogger;\n}\n\nconst BillKitContext = createContext<BillKitContextValue | null>(null);\n\nexport interface BillKitProviderProps extends BillKitContextValue {\n  children: ReactNode;\n}\n\n/**\n * Wrap the part of your tree that renders BillKit elements.\n *\n * No credential is needed here; the element authenticates with the\n * ephemeral `client_secret` your server minted for the session:\n *\n * ```tsx\n * <BillKitProvider>\n *   <CheckoutElement clientSecret={clientSecret} onSuccess={done} />\n * </BillKitProvider>\n * ```\n */\nexport function BillKitProvider({\n  iframeOrigin,\n  apiBase,\n  logger,\n  children,\n}: BillKitProviderProps): JSX.Element {\n  const value = useMemo<BillKitContextValue>(\n    () => ({ iframeOrigin, apiBase, logger }),\n    [iframeOrigin, apiBase, logger],\n  );\n  return <BillKitContext.Provider value={value}>{children}</BillKitContext.Provider>;\n}\n\n/**\n * Read the nearest {@link BillKitProvider}. Throws a clear error when an\n * element is rendered outside a provider, the most common integration\n * mistake.\n */\nexport function useBillKit(): BillKitContextValue {\n  const ctx = useContext(BillKitContext);\n  if (ctx === null) {\n    throw new Error(\n      \"BillKit: a <CheckoutElement/> must be rendered inside a <BillKitProvider>.\",\n    );\n  }\n  return ctx;\n}\n","import type {\n  BaseElementOptions,\n  BillKitElementError,\n  BillKitElementHandle,\n  BillKitElementLogger,\n  BillKitThemeTokens,\n  ChangeEvent,\n  SuccessEvent,\n} from \"@billkit-eu/js\";\nimport { useEffect, useRef, useState } from \"react\";\nimport { useBillKit } from \"./BillKitProvider\";\n\n/** Callback + presentational props common to the React element components. */\nexport interface ReactElementProps {\n  /** Ephemeral checkout `client_secret` (`<sessionId>_secret_...`). */\n  clientSecret: string;\n  theme?: BillKitThemeTokens;\n  locale?: string;\n  /** Load-watchdog timeout (ms) before `onError({code:\"load_timeout\"})`. */\n  loadTimeoutMs?: number;\n  /**\n   * Overrides the provider's `logger` for this element only. Omitted,\n   * the provider's is used; with neither, the element is silent.\n   */\n  logger?: BillKitElementLogger;\n  /** Applied to the container `<div>` the iframe mounts into. */\n  className?: string;\n  style?: React.CSSProperties;\n  onReady?: () => void;\n  onChange?: (event: ChangeEvent) => void;\n  onSuccess?: (event: SuccessEvent) => void;\n  onError?: (error: BillKitElementError) => void;\n  onRedirect?: (url: string) => boolean | void;\n}\n\ntype MountFn = (\n  target: HTMLElement,\n  options: BaseElementOptions,\n) => BillKitElementHandle;\n\n/**\n * SSR-safe mount hook shared by `<CheckoutElement/>` and\n * `<PaymentMethodElement/>`.\n *\n * - Returns `isClient = false` on the server and on the first client\n *   render, so the component renders `null` and hydration matches. The\n *   `useEffect` then flips it true and the real mount happens, with no\n *   hydration mismatch, no `window` access during render.\n * - Callbacks are read through a ref, so a parent passing fresh closures\n *   every render never forces a costly iframe remount. Only the identity\n *   inputs (secret, origins) remount; theme changes hot-update in place.\n */\nexport function useElement(\n  mount: MountFn,\n  // `customerId` is not part of the public `ReactElementProps` (only the\n  // payment-method element has one), but the hook still has to *see* it:\n  // it is a remount input, and leaving it out of the dependency list\n  // meant switching customers kept the previous customer's wallet — and\n  // its \"set default\" / \"remove\" actions — on screen.\n  props: ReactElementProps & { customerId?: string },\n): {\n  isClient: boolean;\n  containerRef: React.RefObject<HTMLDivElement>;\n  handleRef: React.RefObject<BillKitElementHandle | null>;\n} {\n  const { iframeOrigin, apiBase, logger: providerLogger } = useBillKit();\n  const [isClient, setIsClient] = useState(false);\n  const containerRef = useRef<HTMLDivElement>(null);\n  const handleRef = useRef<BillKitElementHandle | null>(null);\n\n  // Latest callbacks, read at event time and decoupled from remount inputs.\n  const callbacks = useRef(props);\n  callbacks.current = props;\n\n  // Same trick for the logger: resolve it at call time through a ref so\n  // an inline `logger={{...}}` (or switching one on mid-session) never\n  // tears down and rebuilds the payment iframe. The element always\n  // receives this one stable object; it forwards to whatever is current,\n  // or drops the line when neither prop nor provider supplies one.\n  const activeLogger = useRef<BillKitElementLogger | undefined>(undefined);\n  activeLogger.current = props.logger ?? providerLogger;\n  const stableLogger = useRef<BillKitElementLogger>({\n    debug: (message, context) => activeLogger.current?.debug(message, context),\n    warn: (message, context) => activeLogger.current?.warn(message, context),\n  }).current;\n\n  useEffect(() => setIsClient(true), []);\n\n  const themeKey = props.theme ? JSON.stringify(props.theme) : \"\";\n\n  useEffect(() => {\n    if (!isClient || containerRef.current === null) return;\n    const options: BaseElementOptions = {\n      clientSecret: props.clientSecret,\n      ...(props.theme ? { theme: props.theme } : {}),\n      ...(props.locale ? { locale: props.locale } : {}),\n      ...(iframeOrigin ? { iframeOrigin } : {}),\n      ...(apiBase ? { apiBase } : {}),\n      ...(props.loadTimeoutMs !== undefined ? { loadTimeoutMs: props.loadTimeoutMs } : {}),\n      logger: stableLogger,\n      onReady: () => callbacks.current.onReady?.(),\n      onChange: (e) => callbacks.current.onChange?.(e),\n      onSuccess: (e) => callbacks.current.onSuccess?.(e),\n      onError: (e) => callbacks.current.onError?.(e),\n      onRedirect: (url) => callbacks.current.onRedirect?.(url),\n    };\n    const handle = mount(containerRef.current, options);\n    handleRef.current = handle;\n    return () => {\n      handle.destroy();\n      handleRef.current = null;\n    };\n    // Remount only on identity inputs (secret / customer / origins);\n    // callbacks are read through a ref and theme is hot-applied in the\n    // effect below, so neither belongs in this dependency list.\n  }, [isClient, props.clientSecret, props.customerId, props.locale, iframeOrigin, apiBase]);\n\n  // Hot-apply theme changes without tearing down the iframe.\n  useEffect(() => {\n    if (themeKey && handleRef.current && props.theme) {\n      handleRef.current.updateTheme(props.theme);\n    }\n  }, [themeKey]);\n\n  return { isClient, containerRef, handleRef };\n}\n\n/**\n * The imperative handle `<CheckoutElement/>` and\n * `<PaymentMethodElement/>` expose through `ref`.\n *\n * Everything else about these components is declarative, but submitting\n * is genuinely an *event*, not a state: a merchant's own pay button\n * lives outside the iframe (that is the point of `onChange.complete`),\n * and it has to be able to say \"go\" exactly once. A `submit` prop would\n * have to be a toggling boolean, which is the classic React smell for an\n * action modelled as state, so this follows the\n * `useImperativeHandle` path that `<input>`'s `focus()` set.\n *\n * Calls made before the iframe has mounted are no-ops rather than\n * throwing — on the server, and on the first client render, there is no\n * element yet.\n */\nexport interface ThemeableElementRef {\n  /** Push new theme tokens in without remounting. */\n  updateTheme(theme: BillKitThemeTokens): void;\n}\n\nexport interface BillKitElementRef extends ThemeableElementRef {\n  /** Submit the form from your own pay button. */\n  submit(): void;\n}\n\n/** Build the ref `<CheckoutElement/>` exposes. */\nexport function checkoutElementRef(\n  handleRef: React.RefObject<BillKitElementHandle | null>,\n): BillKitElementRef {\n  return {\n    submit: () => handleRef.current?.submit(),\n    updateTheme: (theme) => handleRef.current?.updateTheme(theme),\n  };\n}\n\n/**\n * Build the ref `<PaymentMethodElement/>` exposes.\n *\n * Deliberately no `submit`: the wallet element drops `billkit:submit` on\n * the floor (there is no form to submit — its actions are per-row \"set\n * default\" / \"remove\" buttons inside the iframe). Exposing a method that\n * silently does nothing would be worse than not having one.\n */\nexport function themeableElementRef(\n  handleRef: React.RefObject<BillKitElementHandle | null>,\n): ThemeableElementRef {\n  return {\n    updateTheme: (theme) => handleRef.current?.updateTheme(theme),\n  };\n}\n","import { mountCheckoutElement } from \"@billkit-eu/js\";\nimport { forwardRef, useImperativeHandle } from \"react\";\nimport {\n  type BillKitElementRef,\n  checkoutElementRef,\n  type ReactElementProps,\n  useElement,\n} from \"./useElement\";\n\nexport type CheckoutElementProps = ReactElementProps;\n\n/**\n * Embedded checkout, as a React component. SSR-safe: renders `null` on the\n * server and the first client render, then mounts the js.billkit.eu iframe\n * after hydration.\n *\n * ```tsx\n * <BillKitProvider>\n *   <CheckoutElement\n *     clientSecret={clientSecret}\n *     theme={{ colorPrimary: \"#6d28d9\", borderRadius: \"10px\" }}\n *     onSuccess={({ sessionId }) => router.push(`/thanks?cs=${sessionId}`)}\n *   />\n * </BillKitProvider>\n * ```\n *\n * Driving your own pay button: take a `ref` and call `submit()`. Gate the\n * button on `onChange`'s `complete`, and re-enable it from `onError` —\n * a declined card fires `onError({ code: \"payment_declined\" })` and the\n * element shows its own retry panel.\n *\n * ```tsx\n * const element = useRef<BillKitElementRef>(null);\n * const [ready, setReady] = useState(false);\n * <>\n *   <CheckoutElement\n *     ref={element}\n *     clientSecret={clientSecret}\n *     onChange={({ complete }) => setReady(complete)}\n *     onError={() => setSubmitting(false)}\n *   />\n *   <button disabled={!ready} onClick={() => element.current?.submit()}>Pay</button>\n * </>\n * ```\n */\nexport const CheckoutElement = forwardRef<BillKitElementRef, CheckoutElementProps>(\n  function CheckoutElement(props, ref) {\n    const { isClient, containerRef, handleRef } = useElement(mountCheckoutElement, props);\n    // No dependency list: `handleRef` is a stable ref object, and the\n    // closures read `.current` at call time, so the imperative handle\n    // never goes stale across remounts.\n    useImperativeHandle(ref, () => checkoutElementRef(handleRef), []);\n    if (!isClient) return null;\n    return <div ref={containerRef} className={props.className} style={props.style} />;\n  },\n);\n","import { type BaseElementOptions, type BillKitElementHandle, mountPaymentMethodElement } from \"@billkit-eu/js\";\nimport { forwardRef, useImperativeHandle } from \"react\";\nimport {\n  type ReactElementProps,\n  type ThemeableElementRef,\n  themeableElementRef,\n  useElement,\n} from \"./useElement\";\n\nexport interface PaymentMethodElementProps extends ReactElementProps {\n  /** The customer whose saved payment methods to render + manage. */\n  customerId: string;\n}\n\n/**\n * The customer's saved payment methods (\"Visa •••• 4242 · Update\"), as a\n * React component. Same SSR-safe mounting as {@link CheckoutElement}.\n *\n * Changing `customerId` remounts the element, so the wallet on screen\n * always belongs to the customer named in the props.\n *\n * The `ref` exposes `updateTheme()` only — this element has no form to\n * submit; its actions are per-row buttons inside the iframe.\n */\nexport const PaymentMethodElement = forwardRef<ThemeableElementRef, PaymentMethodElementProps>(\n  function PaymentMethodElement(props, ref) {\n    const { customerId } = props;\n    const mount = (target: HTMLElement, options: BaseElementOptions): BillKitElementHandle =>\n      mountPaymentMethodElement(target, { ...options, customerId });\n    const { isClient, containerRef, handleRef } = useElement(mount, props);\n    useImperativeHandle(ref, () => themeableElementRef(handleRef), []);\n    if (!isClient) return null;\n    return <div ref={containerRef} className={props.className} style={props.style} />;\n  },\n);\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@billkit-eu/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React bindings for BillKit's embedded checkout: <BillKitProvider> + <CheckoutElement/>, @stripe/react-stripe-js-shaped and SSR-safe.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -55,12 +55,12 @@
     "provenance": true
   },
   "peerDependencies": {
-    "@billkit-eu/js": "^0.1.0",
+    "@billkit-eu/js": ">=0.2.0 <1",
     "react": ">=18",
     "react-dom": ">=18"
   },
   "devDependencies": {
-    "@billkit-eu/js": "^0.1.0",
+    "@billkit-eu/js": ">=0.2.0 <1",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^26.1.1",
     "@types/react": "^18.3.12",

package/src/BillKitProvider.tsx

@@ -3,27 +3,15 @@ import { createContext, type ReactNode, useContext, useMemo } from "react";
 
 /**
  * Config shared by every BillKit element on the page. Mirrors
- * `@stripe/react-stripe-js`'s `<Elements>` provider: put your public key
- * (and any origin overrides) here once, then render elements freely
- * beneath it.
+ * `@stripe/react-stripe-js`'s `<Elements>` provider — minus the key:
+ * BillKit has no publishable-key concept. The API only mints secret keys
+ * (`sk_live_...` / `sk_test_...`), which must never reach a browser;
+ * elements authenticate with the ephemeral `client_secret` your server
+ * gets from `POST /v1/checkout/sessions` with `ui_mode: "embedded"`, and
+ * that secret already names the tenant, the mode, and the session. So the
+ * provider carries origin overrides and a logger, nothing credential-shaped.
  */
 export interface BillKitContextValue {
-  /**
-   * @deprecated Not required, not used, and not something BillKit issues.
-   *
-   * BillKit has no publishable-key concept; the API only mints secret
-   * keys (`sk_live_...` / `sk_test_...`), which must never reach a browser.
-   * Elements authenticate with the ephemeral `client_secret` your server
-   * gets from `POST /v1/checkout/sessions` with `ui_mode: "embedded"`,
-   * and that secret already names the tenant, the mode, and the session.
-   *
-   * The prop was accepted (and required) in 0.1.0 by analogy with
-   * `@stripe/react-stripe-js`, but nothing ever read it, and a tenant
-   * following the docs went looking for a `pk_...` value that does not
-   * exist. It is now optional and ignored; pass nothing. It will be
-   * removed in the next major.
-   */
-  publishableKey?: string;
   /** Origin the element iframe is served from. Defaults to js.billkit.eu. */
   iframeOrigin?: string;
   /** API origin the iframe calls. Defaults to api.billkit.eu. */
@@ -59,15 +47,14 @@ export interface BillKitProviderProps extends BillKitContextValue {
  * ```
  */
 export function BillKitProvider({
-  publishableKey,
   iframeOrigin,
   apiBase,
   logger,
   children,
 }: BillKitProviderProps): JSX.Element {
   const value = useMemo<BillKitContextValue>(
-    () => ({ publishableKey, iframeOrigin, apiBase, logger }),
-    [publishableKey, iframeOrigin, apiBase, logger],
+    () => ({ iframeOrigin, apiBase, logger }),
+    [iframeOrigin, apiBase, logger],
   );
   return <BillKitContext.Provider value={value}>{children}</BillKitContext.Provider>;
 }

package/src/CheckoutElement.tsx

@@ -1,5 +1,11 @@
 import { mountCheckoutElement } from "@billkit-eu/js";
-import { type ReactElementProps, useElement } from "./useElement";
+import { forwardRef, useImperativeHandle } from "react";
+import {
+  type BillKitElementRef,
+  checkoutElementRef,
+  type ReactElementProps,
+  useElement,
+} from "./useElement";
 
 export type CheckoutElementProps = ReactElementProps;
 
@@ -17,9 +23,34 @@ export type CheckoutElementProps = ReactElementProps;
  *   />
  * </BillKitProvider>
  * ```
+ *
+ * Driving your own pay button: take a `ref` and call `submit()`. Gate the
+ * button on `onChange`'s `complete`, and re-enable it from `onError` —
+ * a declined card fires `onError({ code: "payment_declined" })` and the
+ * element shows its own retry panel.
+ *
+ * ```tsx
+ * const element = useRef<BillKitElementRef>(null);
+ * const [ready, setReady] = useState(false);
+ * <>
+ *   <CheckoutElement
+ *     ref={element}
+ *     clientSecret={clientSecret}
+ *     onChange={({ complete }) => setReady(complete)}
+ *     onError={() => setSubmitting(false)}
+ *   />
+ *   <button disabled={!ready} onClick={() => element.current?.submit()}>Pay</button>
+ * </>
+ * ```
  */
-export function CheckoutElement(props: CheckoutElementProps): JSX.Element | null {
-  const { isClient, containerRef } = useElement(mountCheckoutElement, props);
-  if (!isClient) return null;
-  return <div ref={containerRef} className={props.className} style={props.style} />;
-}
+export const CheckoutElement = forwardRef<BillKitElementRef, CheckoutElementProps>(
+  function CheckoutElement(props, ref) {
+    const { isClient, containerRef, handleRef } = useElement(mountCheckoutElement, props);
+    // No dependency list: `handleRef` is a stable ref object, and the
+    // closures read `.current` at call time, so the imperative handle
+    // never goes stale across remounts.
+    useImperativeHandle(ref, () => checkoutElementRef(handleRef), []);
+    if (!isClient) return null;
+    return <div ref={containerRef} className={props.className} style={props.style} />;
+  },
+);

package/src/PaymentMethodElement.tsx

@@ -1,5 +1,11 @@
 import { type BaseElementOptions, type BillKitElementHandle, mountPaymentMethodElement } from "@billkit-eu/js";
-import { type ReactElementProps, useElement } from "./useElement";
+import { forwardRef, useImperativeHandle } from "react";
+import {
+  type ReactElementProps,
+  type ThemeableElementRef,
+  themeableElementRef,
+  useElement,
+} from "./useElement";
 
 export interface PaymentMethodElementProps extends ReactElementProps {
   /** The customer whose saved payment methods to render + manage. */
@@ -9,12 +15,21 @@ export interface PaymentMethodElementProps extends ReactElementProps {
 /**
  * The customer's saved payment methods ("Visa •••• 4242 · Update"), as a
  * React component. Same SSR-safe mounting as {@link CheckoutElement}.
+ *
+ * Changing `customerId` remounts the element, so the wallet on screen
+ * always belongs to the customer named in the props.
+ *
+ * The `ref` exposes `updateTheme()` only — this element has no form to
+ * submit; its actions are per-row buttons inside the iframe.
  */
-export function PaymentMethodElement(props: PaymentMethodElementProps): JSX.Element | null {
-  const { customerId } = props;
-  const mount = (target: HTMLElement, options: BaseElementOptions): BillKitElementHandle =>
-    mountPaymentMethodElement(target, { ...options, customerId });
-  const { isClient, containerRef } = useElement(mount, props);
-  if (!isClient) return null;
-  return <div ref={containerRef} className={props.className} style={props.style} />;
-}
+export const PaymentMethodElement = forwardRef<ThemeableElementRef, PaymentMethodElementProps>(
+  function PaymentMethodElement(props, ref) {
+    const { customerId } = props;
+    const mount = (target: HTMLElement, options: BaseElementOptions): BillKitElementHandle =>
+      mountPaymentMethodElement(target, { ...options, customerId });
+    const { isClient, containerRef, handleRef } = useElement(mount, props);
+    useImperativeHandle(ref, () => themeableElementRef(handleRef), []);
+    if (!isClient) return null;
+    return <div ref={containerRef} className={props.className} style={props.style} />;
+  },
+);

package/src/index.tsx

@@ -20,7 +20,11 @@ export {
   PaymentMethodElement,
   type PaymentMethodElementProps,
 } from "./PaymentMethodElement";
-export type { ReactElementProps } from "./useElement";
+export type {
+  BillKitElementRef,
+  ReactElementProps,
+  ThemeableElementRef,
+} from "./useElement";
 // Re-export the loader's shared types so consumers import from one place.
 export type {
   BillKitElementError,

package/src/useElement.ts

@@ -52,8 +52,17 @@ type MountFn = (
  */
 export function useElement(
   mount: MountFn,
-  props: ReactElementProps,
-): { isClient: boolean; containerRef: React.RefObject<HTMLDivElement> } {
+  // `customerId` is not part of the public `ReactElementProps` (only the
+  // payment-method element has one), but the hook still has to *see* it:
+  // it is a remount input, and leaving it out of the dependency list
+  // meant switching customers kept the previous customer's wallet — and
+  // its "set default" / "remove" actions — on screen.
+  props: ReactElementProps & { customerId?: string },
+): {
+  isClient: boolean;
+  containerRef: React.RefObject<HTMLDivElement>;
+  handleRef: React.RefObject<BillKitElementHandle | null>;
+} {
   const { iframeOrigin, apiBase, logger: providerLogger } = useBillKit();
   const [isClient, setIsClient] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
@@ -101,10 +110,10 @@ export function useElement(
       handle.destroy();
       handleRef.current = null;
     };
-    // Remount only on identity inputs (secret / origins); callbacks are
-    // read through a ref and theme is hot-applied in the effect below, so
-    // neither belongs in this dependency list.
-  }, [isClient, props.clientSecret, props.locale, iframeOrigin, apiBase]);
+    // Remount only on identity inputs (secret / customer / origins);
+    // callbacks are read through a ref and theme is hot-applied in the
+    // effect below, so neither belongs in this dependency list.
+  }, [isClient, props.clientSecret, props.customerId, props.locale, iframeOrigin, apiBase]);
 
   // Hot-apply theme changes without tearing down the iframe.
   useEffect(() => {
@@ -113,5 +122,57 @@ export function useElement(
     }
   }, [themeKey]);
 
-  return { isClient, containerRef };
+  return { isClient, containerRef, handleRef };
+}
+
+/**
+ * The imperative handle `<CheckoutElement/>` and
+ * `<PaymentMethodElement/>` expose through `ref`.
+ *
+ * Everything else about these components is declarative, but submitting
+ * is genuinely an *event*, not a state: a merchant's own pay button
+ * lives outside the iframe (that is the point of `onChange.complete`),
+ * and it has to be able to say "go" exactly once. A `submit` prop would
+ * have to be a toggling boolean, which is the classic React smell for an
+ * action modelled as state, so this follows the
+ * `useImperativeHandle` path that `<input>`'s `focus()` set.
+ *
+ * Calls made before the iframe has mounted are no-ops rather than
+ * throwing — on the server, and on the first client render, there is no
+ * element yet.
+ */
+export interface ThemeableElementRef {
+  /** Push new theme tokens in without remounting. */
+  updateTheme(theme: BillKitThemeTokens): void;
+}
+
+export interface BillKitElementRef extends ThemeableElementRef {
+  /** Submit the form from your own pay button. */
+  submit(): void;
+}
+
+/** Build the ref `<CheckoutElement/>` exposes. */
+export function checkoutElementRef(
+  handleRef: React.RefObject<BillKitElementHandle | null>,
+): BillKitElementRef {
+  return {
+    submit: () => handleRef.current?.submit(),
+    updateTheme: (theme) => handleRef.current?.updateTheme(theme),
+  };
+}
+
+/**
+ * Build the ref `<PaymentMethodElement/>` exposes.
+ *
+ * Deliberately no `submit`: the wallet element drops `billkit:submit` on
+ * the floor (there is no form to submit — its actions are per-row "set
+ * default" / "remove" buttons inside the iframe). Exposing a method that
+ * silently does nothing would be worse than not having one.
+ */
+export function themeableElementRef(
+  handleRef: React.RefObject<BillKitElementHandle | null>,
+): ThemeableElementRef {
+  return {
+    updateTheme: (theme) => handleRef.current?.updateTheme(theme),
+  };
 }