@agent-foundry/studio 1.0.1 → 1.0.2

package/src/db/deployments.ts

@@ -1,7 +1,38 @@
 /**
  * Deployments Repository
  *
- * CRUD operations for studio_deployments table.
+ * Provides access to studio_deployments table via Supabase client.
+ *
+ * ## Important: Hybrid Access Pattern
+ *
+ * Due to RLS (Row Level Security) restrictions, this repository should
+ * primarily be used for **read operations only**.
+ *
+ * **For write operations, use the BFF client or DirectUploader:**
+ *
+ * ```typescript
+ * import { DirectUploader } from '@agent-foundry/studio/oss';
+ *
+ * // DirectUploader handles the complete deployment workflow via BFF
+ * const uploader = new DirectUploader({
+ *   bffBaseUrl: 'http://localhost:11001',
+ *   authToken: 'your-jwt-token',
+ * });
+ *
+ * const result = await uploader.upload({
+ *   projectId: 'project-uuid',
+ *   files: distFiles,
+ * });
+ * ```
+ *
+ * Or use the BFF client directly:
+ *
+ * ```typescript
+ * import { createBFFClient } from '@agent-foundry/studio/bff';
+ *
+ * const bff = createBFFClient({ ... });
+ * const deployment = await bff.deployments.start({ projectId: '...' });
+ * ```
  */
 
 import { SupabaseClient } from '@supabase/supabase-js';
@@ -81,6 +112,12 @@ export class DeploymentsRepository {
 
   /**
    * Create a new deployment
+   *
+   * @deprecated Use `DirectUploader.upload()` or `createBFFClient().deployments.start()` instead.
+   *
+   * This method may fail with RLS errors. The recommended workflow is:
+   * 1. Use DirectUploader which handles the complete deployment lifecycle
+   * 2. Or use BFF client's deployments.start() to get STS credentials
    */
   async create(input: CreateDeploymentInput): Promise<Deployment> {
     const { data: { user } } = await this.supabase.auth.getUser();
@@ -170,6 +207,10 @@ export class DeploymentsRepository {
 
   /**
    * Update a deployment
+   *
+   * @deprecated Use `createBFFClient().deployments.updateStatus()` instead.
+   *
+   * This method may fail with RLS errors. Use BFF client for write operations.
    */
   async update(id: string, input: UpdateDeploymentInput): Promise<Deployment> {
     const updateData: Record<string, unknown> = {};
@@ -223,6 +264,8 @@ export class DeploymentsRepository {
 
   /**
    * Mark deployment as building
+   *
+   * @deprecated Use `createBFFClient().deployments.updateStatus()` instead.
    */
   async markBuilding(id: string): Promise<Deployment> {
     return this.update(id, { status: 'building' });
@@ -230,6 +273,8 @@ export class DeploymentsRepository {
 
   /**
    * Mark deployment as uploading
+   *
+   * @deprecated Use `createBFFClient().deployments.updateStatus()` instead.
    */
   async markUploading(id: string): Promise<Deployment> {
     return this.update(id, { status: 'uploading' });
@@ -237,6 +282,8 @@ export class DeploymentsRepository {
 
   /**
    * Mark deployment as published
+   *
+   * @deprecated Use `createBFFClient().deployments.complete()` instead.
    */
   async markPublished(
     id: string,
@@ -254,6 +301,8 @@ export class DeploymentsRepository {
 
   /**
    * Mark deployment as failed
+   *
+   * @deprecated Use `createBFFClient().deployments.fail()` instead.
    */
   async markFailed(id: string, errorMessage: string, buildLog?: string): Promise<Deployment> {
     return this.update(id, {
@@ -288,6 +337,9 @@ export class DeploymentsRepository {
 
   /**
    * Delete a deployment
+   *
+   * @deprecated Deployment deletion should be handled server-side.
+   * This method may fail with RLS errors.
    */
   async delete(id: string): Promise<void> {
     const { error } = await this.supabase
@@ -302,6 +354,9 @@ export class DeploymentsRepository {
 
   /**
    * Append to build log
+   *
+   * @deprecated Use `createBFFClient().deployments.updateStatus()` with buildLog field.
+   * This method may fail with RLS errors.
    */
   async appendBuildLog(id: string, logLine: string): Promise<void> {
     const existing = await this.getById(id);
@@ -318,6 +373,9 @@ export class DeploymentsRepository {
 
   /**
    * Link deployment to an artifact (called after publishing to Feed)
+   *
+   * @deprecated This is handled automatically by BFF's publish workflow.
+   * Use `createBFFClient().projects.publish()` instead.
    */
   async linkToArtifact(id: string, artifactId: string): Promise<Deployment> {
     const { data, error } = await this.supabase

package/src/db/index.ts

@@ -1,5 +1,22 @@
 /**
  * Database module - Supabase client for Studio
+ *
+ * ## Important: Read-Only Usage Recommended
+ *
+ * Due to RLS (Row Level Security), this module should primarily be used
+ * for **read operations only**. For write operations, use the BFF client:
+ *
+ * ```typescript
+ * // Read operations - use this module
+ * import { createStudioClient } from '@agent-foundry/studio/db';
+ * const db = createStudioClient({ supabaseUrl: '...', supabaseKey: '...' });
+ * const projects = await db.projects.list();
+ *
+ * // Write operations - use BFF client
+ * import { createBFFClient } from '@agent-foundry/studio/bff';
+ * const bff = createBFFClient({ baseUrl: '...', authToken: '...' });
+ * const project = await bff.projects.create({ ... });
+ * ```
  */
 
 export { createStudioClient, type StudioClientConfig } from './client';

package/src/db/projects.ts

@@ -1,7 +1,29 @@
 /**
  * Projects Repository
  *
- * CRUD operations for studio_projects table.
+ * Provides access to studio_projects table via Supabase client.
+ *
+ * ## Important: Hybrid Access Pattern
+ *
+ * Due to RLS (Row Level Security) restrictions, this repository should
+ * primarily be used for **read operations only**.
+ *
+ * **For write operations (create, update, delete, fork), use the BFF client:**
+ *
+ * ```typescript
+ * import { createBFFClient } from '@agent-foundry/studio/bff';
+ *
+ * const bff = createBFFClient({
+ *   baseUrl: 'http://localhost:11001',
+ *   authToken: 'your-jwt-token',
+ * });
+ *
+ * // Create project via BFF (recommended)
+ * const project = await bff.projects.create({ ... });
+ * ```
+ *
+ * The BFF uses service_role credentials which bypass RLS, ensuring
+ * consistent and secure write operations.
  */
 
 import { SupabaseClient } from '@supabase/supabase-js';
@@ -61,6 +83,11 @@ export class ProjectsRepository {
 
   /**
    * Create a new project
+   *
+   * @deprecated Use BFF client instead: `createBFFClient().projects.create()`
+   *
+   * This method may fail with RLS errors when using anon key.
+   * The BFF client uses service_role credentials which bypass RLS.
    */
   async create(input: CreateProjectInput): Promise<StudioProject> {
     const { data: { user } } = await this.supabase.auth.getUser();
@@ -171,6 +198,11 @@ export class ProjectsRepository {
 
   /**
    * Update a project
+   *
+   * @deprecated Use BFF client instead: `createBFFClient().projects.update()`
+   *
+   * This method may fail with RLS errors when using anon key.
+   * The BFF client uses service_role credentials which bypass RLS.
    */
   async update(id: string, input: UpdateProjectInput): Promise<StudioProject> {
     const updateData: Record<string, unknown> = {};
@@ -206,6 +238,11 @@ export class ProjectsRepository {
 
   /**
    * Delete a project
+   *
+   * @deprecated Use BFF client instead: `createBFFClient().projects.delete()`
+   *
+   * This method may fail with RLS errors when using anon key.
+   * The BFF client uses service_role credentials which bypass RLS.
    */
   async delete(id: string): Promise<void> {
     const { error } = await this.supabase
@@ -220,6 +257,11 @@ export class ProjectsRepository {
 
   /**
    * Fork a project (create a copy)
+   *
+   * @deprecated Use BFF client instead: `createBFFClient().projects.fork()`
+   *
+   * This method may fail with RLS errors when using anon key.
+   * The BFF client uses service_role credentials which bypass RLS.
    */
   async fork(id: string, newSlug: string, newRootPath: string): Promise<StudioProject> {
     const original = await this.getById(id);
@@ -248,6 +290,9 @@ export class ProjectsRepository {
 
   /**
    * Link project to a registered app (called after publishing to Feed)
+   *
+   * @deprecated This is handled automatically by BFF's publish workflow.
+   * Use `createBFFClient().projects.publish()` instead.
    */
   async linkToApp(id: string, appId: string): Promise<StudioProject> {
     const { data, error } = await this.supabase

package/src/index.ts

@@ -2,7 +2,18 @@
  * @agent-foundry/studio
  *
  * Full SDK for Agent Foundry Build Studio.
- * Provides types, Alibaba Cloud OSS upload utilities, and Supabase database client.
+ * Provides types, Alibaba Cloud OSS upload utilities, BFF API client, and Supabase database client.
+ *
+ * ## Recommended Usage Pattern (Hybrid Approach)
+ *
+ * - **Write operations**: Use BFF client (`@agent-foundry/studio/bff`)
+ * - **Read operations**: Use Supabase client (`@agent-foundry/studio/db`)
+ * - **File uploads**: Use DirectUploader (`@agent-foundry/studio/oss`)
+ *
+ * This pattern ensures:
+ * - Security: Write operations go through BFF with service_role (bypasses RLS)
+ * - Performance: Read operations use direct Supabase connection
+ * - Consistency: All writes are validated server-side
  */
 
 // Re-export all types
@@ -11,7 +22,12 @@ export * from './types';
 // Re-export OSS utilities
 export * from './oss';
 
-// Re-export database client
+// Re-export BFF API client (recommended for write operations)
+// Note: Use '@agent-foundry/studio/bff' for full BFF types
+export { createBFFClient, BFFAPIError } from './bff';
+export type { BFFClient, BFFClientConfig } from './bff';
+
+// Re-export database client (recommended for read operations only)
 export * from './db';
 
 // Re-export utilities