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/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..fda90c5a4 --- /dev/null +++ b/overlays/APIs/clickup.com/v2-readonly/crud-causality-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml @@ -0,0 +1,56 @@ +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 +- 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..a91029664 --- /dev/null +++ b/overlays/APIs/clickup.com/v2-readonly/pagination-de95e5bf40f54e3752281a771a786854038d683b-overlay.yaml @@ -0,0 +1,43 @@ +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: >- + 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: + paginationSchemes: + workspaceTaskPages: + type: pageNumber + autoDetect: false + description: >- + 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: + - scheme: workspaceTaskPages diff --git a/overlays/README.md b/overlays/README.md index f046174ca..decf898c4 100644 --- a/overlays/README.md +++ b/overlays/README.md @@ -1631,6 +1631,23 @@ 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 + +`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. 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. +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 +to selected Workspaces. OAuth client registration and a real account grant +are pending. This candidate is not complete synchronization certification. + ## Google Tasks deployment without GitLab `catalog/2026-10-08-google-tasks.json` preserves all eleven production entries 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" + } + } + ] +} diff --git a/overlays/tests/CLICKUP_READONLY_PROVENANCE.md b/overlays/tests/CLICKUP_READONLY_PROVENANCE.md new file mode 100644 index 000000000..a14a32409 --- /dev/null +++ b/overlays/tests/CLICKUP_READONLY_PROVENANCE.md @@ -0,0 +1,58 @@ +# 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. + +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. 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 +(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/test_clickup_readonly.py b/overlays/tests/test_clickup_readonly.py new file mode 100644 index 000000000..df2e097ec --- /dev/null +++ b/overlays/tests/test_clickup_readonly.py @@ -0,0 +1,105 @@ +"""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") + # 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.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"]) + + +if __name__ == "__main__": + unittest.main()