@glidecms/cms-sdk 2.2.0

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.