init

.opencode/skills/stitch/references/stitch-sdk-api.md

@@ -0,0 +1,136 @@
+# 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");
+  }
+}
+```