@glidecms/cms-sdk 2.2.0

package/docs/reference.md

@@ -0,0 +1,352 @@
+# API Reference
+
+## Client
+
+### Constructor
+
+```typescript
+new Client(config: ClientConfig)
+```
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `host` | `string` | yes* | Base domain — endpoints derived as `https://<svc>.<host>/v1` |
+| `composerApiEndpoint` | `string` | yes* | Override composer endpoint |
+| `mediaApiEndpoint` | `string` | yes* | Override media endpoint |
+| `usersApiEndpoint` | `string` | yes* | Override users endpoint |
+| `transmitApiEndpoint` | `string` | no | Override transmit endpoint |
+| `username` | `string` | yes | Authentication username |
+| `password` | `string` | yes | Authentication password |
+| `accountId` | `number` | yes | Account ID |
+| `logger` | `Logger` | no | Logger instance (pino, winston, console) |
+
+*Provide either `host` (recommended) or the individual endpoint URLs.
+
+Constructor validates config at creation time — throws immediately if `host` (or explicit endpoints), `username`, `password`, or `accountId` is missing or invalid.
+
+### Static methods
+
+**`Client.withAccessToken(config)`** — Create a Client instance using a static JWT token instead of username/password authentication.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `host` | `string` | yes* | Base domain |
+| `composerApiEndpoint` | `string` | yes* | Override composer endpoint |
+| `mediaApiEndpoint` | `string` | yes* | Override media endpoint |
+| `usersApiEndpoint` | `string` | yes* | Override users endpoint |
+| `transmitApiEndpoint` | `string` | no | Override transmit endpoint |
+| `accessToken` | `string` | yes | JWT access token |
+| `logger` | `Logger` | no | Logger instance |
+
+### Instance methods
+
+**`client.discover()`** — Discover available resources on this CMS instance. Returns article types, workflow states, taxonomies, locales, authors, collection types, media counts, user counts, and a `warnings` array for non-critical failures. Composer resource failures throw immediately; media and user count failures are soft.
+
+---
+
+## Composer clients
+
+All composer clients are accessed via `sdk.composer.*`.
+
+### article
+
+| Method | Signature | Description |
+|---|---|---|
+| `getById` | `(id: number) → Promise<IArticleGetByIdResponse>` | Fetch article by ID |
+| `list` | `(query?: IArticleListQueryParameters) → Promise<IArticleListGetResponse>` | List articles with pagination |
+| `create` | `(body) → Promise<IArticleCreateResponse>` | Create article |
+| `update` | `(id, body) → Promise<IArticleUpdateResponse>` | Safe update: fetch latest revision, merge changes, save full PUT |
+| `partialUpdate` | _(internal)_ | Protected. Use `.update()` instead. |
+| `delete` | `(id) → Promise<unknown>` | Delete article |
+| `publish` | `(id, revisionId, payload) → Promise<IArticlePublishResponse>` | Publish a revision |
+| `unpublish` | `(id) → Promise<IArticleUnpublishResponse>` | Unpublish |
+| `schedule` | `(id, revisionId) → Promise<IArticleScheduleResponse>` | Schedule publication |
+| `unschedule` | `(id) → Promise<IArticleUnscheduleResponse>` | Cancel schedule |
+| `getRevisionById` | `(versionId) → Promise<IArticleRevisionGetResponse>` | Fetch a specific revision |
+| `getWithBody` | `(id) → Promise<IArticleGetWithBodyResponse>` | Fetch article metadata and latest revision body |
+| `getRelated` | `(query) → Promise<IRelatedArticlesGetResponse>` | Fetch related articles |
+| `getPreviewData` | `(payload) → Promise<IArticlePreviewDataResponse>` | Get preview data |
+| `getPreviewUrl` | `(id, payload) → Promise<IArticlePreviewUrlResponse>` | Get preview URL |
+| `createAndPublish` | `(payload, workflow) → Promise<void>` | Create + publish in one call |
+| `updateAndPublish` | `(id, payload, workflow) → Promise<void>` | Safe update + publish |
+| `partialUpdateAndPublish` | `(id, payload, workflow?) → Promise<void>` | Direct PATCH; publishes when a workflow is supplied |
+| `unpublishAndDelete` | `(id) → Promise<void>` | Unpublish + delete |
+
+### articleType
+
+| Method | Signature |
+|---|---|
+| `getById` | `(id) → Promise<IArticleTypeGetByIdResponse>` |
+| `list` | `(query?) → Promise<IArticleTypeListGetResponse>` |
+| `create` | `(body) → Promise<IArticleTypeCreatedResponse>` |
+| `update` | `(id, body) → Promise<IArticleTypeUpdateResponse>` |
+| `delete` | `(id) → Promise<unknown>` |
+
+### author
+
+| Method | Signature |
+|---|---|
+| `getById` | `(id) → Promise<IAuthorGetByIdResponse>` |
+| `list` | `(query?) → Promise<IAuthorListGetResponse>` |
+| `create` | `(body) → Promise<IAuthorCreateResponse>` |
+| `update` | `(id, body) → Promise<IAuthorUpdateResponse>` |
+| `delete` | `(id) → Promise<unknown>` |
+
+### taxonomy
+
+| Method | Signature | Description |
+|---|---|---|
+| `getById` | `(id) → Promise<ITaxonomyGetByIdResponse>` | |
+| `list` | `(query?) → Promise<ITaxonomyListGetResponse>` | |
+| `create` | `(body) → Promise<ITaxonomyCreatedResponse>` | |
+| `update` | `(id, body) → Promise<ITaxonomyUpdateResponse>` | |
+| `delete` | `(id) → Promise<unknown>` | |
+| `activate` | `(id) → Promise<ITaxonomyActivateResponse>` | Activate a taxonomy |
+| `deactivate` | `(id) → Promise<ITaxonomyDeactivateResponse>` | Deactivate a taxonomy |
+
+### collection
+
+| Method | Signature |
+|---|---|
+| `getById` | `(id) → Promise<ICollectionGetByIdResponse>` |
+| `list` | `(query?) → Promise<ICollectionListGetResponse>` |
+| `create` | `(body) → Promise<ICollectionCreateResponse>` |
+| `update` | `(id, body) → Promise<ICollectionUpdateResponse>` |
+| `addItems` | `(id, items) → Promise<ICollectionUpdateResponse>` |
+| `addArticles` | `(id, articleIds) → Promise<ICollectionUpdateResponse>` |
+| `removeItems` | `(id, itemIds) → Promise<ICollectionUpdateResponse>` |
+| `removeArticles` | `(id, articleIds) → Promise<ICollectionUpdateResponse>` |
+| `delete` | `(id) → Promise<unknown>` |
+| `publish` | `(id, revisionId) → Promise<ICollectionPublishResponse>` |
+| `unpublish` | `(id) → Promise<ICollectionUnpublishResponse>` |
+| `createAndPublish` | `(payload, workflow) → Promise<void>` |
+| `updateAndPublish` | `(id, payload, workflow) → Promise<void>` |
+| `unpublishAndDelete` | `(id) → Promise<void>` |
+
+### Standard CRUD clients
+
+The following clients share the same base methods: `getById(id)`, `list(query?)`, `create(body)`, `update(id, body)`, `delete(id)`.
+
+| Client | Access | Query params |
+|---|---|---|
+| `collectionType` | `sdk.composer.collectionType` | `ICollectionTypeListQueryParameters` |
+| `contentFilter` | `sdk.composer.contentFilter` | `IContentFilterListQueryParameters` |
+| `contentLocale` | `sdk.composer.contentLocale` | none |
+| `contentPanel` | `sdk.composer.contentPanel` | none |
+| `contentTag` | `sdk.composer.contentTag` | `IContentTagListQueryParameters` |
+| `customFieldGroup` | `sdk.composer.customFieldGroup` | `ICustomFieldGroupListQueryParameters` |
+| `htmlSnippet` | `sdk.composer.htmlSnippet` | none |
+| `liveReportType` | `sdk.composer.liveReportType` | `ILiveReportTypeListQueryParameters` |
+| `menu` | `sdk.composer.menu` | none |
+| `pathRedirect` | `sdk.composer.pathRedirect` | `IPathRedirectListQueryParameters` |
+
+Additional methods on specific clients:
+
+| Client | Extra methods |
+|---|---|
+| `contentFilter` | `setDefault(id)`, `clearDefault(id)` |
+| `pathRedirect` | `bulkCreate(payload)` |
+
+### Publishable clients
+
+These clients add `publish(id, ...)` and `unpublish(id)` on top of standard CRUD:
+
+| Client | Publish signature |
+|---|---|
+| `page` | `publish(id)`, `unpublish(id)` |
+| `template` | `publish(id, versionId)`, `unpublish(id)` |
+| `liveReport` | `publish(id, revisionId)`, `unpublish(id)`, `getRelated(id, revisionId, query)` |
+| `verifyAccessBundle` | `publish(id, versionId)`, `unpublish(id)`, `getVersion(versionId)` |
+
+### Special clients
+
+**`liveReportPost`** — Nested under a live report. All methods take `reportId` as first argument.
+
+| Method | Signature |
+|---|---|
+| `getById` | `(reportId, postId) → Promise<...>` |
+| `list` | `(reportId, query?) → Promise<...>` |
+| `create` | `(reportId, payload) → Promise<...>` |
+| `update` | `(reportId, postId, payload) → Promise<...>` |
+| `delete` | `(reportId, postId) → Promise<...>` |
+| `publish` | `(reportId, postId) → Promise<...>` |
+| `unpublish` | `(reportId, postId) → Promise<...>` |
+
+**`liveReportSummary`** — Nested under a live report. Methods take `reportId`.
+
+| Method | Signature |
+|---|---|
+| `getById` | `(reportId) → Promise<...>` |
+| `create` | `(reportId, payload) → Promise<...>` |
+| `update` | `(reportId, payload) → Promise<...>` |
+| `delete` | `(reportId) → Promise<...>` |
+| `publish` | `(reportId) → Promise<...>` |
+| `unpublish` | `(reportId) → Promise<...>` |
+
+**`resourceLock`** — Resource locking by type and ID.
+
+| Method | Signature |
+|---|---|
+| `get` | `(resourceType, resourceId) → Promise<...>` |
+| `create` | `(resourceType, resourceId) → Promise<...>` |
+| `delete` | `(resourceType, resourceId) → Promise<...>` |
+| `revoke` | `(resourceType, resourceId) → Promise<...>` |
+
+**`workflow`** — Read-only.
+
+| Method | Signature |
+|---|---|
+| `list` | `() → Promise<IWorkflowsResponse>` |
+| `getActive` | `() → Promise<IActiveWorkflowResponse>` |
+
+**`systemWidget`** — No `getById`. Methods: `list()`, `create(payload)`, `update(id, payload)`, `delete(id)`.
+
+**`thirdPartyWidget`** — No `getById`. Methods: `list()`, `create(payload)`, `update(id, payload)`, `delete(id)`.
+
+---
+
+## Media clients
+
+All media clients are accessed via `sdk.media.*`.
+
+### image
+
+| Method | Signature |
+|---|---|
+| `getById` | `(id: string) → Promise<IImageGetResponse>` |
+| `list` | `(query?) → Promise<IImageListResponse>` |
+| `create` | `(body) → Promise<IImageCreateResponse>` |
+| `update` | `(id, body) → Promise<IImageUpdateResponse>` |
+| `delete` | `(id) → Promise<unknown>` |
+| `upload` | `(meta, body, opts?) → Promise<IImageCreateResponse>` |
+| ~~`uploadToS3`~~ | Deprecated — use `upload()` instead |
+
+### file
+
+| Method | Signature |
+|---|---|
+| `getById` | `(id: string) → Promise<IFileGetByIdResponse>` |
+| `list` | `(query?) → Promise<IFilesListGetResponse>` |
+| `create` | `(body) → Promise<IFileCreateResponse>` |
+| `update` | `(id, body) → Promise<IFileUpdateResponse>` |
+| `delete` | `(id) → Promise<unknown>` |
+| `upload` | `(meta, body, opts?) → Promise<IFileCreateResponse>` |
+| ~~`uploadToS3`~~ | Deprecated — use `upload()` instead |
+
+### gallery
+
+| Method | Signature |
+|---|---|
+| `getById` | `(id: number) → Promise<IGalleryGetResponse>` |
+| `list` | `(query?) → Promise<IGalleryListResponse>` |
+| `create` | `(body) → Promise<IGalleryCreateResponse>` |
+| `delete` | `(id) → Promise<unknown>` |
+| `createRevision` | `(id, payload) → Promise<IGalleryRevisionCreateResponse>` |
+| `getRevision` | `(id, revisionId) → Promise<IGalleryGetResponse>` |
+| `publish` | `(id, revisionId) → Promise<IGalleryPublishResponse>` |
+| `unpublish` | `(id, revisionId) → Promise<IGalleryUnpublishResponse>` |
+
+### folder
+
+Standard CRUD: `getById(id)`, `list()`, `create(body)`, `update(id, body)`, `delete(id)`.
+
+### tag
+
+| Method | Signature |
+|---|---|
+| `list` | `(query?) → Promise<ITagListResponse>` |
+| `assign` | `(imageId, tagNames[]) → Promise<IAssignTagResponse>` |
+| `update` | `(imageId, tagId, payload) → Promise<IUpdateTagResponse>` |
+| `delete` | `(imageId, tagId) → Promise<IDeleteTagResponse>` |
+
+---
+
+## Users clients
+
+All users clients are accessed via `sdk.users.*`.
+
+### user
+
+| Method | Signature |
+|---|---|
+| `getById` | `(id) → Promise<IUsersGetByIdResponse>` |
+| `list` | `(query?) → Promise<IUserListGetResponse>` |
+| `create` | `(body) → Promise<IUsersCreateResponse>` |
+| `update` | `(id, body) → Promise<IUsersUpdateResponse>` |
+| `delete` | `(id) → Promise<unknown>` |
+| `listDeactivated` | `() → Promise<IUsersGetDeactivatedResponse>` |
+| `basicProjection` | `(query) → Promise<IBasicProjectionGetResponse>` |
+| `changePassword` | `(id, payload) → Promise<IUserChangePasswordResponse>` |
+| `activate` | `(id) → Promise<IUserActivateResponse>` |
+| `deactivate` | `(id) → Promise<IUserDeactivateResponse>` |
+
+### role
+
+| Method | Signature |
+|---|---|
+| `getById` | `(id) → Promise<IRolesGetByIdResponse>` |
+| `list` | `() → Promise<IRolesGetListResponse>` |
+| `create` | `(body) → Promise<IRolesCreateResponse>` |
+| `update` | `(id, body) → Promise<IRolesUpdateResponse>` |
+| `delete` | `(id) → Promise<unknown>` |
+| `listTypes` | `() → Promise<IRoleTypesGetListResponse>` |
+
+### permission
+
+| Method | Signature |
+|---|---|
+| `list` | `() → Promise<IPermissionGetListResponse>` |
+
+---
+
+## Error classes
+
+All errors extend `GlideError` which extends `Error`. Every error carries:
+
+| Property | Type | Description |
+|---|---|---|
+| `message` | `string` | Human-readable error message |
+| `statusCode` | `number` | HTTP status code (0 for network errors) |
+| `requestId` | `string?` | Server request ID for debugging |
+| `details` | `unknown?` | Additional error details (validation errors) |
+
+| Class | Status code | When |
+|---|---|---|
+| `AuthError` | 401 | Invalid or expired credentials |
+| `ForbiddenError` | 403 | Authenticated but not authorized |
+| `NotFoundError` | 404 | Resource doesn't exist |
+| `ValidationError` | 422 | Request body failed validation |
+| `RateLimitError` | 429 | Too many requests |
+| `ServerError` | 5xx | Server-side failure |
+| `NetworkError` | 0 | DNS failure, timeout, connection refused |
+| `TimeoutError` | 0 | Request exceeded its timeout |
+| `UploadError` | varies | Presigned upload returned non-2xx |
+
+---
+
+## Logger interface
+
+```typescript
+interface Logger {
+  debug?(msg: string, meta?: Record<string, unknown>): void;
+  info?(msg: string, meta?: Record<string, unknown>): void;
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+  error?(msg: string, meta?: Record<string, unknown>): void;
+}
+```
+
+All methods are optional. Compatible with `pino`, `winston`, and `console`.
+
+---
+
+## HttpClient configuration
+
+The SDK creates HTTP clients internally. These are the configurable defaults:
+
+| Option | Default | Description |
+|---|---|---|
+| `retryCount` | 3 | Max retries for 5xx and network errors (max 5) |
+| `retryDelay` | 500ms | Base delay between retries (exponential backoff) |
+| `timeout` | 30,000ms | Request timeout via `AbortSignal.timeout` |
+
+These are not currently exposed in `ClientConfig` — they use sensible defaults. The `HttpClient` class is exported if you need custom configuration.

package/docs/tutorial.md

@@ -0,0 +1,152 @@
+# Build your first Glide CMS integration
+
+In this tutorial, you will connect to the Glide CMS API, fetch articles, create a new taxonomy, and handle errors. By the end, you will have a working script that reads and writes CMS content. No prior Glide experience is needed.
+
+## Prerequisites
+
+- Node.js 22 or later
+- A Glide CMS account with API credentials (host, username, password, account ID)
+- A code editor
+
+## Step 1 — Install the SDK
+
+Create a new project and install the SDK:
+
+```bash
+mkdir glide-integration && cd glide-integration
+npm init -y
+npm install @glidecms/glide-cms-sdk
+```
+
+Verify the install succeeded:
+
+```bash
+node -e "import('@glidecms/glide-cms-sdk').then(m => console.log('SDK loaded, exports:', Object.keys(m).slice(0, 5).join(', '), '...'))"
+```
+
+You should see `SDK loaded` followed by some export names.
+
+## Step 2 — Connect to the API
+
+Create `index.ts`:
+
+```typescript
+import { Client } from '@glidecms/glide-cms-sdk';
+
+const sdk = new Client({
+  host: 'your-tenant.gcpp.io',
+  username: 'your-username',
+  password: 'your-password',
+  accountId: 1,
+});
+
+console.log('SDK initialized');
+```
+
+Run it:
+
+```bash
+npx tsx index.ts
+```
+
+You should see `SDK initialized`. The SDK authenticates lazily — no network call happens until you make your first request.
+
+## Step 3 — Fetch articles
+
+Add this after the SDK initialization:
+
+```typescript
+const articles = await sdk.composer.article.list({ page: 0, size: 5 });
+console.log('Fetched', articles.data.length, 'articles');
+
+for (const article of articles.data) {
+  console.log(`  [${article.id}] ${article.headline}`);
+}
+```
+
+Run it. You should see a list of up to 5 articles with their IDs and headlines. The SDK automatically handles authentication — it obtains a JWT token on the first request and refreshes it when it expires.
+
+## Step 4 — Fetch a single article
+
+```typescript
+const article = await sdk.composer.article.get(articles.data[0].id);
+console.log('Article:', article.headline);
+console.log('Status:', article.status);
+```
+
+You should see the full details of the first article.
+
+## Step 5 — List taxonomies
+
+```typescript
+const taxonomies = await sdk.composer.taxonomy.list();
+console.log('Taxonomies:', taxonomies.data.length);
+
+for (const tax of taxonomies.data.slice(0, 5)) {
+  console.log(`  [${tax.id}] ${tax.name}`);
+}
+```
+
+## Step 6 — Handle errors
+
+Wrap a call in a try/catch to see typed error handling:
+
+```typescript
+import { NotFoundError, AuthError, GlideError } from '@glidecms/glide-cms-sdk';
+
+try {
+  await sdk.composer.article.get(999999999);
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.log('Not found:', err.message);
+    console.log('Status code:', err.statusCode); // 404
+  } else if (err instanceof AuthError) {
+    console.log('Auth failed — check your credentials');
+  } else if (err instanceof GlideError) {
+    console.log('API error:', err.statusCode, err.message);
+  }
+}
+```
+
+You should see `Not found:` followed by the error message. Every error carries `statusCode`, `message`, and optionally `requestId`.
+
+## Step 7 — Work with media
+
+```typescript
+const images = await sdk.media.image.list({ page: 0, size: 3 });
+console.log('Images:', images.data.length);
+
+const files = await sdk.media.file.list({ page: 0, size: 3 });
+console.log('Files:', files.data.length);
+```
+
+## Step 8 — Paginate through results
+
+```typescript
+const paginator = sdk.composer.article.paginate({ size: 10 });
+
+for await (const page of paginator) {
+  console.log(`Page ${page.page}: ${page.items.length} articles`);
+}
+```
+
+Or collect everything into a single array:
+
+```typescript
+const allArticles = await sdk.composer.article.paginate({ size: 50 }).collectAll();
+console.log('Total articles:', allArticles.length);
+```
+
+## What you've learned
+
+- How to initialize the SDK with `host` (recommended) or explicit endpoint URLs
+- How to list and fetch resources from Composer, Media, and Users APIs
+- How to paginate through large result sets
+- How to handle typed errors with `instanceof` checks
+- That authentication is automatic — the SDK manages JWT tokens for you
+
+## Next steps
+
+- [How-to guides](./how-to-guides.md) — create articles, upload images, convert HTML
+- [API reference](./reference.md) — full method signatures for all clients
+- [Architecture overview](./architecture.md) — how the SDK is designed and why