@chronos.sh/sdk 0.0.1

package/dist/index.cjs.map

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

package/dist/index.d.cts

@@ -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.cts.map