README de los SDK

# SDKs oficiales de PietroCal API v1

Clientes livianos y sin dependencias externas para PHP, JavaScript y Python.

## Seguridad

Usá tokens `pc_live_...` únicamente en servidores, scripts privados o entornos
controlados. No publiques un Personal Access Token dentro de JavaScript
entregado al navegador.

## Idempotencia automática

Las operaciones de creación compatibles generan automáticamente una
`Idempotency-Key` segura:

- calendarios;
- suscripciones de calendario;
- eventos;
- recordatorios;
- contactos;
- reservas;
- links de disponibilidad personal.

Si la conexión se corta después de enviar una creación, cada SDK realiza como
máximo un reintento de transporte y reutiliza **la misma clave**. PietroCal
puede reproducir la respuesta confirmada sin ejecutar nuevamente el
controlador.

Los SDK no reintentan automáticamente respuestas HTTP. En particular:

- `409 idempotency_conflict` requiere corregir la clave o el payload;
- `409 idempotency_indeterminate` requiere consultar el recurso antes de usar
  otra clave;
- `425 idempotency_in_progress` puede reintentarse más tarde respetando
  `Retry-After`, conservando la misma clave.

Cada respuesta correcta agrega:

```text
idempotency.key
idempotency.replayed
transportAttempts / transport_attempts
```

Para controlar la clave manualmente:

```php
$result = $client->createEvent($event, 'orden-externa-000184');
```

```js
const result = await client.createEvent(event, 'orden-externa-000184');
```

```python
result = client.create_event(event, idempotency_key="orden-externa-000184")
```

También se puede usar `request()` con `idempotencyKey` en PHP/JavaScript o
`idempotency_key` en Python. Para desactivar la generación automática en una
llamada genérica, usar `autoIdempotency: false` o `auto_idempotency=False`.

## PHP

Requiere PHP 8.1+ y la extensión cURL.

```bash
PIETROCAL_API_TOKEN='pc_live_...' php example.php
```

El constructor acepta `maxTransportRetries` como cuarto argumento. El valor
predeterminado es `1` y sólo se usa para creaciones protegidas por una clave
idempotente.

## JavaScript

Funciona con Node.js 18+ o runtimes que incluyan `fetch()`.

```bash
PIETROCAL_API_TOKEN='pc_live_...' node example.mjs
```

El cliente también puede importarse en aplicaciones web con OAuth, pero un
Personal Access Token no debe incorporarse en código público.

## Python

Requiere Python 3.10+ y usa solamente la biblioteca estándar.

```bash
PIETROCAL_API_TOKEN='pc_live_...' python3 example.py
```

## Contrato común

Los tres clientes exponen:

- `profile`;
- `calendars`;
- `events`;
- `tasks`;
- `contacts`;
- `bookings`;
- creación de calendarios, suscripciones, eventos, recordatorios, contactos,
  reservas y links de disponibilidad;
- actualización y eliminación de eventos;
- `request` genérico para cualquier endpoint v1.

Las respuestas incluyen datos, HTTP status, Request ID, rate limiting,
paginación e información idempotente cuando corresponde.

## OAuth 2.1

Se mantienen helpers independientes:

- `php/PietroCalOAuth.php`;
- `javascript/pietrocal-oauth.js`;
- `python/pietrocal_oauth.py`.

Incluyen generación PKCE, URL de autorización, intercambio de code, refresh y
revocación. El almacenamiento seguro de `state`, `code_verifier`, access token
y refresh token sigue siendo responsabilidad de la aplicación integradora.