@centia-io/sdk 0.2.12 → 0.2.14

package/README.md

@@ -115,6 +115,33 @@ await flow.signIn();
 flow.signOut(); // Clears tokens/options in local storage (no redirect)
 ```
 
+### GuestFlow (Guest tokens – anonymous access)
+
+Obtain tokens for a database's default user (the sub-user used for anonymous access) without any user credentials. Useful for public apps that need a bearer token for public data. Requires that the database has a default user; `clientSecret` is only needed when the OAuth client is not public.
+
+Required options:
+- `host`
+- `clientId`
+- `database`
+- `clientSecret` (only for confidential clients)
+
+Example:
+```ts
+import { GuestFlow } from "@centia-io/sdk";
+
+const flow = new GuestFlow({
+  host: "https://api.centia.io",
+  clientId: "your-client-id",
+  database: "your-database"
+});
+
+await flow.signIn();
+// Tokens for the default user are now stored; subsequent Sql/Rpc calls
+// include the Authorization header and refresh works as usual.
+
+flow.signOut(); // Clears tokens/options in local storage (no redirect)
+```
+
 ### SignUp (Browser – Create a new user)
 
 Use this helper in browser applications to redirect the user to the Centia‑io sign‑up page. 
@@ -474,6 +501,36 @@ const job = await mapcache.deleteMapcacheTileset('my_database', 'my_schema.roads
 
 The endpoint accepts anonymous, HTTP Basic and Bearer token requests; tile requests are authorized against the tileset's layer. Authorization travels in the `Authorization` header — it cannot be embedded in the URL — so for protected tilesets, inject the header per tile request via the map library's request hook (e.g. MapLibre's `transformRequest` or OpenLayers' `tileLoadFunction`).
 
+## OGC API (Features / Maps)
+
+`Ogc` wraps the RESTful OGC API under `/api/v4/ogc/database/{database}` — OGC API Features (Part 1 Core, Part 2 CRS) for reading features as GeoJSON and OGC API Maps (Part 1 Core) for rendered images. Like `Ows`/`Wfs` it takes a `CentiaHttpClient`; Bearer token, HTTP Basic and anonymous requests are all accepted:
+
+```ts
+import { createCentiaClient, Ogc, OGC_CRS84, ogcEpsgCrs } from '@centia-io/sdk'
+
+const ogc = new Ogc(http)
+
+const { collections } = await ogc.getCollections('my_database')
+const collection = await ogc.getCollection('my_database', 'my_schema.roads') // extent, crs list, links
+
+// GeoJSON items — default page size is 10; follow the `next` link or pass offset
+const page = await ogc.getItems<{ gid: number; name: string }>('my_database', 'my_schema.roads', {
+  bbox: [9, 55, 10, 56],        // lon/lat in CRS84 (the default bbox-crs)
+  crs: ogcEpsgCrs(25832),       // output CRS from the collection's crs list
+  limit: 100,
+  datetime: '2024-01-01T00:00:00Z', // versioned layers: the version valid at that time
+})
+page.numberMatched // total; page.numberReturned; page.links (next/prev)
+
+const feature = await ogc.getItem('my_database', 'my_schema.roads', 42)
+
+// Map images are fetched by URL (e.g. an <img> or a map library)
+const url = ogc.mapUrl('my_database', 'my_schema.roads', { bbox: [9, 55, 10, 56], width: 512, format: 'png' })
+const multi = ogc.datasetMapUrl('my_database', ['my_schema.roads', 'my_schema.buildings'], { width: 512 })
+```
+
+CRS values are URIs: `OGC_CRS84` (lon/lat, default) or `ogcEpsgCrs(code)`; note `ogcEpsgCrs(4326)` is lat/lon order per OGC API Features Part 2. A collection that exists but is not readable answers `401` (anonymous) or `403` (no privilege); unknown collections and features are `404` — all thrown as `CentiaApiError`. Geofence rules, versioning and workflow are applied server-side.
+
 ## Key/value store
 
 `Keyvalue` wraps the `/api/v4/keyvalue` endpoints for storing arbitrary JSON under globally unique keys. It takes a `CentiaHttpClient` and requires a Bearer token:

package/dist/centia-io-sdk.cjs

@@ -341,6 +341,9 @@ var Gc2Service = class {
 	isSignUpOptions(options) {
 		return "parentDb" in options;
 	}
+	isGuestFlowOptions(options) {
+		return "database" in options && !("username" in options);
+	}
 	buildUrl(path) {
 		if (path.startsWith("http://") || path.startsWith("https://")) return path;
 		return `${this.host}${path}`;
@@ -453,12 +456,24 @@ var Gc2Service = class {
 			database
 		});
 	}
-	async getRefreshToken(token) {
+	async getGuestToken() {
 		var _this5 = this;
-		var _this$options$tokenUr3;
-		const path = (_this$options$tokenUr3 = _this5.options.tokenUri) !== null && _this$options$tokenUr3 !== void 0 ? _this$options$tokenUr3 : `${_this5.host}/api/v4/oauth`;
+		let database;
+		if (_this5.isGuestFlowOptions(_this5.options)) database = _this5.options.database;
+		else throw new Error("GuestFlow options required for this operation");
+		const path = `${_this5.host}/api/v4/oauth/guest`;
 		return _this5.request(_this5.buildUrl(path), "POST", {
+			database,
 			client_id: _this5.options.clientId,
+			client_secret: _this5.options.clientSecret
+		});
+	}
+	async getRefreshToken(token) {
+		var _this6 = this;
+		var _this$options$tokenUr3;
+		const path = (_this$options$tokenUr3 = _this6.options.tokenUri) !== null && _this$options$tokenUr3 !== void 0 ? _this$options$tokenUr3 : `${_this6.host}/api/v4/oauth`;
+		return _this6.request(_this6.buildUrl(path), "POST", {
+			client_id: _this6.options.clientId,
 			grant_type: "refresh_token",
 			refresh_token: token
 		});
@@ -576,6 +591,48 @@ var PasswordFlow = class {
 	}
 };
 
+//#endregion
+//#region src/GuestFlow.ts
+/**
+* @author     Martin Høgh <mh@mapcentia.com>
+* @copyright  2013-2026 MapCentia ApS
+* @license    https://opensource.org/license/mit  The MIT License
+*
+*/
+/**
+* Guest token flow. Issues access/refresh tokens for the database's default
+* user (the sub-user used for anonymous access) without any user credentials.
+* `clientSecret` is only required when the OAuth client is not public.
+*/
+var GuestFlow = class {
+	constructor(options) {
+		this.options = options;
+		this.service = new Gc2Service(options);
+	}
+	async signIn() {
+		var _this = this;
+		const { access_token, refresh_token } = await _this.service.getGuestToken();
+		setTokens({
+			accessToken: access_token,
+			refreshToken: refresh_token
+		});
+		setOptions({
+			clientId: _this.options.clientId,
+			host: _this.options.host,
+			redirectUri: "",
+			clientSecret: _this.options.clientSecret
+		});
+	}
+	signOut() {
+		this.clear();
+	}
+	clear() {
+		clearTokens();
+		clearOptions();
+		clearNonce();
+	}
+};
+
 //#endregion
 //#region src/http/errors.ts
 /**
@@ -3041,6 +3098,157 @@ var Mapcache = class {
 	}
 };
 
+//#endregion
+//#region src/ogc/Ogc.ts
+/** Default CRS of the OGC API: WGS 84 in longitude/latitude order. */
+const OGC_CRS84 = "http://www.opengis.net/def/crs/OGC/1.3/CRS84";
+/**
+* CRS URI for an EPSG code, e.g. `ogcEpsgCrs(25832)`. Note that
+* `ogcEpsgCrs(4326)` is latitude/longitude order; use `OGC_CRS84` for lon/lat.
+*/
+function ogcEpsgCrs(epsg) {
+	return `http://www.opengis.net/def/crs/EPSG/0/${epsg}`;
+}
+function bboxToString(bbox) {
+	return typeof bbox === "string" ? bbox : bbox.join(",");
+}
+function spatialQuery(options) {
+	const query = {};
+	if ((options === null || options === void 0 ? void 0 : options.bbox) !== void 0) query.bbox = bboxToString(options.bbox);
+	if ((options === null || options === void 0 ? void 0 : options.bboxCrs) !== void 0) query["bbox-crs"] = options.bboxCrs;
+	if ((options === null || options === void 0 ? void 0 : options.crs) !== void 0) query.crs = options.crs;
+	if ((options === null || options === void 0 ? void 0 : options.datetime) !== void 0) query.datetime = options.datetime;
+	return query;
+}
+function nonEmpty(query) {
+	return Object.keys(query).length > 0 ? query : void 0;
+}
+/**
+* OGC API Features (Part 1 Core, Part 2 CRS) and OGC API Maps (Part 1 Core)
+* wrapper for `/api/v4/ogc/database/{database}`.
+*
+* The endpoints accept Bearer token, HTTP Basic and anonymous requests. A
+* Bearer token must match the `database` in the path. Anonymous callers read
+* layers below `Read/write`; a `Read/write` collection answers 401 (Basic
+* challenge) for anonymous callers and 403 for identities without privilege.
+* Geofence rules, versioning and workflow are applied server-side.
+*
+* Map images cannot be fetched through this client; use `mapUrl` /
+* `datasetMapUrl` to build image URLs for `<img>` tags or map libraries.
+*
+* ```ts
+* const ogc = new Ogc(createCentiaClient({ baseUrl, auth }));
+* const page = await ogc.getItems('my_database', 'my_schema.roads', { bbox: [9, 55, 10, 56], limit: 100 });
+* ```
+*/
+var Ogc = class {
+	constructor(client) {
+		this.client = client;
+	}
+	basePath(database) {
+		return `api/v4/ogc/database/${encodeURIComponent(database)}`;
+	}
+	collectionPath(database, collectionId) {
+		return `${this.basePath(database)}/collections/${encodeURIComponent(collectionId)}`;
+	}
+	/** The landing page with links to conformance, collections and the OpenAPI document. */
+	async getLandingPage(database) {
+		var _this = this;
+		return _this.client.request({
+			path: _this.basePath(database),
+			method: "GET"
+		});
+	}
+	/** Conformance classes implemented by the server. */
+	async getConformance(database) {
+		var _this2 = this;
+		return _this2.client.request({
+			path: `${_this2.basePath(database)}/conformance`,
+			method: "GET"
+		});
+	}
+	/** The collections (OWS-enabled layers) the caller may read, paged. */
+	async getCollections(database, options) {
+		var _this3 = this;
+		const query = {};
+		if ((options === null || options === void 0 ? void 0 : options.limit) !== void 0) query.limit = String(options.limit);
+		if ((options === null || options === void 0 ? void 0 : options.offset) !== void 0) query.offset = String(options.offset);
+		return _this3.client.request({
+			path: `${_this3.basePath(database)}/collections`,
+			method: "GET",
+			query: nonEmpty(query)
+		});
+	}
+	/**
+	* One collection. Throws a `CentiaApiError` with status 404 (unknown),
+	* 401 (anonymous caller, credentials required) or 403 (no privilege).
+	*/
+	async getCollection(database, collectionId) {
+		var _this4 = this;
+		return _this4.client.request({
+			path: _this4.collectionPath(database, collectionId),
+			method: "GET"
+		});
+	}
+	/**
+	* Features of a collection as a GeoJSON FeatureCollection page. The default
+	* page size is 10; follow `links` with `rel: 'next'` or pass `offset`.
+	*/
+	async getItems(database, collectionId, options) {
+		var _this5 = this;
+		const query = {};
+		if ((options === null || options === void 0 ? void 0 : options.limit) !== void 0) query.limit = String(options.limit);
+		if ((options === null || options === void 0 ? void 0 : options.offset) !== void 0) query.offset = String(options.offset);
+		Object.assign(query, spatialQuery(options));
+		return _this5.client.request({
+			path: `${_this5.collectionPath(database, collectionId)}/items`,
+			method: "GET",
+			query: nonEmpty(query),
+			accept: "application/geo+json"
+		});
+	}
+	/** One feature by primary key. Throws a 404 `CentiaApiError` when it does not exist. */
+	async getItem(database, collectionId, featureId, options) {
+		var _this6 = this;
+		const query = {};
+		if ((options === null || options === void 0 ? void 0 : options.crs) !== void 0) query.crs = options.crs;
+		if ((options === null || options === void 0 ? void 0 : options.datetime) !== void 0) query.datetime = options.datetime;
+		return _this6.client.request({
+			path: `${_this6.collectionPath(database, collectionId)}/items/${encodeURIComponent(String(featureId))}`,
+			method: "GET",
+			query: nonEmpty(query),
+			accept: "application/geo+json"
+		});
+	}
+	/**
+	* URL of a rendered map of one collection (PNG/JPEG), without fetching it.
+	* Authorization travels in the `Authorization` header, so for protected
+	* collections fetch the image with the header set (or use Basic auth).
+	*/
+	mapUrl(database, collectionId, options) {
+		return this.buildUrl(`${this.collectionPath(database, collectionId)}/map`, this.mapQuery(options));
+	}
+	/** URL of a rendered map of several collections of the same schema. */
+	datasetMapUrl(database, collections, options) {
+		const query = _objectSpread2({ collections: collections.join(",") }, this.mapQuery(options));
+		return this.buildUrl(`${this.basePath(database)}/map`, query);
+	}
+	mapQuery(options) {
+		const query = spatialQuery(options);
+		if ((options === null || options === void 0 ? void 0 : options.width) !== void 0) query.width = String(options.width);
+		if ((options === null || options === void 0 ? void 0 : options.height) !== void 0) query.height = String(options.height);
+		if ((options === null || options === void 0 ? void 0 : options.format) !== void 0) query.f = options.format;
+		if ((options === null || options === void 0 ? void 0 : options.transparent) !== void 0) query.transparent = String(options.transparent);
+		if ((options === null || options === void 0 ? void 0 : options.bgcolor) !== void 0) query.bgcolor = options.bgcolor;
+		return query;
+	}
+	buildUrl(path, query) {
+		let url = `${this.client.baseUrl}/${path}`;
+		if (Object.keys(query).length > 0) url += `?${new URLSearchParams(query).toString()}`;
+		return url;
+	}
+};
+
 //#endregion
 //#region src/keyvalue/Keyvalue.ts
 /**
@@ -3305,10 +3513,13 @@ exports.Claims = Claims;
 exports.CodeFlow = CodeFlow;
 exports.Features = Features;
 exports.Gql = Gql;
+exports.GuestFlow = GuestFlow;
 exports.Keyvalue = Keyvalue;
 exports.Mapcache = Mapcache;
 exports.Meta = Meta;
 exports.NotLoggedInError = NotLoggedInError;
+exports.OGC_CRS84 = OGC_CRS84;
+exports.Ogc = Ogc;
 exports.Ows = Ows;
 exports.PasswordFlow = PasswordFlow;
 exports.Rpc = Rpc;
@@ -3327,4 +3538,5 @@ exports.createCentiaAdminClient = createCentiaAdminClient;
 exports.createCentiaClient = createCentiaClient;
 exports.createSqlBuilder = createSqlBuilder;
 exports.createTokenProvider = createTokenProvider;
-exports.isCentiaApiError = isCentiaApiError;
+exports.isCentiaApiError = isCentiaApiError;
+exports.ogcEpsgCrs = ogcEpsgCrs;