137 lines
3.8 KiB
Markdown
137 lines
3.8 KiB
Markdown
# Stitch SDK API Reference
|
|
|
|
Condensed reference for `@google/stitch-sdk`. Agent-optimized — covers common operations only.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @google/stitch-sdk
|
|
# Optional: Vercel AI SDK integration
|
|
npm install @google/stitch-sdk ai
|
|
```
|
|
|
|
## Authentication
|
|
|
|
```bash
|
|
export STITCH_API_KEY="sk_..." # From https://stitch.withgoogle.com/settings/api
|
|
```
|
|
|
|
SDK auto-reads `STITCH_API_KEY` from environment. No explicit config needed.
|
|
|
|
## Core API
|
|
|
|
### Stitch (root singleton)
|
|
|
|
```typescript
|
|
import { stitch } from "@google/stitch-sdk";
|
|
|
|
const projects = await stitch.projects(); // List all projects
|
|
const project = stitch.project("my-id"); // Get project handle (sync)
|
|
```
|
|
|
|
### Project
|
|
|
|
```typescript
|
|
const project = stitch.project("project-123"); // sync — returns handle
|
|
|
|
// Generate screen from prompt (positional params, uppercase device types)
|
|
const screen = await project.generate(
|
|
"Login page with email/password",
|
|
"MOBILE" // optional: "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC"
|
|
);
|
|
|
|
const screens = await project.screens(); // List all screens
|
|
const screen = await project.getScreen(screenId); // Get specific screen
|
|
```
|
|
|
|
### Screen
|
|
|
|
```typescript
|
|
// Export
|
|
const htmlUrl = await screen.getHtml(); // Returns download URL (HTML + Tailwind)
|
|
const imageUrl = await screen.getImage(); // Returns download URL (PNG screenshot)
|
|
|
|
// Edit/refine (positional: prompt, deviceType?, modelId?)
|
|
const edited = await screen.edit("Make colors darker, add search bar");
|
|
|
|
// Generate variants (positional: prompt, variantOptions, deviceType?, modelId?)
|
|
const variants = await screen.variants("Different color schemes", {
|
|
variantCount: 3, // 1-5 variants
|
|
creativeRange: "medium", // "low" | "medium" | "high"
|
|
aspects: ["COLOR_SCHEME"] // "COLOR_SCHEME" | "LAYOUT" | etc.
|
|
});
|
|
```
|
|
|
|
### StitchToolClient (low-level MCP access)
|
|
|
|
```typescript
|
|
import { StitchToolClient } from "@google/stitch-sdk";
|
|
|
|
const client = new StitchToolClient({ apiKey: "sk_..." });
|
|
const tools = await client.listTools();
|
|
const result = await client.callTool("create_project", { title: "My App" });
|
|
```
|
|
|
|
### Vercel AI SDK Integration
|
|
|
|
```typescript
|
|
import { stitchTools } from "@google/stitch-sdk/ai";
|
|
import { generateText } from "ai";
|
|
|
|
const { text } = await generateText({
|
|
model: yourModel,
|
|
tools: stitchTools(),
|
|
prompt: "Create a modern dashboard"
|
|
});
|
|
```
|
|
|
|
## Type Definitions
|
|
|
|
```typescript
|
|
type DeviceType = "DEVICE_TYPE_UNSPECIFIED" | "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC";
|
|
type ModelId = "MODEL_ID_UNSPECIFIED" | "GEMINI_3_PRO" | "GEMINI_3_FLASH";
|
|
|
|
interface Stitch {
|
|
projects(): Promise<Project[]>;
|
|
createProject(title?: string): Promise<Project>;
|
|
project(id: string): Project; // sync — returns handle, no API call
|
|
}
|
|
|
|
interface Project {
|
|
id: string;
|
|
generate(prompt: string, deviceType?: DeviceType, modelId?: ModelId): Promise<Screen>;
|
|
screens(): Promise<Screen[]>;
|
|
getScreen(screenId: string): Promise<Screen>;
|
|
}
|
|
|
|
interface Screen {
|
|
id: string;
|
|
getHtml(): Promise<string>; // Download URL
|
|
getImage(): Promise<string>; // Download URL
|
|
edit(prompt: string, deviceType?: DeviceType, modelId?: ModelId): Promise<Screen>;
|
|
variants(prompt: string, variantOptions: any, deviceType?: DeviceType, modelId?: ModelId): Promise<Screen[]>;
|
|
}
|
|
|
|
class StitchError extends Error {
|
|
code: "AUTH_FAILED" | "NOT_FOUND" | "RATE_LIMITED" | string;
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
| Code | Meaning | Action |
|
|
|------|---------|--------|
|
|
| `AUTH_FAILED` | Bad/missing API key | Check `STITCH_API_KEY` env var |
|
|
| `NOT_FOUND` | Screen/project doesn't exist | Verify ID |
|
|
| `RATE_LIMITED` | Daily quota exceeded | Wait until midnight UTC or use fallback |
|
|
|
|
```typescript
|
|
try {
|
|
const screen = await project.generate(prompt);
|
|
} catch (error) {
|
|
if (error.code === "RATE_LIMITED") {
|
|
console.error("Quota exceeded — use ck:ui-ux-pro-max fallback");
|
|
}
|
|
}
|
|
```
|