obscuraworks-sdk

Official Node.js SDK and CLI for the Obscuraworks API. Covers ~200 endpoints across AI, Downloader, Tools, Stalk, Search, Maker, Games, BPS, v1, v2 and more. Compiled to CommonJS so it drops in cleanly to Baileys WhatsApp bots and any classic Node.js project.

npm install obscuraworks-sdk

const { ObscuraworksClient } = require('obscuraworks-sdk');

const client = new ObscuraworksClient('YOUR_API_KEY');
// or: new ObscuraworksClient({ apiKey: 'YOUR_API_KEY' });
// or: leave empty and set OBSCURAWORKS_API_KEY in your env.

The CLI is bundled with the same package:

npx obscuraworks --help
# or after npm i -g obscuraworks-sdk
obscuraworks ai chat "Halo dunia"

Why this SDK?

• Modular — every endpoint family is its own small module under src/sdk/modules/. Use the high-level client.<module>.<method>() calls or drop down to client.http.get(...) / client.http.post(...) for endpoints that aren't typed yet.
• CommonJS-first — require('obscuraworks-sdk') just works in Baileys bots, PM2 setups, and any legacy stack. No ESM-only surprises.
• Baileys-friendly — image / video maker endpoints return a real Node Buffer, so you can pipe straight into sock.sendMessage(jid, { image: buf }).
• Bundled CLI — obscuraworks / obscura binaries are installed alongside, with brand-orange (#f7931a) accents from chalk.
• Typed — TypeScript types ship in the package. Plain JavaScript usage works without any extra setup.

Quick start: Baileys

const { default: makeWASocket } = require('@whiskeysockets/baileys');
const { ObscuraworksClient } = require('obscuraworks-sdk');

const client = new ObscuraworksClient(process.env.OBSCURAWORKS_API_KEY);

async function handleMessage(sock, jid, body) {
  // 1) AI chat → text
  if (body.startsWith('!ai ')) {
    const prompt = body.slice(4);
    const res = await client.ai.groq(prompt);
    await sock.sendMessage(jid, { text: res.data || res.message });
    return;
  }

  // 2) Instagram downloader → send the resolved video URL
  if (body.startsWith('!ig ')) {
    const url = body.slice(4);
    const res = await client.downloader.ig(url);
    // The API returns one or more video/image URLs depending on the post.
    // Use the first one as a quick example:
    const vid = res?.data?.[0]?.url || res?.url;
    await sock.sendMessage(jid, { video: { url: vid } });
    return;
  }

  // 3) Brat sticker → returns a Buffer ready to send
  if (body.startsWith('!brat ')) {
    const text = body.slice(6);
    const buf = await client.maker.brat(text);
    await sock.sendMessage(jid, { sticker: buf });
    return;
  }

  // 4) TikTok downloader
  if (body.startsWith('!tiktok ')) {
    const res = await client.downloader.tiktok(body.slice(8));
    await sock.sendMessage(jid, { video: { url: res?.data?.video || res?.url } });
    return;
  }
}

The SDK also works perfectly in normal Node servers, Discord bots, scripts, or node --experimental-fetch environments.

Modules

The top-level client exposes:

| Property | Description | | --------------------- | -------------------------------------------------------------------------------------------- | | client.ai | /api/ai/* — chat, vision, image gen, content moderation | | client.downloader | /api/downloader/* — TikTok, IG, YouTube, FB, Spotify, GDrive, MediaFire, all-in-one, ... | | client.tools | /api/tools/* — image edits, OSINT, DNS, whois, TTS, generators, iloveimg.* | | client.stalk | /api/stalk/* — GitHub, Roblox, TikTok, IG, Genshin, MLBB, ER, ... | | client.search | /api/search/* — Brave, NPM, Spotify, Lazada, AN1, Mangatoon, MCPEDL, ... | | client.maker | /api/maker/* — brat, welcome cards, profile, ship, ektp, ... | | client.games | /api/games/* — MLBB checker, mini games | | client.bps | /api/bps/* — Statistics Indonesia | | client.news | /api/news — news feed | | client.server | /api/server — fleet metadata | | client.currency | /api/currency — conversion | | client.system | /api/system/*, /api/healthz, /api/docs, /api/openapi | | client.cron | /api/cron/* (admin only) | | client.authLegacy | /api/auth/* legacy auth flow (OTP, Google, complete-profile) | | client.v1Legacy | /api/v1/* wallet, transaction, profile patches | | client.auth | /v1/auth/* modern JWT auth | | client.me | /v1/me/* JWT-scoped profile, usage, API key rotation | | client.admin | /v1/admin/* staff endpoints | | client.health | /v1/system/* health/ready/version/info/stats | | client.v2 | /api/v2/* modern search/tools/maker (carbon, iqc, ghibli, miniator, ...) |

Each module is a small class — see src/sdk/modules/*.ts for the complete method list.

Examples

// AI chat (any provider)
await client.ai.groq('Tulis pantun lucu');
await client.ai.deepseek('Explain quantum entanglement');
await client.ai.gemini('Translate to French: I love coding');
await client.ai.flux('cyberpunk samurai, neon, ultra detailed'); // image generation
await client.ai.imageToPrompt('https://example.com/img.png');

// Downloaders
await client.downloader.tiktok('https://vt.tiktok.com/...');
await client.downloader.ig('https://www.instagram.com/p/...');
await client.downloader.youtube('https://youtu.be/...');
await client.downloader.allInOne('https://anything.tld/...');

// Tools
await client.tools.whois('obscuraworks.com');
await client.tools.dns('obscuraworks.com');
await client.tools.tts('Hello there');           // text to speech
await client.tools.iloveimg.removebg('https://example.com/img.png');

// Stalk
await client.stalk.github('torvalds');
await client.stalk.mlV2('12345678', 1234);
await client.stalk.ff('123456789');

// Search
await client.search.npm('baileys');
await client.search.brave('obscuraworks api');
await client.search.spotify('weeknd starboy');

// Maker (returns Buffer — perfect for Baileys)
const stickerBuf = await client.maker.brat('hello');
const cardBuf = await client.maker.welcome1({
  username: 'alice',
  avatar: 'https://example.com/avatar.png',
  background: 'https://example.com/bg.png',
  guild_name: 'Obscura Lounge',
  member_count: '420',
});

// v2 endpoints
await client.v2.search.spotify('weeknd');
await client.v2.tools.ghibli('https://example.com/portrait.png');
await client.v2.maker.carbon('console.log("hi")');

// Modern /v1 JWT flow
const login = await client.auth.login({ email: '[email protected]', password: 'secret' });
const me = await client.me.get(login.data.access_token);
const usage = await client.me.usage(login.data.access_token);

Lower-level escape hatch

If an endpoint isn't typed yet, use the bundled HTTP client directly:

const r = await client.http.get('/api/tools/whois', { domain: 'obscuraworks.com' });
const s = await client.http.post('/api/ai/copilot', { message: 'hi' });

You can also override config per call:

await client.ai.groq('hi', {}, { timeoutMs: 5_000 });

CLI usage

The package ships with two binaries: obscuraworks and the shorter alias obscura. Both behave identically.

# Global help
obscuraworks --help

# AI chat
obscuraworks ai chat "Halo"
obscuraworks ai deepseek "Jelaskan bedanya HTTP/1.1 dan HTTP/2"
obscuraworks ai flux "neon cat samurai"

# Downloaders
obscuraworks dl tiktok "https://vt.tiktok.com/..."
obscuraworks dl ig "https://www.instagram.com/p/..."
obscuraworks dl ytmp3 "https://youtu.be/..."

# Tools
obscuraworks tools whois obscuraworks.com
obscuraworks tools dns obscuraworks.com
obscuraworks tools ccgen 411111 --count 5

# Maker — pipe straight to a file with -o
obscuraworks maker brat "hello" -o brat.png
obscuraworks maker welcome1 -x username=alice avatar=https://example.com/a.png -o card.png

# Stalk
obscuraworks stalk github torvalds
obscuraworks stalk ff 12345678

# Auth (JWT)
obscuraworks auth login [email protected] secret
obscuraworks me get <accessToken>

Global options:

| Flag | Purpose | | ----------------- | ------------------------------------------- | | -k, --api-key | Bearer API key (else OBSCURAWORKS_API_KEY) | | -b, --base-url | Override base URL | | -t, --timeout | Per-request timeout (ms) | | --json | Raw JSON output |

Authentication

The SDK sends every request as Authorization: Bearer <apiKey>. You can either:

1. Pass the key to the constructor: new ObscuraworksClient('KEY').
2. Set the environment variable: OBSCURAWORKS_API_KEY=KEY.
3. Rotate at runtime: client.setApiKey('NEW_KEY').

The modern /v1 JWT endpoints take their own per-call access token — see client.auth.login(...) and pass the returned access_token to client.me.* / client.admin.*.

Error handling

Non-2xx responses throw an ObscuraworksError with the full server payload preserved:

const { ObscuraworksError } = require('obscuraworks-sdk');
try {
  await client.ai.groq('hi');
} catch (err) {
  if (err instanceof ObscuraworksError) {
    console.error(err.status, err.message, err.data);
  } else {
    throw err;
  }
}

Links

• Homepage — https://obscuraworks.com
• API docs — https://api.obscuraworks.com/docs
• Issues — https://github.com/NyxObscura/obscuraworks-sdk/issues
• npm — https://www.npmjs.com/package/obscuraworks-sdk

MIT © Obscuraworks