@omelhorsite/sdk 0.16.0 → 0.18.0

package/dist/types/resources/content/news/sources.d.ts

@@ -38,8 +38,20 @@ export interface NewsSource {
     readonly config: Record<string, Json>;
     /** The {@link NewsFeed} it belongs to. */
     readonly news_feed_id: Id;
-    /** Which {@link NewsScript} fetches this source. */
-    readonly news_script_id: Id;
+    /** Which {@link NewsScript} fetches this source, or `null` when a job does. */
+    readonly news_script_id: Id | null;
+    /**
+     * The cron job (`oms.cron.jobs`, with `output` items) that fetches this
+     * source instead of a script, and the schedule of that job the source owns:
+     * its `cron` comes from `poll_interval_minutes` and its `params` are the
+     * source's `config`. `null` for a script source.
+     */
+    readonly cron_job_id: Id | null;
+    readonly cron_schedule_id: Id | null;
+    /** The schedule's cron expression, for a job source. */
+    readonly cron: string | null;
+    /** Where the job runs, for a job source: `sandbox` or `full`. */
+    readonly runtime: "sandbox" | "full" | null;
     /** Minutes between polls. Validated `in: 5..1440`. */
     readonly poll_interval_minutes: number;
     /**
@@ -67,7 +79,7 @@ export interface NewsSource {
     readonly consecutive_failures: number;
 }
 /** Filter columns of `GET /news_sources`, on top of {@link BASE_FILTER_COLUMNS}. */
-export declare const NEWS_SOURCE_FILTER_COLUMNS: readonly ["name", "health", "enabled", "news_feed_id", "news_script_id"];
+export declare const NEWS_SOURCE_FILTER_COLUMNS: readonly ["name", "health", "enabled", "news_feed_id", "news_script_id", "cron_job_id"];
 /** Filters for {@link NewsSourcesNamespace.list}. */
 export interface ListNewsSourcesParams extends ListParams<(typeof NEWS_SOURCE_FILTER_COLUMNS)[number]> {
     /** Only healthy / only broken sources. Sent as `exact_search[health]`. */
@@ -78,6 +90,8 @@ export interface ListNewsSourcesParams extends ListParams<(typeof NEWS_SOURCE_FI
     readonly feedId?: Id;
     /** Every source driven by one script. */
     readonly scriptId?: Id;
+    /** Every source driven by one job. */
+    readonly jobId?: Id;
 }
 /** Arguments for {@link NewsSourcesNamespace.create}. */
 export interface CreateNewsSourceInput {
@@ -89,9 +103,17 @@ export interface CreateNewsSourceInput {
      * The script that fetches it. Must be a built-in or one of yours;
      * `script_visible_to_owner` rejects anything else with
      * `400 "News script is not accessible"` rather than a 404, so this also
-     * tells you the id exists. Do not use it as an existence oracle.
+     * tells you the id exists. Do not use it as an existence oracle. Give
+     * either this or `jobId`.
      */
-    readonly scriptId: Id;
+    readonly scriptId?: Id;
+    /**
+     * A cron job of yours with `output: { kind: "items" }` that fetches it
+     * instead of a script. The source gets a schedule of that job: the cron
+     * from `pollIntervalMinutes`, the `config` as the run params. `400` when
+     * the job has no items output.
+     */
+    readonly jobId?: Id;
     /** Whatever that script reads. Free-form; the API validates nothing in it. */
     readonly config?: Record<string, Json>;
     /** 5-1440. Defaults to 15 server-side. */
@@ -104,11 +126,36 @@ export interface CreateNewsSourceInput {
  *
  * One key wider than the create form: `cursor` is updatable and not creatable.
  */
+/** Arguments for {@link NewsSourcesNamespace.test}: a script, or a sandbox job (its config goes under the given one). */
+export interface TestNewsSourceInput {
+    readonly scriptId?: Id;
+    readonly jobId?: Id;
+    readonly config?: Record<string, Json>;
+}
+export interface NewsSourceTestItem {
+    readonly external_id: string;
+    readonly title: string;
+    readonly url: string | null;
+    readonly published_at: Timestamp | null;
+    readonly content: string | null;
+}
+/** What a dry run produced. `ok: false` carries the script's error. */
+export interface NewsSourceTest {
+    readonly ok: boolean;
+    readonly error?: string;
+    readonly items: NewsSourceTestItem[];
+    readonly count: number;
+    /** Items published in the last 30 days. */
+    readonly dated: number;
+    readonly logs: string[];
+}
 export interface UpdateNewsSourceInput {
     readonly name?: string;
     /** Moves the source (and nothing else: its items stay where they were written) to another of your feeds. */
     readonly newsFeedId?: Id;
+    /** Setting a script drops the job (and its schedule); setting a job drops the script. */
     readonly scriptId?: Id;
+    readonly jobId?: Id;
     /**
      * REPLACES the whole object; there is no merge. `assign_attributes` writes
      * the JSON column wholesale, so sending `{ url: "..." }` to a source that
@@ -235,5 +282,14 @@ export declare class NewsSourcesNamespace extends Resource {
      * @throws {OmsApiError} 404 `"Resource not found"` when the source is not
      *   yours.
      */
+    /**
+     * `POST /news_sources/test` - run a script with a config once, with no cursor
+     * and without creating anything, and get back the items it would produce.
+     * The dry run before creating or repairing a source.
+     *
+     * @throws {OmsApiError} 400 when the script is not a built-in or one of
+     *   yours; 502 when the runner is down.
+     */
+    test(input: TestNewsSourceInput, options?: RequestOptions): Promise<NewsSourceTest>;
     run(id: Id, options?: RequestOptions): Promise<NewsSourceRunAccepted>;
 }

package/dist/types/resources/content/notifications.d.ts

@@ -20,7 +20,7 @@ export type NotificationCategory = (typeof NOTIFICATION_CATEGORIES)[number];
  * `admin_*` kinds only ever reach administrators. The `_done` / `_failed`
  * pairs of the media tools only reach the account that started the job.
  */
-export declare const NOTIFICATION_KINDS: readonly ["security_new_session", "security_password_changed", "security_email_changed", "security_passkey_added", "security_app_authorized", "friendship_request", "friendship_accepted", "user_followed", "message_received", "group_chat_message", "jam_invite", "fs_grant_received", "chest_expires_soon", "vocal_separation_done", "vocal_separation_failed", "transcription_done", "transcription_failed", "upscale_done", "upscale_failed", "background_removal_done", "background_removal_failed", "caption_job_done", "caption_job_failed", "jumpstyle_job_done", "jumpstyle_job_failed", "song_import_done", "song_import_failed", "spotify_sync_done", "spotify_sync_failed", "artist_import_done", "blog_new_post", "form_submission_received", "ticket_reply", "ticket_status_changed", "news_source_failing", "cron_run_failed", "cron_run_done", "oauth_application_approved", "oauth_application_rejected", "admin_oauth_application_submitted", "admin_ticket_created", "admin_feedback_received"];
+export declare const NOTIFICATION_KINDS: readonly ["security_new_session", "security_password_changed", "security_email_changed", "security_passkey_added", "security_app_authorized", "friendship_request", "friendship_accepted", "user_followed", "message_received", "group_chat_message", "jam_invite", "fs_grant_received", "chest_expires_soon", "vocal_separation_done", "vocal_separation_failed", "transcription_done", "transcription_failed", "upscale_done", "upscale_failed", "background_removal_done", "background_removal_failed", "caption_job_done", "caption_job_failed", "jumpstyle_job_done", "jumpstyle_job_failed", "song_import_done", "song_import_failed", "spotify_sync_done", "spotify_sync_failed", "artist_import_done", "blog_new_post", "form_submission_received", "ticket_reply", "ticket_status_changed", "news_source_failing", "cron_run_failed", "cron_run_done", "bot_message_received", "bot_needs_human", "oauth_application_approved", "oauth_application_rejected", "admin_oauth_application_submitted", "admin_ticket_created", "admin_feedback_received"];
 /**
  * One of {@link NOTIFICATION_KINDS}.
  *

package/dist/types/resources/cron.d.ts

@@ -2,25 +2,49 @@
  * The `cron` namespace: TypeScript scripts of the signed-in person that the
  * server runs on a schedule.
  *
- * A script is an ES module exporting `run(ctx)`. It runs with nothing but the
- * API: no filesystem, no environment, no processes, and no network beyond
- * this SDK (`ctx.oms`, authenticated as the owner with the job's scopes) and,
- * when the job has `network` on, a `ctx.fetch` that goes through the server's
- * guard against private addresses. What it keeps in `ctx.state` is stored
- * when a run ends well and handed back on the next one; what it returns is
- * the run's `result`, and `result.summary` is what the listing shows.
+ * A script is an ES module exporting `run(ctx)`. WHERE it runs follows from
+ * what it declares: a job with no scopes runs in the light sandbox (the one
+ * the news sources use: no token, no SDK, only a guarded `fetchText` and the
+ * HTML/XML helpers, thousands of runs a day); a job with scopes runs in the
+ * full runner, with `ctx.oms` authenticated as the owner and, when the job
+ * has `network` on, a `ctx.fetch` that goes through the server's guard
+ * against private addresses. The base contract (`config`, `params`, `state`,
+ * `log`, `fetchText`, `select`, `parseXml`, `htmlText`) is the same in both.
+ * What a script keeps in `ctx.state` is stored when a run ends well and
+ * handed back on the next one; what it returns is the run's `result`, and
+ * `result.summary` is what the listing shows.
+ *
+ * A job whose `output` is `{ kind: "items" }` returns `{ items, cursor? }`
+ * and the server stores the items in the news source the run belongs to.
+ *
+ * A job has zero or more SCHEDULES ({@link CronSchedule}): each a cron
+ * expression in a timezone with its own `params` and switch. A run carries
+ * `params`: an object merged over the job's `config` (so the script reads
+ * `ctx.config` as usual) and handed on its own as `ctx.params`. They come
+ * from the schedule that fired, or from whoever called `run`.
  *
  * Needs the `cron:read` scope to read and `cron:write` to change anything.
- * A job's own token never carries either: a script cannot edit jobs.
+ * A job's own token never carries either; with `cron:run` it may start other
+ * jobs.
  */
 import { Resource, type ApiClient } from "../http";
 import type { ListParams } from "../listing";
-import type { Id, Json, Paginated, RequestOptions, Timestamp } from "../types";
-/** Scopes a job may ask for its token. Anything else answers `400`. */
-export declare const CRON_JOB_SCOPES: readonly ["profile", "news:read", "news:write", "storage:read", "storage:write", "llm", "tools:read", "tools:write", "blogs:read", "blogs:write"];
+import type { Id, Json, JsonObject, Paginated, RequestOptions, Timestamp } from "../types";
+/**
+ * Scopes a job may ask for its token. Anything else answers `400`. `cron:run`
+ * lets a script run other jobs (with params) without reading or editing them.
+ */
+export declare const CRON_JOB_SCOPES: readonly ["profile", "news:read", "news:write", "storage:read", "storage:write", "llm", "tools:read", "tools:write", "blogs:read", "blogs:write", "bots:read", "bots:write", "cron:run"];
 export type CronJobScope = (typeof CRON_JOB_SCOPES)[number];
 export declare const CRON_JOB_HEALTHS: readonly ["unknown", "ok", "error"];
 export type CronJobHealth = (typeof CRON_JOB_HEALTHS)[number];
+/** Where a job runs, derived from its scopes: none means the light sandbox. */
+export declare const CRON_JOB_RUNTIMES: readonly ["sandbox", "full"];
+export type CronJobRuntime = (typeof CRON_JOB_RUNTIMES)[number];
+/** What a job's runs produce, when it is not just a result: news items for a source. */
+export interface CronJobOutput {
+    readonly kind: "items";
+}
 /** Consecutive failures after which a job switches itself off. Turn `enabled` back on to revive it. */
 export declare const CRON_JOB_DISABLE_AFTER_FAILURES = 10;
 /** Code longer than this answers `400`. */
@@ -28,8 +52,10 @@ export declare const CRON_JOB_MAX_CODE_BYTES: number;
 /** `state` and `config` ceilings. A run whose state grows past this fails and the state is not stored. */
 export declare const CRON_JOB_MAX_STATE_BYTES: number;
 export declare const CRON_JOB_MAX_CONFIG_BYTES: number;
-/** Two runs of one job must be at least this far apart. */
+/** Two occurrences of one schedule must be at least this far apart. */
 export declare const CRON_JOB_MIN_INTERVAL_MINUTES = 5;
+/** Schedules one job may have. */
+export declare const CRON_SCHEDULES_MAX_PER_JOB = 200;
 /** `timeout_seconds` range; above 120 the account needs a trusted tier, like `network`. */
 export declare const CRON_JOB_MIN_TIMEOUT_SECONDS = 5;
 export declare const CRON_JOB_MAX_TIMEOUT_SECONDS = 1200;
@@ -41,20 +67,27 @@ export interface CronJob {
     /** Up to 120 characters, unique per account. */
     readonly name: string;
     readonly description: string | null;
-    /** Five-field cron expression, read in `timezone`. */
-    readonly schedule: string;
-    /** An IANA zone such as `"Europe/Lisbon"` (the default). */
+    /** The cron expression of the job's FIRST schedule, or `null` when it has none. The whole list is in {@link CronJobDetail.schedules}. */
+    readonly schedule: string | null;
+    /** How many schedules the job has. */
+    readonly schedules_count: number;
+    /** An IANA zone such as `"Europe/Lisbon"` (the default); the default timezone of new schedules. */
     readonly timezone: string;
-    /** The scopes the run's token carries. */
+    /** The scopes the run's token carries. Empty means the job runs in the sandbox, with no token. */
     readonly scopes: CronJobScope[];
+    /** Derived from `scopes`: `sandbox` when there are none, `full` otherwise. */
+    readonly runtime: CronJobRuntime;
+    /** `{ kind: "items" }` when the script returns news items the server ingests; `null` for a plain result. */
+    readonly output: CronJobOutput | null;
     /** Names of the stored secrets. The values never leave the server. */
     readonly secret_keys: string[];
-    /** Whether `ctx.fetch` exists in the script. */
+    /** Whether `ctx.fetch`/`ctx.fetchText` exist in the script. In the sandbox this needs no trusted tier. */
     readonly network: boolean;
     readonly timeout_seconds: number;
     /** A folder of the owner's storage handed to the script as `ctx.job.outputDirId`. */
     readonly output_dir_id: Id | null;
     readonly enabled: boolean;
+    /** The nearest occurrence among the enabled schedules; `null` when the job is off or has none. */
     readonly next_run_at: Timestamp | null;
     readonly last_run_at: Timestamp | null;
     readonly last_success_at: Timestamp | null;
@@ -67,25 +100,86 @@ export interface CronJob {
     /** Whether a run is queued or running right now. */
     readonly running: boolean;
 }
-/** `GET /cron_jobs/:id` (and every write) adds the code, the config and the state. */
+/** The types a script may give a variable it declares with `// @var key type Label | description`. */
+export declare const CRON_VAR_TYPES: readonly ["string", "text", "number", "boolean", "list", "json"];
+export type CronVarType = (typeof CRON_VAR_TYPES)[number];
+/**
+ * A variable a script declares as editable, parsed by the server from the
+ * `// @var` lines at the top of the code. Its value lives in `config[key]`.
+ */
+export interface CronVar {
+    readonly key: string;
+    readonly type: CronVarType;
+    readonly label: string;
+    readonly description: string | null;
+}
+/** `GET /cron_jobs/:id` (and every write) adds the code, the config, the state, the declared variables and the schedules. */
 export interface CronJobDetail extends CronJob {
     readonly code: string;
     readonly config: Record<string, Json>;
     readonly state: Record<string, Json>;
+    readonly vars: CronVar[];
+    /** Oldest first. */
+    readonly schedules: CronSchedule[];
 }
+/**
+ * One schedule of a job: when it fires and with what params. A job may have
+ * several (a source per site, a report per feed) or none (run by hand, by
+ * the API or by another job).
+ */
+export interface CronSchedule {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly cron_job_id: Id;
+    /** Optional label, up to 120 characters. */
+    readonly name: string | null;
+    /** Five-field cron expression, read in `timezone`. */
+    readonly cron: string;
+    readonly timezone: string;
+    /** Handed to every run this schedule starts, merged over the job's config and as `ctx.params`. */
+    readonly params: Record<string, Json>;
+    /** Off, the schedule does not fire; the job's other schedules still do. */
+    readonly enabled: boolean;
+    readonly next_run_at: Timestamp | null;
+    readonly last_run_at: Timestamp | null;
+}
+export declare const CRON_SCHEDULE_FILTER_COLUMNS: readonly ["cron_job_id", "enabled"];
+export interface ListCronSchedulesParams extends ListParams<(typeof CRON_SCHEDULE_FILTER_COLUMNS)[number]> {
+    readonly jobId?: Id;
+    readonly enabled?: boolean;
+}
+export interface CreateCronScheduleInput {
+    readonly jobId: Id;
+    /** Five fields; two occurrences must be at least {@link CRON_JOB_MIN_INTERVAL_MINUTES} apart. */
+    readonly cron: string;
+    /** Defaults to `"Europe/Lisbon"`. */
+    readonly timezone?: string;
+    readonly name?: string | null;
+    /** Up to 64 KB. */
+    readonly params?: Record<string, Json>;
+    readonly enabled?: boolean;
+}
+export type UpdateCronScheduleInput = Partial<Omit<CreateCronScheduleInput, "jobId">>;
 export declare const CRON_JOB_FILTER_COLUMNS: readonly ["name", "enabled", "health", "template_slug"];
 export interface ListCronJobsParams extends ListParams<(typeof CRON_JOB_FILTER_COLUMNS)[number]> {
 }
 export interface CreateCronJobInput {
     readonly name: string;
     readonly description?: string | null;
-    /** Five fields. Two runs must be at least {@link CRON_JOB_MIN_INTERVAL_MINUTES} apart. */
-    readonly schedule: string;
+    /**
+     * Creates the job's first schedule (in `timezone`). Optional: a job with no
+     * schedule runs by hand, by the API or by another job. Add more with
+     * {@link CronSchedulesNamespace.create}; on update this edits the first one.
+     */
+    readonly schedule?: string;
     readonly timezone?: string;
     /** TypeScript. Checked for syntax on the server before it is stored. */
     readonly code: string;
-    /** Defaults to every scope but `news:write` and `tools:write`. */
+    /** Defaults to every scope but `news:write` and `tools:write`. Pass `[]` for a sandbox job (no token, no SDK). */
     readonly scopes?: readonly CronJobScope[];
+    /** `{ kind: "items" }` makes the runs' items go to the news source of each run. `null` removes it. */
+    readonly output?: CronJobOutput | null;
     readonly config?: Record<string, Json>;
     /** Stored encrypted; on update the object is MERGED, and a `null` value removes that key. */
     readonly secrets?: Record<string, string | null>;
@@ -101,16 +195,28 @@ export interface CreateCronJobInput {
 export type UpdateCronJobInput = Partial<Omit<CreateCronJobInput, "templateSlug">>;
 export declare const CRON_RUN_STATUSES: readonly ["queued", "running", "ok", "error", "timeout", "skipped"];
 export type CronRunStatus = (typeof CRON_RUN_STATUSES)[number];
-export declare const CRON_RUN_TRIGGERS: readonly ["schedule", "manual", "test"];
+/**
+ * Who asked for a run: a schedule, a person with a session (`manual`), a
+ * third-party OAuth token (`api`), another job's run token (`job`), or a test.
+ */
+export declare const CRON_RUN_TRIGGERS: readonly ["schedule", "manual", "api", "job", "test"];
 export type CronRunTrigger = (typeof CRON_RUN_TRIGGERS)[number];
 export interface CronRun {
     readonly id: Id;
     readonly created_at: Timestamp;
     readonly updated_at: Timestamp;
     readonly cron_job_id: Id;
+    /** The schedule that fired it, when the trigger is `schedule` and it still exists. */
+    readonly cron_schedule_id: Id | null;
+    /** The news source that received the items, for runs of a job with `output` items bound to a source. */
+    readonly news_source_id: Id | null;
+    /** Where it ran; `null` while queued. Sandbox runs do not count towards `cron_run_seconds`. */
+    readonly runtime: CronJobRuntime | null;
     readonly status: CronRunStatus;
     /** `test` runs never write the state back and never count as failures. */
     readonly trigger: CronRunTrigger;
+    /** Merged over the job's config for this run and handed to the script as `ctx.params`. */
+    readonly params: Record<string, Json>;
     readonly scheduled_at: Timestamp;
     readonly started_at: Timestamp | null;
     readonly finished_at: Timestamp | null;
@@ -136,6 +242,11 @@ export interface ListCronRunsParams extends ListParams<(typeof CRON_RUN_FILTER_C
     readonly jobId?: Id;
     readonly status?: CronRunStatus;
 }
+/** What `run` and `test` accept. */
+export interface RunCronJobInput {
+    /** Merged over the job's config for this run only; the script also gets them as `ctx.params`. Up to 64 KB. */
+    readonly params?: Record<string, Json>;
+}
 /** A ready-made script: copy it into a job with {@link CronJobsNamespace.create}. */
 export interface CronTemplate {
     readonly slug: string;
@@ -143,10 +254,15 @@ export interface CronTemplate {
     readonly description: string;
     /** The schedule the template expects. */
     readonly schedule: string;
+    /** Empty for sandbox templates (the news source scripts). */
     readonly scopes: CronJobScope[];
+    readonly runtime: CronJobRuntime;
+    readonly output: CronJobOutput | null;
     readonly network: boolean;
     /** The config the script reads, with defaults. */
     readonly config: Record<string, Json>;
+    /** The variables the template declares as editable (`// @var`). */
+    readonly vars: CronVar[];
     /** SHA-256 of the code, so a client can tell an edited copy from a pristine one. */
     readonly hash: string;
 }
@@ -179,15 +295,33 @@ export declare class CronJobsNamespace extends Resource {
      * `POST /cron_jobs/:id/run` - runs now, outside the schedule, as a normal
      * run (the state is stored). `202` with the queued run.
      *
-     * @throws {OmsApiError} 400 `this job is already running`; 429
-     *   `error: "limit"` when the day's `cron_run_seconds` are spent.
+     * @throws {OmsApiError} 400 `this job is already running`, or
+     *   `params must be an object`; 429 `error: "limit"` when the day's
+     *   `cron_run_seconds` are spent.
      */
-    run(id: Id, options?: RequestOptions): Promise<CronRun>;
+    run(id: Id, input?: RunCronJobInput, options?: RequestOptions): Promise<CronRun>;
     /** `POST /cron_jobs/:id/test` - runs now WITHOUT storing the state or counting a failure. `202`. */
-    test(id: Id, options?: RequestOptions): Promise<CronRun>;
+    test(id: Id, input?: RunCronJobInput, options?: RequestOptions): Promise<CronRun>;
     /** `POST /cron_jobs/check` - the syntax check the server runs before storing code, on its own. */
     check(code: string, options?: RequestOptions): Promise<CronCheckResult>;
 }
+export declare class CronSchedulesNamespace extends Resource {
+    /** `GET /cron_schedules` - oldest first, narrowed by job. */
+    list(params?: ListCronSchedulesParams, options?: RequestOptions): Promise<Paginated<CronSchedule>>;
+    get(id: Id, options?: RequestOptions): Promise<CronSchedule>;
+    /**
+     * `POST /cron_schedules`. `201`.
+     *
+     * @throws {OmsApiError} 400 with the sentence: a bad or too frequent cron,
+     *   an unknown timezone, `params must be an object`,
+     *   `cron_job_id must be one of your jobs`, or `schedule limit reached`.
+     */
+    create(input: CreateCronScheduleInput, options?: RequestOptions): Promise<CronSchedule>;
+    /** `PATCH /cron_schedules/:id`. Changing the cron or the timezone recomputes `next_run_at`. */
+    update(id: Id, input: UpdateCronScheduleInput, options?: RequestOptions): Promise<CronSchedule>;
+    /** `DELETE /cron_schedules/:id`. Past runs keep existing without it. `204`. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
 export declare class CronRunsNamespace extends Resource {
     /** `GET /cron_runs` - newest first. */
     list(params?: ListCronRunsParams, options?: RequestOptions): Promise<Paginated<CronRun>>;
@@ -201,9 +335,168 @@ export declare class CronTemplatesNamespace extends Resource {
     get(slug: string, options?: RequestOptions): Promise<CronTemplateDetail>;
 }
 /** The `cron` namespace, reachable as `oms.cron`. */
+/**
+ * A job's small database: rows a script keeps between runs, instead of one
+ * JSON file it has to read and rewrite whole to change a line.
+ *
+ * A row lives in a COLLECTION of the job (`"mentions"`, `"seen"`), under a
+ * KEY unique within it, and holds a JSON object. `at` is the row's own
+ * instant - the date of the mention, the delivery, the decision - and is what
+ * {@link CronRecordsNamespace.list} orders by and
+ * {@link CronRecordsNamespace.prune} trims. Writing is an upsert: the data is
+ * replaced, and `at` only changes when the write carries one.
+ *
+ * Reading needs `cron:read` and writing `cron:write`; a script running as the
+ * job reaches its OWN job's records with the token it already has.
+ */
+export interface CronRecord {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly cron_job_id: Id;
+    readonly collection: string;
+    readonly key: string;
+    readonly data: JsonObject;
+    readonly at: Timestamp | null;
+}
+/** Lowercase letters, digits, `-` and `_`, up to this many characters. */
+export declare const CRON_RECORD_COLLECTION_MAX = 64;
+/** Longer keys are shortened by {@link cronRecordKey} before they are sent. */
+export declare const CRON_RECORD_KEY_MAX = 200;
+/** A row's `data`, serialised. */
+export declare const CRON_RECORD_MAX_DATA_BYTES: number;
+/** Rows one job may hold. Past it new keys are refused; the ones already there still update. */
+export declare const CRON_RECORD_MAX_PER_JOB = 200000;
+/** Rows one write may carry. {@link CronRecordsNamespace.putMany} splits longer lists. */
+export declare const CRON_RECORD_MAX_PER_BATCH = 500;
+/** Rows one {@link CronRecordsNamespace.prune} deletes. Call it again until it answers `0`. */
+export declare const CRON_RECORD_MAX_PER_DELETE = 10000;
+/** `where` fields one listing may compare. */
+export declare const CRON_RECORD_MAX_WHERE = 5;
+export declare const CRON_RECORD_MAX_LIMIT = 500;
+/** What a listing sorts by. Descending unless the suffix says otherwise; rows without an `at` come last either way. */
+export type CronRecordOrder = "at" | "at:asc" | "at:desc" | "updated_at" | "updated_at:asc" | "updated_at:desc";
+export interface ListCronRecordsParams {
+    readonly collection: string;
+    /** 1 to {@link CRON_RECORD_MAX_LIMIT}; 50 by default. */
+    readonly limit?: number;
+    /** The `next_cursor` of the previous page. */
+    readonly cursor?: string | null;
+    /** Over `at`, inclusive. A row without an `at` is outside both. */
+    readonly since?: string | Date;
+    readonly until?: string | Date;
+    /** Fetch several rows at once. Long keys are shortened as {@link CronRecordsNamespace.put} shortens them. */
+    readonly keys?: readonly string[];
+    /** Equality against `data->>field`, as text. At most {@link CRON_RECORD_MAX_WHERE} fields. */
+    readonly where?: Readonly<Record<string, string | number | boolean>>;
+    readonly order?: CronRecordOrder;
+    /** Ask for `count`: how many rows the filter matches, not just this page. */
+    readonly count?: boolean;
+}
+export interface CronRecordPage {
+    readonly records: CronRecord[];
+    /** `null` on the last page. */
+    readonly next_cursor: string | null;
+    /** `null` unless the request asked for it. */
+    readonly count: number | null;
+}
+export interface CronRecordInput {
+    readonly collection: string;
+    readonly key: string;
+    /** Up to {@link CRON_RECORD_MAX_DATA_BYTES} serialised. Defaults to `{}`. */
+    readonly data?: JsonObject;
+    /** The row's own instant. Left out, a row that already exists keeps the one it has. */
+    readonly at?: string | Date | null;
+}
+export interface CronRecordWriteResult {
+    readonly created: number;
+    readonly updated: number;
+}
+export interface CronRecordDeleteResult {
+    readonly deleted: number;
+}
+/** One collection of a job, as {@link CronRecordsNamespace.collections} reports it. */
+export interface CronRecordCollection {
+    readonly collection: string;
+    readonly count: number;
+    readonly first_at: Timestamp | null;
+    readonly last_at: Timestamp | null;
+    readonly updated_at: Timestamp;
+}
+export interface PruneCronRecordsOptions {
+    /** Delete the rows at or before this instant. */
+    readonly before: string | Date;
+    /** Which instant to read: the row's own (default) or the last write. */
+    readonly on?: "at" | "updated_at";
+}
+/**
+ * The key the server stores for a value. Anything past
+ * {@link CRON_RECORD_KEY_MAX} keeps its start and gains a fingerprint of the
+ * whole, so a link stays a usable key and always resolves to the same row.
+ *
+ * @throws {TypeError} on a runtime without WebCrypto, and only for a value
+ *   long enough to need shortening.
+ */
+export declare function cronRecordKey(value: string): Promise<string>;
+export declare class CronRecordsNamespace extends Resource {
+    /**
+     * `GET /cron_jobs/:id/records` - one page of a collection, newest first,
+     * paged by cursor rather than by offset so writes in between neither repeat
+     * nor skip a row.
+     *
+     * @throws {OmsApiError} 400 for a missing or malformed `collection`, a
+     *   `limit` outside 1..500, an unknown `order`, an unparsable date, a
+     *   cursor from somewhere else, or more than 5 `where` fields.
+     */
+    list(jobId: Id, params: ListCronRecordsParams, options?: RequestOptions): Promise<CronRecordPage>;
+    /** Every row of a collection, page after page. The filters of {@link list} apply. */
+    all(jobId: Id, collection: string, params?: Omit<ListCronRecordsParams, "collection" | "cursor" | "count">, options?: RequestOptions): AsyncGenerator<CronRecord>;
+    /** One row, or `null` when the collection has no such key. */
+    get(jobId: Id, collection: string, key: string, options?: RequestOptions): Promise<CronRecord | null>;
+    /** `POST /cron_jobs/:id/records` - creates or replaces one row. */
+    put(jobId: Id, collection: string, key: string, data?: JsonObject, at?: string | Date | null, options?: RequestOptions): Promise<CronRecordWriteResult>;
+    /**
+     * Creates or replaces many rows. Each request is one transaction; a list
+     * longer than {@link CRON_RECORD_MAX_PER_BATCH} goes in several, so a
+     * failure part-way leaves the batches before it written.
+     *
+     * @throws {OmsApiError} 400 for a bad collection, an empty or too long key,
+     *   `data` that is not an object or is past the size ceiling, or
+     *   `record limit reached` when the job is full.
+     */
+    putMany(jobId: Id, records: readonly CronRecordInput[], options?: RequestOptions): Promise<CronRecordWriteResult>;
+    /** `DELETE /cron_jobs/:id/records` - one row. `deleted` is `0` when there was none. */
+    remove(jobId: Id, collection: string, key: string, options?: RequestOptions): Promise<CronRecordDeleteResult>;
+    /** Several rows by key, in one request. */
+    removeMany(jobId: Id, collection: string, keys: readonly string[], options?: RequestOptions): Promise<CronRecordDeleteResult>;
+    /**
+     * Deletes the old rows of a collection, up to
+     * {@link CRON_RECORD_MAX_PER_DELETE} per call - call it again while
+     * `deleted` comes back full.
+     */
+    prune(jobId: Id, collection: string, options: PruneCronRecordsOptions, requestOptions?: RequestOptions): Promise<CronRecordDeleteResult>;
+    /** `GET /cron_jobs/:id/records/collections` - what the job holds, by name. */
+    collections(jobId: Id, options?: RequestOptions): Promise<CronRecordCollection[]>;
+    /** The same methods bound to one job, which is what a running script is handed. */
+    for(jobId: Id): BoundCronRecords;
+}
+/** {@link CronRecordsNamespace} with the job already filled in. */
+export interface BoundCronRecords {
+    list(params: ListCronRecordsParams, options?: RequestOptions): Promise<CronRecordPage>;
+    all(collection: string, params?: Omit<ListCronRecordsParams, "collection" | "cursor" | "count">, options?: RequestOptions): AsyncGenerator<CronRecord>;
+    get(collection: string, key: string, options?: RequestOptions): Promise<CronRecord | null>;
+    put(collection: string, key: string, data?: JsonObject, at?: string | Date | null, options?: RequestOptions): Promise<CronRecordWriteResult>;
+    putMany(records: readonly CronRecordInput[], options?: RequestOptions): Promise<CronRecordWriteResult>;
+    remove(collection: string, key: string, options?: RequestOptions): Promise<CronRecordDeleteResult>;
+    removeMany(collection: string, keys: readonly string[], options?: RequestOptions): Promise<CronRecordDeleteResult>;
+    prune(collection: string, options: PruneCronRecordsOptions, requestOptions?: RequestOptions): Promise<CronRecordDeleteResult>;
+    collections(options?: RequestOptions): Promise<CronRecordCollection[]>;
+}
 export declare class CronNamespace extends Resource {
     readonly jobs: CronJobsNamespace;
+    readonly schedules: CronSchedulesNamespace;
     readonly runs: CronRunsNamespace;
     readonly templates: CronTemplatesNamespace;
+    readonly records: CronRecordsNamespace;
     constructor(http: ApiClient);
 }

package/dist/types/resources/index.d.ts

@@ -23,6 +23,7 @@ export * from "./auth/index";
 export * from "./chests";
 export * from "./content";
 export * from "./cron";
+export * from "./bots";
 export * from "./dynamicQrs";
 export * from "./forms";
 export * from "./ipLookup";

package/dist/types/resources/search.d.ts

@@ -123,6 +123,11 @@ export interface SearchPage {
     readonly title: string;
     /** Plain text, whitespace collapsed, cut at `maxChars`. Never empty: a page with nothing readable is a `422`. */
     readonly text: string;
+    /**
+     * When the page says it was published (`article:published_time`, JSON-LD
+     * `datePublished`, a `<time datetime>`), as ISO 8601; `null` when it does not.
+     */
+    readonly published_at: string | null;
 }
 /** The `search` namespace, reachable as `oms.search`. */
 export declare class SearchNamespace extends Resource {