8 lines
2.2 KiB
Markdown
8 lines
2.2 KiB
Markdown
# 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.
|