@caitlyn-ai/sdk-core 0.0.2 → 0.1.0

package/dist-es/index.mjs

@@ -14,6 +14,181 @@ import {
 } from "@smithy/core/protocols";
 import { NormalizedSchema, TypeRegistry } from "@smithy/core/schema";
 import { decorateServiceException } from "@smithy/core/client";
+
+// packages/sdk-core/src/plugin.ts
+import { getOmitRetryHeadersPlugin } from "@smithy/core/retry";
+import { HttpRequest } from "@smithy/core/protocols";
+import { HttpResponse } from "@smithy/core/protocols";
+
+// packages/sdk-core/src/retry.ts
+var NO_RETRY = /* @__PURE__ */ Symbol.for("caitlyn.noRetry");
+var Token = class {
+  constructor(count, delay) {
+    this.count = count;
+    this.delay = delay;
+  }
+  count;
+  delay;
+  getRetryCount() {
+    return this.count;
+  }
+  getRetryDelay() {
+    return this.delay;
+  }
+};
+var CaitlynRetryStrategy = class {
+  constructor(maxAttempts = 3, maxRetryDelayMs = 6e4) {
+    this.maxRetryDelayMs = maxRetryDelayMs;
+    this.maxAttempts = typeof maxAttempts === "number" ? async () => maxAttempts : maxAttempts;
+  }
+  maxRetryDelayMs;
+  mode = "standard";
+  maxAttempts;
+  async acquireInitialRetryToken() {
+    return new Token(0, 0);
+  }
+  async refreshRetryTokenForRetry(token, info) {
+    const count = token.getRetryCount();
+    const err = info.error;
+    if (count + 1 >= await this.maxAttempts()) throw new Error("retry: attempts exhausted");
+    if (!err || err[NO_RETRY]) throw new Error("retry: operation is not safe to retry");
+    const noResponse = err.$metadata?.httpStatusCode === void 0 && err.name !== "AbortError";
+    if (err.$retryable === void 0 && !noResponse) throw new Error("retry: error is not retryable");
+    let delay;
+    if (info.retryAfterHint instanceof Date) {
+      delay = Math.max(0, info.retryAfterHint.getTime() - Date.now());
+      if (delay > this.maxRetryDelayMs) throw new Error("retry: Retry-After exceeds maxRetryDelay");
+    } else {
+      delay = Math.random() * Math.min(8e3, 500 * 2 ** count);
+    }
+    return new Token(count + 1, delay);
+  }
+  recordSuccess() {
+  }
+};
+
+// packages/sdk-core/src/plugin.ts
+var CAITLYN_SDK_USER_AGENT_PREFIX = "caitlyn-sdk-ts";
+var NO_RESPONSE = /* @__PURE__ */ Symbol.for("caitlyn.noResponse");
+function markNoResponse(err) {
+  if (err && typeof err === "object" && err.name !== "AbortError") Object.defineProperty(err, NO_RESPONSE, { value: true, configurable: true });
+  return err;
+}
+function getCaitlynConnectionErrorPlugin(toError) {
+  const mark = (next) => async (args) => {
+    try {
+      return await next(args);
+    } catch (err) {
+      const e = err;
+      if (!HttpResponse.isInstance(e?.$response) && e?.$metadata?.httpStatusCode === void 0) markNoResponse(err);
+      throw err;
+    }
+  };
+  const wrap = (next, context2) => async (args) => {
+    try {
+      return await next(args);
+    } catch (err) {
+      if (err && typeof err === "object" && err[NO_RESPONSE]) {
+        throw toError(context2.commandName?.replace(/Command$/, "") ?? "call", err);
+      }
+      throw err;
+    }
+  };
+  return {
+    applyToStack(stack) {
+      stack.add(mark, { step: "deserialize", name: "caitlynNoResponse", priority: "low", override: true });
+      stack.add(wrap, { step: "initialize", name: "caitlynConnectionError", priority: "normal", override: true });
+    }
+  };
+}
+var NotSupportedByServer = class extends Error {
+  constructor(operation, requires, server) {
+    super(`NotSupportedByServer(${operation}, requires ${requires}, server is ${server})`);
+    this.operation = operation;
+    this.requires = requires;
+    this.server = server;
+    this.name = "NotSupportedByServer";
+  }
+  operation;
+  requires;
+  server;
+};
+var semver = (a, b) => {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return (pa[i] ?? 0) - (pb[i] ?? 0);
+  return 0;
+};
+function runtime() {
+  const g = globalThis;
+  if (g.process?.versions?.bun) return `md/bun#${g.process.versions.bun}`;
+  if (g.Deno?.version?.deno) return `md/deno#${g.Deno.version.deno}`;
+  if (g.process?.versions?.node) return `md/nodejs#${g.process.versions.node}`;
+  return "md/browser";
+}
+function getCaitlynSdkPlugin(config, options) {
+  let server;
+  const since = new Map((options.since ?? []).map((e) => e.split("=")));
+  const sinceCheck = (next, context2) => async (args) => {
+    const op = context2.commandName?.replace(/Command$/, "");
+    if (op && server) {
+      const required = since.get(op);
+      if (required && semver(required, server) > 0) throw new NotSupportedByServer(op, required, server);
+      for (const [member, value] of Object.entries(args.input)) {
+        const memberSince = value === void 0 ? void 0 : since.get(`${op}.${member}`);
+        if (memberSince && semver(memberSince, server) > 0) throw new NotSupportedByServer(`${op}.${member}`, memberSince, server);
+      }
+    }
+    return next(args);
+  };
+  const serverVersion = (next) => async (args) => {
+    try {
+      const out = await next(args);
+      if (HttpResponse.isInstance(out.response)) server = out.response.headers["caitlyn-api-version"] ?? server;
+      return out;
+    } catch (err) {
+      const res = err.$response;
+      if (HttpResponse.isInstance(res)) server = res.headers["caitlyn-api-version"] ?? server;
+      throw err;
+    }
+  };
+  const userAgent = [`${CAITLYN_SDK_USER_AGENT_PREFIX}/${config.caitlynSdkVersion ?? "0.0.0"}`, "lang/js", runtime(), config.customUserAgent].filter(Boolean).join(" ");
+  const identity = (next) => async (args) => {
+    if (HttpRequest.isInstance(args.request)) {
+      args.request.headers["user-agent"] = userAgent;
+      args.request.headers["caitlyn-sdk-model"] = options.sdkModel;
+    }
+    return next(args);
+  };
+  const safe = new Set(options.retrySafeOperations);
+  const retrySafety = (next, context2) => async (args) => {
+    try {
+      return await next(args);
+    } catch (err) {
+      const op = context2.commandName?.replace(/Command$/, "");
+      if (op && !safe.has(op) && err && typeof err === "object") Object.defineProperty(err, NO_RETRY, { value: true });
+      throw err;
+    }
+  };
+  return {
+    applyToStack(stack) {
+      stack.add(sinceCheck, { step: "initialize", name: "caitlynSinceCheck", priority: "high", override: true });
+      stack.add(serverVersion, { step: "deserialize", name: "caitlynServerVersion", priority: "low", override: true });
+      stack.add(identity, { step: "build", name: "caitlynSdkIdentity", priority: "low", override: true });
+      stack.addRelativeTo(retrySafety, { toMiddleware: "retryMiddleware", relation: "after", name: "caitlynRetrySafety" });
+      getOmitRetryHeadersPlugin({}).applyToStack(stack);
+    }
+  };
+}
+
+// packages/sdk-core/src/protocol.ts
+async function readBody(body, context2) {
+  try {
+    return await collectBody(body, context2);
+  } catch (err) {
+    throw markNoResponse(err);
+  }
+}
 var SETTINGS = {
   timestampFormat: {
     useTrait: true,
@@ -65,7 +240,7 @@ var CaitlynRestJsonProtocol = class extends HttpBindingProtocol {
     const ns = NormalizedSchema.of(operationSchema.output);
     const streaming = [...ns.structIterator()].some(([, m]) => m.getMemberTraits().httpPayload && m.isStreaming());
     if (response.statusCode >= 300) {
-      const bytes2 = await collectBody(response.body, context2);
+      const bytes2 = await readBody(response.body, context2);
       response.body = bytes2;
       if (!isJsonObject(bytes2)) {
         await this.handleError(operationSchema, context2, response, {}, this.deserializeMetadata(response));
@@ -73,7 +248,7 @@ var CaitlynRestJsonProtocol = class extends HttpBindingProtocol {
       return super.deserializeResponse(operationSchema, context2, response);
     }
     if (streaming) return super.deserializeResponse(operationSchema, context2, response);
-    const bytes = await collectBody(response.body, context2);
+    const bytes = await readBody(response.body, context2);
     response.body = bytes;
     const output = await super.deserializeResponse(operationSchema, context2, response);
     if (bytes.byteLength > 0) {
@@ -94,7 +269,7 @@ var CaitlynRestJsonProtocol = class extends HttpBindingProtocol {
     const registry = this.compositeErrorRegistry;
     registry.copyFrom(TypeRegistry.for(this.options.defaultNamespace));
     const errorMetadata = { $metadata: metadata, $fault: response.statusCode < 500 ? "client" : "server" };
-    const rawBody = response.body instanceof Uint8Array ? new TextDecoder().decode(response.body) : "";
+    const { rawBody, rawBodyTruncated } = rawBodyOf(response.body instanceof Uint8Array ? response.body : new Uint8Array());
     const body = {
       ...dataObject,
       // Always the HTTP status: a body's `status` can be wrong (a proxy, a faulty handler), and the class is
@@ -102,7 +277,8 @@ var CaitlynRestJsonProtocol = class extends HttpBindingProtocol {
       status: response.statusCode,
       code: typeof dataObject.code === "string" && dataObject.code ? dataObject.code : `HTTP_${response.statusCode}`,
       requestId: dataObject.requestId ?? response.headers["caitlyn-request-id"],
-      rawBody
+      rawBody,
+      rawBodyTruncated
     };
     const message = body.detail ?? body.title ?? `HTTP ${response.statusCode}`;
     const schema = registry.find((s) => {
@@ -113,7 +289,7 @@ var CaitlynRestJsonProtocol = class extends HttpBindingProtocol {
     if (!schema) {
       const base = registry.getBaseException();
       const Ctor2 = base && registry.getErrorCtor(base) || Error;
-      const name = body.code;
+      const name = "CaitlynError";
       throw decorateServiceException(Object.assign(new Ctor2({ name, message }), errorMetadata), body);
     }
     const ns = NormalizedSchema.of(schema);
@@ -130,6 +306,13 @@ var CaitlynRestJsonProtocol = class extends HttpBindingProtocol {
     throw decorateServiceException(Object.assign(exception, errorMetadata, { $fault: ns.getMergedTraits().error, message }, fields), body);
   }
 };
+var RAW_BODY_LIMIT = 8192;
+function rawBodyOf(bytes) {
+  if (bytes.byteLength <= RAW_BODY_LIMIT) return { rawBody: new TextDecoder().decode(bytes), rawBodyTruncated: false };
+  let end = RAW_BODY_LIMIT;
+  while (end > 0 && (bytes[end] & 192) === 128) end--;
+  return { rawBody: new TextDecoder().decode(bytes.subarray(0, end)), rawBodyTruncated: true };
+}
 function isJsonObject(bytes) {
   if (bytes.byteLength === 0) return false;
   try {
@@ -170,140 +353,6 @@ function resolveContentType(input) {
   return hasBody ? "application/json" : void 0;
 }
 
-// packages/sdk-core/src/plugin.ts
-import { getOmitRetryHeadersPlugin } from "@smithy/core/retry";
-import { HttpRequest } from "@smithy/core/protocols";
-import { HttpResponse } from "@smithy/core/protocols";
-
-// packages/sdk-core/src/retry.ts
-var NO_RETRY = /* @__PURE__ */ Symbol.for("caitlyn.noRetry");
-var Token = class {
-  constructor(count, delay) {
-    this.count = count;
-    this.delay = delay;
-  }
-  count;
-  delay;
-  getRetryCount() {
-    return this.count;
-  }
-  getRetryDelay() {
-    return this.delay;
-  }
-};
-var CaitlynRetryStrategy = class {
-  constructor(maxAttempts = 3, maxRetryDelayMs = 6e4) {
-    this.maxRetryDelayMs = maxRetryDelayMs;
-    this.maxAttempts = typeof maxAttempts === "number" ? async () => maxAttempts : maxAttempts;
-  }
-  maxRetryDelayMs;
-  mode = "standard";
-  maxAttempts;
-  async acquireInitialRetryToken() {
-    return new Token(0, 0);
-  }
-  async refreshRetryTokenForRetry(token, info) {
-    const count = token.getRetryCount();
-    const err = info.error;
-    if (count + 1 >= await this.maxAttempts()) throw new Error("retry: attempts exhausted");
-    if (!err || err[NO_RETRY]) throw new Error("retry: operation is not safe to retry");
-    const noResponse = err.$metadata?.httpStatusCode === void 0 && err.name !== "AbortError";
-    if (err.$retryable === void 0 && !noResponse) throw new Error("retry: error is not retryable");
-    let delay;
-    if (info.retryAfterHint instanceof Date) {
-      delay = Math.max(0, info.retryAfterHint.getTime() - Date.now());
-      if (delay > this.maxRetryDelayMs) throw new Error("retry: Retry-After exceeds maxRetryDelay");
-    } else {
-      delay = Math.random() * Math.min(8e3, 500 * 2 ** count);
-    }
-    return new Token(count + 1, delay);
-  }
-  recordSuccess() {
-  }
-};
-
-// packages/sdk-core/src/plugin.ts
-var CAITLYN_SDK_USER_AGENT_PREFIX = "caitlyn-sdk-ts";
-var NotSupportedByServer = class extends Error {
-  constructor(operation, requires, server) {
-    super(`NotSupportedByServer(${operation}, requires ${requires}, server is ${server})`);
-    this.operation = operation;
-    this.requires = requires;
-    this.server = server;
-    this.name = "NotSupportedByServer";
-  }
-  operation;
-  requires;
-  server;
-};
-var semver = (a, b) => {
-  const pa = a.split(".").map(Number);
-  const pb = b.split(".").map(Number);
-  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return (pa[i] ?? 0) - (pb[i] ?? 0);
-  return 0;
-};
-function runtime() {
-  const g = globalThis;
-  if (g.process?.versions?.bun) return `md/bun#${g.process.versions.bun}`;
-  if (g.Deno?.version?.deno) return `md/deno#${g.Deno.version.deno}`;
-  if (g.process?.versions?.node) return `md/nodejs#${g.process.versions.node}`;
-  return "md/browser";
-}
-function getCaitlynSdkPlugin(config, options) {
-  let server;
-  const since = new Map((options.since ?? []).map((e) => e.split("=")));
-  const sinceCheck = (next, context2) => async (args) => {
-    const op = context2.commandName?.replace(/Command$/, "");
-    if (op && server) {
-      const required = since.get(op);
-      if (required && semver(required, server) > 0) throw new NotSupportedByServer(op, required, server);
-      for (const [member, value] of Object.entries(args.input)) {
-        const memberSince = value === void 0 ? void 0 : since.get(`${op}.${member}`);
-        if (memberSince && semver(memberSince, server) > 0) throw new NotSupportedByServer(`${op}.${member}`, memberSince, server);
-      }
-    }
-    return next(args);
-  };
-  const serverVersion = (next) => async (args) => {
-    try {
-      const out = await next(args);
-      if (HttpResponse.isInstance(out.response)) server = out.response.headers["caitlyn-api-version"] ?? server;
-      return out;
-    } catch (err) {
-      const res = err.$response;
-      if (HttpResponse.isInstance(res)) server = res.headers["caitlyn-api-version"] ?? server;
-      throw err;
-    }
-  };
-  const userAgent = [`${CAITLYN_SDK_USER_AGENT_PREFIX}/${config.caitlynSdkVersion ?? "0.0.0"}`, "lang/js", runtime(), config.customUserAgent].filter(Boolean).join(" ");
-  const identity = (next) => async (args) => {
-    if (HttpRequest.isInstance(args.request)) {
-      args.request.headers["user-agent"] = userAgent;
-      args.request.headers["caitlyn-sdk-model"] = options.sdkModel;
-    }
-    return next(args);
-  };
-  const safe = new Set(options.retrySafeOperations);
-  const retrySafety = (next, context2) => async (args) => {
-    try {
-      return await next(args);
-    } catch (err) {
-      const op = context2.commandName?.replace(/Command$/, "");
-      if (op && !safe.has(op) && err && typeof err === "object") Object.defineProperty(err, NO_RETRY, { value: true });
-      throw err;
-    }
-  };
-  return {
-    applyToStack(stack) {
-      stack.add(sinceCheck, { step: "initialize", name: "caitlynSinceCheck", priority: "high", override: true });
-      stack.add(serverVersion, { step: "deserialize", name: "caitlynServerVersion", priority: "low", override: true });
-      stack.add(identity, { step: "build", name: "caitlynSdkIdentity", priority: "low", override: true });
-      stack.addRelativeTo(retrySafety, { toMiddleware: "retryMiddleware", relation: "after", name: "caitlynRetrySafety" });
-      getOmitRetryHeadersPlugin({}).applyToStack(stack);
-    }
-  };
-}
-
 // packages/sdk-core/src/endpoint.ts
 var caitlynEndpointProvider = (params) => {
   if (!params.endpoint) throw new Error("Caitlyn: no endpoint. Pass `workspace` or `endpoint` when creating the client.");
@@ -313,23 +362,38 @@ var caitlynEndpointProvider = (params) => {
 // packages/sdk-core/src/telemetry.ts
 import { HttpRequest as HttpRequest2, HttpResponse as HttpResponse2 } from "@smithy/core/protocols";
 import { context, propagation, trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+function caitlynTracer(provider) {
+  return (provider ?? trace.getTracerProvider()).getTracer("@caitlyn-ai/sdk", "0.1.0");
+}
+function urlWithoutQuery(url) {
+  const u = new URL(url);
+  u.search = "";
+  u.hash = "";
+  u.username = "";
+  u.password = "";
+  return u.toString();
+}
+function recordFailure(span, err) {
+  const e = err;
+  span.recordException(err instanceof Error ? err : { name: String(e?.name ?? "Error"), message: String(e?.message ?? err) });
+  span.setStatus({ code: SpanStatusCode.ERROR, message: e?.message });
+  span.setAttribute("error.type", e?.name ?? "Error");
+  if (typeof e?.code === "string") span.setAttribute("caitlyn.error.code", e.code);
+}
 function getCaitlynTelemetryPlugin(provider) {
-  const tracer = (provider ?? trace.getTracerProvider()).getTracer("@caitlyn-ai/sdk", "0.0.2");
+  const tracer = caitlynTracer(provider);
   return {
     applyToStack(stack) {
       stack.add(
         (next, ctx) => async (args) => {
           const op = ctx.commandName?.replace(/Command$/, "") ?? "unknown";
-          return tracer.startActiveSpan(`caitlyn ${op}`, { kind: SpanKind.CLIENT, attributes: { "caitlyn.operation": op } }, async (span) => {
+          return tracer.startActiveSpan("caitlyn.call", { kind: SpanKind.CLIENT, attributes: { "rpc.system": "caitlyn", "rpc.method": op } }, async (span) => {
             ctx.__caitlynSpan = span;
             ctx.__attempt = 0;
             try {
-              const out = await next(args);
-              return out;
+              return await next(args);
             } catch (err) {
-              span.recordException(err);
-              span.setStatus({ code: SpanStatusCode.ERROR });
-              span.setAttribute("error.type", err.name);
+              recordFailure(span, err);
               throw err;
             } finally {
               span.end();
@@ -343,26 +407,34 @@ function getCaitlynTelemetryPlugin(provider) {
           const attempt = ctx.__attempt ?? 0;
           ctx.__attempt = attempt + 1;
           const parent = ctx.__caitlynSpan ? trace.setSpan(context.active(), ctx.__caitlynSpan) : context.active();
-          const span = tracer.startSpan(`HTTP ${args.request.method}`, { kind: SpanKind.CLIENT, attributes: { "http.request.resend_count": attempt } }, parent);
+          const span = tracer.startSpan("caitlyn.attempt", { kind: SpanKind.CLIENT, attributes: { "http.request.resend_count": attempt } }, parent);
           const req = args.request;
           if (HttpRequest2.isInstance(req)) {
-            span.setAttribute("server.address", req.hostname);
+            span.setAttributes({
+              "http.request.method": req.method,
+              "server.address": req.hostname,
+              "url.full": urlWithoutQuery(`${req.protocol}//${req.hostname}${req.port ? `:${req.port}` : ""}${req.path}`)
+            });
             propagation.inject(trace.setSpan(parent, span), req.headers);
           }
+          const response = (res) => {
+            if (!HttpResponse2.isInstance(res)) return;
+            span.setAttribute("http.response.status_code", res.statusCode);
+            const rid = res.headers["caitlyn-request-id"];
+            if (rid) {
+              span.setAttribute("caitlyn.request_id", rid);
+              ctx.__caitlynSpan?.setAttribute("caitlyn.request_id", rid);
+            }
+            const api = res.headers["caitlyn-api-version"];
+            if (api) span.setAttribute("caitlyn.server.api_version", api);
+            if (res.statusCode >= 400) span.setStatus({ code: SpanStatusCode.ERROR });
+          };
           try {
             const out = await next(args);
-            if (HttpResponse2.isInstance(out.response)) {
-              span.setAttribute("http.response.status_code", out.response.statusCode);
-              const rid = out.response.headers["caitlyn-request-id"];
-              if (rid) {
-                span.setAttribute("caitlyn.request_id", rid);
-                ctx.__caitlynSpan?.setAttribute("caitlyn.request_id", rid);
-              }
-            }
+            response(out.response);
             return out;
           } catch (err) {
-            const res = err.$response;
-            if (HttpResponse2.isInstance(res)) span.setAttribute("http.response.status_code", res.statusCode);
+            response(err.$response);
             span.setStatus({ code: SpanStatusCode.ERROR });
             throw err;
           } finally {
@@ -425,17 +497,23 @@ var SseStream = class {
   seen = /* @__PURE__ */ new Set();
   lastEventId;
   reconnects = 0;
+  /** The Caitlyn-Request-Id of the response that opened the stream; set once iteration has started. */
+  requestId;
   aborted() {
     return this.signal?.reason ?? new DOMException("Aborted", "AbortError");
   }
   async *[Symbol.asyncIterator]() {
     if (this.consumed) throw new Error("SseStream can only be iterated once");
     this.consumed = true;
-    let body = await this.open();
+    const opened = await this.open();
+    this.requestId = opened.$metadata?.requestId;
+    let body = opened.events;
     for (; ; ) {
       let ended = false;
+      let onResponse = 0;
       try {
         for await (const msg of parseSse(body)) {
+          onResponse++;
           if (msg.id) {
             if (this.seen.has(msg.id)) continue;
             this.seen.add(msg.id);
@@ -452,7 +530,7 @@ var SseStream = class {
             return;
           }
         }
-        if (!this.spec.final) return;
+        if (!this.spec.final || onResponse === 0) return;
       } catch (err) {
         if (this.signal?.aborted) throw this.aborted();
         if (ended || err?.name === "AbortError" || err === void 0 || err.$fault || err instanceof SyntaxError) throw err;
@@ -460,7 +538,7 @@ var SseStream = class {
       if (this.signal?.aborted) throw this.aborted();
       if (!this.resume || ++this.reconnects > this.maxReconnects)
         throw this.spec.toError({ status: 0, code: "STREAM_LOST", title: "The stream dropped and could not be resumed" });
-      body = await this.resume(this.lastEventId);
+      body = (await this.resume(this.lastEventId)).events;
     }
   }
   /** Drains the stream if needed and returns the final event's member. */
@@ -472,15 +550,40 @@ var SseStream = class {
 };
 
 // packages/sdk-core/src/upload.ts
-async function uploadFile(file, fileName, reserve, toError, signal) {
+import { SpanKind as SpanKind2, SpanStatusCode as SpanStatusCode2 } from "@opentelemetry/api";
+var STATUS = /* @__PURE__ */ Symbol("status");
+async function uploadFile(file, fileName, reserve, toError, signal, tracer) {
   const bytes = new Uint8Array(await file.arrayBuffer());
   const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
   let binary = "";
   for (const b of digest) binary += String.fromCharCode(b);
   const slot = await reserve({ fileName, contentType: file.type || "application/octet-stream", byteSize: bytes.byteLength, sha256: btoa(binary) });
-  const res = await fetch(slot.uploadUrl, { method: slot.uploadMethod, headers: slot.requiredHeaders, body: bytes, signal });
-  if (!res.ok) throw toError({ status: res.status, code: "UPLOAD_PUT_FAILED", title: "Uploading the bytes failed", detail: await res.text() });
-  return slot;
+  const put = async () => {
+    const res = await fetch(slot.uploadUrl, { method: slot.uploadMethod, headers: slot.requiredHeaders, body: bytes, signal });
+    if (!res.ok) throw Object.assign(toError({ status: res.status, code: "UPLOAD_PUT_FAILED", title: "Uploading the bytes failed", detail: await res.text() }), { [STATUS]: res.status });
+    return res.status;
+  };
+  if (!tracer) {
+    await put();
+    return slot;
+  }
+  const url = new URL(slot.uploadUrl);
+  const span = tracer.startSpan("caitlyn.upload", {
+    kind: SpanKind2.CLIENT,
+    attributes: { "http.request.method": slot.uploadMethod || "PUT", "server.address": url.hostname, "url.full": urlWithoutQuery(slot.uploadUrl) }
+  });
+  try {
+    span.setAttribute("http.response.status_code", await put());
+    return slot;
+  } catch (err) {
+    const status = err[STATUS];
+    if (status !== void 0) span.setAttribute("http.response.status_code", status);
+    recordFailure(span, err);
+    span.setStatus({ code: SpanStatusCode2.ERROR });
+    throw err;
+  } finally {
+    span.end();
+  }
 }
 
 // packages/sdk-core/src/auth.ts
@@ -504,8 +607,30 @@ var SESSION_PLACEHOLDER = "session";
 var refreshAt = (t) => t.expiresAt === void 0 ? void 0 : t.expiresAt - Math.min(REFRESH_EARLY_MS, (t.expiresAt - Date.now()) / 2);
 var b64url = (bytes) => btoa(String.fromCharCode(...new Uint8Array(bytes))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 var randomString = (n = 32) => b64url(crypto.getRandomValues(new Uint8Array(n)));
-var workspaceAudience = (workspace) => `https://${workspaceHost(workspace)}/api/v3`;
+var workspaceAudience = (workspace) => `https://${workspaceHost(workspace)}/api`;
 var workspaceHost = (workspace) => workspace.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+var isBrowser = () => {
+  const g = globalThis;
+  return typeof g.window !== "undefined" && typeof g.document !== "undefined";
+};
+var IN_BROWSER = "not_allowed_in_browser";
+function guardBrowser(o) {
+  if (!isBrowser()) return;
+  if (o.mode === "clientCredentials" || o.mode === "oauth" && o.clientSecret) {
+    throw new CaitlynAuthError(
+      `${o.mode === "oauth" ? "oauth with a clientSecret" : "clientCredentials"} cannot be used in a browser: a client secret in a browser is visible to everyone who loads the page. Use oauth without a clientSecret (authorisation code with PKCE), or sign in on your server.`,
+      IN_BROWSER
+    );
+  }
+  if (o.mode === "awsIam" || o.mode === "workloadIdentity") {
+    throw new CaitlynAuthError(`${o.mode} cannot be used in a browser: it signs in a server workload with that workload's own identity. Use oauth in a browser.`, IN_BROWSER);
+  }
+  if (o.mode === "token" && !o.allowBrowserToken) {
+    console.warn(
+      "Caitlyn: a long-lived token in a browser is exposed to anyone who can run script on the page. token mode in a browser is for local testing; use oauth instead. Set auth.allowBrowserToken: true to silence this warning."
+    );
+  }
+}
 var AuthSession = class {
   constructor(options, endpoint, workspace, fetchFn = (...a) => fetch(...a)) {
     this.options = options;
@@ -516,6 +641,7 @@ var AuthSession = class {
     this.authorizationEndpoint = `${endpoint}/oauth/authorize`;
     this.workspaceUrl = `https://${workspace}`;
     this.resource = "resource" in options && options.resource || workspaceAudience(workspace);
+    guardBrowser(options);
   }
   options;
   endpoint;
@@ -528,7 +654,7 @@ var AuthSession = class {
   memoryTokens;
   tokenEndpoint;
   authorizationEndpoint;
-  /** The workspace's resource URL, https://<workspace>/api/v3: the audience every token is bound to. */
+  /** The workspace's resource URL, https://<workspace>/api: the audience every token is bound to. */
   resource;
   /** https://<workspace>: the default Origin for session writes. */
   workspaceUrl;
@@ -752,6 +878,9 @@ function clientConfig(opts, auth = createAuth(opts)) {
     workspace: workspaceHost(opts.workspace),
     endpoint: opts.endpoint ?? workspaceEndpoint(opts.workspace),
     token: tokenIdentityProvider(auth),
+    /** The tracer upload helpers record the byte transfer with (PROTOCOL.md 13); absent with telemetry off. */
+    caitlynTracer: opts.telemetry?.enabled === false ? void 0 : caitlynTracer(opts.telemetry?.tracerProvider),
+    ...opts.requestHandler !== void 0 ? { requestHandler: opts.requestHandler } : {},
     ...opts.maxAttempts !== void 0 ? { maxAttempts: opts.maxAttempts } : {},
     ...opts.maxRetryDelayMs !== void 0 ? { retryStrategy: new CaitlynRetryStrategy(opts.maxAttempts ?? 3, opts.maxRetryDelayMs) } : {}
   };
@@ -821,10 +950,12 @@ export {
   SseStream,
   WaiterError,
   caitlynEndpointProvider,
+  caitlynTracer,
   clientConfig,
   createAuth,
   defaultAwsCredentials,
   getCaitlynAuthPlugin,
+  getCaitlynConnectionErrorPlugin,
   getCaitlynSdkPlugin,
   getCaitlynTelemetryPlugin,
   getWebIdentityToken,