remita-inline 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 remita-inline contributors
+
+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,308 @@
+# remita-inline
+
+A fully-typed TypeScript wrapper for the Remita Inline payment SDK with an RRR-only integration flow.
+
+The library supports one payment path:
+- generate or receive an RRR upstream
+- pass that RRR into the SDK
+- open the Remita payment widget
+
+It works as a plain function, a React hook, or a React button component.
+
+## Installation
+
+```bash
+npm install remita-inline
+```
+
+If you use the React hook or button component, install React separately:
+
+```bash
+npm install react react-dom
+```
+
+## Quick start
+
+```ts
+import { startRemitaPayment } from "remita-inline";
+
+await startRemitaPayment(
+  {
+    key: "your-public-key",
+    rrr: "321489526389",
+    transactionId: "unique-tx-id",
+    onSuccess(response) {
+      console.log("Payment successful", response.transactionId);
+    },
+    onError(error) {
+      console.error("Payment failed", error.message);
+    },
+    onClose() {
+      console.log("Payment modal closed");
+    },
+  },
+  {
+    environment: "demo",
+  },
+);
+```
+
+By default the widget opens automatically after the SDK loads. Pass `autoOpen: false` if you want to control when the widget appears.
+
+## React hook
+
+```tsx
+import { useRemitaInline } from "remita-inline";
+
+function RrrPaymentButton() {
+  const { pay, isLoading, error, reset } = useRemitaInline({ environment: "demo" });
+
+  const handlePay = async () => {
+    try {
+      await pay({
+        key: "your-public-key",
+        rrr: "321489526389",
+        transactionId: "unique-tx-id",
+        onSuccess(res) {
+          console.log("Paid", res.transactionId);
+        },
+      });
+    } catch {
+      // error is already available in hook state
+    }
+  };
+
+  return (
+    <>
+      {error && (
+        <p>
+          Payment failed: {error.message}{" "}
+          <button onClick={reset}>Dismiss</button>
+        </p>
+      )}
+      <button onClick={handlePay} disabled={isLoading}>
+        {isLoading ? "Processing..." : "Pay with RRR"}
+      </button>
+    </>
+  );
+}
+```
+
+Per-call options are merged over hook-level defaults.
+
+## React button component
+
+```tsx
+import { RemitaPayButton } from "remita-inline";
+
+function Checkout() {
+  return (
+    <RemitaPayButton
+      paymentConfig={{
+        key: "your-public-key",
+        rrr: "321489526389",
+        transactionId: "unique-tx-id",
+        onSuccess(res) {
+          console.log("Paid", res.transactionId);
+        },
+      }}
+      paymentOptions={{ environment: "demo" }}
+      onPaymentStart={() => console.log("Payment started")}
+      onPaymentError={(err) => console.error(err.message)}
+      loadingText="Please wait..."
+    >
+      Pay with RRR
+    </RemitaPayButton>
+  );
+}
+```
+
+All standard button attributes are forwarded. If your custom `onClick` calls `event.preventDefault()`, the payment flow is cancelled.
+
+## Low-level API
+
+```ts
+import { loadRemitaScript, initRemitaEngine } from "remita-inline";
+
+await loadRemitaScript({ environment: "demo", timeoutMs: 10000 });
+
+const session = initRemitaEngine({
+  key: "your-public-key",
+  rrr: "321489526389",
+  transactionId: "unique-tx-id",
+});
+
+session.openIframe();
+```
+
+Or defer opening with `startRemitaPayment`:
+
+```ts
+import { startRemitaPayment } from "remita-inline";
+
+const { open } = await startRemitaPayment(
+  {
+    key: "your-public-key",
+    rrr: "321489526389",
+    transactionId: "unique-tx-id",
+  },
+  {
+    autoOpen: false,
+    environment: "demo",
+  },
+);
+
+open();
+```
+
+## Configuration reference
+
+### `RemitaPaymentConfig`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `key` | `string` | Yes | Your Remita public key |
+| `rrr` | `string \| number` | Yes | The Remita Retrieval Reference to pay |
+| `transactionId` | `string \| number` | No | Optional transaction reference from your application |
+| `extendedData` | `RemitaExtendedData` | No | Extra data merged into the internal Remita payload |
+| `currency` | `RemitaCurrencyCode` | No | Optional currency override |
+| `metadata` | `Record<string, string \| number \| boolean \| null>` | No | Arbitrary metadata |
+| `onSuccess` | `(res: RemitaSuccessfulPayment) => void` | No | Called on successful payment |
+| `onError` | `(err: RemitaPaymentError) => void` | No | Called on payment failure |
+| `onClose` | `() => void` | No | Called when the payment modal closes |
+
+### `RemitaExtendedData`
+
+| Field | Type | Description |
+|---|---|---|
+| `customFields` | `RemitaExtendedDataCustomField[]` | Additional custom fields merged into the Remita payload |
+
+The library always injects the `rrr` field into `extendedData.customFields` before calling the Remita engine. Any extra custom fields you provide are preserved.
+
+### `RemitaStartPaymentOptions` / `RemitaLibraryOptions`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `autoOpen` | `boolean` | `true` | Open the payment widget immediately |
+| `environment` | `"demo" \| "production"` | `"production"` | Select the Remita SDK environment |
+| `scriptUrl` | `string` | Environment-specific URL | Override the SDK script URL manually |
+| `scriptId` | `string` | `"remita-inline-sdk"` | `id` attribute of the injected script tag |
+| `timeoutMs` | `number` | `15000` | Script load timeout in milliseconds |
+| `nonce` | `string` | None | CSP nonce for the injected script tag |
+
+## Error handling
+
+All library errors extend `RemitaError`.
+
+| Class | Thrown when |
+|---|---|
+| `ValidationError` | Required fields such as `key` or `rrr` are missing or invalid |
+| `ScriptLoadError` | The Remita SDK script fails to load, times out, or runs outside a browser |
+| `EngineError` | `window.RmPaymentEngine` is missing or returns an invalid session |
+
+```ts
+import {
+  startRemitaPayment,
+  ValidationError,
+  ScriptLoadError,
+} from "remita-inline";
+
+try {
+  await startRemitaPayment({
+    key: "your-public-key",
+    rrr: "321489526389",
+  });
+} catch (error) {
+  if (error instanceof ValidationError) {
+    showFormError(error.message);
+  } else if (error instanceof ScriptLoadError) {
+    showNetworkError();
+  } else {
+    throw error;
+  }
+}
+```
+
+## Advanced options
+
+### Demo vs production
+
+```ts
+await startRemitaPayment(config, { environment: "demo" });
+await startRemitaPayment(config, { environment: "production" });
+```
+
+### Pre-loading the script
+
+```ts
+import { loadRemitaScript } from "remita-inline";
+
+await loadRemitaScript({ environment: "demo" });
+```
+
+`loadRemitaScript` is idempotent: concurrent calls share one in-flight Promise, and if the engine is already on `window` it returns immediately.
+
+### Content Security Policy (CSP)
+
+```ts
+await startRemitaPayment(config, { nonce: "abc123" });
+```
+
+### Adding extra custom fields
+
+```ts
+await startRemitaPayment({
+  key: "your-public-key",
+  rrr: "321489526389",
+  extendedData: {
+    customFields: [
+      { name: "orderId", value: "ORD-123" },
+      { name: "customerTier", value: "gold" },
+    ],
+  },
+});
+```
+
+## TypeScript
+
+All public types are exported from the package root:
+
+```ts
+import type {
+  RemitaEngine,
+  RemitaEnginePaymentConfig,
+  RemitaEngineSession,
+  RemitaExtendedData,
+  RemitaExtendedDataCustomField,
+  RemitaPaymentConfig,
+  RemitaPaymentError,
+  RemitaPaymentSession,
+  RemitaStartPaymentOptions,
+  RemitaSuccessfulPayment,
+  UseRemitaInlineResult,
+} from "remita-inline";
+```
+
+The package ships with declaration files and source maps in `dist/`. Both ESM and CJS consumers are supported via the `exports` field in `package.json`.
+
+## Browser support
+
+Requires a browser with native `Promise`, `addEventListener`, and `document.createElement`. Equivalent to ES2020 environments. The library is browser-only because the Remita SDK depends on `window` and `document`.
+
+For Next.js, render payment UI inside a `"use client"` component or guard execution with `typeof window !== "undefined"`.
+
+## Contributing
+
+```bash
+git clone https://github.com/your-org/remita-inline
+cd remita-inline
+npm install
+
+npm run typecheck
+npm test
+npm run build
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -0,0 +1,371 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/core/constant.ts
+var REMITA_SCRIPT_ID = "remita-inline-sdk";
+var REMITA_PRODUCTION_SCRIPT_URL = "https://login.remita.net/payment/v1/remita-pay-inline.bundle.js";
+var REMITA_DEMO_SCRIPT_URL = "https://demo.remita.net/payment/v1/remita-pay-inline.bundle.js";
+var REMITA_SCRIPT_URL = REMITA_PRODUCTION_SCRIPT_URL;
+var REMITA_ENGINE = "RmPaymentEngine";
+
+// src/utils/once.ts
+var promise = null;
+function getPromise() {
+  return promise;
+}
+function setPromise(value) {
+  promise = value;
+}
+function clearPromise() {
+  promise = null;
+}
+
+// src/utils/errors.ts
+var RemitaError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RemitaError";
+  }
+};
+var ValidationError = class extends RemitaError {
+  constructor(message) {
+    super(message);
+    this.name = "ValidationError";
+  }
+};
+var ScriptLoadError = class extends RemitaError {
+  constructor(message) {
+    super(message);
+    this.name = "ScriptLoadError";
+  }
+};
+var EngineError = class extends RemitaError {
+  constructor(message) {
+    super(message);
+    this.name = "EngineError";
+  }
+};
+
+// src/core/loader.ts
+function isBrowserEnvironment() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function getEngine(win) {
+  return win[REMITA_ENGINE];
+}
+function resolveScriptUrl(options) {
+  if (options.scriptUrl) {
+    return options.scriptUrl;
+  }
+  if (options.environment === "demo") {
+    return REMITA_DEMO_SCRIPT_URL;
+  }
+  if (options.environment === "production") {
+    return REMITA_PRODUCTION_SCRIPT_URL;
+  }
+  return REMITA_SCRIPT_URL;
+}
+function waitForExistingScript(script, timeoutMs, win) {
+  if (script.dataset.loaded === "true" && getEngine(win)) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    let timeoutId;
+    const onLoad = () => {
+      cleanup();
+      script.dataset.loaded = "true";
+      if (!getEngine(win)) {
+        reject(new ScriptLoadError("Remita script loaded but payment engine is unavailable."));
+        return;
+      }
+      resolve();
+    };
+    const onError = () => {
+      cleanup();
+      reject(new ScriptLoadError("Failed to load Remita script."));
+    };
+    const cleanup = () => {
+      script.removeEventListener("load", onLoad);
+      script.removeEventListener("error", onError);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    };
+    script.addEventListener("load", onLoad, { once: true });
+    script.addEventListener("error", onError, { once: true });
+    timeoutId = setTimeout(() => {
+      cleanup();
+      reject(new ScriptLoadError(`Timed out waiting for Remita script after ${timeoutMs}ms.`));
+    }, timeoutMs);
+  });
+}
+function createAndLoadScript(scriptId, scriptUrl, timeoutMs, nonce) {
+  const win = window;
+  return new Promise((resolve, reject) => {
+    const script = document.createElement("script");
+    let timeoutId;
+    script.id = scriptId;
+    script.src = scriptUrl;
+    script.async = true;
+    if (nonce) {
+      script.nonce = nonce;
+    }
+    const onLoad = () => {
+      cleanup();
+      script.dataset.loaded = "true";
+      if (!getEngine(win)) {
+        reject(new ScriptLoadError("Remita script loaded but payment engine is unavailable."));
+        return;
+      }
+      resolve();
+    };
+    const onError = () => {
+      cleanup();
+      reject(new ScriptLoadError("Failed to load Remita script."));
+    };
+    const cleanup = () => {
+      script.removeEventListener("load", onLoad);
+      script.removeEventListener("error", onError);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    };
+    script.addEventListener("load", onLoad, { once: true });
+    script.addEventListener("error", onError, { once: true });
+    timeoutId = setTimeout(() => {
+      cleanup();
+      script.remove();
+      reject(new ScriptLoadError(`Timed out loading Remita script after ${timeoutMs}ms.`));
+    }, timeoutMs);
+    document.head.appendChild(script);
+  });
+}
+async function loadRemitaScript(options = {}) {
+  if (!isBrowserEnvironment()) {
+    throw new ScriptLoadError("Remita script loader can only run in a browser environment.");
+  }
+  const scriptId = options.scriptId ?? REMITA_SCRIPT_ID;
+  const scriptUrl = resolveScriptUrl(options);
+  const timeoutMs = options.timeoutMs ?? 15e3;
+  const win = window;
+  if (getEngine(win)) {
+    return;
+  }
+  const inFlight = getPromise();
+  if (inFlight) {
+    return inFlight;
+  }
+  const task = (async () => {
+    const existingScript = document.getElementById(scriptId);
+    if (existingScript) {
+      if (existingScript.src && existingScript.src !== scriptUrl) {
+        throw new ScriptLoadError(
+          `Script with id "${scriptId}" already exists with a different src.`
+        );
+      }
+      await waitForExistingScript(existingScript, timeoutMs, win);
+      return;
+    }
+    await createAndLoadScript(scriptId, scriptUrl, timeoutMs, options.nonce);
+  })();
+  setPromise(task);
+  try {
+    await task;
+  } catch (error) {
+    clearPromise();
+    throw error;
+  }
+}
+
+// src/core/engine.ts
+function isBrowserEnvironment2() {
+  return typeof window !== "undefined";
+}
+function getRemitaEngine(win) {
+  if (!isBrowserEnvironment2()) {
+    throw new EngineError("Remita engine is only available in a browser environment.");
+  }
+  const targetWindow = win ?? window;
+  const engine = targetWindow[REMITA_ENGINE];
+  if (!engine || typeof engine.init !== "function") {
+    throw new EngineError("Remita payment engine is unavailable on window.");
+  }
+  return engine;
+}
+function initRemitaEngine(config, win) {
+  const engine = getRemitaEngine(win);
+  const rawSession = engine.init(toEnginePaymentConfig(config));
+  const openIframe = typeof rawSession.openIframe === "function" ? rawSession.openIframe.bind(rawSession) : typeof rawSession.showPaymentWidget === "function" ? rawSession.showPaymentWidget.bind(rawSession) : void 0;
+  if (!openIframe) {
+    throw new EngineError("Remita engine returned an invalid payment session.");
+  }
+  return {
+    openIframe,
+    ...typeof rawSession.showPaymentWidget === "function" ? { showPaymentWidget: rawSession.showPaymentWidget.bind(rawSession) } : {}
+  };
+}
+function toEnginePaymentConfig(config) {
+  const { rrr, extendedData, ...rest } = config;
+  const engineExtendedData = {
+    ...extendedData ?? {},
+    customFields: [
+      ...(extendedData?.customFields ?? []).filter((field) => field?.name !== "rrr"),
+      {
+        name: "rrr",
+        value: rrr
+      }
+    ]
+  };
+  return {
+    ...rest,
+    processRrr: true,
+    extendedData: engineExtendedData
+  };
+}
+
+// src/core/validator.ts
+function assertNonEmptyString(value, fieldName) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new ValidationError(`${fieldName} is required and must be a non-empty string.`);
+  }
+}
+function assertValidTransactionId(value) {
+  if (value === void 0) {
+    return;
+  }
+  const isString = typeof value === "string" && value.trim().length > 0;
+  const isNumber = typeof value === "number" && Number.isFinite(value);
+  if (!isString && !isNumber) {
+    throw new ValidationError(
+      "transactionId must be a non-empty string or a finite number when provided."
+    );
+  }
+}
+function assertValidRrr(value) {
+  const isString = typeof value === "string" && value.trim().length > 0;
+  const isNumber = typeof value === "number" && Number.isFinite(value);
+  if (!isString && !isNumber) {
+    throw new ValidationError("rrr is required and must be a non-empty string or a finite number.");
+  }
+}
+function validateRrrConfig(config) {
+  assertValidRrr(config.rrr);
+}
+function validatePaymentConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw new ValidationError("Payment config is required.");
+  }
+  assertNonEmptyString(config.key, "key");
+  assertValidRrr(config.rrr);
+  assertValidTransactionId(config.transactionId);
+  validateRrrConfig(config);
+  return config;
+}
+
+// src/core/payment.ts
+async function startRemitaPayment(config, options = {}) {
+  validatePaymentConfig(config);
+  await loadRemitaScript(options);
+  const session = initRemitaEngine(config);
+  const open = () => {
+    if (typeof session.showPaymentWidget === "function") {
+      session.showPaymentWidget();
+      return;
+    }
+    session.openIframe();
+  };
+  if (options.autoOpen !== false) {
+    open();
+  }
+  return {
+    open,
+    session
+  };
+}
+function useRemitaInline(defaultOptions = {}) {
+  const [isLoading, setIsLoading] = react.useState(false);
+  const [error, setError] = react.useState(null);
+  const pay = react.useCallback(
+    async (config, options = {}) => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        await startRemitaPayment(config, {
+          ...defaultOptions,
+          ...options
+        });
+      } catch (err) {
+        const nextError = err instanceof Error ? err : new Error("Payment initialization failed.");
+        setError(nextError);
+        throw nextError;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [defaultOptions]
+  );
+  const reset = react.useCallback(() => {
+    setError(null);
+  }, []);
+  return {
+    pay,
+    isLoading,
+    error,
+    reset
+  };
+}
+function RemitaPayButton({
+  paymentConfig,
+  paymentOptions,
+  onPaymentStart,
+  onPaymentError,
+  onClick,
+  loadingText = "Processing...",
+  disabled,
+  children,
+  ...props
+}) {
+  const { pay, isLoading } = useRemitaInline();
+  const handleClick = react.useCallback(
+    async (event) => {
+      onClick?.(event);
+      if (event.defaultPrevented || isLoading) {
+        return;
+      }
+      onPaymentStart?.();
+      try {
+        await pay(paymentConfig, paymentOptions);
+      } catch (error) {
+        if (onPaymentError) {
+          onPaymentError(error instanceof Error ? error : new Error("Payment failed."));
+        }
+      }
+    },
+    [isLoading, onClick, onPaymentError, onPaymentStart, pay, paymentConfig, paymentOptions]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "button",
+    {
+      type: "button",
+      ...props,
+      disabled: disabled || isLoading,
+      onClick: handleClick,
+      children: isLoading ? loadingText : children ?? "Pay with Remita"
+    }
+  );
+}
+
+exports.REMITA_DEMO_SCRIPT_URL = REMITA_DEMO_SCRIPT_URL;
+exports.REMITA_PRODUCTION_SCRIPT_URL = REMITA_PRODUCTION_SCRIPT_URL;
+exports.RemitaPayButton = RemitaPayButton;
+exports.getRemitaEngine = getRemitaEngine;
+exports.initRemitaEngine = initRemitaEngine;
+exports.loadRemitaScript = loadRemitaScript;
+exports.startRemitaPayment = startRemitaPayment;
+exports.toEnginePaymentConfig = toEnginePaymentConfig;
+exports.useRemitaInline = useRemitaInline;
+exports.validatePaymentConfig = validatePaymentConfig;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map