@a1local/astro-adpages

Astro integration scaffold for AdPages local SEO and landing-page QA. This package is intentionally dependency-free for now: it does not import Astro types, does not depend on @a1local/adpages-audit-core, and can be checked by the root TypeScript lint before the workspace is wired together.

What is included

• adpagesAstro() returns a minimal Astro integration-shaped object with a no-op setup hook.
• buildLocalBusinessSchemaData() creates LocalBusiness JSON-LD data that can be rendered from an Astro component.
• checkAstroPageMetadata() checks frontmatter-like objects for practical local SEO metadata.
• buildServiceAreaPageMatrix() creates a service-by-area landing page matrix for local SEO planning.

Planned Astro wiring

When this package is ready to be connected to Astro directly, it can be used from astro.config.mjs:

import { defineConfig } from "astro/config";
import adpages from "@a1local/astro-adpages";

export default defineConfig({
  integrations: [
    adpages({
      business: {
        name: "Example Plumbing",
        businessType: "Plumber",
        telephone: "+61 8 0000 0000",
        areaServed: ["Perth", "Fremantle", "Joondalup"]
      }
    })
  ]
});

The current factory avoids Astro imports so it can compile in this repository before the Astro dependency and package workspace are added. Later hook work can generate virtual modules, validate content collections, or run @a1local/adpages-audit-core checks during astro:build:done.

LocalBusiness schema data

Use the helper to prepare data for an Astro component without coupling this package to .astro files:

import { buildLocalBusinessSchemaData } from "@a1local/astro-adpages";

const schemaData = buildLocalBusinessSchemaData(
  {
    name: "Example Plumbing",
    businessType: "Plumber",
    url: "https://example.com",
    telephone: "+61 8 0000 0000",
    areaServed: ["Perth"],
    services: ["Emergency plumbing", "Blocked drains"]
  },
  { pretty: true }
);

In Astro, that data can later be rendered with a small project component:

<script type={schemaData.script.type} set:html={schemaData.script.json}></script>

Metadata checklist

checkAstroPageMetadata() accepts plain objects shaped like Astro frontmatter:

import { checkAstroPageMetadata } from "@a1local/astro-adpages";

const result = checkAstroPageMetadata({
  title: "Emergency Plumber in Perth | Example Plumbing",
  description: "Fast emergency plumbing support for Perth homes and businesses.",
  canonical: "https://example.com/plumber/perth/",
  serviceArea: "Perth"
});

The result contains ok, score, missing, warnings, and per-check items that can be surfaced in a dev overlay, CLI report, or build log.

Service area matrix

Use buildServiceAreaPageMatrix() to plan landing pages before content generation:

import { buildServiceAreaPageMatrix } from "@a1local/astro-adpages";

const matrix = buildServiceAreaPageMatrix({
  basePath: "/services",
  services: ["Blocked drains", "Hot water repairs"],
  areas: ["Perth", "Fremantle"],
  pathPattern: "{service}/{area}",
  defaultStatus: "draft"
});

This returns normalized services, areas, URL paths, titles, descriptions, and grouped lookup maps.

Monetisation surface

The integration options reserve a monetization block for later product work:

adpages({
  monetization: {
    enabled: true,
    plan: "agency",
    auditUpsellUrl: "https://adpages.example/upgrade",
    leadCaptureUrl: "https://adpages.example/leads"
  }
});

Good places for monetisation are the hosted audit report, gated export formats, agency-level service-area matrix generation, white-label schema components, and lead capture from failed QA checks. The package should keep these decisions in integration options or generated UI modules rather than hard-coding billing logic into pure helpers.