app-sdk

The partner SDK for the chat App Store. A mini-app is a web app, and every client — web, and iOS/Android through their native webview bridge — hosts it and speaks one protocol. So a partner writes one build that runs everywhere; there is no separate iOS or Android SDK to maintain.

The SDK is the app's side of that protocol. It never sees the conversation — the chat is end-to-end encrypted and the host hands the app only what the user explicitly shares. The host mediates every call: it checks the app's capability, prompts for consent, runs the payment rails, and does the platform-native thing behind a single verb (a web payment request, Apple Pay, Google Pay).

It speaks the App Store protocol (spec revision 1): the same capability names and decisions the host enforces, so the SDK and the host never disagree.

New here? Start with the integration guide — the manifest, capabilities and consent, the verbs, and a worked minimal mini-app.

Install

bun add @myzonerocks/app-sdk

Use

import { connect, AppError, Capabilities } from '@myzonerocks/app-sdk'

const app = await connect({ hostOrigin: 'https://host.example' })

// A per-app scoped identity — never the real account.
console.log(app.session.user.displayName)

// Post a card into the thread.
await app.card({
  title: 'Split the ride?',
  actions: [{ id: 'split', label: 'Split 4 ways', style: 'primary' }],
})

// Ask for money; the host runs consent and the rails. Amount is minor units as a
// string, so precision is never lost.
try {
  const r = await app.requestPayment({ to: 'user_2', amount: '1250', token: 'USD', memo: 'ride' })
  if (r.status === 'settled') app.card({ title: 'Settled — thanks!' })
} catch (e) {
  if (e instanceof AppError && e.code === 'denied') { /* the user declined */ }
}

// Ask the user to share one thing; the host prompts and returns only that.
const ctx = await app.getContext('location')

app.close()

Surface

connect(options) handshakes and returns an App:

• app.session — the scoped user, locale, theme, and the capabilities granted at install.
• app.has(capability) — whether a capability was granted.
• app.card(input) — post a card into the thread.
• app.requestPayment(input) — pay / request-to-pay via the host's rails.
• app.getContext(scope) — request identity | location | selection, with consent.
• app.openSheet(size?) — open the app's UI in a host sheet.
• app.getState() / app.setState(data) — persist your app's state across close/reopen, scoped to the app + user + conversation (stateful apps; no capability needed).
• app.act(input) — (agents) propose or take an action within a granted scope.
• app.on(event, handler) — subscribe to host events (e.g. a payment settling).
• app.close(result?) / app.disconnect().

Every request is correlated to its reply, times out a silent host, and rejects with an AppError whose code (denied, not_configured, timeout, …) is stable to branch on.

Testing / native hosts

connect takes an optional transport, so the SDK runs against a mock host with no DOM (see test/) and a native host (WKWebView, Android WebView) can supply its own bridge while the app code stays identical.

License

See LICENSE.