TypeScript SDK

@nylon/sdk is a typed client over the same REST API these docs describe. It has no runtime dependencies, and its types are generated from Nylon’s OpenAPI specification, so they cannot drift from the API.

npm install @nylon/sdk

Node 18+, Bun, Deno, Cloudflare Workers and Vercel’s edge runtime.

Your first post

import { Nylon } from '@nylon/sdk'

const nylon = new Nylon({ apiKey: process.env.NYLON_API_KEY })

const { data: profiles } = await nylon.profiles.list()

const post = await nylon.posts.create({
  profile_ids: profiles.map(profile => profile.id),
  text: 'Shipping today.',
  media: [{ url: 'https://example.com/launch.jpg' }],
})

for (const target of post.targets) {
  console.log(target.network, target.status, target.url ?? target.error?.message)
}

apiKey defaults to process.env.NYLON_API_KEY, so new Nylon() is enough when that is set.

Server-side only. A key can publish to every social account your organization has connected, so anything shipped to a browser or a mobile app can be read off it.

What the SDK adds over `fetch`

Everything here is reachable with raw HTTP — these are the parts that are easy to get wrong by hand.

Retries that cannot double-post

posts.create generates an idempotency_key for you, so a retry after a network blip returns the original post instead of publishing a second time. Retries use exponential backoff with full jitter and honour Retry-After.Supply your own key when the natural one lives in your system, so your retries collapse too:

await nylon.posts.create({
  profile_ids: [profileId],
  text: 'Your order shipped.',
  idempotency_key: `order-${order.id}`,
})

Typed errors

Branch with instanceof rather than on a string. code is stable; message is for humans.

import { NylonValidationError, NylonPaymentRequiredError } from '@nylon/sdk'

try {
  await nylon.posts.create({ profile_ids: [id], text })
}
catch (error) {
  // Nothing published — `details` names the rule and the network.
  if (error instanceof NylonValidationError) return showToUser(error.details)
  // A billing problem, not a user problem. Do not prompt them to reconnect.
  if (error instanceof NylonPaymentRequiredError) return alertBilling()
  throw error
}

One class per error code, plus NylonConnectionError and NylonTimeoutError for requests that never arrived.

Webhook verification

verifyWebhook signs the raw body, checks the timestamp against a 5-minute tolerance, and compares in constant time — the three things hand-rolled verification usually gets wrong. It is a pure WebCrypto function, so it needs no API key and runs on every supported runtime.

import { verifyWebhook, NylonSignatureVerificationError } from '@nylon/sdk'

app.post('/nylon/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const event = await verifyWebhook({
      payload: req.body,                    // the RAW body
      signature: req.get('Nylon-Signature'),
      secret: process.env.NYLON_WEBHOOK_SECRET,
    })
    res.sendStatus(200)                     // acknowledge first
    await handle(event)                     // then do the work
  }
  catch (error) {
    if (error instanceof NylonSignatureVerificationError) return res.sendStatus(400)
    throw error
  }
})

See Webhooks for the payload shapes and the retry schedule.

Lazy pagination

listAll fetches each page only as you consume it, so a large account holds one page in memory rather than all of it. Breaking out stops the requests.

for await (const post of nylon.posts.listAll({ status: 'failed' })) {
  console.log(post.id)
}

const everything = await nylon.posts.listAll().all()

Resources


`nylon.posts`	`create` `validate` `list` `listAll` `get` `update` `cancel` `retry`
`nylon.profiles`	`list` `listAll` `get` `disconnect` `listBoards`
`nylon.connections`	`list` `create`
`nylon.networks`	`list`
`nylon.webhooks`	`list` `create` `get` `update` `delete` `rotateSecret` `test` `listDeliveries` `listAllDeliveries` `verify`
`nylon.media`	`list` `listAll` `createFromUrl` `upload`

Handling a partial failure

A post to four profiles is four independent attempts, and three succeeding while one fails is a normal outcome. Retry only the failed targets — re-sending the whole post would publish it twice on the ones that already worked.

if (post.status === 'partially_published') {
  await nylon.posts.retry(post.id)
}

Configuration

const nylon = new Nylon({
  apiKey: process.env.NYLON_API_KEY,
  timeout: 60_000,          // per request
  publishTimeout: 300_000,  // publishing calls, which are synchronous
  maxRetries: 2,            // three attempts
  headers: { 'X-App': 'my-service' },
  fetch: myInstrumentedFetch,
})

Per call, including your own AbortSignal:

await nylon.posts.list({}, { signal: controller.signal, timeout: 5_000 })

Your remaining budget from the most recent response, read from the API’s own headers:

nylon.rateLimit   // { limit, remaining, reset: Date } | undefined

Types

Every schema is exported, generated from the OpenAPI specification:

import type { Post, Profile, Network, CreatePostRequest } from '@nylon/sdk'

The raw paths, components and operations are exported too, for reaching past the SDK.

Quickstart

The same first steps in raw HTTP.

API reference

Every endpoint the SDK wraps.

Errors

The error taxonomy behind the typed classes.

Webhooks

Payloads, retries and signature verification.

Get started

Capabilities

Guides

Your first post

What the SDK adds over `fetch`

Resources

Handling a partial failure

Configuration

Types

Next

Quickstart

API reference

Errors

Webhooks

​Your first post

​What the SDK adds over fetch

​Resources

​Handling a partial failure

​Configuration

​Types

​Next

Quickstart

API reference

Errors

Webhooks

Your first post

What the SDK adds over `fetch`

Resources

Handling a partial failure

Configuration

Types

Next