@caasx/sdk 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,12 @@
1
+ ## 0.2.0
2
+
3
+ *November 17, 2026*
4
+
5
+ ### 🚨 Heads up
6
+
7
+ - **Rename viewer sign in to caasX auth**\
8
+ The old names stop working. `X-Caasx-Viewer` is now `X-Caasx-Auth`, `GET /v1/viewer` is now `GET /v1/me` and answers `kind` `user`, and the reasons `viewer_required`, `viewer_invalid`, `viewers_off` and `viewer_keys_unavailable` are now `auth_required`, `auth_invalid`, `auth_off` and `auth_keys_unavailable`. In `@caasx/sdk`, `viewer()` is now `me()`, which returns a `User`, and `ViewerToken` is now `AuthToken`. On `<caasx-feed>`, `getViewerToken` is now `getAuthToken` and the `viewer-token` attribute is now `auth-token`. The request log field `viewer_failure` is now `auth_failure`. The CMS no longer accepts a type keyed `me`, and Migrate stops if a tenant already has one, so rename that type before deploying.
9
+
1
10
  ## @caasx/sdk@0.1.0
2
11
 
3
12
  ### First npm release
package/README.md CHANGED
@@ -11,7 +11,7 @@
11
11
 
12
12
  ## ✨ What is the caasX SDK?
13
13
 
14
- `@caasx/sdk` reads entries, rails, search results and playback sessions from the caasX delivery API, and runs likes, comments and polls for signed in viewers. `caasx types` turns your tenant's content model into a TypeScript interface, so `cms.get("episode", id)` comes back typed as an episode.
14
+ `@caasx/sdk` reads entries, rails, search results and playback sessions from the caasX delivery API, and runs likes, comments and polls for signed in users. `caasx types` turns your tenant's content model into a TypeScript interface, so `cms.get("episode", id)` comes back typed as an episode.
15
15
 
16
16
  The package is ESM with no runtime dependencies. The client uses only `fetch`, `URL` and `AbortController`, with no Node imports. The CLI needs Node 22 or later.
17
17
 
@@ -125,7 +125,7 @@ Polling starts at once. Each finished poll schedules the next one `intervalMs` l
125
125
 
126
126
  ## 💬 Community
127
127
 
128
- Viewers sign in with your app's own identity provider. A platform admin registers that provider's issuer for your tenant, and caasX verifies the JWT your app already holds. There is no caasX token to mint and no server of yours to run. Pass `identity`, a function that returns the current JWT, or null when nobody is signed in:
128
+ Users sign in with your app's own identity provider. A platform admin registers that provider's issuer for your tenant, and caasX verifies the JWT your app already holds. There is no caasX token to mint and no server of yours to run. Pass `identity`, a function that returns the current JWT, or null when nobody is signed in:
129
129
 
130
130
  ```ts
131
131
  const cms = createClient({
@@ -134,7 +134,7 @@ const cms = createClient({
134
134
  identity: ({ forceRefresh }) => auth.getToken({ forceRefresh }),
135
135
  });
136
136
 
137
- const profile = await cms.viewer({ signal });
137
+ const profile = await cms.me({ signal });
138
138
  const counts = await cms.interactions([episodeId], { signal });
139
139
  const liked = await cms.like(episodeId, { signal });
140
140
  const unliked = await cms.unlike(episodeId, { signal });
@@ -146,25 +146,25 @@ const poll = await cms.poll(episodeId, { signal });
146
146
  const voted = await cms.vote(poll.id, optionId, { signal });
147
147
  ```
148
148
 
149
- The client calls `identity` before every community request and sends the token as `X-Caasx-Viewer`. Delivery reads such as `list()`, `get()`, `rail()` and `play()` never call it, and a sign in, sign out or token refresh applies to the next request with the same client.
149
+ The client calls `identity` before every community request and sends the token as `X-Caasx-Auth`. Delivery reads such as `list()`, `get()`, `rail()` and `play()` never call it, and a sign in, sign out or token refresh applies to the next request with the same client.
150
150
 
151
- When the API answers 401 `viewer_invalid`, the client calls `identity({ forceRefresh: true, rejectedToken })` once, with the token that failed, and retries only if it gets a different token back. A callback that throws or rejects fails the call before any request goes out. Aborting `signal` rejects the call even while the callback is still pending. The client never stores, caches or logs a token and never needs a refresh token. A token must not contain spaces or control characters.
151
+ When the API answers 401 `auth_invalid`, the client calls `identity({ forceRefresh: true, rejectedToken })` once, with the token that failed, and retries only if it gets a different token back. A callback that throws or rejects fails the call before any request goes out. Aborting `signal` rejects the call even while the callback is still pending. The client never stores, caches or logs a token and never needs a refresh token. A token must not contain spaces or control characters.
152
152
 
153
- Reads work signed out. `interactions()`, `comments()` and `poll()` return counts with `liked` false, `mine` false and `choice` null. Writes and `viewer()` need a viewer and fail with 401 `viewer_required` without one. For anonymous participation, use your provider's anonymous sign in, and caasX treats those users like any other viewer.
153
+ Reads work signed out. `interactions()`, `comments()` and `poll()` return counts with `liked` false, `mine` false and `choice` null. Writes and `me()` need a signed in user and fail with 401 `auth_required` without one. For anonymous participation, use your provider's anonymous sign in, and caasX treats those users like any other user.
154
154
 
155
- caasX identifies a viewer by the stable id claim your tenant registration names, `sub` by default. Some providers put a session in `sub`. Convex Auth sets it to `userId|sessionId`, which would make every new session a new viewer, so issue a claim that holds only the user id and register that one.
155
+ caasX identifies a user by the stable id claim your tenant registration names, `sub` by default. Some providers put a session in `sub`. Convex Auth sets it to `userId|sessionId`, which would make every new session a new user, so issue a claim that holds only the user id and register that one.
156
156
 
157
157
  The publishable key needs `interactions:write`.
158
158
 
159
- `viewer()` returns the viewer's `display_name` and nullable `badge`. `like()` and `unlike()` return `{ likes, liked }`. `interactions()` takes 1 to 100 nonempty ids without commas and returns `{ entries }`, keyed by entry id, each with `likes`, `liked` and `comments`.
159
+ `me()` returns the user's `display_name` and nullable `badge`. `like()` and `unlike()` return `{ likes, liked }`. `interactions()` takes 1 to 100 nonempty ids without commas and returns `{ entries }`, keyed by entry id, each with `likes`, `liked` and `comments`.
160
160
 
161
- `comment()` needs a viewer and returns the new comment. Leave out `parent` for a top level comment. `comments()` returns `{ items, next }`, and `next` goes back in as `cursor`. Its `limit` is an integer from 1 to 50. A comment has `id`, `parent`, `display_name`, `badge`, `text`, `created_at` and `mine`. `report()` resolves with no value.
161
+ `comment()` needs a user and returns the new comment. Leave out `parent` for a top level comment. `comments()` returns `{ items, next }`, and `next` goes back in as `cursor`. Its `limit` is an integer from 1 to 50. A comment has `id`, `parent`, `display_name`, `badge`, `text`, `created_at` and `mine`. `report()` resolves with no value.
162
162
 
163
- `poll()` and `vote()` return the question, nullable `opens_at` and `closes_at`, `open`, the options with their vote counts, and the viewer's nullable `choice`. Every community method takes `signal` and validates the shape of the response.
163
+ `poll()` and `vote()` return the question, nullable `opens_at` and `closes_at`, `open`, the options with their vote counts, and the user's nullable `choice`. Every community method takes `signal` and validates the shape of the response.
164
164
 
165
165
  ## ⚠️ Errors
166
166
 
167
- `CaasxError` has `status`, `code` and `message` for HTTP failures. `code` is the server's `reason` when it sends one, otherwise its `error` message, otherwise `HTTP <status>`, which is also what a non-JSON error body gets. Errors the SDK creates redact API keys and the viewer tokens `identity` returned for that call, and never include request URLs or response bodies. Network and abort errors come straight from `fetch`, so a custom `fetch` must not put request headers in the errors it throws. `CaasxProtocolError` means a successful response held malformed JSON or a malformed platform envelope.
167
+ `CaasxError` has `status`, `code` and `message` for HTTP failures. `code` is the server's `reason` when it sends one, otherwise its `error` message, otherwise `HTTP <status>`, which is also what a non-JSON error body gets. Errors the SDK creates redact API keys and the user tokens `identity` returned for that call, and never include request URLs or response bodies. Network and abort errors come straight from `fetch`, so a custom `fetch` must not put request headers in the errors it throws. `CaasxProtocolError` means a successful response held malformed JSON or a malformed platform envelope.
168
168
 
169
169
  ### Browsers and CORS
170
170
 
package/dist/client.js CHANGED
@@ -26,9 +26,9 @@ function isNullableNumber(value) {
26
26
  function isCount(value) {
27
27
  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
28
28
  }
29
- function isViewer(value) {
29
+ function isUser(value) {
30
30
  return (isRecord(value) &&
31
- value.kind === "viewer" &&
31
+ value.kind === "user" &&
32
32
  typeof value.display_name === "string" &&
33
33
  isNullableString(value.badge));
34
34
  }
@@ -344,7 +344,7 @@ function sendableToken(token) {
344
344
  return undefined;
345
345
  }
346
346
  if (typeof token !== "string" || !/^[!-~]+$/.test(token)) {
347
- throw new TypeError("identity must return a viewer token without spaces or control characters");
347
+ throw new TypeError("identity must return a token without spaces or control characters");
348
348
  }
349
349
  return token;
350
350
  }
@@ -425,8 +425,8 @@ export function createClient(options) {
425
425
  if (typeof fetcher !== "function") {
426
426
  throw new TypeError("fetch is required");
427
427
  }
428
- async function request(path, signal, parameters = new URLSearchParams(), { ifNoneMatch, method = "GET", body: jsonBody, viewer, staleViewer, } = {}) {
429
- const credentials = [key, viewer, staleViewer].filter((credential) => credential !== undefined);
428
+ async function request(path, signal, parameters = new URLSearchParams(), { ifNoneMatch, method = "GET", body: jsonBody, auth, staleAuth, } = {}) {
429
+ const credentials = [key, auth, staleAuth].filter((credential) => credential !== undefined);
430
430
  const url = new URL(`${baseUrl}${path}`);
431
431
  url.search = parameters.toString();
432
432
  const response = await fetcher(url.href, {
@@ -436,7 +436,7 @@ export function createClient(options) {
436
436
  Accept: "application/json",
437
437
  ...(ifNoneMatch === undefined ? {} : { "If-None-Match": ifNoneMatch }),
438
438
  ...(jsonBody === undefined ? {} : { "Content-Type": "application/json" }),
439
- ...(viewer === undefined ? {} : { "X-Caasx-Viewer": viewer }),
439
+ ...(auth === undefined ? {} : { "X-Caasx-Auth": auth }),
440
440
  },
441
441
  credentials: "omit",
442
442
  redirect: "error",
@@ -466,7 +466,7 @@ export function createClient(options) {
466
466
  }
467
467
  return { status: response.status, etag, body };
468
468
  }
469
- function viewerToken(options) {
469
+ function authToken(options) {
470
470
  if (identity === undefined) {
471
471
  return undefined;
472
472
  }
@@ -474,26 +474,26 @@ export function createClient(options) {
474
474
  return isPromiseLike(token) ? Promise.resolve(token).then(sendableToken) : sendableToken(token);
475
475
  }
476
476
  async function communityRequest(path, signal, parameters, init = {}) {
477
- const pending = viewerToken({ forceRefresh: false });
477
+ const pending = authToken({ forceRefresh: false });
478
478
  const token = pending instanceof Promise ? await untilAborted(pending, signal) : pending;
479
479
  try {
480
- return await request(path, signal, parameters, { ...init, viewer: token });
480
+ return await request(path, signal, parameters, { ...init, auth: token });
481
481
  }
482
482
  catch (error) {
483
483
  if (token === undefined ||
484
484
  !(error instanceof CaasxError) ||
485
485
  error.status !== 401 ||
486
- error.code !== "viewer_invalid") {
486
+ error.code !== "auth_invalid") {
487
487
  throw error;
488
488
  }
489
- const refreshed = await untilAborted(Promise.resolve(viewerToken({ forceRefresh: true, rejectedToken: token })), signal);
489
+ const refreshed = await untilAborted(Promise.resolve(authToken({ forceRefresh: true, rejectedToken: token })), signal);
490
490
  if (refreshed === token) {
491
491
  throw error;
492
492
  }
493
493
  return request(path, signal, parameters, {
494
494
  ...init,
495
- viewer: refreshed,
496
- staleViewer: token,
495
+ auth: refreshed,
496
+ staleAuth: token,
497
497
  });
498
498
  }
499
499
  }
@@ -515,9 +515,9 @@ export function createClient(options) {
515
515
  return { body: result.body, etag: result.etag };
516
516
  }
517
517
  return {
518
- async viewer(options = {}) {
519
- const { body } = await communityRequest("viewer", options.signal);
520
- if (!isViewer(body)) {
518
+ async me(options = {}) {
519
+ const { body } = await communityRequest("me", options.signal);
520
+ if (!isUser(body)) {
521
521
  throw new CaasxProtocolError();
522
522
  }
523
523
  return body;
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  export { CaasxError, CaasxProtocolError, createClient } from "./client.js";
2
- export type { Catalog, CatalogWatcher, Client, ClientOptions, CommentOptions, CommentPage, CommentsOptions, DefaultSchema, EntryComment, EntryEnvelope, EntryPoll, EntryRailItem, Filter, FilterOperator, FilterValue, GetOptions, IdentityOptions, Image, Interactions, LikeState, ListOptions, ModelDocument, ModelField, ModelFieldKind, ModelType, Page, Playback, PlaybackCaption, PlaybackSession, PollOption, PrerollDecision, Rail, RailItem, RequestOptions, Screen, SearchHit, SearchOptions, SearchPage, SponsoredRailItem, Sponsorship, Taxonomy, TaxonomyTerm, Term, Theme, TypedSearchOptions, Video, VideoStatus, Viewer, ViewerToken, WatchCatalogOptions, } from "./types.js";
2
+ export type { AuthToken, Catalog, CatalogWatcher, Client, ClientOptions, CommentOptions, CommentPage, CommentsOptions, DefaultSchema, EntryComment, EntryEnvelope, EntryPoll, EntryRailItem, Filter, FilterOperator, FilterValue, GetOptions, IdentityOptions, Image, Interactions, LikeState, ListOptions, ModelDocument, ModelField, ModelFieldKind, ModelType, Page, Playback, PlaybackCaption, PlaybackSession, PollOption, PrerollDecision, Rail, RailItem, RequestOptions, Screen, SearchHit, SearchOptions, SearchPage, SponsoredRailItem, Sponsorship, Taxonomy, TaxonomyTerm, Term, Theme, TypedSearchOptions, User, Video, VideoStatus, WatchCatalogOptions, } from "./types.js";
package/dist/types.d.ts CHANGED
@@ -64,7 +64,7 @@ export interface ClientOptions {
64
64
  url: string;
65
65
  key: string;
66
66
  fetch?: typeof globalThis.fetch;
67
- identity?: (options: IdentityOptions) => ViewerToken | Promise<ViewerToken>;
67
+ identity?: (options: IdentityOptions) => AuthToken | Promise<AuthToken>;
68
68
  }
69
69
  export type IdentityOptions = {
70
70
  forceRefresh: false;
@@ -72,9 +72,9 @@ export type IdentityOptions = {
72
72
  forceRefresh: true;
73
73
  rejectedToken: string;
74
74
  };
75
- export type ViewerToken = string | null | undefined;
76
- export type Viewer = {
77
- kind: "viewer";
75
+ export type AuthToken = string | null | undefined;
76
+ export type User = {
77
+ kind: "user";
78
78
  display_name: string;
79
79
  badge: string | null;
80
80
  };
@@ -260,7 +260,7 @@ export interface CatalogWatcher {
260
260
  export interface Client<Schema extends {
261
261
  [Key in keyof Schema]: EntryEnvelope;
262
262
  } = DefaultSchema> {
263
- viewer(options?: RequestOptions): Promise<Viewer>;
263
+ me(options?: RequestOptions): Promise<User>;
264
264
  like(entryId: string, options?: RequestOptions): Promise<LikeState>;
265
265
  unlike(entryId: string, options?: RequestOptions): Promise<LikeState>;
266
266
  interactions(entryIds: readonly string[], options?: RequestOptions): Promise<Interactions>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@caasx/sdk",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Fetch client, TypeScript types and type generator for the caasX delivery API.",
5
5
  "license": "MIT",
6
6
  "type": "module",