@yarlis-reach/sdk

The official TypeScript client for the Yarlis Reach API: plan, approve, publish, answer and measure social media across every network Reach supports.

• Typed requests and responses for every /api/v1 endpoint
• Safe retries: every write carries an Idempotency-Key, reused across retries, so a retry never posts twice
• Backoff with jitter that honours Retry-After; per-request timeouts and AbortSignal
• Auto-pagination with for await
• Zero dependencies; works on Node 20.3+, Bun, Deno and edge runtimes with fetch

Install

npm install @yarlis-reach/sdk

Get a key

In Reach, open Developers, create a key for the workspace with the scopes you need, and store it in your secret manager. The key acts as you in that workspace, never with more than your own role allows. API access is on the Agency and Enterprise plans.

Use

import { ReachApiError, ReachClient } from '@yarlis-reach/sdk'

const reach = new ReachClient({ apiKey: process.env.REACH_API_KEY })
const me = await reach.me()
const ws = reach.workspace(me.workspace_id)

const { data: accounts } = await ws.accounts.list()

const post = await ws.posts.create({
  content: { text: 'We open at 9 tomorrow.', link: 'https://example.com' },
  account_ids: accounts.map((a) => a.id),
  campaign: 'launch',
})

const check = await ws.posts.validate(post.id)
if (!check.ok) console.log(check.issues)

await ws.posts.submit(post.id, 'Ready for review')
// …an approver approves in Reach or with ws.posts.approve(post.id)
await ws.posts.queue(post.id) // next free posting slot

for await (const item of ws.inbox.listAll({ status: 'open' })) {
  console.log(item.platform, item.author_handle, item.text)
}

try {
  await ws.posts.schedule(post.id, new Date('2026-11-02T09:00:00Z'))
} catch (error) {
  if (error instanceof ReachApiError) {
    console.error(error.status, error.code, error.message, error.requestId)
  }
}

Options

| Option | Default | | | ------------ | ----------------------------------------------------- | -------------------------------------------- | | apiKey | REACH_API_KEY | Workspace API key (rk_live_…) | | baseUrl | REACH_BASE_URL or https://reach.yarlis.com/api/v1 | | | maxRetries | 2 | For 429, 5xx and connection errors | | timeoutMs | 30000 | Per attempt | | fetch | global fetch | Custom fetch (proxies, tests) | | appInfo | | Added to the User-Agent, e.g. acme-cms/2.0 |

Every method takes a last RequestOptions argument: idempotencyKey (use your own, such as an order id, to make a write idempotent across processes), signal, and timeoutMs.

Errors

• ReachApiError: the API answered with an error. status, code (unauthorized, forbidden, not_found, invalid, conflict, limit, rate_limited, idempotency_mismatch, internal), message, requestId, retryAfter.
• ReachConnectionError: no answer (network failure or timeout) after the retries.

API reference

The OpenAPI 3.1 document is at https://reach.yarlis.com/api/v1/openapi.json.

License

MIT