dsh-tinyfish 0.2.0

package/lib/index.d.mts

@@ -0,0 +1,405 @@
+import z from "@deepseek-ai/schemastery";
+import { WebError, WebFetchProvider, WebFetchRequest, WebFetchResult, WebSearchProvider, WebSearchRequest, WebSearchResult } from "@deepseek-ai/dsh-web";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/client.d.ts
+/**
+ * TinyFish transport for the DSH web capability seam.
+ *
+ * Two channels reach the same upstream:
+ *
+ *   monid  — POST https://api.monid.ai/v1/run  {provider:"tinyfish", …}
+ *            Auth: `Authorization: Bearer <monid platform key>`
+ *            Response: `{ status, output, … }`
+ *
+ *   direct — the TinyFish API directly
+ *            Search: GET  https://api.search.tinyfish.ai?query=…
+ *            Fetch:  POST https://api.fetch.tinyfish.ai
+ *            Auth: `X-API-Key: <tinyfish key>`
+ *            Response: the payload itself
+ *
+ * Monid is a thin envelope: its `output` is byte-for-byte the direct response,
+ * and it forwards the parameter names unchanged (`query`, `location`,
+ * `include_domains`, `after_date`, `urls`, `format`, …). So both channels
+ * normalise to one shape here and the providers above never branch.
+ *
+ * @module dsh-tinyfish/client
+ */
+/** Which upstream route a call takes. */
+type TinyfishChannel = "monid" | "direct";
+/** Monid REST base. */
+export declare const DEFAULT_MONID_BASE = "https://api.monid.ai";
+/** TinyFish's own search and fetch bases. */
+export declare const DEFAULT_SEARCH_BASE = "https://api.search.tinyfish.ai";
+export declare const DEFAULT_FETCH_BASE = "https://api.fetch.tinyfish.ai";
+export declare const WEB_PROVIDER_ERROR = "WEB_PROVIDER_ERROR";
+export declare const WEB_PROVIDER_CREDENTIAL_MISSING = "WEB_PROVIDER_CREDENTIAL_MISSING";
+export declare const WEB_ABORTED = "WEB_ABORTED";
+/** One hit from TinyFish's `/search`. Only the fields this adapter reads. */
+interface TinyfishSearchHit {
+  position?: number;
+  site_name?: string;
+  title?: string;
+  snippet?: string;
+  description?: string;
+  url?: string;
+  date?: string;
+  publisher?: string;
+}
+/** The upstream search payload, byte-identical on both channels. */
+interface TinyfishSearchPayload {
+  query?: string;
+  results?: TinyfishSearchHit[];
+  total_results?: number;
+  page?: number;
+}
+/** One page from TinyFish's `/fetch`. */
+interface TinyfishFetchPage {
+  url?: string;
+  final_url?: string;
+  title?: string;
+  text?: string;
+  published_date?: string;
+  latency_ms?: number;
+}
+/** One per-URL failure from `/fetch`. A 404 arrives here, not in `results`. */
+interface TinyfishFetchFailure {
+  url?: string;
+  error?: string;
+  status?: number;
+}
+/** The upstream fetch payload, byte-identical on both channels. */
+interface TinyfishFetchPayload {
+  results?: TinyfishFetchPage[];
+  errors?: TinyfishFetchFailure[];
+}
+/**
+ * Resolves a stored credential by reference name.
+ *
+ * The shape matches `@deepseek-ai/dsh-credentials`: given a name, return the
+ * stored value or undefined. Passed in rather than imported so the service
+ * stays an optional peer — a host without it falls through to the CLI stores.
+ */
+type CredentialResolver = (name: string) => Promise<string | undefined>;
+/** Inputs for credential resolution, in precedence order. */
+interface ResolveApiKeyOptions {
+  /** Explicit key; wins over everything. */
+  apiKey?: string;
+  /**
+   * Name of a stored credential to ask the harness service for.
+   *
+   * Checked after the literal key and before the ambient environment, because
+   * a stored credential is more specific than whatever happens to be exported.
+   * This is the **direct** channel's ref; the monid channel reads
+   * {@link ResolveApiKeyOptions.monidKeyEnv}.
+   */
+  apiKeyEnv?: string;
+  /**
+   * The monid channel's stored-credential name, kept separate from
+   * {@link ResolveApiKeyOptions.apiKeyEnv} so a user can save both keys.
+   *
+   * One shared ref would hand a TinyFish key to Monid as its bearer token,
+   * which fails upstream as a 401 — indistinguishable from "your Monid key is
+   * wrong". Left unset, the monid channel skips the store and falls through to
+   * its own rungs (`MONID_API_KEY`, `MONID_MCP_TOKEN`, the CLI store).
+   */
+  monidKeyEnv?: string;
+  /** The harness credentials service, when the host provides one. */
+  resolveCredential?: CredentialResolver;
+  /** Override the Monid CLI credential path. */
+  credentialsPath?: string;
+  /** Override the TinyFish CLI config path. */
+  tinyfishConfigPath?: string;
+  /** Environment to read. Defaults to `process.env`; injectable for tests. */
+  env?: Record<string, string | undefined>;
+  /** Caller cancellation, honoured by the async credential lookup. */
+  signal?: AbortSignal;
+}
+/**
+ * Resolve the credential for one channel.
+ *
+ * Explicit config wins, then the environment, then the channel's own
+ * credential store. Stores are re-read per call rather than cached at module
+ * load: they are a few hundred bytes, and caching would pin a rotated key
+ * inside a long-lived host process.
+ */
+export declare function resolveApiKey(channel: TinyfishChannel, options?: ResolveApiKeyOptions): string;
+/** Everything a search call can be pointed at. */
+interface TinyfishSearchOptions extends ResolveApiKeyOptions {
+  channel: TinyfishChannel;
+  query: string;
+  /** Upstream-named filters, already snake_case. */
+  filters?: Record<string, string | number>;
+  monidBase?: string;
+  searchBase?: string;
+  signal?: AbortSignal;
+  attempts?: number;
+  /** Base backoff between attempts, in ms; doubles per attempt. Default 1200. */
+  delayMs?: number;
+  onRetry?: (attempt: number, total: number) => void;
+  /** Poll cadence for an async Monid run. */
+  pollMs?: number;
+  maxPolls?: number;
+}
+/** Everything a fetch call can be pointed at. */
+interface TinyfishFetchOptions extends ResolveApiKeyOptions {
+  channel: TinyfishChannel;
+  urls: string[];
+  /** Goal statement forwarded upstream; TinyFish ranks on it. */
+  purpose?: string;
+  monidBase?: string;
+  fetchBase?: string;
+  signal?: AbortSignal;
+  attempts?: number;
+  /** Base backoff between attempts, in ms; doubles per attempt. Default 1200. */
+  delayMs?: number;
+  onRetry?: (attempt: number, total: number) => void;
+}
+/**
+ * Search TinyFish. Returns the upstream payload for both channels:
+ * `{ query, results[], total_results, page }`.
+ */
+export declare function tinyfishSearch(options: TinyfishSearchOptions): Promise<TinyfishSearchPayload>;
+/**
+ * Fetch up to 10 URLs as clean Markdown. Returns the upstream payload for both
+ * channels: `{ results[], errors[] }`.
+ */
+export declare function tinyfishFetch(options: TinyfishFetchOptions): Promise<TinyfishFetchPayload>;
+//#endregion
+//#region src/provider.d.ts
+/**
+ * The two `ctx.web` providers.
+ *
+ * Both are thin: dispatch through the transport, then normalise TinyFish's
+ * payload into the seam's vocabulary. The seam owns `maxResults` truncation,
+ * cancellation, error codes and the tool card, so nothing here re-implements
+ * any of that.
+ *
+ * @module dsh-tinyfish/provider
+ */
+/** Stable id these providers register under. */
+export declare const TINYFISH_PROVIDER_ID = "tinyfish";
+/** Options a provider snapshots once per operation. */
+interface TinyfishProviderOptions {
+  readonly channel: TinyfishChannel;
+  /** A literal credential, if the settings row carries one. */
+  readonly apiKey?: string;
+  /**
+   * Name of a stored credential or environment variable to read.
+   *
+   * Resolved through the harness credentials service when one is present, so
+   * the value can be rotated or supplied from Settings without editing a patch
+   * file — and without the plugin ever holding a copy.
+   */
+  readonly apiKeyEnv: string;
+  /**
+   * The monid channel's stored-credential name.
+   *
+   * Separate from {@link TinyfishProviderOptions.apiKeyEnv} because the two
+   * channels authenticate against different services, so a user who has both
+   * keys must be able to save both without one overwriting the other.
+   */
+  readonly monidKeyEnv: string;
+  /**
+   * Resolves a stored credential by name, when the host provides a service.
+   *
+   * Built by `apply` from `ctx`, so the plugin uses the *host's* credentials
+   * service instance rather than a private copy — a second instance would have
+   * its own store and never see what the user changed in Settings.
+   */
+  readonly resolveCredential?: CredentialResolver;
+  /** Goal statement forwarded upstream; TinyFish ranks on it. */
+  readonly purpose?: string;
+  /** Upstream-named search filters, already snake_case. */
+  readonly filters: Readonly<Record<string, string>>;
+  readonly attempts: number;
+  readonly monidBase: string;
+  readonly searchBase: string;
+  readonly fetchBase: string;
+  /**
+   * Whether to *offer* this kind. Both providers always register, so a disabled
+   * kind reports itself unavailable rather than missing — `dsh-web` distinguishes
+   * `WEB_PROVIDER_CONFIGURED_MISSING` (a named id that was never registered,
+   * usually a broken install) from `WEB_PROVIDER_UNAVAILABLE` (a registered
+   * provider that declined), and the second is what "I turned this off" means.
+   */
+  readonly search: boolean;
+  readonly fetch: boolean;
+}
+/** Resolves the options for the *next* operation. */
+type TinyfishOptionsSource = () => TinyfishProviderOptions;
+/**
+ * TinyFish reports dates as human strings ("Apr 30, 2026", "1 year ago"), but
+ * `WebSearchSource.publishedAt` is contractually an ISO-8601 string. Rather
+ * than pass a value the type does not promise, coerce what parses and drop the
+ * rest — a missing date is honest, a malformed one is not.
+ *
+ * A date carrying no timezone is read as UTC, not local. `Date.parse("Apr 30,
+ * 2026")` means local midnight, so `.toISOString()` would shift the day for any
+ * host east or west of Greenwich — the same page would report a different
+ * `publishedAt` depending on where the Worker ran. These strings are date-only,
+ * so UTC midnight is both the stable reading and the one that keeps the day the
+ * publisher actually meant.
+ */
+export declare function toIsoDate(value: string | undefined): string | undefined;
+/**
+ * TinyFish search through the `ctx.web` search seam.
+ *
+ * The seam's request is only `{query, maxResults}`; everything else
+ * (`domainType`, `location`, `includeDomains`, …) comes from plugin config and
+ * applies to every query, which is the shape these filters actually want.
+ */
+export declare class TinyfishSearchProvider implements WebSearchProvider {
+  readonly id = "tinyfish";
+  private readonly resolveOptions;
+  /**
+   * @param resolveOptions - a thunk, not a value: the plugin's settings section
+   *   can change between searches, and re-registering the provider to carry a
+   *   new config would make the seam's selection flicker for the user.
+   */
+  constructor(resolveOptions: TinyfishOptionsSource);
+  /**
+   * Cheap local usability check. Must not make network calls — the seam calls
+   * this to decide between providers, and a network call here would turn
+   * selection into a latency spike on every search.
+   *
+   * Checks the same things the shipped providers do: a credential is
+   * resolvable *and* both endpoints parse as URLs. A misconfigured base is a
+   * setup mistake worth surfacing at selection time rather than as a 404 later.
+   */
+  available(): boolean;
+  search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+/**
+ * TinyFish fetch through the `ctx.web` fetch seam.
+ *
+ * Returns `kind: "text"` on purpose: TinyFish already extracts clean Markdown,
+ * so `dsh-tool-web` passes it straight through. The `http` provider instead
+ * returns `kind: "html"` and pays for a turndown conversion this path skips.
+ */
+export declare class TinyfishFetchProvider implements WebFetchProvider {
+  readonly id = "tinyfish";
+  /** A thunk, not a value; see {@link TinyfishSearchProvider} for why. */
+  private readonly resolveOptions;
+  constructor(resolveOptions: TinyfishOptionsSource);
+  /**
+   * Cheap local usability check. Must not make network calls — the seam calls
+   * this to decide between providers, and a network call here would turn
+   * selection into a latency spike on every search.
+   *
+   * Checks the same things the shipped providers do: a credential is
+   * resolvable *and* both endpoints parse as URLs. A misconfigured base is a
+   * setup mistake worth surfacing at selection time rather than as a 404 later.
+   */
+  available(): boolean;
+  fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * `dsh-tinyfish` — TinyFish-backed search and fetch for the DSH web
+ * capability seam.
+ *
+ * Registers two providers under one id, `tinyfish`, and lets the profile pick
+ * the channel:
+ *
+ *   monid  — reach TinyFish through the Monid REST API. Costs nothing on the
+ *            Monid wallet, and reuses the credential the MCP mount already
+ *            holds, so it keeps working when no TinyFish account is configured.
+ *   direct — call TinyFish's own API, using the key the `tinyfish` CLI already
+ *            stored in ~/.tinyfish/config.json.
+ *
+ * Both channels return the same upstream payload, so nothing above this file
+ * branches on which one is active.
+ *
+ * @module dsh-tinyfish
+ */
+/** Settings namespace, matching the `<kind>-<provider>` convention. */
+export declare const WEB_TINYFISH_SETTINGS_NAMESPACE = "web-tinyfish";
+/**
+ * The plugin's settings schema.
+ *
+ * This is the harness's own `@deepseek-ai/schemastery` fork rather than the
+ * public package, because the fork is what implements the `.role()`,
+ * `.volatile()` and `.get()` surface the loader and the settings UI both rely
+ * on, and the public 3.18.x line does not have it. Cordis resolves a plugin's
+ * `Config` through `resolveConfig` and falls back to the raw row when a plugin
+ * exports none — so exporting this is what makes the row render as a real
+ * settings section rather than free-form YAML.
+ *
+ * - `role("secret")` keeps a literal key out of any redacted dump.
+ * - `role("credential-ref")` makes a field a *reference* to a stored
+ *   credential, resolved through `ctx.get("credentials")` — the way the shipped
+ *   search provider does it, so the value is manageable from Settings instead
+ *   of only from a patch file.
+ * - `volatile()` marks a field that must be re-read at the start of every
+ *   operation. Everything here is: a key can be rotated while the harness is
+ *   running, and a provider that captured one at load time would keep sending
+ *   a dead credential.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+  channel: z<"direct" | "monid", "direct" | "monid", "defined">;
+  apiKey: z<string, string, "volatile">;
+  apiKeyEnv: z<string, string, "volatile-defined">;
+  monidKeyEnv: z<string, string, "volatile-defined">;
+  purpose: z<string, string, "volatile">;
+  attempts: z<number, number, "volatile-defined">;
+  filters: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+    domainType: z<"news" | "research_paper" | "web", "news" | "research_paper" | "web", "plain">;
+    language: z<string, string, "plain">;
+    location: z<string, string, "plain">;
+    includeDomains: z<string, string, "plain">;
+    excludeDomains: z<string, string, "plain">;
+  }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+    domainType: z<"news" | "research_paper" | "web", "news" | "research_paper" | "web", "plain">;
+    language: z<string, string, "plain">;
+    location: z<string, string, "plain">;
+    includeDomains: z<string, string, "plain">;
+    excludeDomains: z<string, string, "plain">;
+  }>>>, "volatile">;
+  monidBase: z<string, string, "defined">;
+  searchBase: z<string, string, "defined">;
+  fetchBase: z<string, string, "defined">;
+  search: z<boolean, boolean, "defined">;
+  fetch: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+  channel: z<"direct" | "monid", "direct" | "monid", "defined">;
+  apiKey: z<string, string, "volatile">;
+  apiKeyEnv: z<string, string, "volatile-defined">;
+  monidKeyEnv: z<string, string, "volatile-defined">;
+  purpose: z<string, string, "volatile">;
+  attempts: z<number, number, "volatile-defined">;
+  filters: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+    domainType: z<"news" | "research_paper" | "web", "news" | "research_paper" | "web", "plain">;
+    language: z<string, string, "plain">;
+    location: z<string, string, "plain">;
+    includeDomains: z<string, string, "plain">;
+    excludeDomains: z<string, string, "plain">;
+  }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+    domainType: z<"news" | "research_paper" | "web", "news" | "research_paper" | "web", "plain">;
+    language: z<string, string, "plain">;
+    location: z<string, string, "plain">;
+    includeDomains: z<string, string, "plain">;
+    excludeDomains: z<string, string, "plain">;
+  }>>>, "volatile">;
+  monidBase: z<string, string, "defined">;
+  searchBase: z<string, string, "defined">;
+  fetchBase: z<string, string, "defined">;
+  search: z<boolean, boolean, "defined">;
+  fetch: z<boolean, boolean, "defined">;
+}>>, "plain">;
+/** Cordis service dependencies. */
+export declare const inject: string[];
+/** The bundle name. Must equal the manifest `name`: the loader matches on it. */
+export declare const name = "dsh-tinyfish";
+/** Project one resolved section into the options the next operation serves. */
+export declare function resolveOptions(config: unknown, ctx?: Context, env?: Record<string, string | undefined>): TinyfishProviderOptions;
+/**
+ * Register both providers with `ctx.web`.
+ *
+ * Selection stays the profile's call: this plugin only offers `tinyfish`, and
+ * `dsh-web`'s `searchProvider` / `fetchProvider` decide whether it is used.
+ * Reverting is two words in the patch, with this plugin still mounted.
+ */
+export declare function apply(ctx: Context, config?: unknown): void;
+//#endregion
+export { type TinyfishChannel, type TinyfishFetchPayload, type TinyfishOptionsSource, type TinyfishProviderOptions, type TinyfishSearchPayload, WebError };