@caitlyn-ai/sdk 0.0.2 → 0.1.1

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

package/dist-browser/sdk/index.mjs

@@ -77,19 +77,19 @@ import { TypeRegistry } from "@smithy/core/schema";
 import {
   ServiceException as __ServiceException
 } from "@smithy/core/client";
-var CaitlynServiceException = class _CaitlynServiceException extends __ServiceException {
+var CaitlynServiceException = class extends __ServiceException {
   static shapeId = "smithy.ts.sdk.synthetic.ai.caitlyn.v3#CaitlynServiceException";
   /**
    * @internal
    */
   constructor(options) {
     super(options);
-    Object.setPrototypeOf(this, _CaitlynServiceException.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
   }
 };
 
 // packages/sdk/src/models/errors.ts
-var InternalError = class _InternalError extends CaitlynServiceException {
+var InternalError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#InternalError";
   name = "InternalError";
   $fault = "server";
@@ -142,7 +142,7 @@ var InternalError = class _InternalError extends CaitlynServiceException {
       $fault: "server",
       ...opts
     });
-    Object.setPrototypeOf(this, _InternalError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -152,7 +152,7 @@ var InternalError = class _InternalError extends CaitlynServiceException {
     this.errors = opts.errors;
   }
 };
-var NotFoundError = class _NotFoundError extends CaitlynServiceException {
+var NotFoundError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#NotFoundError";
   name = "NotFoundError";
   $fault = "client";
@@ -205,7 +205,7 @@ var NotFoundError = class _NotFoundError extends CaitlynServiceException {
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _NotFoundError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -215,7 +215,7 @@ var NotFoundError = class _NotFoundError extends CaitlynServiceException {
     this.errors = opts.errors;
   }
 };
-var PermissionDeniedError = class _PermissionDeniedError extends CaitlynServiceException {
+var PermissionDeniedError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#PermissionDeniedError";
   name = "PermissionDeniedError";
   $fault = "client";
@@ -268,7 +268,7 @@ var PermissionDeniedError = class _PermissionDeniedError extends CaitlynServiceE
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _PermissionDeniedError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -278,7 +278,7 @@ var PermissionDeniedError = class _PermissionDeniedError extends CaitlynServiceE
     this.errors = opts.errors;
   }
 };
-var PreconditionFailedError = class _PreconditionFailedError extends CaitlynServiceException {
+var PreconditionFailedError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#PreconditionFailedError";
   name = "PreconditionFailedError";
   $fault = "client";
@@ -331,7 +331,7 @@ var PreconditionFailedError = class _PreconditionFailedError extends CaitlynServ
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _PreconditionFailedError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -341,7 +341,7 @@ var PreconditionFailedError = class _PreconditionFailedError extends CaitlynServ
     this.errors = opts.errors;
   }
 };
-var PreconditionRequiredError = class _PreconditionRequiredError extends CaitlynServiceException {
+var PreconditionRequiredError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#PreconditionRequiredError";
   name = "PreconditionRequiredError";
   $fault = "client";
@@ -394,7 +394,7 @@ var PreconditionRequiredError = class _PreconditionRequiredError extends Caitlyn
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _PreconditionRequiredError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -404,7 +404,7 @@ var PreconditionRequiredError = class _PreconditionRequiredError extends Caitlyn
     this.errors = opts.errors;
   }
 };
-var ServiceUnavailableError = class _ServiceUnavailableError extends CaitlynServiceException {
+var ServiceUnavailableError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#ServiceUnavailableError";
   name = "ServiceUnavailableError";
   $fault = "server";
@@ -463,7 +463,7 @@ var ServiceUnavailableError = class _ServiceUnavailableError extends CaitlynServ
       $fault: "server",
       ...opts
     });
-    Object.setPrototypeOf(this, _ServiceUnavailableError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -474,7 +474,7 @@ var ServiceUnavailableError = class _ServiceUnavailableError extends CaitlynServ
     this.retryAfterSeconds = opts.retryAfterSeconds;
   }
 };
-var TooManyRequestsError = class _TooManyRequestsError extends CaitlynServiceException {
+var TooManyRequestsError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#TooManyRequestsError";
   name = "TooManyRequestsError";
   $fault = "client";
@@ -535,7 +535,7 @@ var TooManyRequestsError = class _TooManyRequestsError extends CaitlynServiceExc
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _TooManyRequestsError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -546,7 +546,7 @@ var TooManyRequestsError = class _TooManyRequestsError extends CaitlynServiceExc
     this.retryAfterSeconds = opts.retryAfterSeconds;
   }
 };
-var UnauthenticatedError = class _UnauthenticatedError extends CaitlynServiceException {
+var UnauthenticatedError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#UnauthenticatedError";
   name = "UnauthenticatedError";
   $fault = "client";
@@ -599,7 +599,7 @@ var UnauthenticatedError = class _UnauthenticatedError extends CaitlynServiceExc
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _UnauthenticatedError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -609,7 +609,7 @@ var UnauthenticatedError = class _UnauthenticatedError extends CaitlynServiceExc
     this.errors = opts.errors;
   }
 };
-var ValidationError = class _ValidationError extends CaitlynServiceException {
+var ValidationError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#ValidationError";
   name = "ValidationError";
   $fault = "client";
@@ -662,7 +662,7 @@ var ValidationError = class _ValidationError extends CaitlynServiceException {
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _ValidationError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -672,7 +672,7 @@ var ValidationError = class _ValidationError extends CaitlynServiceException {
     this.errors = opts.errors;
   }
 };
-var ConflictError = class _ConflictError extends CaitlynServiceException {
+var ConflictError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#ConflictError";
   name = "ConflictError";
   $fault = "client";
@@ -725,7 +725,7 @@ var ConflictError = class _ConflictError extends CaitlynServiceException {
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _ConflictError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -735,7 +735,7 @@ var ConflictError = class _ConflictError extends CaitlynServiceException {
     this.errors = opts.errors;
   }
 };
-var PayloadTooLargeError = class _PayloadTooLargeError extends CaitlynServiceException {
+var PayloadTooLargeError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#PayloadTooLargeError";
   name = "PayloadTooLargeError";
   $fault = "client";
@@ -788,7 +788,7 @@ var PayloadTooLargeError = class _PayloadTooLargeError extends CaitlynServiceExc
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _PayloadTooLargeError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -798,7 +798,7 @@ var PayloadTooLargeError = class _PayloadTooLargeError extends CaitlynServiceExc
     this.errors = opts.errors;
   }
 };
-var UnprocessableContentError = class _UnprocessableContentError extends CaitlynServiceException {
+var UnprocessableContentError = class extends CaitlynServiceException {
   static shapeId = "ai.caitlyn.v3#UnprocessableContentError";
   name = "UnprocessableContentError";
   $fault = "client";
@@ -851,7 +851,7 @@ var UnprocessableContentError = class _UnprocessableContentError extends Caitlyn
       $fault: "client",
       ...opts
     });
-    Object.setPrototypeOf(this, _UnprocessableContentError.prototype);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.type = opts.type;
     this.title = opts.title;
     this.status = opts.status;
@@ -1439,7 +1439,7 @@ var getRuntimeConfig = (config) => {
     apiVersion: "3.0.0",
     base64Decoder: config?.base64Decoder ?? fromBase64,
     base64Encoder: config?.base64Encoder ?? toBase64,
-    caitlynSdkVersion: config?.caitlynSdkVersion ?? "0.0.2",
+    caitlynSdkVersion: config?.caitlynSdkVersion ?? "0.1.1",
     disableHostPrefix: config?.disableHostPrefix ?? false,
     endpointProvider: config?.endpointProvider ?? caitlynEndpointProvider,
     extensions: config?.extensions ?? [],
@@ -1583,7 +1583,24 @@ var CaitlynClient = class extends __Client {
 };
 
 // packages/sdk/src/sdk/client.ts
-import { clientConfig, createAuth, getCaitlynAuthPlugin, getCaitlynTelemetryPlugin } from "@caitlyn-ai/sdk-core";
+import { clientConfig, createAuth, getCaitlynAuthPlugin, getCaitlynConnectionErrorPlugin, getCaitlynTelemetryPlugin } from "@caitlyn-ai/sdk-core";
+
+// packages/sdk/src/sdk/connection.ts
+var CaitlynConnectionError = class _CaitlynConnectionError extends CaitlynServiceException {
+  status = 0;
+  code = "CONNECTION_ERROR";
+  title;
+  requestId = void 0;
+  rawBody = "";
+  rawBodyTruncated = false;
+  constructor(operation, cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    super({ name: "CaitlynConnectionError", $fault: "client", $metadata: {}, message: `${operation}: no response: ${reason}` });
+    Object.setPrototypeOf(this, _CaitlynConnectionError.prototype);
+    this.title = `${operation}: no response`;
+    this.cause = cause;
+  }
+};
 
 // packages/sdk/src/sdk/operations.ts
 import { SseStream, uploadFile } from "@caitlyn-ai/sdk-core";
@@ -1687,7 +1704,7 @@ var toError = (problem) => {
   const fault = status >= 500 ? "server" : "client";
   const message = String(problem.detail ?? problem.title ?? problem.code);
   const Typed = ERROR_CLASSES[status];
-  const error = Typed ? new Typed({ $fault: fault, $metadata: {}, message }) : new CaitlynServiceException({ name: String(problem.code ?? "Error"), $fault: fault, $metadata: {}, message });
+  const error = Typed ? new Typed({ $fault: fault, $metadata: {}, message }) : new CaitlynServiceException({ name: "CaitlynError", $fault: fault, $metadata: {}, message });
   return Object.assign(error, problem, { message });
 };
 function createDocument(client, input, options = {}) {
@@ -1715,7 +1732,7 @@ function resumeConversationStream(client, conversationId, input, options = {}) {
   const { signal, ...rest } = options;
   return new SseStream(
     { known: ConversationEventNames, final: { event: "message.completed", member: "message" }, errorEvent: "message.failed", toError },
-    async () => (await client.send(new ResumeConversationStreamCommand({ ...input, conversationId, ...rest }), { abortSignal: signal })).events,
+    () => client.send(new ResumeConversationStreamCommand({ ...input, conversationId, ...rest }), { abortSignal: signal }),
     void 0,
     signal
   );
@@ -1724,8 +1741,8 @@ function sendMessage(client, conversationId, input, options = {}) {
   const { signal, ...rest } = options;
   return new SseStream(
     { known: ConversationEventNames, final: { event: "message.completed", member: "message" }, errorEvent: "message.failed", toError },
-    async () => (await client.send(new SendMessageCommand({ ...input, conversationId, ...rest }), { abortSignal: signal })).events,
-    async (lastEventId) => (await client.send(new ResumeConversationStreamCommand({ conversationId, lastEventId }), { abortSignal: signal })).events,
+    () => client.send(new SendMessageCommand({ ...input, conversationId, ...rest }), { abortSignal: signal }),
+    (lastEventId) => client.send(new ResumeConversationStreamCommand({ conversationId, lastEventId }), { abortSignal: signal }),
     signal
   );
 }
@@ -1735,7 +1752,14 @@ function updateDraftVersion(client, agentId, input, options) {
 }
 function createUploadFromFile(client, input, options = {}) {
   const { file, fileName, ...rest } = input;
-  return uploadFile(file, fileName, (meta) => createUpload(client, { ...rest, ...meta }, options), toError, options.signal);
+  return uploadFile(
+    file,
+    fileName,
+    (meta) => createUpload(client, { ...rest, ...meta }, options),
+    toError,
+    options.signal,
+    client.config.caitlynTracer
+  );
 }
 async function uploadDocument(client, input, options = {}) {
   const { file, fileName, ...rest } = input;
@@ -1748,6 +1772,7 @@ function createCaitlynClient(options, auth = createAuth(options)) {
   const client = new CaitlynClient(clientConfig(options, auth));
   client.middlewareStack.use(getCaitlynAuthPlugin(auth));
   if (options.telemetry?.enabled !== false) client.middlewareStack.use(getCaitlynTelemetryPlugin(options.telemetry?.tracerProvider));
+  client.middlewareStack.use(getCaitlynConnectionErrorPlugin((operation, cause) => new CaitlynConnectionError(operation, cause)));
   return client;
 }
 var Caitlyn = class {
@@ -1884,6 +1909,7 @@ import { NotSupportedByServer, SseStream as SseStream2, CaitlynAuthError, Waiter
 export {
   Caitlyn,
   CaitlynAuthError,
+  CaitlynConnectionError,
   CaitlynServiceException as CaitlynError,
   ClearableDraftField,
   ConflictError,