enjaz-superapp-bridge

Type-safe bridge for communication with the Enjaz super app (SSO, logout, checkout, notifications, payment methods, login, location, QR scan, file download).

Install

npm install enjaz-superapp-bridge
# or
yarn add enjaz-superapp-bridge

Usage

In a browser environment where the Enjaz super app injects window.__ESA__:

import { enjaz } from 'enjaz-superapp-bridge';

// SSO authorization
const { ssoCode, expiresAt, isGuest } = await enjaz.requestSsoAuthorization();

if (isGuest) {
  // Continue guest flow
}

// Logout
await enjaz.logout();

// Open checkout
const result = await enjaz.openCheckout(paymentIntentId);

// Open native notifications screen
await enjaz.openNotifications();

// Open native payment methods screen
await enjaz.openPaymentMethods();

// Open native login screen
await enjaz.openLogin();

// Get current location from native app
const location = await enjaz.getCurrentLocation();
if (location.success) {
  console.log(location.lat, location.lng);
}

// Open native QR scanner
const scan = await enjaz.scanQrCode();
if (scan.success) {
  console.log(scan.value);
}

// Trigger native file download
await enjaz.downloadFile({
  url: 'https://example.com/files/invoice.pdf',
  filename: 'invoice.pdf', // optional
});

The bridge also attaches window.enjaz when loaded in a browser, so you can use the global if you load the script via a <script> tag.

API

• enjaz.requestSsoAuthorization() – Returns a promise that resolves with { ssoCode, expiresAt, isGuest }.
• enjaz.logout() – Returns a promise that resolves when logout is complete.
• enjaz.openCheckout(paymentIntentId: string) – Returns a promise that resolves with the payment intent result.
• enjaz.openNotifications() – Returns a promise that resolves when the native notifications screen is opened.
• enjaz.openPaymentMethods() – Returns a promise that resolves when the native payment methods screen is opened.
• enjaz.openLogin() – Returns a promise that resolves when the native login screen is opened.
• enjaz.getCurrentLocation() – Returns a promise that resolves with { success, lat, lng }.
• enjaz.scanQrCode() – Returns a promise that resolves with { success, value }.
• enjaz.downloadFile(payload: DownloadFilePayload) – Returns a promise that resolves when native download is triggered with { url, filename? }.

Checkout behavior

openCheckout() may stay pending while the user completes native payment steps such as:

• Adding a card
• 3DS or OTP verification
• Switching to another native screen and coming back

The bridge does not time out this request. It keeps waiting for the final native checkout reply.

If a request stays pending for a long time, the bridge logs warnings such as:

• [enjaz] Message "OPEN_CHECKOUT" is still pending ... (uuid: "...")

Use this UUID to correlate logs between the mini app and native app while troubleshooting delayed or missing responses.

Reload recovery

openCheckout() includes automatic reload recovery with no extra mini-app API calls:

• Pending checkout sessions are persisted in localStorage.
• On SDK initialization, pending sessions are restored so replayed native checkout replies can be consumed.
• Duplicate replay/live responses are de-duplicated to keep single-resolution behavior.

When a replayed checkout result arrives after a reload, the SDK stores it briefly and returns it automatically on the next openCheckout(paymentIntentId) call.

Notes:

• This behavior depends on native support for replaying the final OPEN_CHECKOUT response.
• Persisted pending sessions are removed once a terminal checkout response is processed.
• Recovery logs include paymentIntentId and uuid to simplify cross-platform debugging.

Types

Exported types: EnjazBridge, SsoAuthorizationResponse, CompletePaymentIntentResponse, CurrentLocationResponse, ScanQrCodeResponse, DownloadFilePayload, PaymentIntentStatus, GatewayStatus.

SsoAuthorizationResponse

{
  ssoCode: string | null;
  expiresAt: Date | string | null;
  isGuest: boolean;
}

CurrentLocationResponse

{
  success: boolean;
  lat: number | null;
  lng: number | null;
}

ScanQrCodeResponse

{
  success: boolean;
  value: string | null;
}

DownloadFilePayload

{
  url: string;
  filename?: string;
}

Publish

1. Build and verify types:

npm run build

2. Bump package version (pick one):

npm version patch
# or
npm version minor
# or
npm version major

3. Publish to npm:

npm publish

License

MIT