Build an SEO Automation System

src/
  seo/
    graph.ts
    state.ts
    nodes/
      discover-opportunity.ts
      inspect-existing-content.ts
      research-evidence.ts
      build-brief.ts
      draft-locales.ts
      validate-claims.ts
      validate-seo.ts
      request-approval.ts
      publish.ts
      monitor.ts
  content/
    repository.ts
    schemas.ts
  api/seo-jobs.ts
  evals/seo-cases.json
  tests/seo-workflow.test.ts

npm install @langchain/core @langchain/langgraph @openrouter/ai-sdk-provider ai langsmith zod

# Add your application server, CMS adapter and test runner.
# Keep every credential on the server.

# .env.example — placeholders only
OPENROUTER_API_KEY=replace_with_server_side_secret
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
REFERENCE_MODEL_ID=choose_for_your_requirements
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=replace_with_server_side_secret
LANGSMITH_PROJECT=seo-automation-reference
CONTENT_REPOSITORY_URL=replace_with_internal_endpoint
CONTENT_REPOSITORY_TOKEN=replace_with_server_side_secret
PUBLIC_SITE_ORIGIN=https://replace-with-your-domain.example

import { z } from "zod";

export const Opportunity = z.object({
  id: z.string(),
  query: z.string().min(2),
  locale: z.enum(["en", "ar"]),
  intent: z.enum(["informational", "commercial", "navigational"]),
  existingUrls: z.array(z.string().url()),
  decision: z.enum(["create", "refresh", "merge", "reject"]),
  evidenceIds: z.array(z.string()),
  status: z.enum(["discovered", "researched", "drafted", "validated", "approved", "published", "monitoring"])
});

export const Evidence = z.object({
  id: z.string(),
  url: z.string().url(),
  publisher: z.string(),
  title: z.string(),
  retrievedAt: z.string().datetime(),
  excerpt: z.string(),
  supportsClaims: z.array(z.string()),
  authority: z.enum(["primary", "official", "secondary"]),
  locale: z.enum(["en", "ar"])
});

export const Claim = z.object({
  text: z.string(),
  evidenceIds: z.array(z.string()).min(1),
  status: z.enum(["supported", "needs_review", "rejected"])
});

type SeoState = {
  jobId: string;
  opportunity: Opportunity;
  evidence: Evidence[];
  brief?: ContentBrief;
  drafts: Partial<Record<"en" | "ar", Draft>>;
  gates: GateResult[];
  approval?: { by: string; at: string };
  publication?: { urls: string[]; verifiedAt: string };
  lifecycle?: "keep" | "refresh" | "merge" | "noindex";
  errors: Array<{ node: string; safeCode: string }>;
};

const workflow = new StateGraph(SeoState)
  .addNode("eligibility", inspectExistingContent)
  .addNode("research", researchEvidence)
  .addNode("brief", buildBrief)
  .addNode("draft", draftLocales)
  .addNode("claims", validateClaims)
  .addNode("quality", validateSeo)
  .addNode("approval", requestHumanApproval)
  .addNode("publish", publishAndVerify)
  .addConditionalEdges("eligibility", routeEligibility)
  .addEdge("research", "brief")
  .addEdge("brief", "draft")
  .addEdge("draft", "claims")
  .addConditionalEdges("claims", routeGateResult)
  .addConditionalEdges("quality", routeGateResult)
  .addConditionalEdges("approval", routeApproval)
  .addEdge("publish", END);

export const seoGraph = workflow.compile({ checkpointer });

export function decideAction(input: {
  opportunity: Opportunity;
  candidates: ExistingPage[];
}) {
  const sameIntent = input.candidates.filter((page) =>
    page.locale === input.opportunity.locale &&
    page.intent === input.opportunity.intent
  );

  if (sameIntent.some((page) => page.coverage === "strong")) return "reject";
  if (sameIntent.some((page) => page.coverage === "partial")) return "refresh";
  if (sameIntent.length > 1) return "merge";
  return "create";
}

export function validateClaims(draft: Draft, evidence: Evidence[]) {
  const knownEvidence = new Map(evidence.map((item) => [item.id, item]));
  return draft.claims.map((claim) => {
    const sources = claim.evidenceIds.map((id) => knownEvidence.get(id)).filter(Boolean);
    return {
      ...claim,
      status: sources.length > 0 && sources.every(isFreshAndAllowed)
        ? "supported"
        : "needs_review"
    };
  });
}

{
  "jobId": "seo-ref-0042",
  "status": "awaiting_approval",
  "decision": "refresh",
  "locales": ["en", "ar"],
  "gates": {
    "claims": "pass",
    "duplicateIntent": "pass",
    "internalLinks": "pass",
    "metadata": "pass",
    "localization": "pass"
  },
  "previewUrls": ["/preview/en", "/preview/ar"],
  "publishable": false
}

export async function POST(request: Request) {
  const input = StartJobInput.parse(await request.json());
  const job = await repository.create(input);

  try {
    await seoGraph.invoke({ jobId: job.id, opportunity: input });
    return Response.json({ jobId: job.id, status: "started" }, { status: 202 });
  } catch (error) {
    await repository.failSafely(job.id, "WORKFLOW_UNAVAILABLE");
    return Response.json(
      { jobId: job.id, status: "paused", retryable: true },
      { status: 503 }
    );
  }
}

const cases = [
  ["strong existing page", "reject"],
  ["partial same-intent page", "refresh"],
  ["unsupported claim", "block_publish"],
  ["Arabic draft changes the claim", "block_publish"],
  ["CMS accepts but public URL is 404", "fail_verification"],
  ["traffic decays after publication", "refresh_review"]
];

test.each(cases)("%s", async (scenario, expected) => {
  expect(await runFixture(scenario)).toEqual(expected);
});