TypeScript SDK

The GeoLens TypeScript SDK (@geolens/sdk) is a typed client for the GeoLens API. It uses the platform’s native fetch, ships typed request/response interfaces, and provides Bearer-token + API-key auth helpers. It is Apache-2.0 licensed and auto-generated from the OpenAPI contract, so every operation mirrors a real endpoint in the API reference.

Install

npm install @geolens/sdk

The package is ESM-only and requires Node 18+ (or any runtime with native fetch). Import it from an ES module ("type": "module" in your package.json, or a .mjs/.ts file).

Authenticate

Configure a client with createGeolensClient. The deployed API is served under /api, so include that suffix in baseUrl:

import { createGeolensClient } from '@geolens/sdk';

const sdk = createGeolensClient({
  baseUrl: 'https://geolens.example.com/api',
  bearerToken: '...', // a JWT from POST /api/auth/login
});

You get a bearer token the same way the CLI and any raw client do: POST /api/auth/login returns a JWT. See Authentication for the full token-acquisition flow.

The SDK supports the same two header auth modes as the rest of GeoLens: Bearer or API key, but not both:

// API-key auth instead of a bearer token (sent as X-Api-Key):
const sdk = createGeolensClient({
  baseUrl: 'https://geolens.example.com/api',
  apiKey: '...',
});

Reuse a token from the environment

For scripts and CI, read the token from the environment instead of hard-coding it, the same GEOLENS_TOKEN convention the CLI uses:

import { createGeolensClient } from '@geolens/sdk';

const sdk = createGeolensClient({
  baseUrl: process.env.GEOLENS_INSTANCE!, // e.g. https://geolens.example.com/api
  bearerToken: process.env.GEOLENS_TOKEN!,
});

The CLI and the MCP server append /api to GEOLENS_INSTANCE when it is missing; the SDK does not. Export the variable with the /api suffix and all three accept it. Without the suffix, the SDK points at the site root, which serves the web app’s HTML with a 200, so data comes back as an HTML string and every typed field on it is undefined.

Passing both bearerToken and apiKey throws. With neither, the client is anonymous and can only reach public endpoints.

First call

Operation functions are exported from the package root and take an options object. Pass the configured client via sdk.client. Each returns a promise that resolves to a { data, error, response } result rather than throwing, so a 404 is a value you branch on. That contract starts once bytes come back: when the browser or runtime refuses to make the request at all (CORS, DNS, offline), response is unset and error holds the fetch failure, so check response before data or error.

The health check is the simplest read: no parameters, no auth required:

import { createGeolensClient, healthHealthGet } from '@geolens/sdk';

const sdk = createGeolensClient({
  baseUrl: 'https://geolens.example.com/api',
});

const { data, error, response } = await healthHealthGet({ client: sdk.client });

if (!response) {
  // The request never reached the server: there is no status to read.
  throw new Error(`Could not reach the instance: ${String(error)}`);
}
if (error) {
  throw new Error(`Health check failed (${response.status}): ${JSON.stringify(error)}`);
}

console.log(data.status);     // e.g. "healthy"
console.log(data.providers);  // per-service status, keyed by provider name

data is typed as HealthResponse (status: string plus a providers map of ServiceHealth objects), so your editor autocompletes the response shape.

Catalog search and CORS

Catalog search has two routes, and where your code runs decides which to call. From Node, or from a page the instance itself serves, searchDatasetsEndpointSearchDatasetsGet (GET /api/search/datasets/) resolves to a typed OGCFeatureCollectionResponse. From a browser page on another origin, call the OGC API Records route instead, collectionItemsCollectionsDatasetsItemsGet (GET /api/collections/datasets/items?q=).

Standards routes answer anonymous requests from any origin with Access-Control-Allow-Origin: *; native routes such as /search/datasets/ answer only origins listed in CORS_ALLOWED_ORIGINS, so from an unlisted origin the browser discards the response (as of v1.14.0). Both routes run the same search. Once a request carries X-Api-Key or Authorization, the anonymous wildcard no longer applies and the page’s origin must be listed either way.

In the browser without a build step

@geolens/sdk is ESM, so a static page can import it straight from a CDN:

<script type="module">
  import {
    createGeolensClient,
    collectionItemsCollectionsDatasetsItemsGet,
  } from 'https://esm.sh/@geolens/sdk';
</script>

Pin the package version in that URL (@geolens/sdk@<version>, matching what /api/health reports for your instance) so the page does not change under you; the examples repo keeps the pinned form. For a bundled app, install from npm and let the bundler resolve it.

createGeolensClient configures a module-level singleton and returns it. Calling it twice reconfigures the first client rather than producing a second, so one page cannot talk to two instances at once.

A complete page that searches the catalog, reads a dataset’s record, and draws its vector tiles is typescript/catalog-map.html (live), with the CORS split and authentication notes in typescript/README.md.

Next steps

• Authentication: how to obtain a bearer token or API key.
• API reference: the full operation surface; every exported function maps to an endpoint here.
• CLI & Manifests: for terminal and CI workflows.
• Python SDK: the same surface for Python.