docs: document the public tools/ helpers and types/ (starting with common.ts + payloads.ts)

[IgorShevchik]

🎯 Target: next release (v1.2.0 — see #121).

Context

The public docs site already documents part of the tools/ and types/ surface, under a consistent
convention in docs/content/docs/2.working-with-the-rest-api/:

• Tools → 80.tools-<name>.md, frontmatter category: 'Tools'
• Types → 90.types-<name>.md, frontmatter category: 'Types'
• Each page carries title / description / navigation.title / a links: block pointing at the backing
  source file (rules in .github/contributing/documentation.md).

The gap is that only a subset is covered, and several exported symbols still carry @todo add docs in source
(e.g. tools/index.ts, types/payloads.ts).
Everything below is part of the public contract — it's all re-exported from
packages/jssdk/src/index.ts — so it deserves a page.

tools/ — current coverage vs gaps

Source	Public export	Doc page	Status
tools/text.ts	Text	80.tools-text.md	✅
tools/type.ts	Type	80.tools-type.md	✅
tools/browser.ts	Browser	80.tools-browser.md	✅
tools/use-formatters.ts	useFormatter, FormatterIban, IbanSpecification	80.tools-use-formatters.md	◑ verify FormatterIban/IbanSpecification are covered, not just useFormatter
tools/index.ts	pick, omit, isArrayOfArray, getEnumValue	—	❌ missing (all four have @todo add docs)
tools/environment.ts	Environment, getEnvironment()	—	❌ missing
tools/scroll-size.ts	scroll-size util	—	❌ missing
tools/uuidv7.ts	(internal — surfaced via Text)	—	mention under Text

types/ — current coverage vs gaps

Only 2 of ~17 type modules have a dedicated page (90.types-iresult.md, 90.types-type-b24.md). The two the
request calls out:

• types/common.ts — the foundational building blocks used everywhere:
  scalar aliases (NumberString, ISODate, BoolString, GenderString), the field-metadata shapes (Fields,
  MultiField, MultiFieldArray, UserFieldType), and the DataType enum. No page.
• types/payloads.ts — the REST response envelope: PayloadTime,
  GetPayload, ListPayload, BatchPayload / BatchPayloadResult, SuccessPayload, Payload. SuccessPayload
  already has a good JSDoc; the rest carry @todo / @todo ! add api3 markers, so the v3-envelope story is also
  incomplete in source. No page.

Other undocumented types/* modules (for the overview/follow-ups below): auth, user, slider, handler,
placement/*, crm/*, catalog, bizproc/*, event, plus http/limiters/b24-helper/pull which are only
partially surfaced through the Core / Limiters / Helper / Pull pages.

Proposed placement (where what goes)

Following the existing convention exactly — new files in docs/content/docs/2.working-with-the-rest-api/, copy
frontmatter from the nearest existing page, and add a links: entry to the backing source file:

Tools

New page	Covers	category
80.tools-object-helpers.md	pick, omit, getEnumValue, isArrayOfArray	Tools
80.tools-environment.md	getEnvironment(), Environment enum	Tools
Scroll size	fold a short "Scroll size" section into 80.tools-browser.md (small surface — avoids a near-empty page); split into 80.tools-scroll-size.md only if preferred	Tools

Types

New page	Covers	category
90.types-common.md	all of common.ts (scalars, field shapes, DataType)	Types
90.types-payloads.md	all of payloads.ts (envelope types) + a note on the v2/v3 envelope status	Types
90.types-index.md (or extend the section index)	a types overview table mapping every types/* module → its page (or "internal / surfaced via X"), so the whole directory is navigable	Types

Acceptance criteria

Tools docs

• Add 80.tools-object-helpers.md for pick / omit / getEnumValue / isArrayOfArray, and replace the
  @todo add docs JSDoc in tools/index.ts with real descriptions in the
  same PR (docs ship with code per the contributing guide).
• Add 80.tools-environment.md for getEnvironment() + Environment.
• Decide scroll-size placement (fold into Browser vs own page) and document it.
• Confirm 80.tools-use-formatters.md documents FormatterIban / IbanSpecification, not only useFormatter.

Types docs (the two named files)

• Add 90.types-common.md covering every export of common.ts, with a one-line "where it's used" for the
  non-obvious shapes (MultiField, UserFieldType, DataType).
• Add 90.types-payloads.md covering the envelope types; clarify which fields are v2-only vs v3 and reflect
  (or resolve) the @todo ! add api3 markers in source.

Whole types/ directory

• Add a types overview page that lists every types/* module and links to its page or notes where it's
  surfaced — this is the navigable map for the directory.
• Track per-domain type pages (auth, user, crm, catalog, bizproc, event, placement, pull,
  http, limiters) as follow-up rows; common + payloads are the priority for this release.

Cross-cutting

• Each new page gets accurate links: to its source file and slots into the right .navigation.yml order.
• If any skills/ file references these helpers/types, refresh it in the same PR (agent-facing mirror).

Out of scope

• Per-domain type pages beyond common + payloads — captured as follow-up rows above, not required for v1.2.0.
• Restructuring the existing documented pages.

Related

• Tools source: packages/jssdk/src/tools/
• Types source: packages/jssdk/src/types/ — incl. common.ts, payloads.ts
• Docs conventions: .github/contributing/documentation.md
• Existing reference pattern to copy: 90.types-type-b24.md, 80.tools-text.md
• process: create v1.2.0 milestone and triage open issues against it #121 — v1.2.0 milestone / triage (this targets it)