npm package: @ose-cloud/sdk
Description: Official TypeScript/JavaScript SDK for OSE Cloud Platform
Author: OSE Cloud
Latest version: 1.0.2

# OSE Cloud SDK

Official TypeScript/JavaScript SDK for [OSE Cloud Platform](https://www.ose.sh) - Build, deploy, and manage containerized applications with AI-powered sandboxes.

## Features

- **Sandboxes** - Create isolated development environments
- **Deployments** - Deploy applications to production
- **Chats** - AI-powered chat interface
- **Usage Tracking** - Monitor your resource consumption
- **Type-Safe** - Full TypeScript support
- **Modern** - ESM and CommonJS support

## Installation

```bash
npm install @ose-cloud/sdk
# or
pnpm add @ose-cloud/sdk
# or
yarn add @ose-cloud/sdk
```

## Quick Start

```typescript
import { OSE } from '@ose-cloud/sdk';

// Initialize with your API key
const ose = new OSE({
  apiKey: 'your-api-key-here'
});

// Create a sandbox
const sandbox = await ose.sandboxes.create({
  name: 'my-project',
  template: 'nextjs'
});

console.log('Sandbox created:', sandbox.id);
```

## Getting an API Key

1. Visit [www.ose.sh](https://www.ose.sh)
2. Sign in to your account
3. Navigate to Dashboard → API Keys
4. Create a new API key with the permissions you need

**Available Permissions:**
- `sandbox:create` - Create new sandboxes
- `sandbox:read` - List and view sandboxes
- `sandbox:execute` - Run commands in sandboxes
- `sandbox:delete` - Delete sandboxes
- `files:read` - Read files from sandboxes
- `files:write` - Write files to sandboxes
- `deploy:create` - Create deployments
- `deploy:read` - View deployments
- `usage:read` - View usage statistics
- `chat:create` - Create chat sessions
- `chat:read` - View chat history

## API Reference

### Initialization

```typescript
const ose = new OSE({
  apiKey: 'your-api-key',
  baseUrl?: 'https://www.ose.sh/api', // Optional, defaults to production
  timeout?: 60000, // Optional, request timeout in ms
  maxRetries?: 3 // Optional, max retries for failed requests
});
```

### Sandboxes

#### Available Templates

Choose from these pre-configured environments when creating a sandbox:

| Template | Environment | Best For |
|----------|-------------|----------|
| `nextjs` | Node.js 20 + npm + yarn | Next.js, React SSR apps |
| `react` | Node.js 20 + Vite | Client-side React apps |
| `vue` | Node.js 20 + Vite | Vue.js 3 applications |
| `svelte` | Node.js 20 + SvelteKit | Svelte applications |
| `expo` | Node.js 20 + Expo CLI | React Native mobile apps |
| `python` | Python 3.12 + pip | Data science, ML, APIs |
| `fullstack` | Node.js + Python + DB tools | Full-stack development |

#### Create a sandbox
```typescript
const sandbox = await ose.sandboxes.create({
  name: 'my-app',
  template: 'nextjs', // Choose from templates above
  metadata?: { key: 'value' },
  envs?: { NODE_ENV: 'development' },
  timeoutMS?: 300000,
  port?: 3000
});
```

#### List sandboxes
```typescript
const sandboxes = await ose.sandboxes.list({
  status?: 'running' // Optional filter
});
```

#### Connect to a sandbox
```typescript
const sandbox = ose.sandboxes.connect('sandbox-id');

// Get sandbox info
const info = await sandbox.getInfo();

// Write files
await sandbox.files.write('/workspace/index.js', 'console.log("Hello")');

// Read files
const content = await sandbox.files.read('/workspace/index.js');

// List files
const files = await sandbox.files.list('/workspace');

// Run commands
const result = await sandbox.commands.run('npm install');
console.log(result.stdout);

// Delete sandbox
await sandbox.delete();
```

### Deployments

#### Create a deployment
```typescript
const deployment = await ose.deployments.create({
  name: 'my-production-app',
  sandboxId: 'sandbox-id',
  projectType: 'nextjs',
  port: 3000,
  customDomain?: 'app.example.com',
  buildCommand?: 'npm run build',
  installCommand?: 'npm install',
  startCommand?: 'npm start',
  environmentVariables?: {
    DATABASE_URL: 'postgres://...'
  }
});

console.log('Deployed to:', deployment.url);
```

#### List deployments
```typescript
const deployments = await ose.deployments.list();
```

#### Manage a deployment
```typescript
const deployment = ose.deployments.connect('deployment-id');

// Get deployment info
const info = await deployment.getInfo();

// Get logs
const logs = await deployment.logs.get(100); // Last 100 lines

// Restart deployment
await deployment.restart();

// Stop deployment
await deployment.stop();

// Delete deployment
await deployment.delete();
```

### Chats

#### Create a chat
```typescript
const chat = await ose.chats.create({
  title: 'Project Discussion'
});
```

#### List chats
```typescript
const chats = await ose.chats.list();
```

### Usage

#### Get usage statistics
```typescript
const usage = await ose.usage.get();
console.log('Total requests:', usage.totalRequests);
console.log('Total cost:', usage.totalCost);
```

## Examples

### Deploy a Next.js App

```typescript
import { OSE } from '@ose-cloud/sdk';

async function deployNextApp() {
  const ose = new OSE({ apiKey: process.env.OSE_API_KEY! });

  // Create sandbox
  const sandbox = await ose.sandboxes.create({
    name: 'my-nextjs-app',
    template: 'nextjs'
  });

  console.log('Sandbox created:', sandbox.id);

  // Connect and add files
  const sb = ose.sandboxes.connect(sandbox.id);

  await sb.files.write('/workspace/package.json', JSON.stringify({
    name: 'my-app',
    scripts: {
      dev: 'next dev',
      build: 'next build',
      start: 'next start'
    },
    dependencies: {
      next: '^14.0.0',
      react: '^18.0.0',
      'react-dom': '^18.0.0'
    }
  }, null, 2));

  await sb.files.write('/workspace/app/page.tsx', `
export default function Home() {
  return <div>Hello from OSE Cloud!</div>
}
  `);

  // Deploy
  const deployment = await ose.deployments.create({
    name: 'my-nextjs-app',
    sandboxId: sandbox.id,
    port: 3000
  });

  console.log('Deployed to:', deployment.url);
}

deployNextApp().catch(console.error);
```

### Run Commands in Sandbox

```typescript
import { OSE } from '@ose-cloud/sdk';

async function runCommands() {
  const ose = new OSE({ apiKey: process.env.OSE_API_KEY! });

  const sandbox = await ose.sandboxes.create({
    name: 'test-environment',
    template: 'node'
  });

  const sb = ose.sandboxes.connect(sandbox.id);

  // Install dependencies
  const install = await sb.commands.run('npm install express');
  console.log('Install output:', install.stdout);

  // Run a script
  await sb.files.write('/workspace/server.js', `
    const express = require('express');
    const app = express();
    app.get('/', (req, res) => res.send('Hello!'));
    app.listen(3000, () => console.log('Server started'));
  `);

  const run = await sb.commands.run('node server.js', {
    background: true
  });

  // Cleanup
  await sb.delete();
}

runCommands().catch(console.error);
```

## Error Handling

```typescript
import { OSE, APIError } from '@ose-cloud/sdk';

try {
  const ose = new OSE({ apiKey: 'invalid-key' });
  await ose.sandboxes.list();
} catch (error) {
  if (error instanceof Error) {
    const apiError = error as APIError;
    console.error('Error:', apiError.message);
    console.error('Status:', apiError.status);
    console.error('Details:', apiError.details);
  }
}
```

## TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

```typescript
import { OSE, Sandbox, Deployment, SandboxInfo } from '@ose-cloud/sdk';

const ose: OSE = new OSE({ apiKey: 'key' });
const sandbox: Sandbox = await ose.sandboxes.create({ name: 'test' });
const info: SandboxInfo = await ose.sandboxes.connect(sandbox.id).getInfo();
```

## Rate Limits

API keys have their own rate limiting. If you exceed the limit, you'll receive a `429 Too Many Requests` error with a `retryAfter` field indicating when you can retry.

## Support

- **Email**: support@ose.sh
- **Documentation**: https://www.ose.sh/docs
- **Discord**: https://discord.gg/ose-cloud
- **Issues**: https://github.com/ose-cloud/sdk/issues

## License

MIT © OSE Cloud