@cronvello/sdk 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { T as Transport, P as PublicJob, J as JobCreateBody, a as JobUpdateBody, b as PublicTask, c as TaskCreateBody, A as AccountTasksQuery, d as TasksPage, e as TaskUpdateBody, R as RunNowResult, f as RunsQuery, g as RunsPage, h as AccountRunsQuery, i as PublicRun, M as MeResponse, U as UsageResponse, F as FetchLike, j as RegistryReconcileRequest, k as RegistryReconcileResponse, l as ResolvedJob, S as SyncOptions, m as ReconcileResult, D as DispatchRequest, n as DispatchResponse, C as CronvelloAppConfig } from './dispatch-handler-BoadpsL9.js';
-export { o as CallbackStatus, p as CronvelloHooks, q as CronvelloJobConfig, r as CronvelloJobConfigWithKey, s as CronvelloJobContext, t as CronvelloJobHandler, u as CronvelloJobsInput, v as CronvelloLogger, w as CronvelloRunSource, E as ExecutionMode, H as HttpMethod, x as JobStatus, y as Pagination, z as ReconcileTaskChange, B as RegistryReconcileChange, G as RegistryTaskInput, I as RunStatus, K as RunType, L as SuccessCriteria, N as Urgency } from './dispatch-handler-BoadpsL9.js';
+import { T as Transport, P as PublicJob, J as JobCreateBody, a as JobUpdateBody, b as PublicTask, c as TaskCreateBody, A as AccountTasksQuery, d as TasksPage, e as TaskUpdateBody, R as RunNowResult, f as RunsQuery, g as RunsPage, h as AccountRunsQuery, i as PublicRun, M as MeResponse, U as UsageResponse, F as FetchLike, j as RegistryReconcileRequest, k as RegistryReconcileResponse, l as ResolvedJob, S as SyncOptions, m as ReconcileResult, D as DispatchRequest, n as DispatchResponse, C as CronvelloAppConfig, o as Urgency } from './dispatch-handler-yHIFEnNG.js';
+export { p as CallbackStatus, q as CronvelloHooks, r as CronvelloJobConfig, s as CronvelloJobConfigWithKey, t as CronvelloJobContext, u as CronvelloJobHandler, v as CronvelloJobsInput, w as CronvelloLogger, x as CronvelloRunSource, E as ExecutionMode, H as HttpMethod, y as JobStatus, z as Pagination, B as ReconcileTaskChange, G as RegistryReconcileChange, I as RegistryTaskInput, K as RunStatus, L as RunType, N as SuccessCriteria } from './dispatch-handler-yHIFEnNG.js';
 import { ExpressDispatchHandler } from './express.js';
 import { NextRouteHandler } from './next.js';
 import { LocalEngineOptions, DashboardOptions, LocalEngine } from './dev.js';
@@ -115,23 +115,40 @@ declare class AccountResource {
 /**
  * `defineCronvello` — the high-level, code-first entry point.
  *
+ * Jobs alone are enough. This runs on your machine with no account and no network:
+ *
  *   export const cronvello = defineCronvello({
  *     appName: "my-app",
- *     appUrl: process.env.APP_URL!,
- *     apiKey: process.env.CRONVELLO_API_KEY!,
- *     dispatchSecret: process.env.CRONVELLO_DISPATCH_SECRET!,
  *     jobs: {
  *       "send-daily-digest": { schedule: "0 8 * * *", handler: async () => { … } },
  *       "cleanup-temp":      { schedule: "*\/15 * * * *", handler: async () => { … } },
  *     },
  *   });
  *
+ *   npx cronvello dev                       // real scheduler, locally
+ *   await cronvello.trigger("cleanup-temp") // run one handler now
+ *
+ * Add the hosted side later, when you want run history, alerts on missed runs and replay.
+ * `apiKey`, `appUrl` and `dispatchSecret` are needed only from that point on, and only the
+ * calls that use them complain if they're absent:
+ *
+ *   export const cronvello = defineCronvello({
+ *     appName: "my-app",
+ *     appUrl: process.env.APP_URL!,
+ *     apiKey: process.env.CRONVELLO_API_KEY!,
+ *     dispatchSecret: process.env.CRONVELLO_DISPATCH_SECRET!,
+ *     jobs: { … },
+ *   });
+ *
  *   await cronvello.sync();                 // reconcile the registry to Cronvello (idempotent)
  *   app.post(cronvello.dispatchPath, express.json(), cronvello.expressHandler());
  */
 
 interface CronvelloApp {
-    /** The underlying low-level client for ad-hoc `/v1` calls. */
+    /**
+     * The underlying low-level client for ad-hoc `/v1` calls. Built on first access — reading it
+     * on an app configured without an `apiKey` throws {@link CronvelloConfigError}.
+     */
     readonly client: CronvelloClient;
     /** Resolved jobs, keyed by their stable registry key. */
     readonly jobs: ReadonlyMap<string, ResolvedJob>;
@@ -139,8 +156,13 @@ interface CronvelloApp {
     readonly appName: string;
     /** Path the dispatch handler should be mounted at (e.g. "/cronvello/dispatch"). */
     readonly dispatchPath: string;
-    /** Absolute URL Cronvello calls back (appUrl + dispatchPath). */
+    /**
+     * Absolute URL Cronvello calls back (appUrl + dispatchPath). Reading it on an app configured
+     * without an `appUrl` throws {@link CronvelloConfigError} — a local-only app is never called back.
+     */
     readonly dispatchUrl: string;
+    /** True when this app has everything the hosted side needs (`apiKey`, `appUrl`, `dispatchSecret`). */
+    readonly isCloudConfigured: boolean;
     /** Reconcile the registry into Cronvello. Idempotent — safe to call on every boot/deploy. */
     sync(options?: SyncOptions): Promise<ReconcileResult>;
     /** Trigger one job immediately via Cronvello (manual run). Requires a prior `sync()`. */
@@ -180,8 +202,8 @@ interface DevOptions extends LocalEngineOptions {
      */
     dashboard?: boolean | DashboardOptions;
 }
-/** Config for `defineCronvello.fromEnv` — the three secret fields become optional (read from env). */
-type CronvelloEnvConfig = Omit<CronvelloAppConfig, "apiKey" | "dispatchSecret" | "appUrl"> & Partial<Pick<CronvelloAppConfig, "apiKey" | "dispatchSecret" | "appUrl">>;
+/** Config for `defineCronvello.fromEnv` — the three hosted-side fields are read from the environment. */
+type CronvelloEnvConfig = CronvelloAppConfig;
 declare function defineCronvello(config: CronvelloAppConfig): CronvelloApp;
 declare namespace defineCronvello {
     /**
@@ -282,6 +304,251 @@ declare function validateCron(expr: string): CronValidation;
 /** True if `tz` is a valid IANA timezone (uses the runtime's Intl database). "UTC" always passes. */
 declare function isValidTimeZone(tz: string): boolean;
 
+/**
+ * Wire types for Cronvello's operator ("service") API — `/external-apps/service/*`.
+ *
+ * This is NOT the per-account `/v1` API. It is the backend-to-backend control plane that
+ * registers, inspects, re-keys and removes the *external apps* Cronvello schedules jobs for.
+ * It lives on the same host as `/v1` but behind a different credential — see
+ * {@link ../client/admin-client.js CronvelloAdminClient}.
+ *
+ * Hand-authored plain TypeScript (mirroring the server's Zod DTOs and route contracts) so the
+ * SDK keeps ZERO runtime dependencies. When the server contract changes, update these to match.
+ */
+
+/** How Cronvello authenticates itself towards a registered external app. */
+type ExternalAppAuthMethod = "api_key" | "oauth";
+/**
+ * Why the hourly catalog poll was retired for a registration.
+ *
+ * - `self_managed` — the app drives its own tasks through `@cronvello/sdk`; polling would delete them.
+ * - `catalog_gone` — the job-catalog route 404s.
+ * - `auth_rejected` — the catalog route rejected our credentials over a sustained period.
+ *
+ * Widened to `string` so a newly introduced server-side reason does not break the type.
+ */
+type CatalogRetiredReason = "self_managed" | "catalog_gone" | "auth_rejected" | (string & {});
+/**
+ * A registered external app as the server returns it.
+ *
+ * Secrets are never returned in plaintext: `apiKey` and `oauthClientSecret` are always `null`,
+ * with masked previews alongside them. The one-time plaintext token appears only in
+ * {@link ExternalAppRegisterResult.generatedApiKey} and {@link ExternalAppRotateKeyResult.newApiKey}.
+ *
+ * Timestamps arrive as JSON strings.
+ */
+interface ExternalApp {
+    /** Numeric primary key. This — not {@link appId} — is what `externalApps.delete()` takes. */
+    id: number;
+    /** Caller-chosen stable string identifier, e.g. `"node-shop"`. Unique. */
+    appId: string;
+    name: string;
+    description: string | null;
+    /** Always `null`; the plaintext key is never echoed back. See {@link apiKeyMasked}. */
+    apiKey: null;
+    apiKeyMasked: string | null;
+    hasApiKey: boolean;
+    oauthClientId: string | null;
+    /** Always `null`. See {@link oauthClientSecretMasked}. */
+    oauthClientSecret: null;
+    oauthClientSecretMasked: string | null;
+    hasOAuthClientSecret: boolean;
+    authMethod: ExternalAppAuthMethod;
+    /** Base URL Cronvello calls back on. Snake_case on the wire — the server's column name. */
+    base_url: string;
+    createdAt: string;
+    isActive: boolean;
+    /** Maintained by the server's liveness monitor; not something a caller sets directly. */
+    isLive: boolean;
+    /** FK into the server's job-target-url table. */
+    targetUrl: number;
+    /** Path under `base_url` that serves the app's job catalog. Server default: `/cron-jobs`. */
+    jobRoutePath: string | null;
+    urgency: Urgency;
+    lastSyncedAt: string | null;
+    lastHealthCheckAt: string | null;
+    lastHealthCheckMs: number | null;
+    totalJobCount: number | null;
+    activeJobCount: number | null;
+    livenessMonitoringEnabled: boolean;
+    consecutiveUnreachableCount: number;
+    consecutiveSyncFailureCount: number;
+    lastSyncFailureAt: string | null;
+    lastSyncError: string | null;
+    catalogRetiredAt: string | null;
+    catalogRetiredReason: CatalogRetiredReason | null;
+    webhookCallbackEnabled: boolean;
+    /** Stored encrypted at rest; the server does not mask this field. */
+    webhookCallbackSecret: string | null;
+    webhookCallbackTimeoutMs: number | null;
+    /** `null` for system/B2B apps owned internally rather than by an account. */
+    accountId: number | null;
+}
+/**
+ * Body of `POST /external-apps/service/register`.
+ *
+ * The server validates this strictly — unknown properties are rejected. Cross-field rules
+ * (also checked client-side before the request leaves, so you get a `CronvelloConfigError`
+ * instead of an opaque 400):
+ *
+ * - exactly one of `base_url` or `targetUrl` must be present (at least one);
+ * - with `authMethod: "api_key"` (the default) you must supply either `apiKey` or `generateApiKey: true`;
+ * - with `authMethod: "oauth"` both `oauthClientId` and `oauthClientSecret` are required.
+ */
+interface ExternalAppRegisterInput {
+    /** Stable string identifier. Existing value ⇒ update; new value ⇒ create. */
+    appId: string;
+    name: string;
+    description?: string | null;
+    /** Bring your own per-app token. Mutually exclusive with `generateApiKey`. */
+    apiKey?: string;
+    /**
+     * Let Cronvello mint the per-app token. It comes back exactly once as
+     * {@link ExternalAppRegisterResult.generatedApiKey} — persist it there and then, or rotate.
+     */
+    generateApiKey?: boolean;
+    base_url?: string;
+    /** Existing job-target-url id, as an alternative to `base_url`. */
+    targetUrl?: number;
+    /** Defaults to `/cron-jobs` server-side when omitted. */
+    jobRoutePath?: string;
+    authMethod?: ExternalAppAuthMethod;
+    oauthClientId?: string;
+    oauthClientSecret?: string;
+    /** Defaults to `true` server-side when omitted. */
+    isActive?: boolean;
+    webhookCallbackEnabled?: boolean;
+    /** Required by the server when `webhookCallbackEnabled` is true. Minimum 32 characters. */
+    webhookCallbackSecret?: string;
+    /** Server-enforced range: 10_000 – 3_600_000 ms. */
+    webhookCallbackTimeoutMs?: number;
+}
+/**
+ * Result of a register (upsert) call.
+ *
+ * `generatedApiKey` carries the plaintext token **once**, and only when the server minted it
+ * for a newly created app via `generateApiKey`. On an update, or when you supplied your own
+ * `apiKey`, it is `null`. There is no second chance to read it — use `rotateKey()` if it is lost.
+ */
+interface ExternalAppRegisterResult extends ExternalApp {
+    generatedApiKey: string | null;
+}
+/** Result of a key rotation. `newApiKey` is plaintext and returned exactly once. */
+interface ExternalAppRotateKeyResult extends ExternalApp {
+    newApiKey: string;
+}
+/** Registration status for one app, keyed by its string `appId`. */
+interface ExternalAppStatus {
+    /** `false` when no app with that `appId` exists; every other field is then at its zero value. */
+    registered: boolean;
+    isActive: boolean;
+    lastSyncedAt: string | null;
+    isLive: boolean;
+    jobCount: number;
+}
+
+/**
+ * Operator-side client for Cronvello's backend-to-backend API (`/external-apps/service/*`).
+ *
+ * ## Why this is a separate class from {@link CronvelloClient}
+ *
+ * Both surfaces live on the same host and share the same transport, `{ success, message, data }`
+ * envelope and `Authorization: Bearer` scheme — but they take **different credentials**:
+ *
+ * | Surface                    | Credential                          | Scope                       |
+ * | -------------------------- | ----------------------------------- | --------------------------- |
+ * | `/v1/*`                    | per-account API key (`crn_live_…`)  | one account's jobs and runs |
+ * | `/external-apps/service/*` | Cronvello's service key             | every registered app        |
+ *
+ * The service key is far broader than an account key. Folding both into one object would make it
+ * easy to send the wrong one — or to leak the service key onto an account-scoped call. Keeping
+ * them in two objects, with two differently named options (`apiKey` vs `serviceKey`), makes that
+ * mistake impossible to express.
+ *
+ * Nothing here is needed to *use* Cronvello. It is for the service that provisions apps into it.
+ */
+
+interface CronvelloAdminClientOptions {
+    /**
+     * Cronvello's backend-to-backend service key. Required.
+     *
+     * This is **not** an account API key — it authorizes operations across every registered app.
+     * Keep it server-side only.
+     */
+    serviceKey: string;
+    /** API base URL. Defaults to https://api.cronvello.com. */
+    baseUrl?: string;
+    /** Per-request timeout in ms (default 30_000). */
+    timeoutMs?: number;
+    /** Retry attempts for 429/5xx/network errors (default 2). */
+    maxRetries?: number;
+    /** Custom fetch implementation (default: global fetch). */
+    fetch?: FetchLike;
+    /** Telemetry hook for every request attempt. */
+    onRequest?: (info: {
+        method: string;
+        path: string;
+        status: number;
+        attempt: number;
+        durationMs: number;
+    }) => void;
+}
+/**
+ * Operator access to Cronvello's app registry.
+ *
+ * ```ts
+ * const admin = new CronvelloAdminClient({ serviceKey: process.env.CRONVELLO_SERVICE_KEY! });
+ * const app = await admin.externalApps.register({
+ *   appId: "node-shop",
+ *   name: "Shop",
+ *   base_url: "https://shop.example.com",
+ *   generateApiKey: true,
+ * });
+ * // app.generatedApiKey is plaintext and shown exactly once.
+ * ```
+ *
+ * Errors follow the rest of the SDK: `CronvelloConfigError` for anything caught before the
+ * request leaves, `CronvelloApiError` for a non-2xx response, `CronvelloNetworkError` for a
+ * transport failure.
+ */
+declare class CronvelloAdminClient {
+    private readonly transport;
+    /** The resolved base URL in use. */
+    readonly baseUrl: string;
+    /** Registration, status, key rotation and removal of external apps. */
+    readonly externalApps: ExternalAppsResource;
+    constructor(options: CronvelloAdminClientOptions);
+}
+declare class ExternalAppsResource {
+    private readonly t;
+    constructor(t: Transport);
+    /**
+     * Idempotent upsert, keyed on the string `appId`: creates when unknown, updates credentials
+     * and URL when it already exists. Safe to retry and to re-run on every provisioning pass.
+     *
+     * When the server mints the token (`generateApiKey: true` on a *new* app) it comes back as
+     * `generatedApiKey` — plaintext, exactly once. On an update it is `null`.
+     */
+    register(input: ExternalAppRegisterInput): Promise<ExternalAppRegisterResult>;
+    /** Registration status, last-sync info and job count for one app, by its string `appId`. */
+    status(appId: string): Promise<ExternalAppStatus>;
+    /**
+     * Mint a fresh per-app token, by string `appId`. The new token is returned once as `newApiKey`
+     * and must be written into the app's environment — the previous one stops working.
+     *
+     * Use this for drift recovery when the current token is no longer known.
+     */
+    rotateKey(appId: string): Promise<ExternalAppRotateKeyResult>;
+    /**
+     * Delete a registration, cascading its jobs and tasks.
+     *
+     * ⚠ This one takes the **numeric** {@link ExternalApp.id}, not the string `appId` the other
+     * three methods take — an asymmetry in the server's route contract. Read the id off a
+     * `register()` result (or a prior lookup); passing a string `appId` here is rejected locally.
+     */
+    delete(id: number): Promise<void>;
+}
+
 /**
  * Error taxonomy for the SDK. Everything thrown by the public surface is a
  * `CronvelloError` (or subclass), so callers can `catch (e) { if (e instanceof CronvelloError) … }`.
@@ -331,6 +598,9 @@ declare class CronvelloConfigError extends CronvelloError {
  *   • High-level registry: `defineCronvello({ jobs })` → `.sync()` + `.expressHandler()` / `.nextHandler()`.
  *     Define jobs in code; the SDK reconciles them to https://api.cronvello.com and runs them.
  *   • Low-level client: `new CronvelloClient({ apiKey })` → typed access to the whole `/v1` API.
+ *
+ * Plus an operator surface, `new CronvelloAdminClient({ serviceKey })`, for the service that
+ * registers apps into Cronvello. Separate class, separate credential — see its doc comment.
  */
 
 /**
@@ -339,4 +609,4 @@ declare class CronvelloConfigError extends CronvelloError {
  */
 declare function generateDispatchSecret(bytes?: number): string;
 
-export { AccountRunsQuery, AccountTasksQuery, CRONVELLO_DEFAULT_BASE_URL, type CronValidation, CronvelloApiError, type CronvelloApp, CronvelloAppConfig, CronvelloClient, type CronvelloClientOptions, CronvelloConfigError, type CronvelloEnvConfig, CronvelloError, CronvelloNetworkError, DispatchRequest, DispatchResponse, type FormatOptions, JobCreateBody, JobUpdateBody, MeResponse, PublicJob, PublicRun, PublicTask, ReconcileResult, RegistryReconcileRequest, RegistryReconcileResponse, RunNowResult, RunsPage, RunsQuery, SyncOptions, TaskCreateBody, TaskUpdateBody, TasksPage, UsageResponse, type Weekday, cron, daily, defineCronvello, every, everyHours, everyMinutes, formatSyncResult, generateDispatchSecret, hourly, isValidTimeZone, monthly, schedule, validateCron, weekdays, weekends, weekly };
+export { AccountRunsQuery, AccountTasksQuery, CRONVELLO_DEFAULT_BASE_URL, type CatalogRetiredReason, type CronValidation, CronvelloAdminClient, type CronvelloAdminClientOptions, CronvelloApiError, type CronvelloApp, CronvelloAppConfig, CronvelloClient, type CronvelloClientOptions, CronvelloConfigError, type CronvelloEnvConfig, CronvelloError, CronvelloNetworkError, DispatchRequest, DispatchResponse, type ExternalApp, type ExternalAppAuthMethod, type ExternalAppRegisterInput, type ExternalAppRegisterResult, type ExternalAppRotateKeyResult, type ExternalAppStatus, type FormatOptions, JobCreateBody, JobUpdateBody, MeResponse, PublicJob, PublicRun, PublicTask, ReconcileResult, RegistryReconcileRequest, RegistryReconcileResponse, RunNowResult, RunsPage, RunsQuery, SyncOptions, TaskCreateBody, TaskUpdateBody, TasksPage, Urgency, UsageResponse, type Weekday, cron, daily, defineCronvello, every, everyHours, everyMinutes, formatSyncResult, generateDispatchSecret, hourly, isValidTimeZone, monthly, schedule, validateCron, weekdays, weekends, weekly };