@webwaka/core 1.3.0

package/src/core/chat/index.ts

@@ -0,0 +1,130 @@
+/**
+ * CORE-13: Real-Time Chat & Communication
+ * Blueprint Reference: Part 10 (All Verticals)
+ *
+ * In-app messaging system with offline sync support.
+ *
+ * Tenant Isolation: every mutating and querying method requires a tenantId.
+ * Channels and messages are scoped per tenant — cross-tenant leakage is impossible
+ * by construction.
+ */
+
+export interface Message {
+  id: string;
+  tenantId: string;
+  channelId: string;
+  senderId: string;
+  content: string;
+  type: 'text' | 'image' | 'system';
+  status: 'sent' | 'delivered' | 'read';
+  createdAt: Date;
+}
+
+export interface ChatChannel {
+  id: string;
+  tenantId: string;
+  participants: string[];
+  metadata: Record<string, any>;
+  createdAt: Date;
+}
+
+export class ChatEngine {
+  private channels: Map<string, ChatChannel> = new Map();
+  private messages: Map<string, Message[]> = new Map();
+
+  /**
+   * Creates a new chat channel between participants within a tenant.
+   */
+  createChannel(
+    tenantId: string,
+    participants: string[],
+    metadata: Record<string, any> = {}
+  ): ChatChannel {
+    const channel: ChatChannel = {
+      id: `ch_${crypto.randomUUID()}`,
+      tenantId,
+      participants,
+      metadata,
+      createdAt: new Date(),
+    };
+
+    this.channels.set(channel.id, channel);
+    this.messages.set(channel.id, []);
+
+    // eventBus.publish(WebWakaEventType.CHAT_CHANNEL_CREATED, createEvent(WebWakaEventType.CHAT_CHANNEL_CREATED, tenantId, channel));
+
+    return channel;
+  }
+
+  /**
+   * Sends a message to a channel, validating the channel belongs to the tenant.
+   */
+  sendMessage(
+    tenantId: string,
+    channelId: string,
+    senderId: string,
+    content: string,
+    type: 'text' | 'image' | 'system' = 'text'
+  ): Message {
+    const channel = this.channels.get(channelId);
+    if (!channel || channel.tenantId !== tenantId) {
+      throw new Error('Channel not found');
+    }
+
+    if (!channel.participants.includes(senderId) && type !== 'system') {
+      throw new Error('Sender is not a participant in this channel');
+    }
+
+    const message: Message = {
+      id: `msg_${crypto.randomUUID()}`,
+      tenantId,
+      channelId,
+      senderId,
+      content,
+      type,
+      status: 'sent',
+      createdAt: new Date(),
+    };
+
+    const channelMessages = this.messages.get(channelId) ?? [];
+    channelMessages.push(message);
+    this.messages.set(channelId, channelMessages);
+
+    // eventBus.publish(WebWakaEventType.CHAT_MESSAGE_SENT, createEvent(WebWakaEventType.CHAT_MESSAGE_SENT, tenantId, message));
+
+    return message;
+  }
+
+  /**
+   * Retrieves messages for a channel, scoped to the tenant.
+   */
+  getMessages(
+    tenantId: string,
+    channelId: string,
+    limit = 50,
+    offset = 0
+  ): Message[] {
+    const channel = this.channels.get(channelId);
+    if (!channel || channel.tenantId !== tenantId) {
+      return [];
+    }
+
+    const channelMessages = this.messages.get(channelId) ?? [];
+    return [...channelMessages].reverse().slice(offset, offset + limit);
+  }
+
+  /**
+   * Marks messages as read, scoped to the tenant.
+   */
+  markAsRead(tenantId: string, channelId: string, messageIds: string[]): void {
+    const channel = this.channels.get(channelId);
+    if (!channel || channel.tenantId !== tenantId) return;
+
+    const channelMessages = this.messages.get(channelId) ?? [];
+    for (const msg of channelMessages) {
+      if (messageIds.includes(msg.id)) {
+        msg.status = 'read';
+      }
+    }
+  }
+}

package/src/core/document/index.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { DocumentEngine } from './index';
+
+const T1 = 'tenant_alpha';
+const T2 = 'tenant_beta';
+
+describe('CORE-11: Document & Contract Management', () => {
+  let docEngine: DocumentEngine;
+
+  beforeEach(() => {
+    docEngine = new DocumentEngine();
+  });
+
+  it('should create a document in draft status', () => {
+    const doc = docEngine.createDocument(T1, 'Lease Agreement', 'Terms and conditions...');
+    expect(doc.title).toBe('Lease Agreement');
+    expect(doc.tenantId).toBe(T1);
+    expect(doc.status).toBe('draft');
+    expect(doc.signatures).toHaveLength(0);
+    expect(doc.id).toMatch(/^doc_/);
+    expect(doc.createdAt).toBeInstanceOf(Date);
+  });
+
+  it('should transition document to pending_signature', () => {
+    const doc = docEngine.createDocument(T1, 'Lease Agreement', 'Terms and conditions...');
+    const updatedDoc = docEngine.requestSignatures(T1, doc.id);
+    expect(updatedDoc.status).toBe('pending_signature');
+  });
+
+  it('should allow signing a pending document', () => {
+    const doc = docEngine.createDocument(T1, 'Lease Agreement', 'Terms and conditions...');
+    docEngine.requestSignatures(T1, doc.id);
+
+    const signedDoc = docEngine.signDocument(T1, doc.id, 'user_1', '192.168.1.1');
+    expect(signedDoc.status).toBe('signed');
+    expect(signedDoc.signatures).toHaveLength(1);
+    expect(signedDoc.signatures[0]!.userId).toBe('user_1');
+    expect(signedDoc.signatures[0]!.ipAddress).toBe('192.168.1.1');
+    expect(signedDoc.signatures[0]!.hash).toBeDefined();
+    expect(signedDoc.signatures[0]!.timestamp).toBeInstanceOf(Date);
+  });
+
+  it('should reject signing a draft document', () => {
+    const doc = docEngine.createDocument(T1, 'Lease Agreement', 'Terms and conditions...');
+
+    expect(() => {
+      docEngine.signDocument(T1, doc.id, 'user_1', '192.168.1.1');
+    }).toThrow('Document is not pending signature');
+  });
+
+  it('should throw when requesting signatures on non-existent document', () => {
+    expect(() => {
+      docEngine.requestSignatures(T1, 'doc_nonexistent');
+    }).toThrow('Document not found');
+  });
+
+  it('should throw when signing a non-existent document', () => {
+    expect(() => {
+      docEngine.signDocument(T1, 'doc_nonexistent', 'user_1', '10.0.0.1');
+    }).toThrow('Document not found');
+  });
+
+  it('should throw when requesting signatures on non-draft document', () => {
+    const doc = docEngine.createDocument(T1, 'Contract', 'Content');
+    docEngine.requestSignatures(T1, doc.id);
+
+    expect(() => {
+      docEngine.requestSignatures(T1, doc.id);
+    }).toThrow('Document must be in draft status to request signatures');
+  });
+
+  it('should throw when trying to sign an already-signed document', () => {
+    const doc = docEngine.createDocument(T1, 'Contract', 'Content');
+    docEngine.requestSignatures(T1, doc.id);
+    docEngine.signDocument(T1, doc.id, 'user_1', '10.0.0.1');
+
+    expect(() => {
+      docEngine.signDocument(T1, doc.id, 'user_2', '10.0.0.2');
+    }).toThrow('Document is not pending signature');
+  });
+
+  it('should assign unique IDs to each document', () => {
+    const d1 = docEngine.createDocument(T1, 'Doc A', 'Content A');
+    const d2 = docEngine.createDocument(T1, 'Doc B', 'Content B');
+    expect(d1.id).not.toBe(d2.id);
+  });
+
+  // ─── Cross-Tenant Isolation ───────────────────────────────────────────────
+
+  it('cross-tenant: tenant_B cannot request signatures on tenant_A document', () => {
+    const doc = docEngine.createDocument(T1, 'Lease Agreement', 'Content');
+
+    expect(() => {
+      docEngine.requestSignatures(T2, doc.id);
+    }).toThrow('Document not found');
+  });
+
+  it('cross-tenant: tenant_B cannot sign a tenant_A document', () => {
+    const doc = docEngine.createDocument(T1, 'Lease Agreement', 'Content');
+    docEngine.requestSignatures(T1, doc.id);
+
+    expect(() => {
+      docEngine.signDocument(T2, doc.id, 'user_1', '10.0.0.1');
+    }).toThrow('Document not found');
+  });
+});

package/src/core/document/index.ts

@@ -0,0 +1,99 @@
+/**
+ * CORE-11: Document & Contract Management
+ * Blueprint Reference: Part 10.5 (Real Estate), Part 10.12 (Legal)
+ *
+ * Secure system for generating, signing, and storing legal documents.
+ *
+ * Tenant Isolation: every mutating and querying method requires a tenantId.
+ * Documents are scoped per tenant — cross-tenant leakage is impossible by construction.
+ */
+
+export interface Document {
+  id: string;
+  tenantId: string;
+  title: string;
+  content: string;
+  status: 'draft' | 'pending_signature' | 'signed';
+  signatures: Signature[];
+  createdAt: Date;
+}
+
+export interface Signature {
+  userId: string;
+  timestamp: Date;
+  ipAddress: string;
+  hash: string;
+}
+
+export class DocumentEngine {
+  private documents: Map<string, Document> = new Map();
+
+  /**
+   * Creates a new document from a template, scoped to the tenant.
+   */
+  createDocument(tenantId: string, title: string, content: string): Document {
+    const doc: Document = {
+      id: `doc_${crypto.randomUUID()}`,
+      tenantId,
+      title,
+      content,
+      status: 'draft',
+      signatures: [],
+      createdAt: new Date(),
+    };
+    this.documents.set(doc.id, doc);
+    return doc;
+  }
+
+  /**
+   * Requests signatures for a document, scoped to the tenant.
+   */
+  requestSignatures(tenantId: string, documentId: string): Document {
+    const doc = this.documents.get(documentId);
+    if (!doc || doc.tenantId !== tenantId) throw new Error('Document not found');
+
+    if (doc.status !== 'draft') {
+      throw new Error('Document must be in draft status to request signatures');
+    }
+
+    doc.status = 'pending_signature';
+    return doc;
+  }
+
+  /**
+   * Signs a document, scoped to the tenant.
+   */
+  signDocument(
+    tenantId: string,
+    documentId: string,
+    userId: string,
+    ipAddress: string
+  ): Document {
+    const doc = this.documents.get(documentId);
+    if (!doc || doc.tenantId !== tenantId) throw new Error('Document not found');
+
+    if (doc.status !== 'pending_signature') {
+      throw new Error('Document is not pending signature');
+    }
+
+    if (doc.signatures.some(s => s.userId === userId)) {
+      throw new Error('User has already signed this document');
+    }
+
+    const signature: Signature = {
+      userId,
+      timestamp: new Date(),
+      ipAddress,
+      hash: this.generateSignatureHash(doc.content, userId, ipAddress),
+    };
+
+    doc.signatures.push(signature);
+    doc.status = 'signed';
+
+    return doc;
+  }
+
+  private generateSignatureHash(content: string, userId: string, ipAddress: string): string {
+    return `hash_${userId}_${Date.now()}`;
+  }
+}

package/src/core/events/index.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { createEvent, WebWakaEventType, type DomainEvent } from './index';
+
+describe('CORE-14: Event Bus Primitives', () => {
+  // ─── createEvent ─────────────────────────────────────────────────────────
+
+  it('should create an event with correct structure', () => {
+    const payload = { userId: 'u_1', email: 'user@example.com' };
+    const event = createEvent(WebWakaEventType.AUTH_USER_LOGIN, 'tenant_alpha', payload);
+
+    expect(event.id).toBeDefined();
+    expect(typeof event.id).toBe('string');
+    expect(event.type).toBe(WebWakaEventType.AUTH_USER_LOGIN);
+    expect(event.tenantId).toBe('tenant_alpha');
+    expect(event.occurredAt).toBeInstanceOf(Date);
+    expect(event.payload).toEqual(payload);
+  });
+
+  it('should generate unique IDs for each createEvent call', () => {
+    const e1 = createEvent(WebWakaEventType.CHAT_MESSAGE_SENT, 'tenant_alpha', {});
+    const e2 = createEvent(WebWakaEventType.CHAT_MESSAGE_SENT, 'tenant_alpha', {});
+    expect(e1.id).not.toBe(e2.id);
+  });
+
+  it('should set occurredAt to the current time', () => {
+    const before = new Date();
+    const event = createEvent(WebWakaEventType.BOOKING_CONFIRMED, 'tenant_beta', {});
+    const after = new Date();
+
+    expect(event.occurredAt.getTime()).toBeGreaterThanOrEqual(before.getTime());
+    expect(event.occurredAt.getTime()).toBeLessThanOrEqual(after.getTime());
+  });
+
+  it('should accept an arbitrary typed payload', () => {
+    interface BookingPayload { bookingId: string; resourceId: string }
+    const payload: BookingPayload = { bookingId: 'bk_123', resourceId: 'res_42' };
+
+    const event: DomainEvent<BookingPayload> = createEvent(
+      WebWakaEventType.BOOKING_CONFIRMED,
+      'tenant_beta',
+      payload
+    );
+
+    expect(event.payload.bookingId).toBe('bk_123');
+    expect(event.payload.resourceId).toBe('res_42');
+  });
+
+  it('should carry the tenantId supplied to createEvent', () => {
+    const event = createEvent(WebWakaEventType.KYC_VERIFIED, 'tenant_gamma', { requestId: 'kyc_1' });
+    expect(event.tenantId).toBe('tenant_gamma');
+  });
+
+  // ─── WebWakaEventType enum value stability (regression guard) ─────────────
+
+  it('Auth event type values are stable strings', () => {
+    expect(WebWakaEventType.AUTH_USER_LOGIN).toBe('auth.user.login');
+    expect(WebWakaEventType.AUTH_USER_LOGOUT).toBe('auth.user.logout');
+    expect(WebWakaEventType.AUTH_TOKEN_REFRESHED).toBe('auth.token.refreshed');
+  });
+
+  it('KYC event type values are stable strings', () => {
+    expect(WebWakaEventType.KYC_SUBMITTED).toBe('kyc.submitted');
+    expect(WebWakaEventType.KYC_VERIFIED).toBe('kyc.verified');
+    expect(WebWakaEventType.KYC_REJECTED).toBe('kyc.rejected');
+  });
+
+  it('Booking event type values are stable strings', () => {
+    expect(WebWakaEventType.BOOKING_CONFIRMED).toBe('booking.confirmed');
+    expect(WebWakaEventType.BOOKING_CANCELLED).toBe('booking.cancelled');
+  });
+
+  it('Chat event type values are stable strings', () => {
+    expect(WebWakaEventType.CHAT_MESSAGE_SENT).toBe('chat.message.sent');
+    expect(WebWakaEventType.CHAT_CHANNEL_CREATED).toBe('chat.channel.created');
+  });
+
+  it('Document event type values are stable strings', () => {
+    expect(WebWakaEventType.DOCUMENT_CREATED).toBe('document.created');
+    expect(WebWakaEventType.DOCUMENT_SIGNED).toBe('document.signed');
+  });
+
+  it('Billing event type values are stable strings', () => {
+    expect(WebWakaEventType.BILLING_DEBIT_RECORDED).toBe('billing.debit.recorded');
+    expect(WebWakaEventType.BILLING_CREDIT_RECORDED).toBe('billing.credit.recorded');
+  });
+
+  it('Notification event type values are stable strings', () => {
+    expect(WebWakaEventType.NOTIFICATION_SENT).toBe('notification.sent');
+    expect(WebWakaEventType.NOTIFICATION_FAILED).toBe('notification.failed');
+  });
+});

package/src/core/events/index.ts

@@ -0,0 +1,91 @@
+/**
+ * CORE-14: Event Bus Primitives
+ * Blueprint Reference: Part 2 (Platform Architecture — "Event-Driven: NO direct inter-DB access")
+ *
+ * Canonical event contracts for the entire WebWaka OS v4 platform.
+ * Every domain emits typed DomainEvents; consumers subscribe by event type.
+ *
+ * This module defines shapes and constants only.
+ * Actual queue/bus wiring (Cloudflare Queues) is a separate concern.
+ */
+
+/**
+ * Well-known event type names for all WebWaka OS v4 domains.
+ *
+ * Consumers MUST use these constants — never raw string literals — so that
+ * renaming an event causes a compile-time error instead of a silent mismatch.
+ */
+export enum WebWakaEventType {
+  // ─── Auth ──────────────────────────────────────────────────────────────────
+  AUTH_USER_LOGIN = 'auth.user.login',
+  AUTH_USER_LOGOUT = 'auth.user.logout',
+  AUTH_TOKEN_REFRESHED = 'auth.token.refreshed',
+
+  // ─── KYC ───────────────────────────────────────────────────────────────────
+  KYC_SUBMITTED = 'kyc.submitted',
+  KYC_VERIFIED = 'kyc.verified',
+  KYC_REJECTED = 'kyc.rejected',
+
+  // ─── Booking ───────────────────────────────────────────────────────────────
+  BOOKING_CONFIRMED = 'booking.confirmed',
+  BOOKING_CANCELLED = 'booking.cancelled',
+
+  // ─── Chat ──────────────────────────────────────────────────────────────────
+  CHAT_MESSAGE_SENT = 'chat.message.sent',
+  CHAT_CHANNEL_CREATED = 'chat.channel.created',
+
+  // ─── Document ──────────────────────────────────────────────────────────────
+  DOCUMENT_CREATED = 'document.created',
+  DOCUMENT_SIGNED = 'document.signed',
+
+  // ─── Billing ───────────────────────────────────────────────────────────────
+  BILLING_DEBIT_RECORDED = 'billing.debit.recorded',
+  BILLING_CREDIT_RECORDED = 'billing.credit.recorded',
+
+  // ─── Notification ──────────────────────────────────────────────────────────
+  NOTIFICATION_SENT = 'notification.sent',
+  NOTIFICATION_FAILED = 'notification.failed',
+}
+
+/**
+ * Envelope wrapping every domain event published on the platform bus.
+ *
+ * `type` is constrained to `WebWakaEventType` — arbitrary strings are rejected
+ * at compile time, preventing undeclared event names from entering the bus.
+ *
+ * @template T  The event-specific payload type.
+ */
+export interface DomainEvent<T = unknown> {
+  /** Unique event identifier (UUID v4). */
+  id: string;
+  /** Canonical event type — must be a WebWakaEventType constant. */
+  type: WebWakaEventType;
+  /** The tenant that owns this event. */
+  tenantId: string;
+  /** Wall-clock time the event was created. */
+  occurredAt: Date;
+  /** Domain-specific payload. */
+  payload: T;
+}
+
+/**
+ * Factory that creates a well-formed DomainEvent with a generated id and
+ * current timestamp.
+ *
+ * @param type      A WebWakaEventType constant.
+ * @param tenantId  Tenant that owns the event.
+ * @param payload   Domain-specific payload.
+ */
+export function createEvent<T>(
+  type: WebWakaEventType,
+  tenantId: string,
+  payload: T
+): DomainEvent<T> {
+  return {
+    id: crypto.randomUUID(),
+    type,
+    tenantId,
+    occurredAt: new Date(),
+    payload,
+  };
+}

package/src/core/geolocation/index.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { GeolocationEngine } from './index';
+
+describe('CORE-9: Geolocation & Mapping Engine', () => {
+  let geoEngine: GeolocationEngine;
+
+  beforeEach(() => {
+    geoEngine = new GeolocationEngine('osm');
+  });
+
+  it('should calculate distance and ETA between two points', async () => {
+    const origin = { lat: 6.5244, lng: 3.3792 }; // Lagos
+    const destination = { lat: 9.0579, lng: 7.4951 }; // Abuja
+
+    const route = await geoEngine.calculateRoute(origin, destination);
+
+    expect(route.distanceMeters).toBeGreaterThan(500000);
+    expect(route.distanceMeters).toBeLessThan(600000);
+    expect(route.durationSeconds).toBeGreaterThan(0);
+    expect(route.polyline).toBeDefined();
+  });
+
+  it('should correctly identify if a point is within a geofence', () => {
+    const center = { lat: 6.5244, lng: 3.3792 }; // Lagos
+    const pointInside = { lat: 6.5300, lng: 3.3800 };
+    const pointOutside = { lat: 9.0579, lng: 7.4951 }; // Abuja
+
+    expect(geoEngine.isWithinGeofence(pointInside, center, 5000)).toBe(true);
+    expect(geoEngine.isWithinGeofence(pointOutside, center, 5000)).toBe(false);
+  });
+
+  it('should default to OSM provider when none is specified', async () => {
+    const defaultEngine = new GeolocationEngine();
+    const origin = { lat: 6.5244, lng: 3.3792 };
+    const destination = { lat: 6.6018, lng: 3.3515 }; // Victoria Island
+    const route = await defaultEngine.calculateRoute(origin, destination);
+    expect(route.distanceMeters).toBeGreaterThan(0);
+  });
+
+  it('should support google and mapbox providers', async () => {
+    for (const provider of ['google', 'mapbox'] as const) {
+      const engine = new GeolocationEngine(provider);
+      const route = await engine.calculateRoute(
+        { lat: 6.5244, lng: 3.3792 },
+        { lat: 6.4550, lng: 3.3841 }
+      );
+      expect(route.distanceMeters).toBeGreaterThan(0);
+      expect(route.durationSeconds).toBeGreaterThan(0);
+    }
+  });
+
+  it('should return zero distance for identical coordinates', async () => {
+    const point = { lat: 6.5244, lng: 3.3792 };
+    const route = await geoEngine.calculateRoute(point, point);
+    expect(route.distanceMeters).toBe(0);
+  });
+
+  it('should return true when point is exactly at center of geofence', () => {
+    const center = { lat: 6.5244, lng: 3.3792 };
+    expect(geoEngine.isWithinGeofence(center, center, 1)).toBe(true);
+  });
+
+  it('should compute duration based on distance', async () => {
+    const origin = { lat: 6.5244, lng: 3.3792 };
+    const destination = { lat: 9.0579, lng: 7.4951 };
+    const route = await geoEngine.calculateRoute(origin, destination);
+    // At ~8.33 m/s, 536km should take well over 10000 seconds
+    expect(route.durationSeconds).toBeGreaterThan(10000);
+  });
+});

package/src/core/geolocation/index.ts

@@ -0,0 +1,69 @@
+/**
+ * CORE-9: Geolocation & Mapping Engine
+ * Blueprint Reference: Part 10.3 (Transport), Part 10.4 (Logistics)
+ * 
+ * Vendor-neutral abstraction layer for maps, routing, and geocoding.
+ */
+
+export interface Coordinates {
+  lat: number;
+  lng: number;
+}
+
+export interface Route {
+  distanceMeters: number;
+  durationSeconds: number;
+  polyline: string;
+}
+
+export class GeolocationEngine {
+  private provider: 'google' | 'mapbox' | 'osm';
+
+  constructor(provider: 'google' | 'mapbox' | 'osm' = 'osm') {
+    this.provider = provider;
+  }
+
+  /**
+   * Calculates the distance and ETA between two points.
+   */
+  async calculateRoute(origin: Coordinates, destination: Coordinates): Promise<Route> {
+    // In a real implementation, this would call the respective provider's API
+    // For now, we return a mock calculation based on straight-line distance
+    
+    const distance = this.calculateStraightLineDistance(origin, destination);
+    // Assume average speed of 30 km/h (8.33 m/s) in city traffic
+    const duration = Math.floor(distance / 8.33);
+
+    return {
+      distanceMeters: Math.floor(distance),
+      durationSeconds: duration,
+      polyline: 'mock_polyline_data'
+    };
+  }
+
+  /**
+   * Checks if a coordinate is within a specific geofence (radius in meters).
+   */
+  isWithinGeofence(point: Coordinates, center: Coordinates, radiusMeters: number): boolean {
+    const distance = this.calculateStraightLineDistance(point, center);
+    return distance <= radiusMeters;
+  }
+
+  /**
+   * Haversine formula to calculate distance between two coordinates in meters.
+   */
+  private calculateStraightLineDistance(coord1: Coordinates, coord2: Coordinates): number {
+    const R = 6371e3; // Earth's radius in meters
+    const φ1 = coord1.lat * Math.PI / 180;
+    const φ2 = coord2.lat * Math.PI / 180;
+    const Δφ = (coord2.lat - coord1.lat) * Math.PI / 180;
+    const Δλ = (coord2.lng - coord1.lng) * Math.PI / 180;
+
+    const a = Math.sin(Δφ / 2) * Math.sin(Δφ / 2) +
+              Math.cos(φ1) * Math.cos(φ2) *
+              Math.sin(Δλ / 2) * Math.sin(Δλ / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+
+    return R * c;
+  }
+}