@chronos.sh/sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chronos Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @chronos.sh/sdk
+
+Official Node.js SDK for [Chronos](https://chronos.sh) — reliable job scheduling as a service.
+
+```ts
+import { Chronos } from '@chronos.sh/sdk';
+
+const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY! });
+
+chronos.worker.handle('send-email', async (ctx) => {
+  await sendEmail(ctx.payload);
+  return { sent: true };
+});
+
+await chronos.worker.start();
+```
+
+Zero dependencies. Runs anywhere with `fetch` — Node.js 20+, Bun, Deno.
+
+## Install
+
+```sh
+npm install @chronos.sh/sdk
+```
+
+## Quickstart
+
+```ts
+import { Chronos } from '@chronos.sh/sdk';
+
+const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY! });
+
+chronos.worker.handle<{ to: string }>('send-email', async (ctx) => {
+  await sendEmail(ctx.payload.to);
+  return { sent: true };
+});
+
+await chronos.worker.start();
+```
+
+`worker.start()` long-polls for jobs and dispatches them to registered handlers. It runs until you call `worker.stop()`.
+
+## Graceful shutdown
+
+The SDK does not install signal handlers — your application owns its process lifecycle. Wire `SIGTERM`/`SIGINT` to `worker.stop()` so in-flight jobs and their result reports finish before the process exits:
+
+```ts
+let stopping = false;
+for (const sig of ['SIGTERM', 'SIGINT'] as const) {
+  process.on(sig, () => {
+    if (stopping) process.exit(1);
+    stopping = true;
+    chronos.worker.stop().then(() => process.exit(143));
+  });
+}
+```
+
+A second signal force-exits as an escape hatch. This matters for any long-running worker: standalone scripts, Docker containers, systemd services, PM2, cloud VMs, or CI runners.
+
+## Documentation
+
+[Chronos documentation](https://chronos.sh/docs)
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -0,0 +1,552 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/errors.ts
+/**
+* Base class for all errors thrown by the Chronos SDK. Catch this in a
+* single `catch` to handle any SDK failure generically; use the subclasses
+* to branch on cause.
+*
+* @example
+* ```ts
+* import { Chronos, ChronosError } from '@chronos.sh/sdk';
+*
+* const chronos = new Chronos({ apiKey: 'chrns_...' });
+* try {
+*   await chronos.worker.start();
+* } catch (err) {
+*   if (err instanceof ChronosError) {
+*     console.error('Chronos failed:', err.message);
+*   }
+* }
+* ```
+*/
+var ChronosError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "ChronosError";
+		if (options && !("cause" in this)) Object.defineProperty(this, "cause", {
+			value: options.cause,
+			configurable: true,
+			writable: true
+		});
+	}
+};
+/**
+* Thrown when SDK options fail validation at `new Chronos({ ... })`. Covers
+* `apiKey`, `baseUrl`, `pollWaitTimeSeconds`, and `retryDelayMs`.
+*
+* @example
+* ```ts
+* import { Chronos, ChronosConfigError } from '@chronos.sh/sdk';
+*
+* try {
+*   const chronos = new Chronos({ apiKey: '' });
+* } catch (err) {
+*   if (err instanceof ChronosConfigError) {
+*     console.error('Invalid Chronos config:', err.message);
+*   }
+* }
+* ```
+*/
+var ChronosConfigError = class extends ChronosError {
+	constructor(message) {
+		super(message);
+		this.name = "ChronosConfigError";
+	}
+};
+/**
+* Thrown when the Chronos API responds with a non-2xx status or a
+* `success: false` envelope. Carries HTTP `status`, the application
+* `code`, parsed `body`, and the API's `X-Request-Id`.
+*
+* `instanceof ChronosApiError` means the server replied;
+* network/transport failures throw {@link ChronosNetworkError} instead.
+*
+* @example
+* ```ts
+* import { ChronosApiError } from '@chronos.sh/sdk';
+*
+* function handleSdkError(err: unknown) {
+*   if (err instanceof ChronosApiError) {
+*     if (err.status === 401) return refreshAuth();
+*     console.error('API error', { status: err.status, requestId: err.requestId });
+*   }
+* }
+* ```
+*/
+var ChronosApiError = class extends ChronosError {
+	/** HTTP status code returned by the Chronos API. */
+	status;
+	/** Application-level error code from the response envelope, when present. */
+	code;
+	/** Full parsed response payload (envelope + data, or whatever the server returned). */
+	body;
+	/** Value of the `X-Request-Id` response header, when present. */
+	requestId;
+	constructor(message, options) {
+		super(message);
+		this.name = "ChronosApiError";
+		this.status = options.status;
+		this.code = options.code;
+		this.body = options.body;
+		this.requestId = options.requestId;
+	}
+};
+/**
+* Thrown when the underlying `fetch` rejects before the server replies —
+* DNS failure, TCP reset, connection refused, etc. The original error is
+* available on `.cause`.
+*
+* Abort signals propagate unwrapped — `instanceof ChronosNetworkError`
+* always means a real transport failure, not a graceful shutdown.
+*
+* @example
+* ```ts
+* import { ChronosNetworkError } from '@chronos.sh/sdk';
+*
+* function handleSdkError(err: unknown) {
+*   if (err instanceof ChronosNetworkError) {
+*     console.warn('Transport blip', { cause: err.cause });
+*   }
+* }
+* ```
+*/
+var ChronosNetworkError = class extends ChronosError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "ChronosNetworkError";
+	}
+};
+/**
+* Wraps an exception thrown by a user-supplied {@link ChronosHandler}. The
+* original error is on `.cause`; `.message` is copied from the original so
+* the SDK reports it to the API as the failure reason.
+*
+* @example
+* ```ts
+* import { ChronosHandlerError } from '@chronos.sh/sdk';
+*
+* if (err instanceof ChronosHandlerError) {
+*   console.error('Handler threw', err.cause);
+* }
+* ```
+*/
+var ChronosHandlerError = class extends ChronosError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "ChronosHandlerError";
+	}
+};
+//#endregion
+//#region src/internal/logger.ts
+const defaultLogger = {
+	debug: (message, meta) => logToConsole(console.debug, message, meta),
+	info: (message, meta) => logToConsole(console.info, message, meta),
+	warn: (message, meta) => logToConsole(console.warn, message, meta),
+	error: (message, meta) => logToConsole(console.error, message, meta)
+};
+function logToConsole(method, message, meta) {
+	if (meta) method(message, meta);
+	else method(message);
+}
+function validateApiKey(apiKey) {
+	const trimmed = apiKey?.trim();
+	if (!trimmed) throw new ChronosConfigError("Chronos apiKey is required");
+	return trimmed;
+}
+function validatePollWaitTime(seconds) {
+	if (!Number.isInteger(seconds) || seconds < 0 || seconds > 20) throw new ChronosConfigError(`pollWaitTimeSeconds must be an integer between 0 and 20`);
+}
+function validateRetryDelayMs(ms) {
+	if (!Number.isFinite(ms) || ms < 0) throw new ChronosConfigError("retryDelayMs must be a non-negative number");
+}
+function normalizeHandlerName(name) {
+	const normalized = name.trim();
+	if (!normalized) throw new ChronosError("Handler name is required");
+	if (normalized.length > 255) throw new ChronosError(`Handler name must be 255 characters or fewer`);
+	return normalized;
+}
+//#endregion
+//#region src/client.ts
+/** Default Chronos API base URL. */
+const DEFAULT_BASE_URL = "https://api.chronos.sh";
+var BaseClient = class {
+	apiKey;
+	baseUrl;
+	fetch;
+	logger;
+	headers;
+	constructor(options) {
+		this.apiKey = validateApiKey(options.apiKey);
+		this.baseUrl = normalizeBaseUrl(options.baseUrl ?? "https://api.chronos.sh");
+		this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+		this.logger = options.logger ?? defaultLogger;
+		this.headers = {
+			"content-type": "application/json",
+			authorization: `Bearer ${this.apiKey}`
+		};
+	}
+	async request(path, body, signal) {
+		let response;
+		try {
+			response = await this.fetch(`${this.baseUrl}${path}`, {
+				method: "POST",
+				headers: this.headers,
+				body: JSON.stringify(body),
+				signal
+			});
+		} catch (err) {
+			if (signal?.aborted) throw err;
+			throw new ChronosNetworkError(`Chronos API request failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+		}
+		const payload = await parseJsonResponse(response);
+		const envelope = isEnvelope(payload) ? payload : void 0;
+		if (!response.ok || envelope && !envelope.success) throw new ChronosApiError(apiErrorMessage(response, envelope), {
+			status: response.status,
+			code: typeof envelope?.code === "string" ? envelope.code : void 0,
+			body: payload,
+			requestId: response.headers.get("x-request-id") ?? void 0
+		});
+		if (!envelope) throw new ChronosError("Chronos API returned an invalid response");
+		return envelope.data;
+	}
+};
+function normalizeBaseUrl(baseUrl) {
+	const normalized = baseUrl.trim().replace(/\/+$/, "");
+	if (!normalized) throw new ChronosConfigError("Chronos baseUrl is required");
+	return normalized;
+}
+async function parseJsonResponse(response) {
+	try {
+		return await response.json();
+	} catch {
+		return null;
+	}
+}
+function apiErrorMessage(response, envelope) {
+	if (typeof envelope?.message === "string" && envelope.message.trim()) return envelope.message;
+	return response.ok ? "Chronos API returned an invalid response" : `Chronos API request failed with status ${response.status}`;
+}
+function isEnvelope(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return typeof value.success === "boolean";
+}
+//#endregion
+//#region src/worker.ts
+/** Default worker long-poll wait time in seconds. Equal to the API maximum. */
+const DEFAULT_POLL_WAIT_TIME_SECONDS = 20;
+const DEFAULT_RETRY_DELAY_MS = 1e3;
+const RESULT_REPORT_MAX_ATTEMPTS = 3;
+const MAX_REPORTED_ERROR_LENGTH = 4096;
+const DEFAULT_HANDLER_ERROR = "Chronos handler failed";
+/**
+* Long-poll worker. Claims jobs from the Chronos API, dispatches them to
+* registered handlers, and reports results.
+*
+* Construct via `new Chronos({ apiKey }).worker` rather than directly.
+*/
+var Worker = class {
+	client;
+	pollWaitTimeSeconds;
+	retryDelayMs;
+	handlers = /* @__PURE__ */ new Map();
+	handlerNames = [];
+	startPromise;
+	pollController;
+	constructor(client, options) {
+		this.client = client;
+		this.pollWaitTimeSeconds = options.pollWaitTimeSeconds ?? 20;
+		this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+		validatePollWaitTime(this.pollWaitTimeSeconds);
+		validateRetryDelayMs(this.retryDelayMs);
+	}
+	/**
+	* Register a handler for a named job type. Invoked when the Chronos API
+	* claims a job whose `handler` field matches `name`. Names are trimmed and
+	* must be 1–255 characters.
+	*
+	* @param name - Handler name. Must match the schedule's `handler` on the API side.
+	* @param handler - Async function invoked with the job context. Return a
+	*   plain object to record a result, or `undefined` for none.
+	* @returns The Worker, for chaining.
+	* @throws {ChronosError} If the name is invalid, already registered, or `handler` is not a function.
+	*
+	* @example
+	* ```ts
+	* chronos.worker
+	*   .handle('send-email', async (ctx) => ({ sent: true }))
+	*   .handle('cleanup', async () => undefined);
+	* ```
+	*/
+	handle(name, handler) {
+		const normalizedName = normalizeHandlerName(name);
+		if (this.handlers.has(normalizedName)) throw new ChronosError(`Handler "${normalizedName}" is already registered`);
+		if (typeof handler !== "function") throw new ChronosError(`Handler "${normalizedName}" must be a function`);
+		this.handlers.set(normalizedName, handler);
+		this.handlerNames.push(normalizedName);
+		return this;
+	}
+	/**
+	* Begin long-polling for jobs. The returned promise resolves when
+	* {@link Worker.stop} is called and any in-flight job completes.
+	*
+	* @throws {ChronosError} Synchronously, if no handlers are registered or the worker is already running.
+	*/
+	start() {
+		if (this.startPromise) throw new ChronosError("Chronos worker is already started");
+		if (this.handlers.size === 0) throw new ChronosError("Register at least one handler before starting Chronos");
+		this.pollController = new AbortController();
+		this.startPromise = this.runLoop().finally(() => {
+			this.startPromise = void 0;
+			this.pollController = void 0;
+		});
+		return this.startPromise;
+	}
+	/**
+	* Request graceful shutdown. The poll loop is aborted immediately; any
+	* in-flight handler and result-report are allowed to complete to preserve
+	* at-least-once delivery. Returns the same promise as the active
+	* {@link Worker.start}, or a resolved promise if the worker isn't running.
+	*/
+	stop() {
+		this.pollController?.abort();
+		return this.startPromise ?? Promise.resolve();
+	}
+	get isStopped() {
+		return this.pollController?.signal.aborted ?? true;
+	}
+	async runLoop() {
+		while (!this.isStopped) try {
+			const job = await this.claimJob();
+			if (job) await this.processJob(job);
+		} catch (err) {
+			if (this.isStopped) break;
+			this.client.logger.error("Chronos poll loop error", { err: errorToLogValue(err) });
+			await sleep(this.retryDelayMs, this.pollController?.signal);
+		}
+	}
+	async claimJob() {
+		if (this.handlerNames.length === 0) throw new ChronosError("Cannot claim jobs without registered handlers");
+		return this.client.request("/v1/worker/jobs/claim", {
+			wait_time_seconds: this.pollWaitTimeSeconds,
+			handlers: this.handlerNames
+		}, this.pollController?.signal);
+	}
+	async processJob(job) {
+		const handler = this.handlers.get(job.handler);
+		if (!handler) return this.handleUnregisteredJob(job);
+		let handlerResult;
+		try {
+			handlerResult = await handler(createContext(job));
+		} catch (err) {
+			const message = errorMessage(err);
+			const handlerErr = new ChronosHandlerError(message, { cause: err });
+			this.client.logger.error("Chronos handler failed", {
+				...jobLogMeta(job),
+				err: errorToLogValue(handlerErr)
+			});
+			await this.safeReportFailed(job, message);
+			return;
+		}
+		let result;
+		try {
+			result = normalizeHandlerResult(handlerResult);
+		} catch (err) {
+			this.client.logger.error("Chronos handler returned invalid result", {
+				...jobLogMeta(job),
+				err: errorToLogValue(err)
+			});
+			await this.safeReportFailed(job, errorMessage(err));
+			return;
+		}
+		try {
+			await this.reportCompleted(job.execution_id, result);
+		} catch (err) {
+			this.logResultReportFailure(err, job, "completed");
+		}
+	}
+	async handleUnregisteredJob(job) {
+		const message = `Chronos SDK received job for unregistered handler "${job.handler}"`;
+		this.client.logger.error(message, jobLogMeta(job));
+		await this.safeReportFailed(job, message);
+	}
+	async safeReportFailed(job, message) {
+		try {
+			await this.reportFailed(job.execution_id, message);
+		} catch (err) {
+			this.logResultReportFailure(err, job, "failed");
+		}
+	}
+	async reportCompleted(executionId, result) {
+		await this.reportResultWithRetry(executionId, {
+			status: "completed",
+			...result === void 0 ? {} : { result }
+		});
+	}
+	async reportFailed(executionId, error) {
+		await this.reportResultWithRetry(executionId, {
+			status: "failed",
+			error: truncate(error, MAX_REPORTED_ERROR_LENGTH)
+		});
+	}
+	async reportResultWithRetry(executionId, body) {
+		let lastErr;
+		for (let attempt = 1; attempt <= RESULT_REPORT_MAX_ATTEMPTS; attempt++) try {
+			await this.client.request(`/v1/worker/executions/${encodeURIComponent(executionId)}/result`, body);
+			return;
+		} catch (err) {
+			const apiErr = err instanceof ChronosApiError ? err : void 0;
+			if (apiErr?.status === 409) {
+				this.client.logger.warn("Chronos result discarded; execution already terminal", {
+					executionId,
+					status: body.status,
+					code: apiErr.code
+				});
+				return;
+			}
+			if (apiErr && isTerminalReportError(apiErr.status)) throw apiErr;
+			lastErr = err;
+			if (attempt === RESULT_REPORT_MAX_ATTEMPTS) break;
+			this.client.logger.warn("Chronos result report failed; retrying", {
+				err: errorToLogValue(err),
+				executionId,
+				status: body.status,
+				attempt,
+				maxAttempts: RESULT_REPORT_MAX_ATTEMPTS
+			});
+			await sleep(this.retryDelayMs);
+		}
+		throw lastErr;
+	}
+	logResultReportFailure(err, job, status) {
+		const isTerminal = err instanceof ChronosApiError && isTerminalReportError(err.status);
+		this.client.logger.error(isTerminal ? "Chronos result report rejected by API" : "Chronos result report failed after retries", {
+			...jobLogMeta(job),
+			err: errorToLogValue(err),
+			status
+		});
+	}
+};
+function createContext(job) {
+	return {
+		jobId: job.job_id,
+		executionId: job.execution_id,
+		handler: job.handler,
+		payload: job.payload,
+		scheduledFor: new Date(job.scheduled_for),
+		attempt: job.attempt,
+		timeout: job.timeout,
+		schedule: job.schedule
+	};
+}
+function jobLogMeta(job) {
+	return {
+		jobId: job.job_id,
+		executionId: job.execution_id,
+		handler: job.handler
+	};
+}
+function normalizeHandlerResult(result) {
+	if (result === void 0) return;
+	if (!isPlainObject(result)) throw new ChronosError("Chronos handler result must be a plain object or undefined");
+	try {
+		JSON.stringify(result);
+	} catch (err) {
+		throw new ChronosError(`Chronos handler result is not JSON-encodable: ${err instanceof Error ? err.message : "value is not JSON-encodable"}`);
+	}
+	return result;
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function errorMessage(err) {
+	return (err instanceof Error ? err.message : String(err)).trim() || DEFAULT_HANDLER_ERROR;
+}
+function errorToLogValue(err) {
+	if (!(err instanceof Error)) return err;
+	const base = {
+		name: err.name,
+		message: err.message,
+		stack: err.stack
+	};
+	if (err instanceof ChronosApiError) return {
+		...base,
+		status: err.status,
+		code: err.code,
+		requestId: err.requestId
+	};
+	if (err instanceof ChronosNetworkError || err instanceof ChronosHandlerError) return {
+		...base,
+		cause: errorToLogValue(err.cause)
+	};
+	return base;
+}
+function truncate(value, maxLength) {
+	return value.length <= maxLength ? value : value.slice(0, maxLength);
+}
+const NON_TERMINAL_4XX = new Set([
+	408,
+	409,
+	429
+]);
+function isTerminalReportError(status) {
+	if (status === 200) return true;
+	if (NON_TERMINAL_4XX.has(status)) return false;
+	return status >= 400 && status < 500;
+}
+function sleep(ms, signal) {
+	if (signal?.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const timeout = setTimeout(done, ms);
+		function done() {
+			clearTimeout(timeout);
+			signal?.removeEventListener("abort", done);
+			resolve();
+		}
+		signal?.addEventListener("abort", done, { once: true });
+	});
+}
+//#endregion
+//#region src/index.ts
+/**
+* The Chronos SDK client. Composes worker and (future) REST resource
+* subclients from a single instance.
+*
+* @example
+* ```ts
+* import { Chronos } from '@chronos.sh/sdk';
+*
+* const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY! });
+*
+* chronos.worker.handle<{ to: string }>('send-email', async (ctx) => {
+*   await sendEmail(ctx.payload.to);
+*   return { sent: true };
+* });
+*
+* await chronos.worker.start();
+* ```
+*/
+var Chronos = class {
+	/** Long-poll worker for executing pull-mode jobs. */
+	worker;
+	/**
+	* @param options - Client configuration. Only `apiKey` is required.
+	* @throws {ChronosConfigError} If `apiKey` is missing or any option fails validation.
+	*/
+	constructor(options) {
+		const client = new BaseClient(options);
+		this.worker = new Worker(client, options);
+	}
+};
+//#endregion
+exports.Chronos = Chronos;
+exports.ChronosApiError = ChronosApiError;
+exports.ChronosConfigError = ChronosConfigError;
+exports.ChronosError = ChronosError;
+exports.ChronosHandlerError = ChronosHandlerError;
+exports.ChronosNetworkError = ChronosNetworkError;
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.DEFAULT_POLL_WAIT_TIME_SECONDS = DEFAULT_POLL_WAIT_TIME_SECONDS;
+
+//# sourceMappingURL=index.cjs.map