Skip to Content
Modules

The function find

find(context) takes the cursor of the last good run and the time, and gives back the records it found and the new cursor.

find is the one function of a module. The entry file of the manifest exports it, in TypeScript or in Python.

In TypeScript

import { aBid, aKey, ContractError, fetch, log, theCursor } from "@tommos/module-sdk";

export async function find(context: { cursor: { since?: string } | null; now: string }) {
  const since = theCursor(context, { since: context.now.slice(0, 10) }).since;
  const answer = await fetch(`https://api.example.gov/tenders?from=${since}`);
  const tenders = answer.json() as { id: string; title: string; buyer: string; url: string }[];
  log.read(`the tenders from ${since}`, tenders.length);
  const records = [];
  for (const t of tenders) {
    try {
      records.push(aBid({ source: "example-gov", key: aKey(t.id), matched: "every tender of the register", title: t.title, buyer: { name: t.buyer }, source_url: t.url }));
    } catch (e) {
      if (e instanceof ContractError) records.push(e.record);
      else throw e;
    }
  }
  return { records, cursor: { since: context.now.slice(0, 10) } };
}

TypeScript runs as Node runs it with its types stripped: use plain types, no enum and no namespace.

In Python

from tommos_module import ContractError, a_bid, a_key, fetch, log, the_cursor

def find(context):
    since = the_cursor(context, {"since": context["now"][:10]})["since"]
    tenders = fetch(f"https://api.example.gov/tenders?from={since}").json()
    log.read(f"the tenders from {since}", len(tenders))
    records = []
    for t in tenders:
        try:
            records.append(a_bid(source="example-gov", key=a_key(t["id"]), matched="every tender of the register",
                                 title=t["title"], buyer={"name": t["buyer"]}, source_url=t["url"]))
        except ContractError as e:
            records.append(e.record)
    return {"records": records, "cursor": {"since": context["now"][:10]}}

The context

FieldWhat it holds
cursorThe cursor of the last run that worked, or null on the first run
nowThe time of this run, ISO 8601 in UTC. Use it, never the clock: an example then gives the same records each time

What find gives back

{ "records": [...], "cursor": ... }. The cursor is any JSON you choose: a day, a page token, the newest id. Tommos keeps it only when the run worked; a run that fails keeps the old one, so the next run reads the same part again.

A cursor of a day alone loses a notice posted later on that same day. Keep the keys of the last day with it, as the example does: { "since": "2026-11-10", "keys": ["FN-0005", "FN-0006"] }, and skip only a key of that day you hold.

A run gives at most 5000 records. A record that fails its contract is still worth giving back (e.record): Tommos refuses it with its reason, and the owner reads why in the trial report.

Rules

  • Read only through the tools' fetch: it reaches only the manifest's hosts, waits between calls and tries again.
  • Give the same records for the same answers. A second run from the same cursor must give the same keys (check f).
  • Write a line of what you read with log.read (check e).
  • Give every record its matched: the rule that took it.
  • What find prints is not read. Write to the log through the tools.
  • A module never writes to Tommos. It gives back records, and Tommos decides.

On this page