@ambasada/miniapp 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CENTYSO (https://centyso.com)
+
+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

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @ambasada/miniapp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The page side of the Ambasada app's mini-app shell. Call `ready()` when your first screen is drawn, read the
+launch context, respect the safe areas and the host bar, open links and other mini apps, ask for haptics,
+silent sign-in and notifications. Outside the Ambasada app every call is a safe no-op, so the same page is
+also a plain website. Zero dependencies, ~3 KB.
+
+## Install
+
+```sh
+npm install @ambasada/miniapp
+```
+
+```ts
+import { ready, context, on } from "@ambasada/miniapp";
+
+ready(); // after the first render: the shell drops the splash
+```
+
+Or, with no build step, the `<script>` build the hub serves (defines `window.ambasada`):
+
+```html
+<script src="https://hub.ambasada.id/miniapp.js" defer></script>
+<script>addEventListener("DOMContentLoaded", () => window.ambasada?.ready?.())</script>
+```
+
+The `ambasada init` templates ship both forms, and `ambasada check` warns when a page uses neither.
+
+## API
+
+| Call | Inside the app | Outside |
+|---|---|---|
+| `ready()` | tells the shell the page is drawn (once; idempotent); sets the CSS variables | sets the CSS variables to 0 |
+| `shell()` | the injected `window.ambasadaShell` (version ≥ 2) | `null` |
+| `isInAmbasada()` | `true` (also for older builds that only set the `AmbasadaChat/` user agent) | `false` |
+| `context()` | `{ app, platform, safeArea, hostBar, theme, locale, user, location }`, with defaults for what an older shell omits | the defaults |
+| `capabilities()` | what this shell build supports (version 2: `openUrl`, `close`) | `[]` |
+| `applyCssVars()` | writes `--ambasada-safe-area-{top,bottom,left,right}` and `--ambasada-host-bar` on `<html>` and toggles the `in-ambasada` class | same, with zeros |
+| `openUrl(url)` | the system browser (verified apps) or a confirm sheet | a new tab |
+| `openApp(id, path?)` | another mini app on top of this one | `https://ambasada.id/a/<id><path>` in a new tab |
+| `close()` | closes this mini app | `history.back()` |
+| `share({ url?, text? })` | the system share sheet | the Web Share API, or nothing |
+| `haptics.impact(style?)`, `.notification(style?)`, `.selection()` | haptics | nothing |
+| `setTitle(title)` | the host bar's title and `document.title` | `document.title` |
+| `auth.getToken()` | a 60 s JWT (`aud` = your origin, `sub` = the Ambasada user id), verified apps with the `identity` scope; verify it against `https://hub.ambasada.id/.well-known/jwks.json` | rejects: fall back to Sign in with Ambasada |
+| `notifications.request()` | the shell's permission sheet → `{ enabled }`; your webhook gets `notifications_enabled` | `{ enabled: false }` |
+| `on("context", fn)` / `on("notification", fn)` | a new context (safe areas, theme) / a notification tap `{ id, url }`; returns the unsubscribe | never fires |
+| `mockEnv(overrides?)` | local development: installs a version 3 shell, records `messages`, answers requests, returns `{ messages, emit, uninstall }` | same (`ambasada dev` uses it) |
+
+Layout: pad your first screen by `var(--ambasada-safe-area-top, 0px) + var(--ambasada-host-bar, 0px)` at the top
+and `var(--ambasada-safe-area-bottom, 0px)` at the bottom. The `0px` fallbacks keep the page right on the web.
+
+## The bridge protocol
+
+The native app injects `window.ambasadaShell` before the page loads:
+
+```ts
+{ version: 3, platform: "ios" | "android" | "web", capabilities?: Capability[],
+  app: { id, tier } | null, safeArea: { top, bottom, left, right }, hostBar: number,
+  theme: { accent, scheme: "light" }, locale, user: { id, name, avatar } | null, location: LaunchLocation }
+```
+
+Version 2 shells (the current app) carry only `version`, `platform` and `safeArea`; the SDK falls back to the
+v2 messages (`chrome`, `open`) for them.
+
+**Page → app**: one JSON message per call, through `webkit.messageHandlers.ambasada.postMessage(obj)` on iOS or
+`window.ambasada.postMessage(json)` on Android:
+
+| Message | Fields |
+|---|---|
+| `ready` | |
+| `openUrl` | `url` |
+| `openApp` | `app`, `path?` |
+| `close` | |
+| `share` | `url?`, `text?` |
+| `haptic` | `kind: impact \| notification \| selection`, `style?` |
+| `title` | `title` |
+| `request` | `id`, `method: auth.getToken \| notifications.request` |
+| `chrome` (v2) | `header?`, `tabs?`, `title?`, `back?`, `statusBar?` |
+| `open` (v2) | `url`, `mode: in-app \| external \| sheet` |
+
+**App → page**: `CustomEvent`s dispatched on `window`:
+
+| Event | `detail` |
+|---|---|
+| `ambasada:reply` | `{ id, result }` or `{ id, error }`, answering a `request` (the SDK gives up after 15 s) |
+| `ambasada:context` | a (partial) new `ShellContext`; the SDK merges it into `window.ambasadaShell` and re-applies the CSS variables |
+| `ambasada:notification` | `{ id, url }`, a notification tapped while this app is open |
+
+The `<script>` build merges into an existing `window.ambasada` (Android's bridge object) instead of replacing
+it, so `window.ambasada.postMessage` keeps working next to `window.ambasada.ready()`.
+
+## Build
+
+`node scripts/build.mjs` writes `dist/index.js` (ESM), `dist/miniapp.js` (classic script, global `ambasada`) and
+`dist/index.d.ts`. The hub serves `dist/miniapp.js` at `https://hub.ambasada.id/miniapp.js`.
+
+MIT, CENTYSO.

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+/**
+ * @ambasada/miniapp: the page side of the Ambasada app's mini-app shell (docs/MINI-APPS.md §6).
+ *
+ * The native app injects `window.ambasadaShell` before the page loads (version 3; version 2 shells
+ * carry only `version`, `platform` and `safeArea`). Pages talk back over `webkit.messageHandlers.ambasada`
+ * (iOS) or `window.ambasada.postMessage` (Android). The shell answers requests and pushes events by
+ * dispatching `CustomEvent`s on `window`: `ambasada:reply` ({ id, result | error }), `ambasada:context`
+ * (a new context), `ambasada:notification` ({ id, url }).
+ *
+ * Outside the Ambasada app every call is a safe no-op (promises resolve to a "not in Ambasada" answer),
+ * so the same page is also a plain website. No dependencies; built as ESM and as a classic <script>.
+ */
+export interface SafeArea {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+export type LaunchLocation = {
+    type: "launcher";
+} | {
+    type: "notification";
+    id: string;
+    url: string;
+} | {
+    type: "link";
+    url: string;
+    referrer?: string;
+} | {
+    type: "app";
+    referrer: string;
+} | {
+    type: "share";
+};
+/** What the shell knows about this launch. `user` is display data only: trust comes from `auth.getToken()`. */
+export interface ShellContext {
+    app: {
+        id: string;
+        tier: "unlisted" | "listed" | "verified" | "first_party";
+    } | null;
+    platform: "ios" | "android" | "web";
+    safeArea: SafeArea;
+    /** The host bar's height in CSS px (0 on version 2 shells, which draw no bar). */
+    hostBar: number;
+    theme: {
+        accent: string;
+        scheme: "light";
+    };
+    locale: string;
+    user: {
+        id: string;
+        name: string | null;
+        avatar: string | null;
+    } | null;
+    location: LaunchLocation;
+}
+export type Capability = "ready" | "openUrl" | "openApp" | "close" | "share" | "haptics" | "title" | "auth.getToken" | "notifications";
+/** What the native app injects. Version 3 fills everything; version 2 only `version`, `platform`, `safeArea`. */
+export interface InjectedShell extends Partial<ShellContext> {
+    version: number;
+    platform: "ios" | "android" | "web";
+    capabilities?: Capability[];
+}
+type Message = {
+    type: "ready";
+} | {
+    type: "openUrl";
+    url: string;
+} | {
+    type: "openApp";
+    app: string;
+    path?: string;
+} | {
+    type: "close";
+} | {
+    type: "share";
+    url?: string;
+    text?: string;
+} | {
+    type: "haptic";
+    kind: "impact" | "notification" | "selection";
+    style?: string;
+} | {
+    type: "title";
+    title: string;
+} | {
+    type: "request";
+    id: string;
+    method: "auth.getToken" | "notifications.request";
+} | {
+    type: "chrome";
+    header?: "shown" | "hidden";
+    tabs?: "shown" | "hidden";
+    title?: string;
+    back?: "history" | "close" | "none";
+    statusBar?: "light" | "dark";
+} | {
+    type: "open";
+    url: string;
+    mode: "in-app" | "external" | "sheet";
+};
+/** The injected shell, if this page runs inside the Ambasada app (version 2 or newer). */
+export declare function shell(): InjectedShell | null;
+/** Inside the Ambasada app? Also true for older app builds that only set the user agent. */
+export declare function isInAmbasada(): boolean;
+/** The launch context, with defaults for whatever an older shell did not provide. */
+export declare function context(): ShellContext;
+/** What this shell build supports. Version 2 shells: open links and close only. */
+export declare function capabilities(): Capability[];
+/** Writes the shell's safe areas and host bar as CSS variables on <html>, and marks it `in-ambasada`. */
+export declare function applyCssVars(): void;
+/**
+ * Tell the shell the page is drawn: it drops the splash. Call it once, as soon as your first screen is
+ * visible (after the first render, not after data loads). Idempotent; a no-op outside the app.
+ */
+export declare function ready(): void;
+/** Open another origin: the system browser (verified apps) or a confirm sheet first (others). Outside the app: a new tab. */
+export declare function openUrl(url: string): void;
+/** Open another mini app on top of this one; closing it comes back here. Outside the app: the app's web link. */
+export declare function openApp(appId: string, path?: string): void;
+/** Close this mini app. Outside the app: history.back(). */
+export declare function close(): void;
+/** The system share sheet with the app's link. Falls back to the Web Share API, then to nothing. */
+export declare function share(data?: {
+    url?: string;
+    text?: string;
+}): Promise<void>;
+export declare const haptics: {
+    impact(style?: "light" | "medium" | "heavy"): void;
+    notification(style?: "success" | "warning" | "error"): void;
+    selection(): void;
+};
+/** The host bar's title (and document.title). Keep it short; the bar shows about 24 characters. */
+export declare function setTitle(title: string): void;
+export declare const auth: {
+    /**
+     * Silent sign-in (verified apps with the `identity` scope): a short-lived JWT (60 s, `aud` = this origin,
+     * `sub` = the Ambasada user id) to verify on your server against https://hub.ambasada.id/.well-known/jwks.json.
+     * Rejects outside the app or when the app is not verified: fall back to Sign in with Ambasada.
+     */
+    getToken(): Promise<{
+        token: string;
+        expires_at: string;
+    }>;
+    /**
+     * Silent sign-in in one call: gets a shell token and POSTs it to your server (`/api/auth/shell` in the templates,
+     * `village.auth.shell(req)` in @ambasada/sdk), which sets your session cookie. Resolves the server's `user`, or
+     * null when the shell can't do it (outside the app, an older app, an app that is not verified): then show
+     * "Sign in with Ambasada". Rejects when your server refuses the token.
+     */
+    signIn<User = unknown>(options?: {
+        endpoint?: string;
+    }): Promise<User | null>;
+};
+export declare const notifications: {
+    /**
+     * Ask to send this person notifications. Call it from a tap. The shell shows its own sheet; on accept
+     * your webhook receives `notifications_enabled` with the token (docs/MINI-APPS.md §7).
+     * Outside the app, or without the capability: `{ enabled: false }`.
+     */
+    request(): Promise<{
+        enabled: boolean;
+    }>;
+};
+export type ShellEvent = "context" | "notification";
+/** Listen for a new context (safe areas, theme) or a notification tap while this app is open ({ id, url }). Returns the unsubscribe. */
+export declare function on(event: "context", handler: (ctx: ShellContext) => void): () => void;
+export declare function on(event: "notification", handler: (n: {
+    id: string;
+    url: string;
+}) => void): () => void;
+/**
+ * Local development: pretend to be inside the Ambasada app. Installs a version 3 shell with the given
+ * context, records every message in `messages`, answers requests (`getToken` → a fake token, or with `issuer`
+ * (the `ambasada dev` mock URL) a real signed one from `<issuer>/dev/shell-token`; `request()` → enabled)
+ * and returns `emit` to fire shell events. The templates call it on `?ambasada_shell=mock` under `ambasada dev`.
+ */
+export declare function mockEnv(overrides?: Partial<ShellContext> & {
+    version?: number;
+    capabilities?: Capability[];
+    issuer?: string;
+    answers?: Partial<Record<"auth.getToken" | "notifications.request", unknown | Error>>;
+}): {
+    messages: Message[];
+    emit: (event: ShellEvent, detail: unknown) => boolean;
+    uninstall: () => void;
+};
+/** Everything as one object, for the <script> build (`window.ambasada.ready()`). */
+declare const _default: {
+    shell: typeof shell;
+    isInAmbasada: typeof isInAmbasada;
+    context: typeof context;
+    capabilities: typeof capabilities;
+    applyCssVars: typeof applyCssVars;
+    ready: typeof ready;
+    openUrl: typeof openUrl;
+    openApp: typeof openApp;
+    close: typeof close;
+    share: typeof share;
+    haptics: {
+        impact(style?: "light" | "medium" | "heavy"): void;
+        notification(style?: "success" | "warning" | "error"): void;
+        selection(): void;
+    };
+    setTitle: typeof setTitle;
+    auth: {
+        /**
+         * Silent sign-in (verified apps with the `identity` scope): a short-lived JWT (60 s, `aud` = this origin,
+         * `sub` = the Ambasada user id) to verify on your server against https://hub.ambasada.id/.well-known/jwks.json.
+         * Rejects outside the app or when the app is not verified: fall back to Sign in with Ambasada.
+         */
+        getToken(): Promise<{
+            token: string;
+            expires_at: string;
+        }>;
+        /**
+         * Silent sign-in in one call: gets a shell token and POSTs it to your server (`/api/auth/shell` in the templates,
+         * `village.auth.shell(req)` in @ambasada/sdk), which sets your session cookie. Resolves the server's `user`, or
+         * null when the shell can't do it (outside the app, an older app, an app that is not verified): then show
+         * "Sign in with Ambasada". Rejects when your server refuses the token.
+         */
+        signIn<User = unknown>(options?: {
+            endpoint?: string;
+        }): Promise<User | null>;
+    };
+    notifications: {
+        /**
+         * Ask to send this person notifications. Call it from a tap. The shell shows its own sheet; on accept
+         * your webhook receives `notifications_enabled` with the token (docs/MINI-APPS.md §7).
+         * Outside the app, or without the capability: `{ enabled: false }`.
+         */
+        request(): Promise<{
+            enabled: boolean;
+        }>;
+    };
+    on: typeof on;
+    mockEnv: typeof mockEnv;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,241 @@
+// ../miniapp/src/index.ts
+var DEFAULT_SAFE_AREA = { top: 0, bottom: 0, left: 0, right: 0 };
+var NOT_IN_AMBASADA = "not inside the Ambasada app";
+var win = () => typeof window === "undefined" ? null : window;
+function shell() {
+  const s = win()?.ambasadaShell;
+  return s && typeof s.version === "number" && s.version >= 2 ? s : null;
+}
+function isInAmbasada() {
+  const w = win();
+  if (!w) return false;
+  return shell() !== null || /AmbasadaChat\//.test(w.navigator.userAgent);
+}
+function context() {
+  const s = shell();
+  return {
+    app: s?.app ?? null,
+    platform: s?.platform ?? "web",
+    safeArea: { ...DEFAULT_SAFE_AREA, ...s?.safeArea ?? {} },
+    hostBar: s?.hostBar ?? 0,
+    theme: s?.theme ?? { accent: "#FF002E", scheme: "light" },
+    locale: s?.locale ?? win()?.navigator.language ?? "en",
+    user: s?.user ?? null,
+    location: s?.location ?? { type: "launcher" }
+  };
+}
+function capabilities() {
+  const s = shell();
+  if (!s) return [];
+  if (s.capabilities) return s.capabilities;
+  return s.version >= 3 ? ["ready", "openUrl", "openApp", "close", "share", "haptics", "title", "auth.getToken", "notifications"] : ["openUrl", "close"];
+}
+var has = (c) => capabilities().includes(c);
+function post(message) {
+  const w = win();
+  if (!w || !isInAmbasada()) return false;
+  if (w.webkit?.messageHandlers?.ambasada) w.webkit.messageHandlers.ambasada.postMessage(message);
+  else if (w.ambasada?.postMessage) w.ambasada.postMessage(JSON.stringify(message));
+  else return false;
+  return true;
+}
+var seq = 0;
+function request(method, timeoutMs = 15e3) {
+  const w = win();
+  return new Promise((resolve, reject) => {
+    const id = `${Date.now().toString(36)}-${++seq}`;
+    const timer = setTimeout(() => {
+      w?.removeEventListener("ambasada:reply", onReply);
+      reject(new Error(`${method}: the Ambasada app did not answer`));
+    }, timeoutMs);
+    const onReply = (e) => {
+      const d = e.detail;
+      if (!d || d.id !== id) return;
+      clearTimeout(timer);
+      w?.removeEventListener("ambasada:reply", onReply);
+      if (d.error) reject(new Error(d.error));
+      else resolve(d.result);
+    };
+    w?.addEventListener("ambasada:reply", onReply);
+    if (!post({ type: "request", id, method })) {
+      clearTimeout(timer);
+      w?.removeEventListener("ambasada:reply", onReply);
+      reject(new Error(NOT_IN_AMBASADA));
+    }
+  });
+}
+function applyCssVars() {
+  const w = win();
+  if (!w) return;
+  const root = w.document.documentElement;
+  const ctx = context();
+  for (const side of ["top", "bottom", "left", "right"]) root.style.setProperty(`--ambasada-safe-area-${side}`, `${ctx.safeArea[side]}px`);
+  root.style.setProperty("--ambasada-host-bar", `${ctx.hostBar}px`);
+  root.classList.toggle("in-ambasada", isInAmbasada());
+}
+var readySent = false;
+function ready() {
+  applyCssVars();
+  if (readySent) return;
+  readySent = true;
+  if (has("ready")) post({ type: "ready" });
+  else if (shell()?.version === 2) post({ type: "chrome", header: "hidden", tabs: "hidden", back: "none", statusBar: "dark" });
+}
+function openUrl(url) {
+  if (has("openUrl") && shell().version >= 3) post({ type: "openUrl", url });
+  else if (shell()?.version === 2) post({ type: "open", url, mode: "external" });
+  else win()?.open(url, "_blank", "noopener");
+}
+function openApp(appId, path = "/") {
+  if (has("openApp")) post({ type: "openApp", app: appId, path });
+  else win()?.open(`https://ambasada.id/a/${encodeURIComponent(appId)}${path.startsWith("/") ? path : `/${path}`}`, "_blank", "noopener");
+}
+function close() {
+  if (has("close")) post({ type: "close" });
+  else win()?.history.back();
+}
+async function share(data = {}) {
+  if (has("share")) {
+    post({ type: "share", ...data });
+    return;
+  }
+  const w = win();
+  if (w?.navigator.share) await w.navigator.share({ url: data.url ?? w.location.href, text: data.text }).catch(() => void 0);
+}
+var haptics = {
+  impact(style = "light") {
+    if (has("haptics")) post({ type: "haptic", kind: "impact", style });
+  },
+  notification(style = "success") {
+    if (has("haptics")) post({ type: "haptic", kind: "notification", style });
+  },
+  selection() {
+    if (has("haptics")) post({ type: "haptic", kind: "selection" });
+  }
+};
+function setTitle(title) {
+  const w = win();
+  if (w) w.document.title = title;
+  if (has("title")) post({ type: "title", title });
+  else if (shell()?.version === 2) post({ type: "chrome", title });
+}
+var auth = {
+  /**
+   * Silent sign-in (verified apps with the `identity` scope): a short-lived JWT (60 s, `aud` = this origin,
+   * `sub` = the Ambasada user id) to verify on your server against https://hub.ambasada.id/.well-known/jwks.json.
+   * Rejects outside the app or when the app is not verified: fall back to Sign in with Ambasada.
+   */
+  getToken() {
+    if (!has("auth.getToken")) return Promise.reject(new Error(has("ready") ? "silent sign-in is not available for this app" : NOT_IN_AMBASADA));
+    return request("auth.getToken");
+  },
+  /**
+   * Silent sign-in in one call: gets a shell token and POSTs it to your server (`/api/auth/shell` in the templates,
+   * `village.auth.shell(req)` in @ambasada/sdk), which sets your session cookie. Resolves the server's `user`, or
+   * null when the shell can't do it (outside the app, an older app, an app that is not verified): then show
+   * "Sign in with Ambasada". Rejects when your server refuses the token.
+   */
+  async signIn(options = {}) {
+    const w = win();
+    if (!w || !has("auth.getToken")) return null;
+    let token;
+    try {
+      token = (await request("auth.getToken")).token;
+    } catch {
+      return null;
+    }
+    const res = await w.fetch(options.endpoint ?? "/api/auth/shell", { method: "POST", credentials: "same-origin", headers: { "content-type": "application/json" }, body: JSON.stringify({ token }) });
+    if (!res.ok) throw new Error(`silent sign-in refused (${res.status})`);
+    return (await res.json()).user;
+  }
+};
+var notifications = {
+  /**
+   * Ask to send this person notifications. Call it from a tap. The shell shows its own sheet; on accept
+   * your webhook receives `notifications_enabled` with the token (docs/MINI-APPS.md §7).
+   * Outside the app, or without the capability: `{ enabled: false }`.
+   */
+  request() {
+    if (!has("notifications")) return Promise.resolve({ enabled: false });
+    return request("notifications.request");
+  }
+};
+function on(event, handler) {
+  const w = win();
+  if (!w) return () => void 0;
+  const listener = (e) => {
+    const detail = e.detail;
+    if (event === "context") {
+      if (detail && typeof detail === "object") Object.assign(w.ambasadaShell ?? (w.ambasadaShell = { version: 3, platform: "web" }), detail);
+      applyCssVars();
+      handler(context());
+    } else handler(detail);
+  };
+  w.addEventListener(`ambasada:${event}`, listener);
+  return () => w.removeEventListener(`ambasada:${event}`, listener);
+}
+function mockEnv(overrides = {}) {
+  const w = win();
+  if (!w) throw new Error("mockEnv needs a window");
+  const { version = 3, capabilities: caps, answers = {}, issuer, ...ctx } = overrides;
+  const messages = [];
+  w.ambasadaShell = {
+    version,
+    platform: "ios",
+    safeArea: { top: 59, bottom: 34, left: 0, right: 0 },
+    hostBar: 44,
+    theme: { accent: "#FF002E", scheme: "light" },
+    locale: "ro-RO",
+    app: { id: "my-company", tier: "unlisted" },
+    user: { id: "user_fake", name: "Fake Visitor", avatar: null },
+    location: { type: "launcher" },
+    ...caps ? { capabilities: caps } : {},
+    ...ctx
+  };
+  w.ambasada = {
+    postMessage(raw) {
+      const m = JSON.parse(raw);
+      messages.push(m);
+      if (m.type === "request") {
+        const reply = (a) => {
+          const detail = a instanceof Error ? { id: m.id, error: a.message } : { id: m.id, result: a };
+          setTimeout(() => w.dispatchEvent(new CustomEvent("ambasada:reply", { detail })), 0);
+        };
+        if (m.method in answers) reply(answers[m.method]);
+        else if (m.method === "auth.getToken" && issuer) {
+          w.fetch(`${issuer.replace(/\/+$/, "")}/dev/shell-token?aud=${encodeURIComponent(w.location.origin)}`).then((r) => r.ok ? r.json() : Promise.reject(new Error(`mock issuer answered ${r.status}`))).then(reply, reply);
+        } else reply(m.method === "auth.getToken" ? { token: "fake.jwt.token", expires_at: new Date(Date.now() + 6e4).toISOString() } : { enabled: true });
+      }
+    }
+  };
+  readySent = false;
+  applyCssVars();
+  const emit = (event, detail) => w.dispatchEvent(new CustomEvent(`ambasada:${event}`, { detail }));
+  const uninstall = () => {
+    delete w.ambasadaShell;
+    delete w.ambasada;
+    readySent = false;
+    applyCssVars();
+  };
+  return { messages, emit, uninstall };
+}
+var index_default = { shell, isInAmbasada, context, capabilities, applyCssVars, ready, openUrl, openApp, close, share, haptics, setTitle, auth, notifications, on, mockEnv };
+export {
+  applyCssVars,
+  auth,
+  capabilities,
+  close,
+  context,
+  index_default as default,
+  haptics,
+  isInAmbasada,
+  mockEnv,
+  notifications,
+  on,
+  openApp,
+  openUrl,
+  ready,
+  setTitle,
+  share,
+  shell
+};

package/dist/miniapp.js

@@ -0,0 +1,7 @@
+"use strict";var __ambasadaMiniapp=(()=>{var x=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var F=Object.getOwnPropertyNames;var R=Object.prototype.hasOwnProperty;var D=(e,t)=>{for(var n in t)x(e,n,{get:t[n],enumerable:!0})},N=(e,t,n,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of F(t))!R.call(e,s)&&s!==n&&x(e,s,{get:()=>t[s],enumerable:!(a=O(t,s))||a.enumerable});return e};var W=e=>N(x({},"__esModule",{value:!0}),e);var z={};D(z,{applyCssVars:()=>f,auth:()=>M,capabilities:()=>E,close:()=>P,context:()=>v,default:()=>V,haptics:()=>L,isInAmbasada:()=>y,mockEnv:()=>B,notifications:()=>q,on:()=>j,openApp:()=>$,openUrl:()=>C,ready:()=>T,setTitle:()=>_,share:()=>U,shell:()=>c});var H={top:0,bottom:0,left:0,right:0},A="not inside the Ambasada app",i=()=>typeof window>"u"?null:window;function c(){let e=i()?.ambasadaShell;return e&&typeof e.version=="number"&&e.version>=2?e:null}function y(){let e=i();return e?c()!==null||/AmbasadaChat\//.test(e.navigator.userAgent):!1}function v(){let e=c();return{app:e?.app??null,platform:e?.platform??"web",safeArea:{...H,...e?.safeArea??{}},hostBar:e?.hostBar??0,theme:e?.theme??{accent:"#FF002E",scheme:"light"},locale:e?.locale??i()?.navigator.language??"en",user:e?.user??null,location:e?.location??{type:"launcher"}}}function E(){let e=c();return e?e.capabilities?e.capabilities:e.version>=3?["ready","openUrl","openApp","close","share","haptics","title","auth.getToken","notifications"]:["openUrl","close"]:[]}var o=e=>E().includes(e);function r(e){let t=i();if(!t||!y())return!1;if(t.webkit?.messageHandlers?.ambasada)t.webkit.messageHandlers.ambasada.postMessage(e);else if(t.ambasada?.postMessage)t.ambasada.postMessage(JSON.stringify(e));else return!1;return!0}var J=0;function k(e,t=15e3){let n=i();return new Promise((a,s)=>{let l=`${Date.now().toString(36)}-${++J}`,m=setTimeout(()=>{n?.removeEventListener("ambasada:reply",d),s(new Error(`${e}: the Ambasada app did not answer`))},t),d=S=>{let h=S.detail;!h||h.id!==l||(clearTimeout(m),n?.removeEventListener("ambasada:reply",d),h.error?s(new Error(h.error)):a(h.result))};n?.addEventListener("ambasada:reply",d),r({type:"request",id:l,method:e})||(clearTimeout(m),n?.removeEventListener("ambasada:reply",d),s(new Error(A)))})}function f(){let e=i();if(!e)return;let t=e.document.documentElement,n=v();for(let a of["top","bottom","left","right"])t.style.setProperty(`--ambasada-safe-area-${a}`,`${n.safeArea[a]}px`);t.style.setProperty("--ambasada-host-bar",`${n.hostBar}px`),t.classList.toggle("in-ambasada",y())}var b=!1;function T(){f(),!b&&(b=!0,o("ready")?r({type:"ready"}):c()?.version===2&&r({type:"chrome",header:"hidden",tabs:"hidden",back:"none",statusBar:"dark"}))}function C(e){o("openUrl")&&c().version>=3?r({type:"openUrl",url:e}):c()?.version===2?r({type:"open",url:e,mode:"external"}):i()?.open(e,"_blank","noopener")}function $(e,t="/"){o("openApp")?r({type:"openApp",app:e,path:t}):i()?.open(`https://ambasada.id/a/${encodeURIComponent(e)}${t.startsWith("/")?t:`/${t}`}`,"_blank","noopener")}function P(){o("close")?r({type:"close"}):i()?.history.back()}async function U(e={}){if(o("share")){r({type:"share",...e});return}let t=i();t?.navigator.share&&await t.navigator.share({url:e.url??t.location.href,text:e.text}).catch(()=>{})}var L={impact(e="light"){o("haptics")&&r({type:"haptic",kind:"impact",style:e})},notification(e="success"){o("haptics")&&r({type:"haptic",kind:"notification",style:e})},selection(){o("haptics")&&r({type:"haptic",kind:"selection"})}};function _(e){let t=i();t&&(t.document.title=e),o("title")?r({type:"title",title:e}):c()?.version===2&&r({type:"chrome",title:e})}var M={getToken(){return o("auth.getToken")?k("auth.getToken"):Promise.reject(new Error(o("ready")?"silent sign-in is not available for this app":A))},async signIn(e={}){let t=i();if(!t||!o("auth.getToken"))return null;let n;try{n=(await k("auth.getToken")).token}catch{return null}let a=await t.fetch(e.endpoint??"/api/auth/shell",{method:"POST",credentials:"same-origin",headers:{"content-type":"application/json"},body:JSON.stringify({token:n})});if(!a.ok)throw new Error(`silent sign-in refused (${a.status})`);return(await a.json()).user}},q={request(){return o("notifications")?k("notifications.request"):Promise.resolve({enabled:!1})}};function j(e,t){let n=i();if(!n)return()=>{};let a=s=>{let l=s.detail;e==="context"?(l&&typeof l=="object"&&Object.assign(n.ambasadaShell??(n.ambasadaShell={version:3,platform:"web"}),l),f(),t(v())):t(l)};return n.addEventListener(`ambasada:${e}`,a),()=>n.removeEventListener(`ambasada:${e}`,a)}function B(e={}){let t=i();if(!t)throw new Error("mockEnv needs a window");let{version:n=3,capabilities:a,answers:s={},issuer:l,...m}=e,d=[];return t.ambasadaShell={version:n,platform:"ios",safeArea:{top:59,bottom:34,left:0,right:0},hostBar:44,theme:{accent:"#FF002E",scheme:"light"},locale:"ro-RO",app:{id:"my-company",tier:"unlisted"},user:{id:"user_fake",name:"Fake Visitor",avatar:null},location:{type:"launcher"},...a?{capabilities:a}:{},...m},t.ambasada={postMessage(w){let p=JSON.parse(w);if(d.push(p),p.type==="request"){let g=u=>{let I=u instanceof Error?{id:p.id,error:u.message}:{id:p.id,result:u};setTimeout(()=>t.dispatchEvent(new CustomEvent("ambasada:reply",{detail:I})),0)};p.method in s?g(s[p.method]):p.method==="auth.getToken"&&l?t.fetch(`${l.replace(/\/+$/,"")}/dev/shell-token?aud=${encodeURIComponent(t.location.origin)}`).then(u=>u.ok?u.json():Promise.reject(new Error(`mock issuer answered ${u.status}`))).then(g,g):g(p.method==="auth.getToken"?{token:"fake.jwt.token",expires_at:new Date(Date.now()+6e4).toISOString()}:{enabled:!0})}}},b=!1,f(),{messages:d,emit:(w,p)=>t.dispatchEvent(new CustomEvent(`ambasada:${w}`,{detail:p})),uninstall:()=>{delete t.ambasadaShell,delete t.ambasada,b=!1,f()}}}var V={shell:c,isInAmbasada:y,context:v,capabilities:E,applyCssVars:f,ready:T,openUrl:C,openApp:$,close:P,share:U,haptics:L,setTitle:_,auth:M,notifications:q,on:j,mockEnv:B};return W(z);})();
+(function (g) {
+  var prev = g.ambasada, api = Object.assign({}, __ambasadaMiniapp.default, __ambasadaMiniapp);
+  delete api.default;
+  if (prev && typeof prev.postMessage === 'function') api.postMessage = function (m) { return prev.postMessage(m); };
+  g.ambasada = api;
+})(typeof window !== 'undefined' ? window : globalThis);

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@ambasada/miniapp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "description": "Run your web app inside the Ambasada app as a mini app: ready(), shell context, safe areas, open links, haptics, notifications. Zero dependencies; also a <script> build.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "esbuild": "^0.28.2",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.12"
+  },
+  "author": "CENTYSO (https://centyso.com)",
+  "homepage": "https://ambasada.id",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ambasada/cli.git",
+    "directory": "packages/miniapp"
+  },
+  "bugs": {
+    "url": "https://github.com/ambasada/cli/issues"
+  },
+  "keywords": [
+    "ambasada",
+    "mini-app",
+    "webview"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p .",
+    "test": "vitest run"
+  }
 }