mysticapi 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release. Isomorphic, zero-dependency client for MysticAPI.
+- Methods: `skyToday()`, `bodygraph(birth)`, `skyPersonal(birth)`, `skyPersonalGet(birth)`, and the keyless `MysticApi.getFreeKey(email)` / `getFreeKey(email)` helper.
+- Typed `MysticApiError` surfacing HTTP status, machine-readable code, the JSON error body, the docs URL, and the `429` `Retry-After` (in seconds).
+- Dual ESM + CJS build with type declarations. Runs on Node 18+, Bun, browsers, and Cloudflare Workers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Latimer Woods Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# mysticapi
+
+Official isomorphic client for **[MysticAPI](https://mysticapi.com)** — a metered engine API for deterministic, Human Design–compatible **bodygraphs**, **personal sky charts**, and **ephemeris**. Same input always returns the same output (JPL-validated pure-JS ephemeris; no generative output).
+
+- **Zero dependencies.** Uses the runtime's global `fetch`.
+- **Runs everywhere:** Node 18+, Bun, browsers, and Cloudflare Workers.
+- **Fully typed**, including a typed error that surfaces the JSON error body, HTTP status, and the `429` `Retry-After`.
+
+```bash
+npm install mysticapi
+```
+
+## Get a key (30 seconds, no card)
+
+Free tier is 50 calls/month, no card. The key is emailed to you.
+
+```ts
+import { MysticApi } from 'mysticapi';
+
+await MysticApi.getFreeKey('you@example.com'); // → check your inbox for mk_live_...
+```
+
+Paid tiers (Maker $19 / Pro $49 / Scale $149 per month, flat — never credits) are self-serve Stripe links listed at <https://mysticapi.com/llms.txt>; your key is emailed within a minute of checkout.
+
+## Quick start
+
+```ts
+import { MysticApi } from 'mysticapi';
+
+const mystic = new MysticApi({ apiKey: process.env.MYSTIC_API_KEY! });
+// baseUrl defaults to https://mysticapi.com; pass { baseUrl } to override.
+```
+
+### 1. Today's sky — `skyToday()`
+
+`GET /v1/sky/today` — active retrogrades, moon phase, geocentric positions for 13 bodies (zodiac + Energy Blueprint gate/line), and a 30-day forward scan of stations and new/full moons.
+
+```ts
+const sky = await mystic.skyToday();
+
+console.log(sky.date);                 // "2026-07-07"
+console.log(sky.moon.phaseName);       // "Waxing Gibbous"
+console.log(sky.moon.illumination);    // 0.82
+console.log(sky.retrogrades.active);   // [{ planet: "mercury", label: "Mercury Retrograde" }]
+console.log(sky.positions.sun.zodiac); // { sign: "Cancer", degree: 15.2 }
+console.log(sky.positions.sun.gate);   // { gate: 4, line: 3 }
+```
+
+Response shape:
+
+```jsonc
+{
+  "date": "2026-07-07",
+  "moon": { "phaseName": "Waxing Gibbous", "illumination": 0.82, "nextFullMoon": { "date": "2026-07-10", "type": "full_moon", "daysAway": 3 } },
+  "retrogrades": { "active": [{ "planet": "mercury", "label": "Mercury Retrograde" }], "upcomingStations": [ /* SkyEvent[] */ ] },
+  "positions": { "sun": { "longitude": 105.2, "zodiac": { "sign": "Cancer", "degree": 15.2 }, "gate": { "gate": 4, "line": 3 }, "retrograde": false } /* …13 bodies */ },
+  "upcoming": [ /* SkyEvent[] — next 30 days */ ]
+}
+```
+
+### 2. Bodygraph — `bodygraph(birth)`
+
+`POST /v1/bodygraph` — a birth instant **in UTC** → the full Energy Blueprint (Human Design) chart JSON plus a rendered body-graph SVG. No latitude/longitude needed; the body-graph is location-independent.
+
+```ts
+const { chart, svg } = await mystic.bodygraph({
+  year: 1979, month: 8, day: 5, hour: 22, minute: 51, // UTC — convert local time first
+});
+
+console.log(chart.chart?.type);      // "Manifesting Generator"
+console.log(chart.chart?.authority); // "Sacral"
+console.log(chart.chart?.profile);   // "3/5"
+// `svg` is a complete <svg>…</svg> string — write it to a file or inline it.
+```
+
+Response shape:
+
+```jsonc
+{
+  "chart": {
+    "birth": { "year": 1979, "month": 8, "day": 5, "jdn": 2444091.45 },
+    "design": { /* the 88°-solar-arc design moment */ },
+    "personalityGates": { "sun": { "gate": 4, "line": 3 } /* … */ },
+    "designGates": { "sun": { "gate": 49, "line": 1 } /* … */ },
+    "chart": { "type": "Manifesting Generator", "authority": "Sacral", "strategy": "…", "profile": "3/5", "definition": "…", "cross": "…", "channels": [ /* … */ ], "centers": { /* … */ } }
+  },
+  "svg": "<svg …>…</svg>"
+}
+```
+
+### 3. Personal sky — `skyPersonal(birth)`
+
+`POST /v1/sky/personal` — a birth instant → the natal sky rendered as an SVG string (`image/svg+xml`). Deterministic per birth. Retrogrades render `℞`; fixed stars conjunct natal points light up.
+
+```ts
+const svg = await mystic.skyPersonal(
+  { year: 1990, month: 1, day: 2, hour: 3, minute: 4 },
+  { animate: false }, // optional — request a static render
+);
+// svg === "<svg xmlns=\"http://www.w3.org/2000/svg\" …>…</svg>"
+```
+
+There is also `skyPersonalGet(birth, opts?)` if you want the `GET` query-param form (handy for shareable URLs).
+
+## Error handling
+
+Every non-2xx response throws a typed `MysticApiError`. Network/transport failures throw with `status: 0`, `code: 'network_error'`.
+
+```ts
+import { MysticApi, MysticApiError } from 'mysticapi';
+
+try {
+  await mystic.skyToday();
+} catch (err) {
+  if (err instanceof MysticApiError) {
+    err.status;           // 401 | 402 | 429 | 400 | 0 | …
+    err.code;             // "missing_api_key" | "quota_exceeded" | "http_402" | …
+    err.message;          // human-readable message from the API
+    err.docs;             // documentation URL, when provided
+    err.retryAfter;       // number of seconds (set on 429 when Retry-After is present)
+
+    if (err.isRateLimited) await sleep(err.retryAfter! * 1000); // back off, then retry
+    if (err.isUnauthorized) { /* bad or missing key */ }
+    if (err.isPaymentRequired) { /* 402 — supply a key or an x402 payment */ }
+  }
+}
+```
+
+## Cloudflare Workers
+
+Works out of the box — the client uses global `fetch`. Read the key from a secret binding:
+
+```ts
+export default {
+  async fetch(_req: Request, env: { MYSTIC_API_KEY: string }): Promise<Response> {
+    const mystic = new MysticApi({ apiKey: env.MYSTIC_API_KEY });
+    const sky = await mystic.skyToday();
+    return Response.json(sky);
+  },
+};
+```
+
+You can also inject a custom `fetch` via `new MysticApi({ apiKey, fetch })`.
+
+## API
+
+| Method | HTTP | Returns |
+| --- | --- | --- |
+| `new MysticApi({ apiKey, baseUrl?, fetch? })` | — | client |
+| `skyToday()` | `GET /v1/sky/today` | `Promise<SkyToday>` |
+| `bodygraph(birth)` | `POST /v1/bodygraph` | `Promise<BodygraphResult>` (`{ chart, svg }`) |
+| `skyPersonal(birth, opts?)` | `POST /v1/sky/personal` | `Promise<string>` (SVG) |
+| `skyPersonalGet(birth, opts?)` | `GET /v1/sky/personal` | `Promise<string>` (SVG) |
+| `MysticApi.getFreeKey(email, opts?)` | `POST /v1/keys/free` | `Promise<FreeKeyResponse>` |
+
+`birth` is `{ year, month, day, hour, minute, second? }` in **UTC**. All types are exported. The machine-readable contract lives at <https://mysticapi.com/.well-known/openapi.json>.
+
+## License
+
+MIT © Latimer Woods Tech

package/dist/index.d.mts

@@ -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 };