@natsuneko-laboratory/catalyst-sdk 0.7.2 → 1.0.0-alpha.10

package/README.md

@@ -10,10 +10,10 @@ $ npm install @natsuneko-laboratory/catalyst-sdk --save
 
 ## Usage
 
+### Authentication (OAuth 2.0 + PKCE)
+
 ```typescript
-// authentication
 import { CatalystTS, PKCE } from "@natsuneko-laboratory/catalyst-sdk";
-import { v4 } from "uuid";
 
 const API_KEY = {
   clientId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
@@ -24,32 +24,99 @@ const API_KEY = {
 const client = new CatalystTS({
   clientId: API_KEY.clientId,
   clientSecret: API_KEY.clientSecret,
-  accessToken: "",
-  refreshToken: "",
 });
+
+// 1. redirect the user to the authorization URL
 const pkce = await PKCE.create();
-const state = v4();
-const redirect = client.oauth.getAuthorizeURL(API_KEY.redirectUri, pkce, state);
-
-// redirected to `redirectUri`
-const searchParams = new URLSearchParams(window.location.search);
-const code = searchParams.get("code");
-const returnedState = searchParams.get("state");
-
-if (code && returnedState === state) {
-  const { accessToken, refreshToken } = await client.oauth.getAccessTokenByCode(
-    code,
-    API_KEY.redirectUri,
-    pkce,
-  );
-
-  console.log("accessToken:", accessToken);
-  console.log("refreshToken:", refreshToken);
-}
+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);
+```
 
-// call user specified APIs
-const me = await client.egeria.me();
+If you already have tokens (e.g. restored from storage), pass them directly:
+
+```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:
+
+```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();
+```
+
+Available services: `client.catalyst`, `client.egeria`, `client.epiclese`, `client.featureFlags`, `client.media`, `client.steambird`.
+
+### Automatic token refresh
+
+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.
+
+You can also refresh manually and read back the current tokens for persistence:
+
+```typescript
+const token = await client.refresh();
+
+console.log(client.accessToken);
+console.log(client.refreshToken);
+```
+
+### Interceptors
+
+Requests, responses, and errors can be intercepted. A `LoggingInterceptor` is provided out of the box, and you can implement the `Interceptor` interface yourself:
+
+```typescript
+import { CatalystTS, LoggingInterceptor } from "@natsuneko-laboratory/catalyst-sdk";
+import type { Interceptor } from "@natsuneko-laboratory/catalyst-sdk";
+
+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],
+});
+```
+
+### Error handling
+
+OAuth operations throw `OAuthError`, which carries a `kind` (`authorizationRequestFailed` | `invalidAuthorizationResponse` | `invalidTokenResponse`) and optional error details from the server:
+
+```typescript
+import { OAuthError } from "@natsuneko-laboratory/catalyst-sdk";
+
+try {
+  const code = client.oauth.getAuthorizationCode(callbackUrl, state, API_KEY.redirectUri);
+} catch (err) {
+  if (err instanceof OAuthError) {
+    console.error(err.kind, err.info);
+  }
+}
 ```
 
 ## License