@billkit-eu/react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to the BillKit React SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+This package is a thin binding layer over `@billkit-eu/js`, which it takes as a
+peer dependency. Behaviour changes usually land there and are recorded in that
+package's changelog.
+
+## [Unreleased]
+
+## [0.1.0]
+
+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.
+- `<CheckoutElement/>` and `<PaymentMethodElement/>`: React wrappers over the
+  corresponding `@billkit-eu/js` mounts, with the iframe's lifecycle tied to
+  the component's.
+- `useBillKit()` for reading the provider's context, and the `ReactElementProps`
+  type for components that wrap an element of their own.
+- Server rendering support: elements render `null` on the server and mount the
+  iframe after hydration, so importing this package does not break an SSR build
+  or produce a hydration mismatch.
+- Callback props are held in refs internally, so passing a new inline arrow
+  function on every render does not tear down and remount the iframe. This is
+  the failure mode that makes naive wrappers lose payment state mid-entry.
+- The `@billkit-eu/js` types are re-exported (`BillKitElementHandle`,
+  `BillKitThemeTokens`, `SuccessEvent`, `ChangeEvent`, `BillKitElementError`,
+  `BillKitElementLogger`, `ElementLogContext`), so consumers import from one
+  package.
+- React `>=18` (the peer range; the suite runs against 18), ESM + CJS dual
+  package via `tsup`.
+
+[Unreleased]: https://github.com/billkit-eu/billkit-react/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/billkit-eu/billkit-react/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for the acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 BillKit
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,132 @@
+# BillKit React SDK
+
+React bindings for [BillKit](https://billkit.eu)'s embedded checkout, shaped like `@stripe/react-stripe-js` and safe to render on the server.
+
+A thin wrapper over [`@billkit-eu/js`](https://www.npmjs.com/package/@billkit-eu/js). The card fields render inside a cross-origin iframe served from `js.billkit.eu`, so card data never touches your origin and you stay on PCI SAQ A. All of the security model and `postMessage` handling lives in the loader; this package is the React surface over it.
+
+No secret key ever reaches the browser. For server-side calls, use [`@billkit-eu/sdk`](https://www.npmjs.com/package/@billkit-eu/sdk).
+
+## Install
+
+```bash
+npm install @billkit-eu/react @billkit-eu/js
+# or pnpm add @billkit-eu/react @billkit-eu/js
+```
+
+`@billkit-eu/js`, `react` (18+) and `react-dom` (18+) are peer dependencies, so install `@billkit-eu/js` alongside this package.
+
+## Quick start
+
+Mint an ephemeral `client_secret` on your server, then hand it to the element:
+
+```tsx
+import { BillKitProvider, CheckoutElement } from "@billkit-eu/react";
+
+export function Checkout({ clientSecret }: { clientSecret: string }) {
+  return (
+    <BillKitProvider>
+      <CheckoutElement
+        clientSecret={clientSecret}
+        theme={{ colorPrimary: "#6d28d9", borderRadius: "10px" }}
+        onSuccess={({ sessionId }) => router.push(`/thanks?cs=${sessionId}`)}
+        onError={({ message }) => toast.error(message)}
+      />
+    </BillKitProvider>
+  );
+}
+```
+
+No credential goes on the provider. The element authenticates with the `client_secret`, which already names the tenant, the mode and the session.
+
+## Saved payment methods
+
+```tsx
+import { BillKitProvider, PaymentMethodElement } from "@billkit-eu/react";
+
+<BillKitProvider>
+  <PaymentMethodElement clientSecret={clientSecret} customerId="cus_123" />
+</BillKitProvider>;
+```
+
+## Server rendering
+
+Both components are SSR-safe. They render `null` on the server and on the first client render, then mount the iframe after hydration, so there is no hydration mismatch and no `window` access during render. Next.js App Router, Remix and Astro islands all work without a `dynamic(..., { ssr: false })` wrapper.
+
+## Props
+
+`<CheckoutElement/>` and `<PaymentMethodElement/>` share these:
+
+| Prop | Type | Notes |
+|---|---|---|
+| `clientSecret` | `string` | Required. From `POST /v1/checkout/sessions` with `ui_mode: "embedded"`. |
+| `theme` | `BillKitThemeTokens` | Colour, radius, font and spacing tokens. |
+| `locale` | `string` | BCP-47, for example `"nl"`. Defaults to the customer's browser. |
+| `loadTimeoutMs` | `number` | Before `onError({ code: "load_timeout" })`. Default `20000`; `0` disables it. |
+| `logger` | `BillKitElementLogger` | Overrides the provider's logger for this element only. |
+| `className` / `style` | | Applied to the container `<div>` the iframe mounts into. |
+| `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. |
+| `onRedirect` | `(url: string) => boolean \| void` | Before the top window navigates for 3DS or iDEAL. Return `false` to navigate yourself. |
+
+`<PaymentMethodElement/>` also requires `customerId`.
+
+`<BillKitProvider>` accepts `iframeOrigin`, `apiBase` and `logger`, applied to every element beneath it.
+
+### Callbacks and re-renders
+
+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.
+
+## Content Security Policy
+
+```
+frame-src https://js.billkit.eu;
+```
+
+If the iframe never boots, `onError` fires with `load_timeout`. A missing `frame-src` and an ad blocker look identical from the page, so check both.
+
+## Logging
+
+Elements are silent by default. Installing the package does not start writing to anyone's console. Opt in on the provider, or per element:
+
+```tsx
+<BillKitProvider logger={console}>
+  <CheckoutElement clientSecret={clientSecret} />
+</BillKitProvider>
+```
+
+Never logged: the `clientSecret`, message payloads, or full redirect URLs. Only a redirect's origin is recorded, because the rest of the URL carries provider payment identifiers.
+
+## Migrating from `@stripe/react-stripe-js`
+
+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.
+
+See the [migration guide](https://docs.billkit.eu/migration/elements/) for the full comparison.
+
+## TypeScript
+
+Types ship with the package. The loader's shared types are re-exported so you can import from one place:
+
+```ts
+import type {
+  BillKitThemeTokens,
+  ChangeEvent,
+  SuccessEvent,
+  BillKitElementError,
+} from "@billkit-eu/react";
+```
+
+## Links
+
+- Documentation: [docs.billkit.eu](https://docs.billkit.eu)
+- Source: [github.com/billkit-eu/billkit-react](https://github.com/billkit-eu/billkit-react)
+- Issues: [github.com/billkit-eu/billkit-react/issues](https://github.com/billkit-eu/billkit-react/issues)
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,94 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+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]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(BillKitContext.Provider, { value, children });
+}
+function useBillKit() {
+  const ctx = react.useContext(BillKitContext);
+  if (ctx === null) {
+    throw new Error(
+      "BillKit: a <CheckoutElement/> must be rendered inside a <BillKitProvider>."
+    );
+  }
+  return ctx;
+}
+function useElement(mount, props) {
+  const { iframeOrigin, apiBase, logger: providerLogger } = useBillKit();
+  const [isClient, setIsClient] = react.useState(false);
+  const containerRef = react.useRef(null);
+  const handleRef = react.useRef(null);
+  const callbacks = react.useRef(props);
+  callbacks.current = props;
+  const activeLogger = react.useRef(void 0);
+  activeLogger.current = props.logger ?? providerLogger;
+  const stableLogger = react.useRef({
+    debug: (message, context) => activeLogger.current?.debug(message, context),
+    warn: (message, context) => activeLogger.current?.warn(message, context)
+  }).current;
+  react.useEffect(() => setIsClient(true), []);
+  const themeKey = props.theme ? JSON.stringify(props.theme) : "";
+  react.useEffect(() => {
+    if (!isClient || containerRef.current === null) return;
+    const options = {
+      clientSecret: props.clientSecret,
+      ...props.theme ? { theme: props.theme } : {},
+      ...props.locale ? { locale: props.locale } : {},
+      ...iframeOrigin ? { iframeOrigin } : {},
+      ...apiBase ? { apiBase } : {},
+      ...props.loadTimeoutMs !== void 0 ? { loadTimeoutMs: props.loadTimeoutMs } : {},
+      logger: stableLogger,
+      onReady: () => callbacks.current.onReady?.(),
+      onChange: (e) => callbacks.current.onChange?.(e),
+      onSuccess: (e) => callbacks.current.onSuccess?.(e),
+      onError: (e) => callbacks.current.onError?.(e),
+      onRedirect: (url) => callbacks.current.onRedirect?.(url)
+    };
+    const handle = mount(containerRef.current, options);
+    handleRef.current = handle;
+    return () => {
+      handle.destroy();
+      handleRef.current = null;
+    };
+  }, [isClient, props.clientSecret, props.locale, iframeOrigin, apiBase]);
+  react.useEffect(() => {
+    if (themeKey && handleRef.current && props.theme) {
+      handleRef.current.updateTheme(props.theme);
+    }
+  }, [themeKey]);
+  return { isClient, containerRef };
+}
+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 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 });
+}
+
+exports.BillKitProvider = BillKitProvider;
+exports.CheckoutElement = CheckoutElement;
+exports.PaymentMethodElement = PaymentMethodElement;
+exports.useBillKit = useBillKit;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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"]}

package/dist/index.d.cts

@@ -0,0 +1,117 @@
+import { BillKitElementLogger, BillKitThemeTokens, ChangeEvent, SuccessEvent, BillKitElementError } from '@billkit-eu/js';
+export { BillKitElementError, BillKitElementHandle, BillKitElementLogger, BillKitThemeTokens, ChangeEvent, ElementLogContext, SuccessEvent } from '@billkit-eu/js';
+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.
+ */
+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. */
+    apiBase?: string;
+    /**
+     * Where every element beneath this provider sends its lifecycle
+     * diagnostics: iframe boot, dropped `postMessage`s, refused
+     * redirects, load timeouts. Omitted (the default) means silence: the
+     * elements never write to `console` on their own.
+     *
+     * `console` works as-is. An individual element can override this with
+     * its own `logger` prop. The `clientSecret` is never passed to it.
+     */
+    logger?: BillKitElementLogger;
+}
+interface BillKitProviderProps extends BillKitContextValue {
+    children: ReactNode;
+}
+/**
+ * Wrap the part of your tree that renders BillKit elements.
+ *
+ * No credential is needed here; the element authenticates with the
+ * ephemeral `client_secret` your server minted for the session:
+ *
+ * ```tsx
+ * <BillKitProvider>
+ *   <CheckoutElement clientSecret={clientSecret} onSuccess={done} />
+ * </BillKitProvider>
+ * ```
+ */
+declare function BillKitProvider({ publishableKey, 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
+ * mistake.
+ */
+declare function useBillKit(): BillKitContextValue;
+
+/** Callback + presentational props common to the React element components. */
+interface ReactElementProps {
+    /** Ephemeral checkout `client_secret` (`<sessionId>_secret_...`). */
+    clientSecret: string;
+    theme?: BillKitThemeTokens;
+    locale?: string;
+    /** Load-watchdog timeout (ms) before `onError({code:"load_timeout"})`. */
+    loadTimeoutMs?: number;
+    /**
+     * Overrides the provider's `logger` for this element only. Omitted,
+     * the provider's is used; with neither, the element is silent.
+     */
+    logger?: BillKitElementLogger;
+    /** Applied to the container `<div>` the iframe mounts into. */
+    className?: string;
+    style?: React.CSSProperties;
+    onReady?: () => void;
+    onChange?: (event: ChangeEvent) => void;
+    onSuccess?: (event: SuccessEvent) => void;
+    onError?: (error: BillKitElementError) => void;
+    onRedirect?: (url: string) => boolean | void;
+}
+
+type CheckoutElementProps = ReactElementProps;
+/**
+ * Embedded checkout, as a React component. SSR-safe: renders `null` on the
+ * server and the first client render, then mounts the js.billkit.eu iframe
+ * after hydration.
+ *
+ * ```tsx
+ * <BillKitProvider>
+ *   <CheckoutElement
+ *     clientSecret={clientSecret}
+ *     theme={{ colorPrimary: "#6d28d9", borderRadius: "10px" }}
+ *     onSuccess={({ sessionId }) => router.push(`/thanks?cs=${sessionId}`)}
+ *   />
+ * </BillKitProvider>
+ * ```
+ */
+declare function CheckoutElement(props: CheckoutElementProps): JSX.Element | null;
+
+interface PaymentMethodElementProps extends ReactElementProps {
+    /** The customer whose saved payment methods to render + manage. */
+    customerId: string;
+}
+/**
+ * The customer's saved payment methods ("Visa •••• 4242 · Update"), as a
+ * React component. Same SSR-safe mounting as {@link CheckoutElement}.
+ */
+declare function PaymentMethodElement(props: PaymentMethodElementProps): JSX.Element | null;
+
+export { type BillKitContextValue, BillKitProvider, type BillKitProviderProps, CheckoutElement, type CheckoutElementProps, PaymentMethodElement, type PaymentMethodElementProps, type ReactElementProps, useBillKit };

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { BillKitElementLogger, BillKitThemeTokens, ChangeEvent, SuccessEvent, BillKitElementError } from '@billkit-eu/js';
+export { BillKitElementError, BillKitElementHandle, BillKitElementLogger, BillKitThemeTokens, ChangeEvent, ElementLogContext, SuccessEvent } from '@billkit-eu/js';
+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.
+ */
+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. */
+    apiBase?: string;
+    /**
+     * Where every element beneath this provider sends its lifecycle
+     * diagnostics: iframe boot, dropped `postMessage`s, refused
+     * redirects, load timeouts. Omitted (the default) means silence: the
+     * elements never write to `console` on their own.
+     *
+     * `console` works as-is. An individual element can override this with
+     * its own `logger` prop. The `clientSecret` is never passed to it.
+     */
+    logger?: BillKitElementLogger;
+}
+interface BillKitProviderProps extends BillKitContextValue {
+    children: ReactNode;
+}
+/**
+ * Wrap the part of your tree that renders BillKit elements.
+ *
+ * No credential is needed here; the element authenticates with the
+ * ephemeral `client_secret` your server minted for the session:
+ *
+ * ```tsx
+ * <BillKitProvider>
+ *   <CheckoutElement clientSecret={clientSecret} onSuccess={done} />
+ * </BillKitProvider>
+ * ```
+ */
+declare function BillKitProvider({ publishableKey, 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
+ * mistake.
+ */
+declare function useBillKit(): BillKitContextValue;
+
+/** Callback + presentational props common to the React element components. */
+interface ReactElementProps {
+    /** Ephemeral checkout `client_secret` (`<sessionId>_secret_...`). */
+    clientSecret: string;
+    theme?: BillKitThemeTokens;
+    locale?: string;
+    /** Load-watchdog timeout (ms) before `onError({code:"load_timeout"})`. */
+    loadTimeoutMs?: number;
+    /**
+     * Overrides the provider's `logger` for this element only. Omitted,
+     * the provider's is used; with neither, the element is silent.
+     */
+    logger?: BillKitElementLogger;
+    /** Applied to the container `<div>` the iframe mounts into. */
+    className?: string;
+    style?: React.CSSProperties;
+    onReady?: () => void;
+    onChange?: (event: ChangeEvent) => void;
+    onSuccess?: (event: SuccessEvent) => void;
+    onError?: (error: BillKitElementError) => void;
+    onRedirect?: (url: string) => boolean | void;
+}
+
+type CheckoutElementProps = ReactElementProps;
+/**
+ * Embedded checkout, as a React component. SSR-safe: renders `null` on the
+ * server and the first client render, then mounts the js.billkit.eu iframe
+ * after hydration.
+ *
+ * ```tsx
+ * <BillKitProvider>
+ *   <CheckoutElement
+ *     clientSecret={clientSecret}
+ *     theme={{ colorPrimary: "#6d28d9", borderRadius: "10px" }}
+ *     onSuccess={({ sessionId }) => router.push(`/thanks?cs=${sessionId}`)}
+ *   />
+ * </BillKitProvider>
+ * ```
+ */
+declare function CheckoutElement(props: CheckoutElementProps): JSX.Element | null;
+
+interface PaymentMethodElementProps extends ReactElementProps {
+    /** The customer whose saved payment methods to render + manage. */
+    customerId: string;
+}
+/**
+ * The customer's saved payment methods ("Visa •••• 4242 · Update"), as a
+ * React component. Same SSR-safe mounting as {@link CheckoutElement}.
+ */
+declare function PaymentMethodElement(props: PaymentMethodElementProps): JSX.Element | null;
+
+export { type BillKitContextValue, BillKitProvider, type BillKitProviderProps, CheckoutElement, type CheckoutElementProps, PaymentMethodElement, type PaymentMethodElementProps, type ReactElementProps, useBillKit };

package/dist/index.js

@@ -0,0 +1,89 @@
+import { createContext, useMemo, useContext, useState, useRef, useEffect } 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]
+  );
+  return /* @__PURE__ */ jsx(BillKitContext.Provider, { value, children });
+}
+function useBillKit() {
+  const ctx = useContext(BillKitContext);
+  if (ctx === null) {
+    throw new Error(
+      "BillKit: a <CheckoutElement/> must be rendered inside a <BillKitProvider>."
+    );
+  }
+  return ctx;
+}
+function useElement(mount, props) {
+  const { iframeOrigin, apiBase, logger: providerLogger } = useBillKit();
+  const [isClient, setIsClient] = useState(false);
+  const containerRef = useRef(null);
+  const handleRef = useRef(null);
+  const callbacks = useRef(props);
+  callbacks.current = props;
+  const activeLogger = useRef(void 0);
+  activeLogger.current = props.logger ?? providerLogger;
+  const stableLogger = useRef({
+    debug: (message, context) => activeLogger.current?.debug(message, context),
+    warn: (message, context) => activeLogger.current?.warn(message, context)
+  }).current;
+  useEffect(() => setIsClient(true), []);
+  const themeKey = props.theme ? JSON.stringify(props.theme) : "";
+  useEffect(() => {
+    if (!isClient || containerRef.current === null) return;
+    const options = {
+      clientSecret: props.clientSecret,
+      ...props.theme ? { theme: props.theme } : {},
+      ...props.locale ? { locale: props.locale } : {},
+      ...iframeOrigin ? { iframeOrigin } : {},
+      ...apiBase ? { apiBase } : {},
+      ...props.loadTimeoutMs !== void 0 ? { loadTimeoutMs: props.loadTimeoutMs } : {},
+      logger: stableLogger,
+      onReady: () => callbacks.current.onReady?.(),
+      onChange: (e) => callbacks.current.onChange?.(e),
+      onSuccess: (e) => callbacks.current.onSuccess?.(e),
+      onError: (e) => callbacks.current.onError?.(e),
+      onRedirect: (url) => callbacks.current.onRedirect?.(url)
+    };
+    const handle = mount(containerRef.current, options);
+    handleRef.current = handle;
+    return () => {
+      handle.destroy();
+      handleRef.current = null;
+    };
+  }, [isClient, props.clientSecret, props.locale, iframeOrigin, apiBase]);
+  useEffect(() => {
+    if (themeKey && handleRef.current && props.theme) {
+      handleRef.current.updateTheme(props.theme);
+    }
+  }, [themeKey]);
+  return { isClient, containerRef };
+}
+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 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 });
+}
+
+export { BillKitProvider, CheckoutElement, PaymentMethodElement, useBillKit };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@billkit-eu/react",
+  "version": "0.1.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",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "prepublishOnly": "npm run build && npm run test && npm run typecheck"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "billkit",
+    "react",
+    "checkout",
+    "payment-element",
+    "embedded",
+    "mollie",
+    "stripe"
+  ],
+  "author": "BillKit",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/billkit-eu/billkit-react.git"
+  },
+  "homepage": "https://github.com/billkit-eu/billkit-react#readme",
+  "bugs": {
+    "url": "https://github.com/billkit-eu/billkit-react/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@billkit-eu/js": "^0.1.0",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@billkit-eu/js": "^0.1.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^26.1.1",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@typescript-eslint/eslint-plugin": "^8.64.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "eslint": "^10.7.0",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "sideEffects": false
+}

package/src/BillKitProvider.tsx

@@ -0,0 +1,88 @@
+import type { BillKitElementLogger } from "@billkit-eu/js";
+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.
+ */
+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. */
+  apiBase?: string;
+  /**
+   * Where every element beneath this provider sends its lifecycle
+   * diagnostics: iframe boot, dropped `postMessage`s, refused
+   * redirects, load timeouts. Omitted (the default) means silence: the
+   * elements never write to `console` on their own.
+   *
+   * `console` works as-is. An individual element can override this with
+   * its own `logger` prop. The `clientSecret` is never passed to it.
+   */
+  logger?: BillKitElementLogger;
+}
+
+const BillKitContext = createContext<BillKitContextValue | null>(null);
+
+export interface BillKitProviderProps extends BillKitContextValue {
+  children: ReactNode;
+}
+
+/**
+ * Wrap the part of your tree that renders BillKit elements.
+ *
+ * No credential is needed here; the element authenticates with the
+ * ephemeral `client_secret` your server minted for the session:
+ *
+ * ```tsx
+ * <BillKitProvider>
+ *   <CheckoutElement clientSecret={clientSecret} onSuccess={done} />
+ * </BillKitProvider>
+ * ```
+ */
+export function BillKitProvider({
+  publishableKey,
+  iframeOrigin,
+  apiBase,
+  logger,
+  children,
+}: BillKitProviderProps): JSX.Element {
+  const value = useMemo<BillKitContextValue>(
+    () => ({ publishableKey, iframeOrigin, apiBase, logger }),
+    [publishableKey, iframeOrigin, apiBase, logger],
+  );
+  return <BillKitContext.Provider value={value}>{children}</BillKitContext.Provider>;
+}
+
+/**
+ * Read the nearest {@link BillKitProvider}. Throws a clear error when an
+ * element is rendered outside a provider, the most common integration
+ * mistake.
+ */
+export function useBillKit(): BillKitContextValue {
+  const ctx = useContext(BillKitContext);
+  if (ctx === null) {
+    throw new Error(
+      "BillKit: a <CheckoutElement/> must be rendered inside a <BillKitProvider>.",
+    );
+  }
+  return ctx;
+}

package/src/CheckoutElement.tsx

@@ -0,0 +1,25 @@
+import { mountCheckoutElement } from "@billkit-eu/js";
+import { type ReactElementProps, useElement } from "./useElement";
+
+export type CheckoutElementProps = ReactElementProps;
+
+/**
+ * Embedded checkout, as a React component. SSR-safe: renders `null` on the
+ * server and the first client render, then mounts the js.billkit.eu iframe
+ * after hydration.
+ *
+ * ```tsx
+ * <BillKitProvider>
+ *   <CheckoutElement
+ *     clientSecret={clientSecret}
+ *     theme={{ colorPrimary: "#6d28d9", borderRadius: "10px" }}
+ *     onSuccess={({ sessionId }) => router.push(`/thanks?cs=${sessionId}`)}
+ *   />
+ * </BillKitProvider>
+ * ```
+ */
+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} />;
+}

package/src/PaymentMethodElement.tsx

@@ -0,0 +1,20 @@
+import { type BaseElementOptions, type BillKitElementHandle, mountPaymentMethodElement } from "@billkit-eu/js";
+import { type ReactElementProps, useElement } from "./useElement";
+
+export interface PaymentMethodElementProps extends ReactElementProps {
+  /** The customer whose saved payment methods to render + manage. */
+  customerId: string;
+}
+
+/**
+ * The customer's saved payment methods ("Visa •••• 4242 · Update"), as a
+ * React component. Same SSR-safe mounting as {@link CheckoutElement}.
+ */
+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} />;
+}

package/src/index.tsx

@@ -0,0 +1,33 @@
+/**
+ * `@billkit-eu/react`: React bindings for BillKit's embedded checkout.
+ *
+ * `@stripe/react-stripe-js`-shaped: wrap your tree in a
+ * Wrap your tree in `<BillKitProvider>` and drop in `<CheckoutElement/>`.
+ * SSR-safe: the elements render `null` on the server and mount the
+ * js.billkit.eu iframe after hydration.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  BillKitProvider,
+  type BillKitContextValue,
+  type BillKitProviderProps,
+  useBillKit,
+} from "./BillKitProvider";
+export { CheckoutElement, type CheckoutElementProps } from "./CheckoutElement";
+export {
+  PaymentMethodElement,
+  type PaymentMethodElementProps,
+} from "./PaymentMethodElement";
+export type { ReactElementProps } from "./useElement";
+// Re-export the loader's shared types so consumers import from one place.
+export type {
+  BillKitElementError,
+  BillKitElementHandle,
+  BillKitElementLogger,
+  BillKitThemeTokens,
+  ChangeEvent,
+  ElementLogContext,
+  SuccessEvent,
+} from "@billkit-eu/js";

package/src/useElement.ts

@@ -0,0 +1,117 @@
+import type {
+  BaseElementOptions,
+  BillKitElementError,
+  BillKitElementHandle,
+  BillKitElementLogger,
+  BillKitThemeTokens,
+  ChangeEvent,
+  SuccessEvent,
+} from "@billkit-eu/js";
+import { useEffect, useRef, useState } from "react";
+import { useBillKit } from "./BillKitProvider";
+
+/** Callback + presentational props common to the React element components. */
+export interface ReactElementProps {
+  /** Ephemeral checkout `client_secret` (`<sessionId>_secret_...`). */
+  clientSecret: string;
+  theme?: BillKitThemeTokens;
+  locale?: string;
+  /** Load-watchdog timeout (ms) before `onError({code:"load_timeout"})`. */
+  loadTimeoutMs?: number;
+  /**
+   * Overrides the provider's `logger` for this element only. Omitted,
+   * the provider's is used; with neither, the element is silent.
+   */
+  logger?: BillKitElementLogger;
+  /** Applied to the container `<div>` the iframe mounts into. */
+  className?: string;
+  style?: React.CSSProperties;
+  onReady?: () => void;
+  onChange?: (event: ChangeEvent) => void;
+  onSuccess?: (event: SuccessEvent) => void;
+  onError?: (error: BillKitElementError) => void;
+  onRedirect?: (url: string) => boolean | void;
+}
+
+type MountFn = (
+  target: HTMLElement,
+  options: BaseElementOptions,
+) => BillKitElementHandle;
+
+/**
+ * SSR-safe mount hook shared by `<CheckoutElement/>` and
+ * `<PaymentMethodElement/>`.
+ *
+ * - Returns `isClient = false` on the server and on the first client
+ *   render, so the component renders `null` and hydration matches. The
+ *   `useEffect` then flips it true and the real mount happens, with no
+ *   hydration mismatch, no `window` access during render.
+ * - Callbacks are read through a ref, so a parent passing fresh closures
+ *   every render never forces a costly iframe remount. Only the identity
+ *   inputs (secret, origins) remount; theme changes hot-update in place.
+ */
+export function useElement(
+  mount: MountFn,
+  props: ReactElementProps,
+): { isClient: boolean; containerRef: React.RefObject<HTMLDivElement> } {
+  const { iframeOrigin, apiBase, logger: providerLogger } = useBillKit();
+  const [isClient, setIsClient] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const handleRef = useRef<BillKitElementHandle | null>(null);
+
+  // Latest callbacks, read at event time and decoupled from remount inputs.
+  const callbacks = useRef(props);
+  callbacks.current = props;
+
+  // Same trick for the logger: resolve it at call time through a ref so
+  // an inline `logger={{...}}` (or switching one on mid-session) never
+  // tears down and rebuilds the payment iframe. The element always
+  // receives this one stable object; it forwards to whatever is current,
+  // or drops the line when neither prop nor provider supplies one.
+  const activeLogger = useRef<BillKitElementLogger | undefined>(undefined);
+  activeLogger.current = props.logger ?? providerLogger;
+  const stableLogger = useRef<BillKitElementLogger>({
+    debug: (message, context) => activeLogger.current?.debug(message, context),
+    warn: (message, context) => activeLogger.current?.warn(message, context),
+  }).current;
+
+  useEffect(() => setIsClient(true), []);
+
+  const themeKey = props.theme ? JSON.stringify(props.theme) : "";
+
+  useEffect(() => {
+    if (!isClient || containerRef.current === null) return;
+    const options: BaseElementOptions = {
+      clientSecret: props.clientSecret,
+      ...(props.theme ? { theme: props.theme } : {}),
+      ...(props.locale ? { locale: props.locale } : {}),
+      ...(iframeOrigin ? { iframeOrigin } : {}),
+      ...(apiBase ? { apiBase } : {}),
+      ...(props.loadTimeoutMs !== undefined ? { loadTimeoutMs: props.loadTimeoutMs } : {}),
+      logger: stableLogger,
+      onReady: () => callbacks.current.onReady?.(),
+      onChange: (e) => callbacks.current.onChange?.(e),
+      onSuccess: (e) => callbacks.current.onSuccess?.(e),
+      onError: (e) => callbacks.current.onError?.(e),
+      onRedirect: (url) => callbacks.current.onRedirect?.(url),
+    };
+    const handle = mount(containerRef.current, options);
+    handleRef.current = handle;
+    return () => {
+      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]);
+
+  // Hot-apply theme changes without tearing down the iframe.
+  useEffect(() => {
+    if (themeKey && handleRef.current && props.theme) {
+      handleRef.current.updateTheme(props.theme);
+    }
+  }, [themeKey]);
+
+  return { isClient, containerRef };
+}