@agent-os-sdk/client 0.1.2 → 0.2.2

package/src/client/AgentOsClient.ts

@@ -2,25 +2,40 @@
  * Agent OS SDK - Main Client
  * 
  * Fully typed API client for Agent OS platform.
- * All HTTP calls must go through this client.
+ * Supports both API Token (server) and JWT (browser) authentication.
  * 
  * @example
  * ```ts
+ * // API Token (server-to-server)
  * const api = new AgentOsClient({
- *   baseUrl: "http://localhost:5000",
- *   tenantId: "...",
- *   workspaceId: "...",
- *   token: "...",
+ *   baseUrl: "https://api.agentos.io",
+ *   auth: { type: "api_token", apiKey: "aosk_live_xxx" }
  * });
  * 
- * const run = await api.runs.create({
- *   agent_id: "...",
- *   input: { message: "Hello" },
+ * // JWT (browser)
+ * const api = new AgentOsClient({
+ *   baseUrl: "https://api.agentos.io",
+ *   auth: {
+ *     type: "jwt",
+ *     getToken: () => supabase.auth.getSession().then(s => s.data.session?.access_token),
+ *     getWorkspaceId: () => localStorage.getItem("agentos.workspaceId")!
+ *   }
  * });
  * ```
  */
 
 import { createRawClient, type RawClient } from "./raw.js";
+import {
+    type AgentOsClientOptions,
+    type AgentOsClientOptionsLegacy,
+    type AuthProvider,
+    isNewAuthOptions,
+    isApiTokenAuth,
+    isJwtAuth,
+    isApiToken,
+    isBrowser,
+} from "./auth.js";
+
 import { AgentsModule } from "../modules/agents.js";
 import { RunsModule } from "../modules/runs.js";
 import { ThreadsModule } from "../modules/threads.js";
@@ -64,35 +79,21 @@ import { DeploymentsModule } from "../modules/deployments.js";
 import { IncidentsModule } from "../modules/incidents.js";
 import { ArtifactsModule } from "../modules/artifacts.js";
 
-export type AgentOsClientOptions = {
-    /** Base URL of the Agent OS API (Control Plane) */
-    baseUrl: string;
-
-    /** Tenant ID (multi-tenant) */
-    tenantId: string;
-
-    /** Workspace ID */
-    workspaceId: string;
-
-    /** Optional auth token */
-    token?: string;
-
-    /** Optional member ID (for identity header) */
-    memberId?: string;
-
-    /** Custom headers */
-    headers?: Record<string, string>;
-};
+// Re-export auth types
+export type { AgentOsClientOptions, AgentOsClientOptionsLegacy, AuthProvider } from "./auth.js";
+export { isApiTokenAuth, isJwtAuth, isNewAuthOptions } from "./auth.js";
 
 export class AgentOsClient {
     private readonly _client: RawClient;
     private readonly _baseUrl: string;
-    private readonly _tenantId: string;
-    private readonly _workspaceId: string;
-    private readonly _token?: string;
-    private readonly _memberId?: string;
+    private readonly _auth: AuthProvider | null;
     private readonly _customHeaders: Record<string, string>;
 
+    // Legacy fields (for backwards compat)
+    private readonly _tenantId?: string;
+    private readonly _workspaceId?: string;
+    private readonly _token?: string;
+    private readonly _memberId?: string;
 
     // Core modules
     /** Agents API: CRUD, versions, graph */
@@ -156,62 +157,70 @@ export class AgentOsClient {
     /** Graphs API: Validation and introspection */
     readonly graphs: GraphsModule;
 
-    // MOCK - Future modules (marked for replacement when backend is ready)
-    /** Handoff API: Multi-agent delegation */
+    // MOCK - Future modules
     readonly handoff: HandoffModule;
-    /** Flows API: Workflow orchestration */
     readonly flows: FlowsModule;
-    /** Capabilities API: Agent/run permissions */
     readonly capabilities: CapabilitiesModule;
-    /** Policies API: Governance rules */
     readonly policies: PoliciesModule;
-    /** Approvals API: Human-in-the-loop */
     readonly approvals: ApprovalsModule;
-    /** Budgets API: Cost control */
     readonly budgets: BudgetsModule;
-    /** Deployments API: Release management */
     readonly deployments: DeploymentsModule;
-    /** Incidents API: Operational incidents & SLOs */
     readonly incidents: IncidentsModule;
-    /** Artifacts API: Output management */
     readonly artifacts: ArtifactsModule;
 
-    // ======================== Convenience Aliases ========================
-    /**
-     * Alias for evaluation.listExperiments() - provides first-level access to experiments
-     * @example client.experiments.list() // same as client.evaluation.listExperiments()
-     */
+    // Convenience Aliases
     readonly experiments: {
         list: EvaluationModule["listExperiments"];
         get: EvaluationModule["getExperiment"];
         create: EvaluationModule["createExperiment"];
     };
 
-    /**
-     * Alias for agents.listVersions() - provides first-level access to agent versions
-     */
     readonly agentVersions: {
         list: (agentId: string) => ReturnType<AgentsModule["listVersions"]>;
         get: (agentId: string, versionId: string) => ReturnType<AgentsModule["getVersion"]>;
         create: (agentId: string, body: Parameters<AgentsModule["createVersion"]>[1]) => ReturnType<AgentsModule["createVersion"]>;
     };
 
-    constructor(options: AgentOsClientOptions) {
+    constructor(options: AgentOsClientOptions | AgentOsClientOptionsLegacy) {
         this._baseUrl = options.baseUrl;
-        this._tenantId = options.tenantId;
-        this._workspaceId = options.workspaceId;
-        this._token = options.token;
-        this._memberId = options.memberId;
         this._customHeaders = options.headers ?? {};
 
+        // Detect auth mode
+        if (isNewAuthOptions(options)) {
+            // New auth provider mode
+            this._auth = options.auth;
+            this._validateAuth(options);
+        } else {
+            // Legacy mode - convert to new auth if possible
+            this._tenantId = options.tenantId;
+            this._workspaceId = options.workspaceId;
+            this._token = options.token;
+            this._memberId = options.memberId;
+
+            // Attempt to detect auth type from token
+            if (options.token && isApiToken(options.token)) {
+                // Token looks like API token - use as api_token
+                this._auth = { type: "api_token", apiKey: options.token };
+                console.warn(
+                    "[AgentOS SDK] Using legacy options with API token. " +
+                    "Consider migrating to: new AgentOsClient({ auth: { type: 'api_token', apiKey: '...' } })"
+                );
+            } else {
+                // Legacy JWT mode - keep using headers
+                this._auth = null;
+            }
+        }
+
+        // Create raw HTTP client
         this._client = createRawClient({
             baseUrl: options.baseUrl,
-            headers: this._getHeaders(),
+            headers: {}, // Headers resolved dynamically
         });
 
+        // Bound header getter
         const getHeaders = () => this._getHeaders();
-        const getWorkspaceId = () => this._workspaceId;
-        const getTenantId = () => this._tenantId;
+        const getWorkspaceId = () => this._getWorkspaceIdSync();
+        const getTenantId = () => this._tenantId ?? "";
 
         // Initialize core modules
         this.agents = new AgentsModule(this._client, getHeaders);
@@ -271,33 +280,142 @@ export class AgentOsClient {
         };
     }
 
+    /**
+     * Validate auth configuration
+     */
+    private _validateAuth(options: AgentOsClientOptions): void {
+        const { auth, allowApiTokenInBrowser } = options;
+
+        // Browser guard for API tokens
+        if (isApiTokenAuth(auth) && isBrowser() && !allowApiTokenInBrowser) {
+            throw new Error(
+                "[AgentOS SDK] API tokens should not be used in the browser. " +
+                "They may be exposed in network requests. " +
+                "Use JWT auth for browser clients, or set allowApiTokenInBrowser: true if you understand the risks."
+            );
+        }
+    }
+
+    /**
+     * Get headers for current request (sync version for modules)
+     */
     private _getHeaders(): Record<string, string> {
         const headers: Record<string, string> = {
             "Content-Type": "application/json",
-            "X-Tenant-Id": this._tenantId,
-            "X-Workspace-Id": this._workspaceId,
             ...this._customHeaders,
         };
 
-        if (this._token) {
-            headers["Authorization"] = `Bearer ${this._token}`;
+        if (this._auth) {
+            // New auth mode
+            if (isApiTokenAuth(this._auth)) {
+                // API Token: Only Authorization header
+                const apiKey = typeof this._auth.apiKey === "function"
+                    ? "" // Will be resolved async
+                    : this._auth.apiKey;
+                if (apiKey) {
+                    headers["Authorization"] = `Bearer ${apiKey}`;
+                }
+                // NO X-Tenant-Id, NO X-Workspace-Id (backend resolves from claims)
+            } else if (isJwtAuth(this._auth)) {
+                // JWT: Authorization + X-Workspace-Id
+                // Note: For sync header getter, we use empty strings as placeholders
+                // The actual values are resolved in _getHeadersAsync
+                // This is a limitation of the current module architecture
+            }
+        } else {
+            // Legacy mode - use stored values
+            if (this._token) {
+                headers["Authorization"] = `Bearer ${this._token}`;
+            }
+            if (this._tenantId) {
+                headers["X-Tenant-Id"] = this._tenantId;
+            }
+            if (this._workspaceId) {
+                headers["X-Workspace-Id"] = this._workspaceId;
+            }
+            if (this._memberId) {
+                headers["X-Member-Id"] = this._memberId;
+            }
         }
 
-        if (this._memberId) {
-            headers["X-Member-Id"] = this._memberId;
+        return headers;
+    }
+
+    /**
+     * Get headers for current request (async version - resolves auth functions)
+     */
+    async getHeadersAsync(): Promise<Record<string, string>> {
+        const headers: Record<string, string> = {
+            "Content-Type": "application/json",
+            ...this._customHeaders,
+        };
+
+        if (this._auth) {
+            if (isApiTokenAuth(this._auth)) {
+                // API Token
+                const apiKey = typeof this._auth.apiKey === "function"
+                    ? await this._auth.apiKey()
+                    : this._auth.apiKey;
+                headers["Authorization"] = `Bearer ${apiKey}`;
+                // NO X-Tenant-Id, NO X-Workspace-Id
+            } else if (isJwtAuth(this._auth)) {
+                // JWT
+                const [token, workspaceId] = await Promise.all([
+                    this._auth.getToken(),
+                    this._auth.getWorkspaceId(),
+                ]);
+
+                if (!token) {
+                    throw new Error("[AgentOS SDK] JWT token not available. User may not be authenticated.");
+                }
+                if (!workspaceId) {
+                    throw new Error("[AgentOS SDK] Workspace ID not available. Please select a workspace first.");
+                }
+
+                headers["Authorization"] = `Bearer ${token}`;
+                headers["X-Workspace-Id"] = workspaceId;
+                // NO X-Tenant-Id (backend derives from workspace membership)
+            }
+        } else {
+            // Legacy mode
+            if (this._token) {
+                headers["Authorization"] = `Bearer ${this._token}`;
+            }
+            if (this._tenantId) {
+                headers["X-Tenant-Id"] = this._tenantId;
+            }
+            if (this._workspaceId) {
+                headers["X-Workspace-Id"] = this._workspaceId;
+            }
+            if (this._memberId) {
+                headers["X-Member-Id"] = this._memberId;
+            }
         }
 
         return headers;
     }
 
-    /** Current tenant ID */
+    /**
+     * Get workspace ID synchronously (for modules that need it)
+     */
+    private _getWorkspaceIdSync(): string {
+        return this._workspaceId ?? "";
+    }
+
+    /** Current tenant ID (legacy) */
     get tenantId(): string {
-        return this._tenantId;
+        return this._tenantId ?? "";
     }
 
-    /** Current workspace ID */
+    /** Current workspace ID (legacy) */
     get workspaceId(): string {
-        return this._workspaceId;
+        return this._workspaceId ?? "";
+    }
+
+    /** Auth provider type */
+    get authType(): "api_token" | "jwt" | "legacy" {
+        if (!this._auth) return "legacy";
+        return this._auth.type;
     }
 
     /** Raw HTTP client (use modules instead) */

package/src/client/auth.ts

@@ -0,0 +1,148 @@
+/**
+ * Auth Provider Types for Agent OS SDK
+ * 
+ * Supports two modes:
+ * - JWT (browser): Uses Supabase JWT + workspace header
+ * - API Token (server): Uses aosk_* token with embedded claims
+ */
+
+// ============================================================================
+// Auth Provider Types
+// ============================================================================
+
+/**
+ * API Token authentication for server-to-server integrations.
+ * Token format: aosk_live_* or aosk_test_*
+ * 
+ * @example
+ * ```ts
+ * const client = new AgentOsClient({
+ *   baseUrl: "https://api.example.com",
+ *   auth: { type: "api_token", apiKey: "aosk_live_xxx" }
+ * })
+ * ```
+ */
+export type ApiTokenAuth = {
+    type: "api_token"
+    /** API key (aosk_*) or function that returns one */
+    apiKey: string | (() => string | Promise<string>)
+}
+
+/**
+ * JWT authentication for browser/frontend clients.
+ * Uses Supabase JWT with workspace header.
+ * 
+ * @example
+ * ```ts
+ * const client = new AgentOsClient({
+ *   baseUrl: "https://api.example.com",
+ *   auth: {
+ *     type: "jwt",
+ *     getToken: async () => (await supabase.auth.getSession()).data.session?.access_token,
+ *     getWorkspaceId: () => localStorage.getItem("agentos.workspaceId")!,
+ *   }
+ * })
+ * ```
+ */
+export type JwtAuth = {
+    type: "jwt"
+    /** Function to get the JWT access token */
+    getToken: () => string | Promise<string>
+    /** Function to get the current workspace ID */
+    getWorkspaceId: () => string | Promise<string>
+}
+
+/**
+ * Auth provider union type
+ */
+export type AuthProvider = ApiTokenAuth | JwtAuth
+
+// ============================================================================
+// Client Options
+// ============================================================================
+
+/**
+ * New auth-aware options for AgentOsClient
+ */
+export type AgentOsClientOptions = {
+    /** Base URL of the Agent OS Control Plane */
+    baseUrl: string
+    /** Authentication provider */
+    auth: AuthProvider
+    /** 
+     * Allow API token in browser environment.
+     * Default: false (throws error to prevent accidental exposure)
+     */
+    allowApiTokenInBrowser?: boolean
+    /** Custom headers to add to all requests */
+    headers?: Record<string, string>
+}
+
+/**
+ * Legacy options (backwards compatibility)
+ * @deprecated Use AgentOsClientOptions with auth provider instead
+ */
+export type AgentOsClientOptionsLegacy = {
+    /** Base URL of the Agent OS API */
+    baseUrl: string
+    /** Tenant ID @deprecated */
+    tenantId: string
+    /** Workspace ID @deprecated */
+    workspaceId: string
+    /** Auth token @deprecated */
+    token?: string
+    /** Member ID @deprecated */
+    memberId?: string
+    /** Custom headers */
+    headers?: Record<string, string>
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isNewAuthOptions(
+    opts: AgentOsClientOptions | AgentOsClientOptionsLegacy
+): opts is AgentOsClientOptions {
+    return "auth" in opts && opts.auth !== undefined
+}
+
+export function isLegacyOptions(
+    opts: AgentOsClientOptions | AgentOsClientOptionsLegacy
+): opts is AgentOsClientOptionsLegacy {
+    return "tenantId" in opts || "workspaceId" in opts
+}
+
+export function isApiTokenAuth(auth: AuthProvider): auth is ApiTokenAuth {
+    return auth.type === "api_token"
+}
+
+export function isJwtAuth(auth: AuthProvider): auth is JwtAuth {
+    return auth.type === "jwt"
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Detect browser environment
+ */
+export function isBrowser(): boolean {
+    return typeof window !== "undefined" && typeof document !== "undefined"
+}
+
+/**
+ * Check if token looks like an API token (aosk_*)
+ */
+export function isApiToken(token: string): boolean {
+    return token.startsWith("aosk_")
+}
+
+/**
+ * Check if token looks like a JWT (three base64 segments)
+ */
+export function isJwtToken(token: string): boolean {
+    const parts = token.split(".")
+    return parts.length === 3 && parts.every(p => p.length > 0)
+}