clarizen-lib/README.md

@arco/clarizen-lib

TypeScript client for the Planview Adaptive Work REST API V2.0.

Human-readable guide: REST API Guide Version 2 — see also docs/references/planview-rest-api-v2.md.

Install (library)

cd clarizen-lib
npm install
npm run build

Use from another package in this repo

From the ARCO root (npm workspaces):

cd /path/to/ARCO
npm install

In your app package.json:

{
  "dependencies": {
    "@arco/clarizen-lib": "workspace:*"
  }
}

Without workspaces (sibling folder):

{
  "dependencies": {
    "@arco/clarizen-lib": "file:../clarizen-lib"
  }
}

Then build the library once (npm run build inside clarizen-lib) and import:

import { Clarizen } from "@arco/clarizen-lib";

Usage

API key (recommended)

import { Clarizen } from "@arco/clarizen-lib";

const clarizen = new Clarizen("https://api.clarizen.com", process.env.CLARIZEN_API_KEY);

const users = await clarizen.data.entityQuery({
  typeName: "User",
  fields: ["Name", "Email"],
  paging: { limit: 10, from: 0 },
});

Or with options:

const clarizen = new Clarizen({
  baseUrl: "https://api.clarizen.com",
  apiToken: process.env.CLARIZEN_API_KEY,
});

Session (username + password)

const clarizen = Clarizen.createForLogin("https://api.clarizen.com");

const { sessionId } = await clarizen.loginWithDiscovery({
  userName: "user@company.com",
  password: "secret",
});

Entity CRUD

const { id } = await clarizen.objects.create("Issue", { title: "Issue 1" });
const issue = await clarizen.objects.get("Issue", id, {
  fields: ["CreatedOn", "CreatedBy.Name"],
});

Or construct directly with an existing session:

const clarizen = new Clarizen({
  baseUrl: "https://api.clarizen.com",
  sessionId: "abc123_28849473",
});

Services

All documented operations are exposed under namespaces:

Namespace	Example
authentication	clarizen.authentication.login({ userName, password })
data	clarizen.data.entityQuery({ typeName, fields })
objects	clarizen.objects.get("Issue", id, { fields: [...] })
metadata	clarizen.metadata.fetchCatalog()
files	clarizen.files.getUploadUrl()
bulk	clarizen.bulk.execute({ ... })
applications	clarizen.applications.getApplicationStatus()
utils	clarizen.utils.sendEMail({ ... })

Generic call:

await clarizen.call("data", "EntityQuery", { typeName: "Project", fields: ["Name"] });

Environment

Copy .env.example to .env:

CLARIZEN_BASE_URL=https://api.clarizen.com
CLARIZEN_API_KEY=...
CLARIZEN_USERNAME=...
CLARIZEN_PASSWORD=...

Examples

npm run example:api-key
npm run example:session

Regenerate endpoints from API docs

npm run scrape

Regenerate API types (60 types, recursive crawl)

Crawls all operations and /V2.0/services/types/*, then generates src/clarizen-api-types.ts:

npm run scrape:types    # writes src/generated/clarizen-schema.json
npm run generate:types  # writes src/clarizen-api-types.ts

Includes Condition, Expression, Query (11 variants), EntityQuery, enums (Operator, ErrorCode, …), and nested types referenced from each page.

Org metadata catalog (runtime + codegen)

Fetches your tenant’s entity types, fields, and relations via listEntities + describeMetadata (flags: ["fields", "relations"]). Custom names containing C_ or R_ are excluded.

Runtime:

const catalog = await clarizen.metadata.fetchCatalog();
const project = catalog.entities.find((e) => e.typeName === "Project");

Regenerate (requires .env credentials):

npm run scrape:metadata   # writes src/generated/metadata-catalog.json + metadata-types.ts
npm run build

Typed entity/field names (after scrape):

import type { EntityTypeName } from "@arco/clarizen-lib";
import { FIELDS_BY_ENTITY, entityFields } from "@arco/clarizen-lib/metadata";

Commit metadata-types.ts (and optionally metadata-catalog.json) when refreshing against your reference tenant.