@cronvello/sdk 0.2.1 → 0.4.0

package/dist/index.js

@@ -543,8 +543,13 @@ function createDispatcher(state) {
     if (req.method.toUpperCase() !== "POST") {
       return resp(405, { ok: false, error: "Method not allowed" });
     }
+    const secret = state.dispatchSecret;
+    if (!secret) {
+      log.error?.("[cronvello] dispatch refused: no `dispatchSecret` configured on this app");
+      return resp(500, { ok: false, error: "Dispatch is not configured" });
+    }
     const token = parseBearer(req.authorization);
-    if (!token || !timingSafeEqual(token, state.dispatchSecret)) {
+    if (!token || !timingSafeEqual(token, secret)) {
       log.warn?.("[cronvello] dispatch rejected: bad or missing bearer token");
       return resp(401, { ok: false, error: "Unauthorized" });
     }
@@ -575,7 +580,7 @@ function createDispatcher(state) {
     const isAsync = callback !== null;
     const ctx = buildContext(key, job, req, body, isAsync, "dispatch");
     if (callback) {
-      const work = runAndReportCallback(job, ctx, callback, state.dispatchSecret, log, invokeHandler);
+      const work = runAndReportCallback(job, ctx, callback, secret, log, invokeHandler);
       if (req.waitUntil) req.waitUntil(work);
       return resp(202, { ok: true, job: key, accepted: true });
     }
@@ -1187,6 +1192,7 @@ var LocalEngine = class {
   started = false;
   stopped = false;
   signalCleanup = null;
+  startedAtMs = null;
   constructor(jobs, runner, options = {}) {
     this.clock = options.clock ?? realClock;
     if (options.onEvent) this.listeners.add(options.onEvent);
@@ -1235,7 +1241,8 @@ var LocalEngine = class {
     if (this.started) return this;
     this.started = true;
     this.stopped = false;
-    this.emit({ type: "engine-start", jobs: this.states.length, at: this.clock.now() });
+    this.startedAtMs = this.clock.now();
+    this.emit({ type: "engine-start", jobs: this.states.length, at: this.startedAtMs });
     for (const state of this.states) {
       if (state.isReboot) {
         this.launch(state);
@@ -1299,6 +1306,14 @@ var LocalEngine = class {
   get activeRuns() {
     return this.inFlight.size;
   }
+  /** Epoch ms of the `start()` call, or null while the engine has never been started. */
+  get startedAt() {
+    return this.startedAtMs;
+  }
+  /** True between `start()` and `stop()`. */
+  get running() {
+    return this.started && !this.stopped;
+  }
   // ── Scheduling ─────────────────────────────────────────────────────────────
   scheduleNext(state) {
     if (this.stopped) return;
@@ -1493,14 +1508,20 @@ function defineCronvello(config) {
   }
   const jobs = normalizeJobs(config.jobs, validate);
   const dispatchPath = normalizePath(config.dispatchPath ?? DEFAULT_DISPATCH_PATH);
-  const dispatchUrl = joinUrl(config.appUrl, dispatchPath);
-  const client = new CronvelloClient({
-    apiKey: config.apiKey,
-    baseUrl: config.baseUrl ?? CRONVELLO_DEFAULT_BASE_URL,
-    ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {},
-    ...config.maxRetries !== void 0 ? { maxRetries: config.maxRetries } : {},
-    ...config.fetch ? { fetch: config.fetch } : {}
-  });
+  let clientInstance;
+  const getClient = () => {
+    if (!clientInstance) {
+      requireCloud(config, ["apiKey"], "Talking to the Cronvello API");
+      clientInstance = new CronvelloClient({
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl ?? CRONVELLO_DEFAULT_BASE_URL,
+        ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {},
+        ...config.maxRetries !== void 0 ? { maxRetries: config.maxRetries } : {},
+        ...config.fetch ? { fetch: config.fetch } : {}
+      });
+    }
+    return clientInstance;
+  };
   const dispatcher = createDispatcher({
     jobs,
     dispatchSecret: config.dispatchSecret,
@@ -1509,17 +1530,29 @@ function defineCronvello(config) {
     ...config.maxBodyBytes !== void 0 ? { maxBodyBytes: config.maxBodyBytes } : {}
   });
   const app = {
-    client,
+    get client() {
+      return getClient();
+    },
     jobs,
     appName: config.appName,
     dispatchPath,
-    dispatchUrl,
+    get dispatchUrl() {
+      requireCloud(config, ["appUrl"], "Building the dispatch URL");
+      return joinUrl(config.appUrl, dispatchPath);
+    },
+    get isCloudConfigured() {
+      return missingCloudFields(config, CLOUD_FIELDS).length === 0;
+    },
     async sync(options) {
+      requireCloud(config, CLOUD_FIELDS, "Syncing your jobs to Cronvello");
+      const client = getClient();
+      const dispatchUrl = joinUrl(config.appUrl, dispatchPath);
+      const dispatchSecret = config.dispatchSecret;
       const opts = options ?? {};
       if (!opts.dryRun) {
         try {
           const res = await client.reconcileRegistry(
-            buildRegistryRequest(config, dispatchUrl, defaultTimeZone, [...jobs.values()], opts)
+            buildRegistryRequest(config, dispatchSecret, dispatchUrl, defaultTimeZone, [...jobs.values()], opts)
           );
           return {
             jobId: res.job.id,
@@ -1547,7 +1580,7 @@ function defineCronvello(config) {
           client,
           appName: config.appName,
           dispatchUrl,
-          dispatchSecret: config.dispatchSecret,
+          dispatchSecret,
           defaultTimeZone,
           jobs: [...jobs.values()]
         },
@@ -1558,6 +1591,7 @@ function defineCronvello(config) {
       if (!jobs.has(key)) {
         throw new CronvelloConfigError(`Unknown job '${key}'. Known: ${[...jobs.keys()].join(", ") || "(none)"}`);
       }
+      const client = getClient();
       const containers = await client.jobs.list();
       const container = containers.find((j) => j.name === config.appName);
       if (!container) {
@@ -1572,8 +1606,16 @@ function defineCronvello(config) {
     },
     trigger: (key, payload) => dispatcher.runLocal(key, payload),
     handle: dispatcher.handle,
-    expressHandler: () => expressHandler(app),
-    nextHandler: () => nextHandler(app),
+    // Mounting a dispatch route that could only ever answer "not configured" hides the real
+    // mistake behind a runtime 500, so both adapters fail at mount time instead.
+    expressHandler: () => {
+      requireCloud(config, ["dispatchSecret"], "Mounting the dispatch handler");
+      return expressHandler(app);
+    },
+    nextHandler: () => {
+      requireCloud(config, ["dispatchSecret"], "Mounting the dispatch handler");
+      return nextHandler(app);
+    },
     dev(options) {
       const { autoStart = true, dashboard, ...engineOptions } = options ?? {};
       const engineJobs = buildEngineJobs([...jobs.values()], defaultTimeZone);
@@ -1623,7 +1665,9 @@ function buildEngineJobs(jobs, defaultTimeZone) {
       !appUrl && "CRONVELLO_APP_URL (or PUBLIC_URL)"
     ].filter(Boolean);
     if (missing.length) {
-      throw new CronvelloConfigError(`defineCronvello.fromEnv() is missing required env: ${missing.join(", ")}.`);
+      throw new CronvelloConfigError(
+        `defineCronvello.fromEnv() is missing required env: ${missing.join(", ")}. To run locally with no account, use defineCronvello({ appName, jobs }) instead \u2014 it needs none of these.`
+      );
     }
     return defineCronvello2({
       ...config,
@@ -1635,17 +1679,32 @@ function buildEngineJobs(jobs, defaultTimeZone) {
   }
   defineCronvello2.fromEnv = fromEnv;
 })(defineCronvello || (defineCronvello = {}));
+var CLOUD_FIELDS = ["apiKey", "appUrl", "dispatchSecret"];
+var CLOUD_FIELD_HINT = {
+  apiKey: "`apiKey` (crn_live_\u2026, from your Cronvello account)",
+  appUrl: "`appUrl` (the public https URL of THIS app, where Cronvello delivers callbacks)",
+  dispatchSecret: "`dispatchSecret` (a random 32-byte value: run `npx cronvello secret`)"
+};
+function missingCloudFields(config, fields) {
+  return fields.filter((f) => !config[f]);
+}
+function requireCloud(config, fields, purpose) {
+  const missing = missingCloudFields(config, fields);
+  if (!missing.length) return;
+  throw new CronvelloConfigError(
+    `${purpose} needs config this app doesn't have: ${missing.map((f) => CLOUD_FIELD_HINT[f]).join(", ")}. Local runs (\`cronvello dev\`, \`trigger()\`) work without any of it.`
+  );
+}
 function validateConfig(config) {
   if (!config) throw new CronvelloConfigError("defineCronvello requires a config object.");
   if (!config.appName || !config.appName.trim()) throw new CronvelloConfigError("`appName` is required.");
-  if (!config.appUrl || !/^https?:\/\//i.test(config.appUrl)) {
+  if (!config.jobs) throw new CronvelloConfigError("`jobs` is required.");
+  if (config.appUrl !== void 0 && !/^https?:\/\//i.test(config.appUrl)) {
     throw new CronvelloConfigError("`appUrl` must be an absolute http(s) URL (the public URL of THIS app).");
   }
-  if (!config.apiKey) throw new CronvelloConfigError("`apiKey` (crn_live_\u2026) is required.");
-  if (!config.dispatchSecret || config.dispatchSecret.length < 16) {
-    throw new CronvelloConfigError("`dispatchSecret` is required and must be at least 16 chars (use a random 32-byte value).");
+  if (config.dispatchSecret !== void 0 && config.dispatchSecret.length < 16) {
+    throw new CronvelloConfigError("`dispatchSecret` must be at least 16 chars (use a random 32-byte value).");
   }
-  if (!config.jobs) throw new CronvelloConfigError("`jobs` is required.");
 }
 function normalizeJobs(input, validate) {
   const map = /* @__PURE__ */ new Map();
@@ -1682,14 +1741,14 @@ function normalizePath(path) {
 function joinUrl(base, path) {
   return `${base.replace(/\/+$/, "")}${path}`;
 }
-function buildRegistryRequest(config, dispatchUrl, defaultTimeZone, jobs, opts) {
+function buildRegistryRequest(config, dispatchSecret, dispatchUrl, defaultTimeZone, jobs, opts) {
   const tasks = jobs.map((j) => {
     const cfg = j.config;
     const task = {
       key: j.key,
       schedule: cfg.schedule,
       targetUrl: dispatchUrl,
-      targetToken: config.dispatchSecret,
+      targetToken: dispatchSecret,
       method: "POST",
       timeZone: cfg.timeZone ?? defaultTimeZone,
       requestBody: JSON.stringify({ job: j.key, ...cfg.payload ?? {} })
@@ -1855,6 +1914,112 @@ function field(value, min, max, label) {
   return value;
 }
 
+// src/client/admin-client.ts
+var CronvelloAdminClient = class {
+  transport;
+  /** The resolved base URL in use. */
+  baseUrl;
+  /** Registration, status, key rotation and removal of external apps. */
+  externalApps;
+  constructor(options) {
+    if (!options || !options.serviceKey) {
+      throw new CronvelloConfigError(
+        "CronvelloAdminClient requires a `serviceKey` (Cronvello's backend-to-backend key, not an account apiKey)."
+      );
+    }
+    this.baseUrl = (options.baseUrl ?? CRONVELLO_DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.transport = new Transport({
+      baseUrl: this.baseUrl,
+      apiKey: options.serviceKey,
+      ...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {},
+      ...options.maxRetries !== void 0 ? { maxRetries: options.maxRetries } : {},
+      ...options.fetch ? { fetch: options.fetch } : {},
+      ...options.onRequest ? { onRequest: options.onRequest } : {}
+    });
+    this.externalApps = new ExternalAppsResource(this.transport);
+  }
+};
+var ExternalAppsResource = class {
+  constructor(t) {
+    this.t = t;
+  }
+  t;
+  /**
+   * 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) {
+    assertRegisterInput(input);
+    return this.t.request({ method: "POST", path: "/external-apps/service/register", body: input });
+  }
+  /** Registration status, last-sync info and job count for one app, by its string `appId`. */
+  status(appId) {
+    assertAppId(appId, "status");
+    return this.t.request({ method: "GET", path: `/external-apps/service/status/${enc2(appId)}` });
+  }
+  /**
+   * 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) {
+    assertAppId(appId, "rotateKey");
+    return this.t.request({ method: "POST", path: `/external-apps/service/rotate-key/${enc2(appId)}` });
+  }
+  /**
+   * 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) {
+    if (!Number.isInteger(id) || id <= 0) {
+      throw new CronvelloConfigError(
+        `externalApps.delete() takes the numeric app id (ExternalApp.id), not the string appId \u2014 received ${JSON.stringify(id)}.`
+      );
+    }
+    return this.t.request({ method: "DELETE", path: `/external-apps/service/delete/${id}` });
+  }
+};
+function assertRegisterInput(input) {
+  if (!input || typeof input !== "object") {
+    throw new CronvelloConfigError("externalApps.register() requires an input object.");
+  }
+  if (!input.appId || !input.appId.trim()) {
+    throw new CronvelloConfigError("externalApps.register() requires a non-empty `appId`.");
+  }
+  if (!input.name || !input.name.trim()) {
+    throw new CronvelloConfigError("externalApps.register() requires a non-empty `name`.");
+  }
+  if (!input.base_url && input.targetUrl === void 0) {
+    throw new CronvelloConfigError("externalApps.register() requires either `base_url` or `targetUrl`.");
+  }
+  const authMethod = input.authMethod ?? (input.oauthClientId || input.oauthClientSecret ? "oauth" : "api_key");
+  if (authMethod === "api_key" && !input.apiKey && !input.generateApiKey) {
+    throw new CronvelloConfigError(
+      "externalApps.register() with api_key auth requires either `apiKey` or `generateApiKey: true`."
+    );
+  }
+  if (authMethod === "oauth" && (!input.oauthClientId || !input.oauthClientSecret)) {
+    throw new CronvelloConfigError(
+      "externalApps.register() with oauth auth requires both `oauthClientId` and `oauthClientSecret`."
+    );
+  }
+}
+function assertAppId(appId, method) {
+  if (typeof appId !== "string" || !appId.trim()) {
+    throw new CronvelloConfigError(`externalApps.${method}() requires a non-empty string appId.`);
+  }
+}
+function enc2(segment) {
+  return encodeURIComponent(segment);
+}
+
 // src/index.ts
 function generateDispatchSecret(bytes = 32) {
   const buf = new Uint8Array(bytes);
@@ -1862,6 +2027,6 @@ function generateDispatchSecret(bytes = 32) {
   return Array.from(buf).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
-export { CRONVELLO_DEFAULT_BASE_URL, CronvelloApiError, CronvelloClient, CronvelloConfigError, CronvelloError, CronvelloNetworkError, cron, daily, defineCronvello, every, everyHours, everyMinutes, formatSyncResult, generateDispatchSecret, hourly, isValidTimeZone, monthly, nextOccurrence, previewSchedule, schedule, validateCron, weekdays, weekends, weekly };
+export { CRONVELLO_DEFAULT_BASE_URL, CronvelloAdminClient, CronvelloApiError, CronvelloClient, CronvelloConfigError, CronvelloError, CronvelloNetworkError, cron, daily, defineCronvello, every, everyHours, everyMinutes, formatSyncResult, generateDispatchSecret, hourly, isValidTimeZone, monthly, nextOccurrence, previewSchedule, schedule, validateCron, weekdays, weekends, weekly };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map