@pylonsync/sdk 0.3.287 → 0.3.289

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.287",
+  "version": "0.3.289",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -650,6 +650,21 @@ export interface ManifestPolicy {
 
 export const MANIFEST_VERSION = 1;
 
+/** A recurring job: run a function on a cron schedule. Declared in the
+ *  manifest via `cron(schedule, functionName)`; the runtime fires the named
+ *  function with anonymous auth every time the schedule matches. Server-side
+ *  `ctx.db.*` is trusted, so a maintenance handler reads/writes its entities
+ *  directly without elevating. */
+export interface ManifestCron {
+  /** Standard 5-field cron expression, e.g. `"0 * * * *"` (every hour). */
+  schedule: string;
+  /** Name of the function (query/mutation/action) to run. Should be an
+   *  `internal: true` function so it isn't also reachable over HTTP. */
+  function: string;
+  /** Optional human description, surfaced by `pylon status` / tooling. */
+  description?: string;
+}
+
 export interface AppManifest {
   manifest_version: number;
   name: string;
@@ -665,6 +680,49 @@ export interface AppManifest {
   /** Declared OAuth integrations. Auto-creates the `_Connection`
    *  entity at runtime boot. */
   connections?: ManifestConnection[];
+  /** Recurring jobs — run a function on a cron schedule. */
+  crons?: ManifestCron[];
+}
+
+/**
+ * Declare a recurring job. Runs the named function every time the cron
+ * `schedule` matches (the runtime checks once a minute).
+ *
+ * ```ts
+ * buildManifest({
+ *   // ...
+ *   crons: [
+ *     cron("0 * * * *", "hourlyRollup"),     // every hour, on the hour
+ *     cron("15 3 * * *", "nightlyCleanup"),   // daily at 03:15
+ *   ],
+ * });
+ * ```
+ *
+ * `functionName` is a function in `functions/` — make it `internal: true`
+ * so it isn't also exposed over HTTP. It runs with anonymous auth, and a
+ * function's own `ctx.db.*` calls are server-side (not policy-gated), so a
+ * maintenance handler writes directly. Only call
+ * `ctx.auth.elevate({ admin: true, reason: "..." })` if it chains an
+ * `internal: true` function via `ctx.scheduler`, or you run with
+ * `PYLON_STRICT_FN_POLICIES=1`. The `reason` is mandatory (audited).
+ *
+ * Multiple replicas: each Pylon process runs its own scheduler. On a SHARED
+ * datastore (Postgres — the cloud default), the runtime takes a per-minute
+ * lease so each cron fires exactly ONCE per tick across all replicas. On
+ * per-replica SQLite there's no shared lease, so each replica fires — keep
+ * handlers idempotent there (most maintenance work naturally is). A
+ * single-machine app always fires exactly once.
+ */
+export function cron(
+  schedule: string,
+  functionName: string,
+  opts?: { description?: string }
+): ManifestCron {
+  return {
+    schedule,
+    function: functionName,
+    ...(opts?.description ? { description: opts.description } : {}),
+  };
 }
 
 export function entitiesToManifest(
@@ -1352,6 +1410,7 @@ export function buildManifest(options: {
   auth?: ManifestAuthConfig;
   llm?: ManifestLlmConfig;
   connections?: ManifestConnection[];
+  crons?: ManifestCron[];
 }): AppManifest {
   // Pull policies attached via the fluent `e.entity().policies(...)`
   // chain onto the top-level policies list. Without this, fluent
@@ -1396,6 +1455,9 @@ export function buildManifest(options: {
     ...(options.connections && options.connections.length > 0
       ? { connections: options.connections }
       : {}),
+    ...(options.crons && options.crons.length > 0
+      ? { crons: options.crons }
+      : {}),
   };
 }