@apiosk/checkout-react 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# `@apiosk/checkout-react`
+
+React and Next.js wrapper for the Apiosk four-layer checkout button.
+
+This package does not reimplement the UI logic. It mounts the shared
+`@apiosk/checkout-web` custom element and passes the normalized config through
+to that runtime.
+
+## Install
+
+After publish:
+
+```bash
+npm install @apiosk/checkout-react @apiosk/checkout-web @apiosk/checkout-core
+```
+
+Before publish:
+
+```bash
+npm install ./subs/checkout-react ./subs/checkout-web ./subs/checkout-core
+```
+
+## Quick start
+
+```tsx
+import { PayWithApioskButton } from "@apiosk/checkout-react";
+
+export function MerchantCheckout() {
+  return (
+    <PayWithApioskButton
+      merchantName="Northstar Marketplace"
+      productName="Automation bundle"
+      amountLabel="24.95 EUR"
+      orderReference="ord_2048"
+      subtitle="One trigger for humans, agents, and programmable rails."
+      rails={[
+        {
+          id: "credits",
+          status: "live",
+          launchUrl: "https://gateway.apiosk.com/geocode/forward",
+        },
+        {
+          id: "x402",
+          status: "live",
+          launchUrl: "https://gateway.apiosk.com/geocode/forward",
+        },
+        {
+          id: "agent",
+          status: "pilot",
+        },
+      ]}
+      callbacks={{
+        successUrl: "https://merchant.example/success",
+        cancelUrl: "https://merchant.example/cancel",
+        webhookUrl: "https://merchant.example/webhooks/apiosk",
+      }}
+    />
+  );
+}
+```
+
+## Ref API
+
+```tsx
+import { useRef } from "react";
+import { PayWithApioskButton } from "@apiosk/checkout-react";
+
+const checkoutRef = useRef(null);
+
+<PayWithApioskButton ref={checkoutRef} config={config} />;
+
+checkoutRef.current?.openCheckout();
+```
+
+The component exposes:
+
+- `openCheckout()`
+- `closeCheckout()`
+- `element`
+
+## Why this wrapper exists
+
+The React package should stay thin. The DOM runtime belongs in
+`@apiosk/checkout-web`, and the shared schema belongs in
+`@apiosk/checkout-core`.
+
+That keeps React, Vue, and plain HTML integrations aligned around one contract.

package/index.d.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties, ForwardRefExoticComponent, RefAttributes } from "react";
+import type { CheckoutConfigInput } from "@apiosk/checkout-core";
+
+export interface ApioskCheckoutButtonHandle {
+  element: HTMLElement | null;
+  openCheckout(): void;
+  closeCheckout(): void;
+}
+
+export interface ApioskCheckoutButtonProps extends CheckoutConfigInput {
+  config?: CheckoutConfigInput;
+  className?: string;
+  style?: CSSProperties;
+  testId?: string;
+  onReady?: (element: HTMLElement) => void;
+}
+
+export declare const ApioskCheckoutButton: ForwardRefExoticComponent<
+  ApioskCheckoutButtonProps & RefAttributes<ApioskCheckoutButtonHandle>
+>;
+
+export declare const PayWithApioskButton: typeof ApioskCheckoutButton;
+export declare function registerApioskCheckoutButton(): unknown;
+export default ApioskCheckoutButton;

package/index.mjs

@@ -0,0 +1,66 @@
+import React, { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { normalizeCheckoutConfig } from "@apiosk/checkout-core";
+import {
+  CHECKOUT_ELEMENT_TAG,
+  registerApioskCheckoutButton,
+  serializeCheckoutConfig,
+} from "@apiosk/checkout-web";
+
+export const ApioskCheckoutButton = forwardRef(function ApioskCheckoutButton(
+  props,
+  forwardedRef,
+) {
+  const elementRef = useRef(null);
+  const {
+    config,
+    className,
+    style,
+    testId,
+    onReady,
+    ...flatConfig
+  } = props || {};
+  const normalizedConfig = normalizeCheckoutConfig(config || flatConfig);
+  const serializedConfig = serializeCheckoutConfig(normalizedConfig);
+
+  useEffect(() => {
+    registerApioskCheckoutButton();
+  }, []);
+
+  useEffect(() => {
+    if (!elementRef.current) {
+      return;
+    }
+
+    elementRef.current.config = normalizedConfig;
+
+    if (typeof onReady === "function") {
+      onReady(elementRef.current);
+    }
+  }, [normalizedConfig, onReady]);
+
+  useImperativeHandle(
+    forwardedRef,
+    () => ({
+      get element() {
+        return elementRef.current;
+      },
+      openCheckout: () => elementRef.current?.openCheckout?.(),
+      closeCheckout: () => elementRef.current?.closeCheckout?.(),
+    }),
+    [],
+  );
+
+  return React.createElement(CHECKOUT_ELEMENT_TAG, {
+    ref: (value) => {
+      elementRef.current = value;
+    },
+    config: serializedConfig,
+    className,
+    style,
+    "data-testid": testId,
+  });
+});
+
+export const PayWithApioskButton = ApioskCheckoutButton;
+export { registerApioskCheckoutButton };
+export default ApioskCheckoutButton;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@apiosk/checkout-react",
+  "version": "0.1.0",
+  "description": "React wrapper for the Apiosk four-layer checkout button",
+  "type": "module",
+  "main": "./index.mjs",
+  "types": "./index.d.ts",
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    }
+  },
+  "scripts": {
+    "check": "node --check index.mjs"
+  },
+  "keywords": [
+    "apiosk",
+    "checkout",
+    "react",
+    "nextjs",
+    "payments"
+  ],
+  "author": "Apiosk",
+  "license": "MIT",
+  "homepage": "https://docs.apiosk.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@apiosk/checkout-core": "^0.1.0",
+    "@apiosk/checkout-web": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  }
+}