npm package: @socialrails/js
Description: Official JavaScript/TypeScript SDK for the SocialRails API
Author: SocialRails
Latest version: 1.0.0

# @socialrails/js

Official JavaScript/TypeScript SDK for the [SocialRails](https://socialrails.com) API. Schedule, publish, and manage social media posts across all major platforms from a single, type-safe client.

- Zero dependencies -- uses native `fetch`
- Full TypeScript support with complete type definitions
- Works in Node.js 18+, Deno, Bun, and modern browsers

## Installation

```bash
npm install @socialrails/js
```

```bash
yarn add @socialrails/js
```

```bash
pnpm add @socialrails/js
```

## Quick Start

```typescript
import { SocialRails } from '@socialrails/js';

const sr = new SocialRails({ apiKey: 'sr_live_...' });

// Create a post
const post = await sr.posts.create({
  content: 'Hello from SocialRails!',
  platform: 'twitter',
  scheduled_for: '2026-03-10T14:00:00Z',
});

console.log(post.id, post.status);
```

## Configuration

### Constructor Options

| Option    | Type     | Default                              | Description            |
| --------- | -------- | ------------------------------------ | ---------------------- |
| `apiKey`  | `string` | `process.env.SOCIALRAILS_API_KEY`    | Your SocialRails API key (starts with `sr_live_`) |
| `baseUrl` | `string` | `https://socialrails.com/api/v1`     | API base URL           |

### Environment Variable

Instead of passing the key directly you can set the `SOCIALRAILS_API_KEY` environment variable:

```bash
export SOCIALRAILS_API_KEY=sr_live_your_key_here
```

```typescript
// Automatically picks up the env var
const sr = new SocialRails();
```

## API Reference

### Posts

```typescript
// Create a post
const post = await sr.posts.create({
  content: 'Hello world!',
  platform: 'twitter',
  scheduled_for: '2026-03-10T14:00:00Z', // optional
  media: ['media_abc123'],                // optional media IDs
  platform_settings: { reply_settings: 'everyone' }, // optional
});

// Create a thread
const thread = await sr.posts.create({
  content: 'Thread start',
  platform: 'twitter',
  thread: ['Second tweet', 'Third tweet'],
  thread_delay: 60,
});

// List posts with filters
const { data: posts, pagination } = await sr.posts.list({
  status: 'scheduled',
  platform: 'twitter',
  sort: '-scheduled_for',
  limit: 20,
  offset: 0,
});

// Get a single post
const post = await sr.posts.get('post_abc123');

// Update a post
const updated = await sr.posts.update('post_abc123', {
  content: 'Updated content',
});

// Delete a post
const result = await sr.posts.delete('post_abc123');
// { id: 'post_abc123', deleted: true }

// Batch create across platforms
const batch = await sr.posts.batch({
  content: 'Cross-platform post!',
  platforms: ['twitter', 'linkedin', 'bluesky'],
  platform_content: {
    twitter: 'Short version for Twitter',
  },
});
// { batch_id: '...', posts: [...] }
```

### Analytics

```typescript
const stats = await sr.analytics.get({
  platform: 'twitter', // optional
  period: '30d',       // optional
  post_id: 'post_abc', // optional
});

console.log(stats.total_posts);
console.log(stats.by_platform);
// [{ platform: 'twitter', posts_published: 42 }, ...]
```

### Accounts

```typescript
// List connected accounts
const accounts = await sr.accounts.list();

// Get account settings & capabilities
const settings = await sr.accounts.getSettings('acc_abc123');
console.log(settings.capabilities.character_limit);
console.log(settings.capabilities.supports_thread);
console.log(settings.available_tools);

// Trigger a platform tool
const result = await sr.accounts.triggerTool('acc_abc123', {
  tool: 'fetch_trending',
});
console.log(result.results);
```

### AI Content Generation

```typescript
const result = await sr.ai.generate({
  prompt: 'Write a tweet about our new product launch',
  platform: 'twitter',  // optional
  tone: 'professional', // optional
});

console.log(result.content);
```

### Workspace

```typescript
const workspace = await sr.workspace.get();

console.log(workspace.plan);
console.log(workspace.limits.max_posts_per_month);
console.log(workspace.usage.posts_this_month);
```

### Media

```typescript
// Upload a file (Blob in browsers, Buffer in Node.js)
const media = await sr.media.upload(fileBlob, 'photo.jpg', 'image/jpeg');
console.log(media.media_id, media.url);

// Upload from a remote URL
const media2 = await sr.media.uploadFromUrl({
  url: 'https://example.com/image.png',
  type: 'image', // optional
});
```

### Webhooks

```typescript
// List webhooks
const webhooks = await sr.webhooks.list();

// Create a webhook (secret is only returned at creation)
const webhook = await sr.webhooks.create({
  url: 'https://example.com/hooks/socialrails',
  events: ['post.published', 'post.failed'],
});
console.log(webhook.secret); // Save this!

// Delete a webhook
await sr.webhooks.delete('wh_abc123');
```

## Error Handling

All API errors are thrown as `SocialRailsError` instances with structured error information:

```typescript
import { SocialRails, SocialRailsError } from '@socialrails/js';

const sr = new SocialRails({ apiKey: 'sr_live_...' });

try {
  await sr.posts.create({
    content: '',
    platform: 'twitter',
  });
} catch (error) {
  if (error instanceof SocialRailsError) {
    console.error(error.message); // Human-readable message
    console.error(error.code);    // Machine-readable code, e.g. "validation_error"
    console.error(error.status);  // HTTP status code, e.g. 422
  }
}
```

Common error codes:

| Code                  | Status | Description                       |
| --------------------- | ------ | --------------------------------- |
| `invalid_api_key`     | 401    | API key is missing or invalid     |
| `rate_limit_exceeded` | 429    | Too many requests                 |
| `validation_error`    | 422    | Request body failed validation    |
| `not_found`           | 404    | Resource does not exist           |
| `server_error`        | 500    | Internal server error             |

## TypeScript

This SDK is written in TypeScript and ships with complete type definitions. All request parameters and response objects are fully typed:

```typescript
import type {
  Post,
  CreatePostParams,
  Platform,
  AnalyticsData,
  Workspace,
} from '@socialrails/js';

const params: CreatePostParams = {
  content: 'Typed!',
  platform: 'twitter',
};
```

## Supported Platforms

The SDK supports the following platforms via the `Platform` type:

- `twitter`
- `linkedin`
- `facebook`
- `instagram`
- `tiktok`
- `bluesky`
- `pinterest`
- `threads`
- `youtube`

## Requirements

- **Node.js** 18+ (uses native `fetch`)
- **Deno** -- works out of the box
- **Bun** -- works out of the box
- **Browsers** -- any modern browser with `fetch` support

## License

MIT