Init commit v 0.1.0

Author: Sergii Solonyna

.cursorrules

@@ -0,0 +1,43 @@
+## Project Overview
+- Package: `@procoders/astrology-api-client`
+- Purpose: TypeScript SDK for https://api.astrology-api.io (OpenAPI spec saved in `docs-openapi.json`)
+- Runtime: Node.js (ES modules)
+- HTTP layer: Axios with request/response interceptors, automatic retry logic, strict validation
+- Tests: Vitest with 100% coverage enforced (`npm run test:coverage`)
+
+## Directory Layout
+- `src/client.ts` — core client implementation
+- `src/types/` — strongly typed configs, requests, and responses
+- `src/errors/` — custom error hierarchy (`AstrologyError`)
+- `src/utils/validators.ts` — runtime validation helpers used prior to network calls
+- `tests/` — unit tests with axios-mock-adapter (keep coverage at 100%)
+- `examples/usage.ts` — sample usage (guarded by `RUN_ASTROLOGY_EXAMPLE` flag)
+- `docs-openapi.json` — locally cached OpenAPI v3 spec (use for type references)
+
+## Coding Guidelines
+- Always prefer type-safe solutions; keep files in strict TypeScript.
+- Keep code DRY, KISS, and single-responsibility. Extract helpers if logic repeats.
+- Comments, docs, and logs MUST be written in English.
+- When adding HTTP endpoints ensure:
+  - URL assembled via environment-aware base (`process.env.ASTROLOGY_API_BASE_URL` fallback)
+  - API key header is set (`X-API-Key`)
+  - Payload validated via `validators.ts`.
+- For additions touching API schema, consult `docs-openapi.json` first.
+- Update or add Vitest suites and maintain 100% coverage. Use axios-mock-adapter for HTTP mocks.
+- Run `npm run lint` and `npm run test:coverage` before completion.
+
+## Documentation & Examples
+- README must show installation, configuration, environment variables, and code snippets.
+- When adding examples, wrap network calls with environment checks so examples do not run by default.
+
+## Tooling
+- ESLint + Prettier already configured; match formatting in existing files.
+- Coverage enforced in `vitest.config.ts`. If coverage drops, add tests instead of raising thresholds.
+
+## PR / Commit Checklist
+1. Update relevant types in `src/types/`.
+2. Keep public API exported via `src/index.ts`.
+3. Add/adjust tests to maintain 100% coverage.
+4. Document new features in README.
+5. Ensure `.cursorrules` stays aligned with architecture changes.
+

.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+coverage/
+.env
+.env.*
+.DS_Store
+npm-debug.log*
+pnpm-debug.log*
+vite.config.ts.timestamp-*
+.vitest
+.dist

.prettierrc

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "printWidth": 120,
+  "semi": true,
+  "trailingComma": "all",
+  "arrowParens": "always"
+}
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Procoders
+
+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.
+

README.md

@@ -0,0 +1,140 @@
+## Astrology API TypeScript SDK
+
+Type-safe Node.js client for the [Astrology API v3.0.0](https://api.astrology-api.io/rapidoc). The package ships as an ESM build, exposes a modular architecture with dedicated sub-clients per endpoint family, and enforces 100 % test coverage. Publish-ready as `@procoders/astrology-api-client`.
+
+### Highlights
+- Axios-powered HTTP layer with retry/backoff, header normalization, and response unwrapping
+- Strong TypeScript types generated from the local OpenAPI spec (`docs-openapi.json`)
+- Exhaustive runtime validation via `src/utils/validators.ts` to prevent invalid API calls
+- Rich category coverage: data, charts, horoscopes, analysis, astrocartography, insights, SVG, enhanced traditional analytics, and more
+- Debug-friendly logging pipeline with configurable logger and opt-in verbosity
+
+### Installation
+```bash
+npm install @procoders/astrology-api-client
+```
+
+### Environment Variables
+| Variable | Required | Description |
+| --- | --- | --- |
+| `ASTROLOGY_API_BASE_URL` | optional | Override for the default `https://api.astrology-api.io` endpoint |
+| `ASTROLOGY_DEBUG` | optional | Set to `true` to enable debug logging |
+| `RUN_ASTROLOGY_EXAMPLE` | optional | Set to `true` to execute `examples/usage.ts` |
+
+### Client Architecture
+```ts
+import { AstrologyClient } from '@procoders/astrology-api-client';
+
+const client = new AstrologyClient({
+  apiKey: 'your-api-key-here', // optional for public endpoints
+  baseUrl: process.env.ASTROLOGY_API_BASE_URL ?? 'https://api.astrology-api.io',
+  retry: { attempts: 2, delayMs: 250 },
+  debug: process.env.ASTROLOGY_DEBUG === 'true',
+});
+
+// Category sub-clients
+client.data.getPositions(...);
+client.charts.getNatalChart(...);
+client.analysis.getNatalReport(...);
+client.horoscope.getPersonalDailyHoroscope(...);
+client.insights.relationship.getCompatibility(...);
+client.svg.getNatalChartSvg(...);
+client.enhanced.getGlobalAnalysis(...);
+```
+
+| Sub-client | Path prefix | Sample methods |
+| --- | --- | --- |
+| `data` | `/api/v3/data` | `getPositions`, `getGlobalPositions`, `getLunarMetrics` |
+| `charts` | `/api/v3/charts` | `getNatalChart`, `getTransitChart`, `getSolarReturnChart` |
+| `horoscope` | `/api/v3/horoscope` | `getPersonalDailyHoroscope`, `getSignWeeklyHoroscopeText` |
+| `analysis` | `/api/v3/analysis` | `getSynastryReport`, `getCompatibilityAnalysis`, `getProgressionReport` |
+| `glossary` | `/api/v3/glossary` | `getCities`, `getActivePoints`, `getHouseSystems` |
+| `astrocartography` | `/api/v3/astrocartography` | `getLines`, `getMap`, `getRelocationChart` |
+| `chinese` | `/api/v3/chinese` | `getBaZi`, `getYearlyForecast`, `getCompatibility` |
+| `eclipses` | `/api/v3/eclipses` | `getUpcoming`, `getNatalCheck`, `getInterpretation` |
+| `lunar` | `/api/v3/lunar` | `getCalendar`, `getPhases`, `getVoidOfCourse` |
+| `numerology` | `/api/v3/numerology` | `getCoreNumbers`, `getComprehensiveReport`, `getCompatibility` |
+| `tarot` | `/api/v3/tarot` | `drawCards`, `getTreeOfLife`, `getTimingAnalysis` |
+| `traditional` | `/api/v3/traditional` | `getAnalysis`, `getAnnualProfection`, `getLots` |
+| `fixedStars` | `/api/v3/fixed-stars` | `getPositions`, `getConjunctions`, `getReport` |
+| `insights` | `/api/v3/insights` | relationship/pet/wellness/financial/business suites |
+| `svg` | `/api/v3/svg` | `getNatalChartSvg`, `getSynastryChartSvg`, `getTransitChartSvg` |
+| `enhanced` | `/api/v3/enhanced*` | `getGlobalAnalysis`, `getPersonalAnalysis`, chart variants |
+
+Each category client inherits from a shared base that enforces the API prefix contract and provides a consistent `buildUrl` helper, so request construction stays uniform across the SDK.
+
+### Category Examples
+```ts
+// Data: planetary positions
+const subject = {
+  name: 'Demo User',
+  birth_data: {
+    year: 1990,
+    month: 5,
+    day: 11,
+    hour: 18,
+    minute: 15,
+    city: 'London',
+    country_code: 'GB',
+  },
+};
+const subjectA = subject;
+const subjectB = { ...subject, name: 'Partner' };
+
+const positions = await client.data.getPositions({ subject });
+
+// Charts: natal chart SVG export
+const natalSvg = await client.svg.getNatalChartSvg({ subject, svg_options: { theme: 'dark' } });
+
+// Analysis: synastry report
+const synastry = await client.analysis.getSynastryReport({ subject1: subjectA, subject2: subjectB });
+
+// Horoscope: personalized daily forecast
+const daily = await client.horoscope.getPersonalDailyHoroscope({ subject });
+
+// Insights: relationship compatibility
+const compatibility = await client.insights.relationship.getCompatibility({ subjects: [subjectA, subjectB] });
+
+// Enhanced: global traditional analysis
+const global = await client.enhanced.getGlobalAnalysis({
+  options: { house_system: 'W', zodiac_type: 'Tropic', active_points: ['Sun', 'Moon', 'Mercury'], precision: 3 },
+  orbs: { major_aspects_deg: 2 },
+});
+```
+
+See `examples/usage.ts` for a full script that conditionally runs when `RUN_ASTROLOGY_EXAMPLE=true`.
+
+### Debug Logging
+
+Pass `debug: true` and optionally supply a custom `logger` function. Setting `ASTROLOGY_DEBUG=true` enables the same behaviour globally. The client logs request metadata, retry attempts, and responses (status and url).
+
+### Testing & Linting
+```bash
+npm run lint            # ESLint with @typescript-eslint + Prettier
+npm run test            # Vitest watch mode
+npm run test:coverage   # Vitest with V8 coverage (enforced at 100 %)
+npm run build           # TypeScript build (emits ESM to dist/)
+```
+
+### Project Structure
+```
+├── src/
+│   ├── categories/              # Modular sub-clients per API family
+│   ├── client.ts                # Root client wiring sub-clients & interceptors
+│   ├── errors/AstrologyError.ts # Custom error hierarchy
+│   ├── types/                   # Generated and hand-written typings
+│   └── utils/validators.ts      # Runtime payload guards
+├── tests/unit/                  # Vitest suites with axios-mock-adapter
+├── examples/usage.ts            # Usage example (guarded by env flag)
+├── docs-openapi.json            # Cached OpenAPI specification
+└── README.md
+```
+
+### Publishing Checklist
+1. Ensure `npm run test:coverage` passes with 100 % coverage.
+2. Run `npm run build` and review the emitted `dist/` bundle.
+3. Update version, changelog, and documentation as needed.
+
+### License
+Released under the MIT License. See [`LICENSE`](./LICENSE) for details.
+

docs-openapi.json

@@ -0,0 +1,43 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+export default tseslint.config(
+  {
+    ignores: ['dist/**', 'coverage/**', 'node_modules/**'],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  eslintConfigPrettier,
+  {
+    files: ['src/**/*.ts', 'tests/**/*.ts', 'examples/**/*.ts'],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      globals: {
+        console: 'readonly',
+        describe: 'readonly',
+        it: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        vi: 'readonly',
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-misused-promises': ['error', { checksVoidReturn: false }],
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+    },
+  },
+);
+

eslint.config.js

@@ -0,0 +1,110 @@
+import { AstrologyClient } from '../src';
+import type {
+  DateTimeLocation,
+  GlobalAnalysisRequest,
+  PersonalizedHoroscopeRequest,
+  PlanetaryPositionsRequest,
+  Subject,
+  SynastryReportRequest,
+} from '../src/types';
+
+export async function runExample(): Promise<void> {
+  const client = new AstrologyClient({
+    baseUrl: process.env.ASTROLOGY_API_BASE_URL ?? 'https://api.astrology-api.io',
+    retry: { attempts: 2, delayMs: 250 },
+    debug: process.env.ASTROLOGY_DEBUG === 'true',
+  });
+
+  const baseSubject: Subject = {
+    name: 'Demo User',
+    birth_data: {
+      year: 1990,
+      month: 5,
+      day: 11,
+      hour: 18,
+      minute: 15,
+      city: 'London',
+      country_code: 'GB',
+      timezone: 'Europe/London',
+    },
+  };
+
+  const partner: Subject = {
+    ...baseSubject,
+    name: 'Partner',
+    birth_data: {
+      ...baseSubject.birth_data,
+      year: 1992,
+      month: 3,
+      day: 27,
+    },
+  };
+
+  const transitMoment: DateTimeLocation = {
+    year: 2024,
+    month: 5,
+    day: 11,
+    hour: 12,
+    minute: 30,
+    city: 'New York',
+    country_code: 'US',
+    timezone: 'America/New_York',
+  };
+
+  const positionsRequest: PlanetaryPositionsRequest = { subject: baseSubject };
+  const positions = await client.data.getPositions(positionsRequest);
+  console.log(
+    'Positions planets:',
+    positions.planets?.map((p) => p.name),
+  );
+
+  const natalChart = await client.charts.getNatalChart({ subject: baseSubject });
+  console.log('Natal chart houses count:', natalChart.houses?.length);
+
+  const synastryRequest: SynastryReportRequest = {
+    subject1: baseSubject,
+    subject2: partner,
+  };
+  const synastry = await client.analysis.getSynastryReport(synastryRequest);
+  console.log('Synastry sections:', synastry.sections?.length);
+
+  const horoscopeRequest: PersonalizedHoroscopeRequest = { subject: baseSubject };
+  const horoscope = await client.horoscope.getPersonalDailyHoroscope(horoscopeRequest);
+  console.log('Daily horoscope life areas:', horoscope.life_areas);
+
+  const relationshipInsights = await client.insights.relationship.getCompatibility({
+    subjects: [baseSubject, partner],
+  });
+  console.log('Relationship compatibility keys:', Object.keys(relationshipInsights));
+
+  const svg = await client.svg.getNatalChartSvg({
+    subject: baseSubject,
+    svg_options: { theme: 'dark', language: 'en' },
+  });
+  console.log('SVG size:', svg.length);
+
+  const enhancedRequest: GlobalAnalysisRequest = {
+    options: {
+      house_system: 'W',
+      zodiac_type: 'Tropic',
+      precision: 3,
+      active_points: ['Sun', 'Moon', 'Mercury'],
+    },
+    orbs: { major_aspects_deg: 2 },
+  };
+  const enhanced = await client.enhanced.getGlobalAnalysis(enhancedRequest);
+  console.log('Enhanced planets:', enhanced.planets.length);
+
+  const transits = await client.charts.getTransitChart({
+    natal_subject: baseSubject,
+    transit_datetime: transitMoment,
+  });
+  console.log('Transit chart aspects:', transits.aspects?.length);
+}
+
+if (process.env.RUN_ASTROLOGY_EXAMPLE === 'true') {
+  runExample().catch((error) => {
+    // eslint-disable-next-line no-console
+    console.error('Example execution failed', error);
+  });
+}