@interswitchapi/ship-referral-embed

Lightweight embed for the SHIP referrals module. Drop it into your app, point it at a container, and the full referrals inbox (inbound/outbound list, detail, facility lookup and the referral form) renders inline — auth token, styling, and SHIP API calls are all handled for you.

Use it as a React component, a React-free vanilla package, or a hosted script.

npm install @interswitchapi/ship-referral-embed

React — component

import { ShipReferrals } from "@interswitchapi/ship-referral-embed/react";

function Inbox() {
  return (
    <ShipReferrals
      mode="production" // or "staging"
      getToken={() => auth.accessToken} // or token="..."
      defaultTab="referred-in"
      style={{ height: "80vh" }} // give the container a height
      onSubmitted={(r) => {}}
      onError={(m) => {}}
    />
  );
}

The iframe fills its container, so give the container a height — a heightless container collapses. To take the inbox down, stop rendering <ShipReferrals> (e.g. conditionally); it tears the iframe down on unmount.

Vanilla package

Import the dedicated core entry when React is not installed:

import { openReferralsInbox } from "@interswitchapi/ship-referral-embed/core";

const embed = openReferralsInbox({
  container: "#ship-referrals",
  mode: "production",
  getToken: () => auth.accessToken,
});

// Local teardown does not call onClose.
embed.close();

Hosted script

<div id="ship-referrals" style="height: 80vh"></div>
<script src="https://ship.example/referral-embed.js"></script>
<script>
  const embed = ShipReferral.open({
    container: "#ship-referrals",
    mode: "production", // or "staging"
    getToken: () => auth.accessToken,
    defaultTab: "referred-in",
    onSubmitted: (r) => {},
    onError: (m) => {},
    onClose: () => {}, // the embed asked to close (e.g. session failed)
  });

  // Take it down whenever you like. This does not invoke onClose:
  // embed.close();
</script>

All three paths run the same core implementation.

Unlike the old form overlay, the module is inline — it fills the container you give it and never covers the host page. So there is nothing to "dismiss": you control its lifetime by mounting/unmounting the container (React) or calling handle.close() (vanilla). onClose fires when the embed itself gives up (a fatal session error) so you can hide or unmount the container in response.

Options

| Option | Notes | | -------------------------- | ----------------------------------------------------------------------------------------------- | | container | required (React uses the rendered element; vanilla takes an element or CSS selector) | | token / getToken | one is required; getToken is preferred and read fresh for refresh | | mode | which SHIP environment to point at: "production" or "staging" (see below) | | embedOrigin / embedUrl | a custom SHIP origin/URL, for local, preview or self-hosted deployments; overrides mode | | handshakeTimeoutMs | ready-handshake timeout in milliseconds; defaults to 15000, or set 0 to disable | | defaultTab | "referred-in" (default) or "referred-out" | | onSubmitted(result) | a referral was submitted from inside the inbox | | onError(message) | a non-fatal error to surface | | onClose() | the embed asked to close itself (e.g. session failed) — hide/unmount the container |

Environments

Set mode to the environment you want and the embed resolves the origin for you:

| mode | Origin | | -------------- | --------------------------------------------- | | "production" | https://portal.digitalhealthplatforms.ng | | "staging" | https://ship-admin-ui-web-v2.staging.isw.la |

For anything outside these two — a local build, a preview deployment, or a self-hosted SHIP — set embedOrigin (or a full embedUrl) instead. Either one overrides mode, so you can also drive it from your app's env, e.g. embedOrigin={import.meta.env.VITE_SHIP_ORIGIN}.

Custom targets must use HTTPS. For local development, HTTP is accepted only for localhost, 127.0.0.1, and [::1]. embedOrigin must be an origin without a path, query, or fragment; use embedUrl when you need a full route.

Failure and security behavior

• Messages are accepted only from the configured origin and the exact mounted iframe. Malformed or unknown messages are ignored.
• Protocol version 1 is sent during initialization. Legacy iframes that omit a version remain supported; an explicit incompatible version fails fast.
• Iframe load failures, handshake timeouts, and token-provider failures call onError. Load and handshake failures also remove the unusable iframe.
• handle.close() and React unmount are local teardown operations and never call onClose; only an authenticated close message from the iframe does.

License

MIT © Interswitch Group.