@plitzi/sdk-shared 0.37.0 → 0.37.2

package/dist/theme/ThemeProvider.d.ts

@@ -38,5 +38,5 @@ export type ThemeProviderProps = {
  * updating the moment the visitor changes their system setting, which is how a panel ends up dark inside a page
  * that is still light.
  */
-declare const ThemeProvider: ({ defaultTheme, theme, scope, cookieName, children }: ThemeProviderProps) => import("react").JSX.Element;
+declare const ThemeProvider: ({ defaultTheme, theme, scope, cookieName, children }: ThemeProviderProps) => import('react').JSX.Element;
 export default ThemeProvider;

package/dist/types/ActionTypes.d.ts

@@ -495,3 +495,192 @@ export type ActionStreamFrame = {
     event: 'error';
     data: ActionCallError;
 };
+/**
+ * Where a job is, as the only durable answer to "did it happen".
+ *
+ * `pending` is waiting to be taken, `running` is held by a worker under a lease, and the other four are terminal —
+ * except that an operator may put a `failed`, `dead` or `cancelled` one back to `pending`. `dead` is a job that
+ * used up every attempt it was given: it stays, visibly, because the alternative is work that quietly evaporated.
+ */
+export type ActionJobStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'dead' | 'cancelled';
+/**
+ * One go at a job, kept forever on the job itself.
+ *
+ * `lost` is the attempt nobody reported: a worker took the job, its lease ran out, and another worker found it
+ * abandoned. It is the record of a replica that died mid-run, which is otherwise the one failure that leaves no
+ * trace anywhere — and the reason this list exists rather than a single `error` field.
+ */
+export type ActionJobAttempt = {
+    attempt: number;
+    status: 'succeeded' | 'failed' | 'cancelled' | 'lost';
+    /** Epoch ms, from the QUEUE's clock — never a worker's own. */
+    startedAt: number;
+    endedAt: number;
+    /** Which worker held it, so a bad replica is identifiable from the history alone. */
+    workerId: string;
+    /** The run this attempt became, when it got far enough to be one. Joins to the run history. */
+    runId?: string;
+    error?: string;
+};
+/** What starting a job needs. Everything else is the queue's to fill in. */
+export type ActionJobInput = {
+    /**
+     * The job's identity, and the whole of its exactly-once guarantee.
+     *
+     * A schedule derives it from the fire it belongs to — `schedule:<space>:<action>:<instant>` — so two replicas
+     * reaching the same fire write the same id and the second one is a no-op. Enqueue is idempotent by this, which
+     * is what lets a producer crash between enqueuing and recording that it did.
+     */
+    id: string;
+    spaceId: number;
+    actionId: string;
+    environment: Environment;
+    trigger: ActionTriggerType;
+    input: Record<string, unknown>;
+    /** The instant this job was due, as the schedule stored it. Epoch ms. */
+    dueAt: number;
+    maxAttempts: number;
+    /** Fires that went by unclaimed before this one. Shown to an operator; never acted on. */
+    missed?: number;
+};
+/** One unit of work the queue is holding, as an operator sees it. */
+export type ActionJob = ActionJobInput & {
+    status: ActionJobStatus;
+    /** Epoch ms before which no worker may take it — a retry's backoff, or the moment it was enqueued. */
+    runAt: number;
+    attempts: number;
+    /** While `running`: the instant the holder's claim lapses and another worker may take it over. */
+    leaseUntil?: number;
+    workerId?: string;
+    runId?: string;
+    /** Set by an operator who wants it stopped; the worker holding it reads this and aborts. */
+    cancelRequested?: boolean;
+    createdAt: number;
+    updatedAt: number;
+    /** Why the last attempt ended badly. */
+    error?: string;
+    history: ActionJobAttempt[];
+};
+/**
+ * How a worker reports what became of a claim.
+ *
+ * `delayMs` rather than an instant, and no timestamps: every moment the queue records is read from the QUEUE's
+ * clock, because a cluster whose nodes sit in different countries agrees about durations and not about now.
+ */
+export type ActionJobSettlement = {
+    jobId: string;
+    workerId: string;
+    status: Extract<ActionJobStatus, 'succeeded' | 'failed' | 'dead' | 'cancelled' | 'pending'>;
+    /** For a retry: how long from now before it may be claimed again. */
+    delayMs?: number;
+    runId?: string;
+    error?: string;
+    /** The attempt to append to the history. Omitted only when the claim is being handed back untouched. */
+    attempt?: Omit<ActionJobAttempt, 'attempt' | 'startedAt' | 'endedAt'>;
+};
+export type ActionJobQuery = {
+    spaceIds: number[];
+    actionId?: string;
+    status?: ActionJobStatus;
+    limit: number;
+    offset: number;
+};
+/**
+ * A recurring intent, as a row rather than as a timer.
+ *
+ * `nextRunAt` is the point of the whole design: the instant of the next fire is DECIDED ONCE and written down, so
+ * every replica afterwards reads the same number instead of asking its own clock whether the moment has come. Two
+ * nodes whose clocks differ by a minute then produce the same fires, in the same order, exactly once each — the
+ * disagreement moves the WHEN by their skew and can never move the WHETHER.
+ */
+export type ActionSchedule = {
+    spaceId: number;
+    actionId: string;
+    cron: string;
+    timezone?: string;
+    environment: Environment;
+    enabled: boolean;
+    /** Epoch ms of the next fire this schedule owes. The queue's clock decides when that has arrived. */
+    nextRunAt: number;
+    /** The last fire actually enqueued. */
+    lastFireAt?: number;
+    /** Fires that went by while nothing was running to take them. Cumulative, and shown to an operator. */
+    missed: number;
+    maxAttempts: number;
+    updatedAt: number;
+};
+/** A schedule as it is derived from an action document — everything the queue does not own itself. */
+export type ActionScheduleInput = Omit<ActionSchedule, 'missed' | 'updatedAt' | 'lastFireAt'>;
+/**
+ * Where a deployment keeps its jobs and schedules.
+ *
+ * The same kind of seam as {@link ActionKvAdapter} and for the same reason — the server never learns where a
+ * deployment stores anything — but with one rule this one cannot be written without, and it is written here so no
+ * deployment has to rediscover it:
+ *
+ * **Every instant comes from the store.** `now` is the cluster's clock, and every comparison the queue makes
+ * internally — is this schedule due, has this lease lapsed, may this retry be claimed — is made against it, never
+ * against the caller's. That is why `settle` takes a `delayMs` and not a deadline, and why `claim` takes a
+ * `leaseMs` and not a `leaseUntil`: durations survive a cluster spread across time zones and machines whose clocks
+ * drift, and absolute instants minted by a caller do not.
+ *
+ * **`enqueue` is idempotent by `id`,** and answers whether it was the one that created the job. That, and nothing
+ * else, is what makes a fire happen exactly once when several replicas are racing to produce it.
+ *
+ * **`claim` is atomic, and it also reaps.** A job whose lease has lapsed is a job whose worker died, and it is
+ * taken by whoever claims next — the same operation, because a separate reaper is a second thing to deploy, to
+ * schedule and to forget.
+ */
+export type ActionJobQueue = {
+    /** The cluster's clock. The only clock anything in the scheduling path is allowed to read. */
+    now: () => Promise<Date>;
+    /** True when this call created the job; false when that id was already there. Never throws on a duplicate. */
+    enqueue: (job: ActionJobInput) => Promise<boolean>;
+    /**
+     * Takes up to `limit` jobs that are due, and any whose lease has lapsed — atomically, one worker per job.
+     *
+     * A reclaimed job arrives with its previous holder's attempt already written to the history as `lost`.
+     */
+    claim: (params: {
+        workerId: string;
+        leaseMs: number;
+        limit: number;
+    }) => Promise<ActionJob[]>;
+    /** Extends the lease on jobs this worker still holds, and answers which of them an operator asked to cancel. */
+    heartbeat: (params: {
+        jobIds: string[];
+        workerId: string;
+        leaseMs: number;
+    }) => Promise<string[]>;
+    settle: (settlement: ActionJobSettlement) => Promise<void>;
+    /** Due schedules, oldest fire first. */
+    dueSchedules: (limit: number) => Promise<ActionSchedule[]>;
+    /**
+     * Moves a schedule forward, but only if it is still where the caller last saw it.
+     *
+     * The compare-and-set is what stops two replicas from advancing the same schedule twice. Answers false when
+     * somebody else got there first, which is not an error — it is the other replica having done the work.
+     */
+    advanceSchedule: (params: {
+        spaceId: number;
+        actionId: string;
+        from: number;
+        to: number;
+        missed: number;
+    }) => Promise<boolean>;
+    /** Replaces what this space has scheduled. An action no longer listed stops having a schedule at all. */
+    putSchedules: (params: {
+        spaceId: number;
+        schedules: ActionScheduleInput[];
+    }) => Promise<void>;
+    listJobs: (query: ActionJobQuery) => Promise<{
+        jobs: ActionJob[];
+        total: number;
+    }>;
+    getJob: (spaceIds: number[], jobId: string) => Promise<ActionJob | undefined>;
+    listSchedules: (spaceIds: number[]) => Promise<ActionSchedule[]>;
+    /** An operator putting a finished job back in the queue. Answers false when it is not in a state to go back. */
+    requeue: (spaceIds: number[], jobId: string) => Promise<boolean>;
+    /** An operator stopping a job: dropped if it is waiting, aborted at its next step if it is running. */
+    cancel: (spaceIds: number[], jobId: string) => Promise<boolean>;
+};

package/dist/types/ServerTypes.d.ts

@@ -1,4 +1,4 @@
-import { ActionEmailConfig, ActionEntry, ActionLimits, ActionRejectReason, ActionRunSummary, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionTaskDescriptor, ActionTriggerType } from './ActionTypes';
+import { ActionEmailConfig, ActionEntry, ActionJobQueue, ActionLimits, ActionRejectReason, ActionRunSummary, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionTaskDescriptor, ActionTriggerType } from './ActionTypes';
 import { Environment } from './CommonTypes';
 import { ConnectorEntry } from './ConnectorTypes';
 import { Schema } from './SchemaTypes';
@@ -465,6 +465,8 @@ export type SpaceRevision = {
 export type ActionLookupsConfig = {
     getAction: (spaceId: number, actionId: string, at?: SpaceRevision) => Promise<unknown>;
     listActions?: (spaceId: number, at?: SpaceRevision) => Promise<unknown[]>;
+    /** Which spaces have something scheduled — the periodic reconcile's safety net. See `ActionLookups`. */
+    listScheduledSpaces?: () => Promise<number[]>;
     getCredential?: (spaceId: number, identifier: string) => Promise<Record<string, string> | undefined>;
     getConnector?: (spaceId: number, connectorId: string, at?: SpaceRevision) => Promise<unknown>;
 };
@@ -554,6 +556,55 @@ export type SSRActionConfig = {
         increment: (key: string, amount: number) => Promise<number>;
         expire: (key: string, ttlSeconds: number) => Promise<void>;
     };
+    /**
+     * Scheduled runs: the durable queue they wait in, how many this replica runs at once, and whether it produces.
+     *
+     * On wherever `lookups.listActions` is answerable — a `schedule` trigger the editor offers is a trigger the
+     * server honours, which before this it only did if the deployment wrote a timer and a distributed lock of its
+     * own. With no `queue` it runs over this process's memory: right for one replica, and wrong for two, because
+     * each then keeps its own schedules and the nightly email goes out once per replica.
+     *
+     * `false` turns it off for a replica that must only serve pages.
+     */
+    jobs?: SSRActionJobsConfig | false;
+};
+/**
+ * How this deployment runs what a clock starts.
+ *
+ * Every default here is a safe one for a single machine; the two a cluster has to think about are `queue` — which
+ * must be shared, or the replicas do not see each other's work — and `workers`, which is how fast a backlog
+ * drains. Nothing in this config is a clock: the queue's own is the only one the scheduling path reads, so
+ * replicas in different countries agree about what has run without agreeing about what time it is.
+ */
+export type SSRActionJobsConfig = {
+    /** Shaped as `ActionJobQueue`. Omitted → this process's memory. */
+    queue?: ActionJobQueue;
+    /** Jobs this replica runs at once. Default 4; `0` produces without consuming. */
+    workers?: number;
+    /** Whether this replica sweeps due schedules into the queue. Default true. */
+    produce?: boolean;
+    /** The spaces this server schedules for, when it serves a known few — the self-hosted shape. */
+    spaces?: number[];
+    /** How often a free worker looks for a job. Default 1s. */
+    pollMs?: number;
+    /** How often this replica looks for due schedules. Default 15s. */
+    schedulePollMs?: number;
+    /** How long a claim is held before another replica may take the job over — the failover window. Default 30s. */
+    leaseMs?: number;
+    /** Attempts a job gets before it is left for an operator as `dead`. Default 3. */
+    maxAttempts?: number;
+    /** First retry delay, doubling per attempt, up to `maxMs`. Defaults to 30s and 15 minutes. */
+    backoff?: {
+        baseMs?: number;
+        maxMs?: number;
+    };
+    /** Which environment scheduled runs execute in. Default `main`. */
+    environment?: Environment;
+    /** How often schedules are re-derived from documents. Default 15 minutes. */
+    reconcileMs?: number;
+    /** Names this replica in the job history. Defaults to the pid and a random suffix. */
+    workerId?: string;
+    onError?: (error: unknown) => void;
 };
 /**
  * How the server reaches a space's connectors: the manifest that describes one, and the credential it authenticates

package/dist/types/StoreTypes.d.ts

@@ -102,7 +102,7 @@ export type RenderSettings = {
      *
      * Not the visitor's business and not the page's either — it is a fact about the account behind the site, which is
      * why it rides the render surface rather than the schema: nothing an author writes can set it, and nothing in the
-     * space's settings can turn it off. `branding` is forced on by the same state; this is what says WHY.
+     * space's settings can turn it off.
      */
     overQuota?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-shared",
-  "version": "0.37.0",
+  "version": "0.37.2",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -186,6 +186,10 @@
       "types": "./dist/dataSource/utility/capitalize.d.ts",
       "import": "./dist/dataSource/utility/capitalize.mjs"
     },
+    "./dataSource/utility/checkboxParams": {
+      "types": "./dist/dataSource/utility/checkboxParams.d.ts",
+      "import": "./dist/dataSource/utility/checkboxParams.mjs"
+    },
     "./dataSource/utility/dateConverter": {
       "types": "./dist/dataSource/utility/dateConverter.d.ts",
       "import": "./dist/dataSource/utility/dateConverter.mjs"
@@ -412,6 +416,10 @@
       "types": "./dist/helpers/twigWrapper/templateRoots.d.ts",
       "import": "./dist/helpers/twigWrapper/templateRoots.mjs"
     },
+    "./helpers/twigWrapper/tokens/hasTemplateSyntax": {
+      "types": "./dist/helpers/twigWrapper/tokens/hasTemplateSyntax.d.ts",
+      "import": "./dist/helpers/twigWrapper/tokens/hasTemplateSyntax.mjs"
+    },
     "./helpers/twigWrapper/tokens/hasValidToken": {
       "types": "./dist/helpers/twigWrapper/tokens/hasValidToken.d.ts",
       "import": "./dist/helpers/twigWrapper/tokens/hasValidToken.mjs"
@@ -1285,7 +1293,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@plitzi/nexus": "^1.2.2",
-    "@plitzi/plitzi-ui": "^1.6.21",
+    "@plitzi/plitzi-ui": "^1.6.22",
     "date-fns": "^4.4.0",
     "date-fns-tz": "^3.2.0",
     "graphql-tag": "^2.12.7",
@@ -1297,12 +1305,12 @@
     "react-dom": "^19"
   },
   "devDependencies": {
-    "@babel/cli": "^8.0.5",
-    "@babel/core": "^8.0.5",
-    "@babel/eslint-parser": "^8.0.5",
+    "@babel/cli": "^8.0.6",
+    "@babel/core": "^8.0.6",
+    "@babel/eslint-parser": "^7.29.9",
     "@babel/plugin-syntax-flow": "^8.0.1",
     "@babel/plugin-transform-react-jsx": "^8.0.1",
-    "@babel/preset-env": "^8.0.5",
+    "@babel/preset-env": "^8.0.6",
     "@eslint/js": "^10.0.1",
     "@tailwindcss/forms": "^0.5.11",
     "@testing-library/dom": "^10.4.2",
@@ -1317,12 +1325,12 @@
     "eslint": "^9.39.5",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-config-turbo": "^2.10.13",
+    "eslint-config-turbo": "^2.11.3",
     "eslint-import-resolver-alias": "^1.1.2",
     "eslint-plugin-cypress": "^7.0.2",
     "eslint-plugin-flowtype": "8.0.3",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jsdoc": "^64.5.2",
+    "eslint-plugin-jsdoc": "^64.5.4",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-react": "^7.37.5",
@@ -1330,17 +1338,17 @@
     "eslint-plugin-react-refresh": "^0.5.7",
     "eslint-plugin-storybook": "^10.6.0",
     "globals": "^17.12.0",
-    "jsdom": "^30.1.0",
+    "jsdom": "^30.1.1",
     "postcss": "^8.5.28",
-    "prettier": "^3.9.8",
+    "prettier": "^3.9.9",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "tailwindcss": "^4.3.3",
     "terser": "^5.51.2",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.70.0",
+    "typescript-eslint": "^8.70.1",
     "vite": "^8.3.0",
-    "vite-plugin-dts": "^5.1.0",
+    "vite-plugin-dts": "^5.1.1",
     "vite-plugin-react": "^4.0.1",
     "vitest": "^5.0.1",
     "vitest-fetch-mock": "^0.4.5"