@sptzx/sdk

Official JavaScript SDK for the Siputzx API.

@sptzx/sdk is designed for developers who want a higher-level client than manual fetch or axios calls. It handles endpoint discovery, official SDK session negotiation, request signing, retry-on-refresh flows, and consistent response handling while keeping the public API compact.

Why use the SDK instead of raw HTTP requests?

Using the package provides several practical advantages over calling the API directly.

• Automatic OpenAPI discovery from /api/openapi.json
• Official SDK handshake and session lifecycle management
• Automatic request signing, nonce handling, and timestamping
• Session reuse in-memory with client-level caching per process
• Refresh-on-demand when the gateway requires a new session
• Consistent error handling for invalid sessions, key rotation, stale timestamps, replay protection, and upstream failures
• Human-friendly endpoint groups such as games, anime, downloader, news, and random
• Runtime support verified in Node.js, Bun, and Deno

In practice, this means developers can keep code simple:

import { createClient } from '@sptzx/sdk';

const client = await createClient();
const result = await client.games.asahotak();
console.log(result.soal);

instead of manually implementing handshake, session refresh, signatures, and endpoint routing.

Features

• Runtime endpoint discovery
• Official SDK session handshake
• Automatic client reuse per process
• Concurrent createClient() deduplication
• Automatic session refresh on refresh-required
• Replay protection, fingerprint binding, and key version handling
• Raw response access when needed
• No runtime dependencies

Installation

npm install @sptzx/sdk

Runtime support

The SDK has been verified with the following runtimes:

• Node.js 18+
• Bun
• Deno

For Deno, the distributed build is patched to use node: imports so the package can run through Deno's Node compatibility layer.

Quick start

import { createClient } from '@sptzx/sdk';

const client = await createClient({
  baseUrl: 'https://api.siputzx.my.id',
  apiKey: 'your-api-key',
});

const game = await client.games.asahotak();
console.log(game.soal, game.jawaban);

API overview

createClient(options?)

Creates or reuses an SDK client.

By default, the SDK caches a client per process for the same configuration. This helps avoid repeated handshakes in common bot or plugin patterns where many modules call createClient() independently.

Options:

• baseUrl?: string
• apiKey?: string
• timeoutMs?: number
• openApiPath?: string
• headers?: Record<string, string>
• cache?: boolean
• forceNew?: boolean
• fetch?: typeof fetch

Example:

const client = await createClient({
  baseUrl: 'https://api.siputzx.my.id',
  timeoutMs: 15_000,
});

Endpoint calls

Endpoints are grouped automatically.

await client.games.asahotak();
await client.games.family100();
await client.downloader.fastdl({ url: 'https://www.instagram.com/siputzx_/' });
await client.news.kompas();
await client.info.bmkg();

Raw responses

If you need headers or status codes, use .raw():

const response = await client.games.asahotak.raw();
console.log(response.statusCode, response.headers, response.data);

Metadata and discovery helpers

const endpoints = client.listEndpoints();
const meta = client.meta('games.asahotak');

Session revocation

await client.revokeSession();

This is useful for explicit cleanup, testing, or controlled shutdown flows.

How session management works

The SDK creates a short-lived session through an official gateway handshake. That session is then reused for subsequent requests inside the same process.

Important behavior:

• The session is stored in memory, not on disk
• Repeated requests reuse the same session while it is still valid
• Repeated createClient() calls with the same configuration reuse the same client instance by default
• If the gateway responds with refresh-required, the SDK refreshes the session and retries once
• If the session is revoked or expires, a new session is negotiated automatically

This design is intended to reduce handshake overhead for common use cases such as chatbots, plugins, and command handlers.

Error handling

The SDK normalizes several common failure modes into structured errors.

Examples include:

• invalid token or invalid session
• key version rotation requirements
• stale timestamps
• nonce replay rejection
• maintenance or upstream failures

Typical usage:

try {
  const result = await client.games.asahotak();
  console.log(result);
} catch (error) {
  console.error(error.name, error.code, error.statusCode, error.message);
}

Security model

The package is intentionally designed around server-side verification rather than client secrecy.

Key points:

• the gateway issues SDK sessions
• requests are signed per call
• nonce replay is rejected
• fingerprints and key versions are validated
• anomaly thresholds can revoke bad sessions automatically

This means the SDK provides convenience and a stronger integration path, while final trust decisions remain on the server.

Testing

Build:

npm run build

Live integration suite:

npm run test:live

Runtime compatibility suite:

npm run test:runtime

The runtime suite verifies the built package in:

• Node.js
• Bun
• Deno

Package contents

Published package contents are intentionally small:

• compiled dist/ output
• type declarations
• README.md
• LICENSE

The source remains maintainable in the repository while the published dist/ stays compact and harder to read.

License

MIT