clarizen-lib/AGENTS.md

AGENTS

Learned User Preferences

• Wants a TypeScript Clarizen client with SDK-style API: new Clarizen(url, apiToken) and namespaced methods (e.g. clarizen.data.entityQuery(...)).
• Wants session authentication via authentication.login(user, pass) that returns an API session for subsequent calls, not only static API tokens.
• May describe requirements in Portuguese as well as English.
• Wants full Clarizen API typings from https://api.clarizen.com/V2.0/services/types/, including nested types (Condition, Expression, Operator, etc.) — not generic JsonObject shortcuts for documented fields.
• When adding types, follow nested type links from the API docs and model every referenced type, not only top-level operation params.
• When extending the SDK, cross-check the Planview Adaptive Work REST API Guide (V2) with live api.clarizen.com docs; apply guide content only when it adds value beyond the live schema pages.
• Wants automatic retry (3 attempts) on all Clarizen HTTP calls except when the API returns SessionTimeout.

Learned Workspace Facts

• ARCO monorepo (RivusLab): clarizen-lib/ is the Clarizen SDK; sibling apps consume @arco/clarizen-lib via npm workspaces or file:../clarizen-lib.
• TypeScript package @arco/clarizen-lib: Clarizen / Planview Adaptive Work REST API V2.0 client.
• Clarizen V2.0 REST on api.clarizen.com is the Planview Adaptive Work API (Clarizen host, same V2.0 surface).
• Target API surface: https://api.clarizen.com/V2.0/services/; operations grouped in namespaces (data, authentication, metadata, etc.).
• Type schemas at https://api.clarizen.com/V2.0/services/types/ drive request/response TypeScript types (e.g. EntityQuery where is Condition, sort is orders not orderBy).
• Secondary reference: Planview Adaptive Work REST API Guide V2 at https://success.planview.com/Planview_AdaptiveWork/API/REST_API_Guide_Version_2
• HTTP auth: Authorization: ApiKey {token} for API keys; Authorization: Session {sessionId} after login.
• All SDK HTTP traffic goes through HttpClient.request; retries are centralized there (3 attempts, no retry on SessionTimeout).
• Multi-tenant session login: loginWithDiscovery calls authentication.getServerDefinition, sets baseUrl from serverLocation, then authentication.login.
• Clarizen.createForLogin(baseUrl?) builds a client without prior auth for the discovery/login flow.
• Entity CRUD is exposed as clarizen.objects (REST under /V2.0/services/data/objects/{typeName}/...).
• API TypeScript types are generated from crawled schema (npm run scrape:types → src/generated/clarizen-schema.json, npm run generate:types → src/clarizen-api-types.ts).
• Planview guide notes live in docs/references/planview-rest-api-v2.md.
• Org metadata catalog: listEntities + describeMetadata with flags: ["fields", "relations"]; clarizen.metadata.fetchCatalog() at runtime; npm run scrape:metadata → src/generated/metadata-catalog.json + metadata-types.ts. Filter out names containing C_ or R_ (custom fields/relations/entities).