Feat/sdk targeted list limits (list-limits part of issue #1107)

[mbajji]

The problem

To change how many items a robot's list collects, you currently have to fetch the robot, dig through its workflow, change one number, and send the entire workflow back, every selector, every field, every pagination setting.

The web app's robot editing page doesn't work that way. It sends just the setting you changed. The SDK should be able to do the same.

What this PR adds

const robot = await extractor.getRobot(id);
await robot.setListLimit(25);

That's it. The request body contains nothing else:

{ "limits": [ { "pairIndex": 0, "actionIndex": 0, "argIndex": 0, "limit": 25 } ] }

The three pieces

Robot.setListLimit(limit) — the method most people will use. It looks through the robot's workflow, finds the action that carries a limit, and works out its position for you. You just pass a number.

I did it this way because those positions are decided by the server when it processes the workflow, and they change between robots. Asking users to figure tthem out would be asking them to know something they can't reliably know. Throws a clear error if the robot has no such action.

It covers all three robot types that have a limit:

Robot type	Action	What the limit means
extract	scrapeList	items collected from the list
crawl	crawl	pages crawled
search	search	results returned

Scrape robots store an empty workflow, so they have no limit to set.

Client.updateListLimits(robotId, limits) — the lower-level version, for robots with more than one list, or when you already know the positions.

ListLimitUpdate — the type. It matches the shape the web app already sends (src/api/storage.ts:117), so both clients speak the same language.

Also added examples/list-limit.ts and a row in the README examples table.

Important: needs the server PR first

This depends on getmaxun/maxun PR ##1176, which teaches PUT /api/sdk/robots/:id to understand limits.

Without that, this method silently does nothing. The server returns 200 and ignores the field. I confirmed this against Maxun Cloud before writing any code:

PUT status: 200
limit 10 -> 10 (wanted 7)

So please merge the server PR first, or this looks broken.

How to try it

examples/list-limit.ts creates one robot of each type and prints the stored config before and after each change:

npm install && npm run build
# point .env at a server running the maxun PR 
npx tsx examples/list-limit.ts

Extract robot (scrapeList)
  before  limit=10   listSelector="//article[contains(@class, 'product_pod')]"
  after   limit=25   listSelector="//article[contains(@class, 'product_pod')]"

Crawl robot (crawl)
  before  limit=15   mode="domain", maxDepth=2
  after   limit=50   mode="domain", maxDepth=2

Search robot (search)
  before  limit=8    query="web scraping", provider="duckduckgo"
  after   limit=20   query="web scraping", provider="duckduckgo"

The limit moves; everything beside it is identical.

One snag: examples/package.json is stale — it lists @maxun/extract and @maxun/scrape, which no longer exist on npm, so npm install inside examples/ fails and the maxun-sdk import will not resolve. Running from the repo root as above works. Worth fixing separately.

What I tested

Against a local server with the other PR's code changes applied in maxun repo:

• extract, crawl, and search robots: limit changed on each through
  setListLimit, and again through updateListLimits
• neighbouring config survived every change — fields and listSelector on extract, mode and maxDepth on crawl, query, provider and mode on search
• changed a limit, then changed it again
• robot with two lists: changed one, the other kept its old value
• several limits updated in a single request
• server rejected -1, 0, 2.5, and bad positions; the stored value didn't move
• renaming a robot via meta left the limit alone
  Values were read back through getRobot() after each change, and confirmed
  directly in Postgres rather than trusting the API response:

SELECT recording_meta->>'name' AS name,
       recording_meta->>'type' AS type,
       jsonb_path_query(recording->'workflow', '$[*].what[*].args[*].limit') AS stored_limit
FROM robot WHERE recording_meta->>'id' IN (...);

Phase extract | extract | 10  ->  3
Phase crawl   | crawl   | 15  ->  6
Phase search  | search  |  8  ->  2

[mbajji]

@Reemal786 @J-Nad @Alton8 Hi codeDay labs team. Let me know what you think of the changes so far before we hit merge. Feel free to drop any feedback or add your files right in!