@flung.dev/sdk

The typed TypeScript client for the Flung API: schedule and publish social media posts, connect accounts, manage webhook endpoints and API keys, and verify the webhooks Flung sends. It runs anywhere with fetch and WebCrypto: Node 20+, Cloudflare Workers, Deno, Bun.

import { Flung } from '@flung.dev/sdk'

const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })

const { data: accounts } = await flung.accounts.list()
const post = await flung.posts.create({
  content: 'Launching today.',
  accountIds: accounts.map((account) => account.id),
  publishAt: '2026-11-01T09:00:00.000Z',
})

Keep the key on a server. The SDK talks to https://api.flung.dev; pass baseUrl: 'https://api-preview.flung.dev' to test against preview.

Behaviour

• Errors. A failed call throws FlungError with status, a stable code (unknown_accounts, account_needs_reconnect, network_error, ...) and details. Branch on code; messages may change.
• Retries. Network failures, timeouts, 408, 409, 429 and 5xx are retried twice by default with jittered backoff, honouring Retry-After. Set maxRetries and timeoutMs on the constructor.
• Idempotency. Every POST carries an Idempotency-Key, generated unless you pass 'idempotency-key', so a retry never schedules a post twice. Pass your own key, such as an order id, to make your own retries safe too.
• Pagination. for await (const post of flung.paginate((page) => flung.posts.list(page), { limit: 100 })) walks every page.

Time zones

Flung stores every time in UTC. Give publishAt either as an instant with Z or an offset, or as the local time a person said, without an offset, and Flung converts it on the server:

// 9am in Athens on 3 November, whatever zone this code runs in.
const post = await flung.posts.create({
  content: 'Kalimera.',
  accountIds,
  publishAt: '2026-11-03T09:00',
  timeZone: 'Europe/Athens',
})
post.publishAt // '2026-11-03T07:00:00.000Z', in UTC
post.publishAtLocal // '2026-11-03T09:00:00+02:00'
post.timeZone // 'Europe/Athens'

Without timeZone, a local time is read in the zone of the person behind an OAuth token, else the workspace's default zone (as for an API key), else UTC. flung.me.get() says which: timeZone, timeZoneSource (user, workspace or default) and the time there now as nowLocal. A local time the clocks skip in spring moves forward by the gap, and one they pass twice in autumn takes the earlier instant; either adds an entry to post.warnings (local_time_skipped, local_time_ambiguous). A zone that is not an IANA name is refused with the code invalid_time_zone. Times with Z or an offset work exactly as before.

Images and video

const photo = await flung.uploadMedia(await readFile('launch.png'), { contentType: 'image/png' })
await flung.posts.create({ content: 'Launching today.', accountIds, mediaIds: [photo.id] })
// Or let Flung fetch a file that is already online:
const clip = await flung.media.import({ url: 'https://example.com/launch.mp4' })

JPEG, PNG and WebP up to 20 MB, GIF 15 MB, MP4 and QuickTime 1 GB; uploadMedia sends anything over 100 MB in parts by itself. Flung checks the real type from the file.

A post a platform cannot carry is refused when it is created, not when it fails to publish.

Connecting accounts without a UI

// A new account, or flung.accounts.reconnect({ id }) for one that needs it.
const session = await flung.accounts.connect({ platform: 'linkedin' })
console.warn(`Open ${session.authorizationUrl}`)
const done = await flung.waitForConnection(session.id)
if (done.status === 'connected') console.warn('Connected', done.accountIds)

Without a redirectUrl the person ends on Flung's own "you can close this tab" page. Pass one to bring them back into your app instead.

LinkedIn company pages connect through their own app: flung.accounts.connect({ platform: 'linkedin', variant: 'pages' }) connects every page the person administers, one account per page. flung.platforms.list() gives each platform's variants, ['pages'] for LinkedIn once the pages app is set up.

Most platforms connect by consent: the person signs in at authorizationUrl and lands back on a page. Farcaster connects by approval instead: flung.platforms.list() gives it connectFlow: 'approval', authorizationUrl opens Warpcast (show it as a link or a QR code, as approval usually happens on a phone), and nothing redirects back, so waitForConnection is how you learn it finished. A session nobody approves ends expired.

Each account says how it stays connected: renewal is automatic (Flung refreshes it), manual (only a reconnect renews it) or not_needed, with tokenExpiresAt and reconnectBy. flung.accounts.list({ reconnectBefore }) finds the ones a person must reconnect soon, account.reconnect_required_soon arrives a week ahead, and flung.accounts.refresh({ id }) renews a token now.

Letting people connect from your page

Your server makes a connect token, and <flung-connect> from @flung.dev/connect uses it in the browser. The token can only list, connect, reconnect and disconnect accounts, from the origins you name, until it expires.

const { token } = await flung.connectTokens.create({ origins: ['https://app.example.com'], expiresIn: 900 })

One profile per customer

When your product's users each connect their own accounts, give each a profile, with your own user id as externalId. A connect token made with its profileId connects into it and sees only its accounts.

const profile = await flung.profiles.create({ name: 'Acme Studio', externalId: 'user_8412' })
const { token } = await flung.connectTokens.create({ origins: ['https://app.example.com'], profileId: profile.id })
const { data: accounts } = await flung.accounts.list({ profileId: profile.id })
await flung.posts.create({ content: 'Hello', accountIds: accounts.map((account) => account.id), profileId: profile.id })

flung.profiles.list({ externalId }) finds a profile again. flung.profiles.delete({ id }) disconnects its accounts and cancels its scheduled posts.

A profile (a brand, in the Flung portal) holds at most one account on each platform; a LinkedIn page counts apart from a personal profile. flung.billing.get() gives the limit as limits.accountsPerPlatformPerProfile, and how many profiles the plan allows. Connecting a second account of a platform into the same profile throws FlungError with the code platform_limit_reached, whose details name the platform, the profile and upgradeUrl. Reconnecting an account it already holds is never refused.

Plotwork diagrams

When a workspace has connected Plotwork, its diagrams can go straight into a post: importDiagram has Plotwork paint the diagram as a PNG and keeps it as a media file with alt text.

const { data: diagrams } = await flung.plotwork.listDiagrams({ q: 'architecture' })
const media = await flung.plotwork.importDiagram({ id: diagrams[0].id, width: 1600, scheme: 'light' })
await flung.posts.create({ content: 'How it fits together', accountIds, mediaIds: [media.id] })

flung.plotwork.get() says whether Plotwork is connected and by whom.

Webhooks

import { verifyWebhook } from '@flung.dev/sdk'

const event = await verifyWebhook({ body: rawBody, headers: request.headers, secret: process.env.FLUNG_WEBHOOK_SECRET! })
if (event.type === 'post.published') console.warn(event.data.post.id)

Pass the raw body, not a re-serialised one. During a secret rotation Flung signs with the old and the new secret for 24 hours, and secret also takes both while you switch. Events follow the Standard Webhooks spec, so any Standard Webhooks library verifies them too.

Standards

Code here follows:

• API clients - one client, timeouts, retrying only idempotent calls
• Outbound webhooks - the receiving side of the signing scheme
• Error handling - one typed error with stable codes
• Vitest testing - test layout

Contents