Três SDKs oficiais: TypeScript, Python e PHP em vez de curl puro

Podes chamar a API com curl ou fetch puros: o contrato é simples, um único header X-Api-Key e JSON nos dois sentidos. Mas quando há mais de 771 endpoints e os corpos dos pedidos têm uma dezena de campos, um cliente tipado poupa horas: autocompletar de caminhos, tipos de pedido e de resposta, repetições automáticas numa rede instável.

Por isso temos três SDKs oficiais, gerados a partir de um único contrato OpenAPI 3.1.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

A mesma chamada de mapa natal em três linguagens.

TypeScript: um wrapper fino sobre openapi-fetch (~6 KB de runtime), com autocompletar de caminhos:

import { Astroway } from '@astroway/sdk';

const aw = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY! });

const { data: chart } = await aw.client.POST('/chart', {
  body: {
    date: '1990-07-14',
    time: '14:30:00',
    timezoneOffset: 3,
    latitude: 50.4501,
    longitude: 30.5234,
    houseSystem: 'P',
  },
});

// aw.client.POST is the raw typed fetch, so `chart` is the { ok, data } envelope
console.log(chart.data.houses.ascendant);  // 212.0952574979425

Python: Astroway síncrono e AsyncAstroway assíncrono com a mesma superfície, sobre httpx:

from astroway import Astroway

aw = Astroway(api_key=os.environ['ASTROWAY_API_KEY'])

chart = aw.post('/chart', body={
    'date': '1990-07-14',
    'time': '14:30:00',
    'timezoneOffset': 3,
    'latitude': 50.4501,
    'longitude': 30.5234,
    'houseSystem': 'P',
})

print(chart['houses']['ascendant'])

PHP: sobre Guzzle 7 e PSR-18:

<?php
use Astroway\Astroway;

$aw = new Astroway(['apiKey' => getenv('ASTROWAY_API_KEY')]);

$chart = $aw->post('/chart', body: [
    'date'           => '1990-07-14',
    'time'           => '14:30:00',
    'timezoneOffset' => 3,
    'latitude'       => 50.4501,
    'longitude'      => 30.5234,
    'houseSystem'    => 'P',
]);

echo $chart['houses']['ascendant'];

Três linguagens diferentes, mas as mesmas garantias, porque os três são gerados a partir do mesmo contrato OpenAPI:

• Tipos de pedido e de resposta para todos os endpoints. O TS dá autocompletar de caminhos e corpos tipados; o Python é um pacote tipado PEP 561; o PHP tem assinaturas tipadas. Os campos são sugeridos pelo IDE, não pela documentação no separador ao lado.
• Retry integrado com backoff em 408, 409, 429, 5xx. Uma falha de rede temporária ou um rate limit não derruba o teu código: o cliente repete sozinho.
• Hierarquia de erros ao estilo Stainless. Os erros são tipados por classe, não uma string num catch. Apanhas um tipo concreto, RateLimitError ou ValidationError, e tratas cada caso de forma precisa.
• OpenAPI 3.1 como fonte. Um endpoint adicionado à API aparece no SDK na versão seguinte, sem duplicação manual.
• OIDC + proveniência SLSA na publicação: TS e PHP através de Trusted Publisher / auto-mirror, Python através de Trusted Publisher OIDC no PyPI. A cadeia de fornecimento é verificável.

O Base URL é o mesmo em todos, https://api.astroway.info/v1/, e a chave é enviada no header X-Api-Key. É a mesma chave das chamadas HTTP puras; o SDK não altera nada na autorização.

Sobre os três SDKs base existem integrações prontas para stacks específicas:

• @astroway/react: hooks para aplicações React
• astroway/sdk-symfony: bundle para Symfony
• astroway/sdk-laravel: pacote para Laravel

Em desenvolvimento, mas ainda não publicados: Go, Ruby e Rust. As páginas deles já estão no catálogo de SDKs com uma pré-visualização do comando de instalação; quando o pacote sair no registry, o estado passa a “disponível”.

1. Chave em dashboard/sign-up: 10 000 créditos por mês grátis
2. Instala o SDK na tua linguagem (comandos acima)
3. Primeira chamada: o mapa natal do snippet acima, com a tua chave em ASTROWAY_API_KEY

A lista completa de SDKs, com exemplos para cada um, está na página SDK.