@centia-io/sdk 0.2.14 → 0.2.15

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

@@ -712,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}`;
@@ -722,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;
 		}
@@ -743,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
 				});
@@ -3391,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
 /**
@@ -3530,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.14",
+  "version": "0.2.15",
   "description": "Centia-io TypeScript SDK",
   "author": "Martin Høgh",
   "license": "MIT",