@webority/mobile-core 0.0.27 → 0.0.29

package/README.md

@@ -30,6 +30,7 @@ import { openDatabase } from '@webority/mobile-core/sqlite';
 import { downloadFile } from '@webority/mobile-core/download';
 import { shareFile } from '@webority/mobile-core/share';
 import { initPush, enablePush, usePush } from '@webority/mobile-core/push';
+import { definePushActionTask } from '@webority/mobile-core/push/task';
 import { compressImage } from '@webority/mobile-core/compressor';
 ```
 
@@ -43,7 +44,74 @@ the native token (`Fcm` on Android, `Apns` on iOS) and the bundle id to `registe
 re-registers when the token changes; `disablePush` calls `unregister`. `onOpen` receives the
 tapped notification's data as strings, including the tap that launched the app. `usePush` gives a
 settings switch its `status` and `enabled`. The library does not remember the switch: an app that
-keeps push on calls `enablePush` at each start.
+keeps push on calls `enablePush` at each start. `setBadgeCount(count)` sets the app icon badge.
+
+### Notification buttons
+
+A push names a category; the category's buttons are registered on the phone. Register them at
+every start, with the same ids on both platforms:
+
+```ts
+import { setCategories, notifyLocal } from '@webority/mobile-core/push';
+
+await setCategories([
+  {
+    id: 'approval',
+    actions: [
+      { id: 'approve', title: 'Approve', opensApp: false },
+      { id: 'reject', title: 'Reject', destructive: true }
+    ]
+  },
+  {
+    id: 'reply',
+    actions: [
+      {
+        id: 'reply',
+        title: 'Reply',
+        opensApp: false,
+        textInput: { submitTitle: 'Send', placeholder: 'Write a reply' }
+      }
+    ]
+  }
+]);
+```
+
+`opensApp` defaults to true; `destructive` and `authenticationRequired` (unlock first) are iOS
+only. A button tap arrives as `{ actionId, userText, data, notificationId }`: `userText` is the
+reply text, `data` the push data as strings, `notificationId` the notification's identifier on
+the phone. A plain tap still goes to `onOpen`; a button tap with no handler opens like a plain tap.
+
+To receive button taps in every app state, the killed app included, call `definePushActionTask`
+once at module scope in the entry file, before the root component registers. It needs
+`expo-task-manager`, an optional peer (`npx expo install expo-task-manager`), so it lives on its
+own path:
+
+```js
+// index.js
+import { definePushActionTask } from '@webority/mobile-core/push/task';
+import { notifyLocal } from '@webority/mobile-core/push';
+
+definePushActionTask(async ({ actionId, userText, data }) => {
+  try {
+    await settle(actionId, userText, data);
+  } catch {
+    await notifyLocal({ title: 'Could not approve', body: 'Open the app to try again.' });
+  }
+});
+```
+
+The handler's promise is awaited, so its request can finish before the background work ends.
+`onAction(handler)` from `/push` sets the same handler for taps while JavaScript is running and
+returns a function that removes it. A response reported twice within ten seconds (the launch read,
+the listener and the Android task can each report it) runs once.
+
+- **Android:** the background notification task runs the handler for a button tap on a
+  backgrounded or killed app. Buttons appear only on notifications expo-notifications draws (for
+  example `notifyLocal`). An app that draws its own notifications natively from data-only pushes
+  must build each button's intent with expo's `NotificationsService.createNotificationResponseIntent`,
+  so the tap reaches this handler.
+- **iOS:** a button with `opensApp: false` launches the app in the background; the response
+  reaches the listener `definePushActionTask` sets up. The task is not registered on iOS.
 
 Storage and network status stay on the main barrel but load no package on their own. Wire them at
 startup with `setStorageImplementation` and `setNetworkStatusImplementation` if you want them.

package/lib/commonjs/push/index.js

@@ -21,12 +21,30 @@ Object.defineProperty(exports, "initPush", {
     return _push.initPush;
   }
 });
+Object.defineProperty(exports, "notifyLocal", {
+  enumerable: true,
+  get: function () {
+    return _push.notifyLocal;
+  }
+});
+Object.defineProperty(exports, "onAction", {
+  enumerable: true,
+  get: function () {
+    return _push.onAction;
+  }
+});
 Object.defineProperty(exports, "setBadgeCount", {
   enumerable: true,
   get: function () {
     return _push.setBadgeCount;
   }
 });
+Object.defineProperty(exports, "setCategories", {
+  enumerable: true,
+  get: function () {
+    return _push.setCategories;
+  }
+});
 Object.defineProperty(exports, "setPushImplementation", {
   enumerable: true,
   get: function () {

package/lib/commonjs/push/push.js

@@ -3,10 +3,16 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.usePush = exports.setPushImplementation = exports.setBadgeCount = exports.initPush = exports.enablePush = exports.disablePush = void 0;
+exports.usePush = exports.toPushAction = exports.toNotificationActions = exports.setPushImplementation = exports.setCategories = exports.setBadgeCount = exports.routeTaskPayload = exports.resolveModules = exports.onAction = exports.notifyLocal = exports.initPush = exports.enablePush = exports.disablePush = void 0;
 var _react = require("react");
 var _reactNative = require("react-native");
 var _index = require("../logger/index.js");
+/** A button on a notification category. */
+
+/** A set of buttons a push names through its category id. */
+
+/** A button tap on a notification. */
+
 /** The slice of expo-notifications this module calls, so the optional peer stays untyped at build. */
 
 let override = null;
@@ -26,7 +32,7 @@ const setPushImplementation = impl => {
 /**
  * The only place expo-notifications and expo-application are named. Expo Go is
  * checked first because expo-notifications refuses remote push there and its
- * import throws on Android.
+ * import throws on Android. Exported for `./task`; not on the `/push` entry.
  */
 exports.setPushImplementation = setPushImplementation;
 const resolveModules = () => {
@@ -54,6 +60,7 @@ const resolveModules = () => {
   }
   return resolved;
 };
+exports.resolveModules = resolveModules;
 let state = {
   status: 'unknown',
   enabled: false
@@ -71,7 +78,18 @@ const setState = next => {
 let config = null;
 let channelsReady = Promise.resolve();
 let tokenSubscription = null;
-let lastOpenedId = null;
+let actionHandler = null;
+let listening = false;
+/** Responses that arrived before anything could handle them, e.g. the launching tap before initPush. */
+const pendingResponses = [];
+/** Response key to when it was routed. */
+const routedAt = new Map();
+
+/**
+ * The cold-start read, the live listener and, on Android, the background task
+ * can each report the same response a moment apart.
+ */
+const REPEAT_WINDOW_MS = 10_000;
 const requireConfig = () => {
   if (!config) {
     throw new Error('[@webority/mobile-core] call initPush before enablePush or disablePush.');
@@ -96,22 +114,137 @@ const toStringData = data => {
   }
   return out;
 };
-const handleResponse = response => {
-  if (!response || !config) {
+const contentData = response => {
+  const content = response.notification.request.content;
+  if (content.data) {
+    return toStringData(content.data);
+  }
+  if (typeof content.dataString === 'string') {
+    try {
+      return toStringData(JSON.parse(content.dataString));
+    } catch (error) {
+      _index.Logger.error('[push] notification data is not JSON', error);
+    }
+  }
+  return {};
+};
+
+/**
+ * expo-notifications fills iOS `content.data` only from a `body` object, but our
+ * servers send raw APNs with the app's keys at the top level beside `aps`.
+ */
+const triggerData = response => {
+  const trigger = response.notification.request.trigger;
+  const extra = {
+    ...(trigger?.remoteMessage?.data ?? {})
+  };
+  for (const [key, value] of Object.entries(trigger?.payload ?? {})) {
+    // A `body` object is what expo already turned into content.data.
+    if (key === 'aps' || key === 'body' && typeof value === 'object') {
+      continue;
+    }
+    extra[key] = value;
+  }
+  return toStringData(extra);
+};
+
+/** The push's own data merged over the raw remote payload's keys, so content.data wins a conflict. */
+const responseData = response => ({
+  ...triggerData(response),
+  ...contentData(response)
+});
+const toPushAction = response => ({
+  actionId: response.actionIdentifier,
+  ...(response.userText ? {
+    userText: response.userText
+  } : {}),
+  data: responseData(response),
+  notificationId: response.notification.request.identifier
+});
+exports.toPushAction = toPushAction;
+const toNotificationActions = actions => actions.map(action => ({
+  identifier: action.id,
+  buttonTitle: action.title,
+  ...(action.textInput ? {
+    textInput: {
+      submitButtonTitle: action.textInput.submitTitle,
+      placeholder: action.textInput.placeholder
+    }
+  } : {}),
+  options: {
+    opensAppToForeground: action.opensApp ?? true,
+    isDestructive: action.destructive ?? false,
+    isAuthenticationRequired: action.authenticationRequired ?? false
+  }
+}));
+
+/**
+ * Sends a button tap to the action handler and a plain tap to `onOpen`. A
+ * button tap with no action handler opens like a plain tap. Resolves once the
+ * handler has finished, so a background task stays alive for its request.
+ */
+exports.toNotificationActions = toNotificationActions;
+const routeResponse = async (m, response) => {
+  const key = `${response.notification.request.identifier}:${response.actionIdentifier}`;
+  const last = routedAt.get(key);
+  if (last !== undefined && Date.now() - last < REPEAT_WINDOW_MS) {
     return;
   }
-  // The cold-start read and the listener can both report the launching tap.
-  const id = `${response.notification.request.identifier}:${response.actionIdentifier}`;
-  if (id === lastOpenedId) {
+  const isAction = response.actionIdentifier !== m.DEFAULT_ACTION_IDENTIFIER;
+  if (isAction && actionHandler) {
+    routedAt.set(key, Date.now());
+    try {
+      await actionHandler(toPushAction(response));
+    } catch (error) {
+      _index.Logger.error('[push] onAction threw', error);
+    }
+    return;
+  }
+  if (!config) {
+    pendingResponses.push(response);
     return;
   }
-  lastOpenedId = id;
+  routedAt.set(key, Date.now());
   try {
-    config.onOpen(toStringData(response.notification.request.content.data));
+    config.onOpen(responseData(response));
   } catch (error) {
     _index.Logger.error('[push] onOpen threw', error);
   }
 };
+const drainPending = async m => {
+  const queued = pendingResponses.splice(0);
+  for (const response of queued) {
+    await routeResponse(m, response);
+  }
+};
+
+/** Follows taps and button taps, including the one that launched the app. Wired once per process. */
+const listenForResponses = m => {
+  if (listening) {
+    return;
+  }
+  listening = true;
+  m.addNotificationResponseReceivedListener(response => {
+    void routeResponse(m, response);
+  });
+  void m.getLastNotificationResponseAsync().then(async response => {
+    if (response) {
+      await routeResponse(m, response);
+    }
+    return m.clearLastNotificationResponseAsync?.();
+  }).catch(error => _index.Logger.error('[push] reading the launch notification failed', error));
+};
+
+/** The payload of the background notification task: routes button taps, ignores received pushes. */
+const routeTaskPayload = async payload => {
+  const mods = resolveModules();
+  const response = payload;
+  if (!mods || typeof response?.actionIdentifier !== 'string' || typeof response.notification?.request?.identifier !== 'string') {
+    return;
+  }
+  await routeResponse(mods.notifications, response);
+};
+exports.routeTaskPayload = routeTaskPayload;
 const createChannels = async (m, channels) => {
   for (const channel of channels) {
     try {
@@ -174,11 +307,8 @@ const initPush = next => {
   if (_reactNative.Platform.OS === 'android' && next.androidChannels?.length) {
     channelsReady = createChannels(m, next.androidChannels);
   }
-  m.addNotificationResponseReceivedListener(handleResponse);
-  void m.getLastNotificationResponseAsync().then(response => {
-    handleResponse(response);
-    return m.clearLastNotificationResponseAsync?.();
-  }).catch(error => _index.Logger.error('[push] reading the launch notification failed', error));
+  listenForResponses(m);
+  void drainPending(m);
   void m.getPermissionsAsync().then(response => setState({
     status: toPermissionStatus(response)
   })).catch(error => _index.Logger.error('[push] permission check failed', error));
@@ -256,7 +386,64 @@ const setBadgeCount = async count => {
   }
   await mods.notifications.setBadgeCountAsync(count);
 };
+
+/**
+ * Registers the button sets a push can name by category id. Call it at every
+ * start, with the same ids on both platforms. On Android the buttons show only
+ * on notifications expo-notifications draws, such as `notifyLocal`.
+ */
 exports.setBadgeCount = setBadgeCount;
+const setCategories = async categories => {
+  const mods = resolveModules();
+  if (!mods) {
+    return;
+  }
+  for (const category of categories) {
+    await mods.notifications.setNotificationCategoryAsync(category.id, toNotificationActions(category.actions));
+  }
+};
+
+/**
+ * Handles button taps while JavaScript is running; a plain tap still goes to
+ * `onOpen`. For taps on a killed app use `definePushActionTask` from
+ * `/push/task`, which sets this handler too. Returns a function that removes it.
+ */
+exports.setCategories = setCategories;
+const onAction = handler => {
+  actionHandler = handler;
+  const mods = resolveModules();
+  if (mods) {
+    listenForResponses(mods.notifications);
+    void drainPending(mods.notifications);
+  }
+  return () => {
+    if (actionHandler === handler) {
+      actionHandler = null;
+    }
+  };
+};
+
+/** Shows a notification from the phone itself, for example when a button's request failed. */
+exports.onAction = onAction;
+const notifyLocal = async ({
+  title,
+  body,
+  data
+}) => {
+  const mods = resolveModules();
+  if (!mods) {
+    return;
+  }
+  await mods.notifications.scheduleNotificationAsync({
+    content: {
+      title,
+      body,
+      data: data ?? {}
+    },
+    trigger: null
+  });
+};
+exports.notifyLocal = notifyLocal;
 const subscribe = notify => {
   subscribers.add(notify);
   return () => {

package/lib/commonjs/push/task.js

@@ -0,0 +1,43 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.definePushActionTask = void 0;
+var _reactNative = require("react-native");
+var _index = require("../logger/index.js");
+var _push = require("./push.js");
+const PUSH_ACTION_TASK = 'webority-push-action';
+/**
+ * Handles notification button taps in every app state, the killed app
+ * included. Call it once at module scope in the app's entry file (index.js),
+ * before the root component registers: a tap on a killed app starts the
+ * JavaScript bundle without the UI, so nothing later in the app runs.
+ *
+ * Android runs the handler from a background notification task
+ * (expo-task-manager). iOS has no such task for button taps: it launches the
+ * app in the background and the response reaches the listener this sets up.
+ * The handler's promise is awaited, so a request it makes can finish first.
+ */
+const definePushActionTask = handler => {
+  (0, _push.onAction)(handler);
+  const mods = (0, _push.resolveModules)();
+  if (!mods || _reactNative.Platform.OS !== 'android') {
+    return;
+  }
+  /** The one place `expo-task-manager` is named. Import `/push/task` only if you use button taps. */
+  const taskManager = require('expo-task-manager');
+  taskManager.defineTask(PUSH_ACTION_TASK, async ({
+    data,
+    error
+  }) => {
+    if (error) {
+      _index.Logger.error('[push] the notification task failed', error);
+      return;
+    }
+    await (0, _push.routeTaskPayload)(data);
+  });
+  void mods.notifications.registerTaskAsync(PUSH_ACTION_TASK).catch(registerError => _index.Logger.error('[push] registering the notification task failed', registerError));
+};
+exports.definePushActionTask = definePushActionTask;
+//# sourceMappingURL=task.js.map

package/lib/module/push/index.js

@@ -1,4 +1,4 @@
 "use strict";
 
-export { disablePush, enablePush, initPush, setBadgeCount, setPushImplementation, usePush } from "./push.js";
+export { disablePush, enablePush, initPush, notifyLocal, onAction, setBadgeCount, setCategories, setPushImplementation, usePush } from "./push.js";
 //# sourceMappingURL=index.js.map

package/lib/module/push/push.js

@@ -4,6 +4,12 @@ import { useSyncExternalStore } from 'react';
 import { Platform } from 'react-native';
 import { Logger } from "../logger/index.js";
 
+/** A button on a notification category. */
+
+/** A set of buttons a push names through its category id. */
+
+/** A button tap on a notification. */
+
 /** The slice of expo-notifications this module calls, so the optional peer stays untyped at build. */
 
 let override = null;
@@ -23,9 +29,9 @@ export const setPushImplementation = impl => {
 /**
  * The only place expo-notifications and expo-application are named. Expo Go is
  * checked first because expo-notifications refuses remote push there and its
- * import throws on Android.
+ * import throws on Android. Exported for `./task`; not on the `/push` entry.
  */
-const resolveModules = () => {
+export const resolveModules = () => {
   if (override) {
     return override;
   }
@@ -67,7 +73,18 @@ const setState = next => {
 let config = null;
 let channelsReady = Promise.resolve();
 let tokenSubscription = null;
-let lastOpenedId = null;
+let actionHandler = null;
+let listening = false;
+/** Responses that arrived before anything could handle them, e.g. the launching tap before initPush. */
+const pendingResponses = [];
+/** Response key to when it was routed. */
+const routedAt = new Map();
+
+/**
+ * The cold-start read, the live listener and, on Android, the background task
+ * can each report the same response a moment apart.
+ */
+const REPEAT_WINDOW_MS = 10_000;
 const requireConfig = () => {
   if (!config) {
     throw new Error('[@webority/mobile-core] call initPush before enablePush or disablePush.');
@@ -92,22 +109,134 @@ const toStringData = data => {
   }
   return out;
 };
-const handleResponse = response => {
-  if (!response || !config) {
+const contentData = response => {
+  const content = response.notification.request.content;
+  if (content.data) {
+    return toStringData(content.data);
+  }
+  if (typeof content.dataString === 'string') {
+    try {
+      return toStringData(JSON.parse(content.dataString));
+    } catch (error) {
+      Logger.error('[push] notification data is not JSON', error);
+    }
+  }
+  return {};
+};
+
+/**
+ * expo-notifications fills iOS `content.data` only from a `body` object, but our
+ * servers send raw APNs with the app's keys at the top level beside `aps`.
+ */
+const triggerData = response => {
+  const trigger = response.notification.request.trigger;
+  const extra = {
+    ...(trigger?.remoteMessage?.data ?? {})
+  };
+  for (const [key, value] of Object.entries(trigger?.payload ?? {})) {
+    // A `body` object is what expo already turned into content.data.
+    if (key === 'aps' || key === 'body' && typeof value === 'object') {
+      continue;
+    }
+    extra[key] = value;
+  }
+  return toStringData(extra);
+};
+
+/** The push's own data merged over the raw remote payload's keys, so content.data wins a conflict. */
+const responseData = response => ({
+  ...triggerData(response),
+  ...contentData(response)
+});
+export const toPushAction = response => ({
+  actionId: response.actionIdentifier,
+  ...(response.userText ? {
+    userText: response.userText
+  } : {}),
+  data: responseData(response),
+  notificationId: response.notification.request.identifier
+});
+export const toNotificationActions = actions => actions.map(action => ({
+  identifier: action.id,
+  buttonTitle: action.title,
+  ...(action.textInput ? {
+    textInput: {
+      submitButtonTitle: action.textInput.submitTitle,
+      placeholder: action.textInput.placeholder
+    }
+  } : {}),
+  options: {
+    opensAppToForeground: action.opensApp ?? true,
+    isDestructive: action.destructive ?? false,
+    isAuthenticationRequired: action.authenticationRequired ?? false
+  }
+}));
+
+/**
+ * Sends a button tap to the action handler and a plain tap to `onOpen`. A
+ * button tap with no action handler opens like a plain tap. Resolves once the
+ * handler has finished, so a background task stays alive for its request.
+ */
+const routeResponse = async (m, response) => {
+  const key = `${response.notification.request.identifier}:${response.actionIdentifier}`;
+  const last = routedAt.get(key);
+  if (last !== undefined && Date.now() - last < REPEAT_WINDOW_MS) {
+    return;
+  }
+  const isAction = response.actionIdentifier !== m.DEFAULT_ACTION_IDENTIFIER;
+  if (isAction && actionHandler) {
+    routedAt.set(key, Date.now());
+    try {
+      await actionHandler(toPushAction(response));
+    } catch (error) {
+      Logger.error('[push] onAction threw', error);
+    }
     return;
   }
-  // The cold-start read and the listener can both report the launching tap.
-  const id = `${response.notification.request.identifier}:${response.actionIdentifier}`;
-  if (id === lastOpenedId) {
+  if (!config) {
+    pendingResponses.push(response);
     return;
   }
-  lastOpenedId = id;
+  routedAt.set(key, Date.now());
   try {
-    config.onOpen(toStringData(response.notification.request.content.data));
+    config.onOpen(responseData(response));
   } catch (error) {
     Logger.error('[push] onOpen threw', error);
   }
 };
+const drainPending = async m => {
+  const queued = pendingResponses.splice(0);
+  for (const response of queued) {
+    await routeResponse(m, response);
+  }
+};
+
+/** Follows taps and button taps, including the one that launched the app. Wired once per process. */
+const listenForResponses = m => {
+  if (listening) {
+    return;
+  }
+  listening = true;
+  m.addNotificationResponseReceivedListener(response => {
+    void routeResponse(m, response);
+  });
+  void m.getLastNotificationResponseAsync().then(async response => {
+    if (response) {
+      await routeResponse(m, response);
+    }
+    return m.clearLastNotificationResponseAsync?.();
+  }).catch(error => Logger.error('[push] reading the launch notification failed', error));
+};
+
+/** The payload of the background notification task: routes button taps, ignores received pushes. */
+export const routeTaskPayload = async payload => {
+  const mods = resolveModules();
+  const response = payload;
+  if (!mods || typeof response?.actionIdentifier !== 'string' || typeof response.notification?.request?.identifier !== 'string') {
+    return;
+  }
+  await routeResponse(mods.notifications, response);
+};
 const createChannels = async (m, channels) => {
   for (const channel of channels) {
     try {
@@ -170,11 +299,8 @@ export const initPush = next => {
   if (Platform.OS === 'android' && next.androidChannels?.length) {
     channelsReady = createChannels(m, next.androidChannels);
   }
-  m.addNotificationResponseReceivedListener(handleResponse);
-  void m.getLastNotificationResponseAsync().then(response => {
-    handleResponse(response);
-    return m.clearLastNotificationResponseAsync?.();
-  }).catch(error => Logger.error('[push] reading the launch notification failed', error));
+  listenForResponses(m);
+  void drainPending(m);
   void m.getPermissionsAsync().then(response => setState({
     status: toPermissionStatus(response)
   })).catch(error => Logger.error('[push] permission check failed', error));
@@ -249,6 +375,60 @@ export const setBadgeCount = async count => {
   }
   await mods.notifications.setBadgeCountAsync(count);
 };
+
+/**
+ * Registers the button sets a push can name by category id. Call it at every
+ * start, with the same ids on both platforms. On Android the buttons show only
+ * on notifications expo-notifications draws, such as `notifyLocal`.
+ */
+export const setCategories = async categories => {
+  const mods = resolveModules();
+  if (!mods) {
+    return;
+  }
+  for (const category of categories) {
+    await mods.notifications.setNotificationCategoryAsync(category.id, toNotificationActions(category.actions));
+  }
+};
+
+/**
+ * Handles button taps while JavaScript is running; a plain tap still goes to
+ * `onOpen`. For taps on a killed app use `definePushActionTask` from
+ * `/push/task`, which sets this handler too. Returns a function that removes it.
+ */
+export const onAction = handler => {
+  actionHandler = handler;
+  const mods = resolveModules();
+  if (mods) {
+    listenForResponses(mods.notifications);
+    void drainPending(mods.notifications);
+  }
+  return () => {
+    if (actionHandler === handler) {
+      actionHandler = null;
+    }
+  };
+};
+
+/** Shows a notification from the phone itself, for example when a button's request failed. */
+export const notifyLocal = async ({
+  title,
+  body,
+  data
+}) => {
+  const mods = resolveModules();
+  if (!mods) {
+    return;
+  }
+  await mods.notifications.scheduleNotificationAsync({
+    content: {
+      title,
+      body,
+      data: data ?? {}
+    },
+    trigger: null
+  });
+};
 const subscribe = notify => {
   subscribers.add(notify);
   return () => {

package/lib/module/push/task.js

@@ -0,0 +1,38 @@
+"use strict";
+
+import { Platform } from 'react-native';
+import { Logger } from "../logger/index.js";
+import { onAction, resolveModules, routeTaskPayload } from "./push.js";
+const PUSH_ACTION_TASK = 'webority-push-action';
+/**
+ * Handles notification button taps in every app state, the killed app
+ * included. Call it once at module scope in the app's entry file (index.js),
+ * before the root component registers: a tap on a killed app starts the
+ * JavaScript bundle without the UI, so nothing later in the app runs.
+ *
+ * Android runs the handler from a background notification task
+ * (expo-task-manager). iOS has no such task for button taps: it launches the
+ * app in the background and the response reaches the listener this sets up.
+ * The handler's promise is awaited, so a request it makes can finish first.
+ */
+export const definePushActionTask = handler => {
+  onAction(handler);
+  const mods = resolveModules();
+  if (!mods || Platform.OS !== 'android') {
+    return;
+  }
+  /** The one place `expo-task-manager` is named. Import `/push/task` only if you use button taps. */
+  const taskManager = require('expo-task-manager');
+  taskManager.defineTask(PUSH_ACTION_TASK, async ({
+    data,
+    error
+  }) => {
+    if (error) {
+      Logger.error('[push] the notification task failed', error);
+      return;
+    }
+    await routeTaskPayload(data);
+  });
+  void mods.notifications.registerTaskAsync(PUSH_ACTION_TASK).catch(registerError => Logger.error('[push] registering the notification task failed', registerError));
+};
+//# sourceMappingURL=task.js.map

package/lib/typescript/commonjs/push/index.d.ts

@@ -1,3 +1,3 @@
-export type { PushAndroidChannel, PushConfig, PushDevice, PushModules, PushNotificationsLike, PushPlatform, PushState, PushStatus } from './push';
-export { disablePush, enablePush, initPush, setBadgeCount, setPushImplementation, usePush } from './push';
+export type { PushAction, PushActionHandler, PushAndroidChannel, PushCategory, PushCategoryAction, PushConfig, PushDevice, PushLocalNotification, PushModules, PushNotificationsLike, PushPlatform, PushState, PushStatus } from './push';
+export { disablePush, enablePush, initPush, notifyLocal, onAction, setBadgeCount, setCategories, setPushImplementation, usePush } from './push';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/push/push.d.ts

@@ -26,6 +26,42 @@ export interface PushConfig {
     /** Whether a notification shown while the app is open plays its sound. Defaults to true. */
     playSoundInForeground?: () => boolean;
 }
+/** A button on a notification category. */
+export interface PushCategoryAction {
+    id: string;
+    title: string;
+    /** Whether the tap brings the app to the foreground. Defaults to true. */
+    opensApp?: boolean;
+    /** iOS only: the title shows in red. */
+    destructive?: boolean;
+    /** Turns the button into a reply box; the text arrives as `userText`. */
+    textInput?: {
+        submitTitle: string;
+        placeholder: string;
+    };
+    /** iOS only: the phone must be unlocked before the action runs. */
+    authenticationRequired?: boolean;
+}
+/** A set of buttons a push names through its category id. */
+export interface PushCategory {
+    id: string;
+    actions: PushCategoryAction[];
+}
+/** A button tap on a notification. */
+export interface PushAction {
+    actionId: string;
+    /** What the person typed, for a `textInput` action. */
+    userText?: string;
+    data: Record<string, string>;
+    /** The notification's identifier on the phone, not a server id in `data`. */
+    notificationId: string;
+}
+export type PushActionHandler = (action: PushAction) => Promise<void> | void;
+export interface PushLocalNotification {
+    title: string;
+    body: string;
+    data?: Record<string, string>;
+}
 export type PushStatus = 'unknown' | 'granted' | 'denied' | 'unavailable';
 export interface PushState {
     status: PushStatus;
@@ -41,15 +77,39 @@ interface SubscriptionLike {
 }
 interface NotificationResponseLike {
     actionIdentifier: string;
+    userText?: string;
     notification: {
         request: {
             identifier: string;
+            /** A background task receives the raw content, where data may still be a JSON `dataString`. */
             content: {
                 data?: Record<string, unknown> | null;
+                dataString?: string;
             };
+            /** A remote push carries its raw payload: APNs `userInfo` on iOS, the FCM message on Android. */
+            trigger?: {
+                type?: string;
+                payload?: Record<string, unknown> | null;
+                remoteMessage?: {
+                    data?: Record<string, unknown> | null;
+                } | null;
+            } | null;
         };
     };
 }
+interface NotificationActionLike {
+    identifier: string;
+    buttonTitle: string;
+    textInput?: {
+        submitButtonTitle: string;
+        placeholder: string;
+    };
+    options: {
+        opensAppToForeground: boolean;
+        isDestructive: boolean;
+        isAuthenticationRequired: boolean;
+    };
+}
 interface DevicePushTokenLike {
     type: string;
     data: unknown;
@@ -76,10 +136,22 @@ export interface PushNotificationsLike {
         importance: number;
     }) => Promise<unknown>;
     setBadgeCountAsync: (count: number) => Promise<boolean>;
+    setNotificationCategoryAsync: (identifier: string, actions: NotificationActionLike[]) => Promise<unknown>;
+    scheduleNotificationAsync: (request: {
+        content: {
+            title: string;
+            body: string;
+            data: Record<string, string>;
+        };
+        trigger: null;
+    }) => Promise<string>;
+    registerTaskAsync: (taskName: string) => Promise<unknown>;
     AndroidImportance: {
         DEFAULT: number;
         HIGH: number;
     };
+    /** The `actionIdentifier` of a plain tap on the notification body. */
+    DEFAULT_ACTION_IDENTIFIER: string;
 }
 export interface PushModules {
     notifications: PushNotificationsLike;
@@ -92,6 +164,16 @@ export interface PushModules {
  * included. Pass `null` to restore expo-notifications.
  */
 export declare const setPushImplementation: (impl: PushModules | null) => void;
+/**
+ * The only place expo-notifications and expo-application are named. Expo Go is
+ * checked first because expo-notifications refuses remote push there and its
+ * import throws on Android. Exported for `./task`; not on the `/push` entry.
+ */
+export declare const resolveModules: () => PushModules | null;
+export declare const toPushAction: (response: NotificationResponseLike) => PushAction;
+export declare const toNotificationActions: (actions: PushCategoryAction[]) => NotificationActionLike[];
+/** The payload of the background notification task: routes button taps, ignores received pushes. */
+export declare const routeTaskPayload: (payload: unknown) => Promise<void>;
 /**
  * Wires push at startup: the foreground handler, Android channels, and tap
  * handling, including the tap that launched the app. Calling it again only
@@ -110,6 +192,20 @@ export declare const enablePush: () => Promise<"granted" | "denied" | "unavailab
 export declare const disablePush: () => Promise<void>;
 /** Sets the app icon badge; a no-op where push is unavailable or the launcher has no badge. */
 export declare const setBadgeCount: (count: number) => Promise<void>;
+/**
+ * Registers the button sets a push can name by category id. Call it at every
+ * start, with the same ids on both platforms. On Android the buttons show only
+ * on notifications expo-notifications draws, such as `notifyLocal`.
+ */
+export declare const setCategories: (categories: PushCategory[]) => Promise<void>;
+/**
+ * Handles button taps while JavaScript is running; a plain tap still goes to
+ * `onOpen`. For taps on a killed app use `definePushActionTask` from
+ * `/push/task`, which sets this handler too. Returns a function that removes it.
+ */
+export declare const onAction: (handler: PushActionHandler) => (() => void);
+/** Shows a notification from the phone itself, for example when a button's request failed. */
+export declare const notifyLocal: ({ title, body, data }: PushLocalNotification) => Promise<void>;
 /** Push status for a settings switch, re-rendering when it changes. */
 export declare const usePush: () => PushState & {
     enable: () => Promise<void>;

package/lib/typescript/commonjs/push/task.d.ts

@@ -0,0 +1,15 @@
+import { type PushActionHandler } from './push';
+export type { PushAction, PushActionHandler } from './push';
+/**
+ * Handles notification button taps in every app state, the killed app
+ * included. Call it once at module scope in the app's entry file (index.js),
+ * before the root component registers: a tap on a killed app starts the
+ * JavaScript bundle without the UI, so nothing later in the app runs.
+ *
+ * Android runs the handler from a background notification task
+ * (expo-task-manager). iOS has no such task for button taps: it launches the
+ * app in the background and the response reaches the listener this sets up.
+ * The handler's promise is awaited, so a request it makes can finish first.
+ */
+export declare const definePushActionTask: (handler: PushActionHandler) => void;
+//# sourceMappingURL=task.d.ts.map

package/lib/typescript/module/push/index.d.ts

@@ -1,3 +1,3 @@
-export type { PushAndroidChannel, PushConfig, PushDevice, PushModules, PushNotificationsLike, PushPlatform, PushState, PushStatus } from './push.js';
-export { disablePush, enablePush, initPush, setBadgeCount, setPushImplementation, usePush } from './push.js';
+export type { PushAction, PushActionHandler, PushAndroidChannel, PushCategory, PushCategoryAction, PushConfig, PushDevice, PushLocalNotification, PushModules, PushNotificationsLike, PushPlatform, PushState, PushStatus } from './push.js';
+export { disablePush, enablePush, initPush, notifyLocal, onAction, setBadgeCount, setCategories, setPushImplementation, usePush } from './push.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/push/push.d.ts

@@ -26,6 +26,42 @@ export interface PushConfig {
     /** Whether a notification shown while the app is open plays its sound. Defaults to true. */
     playSoundInForeground?: () => boolean;
 }
+/** A button on a notification category. */
+export interface PushCategoryAction {
+    id: string;
+    title: string;
+    /** Whether the tap brings the app to the foreground. Defaults to true. */
+    opensApp?: boolean;
+    /** iOS only: the title shows in red. */
+    destructive?: boolean;
+    /** Turns the button into a reply box; the text arrives as `userText`. */
+    textInput?: {
+        submitTitle: string;
+        placeholder: string;
+    };
+    /** iOS only: the phone must be unlocked before the action runs. */
+    authenticationRequired?: boolean;
+}
+/** A set of buttons a push names through its category id. */
+export interface PushCategory {
+    id: string;
+    actions: PushCategoryAction[];
+}
+/** A button tap on a notification. */
+export interface PushAction {
+    actionId: string;
+    /** What the person typed, for a `textInput` action. */
+    userText?: string;
+    data: Record<string, string>;
+    /** The notification's identifier on the phone, not a server id in `data`. */
+    notificationId: string;
+}
+export type PushActionHandler = (action: PushAction) => Promise<void> | void;
+export interface PushLocalNotification {
+    title: string;
+    body: string;
+    data?: Record<string, string>;
+}
 export type PushStatus = 'unknown' | 'granted' | 'denied' | 'unavailable';
 export interface PushState {
     status: PushStatus;
@@ -41,15 +77,39 @@ interface SubscriptionLike {
 }
 interface NotificationResponseLike {
     actionIdentifier: string;
+    userText?: string;
     notification: {
         request: {
             identifier: string;
+            /** A background task receives the raw content, where data may still be a JSON `dataString`. */
             content: {
                 data?: Record<string, unknown> | null;
+                dataString?: string;
             };
+            /** A remote push carries its raw payload: APNs `userInfo` on iOS, the FCM message on Android. */
+            trigger?: {
+                type?: string;
+                payload?: Record<string, unknown> | null;
+                remoteMessage?: {
+                    data?: Record<string, unknown> | null;
+                } | null;
+            } | null;
         };
     };
 }
+interface NotificationActionLike {
+    identifier: string;
+    buttonTitle: string;
+    textInput?: {
+        submitButtonTitle: string;
+        placeholder: string;
+    };
+    options: {
+        opensAppToForeground: boolean;
+        isDestructive: boolean;
+        isAuthenticationRequired: boolean;
+    };
+}
 interface DevicePushTokenLike {
     type: string;
     data: unknown;
@@ -76,10 +136,22 @@ export interface PushNotificationsLike {
         importance: number;
     }) => Promise<unknown>;
     setBadgeCountAsync: (count: number) => Promise<boolean>;
+    setNotificationCategoryAsync: (identifier: string, actions: NotificationActionLike[]) => Promise<unknown>;
+    scheduleNotificationAsync: (request: {
+        content: {
+            title: string;
+            body: string;
+            data: Record<string, string>;
+        };
+        trigger: null;
+    }) => Promise<string>;
+    registerTaskAsync: (taskName: string) => Promise<unknown>;
     AndroidImportance: {
         DEFAULT: number;
         HIGH: number;
     };
+    /** The `actionIdentifier` of a plain tap on the notification body. */
+    DEFAULT_ACTION_IDENTIFIER: string;
 }
 export interface PushModules {
     notifications: PushNotificationsLike;
@@ -92,6 +164,16 @@ export interface PushModules {
  * included. Pass `null` to restore expo-notifications.
  */
 export declare const setPushImplementation: (impl: PushModules | null) => void;
+/**
+ * The only place expo-notifications and expo-application are named. Expo Go is
+ * checked first because expo-notifications refuses remote push there and its
+ * import throws on Android. Exported for `./task`; not on the `/push` entry.
+ */
+export declare const resolveModules: () => PushModules | null;
+export declare const toPushAction: (response: NotificationResponseLike) => PushAction;
+export declare const toNotificationActions: (actions: PushCategoryAction[]) => NotificationActionLike[];
+/** The payload of the background notification task: routes button taps, ignores received pushes. */
+export declare const routeTaskPayload: (payload: unknown) => Promise<void>;
 /**
  * Wires push at startup: the foreground handler, Android channels, and tap
  * handling, including the tap that launched the app. Calling it again only
@@ -110,6 +192,20 @@ export declare const enablePush: () => Promise<"granted" | "denied" | "unavailab
 export declare const disablePush: () => Promise<void>;
 /** Sets the app icon badge; a no-op where push is unavailable or the launcher has no badge. */
 export declare const setBadgeCount: (count: number) => Promise<void>;
+/**
+ * Registers the button sets a push can name by category id. Call it at every
+ * start, with the same ids on both platforms. On Android the buttons show only
+ * on notifications expo-notifications draws, such as `notifyLocal`.
+ */
+export declare const setCategories: (categories: PushCategory[]) => Promise<void>;
+/**
+ * Handles button taps while JavaScript is running; a plain tap still goes to
+ * `onOpen`. For taps on a killed app use `definePushActionTask` from
+ * `/push/task`, which sets this handler too. Returns a function that removes it.
+ */
+export declare const onAction: (handler: PushActionHandler) => (() => void);
+/** Shows a notification from the phone itself, for example when a button's request failed. */
+export declare const notifyLocal: ({ title, body, data }: PushLocalNotification) => Promise<void>;
 /** Push status for a settings switch, re-rendering when it changes. */
 export declare const usePush: () => PushState & {
     enable: () => Promise<void>;

package/lib/typescript/module/push/task.d.ts

@@ -0,0 +1,15 @@
+import { type PushActionHandler } from './push.js';
+export type { PushAction, PushActionHandler } from './push.js';
+/**
+ * Handles notification button taps in every app state, the killed app
+ * included. Call it once at module scope in the app's entry file (index.js),
+ * before the root component registers: a tap on a killed app starts the
+ * JavaScript bundle without the UI, so nothing later in the app runs.
+ *
+ * Android runs the handler from a background notification task
+ * (expo-task-manager). iOS has no such task for button taps: it launches the
+ * app in the background and the response reaches the listener this sets up.
+ * The handler's promise is awaited, so a request it makes can finish first.
+ */
+export declare const definePushActionTask: (handler: PushActionHandler) => void;
+//# sourceMappingURL=task.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webority/mobile-core",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "Platform layer for Webority React Native apps: HTTP clients, auth/token storage, config, logging, formatters, validators, network status, permissions, storage and version checks. No UI.",
   "keywords": [
     "react-native",
@@ -171,6 +171,16 @@
         "default": "./lib/commonjs/push/index.js"
       }
     },
+    "./push/task": {
+      "import": {
+        "types": "./lib/typescript/module/push/task.d.ts",
+        "default": "./lib/module/push/task.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/push/task.d.ts",
+        "default": "./lib/commonjs/push/task.js"
+      }
+    },
     "./smsRetriever": {
       "import": {
         "types": "./lib/typescript/module/smsRetriever/index.d.ts",
@@ -242,6 +252,7 @@
     "expo-secure-store": ">=57.0.0",
     "expo-sharing": ">=57.0.0",
     "expo-sqlite": ">=57.0.0",
+    "expo-task-manager": ">=57.0.0",
     "react": "^19.1.0",
     "react-native": ">=0.81.0"
   },
@@ -275,6 +286,9 @@
     },
     "expo-sharing": {
       "optional": true
+    },
+    "expo-task-manager": {
+      "optional": true
     }
   },
   "publishConfig": {