feat: add runnable examples, httptest-based tests, GitHub Actions CI

- examples/natal, examples/transits, examples/positions · self-contained, read TUFFYS_API_KEY
- tuffys/client_test.go · 7 tests via httptest.Server, no real API calls
  covers: happy path, structured API error, raw error fallback, no-key omits header,
  custom http.Client transport, context cancellation, trailing-slash baseURL
- .github/workflows/ci.yml · go vet/build/test -race on Go 1.21, 1.22, 1.23
- README: CI status badge, Examples section, swap private-repo link for case-study,
  soften 'no interface{}' claim (responses are map[string]any today), drop
  nonexistent WithUserAgent from design principles

Author: omkarjaliparthi

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        go: ["1.21", "1.22", "1.23"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+      - name: go vet
+        run: go vet ./...
+      - name: go build
+        run: go build ./...
+      - name: go test
+        run: go test -race -count=1 ./...

README.md

@@ -5,6 +5,7 @@ Official Go client for the [Insights Astrology API](https://tuffys-ai-astrology.
 **Zero runtime dependencies.** Only `net/http` and `encoding/json` from the standard library.
 
 <p align="center">
+  <a href="https://github.com/omkarjaliparthi/tuffys-astrology-go/actions/workflows/ci.yml"><img src="https://github.com/omkarjaliparthi/tuffys-astrology-go/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="https://pkg.go.dev/github.com/omkarjaliparthi/tuffys-astrology-go/tuffys"><img src="https://img.shields.io/badge/pkg.go.dev-docs-007d9c?style=flat-square" /></a>
   <a href="https://tuffys-ai-astrology.vercel.app/docs/api"><img src="https://img.shields.io/badge/API_docs-Scalar-6E56CF?style=flat-square" /></a>
   <a href="https://tuffys-ai-astrology.vercel.app/pricing"><img src="https://img.shields.io/badge/Pricing-tiered-success?style=flat-square" /></a>
@@ -90,23 +91,34 @@ All 43 v1 endpoints, grouped by domain:
 | **Aggregators** | `/daily` · `/compatibility` · `/events` |
 | **Utility** | `/geocode` · `/openapi.json` |
 
-Every method is typed end-to-end. No `interface{}`, no magic strings.
+Inputs are typed (`Person`, `NatalChartOpts`, `AspectPoint`); responses currently decode as `map[string]any` to match the API's rich, endpoint-specific shapes. Typed response structs are on the roadmap as the OpenAPI 3.1 spec stabilizes.
 
 ---
 
+## Examples
+
+Runnable examples live in [`examples/`](./examples):
+
+```bash
+export TUFFYS_API_KEY="eyJ..."
+go run ./examples/natal       # natal chart with typed error handling
+go run ./examples/transits    # transits from a natal chart
+go run ./examples/positions   # stateless body positions
+```
+
 ## Design principles
 
 - **Zero runtime dependencies.** Embed this in anything — serverless, edge, CLI, bot — without dragging a graph.
 - **Context-first.** Every method takes `context.Context`. Cancel anywhere in the tree.
 - **Errors are data.** `*tuffys.APIError` carries the HTTP status, the machine-readable code, and a human message.
-- **Idiomatic options.** Functional options (`WithAPIKey`, `WithHTTPClient`, `WithUserAgent`) — swap out the transport for tracing, retries, or testing.
+- **Idiomatic options.** Functional options (`WithAPIKey`, `WithHTTPClient`) — swap out the transport for tracing, retries, or testing.
 - **Strict input parsing on the server.** ISO-8601 datetimes required — no ambiguous local times. Pair with Go's `time.Time.Format(time.RFC3339)` and you're set.
 
 ---
 
 ## Related
 
-- **[Main repository](https://github.com/omkarjaliparthi/tuffys-ai-astrology)** — engine, API, frontend, case study
+- **[Case study](https://github.com/omkarjaliparthi/insights-astrology-api-case-study)** — architecture, decisions, accuracy, sources
 - **[TypeScript SDK](https://www.npmjs.com/package/tuffys-astrology)** — published on npm
 - **[Python SDK](https://pypi.org/project/tuffys-astrology/)** — published on PyPI
 - **[API docs](https://tuffys-ai-astrology.vercel.app/docs/api)** — interactive Scalar explorer

examples/README.md

@@ -0,0 +1,26 @@
+# Examples
+
+Runnable Go examples for the Tuffy's Astrology API client.
+
+Each example is self-contained — `go run ./examples/<name>` from the repo root.
+
+| Example | What it shows |
+|---|---|
+| [`natal/`](./natal) | Quickstart · `NatalChart` with typed error handling |
+| [`transits/`](./transits) | Relational endpoint · `Transits` of a natal chart to a given datetime |
+| [`positions/`](./positions) | Stateless body positions — no birth data needed |
+
+## Auth
+
+All examples read the API key from `TUFFYS_API_KEY`:
+
+```bash
+export TUFFYS_API_KEY="eyJ..."  # HS256 JWT issued by the API
+go run ./examples/natal
+```
+
+For the free Developer tier, [mint a key](https://tuffys-ai-astrology.vercel.app/pricing). No credit card.
+
+## Base URL
+
+Examples default to the hosted API at `https://tuffys-ai-astrology.vercel.app`. Override with `TUFFYS_BASE_URL` to point at a local or custom deployment.

examples/natal/main.go

@@ -0,0 +1,52 @@
+// Example: compute a natal chart with typed error handling.
+//
+//	TUFFYS_API_KEY=eyJ... go run ./examples/natal
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/omkarjaliparthi/tuffys-astrology-go/tuffys"
+)
+
+func main() {
+	apiKey := os.Getenv("TUFFYS_API_KEY")
+	if apiKey == "" {
+		fmt.Fprintln(os.Stderr, "set TUFFYS_API_KEY — mint one at https://tuffys-ai-astrology.vercel.app/pricing")
+		os.Exit(1)
+	}
+
+	baseURL := os.Getenv("TUFFYS_BASE_URL")
+	if baseURL == "" {
+		baseURL = "https://tuffys-ai-astrology.vercel.app"
+	}
+
+	client := tuffys.New(baseURL, tuffys.WithAPIKey(apiKey))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	chart, err := client.NatalChart(ctx, tuffys.Person{
+		Datetime:  "1990-06-15T12:00:00Z",
+		Latitude:  51.5074,
+		Longitude: -0.1278,
+	}, tuffys.NatalChartOpts{HouseSystem: "placidus"})
+
+	if err != nil {
+		var apiErr *tuffys.APIError
+		if errors.As(err, &apiErr) {
+			fmt.Fprintf(os.Stderr, "API %d %s: %s\n", apiErr.Status, apiErr.Code, apiErr.Message)
+			os.Exit(1)
+		}
+		fmt.Fprintln(os.Stderr, "transport error:", err)
+		os.Exit(1)
+	}
+
+	pretty, _ := json.MarshalIndent(chart, "", "  ")
+	fmt.Println(string(pretty))
+}

examples/positions/main.go

@@ -0,0 +1,50 @@
+// Example: geocentric ecliptic positions of selected bodies at a given UTC instant.
+//
+//	TUFFYS_API_KEY=eyJ... go run ./examples/positions
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/omkarjaliparthi/tuffys-astrology-go/tuffys"
+)
+
+func main() {
+	apiKey := os.Getenv("TUFFYS_API_KEY")
+	if apiKey == "" {
+		fmt.Fprintln(os.Stderr, "set TUFFYS_API_KEY")
+		os.Exit(1)
+	}
+
+	baseURL := os.Getenv("TUFFYS_BASE_URL")
+	if baseURL == "" {
+		baseURL = "https://tuffys-ai-astrology.vercel.app"
+	}
+
+	client := tuffys.New(baseURL, tuffys.WithAPIKey(apiKey))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	now := time.Now().UTC().Format(time.RFC3339)
+
+	// Omit the bodies slice to get all ten.
+	result, err := client.Positions(ctx, now, "sun", "moon", "mercury", "venus", "mars")
+	if err != nil {
+		var apiErr *tuffys.APIError
+		if errors.As(err, &apiErr) {
+			fmt.Fprintf(os.Stderr, "API %d %s: %s\n", apiErr.Status, apiErr.Code, apiErr.Message)
+			os.Exit(1)
+		}
+		fmt.Fprintln(os.Stderr, "transport error:", err)
+		os.Exit(1)
+	}
+
+	pretty, _ := json.MarshalIndent(result, "", "  ")
+	fmt.Println(string(pretty))
+}

examples/transits/main.go

@@ -0,0 +1,54 @@
+// Example: transits from a natal chart to a given datetime.
+//
+//	TUFFYS_API_KEY=eyJ... go run ./examples/transits
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/omkarjaliparthi/tuffys-astrology-go/tuffys"
+)
+
+func main() {
+	apiKey := os.Getenv("TUFFYS_API_KEY")
+	if apiKey == "" {
+		fmt.Fprintln(os.Stderr, "set TUFFYS_API_KEY")
+		os.Exit(1)
+	}
+
+	baseURL := os.Getenv("TUFFYS_BASE_URL")
+	if baseURL == "" {
+		baseURL = "https://tuffys-ai-astrology.vercel.app"
+	}
+
+	client := tuffys.New(baseURL, tuffys.WithAPIKey(apiKey))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	natal := tuffys.Person{
+		Datetime:  "1990-06-15T12:00:00Z",
+		Latitude:  51.5074,
+		Longitude: -0.1278,
+	}
+	transitAt := time.Now().UTC().Format(time.RFC3339)
+
+	result, err := client.Transits(ctx, natal, transitAt)
+	if err != nil {
+		var apiErr *tuffys.APIError
+		if errors.As(err, &apiErr) {
+			fmt.Fprintf(os.Stderr, "API %d %s: %s\n", apiErr.Status, apiErr.Code, apiErr.Message)
+			os.Exit(1)
+		}
+		fmt.Fprintln(os.Stderr, "transport error:", err)
+		os.Exit(1)
+	}
+
+	pretty, _ := json.MarshalIndent(result, "", "  ")
+	fmt.Println(string(pretty))
+}