@socialrails/js

Official JavaScript/TypeScript SDK for the SocialRails 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

npm install @socialrails/js

yarn add @socialrails/js

pnpm add @socialrails/js

Quick Start

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:

export SOCIALRAILS_API_KEY=sr_live_your_key_here

// Automatically picks up the env var
const sr = new SocialRails();

API Reference

Posts

// 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

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

// 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

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

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

// 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

// 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:

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:

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