Skip to main content
This page is the complete reference for every method exposed by the @postsider/node SDK. Each entry documents the method signature, its parameters, the value it returns, and a usage example. For installation and setup instructions, see the SDK Overview.

​
new Postsider(apiKey, instanceUrl?)

Creates a new SDK client. Instantiate this once and reuse it across your application. 
import Postsider from '@postsider/node';

const client = new Postsider('your-api-key', 'https://your-instance.com');
​
apiKey
string
required
Your organization’s API key. Generate one from Settings → API Keys in the Volta dashboard.
​
instanceUrl
string
The base URL of your Volta instance (e.g. "https://your-instance.com"). Defaults to "https://api.postsider.com" for the Volta hosted service.

​
client.post(posts)

Schedules a post or saves it as a draft. Maps to POST /public/v1/posts. 
await client.post({
  type: 'schedule',
  date: '2025-01-15T10:00:00',
  posts: [
    {
      integration: { id: 'ch_abc123' },
      value: [
        {
          content: 'Hello from Volta!',
          image: ['media_xyz789'] // optional
        }
      ]
    }
  ]
});
​
posts
CreatePostDto
required
The post configuration object.
​
type
string
required
"schedule" to publish at the specified time, or "draft" to save without scheduling.
​
date
string
ISO 8601 publish time (e.g. "2025-01-15T10:00:00"). Required when type is "schedule".
​
posts
array
required
Array of per-channel content objects. Each entry targets one connected channel.
​
posts[].integration.id
string
required
The ID of the target channel. Retrieve IDs from client.integrations().
​
posts[].value
array
required
Array of content blocks for this channel.
​
posts[].value[].content
string
The text body of the post.
​
posts[].value[].image
array
Optional array of media IDs from client.upload().
Returns: Promise<{ id: string; status: string }> — the new post’s ID and its initial status.

​
client.postList(filters)

Retrieves a paginated list of posts for your organization. Maps to GET /public/v1/posts. 
const posts = await client.postList({ page: 0, limit: 20 });
console.log(posts);
​
filters
GetPostsDto
required
Pagination and filter options.
​
page
number
Zero-indexed page number. Defaults to 0.
​
limit
number
Number of results per page. Defaults to 20.
Returns: Promise<Post[]> — an array of post objects matching the filters.

​
client.upload(file, extension)

Uploads a media file to the Volta media library. Maps to POST /public/v1/upload. The SDK handles multipart form encoding and MIME type mapping for you. 
import { readFileSync } from 'fs';

const buffer = readFileSync('./photo.jpg');
const media = await client.upload(buffer, 'jpg');

console.log(media.id);  // use in client.post()
console.log(media.url); // publicly accessible URL
​
file
Buffer
required
A Node.js Buffer containing the raw file bytes.
​
extension
string
required
The file extension that determines the MIME type. Accepted values: 'png', 'jpg', 'jpeg', 'gif', 'mp4'.
Returns: Promise<{ id: string; url: string }> — the uploaded file’s ID and public URL.

​
client.integrations()

Returns all channels currently connected to your organization. Maps to GET /public/v1/integrations. 
const channels = await client.integrations();

for (const channel of channels) {
  console.log(channel.id, channel.name, channel.providerIdentifier);
}
Returns: Promise<Channel[]> — an array of channel objects, each with id, name, providerIdentifier, profile, and picture.

​
client.listConnectors()

Returns all connector types available on your Volta instance, including their authorization status and supported capabilities. Maps to GET /public/v1/connectors. Useful in agent workflows to discover which platforms are ready before attempting to authorize or post. 
const connectors = await client.listConnectors();

const ready = connectors.filter(c => c.authorized);
console.log('Ready to post:', ready.map(c => c.name));
Returns: Promise<Connector[]> — an array of connector descriptors with id, name, authorized, and capabilities.

​
client.authorizeConnector(connectorId)

Starts the OAuth authorization flow for a connector. Maps to POST /public/v1/connectors/:id/authorize. Returns an OAuth redirect URL if authorization is required, or confirms immediately if the connector is already authorized. 
const result = await client.authorizeConnector('linkedin');

if ('url' in result) {
  // Redirect the user to result.url to complete OAuth
  console.log('Authorize at:', result.url);
} else {
  console.log('Already authorized');
}
​
connectorId
string
required
The connector identifier (e.g. "x", "linkedin", "instagram"). Retrieve valid IDs from client.listConnectors().
Returns: Promise<{ url: string } | { authorized: true }> — either an OAuth URL to redirect to, or a confirmation that the connector is already authorized.

​
client.connectorAnalytics(connectorId, date)

Fetches analytics for a connected channel on a given date. Maps to GET /public/v1/connectors/:id/analytics. The response shape is platform-specific. 
const stats = await client.connectorAnalytics('ch_abc123', '2025-01-15');
console.log(stats);
​
connectorId
string
required
The ID of the connected channel. Use the id field from client.integrations().
​
date
string
required
The date for which to retrieve analytics, formatted as YYYY-MM-DD (e.g. "2025-01-15").
Returns: Promise<Record<string, unknown>> — a platform-specific analytics object. Common fields include impressions, likes, reposts, and followers.

​
client.deletePost(id)

Deletes a post by its ID. Maps to DELETE /public/v1/posts/:id. 
await client.deletePost('post_abc123');
​
id
string
required
The unique identifier of the post to delete. Use the id returned when creating the post or from client.postList().
Returns: Promise<Response> — the raw node-fetch Response object. A 200 status indicates success.

​
Postsider.verifyWebhookSignature(signature, body, secret) static

Verifies the HMAC-SHA256 signature on an inbound Volta webhook request. Call this at the top of your webhook handler before processing any event data. The method uses a timing-safe comparison to prevent timing attacks. The X-Postsider-Signature header value is formatted as sha256=<hex-digest>. 
import Postsider from '@postsider/node';

app.post('/webhook', (req, res) => {
  const isValid = Postsider.verifyWebhookSignature(
    req.headers['x-postsider-signature'] as string,
    JSON.stringify(req.body),
    process.env.WEBHOOK_SECRET!
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Safe to process the event
  const event = req.body;
  console.log('Received event:', event);

  res.status(200).send('OK');
});
​
signature
string
required
The value of the X-Postsider-Signature header from the incoming request (e.g. "sha256=abc123...").
​
body
string
required
The raw request body as a string. If your framework parses JSON automatically, serialize it back with JSON.stringify(req.body) to ensure the string matches what was signed.
​
secret
string
required
Your webhook signing secret. Configure this in the Volta dashboard when setting up the webhook subscription.
Returns: boolean — true if the signature is valid, false otherwise. Always reject requests that return false.
Always pass the raw request body string to this method. If you pass a re-serialized or pretty-printed version of the parsed JSON, the HMAC will not match even for legitimate requests.