TypeScript SDK

import { Staqly } from '@staqly/sdk'

const staqly = new Staqly({
  baseUrl: 'https://app.staqly.ai', // default: $STAQLY_API_URL, then http://localhost:3333
  apiKey: process.env.STAQLY_API_KEY, // default: $STAQLY_API_KEY; null = ignore the env var
  timeout: 60_000, // per-request timeout in ms
  maxRetries: 2, // retries for 408/429/5xx/network errors
  fetch: myFetch, // custom fetch (tests, proxies, tracing)
  defaultHeaders: { 'X-Team': 'growth' },
  userAgent: 'my-agent/1.0', // appended to "staqly-sdk-ts/<version>"
})

await staqly.posts.list({ status: 'scheduled' }, { timeout: 5_000, maxRetries: 0, signal })
await staqly.posts.create({ collection: 'Posts', content: 'x' }, { idempotencyKey: `job-${jobId}` })

// a draft with a text of its own on one channel (x and publisher are channels from channels.list())
const post = await staqly.posts.create({
  collection: 'Product updates', // ID or exact name
  content: 'Three days, every avatar half price.',
  media: [media.id], // from staqly.media.upload
  targets: [
    { channel_id: x.id, content: 'Three days. Half price.' },
    { channel_id: publisher.id }, // settings: { ... } sets the provider's per-post fields
  ],
  tags: ['sale'],
  metadata: { campaign: 'spring' },
})

await staqly.posts.preview(post.id) // the text per channel and what each platform objects to
await staqly.posts.schedule(post.id, '2026-11-03T09:00:00Z') // onto the calendar
await staqly.posts.cancel(post.id) // back to draft
await staqly.posts.publish(post.id) // now (202: a job does the work)
await staqly.posts.retryTarget(post.id, x.id) // one failed channel again
await staqly.posts.update(post.id, { content: 'Fixed', expected_version: post.version }) // 409 when someone edited it
const copy = await staqly.posts.duplicate(post.id) // a new draft; published posts are read-only

// list, search and page through everything
await staqly.posts.list({ status: 'scheduled', publish_after: '2026-11-02', publish_before: '2026-11-09' }) // the calendar
await staqly.posts.search('half price', { collection_id: post.collection_id })

for await (const p of staqly.posts.iterate({ channel_id: x.id, status: 'published' })) {
  console.log(p.content)
}

await staqly.posts.history(post.id) // its events, newest first
await staqly.posts.tags() // every tag with its count

const providers = await staqly.providers.list() // the catalog: auth, status, limits, fields
// your own automation; token platforms take their credentials in `fields` once they are available
const publisher = await staqly.channels.connect({ provider: 'custom', name: 'My publisher' })
await staqly.channels.test(publisher.id) // against the platform; marks needs_reconnect on failure
await staqly.channels.disable(publisher.id) // or enable(), update(id, { name, settings })

const schedule = await staqly.schedules.create({
  collection: 'Product updates',
  name: 'Weekday mornings',
  kind: 'recurring',
  rule: { times: ['09:00'], weekdays: [1, 2, 3, 4, 5], tz: 'Europe/Warsaw' },
  channels: [publisher.id],
  pick: 'next',
  source: 'agent',
})
await staqly.schedules.run(schedule.id) // now; the regular next run is unchanged

import { WaitTimeoutError } from '@staqly/sdk'

try {
  const post = await staqly.posts.waitForPublished(id, { timeout: 30 * 60_000 }) // ms, default 10 min

  if (post.status === 'failed') {
    for (const t of post.targets.filter((t) => t.status === 'failed')) {
      console.log(t.channel_name, t.error)
    }
  }
} catch (e) {
  if (e instanceof WaitTimeoutError) {
    console.log('still publishing', e.post)
  }
}

for (const w of await staqly.work.list()) {
  if (w.kind === 'target') {
    try {
      const url = await publishSomewhere(w.post, w.channel)
      await staqly.posts.reportResult(w.post.id, w.channel.id, { status: 'published', url })
    } catch (e) {
      await staqly.posts.reportResult(w.post.id, w.channel.id, { status: 'failed', error: String(e) })
    }
  } else {
    // a schedule found nothing to publish: write drafts into w.collection
    await staqly.posts.create({ collection: w.collection.id, content: await draftOne() })
  }
}

import { verifyWebhook, WebhookVerificationError, type PostEventData } from '@staqly/sdk/webhooks'

export async function POST(req: Request) {
  const body = await req.text() // the raw body, exactly as received

  try {
    const event = await verifyWebhook<PostEventData>(process.env.STAQLY_WEBHOOK_SECRET!, body, req.headers)

    if (event.type === 'post.publish_requested') {
      await publishMyself(event.data.post, event.data.channel)
    }

    return new Response('ok')
  } catch (e) {
    if (e instanceof WebhookVerificationError) {
      return new Response('invalid signature', { status: 400 })
    }

    throw e
  }
}

import { ConflictError } from '@staqly/sdk'

try {
  await staqly.posts.update(id, { content: 'x', expected_version: 3 })
} catch (e) {
  if (e instanceof ConflictError) {
    // someone edited the post meanwhile; reload it
  } else {
    throw e
  }
}