@caitlyn-ai/sdk-core 0.0.1 → 0.1.0

package/README.md

@@ -22,7 +22,7 @@ before it expires, one request at a time however many calls are waiting.
 ```ts
 import { Caitlyn } from '@caitlyn-ai/sdk';
 
-// A script using a personal access token
+// A script using a personal access token (it starts cait-pat-)
 const caitlyn = new Caitlyn({ workspace: 'your-company.getcaitlyn.ai', auth: { mode: 'token', token: process.env.CAITLYN_TOKEN! } });
 ```
 
@@ -36,7 +36,7 @@ const caitlyn = new Caitlyn({ workspace: 'your-company.getcaitlyn.ai', auth: { m
 | `session` | The Caitlyn app itself, or a tool driving a local app with a session cookie | `cookie` (server side only), `origin` |
 
 The workspace works as a region does in the AWS SDKs: it decides where requests go (`https://<workspace>/api`)
-and the audience every token is bound to (`https://<workspace>/api/v3`). `endpoint` overrides only where
+and the audience every token is bound to (`https://<workspace>/api`). `endpoint` overrides only where
 requests go, for a proxy or a local app; the audience still comes from the workspace. `caitlyn.auth.workspace`
 and `caitlyn.auth.resource` show what the client uses.
 
@@ -90,13 +90,22 @@ that trusts the account's issuer and the role.
 publish:
   id_tokens:
     CAITLYN_ID_TOKEN:
-      aud: https://your-company.getcaitlyn.ai/api/v3
+      aud: https://your-company.getcaitlyn.ai/api
 ```
 
 ```ts
 new Caitlyn({ workspace, auth: { mode: 'workloadIdentity', token: () => process.env.CAITLYN_ID_TOKEN! } });
 ```
 
+### In a browser
+
+In a browser page, use `oauth` without a `clientSecret` (authorisation code with PKCE), or `session` for the
+Caitlyn app itself. Creating a client with `clientCredentials`, `oauth` with a `clientSecret`, `awsIam` or
+`workloadIdentity` throws `CaitlynAuthError` with code `not_allowed_in_browser`: a client secret in a page is
+visible to everyone who loads it, and the other two sign in server workloads. `token` mode works but warns once
+per client, because a long-lived token in a page is exposed; it is for local testing, and
+`allowBrowserToken: true` on the mode silences the warning.
+
 ## Calls
 
 Every operation is a method on a namespace (`caitlyn.documents.list`) and also a standalone function that
@@ -127,8 +136,12 @@ Every API error is a `CaitlynError` subclass, one per status (`ValidationError`,
 `ConflictError`, `PreconditionFailedError`, `TooManyRequestsError`…), carrying the problem details: `status`,
 `code`, `title`, `detail`, `requestId` (quote it to Caitlyn support) and, on a 400, `errors`, one entry per
 field. An error page from something in front of the API (an HTML 404, a proxy's 502) is the same class for its
-status, with `code` `HTTP_<status>` and the page in `rawBody`. Sign-in failures are `CaitlynAuthError`, with
-the OAuth error code.
+status, with `code` `HTTP_<status>` and the page in `rawBody`. A call that got no response (a refused or reset
+connection, a DNS or TLS failure) is `CaitlynConnectionError`, a `CaitlynError` with `status` 0, `code`
+`CONNECTION_ERROR` and the network error as its `cause`. Sign-in failures are `CaitlynAuthError`, with the OAuth
+error code.
+
+A result's `$metadata` has the response's `httpStatusCode` and `requestId`.
 
 ```ts
 try {
@@ -146,10 +159,29 @@ try {
 failure state throws `WaiterError`. They are generated from the model's `@waitable` traits, so they appear as
 operations gain them.
 
+## Your own HTTP handler
+
+`requestHandler` gives this client its own HTTP handler, for a private certificate authority, a proxy or
+keep-alive settings, without changing the process-wide default:
+
+```ts
+import https from 'node:https';
+import { NodeHttpHandler } from '@smithy/node-http-handler';
+
+const caitlyn = new Caitlyn({
+  workspace: 'your-company.getcaitlyn.ai',
+  auth: { mode: 'token', token: process.env.CAITLYN_TOKEN! },
+  requestHandler: new NodeHttpHandler({ httpsAgent: new https.Agent({ ca: fs.readFileSync('ca.pem') }) }),
+});
+```
+
+Sign-in requests go through the `fetch` option, which takes your own `fetch` the same way.
+
 ## Telemetry
 
-The client creates OpenTelemetry spans for each call and each HTTP attempt, and passes `traceparent` on, with
-whatever tracer provider your application has registered. With none registered it costs nothing. Pass
+The client creates OpenTelemetry spans for each call (`caitlyn.call`), each HTTP attempt (`caitlyn.attempt`) and
+an upload's bytes (`caitlyn.upload`), with the names and attributes every Caitlyn SDK uses (`model/PROTOCOL.md`
+section 13), and passes `traceparent` on, with whatever tracer provider your application has registered. With none registered it costs nothing. Pass
 `telemetry: {tracerProvider}` to use another provider, or `telemetry: {enabled: false}` to switch it off.
 
 ## Runtimes