# How to use the DunSocial TypeScript SDK

> Install dunsocial-sdk, pass a personal access token & workspace id to new DunSocial(), & call methods like workspaces.list or posts.schedule. It's ESM, fetch-only & runs on Node 20+, Bun & Cloudflare Workers. Missing config throws before any request is sent.

Updated: 2026-10-05.

## What the SDK is

The TypeScript SDK is a small client over the same REST API the CLI uses. It saves you writing headers, retries & error parsing by hand.

The package is `dunsocial-sdk` on npm. It's ESM, uses only `fetch` & runs on Node 20+, Bun & Cloudflare Workers.

## Install

```bash
npm install dunsocial-sdk
# bun add dunsocial-sdk
# pnpm add dunsocial-sdk
```

## Create a client

```ts
import { DunSocial } from 'dunsocial-sdk';

const dun = new DunSocial({
  token: process.env.DUN_TOKEN,
  workspaceId: process.env.DUN_WORKSPACE_ID
});

const workspaces = await dun.workspaces.list();
```

`workspaces.list` doesn't need a workspace id, so it's a good first call to find yours.

## The constructor options

| Option | Env fallback | Notes |
|--------|--------------|-------|
| `token` | `DUN_TOKEN` | A personal access token (`dun_pat_…`) |
| `workspaceId` | `DUN_WORKSPACE_ID` | Required for workspace-scoped methods |
| `baseUrl` | `DUN_API_URL` | Defaults to `https://api.dunsocial.com` |
| `fetch` | none | Inject your own, for tests |
| `timeoutMs` | none | Defaults to 60 seconds |

These are the same environment names the CLI uses, so one set of secrets works for both.

## How it authenticates

The client sends `Authorization: Bearer <token>` & a `User-Agent` of `dunsocial-sdk/<version>`. Workspace-scoped calls also send `X-Workspace-Id`.

Missing config doesn't reach the network. If the token or workspace id is absent, the SDK throws a `DunSocialError` with code `missing_config` before any request.

## Scopes per method

Each method maps to a scope. `posts.schedule` needs `posts:schedule`, `posts.publish` needs `posts:publish`, `drafts.create` needs `drafts:write` & `media.upload` needs `media:write`.

DunSocial's scope table lists them all, so create the token with only what your code calls.

## Handling errors

A failing call throws a `DunSocialError`. A 401 means an invalid token, a 403 means a wrong workspace, missing scope or suspended member, & a 402 means the workspace isn't on a paid plan, with a `billingUrl` on the error.

Don't retry a 402. Send the user to the billing URL.

## What PATs can't do here

The SDK can't call AI routes, billing, team admin, webhook endpoint management or token admin, because a PAT can't. Those stay session-only.

For webhooks, the SDK helps on the receiving side by verifying signatures, which the webhook articles in this cluster cover.

DunSocial keeps those routes behind a person's sign-in on purpose, so the SDK can't widen what a token is allowed to do.

## Related guides

- [How to schedule a post with the DunSocial TypeScript SDK](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-schedule-a-post-with-the-dunsocial-typescript-sdk.md)
- [How to authenticate with the DunSocial API](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-authenticate-with-the-dunsocial-api.md)
- [Which PAT scopes should you grant for each automation job?](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/which-pat-scopes-should-you-grant-for-each-automation-job.md)
- [CLI vs API vs MCP: which one should you use?](https://www.dunsocial.com/hub/social-media-automation-for-developers/cli-vs-api-vs-mcp-which-one-should-you-use.md)

## About this document

This is the Markdown representation of https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-use-the-dunsocial-typescript-sdk. The HTML version of the same page is at the same URL. You can also request Markdown from any page by sending `Accept: text/markdown`.

Machine-readable summary of the whole site: https://www.dunsocial.com/llms.txt

## Company

- Product: DunSocial, https://www.dunsocial.com
- Legal entity: THISUX PRIVATE LIMITED, Chennai, Tamil Nadu, India
- Support: support@dunsocial.com
- Open the app: https://app.dunsocial.com/login