@owllet/mini-app-sdk

Platform bridge helpers for Owllet-hosted mini apps.

Install

npm install @owllet/mini-app-sdk

Core Usage

import { createOwlletMiniAppClient } from '@owllet/mini-app-sdk';

const client = createOwlletMiniAppClient();

const context = client.getContext();
const launchParams = client.getLaunchParams();

await client.ready({ screen: 'home', version: '0.1.0' });

React Usage

import { useOwlletMiniApp } from '@owllet/mini-app-sdk';

export function MiniAppHeader() {
  const { context, bridgeAvailable, connecting, error } = useOwlletMiniApp();

  if (connecting) return <p>Connecting to Owllet...</p>;
  if (!bridgeAvailable) return <p>{error}</p>;

  return <h1>{context?.miniApp.title ?? 'Mini App'}</h1>;
}

What The SDK Returns

The SDK normalizes the raw mobile host payload into a platform-wide shape:

• context.host
• context.miniApp
• context.launch
• context.session
• context.permissions
• context.capabilities
• context.raw

This means mini apps do not need to depend on legacy flat host fields like miniAppTitle or hasSession.

Included Helpers

• createOwlletMiniAppClient()
• normalizeOwlletMiniAppContext()
• evaluateOwlletMiniAppSecurity()
• assertOwlletMiniAppSecurity()
• waitForOwlletMiniApp()
• getOwlletMiniAppLaunchParams()
• normalizeOwlletMiniAppExternalUrl()
• isSafeOwlletMiniAppExternalUrl()
• useOwlletMiniApp()
• useOwlletMiniAppContext()
• onOwlletMiniAppReady()
• assertOwlletMiniApp()

Security Helpers

Use security assertions before trusting session-bound actions:

import {
  createOwlletMiniAppClient,
  assertOwlletMiniAppSecurity,
} from '@owllet/mini-app-sdk';

const client = createOwlletMiniAppClient();
const context = assertOwlletMiniAppSecurity(client.getContext(), {
  requireAuthenticatedSession: true,
  requireProfile: true,
});

await client.openExternalSafe('https://owllet.com/help');

Notes

• The client resolves window.OwlletMiniApp lazily, so it still works when the host bridge becomes available after module initialization.
• The SDK keeps compatibility with the current flat Flutter host payload, but exposes a normalized global interface for all future mini apps.
• The package ships a prepare script so local monorepo installs build dist/ automatically.
• Provider secrets and partner credentials must stay on Owllet backend, never in the hosted mini app.

See CONTRACT.md for the current bridge contract.