@agent-foundry/studio

Full SDK for Agent Foundry Build Studio - provides types, BFF API client, Alibaba Cloud OSS upload utilities, and Supabase database client.

Installation

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 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

import type { StudioProject, Deployment } from '@agent-foundry/studio/types';

Write Operations (BFF Client) - Recommended

Use the BFF client for all write operations. It uses service_role credentials on the server side, bypassing RLS.

import { createBFFClient } from '@agent-foundry/studio/bff';

const bff = createBFFClient({
  baseUrl: 'http://localhost:11001',
  authToken: 'your-supabase-jwt',  // User's access token
});

// 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',
});

Read Operations (Supabase Client)

Use the Supabase client for read operations. Requires authenticated user's session.

import { createStudioClient } from '@agent-foundry/studio/db';

const db = createStudioClient({
  supabaseUrl: 'https://your-project.supabase.co',
  supabaseKey: 'your-anon-key',
  // Or pass an existing Supabase client with user session
  existingClient: supabaseClientWithSession,
});

// 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',
});

// 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

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}`);
}

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

pnpm test          # Run all unit tests
pnpm test:watch    # Watch mode

Integration Tests

Integration tests run against a real BFF deployment:

# 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 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