wclient

Minimalistic TypeScript client library for the W social media platform, with a focused subset of Bluesky / AT Protocol XRPC endpoints.

Install

npm install wclient

Usage

import { WClient } from 'wclient';

const client = new WClient();

const repoInfo = await client.repo.describeRepo('did:plc:example');
console.log(repoInfo.handle);

Use a custom PDS URL when needed:

import { WClient } from 'wclient';

const client = new WClient({
  baseUrl: process.env.W_SERVER ?? '',
});

Authenticated example:

import { WClient } from 'wclient';

const client = new WClient();

const session = await client.login({
  identifier: process.env.W_USERNAME,
  password: process.env.W_PASSWORD,
});

if (session) {
  const repoInfo = await client.repo.describeRepo(session.did);
  console.log(repoInfo.handle);
}

Supported API subset

com.atproto.server

• POST /xrpc/com.atproto.server.createSession
• POST /xrpc/com.atproto.server.refreshSession

app.bsky.actor

• GET /xrpc/app.bsky.actor.getProfile
  • Helper: client.actor.getProfile(actor)
  • Example:

const profile = await client.actor.getProfile('did:plc:example');
console.log(profile.displayName, profile.handle);

com.atproto.repo

• GET /xrpc/com.atproto.repo.describeRepo
  • Helper: client.repo.describeRepo(repo)
• GET /xrpc/com.atproto.repo.listRecords
  • Helper: client.repo.listRecords(options)
  • Example:

const records = await client.repo.listRecords({
  repo: 'did:plc:example',
  collection: 'app.bsky.feed.post',
  // Optional. Default is 50, range is 1..100.
  limit: 50,
  // Optional pagination cursor from a previous response.
  cursor: undefined,
  // Optional. Reverse record order.
  reverse: false,
});

com.atproto.sync

• GET /xrpc/com.atproto.sync.listRepos
  • Helper: client.sync.listRepos(options?)
  • Example:

const page = await client.sync.listRepos({
  // Optional pagination cursor from a previous response.
  cursor: undefined,
  // Optional number of repos in one page.
  limit: 500,
});

CLI

wclient also ships with a command-line interface. Run it with npx without installing:

npx wclient <command> [options]

Commands

describe-repo <repo>

Get information about an account and repository.

npx wclient describe-repo alice.wsocial.network

list-records

List records in a repository collection.

npx wclient list-records --repo alice.wsocial.network --collection app.bsky.feed.post
npx wclient list-records --repo alice.wsocial.network --collection app.bsky.feed.post --limit 10
npx wclient list-records --repo alice.wsocial.network --collection app.bsky.feed.post --cursor <cursor> --reverse

# authenticated flow (repo defaults to session.did)
npx wclient --env-file .env --auth list-records --collection "app.bsky.feed.post"

Options:

| Flag | Required | Description | | -------------- | -------- | -------------------------------------------------- | | --repo | yes* | Handle or DID of the repository | | --collection | yes | NSID of the collection (e.g. app.bsky.feed.post) | | --limit | no | Number of records to return (1–100, default 50) | | --cursor | no | Pagination cursor from a previous response | | --reverse | no | Reverse the order of returned records |

* --repo can be omitted when using --auth; in that case, the CLI uses the authenticated session DID.

get-profile <actor>

Get detailed profile view for a handle or DID.

npx wclient get-profile did:plc:example
npx wclient get-profile alice.wsocial.network

# optionally authenticated for extra viewer metadata
npx wclient --env-file .env --auth get-profile did:plc:example

list-repos

List all repositories on the PDS.

npx wclient list-repos

view <report>

Render a custom report.

Currently available reports:

• pds.users: shows active users, inactive users, and total users across all pages from com.atproto.sync.listRepos
• me.haters: shows users (DIDs) that have blocked a subject DID using blue.microcosm.links.getBacklinks and resolves each blocker profile via app.bsky.actor.getProfile

npx wclient view pds.users
npx wclient view pds.users --quiet
npx wclient view pds.users --json

# public API usage with an explicit DID (no auth required)
npx wclient view me.haters --did did:plc:example
npx wclient view me.haters did:plc:example
npx wclient view me.haters --did did:plc:example --limit 100 --reverse
npx wclient view me.haters --did did:plc:example --json

# authenticated flow can infer DID from session
npx wclient --env-file .env --auth view me.haters

# if DID is omitted, CLI also attempts auth from .env automatically
npx wclient --env-file .env view me.haters

Table output example:

PDS Users: 25 July 2026
+----------------+-------+
| Metric         | Value |
+----------------+-------+
| Active users   |   987 |
| Inactive users |   247 |
| Total users    | 1,234 |
+----------------+-------+

JSON output example:

{
  "users": 1234,
  "activeUsers": 987,
  "inactiveUsers": 247
}

me.haters JSON output example:

{
  "subjectDid": "did:plc:example",
  "total": 9,
  "blockers": [
    {
      "did": "did:plc:fakeblocker0000000000001",
      "handle": "blocker-one.test",
      "displayName": "Blocker One"
    },
    {
      "did": "did:plc:fakeblocker0000000000002",
      "handle": "blocker-two.test",
      "displayName": "Blocker Two"
    }
  ],
  "pagesFetched": 1
}

me.haters notes:

• The subject DID is resolved in this order: --did, positional DID (view me.haters <did>), authenticated session DID.
• Optional flags: --limit (1..100), --reverse.
• The endpoint is public, so auth is optional when a DID is provided.
• If DID is omitted, the CLI attempts to authenticate using W_USERNAME and W_PASSWORD from environment/.env and then uses the session DID.

Global options

| Flag | Description | | ------------------- | ------------------------------------------------------------------------------- | | --env-file <path> | Load environment variables from a specific file | | --base-url <url> | Override the default PDS URL | | --auth | Authenticate using W_USERNAME and W_PASSWORD and reuse cached session DID | | --quiet | Suppress non-essential CLI output (for example loading progress in view mode) | | --help | Show help |

npx wclient --env-file .env.local --auth describe-repo
npx wclient --base-url https://my.pds.example list-repos

Environment variables

| Variable | Description | | -------------------- | ---------------------------------------------------------------------------- | | W_USERNAME | Handle or DID used for authentication | | W_PASSWORD | App password used for authentication | | W_SERVER | PDS base URL (overrides the default https://pds.wsocial.network) | | WCLIENT_DEBUG_AUTH | Set to 1 or true to log auth, session restore, and token refresh details |

Exported modules

• WClient: convenience wrapper for auth and namespaced API access
• DEFAULT_PDS_URL: default PDS endpoint used by WClient
• api: low-level typed endpoint helpers and response types
• auth: login/refresh flow, session store interfaces, and defaults
• http: low-level request client and ETag cache helpers

License

Apache-2.0