Skip to content

Update skill to handle web links and have better pagination guidance #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
andrewmumblebee wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

Update skill to handle web links and have better pagination guidance #79

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0a781da
docs(build-plugin): document webLink paging realm and nextUrl absolut…
andrewmumblebee Jul 1, 2026
cb5d588
docs(build-plugin): warn that body-realm paging needs an object postBody
andrewmumblebee Jul 1, 2026
6e50674
docs(build-plugin): note pageSize is optional in paging config
andrewmumblebee Jul 1, 2026
96410ba
docs(build-plugin): clarify root-array path convention for payload pa…
andrewmumblebee Jul 1, 2026
e308888
docs(build-plugin): replace misleading combined realm-options list wi…
andrewmumblebee Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 38 additions & 2 deletions .claude/skills/build-plugin/references/data-streams.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,8 @@ In OOB dashboard tiles, set the stream parameter in the tile's `dataStream` conf
}
```

> ⚠️ **`postBody` must be a JSON object, not a string, if [`paging`](#pagination) uses `realm: "body"`.** The server writes the page-size/cursor/offset value into the body with a path-based `set` that only runs against an object — against a string `postBody` it silently does nothing, and the request goes out without the paging value, with no error.

---

## expandInnerObjects
Expand Down Expand Up @@ -402,6 +404,29 @@ The `paging` block in `config` controls how SquaredUp fetches multiple pages.
}
```

**Next-URL via `Link` header** — API returns pagination links in a standard HTTP `Link` header (RFC 8288) instead of the body, e.g. GitHub, Checkly:

```json
"paging": {
"mode": "nextUrl",
"pageSize": { "realm": "queryArg", "path": "per_page", "value": "100" },
"in": { "realm": "webLink", "path": "next" }
}
```

> ⚠️ For `realm: "webLink"`, `path` is the link's **rel name** (`next`, `prev`, `last`, `first`), not a JSON path — the server parses the `Link` header and looks up that rel. This differs from every other realm, where `path` is a dot-notation path or header name.

> ⚠️ Whatever value `in` extracts (`payload`, `header`, or `webLink`) is used as the **complete URL for the next request** — it is not appended to `baseUrl`/`endpointPath`. The API must return a fully-qualified URL; a relative path will break pagination.

`pageSize` is optional on every mode — omit it (or set `"pageSize": { "realm": "none" }`) when the API has no separate page-size parameter, e.g. a `nextUrl` response whose URL already encodes the page size:

```json
"paging": {
"mode": "nextUrl",
"in": { "realm": "payload", "path": "pageDetails.nextPageUrl" }
}
```

Comment on lines +407 to +429

@coderabbitai coderabbitai Bot Jul 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Remove the blank line inside the blockquote.

markdownlint will flag this as MD028, so the docs build will fail until the two warning callouts are contiguous.

♻️ Proposed fix 
 > ⚠️ For `realm: "webLink"`, `path` is the link's **rel name** (`next`, `prev`, `last`, `first`), not a JSON path — the server parses the `Link` header and looks up that rel. This differs from every other realm, where `path` is a dot-notation path or header name.
-
 > ⚠️ Whatever value `in` extracts (`payload`, `header`, or `webLink`) is used as the **complete URL for the next request** — it is not appended to `baseUrl`/`endpointPath`. The API must return a fully-qualified URL; a relative path will break pagination.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**Next-URL via `Link` header** — API returns pagination links in a standard HTTP `Link` header (RFC 8288) instead of the body, e.g. GitHub, Checkly:
```json
"paging": {
"mode": "nextUrl",
"pageSize": { "realm": "queryArg", "path": "per_page", "value": "100" },
"in": { "realm": "webLink", "path": "next" }
}
```
> ⚠️ For `realm: "webLink"`, `path` is the link's **rel name** (`next`, `prev`, `last`, `first`), not a JSON path — the server parses the `Link` header and looks up that rel. This differs from every other realm, where `path` is a dot-notation path or header name.
> ⚠️ Whatever value `in` extracts (`payload`, `header`, or `webLink`) is used as the **complete URL for the next request** — it is not appended to `baseUrl`/`endpointPath`. The API must return a fully-qualified URL; a relative path will break pagination.
`pageSize` is optional on every mode — omit it (or set `"pageSize": { "realm": "none" }`) when the API has no separate page-size parameter, e.g. a `nextUrl` response whose URL already encodes the page size:
```json
"paging": {
"mode": "nextUrl",
"in": { "realm": "payload", "path": "pageDetails.nextPageUrl" }
}
```
**Next-URL via `Link` header** — API returns pagination links in a standard HTTP `Link` header (RFC 8288) instead of the body, e.g. GitHub, Checkly:
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 418-418: Blank line inside blockquote

(MD028, no-blanks-blockquote)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude/skills/build-plugin/references/data-streams.md around lines 407 -
429, The markdown block in data-streams.md has an extra blank line between the
two warning callouts, which breaks the contiguous blockquote expected by
markdownlint MD028. Remove the empty line inside the quoted section so the
`Link` header note and the `pageSize` note remain directly adjacent, keeping the
blockquote contiguous without changing the surrounding `paging` examples or the
`realm: "webLink"` guidance.

Source: Linters/SAST tools

**Token** — API returns a cursor/token to send with the next request:

```json
Expand All @@ -428,8 +453,19 @@ The `paging` block in `config` controls how SquaredUp fetches multiple pages.
}
```

`realm` options: `"queryArg"`, `"header"`, `"body"` (POST only), `"payload"`, `"payloadArraySize"`.
`offset.mode`: `"page"` (increments 1,2,3…) or `"row"` (increments by page size).
> For a `payload`/`payloadArraySize` path (`in`, `rowCountIn`), use `"."` to mean "the response body itself is the array" — unlike [`pathToData`](#pathtodata), where a root-level array means omitting the field entirely, an empty/omitted `path` here is not equivalent to `"."`.

**`realm` options differ per field — they are not interchangeable:**

| Field | Valid `realm` values |
| ----------------------------------- | ----------------------------------------- |
| `pageSize` | `none`, `queryArg`, `header`, `body` (POST only) |
| `out` (token/offset) | `queryArg`, `header`, `body` (POST only) |
| `in` on `nextUrl` | `header`, `payload`, `webLink` |
| `in` on `token` | `header`, `payload` |
| `offset.rowCountIn` | `header`, `payload`, `payloadArraySize` |

`offset.mode`: `"page"` (increments 1,2,3…) or `"row"` (increments by the number of rows actually returned, read via `rowCountIn` — not necessarily the configured `pageSize`).

---

Expand Down
Loading