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 — 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!,
});

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 } result.

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 } = await healthHealthGet({ client: sdk.client });

if (error) {
  throw new Error(`Health check failed: ${JSON.stringify(error)}`);
}

console.log(data.status);     // e.g. "ok"
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.

Authenticated reads follow the same shape — for example, searching the catalog uses the exported searchDatasetsEndpointSearchDatasetsGet function and resolves to a typed OGCFeatureCollectionResponse.

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.