# Changelog
All notable changes to this project will be documented in this file.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.2.1] — 2025-03-16
### Added
#### API
- `Aurinko.Auth` — OAuth authorization URL builder, code exchange, and token refresh
- `Aurinko.APIs.Email` — List, get, send, draft, update messages; delta sync; attachments; email tracking
- `Aurinko.APIs.Calendar` — List/get calendars and events; create/update/delete events; delta sync; free/busy
- `Aurinko.APIs.Contacts` — CRUD contacts; delta sync
- `Aurinko.APIs.Tasks` — Task list and task management (list, create, update, delete)
- `Aurinko.APIs.Webhooks` — Subscription management (list, create, delete)
- `Aurinko.APIs.Booking` — Booking profile listing and availability
- `Aurinko.Types` — Typed structs for Email, CalendarEvent, Calendar, Contact, Task, Pagination, SyncResult
- `Aurinko.Error` — Structured, tagged error type with HTTP status mapping
- `Aurinko.HTTP.Client` — Req-based HTTP client with retry, backoff, and connection pooling
- `Aurinko.Telemetry` — `:telemetry` events for all HTTP requests
- `Aurinko.Config` — NimbleOptions-validated configuration
- Full typespecs and `@moduledoc`/`@doc` coverage
- GitHub Actions CI with matrix testing (Elixir 1.16/1.17, OTP 26/27)
- Credo strict linting and Dialyzer integration
#### Middleware & Infrastructure
- **`Aurinko.Cache`** — ETS-backed TTL response cache for all `GET` requests
- Configurable TTL (default 60 s), max size (default 5 000 entries), and cleanup interval
- LRU eviction when the entry limit is reached
- Per-token cache invalidation via `invalidate_token/1`
- Hit/miss/eviction statistics via `stats/0`
- SHA-256 cache key derivation from `{token, path, params}`
- `get/1`, `put/3`, `delete/1`, `flush/0`, `build_key/3` public API
- **`Aurinko.RateLimiter`** — Token-bucket rate limiter with dual buckets
- Per-token bucket (default 10 req/s) and global bucket (default 100 req/s)
- Configurable burst allowance (default +5 over steady-state)
- Returns `:ok` or `{:wait, ms}` — the HTTP client sleeps and continues automatically
- `check_rate/1`, `reset_token/1`, `inspect_bucket/1` public API
- ETS-backed buckets with automatic cleanup of stale entries after 5 min of inactivity
- **`Aurinko.CircuitBreaker`** — Per-endpoint circuit breaker (closed → open → half-open)
- Configurable failure threshold (default 5) and recovery timeout (default 30 s)
- Tracks `server_error`, `network_error`, and `timeout` failure types; ignores `not_found` etc.
- Half-open probe on timeout expiry; re-opens on probe failure, closes on probe success
- `call/2`, `status/1`, `reset/1` public API
- ETS-backed state machine; named per normalised URL path (IDs replaced with `:id`)
#### HTTP Client (rewritten)
- **`Aurinko.HTTP.Client`** — Req 0.5-based HTTP client with full middleware pipeline
- Pipeline order: Rate Limiting → Cache Lookup → Circuit Breaker → HTTP + Retry → Cache Write → Telemetry
- Exponential backoff with jitter for `429` and `5xx` responses
- `Retry-After` header parsing for `429` responses
- Structured `%Aurinko.Error{}` on all failure paths (no raw exceptions leak)
- Request packing via `req_info` map to keep internal function arities ≤ 8
- `get/3`, `post/4`, `patch/4`, `put/4`, `delete/3` public API
#### Streaming Pagination
- **`Aurinko.Paginator`** — Lazy `Stream`-based pagination for all list endpoints
- `stream/3` — streams records across all pages on demand, never loading all into memory
- `sync_stream/4` — streams delta-sync records; captures `next_delta_token` via `:on_delta` callback
- `collect_all/3` — synchronous convenience wrapper returning `{:ok, list}`
- Configurable `:on_error` — `:halt` (default) or `:skip` per-page error handling
#### Sync Orchestrator
- **`Aurinko.Sync.Orchestrator`** — High-level delta-sync lifecycle manager
- `sync_email/2` — full or incremental email sync; resolves or provisions delta tokens automatically
- `sync_calendar/3` — calendar sync with configurable `time_min`/`time_max` window
- `sync_contacts/2` — contacts sync (updated records only; no deleted stream)
- Accepts `:get_tokens`, `:save_tokens`, `:on_updated`, `:on_deleted` callbacks
- Automatic retry with backoff when Aurinko sync is not yet `:ready`
- Records are delivered in batches of 200 via `Stream.chunk_every/2`
#### Webhook Support
- **`Aurinko.Webhook.Verifier`** — HMAC-SHA256 signature verification
- `verify/3` — validates `sha256=<hex>` signature header; returns `:ok` or `{:error, :invalid_signature}`
- `sign/2` — test helper for generating valid signatures
- Constant-time comparison via `:crypto.hash/2` to prevent timing attacks (no `plug_crypto` dependency)
- **`Aurinko.Webhook.Handler`** — Behaviour + dispatcher for webhook event processing
- `dispatch/4` — parses raw body, optionally verifies signature, routes `eventType` to handler module
- `@callback handle_event/3` behaviour for implementing custom handlers
#### Observability
- **`Aurinko.Telemetry`** (expanded) — 7 telemetry events now emitted
- `[:aurinko, :request, :start]` — before each HTTP request
- `[:aurinko, :request, :stop]` — after each HTTP request (includes duration, cached flag)
- `[:aurinko, :request, :retry]` — on each retry attempt (includes reason: `:rate_limited`, `:server_error`, `:timeout`)
- `[:aurinko, :circuit_breaker, :opened]` — when a circuit opens (threshold exceeded or probe failure)
- `[:aurinko, :circuit_breaker, :closed]` — when a circuit recovers
- `[:aurinko, :circuit_breaker, :rejected]` — when a request is rejected by an open circuit
- `[:aurinko, :sync, :complete]` — after a full sync run (updated count, deleted count, duration)
- `attach_default_logger/0` and `detach_default_logger/0` for zero-config structured logging
- `Telemetry.Metrics` definitions for Prometheus / StatsD reporters
- **`Aurinko.Logger.JSONFormatter`** — Structured JSON log formatter
- One JSON object per log line: `time`, `level`, `msg`, `pid`, `module`, `function`, `line`, `request_id`
- Compatible with Datadog, Loki, Google Cloud Logging, and other log aggregation pipelines
- Plug-in via `config :logger, :console, format: {Aurinko.Logger.JSONFormatter, :format}`
#### OTP Application
- **`Aurinko.Application`** — Supervised OTP application with ordered start-up
- Supervision order: Cache → RateLimiter → CircuitBreaker → HTTP.Client → Telemetry
- Fail-fast config validation on start (raises `Aurinko.ConfigError` if credentials missing)
- Structured startup summary logged at `:info` level
- 5-second graceful shutdown timeout per child
#### Configuration (expanded)
- `Aurinko.Config` extended with new validated keys (all via `NimbleOptions`):
- Cache: `:cache_enabled`, `:cache_ttl`, `:cache_max_size`, `:cache_cleanup_interval`
- Rate limiter: `:rate_limiter_enabled`, `:rate_limit_per_token`, `:rate_limit_global`, `:rate_limit_burst`
- Circuit breaker: `:circuit_breaker_enabled`, `:circuit_breaker_threshold`, `:circuit_breaker_timeout`
- Telemetry: `:attach_default_telemetry`
- `Config.merge/2` utility for per-request config overrides
#### Developer Experience
- **Guides** — `guides/getting_started.md` and `guides/advanced.md` added to ExDoc
- **CI** extended — Credo strict, Dialyzer, and ExCoveralls added as required checks
- Elixir 1.16 / OTP 26 and Elixir 1.17 / OTP 27 matrix
- Lint, format check, and Dialyzer run as separate CI jobs
- New `mix` aliases: `lint`, `test.all`, `quality`
- `config/staging.exs` — staging environment config with JSON logging pre-configured
- `config/runtime.exs` — runtime config reading all settings from environment variables
### Changed
- `Aurinko.HTTP.Client` completely rewritten — previously a thin `Req` wrapper; now a full GenServer with the middleware pipeline described above
- `Aurinko.Telemetry` expanded from request-only events to 7 events covering the full request lifecycle, circuit breaker state changes, and sync completion
- `Aurinko.Config` schema extended; `load!/0` now strips unknown application env keys before validation to avoid conflicts with middleware config keys
- All API functions (`Email`, `Calendar`, `Contacts`, `Tasks`, `Webhooks`, `Booking`) now route through the full middleware pipeline automatically
### Fixed
- Dialyzer: removed unreachable `is_list` guard clause from `get_header/2` (Req 0.5 always returns headers as a map)
- Dialyzer: narrowed `@spec format/4` return in `JSONFormatter` from `iodata()` to `binary()`
- Dialyzer: removed `{:error, :rate_limit_exceeded}` from `RateLimiter` type and spec (function never returns it)
- Dialyzer: narrowed `@spec events/0` in `Telemetry` from `list(list(atom()))` to `nonempty_list(nonempty_list(atom()))`
- Webhook verifier: replaced `Plug.Crypto.secure_compare/2` (undeclared dependency) with a self-contained `:crypto`-based constant-time comparison
---
## [0.1.0] — 2025-06-01
### Added
- Initial release with Starter Boilerplate elxir app
