TypeScript SDK for social APIs

One adapter layer for social platform integrations.

Nimbipost gives applications a shared user, post, search, and pagination contract while keeping each platform's authentication, request signing, and API details behind dedicated adapters.

Explore platform adapters View HTTP Gateway
9 platform adapters SDK + HTTP Gateway X auth token support

Documentation paths

Choose the entry point that matches your integration.

01 Browse platform adapters

Review supported platforms, credential models, and where each adapter fits.

 02 Use the TypeScript SDK

Start from the shared factory and keep application code platform-neutral.

 03 Run the HTTP Gateway

Expose the same adapter layer to services that do not run TypeScript directly.

Platform coverage without platform-shaped callers.

Each adapter can expose its own credentials and edge cases while the application talks to a stable common interface.

X/TwitterPrimary

GraphQL reads, guest sessions, login flow, session storage, pagination, and transaction ids.

Read X adapter details

A compact contract for common social workflows.

The public shape favors generic post terminology, with X/Twitter aliases retained where existing integrations need them. See the full platform adapter documentation for credential and scope details.

src/app.ts TypeScript 
import { createPlatformAdapter } from 'nimbipost';

const platform = createPlatformAdapter('x', {
  authToken: process.env.X_AUTH_TOKEN,
});

const userId = await platform.getUserId('barton6026');
const posts = await platform.getUserPosts(userId, { total: 100 });
const post = await platform.getPost('1234567890');
const results = await platform.search('BTC');
const followingTimeline = await platform.getFollowingTimeline?.({
  total: 20,
  enableRanking: false,
  since: '2026-06-01T00:00:00Z',
});
const following = await platform.getFriends?.(userId, {
  following: true,
  total: 20,
});

// X/Twitter compatibility aliases remain available:
const tweets = await platform.getUserTweets?.(userId);

Run the SDK as a standalone HTTP Gateway.

Non-Node services can call Nimbipost over HTTP while the Gateway keeps platform credentials, sessions, request signing, and pagination inside the Node process. The HTTP Gateway guide covers routes and deployment shape.

gateway HTTP 
npm run build
X_AUTH_TOKEN=your_auth_token NIMBIPOST_PORT=4334 npm run start:gateway

GET /health
GET /v1/:platform/users/:username
GET /v1/:platform/users/:username/posts?total=20
GET /v1/:platform/posts/:postId
GET /v1/:platform/search?q=BTC

Designed for SDK maintainers and app teams.

The project separates shared interface decisions from the platform details that change most often.

Shared vocabulary

Use posts, users, search, and pagination as the common application-facing language.

Adapter isolation

Keep auth headers, query shapes, request clients, and response normalization per platform.

X transaction ids

Inject `X-Client-Transaction-Id` with the local transaction generator integration.

X auth sessions

Bootstrap `auth_token` sessions with the matching `ct0` CSRF header for authenticated reads.

Thin API adapters

Use lightweight official-API adapters as extension points for deeper platform coverage.

Architecture

Register a platform, keep the caller stable.

`createPlatformAdapter` returns the same public interface for each supported platform. The adapter owns service URLs, credentials, request transport, pagination handling, and platform-specific fallbacks. For X/Twitter-specific session handling, open the X/Twitter adapter page.

1

Application calls the generic contract

Business code asks for users, posts, searches, and paginated results.

2

The factory returns a platform adapter

Adapters are selected by platform name and configured with platform-specific options.

3

The adapter owns API details

Each implementation maps the common method to the platform's current endpoint and response shape.

Current implementation status.

The SDK is ready for local development and adapter expansion. Production use still depends on each platform's access policies and credentials.

Implemented
  • Generic `PlatformAdapter` method names.
  • Factory support for 9 platforms.
  • X/Twitter guest and auth-token session bootstrap.
  • X/Twitter login, GraphQL, pagination, and transaction-id handling.
  • X/Twitter Following timeline reads with optional ranked ordering and SDK-side time filters.
  • Standalone HTTP Gateway for SDK access from backend services.
  • Basic read adapters and tests for non-X platforms.
Needs live validation
  • Real token and API-key checks for every external platform.
  • Production end-to-end X/Twitter login and long-running crawl verification.
  • Additional platform-specific write and moderation workflows.

Deploy as a static GitHub Pages site.

This page is plain HTML, CSS, and SVG under `docs/`. Configure GitHub Pages to publish the repository's `/docs` folder and it can be served without a build pipeline. Browse the supported platform adapters or the HTTP Gateway documentation.

Back to top