@lowdefy/shell 3.23.2 → 7.2.0

package/src/device/field/createLocationFeature.js

@@ -0,0 +1,39 @@
+/*
+  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 Location from 'expo-location';
+
+/**
+ * The location device feature (profile field): GeolocationCurrentPosition reads the phone's
+ * position, asking for location while in use the first time. Answers as the web's geolocation
+ * does: { coords, timestamp }, or the PERMISSION_DENIED shape when refused.
+ */
+function createLocationFeature() {
+  return {
+    async current({ enableHighAccuracy = false } = {}) {
+      const { granted } = await Location.requestForegroundPermissionsAsync();
+      if (!granted) {
+        return { code: 1, error: 'PERMISSION_DENIED', message: 'Location permission was denied.' };
+      }
+      const position = await Location.getCurrentPositionAsync({
+        accuracy: enableHighAccuracy ? Location.Accuracy.High : Location.Accuracy.Balanced,
+      });
+      return { coords: position.coords, timestamp: position.timestamp };
+    },
+  };
+}
+
+export default createLocationFeature;

package/src/device/field/createScanRequests.js

@@ -0,0 +1,55 @@
+/*
+  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 ScanCode requests the scan sheet answers: one at a time. `open` resolves with the first code
+ * read, or null when the sheet closes without one; a request made while one is open replaces it
+ * (the first resolves null).
+ */
+function createScanRequests() {
+  let current = null;
+  const listeners = new Set();
+
+  function notify() {
+    listeners.forEach((listener) => listener(current));
+  }
+
+  function finish(result) {
+    if (current === null) return;
+    const { resolve } = current;
+    current = null;
+    notify();
+    resolve(result);
+  }
+
+  return {
+    open(params) {
+      finish(null);
+      return new Promise((resolve) => {
+        current = { params, resolve };
+        notify();
+      });
+    },
+    finish,
+    get: () => current,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+export default createScanRequests;

package/src/device/field/index.js

@@ -0,0 +1,39 @@
+/*
+  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 createAudioFeature from './createAudioFeature.js';
+import createBrightnessFeature from './createBrightnessFeature.js';
+import createCameraFeature from './createCameraFeature.js';
+import createDocumentScannerFeature from './createDocumentScannerFeature.js';
+import createLocationFeature from './createLocationFeature.js';
+import MapView from './MapView.js';
+import ScanCodeSheet from './ScanCodeSheet.js';
+
+// The `field` profile's device features (profiles.js FIELD_ENTRY). A shell on another profile
+// resolves this module to an empty one (metro.config.js), so it links none of their modules.
+const features = {
+  audio: createAudioFeature(),
+  brightness: createBrightnessFeature(),
+  camera: createCameraFeature(),
+  documentScanner: createDocumentScannerFeature(),
+  location: createLocationFeature(),
+  maps: { MapView },
+};
+
+// Views the features open at the root (DeviceHosts).
+const hosts = [ScanCodeSheet];
+
+export { features, hosts };

package/src/device/field/scanRequests.js

@@ -0,0 +1,22 @@
+/*
+  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 createScanRequests from './createScanRequests.js';
+
+// The shell's one set of ScanCode requests, shared by the action and the sheet.
+const scanRequests = createScanRequests();
+
+export default scanRequests;

package/src/device/injected.js

@@ -0,0 +1,60 @@
+/*
+  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 injector Lowdefy Dev installs (src/dev/inject). A release shell never installs one.
+let injector = null;
+
+/**
+ * The next device result Lowdefy Dev was told to fake, or undefined when there is none: in a
+ * release shell always. A device action reads it first, in one line, and uses the device only when
+ * nothing was injected:
+ *
+ *   const scan = injected('scan');
+ *   if (scan !== undefined) return scan;
+ *
+ * Names:
+ * - `scan`: the next ScanCode or QRScanner read, `{ data, type }`.
+ * - `photo`: the next TakePhoto or PickImage result, `{ base64, mimeType, width, height }`.
+ * - `nfc`: the next ReadNfc read.
+ * - `transcript`: what the next dictation session hears, `{ partials?, final }` or `{ error }`.
+ *   Dictation (blocks-native) reads it through the source Lowdefy Dev installs with
+ *   installDictationSource.
+ * - `location`: the location GeolocationCurrentPosition and geofences read,
+ *   `{ latitude, longitude, accuracy, ... }`.
+ * - `permission:<name>`: the answer to the next request for a permission, 'granted' or 'denied'
+ *   (`permission:microphone` for dictation).
+ *
+ * @param {string} name
+ */
+function injected(name) {
+  if (injector === null) {
+    return undefined;
+  }
+  return injector.take(name);
+}
+
+// Installs the injector `injected` reads (`{ take(name) }`); returns the function that removes it.
+function installInjector(next) {
+  injector = next;
+  return () => {
+    if (injector === next) {
+      injector = null;
+    }
+  };
+}
+
+export { installInjector };
+export default injected;

package/src/device/injected.test.js

@@ -0,0 +1,39 @@
+/*
+  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 injected, { installInjector } from './injected.js';
+
+test('with no injector installed, as in a release shell, nothing is injected', () => {
+  expect(injected('scan')).toBeUndefined();
+  expect(injected('permission:camera')).toBeUndefined();
+});
+
+test('injected reads the installed injector until it is removed', () => {
+  const take = (name) => `next ${name}`;
+  const remove = installInjector({ take });
+  expect(injected('scan')).toBe('next scan');
+  remove();
+  expect(injected('scan')).toBeUndefined();
+});
+
+test('removing an injector that was replaced leaves the newer one installed', () => {
+  const removeFirst = installInjector({ take: () => 'first' });
+  const removeSecond = installInjector({ take: () => 'second' });
+  removeFirst();
+  expect(injected('scan')).toBe('second');
+  removeSecond();
+  expect(injected('scan')).toBeUndefined();
+});

package/src/device/nfc/index.js

@@ -0,0 +1,89 @@
+/*
+  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 NfcManager, { Ndef, NfcError, NfcTech } from 'react-native-nfc-manager';
+
+import toNfcRecord from './toNfcRecord.js';
+
+let started = null;
+
+function start() {
+  if (started === null) {
+    started = NfcManager.start();
+  }
+  return started;
+}
+
+// Runs one NFC session: waits for a tag, works with it, and always ends the session. A cancelled
+// sheet answers null.
+async function withTag(prompt, work) {
+  await start();
+  try {
+    await NfcManager.requestTechnology(NfcTech.Ndef, { alertMessage: prompt });
+    return await work();
+  } catch (error) {
+    if (error instanceof NfcError.UserCancel) {
+      return null;
+    }
+    throw error;
+  } finally {
+    NfcManager.cancelTechnologyRequest().catch(() => {});
+  }
+}
+
+function toRecordBytes(records) {
+  return Ndef.encodeMessage(
+    records.map((record) =>
+      record.type === 'uri'
+        ? Ndef.uriRecord(record.value)
+        : Ndef.textRecord(record.value, record.language ?? 'en')
+    )
+  );
+}
+
+/**
+ * The nfc device feature (profile field-nfc): ReadNfc and WriteNfc on NDEF tags
+ * (react-native-nfc-manager). iOS shows its scan sheet with the prompt.
+ */
+const nfc = {
+  read({ prompt = 'Hold the phone near the tag.' } = {}) {
+    return withTag(prompt, async () => {
+      const tag = await NfcManager.getTag();
+      return {
+        id: tag?.id ?? null,
+        type: tag?.type ?? tag?.tech ?? null,
+        records: (tag?.ndefMessage ?? []).map((record) => toNfcRecord({ Ndef, record })),
+      };
+    });
+  },
+  write({ prompt = 'Hold the phone near the tag to write it.', records }) {
+    return withTag(prompt, async () => {
+      await NfcManager.ndefHandler.writeNdefMessage(toRecordBytes(records));
+      if (Platform.OS === 'ios') {
+        await NfcManager.setAlertMessage('Done');
+      }
+      const tag = await NfcManager.getTag();
+      return { id: tag?.id ?? null };
+    });
+  },
+};
+
+// The `field-nfc` profile's device features (profiles.js NFC_ENTRY).
+const features = { nfc };
+const hosts = [];
+
+export { features, hosts };

package/src/device/nfc/toNfcRecord.js

@@ -0,0 +1,44 @@
+/*
+  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.
+*/
+
+function typeText(recordType) {
+  if (typeof recordType === 'string') {
+    return recordType;
+  }
+  return String.fromCharCode(...recordType);
+}
+
+/**
+ * One NDEF record as ReadNfc returns it: { type, text?, uri?, payload }. Text and URI records are
+ * decoded; any other record keeps its raw payload bytes.
+ *
+ * @param {Object} params
+ * @param {Object} params.record A react-native-nfc-manager NdefRecord.
+ * @param {Object} params.Ndef react-native-nfc-manager's Ndef helpers.
+ */
+function toNfcRecord({ Ndef, record }) {
+  const recordType = typeText(record.type);
+  const payload = Array.from(record.payload ?? []);
+  if (record.tnf === Ndef.TNF_WELL_KNOWN && recordType === Ndef.RTD_TEXT) {
+    return { type: 'text', text: Ndef.text.decodePayload(Uint8Array.from(payload)), payload };
+  }
+  if (record.tnf === Ndef.TNF_WELL_KNOWN && recordType === Ndef.RTD_URI) {
+    return { type: 'uri', uri: Ndef.uri.decodePayload(Uint8Array.from(payload)), payload };
+  }
+  return { type: recordType, payload };
+}
+
+export default toNfcRecord;

package/src/device/nfc/toNfcRecord.test.js

@@ -0,0 +1,48 @@
+/*
+  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 toNfcRecord from './toNfcRecord.js';
+
+const Ndef = {
+  TNF_WELL_KNOWN: 0x01,
+  RTD_TEXT: 'T',
+  RTD_URI: 'U',
+  text: { decodePayload: () => 'ASSET-0042' },
+  uri: { decodePayload: () => 'https://example.com/a/42' },
+};
+
+test('toNfcRecord decodes a text record from iOS type bytes', () => {
+  expect(toNfcRecord({ Ndef, record: { tnf: 1, type: [0x54], payload: [2, 101, 110] } })).toEqual({
+    type: 'text',
+    text: 'ASSET-0042',
+    payload: [2, 101, 110],
+  });
+});
+
+test('toNfcRecord decodes a URI record from an Android type string', () => {
+  expect(toNfcRecord({ Ndef, record: { tnf: 1, type: 'U', payload: [4] } })).toEqual({
+    type: 'uri',
+    uri: 'https://example.com/a/42',
+    payload: [4],
+  });
+});
+
+test('toNfcRecord keeps the raw payload of any other record', () => {
+  expect(toNfcRecord({ Ndef, record: { tnf: 2, type: 'text/plain', payload: [1, 2] } })).toEqual({
+    type: 'text/plain',
+    payload: [1, 2],
+  });
+});

package/src/device/tracking/createBacklog.js

@@ -0,0 +1,63 @@
+/*
+  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 reportShellError from '../../host/reportShellError.js';
+
+// The most posts the backlog keeps; older ones are dropped first, so a phone left offline for days
+// does not fill its store.
+const MAX_ENTRIES = 500;
+
+/**
+ * Background posts that could not be sent (no signal, no session), kept in the device store and
+ * sent on the next wake, oldest first, as { endpointId, payload }.
+ *
+ * @param {Object} params
+ * @param {string} params.key The device store key.
+ * @param {{ get, set }} params.kv The device store.
+ */
+function createBacklog({ key, kv }) {
+  function read() {
+    return JSON.parse(kv.get(key) ?? '[]');
+  }
+  function write(entries) {
+    kv.set(key, JSON.stringify(entries.slice(-MAX_ENTRIES)));
+  }
+  return {
+    add(entry) {
+      write([...read(), entry]);
+    },
+    // Sends every kept post with `send`, stopping at the first failure (reported); the rest stay.
+    async flush(send) {
+      const entries = read();
+      let sent = 0;
+      for (const entry of entries) {
+        try {
+          await send(entry);
+        } catch (error) {
+          reportShellError({ error });
+          break;
+        }
+        sent += 1;
+      }
+      // Read again: a post added while these were sending stays behind them.
+      write(read().slice(sent));
+      return sent;
+    },
+    size: () => read().length,
+  };
+}
+
+export default createBacklog;

package/src/device/tracking/createBacklog.test.js

@@ -0,0 +1,47 @@
+/*
+  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 createBacklog from './createBacklog.js';
+import createNetworkError from '../../test/createNetworkError.js';
+
+function memoryKv() {
+  const values = new Map();
+  return { get: (key) => values.get(key) ?? null, set: (key, value) => values.set(key, value) };
+}
+
+test('a backlog sends its posts oldest first and keeps the rest after a failure', async () => {
+  const backlog = createBacklog({ key: 'k', kv: memoryKv() });
+  backlog.add({ endpointId: 'a', payload: 1 });
+  backlog.add({ endpointId: 'a', payload: 2 });
+  backlog.add({ endpointId: 'a', payload: 3 });
+  const sent = [];
+  const count = await backlog.flush(async (entry) => {
+    if (entry.payload === 2) throw createNetworkError();
+    sent.push(entry.payload);
+  });
+  expect(count).toBe(1);
+  expect(sent).toEqual([1]);
+  expect(backlog.size()).toBe(2);
+});
+
+test('a post added while the backlog flushes is kept', async () => {
+  const backlog = createBacklog({ key: 'k', kv: memoryKv() });
+  backlog.add({ endpointId: 'a', payload: 1 });
+  await backlog.flush(async () => {
+    backlog.add({ endpointId: 'a', payload: 2 });
+  });
+  expect(backlog.size()).toBe(1);
+});