Save this content to: .cursor/rules/project.mdc

# Talaria PHP SDK

Composer monorepo. Primary packages: `talaria/talaria` (core), `talaria/silverstripe`, `talaria/laravel`.

## Role

```
App → TalariaClient
        ├─ capture* / Logger     → EventQueue     → POST /v1/events
        ├─ Tracer (optional APM) → SpanQueue      → POST /v1/spans
        └─ analytics             → AnalyticsQueue → POST /v1/analytics
```

- Fingerprinting and issue grouping are **server-side only** — never compute fingerprints here
- Auth: `Authorization: Bearer` with a checksummed `tal_(pk|sk)_<env>_<cell>_<43 base62><6 CRC32 base62>` key (`<env>` is `prod|stg|test|dev`). Servers use `tal_sk_`; the browser inject uses `tal_pk_`. The ingest host is `https://ingest-<cell>.newtalaria.com` unless `url` / `TALARIA_URL` is set
- Always send via **batch** ingest; never one HTTP call per log or span in the normal path
- Never wrap `ServerpodHttpTransport` or `SpanTransport` Guzzle clients with tracing middleware
- No billing APIs; treat 429 carefully (quota vs rate limit)

## Package map

| Path | Composer | Role |
| ---- | -------- | ---- |
| `packages/talaria/` | [`talaria/talaria`](https://packagist.org/packages/talaria/talaria) | Framework-agnostic SDK (`Talaria\`); Packagist mirror `newtalaria/talaria-php` |
| `packages/silverstripe/` | [`talaria/silverstripe`](https://packagist.org/packages/talaria/silverstripe) | Silverstripe vendormodule (`Talaria\SilverStripe\`); mirror `newtalaria/talaria-silverstripe` |
| `packages/laravel/` | [`talaria/laravel`](https://packagist.org/packages/talaria/laravel) | Laravel adapter (`Talaria\Laravel\`); mirror `newtalaria/talaria-laravel` |

## Vocabulary

| Term | SDK responsibility |
| ---- | --- |
| Event | Build wire JSON (message, level, stack, tags, extra, release) |
| level | Severity: `debug` \| `info` \| `warning` \| `error` \| `fatal` |
| eventType | Derived from level when omitted (`fatal`/`error` → `error`) |
| sampleRate | Client-side event sampling before enqueue |
| enableTracing / tracesSampleRate | APM off until enabled; head-based span sampling (100% errors, default 10% success) |
| enableAnalytics | Product analytics. Core default on; Silverstripe YAML / `TALARIA_ENABLE_ANALYTICS` default off |

## Sources of truth

- Live ingest: Talaria `/v1` routes (`POST /v1/events`, `/v1/spans`, `/v1/analytics`, `GET /v1/sdk-config`, `/v1/flags`, `POST /v1/client-reports`). Plain JSON, no `input` wrapper; errors are `application/problem+json`
- Parity reference: `@newtalaria/browser` transport (same camelCase wire fields)

## Tests at end of work

After any implementation, run PHPUnit in each touched package (`packages/talaria`, `packages/silverstripe`, `packages/laravel`) and report the command plus result. Do not assume green.

## Explicit don'ts

- Do not compute fingerprints
- Do not send one HTTP call per event, span or analytics item — always batch
- Do not retry unbounded on 429
- Do not import Silverstripe or Laravel types from `packages/talaria/src/`
- Do not pin `psr/log` to `^3` only (breaks SS4 and some SS5 resolves)
- Do not Composer-autoload Monolog-specific handler classes
- Do not type `Talaria\Logger::log()` `$message` / `$level` (breaks psr/log 1.x `LoggerInterface`)

## Fail safe (Talaria workspace D19)

Decided by Heath (2026-11-03): "having an invalid Talaria key shouldnt stop the site from building. It should just stop Talaria working". That is the default for every SDK. Full rule: `.cursor/skills/sdk-fail-safe/SKILL.md` in `dunatron/talaria-workspace`.

- Init never throws. A missing, empty, malformed, wrong-checksum or revoked key, or any bad init option, builds a disabled no-op client. Every public method returns normally and sends nothing.
- Log one warning per process, showing at most the key's first 8 characters.
- Keep the key grammar strict. A parse failure disables Talaria. It is never an exception the host app sees.
- Transport errors (4xx, 5xx, timeouts, DNS, TLS) never reach host code. Log them rate-limited.
- Framework hooks (factories, providers, middleware, log handlers, error hooks) catch their own Talaria errors, so a Talaria fault never becomes a 500 or a crash.
- Builds and install steps never fail because of Talaria.
- Tests: no key, empty key, malformed key, wrong checksum and bad option each give no throw, a no-op client and one warning. Transport 401, 500 and timeout never reach the caller.