@latlng/sdk 0.1.0

package/dist/ws/socket.d.ts

@@ -0,0 +1,66 @@
+import { LatLngSubscription } from "./subscriptions.js";
+/**
+ * Configuration for establishing a WebSocket session.
+ */
+export interface LatLngWebSocketConfig {
+    /** Full WebSocket endpoint URL, for example `ws://127.0.0.1:7421/ws`. */
+    url: string;
+    /** Optional bearer token or JWT sent through the initial `auth` command. */
+    token?: string;
+    /** Custom WebSocket constructor/factory for tests or non-browser runtimes. */
+    webSocketFactory?: (url: string) => WebSocket;
+}
+/**
+ * WebSocket client for `latlng` channel subscriptions.
+ */
+export declare class LatLngWebSocketClient {
+    private readonly socket;
+    private readonly token?;
+    private readonly pending;
+    private activeSubscription?;
+    private constructor();
+    /**
+     * Opens a WebSocket connection and optionally authenticates it with the provided token.
+     *
+     * @param config WebSocket connection configuration.
+     * @returns Connected WebSocket client.
+     */
+    static connect(config: LatLngWebSocketConfig): Promise<LatLngWebSocketClient>;
+    /**
+     * Sends a protocol-level ping command over the active WebSocket connection.
+     *
+     * @returns Raw ping acknowledgement payload.
+     */
+    ping(): Promise<unknown>;
+    /**
+     * Subscribes to one or more explicit channel names.
+     *
+     * The returned subscription represents the active stream for this socket.
+     *
+     * @param channels Channel names to subscribe to.
+     * @returns Active subscription stream.
+     */
+    subscribe(channels: string[]): Promise<LatLngSubscription>;
+    /**
+     * Subscribes to one or more channel patterns.
+     *
+     * The returned subscription represents the active stream for this socket.
+     *
+     * @param patterns Channel patterns to subscribe to.
+     * @returns Active subscription stream.
+     */
+    psubscribe(patterns: string[]): Promise<LatLngSubscription>;
+    /**
+     * Requests a graceful server-side close and then closes the underlying socket.
+     */
+    quit(): Promise<void>;
+    /**
+     * Closes the underlying WebSocket immediately.
+     */
+    close(): void;
+    private replaceSubscription;
+    private command;
+    private handleMessage;
+    private tryParseEvent;
+}
+//# sourceMappingURL=socket.d.ts.map

package/dist/ws/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/ws/socket.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;CAC/C;AAOD;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,kBAAkB,CAAC,CAAqB;IAEhD,OAAO;IAoBP;;;;;OAKG;WACiB,OAAO,CACzB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAgCjC;;;;OAIG;IACU,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC;;;;;;;OAOG;IACU,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAWvE;;;;;;;OAOG;IACU,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAWxE;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAUlC;;OAEG;IACI,KAAK,IAAI,IAAI;IAIpB,OAAO,CAAC,mBAAmB;YASb,OAAO;IAWrB,OAAO,CAAC,aAAa;IAwBrB,OAAO,CAAC,aAAa;CAOtB"}

package/dist/ws/subscriptions.d.ts

@@ -0,0 +1,46 @@
+import type { GeofenceEvent } from "../types/events.js";
+/**
+ * Event stream wrapper returned by WebSocket subscription commands.
+ *
+ * It supports callback-style listeners and async iteration.
+ */
+export declare class LatLngSubscription implements AsyncIterable<GeofenceEvent> {
+    private readonly events;
+    private readonly eventHandlers;
+    private readonly closeHandlers;
+    private readonly errorHandlers;
+    private readonly closeFn;
+    private closed;
+    /**
+     * Creates a subscription wrapper around the underlying socket close callback.
+     *
+     * @param closeFn Callback used to close the underlying socket transport.
+     */
+    constructor(closeFn: () => void);
+    /**
+     * Registers an event listener.
+     *
+     * Returns an unsubscribe function that removes the handler again.
+     *
+     * @param type Event type to subscribe to.
+     * @param handler Event handler callback.
+     * @returns Function that removes the registered handler.
+     */
+    on(type: "event", handler: (event: GeofenceEvent) => void): () => void;
+    on(type: "close", handler: () => void): () => void;
+    on(type: "error", handler: (error: unknown) => void): () => void;
+    push(event: GeofenceEvent): void;
+    fail(error: unknown): void;
+    /**
+     * Closes the subscription and its underlying socket.
+     */
+    close(): void;
+    finish(): void;
+    /**
+     * Returns an async iterator that yields geofence events until the subscription closes.
+     *
+     * @returns Async iterator over geofence events.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<GeofenceEvent>;
+}
+//# sourceMappingURL=subscriptions.d.ts.map

package/dist/ws/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/ws/subscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAyCxD;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,aAAa,CAAC,aAAa,CAAC;IACrE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6C;IAC3E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyB;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuC;IACrE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACgB,OAAO,EAAE,MAAM,IAAI;IAItC;;;;;;;;OAQG;IACI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IACtE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAClD,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI;IA0BhE,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAOhC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAMjC;;OAEG;IACI,KAAK,IAAI,IAAI;IASb,MAAM,IAAI,IAAI;IAUrB;;;;OAIG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,aAAa,CAAC;CAK9D"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@latlng/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the latlng geospatial object engine",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/tobilg/latlng",
+  "bugs": {
+    "url": "https://github.com/tobilg/latlng/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tobilg/latlng"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.json --emitDeclarationOnly",
+    "docs:api": "typedoc --options typedoc.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test": "npm run build && npm run test:unit && npm run test:integration"
+  },
+  "devDependencies": {
+    "@emnapi/core": "^1.10.0",
+    "@emnapi/runtime": "^1.10.0",
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.11",
+    "vitest": "^4.1.5"
+  }
+}