@omelhorsite/sdk 0.17.0 → 0.18.0

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;
@@ -80,26 +113,73 @@ export interface CronVar {
     readonly label: string;
     readonly description: string | null;
 }
-/** `GET /cron_jobs/:id` (and every write) adds the code, the config, the state and the declared variables. */
+/** `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>;
@@ -115,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;
@@ -150,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;
@@ -157,7 +254,10 @@ 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>;
@@ -195,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>>;
@@ -217,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 {

package/dist/types/resources/tools/imageGeneration.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Image generation: a prompt in, a PNG out.
+ *
+ * Same shape as the other async tools - `POST /image_generations` enqueues a
+ * job and answers with a row plus a `job_id` and, when anonymous, a
+ * `watch_token`.
+ *
+ * What is different here is that the work can run in two places, and the
+ * caller picks: a model on the server itself, which is free, or a model at a
+ * paid provider, which is not. {@link ImageGenerationNamespace.models} lists
+ * the ones the CURRENT caller may actually use, so an anonymous caller never
+ * sees a model they would be refused for.
+ *
+ * Two daily quotas apply, not one: a count of images, which every model
+ * consumes, and a spend ceiling in USD, which only the paid ones touch.
+ */
+import { Resource } from "../../http";
+import type { Id, RequestOptions } from "../../types";
+import { type ToolCaptcha, type ToolJobHandle, type ToolRecord, type ToolRunOptions } from "./index";
+/** Where a model runs. `"local"` is the server itself and always free. */
+export type ImageProvider = "local" | "fal";
+/** One model the caller may pick, as `GET /image_generations/models` lists it. */
+export interface ImageModel {
+    readonly key: string;
+    readonly name: string;
+    readonly description: string;
+    readonly provider: ImageProvider;
+    /** True when a run costs money and counts against the spend ceiling. */
+    readonly billable: boolean;
+    /** True on models kept behind an account flag. */
+    readonly adult: boolean;
+    /** `width * height` may not exceed this. */
+    readonly max_pixels: number;
+    readonly default_width: number;
+    readonly default_height: number;
+    readonly default_steps: number;
+    readonly max_steps: number;
+    /** False on models that ignore `negative_prompt` entirely, such as FLUX. */
+    readonly supports_negative_prompt: boolean;
+    /** Millionths of a USD per megapixel, rounded up. Zero on local models. */
+    readonly cost_per_megapixel_microusd: number;
+}
+/**
+ * One generation.
+ *
+ * Both routes that answer with one - `POST /image_generations` and
+ * `GET /image_generations/:id` - answer the same shape, so `result_url` is
+ * always PRESENT and simply `null` until the run completes.
+ */
+export interface ImageGeneration extends ToolRecord {
+    readonly model_key: string;
+    readonly provider: ImageProvider;
+    readonly prompt: string;
+    readonly negative_prompt: string | null;
+    readonly width: number;
+    readonly height: number;
+    readonly steps: number;
+    /**
+     * The seed the image was made with. Null only while the run is still
+     * pending: a caller that sent none gets the one the server picked, which is
+     * what makes the image reproducible.
+     */
+    readonly seed: number | null;
+    readonly guidance: string | null;
+    /** What this run costs, in millionths of a USD. Zero on local models. */
+    readonly cost_microusd: number;
+    /**
+     * Signed URL of the PNG, or `null`. `null` covers three different
+     * situations - the run has not finished, it failed, or the 24-hour sweep
+     * took the attachment - which is why {@link ImageGenerationNamespace.resultUrl}
+     * exists rather than a bare read of this field.
+     */
+    readonly result_url: string | null;
+}
+/** What `POST /image_generations` answers with. */
+export type ImageGenerationCreated = ImageGeneration & ToolJobHandle;
+/** Arguments for starting a run. */
+export interface CreateImageGenerationInput extends ToolCaptcha {
+    /** What to draw. Cap: 2000 characters. */
+    readonly prompt: string;
+    /** Defaults to the server's own default model when omitted. */
+    readonly model?: string;
+    /** Ignored by models whose `supports_negative_prompt` is false. */
+    readonly negativePrompt?: string;
+    /** Must be a multiple of 8, at least 256. Defaults to the model's own. */
+    readonly width?: number;
+    /** Must be a multiple of 8, at least 256. Defaults to the model's own. */
+    readonly height?: number;
+    readonly steps?: number;
+    /** Pass the seed of an earlier run to reproduce its image. */
+    readonly seed?: number;
+    readonly guidance?: number;
+}
+/** The `imageGeneration` tool, reachable as `oms.tools.imageGeneration`. */
+export declare class ImageGenerationNamespace extends Resource {
+    private readonly jobs;
+    /**
+     * `GET /image_generations/models` - the models THIS caller may use.
+     *
+     * The list is already filtered by session and by account flags, so it is
+     * safe to render straight into a picker: everything in it is something
+     * {@link create} would accept.
+     */
+    models(options?: RequestOptions): Promise<ImageModel[]>;
+    /**
+     * `POST /image_generations` - enqueues a run and returns straight away.
+     *
+     * Every optional field is omitted from the body when the caller did not set
+     * it, so the server applies the chosen model's own defaults rather than the
+     * SDK guessing at them.
+     *
+     * NOT retried by default: replaying this `POST` after a 502 starts a second
+     * run, and on a paid model bills for it. Pass `retry: {}` to opt back in.
+     *
+     * @throws {OmsApiError} 400 for an unknown model, a blank prompt, or
+     *   dimensions outside the model's limits; 403 for a model this caller may
+     *   not use; 429 once either daily quota is spent.
+     * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.
+     */
+    create(input: CreateImageGenerationInput, options?: RequestOptions): Promise<ImageGenerationCreated>;
+    /**
+     * `GET /image_generations/:id` - one poll.
+     *
+     * @throws {OmsApiError} 404 once the 24-hour retention sweep has taken it.
+     * @throws {OmsAuthError} 401 when the run belongs to someone else, which
+     *   includes an anonymous run being read from a different address.
+     */
+    get(id: Id, options?: RequestOptions): Promise<ImageGeneration>;
+    /**
+     * Creates a run and waits for it, through `oms.jobs.wait`.
+     *
+     * Resolves with a `"failed"` row rather than throwing when the work failed.
+     * Pass `waitTimeoutMs` (or a `signal`) to bound the wait; there is no default
+     * deadline.
+     *
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the run: pick it
+     *   up later with {@link get}.
+     */
+    run(input: CreateImageGenerationInput, options?: ToolRunOptions): Promise<ImageGeneration>;
+    /**
+     * Downloads the PNG of a finished run.
+     *
+     * @throws {OmsError} `conflict` when the run has not finished,
+     *   `invalid_request` when it failed, `not_found` when the artefact is gone.
+     */
+    download(id: Id, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The signed URL of a finished run's image, from a row you already hold.
+     *
+     * It is a credential: anyone holding it can read the image.
+     *
+     * @throws {OmsError} explaining which of the three reasons there is no URL.
+     */
+    resultUrl(record: ImageGeneration): string;
+}