@aui.io/aui-client 3.1.2 → 3.2.0

package/dist/cjs/ApolloClientWrapper.js

@@ -42,25 +42,18 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApolloClient = void 0;
+exports.ApolloManagementClient = exports.ApolloMessagingClient = void 0;
 const ws_1 = require("ws");
 const Client_js_1 = require("./Client.js");
 const environments_js_1 = require("./environments.js");
 const core = __importStar(require("./core/index.js"));
 const Socket_js_1 = require("./api/resources/session/client/Socket.js");
-// A publishable key is exchanged (POST /management/v1/auth/token) for a short-lived
-// bearer token; every request then sends Authorization: Bearer <token>.
 const TOKEN_EXCHANGE_PATH = "/management/v1/auth/token";
-// Re-exchange this many ms before the token expires.
 const REFRESH_SKEW_MS = 60000;
-// Messaging WebSocket channel path (relative to the environment's WS base).
 const SESSION_WS_PATH = "/messaging/v1/session";
-// The v2 messaging server negotiates this subprotocol on the WS upgrade; the
-// connection is rejected without it. Fern emits protocols: [], so we set it here.
 const WS_SUBPROTOCOL = "aui-websocket";
-// Fern injects SDK-telemetry headers (X-Fern-*) on every request. The API doesn't need
-// them, and in the browser each custom header triggers a CORS preflight that fails unless
-// the gateway allow-lists it. Passing null strips them (mergeHeaders deletes null values).
+const ORG_API_KEY_HEADER = "x-organization-api-key";
+// Strip Fern's telemetry headers (null deletes them); they trip browser CORS preflight.
 const STRIPPED_SDK_HEADERS = {
     "X-Fern-Language": null,
     "X-Fern-SDK-Name": null,
@@ -68,18 +61,13 @@ const STRIPPED_SDK_HEADERS = {
     "X-Fern-Runtime": null,
     "X-Fern-Runtime-Version": null,
 };
-// Publishable-key exchange + token caching. Kept as a standalone object so the header
-// suppliers can close over it — a subclass may not touch `this` before super() runs.
-class Auth {
-    constructor(baseUrl, publishableKey, organizationApiKey) {
+// Publishable-key exchange + token cache.
+class PkAuth {
+    constructor(baseUrl, publishableKey) {
         this.pk = publishableKey;
         this.keyType = detectKeyType(publishableKey);
-        this._staticToken = organizationApiKey;
         this._baseUrl = baseUrl;
     }
-    get hasCredential() {
-        return Boolean(this.pk || this._staticToken);
-    }
     get agentId() {
         var _a;
         return (_a = this._cache) === null || _a === void 0 ? void 0 : _a.agentId;
@@ -91,18 +79,13 @@ class Auth {
     getContext() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
-            if (this.pk)
-                yield this.getToken();
+            yield this.getToken();
             return { agentId: (_a = this._cache) === null || _a === void 0 ? void 0 : _a.agentId, organizationId: (_b = this._cache) === null || _b === void 0 ? void 0 : _b.organizationId, keyType: this.keyType };
         });
     }
     getToken() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
-            if (this._staticToken)
-                return this._staticToken;
-            if (!this.pk)
-                return "";
             if (((_a = this._cache) === null || _a === void 0 ? void 0 : _a.token) && Date.now() < this._cache.expiresAt - REFRESH_SKEW_MS) {
                 return this._cache.token;
             }
@@ -141,66 +124,74 @@ class Auth {
         });
     }
 }
-/**
- * ApolloClient adds authentication on top of the generated client: it takes a
- * publishable key (or organization API key) and handles the token exchange/refresh
- * transparently. Every generated resource (agents, threads, messaging, …) is
- * inherited unchanged.
- */
-class ApolloClient extends Client_js_1.ApolloClient {
-    constructor(options = {}) {
-        var _a;
-        const env = (_a = options.environment) !== null && _a !== void 0 ? _a : environments_js_1.ApolloEnvironment.Gcp;
-        const auth = new Auth(env.base, options.publishableKey, options.organizationApiKey);
-        super({
+// Shared base: wraps the generated client, strips telemetry headers, defaults the
+// environment, and lets each client expose only its own audience's resources. Not exported.
+class BaseApolloClient {
+    constructor(env, authHeaders) {
+        // `organizationApiKey` is typed as required by Fern but we authenticate via
+        // headers, so cast to the generated options shape.
+        this._client = new Client_js_1.ApolloClient({
             environment: env,
-            headers: Object.assign(Object.assign({}, STRIPPED_SDK_HEADERS), (auth.hasCredential ? { Authorization: () => __awaiter(this, void 0, void 0, function* () { return `Bearer ${yield auth.getToken()}`; }) } : {})),
+            headers: Object.assign(Object.assign({}, STRIPPED_SDK_HEADERS), authHeaders),
         });
-        this._tokenAuth = auth;
         this._env = env;
     }
+}
+/**
+ * Publishable-key client for end-user / widget messaging (browser-safe).
+ * Exposes the `messaging` audience only.
+ */
+class ApolloMessagingClient extends BaseApolloClient {
+    constructor(options) {
+        if (!(options === null || options === void 0 ? void 0 : options.publishableKey)) {
+            throw new Error("ApolloMessagingClient requires a publishableKey.");
+        }
+        const env = resolveEnv(options.baseUrl);
+        const auth = new PkAuth(env.base, options.publishableKey);
+        super(env, { Authorization: () => __awaiter(this, void 0, void 0, function* () { return `Bearer ${yield auth.getToken()}`; }) });
+        this._pkAuth = auth;
+    }
+    /** Send / stream messages and read thread & interaction traces. */
+    get messaging() {
+        return this._client.messaging;
+    }
+    /** Initiate channel-scoped threads (e.g. SMS). */
+    get channels() {
+        return this._client.channels;
+    }
     /** Publishable-key family (agent / org / unknown). */
     get keyType() {
-        return this._tokenAuth.keyType;
+        return this._pkAuth.keyType;
     }
     /** Agent resolved from an agent-scoped key. Populated after the first exchange. */
     get agentId() {
-        return this._tokenAuth.agentId;
+        return this._pkAuth.agentId;
     }
     /** Organization the key belongs to. Populated after the first exchange. */
     get organizationId() {
-        return this._tokenAuth.organizationId;
+        return this._pkAuth.organizationId;
     }
     /** Force a token exchange (if needed) and return the resolved scope. */
     getContext() {
-        return this._tokenAuth.getContext();
-    }
-    /**
-     * Open a messaging WebSocket session. The bearer token is passed as the first
-     * subprotocol (with `aui-websocket` second) — the gateway reads auth from
-     * Sec-WebSocket-Protocol, the only upgrade header a browser can set. The token is
-     * also sent as an Authorization header for Node. Built here (rather than via the
-     * generated session resource) so the generated code stays vanilla — Fern emits
-     * protocols: [] and forwards only per-call headers, neither of which the server accepts.
-     */
+        return this._pkAuth.getContext();
+    }
+    /** Open a messaging WebSocket session. */
     connect() {
         return __awaiter(this, arguments, void 0, function* (args = {}) {
             var _a, _b;
-            const token = yield this._tokenAuth.getToken();
+            const token = yield this._pkAuth.getToken();
             const headers = Object.assign(Object.assign({}, (token ? { Authorization: `Bearer ${token}` } : {})), args.headers);
             const socket = new core.ReconnectingWebSocket({
                 url: core.url.join(this._env.production, SESSION_WS_PATH),
-                // Order matters: the gateway treats the FIRST subprotocol as the token and
-                // requires `aui-websocket` to follow. This is what makes browser WS auth work.
+                // Token as the first subprotocol is how the gateway reads auth (browsers can't
+                // set upgrade headers); `aui-websocket` must follow.
                 protocols: token ? [token, WS_SUBPROTOCOL] : [WS_SUBPROTOCOL],
                 queryParameters: {},
                 headers,
                 options: {
                     debug: (_a = args.debug) !== null && _a !== void 0 ? _a : false,
                     maxRetries: (_b = args.reconnectAttempts) !== null && _b !== void 0 ? _b : 30,
-                    // On Node 22+ the global (undici) WebSocket drops custom headers on the
-                    // upgrade, so the bearer token never arrives. Force the `ws` library on
-                    // Node; browsers fall back to the native global WebSocket.
+                    // Node's global WebSocket drops upgrade headers; force the `ws` library there.
                     WebSocket: core.RUNTIME.type === "node" ? ws_1.WebSocket : undefined,
                 },
             });
@@ -208,7 +199,44 @@ class ApolloClient extends Client_js_1.ApolloClient {
         });
     }
 }
-exports.ApolloClient = ApolloClient;
+exports.ApolloMessagingClient = ApolloMessagingClient;
+/**
+ * Organization-API-key client for backend services and CI (server-side only).
+ * Exposes the `management` audience only.
+ */
+class ApolloManagementClient extends BaseApolloClient {
+    constructor(options) {
+        if (!(options === null || options === void 0 ? void 0 : options.organizationApiKey)) {
+            throw new Error("ApolloManagementClient requires an organizationApiKey.");
+        }
+        const env = resolveEnv(options.baseUrl);
+        super(env, { [ORG_API_KEY_HEADER]: options.organizationApiKey });
+    }
+    /** Projects: listing, retrieval, and usage. */
+    get projects() {
+        return this._client.projects;
+    }
+    /** Agents: listing, retrieval, and usage. */
+    get agents() {
+        return this._client.agents;
+    }
+    /** Agent versions. */
+    get agentVersions() {
+        return this._client.agentVersions;
+    }
+    /** Threads: listing, retrieval, updates, and traces. */
+    get threads() {
+        return this._client.threads;
+    }
+}
+exports.ApolloManagementClient = ApolloManagementClient;
+// Build the REST + WS URLs from an optional host override, deriving ws(s):// from http(s)://.
+function resolveEnv(baseUrl) {
+    if (!baseUrl)
+        return environments_js_1.ApolloEnvironment.Gcp;
+    const base = baseUrl.replace(/\/+$/, "");
+    return { base, production: base.replace(/^http/i, "ws") };
+}
 function detectKeyType(publishableKey) {
     if (!publishableKey)
         return "unknown";

package/dist/cjs/BaseClient.d.ts

@@ -4,6 +4,9 @@ export interface BaseClientOptions {
     environment?: core.Supplier<environments.ApolloEnvironment | environments.ApolloEnvironmentUrls>;
     /** Specify a custom URL to connect the client to. */
     baseUrl?: core.Supplier<string>;
+    token?: core.Supplier<core.BearerToken | undefined>;
+    /** Override the x-organization-api-key header */
+    organizationApiKey: core.Supplier<string>;
     /** Additional headers to include in requests. */
     headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
     /** The default maximum time to wait for a response in seconds. */
@@ -22,6 +25,8 @@ export interface BaseRequestOptions {
     maxRetries?: number;
     /** A hook to abort the request. */
     abortSignal?: AbortSignal;
+    /** Override the x-organization-api-key header */
+    organizationApiKey?: string;
     /** Additional query string parameters to include in the request. */
     queryParams?: Record<string, unknown>;
     /** Additional headers to include in the request. */

package/dist/cjs/Client.d.ts

@@ -24,7 +24,7 @@ export declare class ApolloClient {
     protected _channels: Channels | undefined;
     protected _auth: Auth | undefined;
     protected _session: Session | undefined;
-    constructor(_options?: ApolloClient.Options);
+    constructor(_options: ApolloClient.Options);
     get agents(): Agents;
     get agentVersions(): AgentVersions;
     get projects(): Projects;
@@ -34,6 +34,8 @@ export declare class ApolloClient {
     get auth(): Auth;
     get session(): Session;
     /**
+     * Liveness probe. Returns ``{"status": "ok"}`` when the service is up.
+     *
      * @param {ApolloClient.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @example
@@ -41,4 +43,5 @@ export declare class ApolloClient {
      */
     health(requestOptions?: ApolloClient.RequestOptions): core.HttpResponsePromise<Record<string, unknown>>;
     private __health;
+    protected _getAuthorizationHeader(): Promise<string | undefined>;
 }

package/dist/cjs/Client.js

@@ -57,12 +57,13 @@ const core = __importStar(require("./core/index.js"));
 const environments = __importStar(require("./environments.js"));
 const errors = __importStar(require("./errors/index.js"));
 class ApolloClient {
-    constructor(_options = {}) {
+    constructor(_options) {
         this._options = Object.assign(Object.assign({}, _options), { logging: core.logging.createLogger(_options === null || _options === void 0 ? void 0 : _options.logging), headers: (0, headers_js_1.mergeHeaders)({
+                "x-organization-api-key": _options === null || _options === void 0 ? void 0 : _options.organizationApiKey,
                 "X-Fern-Language": "JavaScript",
                 "X-Fern-SDK-Name": "@aui.io/aui-client",
-                "X-Fern-SDK-Version": "3.1.2",
-                "User-Agent": "@aui.io/aui-client/3.1.2",
+                "X-Fern-SDK-Version": "3.2.0",
+                "User-Agent": "@aui.io/aui-client/3.2.0",
                 "X-Fern-Runtime": core.RUNTIME.type,
                 "X-Fern-Runtime-Version": core.RUNTIME.version,
             }, _options === null || _options === void 0 ? void 0 : _options.headers) });
@@ -100,6 +101,8 @@ class ApolloClient {
         return ((_a = this._session) !== null && _a !== void 0 ? _a : (this._session = new Client_js_7.Session(this._options)));
     }
     /**
+     * Liveness probe. Returns ``{"status": "ok"}`` when the service is up.
+     *
      * @param {ApolloClient.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @example
@@ -110,17 +113,20 @@ class ApolloClient {
     }
     __health(requestOptions) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-            const _headers = (0, headers_js_1.mergeHeaders)((_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+            const _headers = (0, headers_js_1.mergeHeaders)((_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, (0, headers_js_1.mergeOnlyDefinedHeaders)({
+                Authorization: yield this._getAuthorizationHeader(),
+                "x-organization-api-key": (_b = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.organizationApiKey) !== null && _b !== void 0 ? _b : (_c = this._options) === null || _c === void 0 ? void 0 : _c.organizationApiKey,
+            }), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
             const _response = yield core.fetcher({
-                url: core.url.join((_b = (yield core.Supplier.get(this._options.baseUrl))) !== null && _b !== void 0 ? _b : ((_c = (yield core.Supplier.get(this._options.environment))) !== null && _c !== void 0 ? _c : environments.ApolloEnvironment.Gcp).base, "health"),
+                url: core.url.join((_d = (yield core.Supplier.get(this._options.baseUrl))) !== null && _d !== void 0 ? _d : ((_e = (yield core.Supplier.get(this._options.environment))) !== null && _e !== void 0 ? _e : environments.ApolloEnvironment.Gcp).base, "health"),
                 method: "GET",
                 headers: _headers,
                 queryParameters: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams,
-                timeoutMs: ((_f = (_d = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _d !== void 0 ? _d : (_e = this._options) === null || _e === void 0 ? void 0 : _e.timeoutInSeconds) !== null && _f !== void 0 ? _f : 60) * 1000,
-                maxRetries: (_g = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _g !== void 0 ? _g : (_h = this._options) === null || _h === void 0 ? void 0 : _h.maxRetries,
+                timeoutMs: ((_h = (_f = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _f !== void 0 ? _f : (_g = this._options) === null || _g === void 0 ? void 0 : _g.timeoutInSeconds) !== null && _h !== void 0 ? _h : 60) * 1000,
+                maxRetries: (_j = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _j !== void 0 ? _j : (_k = this._options) === null || _k === void 0 ? void 0 : _k.maxRetries,
                 abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
-                fetchFn: (_j = this._options) === null || _j === void 0 ? void 0 : _j.fetch,
+                fetchFn: (_l = this._options) === null || _l === void 0 ? void 0 : _l.fetch,
                 logging: this._options.logging,
             });
             if (_response.ok) {
@@ -150,5 +156,14 @@ class ApolloClient {
             }
         });
     }
+    _getAuthorizationHeader() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const bearer = yield core.Supplier.get(this._options.token);
+            if (bearer != null) {
+                return `Bearer ${bearer}`;
+            }
+            return undefined;
+        });
+    }
 }
 exports.ApolloClient = ApolloClient;

package/dist/cjs/api/resources/agentVersions/client/Client.d.ts

@@ -9,8 +9,11 @@ export declare namespace AgentVersions {
 }
 export declare class AgentVersions {
     protected readonly _options: AgentVersions.Options;
-    constructor(_options?: AgentVersions.Options);
+    constructor(_options: AgentVersions.Options);
     /**
+     * List an agent's versions, newest first. Filter by status, tag, label,
+     * or version number; set ``exclude_revisions`` to see only base versions.
+     *
      * @param {string} agentId
      * @param {Apollo.ListVersionsRequest} request
      * @param {AgentVersions.RequestOptions} requestOptions - Request-specific configuration.
@@ -28,9 +31,13 @@ export declare class AgentVersions {
      *         filters: {}
      *     })
      */
-    listVersions(agentId: string, request: Apollo.ListVersionsRequest, requestOptions?: AgentVersions.RequestOptions): core.HttpResponsePromise<Apollo.ExternalPageAgentVersion>;
+    listVersions(agentId: string, request: Apollo.ListVersionsRequest, requestOptions?: AgentVersions.RequestOptions): core.HttpResponsePromise<Apollo.PageAgentVersion>;
     private __listVersions;
     /**
+     * Create a new draft version — empty, from a template, or cloned from an
+     * existing version (``source`` selects which). Drafts stay editable until
+     * published.
+     *
      * @param {string} agentId
      * @param {Apollo.AgentVersionCreateRequest} request
      * @param {AgentVersions.RequestOptions} requestOptions - Request-specific configuration.
@@ -51,6 +58,9 @@ export declare class AgentVersions {
     createVersion(agentId: string, request: Apollo.AgentVersionCreateRequest, requestOptions?: AgentVersions.RequestOptions): core.HttpResponsePromise<Apollo.AgentVersionCreateResponse>;
     private __createVersion;
     /**
+     * Update a version's metadata: label, tags, and notes. The configuration
+     * itself changes through push, never here.
+     *
      * @param {string} agentId
      * @param {string} versionId
      * @param {Apollo.AgentVersionUpdateRequest} request
@@ -70,6 +80,10 @@ export declare class AgentVersions {
     updateVersion(agentId: string, versionId: string, request?: Apollo.AgentVersionUpdateRequest, requestOptions?: AgentVersions.RequestOptions): core.HttpResponsePromise<Apollo.AgentVersionUpdateResponse>;
     private __updateVersion;
     /**
+     * Make this version the agent's live version. Publishing a draft freezes
+     * it first; publishing an already-published version re-activates it — the
+     * same call handles shipping, switching, and rolling back.
+     *
      * @param {string} agentId
      * @param {string} versionId
      * @param {AgentVersions.RequestOptions} requestOptions - Request-specific configuration.
@@ -88,6 +102,9 @@ export declare class AgentVersions {
     publishVersion(agentId: string, versionId: string, requestOptions?: AgentVersions.RequestOptions): core.HttpResponsePromise<Apollo.AgentVersionPublishResponse>;
     private __publishVersion;
     /**
+     * Archive a version to retire it from everyday use. The agent's live
+     * version can't be archived — publish another version first.
+     *
      * @param {string} agentId
      * @param {string} versionId
      * @param {AgentVersions.RequestOptions} requestOptions - Request-specific configuration.
@@ -106,6 +123,9 @@ export declare class AgentVersions {
     archiveVersion(agentId: string, versionId: string, requestOptions?: AgentVersions.RequestOptions): core.HttpResponsePromise<Apollo.AgentVersionArchiveResponse>;
     private __archiveVersion;
     /**
+     * Upload a configuration bundle to a version, committing a new revision.
+     * The response carries the new revision's tag and content digest.
+     *
      * @param {string} agentId
      * @param {string} versionId
      * @param {Apollo.AgentVersionPushRequest} request
@@ -130,6 +150,9 @@ export declare class AgentVersions {
     pushVersion(agentId: string, versionId: string, request: Apollo.AgentVersionPushRequest, requestOptions?: AgentVersions.RequestOptions): core.HttpResponsePromise<Apollo.AgentVersionPushResponse>;
     private __pushVersion;
     /**
+     * Download a version's configuration bundle — the current revision, or a
+     * specific one via ``version_tag``.
+     *
      * @param {string} agentId
      * @param {string} versionId
      * @param {Apollo.PullVersionRequest} request
@@ -150,4 +173,5 @@ export declare class AgentVersions {
      */
     pullVersion(agentId: string, versionId: string, request?: Apollo.PullVersionRequest, requestOptions?: AgentVersions.RequestOptions): core.HttpResponsePromise<Apollo.AgentVersionPullResponse>;
     private __pullVersion;
+    protected _getAuthorizationHeader(): Promise<string | undefined>;
 }