AGENTS.md@packages/integration-wordpress-traffic git:20260512.224036cA

Immutable. This exact content is served forever at /api/v1/blob/9f3d6608a12586fb.

# integration-wordpress-traffic

## Purpose

WordPress traffic-logger integration — pulls candidate AI traffic events
(crawler hits + AI-referral hits) from the canonry traffic-logger WordPress
plugin's REST endpoint (`/wp-json/canonry/v1/events`) and normalizes them
into provider-neutral `NormalizedTrafficRequest` events for the traffic
ingestion pipeline.

Companion package: `packages/integration-wordpress/` (content-publishing
client) is **separate** — that handles page/SEO/schema management on a WP
site and shares only the Application-Password auth pattern.

## Key Files

| File | Role |
|------|------|
| `src/client.ts` | `listWordpressTrafficEvents` — cursor-paginated pull, `WordpressTrafficApiError` |
| `src/normalize.ts` | `normalizeWordpressTrafficEvent` — converts a plugin event row into a `NormalizedTrafficRequest` |
| `src/types.ts` | Adapter option/response shapes (`WordpressTrafficEventPayload`, `ListWordpressTrafficEventsOptions`, `WordpressTrafficEventsPage`) |
| `src/index.ts` | Re-exports public API |

## Patterns

- **Application-Password auth.** Callers pass a WordPress username + Application
  Password (the same scheme used by `packages/integration-wordpress/`). This
  package base64-encodes them for HTTP Basic auth. Credentials are caller-supplied
  per request — they live in `~/.canonry/config.yaml` under `wordpressTraffic.connections`.
- **Pull-only, cursor-paginated.** `listWordpressTrafficEvents` accepts an opaque
  `cursor` string returned from the previous page (`next_cursor`). No push,
  no SaaS relay.
- **No classification.** This package only pulls + normalizes. UA pattern
  matching and AI-referer detection happen in `packages/integration-traffic`
  alongside Cloud Run events, so classifier rules evolve without plugin updates.
- **IP hashing happens upstream.** The plugin hashes (sha256 prefix) or omits
  client IPs before writing event rows, so this adapter never sees raw IPs.
  Every WordPress event currently stays `claimed_unverified` — IP/rDNS
  verification needs raw IPs and is future work.
- **Provider-neutral output.** Every adapter in the traffic stack emits the
  same `NormalizedTrafficRequest` shape from `@ainyc/canonry-contracts`. Do
  not leak WordPress-specific types past the package boundary.

## Common Mistakes

- **Storing the Application Password in this package.** Credentials live in
  `~/.canonry/config.yaml` and are supplied per call.
- **Adding UA/referer classification here.** All classification lives in
  `packages/integration-traffic` so Cloud Run, WordPress, and future adapters
  share one rule set.
- **Calling `fetch` against the raw `baseUrl`.** Always append
  `/wp-json/canonry/v1/events` — `resolveEndpoint` does this. Hand-rolled URL
  composition will drop trailing slashes or double up paths.

## See Also

- `packages/contracts/src/traffic.ts` — `NormalizedTrafficRequest`,
  `wordpressTrafficSourceConfigSchema`, `trafficConnectWordpressRequestSchema`
- `packages/integration-traffic/` — provider-neutral classifier + hourly rollup
- `packages/integration-cloud-run/` — sibling pull adapter; mirror this file
  layout when adding a new adapter
- `plans/server-side-ai-traffic-ingestion.md` — overall traffic plan