@openmdm/plugin-geofence 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present OpenMDM Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+import { Device, DeviceLocation, MDMPlugin } from '@openmdm/core';
+export { MDMPlugin } from '@openmdm/core';
+
+/**
+ * OpenMDM Geofencing Plugin
+ *
+ * Provides location-based policy enforcement and monitoring.
+ * Supports circular and polygon geofence zones with enter/exit actions.
+ *
+ * @example
+ * ```typescript
+ * import { createMDM } from '@openmdm/core';
+ * import { geofencePlugin } from '@openmdm/plugin-geofence';
+ *
+ * const mdm = createMDM({
+ *   database: drizzleAdapter(db),
+ *   plugins: [
+ *     geofencePlugin({
+ *       onEnter: async (device, zone) => {
+ *         console.log(`Device ${device.id} entered ${zone.name}`);
+ *       },
+ *       onExit: async (device, zone) => {
+ *         console.log(`Device ${device.id} left ${zone.name}`);
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+interface GeofencePluginOptions {
+    /**
+     * Callback when device enters a geofence zone
+     */
+    onEnter?: (device: Device, zone: GeofenceZone) => Promise<void>;
+    /**
+     * Callback when device exits a geofence zone
+     */
+    onExit?: (device: Device, zone: GeofenceZone) => Promise<void>;
+    /**
+     * Callback when device is inside a zone during heartbeat
+     */
+    onInside?: (device: Device, zone: GeofenceZone) => Promise<void>;
+    /**
+     * Default dwell time (ms) before triggering enter event (default: 0)
+     */
+    defaultDwellTime?: number;
+    /**
+     * Enable location history tracking (default: false)
+     */
+    trackHistory?: boolean;
+    /**
+     * Maximum history entries per device (default: 1000)
+     */
+    maxHistoryEntries?: number;
+}
+interface GeofenceZone {
+    id: string;
+    name: string;
+    description?: string;
+    type: 'circle' | 'polygon';
+    enabled: boolean;
+    center?: {
+        latitude: number;
+        longitude: number;
+    };
+    radius?: number;
+    vertices?: Array<{
+        latitude: number;
+        longitude: number;
+    }>;
+    onEnter?: GeofenceAction;
+    onExit?: GeofenceAction;
+    policyOverride?: string;
+    schedule?: GeofenceSchedule;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface GeofenceAction {
+    /** Action type */
+    type: 'notify' | 'command' | 'policy' | 'webhook' | 'none';
+    /** Notification message */
+    notification?: {
+        title: string;
+        body: string;
+    };
+    /** Command to execute */
+    command?: {
+        type: string;
+        payload?: Record<string, unknown>;
+    };
+    /** Policy to apply */
+    policyId?: string;
+    /** Webhook to call */
+    webhook?: {
+        url: string;
+        method?: 'GET' | 'POST';
+        headers?: Record<string, string>;
+        body?: Record<string, unknown>;
+    };
+}
+interface GeofenceSchedule {
+    /** Days of week (0=Sunday, 6=Saturday) */
+    daysOfWeek?: number[];
+    /** Start time (HH:mm) */
+    startTime?: string;
+    /** End time (HH:mm) */
+    endTime?: string;
+    /** Timezone (default: UTC) */
+    timezone?: string;
+}
+interface DeviceZoneState {
+    deviceId: string;
+    zoneId: string;
+    inside: boolean;
+    enteredAt?: Date;
+    exitedAt?: Date;
+    dwellTime?: number;
+}
+interface LocationHistoryEntry {
+    deviceId: string;
+    location: DeviceLocation;
+    zones: string[];
+    timestamp: Date;
+}
+interface CreateGeofenceZoneInput {
+    name: string;
+    description?: string;
+    type: 'circle' | 'polygon';
+    enabled?: boolean;
+    center?: {
+        latitude: number;
+        longitude: number;
+    };
+    radius?: number;
+    vertices?: Array<{
+        latitude: number;
+        longitude: number;
+    }>;
+    onEnter?: GeofenceAction;
+    onExit?: GeofenceAction;
+    policyOverride?: string;
+    schedule?: GeofenceSchedule;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateGeofenceZoneInput {
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+    center?: {
+        latitude: number;
+        longitude: number;
+    };
+    radius?: number;
+    vertices?: Array<{
+        latitude: number;
+        longitude: number;
+    }>;
+    onEnter?: GeofenceAction;
+    onExit?: GeofenceAction;
+    policyOverride?: string;
+    schedule?: GeofenceSchedule;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Calculate distance between two points using Haversine formula
+ */
+declare function haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Check if point is inside circular zone
+ */
+declare function isInsideCircle(point: {
+    latitude: number;
+    longitude: number;
+}, center: {
+    latitude: number;
+    longitude: number;
+}, radiusMeters: number): boolean;
+/**
+ * Check if point is inside polygon using ray casting algorithm
+ */
+declare function isInsidePolygon(point: {
+    latitude: number;
+    longitude: number;
+}, vertices: Array<{
+    latitude: number;
+    longitude: number;
+}>): boolean;
+/**
+ * Check if zone is active according to schedule
+ */
+declare function isZoneScheduleActive(schedule: GeofenceSchedule | undefined): boolean;
+/**
+ * Create geofencing plugin
+ */
+declare function geofencePlugin(options?: GeofencePluginOptions): MDMPlugin;
+
+export { type CreateGeofenceZoneInput, type DeviceZoneState, type GeofenceAction, type GeofencePluginOptions, type GeofenceSchedule, type GeofenceZone, type LocationHistoryEntry, type UpdateGeofenceZoneInput, geofencePlugin, haversineDistance, isInsideCircle, isInsidePolygon, isZoneScheduleActive };