@gofindme/client 0.1.0

package/README.md

@@ -0,0 +1,175 @@
+# @gofindme/client
+
+Official GoFindMe Location Tracking Client SDK for JavaScript and TypeScript.
+
+## Installation
+
+```bash
+npm install @gofindme/client
+```
+
+## Quick Start
+
+```typescript
+import { GoFindMeClient } from '@gofindme/client';
+
+const client = new GoFindMeClient({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.gofindme.com' // optional, defaults to https://api.gofindme.com
+});
+
+// Submit a location update
+await client.submitLocation({
+  deviceId: 'device-123',
+  latitude: 37.7749,
+  longitude: -122.4194,
+  recordedAt: new Date()
+});
+
+// Stream real-time location updates
+const stream = client.streamLocations();
+stream.addEventListener('location', (event) => {
+  const location = JSON.parse(event.data);
+  console.log('Location update:', location);
+});
+```
+
+## API Reference
+
+### `GoFindMeClient`
+
+Main client class for interacting with the GoFindMe API.
+
+#### Constructor
+
+```typescript
+new GoFindMeClient(config: GoFindMeClientConfig)
+```
+
+**Parameters:**
+- `config.apiKey` (string, required): Your GoFindMe API key
+- `config.baseUrl` (string, optional): Base URL of the GoFindMe API (defaults to `https://api.gofindme.com`)
+
+#### Methods
+
+##### `submitLocation(data: LocationUpdatePayload): Promise<LocationResponse>`
+
+Submit a location update to the API.
+
+**Parameters:**
+- `data.deviceId` (string): Unique identifier for the device
+- `data.latitude` (number): Latitude in decimal degrees (-90 to 90)
+- `data.longitude` (number): Longitude in decimal degrees (-180 to 180)
+- `data.recordedAt` (Date | string): When the location was recorded
+- `data.accuracy` (number, optional): Location accuracy in meters
+- `data.heading` (number, optional): Direction of travel in degrees (0-360)
+- `data.speed` (number, optional): Speed in meters per second
+- `data.metadata` (object, optional): Additional metadata as key-value pairs
+- `data.groupIds` (string[], optional): Array of group IDs to target
+
+**Returns:** Promise resolving to `LocationResponse` with `id` and `receivedAt` fields.
+
+**Throws:** `GoFindMeError` if the request fails.
+
+##### `streamLocations(): EventSource`
+
+Stream location events using Server-Sent Events (SSE).
+
+**Returns:** `EventSource` instance that emits the following events:
+- `location`: Emitted when a new location update is received
+- `ready`: Emitted when the stream is ready
+- `heartbeat`: Emitted periodically to keep the connection alive
+- `error`: Emitted when an error occurs
+
+**Example:**
+```typescript
+const stream = client.streamLocations();
+
+stream.addEventListener('location', (event) => {
+  const location: LocationEvent = JSON.parse(event.data);
+  // Handle location update
+});
+
+stream.addEventListener('error', (error) => {
+  // Handle error
+});
+
+// Close the stream when done
+stream.close();
+```
+
+##### `health(): Promise<HealthResponse>`
+
+Check the health status of the GoFindMe API.
+
+**Returns:** Promise resolving to `HealthResponse` with `status`, `timestamp`, and `uptime` fields.
+
+**Throws:** `GoFindMeError` if the request fails.
+
+## Types
+
+### `LocationUpdatePayload`
+
+```typescript
+interface LocationUpdatePayload {
+  deviceId: string;
+  latitude: number;
+  longitude: number;
+  accuracy?: number;
+  heading?: number;
+  speed?: number;
+  recordedAt: Date | string;
+  metadata?: Record<string, unknown>;
+  payloadVersion?: string;
+  groupIds?: string[];
+}
+```
+
+### `LocationEvent`
+
+```typescript
+interface LocationEvent {
+  id: string;
+  groupId: string;
+  deviceId: string;
+  latitude: number;
+  longitude: number;
+  accuracy?: number | null;
+  heading?: number | null;
+  speed?: number | null;
+  recordedAt: string;
+  receivedAt: string;
+  metadata?: Record<string, unknown> | null;
+}
+```
+
+### `LocationResponse`
+
+```typescript
+interface LocationResponse {
+  id: string;
+  receivedAt: string;
+}
+```
+
+## Error Handling
+
+The client throws `GoFindMeError` instances when API requests fail:
+
+```typescript
+import { GoFindMeClient, GoFindMeError } from '@gofindme/client';
+
+try {
+  await client.submitLocation({ /* ... */ });
+} catch (error) {
+  if (error instanceof GoFindMeError) {
+    console.error('API Error:', error.message);
+    console.error('Status Code:', error.statusCode);
+    console.error('Response:', error.response);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,118 @@
+import type { GoFindMeClientConfig, HealthResponse, LocationResponse, LocationUpdatePayload } from './types.js';
+/**
+ * GoFindMe Client SDK
+ *
+ * This client provides methods to interact with the GoFindMe Location Tracking API.
+ * It uses API key authentication and supports both submitting locations and
+ * streaming real-time location updates.
+ *
+ * @example
+ * ```typescript
+ * import { GoFindMeClient } from '@gofindme/client';
+ *
+ * const client = new GoFindMeClient({
+ *   apiKey: 'your-api-key',
+ *   baseUrl: 'https://api.gofindme.com'
+ * });
+ *
+ * // Submit a location
+ * const response = await client.submitLocation({
+ *   deviceId: 'device-123',
+ *   latitude: 37.7749,
+ *   longitude: -122.4194,
+ *   recordedAt: new Date()
+ * });
+ *
+ * // Stream locations
+ * const stream = client.streamLocations();
+ * stream.addEventListener('location', (event) => {
+ *   const location: LocationEvent = JSON.parse(event.data);
+ *   console.log('Location update:', location);
+ * });
+ * ```
+ */
+export declare class GoFindMeClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    /**
+     * Create a new GoFindMe client instance
+     *
+     * @param config - Client configuration
+     * @param config.apiKey - Your GoFindMe API key
+     * @param config.baseUrl - Base URL of the GoFindMe API (defaults to https://api.gofindme.com)
+     */
+    constructor(config: GoFindMeClientConfig);
+    /**
+     * Submit a location update to the GoFindMe API
+     *
+     * @param data - Location data to submit
+     * @returns Promise resolving to the location response
+     * @throws {GoFindMeError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const response = await client.submitLocation({
+     *   deviceId: 'my-device-123',
+     *   latitude: 37.7749,
+     *   longitude: -122.4194,
+     *   accuracy: 10,
+     *   speed: 5.2,
+     *   heading: 45,
+     *   recordedAt: new Date(),
+     *   metadata: { battery: 85, signal: 'strong' }
+     * });
+     * ```
+     */
+    submitLocation(data: LocationUpdatePayload): Promise<LocationResponse>;
+    /**
+     * Stream location events using Server-Sent Events (SSE)
+     *
+     * This method creates a stream that emits location updates in real-time.
+     * Since EventSource doesn't support custom headers, this uses fetch() with
+     * manual SSE parsing to properly authenticate with the API key.
+     *
+     * @returns An object with methods to control the stream
+     *
+     * @example
+     * ```typescript
+     * const stream = client.streamLocations();
+     *
+     * stream.addEventListener('location', (event) => {
+     *   const location: LocationEvent = event.data;
+     *   console.log('New location:', location);
+     * });
+     *
+     * stream.addEventListener('error', (error) => {
+     *   console.error('Stream error:', error);
+     * });
+     *
+     * // Close the stream when done
+     * stream.close();
+     * ```
+     */
+    streamLocations(): {
+        addEventListener: (event: 'location' | 'ready' | 'heartbeat' | 'error', handler: (event: {
+            type: string;
+            data: unknown;
+        }) => void) => void;
+        removeEventListener: (event: 'location' | 'ready' | 'heartbeat' | 'error', handler: (event: {
+            type: string;
+            data: unknown;
+        }) => void) => void;
+        close: () => void;
+    };
+    /**
+     * Check the health status of the GoFindMe API
+     *
+     * @returns Promise resolving to health status
+     * @throws {GoFindMeError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const health = await client.health();
+     * console.log('API Status:', health.status);
+     * ```
+     */
+    health(): Promise<HealthResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;;;OAMG;gBACS,MAAM,EAAE,oBAAoB;IASxC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,cAAc,CAClB,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,gBAAgB,CAAC;IAuB5B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,eAAe,IAAI;QACjB,gBAAgB,EAAE,CAChB,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,EACnD,OAAO,EAAE,CAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,OAAO,CAAA;SAAE,KAAK,IAAI,KACtD,IAAI,CAAC;QACV,mBAAmB,EAAE,CACnB,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,EACnD,OAAO,EAAE,CAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,OAAO,CAAA;SAAE,KAAK,IAAI,KACtD,IAAI,CAAC;QACV,KAAK,EAAE,MAAM,IAAI,CAAC;KACnB;IAsJD;;;;;;;;;;;OAWG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;CASxC"}

package/dist/client.js

@@ -0,0 +1,264 @@
+import { GoFindMeError } from './errors.js';
+/**
+ * GoFindMe Client SDK
+ *
+ * This client provides methods to interact with the GoFindMe Location Tracking API.
+ * It uses API key authentication and supports both submitting locations and
+ * streaming real-time location updates.
+ *
+ * @example
+ * ```typescript
+ * import { GoFindMeClient } from '@gofindme/client';
+ *
+ * const client = new GoFindMeClient({
+ *   apiKey: 'your-api-key',
+ *   baseUrl: 'https://api.gofindme.com'
+ * });
+ *
+ * // Submit a location
+ * const response = await client.submitLocation({
+ *   deviceId: 'device-123',
+ *   latitude: 37.7749,
+ *   longitude: -122.4194,
+ *   recordedAt: new Date()
+ * });
+ *
+ * // Stream locations
+ * const stream = client.streamLocations();
+ * stream.addEventListener('location', (event) => {
+ *   const location: LocationEvent = JSON.parse(event.data);
+ *   console.log('Location update:', location);
+ * });
+ * ```
+ */
+export class GoFindMeClient {
+    apiKey;
+    baseUrl;
+    /**
+     * Create a new GoFindMe client instance
+     *
+     * @param config - Client configuration
+     * @param config.apiKey - Your GoFindMe API key
+     * @param config.baseUrl - Base URL of the GoFindMe API (defaults to https://api.gofindme.com)
+     */
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('API key is required');
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl || 'https://api.gofindme.com';
+    }
+    /**
+     * Submit a location update to the GoFindMe API
+     *
+     * @param data - Location data to submit
+     * @returns Promise resolving to the location response
+     * @throws {GoFindMeError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const response = await client.submitLocation({
+     *   deviceId: 'my-device-123',
+     *   latitude: 37.7749,
+     *   longitude: -122.4194,
+     *   accuracy: 10,
+     *   speed: 5.2,
+     *   heading: 45,
+     *   recordedAt: new Date(),
+     *   metadata: { battery: 85, signal: 'strong' }
+     * });
+     * ```
+     */
+    async submitLocation(data) {
+        const response = await fetch(`${this.baseUrl}/api/v1/locations`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': this.apiKey,
+            },
+            body: JSON.stringify({
+                ...data,
+                recordedAt: data.recordedAt instanceof Date
+                    ? data.recordedAt.toISOString()
+                    : data.recordedAt,
+            }),
+        });
+        if (!response.ok) {
+            throw await GoFindMeError.fromResponse(response);
+        }
+        return response.json();
+    }
+    /**
+     * Stream location events using Server-Sent Events (SSE)
+     *
+     * This method creates a stream that emits location updates in real-time.
+     * Since EventSource doesn't support custom headers, this uses fetch() with
+     * manual SSE parsing to properly authenticate with the API key.
+     *
+     * @returns An object with methods to control the stream
+     *
+     * @example
+     * ```typescript
+     * const stream = client.streamLocations();
+     *
+     * stream.addEventListener('location', (event) => {
+     *   const location: LocationEvent = event.data;
+     *   console.log('New location:', location);
+     * });
+     *
+     * stream.addEventListener('error', (error) => {
+     *   console.error('Stream error:', error);
+     * });
+     *
+     * // Close the stream when done
+     * stream.close();
+     * ```
+     */
+    streamLocations() {
+        const url = `${this.baseUrl}/api/v1/stream`;
+        const eventHandlers = new Map();
+        let abortController = null;
+        let reader = null;
+        let isClosed = false;
+        const addEventListener = (event, handler) => {
+            if (!eventHandlers.has(event)) {
+                eventHandlers.set(event, new Set());
+            }
+            eventHandlers.get(event).add(handler);
+        };
+        const removeEventListener = (event, handler) => {
+            eventHandlers.get(event)?.delete(handler);
+        };
+        const emit = (type, data) => {
+            const handlers = eventHandlers.get(type);
+            if (handlers) {
+                handlers.forEach((handler) => handler({ type, data }));
+            }
+        };
+        const close = () => {
+            if (isClosed)
+                return;
+            isClosed = true;
+            abortController?.abort();
+            reader?.cancel().catch(() => {
+                // Ignore cancel errors
+            });
+            eventHandlers.clear();
+        };
+        // Start the stream
+        abortController = new AbortController();
+        fetch(url, {
+            method: 'GET',
+            headers: {
+                'X-API-Key': this.apiKey,
+                Accept: 'text/event-stream',
+            },
+            signal: abortController.signal,
+        })
+            .then(async (response) => {
+            if (!response.ok) {
+                emit('error', {
+                    status: response.status,
+                    statusText: response.statusText,
+                    message: `HTTP ${response.status}: ${response.statusText}`,
+                });
+                close();
+                return;
+            }
+            if (!response.body) {
+                emit('error', { message: 'Response body is null' });
+                close();
+                return;
+            }
+            reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            try {
+                while (true) {
+                    const { value, done } = await reader.read();
+                    if (done) {
+                        close();
+                        break;
+                    }
+                    buffer += decoder.decode(value, { stream: true });
+                    // Process complete SSE messages (separated by double newline)
+                    let boundary = buffer.indexOf('\n\n');
+                    while (boundary !== -1) {
+                        const eventString = buffer.slice(0, boundary).trim();
+                        buffer = buffer.slice(boundary + 2);
+                        boundary = buffer.indexOf('\n\n');
+                        if (eventString) {
+                            let eventType = 'message';
+                            let eventData = '';
+                            // Parse SSE format: "event: <type>\ndata: <data>"
+                            for (const line of eventString.split('\n')) {
+                                const colonIndex = line.indexOf(':');
+                                if (colonIndex === -1)
+                                    continue;
+                                const field = line.slice(0, colonIndex).trim();
+                                const value = line.slice(colonIndex + 1).trim();
+                                if (field === 'event') {
+                                    eventType = value;
+                                }
+                                else if (field === 'data') {
+                                    eventData = value;
+                                }
+                            }
+                            try {
+                                const parsedData = JSON.parse(eventData);
+                                emit(eventType, parsedData);
+                            }
+                            catch {
+                                // If parsing fails, emit raw data
+                                emit(eventType, eventData);
+                            }
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                if (!isClosed) {
+                    emit('error', {
+                        message: error instanceof Error ? error.message : 'Unknown stream error',
+                        error,
+                    });
+                    close();
+                }
+            }
+        })
+            .catch((error) => {
+            if (!isClosed && error.name !== 'AbortError') {
+                emit('error', {
+                    message: error instanceof Error ? error.message : 'Connection failed',
+                    error,
+                });
+                close();
+            }
+        });
+        return {
+            addEventListener,
+            removeEventListener,
+            close,
+        };
+    }
+    /**
+     * Check the health status of the GoFindMe API
+     *
+     * @returns Promise resolving to health status
+     * @throws {GoFindMeError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const health = await client.health();
+     * console.log('API Status:', health.status);
+     * ```
+     */
+    async health() {
+        const response = await fetch(`${this.baseUrl}/api/v1/health`);
+        if (!response.ok) {
+            throw await GoFindMeError.fromResponse(response);
+        }
+        return response.json();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Custom error class for GoFindMe API errors
+ */
+export declare class GoFindMeError extends Error {
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+    static fromResponse(response: Response): Promise<GoFindMeError>;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAG7B,UAAU,CAAC,EAAE,MAAM;IACnB,QAAQ,CAAC,EAAE,OAAO;gBAFzB,OAAO,EAAE,MAAM,EACR,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,QAAQ,CAAC,EAAE,OAAO,YAAA;WAOd,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;CAsBtE"}

package/dist/errors.js

@@ -0,0 +1,37 @@
+/**
+ * Custom error class for GoFindMe API errors
+ */
+export class GoFindMeError extends Error {
+    statusCode;
+    response;
+    constructor(message, statusCode, response) {
+        super(message);
+        this.statusCode = statusCode;
+        this.response = response;
+        this.name = 'GoFindMeError';
+        Object.setPrototypeOf(this, GoFindMeError.prototype);
+    }
+    static async fromResponse(response) {
+        let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+        let errorData = null;
+        try {
+            const contentType = response.headers.get('content-type');
+            if (contentType?.includes('application/json')) {
+                errorData = await response.json();
+                errorMessage = errorData?.message || errorMessage;
+            }
+            else {
+                const text = await response.text();
+                if (text) {
+                    errorMessage = text;
+                    errorData = text;
+                }
+            }
+        }
+        catch {
+            // Ignore parsing errors, use default message
+        }
+        return new GoFindMeError(errorMessage, response.status, errorData);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAG7B;IACA;IAHT,YACE,OAAe,EACR,UAAmB,EACnB,QAAkB;QAEzB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,eAAU,GAAV,UAAU,CAAS;QACnB,aAAQ,GAAR,QAAQ,CAAU;QAGzB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,QAAkB;QAC1C,IAAI,YAAY,GAAG,QAAQ,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;QACrE,IAAI,SAAS,GAAY,IAAI,CAAC;QAE9B,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YACzD,IAAI,WAAW,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;gBAC9C,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBAClC,YAAY,GAAI,SAAkC,EAAE,OAAO,IAAI,YAAY,CAAC;YAC9E,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACnC,IAAI,IAAI,EAAE,CAAC;oBACT,YAAY,GAAG,IAAI,CAAC;oBACpB,SAAS,GAAG,IAAI,CAAC;gBACnB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,6CAA6C;QAC/C,CAAC;QAED,OAAO,IAAI,aAAa,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACrE,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { GoFindMeClient } from './client.js';
+export type { LocationUpdatePayload, LocationResponse, LocationEvent, GoFindMeClientConfig, HealthResponse, } from './types.js';
+export { GoFindMeError } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { GoFindMeClient } from './client.js';
+export { GoFindMeError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ7C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Location update payload for submitting location data
+ */
+export interface LocationUpdatePayload {
+    /** Unique identifier for the device */
+    deviceId: string;
+    /** Latitude in decimal degrees (-90 to 90) */
+    latitude: number;
+    /** Longitude in decimal degrees (-180 to 180) */
+    longitude: number;
+    /** Location accuracy in meters (optional) */
+    accuracy?: number;
+    /** Direction of travel in degrees (0-360, optional) */
+    heading?: number;
+    /** Speed in meters per second (optional) */
+    speed?: number;
+    /** When the location was recorded (ISO 8601 string or Date) */
+    recordedAt: Date | string;
+    /** Additional metadata as key-value pairs (optional) */
+    metadata?: Record<string, unknown>;
+    /** Payload version (defaults to 'v1') */
+    payloadVersion?: string;
+    /** Optional array of group IDs to target (optional) */
+    groupIds?: string[];
+}
+/**
+ * Response from submitting a location update
+ */
+export interface LocationResponse {
+    /** Unique identifier for the location record */
+    id: string;
+    /** ISO 8601 timestamp when the location was received */
+    receivedAt: string;
+}
+/**
+ * Location event received from the stream
+ */
+export interface LocationEvent {
+    /** Unique identifier for the location record */
+    id: string;
+    /** Group ID this location belongs to */
+    groupId: string;
+    /** Device ID that reported this location */
+    deviceId: string;
+    /** Latitude in decimal degrees */
+    latitude: number;
+    /** Longitude in decimal degrees */
+    longitude: number;
+    /** Location accuracy in meters (may be null) */
+    accuracy?: number | null;
+    /** Direction of travel in degrees (may be null) */
+    heading?: number | null;
+    /** Speed in meters per second (may be null) */
+    speed?: number | null;
+    /** ISO 8601 timestamp when the location was recorded */
+    recordedAt: string;
+    /** ISO 8601 timestamp when the location was received by the server */
+    receivedAt: string;
+    /** Additional metadata (may be null) */
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * Configuration for the GoFindMe client
+ */
+export interface GoFindMeClientConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL of the GoFindMe API (defaults to https://api.gofindme.com) */
+    baseUrl?: string;
+}
+/**
+ * Health check response
+ */
+export interface HealthResponse {
+    /** Health status */
+    status: string;
+    /** ISO 8601 timestamp */
+    timestamp?: string;
+    /** Server uptime in seconds */
+    uptime?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,UAAU,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@gofindme/client",
+  "version": "0.1.0",
+  "description": "GoFindMe Location Tracking Client SDK",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "location",
+    "tracking",
+    "gps",
+    "geolocation",
+    "realtime"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/gofindme-server.git",
+    "directory": "packages/client"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  }
+}