@centia-io/sdk 0.2.14 → 0.2.16

package/README.md

@@ -602,6 +602,88 @@ 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 })
+
+// Or queue several at once (all-or-nothing; accepted jobs come back in request order).
+// getSnapshot also accepts an array of ids.
+const accepted = await snapshots.postSnapshot([
+  { schema: 'geodanmark', relation: 'bygning' },
+  { schema: 'geodanmark', relation: 'vej' },
+])
+const both = await snapshots.getSnapshot(accepted.map((a) => a.id))
+
+// 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`.
+
+## Scheduler (recurring imports)
+
+`Scheduler` wraps the scheduler API: cron-scheduled data-import jobs and their runs. Super-user only. It takes a `CentiaHttpClient` and requires a Bearer token:
+
+```ts
+import { createCentiaClient, Scheduler } from '@centia-io/sdk'
+
+const scheduler = new Scheduler(http)
+
+// Create one or more jobs (201; arrays are all-or-nothing). The new ids are
+// parsed from the Location header, in request order.
+const { ids } = await scheduler.postSchedulerJob({
+  name: 'import buildings',
+  schema: 'geodanmark',
+  url: 'https://example.com/data.zip',
+  schedule: '0 3 * * *', // 5-field cron
+  epsg: 25832,           // defaults: epsg 4326, type "AUTO", encoding "UTF8",
+})                       // delete_append false, download_schema true, active true, snapshot false
+
+// Read jobs — a single id returns one job, an array returns an array
+const jobs = await scheduler.getSchedulerJobs()
+const job = await scheduler.getSchedulerJob(ids[0])
+const some = await scheduler.getSchedulerJob([5497, 5498])
+
+// Update / delete (delete is all-or-nothing; 409 if a run is in progress)
+await scheduler.patchSchedulerJob(ids[0], { active: false })
+await scheduler.deleteSchedulerJob([5497, 5498])
+
+// Runs. Starting is asynchronous (202) — poll getSchedulerRuns until it finishes.
+await scheduler.postSchedulerRun({ job: ids[0], force: true }) // force ignores delete_append and overwrites
+const runs = await scheduler.getSchedulerRuns({ job: ids[0], status: 'running' })
+const run = await scheduler.getSchedulerRun(runs[0].uuid)
+
+// Stop a running run: SIGINT, escalated to SIGKILL by the server after 30 s.
+// The request itself can take up to ~30 s — do not use a short timeout.
+const { signal } = await scheduler.deleteSchedulerRun(runs[0].uuid)
+```
+
+Errors throw `CentiaApiError` with status/code: 400 `INVALID_CRON_FIELD`/`INPUT_VALIDATION_ERROR`, 404 `JOB_NOT_FOUND`/`RUN_NOT_FOUND`, 409 `JOB_RUNNING`.
+
 ## Error handling
 
 - Network/HTTP errors: thrown as `Error` with the status/body text when available.

package/dist/centia-io-sdk.cjs

@@ -707,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}`;
@@ -717,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;
 	}
@@ -738,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
 			});
@@ -3386,6 +3432,265 @@ 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}`;
+	}
+	async postSnapshot(body) {
+		return this.client.request({
+			path: "api/v4/snapshots",
+			method: "POST",
+			body,
+			expectedStatus: 202
+		});
+	}
+	async getSnapshot(id) {
+		var _this2 = this;
+		const keys = Array.isArray(id) ? id : [id];
+		return _this2.client.request({
+			path: `api/v4/snapshots/${keys.map((k) => encodeURIComponent(k)).join(",")}`,
+			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/scheduler/Scheduler.ts
+function idsPath(id) {
+	return (Array.isArray(id) ? id : [id]).map((k) => encodeURIComponent(String(k))).join(",");
+}
+/**
+* Client for the scheduler API (`/api/v4/scheduler`). Super-user only.
+*
+* Jobs describe recurring data imports (cron-scheduled); runs are their
+* executions. Starting a run is asynchronous — poll `getSchedulerRuns`
+* (the `_links.runs` of the 202) until the run finishes.
+*
+* ```ts
+* const scheduler = new Scheduler(createCentiaClient({ baseUrl, auth }));
+* const { ids } = await scheduler.postSchedulerJob({ name, schema, url, schedule: '0 3 * * *' });
+* await scheduler.postSchedulerRun({ job: ids[0] });
+* ```
+*/
+var Scheduler = class {
+	constructor(client) {
+		this.client = client;
+	}
+	/** List all scheduler jobs. */
+	async getSchedulerJobs() {
+		return this.client.request({
+			path: "api/v4/scheduler/jobs",
+			method: "GET"
+		});
+	}
+	async getSchedulerJob(id) {
+		return this.client.request({
+			path: `api/v4/scheduler/jobs/${idsPath(id)}`,
+			method: "GET"
+		});
+	}
+	/**
+	* Create one or more jobs (201; all-or-nothing for arrays). Returns the
+	* Location header and the new ids parsed from it, in request order.
+	*/
+	async postSchedulerJob(body) {
+		var _this3 = this;
+		var _res$getHeader, _location$split$pop;
+		const location = (_res$getHeader = (await _this3.client.requestFull({
+			path: "api/v4/scheduler/jobs",
+			method: "POST",
+			body,
+			expectedStatus: 201
+		})).getHeader("Location")) !== null && _res$getHeader !== void 0 ? _res$getHeader : "";
+		return {
+			location,
+			ids: ((_location$split$pop = location.split("/").pop()) !== null && _location$split$pop !== void 0 ? _location$split$pop : "").split(",").map((s) => Number(s)).filter((n) => Number.isFinite(n))
+		};
+	}
+	/** Partially update a job (303 + Location). */
+	async patchSchedulerJob(id, body) {
+		var _this4 = this;
+		var _res$getHeader2;
+		return { location: (_res$getHeader2 = (await _this4.client.requestFull({
+			path: `api/v4/scheduler/jobs/${idsPath(id)}`,
+			method: "PATCH",
+			body,
+			expectedStatus: 303
+		})).getHeader("Location")) !== null && _res$getHeader2 !== void 0 ? _res$getHeader2 : "" };
+	}
+	/**
+	* Delete one or more jobs (204). Nothing is deleted if any id fails:
+	* throws 404 (unknown id) or 409 (a run is in progress).
+	*/
+	async deleteSchedulerJob(id) {
+		await this.client.request({
+			path: `api/v4/scheduler/jobs/${idsPath(id)}`,
+			method: "DELETE",
+			expectedStatus: 204
+		});
+	}
+	/** List runs (running plus the newest 50 finished), optionally filtered by job and status. */
+	async getSchedulerRuns(options) {
+		var _this6 = this;
+		const query = {};
+		if ((options === null || options === void 0 ? void 0 : options.job) !== void 0) query.job = String(options.job);
+		if ((options === null || options === void 0 ? void 0 : options.status) !== void 0) query.status = options.status;
+		return _this6.client.request({
+			path: "api/v4/scheduler/runs",
+			method: "GET",
+			query: Object.keys(query).length > 0 ? query : void 0
+		});
+	}
+	/** Get one run by uuid. */
+	async getSchedulerRun(uuid) {
+		return this.client.request({
+			path: `api/v4/scheduler/runs/${encodeURIComponent(uuid)}`,
+			method: "GET"
+		});
+	}
+	/**
+	* Start a run of a job (202). Throws 404 (unknown job) or 409 (a run of
+	* the job is already running).
+	*/
+	async postSchedulerRun(body) {
+		return this.client.request({
+			path: "api/v4/scheduler/runs",
+			method: "POST",
+			body,
+			expectedStatus: 202
+		});
+	}
+	/**
+	* Stop a running run: sends SIGINT, which the server escalates to SIGKILL
+	* after 30 s — the request itself can take up to ~30 s, so do not use a
+	* short timeout. Throws 404 (no running run with that uuid) or 409 (the
+	* run is on another host).
+	*/
+	async deleteSchedulerRun(uuid) {
+		return this.client.request({
+			path: `api/v4/scheduler/runs/${encodeURIComponent(uuid)}`,
+			method: "DELETE"
+		});
+	}
+};
+
 //#endregion
 //#region src/auth/errors.ts
 /**
@@ -3523,8 +3828,10 @@ exports.Ogc = Ogc;
 exports.Ows = Ows;
 exports.PasswordFlow = PasswordFlow;
 exports.Rpc = Rpc;
+exports.Scheduler = Scheduler;
 exports.SessionExpiredError = SessionExpiredError;
 exports.SignUp = SignUp;
+exports.Snapshots = Snapshots;
 exports.Sql = Sql;
 exports.SqlNoToken = SqlNoToken;
 exports.Stats = Stats;