@agent-os-sdk/client 0.9.25 → 0.9.27

package/src/client/auth.ts

@@ -1,136 +0,0 @@
-/**
- * Auth Provider Types for Agent OS SDK
- * 
- * Two modes only:
- * - JWT (browser): Uses Supabase JWT + X-Workspace-Id header
- * - API Token (server): Uses aosk_* token with embedded claims
- */
-
-import type { NetworkConfig } from "./config.js";
-import type { SDKHooks } from "./raw.js";
-import type { OperationContextProvider } from "./OperationContextProvider.js";
-
-// ============================================================================
-// Auth Provider Types
-// ============================================================================
-
-/**
- * API Token authentication for server-to-server integrations.
- * Token format: aosk_live_* or aosk_test_*
- * 
- * SECURITY: API tokens contain embedded workspace/tenant claims.
- * The SDK sends ONLY Authorization header (no X-Workspace-Id, no X-Tenant-Id).
- * 
- * @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 X-Workspace-Id header.
- * 
- * SECURITY: 
- * - X-Workspace-Id is REQUIRED (throws if missing)
- * - X-Tenant-Id is NEVER sent (backend derives from workspace membership)
- * 
- * @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 (REQUIRED) */
-    getWorkspaceId: () => string | Promise<string>
-}
-
-/**
- * Auth provider union type - only two modes supported
- */
-export type AuthProvider = ApiTokenAuth | JwtAuth
-
-// ============================================================================
-// Client Options
-// ============================================================================
-
-/**
- * Options for AgentOsClient - auth is REQUIRED
- */
-export type AgentOsClientOptions = {
-    /** Base URL of the Agent OS Control Plane */
-    baseUrl: string
-    /** Authentication provider (REQUIRED) */
-    auth: AuthProvider
-    /** 
-     * Allow API token in browser environment.
-     * Default: false (throws error to prevent accidental exposure)
-     * Only set to true if you understand the security implications.
-     */
-    allowApiTokenInBrowser?: boolean
-    /** Network policy (timeouts/retries). */
-    network?: Partial<NetworkConfig>
-    /** Optional request lifecycle hooks for observability */
-    hooks?: SDKHooks
-    /** Optional flow context provider (ALS/manual) for sticky correlation per operation. */
-    /** Recommended for long-lived server clients to avoid process-wide sticky fallback correlation. */
-    contextProvider?: OperationContextProvider
-    /** Custom headers to add to all requests */
-    headers?: Record<string, string>
-}
-
-// ============================================================================
-// Type Guards
-// ============================================================================
-
-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)
-}

package/src/client/config.ts

@@ -1,100 +0,0 @@
-/**
- * Agent OS SDK - Network Configuration
- * 
- * Centralized configuration for timeouts, retries, and network policies.
- */
-
-/**
- * Retry configuration for network requests.
- */
-export interface RetryConfig {
-    /** Maximum retry attempts (default: 3) */
-    maxRetries: number;
-
-    /** Base delay between retries in ms (default: 1000) */
-    baseDelayMs: number;
-
-    /** Maximum delay between retries in ms (default: 30000) */
-    maxDelayMs: number;
-
-    /** Jitter factor to prevent thundering herd (0-1, default: 0.2) */
-    jitterFactor: number;
-
-    /** HTTP status codes that trigger retry (default: [408, 429, 500, 502, 503, 504]) */
-    retryableStatuses: number[];
-}
-
-/**
- * Full network configuration for the SDK client.
- */
-export interface NetworkConfig {
-    /** Timeout per request attempt in milliseconds (default: 30000) */
-    timeoutMs: number;
-
-    /** Retry configuration */
-    retry: RetryConfig;
-}
-
-/**
- * Default network configuration.
- * Balanced for most use cases - 30s timeout, 3 retries with exponential backoff.
- */
-export const DEFAULT_NETWORK_CONFIG: NetworkConfig = {
-    timeoutMs: 30_000,
-    retry: {
-        maxRetries: 3,
-        baseDelayMs: 1_000,
-        maxDelayMs: 30_000,
-        jitterFactor: 0.2,
-        retryableStatuses: [408, 429, 500, 502, 503, 504],
-    },
-};
-
-/**
- * Aggressive configuration for interactive UIs.
- * Shorter timeouts, fewer retries.
- */
-export const INTERACTIVE_NETWORK_CONFIG: NetworkConfig = {
-    timeoutMs: 10_000,
-    retry: {
-        maxRetries: 1,
-        baseDelayMs: 500,
-        maxDelayMs: 5_000,
-        jitterFactor: 0.1,
-        retryableStatuses: [429, 503, 504],
-    },
-};
-
-/**
- * Patient configuration for background jobs.
- * Longer timeouts, more retries.
- */
-export const BACKGROUND_NETWORK_CONFIG: NetworkConfig = {
-    timeoutMs: 120_000,
-    retry: {
-        maxRetries: 5,
-        baseDelayMs: 2_000,
-        maxDelayMs: 60_000,
-        jitterFactor: 0.3,
-        retryableStatuses: [408, 429, 500, 502, 503, 504],
-    },
-};
-
-/**
- * Merges user config with defaults.
- */
-export function mergeNetworkConfig(
-    userConfig?: Partial<NetworkConfig>
-): NetworkConfig {
-    if (!userConfig) {
-        return DEFAULT_NETWORK_CONFIG;
-    }
-
-    return {
-        timeoutMs: userConfig.timeoutMs ?? DEFAULT_NETWORK_CONFIG.timeoutMs,
-        retry: {
-            ...DEFAULT_NETWORK_CONFIG.retry,
-            ...userConfig.retry,
-        },
-    };
-}

package/src/client/helpers.ts

@@ -1,98 +0,0 @@
-/**
- * SDK Helper Types and Functions
- * 
- * Provides utilities for working with API responses.
- */
-
-import type { APIResponse } from "./raw.js";
-
-// ============================================================================
-// Pagination
-// ============================================================================
-
-/**
- * Standard pagination parameters used across all list endpoints.
- * Extends Record to be compatible with query parameter types.
- */
-export interface PaginationParams extends Record<string, unknown> {
-    /** Maximum number of items to return (default: 20) */
-    limit?: number;
-    /** Number of items to skip (default: 0) */
-    offset?: number;
-}
-
-/**
- * Paginated list response wrapper.
- */
-export interface PaginatedResponse<T> {
-    items: T[];
-    total: number;
-}
-
-// ============================================================================
-// Error Handling
-// ============================================================================
-
-/**
- * SDK-specific error class with structured error data.
- */
-export class SDKError extends Error {
-    readonly code: string;
-    readonly status: number;
-    readonly details?: unknown;
-
-    constructor(response: APIResponse<unknown>) {
-        const message = response.error?.message || `HTTP ${response.response.status}`;
-        super(message);
-        this.name = "SDKError";
-        this.code = response.error?.code || `HTTP_${response.response.status}`;
-        this.status = response.response.status;
-        this.details = response.error?.details;
-    }
-}
-
-/**
- * Unwraps an APIResponse, returning the data directly or throwing on error.
- * Use this when you want the cleaner "throws on error" pattern.
- * 
- * @example
- * ```ts
- * // Instead of:
- * const { data, error } = await client.agents.list();
- * if (error) throw new Error(error.message);
- * 
- * // Use:
- * const agents = await unwrap(client.agents.list());
- * ```
- */
-export async function unwrap<T>(promise: Promise<APIResponse<T>>): Promise<T> {
-    const result = await promise;
-    if (result.error || !result.data) {
-        throw new SDKError(result);
-    }
-    return result.data;
-}
-
-/**
- * Type helper for unwrapped responses.
- */
-export type Unwrapped<T> = T extends APIResponse<infer U> ? U : never;
-
-// ============================================================================
-// Result Pattern (Alternative to exceptions)
-// ============================================================================
-
-export type Result<T, E = SDKError> =
-    | { success: true; data: T }
-    | { success: false; error: E };
-
-/**
- * Converts an APIResponse to a Result type for pattern matching.
- */
-export async function toResult<T>(promise: Promise<APIResponse<T>>): Promise<Result<T>> {
-    const result = await promise;
-    if (result.error || !result.data) {
-        return { success: false, error: new SDKError(result) };
-    }
-    return { success: true, data: result.data };
-}

package/src/client/pagination.ts

@@ -1,218 +0,0 @@
-/**
- * Agent OS SDK - Pagination Utilities
- * 
- * Auto-paginating iterators that support both offset and cursor pagination.
- * Designed to work with any list endpoint.
- */
-
-import type { APIResponse } from "./raw.js";
-
-// ============================================================================
-// Response Types
-// ============================================================================
-
-/**
- * Offset-based paginated response.
- * Most common format for list endpoints.
- */
-export interface OffsetPaginatedResponse<T> {
-    items: T[];
-    total: number;
-}
-
-/**
- * Cursor-based paginated response.
- * Better for large datasets and real-time consistency.
- */
-export interface CursorPaginatedResponse<T> {
-    items: T[];
-    next_cursor?: string;
-    has_more: boolean;
-}
-
-/**
- * Union type for both pagination styles.
- */
-export type PaginatedResponse<T> =
-    | OffsetPaginatedResponse<T>
-    | CursorPaginatedResponse<T>;
-
-// ============================================================================
-// Parameter Types
-// ============================================================================
-
-/**
- * Offset pagination parameters.
- */
-export interface OffsetParams {
-    limit?: number;
-    offset?: number;
-}
-
-/**
- * Cursor pagination parameters.
- */
-export interface CursorParams {
-    limit?: number;
-    after?: string;
-}
-
-/**
- * Combined pagination parameters.
- */
-export type PaginationParams = OffsetParams | CursorParams;
-
-// ============================================================================
-// Type Guards
-// ============================================================================
-
-/**
- * Checks if response uses cursor pagination.
- */
-function isCursorResponse<T>(response: PaginatedResponse<T>): response is CursorPaginatedResponse<T> {
-    return "has_more" in response;
-}
-
-// ============================================================================
-// Paginate Function
-// ============================================================================
-
-/**
- * Options for pagination behavior.
- */
-export interface PaginateOptions {
-    /** Number of items per page (default: 100) */
-    pageSize?: number;
-
-    /** Maximum total items to fetch (default: unlimited) */
-    maxItems?: number;
-
-    /** AbortSignal for cancellation */
-    signal?: AbortSignal;
-}
-
-/**
- * Creates an async iterator that automatically paginates through results.
- * Supports both offset and cursor pagination transparently.
- * 
- * @example
- * // Basic usage
- * for await (const run of paginate(
- *     (p) => client.runs.list(p),
- *     { status: "completed" }
- * )) {
- *     console.log(run.id);
- * }
- * 
- * @example
- * // With options
- * for await (const agent of paginate(
- *     (p) => client.agents.list(p),
- *     { workspace_id: "ws_123" },
- *     { pageSize: 50, maxItems: 200 }
- * )) {
- *     console.log(agent.name);
- * }
- */
-export async function* paginate<T, P extends PaginationParams>(
-    fetchPage: (params: P) => Promise<APIResponse<PaginatedResponse<T>>>,
-    baseParams: Omit<P, "limit" | "offset" | "after">,
-    options?: PaginateOptions
-): AsyncGenerator<T, void, unknown> {
-    const pageSize = options?.pageSize ?? 100;
-    const maxItems = options?.maxItems ?? Infinity;
-    const signal = options?.signal;
-
-    let offset = 0;
-    let cursor: string | undefined;
-    let hasMore = true;
-    let yielded = 0;
-
-    while (hasMore && yielded < maxItems) {
-        // Check for cancellation
-        if (signal?.aborted) {
-            return;
-        }
-
-        // Build params based on pagination style
-        const params = {
-            ...baseParams,
-            limit: Math.min(pageSize, maxItems - yielded),
-            ...(cursor !== undefined ? { after: cursor } : { offset }),
-        } as P;
-
-        const response = await fetchPage(params);
-
-        if (response.error) {
-            throw response.error;
-        }
-
-        const data = response.data!;
-
-        for (const item of data.items) {
-            if (yielded >= maxItems) {
-                return;
-            }
-            yield item;
-            yielded++;
-        }
-
-        // Update pagination state based on response type
-        if (isCursorResponse(data)) {
-            cursor = data.next_cursor;
-            hasMore = data.has_more && data.items.length > 0;
-        } else {
-            offset += data.items.length;
-            hasMore = offset < data.total && data.items.length > 0;
-        }
-    }
-}
-
-// ============================================================================
-// Collect Utility
-// ============================================================================
-
-/**
- * Collects all items from a paginated endpoint into an array.
- * Useful when you need all items at once.
- * 
- * @example
- * const allRuns = await collectAll(
- *     (p) => client.runs.list(p),
- *     { status: "completed" },
- *     { maxItems: 1000 }
- * );
- */
-export async function collectAll<T, P extends PaginationParams>(
-    fetchPage: (params: P) => Promise<APIResponse<PaginatedResponse<T>>>,
-    baseParams: Omit<P, "limit" | "offset" | "after">,
-    options?: PaginateOptions
-): Promise<T[]> {
-    const items: T[] = [];
-
-    for await (const item of paginate(fetchPage, baseParams, options)) {
-        items.push(item);
-    }
-
-    return items;
-}
-
-/**
- * Gets the first item from a paginated endpoint.
- * More efficient than collecting all items when you only need one.
- * 
- * @example
- * const latestRun = await getFirst(
- *     (p) => client.runs.list({ ...p, order: "desc" }),
- *     { agent_id: "agent_123" }
- * );
- */
-export async function getFirst<T, P extends PaginationParams>(
-    fetchPage: (params: P) => Promise<APIResponse<PaginatedResponse<T>>>,
-    baseParams: Omit<P, "limit" | "offset" | "after">
-): Promise<T | undefined> {
-    for await (const item of paginate(fetchPage, baseParams, { pageSize: 1, maxItems: 1 })) {
-        return item;
-    }
-    return undefined;
-}