@omelhorsite/sdk 0.16.0 → 0.17.0

package/README.md

@@ -132,7 +132,7 @@ const rows = await oms.http.get<{ id: string }[]>("/some/path");
 - `oms.cron` - your TypeScript scripts run on a schedule by the server, with this SDK in scope; runs, logs and templates.
 - `oms.search` - web, image, news and video search, and reading a page's text.
 - `oms.social` - direct messages, friends, group chats.
-- `oms.content.news` - news feeds: sources driven by scripts (RSS, Telegram, YouTube, a page with a selector), the items they produce, full-text search over them.
+- `oms.content.news` - news feeds: sources driven by scripts (RSS, Telegram, YouTube, a page with a selector), the items they produce, full-text and similarity search over them.
 - `oms.content` - blogs (several per account, public, unlisted or private with invited members; `oms.content.blogs.own` manages them), notifications, feedback, site status. `oms.content.notifications.unsubscribe(token)` honours the link at the foot of a notification email and needs no credential.
 - `oms.tools` - media tools, each with its own daily quota.
 - `oms.jobs`, `oms.quotas` - background jobs and account limits.

package/dist/index.js

@@ -11457,6 +11457,17 @@ class NewsItemsNamespace extends Resource {
   async get(id, options = {}) {
     return this.http.get(`/news_items/${encodeURIComponent(id)}`, options);
   }
+  async similar(params, options = {}) {
+    const query = {
+      text: params.text,
+      item_id: params.itemId,
+      news_feed_id: params.feedId,
+      limit: params.limit,
+      since: params.since,
+      max_distance: params.maxDistance
+    };
+    return this.http.get("/news_items/similar", { ...options, query });
+  }
   async delete(id, options = {}) {
     await this.http.delete(`/news_items/${encodeURIComponent(id)}`, options);
   }
@@ -11788,6 +11799,7 @@ var CRON_JOB_MIN_INTERVAL_MINUTES = 5;
 var CRON_JOB_MIN_TIMEOUT_SECONDS = 5;
 var CRON_JOB_MAX_TIMEOUT_SECONDS = 1200;
 var CRON_JOB_BASE_MAX_TIMEOUT_SECONDS = 120;
+var CRON_VAR_TYPES = Object.freeze(["string", "text", "number", "boolean", "list", "json"]);
 var CRON_JOB_FILTER_COLUMNS = Object.freeze(["name", "enabled", "health", "template_slug"]);
 var CRON_RUN_STATUSES = Object.freeze(["queued", "running", "ok", "error", "timeout", "skipped"]);
 var CRON_RUN_TRIGGERS = Object.freeze(["schedule", "manual", "test"]);
@@ -16643,6 +16655,7 @@ export {
   ChestsNamespace,
   ChestEntriesNamespace,
   CaptionsNamespace,
+  CRON_VAR_TYPES,
   CRON_RUN_TRIGGERS,
   CRON_RUN_STATUSES,
   CRON_RUN_FILTER_COLUMNS,

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

@@ -73,6 +73,30 @@ export interface ListNewsItemsParams extends ListParams<(typeof NEWS_ITEM_FILTER
     /** Only items written at or before this instant (ISO 8601). */
     readonly until?: string;
 }
+/** Parameters of {@link NewsItemsNamespace.similar}: an anchor plus optional narrowing. */
+export type SimilarNewsItemsParams = ({
+    /** Free text to compare against. */
+    readonly text: string;
+    readonly itemId?: undefined;
+} | {
+    /** One of your items to compare against. It never comes back in the results. */
+    readonly itemId: Id;
+    readonly text?: undefined;
+}) & {
+    /** Only items of one feed. */
+    readonly feedId?: Id;
+    /** 1..50, default 10. */
+    readonly limit?: number;
+    /** Only items written at or after this instant (ISO 8601). */
+    readonly since?: string | Date;
+    /** Cosine distance ceiling, 0..1, default 0.35. Lower is stricter. */
+    readonly maxDistance?: number;
+};
+/** A hit of {@link NewsItemsNamespace.similar}: the item plus how far it sits from the anchor. */
+export type SimilarNewsItem = NewsItem & {
+    /** Cosine distance to the anchor: `0` is the same text, `1` unrelated. */
+    readonly distance: number;
+};
 /**
  * `/news_items` - the raw material.
  *
@@ -102,6 +126,22 @@ export declare class NewsItemsNamespace extends Resource {
      * @throws {OmsApiError} 404 when the item is not yours.
      */
     get(id: Id, options?: RequestOptions): Promise<NewsItem>;
+    /**
+     * `GET /news_items/similar` - your items closest in meaning to a text or to
+     * one of your items, nearest first, no paging.
+     *
+     * Meaning, not words: "mesquita de Lisboa" finds an item about the mosque
+     * that never uses the word. Every item gets its vector shortly after it is
+     * written, so a fresh one may still be missing from the results; videos
+     * have none (the news cut from them do).
+     *
+     * @throws {OmsApiError} 400 when neither `text` nor `itemId` is given, `limit`
+     *   is outside 1..50, `maxDistance` outside 0..1, or `since` is not ISO 8601.
+     * @throws {OmsApiError} 404 when `itemId` is not yours.
+     * @throws {OmsApiError} 422 when that item has no vector yet.
+     * @throws {OmsApiError} 502 when `text` cannot be embedded right now.
+     */
+    similar(params: SimilarNewsItemsParams, options?: RequestOptions): Promise<SimilarNewsItem[]>;
     /**
      * `DELETE /news_items/:id`. `204`, empty body.
      *

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

@@ -67,11 +67,25 @@ 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 and the declared variables. */
 export interface CronJobDetail extends CronJob {
     readonly code: string;
     readonly config: Record<string, Json>;
     readonly state: Record<string, Json>;
+    readonly vars: CronVar[];
 }
 export declare const CRON_JOB_FILTER_COLUMNS: readonly ["name", "enabled", "health", "template_slug"];
 export interface ListCronJobsParams extends ListParams<(typeof CRON_JOB_FILTER_COLUMNS)[number]> {
@@ -147,6 +161,8 @@ export interface CronTemplate {
     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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omelhorsite/sdk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "TypeScript SDK for the omelhorsite API. Isolate-safe: no node builtins, no environment access, no stdout.",
   "type": "module",
   "license": "UNLICENSED",