@getruba/checkout 0.3.0

package/README.md

@@ -0,0 +1,221 @@
+# `@getruba/checkout`
+
+JavaScript utilities for embedding Ruba into your website. Drop in the single CDN script (auto-init) or import per-feature from npm for tree-shaking.
+
+## Payment Method
+
+A customer session token authenticates every embed. Create it **on your server** — your Ruba access token must stay secret — then hand the token to the browser. The SDK accepts either a `ruba_cst_*` or `ruba_mst_*` prefix and routes internally.
+
+### Javascript
+
+#### Modal
+
+A full-screen overlay the SDK creates and tears down for you — open it on demand, e.g. from a button click.
+
+```ts
+import { Ruba } from '@getruba/sdk'
+import { RubaEmbedPaymentMethod } from '@getruba/checkout/payment-method'
+
+const ruba = new Ruba({ accessToken: process.env.RUBA_ACCESS_TOKEN })
+const session = await ruba.customerSessions.create({
+  customerId: 'ABC-123',
+})
+
+const embed = await RubaEmbedPaymentMethod.create({
+  sessionToken: session.token,
+})
+
+embed.addEventListener('success', (event) => {
+  console.log('Attached:', event.detail.paymentMethodId)
+})
+```
+
+#### `create()` options
+
+| Option         | Type                           | Default     | Description                                                                                                                                                           |
+| -------------- | ------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sessionToken` | `string`                       | —           | **Required.** Session token from `POST /v1/customer-sessions` (`ruba_cst_*` or `ruba_mst_*`).                                                                         |
+| `theme`        | `'light' \| 'dark'`            | `light`     | Colour scheme for the embed.                                                                                                                                          |
+| `setAsDefault` | `boolean`                      | `true`      | Whether the new card should become the customer's default payment method.                                                                                             |
+| `returnUrl`    | `string`                       | current URL | Where to return the customer after a redirect-based payment method (Amazon Pay etc). Defaults to `window.location.href`. See [Redirect re-entry](#redirect-re-entry). |
+| `locale`       | `string`                       | `'en'`      | BCP47 locale for the embed UI and Stripe Elements (e.g. `'en'`, `'fr-FR'`). Unsupported locales fall back to English.                                                 |
+| `onLoaded`     | `(event: CustomEvent) => void` | —           | Convenience callback for the `loaded` event. Equivalent to `embed.addEventListener('loaded', …)`.                                                                     |
+
+#### Inline
+
+A chrome-less, auto-resizing iframe mounted into an element you control — compose it into your own layout.
+
+```ts
+import { Ruba } from '@getruba/sdk'
+import { RubaEmbedPaymentMethod } from '@getruba/checkout/payment-method'
+
+const ruba = new Ruba({ accessToken: process.env.RUBA_ACCESS_TOKEN })
+const session = await ruba.customerSessions.create({
+  customerId: 'ABC-123',
+})
+
+const embed = RubaEmbedPaymentMethod.createInline({
+  sessionToken: session.token,
+  element: document.getElementById('ruba-payment-method')!,
+})
+
+embed.addEventListener('success', (event) => {
+  console.log('Attached:', event.detail.paymentMethodId)
+})
+```
+
+#### `createInline()` options
+
+| Option         | Type                           | Default | Description                                                                                       |
+| -------------- | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
+| `sessionToken` | `string`                       | —       | **Required.** Session token from `POST /v1/customer-sessions` (`ruba_cst_*` or `ruba_mst_*`).     |
+| `element`      | `HTMLElement`                  | —       | **Required.** The element to mount the embed into. Any existing children are replaced.            |
+| `theme`        | `'light' \| 'dark'`            | `light` | Colour scheme for the embed.                                                                      |
+| `setAsDefault` | `boolean`                      | `true`  | Whether the new card should become the customer's default payment method.                         |
+| `locale`       | `string`                       | `'en'`  | BCP47 locale for the embed UI and Stripe Elements. Unsupported locales fall back to English.      |
+| `onLoaded`     | `(event: CustomEvent) => void` | —       | Convenience callback for the `loaded` event. Equivalent to `embed.addEventListener('loaded', …)`. |
+
+#### Events
+
+All events are dispatched as cancelable `CustomEvent`s on the `embed` instance. Call `event.preventDefault()` to opt out of the SDK's default action.
+
+| Event       | Detail                        | Default action                                                        |
+| ----------- | ----------------------------- | --------------------------------------------------------------------- |
+| `loaded`    | —                             | Removes the loader spinner once the iframe is ready.                  |
+| `close`     | —                             | Tears down the iframe (unless locked by a pending `confirmed`).       |
+| `confirmed` | —                             | Marks the modal as non-closable while Stripe is processing.           |
+| `success`   | `{ paymentMethodId: string }` | **Auto-closes the modal.** Call `preventDefault()` to keep it open.   |
+| `error`     | `{ code: ErrorCode }`         | None. `ErrorCode = 'invalid_request' \| 'unauthorized' \| 'unknown'`. |
+
+#### Instance methods
+
+| Method                                      | Description                                             |
+| ------------------------------------------- | ------------------------------------------------------- |
+| `embed.close()`                             | Programmatically close the modal and remove the iframe. |
+| `embed.addEventListener(type, listener)`    | Subscribe to an event. Returns `void`.                  |
+| `embed.removeEventListener(type, listener)` | Unsubscribe.                                            |
+
+#### Redirect re-entry
+
+Redirect-based payment methods (Amazon Pay etc, etc) authorise on the provider's own site — the browser navigates the whole tab away and back to `returnUrl` (defaults to the page the SDK was opened from), so the modal can't survive the round-trip. Read the outcome on the returned page with the static `getRedirectResult()`:
+
+```ts
+const result = RubaEmbedPaymentMethod.getRedirectResult()
+// result: { status: 'succeeded' | 'failed' } | null
+
+if (result?.status === 'succeeded') {
+  // refresh the customer's payment methods
+}
+```
+
+It strips the status param from the URL so a refresh won't resurface a stale result. Card payments (3DS) complete inside the modal and never trigger this path.
+
+### React
+
+#### Modal
+
+Open the full-screen modal with `RubaEmbedPaymentMethod.create()` — the same API as vanilla JS, called from a Client Component event handler.
+
+```tsx
+import { RubaEmbedPaymentMethod } from '@getruba/checkout/payment-method'
+
+export function AddPaymentMethodButton({
+  sessionToken,
+}: {
+  sessionToken: string
+}) {
+  const openEmbed = async () => {
+    const embed = await RubaEmbedPaymentMethod.create({ sessionToken })
+    embed.addEventListener('success', (event) => {
+      console.log('Attached:', event.detail.paymentMethodId)
+    })
+  }
+
+  return <button onClick={openEmbed}>Add payment method</button>
+}
+```
+
+#### Inline
+
+Render `<RubaPaymentMethod />` for a chrome-less, auto-resizing embed inside your own layout.
+
+```tsx
+import { Ruba } from '@getruba/sdk'
+import { RubaPaymentMethod } from '@getruba/checkout/react/payment-method'
+
+const ruba = new Ruba({ accessToken: process.env.RUBA_ACCESS_TOKEN })
+const session = await ruba.customerSessions.create({
+  customerId: 'ABC-123',
+})
+
+return (
+  <RubaPaymentMethod
+    sessionToken={session.token}
+    onSuccess={(id) => console.log('Attached:', id)}
+  />
+)
+```
+
+#### Props
+
+| Prop           | Type                                | Default | Description                                                                       |
+| -------------- | ----------------------------------- | ------- | --------------------------------------------------------------------------------- |
+| `sessionToken` | `string`                            | —       | **Required.** Session token from `POST /v1/customer-sessions`.                    |
+| `theme`        | `'light' \| 'dark'`                 | `light` | Colour scheme.                                                                    |
+| `setAsDefault` | `boolean`                           | `true`  | Whether the new card should become the customer's default payment method.         |
+| `locale`       | `string`                            | `'en'`  | BCP47 locale (e.g. `'en'`, `'fr-FR'`). Unsupported locales fall back to English.  |
+| `onLoaded`     | `() => void`                        | —       | Fires once when the iframe finishes loading and the form becomes interactive.     |
+| `onConfirmed`  | `() => void`                        | —       | Fires when the customer submits and Stripe processing starts.                     |
+| `onSuccess`    | `(paymentMethodId: string) => void` | —       | Fires after the card has been attached to the customer.                           |
+| `onError`      | `(code: ErrorCode) => void`         | —       | Fires when the iframe can't render (token missing/expired). `ErrorCode` as above. |
+| `className`    | `string`                            | —       | Applied to the wrapping `<div>`. Use it to size or position the embed.            |
+| `style`        | `React.CSSProperties`               | —       | Inline style on the wrapping `<div>`.                                             |
+
+#### Redirect re-entry
+
+Redirect-based payment methods (Amazon Pay etc etc.) navigate the whole tab away to the provider and back. Read the outcome on the returned page with the `usePaymentMethodRedirectResult` hook:
+
+```tsx
+import { usePaymentMethodRedirectResult } from '@getruba/checkout/react/payment-method'
+
+usePaymentMethodRedirectResult({
+  onSuccess: () => toast('Payment method added'),
+  onError: () => toast('Could not add payment method'),
+})
+```
+
+It reads the result once on mount and strips the status param from the URL. Card payments (3DS) complete inside the embed and never trigger this path.
+
+### Code snippet
+
+```ts
+import { Ruba } from '@getruba/sdk'
+
+const ruba = new Ruba({ accessToken: process.env.RUBA_ACCESS_TOKEN })
+const session = await ruba.customerSessions.create({
+  customerId: 'ABC-123',
+})
+```
+
+```html
+<script
+  defer
+  data-auto-init
+  src="https://cdn.jsdelivr.net/npm/@getruba/checkout@latest/dist/embed.global.js"
+></script>
+
+<!-- session.token rendered into the attribute server-side -->
+<button data-ruba-payment-method="ruba_cst_…">Add payment method</button>
+```
+
+The same script also powers `RubaEmbedCheckout` triggers — one tag covers every Ruba embed.
+
+#### Attributes
+
+| Attribute                                 | Value           | Description                                                                                        |
+| ----------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------- |
+| `data-ruba-payment-method`                | `string`        | **Required.** The session token. Clicking the element opens the modal.                             |
+| `data-ruba-payment-method-theme`          | `light \| dark` | Optional theme override.                                                                           |
+| `data-ruba-payment-method-set-as-default` | `true \| false` | Optional. Default `true`. Passing `"false"` adds the card without overriding the existing default. |
+| `data-ruba-payment-method-return-url`     | `string`        | Optional. Return URL for redirect-based payment methods. Defaults to the current page.             |
+| `data-ruba-payment-method-locale`         | `string`        | Optional. BCP47 locale (e.g. `'en'`, `'fr-FR'`). Unsupported locales fall back to English.         |

package/dist/chunk-FSZEYAE6.js

@@ -0,0 +1 @@
+var e="RUBA_PAYMENT_METHOD",t="/embed/payment-method",n="ruba_payment_method_status",a=()=>{const e="http://127.0.0.1:3000".split(",");return"undefined"!=typeof window&&e.includes(window.location.origin)?window.location.origin:e[0]},s=()=>{const e="http://127.0.0.1:3000".split(",").join(" ");return`payment 'self' ${e}; publickey-credentials-get 'self' ${e};`},o=class o{iframe;mode;loader;loaded;closable;eventTarget;windowMessageListener;constructor(e,t,n){this.iframe=e,this.mode=t,this.loader=n,this.loaded=!1,this.closable=!0,this.eventTarget=new EventTarget,this.windowMessageListener=this.handleWindowMessage.bind(this),window.addEventListener("message",this.windowMessageListener)}static postMessage(t,n){window.parent.postMessage({...t,type:e},n)}static create(e){const{sessionToken:n,theme:r,setAsDefault:i,returnUrl:d,locale:l,onLoaded:c}=e,h=document.createElement("style");h.innerText=`\n      .ruba-loader-spinner {\n        width: 20px;\n        aspect-ratio: 1;\n        border-radius: 50%;\n        background: ${"dark"===r?"#000":"#fff"};\n        box-shadow: 0 0 0 0 ${"dark"===r?"#fff":"#000"};\n        animation: ruba-loader-spinner-animation 1s infinite;\n      }\n      @keyframes ruba-loader-spinner-animation {\n        100% {box-shadow: 0 0 0 30px #0000}\n      }\n      body.ruba-no-scroll {\n        overflow: hidden;\n      }\n    `,document.head.appendChild(h);const m=document.createElement("div");m.style.position="absolute",m.style.top="50%",m.style.left="50%",m.style.transform="translate(-50%, -50%)",m.style.zIndex="2147483647",m.style.colorScheme="auto";const u=document.createElement("div");u.className="ruba-loader-spinner",m.appendChild(u),document.body.classList.add("ruba-no-scroll"),document.body.appendChild(m);const b=new URL(t,a());b.searchParams.set("session_token",n),b.searchParams.set("embed","true"),b.searchParams.set("embed_origin",window.location.origin),b.searchParams.set("mode","modal"),b.searchParams.set("embed_return_url",d??window.location.href),r&&b.searchParams.set("theme",r),!1===i&&b.searchParams.set("set_default","false"),l&&b.searchParams.set("locale",l);const w=document.createElement("iframe");w.src=b.toString(),w.style.position="fixed",w.style.top="0",w.style.left="0",w.style.width="100%",w.style.height="100%",w.style.border="none",w.style.zIndex="2147483647",w.style.backgroundColor="rgba(0, 0, 0, 0.5)",w.style.colorScheme="auto",w.allow=s(),document.body.appendChild(w);const f=new o(w,"modal",m);return c&&f.addEventListener("loaded",c,{once:!0}),new Promise(e=>{f.addEventListener("loaded",()=>e(f),{once:!0})})}static createInline(e){const{sessionToken:n,element:r,theme:i,setAsDefault:d,locale:l,onLoaded:c}=e,h=new URL(t,a());h.searchParams.set("session_token",n),h.searchParams.set("embed","true"),h.searchParams.set("embed_origin",window.location.origin),h.searchParams.set("mode","inline"),i&&h.searchParams.set("theme",i),!1===d&&h.searchParams.set("set_default","false"),l&&h.searchParams.set("locale",l);const m=document.createElement("iframe");m.src=h.toString(),m.style.display="block",m.style.width="100%",m.style.height="0",m.style.border="none",m.style.colorScheme="auto",m.allow=s(),r.replaceChildren(m);const u=new o(m,"inline",null);return c&&u.addEventListener("loaded",c,{once:!0}),u}static init(){document.querySelectorAll("[data-ruba-payment-method]").forEach(e=>{e.removeEventListener("click",o.elementClickHandler),e.addEventListener("click",o.elementClickHandler)})}static getRedirectResult(){if("undefined"==typeof window)return null;const e=new URLSearchParams(window.location.search),t=e.get(n);if("succeeded"!==t&&"failed"!==t)return null;e.delete(n);const a=e.toString();return window.history.replaceState({},"",`${window.location.pathname}${a?`?${a}`:""}${window.location.hash}`),{status:t}}close(){window.removeEventListener("message",this.windowMessageListener),this.iframe.remove(),"modal"===this.mode&&document.body.classList.remove("ruba-no-scroll")}addEventListener(e,t,n){this.eventTarget.addEventListener(e,t,n)}removeEventListener(e,t){this.eventTarget.removeEventListener(e,t)}static async elementClickHandler(e){e.preventDefault();let t=e.target;for(;!t.hasAttribute("data-ruba-payment-method");){if(!t.parentElement)return;t=t.parentElement}const n=t.getAttribute("data-ruba-payment-method");if(!n)return;const a=t.getAttribute("data-ruba-payment-method-theme"),s=t.getAttribute("data-ruba-payment-method-set-as-default"),r=t.getAttribute("data-ruba-payment-method-return-url"),i=t.getAttribute("data-ruba-payment-method-locale");o.create({sessionToken:n,theme:a??void 0,setAsDefault:null===s?void 0:"false"!==s,returnUrl:r??void 0,locale:i??void 0})}handleLoaded(){this.loaded||(this.loader&&document.body.contains(this.loader)&&document.body.removeChild(this.loader),this.loaded=!0)}handleClose(){this.closable&&this.close()}handleConfirmed(){this.closable=!1}handleSuccess(){"inline"!==this.mode&&(this.closable=!0,this.close())}handleError(){this.closable=!0}handleWindowMessage({data:t,origin:n}){if(!"http://127.0.0.1:3000".split(",").includes(n))return;if(t.type!==e)return;if("resize"===t.event)return void("inline"===this.mode&&(this.iframe.style.height=`${Math.max(0,Math.ceil(t.height))}px`));const a=new CustomEvent(t.event,{detail:t,cancelable:!0});if(this.eventTarget.dispatchEvent(a),!a.defaultPrevented)switch(t.event){case"loaded":this.handleLoaded();break;case"close":this.handleClose();break;case"confirmed":this.handleConfirmed();break;case"success":this.handleSuccess();break;case"error":this.handleError()}}};if("undefined"!=typeof window&&(window.Ruba={...window.Ruba??{},EmbedPaymentMethod:o}),"undefined"!=typeof document){const e=document.currentScript;e&&e.hasAttribute("data-auto-init")&&document.addEventListener("DOMContentLoaded",()=>{o.init()})}export{n as REDIRECT_STATUS_PARAM,o as EmbedPaymentMethod};

package/dist/chunk-GBQE5XCD.js

@@ -0,0 +1 @@
+var i=r=>r.product!==null&&r.prices!==null,t=r=>r.type==="recurring",u=r=>{if(!r.product||!r.prices)return null;let e=r.prices[r.product.id];return e?e.filter(c=>c.price_currency===r.currency).find(c=>c.amount_type==="seat_based")??null:null},s=r=>{if(!r.product||!r.prices)return null;let e=r.prices[r.product.id];return e?e.filter(c=>c.price_currency===r.currency).find(c=>c.amount_type==="fixed")??null:null};export{i as a,t as b,u as c,s as d};