feat: add the VedAstro Java client SDK with 684 generated calculators

A server-oriented Java 21 client for the VedAstro API, matching the Python,
Node.js and Go SDKs in surface while reading the way Java developers expect.

Library (org.vedastro), hand-written:

- VedAstroClient - immutable, thread-safe, one pooled java.net.http.HttpClient,
  built through a builder (apiKey, timeout, defaultAyanamsa, baseUrl,
  transport, silent). An empty key uses the free tier.
- Calculators - the 684 generated endpoints, exposed as client.calculate().
- Time / GeoLocation - records that validate eagerly, so a bad chart fails at
  the call site instead of as a confusing API error. Time.from(ZonedDateTime)
  and friends preserve the supplied offset.
- Json - a small dependency-free codec. Objects decode to LinkedHashMap,
  arrays to ArrayList, every number to Double (matching the Go SDK's float64),
  and a single-property payload is unwrapped exactly as the other SDKs do.
- ApiException / VedAstroException - unchecked, with the API key redacted from
  every message.
- Calculate - a static facade over a shared client for scripts and tests.
- withAyanamsa(...) - scopes an ayanamsa to the calling thread, so concurrent
  server requests cannot interfere.

Generated by StaticTableGenerator Task 12 into org.vedastro.calculate:

- Calculators.java (684 methods, 30 with nullable option classes)
- one enum per API enum, plus PlanetName as a value type with wire values
- api_manifest.json listing every method, parameter and default

Zero runtime dependencies: transport is java.net.http and JSON is bundled, so
the library drops into Spring Boot, Jakarta EE, Quarkus or a plain main without
adding a transitive tree.

Also included: a Maven wrapper, a JUnit 5 suite (36 tests, covering the codec,
Time/GeoLocation validation, request building, payload unwrapping, SVG
responses, error paths and key redaction - all against a fake transport, so no
API key or network is needed), 12 runnable demos, and a CI workflow testing
Java 21 and 23 on Linux and Windows.

Verified: mvn verify passes, the jar and sources jar build, and a live
exec:java run against the API prints "Sun Sign: Libra".

Author: sengiv

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: Java SDK CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        java: ['21', '23']
+    name: Java ${{ matrix.java }} on ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java }}
+          cache: maven
+      # Tests run against a fake transport, so no API key or network access is needed.
+      - name: Build and test
+        run: mvn -B --no-transfer-progress verify

.gitignore

@@ -0,0 +1,20 @@
+# Build output
+target/
+
+# IDE
+.idea/
+*.iml
+*.ipr
+*.iws
+.vscode/
+.settings/
+.classpath
+.project
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Demo output
+*.svg
+astro_data.json

.mvn/wrapper/maven-wrapper.jar

@@ -0,0 +1,3 @@
+wrapperVersion=3.3.2
+distributionType=bin
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,78 @@
+# FAQ
+
+Short answers to the questions that come up most. The [README](README.md) has runnable examples
+for each of them.
+
+**Which Java versions are supported?** Java 21 or newer. The library uses records, pattern
+matching, and `java.net.http.HttpClient`, all of which are standard since Java 21.
+
+**Is this a calculation engine?** No. It is a client for the remote VedAstro API, so every
+calculation needs network access. The astrology itself runs on VedAstro's servers.
+
+**Does it have any dependencies?** No runtime dependencies. Transport uses the JDK's
+`java.net.http`, and a small JSON codec is bundled, so there is no transitive tree to resolve and
+no version conflicts with your framework. JUnit is test-scoped only.
+
+**How do I add it to my build?** Use `org.vedastro:vedastro:1.0.0` from Maven Central. The library
+also builds from source with the included Maven wrapper (`./mvnw -B verify`), so you can vendor it
+if you prefer.
+
+**Are calls blocking?** Yes. Every calculator blocks the calling thread until the API responds.
+That suits a servlet thread or a Java 21 virtual thread; give each request its own thread rather
+than serialising calls behind one lock.
+
+**Is the client thread-safe?** Yes. A `VedAstroClient` is immutable after construction and holds a
+pooled `HttpClient`, so build one at start-up and share it. Creating a client per request would
+throw away connection reuse.
+
+**How do I set the API key?** `VedAstroClient.builder().apiKey(System.getenv("VEDASTRO_API_KEY"))`,
+or `Calculate.setApiKey(...)` for the static facade. An empty key uses the free tier. Never embed a
+paid key in a distributed JAR — they are trivially unpacked.
+
+**What are the rate limits?** The free tier allows five requests per minute, counted per key across
+every thread and process in your application. Paid keys are quoted as 200 calls per minute by the
+API's own rate-limit error. Confirm current limits at [vedastro.org/API.html](https://vedastro.org/API.html).
+
+**Does it retry or throttle automatically?** Neither. Only the caller knows whether a second
+request is safe, so the library leaves both to you. `BatchProcessing` in the demos shows a paced
+multi-threaded version.
+
+**Why do methods return `Object`?** Results vary per calculator: objects, arrays, scalars, or SVG
+markup. Decoded values are `Map`, `List`, `String`, `Double`, `Boolean`, or `null`. Read them with
+`Json.asMap`, `Json.asList`, `Json.asString`, `Json.asInt`, or a checked cast.
+
+**Why is my number `3.0` instead of `3`?** JSON has one number type, so every number decodes as
+`Double`, matching the Go SDK where all numbers are `float64`. Use `Json.asInt(value, fallback)`
+when you need a whole number.
+
+**Why did my payload come back as a plain value instead of a map?** A payload object with exactly
+one property is unwrapped to that property's value, the same rule the Python, Node.js and Go SDKs
+use. So `planetRasiD1Sign` may return a `Map` with `Name` and `DegreesIn`, while `houseSignName`
+returns a bare `String`.
+
+**A call failed — what should I check?** In order: the API key, the time string
+(`"HH:MM DD/MM/YYYY +HH:MM"`, 24-hour, DD/MM/YYYY), the coordinate order
+(`GeoLocation.of(name, longitude, latitude)`), and the rate limit. `ApiException.getMessage()`
+carries the API's own explanation.
+
+**How do I cancel a request?** Set a short `timeout(...)` on the client, or interrupt the calling
+thread. An interruption restores the interrupt flag and raises a `VedAstroException`. To stop a
+long batch, check `Thread.currentThread().isInterrupted()` between calls.
+
+**Can two requests use different ayanamsas at once?** Yes. `client.withAyanamsa(...)` scopes the
+choice to the calling thread for the duration of the lambda and restores the previous value
+afterwards, even if the lambda throws. A client-wide default is set with `defaultAyanamsa(...)`.
+
+**Which ayanamsa should I use?** `Ayanamsa.LAHIRI` for Indian astrology (and it is the server
+default when you set nothing), `Ayanamsa.KRISHNAMURTI` for KP, `Ayanamsa.FAGAN_BRADLEY` for
+Western sidereal.
+
+**Can I use it with Spring Boot?** Yes, and it is the recommended integration: declare one
+`VedAstroClient` as a `@Bean` and inject it. See [Using it in a server](README.md#-using-it-in-a-server).
+
+**Can I call an endpoint that the library does not wrap yet?** Yes:
+`client.call("NewEndpointName", Map.of("time", birth))`. This is useful while the server is ahead of
+a regenerated client.
+
+**Can I use this commercially?** Yes. MIT licensed, and both the free and paid tiers permit
+commercial use.

FAQ.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 VedAstro
+
+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.

LICENSE

@@ -0,0 +1,77 @@
+# Quick start
+
+Requires **Java 21 or newer**. There is nothing else to install — no native code, no ephemeris
+files, and no third-party runtime dependencies.
+
+## 1. Add the dependency
+
+Maven:
+
+```xml
+<dependency>
+  <groupId>org.vedastro</groupId>
+  <artifactId>vedastro</artifactId>
+  <version>1.0.0</version>
+</dependency>
+```
+
+Gradle:
+
+```groovy
+implementation 'org.vedastro:vedastro:1.0.0'
+```
+
+## 2. Make a calculation
+
+Save this as `src/main/java/Main.java`:
+
+```java
+import org.vedastro.Calculate;
+import org.vedastro.GeoLocation;
+import org.vedastro.Time;
+import org.vedastro.calculate.PlanetName;
+
+public class Main {
+    public static void main(String[] args) {
+        // 'FreeAPIUser' is the free-tier key (5 requests per minute).
+        // For a paid key, set VEDASTRO_API_KEY and read it with System.getenv.
+        Calculate.setApiKey("FreeAPIUser");
+
+        // Time format: "HH:MM DD/MM/YYYY +TZ:TZ".
+        // GeoLocation takes the name, then LONGITUDE, then latitude.
+        Time birth = Time.of("14:30 25/10/1992 +05:30",
+                GeoLocation.of("Mumbai", 72.8777, 19.0760));
+
+        Object result = Calculate.planetRasiD1Sign(PlanetName.SUN, birth);
+        System.out.println("Sun Sign: " + Calculate.name(result)); // Libra
+    }
+}
+```
+
+## 3. Run it
+
+```bash
+mvn -q compile exec:java -Dexec.mainClass=Main
+```
+
+Expected output:
+
+```
+Sun Sign: Libra
+```
+
+## Where to go next
+
+- **Runnable demos** — `./mvnw -q exec:java` runs the quick start; see the [demo list](README.md#-common-use-cases--demo-files)
+  for the other eleven, for example
+  `./mvnw -q exec:java -Dexec.mainClass=org.vedastro.demos.DailyPanchanga`
+- **Results are dynamic** — calculators return `Object`. Use `Json.asMap`, `Json.asList`,
+  `Json.asString` and `Json.asInt` rather than casting blindly.
+- **Optional arguments** — thirty calculators have an options class; omit it for the server
+  defaults, or set only the fields you need.
+- **Servers** — build one `VedAstroClient` at start-up and share it; it is thread-safe. See
+  [Using it in a server](README.md#-using-it-in-a-server).
+- **Rate limits** — the free tier allows five requests per minute, so pace calls 13 seconds apart.
+- **Errors** — catch `ApiException` for API failures and `VedAstroException` for transport
+  failures. The API key is always redacted.
+- **Common problems** — [FAQ](FAQ.md)