@glidecms/glide-cms-sdk 2.3.0

package/docs/architecture.md

@@ -0,0 +1,120 @@
+# Architecture overview
+
+This page explains how the SDK is designed, the decisions behind its structure, and how the pieces fit together.
+
+## Three APIs, one SDK
+
+Glide CMS exposes three separate APIs — Composer (content management), Media (images, files, galleries), and Users (accounts, roles, permissions). Each has its own base URL and handles different concerns, but they share the same authentication system.
+
+The SDK creates one `HttpClient` per API endpoint, all sharing a single `TokenProvider`. This means:
+
+- Authentication happens once, tokens are shared across all four APIs
+- Each API gets its own connection pool and request deduplication
+- A 401 on any API triggers a token refresh that benefits all four
+
+```
+Client
+├── TokenProvider (shared)
+│   ├── authenticate() → JWT
+│   └── refresh() → new JWT
+├── HttpClient (composer endpoint)
+│   └── 26 composer clients
+├── HttpClient (media endpoint)
+│   └── 10 media clients
+├── HttpClient (users endpoint)
+│   └── 3 users clients
+└── HttpClient (transmit endpoint)
+    └── 2 transmit clients
+```
+
+## Thin clients over fat services
+
+The v1 SDK had 35 service classes, each 100-600 lines, each creating its own HTTP client and duplicating the same CRUD boilerplate. The v2 uses a `BaseClient<T>` that provides `getById`, `list`, `create`, `update`, and `delete` — most clients are 5-15 lines, only defining custom methods.
+
+A typical client:
+
+```typescript
+class TaxonomyClient extends BaseClient<...> {
+  constructor(http: HttpClient) { super(http, 'taxonomies'); }
+
+  async activate(id: number) { ... }
+  async deactivate(id: number) { ... }
+}
+```
+
+Standard CRUD is inherited. Only `activate` and `deactivate` are custom. This eliminated ~2,000 lines of duplicated code.
+
+## Error hierarchy
+
+Instead of a single `HttpError` class, the SDK uses a typed hierarchy:
+
+```
+GlideError (base)
+├── AuthError (401)
+├── ForbiddenError (403)
+├── NotFoundError (404)
+├── ValidationError (422)
+├── RateLimitError (429)
+├── ServerError (5xx)
+└── NetworkError (0 — DNS, timeout, connection)
+```
+
+This enables `instanceof` checks in catch blocks. Every error carries `statusCode`, `message`, and optionally `requestId` (for correlating with server logs).
+
+The `GlideError.fromResponse(status, body)` factory maps HTTP status codes to the correct subclass. The `HttpClient` calls this automatically — consumers never need to parse raw responses.
+
+## Token management
+
+The SDK handles JWT authentication automatically:
+
+1. On the first API call, it authenticates with username/password and obtains an access token + refresh token
+2. Subsequent calls reuse the cached access token
+3. When the access token expires (checked with a 20-second tolerance), it uses the refresh token to get a new one
+4. When the refresh token expires (8-hour max age), it re-authenticates from scratch
+5. If the server returns 401, the SDK invalidates the token and retries once
+
+Concurrent requests during authentication are deduplicated — if 10 requests arrive while auth is in progress, only one auth call is made and all 10 wait for it.
+
+## Retry and resilience
+
+The `HttpClient` retries on two conditions:
+
+- **5xx server errors** — retried with exponential backoff (500ms, 1s, 2s, ...)
+- **Network errors** — DNS failures, timeouts, connection refused
+
+Client errors (4xx) are never retried (except 401, which triggers token refresh). Every request has a 30-second timeout via `AbortSignal.timeout`.
+
+Aborted requests (`AbortError`) and timed-out requests (`TimeoutError`) are never retried — they propagate immediately to the caller. Only true network failures and 5xx responses enter the retry loop.
+
+GET requests are deduplicated — if the same URL is requested concurrently without per-request opts, only one fetch is made and the result is shared. GETs with per-request `signal` or `timeout` always make independent requests.
+
+## Runtime dependencies
+
+The SDK keeps HTTP/auth dependencies out of the runtime path and uses:
+
+- Native `fetch` for HTTP (Node 18+)
+- Native `crypto.randomUUID` for ID generation (Node 19+)
+- Native `Buffer` for JWT decoding
+- Native `AbortSignal.timeout` for request timeouts
+
+Article body HTML conversion uses `jsdom` through the `@glidecms/glide-cms-sdk/article-body` export. `jsdom` is an optional peer dependency, so main SDK consumers do not install it unless they use HTML body parsing.
+
+## Why ESM
+
+The SDK uses ES modules (`"type": "module"` in package.json). This enables:
+
+- Tree-shaking in bundlers — unused clients are eliminated
+- Native `import`/`export` without transpilation
+- Compatibility with modern Node.js (22+) and all major bundlers
+
+## Design decisions summary
+
+| Decision | Choice | Why |
+|---|---|---|
+| HTTP client | Native `fetch` | Zero deps, works everywhere Node 18+ |
+| Module system | ESM | Tree-shaking, modern standard |
+| Error model | Typed class hierarchy | `instanceof` checks, carries metadata |
+| Auth | Automatic JWT with async mutex | No manual token management |
+| Client pattern | `BaseClient<T>` + composition | Eliminates boilerplate, easy to extend |
+| Retry | Exponential backoff on 5xx/network | Resilient without being aggressive |
+| Naming | `list` not `getList`, camelCase | JavaScript conventions |

package/docs/howto.md

@@ -0,0 +1,422 @@
+# How-to guides
+
+All examples assume you've initialized the client and destructured the service namespaces:
+
+```typescript
+import { Client } from '@glidecms/glide-cms-sdk';
+
+const { composer, media, users, transmit } = new Client({
+  host: 'your-tenant.gcpp.io',
+  username: 'your-username',
+  password: 'your-password',
+  accountId: 1,
+});
+```
+
+---
+
+## How to create and publish articles
+
+Assumes you know your workflow and article type IDs.
+
+> **Important:** The `body` field requires parsed JSON from `parseArticleBody()`, not raw HTML.
+> The `ParsedArticleBody` branded type enforces this at compile time. See [How to convert HTML to article body format](#how-to-convert-html-to-article-body-format).
+
+### Create an article
+
+```typescript
+import { parseArticleBody } from '@glidecms/glide-cms-sdk/article-body';
+
+const body = parseArticleBody('<p>Markets rose sharply today...</p>');
+
+const created = await composer.article.create({
+  headline: 'Breaking: Market Update',
+  articleTypeId: 370,
+  statusId: 4, // Draft
+  contentLocaleId: 1,
+  body,
+});
+
+console.log('Created article:', created.data.id);
+```
+
+### Publish in one step
+
+```typescript
+import { parseArticleBody } from '@glidecms/glide-cms-sdk/article-body';
+
+const workflow = await composer.workflow.getActive();
+const body = parseArticleBody('<p>Markets rose sharply today...</p>');
+
+await composer.article.createAndPublish(
+  {
+    headline: 'Breaking: Market Update',
+    articleTypeId: 370,
+    statusId: 5, // Ready (must be publishable)
+    contentLocaleId: 1,
+    body,
+  },
+  workflow.data,
+);
+```
+
+### Create with a promo image
+
+```typescript
+import { parseArticleBody } from '@glidecms/glide-cms-sdk/article-body';
+
+// Upload image first (see "How to upload images")
+const imageId = '...';
+
+const workflow = await composer.workflow.getActive();
+const body = parseArticleBody('<p>Article content here.</p>');
+
+await composer.article.createAndPublish(
+  {
+    headline: 'Article with Image',
+    articleTypeId: 370,
+    statusId: 5,
+    contentLocaleId: 1,
+    body,
+    additionalItems: {
+      promoDetails: { imageId },
+    },
+  },
+  workflow.data,
+);
+```
+
+### Update and republish
+
+`updateAndPublish()` preserves omitted fields by fetching the latest revision, merging your changes, saving the full revision, then publishing it.
+
+```typescript
+await composer.article.updateAndPublish(
+  articleId,
+  { headline: 'Updated: Market Update' },
+  workflow.data,
+);
+```
+
+### Unpublish and delete
+
+```typescript
+await composer.article.unpublishAndDelete(articleId);
+```
+
+---
+
+## How to convert HTML to article body format
+
+Composer requires article body content in a specific JSON structure. Use `parseArticleBody()` to convert standard HTML.
+
+### Convert HTML
+
+```typescript
+import {
+  parseArticleBody,
+  renderArticleBody,
+  taxonomyMention,
+  IMAGE_PATTERN_REPLACEMENTS,
+} from '@glidecms/glide-cms-sdk/article-body';
+
+// Simple HTML
+const body = parseArticleBody('<p>Hello <strong>world</strong></p>');
+
+// HTML with images — converts <img> tags to Composer's embedded format
+const bodyWithImages = parseArticleBody(htmlFromExternalSource, {
+  patternReplacements: IMAGE_PATTERN_REPLACEMENTS,
+});
+
+const linkedBody = parseArticleBody(`<p>Raised by ${taxonomyMention({
+  id: 28079,
+  name: 'Parliamentary Session',
+  slug: 'parliamentary-session',
+})}</p>`);
+
+const previewHtml = renderArticleBody(linkedBody);
+
+// Use in article creation
+await composer.article.create({
+  headline: 'Imported Article',
+  body: bodyWithImages,
+  articleTypeId: 370,
+  contentLocaleId: 1,
+});
+```
+
+### Custom image patterns
+
+```typescript
+import {
+  parseArticleBody,
+  GLIDE_EXTERNAL_IMAGE_EMBED,
+} from '@glidecms/glide-cms-sdk/article-body';
+
+const body = parseArticleBody(html, {
+  patternReplacements: [
+    {
+      // Match WordPress-style figure/img blocks
+      pattern: /<figure[^>]*>[\s\S]*?<img[^>]*src="([^"]*)"[^>]*\/?>[\\s\\S]*?<\/figure>/gi,
+      replacement: GLIDE_EXTERNAL_IMAGE_EMBED,
+    },
+  ],
+});
+```
+
+---
+
+## How to authenticate with a static token
+
+Use this when you already have a JWT token (e.g., from an external auth system or for testing).
+
+```typescript
+import { Client } from '@glidecms/glide-cms-sdk';
+
+const { composer, media, users } = Client.withAccessToken({
+  host: 'your-tenant.gcpp.io',
+  accessToken: 'eyJhbGciOiJIUzI1NiIs...',
+});
+```
+
+The SDK will use this token for all requests without attempting to refresh it.
+
+---
+
+## How to upload images
+
+Image upload is a two-step process: create the image record, then upload the binary to S3.
+
+```typescript
+// Upload image in one call — creates record, uploads binary, validates response
+const image = await media.image.upload(
+  { name: 'photo.jpg', type: 'image/jpeg' },
+  fs.readFileSync('photo.jpg'),
+);
+```
+
+---
+
+## How to manage live reports
+
+### Create a live report with posts
+
+```typescript
+const report = await composer.liveReport.create({
+  headline: 'Election Night Coverage',
+});
+
+const reportId = report.data.id;
+
+// Add posts
+await composer.liveReportPost.create(reportId, {
+  headline: 'Polls closing in eastern states',
+  body: '<p>First results expected within the hour.</p>',
+});
+
+// Publish the report
+await composer.liveReport.publish(reportId, report.data.latestRevisionId);
+```
+
+### Add a summary
+
+```typescript
+await composer.liveReportSummary.create(reportId, {
+  body: '<p>Key takeaways from tonight...</p>',
+});
+```
+
+---
+
+## How to add logging
+
+Pass any logger compatible with `debug/info/warn/error` methods. Works with `pino`, `winston`, or `console`.
+
+```typescript
+import { Client } from '@glidecms/glide-cms-sdk';
+
+const { composer, media } = new Client({
+  host: 'your-tenant.gcpp.io',
+  username: '...', password: '...', accountId: 1,
+  logger: console, // or pino({ level: 'debug' })
+});
+```
+
+---
+
+## How to set timeout, abort, or override per request
+
+Every method accepts an optional `RequestOpts` as the last argument:
+
+```typescript
+// Custom timeout (default is 30s)
+const images = await media.image.list({ page: 0, size: 5 }, { timeout: 5000 });
+
+// Abort a request
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 10_000);
+const articles = await composer.article.list({ page: 0, size: 10 }, { signal: controller.signal });
+```
+
+**Retry behaviour:** The SDK automatically retries on 5xx server errors and network failures with exponential backoff (3 attempts, 500ms base). Client errors (401, 403, 404, 422) throw immediately and are never retried. A 401 triggers one automatic token refresh before failing.
+
+---
+
+## How to paginate results
+
+```typescript
+const paginator = composer.article.paginate({ size: 50 });
+
+// Iterate pages
+for await (const page of paginator) {
+  console.log(`Page ${page.page}: ${page.items.length} items`);
+}
+
+// Or collect everything
+const all = await composer.article.paginate({ size: 50 }).collectAll();
+```
+
+Fetch one page at a time:
+
+```typescript
+const paginator = composer.article.paginate({ size: 20 });
+const first = await paginator.fetchNext();
+const second = await paginator.fetchNext();
+console.log('Done?', paginator.done);
+```
+
+---
+
+## How to handle errors
+
+All API errors extend `GlideError` and carry `statusCode`, `message`, and optionally `requestId`:
+
+```typescript
+import { GlideError, NotFoundError, AuthError, ValidationError, RateLimitError } from '@glidecms/glide-cms-sdk';
+
+try {
+  await composer.article.get(999999);
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.log('Not found:', err.message);       // 404
+  } else if (err instanceof AuthError) {
+    console.log('Auth failed:', err.message);      // 401
+  } else if (err instanceof ValidationError) {
+    console.log('Validation:', err.details);       // 422
+  } else if (err instanceof RateLimitError) {
+    console.log('Rate limited');                   // 429
+  } else if (err instanceof GlideError) {
+    console.log('API error:', err.statusCode, err.message);
+  }
+}
+```
+
+Error hierarchy: `GlideError` → `AuthError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ValidationError` (422), `RateLimitError` (429), `ServerError` (5xx), `NetworkError` (connection failures), `TimeoutError` (request timeout), `UploadError` (presigned upload failure).
+
+---
+
+## Environment variables
+
+The SDK does not read environment variables. Scripts and tests use these conventions:
+
+**Host-based** (recommended — derives all endpoints from a single domain):
+
+| Variable | Description |
+|---|---|
+| `CMS_HOST` | Base domain (e.g. `your-tenant.gcpp.io`) |
+| `CMS_USERNAME` | Username |
+| `CMS_PASSWORD` | Password |
+| `CMS_ACCOUNT_ID` | Account ID |
+
+**Explicit endpoints** (used in `.env.test` files for non-standard setups):
+
+| Variable | Description |
+|---|---|
+| `COMPOSER_API` | Full composer endpoint URL (e.g. `https://cmp.your-tenant.gcpp.io/v1`) |
+| `MEDIA_API` | Full media endpoint URL |
+| `USERS_API` | Full users endpoint URL |
+
+---
+
+## How to migrate from v1
+
+Upgrading from `@glidecms/glide-typescript-sdk` (v1) to `@glidecms/glide-cms-sdk` (v2).
+
+### Install v2
+
+```bash
+npm uninstall @glidecms/glide-typescript-sdk
+npm install @glidecms/glide-cms-sdk
+```
+
+### Update imports and constructor
+
+```typescript
+// Before
+import { GlideSDK } from '@glidecms/glide-typescript-sdk';
+const sdk = new GlideSDK({
+  COMPOSER_API_ENDPOINT: '...',
+  MEDIA_API_ENDPOINT: '...',
+  USERS_API_ENDPOINT: '...',
+  USERS_USERNAME: '...',
+  USERS_PASSWORD: '...',
+  USERS_ACCOUNT_ID: 1,
+});
+
+// After
+import { Client } from '@glidecms/glide-cms-sdk';
+const { composer, media, users } = new Client({
+  host: 'your-tenant.gcpp.io',
+  username: '...',
+  password: '...',
+  accountId: 1,
+});
+```
+
+### Rename method calls
+
+| v1 method | v2 method |
+|---|---|
+| `.getList(query)` | `.list(query)` |
+| `.getById(id)` | `.getById(id)` (unchanged) |
+| `.getDeactivatedUsers()` | `.listDeactivated()` |
+| `.activateUser(id)` | `.activate(id)` |
+| `.deactivateUser(id)` | `.deactivate(id)` |
+| `.getTagList(query)` | `.list(query)` |
+| `.getRoleTypes()` | `.listTypes()` |
+| `.getWorkflows()` | `.list()` |
+| `.getActiveWorkflow()` | `.getActive()` |
+
+### Update error handling
+
+```typescript
+// Before
+import { HttpError } from '@glidecms/glide-typescript-sdk';
+try { ... } catch (err) {
+  if (err instanceof HttpError) {
+    console.log(err.status, err.body);
+  }
+}
+
+// After
+import { GlideError, NotFoundError, AuthError } from '@glidecms/glide-cms-sdk';
+try { ... } catch (err) {
+  if (err instanceof NotFoundError) {
+    console.log(err.statusCode, err.message, err.requestId);
+  } else if (err instanceof GlideError) {
+    console.log(err.statusCode, err.message);
+  }
+}
+```
+
+### Update access token usage
+
+```typescript
+// Before
+import { GlideSDKAccessToken } from '@glidecms/glide-typescript-sdk';
+const sdk = new GlideSDKAccessToken({ ...config, accessToken: 'tok' });
+
+// After
+import { Client } from '@glidecms/glide-cms-sdk';
+const { composer, media, users } = Client.withAccessToken({ ...config, accessToken: 'tok' });
+```

package/docs/migration.md

@@ -0,0 +1,51 @@
+# CMS SDK Migration Notes
+
+## v2.2.0 Changes
+
+### `partialUpdate()` removed from public API
+
+`partialUpdate()` is no longer callable by consumers. Use `.update()` instead — it preserves fields returned by GET via fetch-merge-put.
+
+```typescript
+// Before (v2):
+await client.composer.article.partialUpdate(id, { statusId: 3 });
+
+// After (v3):
+await client.composer.article.update(id, { statusId: 3 });
+```
+
+`partialUpdateAndPublish()` remains available on ArticleClient for PATCH+publish workflows.
+
+### Per-client update guarantees
+
+| Client | `.update()` preserves | Caller must pass (not in GET) |
+|--------|----------------------|-------------------------------|
+| ArticleClient | All revision fields | — |
+| CollectionClient | name, typeId, statusId | items, description, taxonomies, image |
+| TaxonomyClient | name, slug, active, additionalItems, introText, position, sectionPage, seoData, shortDescription | parentId, image, icon, children, lookupId |
+| AuthorClient | name, slug, about, email, jobTitle, organisation, otherTitle, socialNetworks | image, userId |
+| All others | Nothing (raw PUT) | Everything |
+
+### `CollectionTypeClient.create()` validation
+
+Throws `ValidationError` if `embeddableResources` is empty or missing. Previously silently accepted by the SDK (but broke Publisher).
+
+---
+
+## Article Updates
+
+`composer.article.update(id, payload)` fetches the latest revision, merges supplied fields, and saves via PUT. Omitted fields are preserved.
+
+`ArticleUpdatePayload` is partial — `typeId` and `statusId` are preserved from the latest revision unless overridden.
+
+## Article Body Helpers
+
+`@glidecms/glide-cms-sdk/article-body` includes `renderArticleBody()` and `taxonomyMention()`.
+
+The parser uses `jsdom` as an optional peer dependency. Install it in applications that call `parseArticleBody()` or pass `{ html }` as article body.
+
+## Collection Helpers
+
+`composer.collection.update()` preserves name, typeId, and statusId from the existing collection. Use `addItems`, `addArticles`, `removeItems`, and `removeArticles` for item changes.
+
+Note: `collection.update()` does NOT preserve items or other fields beyond name/typeId/statusId. If you pass a partial payload without items, existing items will be wiped.