@pmate/bridge 0.1.7 → 0.1.9

package/README.md

@@ -0,0 +1,10 @@
+# Native application opening
+
+The application catalog and deployment URL lookup belong to the apps API. The bridge only opens the resolved URL in a separate native WebView, leaving its caller alive.
+
+```tsx
+import { openApp, useIsPmate } from "@pmate/bridge"
+await openApp({ url: "https://issues.pmate.chat/" })
+```
+
+Requires a host implementing `container.openApp`. Resolves `{ opened: true }` after native presentation, not after page load. Rejects unsupported hosts and invalid URLs; callers must display the error. HTTPS and loopback HTTP are allowed; embedded URL credentials are rejected. No authentication token is added to the URL. Closing the child returns to its existing parent. Browser apps should use their explicit browser navigation path instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/bridge",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "files": [
     "src",
     "global.d.ts"

package/src/hooks.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useState } from "react"
 import { useOptionalPmateBridgeContext } from "./context"
 import {
+  openApp,
   getFallbackSafeInsets,
   getNotificationStatus,
   getPushToken,
@@ -111,3 +112,7 @@ export function useGetPushToken() {
     [context]
   )
 }
+
+export function useOpenApp() {
+  return openApp
+}

package/src/index.ts

@@ -2,6 +2,9 @@ export * from "./PmateBridgeProvider"
 export * from "./SafeAreaVarsProvider"
 export * from "./hooks"
 export {
+  openApp,
+  getPendingAppOpen,
+  onAppOpenRequested,
   cancelAlarm,
   cancelAllAlarms,
   connectBluetoothDevice,

package/src/internal.ts

@@ -245,3 +245,34 @@ export function onBluetoothEvent(
   }
   return (window as PmateWindow).PmateBridge!.on!(`bluetooth.${eventName}`, handler)
 }
+
+/** Native only. Errors are surfaced; this never navigates or replaces the caller. */
+export async function openApp(options: import("./types").OpenAppOptions): Promise<import("./types").OpenAppResult> {
+  const url = new URL(options.url)
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+  if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) || url.username || url.password) {
+    return Promise.reject(new Error("App URL must use HTTPS (or loopback HTTP) without credentials"))
+  }
+  const notificationId = options.notificationId
+  if (notificationId !== undefined && (!notificationId || notificationId.length > 512)) throw new Error("Invalid notification ID")
+  const result = await requireBridge<import("./types").OpenAppResult>("container.openApp", { url: url.href, ...(notificationId === undefined ? {} : { notificationId }) })
+  if (result?.opened !== true) throw new Error("Native app opening was not confirmed")
+  return result
+}
+
+/** Available only to a native host's designated launcher. Older hosts reject it. */
+export async function getPendingAppOpen(): Promise<import("./types").AppOpenIntent | null> {
+  const result = await requireBridge<import("./types").AppOpenIntent | null>("container.getPendingAppOpen")
+  if (result === null) return null
+  if (!result || typeof result.appId !== "string" || !result.appId || result.appId.length > 128
+    || typeof result.notificationId !== "string" || !result.notificationId || result.notificationId.length > 512
+    || typeof result.origin !== "string" || result.origin.length > 2048) throw new Error("Invalid application notification")
+  const origin = new URL(result.origin)
+  if (origin.protocol !== "https:" || origin.username || origin.password || origin.pathname !== "/" || origin.search || origin.hash) throw new Error("Invalid application notification origin")
+  return { appId: result.appId, notificationId: result.notificationId, origin: origin.origin }
+}
+
+/** A hint to re-read the pending intent; the event itself never supplies a URL to open. */
+export function onAppOpenRequested(handler: () => void): () => void {
+  return hasWindow() ? (window as PmateWindow).PmateBridge?.on?.("container.appOpenRequested", handler) ?? (() => {}) : () => {}
+}

package/src/types.ts

@@ -207,3 +207,9 @@ export interface BluetoothDataEvent {
   encoding: BluetoothBinaryEncoding
   receivedAt: number
 }
+
+/** Opens a separate native WebView. The caller resolves the app URL via the apps API. */
+export interface OpenAppOptions { url: string; notificationId?: string }
+export interface OpenAppResult { opened: true }
+/** Destination only; notification content is delivered to the target app after authentication. */
+export interface AppOpenIntent { appId: string; notificationId: string; origin: string }