@glidecms/cms-sdk 2.2.0

package/docs/whats-different.md

@@ -0,0 +1,338 @@
+# What's different in v2
+
+A complete summary of changes between `@glidecms/glide-typescript-sdk` (v1) and `@glidecms/glide-cms-sdk` (v2).
+
+---
+
+## At a glance
+
+|  | v1 | v2 |
+|---|---|---|
+| Package | `@glidecms/glide-typescript-sdk` | `@glidecms/glide-cms-sdk` |
+| Entry class | `GlideSDK` | `Client` |
+| Source files | 222 | 41 (+ 173 ported types) |
+| Source LOC | 15,419 | 2,009 (+ 6,868 types) |
+| Runtime deps | `jsdom`, `nanoid` | none for the main SDK; optional `jsdom` for article body parsing |
+| Module system | CommonJS | ESM |
+| Node target | >=20 | >=22 |
+| HTTP client | `fetch` (34 instances) | `fetch` (3 instances) |
+| Error handling | Single `HttpError` class | 7-class typed hierarchy |
+| Retry | None | Exponential backoff on 5xx/network |
+| Request timeout | None | 30s via `AbortSignal.timeout` |
+| User-Agent | `glide-typescript-sdk/{version}` | `glide-cms-sdk/2.0.0` |
+| Tests | 0 | 107 (34 unit + 58 parity + 15 e2e) |
+| Documentation | README only | Diátaxis: tutorial, how-to, reference, architecture |
+
+---
+
+## Architecture changes
+
+### Before: 34 independent HTTP clients
+
+Every service class extended `RestService`, which created its own `GlideFetch` instance. 26 composer services + 5 media + 3 users = 34 separate HTTP clients, each with its own in-flight dedup map and token refresh flow.
+
+### After: 3 shared HTTP clients
+
+One `HttpClient` per API endpoint (composer, media, users), all sharing a single `TokenProvider`. Clients are thin wrappers — standard CRUD is inherited from `BaseClient<T>`.
+
+### Before: 100-600 LOC per service
+
+```typescript
+// v1: TaxonomyService — 252 lines
+export class TaxonomyService extends RestService implements ITaxonomyService {
+  private resource: string = 'taxonomies';
+  constructor(composerApiEndpoint: string, glideToken: IGlideToken, logger?: ILogger) {
+    super(composerApiEndpoint, glideToken, logger);
+  }
+  async getById(id: number) { /* 10 lines */ }
+  async getList(query) { /* 15 lines */ }
+  async create(payload) { /* 10 lines */ }
+  async update(id, payload) { /* 10 lines */ }
+  async delete(id) { /* 10 lines */ }
+  async activate(id) { /* 10 lines */ }
+  async deactivate(id) { /* 10 lines */ }
+}
+```
+
+### After: 5-20 LOC per client
+
+```typescript
+// v2: TaxonomyClient — 20 lines
+export class TaxonomyClient extends BaseClient<...> {
+  constructor(http: HttpClient) { super(http, 'taxonomies'); }
+
+  override async list(query?) { /* 3 lines */ }
+  async activate(id: number) { /* 1 line */ }
+  async deactivate(id: number) { /* 1 line */ }
+}
+// getById, create, update, delete — inherited from BaseClient
+```
+
+---
+
+## Error handling
+
+### Before
+
+```typescript
+// v1: single error class, raw body string
+export class HttpError extends Error {
+  constructor(
+    public status: number,
+    public statusText: string,
+    public body: string  // raw unparsed string
+  ) { ... }
+}
+```
+
+Consumers had to parse the body themselves. No `instanceof` narrowing beyond `HttpError`. No `requestId`.
+
+### After
+
+```typescript
+// v2: typed hierarchy
+GlideError (base — statusCode, requestId, message, details)
+├── AuthError (401)
+├── ForbiddenError (403)
+├── NotFoundError (404)
+├── ValidationError (422, carries details)
+├── RateLimitError (429, carries retryAfter)
+├── ServerError (5xx)
+└── NetworkError (0 — DNS, timeout, connection)
+```
+
+```typescript
+// Consumer code
+try {
+  await sdk.composer.article.getById(id);
+} catch (err) {
+  if (err instanceof NotFoundError) { /* typed, has .requestId */ }
+  if (err instanceof RateLimitError) { /* has .retryAfter */ }
+}
+```
+
+`GlideError.fromResponse(status, body)` factory maps status codes automatically. Consumers never parse raw responses.
+
+---
+
+## Config naming
+
+Config keys changed from SCREAMING_CASE (env-var style) to camelCase (JS convention):
+
+| v1 | v2 |
+|---|---|
+| `COMPOSER_API_ENDPOINT` | `composerApiEndpoint` |
+| `MEDIA_API_ENDPOINT` | `mediaApiEndpoint` |
+| `USERS_API_ENDPOINT` | `usersApiEndpoint` |
+| `USERS_USERNAME` | `username` |
+| `USERS_PASSWORD` | `password` |
+| `USERS_ACCOUNT_ID` | `accountId` |
+| `ACCESS_TOKEN` | `accessToken` |
+
+---
+
+## Method naming
+
+| Intent | v1 | v2 |
+|---|---|---|
+| List resources | `getList(query)` | `list(query)` |
+| Get by ID | `getById(id)` | `getById(id)` |
+| Create | `create(payload)` | `create(payload)` |
+| Update | `update(id, payload)` | `update(id, payload)` |
+| Delete | `delete(id)` | `delete(id)` |
+| List deactivated users | `getDeactivatedUsers()` | `listDeactivated()` |
+| Activate user | `activateUser(id)` | `activate(id)` |
+| Deactivate user | `deactivateUser(id)` | `deactivate(id)` |
+| List tags | `getTagList(query)` | `list(query)` |
+| List role types | `getRoleTypes()` | `listTypes()` |
+| List workflows | `getWorkflows()` | `list()` |
+| Get active workflow | `getActiveWorkflow()` | `getActive()` |
+| Get preview URL | `getPreviewUrl(payload, id)` | `getPreviewUrl(id, payload)` |
+
+The `getPreviewUrl` argument order was fixed — v1 had `(payload, id)` which violated the `id → body → opts` convention.
+
+---
+
+## Token management
+
+### Before
+
+- Async mutex for concurrent auth ✓
+- 401 retry calls `token()` again — but `token()` returns the cached token if it hasn't expired, so the retry uses the same stale token
+
+### After
+
+- Async mutex for concurrent auth ✓
+- 401 triggers `invalidate()` on the token provider, forcing a full re-auth on retry
+- `atob()` replaced with `Buffer.from(base64, 'base64')` for JWT decoding
+
+---
+
+## Resilience
+
+| Feature | v1 | v2 |
+|---|---|---|
+| Retry on 5xx | ❌ | ✓ exponential backoff (3 retries, 500ms base) |
+| Retry on network error | ❌ | ✓ same backoff |
+| Request timeout | ❌ | ✓ 30s via `AbortSignal.timeout` |
+| GET deduplication | ✓ | ✓ |
+| 401 token refresh | ✓ (broken) | ✓ (calls `invalidate()`) |
+
+---
+
+## Dependencies
+
+### Before
+
+```json
+{
+  "dependencies": {
+    "jsdom": "^24.1.0",
+    "nanoid": "^3.3.11"
+  },
+  "devDependencies": { /* 16 packages */ }
+}
+```
+
+`jsdom` is ~20MB and was required even if you never used `ArticleBodyProcessingService`.
+
+### After
+
+```json
+{
+  "peerDependencies": {
+    "jsdom": ">=24.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jsdom": {
+      "optional": true
+    }
+  },
+  "devDependencies": { /* 4 packages */ }
+}
+```
+
+- `jsdom` → optional peer dependency for `@glidecms/glide-cms-sdk/article-body`
+- `nanoid` → replaced with `crypto.randomUUID()` (Node 19+)
+- HTTP/auth code uses native platform APIs without extra runtime dependencies
+
+---
+
+## Module system
+
+| | v1 | v2 |
+|---|---|---|
+| `package.json` type | (none — defaults to CJS) | `"type": "module"` |
+| tsconfig module | `CommonJS` | `ESNext` |
+| tsconfig target | `ES2021` | `ES2022` |
+| Exports | `export *` (wildcard) | Named exports |
+| Tree-shaking | ❌ | ✓ |
+
+---
+
+## Type safety
+
+| | v1 | v2 |
+|---|---|---|
+| `any` types in src | 0 | 0 |
+| Generic base class | ❌ | `BaseClient<TGet, TList, TCreate, TUpdate>` |
+| Typed CRUD returns | ❌ (each service manually typed) | ✓ (generics flow through) |
+| Error types | `HttpError` (untyped body) | `GlideError` hierarchy with `instanceof` |
+
+---
+
+## Static token auth
+
+### Before
+
+```typescript
+import { GlideSDKAccessToken } from '@glidecms/glide-typescript-sdk';
+const sdk = new GlideSDKAccessToken({ ...config, ACCESS_TOKEN: 'tok' });
+```
+
+Separate class, marked `@internal`.
+
+### After
+
+```typescript
+import { Client } from '@glidecms/glide-cms-sdk';
+const sdk = Client.withAccessToken({ ...config, accessToken: 'tok' });
+```
+
+Static factory method on the main class. No separate class needed.
+
+---
+
+## Dead code removed
+
+| Item | v1 | v2 |
+|---|---|---|
+| `src/glide-axios/` (151 LOC) | Present (unused, axios removed from deps) | Deleted |
+| `.kiro/` steering files | Committed to repo | Gitignored |
+
+---
+
+## Testing
+
+| | v1 | v2 |
+|---|---|---|
+| Unit tests | 0 | 34 (errors, http-client, token, base-client) |
+| Parity tests | 0 | 58 (list + getById for all 33 clients against live sandbox) |
+| E2E lifecycle | 0 | 15 (taxonomy + article full CRUD: create → read → update → patch → delete → verify 404) |
+| Test framework | none | vitest |
+| **Total** | **0** | **107** |
+
+---
+
+## Documentation
+
+| | v1 | v2 |
+|---|---|---|
+| README | Basic usage | Landing page with links |
+| Tutorial | ❌ | Build your first integration (step-by-step) |
+| How-to guides | ❌ | 7 guides (articles, HTML, images, live reports, logging, migration) |
+| API reference | ❌ | All 33 clients, error classes, config |
+| Architecture | ❌ | Design decisions, token flow, retry strategy |
+| OpenAPI assessment | ❌ | Full endpoint + type comparison against specs |
+
+---
+
+## Bugs found and fixed
+
+### Via parity tests (58 GET endpoints against live sandbox)
+
+6 wrong resource paths caught before any consumer hit them:
+
+| Resource | Wrong path | Correct path |
+|---|---|---|
+| HTML snippets | `html-snippets` | `widgets/html-snippets` |
+| Resource locks | `resource-locks` | `locks` |
+| Verify access bundles | `verify-access-bundles` | `verify/access-bundles` |
+| Templates | `templates` | `page-templates` |
+| Active workflow | `workflows/active` | `workflows/active-workflow` |
+| Role types | `role-types` | `roles/types` |
+
+### Via OpenAPI spec assessment (compared all endpoints against specs)
+
+11 wrong paths in write operations (POST/PUT/DELETE) that parity tests couldn't catch:
+
+| Client | Method | Wrong path/verb | Correct path/verb |
+|---|---|---|---|
+| `article` | `publish` | POST `{id}/revisions/{rev}/publish` | POST `{id}/publish/{rev}` |
+| `article` | `getRevisionById` | GET `revisions/{id}` | GET `articles/versions/{id}` |
+| `article` | `getRelated` | GET `articles/related?...` | GET `articles/versions/{vId}/related?...` |
+| `article` | `getPreviewData` | POST `articles/preview` | POST `articles/url-preview` |
+| `article` | `getPreviewUrl` | POST `articles/{id}/preview-url` | PUT `articles/preview/{id}` |
+| `collection` | `publish` | POST `{id}/revisions/{rev}/publish` | POST `{id}/publish/{rev}` |
+| `template` | `publish` | POST `{id}/versions/{v}/publish` | POST `{id}/publish/{v}` |
+| `liveReport` | `publish` | POST `{id}/revisions/{rev}/publish` | POST `{id}/publish/{rev}` |
+| `verifyAccessBundle` | `publish` | POST `{id}/versions/{v}/publish` | POST `{id}/publish/{v}` |
+| `gallery` | `publish/unpublish` | POST `{id}/revisions/{rev}/publish` | PUT `{id}` with status payload |
+| `resourceLock` | `revoke` | POST `locks/{t}/{id}/revoke` | PUT `locks/revoke/{t}/{id}` |
+| `user` | `changePassword` | POST `users/{id}/change-password` | PUT `users/{id}/password` |
+
+### Via v1 code review
+
+- 401 retry bug: v1 retries with the same stale token because `token()` returns cached value. v2 calls `invalidate()` first.
+
+**Total: 18 bugs found and fixed** (6 parity + 11 OpenAPI + 1 auth bug).

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@glidecms/cms-sdk",
+  "version": "2.2.0",
+  "description": "TypeScript SDK for the Glide CMS content authoring API",
+  "author": "Glide Publishing Platform <engineering@glidepublishing.com>",
+  "private": false,
+  "keywords": ["glide", "cms", "sdk", "headless-cms", "content-authoring", "publishing"],
+  "type": "module",
+  "publishConfig": { "access": "restricted" },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./article-body": {
+      "import": "./dist/article-body.js",
+      "types": "./dist/article-body.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc --noEmit false --rewriteRelativeImportExtensions",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run build",
+    "pack:check": "npm pack --dry-run",
+    "compare": "echo 'Removed — use examples/ instead'",
+    "compare:media": "echo 'Removed — use examples/ instead'",
+    "test:e2e": "vitest run --config vitest.config.e2e.ts",
+    "smoke": "echo 'Moved to examples/smoke-cms.ts'",
+    "register-gaia": "echo 'Moved to examples/register-gaia-webhook.ts'"
+  },
+  "peerDependencies": {
+    "jsdom": ">=24.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jsdom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jsdom": "^21.0.0",
+    "@types/node": "^22.0.0",
+    "jsdom": "^29.0.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.0"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "AGENT.md",
+    "CHANGELOG.md",
+    "docs"
+  ]
+}