@centia-io/sdk 0.2.13 → 0.2.15

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. 
@@ -575,6 +602,40 @@ await features.deleteFeature('my_schema', 'my_table', [1, 2, 3])
 
 `srs` on `postFeature`/`patchFeature` declares the SRID of the *incoming* geometry. Reading requires a key — use the SQL or WFS APIs to query whole collections. PUT is not supported.
 
+## Snapshots (GeoParquet exports)
+
+`Snapshots` wraps the snapshot API: asynchronous GeoParquet exports of a table or view to S3, and read access to the published snapshot files. It takes a `CentiaHttpClient` and requires a Bearer token:
+
+```ts
+import { createCentiaClient, Snapshots } from '@centia-io/sdk'
+
+const snapshots = new Snapshots(http)
+
+// Queue an export (202; super-user only). The export runs asynchronously.
+const { id } = await snapshots.postSnapshot({ schema: 'geodanmark', relation: 'bygning', srs: 25832 })
+
+// Poll until it finishes (succeeded/failed/superseded) — or use getSnapshot(id) yourself
+const job = await snapshots.waitForSnapshot(id, { intervalMs: 2000, timeoutMs: 300_000 })
+if (job.status === 'failed') throw new Error(job.error ?? 'export failed')
+
+// List jobs, optionally filtered (super-user only)
+const jobs = await snapshots.getSnapshots({ schema: 'geodanmark', relation: 'bygning' })
+
+// Read API — any user with read access to the relation:
+const published = await snapshots.getRelationSnapshots('geodanmark', 'bygning') // newest first
+const meta = await snapshots.getRelationSnapshot('geodanmark', 'bygning', '2026-09-16')
+
+// The Parquet file itself. dataUrl for DuckDB/GDAL/plain fetch; the data
+// methods return the raw Response (stream or buffer it yourself) and follow
+// the 302 redirect to presigned storage URLs.
+const url = snapshots.getRelationSnapshotDataUrl('geodanmark', 'bygning', '2026-09-16')
+const head = await snapshots.headRelationSnapshotData('geodanmark', 'bygning', '2026-09-16') // Content-Length/ETag
+const part = await snapshots.getRelationSnapshotData('geodanmark', 'bygning', '2026-09-16', { range: [0, 1023] })
+const file = await snapshots.getRelationSnapshotFile('geodanmark', 'bygning', '2026-09-16', 'metadata-<id>.json')
+```
+
+The job API is super-user only (403 `SUPER_USER_ONLY`); creating throws 404 (relation not found), 409 (a snapshot of the relation is already pending or running) or 501 (snapshot storage not configured). The read API needs read access to the relation — sub-users with a deny/limit geofence rule get 403 `GEOFENCE_RULES_APPLY`. A snapshot with several data files answers 409 `MULTI_FILE_SNAPSHOT` on `/data`; list `files` in the metadata and fetch them with `getRelationSnapshotFile`.
+
 ## Error handling
 
 - Network/HTTP errors: thrown as `Error` with the status/body text when available.

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
 /**
@@ -650,6 +707,52 @@ var CentiaHttpClient = class {
 			getHeader: (name) => response.headers.get(name)
 		};
 	}
+	/**
+	* Execute a request and return the raw Response without consuming the body.
+	* For binary endpoints (file downloads): follows redirects (a presigned
+	* storage URL — the fetch spec strips Authorization on cross-origin
+	* redirects), sends no Content-Type, and supports extra request headers
+	* such as Range. Throws CentiaApiError on a status not in expectedStatus.
+	*/
+	async requestRaw(opts) {
+		var _this3 = this;
+		var _opts$accept, _opts$expectedStatus2;
+		const url = _this3.buildUrl(opts.path, opts.query);
+		const headers = { "Accept": (_opts$accept = opts.accept) !== null && _opts$accept !== void 0 ? _opts$accept : "*/*" };
+		if (_this3.auth.getAccessToken) {
+			const token = await _this3.auth.getAccessToken();
+			if (token) headers["Authorization"] = `Bearer ${token}`;
+		}
+		if (_this3.auth.getHeaders) Object.assign(headers, await _this3.auth.getHeaders());
+		if (_this3.userAgent && typeof navigator === "undefined") headers["User-Agent"] = _this3.userAgent;
+		Object.assign(headers, opts.headers);
+		const response = await _this3.fetchFn(url, {
+			method: opts.method,
+			headers,
+			redirect: "follow"
+		});
+		if (!((_opts$expectedStatus2 = opts.expectedStatus) !== null && _opts$expectedStatus2 !== void 0 ? _opts$expectedStatus2 : [200]).includes(response.status)) {
+			var _ref, _parsed$message, _response$headers$get;
+			let bodyText = "";
+			try {
+				bodyText = await response.text();
+			} catch (_unused) {}
+			let parsed = null;
+			if (bodyText) try {
+				parsed = JSON.parse(bodyText);
+			} catch (_unused2) {}
+			throw new CentiaApiError({
+				message: ((_ref = (_parsed$message = parsed === null || parsed === void 0 ? void 0 : parsed.message) !== null && _parsed$message !== void 0 ? _parsed$message : parsed === null || parsed === void 0 ? void 0 : parsed.error) !== null && _ref !== void 0 ? _ref : bodyText) || `Unexpected status ${response.status}`,
+				status: response.status,
+				code: parsed === null || parsed === void 0 ? void 0 : parsed.code,
+				details: parsed,
+				requestId: (_response$headers$get = response.headers.get("x-request-id")) !== null && _response$headers$get !== void 0 ? _response$headers$get : void 0,
+				method: opts.method,
+				url
+			});
+		}
+		return response;
+	}
 	buildUrl(path, query) {
 		const cleanPath = path.replace(/^\/+/, "");
 		let url = `${this.baseUrl}/${cleanPath}`;
@@ -660,19 +763,19 @@ var CentiaHttpClient = class {
 		return url;
 	}
 	async buildHeaders(opts) {
-		var _this3 = this;
-		var _opts$accept;
-		const headers = { "Accept": (_opts$accept = opts.accept) !== null && _opts$accept !== void 0 ? _opts$accept : "application/json" };
-		if (_this3.auth.getAccessToken) {
-			const token = await _this3.auth.getAccessToken();
+		var _this4 = this;
+		var _opts$accept2;
+		const headers = { "Accept": (_opts$accept2 = opts.accept) !== null && _opts$accept2 !== void 0 ? _opts$accept2 : "application/json" };
+		if (_this4.auth.getAccessToken) {
+			const token = await _this4.auth.getAccessToken();
 			if (token) headers["Authorization"] = `Bearer ${token}`;
 		}
-		if (_this3.auth.getHeaders) {
-			const authHeaders = await _this3.auth.getHeaders();
+		if (_this4.auth.getHeaders) {
+			const authHeaders = await _this4.auth.getHeaders();
 			Object.assign(headers, authHeaders);
 		}
-		if (_this3.userAgent && typeof navigator === "undefined") headers["User-Agent"] = _this3.userAgent;
-		const ct = _this3.resolveContentType(opts.contentType);
+		if (_this4.userAgent && typeof navigator === "undefined") headers["User-Agent"] = _this4.userAgent;
+		const ct = _this4.resolveContentType(opts.contentType);
 		if (ct) headers["Content-Type"] = ct;
 		return headers;
 	}
@@ -681,24 +784,24 @@ var CentiaHttpClient = class {
 		return contentType !== null && contentType !== void 0 ? contentType : "application/json";
 	}
 	async handleResponse(response, opts, url) {
-		var _opts$expectedStatus2, _parsed;
-		const expectedStatus = (_opts$expectedStatus2 = opts.expectedStatus) !== null && _opts$expectedStatus2 !== void 0 ? _opts$expectedStatus2 : 200;
+		var _opts$expectedStatus3, _parsed;
+		const expectedStatus = (_opts$expectedStatus3 = opts.expectedStatus) !== null && _opts$expectedStatus3 !== void 0 ? _opts$expectedStatus3 : 200;
 		let bodyText = "";
 		try {
 			bodyText = await response.text();
-		} catch (_unused) {}
+		} catch (_unused3) {}
 		let parsed = null;
 		if (bodyText) try {
 			parsed = JSON.parse(bodyText);
-		} catch (_unused2) {}
+		} catch (_unused4) {}
 		if (response.status !== expectedStatus) {
-			var _ref, _parsed$message, _response$headers$get;
+			var _ref2, _parsed$message2, _response$headers$get2;
 			throw new CentiaApiError({
-				message: ((_ref = (_parsed$message = parsed === null || parsed === void 0 ? void 0 : parsed.message) !== null && _parsed$message !== void 0 ? _parsed$message : parsed === null || parsed === void 0 ? void 0 : parsed.error) !== null && _ref !== void 0 ? _ref : bodyText) || `Unexpected status ${response.status}`,
+				message: ((_ref2 = (_parsed$message2 = parsed === null || parsed === void 0 ? void 0 : parsed.message) !== null && _parsed$message2 !== void 0 ? _parsed$message2 : parsed === null || parsed === void 0 ? void 0 : parsed.error) !== null && _ref2 !== void 0 ? _ref2 : bodyText) || `Unexpected status ${response.status}`,
 				status: response.status,
 				code: parsed === null || parsed === void 0 ? void 0 : parsed.code,
 				details: parsed,
-				requestId: (_response$headers$get = response.headers.get("x-request-id")) !== null && _response$headers$get !== void 0 ? _response$headers$get : void 0,
+				requestId: (_response$headers$get2 = response.headers.get("x-request-id")) !== null && _response$headers$get2 !== void 0 ? _response$headers$get2 : void 0,
 				method: opts.method,
 				url
 			});
@@ -3329,6 +3432,150 @@ var Features = class {
 	}
 };
 
+//#endregion
+//#region src/snapshots/Snapshots.ts
+/**
+* Client for the snapshot API: GeoParquet exports of a relation.
+*
+* The job API (`/api/v4/snapshots`) queues and inspects exports and is
+* super-user only; exports run asynchronously — poll with `getSnapshot` or
+* use `waitForSnapshot`. The read API
+* (`/api/v4/schemas/{schema}/relations/{relation}/snapshots`) serves the
+* published snapshots to any user with read access to the relation, with
+* HEAD + byte-range support so Parquet readers can fetch footers and row
+* groups selectively.
+*
+* ```ts
+* const snapshots = new Snapshots(createCentiaClient({ baseUrl, auth }));
+* const { id } = await snapshots.postSnapshot({ schema: 'geodanmark', relation: 'bygning' });
+* const done = await snapshots.waitForSnapshot(id);
+* ```
+*/
+var Snapshots = class {
+	constructor(client) {
+		this.client = client;
+	}
+	relationPath(schema, relation, rest = "") {
+		return `api/v4/schemas/${encodeURIComponent(schema)}/relations/${encodeURIComponent(relation)}/snapshots${rest}`;
+	}
+	/**
+	* Queue a Parquet snapshot of a table or view. Returns 202 with the job id.
+	* Throws `CentiaApiError`: 403 (super-user only), 404 (relation not found),
+	* 409 (a snapshot of the relation is already pending or running),
+	* 501 (snapshot storage not configured).
+	*/
+	async postSnapshot(body) {
+		return this.client.request({
+			path: "api/v4/snapshots",
+			method: "POST",
+			body,
+			expectedStatus: 202
+		});
+	}
+	/** Get a snapshot job by id. Super-user only. */
+	async getSnapshot(id) {
+		return this.client.request({
+			path: `api/v4/snapshots/${encodeURIComponent(id)}`,
+			method: "GET"
+		});
+	}
+	/** List the newest snapshot jobs (50), optionally filtered by schema/relation. Super-user only. */
+	async getSnapshots(options) {
+		var _this3 = this;
+		const query = {};
+		if ((options === null || options === void 0 ? void 0 : options.schema) !== void 0) query.schema = options.schema;
+		if ((options === null || options === void 0 ? void 0 : options.relation) !== void 0) query.relation = options.relation;
+		return _this3.client.request({
+			path: "api/v4/snapshots",
+			method: "GET",
+			query: Object.keys(query).length > 0 ? query : void 0
+		});
+	}
+	/**
+	* Poll a snapshot job until it reaches a terminal status (succeeded, failed
+	* or superseded) and return it — check `status`/`error` on the result.
+	* Throws an `Error` when `timeoutMs` elapses first.
+	*/
+	async waitForSnapshot(id, options) {
+		var _this4 = this;
+		var _options$intervalMs, _options$timeoutMs;
+		const intervalMs = (_options$intervalMs = options === null || options === void 0 ? void 0 : options.intervalMs) !== null && _options$intervalMs !== void 0 ? _options$intervalMs : 2e3;
+		const timeoutMs = (_options$timeoutMs = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _options$timeoutMs !== void 0 ? _options$timeoutMs : 3e5;
+		const deadline = Date.now() + timeoutMs;
+		for (;;) {
+			const job = await _this4.getSnapshot(id);
+			if (job.status === "succeeded" || job.status === "failed" || job.status === "superseded") return job;
+			if (Date.now() + intervalMs > deadline) throw new Error(`Timed out after ${timeoutMs} ms waiting for snapshot ${id} (status: ${job.status})`);
+			await new Promise((resolve) => setTimeout(resolve, intervalMs));
+		}
+	}
+	/** List the published snapshots of a relation, newest first. */
+	async getRelationSnapshots(schema, relation) {
+		var _this5 = this;
+		return _this5.client.request({
+			path: _this5.relationPath(schema, relation),
+			method: "GET"
+		});
+	}
+	/** Get one published snapshot (metadata) by date (`YYYY-MM-DD`). */
+	async getRelationSnapshot(schema, relation, date) {
+		var _this6 = this;
+		return _this6.client.request({
+			path: _this6.relationPath(schema, relation, `/${encodeURIComponent(date)}`),
+			method: "GET"
+		});
+	}
+	/**
+	* Absolute URL of the snapshot's Parquet file, without fetching it — for
+	* DuckDB/GDAL or a plain fetch. Authorization travels in the request
+	* header, so protected relations need the caller to attach the token.
+	*/
+	getRelationSnapshotDataUrl(schema, relation, date) {
+		return `${this.client.baseUrl}/${this.relationPath(schema, relation, `/${encodeURIComponent(date)}/data`)}`;
+	}
+	/**
+	* Fetch the snapshot's Parquet file and return the raw `Response` (stream
+	* or buffer it yourself). Follows the 302 redirect the server answers in
+	* redirect mode. Pass `range` for a single byte range (206). Throws
+	* `CentiaApiError`: 403, 404, 409 (several files; use
+	* getRelationSnapshotFile), 416, 502.
+	*/
+	async getRelationSnapshotData(schema, relation, date, options) {
+		var _this7 = this;
+		return _this7.rawGet(_this7.relationPath(schema, relation, `/${encodeURIComponent(date)}/data`), "GET", options);
+	}
+	/** HEAD request for the snapshot's Parquet file — Content-Length, Accept-Ranges and ETag without the body. */
+	async headRelationSnapshotData(schema, relation, date) {
+		var _this8 = this;
+		return _this8.rawGet(_this8.relationPath(schema, relation, `/${encodeURIComponent(date)}/data`), "HEAD");
+	}
+	/**
+	* Fetch one file of the snapshot by catalog name (`data-<id>.parquet`,
+	* `metadata-<id>.json`). Same redirect/range semantics as
+	* getRelationSnapshotData.
+	*/
+	async getRelationSnapshotFile(schema, relation, date, file, options) {
+		var _this9 = this;
+		return _this9.rawGet(_this9.relationPath(schema, relation, `/${encodeURIComponent(date)}/files/${encodeURIComponent(file)}`), "GET", options);
+	}
+	/** HEAD request for one file of the snapshot. */
+	async headRelationSnapshotFile(schema, relation, date, file) {
+		var _this10 = this;
+		return _this10.rawGet(_this10.relationPath(schema, relation, `/${encodeURIComponent(date)}/files/${encodeURIComponent(file)}`), "HEAD");
+	}
+	async rawGet(path, method, options) {
+		var _this11 = this;
+		const headers = {};
+		if (options === null || options === void 0 ? void 0 : options.range) headers["Range"] = `bytes=${options.range[0]}-${options.range[1]}`;
+		return _this11.client.requestRaw({
+			path,
+			method,
+			headers: Object.keys(headers).length > 0 ? headers : void 0,
+			expectedStatus: [200, 206]
+		});
+	}
+};
+
 //#endregion
 //#region src/auth/errors.ts
 /**
@@ -3456,6 +3703,7 @@ exports.Claims = Claims;
 exports.CodeFlow = CodeFlow;
 exports.Features = Features;
 exports.Gql = Gql;
+exports.GuestFlow = GuestFlow;
 exports.Keyvalue = Keyvalue;
 exports.Mapcache = Mapcache;
 exports.Meta = Meta;
@@ -3467,6 +3715,7 @@ exports.PasswordFlow = PasswordFlow;
 exports.Rpc = Rpc;
 exports.SessionExpiredError = SessionExpiredError;
 exports.SignUp = SignUp;
+exports.Snapshots = Snapshots;
 exports.Sql = Sql;
 exports.SqlNoToken = SqlNoToken;
 exports.Stats = Stats;