@agent-foundry/studio 1.0.1 → 1.0.2

package/src/bff/client.ts

@@ -0,0 +1,412 @@
+/**
+ * BFF API Client
+ *
+ * Client for interacting with the BFF Studio API endpoints.
+ * All write operations (create, update, delete) should go through this client.
+ *
+ * The BFF uses SQLAlchemy with service_role credentials, which bypasses RLS.
+ * This is the secure and recommended way to perform write operations.
+ *
+ * @example
+ * ```typescript
+ * import { createBFFClient } from '@agent-foundry/studio/bff';
+ *
+ * const client = createBFFClient({
+ *   baseUrl: 'http://localhost:11001',
+ *   authToken: 'your-supabase-jwt',
+ * });
+ *
+ * // Create a project
+ * const project = await client.projects.create({
+ *   name: 'My App',
+ *   slug: 'my-app',
+ *   rootPath: '/Users/me/projects/my-app',
+ * });
+ * ```
+ */
+
+import type { StudioProject, CreateProjectInput, UpdateProjectInput } from '../types/project';
+import type { Deployment, DeploymentMetadata } from '../types/deployment';
+import type {
+  BFFClientConfig,
+  CreateProjectRequest,
+  UpdateProjectRequest,
+  ForkProjectRequest,
+  ProjectResponse,
+  ProjectListResponse,
+  StartDeploymentRequest,
+  StartDeploymentResponse,
+  UpdateDeploymentStatusRequest,
+  CompleteDeploymentRequest,
+  CompleteDeploymentResponse,
+  FailDeploymentRequest,
+  DeploymentListResponse,
+  PublishRequest,
+  PublishResponse,
+  APIError,
+} from './types';
+
+/**
+ * Error thrown by BFF API client
+ */
+export class BFFAPIError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly detail?: string,
+    public readonly code?: string
+  ) {
+    super(message);
+    this.name = 'BFFAPIError';
+  }
+}
+
+/**
+ * Projects API client
+ */
+export class ProjectsAPI {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly authToken: string,
+    private readonly timeout: number
+  ) {}
+
+  private get headers(): HeadersInit {
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.authToken}`,
+    };
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        let detail: string | undefined;
+        let code: string | undefined;
+        try {
+          const error: APIError = await response.json();
+          detail = error.detail;
+          code = error.code;
+        } catch {
+          detail = await response.text();
+        }
+        throw new BFFAPIError(
+          `BFF API error: ${response.status}`,
+          response.status,
+          detail,
+          code
+        );
+      }
+
+      // Handle 204 No Content
+      if (response.status === 204) {
+        return undefined as T;
+      }
+
+      return response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Create a new project
+   */
+  async create(input: CreateProjectInput): Promise<StudioProject> {
+    const request: CreateProjectRequest = {
+      name: input.name,
+      slug: input.slug,
+      description: input.description,
+      rootPath: input.rootPath,
+      framework: input.framework,
+      config: input.config,
+      parentProjectId: input.parentProjectId,
+    };
+
+    return this.request<ProjectResponse>('POST', '/studio/projects', request);
+  }
+
+  /**
+   * Get a project by ID
+   */
+  async get(id: string): Promise<ProjectResponse> {
+    return this.request<ProjectResponse>('GET', `/studio/projects/${id}`);
+  }
+
+  /**
+   * List all projects with optional pagination
+   */
+  async list(options?: {
+    page?: number;
+    pageSize?: number;
+    framework?: string;
+    search?: string;
+  }): Promise<ProjectListResponse> {
+    const params = new URLSearchParams();
+    if (options?.page) params.set('page', String(options.page));
+    if (options?.pageSize) params.set('pageSize', String(options.pageSize));
+    if (options?.framework) params.set('framework', options.framework);
+    if (options?.search) params.set('search', options.search);
+
+    const query = params.toString();
+    const path = query ? `/studio/projects?${query}` : '/studio/projects';
+    return this.request<ProjectListResponse>('GET', path);
+  }
+
+  /**
+   * Update a project
+   */
+  async update(id: string, input: UpdateProjectInput): Promise<StudioProject> {
+    const request: UpdateProjectRequest = {
+      name: input.name,
+      description: input.description,
+      config: input.config,
+    };
+
+    return this.request<ProjectResponse>('PUT', `/studio/projects/${id}`, request);
+  }
+
+  /**
+   * Delete a project
+   */
+  async delete(id: string): Promise<void> {
+    return this.request<void>('DELETE', `/studio/projects/${id}`);
+  }
+
+  /**
+   * Fork a project
+   */
+  async fork(
+    id: string,
+    options: { newSlug: string; newRootPath: string; newName?: string }
+  ): Promise<StudioProject> {
+    const request: ForkProjectRequest = {
+      newSlug: options.newSlug,
+      newRootPath: options.newRootPath,
+      newName: options.newName,
+    };
+
+    return this.request<ProjectResponse>('POST', `/studio/projects/${id}/fork`, request);
+  }
+
+  /**
+   * Publish a project to Feed
+   */
+  async publish(
+    id: string,
+    options?: PublishRequest
+  ): Promise<PublishResponse> {
+    return this.request<PublishResponse>(
+      'POST',
+      `/studio/projects/${id}/publish`,
+      options ?? {}
+    );
+  }
+}
+
+/**
+ * Deployments API client
+ */
+export class DeploymentsAPI {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly authToken: string,
+    private readonly timeout: number
+  ) {}
+
+  private get headers(): HeadersInit {
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.authToken}`,
+    };
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        let detail: string | undefined;
+        let code: string | undefined;
+        try {
+          const error: APIError = await response.json();
+          detail = error.detail;
+          code = error.code;
+        } catch {
+          detail = await response.text();
+        }
+        throw new BFFAPIError(
+          `BFF API error: ${response.status}`,
+          response.status,
+          detail,
+          code
+        );
+      }
+
+      return response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Start a new deployment (creates deployment record and returns STS credentials)
+   */
+  async start(input: {
+    projectId: string;
+    version?: string;
+    metadata?: Partial<DeploymentMetadata>;
+  }): Promise<StartDeploymentResponse> {
+    const request: StartDeploymentRequest = {
+      projectId: input.projectId,
+      version: input.version,
+      metadata: input.metadata,
+    };
+
+    return this.request<StartDeploymentResponse>(
+      'POST',
+      '/studio/deployments/start',
+      request
+    );
+  }
+
+  /**
+   * Get a deployment by ID
+   */
+  async get(id: string): Promise<Deployment> {
+    return this.request<Deployment>('GET', `/studio/deployments/${id}`);
+  }
+
+  /**
+   * List deployments for a project
+   */
+  async list(projectId: string, limit?: number): Promise<DeploymentListResponse> {
+    const params = new URLSearchParams();
+    if (limit) params.set('limit', String(limit));
+
+    const query = params.toString();
+    const path = query
+      ? `/studio/projects/${projectId}/deployments?${query}`
+      : `/studio/projects/${projectId}/deployments`;
+
+    return this.request<DeploymentListResponse>('GET', path);
+  }
+
+  /**
+   * Update deployment status
+   */
+  async updateStatus(
+    id: string,
+    input: UpdateDeploymentStatusRequest
+  ): Promise<{ status: string; deploymentId: string }> {
+    return this.request<{ status: string; deploymentId: string }>(
+      'PUT',
+      `/studio/deployments/${id}/status`,
+      input
+    );
+  }
+
+  /**
+   * Mark deployment as complete (after successful OSS upload)
+   */
+  async complete(
+    id: string,
+    input: CompleteDeploymentRequest
+  ): Promise<CompleteDeploymentResponse> {
+    return this.request<CompleteDeploymentResponse>(
+      'POST',
+      `/studio/deployments/${id}/complete`,
+      input
+    );
+  }
+
+  /**
+   * Mark deployment as failed
+   */
+  async fail(
+    id: string,
+    input: FailDeploymentRequest
+  ): Promise<{ status: string; deploymentId: string }> {
+    return this.request<{ status: string; deploymentId: string }>(
+      'POST',
+      `/studio/deployments/${id}/fail`,
+      input
+    );
+  }
+}
+
+/**
+ * BFF Client - main entry point for BFF API operations
+ */
+export interface BFFClient {
+  /** Projects API */
+  readonly projects: ProjectsAPI;
+
+  /** Deployments API */
+  readonly deployments: DeploymentsAPI;
+}
+
+/**
+ * Create a new BFF client
+ *
+ * @param config - Client configuration
+ * @returns BFFClient instance
+ *
+ * @example
+ * ```typescript
+ * const client = createBFFClient({
+ *   baseUrl: 'http://localhost:11001',
+ *   authToken: 'your-supabase-jwt',
+ * });
+ *
+ * // Create a project
+ * const project = await client.projects.create({
+ *   name: 'My App',
+ *   slug: 'my-app',
+ *   rootPath: '/Users/me/projects/my-app',
+ * });
+ *
+ * // Start a deployment
+ * const deployment = await client.deployments.start({
+ *   projectId: project.id,
+ * });
+ * ```
+ */
+export function createBFFClient(config: BFFClientConfig): BFFClient {
+  const timeout = config.timeout ?? 30000;
+
+  return {
+    projects: new ProjectsAPI(config.baseUrl, config.authToken, timeout),
+    deployments: new DeploymentsAPI(config.baseUrl, config.authToken, timeout),
+  };
+}

package/src/bff/index.ts

@@ -0,0 +1,32 @@
+/**
+ * BFF module - API client for BFF Studio endpoints
+ *
+ * Use this for all write operations (create, update, delete).
+ * The BFF uses SQLAlchemy with service_role credentials, which bypasses RLS.
+ *
+ * @example
+ * ```typescript
+ * import { createBFFClient } from '@agent-foundry/studio/bff';
+ *
+ * const client = createBFFClient({
+ *   baseUrl: 'http://localhost:11001',
+ *   authToken: 'your-supabase-jwt',
+ * });
+ *
+ * // Create a project (write operation via BFF)
+ * const project = await client.projects.create({
+ *   name: 'My App',
+ *   slug: 'my-app',
+ *   rootPath: '/path/to/project',
+ * });
+ * ```
+ */
+
+export * from './types';
+export {
+  createBFFClient,
+  BFFAPIError,
+  ProjectsAPI,
+  DeploymentsAPI,
+} from './client';
+export type { BFFClient } from './client';

package/src/bff/types.ts

@@ -0,0 +1,212 @@
+/**
+ * BFF API Types
+ *
+ * Response types from the BFF Studio API endpoints.
+ * These match the Pydantic models in services/bff/app/models/studio.py
+ */
+
+import type {
+  StudioProject,
+  ProjectConfig,
+  ProjectFramework,
+} from '../types/project';
+import type {
+  DeploymentStatus,
+  DeploymentMetadata,
+  AppManifest,
+} from '../types/deployment';
+
+// =============================================================================
+// Project API Types
+// =============================================================================
+
+/**
+ * Request body for creating a project via BFF
+ */
+export interface CreateProjectRequest {
+  name: string;
+  slug: string;
+  description?: string;
+  rootPath: string;
+  framework?: ProjectFramework;
+  config?: ProjectConfig;
+  parentProjectId?: string;
+}
+
+/**
+ * Request body for updating a project via BFF
+ */
+export interface UpdateProjectRequest {
+  name?: string;
+  description?: string;
+  config?: Partial<ProjectConfig>;
+}
+
+/**
+ * Request body for forking a project via BFF
+ */
+export interface ForkProjectRequest {
+  newSlug: string;
+  newRootPath: string;
+  newName?: string;
+}
+
+/**
+ * Project response from BFF API
+ */
+export interface ProjectResponse extends StudioProject {
+  latestDeployment?: DeploymentSummary;
+}
+
+/**
+ * Paginated project list response
+ */
+export interface ProjectListResponse {
+  projects: ProjectResponse[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+// =============================================================================
+// Deployment API Types
+// =============================================================================
+
+/**
+ * Deployment summary (for lists)
+ */
+export interface DeploymentSummary {
+  id: string;
+  version: string;
+  status: DeploymentStatus;
+  ossUrl?: string;
+  bundleSizeBytes?: number;
+  createdAt: string;
+  publishedAt?: string;
+}
+
+/**
+ * Request body for starting a deployment
+ */
+export interface StartDeploymentRequest {
+  projectId: string;
+  version?: string;
+  metadata?: Partial<DeploymentMetadata>;
+}
+
+/**
+ * STS credentials for OSS upload
+ */
+export interface STSCredentials {
+  accessKeyId: string;
+  accessKeySecret: string;
+  securityToken: string;
+  expiration: string;
+}
+
+/**
+ * Response from starting a deployment
+ */
+export interface StartDeploymentResponse {
+  deploymentId: string;
+  credentials: STSCredentials;
+  bucket: string;
+  region: string;
+  keyPrefix: string;
+}
+
+/**
+ * Request body for updating deployment status
+ */
+export interface UpdateDeploymentStatusRequest {
+  status: DeploymentStatus;
+  buildLog?: string;
+  errorMessage?: string;
+  metadata?: Partial<DeploymentMetadata>;
+}
+
+/**
+ * Request body for completing a deployment
+ */
+export interface CompleteDeploymentRequest {
+  bucket: string;
+  keyPrefix: string;
+  ossUrl: string;
+  totalBytes: number;
+  fileCount: number;
+}
+
+/**
+ * Response from completing a deployment
+ */
+export interface CompleteDeploymentResponse {
+  deploymentId: string;
+  ossUrl: string;
+  version: string;
+}
+
+/**
+ * Request body for failing a deployment
+ */
+export interface FailDeploymentRequest {
+  errorMessage: string;
+  buildLog?: string;
+}
+
+/**
+ * Deployment list response
+ */
+export interface DeploymentListResponse {
+  deployments: DeploymentSummary[];
+  total: number;
+}
+
+// =============================================================================
+// Publish API Types
+// =============================================================================
+
+/**
+ * Request body for publishing to Feed
+ */
+export interface PublishRequest {
+  deploymentId?: string;
+  manifest?: AppManifest;
+  status?: 'canary' | 'stable';
+}
+
+/**
+ * Response from publishing to Feed
+ */
+export interface PublishResponse {
+  appId: string;
+  artifactId: string;
+  deploymentId: string;
+  shareUrl: string;
+  entryUrl: string;
+}
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+/**
+ * API error response
+ */
+export interface APIError {
+  detail: string;
+  code?: string;
+}
+
+/**
+ * BFF client configuration
+ */
+export interface BFFClientConfig {
+  /** BFF base URL (e.g., "http://localhost:11001") */
+  baseUrl: string;
+
+  /** Supabase JWT token for authentication */
+  authToken: string;
+
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+}