@agent-os-sdk/client 0.1.1 → 0.2.1

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";
@@ -53,38 +68,32 @@ import { InfoModule } from "../modules/info.js";
 import { MetricsModule } from "../modules/metrics.js";
 import { GraphsModule } from "../modules/graphs.js";
 
-export type AgentOsClientOptions = {
-    /** Base URL of the Agent OS API */
-    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;
+// MOCK - Future modules (marked for replacement when backend is ready)
+import { HandoffModule } from "../modules/handoff.js";
+import { FlowsModule } from "../modules/flows.js";
+import { CapabilitiesModule } from "../modules/capabilities.js";
+import { PoliciesModule } from "../modules/policies.js";
+import { ApprovalsModule } from "../modules/approvals.js";
+import { BudgetsModule } from "../modules/budgets.js";
+import { DeploymentsModule } from "../modules/deployments.js";
+import { IncidentsModule } from "../modules/incidents.js";
+import { ArtifactsModule } from "../modules/artifacts.js";
 
-    /** Custom headers */
-    headers?: Record<string, string>;
-
-    /** Kernel base URL (for meta-agent, different from control plane) */
-    kernelBaseUrl?: 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 _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;
-    private readonly _customHeaders: Record<string, string>;
-    private readonly _kernelBaseUrl: string;
 
     // Core modules
     /** Agents API: CRUD, versions, graph */
@@ -148,43 +157,70 @@ export class AgentOsClient {
     /** Graphs API: Validation and introspection */
     readonly graphs: GraphsModule;
 
-    // ======================== Convenience Aliases ========================
-    /**
-     * Alias for evaluation.listExperiments() - provides first-level access to experiments
-     * @example client.experiments.list() // same as client.evaluation.listExperiments()
-     */
+    // MOCK - Future modules
+    readonly handoff: HandoffModule;
+    readonly flows: FlowsModule;
+    readonly capabilities: CapabilitiesModule;
+    readonly policies: PoliciesModule;
+    readonly approvals: ApprovalsModule;
+    readonly budgets: BudgetsModule;
+    readonly deployments: DeploymentsModule;
+    readonly incidents: IncidentsModule;
+    readonly artifacts: ArtifactsModule;
+
+    // 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._kernelBaseUrl = options.kernelBaseUrl ?? options.baseUrl.replace(':5000', ':8001');
-        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);
@@ -194,7 +230,7 @@ export class AgentOsClient {
         this.knowledge = new KnowledgeModule(this._client, getWorkspaceId, getHeaders);
         this.triggers = new TriggersModule(this._client, getHeaders);
         this.credentials = new CredentialsModule(this._client, getWorkspaceId, getHeaders);
-        this.builder = new BuilderModule(this._kernelBaseUrl, getHeaders);
+        this.builder = new BuilderModule(this._baseUrl, getHeaders);
         this.members = new MembersModule(this._client, getHeaders);
         this.tenants = new TenantsModule(this._client, getHeaders);
         this.workspaces = new WorkspacesModule(this._client, getTenantId, getHeaders);
@@ -219,6 +255,17 @@ export class AgentOsClient {
         this.metrics = new MetricsModule(this._baseUrl, getHeaders);
         this.graphs = new GraphsModule(this._client, getHeaders);
 
+        // MOCK - Initialize future modules
+        this.handoff = new HandoffModule(this._client, getHeaders);
+        this.flows = new FlowsModule(this._client, getHeaders);
+        this.capabilities = new CapabilitiesModule(this._client, getHeaders);
+        this.policies = new PoliciesModule(this._client, getHeaders);
+        this.approvals = new ApprovalsModule(this._client, getHeaders);
+        this.budgets = new BudgetsModule(this._client, getHeaders);
+        this.deployments = new DeploymentsModule(this._client, getHeaders);
+        this.incidents = new IncidentsModule(this._client, getHeaders);
+        this.artifacts = new ArtifactsModule(this._client, getHeaders);
+
         // Initialize convenience aliases
         this.experiments = {
             list: this.evaluation.listExperiments.bind(this.evaluation),
@@ -233,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)
+}