mysticapi 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Types for the MysticAPI HTTP contract.
+ *
+ * Mirrors https://mysticapi.com/.well-known/openapi.json (OpenAPI 3.1). The live
+ * spec is the source of truth; these types track it and are kept deliberately
+ * permissive (index signatures on open-ended objects) so the client never breaks
+ * when the engine adds fields.
+ */
+/** A birth instant expressed in UTC. Convert local time + timezone to UTC first. */
+interface BirthInput {
+    /** Full year, 1–2200. */
+    year: number;
+    /** Month, 1–12. */
+    month: number;
+    /** Day of month, 1–31. */
+    day: number;
+    /** Hour, 0–23 (UTC). */
+    hour: number;
+    /** Minute, 0–59 (UTC). */
+    minute: number;
+    /** Second, 0–59 (UTC). Defaults to 0. */
+    second?: number;
+}
+/** A zodiac placement: sign name plus degree within the sign. */
+interface ZodiacPlacement {
+    sign: string;
+    degree: number;
+}
+/** An Energy Blueprint gate/line placement on the 64-gate wheel. */
+interface GatePlacement {
+    /** Gate number, 1–64. */
+    gate: number;
+    /** Line number, 1–6. */
+    line: number;
+}
+/** Geocentric position of a single celestial body. */
+interface BodyPosition {
+    label?: string;
+    /** Ecliptic longitude in degrees, 0 ≤ longitude < 360. */
+    longitude?: number;
+    zodiac?: ZodiacPlacement;
+    gate?: GatePlacement;
+    retrograde?: boolean;
+    [key: string]: unknown;
+}
+/** A forthcoming sky event (retrograde station or new/full moon). May be null. */
+interface SkyEvent {
+    date?: string;
+    type?: 'retrograde_start' | 'retrograde_end' | 'new_moon' | 'full_moon';
+    planet?: string;
+    title?: string;
+    /** Practical prep guidance for the event. */
+    prep?: string;
+    daysAway?: number;
+    [key: string]: unknown;
+}
+/** Moon phase snapshot for {@link SkyToday}. */
+interface MoonState {
+    phaseName?: string;
+    /** Illuminated fraction, 0–1. */
+    illumination?: number;
+    elongationDeg?: number;
+    nextNewMoon?: SkyEvent | null;
+    nextFullMoon?: SkyEvent | null;
+    [key: string]: unknown;
+}
+/** Active + upcoming retrograde state for {@link SkyToday}. */
+interface RetrogradeState {
+    active?: Array<{
+        planet?: string;
+        label?: string;
+    }>;
+    upcomingStations?: SkyEvent[];
+    [key: string]: unknown;
+}
+/** Response of {@link MysticApi.skyToday}: the universal (non-personal) sky. */
+interface SkyToday {
+    date: string;
+    generatedAt?: string;
+    moon: MoonState;
+    retrogrades: RetrogradeState;
+    /** Positions keyed by body id (e.g. `sun`, `moon`, `mercury`, ...). */
+    positions: Record<string, BodyPosition>;
+    upcoming: SkyEvent[];
+    attribution?: string;
+    [key: string]: unknown;
+}
+/**
+ * The computed Energy Blueprint chart. The engine returns a rich, evolving
+ * object (birth with jdn, the 88°-solar-arc design moment, per-body conscious +
+ * unconscious gate maps, and the derived chart: type, authority, strategy,
+ * profile, definition, incarnation cross, channels, centers). Known top-level
+ * fields are typed; the index signature keeps forward-compatibility.
+ */
+interface BodygraphChart {
+    birth?: Record<string, unknown>;
+    design?: Record<string, unknown>;
+    personalityGates?: Record<string, GatePlacement>;
+    designGates?: Record<string, GatePlacement>;
+    chart?: {
+        type?: string;
+        authority?: string;
+        strategy?: string;
+        profile?: string;
+        definition?: string;
+        cross?: string;
+        channels?: unknown;
+        centers?: unknown;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/** Response of {@link MysticApi.bodygraph}: chart JSON plus a rendered SVG. */
+interface BodygraphResult {
+    chart: BodygraphChart;
+    /** Body-graph SVG markup (a complete `<svg>…</svg>` string). */
+    svg: string;
+    attribution?: string;
+}
+/** Response of {@link MysticApi.getFreeKey}. The key itself arrives by email. */
+interface FreeKeyResponse {
+    message?: string;
+    docs?: string;
+    [key: string]: unknown;
+}
+/** Options for {@link MysticApi.skyPersonal}. */
+interface SkyPersonalOptions {
+    /** When `false`, request a static (non-animated) SVG. Defaults to the API default. */
+    animate?: boolean;
+}
+/** The JSON error envelope returned by MysticAPI on non-2xx responses. */
+interface ApiErrorBody {
+    error?: string;
+    message?: string;
+    docs?: string;
+    [key: string]: unknown;
+}
+/** Constructor options for {@link MysticApi}. */
+interface MysticApiOptions {
+    /** Your API key, e.g. `mk_live_...`. Get a free one via {@link MysticApi.getFreeKey}. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to `https://mysticapi.com`. */
+    baseUrl?: string;
+    /** Inject a fetch implementation. Defaults to the runtime's global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Options for the keyless helpers ({@link MysticApi.getFreeKey}). */
+interface KeylessOptions {
+    /** Override the API base URL. Defaults to `https://mysticapi.com`. */
+    baseUrl?: string;
+    /** Inject a fetch implementation. Defaults to the runtime's global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+
+/** Default MysticAPI base URL. */
+declare const DEFAULT_BASE_URL = "https://mysticapi.com";
+/**
+ * Isomorphic MysticAPI client. Zero dependencies — uses the runtime's global
+ * `fetch`, so it runs unchanged on Node 18+, Bun, browsers, and Cloudflare
+ * Workers.
+ *
+ * @example
+ * ```ts
+ * const mystic = new MysticApi({ apiKey: 'mk_live_...' });
+ * const sky = await mystic.skyToday();
+ * console.log(sky.moon.phaseName);
+ * ```
+ */
+declare class MysticApi {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: MysticApiOptions);
+    private authHeaders;
+    /**
+     * Today's universal sky: active retrogrades, moon phase + illumination,
+     * geocentric positions for 13 bodies (zodiac + Energy Blueprint gate/line),
+     * and a 30-day forward scan of retrograde stations and new/full moons.
+     *
+     * `GET /v1/sky/today` — metered (1 call).
+     */
+    skyToday(): Promise<SkyToday>;
+    /**
+     * Compute an Energy Blueprint (Human Design) chart from a birth instant and
+     * return the full chart JSON plus a rendered body-graph SVG. Location is not
+     * required — the body-graph is location-independent.
+     *
+     * `POST /v1/bodygraph` — metered (1 call).
+     */
+    bodygraph(birth: BirthInput): Promise<BodygraphResult>;
+    /**
+     * Render a personal-sky chart from a birth instant. Returns the SVG markup as
+     * a string (`image/svg+xml`). Deterministic: the same birth always yields the
+     * same sky.
+     *
+     * `POST /v1/sky/personal` — metered (1 call).
+     */
+    skyPersonal(birth: BirthInput, options?: SkyPersonalOptions): Promise<string>;
+    /**
+     * Render a personal-sky chart via `GET /v1/sky/personal` (birth as query
+     * params). Equivalent to {@link MysticApi.skyPersonal}; useful when you want a
+     * shareable URL shape. Returns the SVG markup as a string.
+     */
+    skyPersonalGet(birth: BirthInput, options?: SkyPersonalOptions): Promise<string>;
+    /**
+     * Request a free, no-card API key. The key is emailed (the API responds `202`
+     * with a confirmation message — the secret itself is never returned in the
+     * body). One active key per email; 50 calls/month.
+     *
+     * `POST /v1/keys/free` — no auth required.
+     */
+    static getFreeKey(email: string, options?: KeylessOptions): Promise<FreeKeyResponse>;
+}
+/**
+ * Standalone helper to request a free, no-card API key (emailed to `email`).
+ * Same as {@link MysticApi.getFreeKey}; exported for keyless call sites.
+ *
+ * `POST /v1/keys/free` — no auth required.
+ */
+declare function getFreeKey(email: string, options?: KeylessOptions): Promise<FreeKeyResponse>;
+
+/** Fields used to construct a {@link MysticApiError}. */
+interface MysticApiErrorInit {
+    status: number;
+    code: string;
+    message: string;
+    docs?: string;
+    retryAfter?: number;
+    body?: ApiErrorBody | string;
+}
+/**
+ * Error thrown for any non-2xx MysticAPI response (and for network failures,
+ * which surface as `status: 0`, `code: 'network_error'`).
+ *
+ * The parsed JSON error envelope (`{ error, message, docs }`) is exposed on
+ * {@link MysticApiError.body}, the machine-readable code on
+ * {@link MysticApiError.code}, and — for `429` — the `Retry-After` value in
+ * seconds on {@link MysticApiError.retryAfter}.
+ */
+declare class MysticApiError extends Error {
+    /** HTTP status code. `0` for a network/transport failure. */
+    readonly status: number;
+    /** Machine-readable error code (from the body's `error` field, or a synthetic one). */
+    readonly code: string;
+    /** Documentation URL surfaced by the API, when present. */
+    readonly docs?: string;
+    /** For `429`: the `Retry-After` value in seconds, when the header is present. */
+    readonly retryAfter?: number;
+    /** The parsed JSON error body, or raw text when the body was not JSON. */
+    readonly body?: ApiErrorBody | string;
+    constructor(init: MysticApiErrorInit);
+    /** True for a `401` (missing/invalid API key). */
+    get isUnauthorized(): boolean;
+    /** True for a `402` (payment required — no key and no valid x402 payment). */
+    get isPaymentRequired(): boolean;
+    /** True for a `429` (monthly allotment reached or rate limited). */
+    get isRateLimited(): boolean;
+    /**
+     * Build a {@link MysticApiError} from a failed {@link Response}, parsing the
+     * JSON error envelope and the `Retry-After` header.
+     */
+    static fromResponse(res: Response, path: string): Promise<MysticApiError>;
+}
+
+export { type ApiErrorBody, type BirthInput, type BodyPosition, type BodygraphChart, type BodygraphResult, DEFAULT_BASE_URL, type FreeKeyResponse, type GatePlacement, type KeylessOptions, type MoonState, MysticApi, MysticApiError, type MysticApiErrorInit, type MysticApiOptions, type RetrogradeState, type SkyEvent, type SkyPersonalOptions, type SkyToday, type ZodiacPlacement, getFreeKey };

package/dist/index.js

@@ -0,0 +1,270 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  MysticApi: () => MysticApi,
+  MysticApiError: () => MysticApiError,
+  getFreeKey: () => getFreeKey
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var MysticApiError = class _MysticApiError extends Error {
+  /** HTTP status code. `0` for a network/transport failure. */
+  status;
+  /** Machine-readable error code (from the body's `error` field, or a synthetic one). */
+  code;
+  /** Documentation URL surfaced by the API, when present. */
+  docs;
+  /** For `429`: the `Retry-After` value in seconds, when the header is present. */
+  retryAfter;
+  /** The parsed JSON error body, or raw text when the body was not JSON. */
+  body;
+  constructor(init) {
+    super(init.message);
+    this.name = "MysticApiError";
+    this.status = init.status;
+    this.code = init.code;
+    this.docs = init.docs;
+    this.retryAfter = init.retryAfter;
+    this.body = init.body;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /** True for a `401` (missing/invalid API key). */
+  get isUnauthorized() {
+    return this.status === 401;
+  }
+  /** True for a `402` (payment required — no key and no valid x402 payment). */
+  get isPaymentRequired() {
+    return this.status === 402;
+  }
+  /** True for a `429` (monthly allotment reached or rate limited). */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+  /**
+   * Build a {@link MysticApiError} from a failed {@link Response}, parsing the
+   * JSON error envelope and the `Retry-After` header.
+   */
+  static async fromResponse(res, path) {
+    const raw = await res.text().catch(() => "");
+    let body;
+    if (raw) {
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        body = raw;
+      }
+    }
+    const envelope = typeof body === "object" && body !== null ? body : void 0;
+    const code = typeof envelope?.error === "string" && envelope.error ? envelope.error : `http_${res.status}`;
+    const message = typeof envelope?.message === "string" && envelope.message ? envelope.message : `MysticAPI request to ${path} failed with status ${res.status}`;
+    const docs = typeof envelope?.docs === "string" ? envelope.docs : void 0;
+    let retryAfter;
+    const retryHeader = res.headers.get("retry-after");
+    if (retryHeader) {
+      const seconds = Number(retryHeader);
+      if (Number.isFinite(seconds)) {
+        retryAfter = seconds;
+      } else {
+        const when = Date.parse(retryHeader);
+        if (Number.isFinite(when)) {
+          retryAfter = Math.max(0, Math.round((when - Date.now()) / 1e3));
+        }
+      }
+    }
+    return new _MysticApiError({ status: res.status, code, message, docs, retryAfter, body });
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://mysticapi.com";
+function resolveFetch(injected) {
+  const impl = injected ?? globalThis.fetch;
+  if (typeof impl !== "function") {
+    throw new MysticApiError({
+      status: 0,
+      code: "no_fetch",
+      message: "No global `fetch` found. Pass a `fetch` implementation in the options, or run on Node 18+, Bun, a browser, or Cloudflare Workers."
+    });
+  }
+  return impl;
+}
+function normalizeBaseUrl(baseUrl) {
+  return (baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+function birthQuery(birth, options) {
+  const params = new URLSearchParams({
+    year: String(birth.year),
+    month: String(birth.month),
+    day: String(birth.day),
+    hour: String(birth.hour),
+    minute: String(birth.minute)
+  });
+  if (birth.second !== void 0) params.set("second", String(birth.second));
+  if (options?.animate !== void 0) params.set("animate", options.animate ? "true" : "false");
+  return params.toString();
+}
+async function requestRaw(fetchImpl, url, init, path) {
+  let res;
+  try {
+    res = await fetchImpl(url, init);
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : "network error";
+    throw new MysticApiError({
+      status: 0,
+      code: "network_error",
+      message: `MysticAPI request to ${path} failed: ${detail}`
+    });
+  }
+  if (!res.ok) {
+    throw await MysticApiError.fromResponse(res, path);
+  }
+  return res;
+}
+var MysticApi = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  constructor(options) {
+    if (!options || !options.apiKey) {
+      throw new MysticApiError({
+        status: 0,
+        code: "missing_api_key",
+        message: "A MysticAPI `apiKey` is required. Get a free one with MysticApi.getFreeKey(email)."
+      });
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = normalizeBaseUrl(options.baseUrl);
+    this.fetchImpl = resolveFetch(options.fetch);
+  }
+  authHeaders(extra) {
+    const headers = new Headers(extra);
+    headers.set("Authorization", `Bearer ${this.apiKey}`);
+    return headers;
+  }
+  /**
+   * Today's universal sky: active retrogrades, moon phase + illumination,
+   * geocentric positions for 13 bodies (zodiac + Energy Blueprint gate/line),
+   * and a 30-day forward scan of retrograde stations and new/full moons.
+   *
+   * `GET /v1/sky/today` — metered (1 call).
+   */
+  async skyToday() {
+    const res = await requestRaw(
+      this.fetchImpl,
+      `${this.baseUrl}/v1/sky/today`,
+      { method: "GET", headers: this.authHeaders({ Accept: "application/json" }) },
+      "/v1/sky/today"
+    );
+    return await res.json();
+  }
+  /**
+   * Compute an Energy Blueprint (Human Design) chart from a birth instant and
+   * return the full chart JSON plus a rendered body-graph SVG. Location is not
+   * required — the body-graph is location-independent.
+   *
+   * `POST /v1/bodygraph` — metered (1 call).
+   */
+  async bodygraph(birth) {
+    const res = await requestRaw(
+      this.fetchImpl,
+      `${this.baseUrl}/v1/bodygraph`,
+      {
+        method: "POST",
+        headers: this.authHeaders({ "Content-Type": "application/json", Accept: "application/json" }),
+        body: JSON.stringify(birth)
+      },
+      "/v1/bodygraph"
+    );
+    return await res.json();
+  }
+  /**
+   * Render a personal-sky chart from a birth instant. Returns the SVG markup as
+   * a string (`image/svg+xml`). Deterministic: the same birth always yields the
+   * same sky.
+   *
+   * `POST /v1/sky/personal` — metered (1 call).
+   */
+  async skyPersonal(birth, options) {
+    const body = {
+      year: birth.year,
+      month: birth.month,
+      day: birth.day,
+      hour: birth.hour,
+      minute: birth.minute
+    };
+    if (birth.second !== void 0) body.second = birth.second;
+    const query = options?.animate !== void 0 ? `?animate=${options.animate ? "true" : "false"}` : "";
+    const res = await requestRaw(
+      this.fetchImpl,
+      `${this.baseUrl}/v1/sky/personal${query}`,
+      {
+        method: "POST",
+        headers: this.authHeaders({ "Content-Type": "application/json", Accept: "image/svg+xml" }),
+        body: JSON.stringify(body)
+      },
+      "/v1/sky/personal"
+    );
+    return await res.text();
+  }
+  /**
+   * Render a personal-sky chart via `GET /v1/sky/personal` (birth as query
+   * params). Equivalent to {@link MysticApi.skyPersonal}; useful when you want a
+   * shareable URL shape. Returns the SVG markup as a string.
+   */
+  async skyPersonalGet(birth, options) {
+    const res = await requestRaw(
+      this.fetchImpl,
+      `${this.baseUrl}/v1/sky/personal?${birthQuery(birth, options)}`,
+      { method: "GET", headers: this.authHeaders({ Accept: "image/svg+xml" }) },
+      "/v1/sky/personal"
+    );
+    return await res.text();
+  }
+  /**
+   * Request a free, no-card API key. The key is emailed (the API responds `202`
+   * with a confirmation message — the secret itself is never returned in the
+   * body). One active key per email; 50 calls/month.
+   *
+   * `POST /v1/keys/free` — no auth required.
+   */
+  static async getFreeKey(email, options) {
+    return getFreeKey(email, options);
+  }
+};
+async function getFreeKey(email, options) {
+  const fetchImpl = resolveFetch(options?.fetch);
+  const baseUrl = normalizeBaseUrl(options?.baseUrl);
+  const res = await requestRaw(
+    fetchImpl,
+    `${baseUrl}/v1/keys/free`,
+    {
+      method: "POST",
+      headers: new Headers({ "Content-Type": "application/json", Accept: "application/json" }),
+      body: JSON.stringify({ email })
+    },
+    "/v1/keys/free"
+  );
+  return await res.json();
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/client.ts"],"sourcesContent":["/**\n * `mysticapi` — the official isomorphic TypeScript/JavaScript client for\n * MysticAPI (https://mysticapi.com): deterministic Human Design–compatible\n * bodygraphs, personal sky charts, and ephemeris.\n *\n * Zero dependencies. Runs on Node 18+, Bun, browsers, and Cloudflare Workers.\n *\n * @packageDocumentation\n */\nexport { MysticApi, getFreeKey, DEFAULT_BASE_URL } from './client.js';\nexport { MysticApiError } from './errors.js';\nexport type { MysticApiErrorInit } from './errors.js';\nexport type {\n  ApiErrorBody,\n  BirthInput,\n  BodyPosition,\n  BodygraphChart,\n  BodygraphResult,\n  FreeKeyResponse,\n  GatePlacement,\n  KeylessOptions,\n  MoonState,\n  MysticApiOptions,\n  RetrogradeState,\n  SkyEvent,\n  SkyPersonalOptions,\n  SkyToday,\n  ZodiacPlacement,\n} from './types.js';\n","import type { ApiErrorBody } from './types.js';\n\n/** Fields used to construct a {@link MysticApiError}. */\nexport interface MysticApiErrorInit {\n  status: number;\n  code: string;\n  message: string;\n  docs?: string;\n  retryAfter?: number;\n  body?: ApiErrorBody | string;\n}\n\n/**\n * Error thrown for any non-2xx MysticAPI response (and for network failures,\n * which surface as `status: 0`, `code: 'network_error'`).\n *\n * The parsed JSON error envelope (`{ error, message, docs }`) is exposed on\n * {@link MysticApiError.body}, the machine-readable code on\n * {@link MysticApiError.code}, and — for `429` — the `Retry-After` value in\n * seconds on {@link MysticApiError.retryAfter}.\n */\nexport class MysticApiError extends Error {\n  /** HTTP status code. `0` for a network/transport failure. */\n  readonly status: number;\n  /** Machine-readable error code (from the body's `error` field, or a synthetic one). */\n  readonly code: string;\n  /** Documentation URL surfaced by the API, when present. */\n  readonly docs?: string;\n  /** For `429`: the `Retry-After` value in seconds, when the header is present. */\n  readonly retryAfter?: number;\n  /** The parsed JSON error body, or raw text when the body was not JSON. */\n  readonly body?: ApiErrorBody | string;\n\n  constructor(init: MysticApiErrorInit) {\n    super(init.message);\n    this.name = 'MysticApiError';\n    this.status = init.status;\n    this.code = init.code;\n    this.docs = init.docs;\n    this.retryAfter = init.retryAfter;\n    this.body = init.body;\n    // Restore the prototype chain so `instanceof MysticApiError` holds after\n    // transpilation to older targets.\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  /** True for a `401` (missing/invalid API key). */\n  get isUnauthorized(): boolean {\n    return this.status === 401;\n  }\n\n  /** True for a `402` (payment required — no key and no valid x402 payment). */\n  get isPaymentRequired(): boolean {\n    return this.status === 402;\n  }\n\n  /** True for a `429` (monthly allotment reached or rate limited). */\n  get isRateLimited(): boolean {\n    return this.status === 429;\n  }\n\n  /**\n   * Build a {@link MysticApiError} from a failed {@link Response}, parsing the\n   * JSON error envelope and the `Retry-After` header.\n   */\n  static async fromResponse(res: Response, path: string): Promise<MysticApiError> {\n    const raw = await res.text().catch(() => '');\n    let body: ApiErrorBody | string | undefined;\n    if (raw) {\n      try {\n        body = JSON.parse(raw) as ApiErrorBody;\n      } catch {\n        body = raw;\n      }\n    }\n\n    const envelope = typeof body === 'object' && body !== null ? body : undefined;\n    const code =\n      typeof envelope?.error === 'string' && envelope.error ? envelope.error : `http_${res.status}`;\n    const message =\n      typeof envelope?.message === 'string' && envelope.message\n        ? envelope.message\n        : `MysticAPI request to ${path} failed with status ${res.status}`;\n    const docs = typeof envelope?.docs === 'string' ? envelope.docs : undefined;\n\n    let retryAfter: number | undefined;\n    const retryHeader = res.headers.get('retry-after');\n    if (retryHeader) {\n      const seconds = Number(retryHeader);\n      if (Number.isFinite(seconds)) {\n        retryAfter = seconds;\n      } else {\n        const when = Date.parse(retryHeader);\n        if (Number.isFinite(when)) {\n          retryAfter = Math.max(0, Math.round((when - Date.now()) / 1000));\n        }\n      }\n    }\n\n    return new MysticApiError({ status: res.status, code, message, docs, retryAfter, body });\n  }\n}\n","import { MysticApiError } from './errors.js';\nimport type {\n  BirthInput,\n  BodygraphResult,\n  FreeKeyResponse,\n  KeylessOptions,\n  MysticApiOptions,\n  SkyPersonalOptions,\n  SkyToday,\n} from './types.js';\n\n/** Default MysticAPI base URL. */\nexport const DEFAULT_BASE_URL = 'https://mysticapi.com';\n\nfunction resolveFetch(injected?: typeof globalThis.fetch): typeof globalThis.fetch {\n  const impl = injected ?? globalThis.fetch;\n  if (typeof impl !== 'function') {\n    throw new MysticApiError({\n      status: 0,\n      code: 'no_fetch',\n      message:\n        'No global `fetch` found. Pass a `fetch` implementation in the options, or run on Node 18+, Bun, a browser, or Cloudflare Workers.',\n    });\n  }\n  return impl;\n}\n\nfunction normalizeBaseUrl(baseUrl?: string): string {\n  return (baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, '');\n}\n\nfunction birthQuery(birth: BirthInput, options?: SkyPersonalOptions): string {\n  const params = new URLSearchParams({\n    year: String(birth.year),\n    month: String(birth.month),\n    day: String(birth.day),\n    hour: String(birth.hour),\n    minute: String(birth.minute),\n  });\n  if (birth.second !== undefined) params.set('second', String(birth.second));\n  if (options?.animate !== undefined) params.set('animate', options.animate ? 'true' : 'false');\n  return params.toString();\n}\n\nasync function requestRaw(\n  fetchImpl: typeof globalThis.fetch,\n  url: string,\n  init: RequestInit,\n  path: string,\n): Promise<Response> {\n  let res: Response;\n  try {\n    res = await fetchImpl(url, init);\n  } catch (cause) {\n    const detail = cause instanceof Error ? cause.message : 'network error';\n    throw new MysticApiError({\n      status: 0,\n      code: 'network_error',\n      message: `MysticAPI request to ${path} failed: ${detail}`,\n    });\n  }\n  if (!res.ok) {\n    throw await MysticApiError.fromResponse(res, path);\n  }\n  return res;\n}\n\n/**\n * Isomorphic MysticAPI client. Zero dependencies — uses the runtime's global\n * `fetch`, so it runs unchanged on Node 18+, Bun, browsers, and Cloudflare\n * Workers.\n *\n * @example\n * ```ts\n * const mystic = new MysticApi({ apiKey: 'mk_live_...' });\n * const sky = await mystic.skyToday();\n * console.log(sky.moon.phaseName);\n * ```\n */\nexport class MysticApi {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly fetchImpl: typeof globalThis.fetch;\n\n  constructor(options: MysticApiOptions) {\n    if (!options || !options.apiKey) {\n      throw new MysticApiError({\n        status: 0,\n        code: 'missing_api_key',\n        message: 'A MysticAPI `apiKey` is required. Get a free one with MysticApi.getFreeKey(email).',\n      });\n    }\n    this.apiKey = options.apiKey;\n    this.baseUrl = normalizeBaseUrl(options.baseUrl);\n    this.fetchImpl = resolveFetch(options.fetch);\n  }\n\n  private authHeaders(extra?: Record<string, string>): Headers {\n    const headers = new Headers(extra);\n    headers.set('Authorization', `Bearer ${this.apiKey}`);\n    return headers;\n  }\n\n  /**\n   * Today's universal sky: active retrogrades, moon phase + illumination,\n   * geocentric positions for 13 bodies (zodiac + Energy Blueprint gate/line),\n   * and a 30-day forward scan of retrograde stations and new/full moons.\n   *\n   * `GET /v1/sky/today` — metered (1 call).\n   */\n  async skyToday(): Promise<SkyToday> {\n    const res = await requestRaw(\n      this.fetchImpl,\n      `${this.baseUrl}/v1/sky/today`,\n      { method: 'GET', headers: this.authHeaders({ Accept: 'application/json' }) },\n      '/v1/sky/today',\n    );\n    return (await res.json()) as SkyToday;\n  }\n\n  /**\n   * Compute an Energy Blueprint (Human Design) chart from a birth instant and\n   * return the full chart JSON plus a rendered body-graph SVG. Location is not\n   * required — the body-graph is location-independent.\n   *\n   * `POST /v1/bodygraph` — metered (1 call).\n   */\n  async bodygraph(birth: BirthInput): Promise<BodygraphResult> {\n    const res = await requestRaw(\n      this.fetchImpl,\n      `${this.baseUrl}/v1/bodygraph`,\n      {\n        method: 'POST',\n        headers: this.authHeaders({ 'Content-Type': 'application/json', Accept: 'application/json' }),\n        body: JSON.stringify(birth),\n      },\n      '/v1/bodygraph',\n    );\n    return (await res.json()) as BodygraphResult;\n  }\n\n  /**\n   * Render a personal-sky chart from a birth instant. Returns the SVG markup as\n   * a string (`image/svg+xml`). Deterministic: the same birth always yields the\n   * same sky.\n   *\n   * `POST /v1/sky/personal` — metered (1 call).\n   */\n  async skyPersonal(birth: BirthInput, options?: SkyPersonalOptions): Promise<string> {\n    const body: Record<string, number> = {\n      year: birth.year,\n      month: birth.month,\n      day: birth.day,\n      hour: birth.hour,\n      minute: birth.minute,\n    };\n    if (birth.second !== undefined) body.second = birth.second;\n    const query = options?.animate !== undefined ? `?animate=${options.animate ? 'true' : 'false'}` : '';\n    const res = await requestRaw(\n      this.fetchImpl,\n      `${this.baseUrl}/v1/sky/personal${query}`,\n      {\n        method: 'POST',\n        headers: this.authHeaders({ 'Content-Type': 'application/json', Accept: 'image/svg+xml' }),\n        body: JSON.stringify(body),\n      },\n      '/v1/sky/personal',\n    );\n    return await res.text();\n  }\n\n  /**\n   * Render a personal-sky chart via `GET /v1/sky/personal` (birth as query\n   * params). Equivalent to {@link MysticApi.skyPersonal}; useful when you want a\n   * shareable URL shape. Returns the SVG markup as a string.\n   */\n  async skyPersonalGet(birth: BirthInput, options?: SkyPersonalOptions): Promise<string> {\n    const res = await requestRaw(\n      this.fetchImpl,\n      `${this.baseUrl}/v1/sky/personal?${birthQuery(birth, options)}`,\n      { method: 'GET', headers: this.authHeaders({ Accept: 'image/svg+xml' }) },\n      '/v1/sky/personal',\n    );\n    return await res.text();\n  }\n\n  /**\n   * Request a free, no-card API key. The key is emailed (the API responds `202`\n   * with a confirmation message — the secret itself is never returned in the\n   * body). One active key per email; 50 calls/month.\n   *\n   * `POST /v1/keys/free` — no auth required.\n   */\n  static async getFreeKey(email: string, options?: KeylessOptions): Promise<FreeKeyResponse> {\n    return getFreeKey(email, options);\n  }\n}\n\n/**\n * Standalone helper to request a free, no-card API key (emailed to `email`).\n * Same as {@link MysticApi.getFreeKey}; exported for keyless call sites.\n *\n * `POST /v1/keys/free` — no auth required.\n */\nexport async function getFreeKey(email: string, options?: KeylessOptions): Promise<FreeKeyResponse> {\n  const fetchImpl = resolveFetch(options?.fetch);\n  const baseUrl = normalizeBaseUrl(options?.baseUrl);\n  const res = await requestRaw(\n    fetchImpl,\n    `${baseUrl}/v1/keys/free`,\n    {\n      method: 'POST',\n      headers: new Headers({ 'Content-Type': 'application/json', Accept: 'application/json' }),\n      body: JSON.stringify({ email }),\n    },\n    '/v1/keys/free',\n  );\n  return (await res.json()) as FreeKeyResponse;\n}\n"],"mappings":"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","names":[]}