v0-sdk 0.0.5 → 0.0.7

package/README.md

@@ -1,10 +1,21 @@
-### v0 Chats API Client
+# v0 Chat SDK
 
-A lightweight client for interacting with the v0 Chats API to create and manage AI-powered chat conversations.
+A TypeScript SDK for interacting with the v0 API to create and manage AI-powered chat conversations, projects, integrations, and more.
+
+## Features
+
+- Full TypeScript support with complete type definitions
+- Chat management - Create, manage, and interact with AI chats
+- Project operations - Create and manage v0 projects
+- Vercel integrations - Seamless Vercel project integration
+- User management - Access user information and billing
+- Deployment logs - Monitor and retrieve deployment information
+- Comprehensive testing - Extensive test coverage for all functions
+- Error handling - Robust error handling with detailed error types
 
 ## Installation
 
-```shellscript
+```bash
 npm install v0-sdk
 # or
 yarn add v0-sdk
@@ -14,25 +25,23 @@ pnpm add v0-sdk
 
 ## Quick Start
 
-Get your API key from [v0.dev/chat/settings/keys](https://v0.dev/chat/settings/keys) and start creating chats.
-
-```javascript
-import { V0Client } from 'v0-sdk'
+Get your API key from [v0.dev/chat/settings/keys](https://v0.dev/chat/settings/keys).
 
-// Initialize with your API key
-const client = new V0Client('your_v0_api_key')
+```typescript
+import { v0 } from 'v0-sdk'
 
 // Create a new chat
-const chat = await client.createChat({
+const chat = await v0.chats.create({
   message: 'Create a responsive navbar with Tailwind CSS',
   system: 'You are an expert React developer',
 })
 
 console.log(`Chat created: ${chat.url}`)
-console.log(`Generated code: ${chat.files.length} files`)
+console.log(`Generated code: ${chat.files?.length} files`)
 
 // Add a message to the chat
-const response = await client.addMessage(chat.chatId, {
+const response = await v0.chats.createMessage({
+  chatId: chat.chatId,
   message: 'Add a dropdown menu to the navbar',
 })
 
@@ -43,22 +52,24 @@ console.log(`AI response: ${response.text}`)
 
 The client requires a v0 API key, which you can create at [v0.dev/chat/settings/keys](https://v0.dev/chat/settings/keys).
 
-```javascript
-// Initialize with API key
-const client = new V0Client('your_v0_api_key')
+```typescript
+// Set your API key as an environment variable
+process.env.V0_API_KEY = 'your_v0_api_key'
 
-// Or set it later
-client.setApiKey('your_v0_api_key')
+// Or pass custom base URL
+// The SDK will automatically use the V0_API_KEY environment variable
 ```
 
 ## API Reference
 
-### Create a Chat
+### Chat Operations
+
+#### Create a Chat
 
 Create a new chat conversation with the AI.
 
-```javascript
-const result = await client.createChat({
+```typescript
+const result = await v0.chats.create({
   message: 'Create a login form with validation',
   system: 'You are an expert in React and form validation',
   chatPrivacy: 'private',
@@ -70,95 +81,194 @@ const result = await client.createChat({
 })
 ```
 
-**Response:**
-
-```javascript
-{
-  chatId: 'abc123',
-  url: 'https://v0.dev/chat/abc123',
-  text: 'I'll create a login form with validation...',
-  files: [
-    {
-      name: 'login-form.tsx',
-      content: '...',
-      type: 'component'
-    }
-  ],
-  demo: 'https://v0.dev/demo/abc123'
-}
+#### Get Chat by ID
+
+```typescript
+const chat = await v0.chats.getById({ chatId: 'chat_id' })
+console.log(chat.messages) // Fully typed message array
 ```
 
-### Add a Message
+#### Manage Chat Favorites
+
+```typescript
+// Favorite a chat
+await v0.chats.favorite({ chatId: 'chat_id' })
+
+// Unfavorite a chat
+await v0.chats.unfavorite({ chatId: 'chat_id' })
+
+// Get favorite chats
+const favorites = await v0.chats.find()
+```
+
+#### Chat History and Management
+
+```typescript
+// Get chat history
+const chats = await v0.chats.find()
 
-Add a message to an existing chat.
+// Delete a chat
+await v0.chats.delete({ chatId: 'chat_id' })
 
-```javascript
-const response = await client.addMessage('abc123', {
+// Get chat's associated project
+const project = await v0.chats.getProject({ chatId: 'chat_id' })
+```
+
+#### Add Messages to Chat
+
+```typescript
+const response = await v0.chats.createMessage({
+  chatId: 'chat_id',
   message: 'Add password strength indicator',
   attachments: [{ url: 'https://example.com/mockup.jpg' }],
-  modelConfiguration: {},
+  modelConfiguration: {
+    imageGenerations: true,
+  },
+})
+```
+
+#### Get Version Frame Token
+
+```typescript
+const token = await v0.chats.getVersionFrameToken({
+  chatId: 'chat_id',
+  versionId: 'version_id',
+})
+```
+
+### Project Operations
+
+#### Create a Project
+
+```typescript
+const project = await v0.projects.create({
+  name: 'My New Project',
+  description: 'A sample project',
+  environmentVariables: [{ key: 'API_KEY', value: 'secret_value' }],
+  icon: 'https://example.com/icon.png',
+})
+```
+
+#### Find Projects
+
+```typescript
+const projects = await v0.projects.find()
+```
+
+### Vercel Integration
+
+#### Create Vercel Integration Project
+
+```typescript
+const integration = await v0.integrations.vercel.projects.create({
+  projectId: 'vercel_project_id',
+  name: 'project_name',
+})
+```
+
+#### Find Vercel Projects
+
+```typescript
+const projects = await v0.integrations.vercel.projects.find()
+```
+
+### User Management
+
+#### Get User Information
+
+```typescript
+const userResponse = await v0.user.get()
+console.log(userResponse.user.name, userResponse.user.email)
+```
+
+#### Get User Plan and Billing
+
+```typescript
+const planResponse = await v0.user.getPlan()
+console.log(planResponse.plan, planResponse.balance)
+```
+
+### Deployment and Monitoring
+
+#### Find Deployment Logs
+
+```typescript
+const logs = await v0.deployments.findLogs({
+  deploymentId: 'deployment_id',
 })
 ```
 
-### Get Chat History
+### Scopes and Rate Limits
+
+#### Find Scopes
+
+```typescript
+const scopesResponse = await v0.scopes.find()
+console.log(scopesResponse.scopes)
+```
+
+#### Check Rate Limits
 
-Coming soon
+```typescript
+const rateLimits = await v0.rateLimits.find()
+console.log(rateLimits.remaining, rateLimits.reset)
+```
 
 ## Working with Attachments
 
-The client supports both URL and base64-encoded attachments:
+The SDK supports URL and base64-encoded attachments:
 
-```javascript
+```typescript
 // URL attachment
-const response = await client.createChat({
+const response = await v0.chats.create({
   message: 'Create a component based on this design',
   attachments: [{ url: 'https://example.com/design.png' }],
 })
 
-// Base64 attachment (from file input)
-document
-  .querySelector('input[type="file"]')
-  .addEventListener('change', async e => {
-    const file = e.target.files[0]
-    const reader = new FileReader()
+// Base64 attachment
+const handleFileUpload = async (file: File) => {
+  const reader = new FileReader()
 
-    reader.onload = async () => {
-      const response = await client.createChat({
-        message: 'Create a component based on this image',
-        attachments: [{ url: reader.result }],
-      })
+  reader.onload = async () => {
+    const response = await v0.chats.create({
+      message: 'Create a component based on this image',
+      attachments: [{ url: reader.result as string }],
+    })
 
-      console.log(response)
-    }
+    console.log(response)
+  }
 
-    reader.readAsDataURL(file)
-  })
+  reader.readAsDataURL(file)
+}
 ```
 
-## Customizing Model Behavior
+## TypeScript Support
 
-Control the AI model's behavior with the `modelConfiguration` parameter:
+The SDK includes complete type definitions for all API operations:
 
-```javascript
-const response = await client.createChat({
-  message: 'Create a dashboard layout',
-  modelConfiguration: {
-    // Use a specific model version
-    modelId: 'v0-1.5-md',
+```typescript
+import type {
+  ChatsCreateRequest,
+  ChatsCreateResponse,
+  User,
+  Project,
+  ScopeSummary,
+} from 'v0-sdk'
 
-    // Enable AI-generated images in the response
-    imageGenerations: true,
-  },
-})
+// All request and response types are fully typed
+const createChatRequest: ChatsCreateRequest = {
+  message: 'Create a component',
+  system: 'You are a helpful assistant',
+}
 ```
 
 ## Error Handling
 
-The client throws descriptive errors for various failure scenarios:
+The SDK provides detailed error information:
 
-```javascript
+```typescript
 try {
-  const chat = await client.createChat({
+  const chat = await v0.chats.create({
     message: 'Create a component',
   })
 } catch (error) {
@@ -172,18 +282,86 @@ try {
 }
 ```
 
+## Testing
+
+The SDK includes comprehensive test coverage. Run tests with:
+
+```bash
+npm test
+```
+
+### Test Structure
+
+Tests are organized by functionality:
+
+```
+tests/
+├── chats/
+│   ├── create.test.ts
+│   ├── find.test.ts
+│   ├── delete.test.ts
+│   ├── getById.test.ts
+│   ├── favorite.test.ts
+│   ├── unfavorite.test.ts
+│   ├── getProject.test.ts
+│   ├── createMessage.test.ts
+│   └── getVersionFrameToken.test.ts
+├── projects/
+│   ├── create.test.ts
+│   └── find.test.ts
+├── integrations/vercel/projects/
+│   ├── create.test.ts
+│   └── find.test.ts
+├── user/
+│   ├── get.test.ts
+│   └── getPlan.test.ts
+├── deployments/
+│   └── findLogs.test.ts
+├── scopes/
+│   └── find.test.ts
+└── rateLimits/
+    └── find.test.ts
+```
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Generating SDK
+
+The SDK is generated from the OpenAPI specification:
+
+```bash
+npm run generate
+```
+
+### Running Tests
+
+```bash
+npm test
+```
+
 ## Advanced Usage
 
-### Streaming Responses
+### Custom Configuration
 
-Coming soon
+```typescript
+const client = new V0Client('your_api_key', 'https://custom-api.example.com', {
+  timeout: 30000,
+  retries: 3,
+})
+```
 
 ### Team Collaboration
 
 Share chats with your team:
 
-```javascript
-const chat = await client.createChat({
+```typescript
+const chat = await v0.chats.create({
   message: 'Create a component for our design system',
   chatPrivacy: 'team-edit',
   teamId: 'your-team-id',
@@ -197,22 +375,20 @@ console.log(`Team chat URL: ${chat.url}`)
 
 ### Rate Limiting
 
-The API has rate limits of 100 requests per minute and 1,000 requests per hour. If you hit these limits, you'll receive a 429 status code.
+The API has rate limits. Check your current limits:
 
-### Common Errors
-
-- **403 Forbidden**: Check your API key and ensure you have a valid subscription.
-- **400 Bad Request**: Verify your request parameters match the API requirements.
-- **404 Not Found**: Ensure the chat ID exists and is accessible to your API key.
-- **413 Payload Too Large**: Reduce attachment size (max 10MB per attachment).
-
-### Debugging
+```typescript
+const limits = await v0.rateLimits.find()
+console.log(`Remaining requests: ${limits.remaining}`)
+```
 
-Enable debug mode to see detailed request and response information:
+### Common Errors
 
-```javascript
-const client = new V0Client('your_api_key', undefined, { debug: true })
-```
+- **403 Forbidden**: Check your API key and ensure you have a valid subscription
+- **400 Bad Request**: Verify your request parameters match the API requirements
+- **404 Not Found**: Ensure the resource ID exists and is accessible to your API key
+- **413 Payload Too Large**: Reduce attachment size (max 10MB per attachment)
+- **429 Too Many Requests**: You've hit the rate limit, wait before making more requests
 
 ## Resources