From 9b6b9dd8b6b1c941cecc858951bce53a77bed9d9 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 8 Oct 2026 14:37:16 +0200 Subject: [PATCH 1/4] Add ClickUp read-only metadata overlays --- ...54e3752281a771a786854038d683b-overlay.yaml | 49 +++++++++ ...54e3752281a771a786854038d683b-overlay.yaml | 58 ++++++++++ ...54e3752281a771a786854038d683b-overlay.yaml | 30 +++++ overlays/tests/CLICKUP_READONLY_PROVENANCE.md | 47 ++++++++ overlays/tests/runtime_clickup_readonly.mjs | 103 ++++++++++++++++++ overlays/tests/test_clickup_readonly.py | 99 +++++++++++++++++ 6 files changed, 386 insertions(+) create mode 100644 overlays/APIs/clickup.com/v2-readonly/auth-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml create mode 100644 overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml create mode 100644 overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml create mode 100644 overlays/tests/CLICKUP_READONLY_PROVENANCE.md create mode 100644 overlays/tests/runtime_clickup_readonly.mjs create mode 100644 overlays/tests/test_clickup_readonly.py diff --git a/overlays/APIs/clickup.com/v2-readonly/auth-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml b/overlays/APIs/clickup.com/v2-readonly/auth-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml new file mode 100644 index 000000000..0cfb4ce90 --- /dev/null +++ b/overlays/APIs/clickup.com/v2-readonly/auth-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml @@ -0,0 +1,49 @@ +overlay: 1.0.0 +extends: https://raw.githubusercontent.com/ontola/openapi-directory/de95e5bf40f54e3752281a771a786854038d683b/APIs/clickup.com/v2-readonly/openapi.yaml +info: + title: ClickUp read-only OAuth authentication profile + version: 1.0.0 + description: >- + Select the documented OAuth authorization-code flow for reads from + authorized Workspaces. ClickUp tokens grant the Workspaces selected by + the user and do not have selectable scopes; this profile limits the + declared operations to reads but does not narrow the provider token. + OAuth behavior checked against ClickUp's authentication documentation on + 2026-10-08. +actions: +- target: $.components.securitySchemes + update: + clickupReadOnlyOAuth: + type: oauth2 + x-oauth-authentication-details: + authorizationServerMetadata: + token_endpoint_auth_methods_supported: [client_secret_post] + authorizationCode: + pkce: + requirement: unsupported + flows: + authorizationCode: + authorizationUrl: https://app.clickup.com/api + tokenUrl: https://api.clickup.com/api/v2/oauth/token + scopes: {} +- target: $.paths['/v2/team'].get + update: + security: + - clickupReadOnlyOAuth: [] +- target: $.paths['/v2/team/{team_Id}/task'].get + update: + security: + - clickupReadOnlyOAuth: [] +- target: $.paths['/v2/task/{task_id}'].get + update: + security: + - clickupReadOnlyOAuth: [] +- target: $.components + update: + x-authentication-profiles: + clickupReadOnly: + securityScheme: clickupReadOnlyOAuth + description: >- + Read the authorized Workspace list and tasks the user can access. + The provider authorization may cover one or more Workspaces and does + not expose a read-only OAuth scope. diff --git a/overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml b/overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml new file mode 100644 index 000000000..c8bdf13f7 --- /dev/null +++ b/overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml @@ -0,0 +1,58 @@ +overlay: 1.0.0 +extends: https://raw.githubusercontent.com/ontola/openapi-directory/de95e5bf40f54e3752281a771a786854038d683b/APIs/clickup.com/v2-readonly/openapi.yaml +info: + title: ClickUp Workspace and task read causality + version: 1.0.0 + description: >- + Model authorized Workspaces as the root collection and tasks as a + Workspace-scoped child collection. Task.parent remains the provider's + subtask field; it does not imply separate subtask CRUD resources. +actions: +- target: $.components + update: + crudResources: + workspace: + description: A Workspace authorized for the current user. + identity: + # ClickUp has no Workspace item-read endpoint. This identity template + # carries the Workspace id into its child collection request. + urlTemplate: /v2/team/{team_Id} + bindings: + team_Id: + field: id + collections: + workspaces: + urlTemplate: /v2/team + envelope: + itemsField: teams + task: + description: A task the authenticated user can access in a Workspace. + identity: + urlTemplate: /v2/task/{task_id} + bindings: + task_id: + field: id + collections: + workspaceTasks: + urlTemplate: /v2/team/{team_Id}/task + envelope: + itemsField: tasks + x-list-query: + page: 0 +- target: $.paths['/v2/team'].get + update: + x-crud: + action: list + resource: workspace + collection: workspaces +- target: $.paths['/v2/team/{team_Id}/task'].get + update: + x-crud: + action: list + resource: task + collection: workspaceTasks +- target: $.paths['/v2/task/{task_id}'].get + update: + x-crud: + action: read + resource: task diff --git a/overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml b/overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml new file mode 100644 index 000000000..87d1adb88 --- /dev/null +++ b/overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml @@ -0,0 +1,30 @@ +overlay: 1.0.0 +extends: https://raw.githubusercontent.com/ontola/openapi-directory/de95e5bf40f54e3752281a771a786854038d683b/APIs/clickup.com/v2-readonly/openapi.yaml +info: + title: ClickUp filtered Workspace task pagination + version: 1.0.0 + description: >- + ClickUp documents zero-based page numbers and a maximum of 100 tasks per + response. The current API reference declares no continuation field, so + this metadata describes page selection and the response envelope without + asserting a terminal-page signal. +actions: +- target: $.components + update: + paginationSchemes: + workspaceTaskPages: + type: pageNumber + autoDetect: false + description: >- + The page query parameter starts at 0 and responses are capped at + 100 tasks. The API reference does not document a continuation field. + Pagination Schemes defines page-number requests as 1-based and does + not describe a response-less terminal rule, so no page role is + assigned here. + response: + envelope: + itemsField: tasks +- target: $.paths['/v2/team/{team_Id}/task'].get + update: + x-pagination: + - scheme: workspaceTaskPages diff --git a/overlays/tests/CLICKUP_READONLY_PROVENANCE.md b/overlays/tests/CLICKUP_READONLY_PROVENANCE.md new file mode 100644 index 000000000..0b40f5fdc --- /dev/null +++ b/overlays/tests/CLICKUP_READONLY_PROVENANCE.md @@ -0,0 +1,47 @@ +# ClickUp read-only overlay evidence and current limit + +The overlays target the read-only subset at immutable OpenAPI Directory commit +[`de95e5bf40f54e3752281a771a786854038d683b`](https://github.com/ontola/openapi-directory/tree/de95e5bf40f54e3752281a771a786854038d683b/APIs/clickup.com/v2-readonly). +The subset keeps the ClickUp source schemas and examples. Its source examples +do not consistently validate against their declared schemas, so neither the +composition test nor the Syncables fixture treats them as captured-response +validation. + +Authentication metadata follows ClickUp's [authentication guide](https://developer.clickup.com/docs/authentication) +and [Get Access Token reference](https://developer.clickup.com/reference/getaccesstoken), +checked 2026-10-08. The guide documents authorization-code OAuth, the +authorization and token URLs, and says current access tokens do not expire. +The token operation requires `client_id`, `client_secret`, and `code` in the +request body. The profile therefore records `client_secret_post`, no scopes, +and `pkce.requirement: unsupported` because the provider documentation gives +no PKCE support. It defines no refresh URL or refresh-token behavior. The +profile selects three GET operations; ClickUp's user-selected Workspace grant +is broad and provides no read-only scope, so this is only a Local Thought +operation allowlist. + +The [Get Authorized Teams reference](https://developer.clickup.com/reference/getauthorizedteams), +[Get Filtered Team Tasks reference](https://developer.clickup.com/reference/getfilteredteamtasks), +and [Get Task reference](https://developer.clickup.com/reference/gettask) +document the root Workspace list, task collection, and task item routes. The +filtered Workspace task reference documents a zero-based `page` parameter and +a cap of 100 tasks per response. It does not document a response continuation +field. CRUD metadata carries the Workspace ID from a root team record into the +task collection and retains `task.parent` as ordinary task data. + +The pagination limitation is tracked in +[openapi-extensions issue #25](https://github.com/pondersource/openapi-extensions/issues/25). +The current Pagination Schemes page role is 1-based, while ClickUp's `page` is +0-based; it also cannot express “request another page while the prior page +contained 100 items” when the API provides no continuation field. The actual +Syncables fixture records this result: it reaches the task collection at +`page=0`, imports 100 synthetic tasks, and stops without requesting a next +page. This is evidence that the current generic consumer cannot establish a +complete task listing. It is not evidence of provider response validity or a +live ClickUp synchronization. + +Run from the atomic-plugins repository root: + +```sh +python3 overlays/tests/test_clickup_readonly.py +node overlays/tests/runtime_clickup_readonly.mjs +``` diff --git a/overlays/tests/runtime_clickup_readonly.mjs b/overlays/tests/runtime_clickup_readonly.mjs new file mode 100644 index 000000000..adabc35bc --- /dev/null +++ b/overlays/tests/runtime_clickup_readonly.mjs @@ -0,0 +1,103 @@ +#!/usr/bin/env node +// Runs the pinned and composed ClickUp document through the shipped Syncables +// consumer with synthetic provider responses. It makes no provider requests. +import { execFileSync } from 'node:child_process'; +import { readFileSync } from 'node:fs'; +import { dirname, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const here = dirname(fileURLToPath(import.meta.url)); +const repo = resolve(here, '../..'); +const catalog = 'overlays/catalog/2026-10-08-gitlab-tasks-clickup.json'; +const composed = execFileSync( + 'python3', + ['overlays/tests/compose_gitlab_platform.py', 'clickup'], + { + cwd: repo, + env: { ...process.env, ONBOARDING_CATALOG_PATH: catalog }, + encoding: 'utf8', + maxBuffer: 32 * 1024 * 1024, + }, +); +const { prepareDocument, describePlatform, readPlatform } = await import( + '../../syncables/build/src/browser.js' +); +const document = prepareDocument(JSON.parse(composed), []); +const description = describePlatform(document); +const assert = (condition, message) => { + if (!condition) throw new Error(message); +}; + +assert( + JSON.stringify(description.collections) === + JSON.stringify(['workspaces', 'workspaceTasks']), + `Expected root workspace and child task collections; got ${description.collections}`, +); +assert( + description.parameters.length === 0, + `Workspace ID should be supplied by the root workspace records; got ${description.parameters}`, +); +assert( + description.upstream === 'https://api.clickup.com/api', + `Unexpected upstream base: ${description.upstream}`, +); + +const requests = []; +const tasks = Array.from({ length: 100 }, (_, index) => ({ + id: `task-${index}`, + name: `Task ${index}`, + team_id: '1234', + parent: null, +})); +const result = await readPlatform(document, { + platform: 'clickup', + constants: {}, + limits: { maxPages: 4, maxRecords: 1000 }, + transport: async ({ url, method }) => { + assert(method === 'GET', `Expected GET; got ${method}`); + const request = new URL(url.href); + requests.push(request); + if (request.pathname === '/api/v2/team') { + return { + status: 200, + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ teams: [{ id: '1234', name: 'Workspace' }] }), + }; + } + if (request.pathname === '/api/v2/team/1234/task') { + assert(request.searchParams.get('page') === '0', 'The first ClickUp task request must use page 0'); + return { + status: 200, + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ tasks }), + }; + } + throw new Error(`Unexpected ClickUp request ${request.href}`); + }, +}); + +assert(requests.length === 2, `Expected workspace traversal and one task page; got ${requests.length} requests`); +assert(requests[0].href === 'https://api.clickup.com/api/v2/team', 'Workspace request lost the server base path'); +assert( + requests[1].href === 'https://api.clickup.com/api/v2/team/1234/task?page=0', + `Task child must inherit the workspace ID and base path: ${requests[1].href}`, +); +assert(result.errors.length === 0, `Syncables reported errors: ${result.errors.join('; ')}`); +assert( + result.records.filter((record) => record.resource === 'task').length === 100, + 'Syncables must import the 100 tasks returned on the first page', +); + +// ClickUp documents a 100-task response cap, but neither its official +// reference nor the pinned OAD declares a continuation/terminal field. The +// consumer consequently stops after this page. Pagination Schemes gives the +// page role 1-based semantics, so the ClickUp 0-based parameter is left as a +// fixed list query and cannot be incremented by this consumer. +console.log(JSON.stringify({ + collections: description.collections, + inputs: description.parameters, + importedTaskCount: result.records.filter((record) => record.resource === 'task').length, + requests: requests.map(({ href }) => href), + pageIndexIssue: 'ClickUp page is 0-based; the supported pageNumber role is 1-based, so the page parameter cannot be incremented.', + paginationLimit: 'No declared continuation field; Syncables stops after the first page.', +}, null, 2)); diff --git a/overlays/tests/test_clickup_readonly.py b/overlays/tests/test_clickup_readonly.py new file mode 100644 index 000000000..2b5351600 --- /dev/null +++ b/overlays/tests/test_clickup_readonly.py @@ -0,0 +1,99 @@ +"""ClickUp overlay composition and profile checks against the pinned OAD.""" +import json +import os +from pathlib import Path +import subprocess +import sys +import unittest + +import yaml +from openapi_spec_validator import validate + +ROOT = Path(__file__).resolve().parents[1] +REPO = ROOT.parent +CATALOG = "overlays/catalog/2026-10-08-gitlab-tasks-clickup.json" +PIN = "de95e5bf40f54e3752281a771a786854038d683b" + + +def compose(): + raw = subprocess.check_output( + ["python3", "overlays/tests/compose_gitlab_platform.py", "clickup"], + cwd=REPO, + env={**os.environ, "ONBOARDING_CATALOG_PATH": CATALOG}, + ) + return json.loads(raw) + + +class ClickUpOverlayTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.document = compose() + + def test_composed_document_is_valid_and_pinned(self): + # These extension specifications intentionally add unprefixed keys + # under components; the generic OpenAPI validator predates them. + standard_openapi = json.loads(json.dumps(self.document)) + standard_openapi["components"].pop("crudResources", None) + standard_openapi["components"].pop("paginationSchemes", None) + validate(standard_openapi) + entry = next( + item for item in json.loads((REPO / CATALOG).read_text())["platforms"] + if item["name"] == "clickup" + ) + self.assertIn(PIN, entry["openapi"]) + for url in entry["overlays"]: + path = ROOT / url.split("/overlays/", 1)[1] + overlay = yaml.safe_load(path.read_text()) + self.assertIn(PIN, overlay["extends"]) + + def test_oauth_profile_is_read_only_and_has_no_provider_scope(self): + doc = self.document + profile = doc["components"]["x-authentication-profiles"]["clickupReadOnly"] + scheme_name = profile["securityScheme"] + scheme = doc["components"]["securitySchemes"][scheme_name] + self.assertEqual(scheme["flows"]["authorizationCode"]["scopes"], {}) + self.assertEqual( + scheme["flows"]["authorizationCode"]["authorizationUrl"], + "https://app.clickup.com/api", + ) + self.assertEqual( + scheme["flows"]["authorizationCode"]["tokenUrl"], + "https://api.clickup.com/api/v2/oauth/token", + ) + details = scheme["x-oauth-authentication-details"] + self.assertEqual( + details["authorizationServerMetadata"]["token_endpoint_auth_methods_supported"], + ["client_secret_post"], + ) + self.assertEqual(details["authorizationCode"]["pkce"]["requirement"], "unsupported") + expected_paths = { + "/v2/team", + "/v2/team/{team_Id}/task", + "/v2/task/{task_id}", + } + self.assertEqual(set(doc["paths"]), expected_paths) + for path in expected_paths: + self.assertEqual(doc["paths"][path]["get"]["security"], [{scheme_name: []}]) + + def test_crud_traversal_and_page_metadata(self): + doc = self.document + resources = doc["components"]["crudResources"] + self.assertEqual(resources["workspace"]["collections"]["workspaces"]["urlTemplate"], "/v2/team") + self.assertEqual( + resources["workspace"]["collections"]["workspaces"]["envelope"]["itemsField"], + "teams", + ) + self.assertEqual(resources["workspace"]["identity"]["bindings"]["team_Id"]["field"], "id") + tasks = resources["task"]["collections"]["workspaceTasks"] + self.assertEqual(tasks["urlTemplate"], "/v2/team/{team_Id}/task") + self.assertEqual(tasks["envelope"]["itemsField"], "tasks") + self.assertEqual(tasks["x-list-query"], {"page": 0}) + self.assertEqual(doc["paths"]["/v2/team/{team_Id}/task"]["get"]["x-pagination"][0]["scheme"], "workspaceTaskPages") + pagination = doc["components"]["paginationSchemes"]["workspaceTaskPages"] + self.assertNotIn("request", pagination) + self.assertEqual(pagination["response"]["envelope"]["itemsField"], "tasks") + self.assertNotIn("bodyFields", pagination["response"]) + + +if __name__ == "__main__": + unittest.main() From 7b069faacffc754e45c5c2dabfa29f5a94e28bda Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 8 Oct 2026 14:37:58 +0200 Subject: [PATCH 2/4] Prepare ClickUp catalog with explicit pagination blocker --- .../src/identity_catalog_tests.rs | 52 +++++ overlays/README.md | 18 ++ .../2026-10-08-gitlab-tasks-clickup.json | 215 ++++++++++++++++++ 3 files changed, 285 insertions(+) create mode 100644 overlays/catalog/2026-10-08-gitlab-tasks-clickup.json diff --git a/integration-proxy/src/identity_catalog_tests.rs b/integration-proxy/src/identity_catalog_tests.rs index 173c41472..f60233226 100644 --- a/integration-proxy/src/identity_catalog_tests.rs +++ b/integration-proxy/src/identity_catalog_tests.rs @@ -346,3 +346,55 @@ async fn google_tasks_readonly_profile_is_scoped_and_proxy_compatible() { ) .is_none()); } + +/// Prepared ClickUp catalog: proxy-only read restrictions, no invented provider +/// scope. Pagination is blocked pending openapi-extensions#25; this is not a +/// claim of complete import or live OAuth certification. +#[tokio::test] +#[ignore = "downloads pinned candidate sources; set CLICKUP_CATALOG_URL for Pages"] +async fn clickup_read_profile_is_proxy_compatible_without_invented_scopes() { + let client = crate::build_http_client(); + let catalog = if let Ok(url) = std::env::var("CLICKUP_CATALOG_URL") { + Catalog::load(&url, &client).await + } else { + Catalog::load_checked_in_file(&client, "catalog/2026-10-08-gitlab-tasks-clickup.json").await + } + .expect("prepared catalog pins must compose"); + let provider = catalog + .oauth_provider("clickup") + .expect("ClickUp OAuth metadata must parse"); + assert_eq!(provider.authorization_url, "https://app.clickup.com/api"); + assert_eq!( + provider.token_url, + "https://api.clickup.com/api/v2/oauth/token" + ); + assert!( + provider.scopes.is_empty(), + "ClickUp declares no selectable scopes" + ); + assert!( + !provider.use_pkce, + "PKCE support is not documented by ClickUp" + ); + for path in [ + "/api/v2/team", + "/api/v2/team/123/task", + "/api/v2/task/task-1", + ] { + assert!(catalog.allows("clickup", "GET", path).is_some()); + for method in ["POST", "PUT", "PATCH", "DELETE"] { + assert!(catalog.allows("clickup", method, path).is_none()); + } + } + assert!(catalog.allows("clickup", "GET", "/api/v2/user").is_none()); + catalog + .validate_request( + "clickup", + "GET", + "/api/v2/team/123/task", + Some("page=0"), + None, + false, + ) + .expect("zero-based page request must validate"); +} diff --git a/overlays/README.md b/overlays/README.md index 4890a7196..a1e0cae8b 100644 --- a/overlays/README.md +++ b/overlays/README.md @@ -749,3 +749,21 @@ actual two-page Syncables imports for each new platform and both profiles in the proxy parser. The Google Tasks importer fixture is `tests/google_tasks_syncables.test.ts`; its composition checks are `tests/test_google_tasks_readonly.py`. Real-account sync is not certified. + +## ClickUp preparation — pagination blocked + +`catalog/2026-10-08-gitlab-tasks-clickup.json` is a prepared fourteen-entry +candidate. It preserves the thirteen GitLab/Google Tasks entries and adds +three ClickUp GET operations. It is not approved for production activation: +ClickUp's page-number response supplies no documented continuation/count +signal that the current importer can use. A Workspace with more than 100 +matching tasks would stop after its first page. Its zero-based page also +conflicts with the current specification's one-based `page` role, so assigning +that role would skip page zero. The generic specification +gap is recorded in [openapi-extensions#25](https://github.com/pondersource/openapi-extensions/issues/25); +no provider-specific runtime workaround or invented response field is used. + +ClickUp OAuth has no selectable read scopes; the proxy profile limits reads +to these three operations, while the provider token can have broader access +to selected Workspaces. OAuth client registration and a real account grant +are pending. This candidate is not complete synchronization certification. diff --git a/overlays/catalog/2026-10-08-gitlab-tasks-clickup.json b/overlays/catalog/2026-10-08-gitlab-tasks-clickup.json new file mode 100644 index 000000000..bf222e513 --- /dev/null +++ b/overlays/catalog/2026-10-08-gitlab-tasks-clickup.json @@ -0,0 +1,215 @@ +{ + "platforms": [ + { + "name": "github-issues", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/9c5cfb87b3f8b64e11069373a73e3fc85de0de5e/APIs/github.com/github-issues/1.1.4/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/github.com/github-issues/1.1.4/auth-9c5cfb87b3f8b64e11069373a73e3fc85de0de5e-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/github.com/github-issues/1.1.4/pagination-9c5cfb87b3f8b64e11069373a73e3fc85de0de5e-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/github.com/github-issues/1.1.4/repositories-read-9c5cfb87b3f8b64e11069373a73e3fc85de0de5e-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/github.com/github-issues/1.1.4/crud-causality-9c5cfb87b3f8b64e11069373a73e3fc85de0de5e-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/github.com/github-issues/1.1.4/canonical-paths-9c5cfb87b3f8b64e11069373a73e3fc85de0de5e-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/github.com/github-issues/1.1.4/identity-9c5cfb87b3f8b64e11069373a73e3fc85de0de5e-overlay.yaml" + ], + "selection": { + "oauthSecurityScheme": "githubOAuth", + "tenantIdentity": { + "operationId": "getGitHubAuthenticatedPrincipal", + "namespace": "https://github.com" + } + } + }, + { + "name": "google-calendar", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/32237fa5d14aa887dc9f3923395dac971e00a36c/APIs/googleapis.com/calendar/v3/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/googleapis.com/calendar/v3/auth-32237fa5d14aa887dc9f3923395dac971e00a36c-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/googleapis.com/calendar/v3/app-pagination-32237fa5d14aa887dc9f3923395dac971e00a36c-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/googleapis.com/calendar/v3/app-crud-causality-32237fa5d14aa887dc9f3923395dac971e00a36c-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/googleapis.com/calendar/v3/identity-32237fa5d14aa887dc9f3923395dac971e00a36c-overlay.yaml" + ], + "selection": { + "oauthSecurityScheme": "googleOffline", + "tenantIdentity": { + "operationId": "getGoogleAuthenticatedPrincipal", + "namespace": "https://accounts.google.com" + } + } + }, + { + "name": "moneybird", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/85a6105220036a98ef0d7cd6f228d4aae0036508/APIs/moneybird.com/v2-readonly/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/moneybird.com/v2-readonly/auth-85a6105220036a98ef0d7cd6f228d4aae0036508-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/moneybird.com/v2-readonly/pagination-85a6105220036a98ef0d7cd6f228d4aae0036508-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/moneybird.com/v2-readonly/crud-causality-85a6105220036a98ef0d7cd6f228d4aae0036508-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/moneybird.com/v2-readonly/throttling-85a6105220036a98ef0d7cd6f228d4aae0036508-overlay.yaml" + ], + "selection": { + "query_overrides": [ + { + "path": "/{administration_id}/assets.json", + "values": { + "active": false + } + }, + { + "path": "/{administration_id}/contacts/{contact_id}/additional_charges.json", + "values": { + "include_billed": true + } + }, + { + "path": "/{administration_id}/contacts.json", + "values": { + "include_archived": true + } + }, + { + "path": "/{administration_id}/products.json", + "values": { + "active": false + } + }, + { + "path": "/{administration_id}/projects.json", + "values": { + "filter": "state:all" + } + }, + { + "path": "/{administration_id}/subscriptions/{id}/additional_charges.json", + "values": { + "include_billed": true + } + } + ] + } + }, + { + "name": "todoist", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/ac07532b0a0ac101cf8bae2a54177fb1d8ea3779/APIs/todoist.com/1/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/todoist.com/1/auth-ac07532b0a0ac101cf8bae2a54177fb1d8ea3779-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/todoist.com/1/pagination-ac07532b0a0ac101cf8bae2a54177fb1d8ea3779-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/todoist.com/1/crud-causality-ac07532b0a0ac101cf8bae2a54177fb1d8ea3779-overlay.yaml" + ] + }, + { + "name": "spotify", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/2914e6bed4db4389921b36e4ed79e645c2085668/APIs/spotify.com/1.0.0-readonly/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/spotify.com/1.0.0-readonly/auth-2914e6bed4db4389921b36e4ed79e645c2085668-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/spotify.com/1.0.0-readonly/pagination-2914e6bed4db4389921b36e4ed79e645c2085668-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/spotify.com/1.0.0-readonly/crud-causality-2914e6bed4db4389921b36e4ed79e645c2085668-overlay.yaml" + ] + }, + { + "name": "discord", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/9d0d73c6b23cb07ca2d225fb8b3848fede322b21/APIs/discord.com/10/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/discord.com/10/auth-v2-9d0d73c6b23cb07ca2d225fb8b3848fede322b21-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/discord.com/10/pagination-9d0d73c6b23cb07ca2d225fb8b3848fede322b21-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/discord.com/10/crud-causality-9d0d73c6b23cb07ca2d225fb8b3848fede322b21-overlay.yaml" + ], + "selection": { + "authenticationProfile": "discordUser" + } + }, + { + "name": "notion", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/0c8e229623efdcc1d4ab50111d17bcca3214a899/APIs/notion.com/2026-03-11/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/notion.com/2026-03-11/auth-0c8e229623efdcc1d4ab50111d17bcca3214a899-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/notion.com/2026-03-11/pagination-0c8e229623efdcc1d4ab50111d17bcca3214a899-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/notion.com/2026-03-11/crud-causality-0c8e229623efdcc1d4ab50111d17bcca3214a899-overlay.yaml" + ], + "selection": { + "oauthSecurityScheme": "notionOAuth" + } + }, + { + "name": "clockify", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/dd34a70a45c5109479068b4b5d91337baf8822cd/APIs/clockify.me/1.0.0-readonly/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/clockify.me/1.0.0-readonly/crud-causality-dd34a70a45c5109479068b4b5d91337baf8822cd-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/clockify.me/1.0.0-readonly/auth-dd34a70a45c5109479068b4b5d91337baf8822cd-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/clockify.me/1.0.0-readonly/pagination-dd34a70a45c5109479068b4b5d91337baf8822cd-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/clockify.me/1.0.0-readonly/time-entry-write-dd34a70a45c5109479068b4b5d91337baf8822cd-overlay.yaml" + ] + }, + { + "name": "pets", + "openapi": "https://ontola.github.io/atomic-plugins/overlays/pets-demo/1.0.0/openapi.json", + "overlays": [] + }, + { + "name": "asana", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/b58c91d9f59c6a10178916e7948793809edae46d/APIs/asana.com/1.0/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/asana.com/1.0/auth-b58c91d9f59c6a10178916e7948793809edae46d-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/asana.com/1.0/pagination-b58c91d9f59c6a10178916e7948793809edae46d-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/asana.com/1.0/crud-causality-b58c91d9f59c6a10178916e7948793809edae46d-overlay.yaml" + ], + "selection": { + "authenticationProfile": "asanaReadOnly" + } + }, + { + "name": "airtable", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/1f5368e0251bfbaa233860dc8131507c38a4f8b3/APIs/airtable.com/1.0-readonly/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/airtable.com/1.0-readonly/auth-1f5368e0251bfbaa233860dc8131507c38a4f8b3-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/airtable.com/1.0-readonly/pagination-1f5368e0251bfbaa233860dc8131507c38a4f8b3-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/airtable.com/1.0-readonly/crud-causality-1f5368e0251bfbaa233860dc8131507c38a4f8b3-overlay.yaml" + ], + "selection": { + "authenticationProfile": "airtableReadOnly" + } + }, + { + "name": "gitlab", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/f6d7940e9865903b9c99c5c1fc2d57d92811eef4/APIs/gitlab.com/v4-readonly/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/gitlab.com/v4-readonly/auth-f6d7940e9865903b9c99c5c1fc2d57d92811eef4-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/gitlab.com/v4-readonly/pagination-f6d7940e9865903b9c99c5c1fc2d57d92811eef4-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/gitlab.com/v4-readonly/crud-causality-f6d7940e9865903b9c99c5c1fc2d57d92811eef4-overlay.yaml" + ], + "selection": { + "authenticationProfile": "gitlabReadOnly", + "query_overrides": [ + { + "path": "/projects", + "values": { + "membership": true + } + } + ] + } + }, + { + "name": "google-tasks", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/7ca47c73cf2308c9812692b482b3713b397bc88c/APIs/googleapis.com/tasks/v1/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/googleapis.com/tasks/v1/auth-v2-7ca47c73cf2308c9812692b482b3713b397bc88c-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/googleapis.com/tasks/v1/pagination-7ca47c73cf2308c9812692b482b3713b397bc88c-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/googleapis.com/tasks/v1/crud-causality-7ca47c73cf2308c9812692b482b3713b397bc88c-overlay.yaml" + ], + "selection": { + "authenticationProfile": "googleTasksReadOnly" + } + }, + { + "name": "clickup", + "openapi": "https://raw.githubusercontent.com/ontola/openapi-directory/de95e5bf40f54e3752281a771a786854038d683b/APIs/clickup.com/v2-readonly/openapi.yaml", + "overlays": [ + "https://ontola.github.io/atomic-plugins/overlays/APIs/clickup.com/v2-readonly/auth-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml", + "https://ontola.github.io/atomic-plugins/overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml" + ], + "selection": { + "authenticationProfile": "clickupReadOnly" + } + } + ] +} From 13fc4e7923f4f20b03cd39b19423b0a96007b92c Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 9 Oct 2026 00:20:40 +0000 Subject: [PATCH 3/4] ClickUp: zero-based pages with an assumed short-page end (suggestion for #385) Suggested change to #385's unpublished ClickUp overlays, using Pagination Schemes 0.6.0: the task scheme's page field starts at 0 and a page with fewer than 100 tasks ends the list (shortPage size 100, assurance assumed, since ClickUp documents only the cap). The crud overlay drops the fixed x-list-query page 0. The runtime fixture now serves 250 tasks and expects pages 0, 1 and 2, all 250 imported, and a task read that readCollections reports not complete; it needs a Syncables build with the 0.6.0 consumer (#424). Provenance and README updated. Co-Authored-By: Claude Opus 5.5 --- ...54e3752281a771a786854038d683b-overlay.yaml | 2 - ...54e3752281a771a786854038d683b-overlay.yaml | 31 ++++-- overlays/README.md | 16 ++- overlays/tests/CLICKUP_READONLY_PROVENANCE.md | 21 ++-- overlays/tests/runtime_clickup_readonly.mjs | 105 ++++++++++-------- overlays/tests/test_clickup_readonly.py | 10 +- 6 files changed, 107 insertions(+), 78 deletions(-) diff --git a/overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml b/overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml index c8bdf13f7..fda90c5a4 100644 --- a/overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml +++ b/overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml @@ -37,8 +37,6 @@ actions: urlTemplate: /v2/team/{team_Id}/task envelope: itemsField: tasks - x-list-query: - page: 0 - target: $.paths['/v2/team'].get update: x-crud: diff --git a/overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml b/overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml index 87d1adb88..a91029664 100644 --- a/overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml +++ b/overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml @@ -4,10 +4,13 @@ info: title: ClickUp filtered Workspace task pagination version: 1.0.0 description: >- - ClickUp documents zero-based page numbers and a maximum of 100 tasks per - response. The current API reference declares no continuation field, so - this metadata describes page selection and the response envelope without - asserting a terminal-page signal. + Pagination Schemes 0.6.0: ClickUp documents zero-based page numbers + ("Page to fetch (starts at 0)") and "Responses are limited to 100 tasks + per page"; the response holds only `tasks`, with no continuation or + count field. The page role starts at 0, and a page with fewer than 100 + tasks ends the list. ClickUp does not document that a short page is + the last one, so the end is assumed: a read is not complete, and no + absence is inferred from it. actions: - target: $.components update: @@ -16,14 +19,24 @@ actions: type: pageNumber autoDetect: false description: >- - The page query parameter starts at 0 and responses are capped at - 100 tasks. The API reference does not document a continuation field. - Pagination Schemes defines page-number requests as 1-based and does - not describe a response-less terminal rule, so no page role is - assigned here. + page starts at 0; responses are limited to 100 tasks per page; the + response has no continuation or count field + (https://developer.clickup.com/reference/getfilteredteamtasks, + checked 2026-10-08). + request: + queryParameters: + page: + role: page + start: 0 response: envelope: itemsField: tasks + shortPage: + size: 100 + assurance: assumed + description: >- + The reference documents only "Responses are limited to 100 tasks + per page"; it does not say that a short page is the last one. - target: $.paths['/v2/team/{team_Id}/task'].get update: x-pagination: diff --git a/overlays/README.md b/overlays/README.md index a1e0cae8b..208d6966e 100644 --- a/overlays/README.md +++ b/overlays/README.md @@ -750,18 +750,16 @@ the proxy parser. The Google Tasks importer fixture is `tests/google_tasks_syncables.test.ts`; its composition checks are `tests/test_google_tasks_readonly.py`. Real-account sync is not certified. -## ClickUp preparation — pagination blocked +## ClickUp preparation `catalog/2026-10-08-gitlab-tasks-clickup.json` is a prepared fourteen-entry candidate. It preserves the thirteen GitLab/Google Tasks entries and adds -three ClickUp GET operations. It is not approved for production activation: -ClickUp's page-number response supplies no documented continuation/count -signal that the current importer can use. A Workspace with more than 100 -matching tasks would stop after its first page. Its zero-based page also -conflicts with the current specification's one-based `page` role, so assigning -that role would skip page zero. The generic specification -gap is recorded in [openapi-extensions#25](https://github.com/pondersource/openapi-extensions/issues/25); -no provider-specific runtime workaround or invented response field is used. +three ClickUp GET operations. Task pages follow Pagination Schemes 0.6.0: +`page` starts at 0, and a page with fewer than 100 tasks ends the list, with +`assurance: assumed`, since ClickUp documents only the 100-task cap. Every +task read is therefore not complete, and no deletion is inferred from it. +Activation needs a Syncables release that reads `start` and `shortPage`: an +older consumer would ask for page 1 first and skip page 0. ClickUp OAuth has no selectable read scopes; the proxy profile limits reads to these three operations, while the provider token can have broader access diff --git a/overlays/tests/CLICKUP_READONLY_PROVENANCE.md b/overlays/tests/CLICKUP_READONLY_PROVENANCE.md index 0b40f5fdc..8f2fbe2e8 100644 --- a/overlays/tests/CLICKUP_READONLY_PROVENANCE.md +++ b/overlays/tests/CLICKUP_READONLY_PROVENANCE.md @@ -28,16 +28,17 @@ a cap of 100 tasks per response. It does not document a response continuation field. CRUD metadata carries the Workspace ID from a root team record into the task collection and retains `task.parent` as ordinary task data. -The pagination limitation is tracked in -[openapi-extensions issue #25](https://github.com/pondersource/openapi-extensions/issues/25). -The current Pagination Schemes page role is 1-based, while ClickUp's `page` is -0-based; it also cannot express “request another page while the prior page -contained 100 items” when the API provides no continuation field. The actual -Syncables fixture records this result: it reaches the task collection at -`page=0`, imports 100 synthetic tasks, and stops without requesting a next -page. This is evidence that the current generic consumer cannot establish a -complete task listing. It is not evidence of provider response validity or a -live ClickUp synchronization. +Pagination follows Pagination Schemes 0.6.0 (the gap of +[openapi-extensions issue #25](https://github.com/pondersource/openapi-extensions/issues/25)): +the `page` field starts at 0 (`start: 0`), and a page with fewer than 100 +tasks ends the list (`shortPage: { size: 100, assurance: assumed }`). The +assurance is `assumed` because the reference documents only the 100-task cap, +not that a short page is the last one; a task read is therefore never +complete, and no absence is inferred from it. The Syncables fixture serves +250 synthetic tasks: it requests `page=0`, `page=1` and `page=2`, imports all +250, and `readCollections` reports the task read as not complete. This needs +a Syncables release with the 0.6.0 consumer. It is not evidence of provider +response validity or a live ClickUp synchronization. Run from the atomic-plugins repository root: diff --git a/overlays/tests/runtime_clickup_readonly.mjs b/overlays/tests/runtime_clickup_readonly.mjs index adabc35bc..71612da10 100644 --- a/overlays/tests/runtime_clickup_readonly.mjs +++ b/overlays/tests/runtime_clickup_readonly.mjs @@ -19,7 +19,7 @@ const composed = execFileSync( maxBuffer: 32 * 1024 * 1024, }, ); -const { prepareDocument, describePlatform, readPlatform } = await import( +const { prepareDocument, describePlatform, readPlatform, readCollections } = await import( '../../syncables/build/src/browser.js' ); const document = prepareDocument(JSON.parse(composed), []); @@ -42,62 +42,75 @@ assert( `Unexpected upstream base: ${description.upstream}`, ); +// 250 synthetic tasks: pages 0 and 1 full (100 each), page 2 short (50). +const TOTAL = 250; +const PAGE = 100; +const taskPage = (page) => + Array.from({ length: Math.max(0, Math.min(PAGE, TOTAL - page * PAGE)) }, (_, i) => { + const index = page * PAGE + i; + return { id: `task-${index}`, name: `Task ${index}`, team_id: '1234', parent: null }; + }); + const requests = []; -const tasks = Array.from({ length: 100 }, (_, index) => ({ - id: `task-${index}`, - name: `Task ${index}`, - team_id: '1234', - parent: null, -})); +const transport = async ({ url, method }) => { + assert(method === 'GET', `Expected GET; got ${method}`); + const request = new URL(url.href); + requests.push(request); + if (request.pathname === '/api/v2/team') { + return { + status: 200, + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ teams: [{ id: '1234', name: 'Workspace' }] }), + }; + } + if (request.pathname === '/api/v2/team/1234/task') { + const page = Number(request.searchParams.get('page')); + assert(Number.isInteger(page) && page >= 0, `Bad page ${request.searchParams.get('page')}`); + return { + status: 200, + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ tasks: taskPage(page) }), + }; + } + throw new Error(`Unexpected ClickUp request ${request.href}`); +}; + const result = await readPlatform(document, { platform: 'clickup', constants: {}, - limits: { maxPages: 4, maxRecords: 1000 }, - transport: async ({ url, method }) => { - assert(method === 'GET', `Expected GET; got ${method}`); - const request = new URL(url.href); - requests.push(request); - if (request.pathname === '/api/v2/team') { - return { - status: 200, - headers: { 'content-type': 'application/json' }, - body: JSON.stringify({ teams: [{ id: '1234', name: 'Workspace' }] }), - }; - } - if (request.pathname === '/api/v2/team/1234/task') { - assert(request.searchParams.get('page') === '0', 'The first ClickUp task request must use page 0'); - return { - status: 200, - headers: { 'content-type': 'application/json' }, - body: JSON.stringify({ tasks }), - }; - } - throw new Error(`Unexpected ClickUp request ${request.href}`); - }, + limits: { maxRecords: 1000 }, + transport, }); -assert(requests.length === 2, `Expected workspace traversal and one task page; got ${requests.length} requests`); -assert(requests[0].href === 'https://api.clickup.com/api/v2/team', 'Workspace request lost the server base path'); +const base = 'https://api.clickup.com/api/v2'; assert( - requests[1].href === 'https://api.clickup.com/api/v2/team/1234/task?page=0', - `Task child must inherit the workspace ID and base path: ${requests[1].href}`, + JSON.stringify(requests.map(({ href }) => href)) === + JSON.stringify([ + `${base}/team`, + `${base}/team/1234/task?page=0`, + `${base}/team/1234/task?page=1`, + `${base}/team/1234/task?page=2`, + ]), + `Expected the workspace read, then task pages 0, 1 and 2 (Pagination Schemes 0.6.0 start: 0, ended by the short page 2); got ${requests.map(({ href }) => href)}`, ); assert(result.errors.length === 0, `Syncables reported errors: ${result.errors.join('; ')}`); -assert( - result.records.filter((record) => record.resource === 'task').length === 100, - 'Syncables must import the 100 tasks returned on the first page', -); +const imported = result.records.filter((record) => record.resource === 'task').length; +assert(imported === TOTAL, `Syncables must import all ${TOTAL} tasks; got ${imported}`); + +// The short-page end is assumed (ClickUp documents only the 100-task cap), +// so the read is not complete: no absence may be inferred from it. +requests.length = 0; +const collections = await readCollections(document, { transport, constants: {} }); +const taskRead = collections.collections.find((snapshot) => snapshot.collection.name === 'workspaceTasks'); +assert(taskRead && taskRead.items.length === TOTAL, 'readCollections must return every task'); +assert(taskRead.complete === false, 'An assumed short-page end must not make the task read complete'); +assert(/assumed, not documented/.test(taskRead.notComplete ?? ''), `Unexpected notComplete: ${taskRead.notComplete}`); -// ClickUp documents a 100-task response cap, but neither its official -// reference nor the pinned OAD declares a continuation/terminal field. The -// consumer consequently stops after this page. Pagination Schemes gives the -// page role 1-based semantics, so the ClickUp 0-based parameter is left as a -// fixed list query and cannot be incremented by this consumer. console.log(JSON.stringify({ collections: description.collections, inputs: description.parameters, - importedTaskCount: result.records.filter((record) => record.resource === 'task').length, - requests: requests.map(({ href }) => href), - pageIndexIssue: 'ClickUp page is 0-based; the supported pageNumber role is 1-based, so the page parameter cannot be incremented.', - paginationLimit: 'No declared continuation field; Syncables stops after the first page.', + importedTaskCount: imported, + taskPagesRequested: [0, 1, 2], + taskReadComplete: taskRead.complete, + notComplete: taskRead.notComplete, }, null, 2)); diff --git a/overlays/tests/test_clickup_readonly.py b/overlays/tests/test_clickup_readonly.py index 2b5351600..df2e097ec 100644 --- a/overlays/tests/test_clickup_readonly.py +++ b/overlays/tests/test_clickup_readonly.py @@ -87,11 +87,17 @@ def test_crud_traversal_and_page_metadata(self): tasks = resources["task"]["collections"]["workspaceTasks"] self.assertEqual(tasks["urlTemplate"], "/v2/team/{team_Id}/task") self.assertEqual(tasks["envelope"]["itemsField"], "tasks") - self.assertEqual(tasks["x-list-query"], {"page": 0}) + # The page number is the scheme's (Pagination Schemes 0.6.0 start: 0), not a fixed query. + self.assertNotIn("x-list-query", tasks) + self.assertNotIn("listQuery", tasks) self.assertEqual(doc["paths"]["/v2/team/{team_Id}/task"]["get"]["x-pagination"][0]["scheme"], "workspaceTaskPages") pagination = doc["components"]["paginationSchemes"]["workspaceTaskPages"] - self.assertNotIn("request", pagination) + self.assertEqual(pagination["request"]["queryParameters"]["page"], {"role": "page", "start": 0}) self.assertEqual(pagination["response"]["envelope"]["itemsField"], "tasks") + self.assertEqual( + {k: v for k, v in pagination["response"]["shortPage"].items() if k != "description"}, + {"size": 100, "assurance": "assumed"}, + ) self.assertNotIn("bodyFields", pagination["response"]) From 1d73c4dec874bdad97261e9791325b11409895a9 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 27 Oct 2026 13:34:04 +0000 Subject: [PATCH 4/4] Validate ClickUp pagination in CI and document a tested npm consumer --- overlays/README.md | 5 +- overlays/tests/CLICKUP_READONLY_PROVENANCE.md | 18 ++- overlays/tests/clickup_syncables.test.ts | 109 ++++++++++++++++ overlays/tests/runtime_clickup_readonly.mjs | 116 ------------------ 4 files changed, 126 insertions(+), 122 deletions(-) create mode 100644 overlays/tests/clickup_syncables.test.ts delete mode 100644 overlays/tests/runtime_clickup_readonly.mjs diff --git a/overlays/README.md b/overlays/README.md index a160f7a0e..decf898c4 100644 --- a/overlays/README.md +++ b/overlays/README.md @@ -1639,8 +1639,9 @@ three ClickUp GET operations. Task pages follow Pagination Schemes 0.6.0: `page` starts at 0, and a page with fewer than 100 tasks ends the list, with `assurance: assumed`, since ClickUp documents only the 100-task cap. Every task read is therefore not complete, and no deletion is inferred from it. -Activation needs a Syncables release that reads `start` and `shortPage`: an -older consumer would ask for page 1 first and skip page 0. +Consumer validation passes with published Syncables 0.25.0 on Node 22 and +the current repository source. Use that verified release: the published +0.21.0 package still asks for page 1 first and skips page 0. ClickUp OAuth has no selectable read scopes; the proxy profile limits reads to these three operations, while the provider token can have broader access diff --git a/overlays/tests/CLICKUP_READONLY_PROVENANCE.md b/overlays/tests/CLICKUP_READONLY_PROVENANCE.md index 8f2fbe2e8..a14a32409 100644 --- a/overlays/tests/CLICKUP_READONLY_PROVENANCE.md +++ b/overlays/tests/CLICKUP_READONLY_PROVENANCE.md @@ -36,13 +36,23 @@ assurance is `assumed` because the reference documents only the 100-task cap, not that a short page is the last one; a task read is therefore never complete, and no absence is inferred from it. The Syncables fixture serves 250 synthetic tasks: it requests `page=0`, `page=1` and `page=2`, imports all -250, and `readCollections` reports the task read as not complete. This needs -a Syncables release with the 0.6.0 consumer. It is not evidence of provider -response validity or a live ClickUp synchronization. +250, and `readCollections` reports the task read as not complete. The fixture +passes against the current repository source and the actual published +Syncables 0.25.0 package on Node 22.23.4. The published 0.21.0 package fails +the same fixture by requesting page 1 first; a source merge or version label +alone does not establish consumer support. Use the verified 0.25.0 release. +This is not evidence of provider response validity or a live ClickUp synchronization. Run from the atomic-plugins repository root: ```sh python3 overlays/tests/test_clickup_readonly.py -node overlays/tests/runtime_clickup_readonly.mjs +(cd syncables && npx vitest run --root .. overlays/tests/clickup_syncables.test.ts) +``` + +To check the actual published consumer, use Node 22 and an isolated install: + +```sh +npm install --prefix /tmp/clickup-consumer-check --ignore-scripts syncables@0.25.0 +(cd syncables && SYNCABLES_TEST_MODULE=/tmp/clickup-consumer-check/node_modules/syncables/build/src/browser.js npx vitest run --root .. overlays/tests/clickup_syncables.test.ts) ``` diff --git a/overlays/tests/clickup_syncables.test.ts b/overlays/tests/clickup_syncables.test.ts new file mode 100644 index 000000000..e099b4649 --- /dev/null +++ b/overlays/tests/clickup_syncables.test.ts @@ -0,0 +1,109 @@ +import { execFileSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; +import type { Transport } from "../../syncables/src/browser.js"; +import type { OpenApiDocument } from "../../syncables/src/openapi/types.js"; + +// Also exercise an installed npm release with this same fixture; the source +// version number alone does not establish which consumer was published. +const consumer = process.env.SYNCABLES_TEST_MODULE + ? await import(/* @vite-ignore */ process.env.SYNCABLES_TEST_MODULE) + : await import("../../syncables/src/browser.js"); +const { prepareDocument, describePlatform, readPlatform, readCollections } = + consumer as typeof import("../../syncables/src/browser.js"); + +// Compose the candidate's real immutable OAD and overlay pins. Only the +// provider responses below are synthetic; no ClickUp request is made. +const repo = fileURLToPath(new URL("../../", import.meta.url)); +const document = prepareDocument( + JSON.parse( + execFileSync( + "python3", + ["overlays/tests/compose_gitlab_platform.py", "clickup"], + { + cwd: repo, + env: { + ...process.env, + ONBOARDING_CATALOG_PATH: + "overlays/catalog/2026-10-08-gitlab-tasks-clickup.json", + }, + encoding: "utf8", + maxBuffer: 32 * 1024 * 1024, + }, + ), + ) as OpenApiDocument, + [], +); + +describe("ClickUp Syncables read metadata", () => { + it("reads from page zero without claiming an assumed short-page end is complete", async () => { + const description = describePlatform(document); + expect(description.collections).toEqual(["workspaces", "workspaceTasks"]); + expect(description.parameters).toEqual([]); + expect(description.upstream).toBe("https://api.clickup.com/api"); + + const total = 250; + const pageSize = 100; + const requests: string[] = []; + const transport: Transport = async ({ url, method }) => { + expect(method).toBe("GET"); + requests.push(url.href); + let body: unknown; + + if (url.pathname === "/api/v2/team") { + body = { teams: [{ id: "1234", name: "Workspace" }] }; + } else if (url.pathname === "/api/v2/team/1234/task") { + const page = Number(url.searchParams.get("page")); + expect(Number.isInteger(page) && page >= 0).toBe(true); + body = { + tasks: Array.from( + { + length: Math.max(0, Math.min(pageSize, total - page * pageSize)), + }, + (_, index) => ({ + id: `task-${page * pageSize + index}`, + name: `Task ${page * pageSize + index}`, + team_id: "1234", + parent: null, + }), + ), + }; + } else { + throw new Error(`Unexpected ClickUp request ${url.href}`); + } + + return { + status: 200, + headers: { "content-type": "application/json" }, + body: JSON.stringify(body), + }; + }; + + const result = await readPlatform(document, { + platform: "clickup", + constants: {}, + limits: { maxRecords: 1000 }, + transport, + }); + const base = "https://api.clickup.com/api/v2"; + expect(requests).toEqual([ + `${base}/team`, + `${base}/team/1234/task?page=0`, + `${base}/team/1234/task?page=1`, + `${base}/team/1234/task?page=2`, + ]); + expect(result.errors).toEqual([]); + expect( + result.records.filter((record) => record.resource === "task"), + ).toHaveLength(total); + + // The provider documents the page cap, not that a short page is final. + const read = await readCollections(document, { transport, constants: {} }); + const tasks = read.collections.find( + (snapshot) => snapshot.collection.name === "workspaceTasks", + ); + expect(tasks?.items).toHaveLength(total); + expect(tasks?.complete).toBe(false); + expect(tasks?.notComplete).toMatch(/assumed, not documented/); + }); +}); diff --git a/overlays/tests/runtime_clickup_readonly.mjs b/overlays/tests/runtime_clickup_readonly.mjs deleted file mode 100644 index 71612da10..000000000 --- a/overlays/tests/runtime_clickup_readonly.mjs +++ /dev/null @@ -1,116 +0,0 @@ -#!/usr/bin/env node -// Runs the pinned and composed ClickUp document through the shipped Syncables -// consumer with synthetic provider responses. It makes no provider requests. -import { execFileSync } from 'node:child_process'; -import { readFileSync } from 'node:fs'; -import { dirname, resolve } from 'node:path'; -import { fileURLToPath } from 'node:url'; - -const here = dirname(fileURLToPath(import.meta.url)); -const repo = resolve(here, '../..'); -const catalog = 'overlays/catalog/2026-10-08-gitlab-tasks-clickup.json'; -const composed = execFileSync( - 'python3', - ['overlays/tests/compose_gitlab_platform.py', 'clickup'], - { - cwd: repo, - env: { ...process.env, ONBOARDING_CATALOG_PATH: catalog }, - encoding: 'utf8', - maxBuffer: 32 * 1024 * 1024, - }, -); -const { prepareDocument, describePlatform, readPlatform, readCollections } = await import( - '../../syncables/build/src/browser.js' -); -const document = prepareDocument(JSON.parse(composed), []); -const description = describePlatform(document); -const assert = (condition, message) => { - if (!condition) throw new Error(message); -}; - -assert( - JSON.stringify(description.collections) === - JSON.stringify(['workspaces', 'workspaceTasks']), - `Expected root workspace and child task collections; got ${description.collections}`, -); -assert( - description.parameters.length === 0, - `Workspace ID should be supplied by the root workspace records; got ${description.parameters}`, -); -assert( - description.upstream === 'https://api.clickup.com/api', - `Unexpected upstream base: ${description.upstream}`, -); - -// 250 synthetic tasks: pages 0 and 1 full (100 each), page 2 short (50). -const TOTAL = 250; -const PAGE = 100; -const taskPage = (page) => - Array.from({ length: Math.max(0, Math.min(PAGE, TOTAL - page * PAGE)) }, (_, i) => { - const index = page * PAGE + i; - return { id: `task-${index}`, name: `Task ${index}`, team_id: '1234', parent: null }; - }); - -const requests = []; -const transport = async ({ url, method }) => { - assert(method === 'GET', `Expected GET; got ${method}`); - const request = new URL(url.href); - requests.push(request); - if (request.pathname === '/api/v2/team') { - return { - status: 200, - headers: { 'content-type': 'application/json' }, - body: JSON.stringify({ teams: [{ id: '1234', name: 'Workspace' }] }), - }; - } - if (request.pathname === '/api/v2/team/1234/task') { - const page = Number(request.searchParams.get('page')); - assert(Number.isInteger(page) && page >= 0, `Bad page ${request.searchParams.get('page')}`); - return { - status: 200, - headers: { 'content-type': 'application/json' }, - body: JSON.stringify({ tasks: taskPage(page) }), - }; - } - throw new Error(`Unexpected ClickUp request ${request.href}`); -}; - -const result = await readPlatform(document, { - platform: 'clickup', - constants: {}, - limits: { maxRecords: 1000 }, - transport, -}); - -const base = 'https://api.clickup.com/api/v2'; -assert( - JSON.stringify(requests.map(({ href }) => href)) === - JSON.stringify([ - `${base}/team`, - `${base}/team/1234/task?page=0`, - `${base}/team/1234/task?page=1`, - `${base}/team/1234/task?page=2`, - ]), - `Expected the workspace read, then task pages 0, 1 and 2 (Pagination Schemes 0.6.0 start: 0, ended by the short page 2); got ${requests.map(({ href }) => href)}`, -); -assert(result.errors.length === 0, `Syncables reported errors: ${result.errors.join('; ')}`); -const imported = result.records.filter((record) => record.resource === 'task').length; -assert(imported === TOTAL, `Syncables must import all ${TOTAL} tasks; got ${imported}`); - -// The short-page end is assumed (ClickUp documents only the 100-task cap), -// so the read is not complete: no absence may be inferred from it. -requests.length = 0; -const collections = await readCollections(document, { transport, constants: {} }); -const taskRead = collections.collections.find((snapshot) => snapshot.collection.name === 'workspaceTasks'); -assert(taskRead && taskRead.items.length === TOTAL, 'readCollections must return every task'); -assert(taskRead.complete === false, 'An assumed short-page end must not make the task read complete'); -assert(/assumed, not documented/.test(taskRead.notComplete ?? ''), `Unexpected notComplete: ${taskRead.notComplete}`); - -console.log(JSON.stringify({ - collections: description.collections, - inputs: description.parameters, - importedTaskCount: imported, - taskPagesRequested: [0, 1, 2], - taskReadComplete: taskRead.complete, - notComplete: taskRead.notComplete, -}, null, 2));