curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -H "Idempotency-Key: report-synthetic-demo-001" \
 -d '{
    "name": "Synthetic Demo Candidate",
    "year": 1992,
    "month": 11,
    "day": 23,
    "hour": 14,
    "minute": 17,
    "city": "Lisbon",
    "tz_str": "Auto",
    "include_fixed_stars": true,
    "fixed_stars": ["Sirius", "Regulus", "Spica"],
    "include_dominants": true,
    "include_rulers": true,
    "psychological_report": {
      "enabled": true,
      "mode": "async",
      "style": "standard",
      "output_format": "pdf",
      "include_chart_in_pdf": true,
      "include_profile_branding_logo": true,
      "pdf_footer_label": "Acme Astrology",
      "markdown": true,
      "tone": "essayistic",
      "depth": "deep",
      "audience": "advanced astrology app user",
      "focus_areas": ["identity", "relationships", "integration"],
      "custom_instructions": "Prioritize precise psychological synthesis over generic placement descriptions.",
      "report_structure": {
        "chapters": [
          {
            "id": "orientation",
            "enabled": true,
            "title": "Orientation",
            "question": "What core psychological pattern does this chart describe?",
            "target_words": "450-650",
            "evidence_topics": ["identity", "temperament", "integration"],
            "subsections": [
              {
                "heading": "Dominant pattern",
                "instructions": "Name the chart's main psychological pattern."
              },
              {
                "heading": "Developmental direction",
                "instructions": "Describe the growth task without fatalistic prediction."
              }
            ]
          }
        ]
      }
    }
 }'

{
  "subject": { "...": "normal natal chart payload..." },
  "credits_used": 0,
  "psychological_report": {
    "status": "pending",
    "mode": "async",
    "style": "standard",
    "output_format": "pdf",
    "include_chart_in_pdf": true,
    "job_id": "7a7f3f9f-...",
    "fetch_url": "/api/v1/natal/report/7a7f3f9f-...",
    "pdf_url": "/api/v1/natal/report/7a7f3f9f-...?format=pdf&include_profile_branding_logo=true",
    "credits_used": 0,
    "include_profile_branding_logo": true,
    "next_poll_after_seconds": 15
  }
}

curl -X GET "https://api.freeastroapi.com/api/v1/natal/report/{job_id}?format=json" \
 -H "x-api-key: YOUR_API_KEY"

{
  "job_id": "7a7f3f9f-...",
  "status": "completed",
  "credits_used": 0,
  "report_metadata": {
    "report_id": "e5efe6ea-...",
    "title": "Jane Example Natal Psychological Report",
    "generated_at": "2026-03-21T11:44:09.531Z",
    "provider": "openai-compatible",
    "model": "gpt-5.3-chat-latest",
    "summary": "Core report summary...",
    "word_count": 7350
  },
  "report_markdown": "## Introduction ... (full markdown report)"
}

curl -L "https://api.freeastroapi.com/api/v1/natal/report/{job_id}?format=pdf&include_profile_branding_logo=true" \
 -H "x-api-key: YOUR_API_KEY" \
 -o branded-western-report.pdf

{
  "psychological_report": {
    "enabled": true,
    "mode": "async",
    "output_format": "pdf",
    "callback_url": "https://example.com/webhooks/freeastro/report",
    "callback_signing_secret": "replace-with-a-long-random-secret"
  }
}

{
  "event": "psychological_report.completed",
  "job_id": "7a7f3f9f-...",
  "status": "completed",
  "credits_used": 1,
  "report_metadata": { "...": "same metadata object as polling response" },
  "report_markdown": "## Introduction ...",
  "created_at": "2026-03-21T11:44:09.531Z"
}

Headers:
X-FreeAstro-Event: psychological_report.completed
X-FreeAstro-Timestamp: 1711025109
X-FreeAstro-Signature: <HMAC_SHA256_HEX>

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/freeastro/report", (req, res) => {
  const rawBody = req.body.toString("utf8");
  const timestamp = req.header("X-FreeAstro-Timestamp") || "";
  const signature = req.header("X-FreeAstro-Signature") || "";
  const secret = process.env.FREE_ASTRO_CALLBACK_SECRET || "";

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(rawBody);
  // Save report by event.job_id, then ack
  return res.status(200).json({ ok: true });
});