# Cloud Astrology API business API clients

Use a scoped organization key, explicit `test` or `production` environment, and one unique caller-retained idempotency key per billable operation. The production label is currently a logical local namespace, not an activated paid service. Do not put API secrets or birth details in URLs, analytics or logs.

Python3.9+: import `Client` from `python/gaya_one.py`. JavaScript: import from `javascript/gaya-one.mjs` (Node22+ or modern fetch/WebCrypto). No engine libraries are required by the clients. Set `G1_BASE_URL`, `G1_API_KEY` and optionally `G1_ENVIRONMENT=test`; run the corresponding `examples.py` or `examples.mjs` to execute Indian and Western synthetic natal cases. Run `sh integrations/business/examples.sh` for cURL or import `postman.json` and set variables. Replace the synthetic examples only with inputs you are authorized to process.

`calculate`, `batch` and `submit` accept an idempotency key; keep it in your own durable job record before calling. If omitted, a convenience UUID is generated and reused only within that invocation's retries. Retrying a new invocation with a new UUID creates a new billable operation. Changed input under an existing key returns409. A cached receipt retains its original engine and request ID; response header X-Request-ID identifies the current transport attempt.

HTTP202 is accepted work, not a result. Poll `job(id)` or `wait(id)`; check the returned terminal state and per-item status. Running cancellation discards the eventual result and releases credits; it is cooperative. The client retries network failures and explicitly retryable429/502/503/504 responses only when the request is safe or has idempotency. It does not retry validation, authentication or hard-cap failures, or silently change birth-time offsets. A poll timeout does not create replacement work.

Webhook helpers verify exact raw-body bytes and the five-minute timestamp tolerance. Persist event IDs in a durable receiver database with an atomic unique insert; the optional in-memory `seen` set is for examples/tests and cannot protect across receiver restarts. Return a successful acknowledgement after durable handling. HMAC secrets are per destination; never share API keys with the sender. Events contain job status and credits, not birth data.

See `docs/api/081_100_BUSINESS_API_ACCEPTANCE.md` for operation, encryption, scope and retention limits, and `docs/api/090_VERSION_AND_DEPRECATION_POLICY.md` for the supported-version policy. Both v2 quotes and its ledger use the fixed weighted credit schedule, separately from legacy component units. Commercial licenses and production billing remain open.

The automated JavaScript integration run uses Node. Before a cross-origin browser deployment, configure explicit allowed origins and expose `Retry-After`, `X-Request-ID`, `Location`, the credit headers and rate headers at the API gateway; verify the browser CORS path in that deployment. The local Node/Python checks do not constitute browser, production-network or availability certification.
