@protocol-top/sdk

The official TypeScript SDK for Protocol — a unified Metaphysics-as-a-Service API that exposes 40+ calculation engines across Vedic astrology, Chinese Bazi, Qi Men Dun Jia, Japanese Sukuyodo, Islamic astrology, horary, synastry, and timing systems. Use it the same way you'd use stripe or @anthropic-ai/sdk: one client, strict types, friendly errors, batteries included.

Feature Highlights

• Live today — 24 namespaces: oracle (7 engines), fengShui, tasyir, vedic (chart / dasha / nakshatra / transits / yogas / ashtakavarga / vargas), bazi, acg, daLiuRen, taiYi, tarot, mahakala (30 engines), muhurta, panchaPakshi, ziwei, mawalid, western, horary, mundane, rosetta, financial, sahl, picatrix, mashaallah, synastry, qiMen. Remaining methods roll out endpoint-by-endpoint (they throw NotImplementedError until live).
• Strict TypeScript — every method has explicit input/output types. No any, no guesswork.
• Zero production deps — one lightweight fetch wrapper, works in Node 18+, Edge runtimes, and modern browsers.
• Friendly errors — branch on instanceof AuthError, RateLimitError, ValidationError, EngineError, NetworkError, TimeoutError.
• Built-in retries + timeouts — exponential backoff on 5xx/network errors, per-request AbortController.
• Tree-shakable — pure ESM, sideEffects: false, ships ~8 KB gzipped for the core.
• Provenance-signed — every npm release is built via GitHub Actions with npm provenance attestation.

Installation

pnpm add @protocol-top/sdk
# or
npm install @protocol-top/sdk
# or
yarn add @protocol-top/sdk

Requires Node 18+ (for native fetch / AbortController) or any modern browser / edge runtime.

Quickstart

import { ProtocolClient } from '@protocol-top/sdk';

const client = new ProtocolClient({
  apiKey: process.env.PROTOCOL_API_KEY!, // pk_live_... or pk_test_...
});

// Oracle reading (live today)
const reading = await client.oracle.read({
  engine: 'career',
  birth_date: '1990-05-15',
  birth_time: '14:30',
  birth_lat: 13.7563,
  birth_lng: 100.5018,
  include_ai: false,
});

console.log(reading.engine_result);

Availability: 24 namespaces are live today — check ProtocolClient.LIVE_NAMESPACES at runtime for the authoritative list. Only client.career and client.karma remain typed-but-unbacked (they throw NotImplementedError). API keys (pk_test_* / pk_live_*) are issued by the Protocol team — contact us via GitHub Issues.

Core Concepts

Protocol's SDK is organized around four ideas:

1. Cosmic Identity — a zero-PII profile keyed only on space-time birth coordinates. No name, no email leaks into the metaphysics engines. See @protocol/identity for the server-side counterpart.
2. Karma Wallet — every API call costs Karma Coins. A base cost of 5 + 2 per extra module ensures complex requests (e.g. a 9-engine synastry) are priced fairly. Balances, top-ups, and refunds are exposed via the Protocol Commerce API.
3. Engines — each of the 40+ calculation engines lives at its own namespace on the client (client.vedic, client.bazi, etc.). Engines are pure, deterministic, and return bilingual (Thai + English) text fields alongside raw numeric output.
4. Oracle — a synthesis layer that combines multiple engines plus an AI narrator (Gemini / OpenAI / deterministic fallback) to produce human-readable readings. Exposed via client.oracle in v0.2+.

Engines

| Property | Engine | Status | Key methods | |---|---|---|---| | client.oracle | Multi-engine oracle (career, wealth, vitality, genesis, armory, akashic, amrit_tatva) + AI narration | ✅ Live | read, stream | | client.fengShui | Chinese Feng Shui | ✅ Live | baZhai, flyingStar, scoreProperty | | client.tasyir | Islamic primary directions | ✅ Live | timeline, events, nextEvent | | client.vedic | Vedic astrology (sidereal) | ✅ Live | calculateChart, calculateDasha, calculateNakshatra, getTransits, getYogas, getAshtakavarga, getVargas | | client.bazi | Chinese Bazi (Four Pillars) | ✅ Live | calculateChart, getAnalysis, calculateLuck | | client.acg | Astro-cartography | ✅ Live | calculatePlanetaryLines, getLocationVerdict | | client.daLiuRen | Chinese horary (Da Liu Ren) | ✅ Live | ask | | client.taiYi | Macro cycle forecaster (Tai Yi) | ✅ Live | forecast | | client.tarot | Tarot draw (provably-fair seeded) | ✅ Live | draw | | client.mahakala | Mahakala Vedic suite (30 engines) | ✅ Live | calculate, intelligence, love, forge | | client.muhurta | Auspicious-time selection | ✅ Live | analyze | | client.panchaPakshi | Pancha Pakshi (Tamil bird astrology) | ✅ Live | daily | | client.ziwei | Zi Wei Dou Shu 紫微斗數 | ✅ Live | calculateChart | | client.mawalid | Islamic nativity | ✅ Live | calculateNativity, getMelothesia, getSolarReturn | | client.western | Western tropical astrology | ✅ Live | calculateNatal, calculateTransits | | client.horary | Islamic horary (qiranat) | ✅ Live | ask | | client.mundane | Mundane astrology (BYO-LLM data feed) | ✅ Live | ariesIngress, dangerZones, weekly | | client.rosetta | Cross-cultural fusion (Vedic × Islamic) | ✅ Live | dualDestiny | | client.financial | Financial astrology (BYO-LLM data feed) | ✅ Live | marketSignals, retrogrades | | client.sahl | Sahl ibn Bishr horary QA protocol (BYO-LLM) | ✅ Live | protocol | | client.picatrix | Picatrix Qadar Multiverse simulation (BYO-LLM) | ✅ Live | simulate | | client.mashaallah | Masha'allah Baghdad Matrix elections (BYO-LLM) | ✅ Live | baghdadMatrix | | client.qiMen | Qi Men Dun Jia (execution = BYO-LLM) | ✅ Live | calculateChart, warcraft, calculateExecution | | client.synastry | Multi-system compatibility (relationship = BYO-LLM) | ✅ Live | calculateVedicCompatibility, calculate3D, calculateRelationship | | client.career | Career oracle (also via oracle.read({ engine: 'career' })) | ⏳ Coming | calculateOracle | | client.karma | Karma wallet / billing | ⏳ Coming | getBalance, charge, getTransactions |

⏳ Coming namespaces/methods are fully typed but throw NotImplementedError until their /api/v1/* endpoint ships. Check ProtocolClient.LIVE_NAMESPACES at runtime.

Usage Examples

Vedic birth chart + Vimshottari dasha

const chart = await client.vedic.calculateChart({
  birth_date: '1990-05-15',
  birth_time: '14:30',
  birth_lat: 13.7563,
  birth_lng: 100.5018,
});

const dasha = await client.vedic.calculateDasha({
  birth_date: '1990-05-15',
  birth_time: '14:30',
  birth_lat: 13.7563,
  birth_lng: 100.5018,
});

console.log(`Ascendant: ${chart.ascendant}`);
console.log(`Current Maha Dasha: ${dasha.current_maha_dasha.planet}`);

Bazi Four Pillars with day master

const pillars = await client.bazi.calculateChart({
  birth_date: '1990-05-15',
  birth_time: '14:30',
  timezone: 'Asia/Bangkok',
});

console.log(`Day Master: ${pillars.day_master} (${pillars.day_master_element})`);
pillars.pillars.forEach((p) => console.log(`${p.label}: ${p.stem}${p.branch}`));

Qi Men Dun Jia chart for "now"

const qm = await client.qiMen.calculateChart({
  target_time: new Date().toISOString(),
  latitude: 13.7563,
  longitude: 100.5018,
});

console.log(`Ju: ${qm.ju}, Duty Officer: ${qm.duty_officer}`);

Da Liu Ren horary question

const reading = await client.daLiuRen.ask({
  question_time: new Date(),
  question_category: 'business',
  question_text: 'Should I sign the M&A deal this quarter?',
});

console.log(`Verdict: ${reading.verdict}`);
console.log(`Confidence: ${reading.confidence_score}%`);

Tai Yi macro forecast

const forecast = await client.taiYi.forecast({
  reference_year: 2026,
  scope: 'economy',
  cycle_length: 72,
});

forecast.events.forEach((e) => console.log(`${e.year}: ${e.summary_english}`));

Configuration

const client = new ProtocolClient({
  apiKey: 'pk_live_...',
  baseUrl: 'https://api.protocol.top', // default
  timeoutMs: 30_000,                    // default — 30s per request
  maxRetries: 3,                        // default — retry 5xx with backoff
  fetch: customFetch,                   // optional — inject your own fetch
});

Errors

Every SDK error extends ProtocolError. Branch with instanceof:

import {
  ProtocolClient,
  AuthError,
  RateLimitError,
  ValidationError,
  EngineError,
  NetworkError,
  TimeoutError,
} from '@protocol-top/sdk';

try {
  await client.vedic.calculateChart(input);
} catch (e) {
  if (e instanceof AuthError) {
    // bad or revoked key
  } else if (e instanceof RateLimitError) {
    console.log(`Retry after ${e.retryAfterSeconds}s`);
  } else if (e instanceof ValidationError) {
    console.log('Bad input:', e.fieldErrors);
  } else if (e instanceof EngineError) {
    console.log(`Engine ${e.engine} failed:`, e.message);
  } else if (e instanceof TimeoutError) {
    // bumped past timeoutMs
  } else if (e instanceof NetworkError) {
    // DNS / offline / TLS
  }
}

Auth

API keys are issued by the Protocol team (self-serve developer portal coming soon). All keys use the pk_ prefix. The SDK sends them via the X-Protocol-API-Key header automatically.

Never ship a live API key to the browser. Call the SDK from a backend / edge function, or use a scoped pk_public_* key with per-endpoint restrictions.

Retries & Timeouts

• 5xx responses (502, 503, 504) retry up to maxRetries with exponential backoff (100ms × 2^attempt).
• Network errors and AbortError also retry.
• 4xx responses (400, 401, 429, etc.) fail fast — no retry.
• Requests abort after timeoutMs via AbortController and throw TimeoutError.

TypeScript

The SDK ships full .d.ts declarations and declaration maps. Every engine method has strict input/output types — no any.

import type { VedicChartOutput, DaLiuRenAskOutput, BaziChartOutput } from '@protocol-top/sdk';

Documentation

• Quickstart: docs/sdk-quickstart.md
• Full API reference: docs/sdk-reference.md
• Runnable examples: src/examples/ — one script per engine
• Docs site + interactive explorer: https://sdk.protocol.top
• OpenAPI 3.1 spec: https://api.protocol.top/api/v1/openapi.json

Run any example with tsx:

PROTOCOL_API_KEY=pk_test_... npx tsx src/examples/basic-vedic-chart.ts

Contributing

This SDK lives inside the Protocol monorepo. To contribute:

1. Clone the monorepo and run pnpm install at the root.
2. Edit files under packages/sdk/src/.
3. Run pnpm --filter @protocol-top/sdk test and pnpm --filter @protocol-top/sdk build.
4. Add a changeset: pnpm changeset and describe the bump (patch / minor / major).
5. Open a PR against main.

Issues and feature requests: github.com/Rigky/Protocol/issues.

Changelog

See CHANGELOG.md. Versions follow semver and are tracked via Changesets.

License

MIT © 2026 Protocol (mongkornjin / Rigky). See LICENSE.