@orqex/checkout-js 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Axa Zara LLC
+
+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,73 @@
+# @orqex/checkout-js
+
+Client-side SDK to integrate Orqex payments on your own site.
+
+## Install
+
+```bash
+npm i @orqex/checkout-js
+```
+
+Or via CDN (UMD global `Orqex`):
+
+```html
+<script src="https://cdn.orqex.com/checkout-js/orqex.global.js"></script>
+```
+
+## Usage
+
+Your server mints a checkout with your secret key and returns its `public_id`
+(via `@orqex/node` or `orchestrate-php`). In the browser:
+
+```js
+import { Orqex } from '@orqex/checkout-js';
+
+const orqex = Orqex('pk_live_…'); // publishable key from the Orqex admin
+
+// Embedded — hosted checkout in a sandboxed iframe (PCI stays with Orqex).
+orqex.mount('#checkout', { publicId });
+
+// Redirect — full-page navigation to the hosted checkout.
+orqex.redirectToCheckout({ publicId });
+
+// Lifecycle events (embedded mode):
+orqex.on('success', ({ status }) => {/* … */});
+orqex.on('error', ({ code, message }) => {/* … */});
+orqex.on('redirect', ({ url }) => {/* the SDK also navigates top-level */});
+orqex.on('close', ({ status }) => {/* … */});
+```
+
+`Orqex(pk, { checkoutBaseUrl })` overrides the hosted-checkout origin (staging
+or self-hosted).
+
+## Security
+
+- Only a publishable key (`pk_…`) is accepted; never pass a secret key.
+- The embedded iframe is `sandbox`ed and only trusts messages from the hosted
+  origin. Your site's origin must be authorised to embed your project.
+
+## Headless
+
+Run the engine in your own page and render your own UI from the `CheckoutView`:
+
+```js
+const orqex = Orqex('pk_live_…', { apiBaseUrl: 'https://api.orqex.com' });
+const checkout = orqex.createEngine({ publicId });
+
+checkout.subscribe((view) => renderYourUI(view)); // view.kind: loading|form|processing|action|succeeded|failed|closed
+await checkout.pay({ /* PayInput */ });
+```
+
+Headless is for PAN-free methods (mobile money, redirect, OTP, phone-approval, QR). Raw card entry is not supported here — that is hosted (embedded/redirect) or a future hosted-fields component.
+
+**Redirects.** When `view` is a redirect action, call `checkout.performRedirect()` (or navigate yourself). On return, re-create the engine and call `checkout.resumeFromRedirect()`. Or pass `autoResume: true` and the SDK persists `publicId` and resumes automatically:
+
+```js
+const checkout = orqex.createEngine({ publicId, autoResume: true });
+```
+
+`autoResume` uses `sessionStorage` and page-lifecycle events; leave it off if you manage routing yourself (SPA).
+
+## Roadmap
+
+- **Hosted card fields** — Phase 3, gated on demand.

package/dist/chunk-4Q2JETLA.js

@@ -0,0 +1,37 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/protocol.ts
+var ORQEX_PROTOCOL_VERSION = 1;
+var KNOWN_TYPES = ["ready", "resize", "success", "error", "redirect", "close"];
+function isEmbedMessage(data) {
+  if (data === null || typeof data !== "object") return false;
+  const record = data;
+  return record.__orqex === true && record.v === ORQEX_PROTOCOL_VERSION && typeof record.type === "string" && KNOWN_TYPES.includes(record.type);
+}
+function base(type) {
+  return { __orqex: true, v: ORQEX_PROTOCOL_VERSION, type };
+}
+function readyMessage() {
+  return base("ready");
+}
+function resizeMessage(height) {
+  return { ...base("resize"), height };
+}
+function successMessage(status) {
+  return { ...base("success"), status };
+}
+function errorMessage(code, message) {
+  return { ...base("error"), code, message };
+}
+function redirectMessage(url) {
+  return { ...base("redirect"), url };
+}
+function closeMessage(status) {
+  return { ...base("close"), status };
+}
+
+export { ORQEX_PROTOCOL_VERSION, __publicField, closeMessage, errorMessage, isEmbedMessage, readyMessage, redirectMessage, resizeMessage, successMessage };
+//# sourceMappingURL=chunk-4Q2JETLA.js.map
+//# sourceMappingURL=chunk-4Q2JETLA.js.map

package/dist/chunk-4Q2JETLA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol.ts"],"names":[],"mappings":";;;;;AASO,IAAM,sBAAA,GAAyB;AAqCtC,IAAM,cAA+C,CAAC,OAAA,EAAS,UAAU,SAAA,EAAW,OAAA,EAAS,YAAY,OAAO,CAAA;AAGzG,SAAS,eAAe,IAAA,EAAqC;AAClE,EAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,OAAO,IAAA,KAAS,UAAU,OAAO,KAAA;AACtD,EAAA,MAAM,MAAA,GAAS,IAAA;AACf,EAAA,OACE,MAAA,CAAO,OAAA,KAAY,IAAA,IACnB,MAAA,CAAO,CAAA,KAAM,sBAAA,IACb,OAAO,MAAA,CAAO,IAAA,KAAS,QAAA,IACvB,WAAA,CAAY,QAAA,CAAS,OAAO,IAAwB,CAAA;AAExD;AAEA,SAAS,KAAiC,IAAA,EAAkB;AAE1D,EAAA,OAAO,EAAE,OAAA,EAAS,IAAA,EAAM,CAAA,EAAG,wBAAwB,IAAA,EAAK;AAC1D;AAEO,SAAS,YAAA,GAA6B;AAC3C,EAAA,OAAO,KAAK,OAAO,CAAA;AACrB;AACO,SAAS,cAAc,MAAA,EAA+B;AAC3D,EAAA,OAAO,EAAE,GAAG,IAAA,CAAK,QAAQ,GAAG,MAAA,EAAO;AACrC;AACO,SAAS,eAAe,MAAA,EAAgC;AAC7D,EAAA,OAAO,EAAE,GAAG,IAAA,CAAK,SAAS,GAAG,MAAA,EAAO;AACtC;AACO,SAAS,YAAA,CAAa,MAAc,OAAA,EAA+B;AACxE,EAAA,OAAO,EAAE,GAAG,IAAA,CAAK,OAAO,CAAA,EAAG,MAAM,OAAA,EAAQ;AAC3C;AACO,SAAS,gBAAgB,GAAA,EAA8B;AAC5D,EAAA,OAAO,EAAE,GAAG,IAAA,CAAK,UAAU,GAAG,GAAA,EAAI;AACpC;AACO,SAAS,aAAa,MAAA,EAA8B;AACzD,EAAA,OAAO,EAAE,GAAG,IAAA,CAAK,OAAO,GAAG,MAAA,EAAO;AACpC","file":"chunk-4Q2JETLA.js","sourcesContent":["/**\n * The embed postMessage protocol: the wire contract between the hosted checkout\n * (inside a sandboxed iframe) and the SDK running in the merchant's top window.\n *\n * Every message carries `__orqex: true` and `v` (version) so each side can\n * reject foreign or mis-versioned traffic. This module is the single source of\n * truth: `checkout-next` imports it to emit, `checkout-js` imports it to receive.\n */\n\nexport const ORQEX_PROTOCOL_VERSION = 1;\n\nexport type EmbedMessageType = 'ready' | 'resize' | 'success' | 'error' | 'redirect' | 'close';\n\ninterface Base<T extends EmbedMessageType> {\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  __orqex: true;\n  v: number;\n  type: T;\n}\n\nexport type ReadyMessage = Base<'ready'>;\nexport interface ResizeMessage extends Base<'resize'> {\n  height: number;\n}\nexport interface SuccessMessage extends Base<'success'> {\n  status: string;\n}\nexport interface ErrorMessage extends Base<'error'> {\n  code: string;\n  message: string;\n}\nexport interface RedirectMessage extends Base<'redirect'> {\n  url: string;\n}\nexport interface CloseMessage extends Base<'close'> {\n  status: string;\n}\n\nexport type EmbedMessage =\n  | ReadyMessage\n  | ResizeMessage\n  | SuccessMessage\n  | ErrorMessage\n  | RedirectMessage\n  | CloseMessage;\n\nconst KNOWN_TYPES: ReadonlyArray<EmbedMessageType> = ['ready', 'resize', 'success', 'error', 'redirect', 'close'];\n\n/** Structural + version guard for messages arriving over postMessage. */\nexport function isEmbedMessage(data: unknown): data is EmbedMessage {\n  if (data === null || typeof data !== 'object') return false;\n  const record = data as Record<string, unknown>;\n  return (\n    record.__orqex === true &&\n    record.v === ORQEX_PROTOCOL_VERSION &&\n    typeof record.type === 'string' &&\n    KNOWN_TYPES.includes(record.type as EmbedMessageType)\n  );\n}\n\nfunction base<T extends EmbedMessageType>(type: T): Base<T> {\n  // eslint-disable-next-line @typescript-eslint/naming-convention, id-length\n  return { __orqex: true, v: ORQEX_PROTOCOL_VERSION, type };\n}\n\nexport function readyMessage(): ReadyMessage {\n  return base('ready');\n}\nexport function resizeMessage(height: number): ResizeMessage {\n  return { ...base('resize'), height };\n}\nexport function successMessage(status: string): SuccessMessage {\n  return { ...base('success'), status };\n}\nexport function errorMessage(code: string, message: string): ErrorMessage {\n  return { ...base('error'), code, message };\n}\nexport function redirectMessage(url: string): RedirectMessage {\n  return { ...base('redirect'), url };\n}\nexport function closeMessage(status: string): CloseMessage {\n  return { ...base('close'), status };\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import { CheckoutView, PayInput, AuthorizeInput, CountrySimplified } from '@orqex/checkout-engine';
+export { AuthorizeInput, CheckoutView, CountrySimplified, PayInput } from '@orqex/checkout-engine';
+import { EmbedMessage } from './protocol.js';
+export { CloseMessage, EmbedMessageType, ErrorMessage, ORQEX_PROTOCOL_VERSION, ReadyMessage, RedirectMessage, ResizeMessage, SuccessMessage, closeMessage, errorMessage, isEmbedMessage, readyMessage, redirectMessage, resizeMessage, successMessage } from './protocol.js';
+
+interface OrqexOptions {
+    /** Override the hosted-checkout origin (e.g. a staging or self-hosted deploy). */
+    checkoutBaseUrl?: string;
+    /** Override the API origin the headless engine calls (e.g. staging). */
+    apiBaseUrl?: string;
+}
+
+/** Merchant-facing lifecycle events for embedded/redirect modes. */
+type MerchantEvent = 'success' | 'error' | 'redirect' | 'close';
+interface EventPayloads {
+    success: {
+        status: string;
+    };
+    error: {
+        code: string;
+        message: string;
+    };
+    redirect: {
+        url: string;
+    };
+    close: {
+        status: string;
+    };
+}
+
+interface MountOptions {
+    publicId: string;
+}
+
+interface CreateEngineOptions {
+    /** cs_… checkout handle minted server-side by the merchant. */
+    publicId: string;
+    /** BCP-47 locale for Accept-Language. Default navigator.language. */
+    locale?: string;
+    /**
+     * When true, the SDK persists publicId across a redirect and auto-resumes on
+     * return, and auto-performs redirect actions. Default false (fully manual).
+     */
+    autoResume?: boolean;
+}
+/** Narrowed, browser-facing surface over CheckoutEngine. Cross-SDK contract. */
+interface OrqexCheckout {
+    subscribe(fn: (view: CheckoutView) => void): () => void;
+    getView(): CheckoutView;
+    pay(input: PayInput): Promise<void>;
+    authorize(input: AuthorizeInput): Promise<void>;
+    poll(): Promise<void>;
+    selectCountry(country: string): Promise<void>;
+    selectCurrency(currency: string): Promise<void>;
+    listCountries(): Promise<CountrySimplified[]>;
+    /** Poll the current server state (call on return from an external redirect). */
+    resumeFromRedirect(): Promise<void>;
+    startPolling(): void;
+    stopPolling(): void;
+    /** Perform the pending redirect action; no-op if the current view is not one. */
+    performRedirect(): void;
+    destroy(): void;
+}
+
+interface RedirectOptions {
+    /** cs_… checkout handle minted server-side by the merchant. */
+    publicId: string;
+}
+
+interface OrqexInstance {
+    /** Embedded mode: hosted checkout in a sandboxed iframe. */
+    mount(target: string | HTMLElement, options: MountOptions): void;
+    /** Redirect mode: full-page navigation to the hosted checkout. */
+    redirectToCheckout(options: RedirectOptions): void;
+    /** Subscribe to a lifecycle event; returns a disposer. */
+    on<TEvent extends MerchantEvent>(event: TEvent, handler: (payload: EventPayloads[TEvent]) => void): () => void;
+    /** Tear down the embedded iframe and its listener (no-op in redirect mode). */
+    unmount(): void;
+    /** Headless mode: run the engine in this page and render your own UI. */
+    createEngine(options: CreateEngineOptions): OrqexCheckout;
+}
+/**
+ * SDK entry point. `Orqex('pk_…')` validates the key, then exposes embedded,
+ * redirect, and headless (`createEngine`) modes over one event bus.
+ */
+declare function Orqex(publishableKey: string, options?: OrqexOptions): OrqexInstance;
+
+interface EmbedProjection {
+    message: EmbedMessage;
+    /** Dedup key so the host posts each terminal state at most once. */
+    key: string;
+}
+/**
+ * Pure mapping from the engine's projected view to an embed lifecycle message.
+ * Terminal views only; `redirect` is handled by the host's redirect override
+ * (a redirect action is not a terminal view). Returns null when there is
+ * nothing new to post or `key` equals `lastKey`.
+ */
+declare function projectEmbedMessage(view: CheckoutView, lastKey: string | null): EmbedProjection | null;
+
+/**
+ * @orqex/checkout-js — client-side SDK for Orqex payments.
+ *
+ * Browser-host glue over the existing engine + hosted checkout. Never accepts a
+ * secret key; the publishable key (pk_) is public by design.
+ */
+declare const SDK_VERSION = "0.0.1";
+
+export { type CreateEngineOptions, EmbedMessage, type EmbedProjection, type EventPayloads, type MerchantEvent, type MountOptions, Orqex, type OrqexCheckout, type OrqexInstance, type OrqexOptions, type RedirectOptions, SDK_VERSION, projectEmbedMessage };