2.2 KiB
SEO tracking contract v2 (local implementation)
Base /api/admin/seo-tracking, existing JWT or API key authentication mandatory, admin role (API keys require admin scope). No new unauthenticated worker path.
GET list page integer 1..100000, limit 1..100, status enum, sortBy createdAt|updatedAt|title|status, sortOrder asc|desc; returns data and standard meta. GET /:uuid returns finding including version, feedbackVersion, blog, snapshots.
POST finding: title,hypothesis,targetKeywords[],primaryKeyword,expectedOutcome required; optional blogId UUID, status, goalMetric (metric name), goalTarget nonnegative, actionId external reference. PATCH /:id feedback: {feedback:string, expectedVersion:integer>=0} required; atomic claim advances version and feedbackVersion; stale 409; return updated finding. Clearing feedback uses empty string and advances version.
PATCH /:id/action: {expectedVersion, feedbackVersion, blogId?, actionId?, status?}; atomic finding version AND feedbackVersion claim. Feedback present requires acknowledgement of exact feedbackVersion. This protects this endpoint; existing blog publishers are NOT automatically integrated and must consume this contract before claiming enforcement.
POST /:id/snapshots: ingestionKey string <=128, periodStart/periodEnd ISO timestamps (start<end), sourceMetadata object with gsc,ga4,commerce each {status: available|unavailable|error, source:string, fetchedAt:ISO timestamp, error?:string}; optional metric fields. Metrics absent/null remain null, actual zero remains zero. All non-available source metrics MUST be null/omitted. Available sources require all their metrics except ga4ScrollDepthRate (optional if uninstrumented). Counts integer >=0, rates [0,1], other metrics >=0 finite. Key unique per finding: identical retry returns existing; changed payload same key returns 409. No revenue inferred from aggregate orders. No recommendations from incomplete data; ingestion accepts optional recommendation only with all sources available.
Legacy snapshots with null provenance are unverified historical data, not measured zero. Legacy findings require normalized searchText backfill before normalized search can be complete. No live migration/scheduling/deployment authorized.