npm package: @genofx/sdk
Description: Official GenofX SDK for building apps, integrations & workspace automation
Author: truehannan
Latest version: 2.0.0

# GenOfX SDK

Official TypeScript/JavaScript SDK for building powerful integrations with the GenOfX platform.

## Installation

```bash
npm install @genofx/sdk
```

## Quick Start

```typescript
import GenOfX from '@genofx/sdk';

const client = new GenOfX({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  workspaceId: 'your_workspace_id'
});

// Authenticate
await client.authenticate();

// List frames
const frames = await client.frames.list();

// Create a frame
const newFrame = await client.frames.create({
  title: 'My New Page',
  content: { blocks: [...] }
});

// Query database
const records = await client.databases.query('db_id', {
  table: 'customers',
  filter: { status: 'active' }
});
```

## Features

- **Full TypeScript Support** - Complete type definitions included
- **OAuth 2.0 Authentication** - Secure client credentials flow
- **Comprehensive APIs** - Frames, Databases, Users, Workspaces, Files, Email, Calendar
- **Error Handling** - Built-in rate limit handling and retry logic
- **Workspace Isolation** - Automatic workspace scoping for security

## Resource APIs

### Frames

```typescript
// List frames
const frames = await client.frames.list({ limit: 20 });

// Get frame
const frame = await client.frames.get('frame_id');

// Create frame
const newFrame = await client.frames.create({
  title: 'My Page',
  content: { blocks: [] }
});

// Update frame
await client.frames.update('frame_id', { title: 'Updated Title' });

// Delete frame
await client.frames.delete('frame_id');

// Search frames
const results = await client.frames.search('project docs');
```

### Databases

```typescript
// List databases
const databases = await client.databases.list();

// Query records
const records = await client.databases.query('db_id', {
  table: 'customers',
  filter: { status: 'active' },
  limit: 100
});

// Create record
const record = await client.databases.createRecord('db_id', 'customers', {
  name: 'Acme Corp',
  email: 'contact@acme.com'
});

// Bulk create
await client.databases.bulkCreate('db_id', 'customers', [
  { name: 'Company 1' },
  { name: 'Company 2' }
]);
```

### Users

```typescript
// Get current user
const user = await client.users.me();

// List workspace users
const users = await client.users.list();

// Update user
await client.users.update('user_id', {
  displayName: 'John Doe'
});
```

### Email

```typescript
// Send email
await client.email.send({
  to: ['user@example.com'],
  subject: 'Hello',
  body: 'Email body content'
});

// List sent emails
const emails = await client.email.listSent({ limit: 50 });
```

### Calendar

```typescript
// List events
const events = await client.calendar.list({
  startDate: '2026-02-01',
  endDate: '2026-02-28'
});

// Create event
const event = await client.calendar.createEvent({
  title: 'Team Meeting',
  startTime: '2026-02-15T10:00:00Z',
  endTime: '2026-02-15T11:00:00Z',
  attendees: ['user@example.com']
});
```

## Rate Limits

The SDK automatically handles rate limits based on your workspace tier:

| Tier | Daily Actions | API Requests (per 10 min) |
|------|---------------|---------------------------|
| Free | 100 | 10 |
| Pro | 10,000 | 100 |
| Enterprise | Unlimited | Unlimited |

Rate limit information is available in API responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Used: 13
```

## Error Handling

```typescript
try {
  await client.frames.create({...});
} catch (error) {
  if (error.response?.status === 429) {
    // Rate limit exceeded
    const retryAfter = error.response.headers['retry-after'];
    console.log(`Retry after ${retryAfter} seconds`);
  }
}
```

## Examples

See the [examples](./examples) directory for complete working examples:

- **Basic Usage** - Authentication, CRUD operations
- **Database Sync** - Syncing external data
- **Weekly Report** - Automated report generation
- **User Onboarding** - Workflow automation

## Documentation

- **Full API Reference**: https://docs.genofx.com/sdk
- **Platform Docs**: https://docs.genofx.com
- **Support**: developers@genofx.com

## License

MIT © GenOfX

---

## Development

```bash
# Install dependencies
npm install

# Build SDK
npm run build

# Run tests
npm test

# Run example
npm run example
```

## Contributing

Contributions welcome! Please read our contributing guidelines before submitting PRs.

## Changelog

### v1.0.0 (2026-02-11)
- Initial release
- Frames, Databases, Users, Workspaces APIs
- OAuth 2.0 authentication
- TypeScript support
- File upload/download
- Email and Calendar integrations