SDK

/**
 * ZaruviaClient — cliente del Zaruvia Open Numerology API.
 *
 * Licencia: MIT (código), CC-BY 4.0 (datos).
 * Documentación: https://zaruvia.com/docs
 */

export interface ArcanaPosition {
  arcana: number;
  name: string;
  keyword: string;
  emoji: string;
}

export interface Matrix {
  personal: ArcanaPosition; social: ArcanaPosition;
  soul: ArcanaPosition;     body: ArcanaPosition;
  spirit: ArcanaPosition;   center: ArcanaPosition;
  talents: ArcanaPosition;  karma: ArcanaPosition;
  money: ArcanaPosition;    relationships: ArcanaPosition;
  destiny: ArcanaPosition;  purpose: ArcanaPosition;
}

export interface MatrixResponse {
  input: { day: number; month: number; year: number };
  matrix: Matrix;
  source_url: string;
  details_url: string;
  license: string;
  attribution: string;
  attribution_html: string;
  api_version: string;
}

export type LifePathNumber = 1|2|3|4|5|6|7|8|9|11|22|33;

export class ZaruviaError extends Error {
  constructor(public status: number, public body: unknown) {
    super(`Zaruvia API HTTP ${status}`);
    this.name = "ZaruviaError";
  }
}

export class ZaruviaClient {
  private baseUrl: string;
  private timeoutMs: number;

  constructor(opts: { baseUrl?: string; timeoutMs?: number } = {}) {
    this.baseUrl = (opts.baseUrl ?? "https://zaruvia.com/api/public").replace(/\/$/, "");
    this.timeoutMs = opts.timeoutMs ?? 10_000;
  }

  async getMatrix(day: number, month: number, year: number): Promise<MatrixResponse> {
    return this.request<MatrixResponse>(`/matrix/${day}/${month}/${year}`);
  }

  async getLifePath(n: LifePathNumber | number): Promise<unknown> {
    return this.request(`/life-path/${n}`);
  }

  async listLifePaths(): Promise<unknown[]> {
    return this.request(`/life-path`);
  }

  private async request<T>(path: string): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      headers: { Accept: "application/json" },
      signal: AbortSignal.timeout(this.timeoutMs),
    });
    if (!res.ok) {
      const body = await res.json().catch(() => null);
      throw new ZaruviaError(res.status, body);
    }
    return res.json();
  }
}

import { ZaruviaClient } from "./zaruvia-client";

const client = new ZaruviaClient();

// Matriz del destino
const matrix = await client.getMatrix(15, 3, 1990);
console.log(matrix.matrix.center.name); // "La Rueda de la Fortuna"
console.log(matrix.matrix.money.emoji); // "⚡"

// Número del camino de vida
const lp = await client.getLifePath(7);
console.log(lp);

// Lista de todos los números
const all = await client.listLifePaths();
console.log(all.length); // 12

"""
ZaruviaClient — cliente del Zaruvia Open Numerology API.

Licencia: MIT (código), CC-BY 4.0 (datos).
Documentación: https://zaruvia.com/docs
"""
import json
import urllib.error
import urllib.request
from typing import Any, Dict, List


class ZaruviaError(Exception):
    def __init__(self, message: str, status: int, body: Any):
        super().__init__(message)
        self.status = status
        self.body = body


class ZaruviaClient:
    def __init__(
        self,
        base_url: str = "https://zaruvia.com/api/public",
        timeout: float = 10.0,
        user_agent: str = "zaruvia-python/1.0",
    ) -> None:
        self.base_url = base_url.rstrip("/")
        self.timeout = timeout
        self.user_agent = user_agent

    def get_matrix(self, day: int, month: int, year: int) -> Dict[str, Any]:
        return self._request(f"/matrix/{int(day)}/{int(month)}/{int(year)}")

    def list_life_paths(self) -> List[Dict[str, Any]]:
        return self._request("/life-path")

    def get_life_path(self, number: int) -> Dict[str, Any]:
        return self._request(f"/life-path/{int(number)}")

    def _request(self, path: str) -> Any:
        req = urllib.request.Request(
            f"{self.base_url}{path}",
            headers={"Accept": "application/json", "User-Agent": self.user_agent},
            method="GET",
        )
        try:
            with urllib.request.urlopen(req, timeout=self.timeout) as r:
                return json.loads(r.read().decode("utf-8"))
        except urllib.error.HTTPError as e:
            try:
                body = json.loads(e.read().decode("utf-8"))
            except Exception:
                body = None
            raise ZaruviaError(f"Zaruvia API HTTP {e.code}", e.code, body) from None
        except urllib.error.URLError as e:
            raise ZaruviaError(f"Network error: {e.reason}", 0, None) from None


# Uso:
#   from zaruvia_client import ZaruviaClient
#   client = ZaruviaClient()
#   matrix = client.get_matrix(day=15, month=3, year=1990)
#   print(matrix["matrix"]["center"]["name"])  # "La Rueda de la Fortuna"

from zaruvia_client import ZaruviaClient

client = ZaruviaClient()

# Matriz del destino
matrix = client.get_matrix(day=15, month=3, year=1990)
print(matrix["matrix"]["center"]["name"])  # "La Rueda de la Fortuna"
print(matrix["matrix"]["money"]["emoji"])  # "⚡"

# Número del camino de vida
lp = client.get_life_path(7)
print(lp["archetype"])  # "El Sabio"

curl https://zaruvia.com/api/public/matrix/15/3/1990