@vvstream/bss-capabilities (0.1.0)

Published 2026-06-08 23:06:29 +08:00 by llbro

Setup this registry in your project .npmrc file:

@vvstream:registry=

To install the package using npm, run the following command:

npm install @vvstream/bss-capabilities@0.1.0

or add it to the package.json file:

"@vvstream/bss-capabilities": "0.1.0"

For more information on the npm registry, see the documentation.

BSS Capabilities

@vvstream/bss-capabilities is the browser-side SDK for capabilities exposed by the BSS Capacitor shell.

The shell owns native plugin registration and bridge injection. Business H5 apps should import helpers from this package instead of hand-writing window.Capacitor wrappers per app.

Flow

Register a capability in packages/server/src/capabilities/registry.ts.
The capability compiler adds native plugin dependencies, Android permissions, runtime keys, and build invalidation flags.
packages/mobile/scripts/sync-config.ts turns the compiled plan into package.json, capacitor.config.json, Android resources, permissions, and plugin registration.
RemoteCapacitorBridge.java injects the allowed plugin methods into remote business H5 pages.
Business apps import this SDK and call the capability helper.

Badge

Capacitor does not provide an official Badge plugin. The shell uses @capawesome/capacitor-badge.

import {
  isNativeBadgeSupported,
  requestNativeBadgePermission,
  setNativeBadgeCount,
} from '@vvstream/bss-capabilities/badge'

if (await isNativeBadgeSupported()) {
  await requestNativeBadgePermission()
  await setNativeBadgeCount(3)
}

Use setNativeBadgeCount(0) or clearNativeBadge() to clear the launcher badge.

Android launcher badge support depends on the user's launcher and device vendor. Always treat badge updates as best effort.

Helpers

The SDK currently wraps the plugins exposed by RemoteCapacitorBridge.java.

Module	Plugin	Main Helpers
`@vvstream/bss-capabilities/app`	`App`	`onNativeResume`, `onNativeAppStateChange`, `onNativeBackButton`, `getNativeLaunchUrl`
`@vvstream/bss-capabilities/notifications`	`LocalNotifications`	`requestNativeNotificationPermission`, `showNativeNotification`, `scheduleNativeNotifications`
`@vvstream/bss-capabilities/badge`	`Badge`	`setNativeBadgeCount`, `clearNativeBadge`, `isNativeBadgeSupported`
`@vvstream/bss-capabilities/clipboard`	`Clipboard`	`writeNativeClipboardText`, `readNativeClipboardText`
`@vvstream/bss-capabilities/native-file-save`	`NativeFileSave`	`saveNativeUrl`, `saveNativeBase64`, `openNativeUri`
`@vvstream/bss-capabilities/call-keep-awake`	`CallKeepAwake`	`startCallKeepAwake`, `stopCallKeepAwake`

Examples:

import { onNativeResume } from '@vvstream/bss-capabilities/app'

const listener = await onNativeResume(() => {
  // Invalidate page/query state here.
})

await listener?.remove()

import {
  requestNativeNotificationPermission,
  showNativeNotification,
} from '@vvstream/bss-capabilities/notifications'

if (await requestNativeNotificationPermission()) {
  await showNativeNotification({
    id: Date.now(),
    title: '订单状态更新',
    body: '您的订单状态已更新',
  })
}

import { saveNativeUrl } from '@vvstream/bss-capabilities/native-file-save'

await saveNativeUrl({
  url: fileUrl,
  fileName: 'receipt.pdf',
  mimeType: 'application/pdf',
  openAfterSave: true,
})

Business App Setup

Business apps consume this package from the private npm registry. Do not use Vite aliases or app-local wrappers for BSS native helpers.

{
  "dependencies": {
    "@vvstream/bss-capabilities": "^0.1.0"
  }
}

The repo .npmrc must route @vvstream to the Forgejo npm registry:

@vvstream:registry=https://code.vvstream.im/api/packages/llbro/npm/
//code.vvstream.im/api/packages/llbro/npm/:_authToken=${NODE_AUTH_TOKEN}

Publish:

NODE_AUTH_TOKEN=... npm publish --registry https://code.vvstream.im/api/packages/llbro/npm/

Adding A Capability

When adding a native capability, keep the layers separate:

registry.ts: declare the capability id, display metadata, native dependencies, permissions, runtime keys, and build invalidation.
types.ts: add the capability id to CapabilityId.
sync-config.ts: add optional npm dependencies and generated Capacitor config if the native plugin requires configuration.
RemoteCapacitorBridge.java: expose only the plugin methods that remote H5 pages are allowed to call.
packages/capabilities/src: add a typed browser helper.
Tests: cover the compiled capability plan and run Android sync/build for native plugin changes.

Business apps should not call window.Capacitor directly unless a capability helper does not exist yet.

Development dependencies

ID	Version
typescript	^6.0.3

Details

npm

2026-06-08 23:06:29 +08:00

latest

5.5 KiB

Assets (1)

bss-capabilities-0.1.0.tgz 5.5 KiB

Versions (1) View all

0.1.0

2026-06-08