docs(datasources): explain what a subscription costs an app

[farhantariq12b]

JIRA Issue

https://weboo.atlassian.net/browse/PS-2154

Why

The Data Sources page presented subscribe() as "Real-time Data Subscriptions" that "listen to real-time updates on data source changes". Updates are not instant, and nothing on the page said what keeping a subscription open actually does to an app.

That matters beyond wording, because the V3 AI builder fetches this exact file for data source guidance:

// fliplet-studio/src/v3/ai/tools/fetchFlipletDoc.js:37
datasources: { path: 'API/fliplet-datasources.md', title: 'Data Sources JS APIs' },

So the framing reaches generated apps as well as the developers reading it. In PS-2154, one live app subscribed to a data source that had been empty for weeks, kept checking in backgrounded tabs overnight, and carried a second timer of its own on top as a "backup". Every one of those is a pattern the old page invited: it never mentioned cost, showed pause()/resume() only as toys, and demonstrated cleanup as setTimeout(unsubscribe, 30000).

What changed

The section is rewritten around what a reader has to decide, not around how the SDK works internally.

How updates arrive — within about 30 seconds rather than the instant they happen, so design around the delay. If something has to appear the moment it is created, a subscription is the wrong tool.

What a subscription costs your app

• It adds up with people, not with data. 200 people with the screen open means the data source is read around 400 times a minute, whether or not anything has changed.
• An empty data source costs the same as a busy one. The check still runs; there is simply nothing to report.
• It carries on in the background. A screen left open in a background tab keeps checking overnight, on every device that left it open.

Two rules for any screen that stays open

1. Pause while the screen is hidden — full visibilitychange example with the status() guards, and why cleaning up on teardown is not enough on its own.
2. Never add a timer of your own on top — named as the most common mistake, with why it covers nothing extra.

Also: replaced the setTimeout(unsubscribe, 30000) cleanup demo with a real teardown, and renamed setupRealTimeUpdates → subscribeToUpdates in the pagination walkthrough (and its caller) so the second example stops repeating the old framing.

Deliberately not included

The mechanism. An earlier draft of this led with "not a push channel", "no socket", "polled every 30 seconds" — accurate, but it reads as an internal note. Customers read this page too, and what they need is the effect on their app and what to do about it. The 30-second figure stays because it changes how you design a screen; the plumbing behind it does not.

The page also does not document a configurable interval. A change making it settable is written but has not shipped, and documenting an option that does not exist yet is worse than saying nothing.

Files Changed

• docs/API/fliplet-datasources.md — the section rewrite
• docs/.well-known/llms-full.txt — regenerated so the published bundle carries the new text

Testing

Both CI checks run clean locally, from docs/:

• npm run check:docs (build-agent-indexes.mjs --strict) — exit 0
• npm run test:unit — 163 passing, 0 failing

Verified llms-full.txt contains the new section and no longer contains the old wording. Without regenerating it the page would be correct while the published bundle served the old text — the drift cb6d473 ("regenerate llms-full.txt from source (review fix)") already caught once.

llms-v3-libraries.json is deliberately left out: the build rewrites its generatedAt on every run and nothing here affects its content.

Spelling checked against the repo's American English convention (docs/CLAUDE.md).

Risk

• Risk Level: LOW — documentation only, no code paths touched
• Type: Docs (prevention arm of a production incident)

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying fliplet-cli with    Cloudflare Pages

Latest commit:	4429e69
Status:	✅  Deploy successful!
Preview URL:	https://6313bec7.fliplet-cli.pages.dev
Branch Preview URL:	https://docs-subscribe-polling-cost.fliplet-cli.pages.dev

View logs