@astroway/sdk 0.1.0-alpha.2 → 0.1.0

package/dist/cache.js

@@ -0,0 +1,198 @@
+/**
+ * Deterministic response cache.
+ *
+ * Charts are pure functions of `(date, time, lat, lon, tz)`. Caching them
+ * client-side saves credits and makes dev loops instant. None of the public
+ * astrology APIs do this — pure differentiator vs Prokerala / Astrologer.
+ *
+ * ## Storage
+ *
+ * Pluggable via the {@link CacheStore} interface:
+ *   - {@link MemoryStore}: in-process Map (default when `cache: 'memory'`)
+ *   - {@link LocalStorageStore}: browser/edge `Storage` adapter
+ *   - bring-your-own: pass any object satisfying `CacheStore` (Redis, IndexedDB, etc.)
+ *
+ * ## Policy
+ *
+ * Two lists baked into the SDK (override per-call via `{cache: true|false}`):
+ *
+ *   - {@link DETERMINISTIC_PATH_PREFIXES} — pure functions (cached by default)
+ *   - {@link NON_DETERMINISTIC_PATH_PREFIXES} — time-sensitive (skipped by default)
+ *
+ * Unknown endpoints are skipped by default. Force per-call when known safe.
+ *
+ * ## Key
+ *
+ * `astroway_v1_<sha256(canonical-json(method, path, body))>` — order-insensitive
+ * on object keys, order-preserving on lists.
+ */
+const VERSION_PATH_RE = /^\/v\d+(\/.*)?$/;
+export const CACHE_KEY_PREFIX = 'astroway_v1_';
+export const DETERMINISTIC_PATH_PREFIXES = [
+    '/chart',
+    '/synastry',
+    '/composite',
+    '/midpoints',
+    '/aspects',
+    '/houses',
+    '/planets',
+    '/vedic/',
+    '/numerology/',
+    '/tarot/',
+    '/hd/',
+    '/human-design/',
+    '/dasha/',
+];
+export const NON_DETERMINISTIC_PATH_PREFIXES = [
+    '/transits',
+    '/horoscope',
+    '/interpret',
+    '/ai/',
+    '/mcp/',
+    '/stream/',
+    '/now',
+    '/today',
+];
+/**
+ * Whether `path` is safe to cache by default. The denylist wins over the
+ * allowlist — `/horoscope/daily` is never cached even if `/horoscope` is on
+ * a custom allowlist.
+ */
+export function isDeterministicPath(path) {
+    const normalised = stripVersionPrefix(path);
+    for (const prefix of NON_DETERMINISTIC_PATH_PREFIXES) {
+        if (normalised.startsWith(prefix))
+            return false;
+    }
+    for (const prefix of DETERMINISTIC_PATH_PREFIXES) {
+        if (normalised.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+function stripVersionPrefix(path) {
+    const m = path.match(VERSION_PATH_RE);
+    if (m)
+        return m[1] ?? '/';
+    return path;
+}
+/**
+ * Recursively sort object keys; preserve list order. After canonicalisation,
+ * two requests with the same logical body but different field order produce
+ * identical JSON.
+ */
+export function canonicalise(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalise);
+    if (value !== null && typeof value === 'object') {
+        const obj = value;
+        const sorted = {};
+        for (const k of Object.keys(obj).sort())
+            sorted[k] = canonicalise(obj[k]);
+        return sorted;
+    }
+    return value;
+}
+/**
+ * SHA-256 via Web Crypto. Available in every modern runtime — Node 20+, Deno,
+ * Bun, browsers, Cloudflare Workers, Vercel Edge.
+ */
+async function sha256Hex(input) {
+    const enc = new TextEncoder().encode(input);
+    const buf = await globalThis.crypto.subtle.digest('SHA-256', enc);
+    const bytes = new Uint8Array(buf);
+    let hex = '';
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+/**
+ * Build a cache key for a request. Two semantically-equivalent calls produce
+ * the same key — `{ date, lat }` and `{ lat, date }` collide, by design.
+ */
+export async function buildCacheKey(method, path, body) {
+    const canonical = canonicalise({ m: method.toUpperCase(), p: path, b: body ?? null });
+    const json = JSON.stringify(canonical);
+    return CACHE_KEY_PREFIX + (await sha256Hex(json));
+}
+/** In-process `Map`-backed store. Use this for tests and short-lived processes. */
+export class MemoryStore {
+    map = new Map();
+    get(key) {
+        return this.map.get(key) ?? null;
+    }
+    set(key, entry) {
+        this.map.set(key, entry);
+    }
+    delete(key) {
+        this.map.delete(key);
+    }
+    /** Discard all entries — useful in test teardown. */
+    clear() {
+        this.map.clear();
+    }
+    /** Number of cached entries (regardless of expiry). */
+    get size() {
+        return this.map.size;
+    }
+}
+/**
+ * Browser / edge-runtime `Storage` adapter. Falls back to no-op on
+ * quota / private-mode errors.
+ */
+export class LocalStorageStore {
+    storage;
+    constructor(storage = globalThis.localStorage) {
+        this.storage = storage;
+    }
+    get(key) {
+        try {
+            const raw = this.storage.getItem(key);
+            if (raw === null)
+                return null;
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    set(key, entry) {
+        try {
+            this.storage.setItem(key, JSON.stringify(entry));
+        }
+        catch {
+            // Quota exceeded / private browsing — silently drop.
+        }
+    }
+    delete(key) {
+        try {
+            this.storage.removeItem(key);
+        }
+        catch { /* noop */ }
+    }
+}
+/** Default 24h TTL — long enough that pure-function endpoints feel "permanent". */
+export const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Turn the user-facing `cache` option into a `{store, defaultTtlMs}` pair.
+ * `undefined` / `false` → no cache.
+ */
+export function resolveCacheOption(option) {
+    if (option === undefined || option === false)
+        return null;
+    if (option === 'memory')
+        return { store: new MemoryStore(), defaultTtlMs: DEFAULT_CACHE_TTL_MS };
+    if (option === 'localStorage') {
+        if (typeof globalThis.localStorage === 'undefined') {
+            throw new Error('AstroWay SDK: cache: "localStorage" requires a global `localStorage`. '
+                + 'Use cache: "memory" outside the browser, or pass a custom CacheStore.');
+        }
+        return { store: new LocalStorageStore(), defaultTtlMs: DEFAULT_CACHE_TTL_MS };
+    }
+    if ('store' in option && option.store) {
+        return { store: option.store, defaultTtlMs: option.ttlMs ?? DEFAULT_CACHE_TTL_MS };
+    }
+    return { store: option, defaultTtlMs: DEFAULT_CACHE_TTL_MS };
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -4,16 +4,24 @@
  * Catch order recommendation in user code:
  *   try { ... } catch (e) {
  *     if (e instanceof RateLimitError) { ... await sleep ... }
+ *     else if (e instanceof QuotaExceededError) { ... top up credits ... }
  *     else if (e instanceof AuthenticationError) { ... rotate key ... }
  *     else if (e instanceof ApiError) { ... generic 4xx/5xx ... }
  *     else throw e;
  *   }
+ *
+ * Every `ApiError` carries `requestId`, `creditsRemaining`, and (when applicable)
+ * `retryAfterSeconds` so user code can build support tickets and debug uniformly.
  */
 interface ApiErrorInit {
     status?: number;
     code?: string;
     body?: unknown;
     requestId?: string;
+    /** Credits left in the caller's account, when surfaced via `X-Credits-Remaining`. */
+    creditsRemaining?: number;
+    /** Seconds to wait before retrying — set on 429 and quota-exceeded responses. */
+    retryAfterSeconds?: number;
     cause?: unknown;
 }
 export declare class ApiError extends Error {
@@ -26,6 +34,10 @@ export declare class ApiError extends Error {
     readonly body?: unknown;
     /** AstroWay request ID, when present in `X-Request-Id` response header. */
     readonly requestId?: string;
+    /** Credits remaining on the caller's account, surfaced from `X-Credits-Remaining`. */
+    readonly creditsRemaining?: number;
+    /** Seconds to wait before retrying (429, quota-exceeded). */
+    readonly retryAfterSeconds?: number;
     constructor(message: string, init?: ApiErrorInit);
 }
 export declare class APIConnectionError extends ApiError {
@@ -49,14 +61,25 @@ export declare class NotFoundError extends ApiError {
 export declare class UnprocessableEntityError extends ApiError {
     readonly name: string;
 }
-interface RateLimitErrorInit extends ApiErrorInit {
-    retryAfterSeconds?: number;
-}
 export declare class RateLimitError extends ApiError {
     readonly name: string;
-    /** Suggested seconds to wait before retrying, from `Retry-After` or server hint. */
-    readonly retryAfterSeconds?: number;
-    constructor(message: string, init?: RateLimitErrorInit);
+}
+/**
+ * Account ran out of credits / quota for the current period. HTTP 402 or
+ * `code: OUT_OF_CREDITS` / `QUOTA_EXCEEDED`. Distinct from RateLimitError
+ * (which is short-window throttling — backing off helps; for quota you need
+ * to top up or wait until the period resets).
+ */
+export declare class QuotaExceededError extends ApiError {
+    readonly name: string;
+}
+/**
+ * Server-side calculation failure for an otherwise-valid request — usually
+ * means a Swiss Ephemeris boundary, missing dataset, or unsupported house
+ * system for high latitudes. `code: CALCULATION_ERROR` from the API.
+ */
+export declare class CalculationError extends ApiError {
+    readonly name: string;
 }
 export declare class InternalServerError extends ApiError {
     readonly name: string;
@@ -67,6 +90,7 @@ interface ClassifyArgs {
     message: string;
     body?: unknown;
     requestId?: string;
+    creditsRemaining?: number;
     retryAfterSeconds?: number;
 }
 /**

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,UAAU,YAAY;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAkB,IAAI,EAAE,MAAM,CAAc;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY;CAOjD;AAED,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,SAAkB,IAAI,EAAE,MAAM,CAAwB;CACvD;AAED,qBAAa,eAAgB,SAAQ,kBAAkB;IACrD,SAAkB,IAAI,EAAE,MAAM,CAAqB;CACpD;AAED,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,SAAkB,IAAI,EAAE,MAAM,CAAqB;CACpD;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,SAAkB,IAAI,EAAE,MAAM,CAAyB;CACxD;AAED,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,SAAkB,IAAI,EAAE,MAAM,CAA2B;CAC1D;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,SAAkB,IAAI,EAAE,MAAM,CAAmB;CAClD;AAED,qBAAa,wBAAyB,SAAQ,QAAQ;IACpD,SAAkB,IAAI,EAAE,MAAM,CAA8B;CAC7D;AAED,UAAU,kBAAmB,SAAQ,YAAY;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,SAAkB,IAAI,EAAE,MAAM,CAAoB;IAClD,oFAAoF;IACpF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB;CAIvD;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,SAAkB,IAAI,EAAE,MAAM,CAAyB;CACxD;AAED,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAoB9D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,UAAU,YAAY;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAkB,IAAI,EAAE,MAAM,CAAc;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY;CASjD;AAED,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,SAAkB,IAAI,EAAE,MAAM,CAAwB;CACvD;AAED,qBAAa,eAAgB,SAAQ,kBAAkB;IACrD,SAAkB,IAAI,EAAE,MAAM,CAAqB;CACpD;AAED,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,SAAkB,IAAI,EAAE,MAAM,CAAqB;CACpD;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,SAAkB,IAAI,EAAE,MAAM,CAAyB;CACxD;AAED,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,SAAkB,IAAI,EAAE,MAAM,CAA2B;CAC1D;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,SAAkB,IAAI,EAAE,MAAM,CAAmB;CAClD;AAED,qBAAa,wBAAyB,SAAQ,QAAQ;IACpD,SAAkB,IAAI,EAAE,MAAM,CAA8B;CAC7D;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,SAAkB,IAAI,EAAE,MAAM,CAAoB;CACnD;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,SAAkB,IAAI,EAAE,MAAM,CAAwB;CACvD;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,SAAkB,IAAI,EAAE,MAAM,CAAsB;CACrD;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,SAAkB,IAAI,EAAE,MAAM,CAAyB;CACxD;AAED,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAKD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CA0B9D"}

package/dist/errors.js

@@ -4,10 +4,14 @@
  * Catch order recommendation in user code:
  *   try { ... } catch (e) {
  *     if (e instanceof RateLimitError) { ... await sleep ... }
+ *     else if (e instanceof QuotaExceededError) { ... top up credits ... }
  *     else if (e instanceof AuthenticationError) { ... rotate key ... }
  *     else if (e instanceof ApiError) { ... generic 4xx/5xx ... }
  *     else throw e;
  *   }
+ *
+ * Every `ApiError` carries `requestId`, `creditsRemaining`, and (when applicable)
+ * `retryAfterSeconds` so user code can build support tickets and debug uniformly.
  */
 export class ApiError extends Error {
     name = 'ApiError';
@@ -19,6 +23,10 @@ export class ApiError extends Error {
     body;
     /** AstroWay request ID, when present in `X-Request-Id` response header. */
     requestId;
+    /** Credits remaining on the caller's account, surfaced from `X-Credits-Remaining`. */
+    creditsRemaining;
+    /** Seconds to wait before retrying (429, quota-exceeded). */
+    retryAfterSeconds;
     constructor(message, init) {
         super(message, init?.cause !== undefined ? { cause: init.cause } : undefined);
         if (init?.status !== undefined)
@@ -29,6 +37,10 @@ export class ApiError extends Error {
             this.body = init.body;
         if (init?.requestId !== undefined)
             this.requestId = init.requestId;
+        if (init?.creditsRemaining !== undefined)
+            this.creditsRemaining = init.creditsRemaining;
+        if (init?.retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = init.retryAfterSeconds;
     }
 }
 export class APIConnectionError extends ApiError {
@@ -54,23 +66,35 @@ export class UnprocessableEntityError extends ApiError {
 }
 export class RateLimitError extends ApiError {
     name = 'RateLimitError';
-    /** Suggested seconds to wait before retrying, from `Retry-After` or server hint. */
-    retryAfterSeconds;
-    constructor(message, init) {
-        super(message, init);
-        if (init?.retryAfterSeconds !== undefined)
-            this.retryAfterSeconds = init.retryAfterSeconds;
-    }
+}
+/**
+ * Account ran out of credits / quota for the current period. HTTP 402 or
+ * `code: OUT_OF_CREDITS` / `QUOTA_EXCEEDED`. Distinct from RateLimitError
+ * (which is short-window throttling — backing off helps; for quota you need
+ * to top up or wait until the period resets).
+ */
+export class QuotaExceededError extends ApiError {
+    name = 'QuotaExceededError';
+}
+/**
+ * Server-side calculation failure for an otherwise-valid request — usually
+ * means a Swiss Ephemeris boundary, missing dataset, or unsupported house
+ * system for high latitudes. `code: CALCULATION_ERROR` from the API.
+ */
+export class CalculationError extends ApiError {
+    name = 'CalculationError';
 }
 export class InternalServerError extends ApiError {
     name = 'InternalServerError';
 }
+const QUOTA_CODES = new Set(['OUT_OF_CREDITS', 'QUOTA_EXCEEDED', 'CREDIT_LIMIT_REACHED']);
+const CALCULATION_CODES = new Set(['CALCULATION_ERROR', 'EPHEMERIS_ERROR']);
 /**
  * Maps an HTTP status + optional server error code to the most specific
  * subclass. Used by the openapi-fetch error path.
  */
 export function classifyHttpError(args) {
-    const { status, code, message, body, requestId, retryAfterSeconds } = args;
+    const { status, code, message, body, requestId, creditsRemaining, retryAfterSeconds } = args;
     const init = { status };
     if (code !== undefined)
         init.code = code;
@@ -78,18 +102,25 @@ export function classifyHttpError(args) {
         init.body = body;
     if (requestId !== undefined)
         init.requestId = requestId;
+    if (creditsRemaining !== undefined)
+        init.creditsRemaining = creditsRemaining;
+    if (retryAfterSeconds !== undefined)
+        init.retryAfterSeconds = retryAfterSeconds;
+    // Code-first dispatch for app-level errors that may ride on multiple HTTP statuses.
+    if (code !== undefined) {
+        if (QUOTA_CODES.has(code))
+            return new QuotaExceededError(message, init);
+        if (CALCULATION_CODES.has(code))
+            return new CalculationError(message, init);
+    }
     switch (status) {
         case 400: return new BadRequestError(message, init);
         case 401: return new AuthenticationError(message, init);
+        case 402: return new QuotaExceededError(message, init);
         case 403: return new PermissionDeniedError(message, init);
         case 404: return new NotFoundError(message, init);
         case 422: return new UnprocessableEntityError(message, init);
-        case 429: {
-            const rlInit = { ...init };
-            if (retryAfterSeconds !== undefined)
-                rlInit.retryAfterSeconds = retryAfterSeconds;
-            return new RateLimitError(message, rlInit);
-        }
+        case 429: return new RateLimitError(message, init);
     }
     if (status >= 500)
         return new InternalServerError(message, init);

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/helpers/birth-date-time.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `BirthDateTime` — typed builder + validator for the (date, time, lat, lon, tz)
+ * tuple that every chart-style endpoint takes. Reduces boilerplate when constructing
+ * request bodies and catches malformed dates before the network round-trip.
+ *
+ * Tree-shakeable: import directly from `@astroway/sdk/helpers` so the helper
+ * doesn't bloat the core bundle when you don't use it.
+ *
+ *   import { BirthDateTime } from '@astroway/sdk/helpers';
+ *
+ *   const birth = BirthDateTime.fromCoordinates({
+ *     date: '1990-07-14', time: '14:30:00',
+ *     latitude: 50.45, longitude: 30.52, timezoneOffset: 3,
+ *   });
+ *   const chart = await aw.chart.compute(birth.toBody());
+ */
+export interface BirthDateTimeInit {
+    /** ISO date `YYYY-MM-DD`. */
+    date: string;
+    /** Time `HH:MM:SS`. */
+    time: string;
+    /** UTC offset in hours. Defaults to 0 if omitted. */
+    timezoneOffset?: number;
+    /** Decimal latitude, north positive. Defaults to 0. */
+    latitude?: number;
+    /** Decimal longitude, east positive. Defaults to 0. */
+    longitude?: number;
+}
+export interface BirthDateTimeBody {
+    date: string;
+    time: string;
+    timezoneOffset: number;
+    latitude: number;
+    longitude: number;
+}
+export declare class BirthDateTime {
+    readonly date: string;
+    readonly time: string;
+    readonly timezoneOffset: number;
+    readonly latitude: number;
+    readonly longitude: number;
+    private constructor();
+    /**
+     * Build from explicit `{ date, time, latitude, longitude, timezoneOffset }`.
+     * Validates date / time format eagerly.
+     */
+    static fromCoordinates(init: BirthDateTimeInit): BirthDateTime;
+    /**
+     * Build from a `Date` (assumed to be a "local birth moment in the user's
+     * birth timezone") plus the corresponding `(lat, lon, tzOffset)`.
+     *
+     * The Date is split into `YYYY-MM-DD` + `HH:MM:SS` using its UTC components
+     * — the caller is responsible for passing a Date that already represents the
+     * birth-place local time (use `new Date(Date.UTC(year, month-1, day, hour, min, sec))`).
+     */
+    static fromDate(date: Date, geo: {
+        latitude: number;
+        longitude: number;
+        timezoneOffset?: number;
+    }): BirthDateTime;
+    /**
+     * Build from a full ISO 8601 string (`1990-07-14T14:30:00`) plus geo data.
+     * The trailing `Z` / `+HH:MM` offset, if present, is stripped — the API
+     * separately tracks `timezoneOffset`.
+     */
+    static parse(iso: string, geo: {
+        latitude: number;
+        longitude: number;
+        timezoneOffset?: number;
+    }): BirthDateTime;
+    /** Wire shape suitable for `aw.chart.compute(birth.toBody())` etc. */
+    toBody(): BirthDateTimeBody;
+    /** Same fields, but as a JS `Date` (constructed in UTC for determinism). */
+    toDate(): Date;
+}
+//# sourceMappingURL=birth-date-time.d.ts.map

package/dist/helpers/birth-date-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"birth-date-time.d.ts","sourceRoot":"","sources":["../../src/helpers/birth-date-time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,aAAa;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO;IAQP;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa;IAgB9D;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,CACb,IAAI,EAAE,IAAI,EACV,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GACpE,aAAa;IAgBhB;;;;OAIG;IACH,MAAM,CAAC,KAAK,CACV,GAAG,EAAE,MAAM,EACX,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GACpE,aAAa;IAgBhB,sEAAsE;IACtE,MAAM,IAAI,iBAAiB;IAU3B,4EAA4E;IAC5E,MAAM,IAAI,IAAI;CAKf"}

package/dist/helpers/birth-date-time.js

@@ -0,0 +1,112 @@
+/**
+ * `BirthDateTime` — typed builder + validator for the (date, time, lat, lon, tz)
+ * tuple that every chart-style endpoint takes. Reduces boilerplate when constructing
+ * request bodies and catches malformed dates before the network round-trip.
+ *
+ * Tree-shakeable: import directly from `@astroway/sdk/helpers` so the helper
+ * doesn't bloat the core bundle when you don't use it.
+ *
+ *   import { BirthDateTime } from '@astroway/sdk/helpers';
+ *
+ *   const birth = BirthDateTime.fromCoordinates({
+ *     date: '1990-07-14', time: '14:30:00',
+ *     latitude: 50.45, longitude: 30.52, timezoneOffset: 3,
+ *   });
+ *   const chart = await aw.chart.compute(birth.toBody());
+ */
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const TIME_RE = /^\d{2}:\d{2}:\d{2}$/;
+const ISO_RE = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}(?::\d{2})?)/;
+export class BirthDateTime {
+    date;
+    time;
+    timezoneOffset;
+    latitude;
+    longitude;
+    constructor(init) {
+        this.date = init.date;
+        this.time = init.time;
+        this.timezoneOffset = init.timezoneOffset;
+        this.latitude = init.latitude;
+        this.longitude = init.longitude;
+    }
+    /**
+     * Build from explicit `{ date, time, latitude, longitude, timezoneOffset }`.
+     * Validates date / time format eagerly.
+     */
+    static fromCoordinates(init) {
+        if (!DATE_RE.test(init.date)) {
+            throw new Error(`BirthDateTime: date must be YYYY-MM-DD, got '${init.date}'`);
+        }
+        if (!TIME_RE.test(init.time)) {
+            throw new Error(`BirthDateTime: time must be HH:MM:SS, got '${init.time}'`);
+        }
+        return new BirthDateTime({
+            date: init.date,
+            time: init.time,
+            timezoneOffset: init.timezoneOffset ?? 0,
+            latitude: init.latitude ?? 0,
+            longitude: init.longitude ?? 0,
+        });
+    }
+    /**
+     * Build from a `Date` (assumed to be a "local birth moment in the user's
+     * birth timezone") plus the corresponding `(lat, lon, tzOffset)`.
+     *
+     * The Date is split into `YYYY-MM-DD` + `HH:MM:SS` using its UTC components
+     * — the caller is responsible for passing a Date that already represents the
+     * birth-place local time (use `new Date(Date.UTC(year, month-1, day, hour, min, sec))`).
+     */
+    static fromDate(date, geo) {
+        const yyyy = date.getUTCFullYear().toString().padStart(4, '0');
+        const mm = (date.getUTCMonth() + 1).toString().padStart(2, '0');
+        const dd = date.getUTCDate().toString().padStart(2, '0');
+        const hh = date.getUTCHours().toString().padStart(2, '0');
+        const mi = date.getUTCMinutes().toString().padStart(2, '0');
+        const ss = date.getUTCSeconds().toString().padStart(2, '0');
+        return BirthDateTime.fromCoordinates({
+            date: `${yyyy}-${mm}-${dd}`,
+            time: `${hh}:${mi}:${ss}`,
+            latitude: geo.latitude,
+            longitude: geo.longitude,
+            timezoneOffset: geo.timezoneOffset ?? 0,
+        });
+    }
+    /**
+     * Build from a full ISO 8601 string (`1990-07-14T14:30:00`) plus geo data.
+     * The trailing `Z` / `+HH:MM` offset, if present, is stripped — the API
+     * separately tracks `timezoneOffset`.
+     */
+    static parse(iso, geo) {
+        const match = ISO_RE.exec(iso);
+        if (!match) {
+            throw new Error(`BirthDateTime: cannot parse ISO datetime '${iso}'`);
+        }
+        const [, date, timeRaw] = match;
+        const time = timeRaw.length === 5 ? `${timeRaw}:00` : timeRaw;
+        return BirthDateTime.fromCoordinates({
+            date: date,
+            time,
+            latitude: geo.latitude,
+            longitude: geo.longitude,
+            timezoneOffset: geo.timezoneOffset ?? 0,
+        });
+    }
+    /** Wire shape suitable for `aw.chart.compute(birth.toBody())` etc. */
+    toBody() {
+        return {
+            date: this.date,
+            time: this.time,
+            timezoneOffset: this.timezoneOffset,
+            latitude: this.latitude,
+            longitude: this.longitude,
+        };
+    }
+    /** Same fields, but as a JS `Date` (constructed in UTC for determinism). */
+    toDate() {
+        const [y, m, d] = this.date.split('-').map(Number);
+        const [h, mi, s] = this.time.split(':').map(Number);
+        return new Date(Date.UTC(y, m - 1, d, h, mi, s));
+    }
+}
+//# sourceMappingURL=birth-date-time.js.map

package/dist/helpers/birth-date-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"birth-date-time.js","sourceRoot":"","sources":["../../src/helpers/birth-date-time.ts"],"names":[],"mappings":"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"}

package/dist/helpers/index.d.ts

@@ -0,0 +1,3 @@
+/** Tree-shakeable helpers. Import from `@astroway/sdk/helpers` to keep the core bundle lean. */
+export { BirthDateTime, type BirthDateTimeInit, type BirthDateTimeBody, } from './birth-date-time.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAEhG,OAAO,EACL,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC"}

package/dist/helpers/index.js

@@ -0,0 +1,3 @@
+/** Tree-shakeable helpers. Import from `@astroway/sdk/helpers` to keep the core bundle lean. */
+export { BirthDateTime, } from './birth-date-time.js';
+//# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAEhG,OAAO,EACL,aAAa,GAGd,MAAM,sBAAsB,CAAC"}

package/dist/idempotency.d.ts

@@ -0,0 +1,10 @@
+/** Idempotency key generation + policy. */
+export type IdempotencyMode = 'auto' | 'off' | {
+    generator: () => string;
+};
+/** RFC 4122 v4 UUID. Uses Web Crypto when available, falls back to Math.random. */
+export declare function generateIdempotencyKey(): string;
+/** True for the methods we auto-attach an idempotency key on (POST only). */
+export declare function shouldAttachIdempotency(mode: IdempotencyMode | undefined, method: string): boolean;
+export declare function resolveKeyGenerator(mode: IdempotencyMode | undefined): () => string;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAE3C,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,KAAK,GACL;IAAE,SAAS,EAAE,MAAM,MAAM,CAAA;CAAE,CAAC;AAIhC,mFAAmF;AACnF,wBAAgB,sBAAsB,IAAI,MAAM,CAsB/C;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGlG;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,MAAM,CAKnF"}