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
| Field | What it holds |
|---|---|
cursor | The cursor of the last run that worked, or null on the first run |
now | The 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
findprints is not read. Write to the log through the tools. - A module never writes to Tommos. It gives back records, and Tommos decides.
The contracts
Each record a module gives back holds the contract of its kind, Bid or Prospect, version 1, field by field.
The tools
The tools of Tommos for a module, in TypeScript and in Python: fetch, the cursor, the builders of a bid and a prospect, the domain, the date and the key, the log, and ask.