@mycadet/assistant 0.12.7 → 0.12.9

package/src/oauth/{platform-connection.test.ts → cloud-connection.test.ts}

@@ -8,19 +8,17 @@ mock.module("../util/retry.js", () => ({
   sleep: () => Promise.resolve(),
 }));
 
-import type { CadetPlatformClient } from "../platform/client.js";
+import type { CadetCloudClient } from "../cloud/client.js";
 import { BackendError, CadetError } from "../util/errors.js";
 import {
+  CloudOAuthConnection,
   CredentialRequiredError,
   InsufficientBalanceError,
-  PlatformOAuthConnection,
   ProviderUnreachableError,
   unhonoredManagedOptions,
-} from "./platform-connection.js";
+} from "./cloud-connection.js";
 
-function makeMockClient(
-  fetchImpl?: typeof globalThis.fetch,
-): CadetPlatformClient {
+function makeMockClient(fetchImpl?: typeof globalThis.fetch): CadetCloudClient {
   const mockFetchFn =
     fetchImpl ??
     (mock(async () => {
@@ -33,14 +31,14 @@ function makeMockClient(
   return {
     baseUrl: "https://platform.example.com",
     assistantApiKey: "test-api-key",
-    platformAssistantId: "asst-abc",
+    cloudAssistantId: "asst-abc",
     fetch: mock(async (path: string, init?: RequestInit) => {
       const url = `https://platform.example.com${path}`;
       const headers = new Headers(init?.headers);
       headers.set("Authorization", "Bearer test-api-key");
       return mockFetchFn(url, { ...init, headers });
     }),
-  } as unknown as CadetPlatformClient;
+  } as unknown as CadetCloudClient;
 }
 
 const DEFAULT_OPTIONS = {
@@ -52,7 +50,7 @@ const DEFAULT_OPTIONS = {
   connectionId: "platform-conn-123",
 };
 
-describe("PlatformOAuthConnection", () => {
+describe("CloudOAuthConnection", () => {
   test("successful proxied request", async () => {
     const upstreamBody = { messages: [{ id: "msg-1", snippet: "Hello" }] };
 
@@ -88,7 +86,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({
+    const conn = new CloudOAuthConnection({
       ...DEFAULT_OPTIONS,
       client,
     });
@@ -126,7 +124,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({
+    const conn = new CloudOAuthConnection({
       ...DEFAULT_OPTIONS,
       client,
     });
@@ -157,7 +155,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({
+    const conn = new CloudOAuthConnection({
       ...DEFAULT_OPTIONS,
       client,
     });
@@ -187,7 +185,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await conn.request({
       method: "GET",
       path: "/calendars/primary/events",
@@ -210,7 +208,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({
+    const conn = new CloudOAuthConnection({
       ...DEFAULT_OPTIONS,
       client,
       baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
@@ -233,7 +231,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({
+    const conn = new CloudOAuthConnection({
       ...DEFAULT_OPTIONS,
       client,
       baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
@@ -258,7 +256,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await conn.request({ method: "GET", path: "/some/path" });
   });
 
@@ -283,7 +281,7 @@ describe("PlatformOAuthConnection", () => {
       ) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
     ).rejects.toThrow(InsufficientBalanceError);
@@ -296,7 +294,7 @@ describe("PlatformOAuthConnection", () => {
       ) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
     ).rejects.toThrow(/add funds/i);
@@ -311,7 +309,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
     ).rejects.toThrow(InsufficientBalanceError);
@@ -325,7 +323,7 @@ describe("PlatformOAuthConnection", () => {
       ) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
     ).rejects.toThrow(CredentialRequiredError);
@@ -340,7 +338,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
     ).rejects.toThrow(ProviderUnreachableError);
@@ -355,7 +353,7 @@ describe("PlatformOAuthConnection", () => {
       ) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
     ).rejects.toThrow(/upstream timeout after 30s/);
@@ -376,7 +374,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     const result = await conn.request({ method: "GET", path: "/test" });
 
     expect(result.status).toBe(200);
@@ -385,9 +383,9 @@ describe("PlatformOAuthConnection", () => {
   });
 
   test("withToken throws clear error", async () => {
-    const conn = new PlatformOAuthConnection(DEFAULT_OPTIONS);
+    const conn = new CloudOAuthConnection(DEFAULT_OPTIONS);
     await expect(conn.withToken(async (token) => token)).rejects.toThrow(
-      "Raw token access is not supported for platform-managed connections. Use connection.request() instead.",
+      "Raw token access is not supported for cloud connections. Use connection.request() instead.",
     );
   });
 
@@ -406,7 +404,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     const result = await conn.request({ method: "GET", path: "/test" });
 
     expect(result.status).toBe(200);
@@ -421,7 +419,7 @@ describe("PlatformOAuthConnection", () => {
       ) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
     ).rejects.toThrow("Platform proxy returned unexpected status 429");
@@ -442,7 +440,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     const result = await conn.request({ method: "GET", path: "/test" });
 
     expect(result.status).toBe(200);
@@ -458,7 +456,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
     ).rejects.toThrow(CredentialRequiredError);
@@ -474,7 +472,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
     ).rejects.toThrow("Platform proxy returned unexpected status 403");
@@ -490,7 +488,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({
         method: "POST",
@@ -510,7 +508,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({
         method: "POST",
@@ -536,7 +534,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     const result = await conn.request({
       method: "POST",
       path: "/messages/send",
@@ -559,7 +557,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     const result = await conn.request({
       method: "POST",
       path: "/v1/payment_intents",
@@ -583,7 +581,7 @@ describe("PlatformOAuthConnection", () => {
 
     // 700 reaches `new Response(body, { status })` as a RangeError, which is
     // not a mapped error, so the caller would see an opaque 500.
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(conn.request({ method: "GET", path: "/x" })).rejects.toThrow(
       "Platform proxy returned an unusable response status: 700",
     );
@@ -598,13 +596,13 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(conn.request({ method: "GET", path: "/x" })).rejects.toThrow(
       BackendError,
     );
   });
 
-  // The platform proxy rebuilds the query from the parsed record, so managed
+  // The cloud proxy rebuilds the query from the parsed record, so managed
   // mode cannot carry a signed query string.
   test("sends the parsed query and never rawQuery", async () => {
     const client = makeMockClient(
@@ -621,7 +619,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await conn.request({
       method: "GET",
       path: "/x",
@@ -630,10 +628,10 @@ describe("PlatformOAuthConnection", () => {
     });
   });
 
-  // The platform proxy parses the response, rebuilds the query, and follows
+  // The cloud proxy parses the response, rebuilds the query, and follows
   // redirects server-side, so managed mode diverges from BYO on all three by
   // design.
-  test("names every option the platform proxy cannot honor", () => {
+  test("names every option the cloud proxy cannot honor", () => {
     expect(unhonoredManagedOptions({ method: "GET", path: "/x" })).toEqual([]);
     expect(
       unhonoredManagedOptions({
@@ -670,7 +668,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const conn = new CloudOAuthConnection({ ...DEFAULT_OPTIONS, client });
     const result = await conn.request({
       method: "GET",
       path: "/v1/redirecting",
@@ -678,7 +676,7 @@ describe("PlatformOAuthConnection", () => {
       rawResponseBody: true,
     });
 
-    // The platform already followed the redirect and parsed the body, so the
+    // The cloud already followed the redirect and parsed the body, so the
     // caller sees the destination's JSON rather than a 3xx or raw bytes.
     expect(result.status).toBe(200);
     expect(result.body).toEqual({ followed: true });
@@ -697,7 +695,7 @@ describe("PlatformOAuthConnection", () => {
       }) as unknown as typeof globalThis.fetch,
     );
 
-    const conn = new PlatformOAuthConnection({
+    const conn = new CloudOAuthConnection({
       ...DEFAULT_OPTIONS,
       client,
       provider: "slack",

package/src/oauth/{platform-connection.ts → cloud-connection.ts}

@@ -1,4 +1,4 @@
-import type { CadetPlatformClient } from "../platform/client.js";
+import type { CadetCloudClient } from "../cloud/client.js";
 import { BackendError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import { getHttpRetryDelay, isRetryableStatus, sleep } from "../util/retry.js";
@@ -36,7 +36,7 @@ export class ProviderUnreachableError extends BackendError {
 
 export class InsufficientBalanceError extends BackendError {
   constructor(
-    message = "Your Cadet account balance is too low to use this managed OAuth connection. " +
+    message = "Your Cadet account balance is too low to use this cloud OAuth connection. " +
       "You can add funds or switch to using your own OAuth app.",
   ) {
     super(message);
@@ -45,9 +45,9 @@ export class InsufficientBalanceError extends BackendError {
 }
 
 /**
- * Request options the platform proxy cannot honor. It parses the response
+ * Request options the cloud proxy cannot honor. It parses the response
  * body, rebuilds the query string from the parsed record, and follows provider
- * redirects server-side, so a managed connection answers with re-serialized
+ * redirects server-side, so a cloud connection answers with re-serialized
  * JSON, a regrouped query, and the redirect target's response. A caller that
  * needs the provider's exact bytes, its exact query string, or a verbatim 3xx
  * needs a BYO connection.
@@ -71,7 +71,7 @@ const MANAGED_PROXY_REQUEST_HEADERS = new Set([
 ]);
 
 /** Node fetch defaults can be dropped; other unsupported headers need caller handling. */
-export function prepareManagedProxyHeaders(headers: Record<string, string>): {
+export function prepareCloudProxyHeaders(headers: Record<string, string>): {
   headers: Record<string, string>;
   unsupportedHeaders: string[];
 } {
@@ -91,12 +91,12 @@ export function prepareManagedProxyHeaders(headers: Record<string, string>): {
   return { headers: forwarded, unsupportedHeaders: unsupportedHeaders.sort() };
 }
 
-export interface PlatformOAuthConnectionOptions {
+export interface CloudOAuthConnectionOptions {
   id: string;
   provider: string;
   externalId: string;
   accountInfo: string | null;
-  client: CadetPlatformClient;
+  client: CadetCloudClient;
   /** Platform-side connection ID used in the proxy URL path. */
   connectionId: string;
   /** Provider API base URL (e.g. "https://gmail.googleapis.com/gmail/v1/users/me").
@@ -104,20 +104,20 @@ export interface PlatformOAuthConnectionOptions {
   baseUrl?: string;
 }
 
-export class PlatformOAuthConnection implements OAuthConnection {
+export class CloudOAuthConnection implements OAuthConnection {
   readonly id: string;
   readonly provider: string;
   readonly externalId: string;
   readonly accountInfo: string | null;
 
-  private readonly client: CadetPlatformClient;
+  private readonly client: CadetCloudClient;
   private readonly connectionId: string;
   private readonly baseUrl: string | undefined;
 
-  constructor(options: PlatformOAuthConnectionOptions) {
+  constructor(options: CloudOAuthConnectionOptions) {
     if (!options.connectionId) {
       throw new BackendError(
-        `Platform-managed connection for "${options.provider}" cannot be created: missing connection ID. ` +
+        `Cloud connection for "${options.provider}" cannot be created: missing connection ID. ` +
           `Log in to Cadet Cloud or switch to using your own OAuth app.`,
       );
     }
@@ -132,7 +132,7 @@ export class PlatformOAuthConnection implements OAuthConnection {
   }
 
   async request(req: OAuthConnectionRequest): Promise<OAuthConnectionResponse> {
-    const proxyPath = `/v1/assistants/${this.client.platformAssistantId}/external-provider-proxy/${this.connectionId}/`;
+    const proxyPath = `/v1/assistants/${this.client.cloudAssistantId}/external-provider-proxy/${this.connectionId}/`;
 
     // The envelope carries the caller's headers and body side by side. A
     // string body is placed in the envelope as a string, so the proxy forwards
@@ -164,7 +164,7 @@ export class PlatformOAuthConnection implements OAuthConnection {
     }
 
     // A retry replays the whole request upstream, and a 502 arrives only after
-    // the platform already called the provider, so a caller forwarding a write
+    // the cloud already called the provider, so a caller forwarding a write
     // it cannot repeat gets a single attempt.
     const retriesAllowed = req.singleAttempt === true ? 0 : MAX_RETRIES;
 
@@ -192,8 +192,8 @@ export class PlatformOAuthConnection implements OAuthConnection {
         attempt < retriesAllowed
       ) {
         log.warn(
-          { status: response.status, attempt, provider: "platform-proxy" },
-          `Retryable status ${response.status} from platform proxy (attempt ${attempt + 1}/${retriesAllowed + 1})`,
+          { status: response.status, attempt, provider: "cloud-proxy" },
+          `Retryable status ${response.status} from cloud proxy (attempt ${attempt + 1}/${retriesAllowed + 1})`,
         );
         await sleep(getHttpRetryDelay(response, attempt));
         continue;
@@ -219,7 +219,7 @@ export class PlatformOAuthConnection implements OAuthConnection {
         body_encoding?: string | null;
       };
 
-      return decodePlatformProxyEnvelope(json);
+      return decodeCloudProxyEnvelope(json);
     }
 
     throw new BackendError("Platform proxy request failed after retries");
@@ -227,12 +227,12 @@ export class PlatformOAuthConnection implements OAuthConnection {
 
   async withToken<T>(_fn: (token: string) => Promise<T>): Promise<T> {
     throw new BackendError(
-      "Raw token access is not supported for platform-managed connections. Use connection.request() instead.",
+      "Raw token access is not supported for cloud connections. Use connection.request() instead.",
     );
   }
 }
 
-function decodePlatformProxyEnvelope(json: {
+function decodeCloudProxyEnvelope(json: {
   status: number;
   headers: Record<string, string>;
   body: unknown;
@@ -240,7 +240,7 @@ function decodePlatformProxyEnvelope(json: {
 }): OAuthConnectionResponse {
   // A status outside the range `Response` accepts cannot be emitted, and
   // clamping it would attribute a status to the provider that it never sent,
-  // so an unusable envelope fails as a platform fault instead.
+  // so an unusable envelope fails as a cloud fault instead.
   const { status } = json;
   if (
     !Number.isInteger(status) ||