@sierragridteam/sdk 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,99 @@
+import * as schemas from './generated/zod.gen.js';
+export class SierraApiError extends Error {
+    status;
+    codeName;
+    retryAfter;
+    body;
+    constructor(message, status, codeName, retryAfter, body) {
+        super(message);
+        this.status = status;
+        this.codeName = codeName;
+        this.retryAfter = retryAfter;
+        this.body = body;
+        this.name = 'SierraApiError';
+    }
+}
+/** Public read-only client. All returned JSON is validated against generated Zod schemas. */
+export function createSierraClient(config = {}) {
+    const base = (config.baseUrl ?? 'https://data.sierragridteam.org').replace(/\/$/, '');
+    const fetcher = config.fetch ?? globalThis.fetch;
+    async function request(path, schema, query = {}, options = {}) {
+        const url = new URL(base + path);
+        for (const [key, value] of Object.entries(query)) {
+            if (value === undefined || value === null)
+                continue;
+            for (const item of Array.isArray(value) ? value : [value])
+                url.searchParams.append(key, String(item));
+        }
+        const timeout = options.timeoutMs ?? config.timeoutMs ?? 20_000;
+        if (!Number.isFinite(timeout) || timeout <= 0)
+            throw new RangeError('timeoutMs must be positive');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new DOMException('Request deadline exceeded', 'TimeoutError')), timeout);
+        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+        try {
+            const response = await fetcher(url, { method: 'GET', signal, headers: options.etag ? { 'If-None-Match': options.etag } : {} });
+            const etag = response.headers.get('ETag');
+            if (response.status === 304)
+                return { data: undefined, status: 304, etag, notModified: true };
+            const text = await response.text();
+            let body;
+            try {
+                body = text ? JSON.parse(text) : null;
+            }
+            catch {
+                body = text;
+            }
+            if (!response.ok) {
+                const error = schemas.zRpcStatus.safeParse(body);
+                throw new SierraApiError(error.success ? (error.data.message ?? 'Grid error') : `Grid request failed (${response.status})`, response.status, error.success ? (error.data.codeName ?? 'UNKNOWN') : 'HTTP_ERROR', response.headers.get('Retry-After'), body);
+            }
+            return { data: schema.parse(body), status: response.status, etag, notModified: false };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    const geometry = (query = {}) => ({ geometryFormat: 'OBJECT', ...query });
+    const api = {
+        listEvents: (query = {}, options = {}) => request(`/api/v1/events`, schemas.zGridServiceListEventsResponse, geometry(query), options),
+        getEvent: (id, query = {}, options = {}) => request(`/api/v1/events/${encodeURIComponent(id)}`, schemas.zGridServiceGetEventResponse, geometry(query), options),
+        getEventHistory: (id, query = {}, options = {}) => request(`/api/v1/events/${encodeURIComponent(id)}/history`, schemas.zGridServiceGetEventHistoryResponse, geometry(query), options),
+        listPlaces: (query = {}, options = {}) => request(`/api/v1/places`, schemas.zGridServiceListPlacesResponse, geometry(query), options),
+        getPlace: (place, options = {}) => request(`/api/v1/places/${encodeURIComponent(place)}`, schemas.zGridServiceGetPlaceResponse, geometry(), options),
+        resolvePlace: (query, options = {}) => request(`/api/v1/places:resolve`, schemas.zGridServiceResolvePlaceResponse, geometry(query), options),
+        getPlaceSummary: (place, options = {}) => request(`/api/v1/places/${encodeURIComponent(place)}/summary`, schemas.zGridServiceGetPlaceSummaryResponse, {}, options),
+        getConditions: (query = {}, options = {}) => request(`/api/v1/conditions`, schemas.zGridServiceGetConditionsResponse, query, options),
+        listCameras: (query = {}, options = {}) => request(`/api/v1/cameras`, schemas.zGridServiceListCamerasResponse, query, options),
+        listScanners: (query = {}, options = {}) => request(`/api/v1/scanners`, schemas.zGridServiceListScannersResponse, query, options),
+        listSources: (options = {}) => request(`/api/v1/sources`, schemas.zGridServiceListSourcesResponse, {}, options),
+        getMapLayer: (place, layer, query = {}, options = {}) => request(`/api/v1/places/${encodeURIComponent(place)}/map/${layer}.geojson`, schemas.zGetMapLayerResponse, query, options),
+        listMeshLinks: (query = {}, options = {}) => request(`/api/v1/mesh/links`, schemas.zListMeshLinksResponse, query, options),
+        getMeshTelemetry: (query, options = {}) => request(`/api/v1/mesh/telemetry`, schemas.zGridServiceGetMeshTelemetryResponse, query, options),
+        listHistory: (query, options = {}) => {
+            if (!Number.isFinite(Date.parse(query.from)) || !Number.isFinite(Date.parse(query.to)) || Date.parse(query.from) >= Date.parse(query.to))
+                throw new RangeError('History requires a valid explicit from < to window');
+            return request('/api/v1/history', schemas.zGridServiceListHistoryResponse, geometry(query), options);
+        },
+    };
+    return api;
+}
+/** Yields pages, including continuation tokens. A caller stopping early owns that incompleteness. */
+export async function* paginate(load, maxPages = 100) {
+    if (!Number.isInteger(maxPages) || maxPages < 1)
+        throw new RangeError('maxPages must be a positive integer');
+    let token;
+    const seen = new Set();
+    for (let page = 0; page < maxPages; page++) {
+        const result = await load(token);
+        if (result.notModified)
+            throw new Error('Pagination cannot advance from a 304; do not pass an ETag');
+        yield result.data;
+        token = result.data.nextPageToken;
+        if (!token)
+            return;
+        if (seen.has(token))
+            throw new Error('API returned a repeated pagination token');
+        seen.add(token);
+    }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@sierragridteam/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Generated, runtime-validated public SIERRA Grid API client",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sierragridteam/sierra-sdk.git",
+    "directory": "packages/typescript"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./generated": {
+      "types": "./dist/generated/index.d.ts",
+      "import": "./dist/generated/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/generated/zod.gen.d.ts",
+      "import": "./dist/generated/zod.gen.js"
+    },
+    "./fixtures": {
+      "types": "./dist/fixtures.d.ts",
+      "import": "./dist/fixtures.js"
+    }
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsc",
+    "test": "pnpm build && node --experimental-strip-types --test test/*.test.ts"
+  },
+  "dependencies": {
+    "zod": "4.6.7"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}