@molecule/app-badge

App badge/notification count interface for molecule.dev.

Provides a unified API for the app-icon badge across platforms: set, get, clear, increment/decrement, permission handling, and capability discovery. This is a core interface package — you register a platform implementation once with setProvider(), then call the module functions anywhere.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import type { BadgeProvider } from '@molecule/app-badge'
import { setProvider, setWithPermission, clear, isSupported } from '@molecule/app-badge'

// No prebuilt provider bond ships yet — supply your platform implementation
// (web: navigator.setAppBadge/clearAppBadge; RN/Capacitor: the platform badge API).
const myBadgeProvider = {} as BadgeProvider // stand-in for your implementation
setProvider(myBadgeProvider)

if (await isSupported()) {
  await setWithPermission(3) // requests permission if needed, then sets
  await clear()
}

Type

native

Installation

npm install @molecule/app-badge @molecule/app-bond @molecule/app-i18n

API

Interfaces

BadgeOptions

Options for setting the app icon badge (numeric count or text overlay).

interface BadgeOptions {
  /** Badge count (0 to clear) */
  count: number
  /** Badge text (if supported, overrides count) */
  text?: string
}

BadgeState

Current app badge state: count, platform support, and permission status.

interface BadgeState {
  /** Current badge count */
  count: number
  /** Whether badge is supported */
  supported: boolean
  /** Whether permission is granted */
  permissionGranted: boolean
}

BadgeCapabilities

Badge capabilities

interface BadgeCapabilities {
  /** Whether badges are supported */
  supported: boolean
  /** Whether permission is required */
  requiresPermission: boolean
  /** Maximum badge count (if limited) */
  maxCount?: number
  /** Whether text badges are supported */
  supportsText: boolean
  /** Whether badges can be cleared */
  canClear: boolean
}

BadgeProvider

Badge provider interface

interface BadgeProvider {
  /**
   * Set the app badge count
   * @param count - Badge count (0 to clear)
   */
  set(count: number): Promise<void>

  /**
   * Get the current badge count
   */
  get(): Promise<number>

  /**
   * Clear the badge (set to 0)
   */
  clear(): Promise<void>

  /**
   * Increment the badge count
   * @param amount - Amount to increment (default: 1)
   * @returns The new badge count after incrementing.
   */
  increment(amount?: number): Promise<number>

  /**
   * Decrement the badge count
   * @param amount - Amount to decrement (default: 1)
   * @returns The new badge count after decrementing.
   */
  decrement(amount?: number): Promise<number>

  /**
   * Check if badges are supported
   * @returns `true` if the platform supports badges.
   */
  isSupported(): Promise<boolean>

  /**
   * Get badge permission status
   * @returns The current permission status.
   */
  getPermissionStatus(): Promise<BadgePermissionStatus>

  /**
   * Request badge permission
   * @returns The resulting permission status after the request.
   */
  requestPermission(): Promise<BadgePermissionStatus>

  /**
   * Get badge state
   * @returns The current badge state (count, supported, permissionGranted).
   */
  getState(): Promise<BadgeState>

  /**
   * Get badge capabilities
   * @returns The platform's badge capabilities.
   */
  getCapabilities(): Promise<BadgeCapabilities>
}

Types

BadgePermissionStatus

Badge permission status

type BadgePermissionStatus = 'granted' | 'denied' | 'prompt' | 'unsupported'

Functions

setProvider(provider)

Set the badge provider

function setProvider(provider: BadgeProvider): void

• provider — BadgeProvider implementation

getProvider()

Get the current badge provider

function getProvider(): BadgeProvider

Returns: The bonded BadgeProvider.

hasProvider()

Check if a badge provider is bonded.

function hasProvider(): boolean

Returns: true if a provider is available.

set(count)

Set the app badge count.

function set(count: number): Promise<void>

• count — Badge count (0 to clear).

Returns: A promise that resolves when the badge count is set.

get()

Get the current badge count.

function get(): Promise<number>

Returns: The current count.

clear()

Clear the badge (set to 0).

function clear(): Promise<void>

Returns: A promise that resolves when the badge is cleared.

increment(amount)

Increment the badge count.

function increment(amount?: number): Promise<number>

• amount — Amount to increment (default: 1).

Returns: The new badge count after incrementing.

decrement(amount)

Decrement the badge count.

function decrement(amount?: number): Promise<number>

• amount — Amount to decrement (default: 1).

Returns: The new badge count after decrementing.

isSupported()

Check if badges are supported on this platform.

function isSupported(): Promise<boolean>

Returns: true if badges are supported, false if no provider is set or badges are unsupported.

getPermissionStatus()

Get badge permission status.

function getPermissionStatus(): Promise<BadgePermissionStatus>

Returns: The current permission status.

requestPermission()

Request badge permission.

function requestPermission(): Promise<BadgePermissionStatus>

Returns: The resulting permission status after the request.

getState()

Get badge state (count, supported, permissionGranted).

function getState(): Promise<BadgeState>

Returns: The current badge state.

getCapabilities()

Get the platform's badge capabilities.

function getCapabilities(): Promise<BadgeCapabilities>

Returns: The badge capabilities.

setWithPermission(count)

Ensure badge permission and set count

function setWithPermission(count: number): Promise<boolean>

• count — Badge count to set

Returns: Whether the badge was set successfully

syncBadge(getValue, interval)

Sync badge with a value (useful for reactive state)

function syncBadge(getValue: () => number | Promise<number>, interval?: number): () => void

• getValue — Function to get current count
• interval — Sync interval in milliseconds (default: 5000).

Returns: A cleanup function that stops the sync loop.

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-bond ^1.0.1
• @molecule/app-i18n ^1.0.1

Runtime Dependencies

• @molecule/app-bond

• @molecule/app-i18n

• No prebuilt provider bond exists for this interface yet — you MUST implement BadgeProvider and call setProvider() at startup. Every function except isSupported() (which returns false) throws until then. Ignore any runtime error text suggesting a -capacitor package; no such package ships.

• On the web, badge APIs (navigator.setAppBadge) only work in secure contexts and generally only for INSTALLED PWAs — in a plain browser tab expect getPermissionStatus() to report unsupported; design the feature to degrade (that is what setWithPermission() returning false means).

• Prefer setWithPermission(count) over raw set() — it handles the unsupported/denied/prompt permission states for you.

Translations

Translation strings are provided by @molecule/app-locales-badge.