@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

• 10 engines on day one — Vedic, Bazi, Qi Men, Synastry, ACG, Pancha Pakshi, Muhurta, Career Oracle, Da Liu Ren, Tai Yi.
• 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_...
});

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

console.log(chart.ascendant, chart.moon_nakshatra);

Grab an API key at partner.protocol.app (public preview opens with v0.1). Until the partner portal is live, contact the team via GitHub Issues for a test key.

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 (v0.1)

| Property | Engine | Key methods | |---|---|---| | client.vedic | Vedic astrology (sidereal) | calculateChart, calculateDasha, calculateNakshatra | | client.bazi | Chinese Bazi (Four Pillars) | calculateChart, calculateLuck | | client.qiMen | Qi Men Dun Jia | calculateChart, calculateExecution | | client.synastry | 3D compatibility | calculate3D, calculateRelationship | | client.acg | Astro-cartography | calculatePlanetaryLines, getLocationVerdict | | client.panchaPakshi | Pancha Pakshi (Tamil bird astrology) | calculate, getDailyBird | | client.muhurta | Auspicious-time selection | findAuspiciousTime, analyzeDate | | client.career | Career oracle | calculateOracle | | client.daLiuRen | Chinese horary (Da Liu Ren) | ask | | client.taiYi | Macro cycle forecaster (Tai Yi) | forecast |

More engines (Sukuyodo, Feng Shui Flying Star, Mahakala Vedic, Al-Tanjim Islamic, Al-Biruni Rosetta) roll out through v0.2 – v1.0.

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.app', // 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 obtained from partner.protocol.app. 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 (coming soon): https://docs.protocol.dev

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.