@inttegro/react 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,18 @@
+# `@inttegro/react`
+
+React adapter for Inttegro hosted workflows. The component automatically uses
+`@inttegro/js` to load the executable runtime from Inttegro's fixed origin; it
+does not bundle the payment-collection runtime.
+
+```tsx
+import { Checkout } from '@inttegro/react'
+
+export function Payment({ orderId }: { orderId: string }) {
+  return (
+    <Checkout
+      orderId={orderId}
+      onCompleted={() => location.assign('/complete')}
+    />
+  )
+}
+```

package/dist/index.cjs

@@ -0,0 +1,113 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Checkout: () => Checkout
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Checkout.tsx
+var import_js = require("@inttegro/js");
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var Checkout = (0, import_react.forwardRef)(
+  function Checkout2({
+    appearance,
+    className,
+    locale,
+    onCompleted,
+    onError,
+    onEvent,
+    onReady,
+    orderId,
+    style,
+    timeout,
+    title
+  }, forwardedRef) {
+    const containerRef = (0, import_react.useRef)(null);
+    const checkoutRef = (0, import_react.useRef)(null);
+    const callbacksRef = (0, import_react.useRef)({ onCompleted, onError, onEvent, onReady });
+    const updateOptionsRef = (0, import_react.useRef)({ appearance, locale });
+    callbacksRef.current = { onCompleted, onError, onEvent, onReady };
+    updateOptionsRef.current = { appearance, locale };
+    (0, import_react.useImperativeHandle)(
+      forwardedRef,
+      () => ({
+        focus: () => checkoutRef.current?.focus(),
+        update: (options) => checkoutRef.current?.update(options)
+      }),
+      []
+    );
+    (0, import_react.useEffect)(() => {
+      const target = containerRef.current;
+      if (!target) return;
+      let active = true;
+      let checkout;
+      let unsubscribe;
+      void (0, import_js.loadInttegro)().then(async (inttegro) => {
+        if (!active || !inttegro) return;
+        const instance = inttegro.createCheckout(
+          definedOptions({
+            ...updateOptionsRef.current,
+            orderId,
+            timeout,
+            title
+          })
+        );
+        if (!active) {
+          instance.destroy();
+          return;
+        }
+        checkout = instance;
+        checkoutRef.current = instance;
+        unsubscribe = instance.onEvent((event) => {
+          callbacksRef.current.onEvent?.(event);
+          if (event.type === "ready") callbacksRef.current.onReady?.(event);
+          if (event.type === "completed")
+            callbacksRef.current.onCompleted?.(event);
+          if (event.type === "error") callbacksRef.current.onError?.(event);
+        });
+        await instance.mount(target);
+      }).catch((error) => {
+        if (active) callbacksRef.current.onError?.(asError(error));
+      });
+      return () => {
+        active = false;
+        unsubscribe?.();
+        checkout?.destroy();
+        if (checkoutRef.current === checkout) checkoutRef.current = null;
+      };
+    }, [orderId, timeout, title]);
+    (0, import_react.useEffect)(() => {
+      checkoutRef.current?.update(definedOptions({ appearance, locale }));
+    }, [appearance, locale]);
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className, ref: containerRef, style });
+  }
+);
+function definedOptions(options) {
+  return Object.fromEntries(
+    Object.entries(options).filter(([, value]) => value !== void 0)
+  );
+}
+function asError(error) {
+  return error instanceof Error ? error : new Error("Checkout failed to load.");
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/Checkout.tsx"],"sourcesContent":["/**\n * React component adapter for Inttegro-hosted Checkout.\n *\n * @module @inttegro/react\n */\nexport { Checkout, type CheckoutHandle, type CheckoutProps } from './Checkout'\nexport type {\n  CheckoutAppearance,\n  CheckoutErrorEvent,\n  CheckoutEvent,\n  CheckoutTheme,\n} from '@inttegro/js'\n","import {\n  loadInttegro,\n  type CheckoutController,\n  type CheckoutErrorEvent,\n  type CheckoutEvent,\n  type CheckoutOptions,\n} from '@inttegro/js'\nimport {\n  forwardRef,\n  useEffect,\n  useImperativeHandle,\n  useRef,\n  type CSSProperties,\n} from 'react'\n\n/**\n * Props for {@link Checkout}.\n *\n * `orderId`, `timeout`, and `title` identify the embedded experience. Changing\n * one replaces the underlying controller. `appearance` and `locale` update the\n * existing controller without discarding payer progress.\n *\n * @category React\n */\nexport interface CheckoutProps extends CheckoutOptions {\n  /** CSS class applied to the outer container owned by your React application. */\n  className?: string\n  /** Inline styles applied to the outer container, never to controls inside Checkout. */\n  style?: CSSProperties\n  /**\n   * Called after Checkout reports its successful terminal state.\n   * Use this to navigate or refresh server-owned Order state, not as the sole\n   * signal for fulfillment.\n   */\n  onCompleted?: (event: Extract<CheckoutEvent, { type: 'completed' }>) => void\n  /**\n   * Called for loader/mount errors and sanitized hosted errors.\n   * Use `error instanceof InttegroCheckoutError` or check for an event `type`\n   * before reading framework-independent details.\n   */\n  onError?: (event: CheckoutErrorEvent | Error) => void\n  /** Called for every sanitized lifecycle event, including events above. */\n  onEvent?: (event: CheckoutEvent) => void\n  /** Called once the iframe is interactive and its mount promise has resolved. */\n  onReady?: (event: Extract<CheckoutEvent, { type: 'ready' }>) => void\n}\n\n/**\n * Imperative operations exposed by {@link Checkout} through a React ref.\n *\n * Prefer props for normal updates. Use the handle for focus management in\n * dialogs or for updates driven by imperative host integrations.\n *\n * @category React\n */\nexport interface CheckoutHandle {\n  /** Moves focus into Checkout when its controller is ready; otherwise does nothing. */\n  focus(): void\n  /** Applies a new locale or theme when the controller exists. */\n  update(options: Parameters<CheckoutController['update']>[0]): void\n}\n\n/**\n * Embeds Inttegro-hosted Checkout in a React application.\n *\n * The component renders an empty `div`, loads the executable runtime from\n * Inttegro's fixed origin after mount, creates a controller for `orderId`, and\n * destroys it during cleanup. Server rendering is safe because no runtime is\n * loaded until the effect runs in a browser.\n *\n * Changing `orderId`, `timeout`, or `title` starts a fresh hosted experience.\n * Changing `appearance` or `locale` updates the active experience in place.\n * Keep the component mounted while a payment is pending or confirmation is in\n * progress.\n *\n * @example Handle success, failure, and focus in a dialog\n * ```tsx\n * import { useRef } from 'react'\n * import { Checkout, type CheckoutHandle } from '@inttegro/react'\n *\n * function Payment({ orderId }: { orderId: string }) {\n *   const checkout = useRef<CheckoutHandle>(null)\n *\n *   return (\n *     <dialog open onTransitionEnd={() => checkout.current?.focus()}>\n *       <Checkout\n *         ref={checkout}\n *         orderId={orderId}\n *         appearance={{ theme: 'system' }}\n *         onCompleted={() => location.assign(`/orders/${orderId}/complete`)}\n *         onError={(error) => reportCheckoutError(error)}\n *       />\n *     </dialog>\n *   )\n * }\n * ```\n *\n * @category React\n */\nexport const Checkout = forwardRef<CheckoutHandle, CheckoutProps>(\n  function Checkout(\n    {\n      appearance,\n      className,\n      locale,\n      onCompleted,\n      onError,\n      onEvent,\n      onReady,\n      orderId,\n      style,\n      timeout,\n      title,\n    },\n    forwardedRef,\n  ) {\n    const containerRef = useRef<HTMLDivElement>(null)\n    const checkoutRef = useRef<CheckoutController | null>(null)\n    const callbacksRef = useRef({ onCompleted, onError, onEvent, onReady })\n    const updateOptionsRef = useRef({ appearance, locale })\n    callbacksRef.current = { onCompleted, onError, onEvent, onReady }\n    updateOptionsRef.current = { appearance, locale }\n\n    useImperativeHandle(\n      forwardedRef,\n      () => ({\n        focus: () => checkoutRef.current?.focus(),\n        update: (options) => checkoutRef.current?.update(options),\n      }),\n      [],\n    )\n\n    useEffect(() => {\n      const target = containerRef.current\n      if (!target) return\n\n      let active = true\n      let checkout: CheckoutController | undefined\n      let unsubscribe: (() => void) | undefined\n\n      void loadInttegro()\n        .then(async (inttegro) => {\n          if (!active || !inttegro) return\n          const instance = inttegro.createCheckout(\n            definedOptions({\n              ...updateOptionsRef.current,\n              orderId,\n              timeout,\n              title,\n            }),\n          )\n          if (!active) {\n            instance.destroy()\n            return\n          }\n          checkout = instance\n          checkoutRef.current = instance\n          unsubscribe = instance.onEvent((event) => {\n            callbacksRef.current.onEvent?.(event)\n            if (event.type === 'ready') callbacksRef.current.onReady?.(event)\n            if (event.type === 'completed')\n              callbacksRef.current.onCompleted?.(event)\n            if (event.type === 'error') callbacksRef.current.onError?.(event)\n          })\n          await instance.mount(target)\n        })\n        .catch((error: unknown) => {\n          if (active) callbacksRef.current.onError?.(asError(error))\n        })\n\n      return () => {\n        active = false\n        unsubscribe?.()\n        checkout?.destroy()\n        if (checkoutRef.current === checkout) checkoutRef.current = null\n      }\n    }, [orderId, timeout, title])\n\n    useEffect(() => {\n      checkoutRef.current?.update(definedOptions({ appearance, locale }))\n    }, [appearance, locale])\n\n    return <div className={className} ref={containerRef} style={style} />\n  },\n)\n\nfunction definedOptions<Value extends object>(options: Value): Value {\n  return Object.fromEntries(\n    Object.entries(options).filter(([, value]) => value !== undefined),\n  ) as Value\n}\n\nfunction asError(error: unknown): Error {\n  return error instanceof Error ? error : new Error('Checkout failed to load.')\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,gBAMO;AACP,mBAMO;AAyKI;AAnFJ,IAAM,eAAW;AAAA,EACtB,SAASA,UACP;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,GACA,cACA;AACA,UAAM,mBAAe,qBAAuB,IAAI;AAChD,UAAM,kBAAc,qBAAkC,IAAI;AAC1D,UAAM,mBAAe,qBAAO,EAAE,aAAa,SAAS,SAAS,QAAQ,CAAC;AACtE,UAAM,uBAAmB,qBAAO,EAAE,YAAY,OAAO,CAAC;AACtD,iBAAa,UAAU,EAAE,aAAa,SAAS,SAAS,QAAQ;AAChE,qBAAiB,UAAU,EAAE,YAAY,OAAO;AAEhD;AAAA,MACE;AAAA,MACA,OAAO;AAAA,QACL,OAAO,MAAM,YAAY,SAAS,MAAM;AAAA,QACxC,QAAQ,CAAC,YAAY,YAAY,SAAS,OAAO,OAAO;AAAA,MAC1D;AAAA,MACA,CAAC;AAAA,IACH;AAEA,gCAAU,MAAM;AACd,YAAM,SAAS,aAAa;AAC5B,UAAI,CAAC,OAAQ;AAEb,UAAI,SAAS;AACb,UAAI;AACJ,UAAI;AAEJ,eAAK,wBAAa,EACf,KAAK,OAAO,aAAa;AACxB,YAAI,CAAC,UAAU,CAAC,SAAU;AAC1B,cAAM,WAAW,SAAS;AAAA,UACxB,eAAe;AAAA,YACb,GAAG,iBAAiB;AAAA,YACpB;AAAA,YACA;AAAA,YACA;AAAA,UACF,CAAC;AAAA,QACH;AACA,YAAI,CAAC,QAAQ;AACX,mBAAS,QAAQ;AACjB;AAAA,QACF;AACA,mBAAW;AACX,oBAAY,UAAU;AACtB,sBAAc,SAAS,QAAQ,CAAC,UAAU;AACxC,uBAAa,QAAQ,UAAU,KAAK;AACpC,cAAI,MAAM,SAAS,QAAS,cAAa,QAAQ,UAAU,KAAK;AAChE,cAAI,MAAM,SAAS;AACjB,yBAAa,QAAQ,cAAc,KAAK;AAC1C,cAAI,MAAM,SAAS,QAAS,cAAa,QAAQ,UAAU,KAAK;AAAA,QAClE,CAAC;AACD,cAAM,SAAS,MAAM,MAAM;AAAA,MAC7B,CAAC,EACA,MAAM,CAAC,UAAmB;AACzB,YAAI,OAAQ,cAAa,QAAQ,UAAU,QAAQ,KAAK,CAAC;AAAA,MAC3D,CAAC;AAEH,aAAO,MAAM;AACX,iBAAS;AACT,sBAAc;AACd,kBAAU,QAAQ;AAClB,YAAI,YAAY,YAAY,SAAU,aAAY,UAAU;AAAA,MAC9D;AAAA,IACF,GAAG,CAAC,SAAS,SAAS,KAAK,CAAC;AAE5B,gCAAU,MAAM;AACd,kBAAY,SAAS,OAAO,eAAe,EAAE,YAAY,OAAO,CAAC,CAAC;AAAA,IACpE,GAAG,CAAC,YAAY,MAAM,CAAC;AAEvB,WAAO,4CAAC,SAAI,WAAsB,KAAK,cAAc,OAAc;AAAA,EACrE;AACF;AAEA,SAAS,eAAqC,SAAuB;AACnE,SAAO,OAAO;AAAA,IACZ,OAAO,QAAQ,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,MAAM,UAAU,MAAS;AAAA,EACnE;AACF;AAEA,SAAS,QAAQ,OAAuB;AACtC,SAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,0BAA0B;AAC9E;","names":["Checkout"]}

package/dist/index.d.cts

@@ -0,0 +1,94 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+import { CheckoutOptions, CheckoutEvent, CheckoutErrorEvent, CheckoutController } from '@inttegro/js';
+export { CheckoutAppearance, CheckoutErrorEvent, CheckoutEvent, CheckoutTheme } from '@inttegro/js';
+
+/**
+ * Props for {@link Checkout}.
+ *
+ * `orderId`, `timeout`, and `title` identify the embedded experience. Changing
+ * one replaces the underlying controller. `appearance` and `locale` update the
+ * existing controller without discarding payer progress.
+ *
+ * @category React
+ */
+interface CheckoutProps extends CheckoutOptions {
+    /** CSS class applied to the outer container owned by your React application. */
+    className?: string;
+    /** Inline styles applied to the outer container, never to controls inside Checkout. */
+    style?: CSSProperties;
+    /**
+     * Called after Checkout reports its successful terminal state.
+     * Use this to navigate or refresh server-owned Order state, not as the sole
+     * signal for fulfillment.
+     */
+    onCompleted?: (event: Extract<CheckoutEvent, {
+        type: 'completed';
+    }>) => void;
+    /**
+     * Called for loader/mount errors and sanitized hosted errors.
+     * Use `error instanceof InttegroCheckoutError` or check for an event `type`
+     * before reading framework-independent details.
+     */
+    onError?: (event: CheckoutErrorEvent | Error) => void;
+    /** Called for every sanitized lifecycle event, including events above. */
+    onEvent?: (event: CheckoutEvent) => void;
+    /** Called once the iframe is interactive and its mount promise has resolved. */
+    onReady?: (event: Extract<CheckoutEvent, {
+        type: 'ready';
+    }>) => void;
+}
+/**
+ * Imperative operations exposed by {@link Checkout} through a React ref.
+ *
+ * Prefer props for normal updates. Use the handle for focus management in
+ * dialogs or for updates driven by imperative host integrations.
+ *
+ * @category React
+ */
+interface CheckoutHandle {
+    /** Moves focus into Checkout when its controller is ready; otherwise does nothing. */
+    focus(): void;
+    /** Applies a new locale or theme when the controller exists. */
+    update(options: Parameters<CheckoutController['update']>[0]): void;
+}
+/**
+ * Embeds Inttegro-hosted Checkout in a React application.
+ *
+ * The component renders an empty `div`, loads the executable runtime from
+ * Inttegro's fixed origin after mount, creates a controller for `orderId`, and
+ * destroys it during cleanup. Server rendering is safe because no runtime is
+ * loaded until the effect runs in a browser.
+ *
+ * Changing `orderId`, `timeout`, or `title` starts a fresh hosted experience.
+ * Changing `appearance` or `locale` updates the active experience in place.
+ * Keep the component mounted while a payment is pending or confirmation is in
+ * progress.
+ *
+ * @example Handle success, failure, and focus in a dialog
+ * ```tsx
+ * import { useRef } from 'react'
+ * import { Checkout, type CheckoutHandle } from '@inttegro/react'
+ *
+ * function Payment({ orderId }: { orderId: string }) {
+ *   const checkout = useRef<CheckoutHandle>(null)
+ *
+ *   return (
+ *     <dialog open onTransitionEnd={() => checkout.current?.focus()}>
+ *       <Checkout
+ *         ref={checkout}
+ *         orderId={orderId}
+ *         appearance={{ theme: 'system' }}
+ *         onCompleted={() => location.assign(`/orders/${orderId}/complete`)}
+ *         onError={(error) => reportCheckoutError(error)}
+ *       />
+ *     </dialog>
+ *   )
+ * }
+ * ```
+ *
+ * @category React
+ */
+declare const Checkout: react.ForwardRefExoticComponent<CheckoutProps & react.RefAttributes<CheckoutHandle>>;
+
+export { Checkout, type CheckoutHandle, type CheckoutProps };

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+import { CheckoutOptions, CheckoutEvent, CheckoutErrorEvent, CheckoutController } from '@inttegro/js';
+export { CheckoutAppearance, CheckoutErrorEvent, CheckoutEvent, CheckoutTheme } from '@inttegro/js';
+
+/**
+ * Props for {@link Checkout}.
+ *
+ * `orderId`, `timeout`, and `title` identify the embedded experience. Changing
+ * one replaces the underlying controller. `appearance` and `locale` update the
+ * existing controller without discarding payer progress.
+ *
+ * @category React
+ */
+interface CheckoutProps extends CheckoutOptions {
+    /** CSS class applied to the outer container owned by your React application. */
+    className?: string;
+    /** Inline styles applied to the outer container, never to controls inside Checkout. */
+    style?: CSSProperties;
+    /**
+     * Called after Checkout reports its successful terminal state.
+     * Use this to navigate or refresh server-owned Order state, not as the sole
+     * signal for fulfillment.
+     */
+    onCompleted?: (event: Extract<CheckoutEvent, {
+        type: 'completed';
+    }>) => void;
+    /**
+     * Called for loader/mount errors and sanitized hosted errors.
+     * Use `error instanceof InttegroCheckoutError` or check for an event `type`
+     * before reading framework-independent details.
+     */
+    onError?: (event: CheckoutErrorEvent | Error) => void;
+    /** Called for every sanitized lifecycle event, including events above. */
+    onEvent?: (event: CheckoutEvent) => void;
+    /** Called once the iframe is interactive and its mount promise has resolved. */
+    onReady?: (event: Extract<CheckoutEvent, {
+        type: 'ready';
+    }>) => void;
+}
+/**
+ * Imperative operations exposed by {@link Checkout} through a React ref.
+ *
+ * Prefer props for normal updates. Use the handle for focus management in
+ * dialogs or for updates driven by imperative host integrations.
+ *
+ * @category React
+ */
+interface CheckoutHandle {
+    /** Moves focus into Checkout when its controller is ready; otherwise does nothing. */
+    focus(): void;
+    /** Applies a new locale or theme when the controller exists. */
+    update(options: Parameters<CheckoutController['update']>[0]): void;
+}
+/**
+ * Embeds Inttegro-hosted Checkout in a React application.
+ *
+ * The component renders an empty `div`, loads the executable runtime from
+ * Inttegro's fixed origin after mount, creates a controller for `orderId`, and
+ * destroys it during cleanup. Server rendering is safe because no runtime is
+ * loaded until the effect runs in a browser.
+ *
+ * Changing `orderId`, `timeout`, or `title` starts a fresh hosted experience.
+ * Changing `appearance` or `locale` updates the active experience in place.
+ * Keep the component mounted while a payment is pending or confirmation is in
+ * progress.
+ *
+ * @example Handle success, failure, and focus in a dialog
+ * ```tsx
+ * import { useRef } from 'react'
+ * import { Checkout, type CheckoutHandle } from '@inttegro/react'
+ *
+ * function Payment({ orderId }: { orderId: string }) {
+ *   const checkout = useRef<CheckoutHandle>(null)
+ *
+ *   return (
+ *     <dialog open onTransitionEnd={() => checkout.current?.focus()}>
+ *       <Checkout
+ *         ref={checkout}
+ *         orderId={orderId}
+ *         appearance={{ theme: 'system' }}
+ *         onCompleted={() => location.assign(`/orders/${orderId}/complete`)}
+ *         onError={(error) => reportCheckoutError(error)}
+ *       />
+ *     </dialog>
+ *   )
+ * }
+ * ```
+ *
+ * @category React
+ */
+declare const Checkout: react.ForwardRefExoticComponent<CheckoutProps & react.RefAttributes<CheckoutHandle>>;
+
+export { Checkout, type CheckoutHandle, type CheckoutProps };

package/dist/index.js

@@ -0,0 +1,97 @@
+// src/Checkout.tsx
+import {
+  loadInttegro
+} from "@inttegro/js";
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef
+} from "react";
+import { jsx } from "react/jsx-runtime";
+var Checkout = forwardRef(
+  function Checkout2({
+    appearance,
+    className,
+    locale,
+    onCompleted,
+    onError,
+    onEvent,
+    onReady,
+    orderId,
+    style,
+    timeout,
+    title
+  }, forwardedRef) {
+    const containerRef = useRef(null);
+    const checkoutRef = useRef(null);
+    const callbacksRef = useRef({ onCompleted, onError, onEvent, onReady });
+    const updateOptionsRef = useRef({ appearance, locale });
+    callbacksRef.current = { onCompleted, onError, onEvent, onReady };
+    updateOptionsRef.current = { appearance, locale };
+    useImperativeHandle(
+      forwardedRef,
+      () => ({
+        focus: () => checkoutRef.current?.focus(),
+        update: (options) => checkoutRef.current?.update(options)
+      }),
+      []
+    );
+    useEffect(() => {
+      const target = containerRef.current;
+      if (!target) return;
+      let active = true;
+      let checkout;
+      let unsubscribe;
+      void loadInttegro().then(async (inttegro) => {
+        if (!active || !inttegro) return;
+        const instance = inttegro.createCheckout(
+          definedOptions({
+            ...updateOptionsRef.current,
+            orderId,
+            timeout,
+            title
+          })
+        );
+        if (!active) {
+          instance.destroy();
+          return;
+        }
+        checkout = instance;
+        checkoutRef.current = instance;
+        unsubscribe = instance.onEvent((event) => {
+          callbacksRef.current.onEvent?.(event);
+          if (event.type === "ready") callbacksRef.current.onReady?.(event);
+          if (event.type === "completed")
+            callbacksRef.current.onCompleted?.(event);
+          if (event.type === "error") callbacksRef.current.onError?.(event);
+        });
+        await instance.mount(target);
+      }).catch((error) => {
+        if (active) callbacksRef.current.onError?.(asError(error));
+      });
+      return () => {
+        active = false;
+        unsubscribe?.();
+        checkout?.destroy();
+        if (checkoutRef.current === checkout) checkoutRef.current = null;
+      };
+    }, [orderId, timeout, title]);
+    useEffect(() => {
+      checkoutRef.current?.update(definedOptions({ appearance, locale }));
+    }, [appearance, locale]);
+    return /* @__PURE__ */ jsx("div", { className, ref: containerRef, style });
+  }
+);
+function definedOptions(options) {
+  return Object.fromEntries(
+    Object.entries(options).filter(([, value]) => value !== void 0)
+  );
+}
+function asError(error) {
+  return error instanceof Error ? error : new Error("Checkout failed to load.");
+}
+export {
+  Checkout
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/Checkout.tsx"],"sourcesContent":["import {\n  loadInttegro,\n  type CheckoutController,\n  type CheckoutErrorEvent,\n  type CheckoutEvent,\n  type CheckoutOptions,\n} from '@inttegro/js'\nimport {\n  forwardRef,\n  useEffect,\n  useImperativeHandle,\n  useRef,\n  type CSSProperties,\n} from 'react'\n\n/**\n * Props for {@link Checkout}.\n *\n * `orderId`, `timeout`, and `title` identify the embedded experience. Changing\n * one replaces the underlying controller. `appearance` and `locale` update the\n * existing controller without discarding payer progress.\n *\n * @category React\n */\nexport interface CheckoutProps extends CheckoutOptions {\n  /** CSS class applied to the outer container owned by your React application. */\n  className?: string\n  /** Inline styles applied to the outer container, never to controls inside Checkout. */\n  style?: CSSProperties\n  /**\n   * Called after Checkout reports its successful terminal state.\n   * Use this to navigate or refresh server-owned Order state, not as the sole\n   * signal for fulfillment.\n   */\n  onCompleted?: (event: Extract<CheckoutEvent, { type: 'completed' }>) => void\n  /**\n   * Called for loader/mount errors and sanitized hosted errors.\n   * Use `error instanceof InttegroCheckoutError` or check for an event `type`\n   * before reading framework-independent details.\n   */\n  onError?: (event: CheckoutErrorEvent | Error) => void\n  /** Called for every sanitized lifecycle event, including events above. */\n  onEvent?: (event: CheckoutEvent) => void\n  /** Called once the iframe is interactive and its mount promise has resolved. */\n  onReady?: (event: Extract<CheckoutEvent, { type: 'ready' }>) => void\n}\n\n/**\n * Imperative operations exposed by {@link Checkout} through a React ref.\n *\n * Prefer props for normal updates. Use the handle for focus management in\n * dialogs or for updates driven by imperative host integrations.\n *\n * @category React\n */\nexport interface CheckoutHandle {\n  /** Moves focus into Checkout when its controller is ready; otherwise does nothing. */\n  focus(): void\n  /** Applies a new locale or theme when the controller exists. */\n  update(options: Parameters<CheckoutController['update']>[0]): void\n}\n\n/**\n * Embeds Inttegro-hosted Checkout in a React application.\n *\n * The component renders an empty `div`, loads the executable runtime from\n * Inttegro's fixed origin after mount, creates a controller for `orderId`, and\n * destroys it during cleanup. Server rendering is safe because no runtime is\n * loaded until the effect runs in a browser.\n *\n * Changing `orderId`, `timeout`, or `title` starts a fresh hosted experience.\n * Changing `appearance` or `locale` updates the active experience in place.\n * Keep the component mounted while a payment is pending or confirmation is in\n * progress.\n *\n * @example Handle success, failure, and focus in a dialog\n * ```tsx\n * import { useRef } from 'react'\n * import { Checkout, type CheckoutHandle } from '@inttegro/react'\n *\n * function Payment({ orderId }: { orderId: string }) {\n *   const checkout = useRef<CheckoutHandle>(null)\n *\n *   return (\n *     <dialog open onTransitionEnd={() => checkout.current?.focus()}>\n *       <Checkout\n *         ref={checkout}\n *         orderId={orderId}\n *         appearance={{ theme: 'system' }}\n *         onCompleted={() => location.assign(`/orders/${orderId}/complete`)}\n *         onError={(error) => reportCheckoutError(error)}\n *       />\n *     </dialog>\n *   )\n * }\n * ```\n *\n * @category React\n */\nexport const Checkout = forwardRef<CheckoutHandle, CheckoutProps>(\n  function Checkout(\n    {\n      appearance,\n      className,\n      locale,\n      onCompleted,\n      onError,\n      onEvent,\n      onReady,\n      orderId,\n      style,\n      timeout,\n      title,\n    },\n    forwardedRef,\n  ) {\n    const containerRef = useRef<HTMLDivElement>(null)\n    const checkoutRef = useRef<CheckoutController | null>(null)\n    const callbacksRef = useRef({ onCompleted, onError, onEvent, onReady })\n    const updateOptionsRef = useRef({ appearance, locale })\n    callbacksRef.current = { onCompleted, onError, onEvent, onReady }\n    updateOptionsRef.current = { appearance, locale }\n\n    useImperativeHandle(\n      forwardedRef,\n      () => ({\n        focus: () => checkoutRef.current?.focus(),\n        update: (options) => checkoutRef.current?.update(options),\n      }),\n      [],\n    )\n\n    useEffect(() => {\n      const target = containerRef.current\n      if (!target) return\n\n      let active = true\n      let checkout: CheckoutController | undefined\n      let unsubscribe: (() => void) | undefined\n\n      void loadInttegro()\n        .then(async (inttegro) => {\n          if (!active || !inttegro) return\n          const instance = inttegro.createCheckout(\n            definedOptions({\n              ...updateOptionsRef.current,\n              orderId,\n              timeout,\n              title,\n            }),\n          )\n          if (!active) {\n            instance.destroy()\n            return\n          }\n          checkout = instance\n          checkoutRef.current = instance\n          unsubscribe = instance.onEvent((event) => {\n            callbacksRef.current.onEvent?.(event)\n            if (event.type === 'ready') callbacksRef.current.onReady?.(event)\n            if (event.type === 'completed')\n              callbacksRef.current.onCompleted?.(event)\n            if (event.type === 'error') callbacksRef.current.onError?.(event)\n          })\n          await instance.mount(target)\n        })\n        .catch((error: unknown) => {\n          if (active) callbacksRef.current.onError?.(asError(error))\n        })\n\n      return () => {\n        active = false\n        unsubscribe?.()\n        checkout?.destroy()\n        if (checkoutRef.current === checkout) checkoutRef.current = null\n      }\n    }, [orderId, timeout, title])\n\n    useEffect(() => {\n      checkoutRef.current?.update(definedOptions({ appearance, locale }))\n    }, [appearance, locale])\n\n    return <div className={className} ref={containerRef} style={style} />\n  },\n)\n\nfunction definedOptions<Value extends object>(options: Value): Value {\n  return Object.fromEntries(\n    Object.entries(options).filter(([, value]) => value !== undefined),\n  ) as Value\n}\n\nfunction asError(error: unknown): Error {\n  return error instanceof Error ? error : new Error('Checkout failed to load.')\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,OAKK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AAyKI;AAnFJ,IAAM,WAAW;AAAA,EACtB,SAASA,UACP;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,GACA,cACA;AACA,UAAM,eAAe,OAAuB,IAAI;AAChD,UAAM,cAAc,OAAkC,IAAI;AAC1D,UAAM,eAAe,OAAO,EAAE,aAAa,SAAS,SAAS,QAAQ,CAAC;AACtE,UAAM,mBAAmB,OAAO,EAAE,YAAY,OAAO,CAAC;AACtD,iBAAa,UAAU,EAAE,aAAa,SAAS,SAAS,QAAQ;AAChE,qBAAiB,UAAU,EAAE,YAAY,OAAO;AAEhD;AAAA,MACE;AAAA,MACA,OAAO;AAAA,QACL,OAAO,MAAM,YAAY,SAAS,MAAM;AAAA,QACxC,QAAQ,CAAC,YAAY,YAAY,SAAS,OAAO,OAAO;AAAA,MAC1D;AAAA,MACA,CAAC;AAAA,IACH;AAEA,cAAU,MAAM;AACd,YAAM,SAAS,aAAa;AAC5B,UAAI,CAAC,OAAQ;AAEb,UAAI,SAAS;AACb,UAAI;AACJ,UAAI;AAEJ,WAAK,aAAa,EACf,KAAK,OAAO,aAAa;AACxB,YAAI,CAAC,UAAU,CAAC,SAAU;AAC1B,cAAM,WAAW,SAAS;AAAA,UACxB,eAAe;AAAA,YACb,GAAG,iBAAiB;AAAA,YACpB;AAAA,YACA;AAAA,YACA;AAAA,UACF,CAAC;AAAA,QACH;AACA,YAAI,CAAC,QAAQ;AACX,mBAAS,QAAQ;AACjB;AAAA,QACF;AACA,mBAAW;AACX,oBAAY,UAAU;AACtB,sBAAc,SAAS,QAAQ,CAAC,UAAU;AACxC,uBAAa,QAAQ,UAAU,KAAK;AACpC,cAAI,MAAM,SAAS,QAAS,cAAa,QAAQ,UAAU,KAAK;AAChE,cAAI,MAAM,SAAS;AACjB,yBAAa,QAAQ,cAAc,KAAK;AAC1C,cAAI,MAAM,SAAS,QAAS,cAAa,QAAQ,UAAU,KAAK;AAAA,QAClE,CAAC;AACD,cAAM,SAAS,MAAM,MAAM;AAAA,MAC7B,CAAC,EACA,MAAM,CAAC,UAAmB;AACzB,YAAI,OAAQ,cAAa,QAAQ,UAAU,QAAQ,KAAK,CAAC;AAAA,MAC3D,CAAC;AAEH,aAAO,MAAM;AACX,iBAAS;AACT,sBAAc;AACd,kBAAU,QAAQ;AAClB,YAAI,YAAY,YAAY,SAAU,aAAY,UAAU;AAAA,MAC9D;AAAA,IACF,GAAG,CAAC,SAAS,SAAS,KAAK,CAAC;AAE5B,cAAU,MAAM;AACd,kBAAY,SAAS,OAAO,eAAe,EAAE,YAAY,OAAO,CAAC,CAAC;AAAA,IACpE,GAAG,CAAC,YAAY,MAAM,CAAC;AAEvB,WAAO,oBAAC,SAAI,WAAsB,KAAK,cAAc,OAAc;AAAA,EACrE;AACF;AAEA,SAAS,eAAqC,SAAuB;AACnE,SAAO,OAAO;AAAA,IACZ,OAAO,QAAQ,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,MAAM,UAAU,MAAS;AAAA,EACnE;AACF;AAEA,SAAS,QAAQ,OAAuB;AACtC,SAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,0BAA0B;AAC9E;","names":["Checkout"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@inttegro/react",
+  "version": "0.1.0",
+  "description": "React components for Inttegro hosted workflows",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inttegro/js": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zebodotdev/js.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://studio.inttegro.com/web/react",
+  "author": "Inttegro Eng <engineering@inttegro.com> (https://inttegro.com)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "src/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@types/react": "19.2.18",
+    "react": "19.2.8",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3"
+  }
+}