@agent-foundry/studio 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @agent-foundry/studio
 
-Full SDK for Agent Foundry Build Studio - provides types, Alibaba Cloud OSS upload utilities, and Supabase database client.
+Full SDK for Agent Foundry Build Studio - provides types, BFF API client, Alibaba Cloud OSS upload utilities, and Supabase database client.
 
 ## Installation
 
@@ -11,86 +11,219 @@ pnpm add @agent-foundry/studio
 ## Features
 
 - **Types**: TypeScript interfaces for Studio projects, deployments, workspaces, and users
+- **BFF Client**: API client for write operations (create, update, delete projects/deployments)
 - **OSS Client**: Direct upload to Alibaba Cloud OSS with STS credentials
-- **DB Client**: Supabase client wrapper for project and deployment management
+- **DB Client**: Supabase client for read operations (list, get projects/deployments)
+
+## Recommended Usage Pattern (Hybrid Approach)
+
+Due to RLS (Row Level Security) restrictions, this SDK uses a **hybrid access pattern**:
+
+| Operation | Client | Reason |
+|-----------|--------|--------|
+| **Read** (list, get) | Supabase Client (`/db`) | Direct database access, low latency |
+| **Write** (create, update, delete) | BFF Client (`/bff`) | Bypasses RLS, server-side validation |
+| **File Upload** | DirectUploader (`/oss`) | Direct OSS upload with STS credentials |
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Desktop App / Client                     │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+            ┌───────────────┼───────────────┐
+            ▼               ▼               ▼
+     ┌────────────┐  ┌────────────┐  ┌────────────┐
+     │ BFF Client │  │ DB Client  │  │ OSS Upload │
+     │  (writes)  │  │  (reads)   │  │  (files)   │
+     └──────┬─────┘  └──────┬─────┘  └──────┬─────┘
+            │               │               │
+            ▼               ▼               ▼
+     ┌────────────┐  ┌────────────┐  ┌────────────┐
+     │  BFF API   │  │  Supabase  │  │ Alibaba    │
+     │ (FastAPI)  │  │ PostgreSQL │  │ Cloud OSS  │
+     └────────────┘  └────────────┘  └────────────┘
+```
 
 ## Usage
 
 ### Types Only
 
 ```typescript
-import type { StudioProject, Deployment, Workspace } from '@agent-foundry/studio/types';
+import type { StudioProject, Deployment } from '@agent-foundry/studio/types';
 ```
 
-### OSS Upload
+### Write Operations (BFF Client) - Recommended
+
+Use the BFF client for all write operations. It uses service_role credentials on the server side, bypassing RLS.
 
 ```typescript
-import { DirectUploader } from '@agent-foundry/studio/oss';
+import { createBFFClient } from '@agent-foundry/studio/bff';
 
-const uploader = new DirectUploader({
-  bffBaseUrl: 'http://localhost:11001',
-  authToken: 'your-supabase-jwt',
+const bff = createBFFClient({
+  baseUrl: 'http://localhost:11001',
+  authToken: 'your-supabase-jwt',  // User's access token
 });
 
-// Upload a built bundle
-const result = await uploader.upload({
-  projectId: 'project-uuid',
-  files: distFiles,
-  onProgress: (progress) => console.log(`${progress.percent}%`),
+// Create a project
+const project = await bff.projects.create({
+  name: 'My App',
+  slug: 'my-app',
+  rootPath: '/Users/me/projects/my-app',
+});
+
+// Update a project
+await bff.projects.update(project.id, {
+  name: 'My Updated App',
+});
+
+// Delete a project
+await bff.projects.delete(project.id);
+
+// Fork a project
+const fork = await bff.projects.fork(project.id, {
+  newSlug: 'my-app-fork',
+  newRootPath: '/Users/me/projects/my-app-fork',
+});
+
+// Publish to Feed
+const published = await bff.projects.publish(project.id, {
+  status: 'stable',
 });
 ```
 
-### Database Operations
+### Read Operations (Supabase Client)
+
+Use the Supabase client for read operations. Requires authenticated user's session.
 
 ```typescript
 import { createStudioClient } from '@agent-foundry/studio/db';
 
-const client = createStudioClient({
+const db = createStudioClient({
   supabaseUrl: 'https://your-project.supabase.co',
   supabaseKey: 'your-anon-key',
+  // Or pass an existing Supabase client with user session
+  existingClient: supabaseClientWithSession,
 });
 
-// Create a project
-const project = await client.projects.create({
-  name: 'My App',
-  slug: 'my-app',
-  rootPath: '/Users/me/projects/my-app',
+// List projects
+const projects = await db.projects.list({
+  framework: 'vite-react',
+  limit: 10,
+});
+
+// Get a project by ID
+const project = await db.projects.getById('project-uuid');
+
+// Get a project by slug
+const projectBySlug = await db.projects.getBySlug('my-app');
+
+// List deployments
+const deployments = await db.deployments.list({
+  projectId: 'project-uuid',
 });
 
-// Create a deployment
-const deployment = await client.deployments.create({
-  projectId: project.id,
-  version: '1.0.0',
+// Get latest published deployment
+const latest = await db.deployments.getLatestPublished('project-uuid');
+```
+
+### File Upload (OSS)
+
+Use DirectUploader for uploading build artifacts. It handles the complete workflow:
+
+1. Requests STS credentials from BFF
+2. Uploads files directly to OSS
+3. Notifies BFF of completion
+
+```typescript
+import { DirectUploader } from '@agent-foundry/studio/oss';
+
+const uploader = new DirectUploader({
+  bffBaseUrl: 'http://localhost:11001',
+  authToken: 'your-supabase-jwt',
 });
+
+// Upload a built bundle
+const result = await uploader.upload({
+  projectId: 'project-uuid',
+  files: [
+    { path: 'index.html', content: indexHtml, contentType: 'text/html' },
+    { path: 'assets/main.js', content: mainJs, contentType: 'application/javascript' },
+  ],
+  onProgress: (progress) => {
+    console.log(`${progress.stage}: ${progress.percent}%`);
+  },
+});
+
+if (result.success) {
+  console.log(`Deployed to: ${result.url}`);
+}
 ```
 
-## Architecture
+## Why Hybrid Approach?
+
+1. **Security**: Write operations go through BFF with service_role, no need to expose sensitive keys
+2. **Performance**: Read operations use direct Supabase connection, minimal latency
+3. **Validation**: BFF can validate writes (slug uniqueness, path validation, etc.)
+4. **Consistency**: Deployment state machine is controlled server-side
+
+## Testing
+
+### Unit Tests
 
+```bash
+pnpm test          # Run all unit tests
+pnpm test:watch    # Watch mode
 ```
-┌─────────────────────────────────────────────────────────┐
-│                   Tauri Desktop App                      │
-│  ┌─────────────────┐    ┌─────────────────────────────┐ │
-│  │   Studio UI     │    │   OpenCode Server (Hono)    │ │
-│  │   (React)       │    │                             │ │
-│  └────────┬────────┘    └─────────────────────────────┘ │
-└───────────┼─────────────────────────────────────────────┘
-            │
-            ▼
-┌─────────────────────────────────────────────────────────┐
-│              @agent-foundry/studio Package               │
-│  ┌──────────┐  ┌──────────────┐  ┌──────────────────┐   │
-│  │  Types   │  │  OSS Client  │  │  Supabase Client │   │
-│  └──────────┘  └──────┬───────┘  └────────┬─────────┘   │
-└─────────────────────────┼──────────────────┼────────────┘
-                          │                  │
-            ┌─────────────┘                  │
-            ▼                                ▼
-   ┌────────────────┐              ┌────────────────────┐
-   │ Alibaba Cloud  │              │     Supabase       │
-   │     OSS        │              │   PostgreSQL       │
-   └────────────────┘              └────────────────────┘
+
+### Integration Tests
+
+Integration tests run against a real BFF deployment:
+
+```bash
+# Set required environment variables
+export BFF_URL=http://localhost:11001
+export SUPABASE_JWT_SECRET=your-secret
+
+# Run integration tests
+pnpm test:integration
 ```
 
+See [test/README.md](test/README.md) for detailed test documentation.
+
+## API Reference
+
+### BFF Client (`@agent-foundry/studio/bff`)
+
+- `createBFFClient(config)` - Create BFF client
+- `bff.projects.create(input)` - Create project
+- `bff.projects.get(id)` - Get project
+- `bff.projects.list(options)` - List projects
+- `bff.projects.update(id, input)` - Update project
+- `bff.projects.delete(id)` - Delete project
+- `bff.projects.fork(id, options)` - Fork project
+- `bff.projects.publish(id, options)` - Publish to Feed
+- `bff.deployments.start(input)` - Start deployment
+- `bff.deployments.get(id)` - Get deployment
+- `bff.deployments.list(projectId, limit)` - List deployments
+- `bff.deployments.updateStatus(id, input)` - Update status
+- `bff.deployments.complete(id, input)` - Mark complete
+- `bff.deployments.fail(id, input)` - Mark failed
+
+### DB Client (`@agent-foundry/studio/db`)
+
+- `createStudioClient(config)` - Create Supabase client
+- `db.projects.getById(id)` - Get project by ID
+- `db.projects.getBySlug(slug)` - Get project by slug
+- `db.projects.list(filters)` - List projects
+- `db.deployments.getById(id)` - Get deployment by ID
+- `db.deployments.list(filters)` - List deployments
+- `db.deployments.getLatestPublished(projectId)` - Get latest published
+
+### OSS Client (`@agent-foundry/studio/oss`)
+
+- `DirectUploader` - High-level upload client
+- `AliOSSClient` - Low-level OSS client
+
 ## License
 
 MIT

package/dist/bff/client.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 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, ProjectResponse, ProjectListResponse, StartDeploymentResponse, UpdateDeploymentStatusRequest, CompleteDeploymentRequest, CompleteDeploymentResponse, FailDeploymentRequest, DeploymentListResponse, PublishRequest, PublishResponse } from './types';
+/**
+ * Error thrown by BFF API client
+ */
+export declare class BFFAPIError extends Error {
+    readonly status: number;
+    readonly detail?: string | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, detail?: string | undefined, code?: string | undefined);
+}
+/**
+ * Projects API client
+ */
+export declare class ProjectsAPI {
+    private readonly baseUrl;
+    private readonly authToken;
+    private readonly timeout;
+    constructor(baseUrl: string, authToken: string, timeout: number);
+    private get headers();
+    private request;
+    /**
+     * Create a new project
+     */
+    create(input: CreateProjectInput): Promise<StudioProject>;
+    /**
+     * Get a project by ID
+     */
+    get(id: string): Promise<ProjectResponse>;
+    /**
+     * List all projects with optional pagination
+     */
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+        framework?: string;
+        search?: string;
+    }): Promise<ProjectListResponse>;
+    /**
+     * Update a project
+     */
+    update(id: string, input: UpdateProjectInput): Promise<StudioProject>;
+    /**
+     * Delete a project
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Fork a project
+     */
+    fork(id: string, options: {
+        newSlug: string;
+        newRootPath: string;
+        newName?: string;
+    }): Promise<StudioProject>;
+    /**
+     * Publish a project to Feed
+     */
+    publish(id: string, options?: PublishRequest): Promise<PublishResponse>;
+}
+/**
+ * Deployments API client
+ */
+export declare class DeploymentsAPI {
+    private readonly baseUrl;
+    private readonly authToken;
+    private readonly timeout;
+    constructor(baseUrl: string, authToken: string, timeout: number);
+    private get headers();
+    private request;
+    /**
+     * Start a new deployment (creates deployment record and returns STS credentials)
+     */
+    start(input: {
+        projectId: string;
+        version?: string;
+        metadata?: Partial<DeploymentMetadata>;
+    }): Promise<StartDeploymentResponse>;
+    /**
+     * Get a deployment by ID
+     */
+    get(id: string): Promise<Deployment>;
+    /**
+     * List deployments for a project
+     */
+    list(projectId: string, limit?: number): Promise<DeploymentListResponse>;
+    /**
+     * Update deployment status
+     */
+    updateStatus(id: string, input: UpdateDeploymentStatusRequest): Promise<{
+        status: string;
+        deploymentId: string;
+    }>;
+    /**
+     * Mark deployment as complete (after successful OSS upload)
+     */
+    complete(id: string, input: CompleteDeploymentRequest): Promise<CompleteDeploymentResponse>;
+    /**
+     * Mark deployment as failed
+     */
+    fail(id: string, input: FailDeploymentRequest): Promise<{
+        status: string;
+        deploymentId: string;
+    }>;
+}
+/**
+ * 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 declare function createBFFClient(config: BFFClientConfig): BFFClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/bff/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bff/client.ts"],"names":[],"mappings":"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"}