@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 +9 -0
- package/README.md +11 -11
- package/dist/client.js +16 -16
- package/dist/index.d.ts +1 -1
- package/dist/types.d.ts +5 -5
- package/package.json +1 -1
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
|
|
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
|
-
|
|
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.
|
|
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-
|
|
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 `
|
|
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 `
|
|
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
|
|
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
|
-
`
|
|
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
|
|
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
|
|
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
|
|
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
|
|
29
|
+
function isUser(value) {
|
|
30
30
|
return (isRecord(value) &&
|
|
31
|
-
value.kind === "
|
|
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
|
|
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,
|
|
429
|
-
const credentials = [key,
|
|
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
|
-
...(
|
|
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
|
|
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 =
|
|
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,
|
|
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 !== "
|
|
486
|
+
error.code !== "auth_invalid") {
|
|
487
487
|
throw error;
|
|
488
488
|
}
|
|
489
|
-
const refreshed = await untilAborted(Promise.resolve(
|
|
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
|
-
|
|
496
|
-
|
|
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
|
|
519
|
-
const { body } = await communityRequest("
|
|
520
|
-
if (!
|
|
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,
|
|
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) =>
|
|
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
|
|
76
|
-
export type
|
|
77
|
-
kind: "
|
|
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
|
-
|
|
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>;
|