@oleq-ai/pay 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleq
+
+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,56 @@
+# @oleq-ai/pay
+
+Browser SDK for [OleqPay](https://my.olefi.co) hosted checkout — modal iframe or full-page redirect.
+
+Full documentation: [docs.oleq.co](https://docs.oleq.co).
+
+Bugs & issues: [oleq.co/contact](https://oleq.co/contact).
+
+## Install
+
+```bash
+pnpm add @oleq-ai/pay
+```
+
+```bash
+npm install @oleq-ai/pay
+```
+
+## Quick start
+
+```ts
+import { OleqPayCheckout } from '@oleq-ai/pay';
+
+const oleqpay = new OleqPayCheckout({
+  checkoutBaseUrl: 'https://my.olefi.co',
+});
+
+oleqpay.openIframe(
+  {
+    apikey: 'demo_public_key',
+    amount: '1500',
+    orderid: order.id,
+    reference: order.reference,
+    returnurl: location.href,
+  },
+  {
+    onSuccess: (e) => console.log('paid', e.vreference),
+    onError: (e) => console.log('failed', e.message),
+    onClose: () => console.log('closed'),
+  },
+);
+```
+
+Prefer minting the session URL on your server with `buildUrl()`, then hand that URL to `openIframe()` / `redirect()` in the browser.
+
+## Surface
+
+| Entry                | Exports                                               |
+| -------------------- | ----------------------------------------------------- |
+| `@oleq-ai/pay`       | `OleqPayCheckout`, `OleqPayCheckoutError`, types      |
+| `@oleq-ai/pay/react` | `useOleqPayCheckout()`                                |
+| `@oleq-ai/pay/nest`  | `OleqPayCheckoutModule.forRoot()` / `.forRootAsync()` |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,63 @@
+interface CheckoutPayload {
+    apikey: string;
+    amount: string | number;
+    orderid: string | number;
+    reference: string;
+    callbackurl?: string;
+    returnurl?: string;
+}
+type CheckoutEvent = {
+    type: 'oleqpay:ready';
+} | {
+    type: 'oleqpay:success';
+    vreference: string;
+    amount?: string;
+} | {
+    type: 'oleqpay:failed';
+    vreference?: string;
+    message?: string;
+} | {
+    type: 'oleqpay:close';
+};
+type OleqPayCheckoutOptions = {
+    checkoutBaseUrl?: string;
+    locale?: string;
+};
+interface OpenOptions {
+    onSuccess?: (event: Extract<CheckoutEvent, {
+        type: 'oleqpay:success';
+    }>) => void;
+    onError?: (event: Extract<CheckoutEvent, {
+        type: 'oleqpay:failed';
+    }>) => void;
+    onClose?: () => void;
+}
+
+declare class OleqPayCheckout {
+    private readonly checkoutBaseUrl;
+    private readonly locale;
+    private activeModal;
+    private messageHandler;
+    constructor(options?: OleqPayCheckoutOptions);
+    /**
+     * Build a hosted-checkout URL from a payload.
+     * Safe on the server (no DOM) — use this to mint session URLs in Nest/backends.
+     */
+    buildUrl(payload: CheckoutPayload): string;
+    /** Opens checkout in a modal iframe. Accepts either a raw payload or a pre-built session URL. */
+    openIframe(payloadOrUrl: CheckoutPayload | string, options?: OpenOptions): void;
+    /** Full-page redirect to hosted checkout — mirrors Stripe Checkout / Paystack redirect flow. */
+    redirect(payloadOrUrl: CheckoutPayload | string): void;
+    /** Programmatically close an open iframe modal. */
+    close(): void;
+    private resolveUrl;
+    private teardown;
+}
+
+type OleqPayCheckoutErrorCode = 'ssr_unsupported' | 'invalid_api_key' | 'invalid_payload';
+declare class OleqPayCheckoutError extends Error {
+    readonly code: OleqPayCheckoutErrorCode;
+    constructor(message: string, code: OleqPayCheckoutErrorCode);
+}
+
+export { type CheckoutEvent, type CheckoutPayload, OleqPayCheckout, OleqPayCheckoutError, type OleqPayCheckoutErrorCode, type OleqPayCheckoutOptions, type OpenOptions, OleqPayCheckout as default };

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+interface CheckoutPayload {
+    apikey: string;
+    amount: string | number;
+    orderid: string | number;
+    reference: string;
+    callbackurl?: string;
+    returnurl?: string;
+}
+type CheckoutEvent = {
+    type: 'oleqpay:ready';
+} | {
+    type: 'oleqpay:success';
+    vreference: string;
+    amount?: string;
+} | {
+    type: 'oleqpay:failed';
+    vreference?: string;
+    message?: string;
+} | {
+    type: 'oleqpay:close';
+};
+type OleqPayCheckoutOptions = {
+    checkoutBaseUrl?: string;
+    locale?: string;
+};
+interface OpenOptions {
+    onSuccess?: (event: Extract<CheckoutEvent, {
+        type: 'oleqpay:success';
+    }>) => void;
+    onError?: (event: Extract<CheckoutEvent, {
+        type: 'oleqpay:failed';
+    }>) => void;
+    onClose?: () => void;
+}
+
+declare class OleqPayCheckout {
+    private readonly checkoutBaseUrl;
+    private readonly locale;
+    private activeModal;
+    private messageHandler;
+    constructor(options?: OleqPayCheckoutOptions);
+    /**
+     * Build a hosted-checkout URL from a payload.
+     * Safe on the server (no DOM) — use this to mint session URLs in Nest/backends.
+     */
+    buildUrl(payload: CheckoutPayload): string;
+    /** Opens checkout in a modal iframe. Accepts either a raw payload or a pre-built session URL. */
+    openIframe(payloadOrUrl: CheckoutPayload | string, options?: OpenOptions): void;
+    /** Full-page redirect to hosted checkout — mirrors Stripe Checkout / Paystack redirect flow. */
+    redirect(payloadOrUrl: CheckoutPayload | string): void;
+    /** Programmatically close an open iframe modal. */
+    close(): void;
+    private resolveUrl;
+    private teardown;
+}
+
+type OleqPayCheckoutErrorCode = 'ssr_unsupported' | 'invalid_api_key' | 'invalid_payload';
+declare class OleqPayCheckoutError extends Error {
+    readonly code: OleqPayCheckoutErrorCode;
+    constructor(message: string, code: OleqPayCheckoutErrorCode);
+}
+
+export { type CheckoutEvent, type CheckoutPayload, OleqPayCheckout, OleqPayCheckoutError, type OleqPayCheckoutErrorCode, type OleqPayCheckoutOptions, type OpenOptions, OleqPayCheckout as default };

package/dist/index.js

@@ -0,0 +1,298 @@
+"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, {
+  OleqPayCheckout: () => OleqPayCheckout,
+  OleqPayCheckoutError: () => OleqPayCheckoutError,
+  default: () => OleqPayCheckout
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/encode.ts
+function encodePaymentData(payload) {
+  const json = JSON.stringify(payload);
+  const firstEncode = utf8ToBase64(json);
+  return utf8ToBase64(firstEncode);
+}
+function utf8ToBase64(input) {
+  const bytes = new TextEncoder().encode(input);
+  let binary = "";
+  bytes.forEach((byte) => {
+    binary += String.fromCharCode(byte);
+  });
+  return btoa(binary);
+}
+function buildCheckoutUrl(baseUrl, payload, options) {
+  const qp = encodePaymentData(payload);
+  const locale = options?.locale ?? "en";
+  const path = options?.path ?? "p";
+  const normalizedBase = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  const url = new URL(`${locale}/${path}`, normalizedBase);
+  url.searchParams.set("qp", qp);
+  return url.toString();
+}
+
+// src/errors.ts
+var OleqPayCheckoutError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "OleqPayCheckoutError";
+    this.code = code;
+  }
+};
+
+// src/modal.ts
+var OVERLAY_ID = "oleqpay-checkout-overlay";
+function openCheckoutModal(url, onCloseRequested) {
+  removeExistingModal();
+  const overlay = document.createElement("div");
+  overlay.id = OVERLAY_ID;
+  Object.assign(overlay.style, {
+    position: "fixed",
+    inset: "0",
+    zIndex: "2147483000",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    background: "rgba(15, 23, 42, 0.55)",
+    backdropFilter: "blur(2px)"
+  });
+  const panel = document.createElement("div");
+  Object.assign(panel.style, {
+    position: "relative",
+    width: "min(440px, calc(100vw - 32px))",
+    height: "min(720px, calc(100vh - 32px))",
+    borderRadius: "16px",
+    overflow: "hidden",
+    boxShadow: "0 20px 60px rgba(0,0,0,0.35)",
+    background: "#fff"
+  });
+  const closeBtn = document.createElement("button");
+  closeBtn.setAttribute("aria-label", "Close checkout");
+  closeBtn.textContent = "\xD7";
+  Object.assign(closeBtn.style, {
+    position: "absolute",
+    top: "8px",
+    right: "8px",
+    width: "32px",
+    height: "32px",
+    borderRadius: "9999px",
+    border: "none",
+    background: "rgba(0,0,0,0.06)",
+    fontSize: "20px",
+    lineHeight: "1",
+    cursor: "pointer",
+    zIndex: "1"
+  });
+  closeBtn.onclick = () => onCloseRequested();
+  const iframe = document.createElement("iframe");
+  iframe.src = url;
+  iframe.title = "OleqPay Checkout";
+  iframe.setAttribute(
+    "allow",
+    "payment *; clipboard-write; camera; publickey-credentials-get"
+  );
+  Object.assign(iframe.style, {
+    width: "100%",
+    height: "100%",
+    border: "0"
+  });
+  panel.appendChild(closeBtn);
+  panel.appendChild(iframe);
+  overlay.appendChild(panel);
+  document.body.appendChild(overlay);
+  document.body.style.overflow = "hidden";
+  const onKeydown = (e) => {
+    if (e.key === "Escape") onCloseRequested();
+  };
+  window.addEventListener("keydown", onKeydown);
+  return {
+    iframe,
+    close: () => {
+      window.removeEventListener("keydown", onKeydown);
+      document.body.style.overflow = "";
+      overlay.remove();
+    }
+  };
+}
+function removeExistingModal() {
+  const existing = document.getElementById(OVERLAY_ID);
+  if (!existing) return;
+  existing.remove();
+  document.body.style.overflow = "";
+}
+
+// src/api-key.ts
+function assertPublicApiKey(apikey) {
+  if (!apikey) {
+    throw new OleqPayCheckoutError(
+      "OleqPayCheckout: apikey is required.",
+      "invalid_api_key"
+    );
+  }
+  if (apikey.startsWith("sk_")) {
+    throw new OleqPayCheckoutError(
+      "OleqPayCheckout: this looks like a secret key (sk_\u2026). Only public keys belong in browser code \u2014 mint a session server-side with buildUrl() and pass the resulting URL to openIframe()/redirect() instead.",
+      "invalid_api_key"
+    );
+  }
+}
+
+// src/payload.ts
+function assertValidPayload(payload) {
+  assertPublicApiKey(payload.apikey);
+  if (payload.apikey.length < 10) {
+    throw new OleqPayCheckoutError(
+      "OleqPayCheckout: apikey must be at least 10 characters.",
+      "invalid_api_key"
+    );
+  }
+  if (payload.orderid === void 0 || payload.orderid === "") {
+    throw new OleqPayCheckoutError(
+      "OleqPayCheckout: orderid is required \u2014 the checkout page rejects payloads without it.",
+      "invalid_payload"
+    );
+  }
+  if (!payload.reference) {
+    throw new OleqPayCheckoutError(
+      "OleqPayCheckout: reference is required \u2014 the checkout page rejects payloads without it.",
+      "invalid_payload"
+    );
+  }
+  const amountValue = typeof payload.amount === "number" ? payload.amount : parseFloat(payload.amount);
+  if (!Number.isFinite(amountValue) || amountValue <= 0) {
+    throw new OleqPayCheckoutError(
+      "OleqPayCheckout: amount must be a number greater than 0.",
+      "invalid_payload"
+    );
+  }
+  if (payload.callbackurl && !isValidUrl(payload.callbackurl)) {
+    throw new OleqPayCheckoutError(
+      "OleqPayCheckout: callbackurl must be a valid URL.",
+      "invalid_payload"
+    );
+  }
+  if (payload.returnurl && !isValidUrl(payload.returnurl)) {
+    throw new OleqPayCheckoutError(
+      "OleqPayCheckout: returnurl must be a valid URL.",
+      "invalid_payload"
+    );
+  }
+}
+function isValidUrl(value) {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/types.ts
+var DEFAULT_CHECKOUT_BASE_URL = "https://my.olefi.co";
+
+// src/client.ts
+var OleqPayCheckout = class {
+  constructor(options = {}) {
+    this.activeModal = null;
+    this.messageHandler = null;
+    this.checkoutBaseUrl = options.checkoutBaseUrl ?? DEFAULT_CHECKOUT_BASE_URL;
+    this.locale = options.locale ?? "en";
+  }
+  /**
+   * Build a hosted-checkout URL from a payload.
+   * Safe on the server (no DOM) — use this to mint session URLs in Nest/backends.
+   */
+  buildUrl(payload) {
+    assertValidPayload(payload);
+    return buildCheckoutUrl(this.checkoutBaseUrl, payload, {
+      locale: this.locale
+    });
+  }
+  /** Opens checkout in a modal iframe. Accepts either a raw payload or a pre-built session URL. */
+  openIframe(payloadOrUrl, options = {}) {
+    if (typeof window === "undefined") {
+      throw new OleqPayCheckoutError(
+        "OleqPayCheckout.openIframe() can only run in a browser.",
+        "ssr_unsupported"
+      );
+    }
+    this.close();
+    const url = this.resolveUrl(payloadOrUrl);
+    const targetOrigin = new URL(url).origin;
+    const onUserClose = () => {
+      this.close();
+      options.onClose?.();
+    };
+    this.activeModal = openCheckoutModal(url, onUserClose);
+    this.messageHandler = (event) => {
+      if (event.origin !== targetOrigin) return;
+      const data = event.data;
+      if (!data || typeof data !== "object" || !("type" in data)) return;
+      switch (data.type) {
+        case "oleqpay:success":
+          options.onSuccess?.(data);
+          this.close();
+          break;
+        case "oleqpay:failed":
+          options.onError?.(data);
+          break;
+        case "oleqpay:close":
+          onUserClose();
+          break;
+        default:
+          break;
+      }
+    };
+    window.addEventListener("message", this.messageHandler);
+  }
+  /** Full-page redirect to hosted checkout — mirrors Stripe Checkout / Paystack redirect flow. */
+  redirect(payloadOrUrl) {
+    if (typeof window === "undefined") {
+      throw new OleqPayCheckoutError(
+        "OleqPayCheckout.redirect() can only run in a browser.",
+        "ssr_unsupported"
+      );
+    }
+    window.location.href = this.resolveUrl(payloadOrUrl);
+  }
+  /** Programmatically close an open iframe modal. */
+  close() {
+    this.activeModal?.close();
+    this.teardown();
+  }
+  resolveUrl(payloadOrUrl) {
+    if (typeof payloadOrUrl === "string") return payloadOrUrl;
+    return this.buildUrl(payloadOrUrl);
+  }
+  teardown() {
+    if (this.messageHandler) {
+      window.removeEventListener("message", this.messageHandler);
+      this.messageHandler = null;
+    }
+    this.activeModal = null;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OleqPayCheckout,
+  OleqPayCheckoutError
+});