@railbed/embed 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MediaGlobe
+
+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

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @railbed/embed
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Railbed's embedded checkout for React, Vue and plain pages: the payment widget or pricing table in your page, a buy
+button that opens it over the page, and checkout sessions your server made. Typed events tell your page what happened.
+
+It's a thin layer over Railbed's embed script (`https://pay.railbed.io/embed.js`): this package adds the script to the
+page once, renders the elements it draws, and turns its DOM events into props and emits. No runtime dependencies; React
+18+ and Vue 3.3+ are optional peers.
+
+Full guide: https://railbed.com/docs/guides/embedded-checkout/
+
+```bash
+npm install @railbed/embed
+```
+
+The package is ESM only. Bundlers and Next.js find it as is, as does `require()` in Node 20.19+ or 22.12+ (where it
+loads ES modules without a flag), and TypeScript finds its types with `moduleResolution` `bundler`, `node16` (from an
+ES module) or `node`. A Jest setup that runs CommonJS has to transform it:
+`transformIgnorePatterns: ['/node_modules/(?!@railbed/embed/)']`.
+
+## React and Next.js
+
+The components are client components (`'use client'` is built in), so a Next.js app router page can render
+`<RailbedCheckout checkout="pro-plan" />` directly. Event handlers are functions, which can't cross from a server
+component, so pass them from a component of your own marked `'use client'`. On the server the components render the
+element with a plain link to the checkout, which stays if a site blocks the script.
+
+```tsx
+'use client';
+import { useRouter } from 'next/navigation';
+import { RailbedCheckout } from '@railbed/embed/react';
+
+export function ProCheckout({ email }: { email?: string }) {
+  const router = useRouter();
+  return (
+    <RailbedCheckout
+      checkout="pro-plan"                    // the slug on the checkout's Share tab
+      sessionEndpoint="/api/railbed/session" // optional: your server makes the session at Continue
+      email={email}                          // optional: fills in the buyer's email
+      style={{ '--railbed-accent': '#1F4D3A', '--railbed-font': 'Inter' }}
+      onPaid={(detail, event) => {
+        event.preventDefault(); // stay on this page instead of going to the success URL
+        router.push(`/thanks?payment=${detail.session}`);
+      }}
+      onError={(detail) => console.warn(detail.code)}
+    />
+  );
+}
+```
+
+`<RailbedButton checkout="…" label="Buy now" shape="pill">` takes the same props and opens the checkout over the page
+(a full-screen sheet on phones).
+
+Instead of `sessionEndpoint`, pass `createSession`, a function that gets `{ checkout, plan, option, email }` and returns
+the session id (or `{ session }`, or the API's session object):
+
+```tsx
+<RailbedCheckout checkout="pro-plan" createSession={(request) => api.post('/railbed/session', request)} />
+```
+
+## Vue
+
+```js
+import { RailbedCheckout } from '@railbed/embed/vue';
+```
+
+```html
+<RailbedCheckout
+  checkout="pro-plan"
+  session-endpoint="/api/railbed/session"
+  :email="user.email"
+  class="checkout"
+  @paid="(detail, event) => onPaid(detail, event)"
+  @error="(detail) => console.warn(detail.code)"
+/>
+```
+
+Events are `ready`, `step`, `handoff`, `paid`, `held`, `failed`, `expired`, `error`, `close` (each with the detail and
+the DOM event) and `load-error` when the script can't load.
+
+## Any page
+
+```js
+import { openCheckout } from '@railbed/embed';
+
+// Your server made a checkout session and returned its url (or its id, pay_…).
+const { status, session } = await openCheckout(url);
+// status: 'paid' | 'held' | 'failed' | 'expired' | 'closed'. Fulfil from your server, not from this.
+```
+
+`loadRailbed()` adds the script and resolves with `window.Railbed`; plain HTML can skip this package entirely:
+
+```html
+<script src="https://pay.railbed.io/embed.js" async></script>
+<railbed-checkout checkout="pro-plan"></railbed-checkout>
+```
+
+## Props
+
+| Prop | What it does |
+| --- | --- |
+| `checkout` | The checkout's slug. |
+| `session` | A session your server already made (`pay_…`). |
+| `sessionEndpoint` | Your endpoint that makes a session when the buyer presses Continue. |
+| `createSession` | A function that makes the session, instead of the endpoint. |
+| `email` | Fills in the buyer's email. Sent by message, never in a URL. |
+| `label`, `shape` | `RailbedButton` only: its text, and `pill` or `rounded`. |
+| `origin` | Default `https://pay.railbed.io`. |
+| `nonce` | For a Content Security Policy that uses nonces. |
+| `className`/`class`, `style` | Passed to the element, so the `--railbed-*` variables work from either. |
+
+Event details never carry the buyer's email or details. Fulfil orders from the signed webhook or
+`GET /v1/payments/:id`, never from a browser event.
+
+## Development
+
+```bash
+npm install
+npm test        # vitest in jsdom; no network
+npm run build   # ESM and .d.ts in dist/
+```
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+/** Where the checkout lives. Override it only to point at a Railbed test host. */
+export declare const DEFAULT_ORIGIN = "https://pay.railbed.io";
+/** The events every element fires, as `railbed:<name>` DOM events that bubble and cross shadow roots. */
+export declare const RAILBED_EVENTS: readonly ["ready", "step", "handoff", "paid", "held", "failed", "expired", "error", "close"];
+export type RailbedEventName = (typeof RAILBED_EVENTS)[number];
+/** Where the buyer is in the checkout (`railbed:step`). */
+export type RailbedStep = 'plan' | 'details' | 'method' | 'opening' | 'waiting' | 'crypto' | 'receipt';
+/**
+ * What an event carries. Never the buyer's email or details, a reference, metadata or a deposit address: ask your
+ * server (GET /v1/payments/:id) or use the signed webhook for anything you fulfil from.
+ */
+export interface RailbedEventDetail {
+    /** The checkout session (`pay_…`), once there is one. */
+    session: string | null;
+    /** The checkout's slug, for an element made from a checkout. */
+    checkout: string | null;
+    mode?: 'test' | 'live';
+    /** In the checkout's currency, as a decimal string: "49.00". */
+    amount?: string;
+    currency?: string;
+    /** A pricing table's plan, as the buyer saw it. */
+    plan?: string;
+    status?: string;
+    /** `railbed:step` only. */
+    step?: RailbedStep;
+    /** `railbed:error` only: what went wrong, for example `session_failed` when your server didn't make a session. */
+    code?: string;
+    /** `railbed:handoff` only: the card provider the buyer went on to. */
+    provider?: string;
+}
+export type RailbedEvent = CustomEvent<RailbedEventDetail>;
+/** What the checkout sends your session endpoint or `createSession` when the buyer presses Continue. */
+export interface SessionRequest {
+    checkout: string | null;
+    /** A pricing table's plan id. */
+    plan: string | null;
+    /** A pricing table's billing option (its switch): 0 or 1. */
+    option: 0 | 1 | null;
+    /** What the buyer typed. Your server's own record of the user is the one to trust. */
+    email: string;
+}
+/** A session id (`pay_…`), or an object carrying one as `session` or `id` (the API's session object works as is). */
+export type SessionAnswer = string | {
+    session: string;
+} | {
+    id: string;
+};
+/** Makes the session on your server and returns it. A rejection or a wrong answer shows the buyer a retry. */
+export type CreateSession = (request: SessionRequest) => SessionAnswer | Promise<SessionAnswer>;
+/** How a pop-up opened with `openCheckout` ended. */
+export interface OpenResult {
+    status: 'paid' | 'held' | 'failed' | 'expired' | 'closed';
+    session: string;
+}
+/** What embed.js puts on `window.Railbed`. */
+export interface RailbedGlobal {
+    open(urlOrId: string): Promise<OpenResult>;
+}
+export interface LoadOptions {
+    /** Default https://pay.railbed.io. */
+    origin?: string;
+    /** For a Content Security Policy that uses nonces. */
+    nonce?: string;
+    /** How long to wait for the script, in ms. Default 20 000. */
+    timeout?: number;
+}
+/** The `on…` prop for each event, as the React components name them. */
+export declare const HANDLER_NAMES: {
+    readonly ready: "onReady";
+    readonly step: "onStep";
+    readonly handoff: "onHandoff";
+    readonly paid: "onPaid";
+    readonly held: "onHeld";
+    readonly failed: "onFailed";
+    readonly expired: "onExpired";
+    readonly error: "onError";
+    readonly close: "onClose";
+};
+export type RailbedHandler = (detail: RailbedEventDetail, event: RailbedEvent) => void;
+/** The origin, checked: http or https only, nothing after the host. */
+export declare function railbedOrigin(origin?: string): string;
+/**
+ * Adds `{origin}/embed.js` to the page once and resolves when it has run, with `window.Railbed`. Safe to call as often
+ * as you like; a script tag already on the page is reused. Browser only.
+ */
+export declare function loadRailbed(options?: LoadOptions): Promise<RailbedGlobal>;
+/**
+ * Opens a checkout session your server made (its `url`, or its id `pay_…`) over the page and resolves when the buyer
+ * closes it. Fulfil from your server (the webhook, or GET /v1/payments/:id), not from `status`.
+ */
+export declare function openCheckout(urlOrId: string, options?: LoadOptions): Promise<OpenResult>;
+/** The element's plain link while embed.js loads, or if a site blocks it (the script draws over it once it runs). */
+export declare function fallbackHref(origin: string, checkout?: string | null, session?: string | null): string | null;
+/** The element's attributes from the components' props, leaving out what isn't set. */
+export declare function elementAttributes(props: {
+    checkout?: string | null;
+    session?: string | null;
+    sessionEndpoint?: string | null;
+    email?: string | null;
+    label?: string | null;
+    shape?: 'pill' | 'rounded' | null;
+}): Record<string, string>;
+/** The element's `createSession` hook (embed.js reads it at Continue; set before or after the script runs). */
+export interface SessionHost extends HTMLElement {
+    createSession: CreateSession | null;
+}
+/** Listens for every `railbed:*` event on `el`, calling `handle(name, event)`; returns the clean-up. */
+export declare function listen(el: EventTarget, handle: (name: RailbedEventName, event: RailbedEvent) => void): () => void;

package/dist/index.js

@@ -0,0 +1,143 @@
+// @railbed/embed: a thin, typed layer over Railbed's embed script ({origin}/embed.js). The script does the work (the
+// <railbed-checkout> and <railbed-button> elements, their frames, Railbed.open); this package loads it once and gives
+// React and Vue components, and plain pages, the same API with types. No runtime dependencies.
+// Reference: https://railbed.com/docs/guides/embedded-checkout/
+/** Where the checkout lives. Override it only to point at a Railbed test host. */
+export const DEFAULT_ORIGIN = 'https://pay.railbed.io';
+/** The events every element fires, as `railbed:<name>` DOM events that bubble and cross shadow roots. */
+export const RAILBED_EVENTS = ['ready', 'step', 'handoff', 'paid', 'held', 'failed', 'expired', 'error', 'close'];
+/** The `on…` prop for each event, as the React components name them. */
+export const HANDLER_NAMES = {
+    ready: 'onReady',
+    step: 'onStep',
+    handoff: 'onHandoff',
+    paid: 'onPaid',
+    held: 'onHeld',
+    failed: 'onFailed',
+    expired: 'onExpired',
+    error: 'onError',
+    close: 'onClose',
+};
+/** The origin, checked: http or https only, nothing after the host. */
+export function railbedOrigin(origin = DEFAULT_ORIGIN) {
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        throw new TypeError(`Not an origin: ${origin}`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        throw new TypeError(`Not an http or https origin: ${origin}`);
+    return url.origin;
+}
+function railbed() {
+    const r = window.Railbed;
+    return r && typeof r.open === 'function' ? r : null;
+}
+const loading = new Map();
+/**
+ * Adds `{origin}/embed.js` to the page once and resolves when it has run, with `window.Railbed`. Safe to call as often
+ * as you like; a script tag already on the page is reused. Browser only.
+ */
+export function loadRailbed(options = {}) {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return Promise.reject(new Error('loadRailbed runs in the browser only.'));
+    }
+    let origin;
+    try {
+        origin = railbedOrigin(options.origin);
+    }
+    catch (err) {
+        return Promise.reject(err);
+    }
+    const ready = railbed();
+    if (ready)
+        return Promise.resolve(ready);
+    const pending = loading.get(origin);
+    if (pending)
+        return pending;
+    const src = `${origin}/embed.js`;
+    const promise = new Promise((resolve, reject) => {
+        let script = Array.from(document.querySelectorAll('script[src]')).find((s) => s.src === src);
+        if (!script) {
+            script = document.createElement('script');
+            script.src = src;
+            script.async = true;
+            if (options.nonce)
+                script.nonce = options.nonce;
+            document.head.appendChild(script);
+        }
+        const tag = script;
+        const fail = (message) => {
+            cleanup();
+            loading.delete(origin); // the next call tries again
+            reject(new Error(message));
+        };
+        const onLoad = () => {
+            const r = railbed();
+            if (r) {
+                cleanup();
+                resolve(r);
+            }
+            else
+                fail('Railbed’s embed script ran but can’t work in this browser.');
+        };
+        const onError = () => {
+            tag.remove();
+            fail(`Couldn’t load ${src}. If your site sets a Content Security Policy, allow ${new URL(origin).host} in it.`);
+        };
+        const timer = setTimeout(() => fail(`${src} took too long to load.`), options.timeout ?? 20000);
+        function cleanup() {
+            clearTimeout(timer);
+            tag.removeEventListener('load', onLoad);
+            tag.removeEventListener('error', onError);
+        }
+        tag.addEventListener('load', onLoad);
+        tag.addEventListener('error', onError);
+    });
+    loading.set(origin, promise);
+    return promise;
+}
+/**
+ * Opens a checkout session your server made (its `url`, or its id `pay_…`) over the page and resolves when the buyer
+ * closes it. Fulfil from your server (the webhook, or GET /v1/payments/:id), not from `status`.
+ */
+export function openCheckout(urlOrId, options = {}) {
+    return loadRailbed(options).then((r) => r.open(urlOrId));
+}
+// ---------- Shared by the React and Vue components ----------
+/** The element's plain link while embed.js loads, or if a site blocks it (the script draws over it once it runs). */
+export function fallbackHref(origin, checkout, session) {
+    if (checkout)
+        return `${origin}/c/${encodeURIComponent(checkout)}`;
+    if (session)
+        return `${origin}/p/${encodeURIComponent(session)}`;
+    return null;
+}
+/** The element's attributes from the components' props, leaving out what isn't set. */
+export function elementAttributes(props) {
+    const out = {};
+    if (props.checkout)
+        out.checkout = props.checkout;
+    if (props.session)
+        out.session = props.session;
+    if (props.sessionEndpoint)
+        out['session-endpoint'] = props.sessionEndpoint;
+    if (props.email)
+        out.email = props.email;
+    if (props.label)
+        out.label = props.label;
+    if (props.shape)
+        out.shape = props.shape;
+    return out;
+}
+/** Listens for every `railbed:*` event on `el`, calling `handle(name, event)`; returns the clean-up. */
+export function listen(el, handle) {
+    const off = RAILBED_EVENTS.map((name) => {
+        const fn = (e) => handle(name, e);
+        el.addEventListener(`railbed:${name}`, fn);
+        return () => el.removeEventListener(`railbed:${name}`, fn);
+    });
+    return () => off.forEach((f) => f());
+}

package/dist/react.d.ts

@@ -0,0 +1,47 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { HANDLER_NAMES, type CreateSession, type RailbedEventName, type RailbedHandler } from './index.js';
+export type { CreateSession, OpenResult, RailbedEvent, RailbedEventDetail, RailbedEventName, RailbedHandler, RailbedStep, SessionAnswer, SessionRequest, } from './index.js';
+export { DEFAULT_ORIGIN, loadRailbed, openCheckout } from './index.js';
+/** `onReady`, `onStep`, `onHandoff`, `onPaid`, `onHeld`, `onFailed`, `onExpired`, `onError`, `onClose`. */
+export type RailbedEventProps = {
+    [K in RailbedEventName as (typeof HANDLER_NAMES)[K]]?: RailbedHandler;
+};
+/** Inline styles, including the --railbed-* variables that match the checkout to your site. */
+export type RailbedStyle = CSSProperties & {
+    [name: `--railbed-${string}`]: string | number | undefined;
+};
+export interface RailbedCheckoutProps extends RailbedEventProps {
+    /** The checkout's slug, from its Share tab. */
+    checkout?: string;
+    /** A session your server already made (`pay_…`). With `checkout`, the buyer pays that session. */
+    session?: string;
+    /** Your endpoint that makes a session when the buyer presses Continue (POST, same site, JSON). */
+    sessionEndpoint?: string;
+    /** Makes the session instead of `sessionEndpoint`, for example through your own API client. */
+    createSession?: CreateSession;
+    /** Fills in the buyer's email. Sent to the checkout by message, never in a URL. */
+    email?: string;
+    className?: string;
+    style?: RailbedStyle;
+    id?: string;
+    /**
+     * What shows until embed.js has drawn the checkout, and stays if a site blocks it. Defaults to a plain link to the
+     * checkout; pass `null` for nothing.
+     */
+    children?: ReactNode;
+    /** Default https://pay.railbed.io. */
+    origin?: string;
+    /** For a Content Security Policy that uses nonces. */
+    nonce?: string;
+    /** embed.js couldn't load (blocked, offline): the plain link is still there. */
+    onLoadError?: (error: Error) => void;
+}
+export interface RailbedButtonProps extends RailbedCheckoutProps {
+    /** The button's text. Default "Buy now" ("Pay now" for a session alone). */
+    label?: string;
+    shape?: 'pill' | 'rounded';
+}
+/** The payment widget or pricing table in your page. */
+export declare const RailbedCheckout: import("react").ForwardRefExoticComponent<RailbedCheckoutProps & import("react").RefAttributes<HTMLElement>>;
+/** A buy button that opens the checkout over your page (a full-screen sheet on phones). */
+export declare const RailbedButton: import("react").ForwardRefExoticComponent<RailbedButtonProps & import("react").RefAttributes<HTMLElement>>;

package/dist/react.js

@@ -0,0 +1,70 @@
+'use client';
+// React components for Railbed's embedded checkout: <RailbedCheckout> (the payment widget or pricing table in the page)
+// and <RailbedButton> (a buy button that opens it over the page). Both render the custom element embed.js draws, load
+// embed.js once, and turn its `railbed:*` DOM events into props. Works with React 18 and 19, and in Next.js's app router
+// (this file is a client component). Reference: https://railbed.com/docs/guides/embedded-checkout/
+import { createElement, forwardRef, useCallback, useEffect, useRef, version } from 'react';
+import { DEFAULT_ORIGIN, elementAttributes, fallbackHref, HANDLER_NAMES, listen, loadRailbed, railbedOrigin, } from './index.js';
+export { DEFAULT_ORIGIN, loadRailbed, openCheckout } from './index.js';
+// React 19 sets `className` on a custom element as its class; React 18 passes props through as attributes, so it needs
+// `class` itself.
+const REACT_MAJOR = Number.parseInt(version, 10);
+const CLASS_PROP = REACT_MAJOR >= 19 ? 'className' : 'class';
+function assignRef(ref, value) {
+    if (typeof ref === 'function')
+        ref(value);
+    else if (ref)
+        ref.current = value;
+}
+function useRailbedElement(tag, props, ref, words) {
+    const node = useRef(null);
+    const latest = useRef(props);
+    latest.current = props;
+    const origin = railbedOrigin(props.origin ?? DEFAULT_ORIGIN);
+    useEffect(() => {
+        let live = true;
+        loadRailbed({ origin, nonce: props.nonce }).catch((err) => {
+            if (live)
+                latest.current.onLoadError?.(err);
+        });
+        return () => {
+            live = false;
+        };
+    }, [origin, props.nonce]);
+    useEffect(() => {
+        const el = node.current;
+        if (!el)
+            return;
+        return listen(el, (name, event) => latest.current[HANDLER_NAMES[name]]?.(event.detail, event));
+    }, []);
+    // One stable function while a createSession prop is given, so a new arrow each render doesn't re-send anything.
+    const hasCreate = typeof props.createSession === 'function';
+    useEffect(() => {
+        const el = node.current;
+        if (!el)
+            return;
+        el.createSession = hasCreate ? (request) => latest.current.createSession(request) : null;
+    }, [hasCreate]);
+    const setNode = useCallback((el) => {
+        node.current = el;
+        assignRef(ref, el);
+    }, [ref]);
+    const href = fallbackHref(origin, props.checkout, props.session);
+    const children = props.children !== undefined ? props.children : href ? createElement('a', { href }, words) : null;
+    return createElement(tag, {
+        ...elementAttributes(props),
+        ref: setNode,
+        id: props.id,
+        style: props.style,
+        [CLASS_PROP]: props.className,
+        suppressHydrationWarning: true,
+    }, children);
+}
+/** The payment widget or pricing table in your page. */
+export const RailbedCheckout = forwardRef(function RailbedCheckout(props, ref) {
+    return useRailbedElement('railbed-checkout', props, ref, 'Open the checkout');
+});
+/** A buy button that opens the checkout over your page (a full-screen sheet on phones). */
+export const RailbedButton = forwardRef(function RailbedButton(props, ref) {
+    return useRailbedElement('railbed-button', props, ref, props.label || (props.checkout ? 'Buy now' : 'Pay now'));
+});

package/dist/vue.d.ts

@@ -0,0 +1,146 @@
+import { type PropType, type SlotsType, type VNodeChild } from 'vue';
+import { type CreateSession, type RailbedEvent, type RailbedEventDetail } from './index.js';
+export type { CreateSession, OpenResult, RailbedEvent, RailbedEventDetail, RailbedEventName, RailbedStep, SessionAnswer, SessionRequest, } from './index.js';
+export { DEFAULT_ORIGIN, loadRailbed, openCheckout } from './index.js';
+type Handler = (detail: RailbedEventDetail, event: RailbedEvent) => true;
+type Slots = SlotsType<{
+    default?: () => VNodeChild;
+}>;
+/** The payment widget or pricing table in your page. */
+export declare const RailbedCheckout: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /** The checkout's slug, from its Share tab. */
+    readonly checkout: StringConstructor;
+    /** A session your server already made (`pay_…`). */
+    readonly session: StringConstructor;
+    /** Your endpoint that makes a session when the buyer presses Continue (POST, same site, JSON). */
+    readonly sessionEndpoint: StringConstructor;
+    /** Makes the session instead of `sessionEndpoint`. */
+    readonly createSession: PropType<CreateSession>;
+    /** Fills in the buyer's email. Sent to the checkout by message, never in a URL. */
+    readonly email: StringConstructor;
+    /** Default https://pay.railbed.io. */
+    readonly origin: {
+        readonly type: StringConstructor;
+        readonly default: "https://pay.railbed.io";
+    };
+    /** For a Content Security Policy that uses nonces. */
+    readonly nonce: StringConstructor;
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    ready: Handler;
+    step: Handler;
+    handoff: Handler;
+    paid: Handler;
+    held: Handler;
+    failed: Handler;
+    expired: Handler;
+    error: Handler;
+    close: Handler;
+    /** embed.js couldn't load (blocked, offline): the plain link is still there. */
+    'load-error': (error: Error) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /** The checkout's slug, from its Share tab. */
+    readonly checkout: StringConstructor;
+    /** A session your server already made (`pay_…`). */
+    readonly session: StringConstructor;
+    /** Your endpoint that makes a session when the buyer presses Continue (POST, same site, JSON). */
+    readonly sessionEndpoint: StringConstructor;
+    /** Makes the session instead of `sessionEndpoint`. */
+    readonly createSession: PropType<CreateSession>;
+    /** Fills in the buyer's email. Sent to the checkout by message, never in a URL. */
+    readonly email: StringConstructor;
+    /** Default https://pay.railbed.io. */
+    readonly origin: {
+        readonly type: StringConstructor;
+        readonly default: "https://pay.railbed.io";
+    };
+    /** For a Content Security Policy that uses nonces. */
+    readonly nonce: StringConstructor;
+}>> & Readonly<{
+    onReady?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onStep?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onHandoff?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onPaid?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onHeld?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onFailed?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onExpired?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onError?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onClose?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    "onLoad-error"?: ((error: Error) => any) | undefined;
+}>, {
+    readonly origin: string;
+}, Slots, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** A buy button that opens the checkout over your page (a full-screen sheet on phones). */
+export declare const RailbedButton: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /** The button's text. Default "Buy now" ("Pay now" for a session alone). */
+    readonly label: StringConstructor;
+    readonly shape: PropType<"pill" | "rounded">;
+    /** The checkout's slug, from its Share tab. */
+    readonly checkout: StringConstructor;
+    /** A session your server already made (`pay_…`). */
+    readonly session: StringConstructor;
+    /** Your endpoint that makes a session when the buyer presses Continue (POST, same site, JSON). */
+    readonly sessionEndpoint: StringConstructor;
+    /** Makes the session instead of `sessionEndpoint`. */
+    readonly createSession: PropType<CreateSession>;
+    /** Fills in the buyer's email. Sent to the checkout by message, never in a URL. */
+    readonly email: StringConstructor;
+    /** Default https://pay.railbed.io. */
+    readonly origin: {
+        readonly type: StringConstructor;
+        readonly default: "https://pay.railbed.io";
+    };
+    /** For a Content Security Policy that uses nonces. */
+    readonly nonce: StringConstructor;
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    ready: Handler;
+    step: Handler;
+    handoff: Handler;
+    paid: Handler;
+    held: Handler;
+    failed: Handler;
+    expired: Handler;
+    error: Handler;
+    close: Handler;
+    /** embed.js couldn't load (blocked, offline): the plain link is still there. */
+    'load-error': (error: Error) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /** The button's text. Default "Buy now" ("Pay now" for a session alone). */
+    readonly label: StringConstructor;
+    readonly shape: PropType<"pill" | "rounded">;
+    /** The checkout's slug, from its Share tab. */
+    readonly checkout: StringConstructor;
+    /** A session your server already made (`pay_…`). */
+    readonly session: StringConstructor;
+    /** Your endpoint that makes a session when the buyer presses Continue (POST, same site, JSON). */
+    readonly sessionEndpoint: StringConstructor;
+    /** Makes the session instead of `sessionEndpoint`. */
+    readonly createSession: PropType<CreateSession>;
+    /** Fills in the buyer's email. Sent to the checkout by message, never in a URL. */
+    readonly email: StringConstructor;
+    /** Default https://pay.railbed.io. */
+    readonly origin: {
+        readonly type: StringConstructor;
+        readonly default: "https://pay.railbed.io";
+    };
+    /** For a Content Security Policy that uses nonces. */
+    readonly nonce: StringConstructor;
+}>> & Readonly<{
+    onReady?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onStep?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onHandoff?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onPaid?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onHeld?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onFailed?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onExpired?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onError?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    onClose?: ((detail: RailbedEventDetail, event: RailbedEvent) => any) | undefined;
+    "onLoad-error"?: ((error: Error) => any) | undefined;
+}>, {
+    readonly origin: string;
+}, Slots, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** The event names, for anyone wiring listeners by hand. */
+export declare const EVENTS: readonly ["ready", "step", "handoff", "paid", "held", "failed", "expired", "error", "close"];

package/dist/vue.js

@@ -0,0 +1,98 @@
+// Vue 3 components for Railbed's embedded checkout: <RailbedCheckout> (the payment widget or pricing table in the page)
+// and <RailbedButton> (a buy button that opens it over the page). Same props as the React components; events are
+// emitted as `ready`, `step`, `handoff`, `paid`, `held`, `failed`, `expired`, `error`, `close` with (detail, event).
+// class and style fall through to the element, so the --railbed-* variables work from either.
+// Reference: https://railbed.com/docs/guides/embedded-checkout/
+import { defineComponent, h, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { DEFAULT_ORIGIN, elementAttributes, fallbackHref, listen, loadRailbed, railbedOrigin, RAILBED_EVENTS, } from './index.js';
+export { DEFAULT_ORIGIN, loadRailbed, openCheckout } from './index.js';
+const props = {
+    /** The checkout's slug, from its Share tab. */
+    checkout: String,
+    /** A session your server already made (`pay_…`). */
+    session: String,
+    /** Your endpoint that makes a session when the buyer presses Continue (POST, same site, JSON). */
+    sessionEndpoint: String,
+    /** Makes the session instead of `sessionEndpoint`. */
+    createSession: Function,
+    /** Fills in the buyer's email. Sent to the checkout by message, never in a URL. */
+    email: String,
+    /** Default https://pay.railbed.io. */
+    origin: { type: String, default: DEFAULT_ORIGIN },
+    /** For a Content Security Policy that uses nonces. */
+    nonce: String,
+};
+const buttonProps = {
+    ...props,
+    /** The button's text. Default "Buy now" ("Pay now" for a session alone). */
+    label: String,
+    shape: String,
+};
+const emits = {
+    ready: (() => true),
+    step: (() => true),
+    handoff: (() => true),
+    paid: (() => true),
+    held: (() => true),
+    failed: (() => true),
+    expired: (() => true),
+    error: (() => true),
+    close: (() => true),
+    /** embed.js couldn't load (blocked, offline): the plain link is still there. */
+    'load-error': ((_error) => true),
+};
+/** The shared part of both components: load embed.js, forward events, keep createSession on the element, render. */
+function useRailbed(tag, p, emit, slots, words) {
+    const el = ref(null);
+    let off = null;
+    let live = true;
+    const load = () => loadRailbed({ origin: p.origin, nonce: p.nonce }).catch((err) => {
+        if (live)
+            emit('load-error', err);
+    });
+    // One stable function while a createSession prop is given; it calls whatever the prop is when the buyer continues.
+    const hook = () => {
+        if (!el.value)
+            return;
+        el.value.createSession = typeof p.createSession === 'function' ? (request) => p.createSession(request) : null;
+    };
+    onMounted(() => {
+        if (el.value)
+            off = listen(el.value, (name, event) => emit(name, event.detail, event));
+        hook();
+        load();
+    });
+    watch(() => typeof p.createSession === 'function', hook);
+    watch(() => p.origin, load);
+    onBeforeUnmount(() => {
+        live = false;
+        off?.();
+    });
+    return () => {
+        const href = fallbackHref(railbedOrigin(p.origin), p.checkout, p.session);
+        const inside = slots.default ? slots.default() : href ? h('a', { href }, words()) : null;
+        return h(tag, { ...elementAttributes(p), ref: el }, inside ?? undefined);
+    };
+}
+/** The payment widget or pricing table in your page. */
+export const RailbedCheckout = defineComponent({
+    name: 'RailbedCheckout',
+    props,
+    emits,
+    slots: Object,
+    setup(p, { emit, slots }) {
+        return useRailbed('railbed-checkout', p, emit, slots, () => 'Open the checkout');
+    },
+});
+/** A buy button that opens the checkout over your page (a full-screen sheet on phones). */
+export const RailbedButton = defineComponent({
+    name: 'RailbedButton',
+    props: buttonProps,
+    emits,
+    slots: Object,
+    setup(p, { emit, slots }) {
+        return useRailbed('railbed-button', p, emit, slots, () => p.label || (p.checkout ? 'Buy now' : 'Pay now'));
+    },
+});
+/** The event names, for anyone wiring listeners by hand. */
+export const EVENTS = RAILBED_EVENTS;

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@railbed/embed",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Railbed's embedded checkout for React, Vue and any page: the payment widget, pricing table and buy button, with typed events.",
+  "license": "MIT",
+  "homepage": "https://railbed.com/docs/guides/embedded-checkout/",
+  "keywords": [
+    "railbed",
+    "checkout",
+    "payments",
+    "embed",
+    "react",
+    "vue"
+  ],
+  "author": {
+    "name": "Railbed by MediaGlobe",
+    "email": "support@railbed.com",
+    "url": "https://railbed.com"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js",
+      "default": "./dist/vue.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "react": [
+        "dist/react.d.ts"
+      ],
+      "vue": [
+        "dist/vue.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "vue": ">=3.3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "jsdom": "^27.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.12",
+    "vue": "^3.5.0"
+  }
+}