npm package: @orchestree/sdk
Description: Core SDK for the Orchestree Intelligence Platform
Author: Orchestree
Latest version: 1.4.0

# @orchestree/sdk

[![npm version](https://img.shields.io/npm/v/@orchestree/sdk.svg)](https://www.npmjs.com/package/@orchestree/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@orchestree/sdk.svg)](https://nodejs.org/en/)

Core SDK for the **Orchestree Intelligence Platform** - A comprehensive AI-powered automation and workflow orchestration system.

## Features

- **Workflow Orchestration** - Create, manage, and execute complex automation workflows
- **Social Media Management** - Schedule, publish, and analyze social content across platforms
- **Code Generation** - Auto-generate APIs, SDKs, and documentation
- **Creative Asset Generation** - Produce high-quality images, videos, and graphics with AI
- **Customer Communications** - Multi-channel messaging and campaign management
- **Collaboration Tools** - Team workspaces with role-based access control
- **Data Management** - Query and manage databases seamlessly
- **Enterprise Features** - Organizations, billing, and SSO for enterprise deployments

## Installation

### npm
```bash
npm install @orchestree/sdk
```

### yarn
```bash
yarn add @orchestree/sdk
```

### pnpm
```bash
pnpm add @orchestree/sdk
```

## Quick Start

### Basic Usage

```javascript
const createClient = require('@orchestree/sdk');

// Initialize the client
const client = createClient({
  apiKey: process.env.ORCHESTREE_API_KEY,
  workspace: process.env.ORCHESTREE_WORKSPACE_ID,
  baseUrl: 'https://api.orchestree.ai' // optional
});

// Access any module
const workflows = await client.conductor.listWorkflows();
console.log(workflows);
```

### TypeScript

```typescript
import createClient, { OrchestreConfig, PaginatedResponse, Workflow } from '@orchestree/sdk';

const config: OrchestreConfig = {
  apiKey: process.env.ORCHESTREE_API_KEY!,
  workspace: process.env.ORCHESTREE_WORKSPACE_ID!
};

const client = createClient(config);

// Full type safety
const workflows: PaginatedResponse<Workflow> = await client.conductor.listWorkflows();
```

## Module Guide

### Conductor - Workflow Orchestration

Automate complex business processes with visual workflows.

```javascript
// List workflows
const { data, total } = await client.conductor.listWorkflows({
  page: 1,
  limit: 10,
  sort: 'createdAt',
  order: 'desc'
});

// Get specific workflow
const workflow = await client.conductor.getWorkflow('workflow-id');

// Create workflow
const newWorkflow = await client.conductor.createWorkflow({
  name: 'Customer Onboarding',
  description: 'Automated onboarding process',
  definition: {
    steps: [
      { type: 'send-email', to: '{{customer.email}}' },
      { type: 'webhook', url: 'https://example.com/onboard' }
    ]
  }
});

// Execute workflow
const execution = await client.conductor.executeWorkflow('workflow-id', {
  customer: { email: 'user@example.com', name: 'John Doe' }
});

// Check execution status
const status = await client.conductor.getExecutionHistory('workflow-id', {
  limit: 20
});
```

### Social - Social Media Management

Schedule, publish, and monitor social content.

```javascript
// List connected accounts
const accounts = await client.social.listAccounts();

// Create a post
const post = await client.social.createPost('account-id', {
  content: 'Check out our new feature! 🚀',
  mediaIds: ['media-id-1', 'media-id-2']
});

// Schedule a post
const scheduled = await client.social.schedulePost('account-id', {
  content: 'Launching tomorrow!',
  scheduledAt: '2024-04-15T10:00:00Z'
});

// Get analytics
const analytics = await client.social.getAnalytics('account-id', {
  dateStart: '2024-01-01',
  dateEnd: '2024-04-30'
});

console.log(`Followers: ${analytics.followers}`);
console.log(`Engagement Rate: ${analytics.averageEngagementRate}%`);
```

### Codenza - API & Code Generation

Generate API documentation, SDKs, and code templates.

```javascript
// List APIs
const apis = await client.codenza.listAPIs({ limit: 20 });

// Generate documentation
const docs = await client.codenza.generateDocumentation('api-id', {
  format: 'markdown',
  includeExamples: true,
  includeAuth: true
});

// Generate SDK in multiple languages
const pythonSDK = await client.codenza.generateSDK('api-id', {
  language: 'python',
  format: 'pip'
});

const goSDK = await client.codenza.generateSDK('api-id', {
  language: 'go',
  format: 'go-module'
});
```

### ForgeStudio - Creative Assets

Generate images, videos, and graphics with AI.

```javascript
// List projects
const projects = await client.forgestudio.listProjects();

// Generate assets
const job = await client.forgestudio.generateAssets('project-id', {
  assetType: 'image',
  style: 'Modern, professional tech company branding',
  count: 5,
  size: { width: 1920, height: 1080 }
});

console.log(`Generation job: ${job.id}`);

// List generated assets
const assets = await client.forgestudio.listAssets('project-id', {
  page: 1,
  limit: 50
});

assets.data.forEach(asset => {
  console.log(`Asset: ${asset.url}`);
});
```

### Chorus - Communications

Multi-channel messaging and campaign management.

```javascript
// List campaigns
const campaigns = await client.chorus.listCampaigns();

// Create campaign
const campaign = await client.chorus.createCampaign({
  name: 'Summer Sale',
  description: 'Special summer promotion',
  channel: 'email'
});

// Send message
const message = await client.chorus.sendMessage(campaign.id, {
  recipient: 'customer@example.com',
  content: 'Don\'t miss our summer sale!',
  variables: { discount: '30%', endDate: '2024-08-31' }
});

// Get campaign analytics
const stats = await client.chorus.getAnalytics(campaign.id);
console.log(`Sent: ${stats.totalSent}`);
console.log(`Delivered: ${stats.delivered}`);
console.log(`Open Rate: ${stats.openRate}%`);
```

### Colab - Collaboration

Manage team workspaces and permissions.

```javascript
// List workspaces
const workspaces = await client.colab.listWorkspaces();

// Get workspace members
const members = await client.colab.listMembers('workspace-id');

// Add member
const newMember = await client.colab.addMember('workspace-id', {
  email: 'developer@example.com',
  role: 'member'
});

// Remove member
await client.colab.removeMember('workspace-id', 'member-id');
```

### Databases - Data Management

Query and manage databases.

```javascript
// List databases
const databases = await client.databases.listDatabases();

// Get database info
const db = await client.databases.getDatabase('db-id');

// List tables
const tables = await client.databases.listTables('db-id');

// Query database
const result = await client.databases.query('db-id', {
  query: 'SELECT * FROM users WHERE status = ?',
  parameters: ['active']
});

console.log(`Rows: ${result.rowCount}`);
console.log(`Execution time: ${result.executionTime}ms`);
```

### Projects - Project Management

Create and manage projects.

```javascript
// List projects
const projects = await client.projects.listProjects();

// Create project
const project = await client.projects.createProject({
  name: 'Q2 Marketing Initiative',
  description: 'All Q2 marketing campaigns'
});

// Update project
const updated = await client.projects.updateProject(project.id, {
  status: 'active'
});
```

### Workspace - Settings & Usage

Configure workspace and monitor usage.

```javascript
// Get settings
const settings = await client.workspace.getSettings();
console.log(`Workspace: ${settings.name}`);
console.log(`Timezone: ${settings.timezone}`);

// Update settings
await client.workspace.updateSettings({
  name: 'My Company',
  timezone: 'America/New_York',
  language: 'en'
});

// Check usage
const usage = await client.workspace.getUsage();
console.log(`API calls: ${usage.apiCalls}`);
console.log(`Storage: ${usage.storageGB}GB`);
console.log(`Workflows: ${usage.workflowsExecuted}`);
```

### Enterprise - Organizations & Billing

Enterprise organization and billing management.

```javascript
// List organizations
const orgs = await client.enterprise.listOrganizations();

// Get organization
const org = await client.enterprise.getOrganization('org-id');

// List members
const members = await client.enterprise.listMembers('org-id');

// Get billing info
const billing = await client.enterprise.getBilling('org-id');
console.log(`Plan: ${billing.plan}`);
console.log(`Monthly Cost: $${billing.monthlyCost}`);
console.log(`Usage: ${billing.usagePercentage}%`);
```

## Error Handling

```javascript
try {
  const workflow = await client.conductor.getWorkflow('invalid-id');
} catch (error) {
  console.error(`Error: ${error.message}`);

  if (error.status === 404) {
    console.error('Workflow not found');
  } else if (error.status === 401) {
    console.error('Authentication failed');
  } else if (error.status === 429) {
    console.error('Rate limited');
  }

  // Original error details
  console.error('Details:', error.data);
}
```

## Authentication

Set your API key via environment variable:

```bash
export ORCHESTREE_API_KEY=sk_live_xxxxxxxxxxxx
export ORCHESTREE_WORKSPACE_ID=ws_xxxxxxxxxxxx
```

Or pass directly to the client:

```javascript
const client = createClient({
  apiKey: 'sk_live_xxxxxxxxxxxx',
  workspace: 'ws_xxxxxxxxxxxx'
});
```

## Pagination

All list methods support pagination:

```javascript
const response = await client.conductor.listWorkflows({
  page: 2,
  limit: 25,
  sort: 'updatedAt',
  order: 'desc'
});

console.log(`Page: ${response.page}`);
console.log(`Total: ${response.total}`);
console.log(`Has more: ${response.hasMore}`);
```

## API Reference

Complete API documentation is available at:
**https://orchestree.ai/developer/sdk**

## Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/orchestree/orchestree/blob/main/CONTRIBUTING.md).

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- Documentation: https://orchestree.ai/developer
- Issues: https://github.com/orchestree/orchestree/issues
- Email: support@orchestree.ai

## Changelog

### 1.4.0
- Added Enterprise module with organization and billing APIs
- Improved error handling with status codes
- Added full TypeScript support
- Added Analytics API to Social module

### 1.3.0
- Added Databases module
- Added Projects module
- Improved request retry logic

### 1.2.0
- Added Colab module for collaboration
- Added Workspace settings API

### 1.1.0
- Initial public release
- Core modules: Conductor, Social, Codenza, ForgeStudio, Chorus

---

Made with ❤️ by the [Orchestree Team](https://orchestree.ai)