@chronos.sh/sdk 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+//#region src/types.d.ts
+/**
+ * Result returned by a {@link ChronosHandler}. Plain objects are recorded on
+ * the execution; `void` / `undefined` records no result.
+ */
+type ChronosHandlerResult = Record<string, unknown> | void;
+/**
+ * Custom fetch implementation. Compatible with `globalThis.fetch`. Pass via
+ * {@link ChronosOptions.fetch} to inject middleware (logging, tracing, custom
+ * timeouts) or run in environments without a global `fetch`.
+ */
+type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Logger interface. Pass via {@link ChronosOptions.logger} to integrate with
+ * your app's logging stack.
+ *
+ * Note: signature is `(message, meta?)` — message string first, optional
+ * structured metadata second. If adapting from pino-style `(obj, message)`,
+ * swap the argument order.
+ */
+type ChronosLogger = {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+};
+/** Options for constructing a {@link Chronos} client. */
+type ChronosOptions = {
+  /** API key for authentication. Sent as `Authorization: Bearer <key>`. */apiKey: string;
+  /**
+   * Override the API base URL. Defaults to `https://api.chronos.sh`. Useful
+   * for local development or self-hosted Chronos instances.
+   */
+  baseUrl?: string; /** Custom fetch implementation. Defaults to `globalThis.fetch`. */
+  fetch?: FetchLike; /** Custom logger. Defaults to a console-backed logger. */
+  logger?: ChronosLogger;
+  /**
+   * Worker long-poll wait time in seconds. Must be an integer between 0 and
+   * 20 inclusive. Defaults to 20 (the API maximum).
+   */
+  pollWaitTimeSeconds?: number;
+  /**
+   * Worker retry delay in milliseconds. Used between failed result-report
+   * attempts and between poll-loop iterations after a claim error. Defaults
+   * to 1000.
+   */
+  retryDelayMs?: number;
+};
+/** Schedule that produced a job. */
+type ChronosSchedule = {
+  /** Schedule identifier. */id: string; /** Human-readable schedule name. */
+  name: string;
+};
+/**
+ * Context passed to a {@link ChronosHandler} when a job is claimed. Type the
+ * payload by supplying a generic argument.
+ *
+ * @example
+ * ```ts
+ * type SendEmailPayload = { to: string; subject: string };
+ *
+ * chronos.worker.handle<SendEmailPayload>('send-email', async (ctx) => {
+ *   await sendEmail(ctx.payload.to, ctx.payload.subject);
+ *   return { sent: true };
+ * });
+ * ```
+ */
+type ChronosContext<TPayload = unknown> = {
+  /** Stable identifier for the job (the schedule run). */jobId: string; /** Identifier for this specific execution attempt. Use for idempotency. */
+  executionId: string; /** Handler name, matching the one registered with `worker.handle()`. */
+  handler: string; /** Job payload, typed as `TPayload`. */
+  payload: TPayload; /** When the job was scheduled to run. */
+  scheduledFor: Date; /** Attempt number. 1 for the first attempt, increments on retries. */
+  attempt: number; /** Soft timeout for the handler in seconds. Informational; the SDK does not enforce. */
+  timeout: number; /** Schedule that produced this job, or `null` for ad-hoc jobs. */
+  schedule: ChronosSchedule | null;
+};
+/**
+ * Async function that processes a Chronos job. Return a plain object to
+ * record a result on the execution, or `undefined` for no result.
+ */
+type ChronosHandler<TPayload = unknown> = (ctx: ChronosContext<TPayload>) => ChronosHandlerResult | Promise<ChronosHandlerResult>;
+//#endregion
+//#region src/client.d.ts
+/** Default Chronos API base URL. */
+declare const DEFAULT_BASE_URL = "https://api.chronos.sh";
+declare class BaseClient {
+  readonly apiKey: string;
+  readonly baseUrl: string;
+  readonly fetch: FetchLike;
+  readonly logger: ChronosLogger;
+  private readonly headers;
+  constructor(options: ChronosOptions);
+  request<T>(path: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+}
+//#endregion
+//#region src/worker.d.ts
+/** Default worker long-poll wait time in seconds. Equal to the API maximum. */
+declare const DEFAULT_POLL_WAIT_TIME_SECONDS = 20;
+/**
+ * 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.
+ */
+declare class Worker {
+  private readonly client;
+  private readonly pollWaitTimeSeconds;
+  private readonly retryDelayMs;
+  private readonly handlers;
+  private handlerNames;
+  private startPromise?;
+  private pollController?;
+  constructor(client: BaseClient, options: ChronosOptions);
+  /**
+   * 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<TPayload = unknown>(name: string, handler: ChronosHandler<TPayload>): 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(): Promise<void>;
+  /**
+   * 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(): Promise<void>;
+  private get isStopped();
+  private runLoop;
+  private claimJob;
+  private processJob;
+  private handleUnregisteredJob;
+  private safeReportFailed;
+  private reportCompleted;
+  private reportFailed;
+  private reportResultWithRetry;
+  private logResultReportFailure;
+}
+//#endregion
+//#region src/errors.d.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);
+ *   }
+ * }
+ * ```
+ */
+declare class ChronosError extends Error {
+  /** Original error/value that caused this SDK error, when one is available. */
+  readonly cause?: unknown;
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+declare class ChronosConfigError extends ChronosError {
+  constructor(message: string);
+}
+/** Options for constructing a {@link ChronosApiError}. */
+type ChronosApiErrorOptions = {
+  /** HTTP status code returned by the Chronos API. */status: number; /** Application-level error code from the response envelope, when present. */
+  code?: string; /** Full parsed response payload (envelope + data, or whatever the server returned). */
+  body?: unknown; /** Value of the `X-Request-Id` response header, when present. Pair with server logs. */
+  requestId?: string;
+};
+/**
+ * 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 });
+ *   }
+ * }
+ * ```
+ */
+declare class ChronosApiError extends ChronosError {
+  /** HTTP status code returned by the Chronos API. */
+  readonly status: number;
+  /** Application-level error code from the response envelope, when present. */
+  readonly code?: string;
+  /** Full parsed response payload (envelope + data, or whatever the server returned). */
+  readonly body?: unknown;
+  /** Value of the `X-Request-Id` response header, when present. */
+  readonly requestId?: string;
+  constructor(message: string, options: ChronosApiErrorOptions);
+}
+/**
+ * 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 });
+ *   }
+ * }
+ * ```
+ */
+declare class ChronosNetworkError extends ChronosError {
+  /** Original error/value rejected by the underlying `fetch`. */
+  readonly cause: unknown;
+  constructor(message: string, options: {
+    cause: unknown;
+  });
+}
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare class ChronosHandlerError extends ChronosError {
+  /** Original error/value thrown by the user-supplied handler. */
+  readonly cause: unknown;
+  constructor(message: string, options: {
+    cause: unknown;
+  });
+}
+//#endregion
+//#region src/index.d.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();
+ * ```
+ */
+declare class Chronos {
+  /** Long-poll worker for executing pull-mode jobs. */
+  readonly worker: Worker;
+  /**
+   * @param options - Client configuration. Only `apiKey` is required.
+   * @throws {ChronosConfigError} If `apiKey` is missing or any option fails validation.
+   */
+  constructor(options: ChronosOptions);
+}
+//#endregion
+export { Chronos, ChronosApiError, type ChronosApiErrorOptions, ChronosConfigError, type ChronosContext, ChronosError, type ChronosHandler, ChronosHandlerError, type ChronosHandlerResult, type ChronosLogger, ChronosNetworkError, type ChronosOptions, type ChronosSchedule, DEFAULT_BASE_URL, DEFAULT_POLL_WAIT_TIME_SECONDS, type FetchLike };
+//# sourceMappingURL=index.d.ts.map