@centia-io/sdk 0.2.13 → 0.2.15

package/dist/centia-io-sdk.umd.js

@@ -346,6 +346,9 @@
 		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}`;
@@ -458,12 +461,24 @@
 				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
 			});
@@ -581,6 +596,48 @@
 		}
 	};
 
+//#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
 /**
@@ -655,6 +712,52 @@
 				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}`;
@@ -665,19 +768,19 @@
 			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;
 		}
@@ -686,24 +789,24 @@
 			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
 				});
@@ -3334,6 +3437,150 @@
 		}
 	};
 
+//#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
 /**
@@ -3461,6 +3708,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;
@@ -3472,6 +3720,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centia-io/sdk",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Centia-io TypeScript SDK",
   "author": "Martin Høgh",
   "license": "MIT",