@pmate/bridge 0.1.8 → 0.1.10

package/README.md

@@ -1,5 +1,7 @@
 # Native application opening
 
+## Background
+
 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
@@ -8,3 +10,19 @@ 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.
+
+## Pending application notifications
+
+A designated native launcher can use `getPendingAppOpen()` and `onAppOpenRequested()` to receive a destination containing only `appId`, `notificationId`, and `origin`. Other WebViews cannot read this queue. Hosts without this capability reject the query; their existing notification routing continues unchanged.
+
+The launcher must first query the apps API with its current identity and Team, verify the application is visible, and resolve its deployed URL. Compare the resolved origin to the pending origin, then call `openApp({ url, notificationId })`. Native verifies that the same pending notification still exists and that the URL matches its origin, opens a new WebView, and consumes that pending request. A failed open retains the request until retry or expiry. Cancel stale API results when identity or Team changes.
+
+The target application receives the full notification through its own authenticated online session. The launcher does not receive notification bodies or another application's token.
+
+## Runtime environment
+
+Desktop hosts expose a preload bridge separately from mobile WebViews. Applications must not treat a missing mobile bridge as proof they are running in a browser.
+
+`getRuntimeInfo()` returns `environment` (`browser`, `electron`, or `native`), desktop `platform`, `appVersion`, `electronVersion` when supplied by the host, and `capabilities.openNotificationSettings`. Detection uses host injection, never the user agent; it is not an authorization boundary. Native device details remain available through `useDeviceInfo()`.
+
+`openNotificationSettings()` routes to the desktop host or native settings protocol and rejects on unavailable/failed operations. Electron notification permissions are managed by the OS: browser `Notification.permission` does not describe the main-process notification permission. Do not display browser permission prompts or claim OS permission is granted based on notification API support.

package/package.json

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

package/src/index.ts

@@ -3,6 +3,8 @@ export * from "./SafeAreaVarsProvider"
 export * from "./hooks"
 export {
   openApp,
+  getPendingAppOpen,
+  onAppOpenRequested,
   cancelAlarm,
   cancelAllAlarms,
   connectBluetoothDevice,
@@ -27,3 +29,6 @@ export {
   writeBluetooth,
 } from "./internal"
 export type * from "./types"
+
+export { getRuntimeInfo, openNotificationSettings } from "./runtime"
+export type { RuntimeInfo } from "./runtime"

package/src/internal.ts

@@ -253,5 +253,26 @@ export async function openApp(options: import("./types").OpenAppOptions): Promis
   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"))
   }
-  return requireBridge<import("./types").OpenAppResult>("container.openApp", { url: url.href })
+  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/runtime.ts

@@ -0,0 +1,33 @@
+/** Host identity comes from the preload/native bridge, never the user agent. */
+export interface RuntimeInfo {
+  environment: "browser" | "electron" | "native"
+  platform?: string
+  appVersion?: string
+  electronVersion?: string
+  capabilities: { openNotificationSettings: boolean }
+}
+type HostWindow = Window & {
+  PmateBridge?: { call: (name: string, params?: unknown) => Promise<unknown> }
+  pmateDesktop?: {
+    runtime?: { platform: string; appVersion: string; electronVersion: string }
+    notifications?: { openSettings?: () => Promise<boolean> }
+  }
+}
+export function getRuntimeInfo(): RuntimeInfo {
+  const host = typeof window === "undefined" ? undefined : window as HostWindow
+  if (host?.pmateDesktop) return {
+    environment: "electron", ...host.pmateDesktop.runtime,
+    capabilities: { openNotificationSettings: typeof host.pmateDesktop.notifications?.openSettings === "function" },
+  }
+  return { environment: host?.PmateBridge ? "native" : "browser", capabilities: { openNotificationSettings: !!host?.PmateBridge } }
+}
+/** Rejects when the host cannot confirm opening settings; never uses browser permission APIs. */
+export async function openNotificationSettings(): Promise<void> {
+  const host = typeof window === "undefined" ? undefined : window as HostWindow
+  if (getRuntimeInfo().environment === "electron") {
+    if (await host?.pmateDesktop?.notifications?.openSettings?.() !== true) throw new Error("当前桌面版本无法打开通知设置，请在系统设置中选择 Going Merry")
+    return
+  }
+  if (!host?.PmateBridge) throw new Error("当前环境不支持打开系统通知设置")
+  await host.PmateBridge.call("settings.open", { destination: "notification" })
+}

package/src/types.ts

@@ -209,5 +209,7 @@ export interface BluetoothDataEvent {
 }
 
 /** Opens a separate native WebView. The caller resolves the app URL via the apps API. */
-export interface OpenAppOptions { url: string }
+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 }