@natsuneko-laboratory/catalyst-sdk 1.0.0-alpha.9 → 2026.10.26-beta.2

package/README.md

@@ -1,124 +1,65 @@
 # CatalystTS
 
-Official Catalyst SDK for TypeScript / JavaScript / Node.js, built for both browser and server environments.
+TypeScript/JavaScript SDK for the Natsuneko Laboratory platform. ESM only.
 
-## Installation
+The API client is generated from the OpenAPI spec by [archon](https://github.com/natsuneko-laboratory/archon). `Catalyst` is a thin layer on top of it that wires up authentication, a `User-Agent` header and automatic token refresh.
 
-```bash
-$ npm install @natsuneko-laboratory/catalyst-sdk --save
-```
-
-## Usage
-
-### Authentication (OAuth 2.0 + PKCE)
-
-```typescript
-import { CatalystTS, PKCE } from "@natsuneko-laboratory/catalyst-sdk";
-
-const API_KEY = {
-  clientId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
-  clientSecret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
-  redirectUri: "https://example.com/callback",
-};
-
-const client = new CatalystTS({
-  clientId: API_KEY.clientId,
-  clientSecret: API_KEY.clientSecret,
-});
-
-// 1. redirect the user to the authorization URL
-const pkce = await PKCE.create();
-const state = crypto.randomUUID();
-const url = client.oauth.getAuthorizeURL(API_KEY.redirectUri, pkce, state);
-
-// 2. after the user is redirected back to `redirectUri`, extract the
-//    authorization code (state and redirect URI are verified for you,
-//    throws OAuthError on failure)
-const callbackUrl = new URL(window.location.href);
-const code = client.oauth.getAuthorizationCode(callbackUrl, state, API_KEY.redirectUri);
-
-// 3. exchange the code for tokens and attach them to the client
-const token = await client.oauth.getAccessTokenByCode(code, API_KEY.redirectUri, pkce);
-client.setCredential(token.accessToken, token.refreshToken);
-```
-
-If you already have tokens (e.g. restored from storage), pass them directly:
+## Install
 
-```typescript
-const client = new CatalystTS({
-  clientId: API_KEY.clientId,
-  clientSecret: API_KEY.clientSecret,
-  accessToken: storedAccessToken,
-  refreshToken: storedRefreshToken,
-});
-```
-
-### Calling APIs
-
-API clients are generated from the OpenAPI schema by [@hey-api/openapi-ts](https://heyapi.dev/) and grouped by service:
+```sh
+# Stable releases
+npm install @natsuneko-laboratory/catalyst-sdk
 
-```typescript
-// GET /egeria/v1/me
-const { data: me } = await client.egeria.egeria.v1.me.get();
-console.log({ me });
-
-// GET /epiclese/v1/authors
-const { data: authors } = await client.epiclese.epiclese.v1.authors.get();
+# Betas (published to the `beta` dist-tag)
+npm install @natsuneko-laboratory/catalyst-sdk@beta
 ```
 
-Available services: `client.catalyst`, `client.egeria`, `client.epiclese`, `client.featureFlags`, `client.media`, `client.steambird`.
+Until the first stable `2026.x` release, the `latest` dist-tag still points to the old `1.0.0-alpha.17`, so use `@beta` to get this SDK.
 
-### Automatic token refresh
+The package is ESM only; CommonJS `require()` is not supported.
 
-When a request fails with `401 Unauthorized` and a refresh token is set, the SDK automatically refreshes the access token and retries the request (up to 5 times). Concurrent requests share a single refresh operation.
+## Usage
 
-You can also refresh manually and read back the current tokens for persistence:
+```ts
+import { Catalyst, getCatalystV11Random } from "@natsuneko-laboratory/catalyst-sdk";
 
-```typescript
-const token = await client.refresh();
+const catalyst = new Catalyst({
+  clientId: "your-client-id",
+  clientSecret: "your-client-secret",
+  accessToken: "access-token",
+  refreshToken: "refresh-token",
+  onTokenRefreshed: async (token) => {
+    // persist token.accessToken / token.refreshToken
+  },
+});
 
-console.log(client.accessToken);
-console.log(client.refreshToken);
+// Pass the configured client to any generated operation.
+const { data, error } = await getCatalystV11Random({ client: catalyst.client });
 ```
 
-### Interceptors
+When a request returns `401` and a refresh token is set, the SDK refreshes the access token once (concurrent requests share a single refresh) and retries. If the refresh fails, the original `401` is returned as an `ApiError`. Calling an operation that needs a bearer token without an access token fails with `AuthError` before any request is sent.
 
-Requests, responses, and errors can be intercepted. A `LoggingInterceptor` is provided out of the box, and you can implement the `Interceptor` interface yourself:
+Other members: `catalyst.accessToken`, `catalyst.refreshToken`, `catalyst.setCredential(accessToken, refreshToken?)`, `catalyst.clearCredential()`, `catalyst.refresh()`.
 
-```typescript
-import { CatalystTS, LoggingInterceptor } from "@natsuneko-laboratory/catalyst-sdk";
-import type { Interceptor } from "@natsuneko-laboratory/catalyst-sdk";
+Options `baseUrl`, `middleware` (run before the built-in User-Agent and 401 middleware) and `fetch` (replaces the global `fetch`) are also available.
 
-const myInterceptor: Interceptor = {
-  onRequest: (request) => {
-    request.headers.set("X-Custom-Header", "value");
-    return request;
-  },
-};
-
-const client = new CatalystTS({
-  clientId: API_KEY.clientId,
-  clientSecret: API_KEY.clientSecret,
-  interceptors: [new LoggingInterceptor(), myInterceptor],
-});
-```
+## OAuth (authorization code + PKCE)
 
-### Error handling
+```ts
+import { Catalyst, PKCE } from "@natsuneko-laboratory/catalyst-sdk";
 
-OAuth operations throw `OAuthError`, which carries a `kind` (`authorizationRequestFailed` | `invalidAuthorizationResponse` | `invalidTokenResponse`) and optional error details from the server:
+const catalyst = new Catalyst({ clientId: "...", clientSecret: "..." });
+const redirectUri = "app://callback";
+const state = crypto.randomUUID();
+const pkce = await PKCE.create();
 
-```typescript
-import { OAuthError } from "@natsuneko-laboratory/catalyst-sdk";
+// 1. Send the user to the authorization page.
+const authorizeUrl = catalyst.oauth.getAuthorizeURL(redirectUri, pkce, state);
 
-try {
-  const code = client.oauth.getAuthorizationCode(callbackUrl, state, API_KEY.redirectUri);
-} catch (err) {
-  if (err instanceof OAuthError) {
-    console.error(err.kind, err.info);
-  }
-}
+// 2. After the redirect, validate the callback and exchange the code.
+const code = catalyst.oauth.getAuthorizationCode(new URL(callbackUrl), state, redirectUri);
+const token = await catalyst.oauth.getAccessTokenByCode(code, redirectUri, pkce);
+catalyst.setCredential(token.accessToken, token.refreshToken);
 ```
 
-## License
-
-MIT by [@6jz](https://twitter.com/6jz)
+Failures are reported as `OAuthError` with `kind` of `authorizationRequestFailed`, `invalidAuthorizationResponse` or `invalidTokenResponse`.