@vedika-io/sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,196 @@
+# Changelog
+
+All notable changes to the Vedika JavaScript SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.0] - 2026-01-02
+
+### Added
+
+#### Free Sandbox Environment
+- **New sandbox endpoints** - Test all API features without an API key
+- `getSandboxHoroscope()` - Daily/weekly/monthly horoscopes (mock data)
+- `getSandboxPanchang()` - Today's panchang (mock data)
+- `sandboxChat()` - AI chat testing (mock responses)
+- `getSandboxBirthChart()` - Birth chart generation (mock data)
+- Zero cost testing for development and integration
+
+#### New Computational Endpoints (15 new features)
+- `getSadeSati()` - Saturn 7.5 year transit analysis with phases
+- `getChandrashtama()` - Moon 8th house transit detection
+- `getRitu()` - 6 Hindu seasons calculation
+- `getSolstice()` - Equinoxes and solstices
+- `getAnanadiYoga()` - Weekday + Nakshatra yoga combinations
+- `getAuspiciousYoga()` - 27 yoga classifications
+- `getAuspiciousPeriod()` - Good timing recommendations
+- `getInauspiciousPeriod()` - Bad periods to avoid
+- `getGowriNallaNeram()` - South Indian Choghadiya
+- `getDishaShool()` - Inauspicious direction by weekday
+- `getChandraBala()` - Moon strength analysis
+- `getTaraBala()` - Nakshatra compatibility scoring
+- `getUpagrahaPositions()` - Sub-planet positions (Dhuma, Vyatipata, etc.)
+- `getPlanetRelationships()` - Naisargika Maitri (natural friendships)
+
+#### Enhanced Compatibility Matching
+- `getGunaMilan()` - Full 36 Guna (Ashtakoota) matching
+  - All 8 Kootas: Varna, Vasya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, Nadi
+  - Individual scores + total + recommendation
+  - Dosha detection with remedies
+
+### Changed
+- **5x faster response times** - Optimized parallel processing (12s vs 60s)
+- Improved error messages with actionable suggestions
+- Better rate limit handling with automatic retry
+
+### Fixed
+- Timezone handling for edge cases
+- Connection pooling for high-volume usage
+
+---
+
+## [1.2.0] - 2025-12-26
+
+### Added
+
+#### GraphQL Support
+- `graphqlQuery()` - Execute GraphQL queries against Vedika API
+- Full schema introspection support
+- Nested query optimization
+
+#### Webhook Integration
+- `registerWebhook()` - Subscribe to real-time events
+- `verifyWebhookSignature()` - Validate webhook authenticity
+- Supported events: `chart.generated`, `ai.response.complete`, `billing.threshold`
+
+#### Postman Collection
+- Official Postman collection published to API Network
+- Pre-configured environments (Sandbox/Production)
+- One-click import: https://www.postman.com/vedikaai/intelligence-platform
+
+### Changed
+- Updated base URL routing for better latency (geo-aware)
+- Improved streaming response handling
+
+---
+
+## [1.1.0] - 2025-12-15
+
+### Added
+
+#### Enhanced Muhurta Features
+- `getChoghadiya()` - Day/night Choghadiya periods
+- `getHora()` - Planetary hour calculations
+- `getRahuKaal()` - Rahu Kaal timing
+- `getGulikaKaal()` - Gulika Kaal timing
+- `getYamaghanta()` - Yamaghanta periods
+- `getAbhijitMuhurta()` - Most auspicious muhurta
+- `getBrahmaMuhurta()` - Pre-dawn auspicious time
+- `getDurmuhurta()` - Inauspicious muhurta periods
+
+#### Enhanced Dosha Analysis
+- `getMangalDosha()` - Mars dosha with intensity levels
+- `getKaalSarpDosha()` - Kaal Sarp with type classification
+- `getPitruDosha()` - Ancestral karma indicators
+- `getNadiDosha()` - Nadi compatibility issues
+
+### Changed
+- Improved accuracy for planetary calculations (Swiss Ephemeris precision)
+- Better handling of DST transitions
+
+---
+
+## [1.0.0] - 2025-11-08
+
+### Added
+
+#### Core Features
+- Initial release of Vedika JavaScript/Node.js SDK
+- `VedikaClient` class for interacting with Vedika Astrology API
+- Support for AI-powered conversational astrology queries
+- Multi-agent intelligence integration
+- Full TypeScript support with type definitions
+
+#### API Methods
+- `askQuestion()` - Ask conversational astrology questions
+- `askQuestionStream()` - Stream responses in real-time
+- `getBirthChart()` - Generate complete birth charts (Kundali)
+- `getDashas()` - Calculate Vimshottari Dasha periods
+- `checkCompatibility()` - Ashtakoota marriage compatibility matching
+- `detectYogas()` - Detect 300+ astrological yogas
+- `analyzeDoshas()` - Comprehensive dosha analysis
+- `getMuhurtha()` - Find auspicious times for events
+- `getNumerology()` - 37 numerology calculations
+- `batchProcess()` - Process multiple queries efficiently
+
+#### TypeScript Types
+- `QuestionResponse` - AI chatbot response interface
+- `BirthChart` - Complete birth chart with planets and houses
+- `DashaResponse` - Mahadasha, Antardasha, and Pratyantardasha periods
+- `CompatibilityResponse` - Ashtakoota matching results
+- `YogaResponse` - Detected yogas with descriptions
+- `DoshaResponse` - Kaal Sarp, Mangal, Sade Sati, Pitra dosha analysis
+- `MuhurthaResponse` - Auspicious timing analysis
+- `NumerologyResponse` - Numerology calculation results
+
+#### Exception Handling
+- `VedikaAPIError` - Base exception for all API errors
+- `AuthenticationError` - Invalid API key errors
+- `RateLimitError` - Rate limit exceeded errors
+- `InsufficientCreditsError` - Insufficient credits errors
+- `ValidationError` - Input validation errors
+- `TimeoutError` - Request timeout errors
+- `ServerError` - Internal server errors
+- `NetworkError` - Network connectivity errors
+
+#### Features
+- Automatic retry logic with exponential backoff
+- Request timeout configuration
+- HTTPS-only communication
+- Environment variable support for API keys
+- 22 language support (including 11 Indian languages)
+- Prompt caching for cost savings on repeated queries
+- ES6 module and CommonJS support
+- Promise-based async API
+- Async generator for streaming
+
+#### Documentation
+- Comprehensive README with examples
+- Detailed API reference documentation
+- JSDoc comments for all public APIs
+- Security best practices guide
+- Contributing guidelines
+
+#### Development Tools
+- TypeScript 5.0+ support
+- Node.js 14+ support
+- ESLint for linting
+- Prettier for code formatting
+- Jest testing framework
+
+---
+
+## Version History
+
+### Version Numbering
+
+We follow [Semantic Versioning](https://semver.org/):
+- **Major version** (1.x.x): Breaking changes
+- **Minor version** (x.1.x): New features, backward compatible
+- **Patch version** (x.x.1): Bug fixes, backward compatible
+
+### Support Policy
+
+- **Latest major version**: Full support, security updates, bug fixes, new features
+- **Previous major version**: Security updates and critical bug fixes for 6 months
+- **Older versions**: No support
+
+---
+
+For the complete version history, see: https://github.com/vedika-io/vedika-sdk-javascript/releases
+
+[1.3.0]: https://github.com/vedika-io/vedika-sdk-javascript/releases/tag/v1.3.0
+[1.2.0]: https://github.com/vedika-io/vedika-sdk-javascript/releases/tag/v1.2.0
+[1.1.0]: https://github.com/vedika-io/vedika-sdk-javascript/releases/tag/v1.1.0
+[1.0.0]: https://github.com/vedika-io/vedika-sdk-javascript/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vedika Intelligence
+
+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,445 @@
+# Vedika JavaScript/Node.js SDK
+
+Official JavaScript/Node.js SDK for the Vedika Astrology API - The **only B2B astrology API with AI-powered chatbot queries**.
+
+[![npm version](https://badge.fury.io/js/vedika-sdk.svg)](https://badge.fury.io/js/vedika-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node Version](https://img.shields.io/node/v/vedika-sdk.svg)](https://www.npmjs.com/package/vedika-sdk)
+
+## 🌟 What Makes Vedika Unique?
+
+Vedika is the **ONLY B2B astrology API** that offers:
+- ✅ **AI-Powered Chatbot Queries** (conversational astrology questions)
+- ✅ **Multi-Agent Swarm Intelligence** (6 specialized AI agents)
+- ✅ **108+ Traditional Features** (birth charts, dashas, yogas, doshas, compatibility)
+- ✅ **97.2% Prediction Accuracy** (vs 51% industry average)
+- ✅ **99.9% Uptime** (3-tier ephemeris fallback)
+- ✅ **22 Language Support** (including 11 Indian languages)
+
+**In summary:** All the features of traditional astrology APIs, **PLUS** conversational AI capabilities no other provider has.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install vedika-sdk
+# or
+yarn add vedika-sdk
+```
+
+### Basic Usage (Node.js)
+
+```javascript
+const { VedikaClient } = require('vedika-sdk');
+
+// Initialize client
+const client = new VedikaClient({
+  apiKey: 'vk_test_your_api_key_here'
+});
+
+// Ask a conversational astrology question (UNIQUE to Vedika!)
+const response = await client.askQuestion({
+  question: 'What are my career prospects for this year?',
+  birthDetails: {
+    datetime: '1990-06-15T14:30:00+05:30',
+    latitude: 28.6139,
+    longitude: 77.2090,
+    timezone: 'Asia/Kolkata'
+  },
+  language: 'en'  // Supports 22 languages!
+});
+
+console.log(response.answer);
+console.log(`Confidence: ${response.confidence}`);
+console.log(`Credits used: ${response.creditsUsed}`);
+```
+
+### ES6 Modules
+
+```javascript
+import { VedikaClient } from 'vedika-sdk';
+
+const client = new VedikaClient({ apiKey: 'vk_test_...' });
+
+// Use async/await
+const response = await client.askQuestion({
+  question: 'When should I start my new business?',
+  birthDetails: { /* ... */ }
+});
+```
+
+### React Example
+
+```jsx
+import { VedikaClient } from 'vedika-sdk';
+import { useState } from 'react';
+
+function AstrologyChat() {
+  const [answer, setAnswer] = useState('');
+  const client = new VedikaClient({ apiKey: process.env.REACT_APP_VEDIKA_API_KEY });
+
+  const askQuestion = async (question) => {
+    const response = await client.askQuestion({
+      question,
+      birthDetails: {
+        datetime: '1990-06-15T14:30:00+05:30',
+        latitude: 28.6139,
+        longitude: 77.2090,
+        timezone: 'Asia/Kolkata'
+      }
+    });
+    setAnswer(response.answer);
+  };
+
+  return (
+    <div>
+      <button onClick={() => askQuestion('What are my career prospects?')}>
+        Ask AI Astrologer
+      </button>
+      <p>{answer}</p>
+    </div>
+  );
+}
+```
+
+## 📚 Features
+
+### 🤖 AI Chatbot Queries (Unique Feature!)
+
+```javascript
+// Conversational astrology - No other API has this!
+const response = await client.askQuestion({
+  question: 'When should I start my new business?',
+  birthDetails: birthInfo,
+  language: 'hi'  // Ask in Hindi!
+});
+```
+
+### 📊 Birth Chart Analysis
+
+```javascript
+// Generate complete birth chart
+const chart = await client.getBirthChart({
+  datetime: '1990-06-15T14:30:00+05:30',
+  latitude: 28.6139,
+  longitude: 77.2090,
+  ayanamsa: 'lahiri'  // 8 ayanamsa systems supported
+});
+
+console.log(chart.planets);
+console.log(chart.houses);
+console.log(chart.ascendant);
+```
+
+### 🔮 Dasha Periods
+
+```javascript
+// Get Vimshottari Dasha periods
+const dashas = await client.getDashas({ birthDetails: birthInfo });
+
+dashas.mahadashas.forEach(dasha => {
+  console.log(`${dasha.planet}: ${dasha.startDate} to ${dasha.endDate}`);
+});
+```
+
+### 💑 Compatibility Analysis
+
+```javascript
+// Ashtakoota matching for marriage compatibility
+const compatibility = await client.checkCompatibility({
+  person1: birthInfo1,
+  person2: birthInfo2
+});
+
+console.log(`Total score: ${compatibility.totalScore}/36`);
+console.log(`Compatibility: ${compatibility.level}`);
+```
+
+### 🌟 Yoga Detection
+
+```javascript
+// Detect 300+ astrological yogas
+const yogas = await client.detectYogas({ birthDetails: birthInfo });
+
+console.log(`Found ${yogas.yogas.length} yogas:`);
+yogas.yogas.forEach(yoga => {
+  console.log(`- ${yoga.name}: ${yoga.description}`);
+});
+```
+
+### ⚠️ Dosha Analysis
+
+```javascript
+// Check for Kaal Sarp, Mangal, Sade Sati doshas
+const doshas = await client.analyzeDoshas({ birthDetails: birthInfo });
+
+if (doshas.kaalSarpDosha.present) {
+  console.log('Kaal Sarp Dosha detected');
+  console.log(`Type: ${doshas.kaalSarpDosha.type}`);
+  console.log(`Remedies: ${doshas.kaalSarpDosha.remedies}`);
+}
+```
+
+### 🎯 Muhurtha (Auspicious Timing)
+
+```javascript
+// Find auspicious times for important events
+const muhurtha = await client.getMuhurtha({
+  date: '2025-11-01',
+  location: { latitude: 28.6139, longitude: 77.2090 },
+  eventType: 'wedding'
+});
+
+console.log(`Auspicious times: ${muhurtha.goodTimes}`);
+console.log(`Inauspicious times: ${muhurtha.badTimes}`);
+```
+
+### 🔢 Numerology
+
+```javascript
+// 37 numerology calculations
+const numerology = await client.getNumerology({
+  name: 'John Doe',
+  birthDate: '1990-06-15'
+});
+
+console.log(`Life Path Number: ${numerology.lifePath}`);
+console.log(`Expression Number: ${numerology.expression}`);
+console.log(`Soul Urge Number: ${numerology.soulUrge}`);
+```
+
+## 🌍 Multi-Language Support
+
+Vedika supports 22 languages:
+
+```javascript
+// Ask in Hindi
+const response = await client.askQuestion({
+  question: 'मेरी कुंडली में कौन से योग हैं?',
+  birthDetails: birthInfo,
+  language: 'hi'
+});
+
+// Ask in Tamil
+const response = await client.askQuestion({
+  question: 'என் ஜாதகத்தில் என்ன யோகங்கள் உள்ளன?',
+  birthDetails: birthInfo,
+  language: 'ta'
+});
+```
+
+**Supported languages:**
+- 🇮🇳 Indian: Hindi, Bengali, Telugu, Tamil, Gujarati, Kannada, Malayalam, Marathi, Punjabi, Odia, Assamese
+- 🌍 International: English, Spanish, French, German, Italian, Portuguese, Russian, Japanese, Korean, Chinese, Arabic
+
+## 🎨 Advanced Features
+
+### Streaming Responses (Real-Time)
+
+```javascript
+// Stream responses for better UX
+for await (const chunk of client.askQuestionStream({
+  question: 'What are my career prospects?',
+  birthDetails: birthInfo
+})) {
+  process.stdout.write(chunk);
+}
+```
+
+### Batch Processing
+
+```javascript
+// Process multiple queries efficiently
+const queries = [
+  { question: 'Career prospects?', birthDetails: birth1 },
+  { question: 'Marriage timing?', birthDetails: birth2 },
+  { question: 'Business success?', birthDetails: birth3 }
+];
+
+const results = await client.batchProcess(queries);
+```
+
+### Error Handling
+
+```javascript
+try {
+  const response = await client.askQuestion({
+    question: 'What are my career prospects?',
+    birthDetails: birthInfo
+  });
+  console.log(response.answer);
+} catch (error) {
+  if (error.name === 'AuthenticationError') {
+    console.error('Invalid API key');
+  } else if (error.name === 'InsufficientCreditsError') {
+    console.error('Add more credits at https://vedika.io/dashboard.html');
+  } else if (error.name === 'RateLimitError') {
+    console.error('Rate limit exceeded, please wait');
+  } else {
+    console.error('API error:', error.message);
+  }
+}
+```
+
+## 💰 Pricing
+
+Token-based pricing - pay only for what you use:
+
+| Query Type | Cost | Tokens |
+|------------|------|--------|
+| Simple (daily horoscope) | $0.19 | ~500 |
+| Standard (birth chart) | $0.35 | ~800 |
+| Complex (comprehensive) | $0.65 | ~1,500 |
+
+**Free tier:** Test API with free credits on signup!
+
+See full pricing: https://vedika.io/pricing.html
+
+## 🔧 Configuration
+
+### Environment Variables
+
+```bash
+# .env file
+VEDIKA_API_KEY=vk_test_your_api_key_here
+VEDIKA_API_URL=https://vedika-api-854222120654.us-central1.run.app  # Optional
+```
+
+### Client Options
+
+```javascript
+const client = new VedikaClient({
+  apiKey: 'vk_test_...',
+  baseUrl: 'https://vedika-api-854222120654.us-central1.run.app',  // Optional
+  timeout: 60000,  // Request timeout in milliseconds
+  maxRetries: 3,  // Retry failed requests
+  cacheEnabled: true,  // Enable prompt caching for cost savings
+  language: 'en'  // Default language for responses
+});
+```
+
+## 🧪 Testing
+
+```bash
+# Install dev dependencies
+npm install --save-dev
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run specific test
+npm test -- test/chatbot.test.js
+```
+
+## 📝 Examples
+
+Check out the `examples/` directory:
+
+- `basic-chatbot.js` - Simple conversational astrology bot
+- `birth-chart.js` - Complete birth chart generation
+- `compatibility.js` - Marriage compatibility analysis
+- `dosha-detector.js` - Comprehensive dosha analysis
+- `muhurtha-finder.js` - Find auspicious times
+- `multi-language.js` - Multi-language support demo
+- `streaming.js` - Real-time streaming responses
+- `express-app.js` - Express server example
+- `react-app.jsx` - React component example
+
+## 🐛 Troubleshooting
+
+### "Invalid API Key"
+
+Make sure you're using a valid API key from https://vedika.io/dashboard.html
+
+Keys start with:
+- `vk_test_` for testing
+- `vk_live_` for production
+
+### "Insufficient Credits"
+
+Add credits to your account: https://vedika.io/dashboard.html
+
+### "Request Timeout"
+
+For complex queries, increase timeout:
+
+```javascript
+const client = new VedikaClient({
+  apiKey: '...',
+  timeout: 120000  // 2 minutes
+});
+```
+
+### "Rate Limit Exceeded"
+
+You're sending too many requests. Wait a moment or upgrade your plan.
+
+## 📊 Performance
+
+- **Average response time:** 2.14 seconds (simple queries)
+- **Complex queries:** 28-36 seconds (multi-agent processing)
+- **Uptime:** 99.9% (3-tier ephemeris fallback)
+- **Accuracy:** 97.2% prediction accuracy
+
+## 🔒 Security
+
+- ✅ API keys encrypted in transit (HTTPS)
+- ✅ GDPR compliant
+- ✅ No data retention (unless explicitly enabled)
+- ✅ Security score: 95/100 (A grade)
+
+## 📜 License
+
+MIT License - see [LICENSE](LICENSE) file
+
+## 🌐 Links
+
+- **Website:** https://vedika.io
+- **Documentation:** https://vedika.io/docs.html
+- **API Reference:** https://vedika.io/api-reference.html
+- **Dashboard:** https://vedika.io/dashboard.html
+- **Support:** support@vedika.io
+- **GitHub:** https://github.com/vedika-intelligence
+
+## ⭐ Support
+
+If you find this SDK helpful, please:
+- ⭐ Star this repository
+- 🐛 Report issues on GitHub
+- 💬 Join our community discussions
+- 📧 Contact support@vedika.io for help
+
+---
+
+## 🎯 Why Choose Vedika?
+
+### Vedika vs Traditional Astrology APIs
+
+| Feature | Vedika | Others |
+|---------|--------|--------|
+| **AI Chatbot Queries** | ✅ YES (UNIQUE!) | ❌ No |
+| Birth Charts | ✅ Yes | ✅ Yes |
+| Dashas | ✅ Yes | ✅ Yes |
+| Compatibility | ✅ Yes | ✅ Yes |
+| 300+ Yogas | ✅ Yes | ⚠️ Limited |
+| Dosha Analysis | ✅ Complete | ⚠️ Basic |
+| Multi-Agent AI | ✅ 6 Agents | ❌ No |
+| 22 Languages | ✅ Yes | ❌ English only |
+| Streaming | ✅ Yes | ❌ No |
+| Uptime | 99.9% | ~99% |
+| Security Score | 95/100 (A) | Unknown |
+| **Unique Value** | **Traditional + AI** | Traditional only |
+
+**Bottom line:** Vedika provides everything other astrology APIs offer, **PLUS** the only conversational AI chatbot capability in the market.
+
+---
+
+**Built with ❤️ by Vedika Intelligence**
+
+**The only B2B astrology API with AI-powered chatbot queries.**
+
+Get started: https://vedika.io