@aistudioapk/notifications

Local notifications for apps built with AIStudioAPK — renders web toasts in the browser for testing, native Android notifications in your APK automatically.

How it works

Write your notification logic once using this library. In the browser it shows styled toast popups so you can test everything normally. When you build your APK with AIStudioAPK, the platform detects the library and automatically injects a native Android bridge — no code changes needed.

| Environment | Behaviour | |-------------|-----------| | Browser | Styled toast popup in the corner of the page | | APK (AIStudioAPK build) | Native Android notification |

If the library is not found in your project, the build skips injection entirely — no extra permissions, no bloat added to your APK.

Installation

npm install @aistudioapk/notifications

Quick start

import { notify } from '@aistudioapk/notifications'

// Show a notification immediately
await notify.show({
  title: 'Download complete',
  body: 'Your file is ready.',
  data: { screen: '/results' }
})

// Schedule one for later
await notify.schedule({
  title: 'Daily reminder',
  body: 'Check your dashboard',
  triggerAt: Date.now() + 24 * 60 * 60 * 1000,
  repeat: 'daily'
})

// Handle taps — register once on app startup
notify.onTap((data) => {
  console.log('Notification tapped:', data)
})

API

notify.show(options) → Promise<void>

Show a notification immediately.

| Option | Type | Required | Description | |--------|------|----------|-------------| | title | string | ✅ | Notification heading | | body | string | ✅ | Notification message | | id | string \| number | — | Stable ID. Auto-generated if omitted. | | data | object | — | Payload forwarded to onTap callback | | icon | string | — | Emoji shown in browser toast | | sound | boolean | — | Play sound. Default: true | | vibrate | boolean | — | Vibrate device. Default: true | | priority | 'low' \| 'normal' \| 'high' | — | Android priority. Default: 'normal' | | ongoing | boolean | — | Persistent notification. Default: false |

notify.schedule(options) → Promise<void>

Schedule a notification to fire at a future time. Survives app restarts on Android.

| Option | Type | Required | Description | |--------|------|----------|-------------| | triggerAt | Date \| number | ✅ | When to fire — Date or ms timestamp | | repeat | 'hourly' \| 'daily' \| 'weekly' \| number | — | Repeat interval. Pass ms for custom intervals. | | ... | | | All show() options are supported |

notify.cancel(id) → Promise<void>

Cancel a displayed notification or pending alarm by ID.

notify.cancelAll() → Promise<void>

Cancel all notifications and pending alarms.

notify.onTap(callback) → void

Register a callback invoked when the user taps a notification. Call once on app startup.

notify.onTap((data) => {
  // data = the object you passed in show() or schedule()
  if (data.screen) router.push(data.screen)
})

notify.requestPermission() → Promise<'granted' | 'denied' | 'not-determined'>

Request Android POST_NOTIFICATIONS permission. Always returns 'granted' in the browser.

notify.configure(config) → void

Set global defaults. Call once before using other methods.

notify.configure({
  webPosition: 'top-right',   // where browser toasts appear
  defaultSound: true,
  defaultVibrate: true,
  defaultChannelId: 'general'
})

| Option | Type | Default | |--------|------|---------| | webPosition | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'top-center' \| 'bottom-center' | 'bottom-right' | | defaultSound | boolean | true | | defaultVibrate | boolean | true | | defaultChannelId | string | 'general' |

Examples

Process completion

async function runExport() {
  await generateReport()
  await notify.show({
    title: 'Export ready',
    body: 'Your report has been generated.',
    data: { screen: '/reports/latest' }
  })
}

notify.onTap(({ screen }) => {
  if (screen) router.push(screen)
})

Daily reminder with cancel

notify.schedule({
  id: 'daily-reminder',
  title: 'Good morning!',
  body: 'Your daily summary is ready.',
  triggerAt: new Date().setHours(9, 0, 0, 0),
  repeat: 'daily'
})

// Cancel it later
notify.cancel('daily-reminder')

Requirements

• Built with AIStudioAPK for native Android support
• Works in any React / Vue / Svelte / vanilla JS project

License

MIT © AIStudioAPK