@actual-app/core 26.3.0

package/src/shared/currencies.ts

@@ -0,0 +1,70 @@
+import type { NumberFormats } from './util';
+
+export type Currency = {
+  code: string;
+  symbol: string;
+  name: string;
+  decimalPlaces: number;
+  numberFormat: NumberFormats;
+  symbolFirst: boolean;
+};
+
+// When adding a new currency with a higher decimal precision, make sure to update
+// the MAX_SAFE_NUMBER in util.ts.
+// When adding a currency, also update the translation map in
+// packages/desktop-client/src/components/settings/Currency.tsx for the translation.
+// Number formats and symbol placement based on CLDR (Common Locale Data Repository) /
+// LDML (Locale Data Markup Language) locale conventions and Intl.NumberFormat standards
+// References:
+// https://www.localeplanet.com/icu/decimal-symbols.html
+// https://www.localeplanet.com/api/auto/currencymap.html
+// prettier-ignore
+export const currencies: Currency[] = [
+  { code: '', name: 'None', symbol: '', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'AED', name: 'UAE Dirham', symbol: 'د.إ', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: false },
+  { code: 'ARS', name: 'Argentinian Peso', symbol: 'Arg$', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: true },
+  { code: 'AUD', name: 'Australian Dollar', symbol: 'A$', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'BRL', name: 'Brazilian Real', symbol: 'R$', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: true },
+  { code: 'BYN', name: 'Belarusian Ruble', symbol: 'Br', decimalPlaces: 2, numberFormat: 'space-comma', symbolFirst: false },
+  { code: 'CAD', name: 'Canadian Dollar', symbol: 'CA$', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'CHF', name: 'Swiss Franc', symbol: 'Fr.', decimalPlaces: 2, numberFormat: 'apostrophe-dot', symbolFirst: true },
+  { code: 'CNY', name: 'Yuan Renminbi', symbol: '¥', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'COP', name: 'Colombian Peso', symbol: 'Col$', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: true },
+  { code: 'CRC', name: 'Costa Rican Colón', symbol: '₡', decimalPlaces: 2, numberFormat: 'space-comma', symbolFirst: true },
+  { code: 'CZK', name: 'Czech Koruna', symbol: 'Kč', decimalPlaces: 2, numberFormat: 'space-comma', symbolFirst: false },
+  { code: 'DKK', name: 'Danish Krone', symbol: 'kr', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: false },
+  { code: 'DOP', name: 'Dominican Peso', symbol: 'RD$', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'EGP', name: 'Egyptian Pound', symbol: 'ج.م', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: false },
+  { code: 'EUR', name: 'Euro', symbol: '€', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: false },
+  { code: 'GBP', name: 'Pound Sterling', symbol: '£', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'GTQ', name: 'Guatemalan Quetzal', symbol: 'Q', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'HKD', name: 'Hong Kong Dollar', symbol: 'HK$', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'HUF', name: 'Hungarian Forint', symbol: 'Ft', decimalPlaces: 2, numberFormat: 'space-comma', symbolFirst: false },
+  { code: 'IDR', name: 'Indonesian Rupiah', symbol: 'Rp', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: true },
+  { code: 'INR', name: 'Indian Rupee', symbol: '₹', decimalPlaces: 2, numberFormat: 'comma-dot-in', symbolFirst: true },
+  { code: 'JMD', name: 'Jamaican Dollar', symbol: 'J$', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'JPY', name: 'Japanese Yen', symbol: '¥', decimalPlaces: 0, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'KRW', name: 'South Korean Won', symbol: '₩', decimalPlaces: 0, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'LKR', name: 'Sri Lankan Rupee', symbol: 'Rs.', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'MDL', name: 'Moldovan Leu', symbol: 'L', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: false },
+  { code: 'MYR', name: 'Malaysian Ringgit', symbol: 'RM', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'PHP', name: 'Philippine Peso', symbol: '₱', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'PLN', name: 'Polish Złoty', symbol: 'zł', decimalPlaces: 2, numberFormat: 'space-comma', symbolFirst: false },
+  { code: 'QAR', name: 'Qatari Riyal', symbol: 'ر.ق', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: false },
+  { code: 'RON', name: 'Romanian Leu', symbol: 'lei', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: false },
+  { code: 'RSD', name: 'Serbian Dinar', symbol: 'дин', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: false },
+  { code: 'RUB', name: 'Russian Ruble', symbol: '₽', decimalPlaces: 2, numberFormat: 'space-comma', symbolFirst: false },
+  { code: 'SAR', name: 'Saudi Riyal', symbol: 'ر.س', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: false },
+  { code: 'SEK', name: 'Swedish Krona', symbol: 'kr', decimalPlaces: 2, numberFormat: 'space-comma', symbolFirst: false },
+  { code: 'SGD', name: 'Singapore Dollar', symbol: 'S$', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'THB', name: 'Thai Baht', symbol: '฿', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'TRY', name: 'Turkish Lira', symbol: '₺', decimalPlaces: 2, numberFormat: 'dot-comma', symbolFirst: true },
+  { code: 'TWD', name: 'New Taiwan Dollar', symbol: 'NT$', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'UAH', name: 'Ukrainian Hryvnia', symbol: '₴', decimalPlaces: 2, numberFormat: 'space-comma', symbolFirst: false },
+  { code: 'USD', name: 'US Dollar', symbol: '$', decimalPlaces: 2, numberFormat: 'comma-dot', symbolFirst: true },
+  { code: 'UZS', name: 'Uzbek Soum', symbol: 'UZS', decimalPlaces: 2, numberFormat: 'space-comma', symbolFirst: false },
+];
+
+export function getCurrency(code: string): Currency {
+  return currencies.find(c => c.code === code) || currencies[0];
+}

package/src/shared/dashboard.ts

@@ -0,0 +1,260 @@
+import type { NewDashboardWidgetEntity } from '../types/models';
+
+export const DEFAULT_DASHBOARD_STATE: NewDashboardWidgetEntity[] = [
+  // Top row: Key metrics at a glance
+  {
+    type: 'summary-card',
+    width: 3,
+    height: 2,
+    x: 0,
+    y: 0,
+    meta: {
+      name: 'Total Income (YTD)',
+      content: JSON.stringify({
+        type: 'sum',
+        fontSize: 20,
+      }),
+      timeFrame: {
+        start: '2024-01-01',
+        end: '2024-12-31',
+        mode: 'yearToDate',
+      },
+      conditions: [
+        {
+          field: 'amount',
+          op: 'gt',
+          value: 0,
+        },
+        {
+          field: 'account',
+          op: 'onBudget',
+          value: '',
+        },
+        {
+          field: 'transfer',
+          op: 'is',
+          value: false,
+        },
+      ],
+      conditionsOp: 'and',
+    },
+  },
+  {
+    type: 'summary-card',
+    width: 3,
+    height: 2,
+    x: 3,
+    y: 0,
+    meta: {
+      name: 'Total Expenses (YTD)',
+      content: JSON.stringify({
+        type: 'sum',
+        fontSize: 20,
+      }),
+      timeFrame: {
+        start: '2024-01-01',
+        end: '2024-12-31',
+        mode: 'yearToDate',
+      },
+      conditions: [
+        {
+          field: 'amount',
+          op: 'lt',
+          value: 0,
+        },
+        {
+          field: 'account',
+          op: 'onBudget',
+          value: '',
+        },
+        {
+          field: 'transfer',
+          op: 'is',
+          value: false,
+        },
+      ],
+      conditionsOp: 'and',
+    },
+  },
+  {
+    type: 'summary-card',
+    width: 3,
+    height: 2,
+    x: 6,
+    y: 0,
+    meta: {
+      name: 'Avg Per Month',
+      content: JSON.stringify({
+        type: 'avgPerMonth',
+        fontSize: 20,
+      }),
+      timeFrame: {
+        start: '2024-01-01',
+        end: '2024-12-31',
+        mode: 'yearToDate',
+      },
+      conditions: [
+        {
+          field: 'amount',
+          op: 'lt',
+          value: 0,
+        },
+        {
+          field: 'account',
+          op: 'onBudget',
+          value: '',
+        },
+        {
+          field: 'transfer',
+          op: 'is',
+          value: false,
+        },
+      ],
+      conditionsOp: 'and',
+    },
+  },
+  {
+    type: 'summary-card',
+    width: 3,
+    height: 2,
+    x: 9,
+    y: 0,
+    meta: {
+      name: 'Avg Per Transaction',
+      content: JSON.stringify({
+        type: 'avgPerTransact',
+        fontSize: 20,
+      }),
+      timeFrame: {
+        start: '2024-01-01',
+        end: '2024-12-31',
+        mode: 'yearToDate',
+      },
+      conditions: [
+        {
+          field: 'amount',
+          op: 'lt',
+          value: 0,
+        },
+        {
+          field: 'account',
+          op: 'onBudget',
+          value: '',
+        },
+        {
+          field: 'transfer',
+          op: 'is',
+          value: false,
+        },
+      ],
+      conditionsOp: 'and',
+    },
+  },
+  // Second row: Net worth and cash flow side by side
+  {
+    type: 'net-worth-card',
+    width: 6,
+    height: 2,
+    x: 0,
+    y: 2,
+    meta: null,
+  },
+  {
+    type: 'cash-flow-card',
+    width: 6,
+    height: 2,
+    x: 6,
+    y: 2,
+    meta: null,
+  },
+  // Third row: Spending comparisons
+  {
+    type: 'spending-card',
+    width: 4,
+    height: 2,
+    x: 0,
+    y: 5,
+    meta: {
+      name: 'This Month',
+      mode: 'single-month',
+    },
+  },
+  {
+    type: 'spending-card',
+    width: 4,
+    height: 2,
+    x: 4,
+    y: 5,
+    meta: {
+      name: 'Budget Overview',
+      mode: 'budget',
+    },
+  },
+  {
+    type: 'spending-card',
+    width: 4,
+    height: 2,
+    x: 8,
+    y: 5,
+    meta: {
+      name: '3-Month Average',
+      mode: 'average',
+    },
+  },
+  // Fourth row: Calendar and savings rate
+  {
+    type: 'calendar-card',
+    width: 8,
+    height: 4,
+    x: 0,
+    y: 8,
+    meta: {
+      name: 'Transaction Calendar',
+      timeFrame: {
+        start: '2024-01-01',
+        end: '2024-03-31',
+        mode: 'sliding-window',
+      },
+      conditions: [
+        {
+          field: 'transfer',
+          op: 'is',
+          value: false,
+        },
+      ],
+      conditionsOp: 'and',
+    },
+  },
+  {
+    type: 'summary-card',
+    width: 4,
+    height: 2,
+    x: 8,
+    y: 8,
+    meta: {
+      name: 'Recent Net Worth Change',
+      content: JSON.stringify({
+        type: 'sum',
+        fontSize: 32,
+      }),
+      timeFrame: {
+        start: '2024-01-01',
+        end: '2024-03-31',
+        mode: 'sliding-window',
+      },
+      conditions: [],
+      conditionsOp: 'and',
+    },
+  },
+  {
+    type: 'markdown-card',
+    width: 4,
+    height: 2,
+    x: 8,
+    y: 10,
+    meta: {
+      content:
+        '## Dashboard Tips\n\nYou can add new widgets or edit existing widgets by using the buttons at the top of the page. Choose a widget type and customize it to fit your needs.\n\n**Moving cards:** Drag any card by its header to reposition it.\n\n**Deleting cards:** Click the three-dot menu on any card and select "Remove".',
+    },
+  },
+];

package/src/shared/environment.ts

@@ -0,0 +1,18 @@
+export function isPreviewEnvironment() {
+  return String(process.env.REACT_APP_NETLIFY) === 'true';
+}
+
+export function isDevelopmentEnvironment() {
+  return process.env.NODE_ENV === 'development';
+}
+
+export function isNonProductionEnvironment() {
+  return isPreviewEnvironment() || isDevelopmentEnvironment();
+}
+
+export function isElectron() {
+  if (navigator.userAgent.indexOf('Electron') >= 0) {
+    return true;
+  }
+  return false;
+}

package/src/shared/errors.ts

@@ -0,0 +1,195 @@
+import { t } from 'i18next';
+
+type ErrorWithMeta = {
+  reason: string;
+  meta?: unknown;
+};
+
+export function getUploadError({ reason, meta }: ErrorWithMeta) {
+  switch (reason) {
+    case 'unauthorized':
+      return t('You are not logged in.');
+    case 'encrypt-failure':
+      if ((meta as { isMissingKey: boolean }).isMissingKey) {
+        return t(
+          'Encrypting your file failed because you are missing your encryption key. Create your key in the next step.',
+        );
+      }
+      return t(
+        'Encrypting the file failed. You have the correct key so this is an internal bug. To fix this, generate a new key in the next step.',
+      );
+    case 'file-has-reset':
+      // Something really weird happened - during reset a sanity
+      // check on the server failed. The user just needs to
+      // restart the whole process.
+      return t(
+        'Something went wrong while resetting your file. Please try again.',
+      );
+    case 'file-has-new-key':
+      return t(
+        'Unable to encrypt your data because you are missing the key. Create the latest key in the next step.',
+      );
+    case 'network':
+      return t('Uploading the file failed. Check your network connection.');
+    default:
+      return t(
+        'An internal error occurred, sorry! Visit https://actualbudget.org/contact/ for support. (ref: {{reason}})',
+        { reason },
+      );
+  }
+}
+
+export function getDownloadError({
+  reason,
+  meta,
+  fileName,
+}: {
+  reason: string;
+  meta?: unknown;
+  fileName?: string;
+}) {
+  switch (reason) {
+    case 'network':
+    case 'download-failure':
+      return t('Downloading the file failed. Check your network connection.');
+    case 'not-zip-file':
+    case 'invalid-zip-file':
+    case 'invalid-meta-file':
+      return t(
+        'Downloaded file is invalid, sorry! Visit https://actualbudget.org/contact/ for support.',
+      );
+    case 'decrypt-failure':
+      return (
+        'Unable to decrypt file ' +
+        (fileName || '(unknown)') +
+        '. To change your key, first ' +
+        'download this file with the proper password.'
+      );
+
+    case 'out-of-sync-migrations':
+      return t(
+        'This budget cannot be loaded with this version of the app. Make sure the app is up-to-date.',
+      );
+
+    case 'clock-drift':
+      return t(
+        'Failed to download the budget because your device time differs too much from the server. Please check your device time settings and ensure they are correct.',
+      );
+
+    default:
+      const info =
+        meta && typeof meta === 'object' && 'fileId' in meta && meta.fileId
+          ? `, fileId: ${String(meta.fileId)}`
+          : '';
+      return t(
+        'Something went wrong trying to download that file, sorry! Visit https://actualbudget.org/contact/ for support. reason: {{reason}}{{info}}',
+        { reason, info },
+      );
+  }
+}
+
+export function getCreateKeyError(error: ErrorWithMeta) {
+  return getUploadError(error);
+}
+
+export function getTestKeyError({ reason }: ErrorWithMeta) {
+  switch (reason) {
+    case 'network':
+      return t(
+        'Unable to connect to the server. We need to access the server to get some information about your keys.',
+      );
+    case 'old-key-style':
+      return t(
+        'This file is encrypted with an old unsupported key style. Recreate the key on a device where the file is available, or use an older version of Actual to download it.',
+      );
+    case 'decrypt-failure':
+      return t('Unable to decrypt file with this password. Please try again.');
+    default:
+      return t(
+        'Something went wrong trying to create a key, sorry! Visit https://actualbudget.org/contact/ for support.',
+      );
+  }
+}
+
+export function getSyncError(error: string, id: string) {
+  if (error === 'out-of-sync-migrations' || error === 'out-of-sync-data') {
+    return t('This budget cannot be loaded with this version of the app.');
+  } else if (error === 'budget-not-found') {
+    return t(
+      'Budget "{{id}}" not found. Check the ID of your budget in the Advanced section of the settings page.',
+      { id },
+    );
+  } else if (error === 'clock-drift') {
+    return t(
+      'Failed to sync because your device time differs too much from the server. Please check your device time settings and ensure they are correct.',
+    );
+  } else {
+    return t('We had an unknown problem opening "{{id}}".', { id });
+  }
+}
+
+export function getBankSyncError(error: { message?: string }) {
+  return error.message || t('We had an unknown problem syncing the account.');
+}
+
+export class LazyLoadFailedError extends Error {
+  type = 'app-init-failure';
+  meta = {};
+
+  constructor(name: string, cause: unknown) {
+    super(`Error: failed loading lazy-loaded module ${name}`);
+    this.meta = { name };
+    this.cause = cause;
+  }
+}
+
+export function getUserAccessErrors(reason: string) {
+  switch (reason) {
+    case 'unauthorized':
+      return t('You are not logged in.');
+    case 'token-expired':
+      return t('Login expired, please log in again.');
+    case 'user-cant-be-empty':
+      return t('Please select a user.');
+    case 'invalid-file-id':
+      return t('This file is invalid.');
+    case 'file-denied':
+      return t('You don`t have permissions over this file.');
+    case 'user-already-have-access':
+      return t('User already has access.');
+    default:
+      return t(
+        'An internal error occurred, sorry! Visit https://actualbudget.org/contact/ for support. (ref: {{reason}})',
+        { reason },
+      );
+  }
+}
+
+export function getSecretsError(error: string, reason: string) {
+  switch (reason) {
+    case 'unauthorized':
+      return t('You are not logged in.');
+    case 'not-admin':
+      return t('You have to be admin to set secrets');
+    default:
+      return error;
+  }
+}
+
+export function getOpenIdErrors(reason: string) {
+  switch (reason) {
+    case 'unauthorized':
+      return t('You are not logged in.');
+    case 'configuration-error':
+      return t('This configuration is not valid. Please check it again.');
+    case 'unable-to-change-file-config-enabled':
+      return t(
+        'Unable to enable OpenID. Please update the config.json file in this case.',
+      );
+    default:
+      return t(
+        'An internal error occurred, sorry! Visit https://actualbudget.org/contact/ for support. (ref: {{reason}})',
+        { reason },
+      );
+  }
+}

package/src/shared/locale.ts

@@ -0,0 +1,27 @@
+import * as localesNamespace from 'date-fns/locale';
+
+// Spread into plain object to allow dynamic access without ESLint namespace warnings
+const locales: Record<string, localesNamespace.Locale> = {
+  ...localesNamespace,
+};
+
+export function getLocale(language: string) {
+  if (!language || typeof language !== 'string') {
+    return locales.enUS;
+  }
+
+  let localeKey = language.replace('-', '');
+
+  if (localeKey in locales) {
+    return locales[localeKey];
+  }
+
+  //if language was not found with four letters, try with two
+  localeKey = language.replace('-', '').substring(0, 2);
+
+  if (localeKey in locales) {
+    return locales[localeKey];
+  }
+
+  return locales.enUS;
+}

package/src/shared/location-utils.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+
+import { calculateDistance, formatDistance } from './location-utils';
+
+describe('Location Utils', () => {
+  describe('calculateDistance', () => {
+    it('calculates distance between same location as 0', () => {
+      const pos = { latitude: 40.7128, longitude: -74.006 };
+      const distance = calculateDistance(pos, pos);
+      expect(distance).toBe(0);
+    });
+
+    it('calculates distance between known coordinates accurately', () => {
+      // NYC to Philadelphia (approximately 129 km)
+      const nyc = { latitude: 40.7128, longitude: -74.006 };
+      const philly = { latitude: 39.9526, longitude: -75.1652 };
+
+      const distance = calculateDistance(nyc, philly);
+      // Should be approximately 129,000meters (allow 5% variance for rounding)
+      expect(distance).toBeGreaterThan(122000);
+      expect(distance).toBeLessThan(136000);
+    });
+
+    it('calculates short distances accurately', () => {
+      // Two points very close together (about 100m apart in NYC)
+      const pos1 = { latitude: 40.7128, longitude: -74.006 };
+      const pos2 = { latitude: 40.7137, longitude: -74.0068 }; // ~100m north
+
+      const distance = calculateDistance(pos1, pos2);
+      // Should be approximately 100meters (allow reasonable variance for coord precision)
+      expect(distance).toBeGreaterThan(90);
+      expect(distance).toBeLessThan(130);
+    });
+
+    it('handles cross-equator distances', () => {
+      const northPole = { latitude: 89.0, longitude: 0 };
+      const southPole = { latitude: -89.0, longitude: 0 };
+
+      const distance = calculateDistance(northPole, southPole);
+      // Should be very large (close to half Earth's circumference)
+      expect(distance).toBeGreaterThan(19000000); // > 19,000 km
+    });
+
+    it('handles cross-meridian distances', () => {
+      const nearAntimeridianEast = { latitude: 51.5074, longitude: 179 };
+      const nearAntimeridianWest = { latitude: 51.5074, longitude: -179 };
+
+      const distance = calculateDistance(
+        nearAntimeridianEast,
+        nearAntimeridianWest,
+      );
+      // Should be a reasonable distance, not the long way around
+      expect(distance).toBeGreaterThan(0);
+      expect(distance).toBeLessThan(1000000); // < 1000 km
+    });
+  });
+
+  describe('formatDistance', () => {
+    it('formats feet/meters correctly', () => {
+      expect(formatDistance(0)).toBe('0ft | 0m');
+      expect(formatDistance(0.9)).toBe('3ft | 1m');
+      expect(formatDistance(50)).toBe('164ft | 50m');
+      expect(formatDistance(500)).toBe('1640ft | 500m');
+      expect(formatDistance(1000)).toBe('3281ft | 1000m');
+      expect(formatDistance(1500)).toBe('4921ft | 1500m');
+      expect(formatDistance(2500)).toBe('8202ft | 2500m');
+    });
+  });
+});

package/src/shared/location-utils.ts

@@ -0,0 +1,49 @@
+/**
+ * Pure utility functions for location calculations and formatting.
+ * These functions have no side effects and can be easily tested.
+ */
+
+const metersToFeet = 3.28084;
+
+export type LocationCoordinates = {
+  latitude: number;
+  longitude: number;
+};
+
+/**
+ * Calculate the distance between two geographic coordinates using the Haversine formula
+ * @param pos1 First position coordinates
+ * @param pos2 Second position coordinates
+ * @returns Distance in meters
+ */
+export function calculateDistance(
+  pos1: LocationCoordinates,
+  pos2: LocationCoordinates,
+): number {
+  const R = 6371e3; // Earth's radius in meters
+  const phi1 = (pos1.latitude * Math.PI) / 180;
+  const phi2 = (pos2.latitude * Math.PI) / 180;
+  const deltaPhi = ((pos2.latitude - pos1.latitude) * Math.PI) / 180;
+  const deltaLambda = ((pos2.longitude - pos1.longitude) * Math.PI) / 180;
+
+  const a =
+    Math.sin(deltaPhi / 2) * Math.sin(deltaPhi / 2) +
+    Math.cos(phi1) *
+      Math.cos(phi2) *
+      Math.sin(deltaLambda / 2) *
+      Math.sin(deltaLambda / 2);
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+
+  return R * c; // Distance in meters
+}
+
+/**
+ * Format a distance in meters to a human-readable string
+ * @param meters Distance in meters
+ * @returns Formatted distance string
+ */
+export function formatDistance(meters: number): string {
+  const distanceImperial = `${Math.round(meters * metersToFeet)}ft`;
+  const distanceMetric = `${Math.round(meters)}m`;
+  return `${distanceImperial} | ${distanceMetric}`;
+}