@lowdefy/shell 3.23.2 → 7.2.0

package/src/notifications/registerPushToken.js

@@ -0,0 +1,71 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Platform } from 'react-native';
+import * as Notifications from 'expo-notifications';
+
+import callEndpoint from '../native/callEndpoint.js';
+import reportShellError from '../host/reportShellError.js';
+
+// The Expo push token, for an app that sends through Expo's push service. A shell without an EAS
+// project has none. Without it the native token is still registered, so a failure is reported and
+// the registration goes on.
+async function getExpoToken({ projectId, session }) {
+  if (typeof projectId !== 'string') {
+    return null;
+  }
+  try {
+    const { data } = await Notifications.getExpoPushTokenAsync({ projectId });
+    return data;
+  } catch (error) {
+    reportShellError({ error, session });
+    return null;
+  }
+}
+
+/**
+ * Sends this phone's push token to the app's mobile.notifications.register endpoint, once signed in
+ * and allowed to notify: { token (APNs or FCM), expoToken, platform, provider, shellId,
+ * appVersion }. The app stores it per user (the endpoint has the caller's session) and sends pushes
+ * through APNs, FCM or Expo. Does nothing without a register endpoint or permission.
+ *
+ * @param {Object} params
+ * @param {Object} params.app The open app (currentApp.js).
+ * @param {string} [params.token] A new native token (the token listener), else read now.
+ */
+async function registerPushToken({ app, token }) {
+  const endpointId = app.session.getState().root?.notifications?.register;
+  if (typeof endpointId !== 'string' || app.tokenStore.get() === null) {
+    return null;
+  }
+  const { granted } = await Notifications.getPermissionsAsync();
+  if (!granted) {
+    return null;
+  }
+  const nativeToken = token ?? (await Notifications.getDevicePushTokenAsync()).data;
+  const registration = {
+    token: nativeToken,
+    expoToken: await getExpoToken({ projectId: app.shell.easProjectId, session: app.session }),
+    platform: Platform.OS,
+    provider: Platform.OS === 'ios' ? 'apns' : 'fcm',
+    shellId: app.shell.id,
+    appVersion: app.shell.version,
+  };
+  await callEndpoint({ app, endpointId, payload: registration });
+  return registration;
+}
+
+export default registerPushToken;

package/src/notifications/startNotifications.js

@@ -0,0 +1,114 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import * as Notifications from 'expo-notifications';
+import { type } from '@lowdefy/helpers';
+
+import handleNotificationResponse from './handleNotificationResponse.js';
+import refreshWidgets from '../widgets/refreshWidgets.js';
+import registerPushToken from './registerPushToken.js';
+import reportShellError from '../host/reportShellError.js';
+import toCategoryActions from './toCategoryActions.js';
+import toNotificationEvent from './toNotificationEvent.js';
+
+/**
+ * Notifications for the open app, once its root is held: registers its categories, shows a
+ * notification that arrives while it is open as mobile.notifications.foreground says, fires
+ * onNotification for it, handles taps and buttons (handleNotificationResponse, also the one that
+ * launched the app), and registers the push token once signed in and allowed. A push with
+ * `data.refreshWidgets` updates the widgets.
+ *
+ * @param {Object} params
+ * @param {Object} params.app The open app (currentApp.js).
+ * @returns {() => void} Stops listening.
+ */
+function startNotifications({ app }) {
+  const subscriptions = [];
+  let registeredCategories = null;
+  // The response that launched the app can also reach the listener: each is handled once.
+  const handled = new Set();
+  function report(error) {
+    reportShellError({ error, session: app.session });
+  }
+  function respond(response) {
+    const key = `${response.notification.request.identifier}:${response.actionIdentifier}`;
+    if (handled.has(key)) return;
+    handled.add(key);
+    // A button's endpoint call and the path it opens need the token and the root.
+    app.ready.then(() => handleNotificationResponse({ app, response })).catch(report);
+  }
+
+  function applyRoot() {
+    const notifications = app.session.getState().root?.notifications;
+    if (!type.isObject(notifications) || notifications === registeredCategories) {
+      return;
+    }
+    registeredCategories = notifications;
+    notifications.categories.forEach((category) => {
+      Notifications.setNotificationCategoryAsync(
+        category.id,
+        toCategoryActions(category.actions)
+      ).catch(() => {});
+    });
+    registerPushToken({ app }).catch(report);
+  }
+
+  Notifications.setNotificationHandler({
+    handleNotification: async () => {
+      const banner = app.session.getState().root?.notifications?.foreground !== 'silent';
+      return {
+        shouldShowBanner: banner,
+        shouldShowList: true,
+        shouldPlaySound: banner,
+        shouldSetBadge: true,
+      };
+    },
+  });
+
+  subscriptions.push(
+    Notifications.addNotificationReceivedListener((notification) => {
+      const event = toNotificationEvent(notification);
+      if (event.data.refreshWidgets === true) {
+        refreshWidgets({ app }).catch(() => {});
+      }
+      app.triggerAppEvent({ name: 'onNotification', event: { notification: event } });
+    }),
+    Notifications.addNotificationResponseReceivedListener(respond),
+    Notifications.addPushTokenListener(({ data }) => {
+      registerPushToken({ app, token: data }).catch(report);
+    })
+  );
+  const unsubscribe = app.session.subscribe(applyRoot);
+  applyRoot();
+  // A sign-in after the app opened registers the token for the person who signed in.
+  const unsubscribeToken = app.tokenStore.subscribe((token) => {
+    if (token !== null) registerPushToken({ app }).catch(report);
+  });
+
+  const launching = Notifications.getLastNotificationResponse();
+  if (launching !== null) {
+    Notifications.clearLastNotificationResponse();
+    respond(launching);
+  }
+
+  return () => {
+    unsubscribe();
+    unsubscribeToken();
+    subscriptions.forEach((subscription) => subscription.remove());
+  };
+}
+
+export default startNotifications;

package/src/notifications/toCategoryActions.js

@@ -0,0 +1,42 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+/**
+ * A mobile.notifications category's actions as expo-notifications registers them. A button that
+ * calls an endpoint or snoozes runs without opening the app; the others open it.
+ *
+ * @param {Object[]} actions The category's actions (getMobileNotifications in the build).
+ */
+function toCategoryActions(actions) {
+  return actions.map((action) => ({
+    identifier: action.id,
+    buttonTitle: action.title,
+    textInput:
+      action.input === null
+        ? undefined
+        : {
+            placeholder: action.input.placeholder ?? '',
+            submitButtonTitle: action.input.buttonTitle ?? action.title,
+          },
+    options: {
+      opensAppToForeground: action.endpointId === null && action.snooze === null,
+      isDestructive: action.destructive,
+      isAuthenticationRequired: action.authenticationRequired,
+    },
+  }));
+}
+
+export default toCategoryActions;

package/src/notifications/toNotificationEvent.js

@@ -0,0 +1,36 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+/**
+ * A notification as the app's events see it: { id, title, body, data, categoryId, badge }.
+ *
+ * @param {Object} notification An expo-notifications Notification.
+ */
+function toNotificationEvent(notification) {
+  const { content, identifier } = notification.request;
+  return {
+    id: identifier,
+    title: content.title ?? null,
+    body: content.body ?? null,
+    data: type.isObject(content.data) ? content.data : {},
+    categoryId: content.categoryIdentifier ?? null,
+    badge: content.badge ?? null,
+  };
+}
+
+export default toNotificationEvent;

package/src/notifications/toScheduleRequest.js

@@ -0,0 +1,62 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import * as Notifications from 'expo-notifications';
+import { type } from '@lowdefy/helpers';
+
+function getTrigger({ at, repeats, seconds }) {
+  if (type.isString(at)) {
+    const date = new Date(at);
+    if (Number.isNaN(date.getTime())) {
+      throw new Error(`ScheduleNotification "at" should be an ISO date-time. Received "${at}".`);
+    }
+    return { type: Notifications.SchedulableTriggerInputTypes.DATE, date };
+  }
+  if (type.isNumber(seconds)) {
+    if (repeats === true && seconds < 60) {
+      throw new Error('ScheduleNotification with "repeats" needs "seconds" of 60 or more.');
+    }
+    return {
+      type: Notifications.SchedulableTriggerInputTypes.TIME_INTERVAL,
+      seconds: Math.max(1, seconds),
+      repeats: repeats === true,
+    };
+  }
+  return null;
+}
+
+/**
+ * ScheduleNotification's params as an expo-notifications request: shown now with neither `at` nor
+ * `seconds`. `path` goes into data.path, which a tap opens.
+ *
+ * @param {Object} params ScheduleNotification's params.
+ */
+function toScheduleRequest(params) {
+  const { badge, body, categoryId, data, id, path, title } = params;
+  return {
+    identifier: id,
+    content: {
+      title,
+      body,
+      data: { ...(data ?? {}), ...(type.isString(path) ? { path } : {}) },
+      categoryIdentifier: categoryId,
+      badge,
+    },
+    trigger: getTrigger(params),
+  };
+}
+
+export default toScheduleRequest;

package/src/plugins/appTypes.js

@@ -0,0 +1,28 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// The native types of the app's shell plugins (shell.json `plugins`), which src/plugins/types.js
+// registers after the built-in types. The shell package ships it empty; `lowdefy mobile config`
+// rewrites it in the copied shell to import each plugin's `./native`, with its typePrefix applied:
+//
+//   import * as plugin0 from '@example/lowdefy-printer/native';
+//   import prefixTypes from './prefixTypes.js';
+//
+//   export default {
+//     actions: { ...prefixTypes({ types: plugin0.actions, typePrefix: 'Printer' }) },
+//     blocks: { ...prefixTypes({ types: plugin0.blocks, typePrefix: 'Printer' }) },
+//   };
+export default { actions: {}, blocks: {} };

package/src/plugins/prefixTypes.js

@@ -0,0 +1,28 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// A shell plugin's native types with its typePrefix (shell.json `plugins[].typePrefix`) on each
+// name, as the type manifest names them (scripts/createTypeManifest.mjs).
+function prefixTypes({ types, typePrefix }) {
+  return Object.fromEntries(
+    Object.entries(types ?? {}).map(([name, implementation]) => [
+      `${typePrefix ?? ''}${name}`,
+      implementation,
+    ])
+  );
+}
+
+export default prefixTypes;

package/src/plugins/shellPlugins.json

@@ -0,0 +1,15 @@
+[
+  { "category": "actions", "package": "@lowdefy/actions-core" },
+  { "category": "actions", "package": "@lowdefy/blocks-native" },
+  { "category": "blocks", "package": "@lowdefy/blocks-native" },
+  { "category": "operators", "package": "@lowdefy/operators-js" },
+  { "category": "operators", "package": "@lowdefy/operators-change-case" },
+  { "category": "operators", "package": "@lowdefy/operators-cron" },
+  { "category": "operators", "package": "@lowdefy/operators-dayjs" },
+  { "category": "operators", "package": "@lowdefy/operators-diff" },
+  { "category": "operators", "package": "@lowdefy/operators-jsonata" },
+  { "category": "operators", "package": "@lowdefy/operators-mql" },
+  { "category": "operators", "package": "@lowdefy/operators-nunjucks" },
+  { "category": "operators", "package": "@lowdefy/operators-uuid" },
+  { "category": "operators", "package": "@lowdefy/operators-yaml" }
+]