@postsider/node SDK reference

This page is the reference for the methods exposed by @postsider/node version 2.x. Each entry documents the signature, parameters, return value, and a usage example. For installation and setup, see the SDK Overview.

SDK 2.0.0 changed deletePost() to return the parsed response body (or null for a 204) instead of the raw fetch Response. Failed calls throw PostsiderApiError with status and details. See the Changelog.

The SDK currently exposes post, postList, upload, integrations, deletePost, and webhook signature verification. For queue slots, status changes, analytics, groups, notifications, and import-from-URL, call the REST API directly.

new Postsider(apiKey, instanceUrl?, options?)

Creates a new client. Instantiate it once and reuse it.

import Postsider from '@postsider/node';

const client = new Postsider('your-api-key', 'https://your-instance.com', {
  apiBasePath: '/api',
});

string

required

Your organization API key. Generate one from Settings → API in the dashboard.

string

The instance origin. Pass https://api.postsider.com for Cloud or your self-hosted origin. Do not rely on a package default because Cloud and OSS releases may differ. The SDK appends /public/v1 after the configured path prefix.

string

Optional path prefix. Set /api for the bundled self-hosted Compose deployment.

client.post(posts)

Creates a post. Maps to POST /public/v1/posts.

await client.post({
  type: 'schedule',
  date: '2026-07-01T10:00:00Z',
  posts: [
    {
      integration: { id: 'ch_abc123' },
      value: [
        {
          content: 'Hello from PostSider!',
          image: [media] // optional, the object returned by client.upload()
        }
      ]
    }
  ]
});

CreatePostDto

required

The post configuration.

string

required

now publishes immediately, schedule books the post for date, draft saves without publishing.

string

required

ISO 8601 publish time in UTC, for example 2026-07-01T10:00:00Z.

array

required

One entry per channel.

string

required

The id of the target channel. Get ids from client.integrations().

array

required

Content blocks for this channel.

string

The text body of the post.

array

Optional media objects returned by client.upload().

Returns: Promise<unknown[]> - an array with one entry per target channel: { postId, integration }. The full post is available via the REST API afterwards.

client.postList(filters)

Lists posts in a date range. Maps to GET /public/v1/posts.

const { posts } = await client.postList({
  startDate: '2026-06-01T00:00:00Z',
  endDate: '2026-06-30T23:59:59Z'
});
console.log(posts);

GetPostsDto

required

string

required

Range start, ISO 8601 (for example 2026-06-01T00:00:00Z).

string

required

Range end, ISO 8601 (for example 2026-06-30T23:59:59Z).

string

Optional channel group id to filter by.

Returns: Promise<{ posts: Post[] }>.

client.upload(file, extension)

Uploads a media file. Maps to POST /public/v1/upload. The SDK handles multipart encoding and MIME type mapping.

import { readFileSync } from 'fs';

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

console.log(media.id);   // use the object in client.post()
console.log(media.path); // publicly accessible URL

Buffer

required

A Node.js Buffer with the raw file bytes.

string

required

The file extension, used to set the MIME type. Image types: png, jpg, jpeg, gif.

Returns: Promise<object> with the media id and path. Pass the object straight into a post’s image array.

client.integrations()

Lists connected channels. Maps to GET /public/v1/integrations.

const channels = await client.integrations();

for (const channel of channels) {
  console.log(channel.id, channel.name, channel.identifier);
}

Returns: Promise<Channel[]>, each with id, name, identifier, profile, picture, and disabled.

client.deletePost(id)

Deletes a post by id. Maps to DELETE /public/v1/posts/:id.

await client.deletePost('post_abc123');

string

required

The id of the post to delete.

Returns: a promise containing the parsed response body, or null for an empty response. Errors throw PostsiderApiError with the HTTP status and request details.

Postsider.verifyWebhookSignature(signature, body, secret)

Static method. Verifies a timestamped HMAC SHA-256 signature on an inbound post.published webhook before you process it. Use it only when the delivery includes the signature and timestamp headers. It uses a timing-safe comparison and rejects timestamps older than five minutes by default. 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,
    req.rawBody.toString('utf8'),
    process.env.WEBHOOK_SECRET!,
    req.headers['x-postsider-timestamp'] as string
  );

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

  res.status(200).send('OK');
});

string

required

The X-Postsider-Signature header value, for example sha256=abc123....

string

required

The exact raw request body as a string or buffer converted to UTF-8. Do not re-serialize a parsed JSON object; key order or whitespace changes invalidate the signature.

string

required

Your webhook signing secret, configured when you create the webhook subscription.

string

required

The X-Postsider-Timestamp header value. The signature covers timestamp + "." + rawBody.

Returns: boolean, true if the signature is valid. Always reject requests that return false.

Pass the raw request body string. A re-serialized or pretty-printed version of the parsed JSON will not match the signature, even for legitimate requests.

​new Postsider(apiKey, instanceUrl?, options?)

​client.post(posts)

​client.postList(filters)

​client.upload(file, extension)

​client.integrations()

​client.deletePost(id)

​Postsider.verifyWebhookSignature(signature, body, secret)

new Postsider(apiKey, instanceUrl?, options?)

client.post(posts)

client.postList(filters)

client.upload(file, extension)

client.integrations()

client.deletePost(id)

Postsider.verifyWebhookSignature(signature, body, secret)