@socialapitech/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SocialAPI Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# SocialAPI — TypeScript / JavaScript SDK
+
+Real-time X (Twitter) data. **40 read endpoints** plus free account endpoints for checking your own balance and usage. Around 100× cheaper than the official X API.
+
+```bash
+npm i @socialapitech/sdk
+```
+
+```ts
+import { SocialAPI } from "@socialapitech/sdk";
+
+const api = new SocialAPI("sk_your_key");   // or set SOCIALAPI_KEY
+
+const user = await api.user_info("elonmusk");
+console.log(user.followers_count);
+
+const tweets = await api.user_last_tweets("elonmusk", { limit: 10 });
+for (const t of tweets) console.log(t.created_at, t.text.slice(0, 80));
+```
+
+Get a key at **[socialapi.tech/signup](https://socialapi.tech/signup)** — no credit card.
+
+Ships with full TypeScript declarations. Works in Node 18+, Deno, Bun, and
+any runtime with `fetch`.
+
+---
+
+## Why this exists
+
+The official X API bills **per resource returned** — $0.005 a post, $0.010 a
+profile. Pulling 30 posts costs $0.15 there; the same call here is $0.0008,
+and a profile is $0.00015 instead of $0.010.
+
+That gap is the whole reason this exists. Same pay-as-you-go model, roughly
+100× less, one balance across every endpoint, and composite lookups plus
+per-account streaming that the official API does not offer at all.
+
+**Read-only by design.** There is no posting, liking, or following. That means
+you never hand us an X account — a leaked key costs you some data queries, not
+your voice.
+
+---
+
+## Common tasks
+
+```ts
+// Search — full X syntax, real-time (not cached)
+await api.search_advanced("bitcoin min_faves:100", { limit: 30 });
+
+// Is this account alive, suspended, or gone?
+await api.user_status("someaccount");        // -> alive | suspended | not_found
+
+// Followers / following with cursor pagination
+await api.user_followers("jack", { limit: 200 });
+
+// Trends — worldwide, or per-region with a WOEID
+await api.trends();
+await api.trends_place({ woeid: 1 });
+
+// One call, full picture (several lookups run concurrently server-side)
+await api.user_whois("elonmusk");
+
+// Batch profiles in one request
+await api.batch_user_info("elonmusk,jack,binance");
+
+// Your own account — balance, spend, and what you're monitoring. These are free.
+const me = await api.usage();               // balance + today/month spend
+await api.analytics({ days: 14 });          // per-endpoint usage + days of runway left
+await api.stream_subscriptions();           // which accounts you're watching, and the daily cost
+```
+
+Every method maps 1:1 to an endpoint in the
+[API reference](https://socialapi.tech/docs).
+
+---
+
+## Watching accounts, not just querying them
+
+The methods above are request-and-response: you ask, you get an answer. If what
+you need is *"tell me the moment they post"*, that runs over a WebSocket or a
+webhook instead — we push to you, median **two seconds** from post to delivery.
+
+```ts
+// Your handler receives each new tweet as it lands
+const ws = new WebSocket("wss://api.socialapi.tech/v1/stream/ws?api_key=sk_your_key");
+ws.onmessage = (e) => console.log(JSON.parse(e.data));
+```
+
+Monitoring is **$0.08 per account per day**, billed hourly — stop it and the
+billing stops. One account minimum, no bundles. It draws from the same balance
+as everything else, so there's nothing extra to sign up for.
+
+Setup and payload format: [socialapi.tech/docs](https://socialapi.tech/docs)
+
+---
+
+## What it costs
+
+| | |
+|---|---|
+| A call returning up to 30 tweets | **$0.0008** |
+| Per tweet, at 30 per call | **$0.000027** |
+| Single profile lookup | **$0.00015** |
+| Watching one account | **$0.08 / day** |
+
+No monthly fee, no minimum, no card. Failed calls cost nothing, and credits
+don't expire.
+
+---
+
+## Errors worth handling
+
+```ts
+import { SocialAPI, RateLimited, InsufficientCredits, SocialAPIError }
+  from "@socialapitech/sdk";
+
+try {
+  await api.user_info("elonmusk");
+} catch (e) {
+  if (e instanceof InsufficientCredits) {
+    // 402 — top up. Do NOT retry; it will fail the same way.
+  } else if (e instanceof RateLimited) {
+    // 429 — not charged. Back off (the SDK already retries twice).
+  } else if (e instanceof SocialAPIError) {
+    console.error(e.status, e.message);
+  }
+}
+```
+
+**402 and 429 mean different things.** 429 is "too fast, slow down" and costs
+nothing. 402 is "out of balance" — retrying just burns time. The SDK retries
+429 and 5xx automatically with exponential backoff, and never retries 402.
+
+---
+
+## Billing, briefly
+
+- Only **successful** requests are charged.
+- A call returning up to 30 items is **one tier** — asking for 30 costs the
+  same as asking for 3, so request what you actually need.
+- Every response carries an `x-credits-used` header.
+
+Full rules: [socialapi.tech/#pricing](https://socialapi.tech/#pricing)
+
+---
+
+## Configuration
+
+```ts
+const api = new SocialAPI({
+  apiKey: "sk_...",                        // or env SOCIALAPI_KEY
+  baseUrl: "https://api.socialapi.tech",
+  timeoutMs: 30_000,
+  maxRetries: 2,                           // for 429 / 5xx only
+});
+```
+
+---
+
+## Support
+
+- Docs — <https://socialapi.tech/docs>
+- Telegram — <https://t.me/socialapi_support>
+- Email — <contact@socialapi.tech>
+
+MIT licensed.
+
+> *SocialAPI is an independent service and is not affiliated with, endorsed by,
+> or authorized by X Corp. "X" and "Twitter" are trademarks of X Corp., used
+> here only to describe the data this service reads. We access only publicly
+> visible data.*

package/dist/index.d.ts

@@ -0,0 +1,387 @@
+/**
+ * SocialAPI TypeScript/JavaScript SDK — real-time X (Twitter) data.
+ *
+ * GENERATED FILE - DO NOT EDIT BY HAND.
+ * Produced by sdk-generator/generate.mjs from openapi.json. Edit the spec and
+ * regenerate; hand edits are overwritten on the next run.
+ *
+ * Docs: https://socialapi.tech/docs
+ */
+export declare class SocialAPIError extends Error {
+    status: number;
+    code?: unknown | undefined;
+    constructor(message: string, status?: number, code?: unknown | undefined);
+}
+/** 429 - rate limited. **Not charged**; back off and retry. */
+export declare class RateLimited extends SocialAPIError {
+    constructor(message: string);
+}
+/** 402 - out of credits. **Do not retry**; top up first. */
+export declare class InsufficientCredits extends SocialAPIError {
+    constructor(message: string);
+}
+export interface SocialAPIOptions {
+    /** API key; falls back to process.env.SOCIALAPI_KEY */
+    apiKey?: string;
+    /** Override the API host (self-hosted or staging) */
+    baseUrl?: string;
+    /** Per-request timeout in ms (default 30000) */
+    timeoutMs?: number;
+    /** Retries for 429/5xx (default 2). **402 is never retried.** */
+    maxRetries?: number;
+}
+export declare class SocialAPI {
+    private apiKey;
+    private baseUrl;
+    private timeoutMs;
+    private maxRetries;
+    constructor(opts?: SocialAPIOptions | string);
+    private get;
+    /**
+     * Get user profile by username
+     *
+     * Look up a single X account's profile: followers, bio, verification, join date. **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    user_info(username: string): Promise<any>;
+    /**
+     * Get user profile by numeric ID
+     *
+     * Reverse lookup: numeric ID to profile. Useful after followers_ids returns raw IDs. **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    user_info_by_id(user_id: string): Promise<any>;
+    /**
+     * Account transparency details
+     *
+     * X's 'About this account' data: country, join date, username change count, verification history. Anti-bot signal. **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    user_about(username: string): Promise<any>;
+    /**
+     * Recent tweets
+     *
+     * Most recent tweets from an account, newest first. Includes original posts, replies, retweets and quote tweets — the same set X shows on a profile timeline. Use `exclude` to narrow it down. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits). **Deep history**: for accounts under continuous monitoring this endpoint serves up to 1,000 tweets from our own store — well beyond what a live timeline scrape returns. Coverage begins when an account entered monitoring, so the earliest available date differs per account; accounts outside the monitored set return whatever the live timeline yields.
+     */
+    user_last_tweets(username: string, opts?: {
+        limit?: number;
+        cursor?: string;
+        exclude?: string;
+    }): Promise<any>;
+    /**
+     * Replies only
+     *
+     * Only this account's replies, using X's own replies timeline. Equivalent to filtering last_tweets down to replies, but sourced directly from X. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits). **Note**: served from a live timeline read, so depth is bounded by what X returns.
+     */
+    user_replies(username: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Tweets with photos
+     *
+     * Only image posts. Measured 88% carry photos, zero overlap with last_tweets. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits). **Note**: served from a live timeline read, so depth is bounded by what X returns.
+     */
+    user_photos(username: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Tweets with video
+     *
+     * Only video posts, with direct mp4 URLs, duration and thumbnail. Measured 100% carry video. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits). **Note**: served from a live timeline read, so depth is bounded by what X returns.
+     */
+    user_videos(username: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Tweets with any media
+     *
+     * Photos and video combined. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_media(username: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Highlighted tweets
+     *
+     * Tweets the account pinned to its Highlights tab. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_highlights(username: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Long-form articles
+     *
+     * X Articles (long-form posts) with full plain text. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_articles(username: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Mentions of an account
+     *
+     * Who is talking to this account. Core endpoint for brand and ticker sentiment monitoring. **Pricing**: 100 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_mentions(username: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Followers with full profiles
+     *
+     * Follower list with complete profile objects. 200 per page, no depth cap. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_followers(username: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Accounts this user follows
+     *
+     * Following list with full profiles. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_followings(username: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Verified followers
+     *
+     * Only blue-check followers - audience quality signal. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_verified_followers(username: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Follower IDs (lightweight)
+     *
+     * IDs and handles only - 8.3 bytes per follower vs 151 for full profiles. Built for follower-graph crawling at scale. **Pricing**: 60 credits per 100-item tier (1 USD = 100,000 credits).
+     */
+    user_followers_ids(username: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Follow relationship between two accounts
+     *
+     * Does A follow B? Works on any two third-party accounts, not just your own. **Pricing**: 80 credits per call (1 USD = 100,000 credits).
+     */
+    user_relationship(source: string, target: string): Promise<any>;
+    /**
+     * Aggregate account intelligence
+     *
+     * One call returns profile plus recent activity plus transparency data. Concurrent internally. **Pricing**: 80 credits per call (1 USD = 100,000 credits).
+     */
+    user_whois(username: string): Promise<any>;
+    /**
+     * Single tweet
+     *
+     * Full tweet object with all metrics and media. **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    tweet_info(id: string): Promise<any>;
+    /**
+     * Batch fetch tweets by IDs
+     *
+     * Fetch up to 100 tweets by ID in one request — the IDs can come from anywhere, including different accounts. Use this to refresh engagement counts on tweets you already stored, or to fill gaps a timeline cannot reach. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits) — the same rate as any tweet list. Billed on what is actually returned, so IDs that no longer exist cost nothing extra.
+     */
+    tweets_batch(ids: string): Promise<any>;
+    /**
+     * Replies to a tweet
+     *
+     * The reply tree under a tweet. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    tweet_replies(id: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Full thread
+     *
+     * Reconstructs a multi-tweet thread in order. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    tweet_thread(id: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Quote tweets
+     *
+     * Who quoted this tweet and what they said. Note: X's search index favours recent content. **Pricing**: 100 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    tweet_quotes(id: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Users who retweeted
+     *
+     * Retweeter profiles. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    tweet_retweeters(id: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Engagement panorama
+     *
+     * Everything about how one tweet performed, in a single call: the tweet's own counts (likes, retweets, replies, quotes, views, bookmarks) plus the people behind them — who replied and who retweeted, with full profiles. **Pricing**: 120 credits for the first 60 items, then 12 credits per extra item — replies and retweeters counted together. Cheaper than calling `/v1/tweet/replies` and `/v1/tweet/retweeters` separately, which is the point — it saves you the round trip.
+     */
+    tweet_engagement(id: string): Promise<any>;
+    /**
+     * Advanced tweet search
+     *
+     * Full X search syntax. Real-time, not cached. The workhorse for sentiment and event detection. **Pricing**: 100 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    search_advanced(query: string, opts?: {
+        limit?: number;
+        product?: string;
+    }): Promise<any>;
+    /**
+     * Search users
+     *
+     * Find accounts by keyword. **Pricing**: 100 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    search_user(query: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Community details
+     *
+     * Name, description, member count, join policy, rules. **Pricing**: 12 credits per call (1 USD = 100,000 credits).
+     */
+    community_info(community_id: string): Promise<any>;
+    /**
+     * Community tweet stream
+     *
+     * Posts inside an X Community. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    community_tweets(community_id: string, opts?: {
+        limit?: number;
+        cursor?: string;
+        ranking?: string;
+    }): Promise<any>;
+    /**
+     * Community members
+     *
+     * Member list with cursor pagination - measured zero duplicates across 39 pages. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    community_members(community_id: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Community moderators
+     *
+     * Moderator list. Single digits typically, returned in one call. **Pricing**: 25 credits per call (1 USD = 100,000 credits).
+     */
+    community_moderators(community_id: string): Promise<any>;
+    /**
+     * List timeline
+     *
+     * Tweets from every account on an X List. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    list_timeline(list_id: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * List members
+     *
+     * Accounts on a List. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    list_members(list_id: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * List subscribers
+     *
+     * Accounts subscribed to a List. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    list_subscribers(list_id: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Global trending topics
+     *
+     * What is trending right now worldwide. **Pricing**: 12 credits per call (1 USD = 100,000 credits).
+     */
+    trends(): Promise<any>;
+    /**
+     * Trends for a region
+     *
+     * Region-specific trends across 467 locations - neither competitor offers this. **Pricing**: 12 credits per call (1 USD = 100,000 credits).
+     */
+    trends_place(opts?: {
+        woeid?: number;
+    }): Promise<any>;
+    /**
+     * Available trend regions
+     *
+     * The 467 WOEIDs accepted by /v1/trends/place. Static data, cache it. **Pricing**: 12 credits per call (1 USD = 100,000 credits).
+     */
+    trends_locations(): Promise<any>;
+    /**
+     * Explore feed
+     *
+     * X's multi-section explore page. **Pricing**: 20 credits per call (1 USD = 100,000 credits).
+     */
+    explore(): Promise<any>;
+    /**
+     * Batch user profiles
+     *
+     * Multiple profiles in one call, fetched concurrently. **Pricing**: 40 credits per call (1 USD = 100,000 credits).
+     */
+    batch_user_info(usernames: string): Promise<any>;
+    /**
+     * Account status (alive / suspended / not found)
+     *
+     * Check whether an X account is alive, suspended, deleted or otherwise unavailable — without guessing from a 404. Returns one of: `alive` (with user_id), `suspended`, `not_found`, `unavailable`. Always HTTP 200 — "the account does not exist"… **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    user_status(username: string): Promise<any>;
+    /**
+     * Verified organization affiliates
+     *
+     * Official accounts affiliated with a verified organization (staff, sub-brands). Get a company's entire X footprint in one call. Note: pass the ORGANIZATION handle (e.g. `X`), not a member account. **Pricing**: 80 credits per call (1 USD = 100,000 credits).
+     */
+    user_affiliates(username: string, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Account usage & balance
+     *
+     * Your current credit balance, plus call counts and spend for today and the last 30 days, your account email and join date, and your total deposits with the volume-bonus tier they earn. **Free** — this endpoint is not billed. Use it to check
+     */
+    usage(): Promise<any>;
+    /**
+     * Usage analytics & runway
+     *
+     * Per-day and per-endpoint usage over a window, plus success rate, p50/p95 latency, and a **runway estimate** — how many days your balance lasts at the current burn rate (API spend plus any live-stream subscriptions). **Free** — this endpoint
+     */
+    analytics(opts?: {
+        days?: number;
+    }): Promise<any>;
+    /**
+     * Recent request log
+     *
+     * Your most recent API calls with endpoint, status, latency and credits charged. Useful for debugging a client without leaving your terminal. **Free** — this endpoint is not billed.
+     */
+    logs(opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * List API keys
+     *
+     * Your API keys with labels, creation time and last-used time. Key values themselves are stored hashed and are never returned — only their metadata. **Free** — this endpoint is not billed.
+     */
+    keys(): Promise<any>;
+    /**
+     * Live-stream subscriptions
+     *
+     * Which accounts you are monitoring over the live stream, how many are active versus paused, what they cost per hour and per day, and how many days your balance covers at that rate. **Free** — this endpoint is not billed. (The subscriptions t
+     */
+    stream_subscriptions(): Promise<any>;
+    /**
+     * Credit balance
+     *
+     * Your credit balance on its own — the smallest call for a balance check. **Free** — this endpoint is not billed.
+     */
+    deposit_balance(): Promise<any>;
+}
+export default SocialAPI;

package/dist/index.js

@@ -0,0 +1,494 @@
+/**
+ * SocialAPI TypeScript/JavaScript SDK — real-time X (Twitter) data.
+ *
+ * GENERATED FILE - DO NOT EDIT BY HAND.
+ * Produced by sdk-generator/generate.mjs from openapi.json. Edit the spec and
+ * regenerate; hand edits are overwritten on the next run.
+ *
+ * Docs: https://socialapi.tech/docs
+ */
+export class SocialAPIError extends Error {
+    status;
+    code;
+    constructor(message, status = 0, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "SocialAPIError";
+    }
+}
+/** 429 - rate limited. **Not charged**; back off and retry. */
+export class RateLimited extends SocialAPIError {
+    constructor(message) {
+        super(message, 429);
+        this.name = "RateLimited";
+    }
+}
+/** 402 - out of credits. **Do not retry**; top up first. */
+export class InsufficientCredits extends SocialAPIError {
+    constructor(message) {
+        super(message, 402);
+        this.name = "InsufficientCredits";
+    }
+}
+const VERSION = "1.0.0";
+export class SocialAPI {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    constructor(opts = {}) {
+        const o = typeof opts === "string" ? { apiKey: opts } : opts;
+        const key = o.apiKey ??
+            (typeof process !== "undefined" ? process.env?.SOCIALAPI_KEY : undefined) ??
+            "";
+        if (!key) {
+            throw new Error("API key missing. Pass apiKey or set SOCIALAPI_KEY. " +
+                "Get one free at https://socialapi.tech/signup");
+        }
+        this.apiKey = key;
+        this.baseUrl = (o.baseUrl ?? "https://api.socialapi.tech").replace(/\/$/, "");
+        this.timeoutMs = o.timeoutMs ?? 30_000;
+        this.maxRetries = o.maxRetries ?? 2;
+    }
+    async get(path, params) {
+        // Drop undefined/null so the server applies its own default.
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== null)
+                url.searchParams.set(k, String(v));
+        }
+        let lastErr;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+            try {
+                const res = await fetch(url, {
+                    headers: {
+                        "X-API-Key": this.apiKey,
+                        "User-Agent": `socialapi-js/${VERSION}`,
+                    },
+                    signal: ac.signal,
+                });
+                clearTimeout(timer);
+                if (res.status === 200) {
+                    const body = await res.json();
+                    if (body && body.status === "error") {
+                        throw new SocialAPIError(body.error?.message ?? "unknown error", 200, body.error?.code);
+                    }
+                    return body?.data ?? body;
+                }
+                // Never retry 402: deterministic failure.
+                if (res.status === 402) {
+                    throw new InsufficientCredits("insufficient credits — top up at https://socialapi.tech/dashboard/deposit");
+                }
+                if (res.status === 429) {
+                    lastErr = new RateLimited("rate limited (not charged) — back off and retry");
+                    if (attempt < this.maxRetries) {
+                        await sleep(2 ** attempt * 1000);
+                        continue;
+                    }
+                    throw lastErr;
+                }
+                if (res.status >= 500 && attempt < this.maxRetries) {
+                    lastErr = new SocialAPIError(`server error ${res.status}`, res.status);
+                    await sleep(2 ** attempt * 1000);
+                    continue;
+                }
+                let msg = `HTTP ${res.status}`;
+                try {
+                    msg = (await res.json())?.error?.message ?? msg;
+                }
+                catch {
+                    /* body was not JSON - fall back to the status code */
+                }
+                throw new SocialAPIError(msg, res.status);
+            }
+            catch (e) {
+                clearTimeout(timer);
+                if (e instanceof SocialAPIError)
+                    throw e;
+                lastErr = e;
+                if (attempt < this.maxRetries) {
+                    await sleep(2 ** attempt * 1000);
+                    continue;
+                }
+                throw new SocialAPIError(`network error: ${e?.message ?? e}`);
+            }
+        }
+        throw lastErr ?? new SocialAPIError("request failed");
+    }
+    // ── generated endpoint methods (46) ──────────────────
+    /**
+     * Get user profile by username
+     *
+     * Look up a single X account's profile: followers, bio, verification, join date. **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    user_info(username) {
+        return this.get("/v1/user/info", { username });
+    }
+    /**
+     * Get user profile by numeric ID
+     *
+     * Reverse lookup: numeric ID to profile. Useful after followers_ids returns raw IDs. **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    user_info_by_id(user_id) {
+        return this.get("/v1/user/info_by_id", { user_id });
+    }
+    /**
+     * Account transparency details
+     *
+     * X's 'About this account' data: country, join date, username change count, verification history. Anti-bot signal. **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    user_about(username) {
+        return this.get("/v1/user/about", { username });
+    }
+    /**
+     * Recent tweets
+     *
+     * Most recent tweets from an account, newest first. Includes original posts, replies, retweets and quote tweets — the same set X shows on a profile timeline. Use `exclude` to narrow it down. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits). **Deep history**: for accounts under continuous monitoring this endpoint serves up to 1,000 tweets from our own store — well beyond what a live timeline scrape returns. Coverage begins when an account entered monitoring, so the earliest available date differs per account; accounts outside the monitored set return whatever the live timeline yields.
+     */
+    user_last_tweets(username, opts = {}) {
+        return this.get("/v1/user/last_tweets", { username, limit: opts.limit, cursor: opts.cursor, exclude: opts.exclude });
+    }
+    /**
+     * Replies only
+     *
+     * Only this account's replies, using X's own replies timeline. Equivalent to filtering last_tweets down to replies, but sourced directly from X. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits). **Note**: served from a live timeline read, so depth is bounded by what X returns.
+     */
+    user_replies(username, opts = {}) {
+        return this.get("/v1/user/replies", { username, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * Tweets with photos
+     *
+     * Only image posts. Measured 88% carry photos, zero overlap with last_tweets. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits). **Note**: served from a live timeline read, so depth is bounded by what X returns.
+     */
+    user_photos(username, opts = {}) {
+        return this.get("/v1/user/photos", { username, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * Tweets with video
+     *
+     * Only video posts, with direct mp4 URLs, duration and thumbnail. Measured 100% carry video. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits). **Note**: served from a live timeline read, so depth is bounded by what X returns.
+     */
+    user_videos(username, opts = {}) {
+        return this.get("/v1/user/videos", { username, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * Tweets with any media
+     *
+     * Photos and video combined. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_media(username, opts = {}) {
+        return this.get("/v1/user/media", { username, limit: opts.limit });
+    }
+    /**
+     * Highlighted tweets
+     *
+     * Tweets the account pinned to its Highlights tab. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_highlights(username, opts = {}) {
+        return this.get("/v1/user/highlights", { username, limit: opts.limit });
+    }
+    /**
+     * Long-form articles
+     *
+     * X Articles (long-form posts) with full plain text. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_articles(username, opts = {}) {
+        return this.get("/v1/user/articles", { username, limit: opts.limit });
+    }
+    /**
+     * Mentions of an account
+     *
+     * Who is talking to this account. Core endpoint for brand and ticker sentiment monitoring. **Pricing**: 100 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_mentions(username, opts = {}) {
+        return this.get("/v1/user/mentions", { username, limit: opts.limit });
+    }
+    /**
+     * Followers with full profiles
+     *
+     * Follower list with complete profile objects. 200 per page, no depth cap. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_followers(username, opts = {}) {
+        return this.get("/v1/user/followers", { username, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * Accounts this user follows
+     *
+     * Following list with full profiles. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_followings(username, opts = {}) {
+        return this.get("/v1/user/followings", { username, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * Verified followers
+     *
+     * Only blue-check followers - audience quality signal. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    user_verified_followers(username, opts = {}) {
+        return this.get("/v1/user/verified_followers", { username, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * Follower IDs (lightweight)
+     *
+     * IDs and handles only - 8.3 bytes per follower vs 151 for full profiles. Built for follower-graph crawling at scale. **Pricing**: 60 credits per 100-item tier (1 USD = 100,000 credits).
+     */
+    user_followers_ids(username, opts = {}) {
+        return this.get("/v1/user/followers_ids", { username, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * Follow relationship between two accounts
+     *
+     * Does A follow B? Works on any two third-party accounts, not just your own. **Pricing**: 80 credits per call (1 USD = 100,000 credits).
+     */
+    user_relationship(source, target) {
+        return this.get("/v1/user/relationship", { source, target });
+    }
+    /**
+     * Aggregate account intelligence
+     *
+     * One call returns profile plus recent activity plus transparency data. Concurrent internally. **Pricing**: 80 credits per call (1 USD = 100,000 credits).
+     */
+    user_whois(username) {
+        return this.get("/v1/user/whois", { username });
+    }
+    /**
+     * Single tweet
+     *
+     * Full tweet object with all metrics and media. **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    tweet_info(id) {
+        return this.get("/v1/tweet/info", { id });
+    }
+    /**
+     * Batch fetch tweets by IDs
+     *
+     * Fetch up to 100 tweets by ID in one request — the IDs can come from anywhere, including different accounts. Use this to refresh engagement counts on tweets you already stored, or to fill gaps a timeline cannot reach. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits) — the same rate as any tweet list. Billed on what is actually returned, so IDs that no longer exist cost nothing extra.
+     */
+    tweets_batch(ids) {
+        return this.get("/v1/tweets/batch", { ids });
+    }
+    /**
+     * Replies to a tweet
+     *
+     * The reply tree under a tweet. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    tweet_replies(id, opts = {}) {
+        return this.get("/v1/tweet/replies", { id, limit: opts.limit });
+    }
+    /**
+     * Full thread
+     *
+     * Reconstructs a multi-tweet thread in order. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    tweet_thread(id, opts = {}) {
+        return this.get("/v1/tweet/thread", { id, limit: opts.limit });
+    }
+    /**
+     * Quote tweets
+     *
+     * Who quoted this tweet and what they said. Note: X's search index favours recent content. **Pricing**: 100 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    tweet_quotes(id, opts = {}) {
+        return this.get("/v1/tweet/quotes", { id, limit: opts.limit });
+    }
+    /**
+     * Users who retweeted
+     *
+     * Retweeter profiles. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    tweet_retweeters(id, opts = {}) {
+        return this.get("/v1/tweet/retweeters", { id, limit: opts.limit });
+    }
+    /**
+     * Engagement panorama
+     *
+     * Everything about how one tweet performed, in a single call: the tweet's own counts (likes, retweets, replies, quotes, views, bookmarks) plus the people behind them — who replied and who retweeted, with full profiles. **Pricing**: 120 credits for the first 60 items, then 12 credits per extra item — replies and retweeters counted together. Cheaper than calling `/v1/tweet/replies` and `/v1/tweet/retweeters` separately, which is the point — it saves you the round trip.
+     */
+    tweet_engagement(id) {
+        return this.get("/v1/tweet/engagement", { id });
+    }
+    /**
+     * Advanced tweet search
+     *
+     * Full X search syntax. Real-time, not cached. The workhorse for sentiment and event detection. **Pricing**: 100 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    search_advanced(query, opts = {}) {
+        return this.get("/v1/search/advanced", { query, limit: opts.limit, product: opts.product });
+    }
+    /**
+     * Search users
+     *
+     * Find accounts by keyword. **Pricing**: 100 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    search_user(query, opts = {}) {
+        return this.get("/v1/search/user", { query, limit: opts.limit });
+    }
+    /**
+     * Community details
+     *
+     * Name, description, member count, join policy, rules. **Pricing**: 12 credits per call (1 USD = 100,000 credits).
+     */
+    community_info(community_id) {
+        return this.get("/v1/community/info", { community_id });
+    }
+    /**
+     * Community tweet stream
+     *
+     * Posts inside an X Community. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    community_tweets(community_id, opts = {}) {
+        return this.get("/v1/community/tweets", { community_id, limit: opts.limit, cursor: opts.cursor, ranking: opts.ranking });
+    }
+    /**
+     * Community members
+     *
+     * Member list with cursor pagination - measured zero duplicates across 39 pages. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    community_members(community_id, opts = {}) {
+        return this.get("/v1/community/members", { community_id, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * Community moderators
+     *
+     * Moderator list. Single digits typically, returned in one call. **Pricing**: 25 credits per call (1 USD = 100,000 credits).
+     */
+    community_moderators(community_id) {
+        return this.get("/v1/community/moderators", { community_id });
+    }
+    /**
+     * List timeline
+     *
+     * Tweets from every account on an X List. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    list_timeline(list_id, opts = {}) {
+        return this.get("/v1/list/timeline", { list_id, limit: opts.limit });
+    }
+    /**
+     * List members
+     *
+     * Accounts on a List. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    list_members(list_id, opts = {}) {
+        return this.get("/v1/list/members", { list_id, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * List subscribers
+     *
+     * Accounts subscribed to a List. **Pricing**: 80 credits for the first 30 items, then 12 credits per extra item (1 USD = 100,000 credits).
+     */
+    list_subscribers(list_id, opts = {}) {
+        return this.get("/v1/list/subscribers", { list_id, limit: opts.limit, cursor: opts.cursor });
+    }
+    /**
+     * Global trending topics
+     *
+     * What is trending right now worldwide. **Pricing**: 12 credits per call (1 USD = 100,000 credits).
+     */
+    trends() {
+        return this.get("/v1/trends", {});
+    }
+    /**
+     * Trends for a region
+     *
+     * Region-specific trends across 467 locations - neither competitor offers this. **Pricing**: 12 credits per call (1 USD = 100,000 credits).
+     */
+    trends_place(opts = {}) {
+        return this.get("/v1/trends/place", { woeid: opts.woeid });
+    }
+    /**
+     * Available trend regions
+     *
+     * The 467 WOEIDs accepted by /v1/trends/place. Static data, cache it. **Pricing**: 12 credits per call (1 USD = 100,000 credits).
+     */
+    trends_locations() {
+        return this.get("/v1/trends/locations", {});
+    }
+    /**
+     * Explore feed
+     *
+     * X's multi-section explore page. **Pricing**: 20 credits per call (1 USD = 100,000 credits).
+     */
+    explore() {
+        return this.get("/v1/explore", {});
+    }
+    /**
+     * Batch user profiles
+     *
+     * Multiple profiles in one call, fetched concurrently. **Pricing**: 40 credits per call (1 USD = 100,000 credits).
+     */
+    batch_user_info(usernames) {
+        return this.get("/v1/batch/user_info", { usernames });
+    }
+    /**
+     * Account status (alive / suspended / not found)
+     *
+     * Check whether an X account is alive, suspended, deleted or otherwise unavailable — without guessing from a 404. Returns one of: `alive` (with user_id), `suspended`, `not_found`, `unavailable`. Always HTTP 200 — "the account does not exist"… **Pricing**: 15 credits per call (1 USD = 100,000 credits).
+     */
+    user_status(username) {
+        return this.get("/v1/user/status", { username });
+    }
+    /**
+     * Verified organization affiliates
+     *
+     * Official accounts affiliated with a verified organization (staff, sub-brands). Get a company's entire X footprint in one call. Note: pass the ORGANIZATION handle (e.g. `X`), not a member account. **Pricing**: 80 credits per call (1 USD = 100,000 credits).
+     */
+    user_affiliates(username, opts = {}) {
+        return this.get("/v1/user/affiliates", { username, cursor: opts.cursor, limit: opts.limit });
+    }
+    /**
+     * Account usage & balance
+     *
+     * Your current credit balance, plus call counts and spend for today and the last 30 days, your account email and join date, and your total deposits with the volume-bonus tier they earn. **Free** — this endpoint is not billed. Use it to check
+     */
+    usage() {
+        return this.get("/v1/usage", {});
+    }
+    /**
+     * Usage analytics & runway
+     *
+     * Per-day and per-endpoint usage over a window, plus success rate, p50/p95 latency, and a **runway estimate** — how many days your balance lasts at the current burn rate (API spend plus any live-stream subscriptions). **Free** — this endpoint
+     */
+    analytics(opts = {}) {
+        return this.get("/v1/analytics", { days: opts.days });
+    }
+    /**
+     * Recent request log
+     *
+     * Your most recent API calls with endpoint, status, latency and credits charged. Useful for debugging a client without leaving your terminal. **Free** — this endpoint is not billed.
+     */
+    logs(opts = {}) {
+        return this.get("/v1/logs", { limit: opts.limit });
+    }
+    /**
+     * List API keys
+     *
+     * Your API keys with labels, creation time and last-used time. Key values themselves are stored hashed and are never returned — only their metadata. **Free** — this endpoint is not billed.
+     */
+    keys() {
+        return this.get("/v1/keys", {});
+    }
+    /**
+     * Live-stream subscriptions
+     *
+     * Which accounts you are monitoring over the live stream, how many are active versus paused, what they cost per hour and per day, and how many days your balance covers at that rate. **Free** — this endpoint is not billed. (The subscriptions t
+     */
+    stream_subscriptions() {
+        return this.get("/v1/stream/subscriptions", {});
+    }
+    /**
+     * Credit balance
+     *
+     * Your credit balance on its own — the smallest call for a balance check. **Free** — this endpoint is not billed.
+     */
+    deposit_balance() {
+        return this.get("/v1/deposit/balance", {});
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export default SocialAPI;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@socialapitech/sdk",
+  "version": "1.0.0",
+  "description": "Real-time X (Twitter) data — 40 endpoints plus live streaming. $0.0008 per call, up to 30 tweets, from $0.000027 each. Around 100x cheaper than the official X API.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node --test test/smoke.test.js"
+  },
+  "keywords": [
+    "twitter",
+    "x",
+    "twitter-api",
+    "x-api",
+    "twitter-scraper",
+    "social-media",
+    "sentiment-analysis",
+    "twitter-data",
+    "api-client",
+    "typescript",
+    "socialapi",
+    "twitter-stream",
+    "realtime",
+    "websocket",
+    "twitter-monitoring"
+  ],
+  "author": "SocialAPI Tech <contact@socialapi.tech>",
+  "license": "MIT",
+  "homepage": "https://socialapi.tech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/socialapitech/socialapi-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/socialapitech/socialapi-node/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  }
+}