@orion-studios/payload-seo-audit 1.1.5-beta.0 → 1.2.0-beta.0

package/README.md

@@ -1,130 +1,37 @@
 # @orion-studios/payload-seo-audit
 
-Professional SEO audit system for Payload CMS 3.0 + Next.js 15 projects.
+`payload-seo-audit` is the optional SEO add-on for Orion's studio-first website stack.
 
-## Features
+## Start Here
 
-- 🔍 **Comprehensive SEO Analysis** - Crawls your site and checks 50+ SEO factors
-- 📊 **Visual Dashboard** - Admin UI with scores, trends, issues, and CrUX metrics
-- 🎯 **Category Scoring** - Metadata, indexability, structure, links, media, structured data, performance
-- 📈 **Trend Tracking** - Monitor SEO performance over time
-- ⚡ **Performance Integrations** - Google PageSpeed + Chrome UX Report (CrUX)
-- 🔎 **Search Visibility Sync** - Google Search Console keyword visibility imports
-- 🔗 **Authority Snapshots** - DataForSEO authority/backlink snapshots with run policy controls
-- 🔄 **Auto-Trigger** - Optionally run audits when content is published
-- 🔐 **Encrypted Integration Settings** - Credentials managed in Payload admin (with env fallback)
-- 📄 **PDF Export** - Download snapshot reports
+Build the base site first:
 
-## Quick Start
+- [Studio Website Setup Guide](../payload-studio/docs/studio-website-setup-guide.md)
 
-### Installation
+Then layer SEO:
 
-```bash
-npm install @orion-studios/payload-seo-audit
-```
+- [SEO Studio Add-on Guide](./INTEGRATION.md)
 
-### Setup (10-15 minutes)
+## Install
 
 ```bash
-# 1. Run the automated setup tool
-npx payload-seo-audit init
-
-# 2. Configure required environment variables (.env.local)
-SEO_AUDIT_SECRET=<random-secret-key>
-NEXT_PUBLIC_SERVER_URL=https://your-site.com
-
-# 3. Add plugin to payload.config.ts (see below)
-
-# 4. Generate types and start dev server
-npx payload generate:types
-npm run dev
+npm install @orion-studios/payload-seo-audit
 ```
 
-### Plugin Configuration
-
-Add to your `payload.config.ts`:
+## Studio Integration
 
-```typescript
-import { seoAuditPlugin } from '@orion-studios/payload-seo-audit'
+Prefer the dedicated studio subpath:
 
-export default buildConfig({
-  plugins: [
-    seoAuditPlugin({
-      site: {
-        name: 'Your Site Name',
-        domain: 'www.yoursite.com',
-        canonicalHost: 'https://www.yoursite.com',
-        sitemapURL: 'https://www.yoursite.com/sitemap.xml',
-        keyURLs: ['https://www.yoursite.com', 'https://www.yoursite.com/about'],
-      },
-      crawl: {
-        maxPages: 120,
-        maxDepth: 2,
-        excludePatterns: ['/admin', '/api', '?preview='],
-      },
-      triggers: {
-        collections: ['posts', 'pages'],
-        globals: ['home'],
-      },
-      access: (user) => user?.role === 'admin',
-      integrations: {
-        enablePageSpeed: true,
-        enableSearchConsole: false,
-        enableCrUX: false,
-      },
-    }),
-  ],
-})
+```ts
+import { createSeoStudioExtension } from '@orion-studios/payload-seo-audit/studio'
 ```
 
-### Configure API Integrations in Admin
-
-After startup, open:
-
-- `/admin/globals/seo-integrations`
-
-From there you can securely configure:
+## Styling Contract
 
-- Google Search Console (OAuth or service account)
-- PageSpeed API key
-- CrUX API key and query scope
-- DataForSEO credentials + run policy
-- Private operator webhook settings
+Import the package CSS once in your admin-facing layout or bundle entry:
 
-Secrets are encrypted at rest and masked in the admin form.
-
-### Usage
-
-1. Visit `/admin/globals/seo-dashboard`
-2. Click **Run Audit Now**
-3. Review scores, issues, trends, and CrUX field data
-4. Open snapshots for detailed reports and exports
-
-## Environment Variable Fallbacks
-
-If `seo-integrations` is not configured yet, these env vars are used as fallback:
-
-- `SEO_GSC_CLIENT_ID`
-- `SEO_GSC_CLIENT_SECRET`
-- `SEO_GSC_REDIRECT_URI`
-- `SEO_GSC_REFRESH_TOKEN`
-- `GOOGLE_SERVICE_ACCOUNT_EMAIL`
-- `GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY`
-- `SEO_PAGESPEED_API_KEY`
-- `SEO_CRUX_API_KEY`
-- `SEO_DATAFORSEO_LOGIN`
-- `SEO_DATAFORSEO_PASSWORD`
-- `SEO_DATAFORSEO_BASE_URL`
-
-## Documentation
-
-- **[Integration Guide](./INTEGRATION.md)** - Full setup and troubleshooting
-- **[Troubleshooting](./INTEGRATION.md#troubleshooting)** - Common issues and fixes
-
-## License
-
-MIT License
-
-## Author
+```ts
+import '@orion-studios/payload-seo-audit/styles.css'
+```
 
-Built by Orion Studios
+This package now ships its own compiled styles and no longer requires consumer Tailwind scanning or `tailwind.config` edits.

package/bin/init.js

@@ -15,8 +15,6 @@ const ROUTES = [
   { path: 'backlinks/import/route.ts', method: 'POST', handler: 'handleSeoBacklinksImport' },
 ]
 
-const PLUGIN_PATH = './node_modules/@orion-studios/payload-seo-audit/dist/**/*.js'
-
 console.log('🔧 SEO Audit Plugin Setup\n')
 console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n')
 
@@ -39,103 +37,14 @@ function findApiDirectory() {
   return path.join(cwd, 'src/app/api')
 }
 
-// Find Tailwind config file
-function findTailwindConfig() {
-  const cwd = process.cwd()
-  const possibleConfigs = [
-    path.join(cwd, 'tailwind.config.ts'),
-    path.join(cwd, 'tailwind.config.js'),
-    path.join(cwd, 'tailwind.config.mjs'),
-  ]
-
-  for (const configPath of possibleConfigs) {
-    if (fs.existsSync(configPath)) {
-      return configPath
-    }
-  }
-
-  return null
-}
-
-// Update Tailwind config to include plugin path
-function updateTailwindConfig(configPath) {
-  try {
-    let content = fs.readFileSync(configPath, 'utf-8')
-    let updated = false
-
-    // Check if plugin path already exists
-    if (content.includes(PLUGIN_PATH)) {
-      console.log('✓ Tailwind config already includes plugin path')
-    } else {
-      // Find the content array and add the plugin path
-      const contentArrayRegex = /content\s*:\s*\[([^\]]*)\]/s
-      const match = content.match(contentArrayRegex)
-
-      if (!match) {
-        console.log('⚠️  Could not find content array in Tailwind config')
-        console.log('   Please manually add to tailwind.config.ts:')
-        console.log(`   content: [..., '${PLUGIN_PATH}']`)
-        return false
-      }
-
-      // Extract existing content array items
-      const existingContent = match[1].trim()
-
-      // Add plugin path to the end
-      const newContent = existingContent
-        ? `${existingContent},\n    '${PLUGIN_PATH}',`
-        : `'${PLUGIN_PATH}',`
-
-      // Replace the content array
-      content = content.replace(
-        contentArrayRegex,
-        `content: [\n    ${newContent}\n  ]`
-      )
-
-      updated = true
-      console.log('✓ Updated Tailwind config with plugin path')
-    }
-
-    // Check darkMode configuration
-    const hasDarkModeConfig = content.match(/darkMode\s*:\s*\[['"]selector['"]\s*,\s*['"]\[data-theme="dark"\]['"]\]/)
-
-    if (!hasDarkModeConfig) {
-      console.log('⚠️  Dark mode configuration may be incorrect')
-      console.log('   For proper dark mode support, your tailwind.config should have:')
-      console.log(`   darkMode: ['selector', '[data-theme="dark"]'],`)
-      console.log('')
-      console.log('   This ensures compatibility with both your frontend and Payload admin.')
-      console.log('   See INTEGRATION.md for more details.')
-      updated = true // Flag that manual review is needed
-    } else {
-      console.log('✓ Dark mode configuration is correct')
-    }
-
-    // Write back to file if updated
-    if (updated && content !== fs.readFileSync(configPath, 'utf-8')) {
-      fs.writeFileSync(configPath, content)
-    }
-
-    return true
-
-  } catch (error) {
-    console.log('⚠️  Error updating Tailwind config:', error.message)
-    console.log('   Please manually add to tailwind.config.ts:')
-    console.log(`   content: [..., '${PLUGIN_PATH}']`)
-    console.log(`   darkMode: ['selector', '[data-theme="dark"]'],`)
-    return false
-  }
-}
-
 // Generate route template
 function generateRouteTemplate(route) {
   return `import { NextRequest } from 'next/server'
-import { getPayload } from '@/utilities/getPayload'
+import { getPayloadClient } from '@/lib/payload'
 import { ${route.handler} } from '@orion-studios/payload-seo-audit/api'
 
 export async function ${route.method}(request: NextRequest) {
-  const payload = await getPayload()
-  // @ts-expect-error - Peer dependency type mismatch between plugin and parent payload
+  const payload = await getPayloadClient()
   return ${route.handler}(payload, request)
 }
 `
@@ -197,26 +106,8 @@ try {
     console.log(`   ℹ Skipped ${skippedCount} existing route${skippedCount !== 1 ? 's' : ''}`)
   }
 
-  // Step 2: Update Tailwind config
-  console.log('\nStep 2: Updating Tailwind configuration\n')
-
-  const tailwindConfigPath = findTailwindConfig()
-
-  if (tailwindConfigPath) {
-    console.log(`   📄 Found: ${path.basename(tailwindConfigPath)}`)
-    const updated = updateTailwindConfig(tailwindConfigPath)
-
-    if (!updated) {
-      console.log('\n   ⚠️  IMPORTANT: Dark mode styles will NOT work without this!')
-    }
-  } else {
-    console.log('   ⚠️  No Tailwind config found')
-    console.log('   If using Tailwind, manually add:')
-    console.log(`   content: [..., '${PLUGIN_PATH}']`)
-  }
-
-  // Step 3: Check environment setup
-  console.log('\nStep 3: Environment variable check\n')
+  // Step 2: Check environment setup
+  console.log('\nStep 2: Environment variable check\n')
 
   const { hasSecret, hasServerUrl } = checkEnvironmentSetup()
 
@@ -252,9 +143,12 @@ try {
   }
 
   console.log(`   ${!hasSecret || !hasServerUrl ? '2' : '1'}. Configure the plugin in payload.config.ts`)
-  console.log(`   ${!hasSecret || !hasServerUrl ? '3' : '2'}. Run: npx payload generate:types`)
-  console.log(`   ${!hasSecret || !hasServerUrl ? '4' : '3'}. Start dev server: npm run dev`)
-  console.log(`   ${!hasSecret || !hasServerUrl ? '5' : '4'}. Visit: /admin/globals/seo-dashboard`)
+  console.log(`   ${!hasSecret || !hasServerUrl ? '3' : '2'}. Register createSeoStudioExtension() from @orion-studios/payload-seo-audit/studio if you use the custom Studio nav`)
+  console.log(`   ${!hasSecret || !hasServerUrl ? '4' : '3'}. Import @orion-studios/payload-seo-audit/styles.css in your admin-facing layout`)
+  console.log(`   ${!hasSecret || !hasServerUrl ? '5' : '4'}. Ensure src/lib/payload.ts exports getPayloadClient()`)
+  console.log(`   ${!hasSecret || !hasServerUrl ? '6' : '5'}. Run: npx payload generate:types`)
+  console.log(`   ${!hasSecret || !hasServerUrl ? '7' : '6'}. Start dev server: npm run dev`)
+  console.log(`   ${!hasSecret || !hasServerUrl ? '8' : '7'}. Visit: /admin/globals/seo-dashboard`)
 
   console.log('\n💡 Documentation: See INTEGRATION.md for detailed setup guide')
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n')

package/dist/api/index.d.mts

@@ -0,0 +1,86 @@
+import { Payload } from 'payload';
+import { NextRequest, NextResponse } from 'next/server';
+
+declare function handleSeoRun(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoRunStream(payload: Payload, request: NextRequest): Promise<Response>;
+
+declare function handleSeoSnapshots(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoSnapshotReport(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoPageResults(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoPageResult(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoTrend(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoCron(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoBacklinksImport(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+type SEOIssueSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+type SEOPageScore = {
+    metadata: number;
+    indexability: number;
+    structure: number;
+    links: number;
+    media: number;
+    structuredData: number;
+    performance: number;
+    overall: number;
+};
+
+type SeoApiErrorResponse = {
+    error: string;
+};
+type SeoRunResponse = {
+    completedAt: string;
+    issueCounts: Record<SEOIssueSeverity, number>;
+    overallScore: number;
+    pagesChecked: number;
+    snapshotID: number | string;
+    status: 'completed';
+    success: true;
+};
+type SeoSnapshotsResponse = {
+    latestIssues: Array<{
+        message?: string;
+        recommendation?: string;
+        severity?: string;
+        url?: string;
+    }>;
+    snapshots: Array<Record<string, unknown>>;
+};
+type SeoTrendResponse = {
+    points: Array<{
+        issueCounts: Record<string, unknown>;
+        metrics: Record<string, unknown>;
+        runLabel: string;
+        scores: Partial<SEOPageScore>;
+        snapshotId: number | string;
+        startedAt: string;
+    }>;
+};
+type SeoPageResultsResponse = {
+    docs: Array<Record<string, unknown>>;
+    hasNextPage?: boolean;
+    hasPrevPage?: boolean;
+    limit?: number;
+    nextPage?: number | null;
+    page?: number;
+    prevPage?: number | null;
+    totalDocs?: number;
+    totalPages?: number;
+};
+type SeoPageResultResponse = Record<string, unknown>;
+type SeoSnapshotReportResponse = Record<string, unknown>;
+type SeoCronResponse = {
+    runType: string;
+    success: true;
+} & Record<string, unknown>;
+type SeoBacklinksImportResponse = {
+    success: true;
+} & Record<string, unknown>;
+
+export { type SeoApiErrorResponse, type SeoBacklinksImportResponse, type SeoCronResponse, type SeoPageResultResponse, type SeoPageResultsResponse, type SeoRunResponse, type SeoSnapshotReportResponse, type SeoSnapshotsResponse, type SeoTrendResponse, handleSeoBacklinksImport, handleSeoCron, handleSeoPageResult, handleSeoPageResults, handleSeoRun, handleSeoRunStream, handleSeoSnapshotReport, handleSeoSnapshots, handleSeoTrend };

package/dist/api/index.d.ts

@@ -1,10 +1,86 @@
-export { handleSeoRun } from './run';
-export { handleSeoRunStream } from './run-stream';
-export { handleSeoSnapshots } from './snapshots';
-export { handleSeoSnapshotReport } from './snapshot-report';
-export { handleSeoPageResults } from './page-results';
-export { handleSeoPageResult } from './page-result';
-export { handleSeoTrend } from './trend';
-export { handleSeoCron } from './cron';
-export { handleSeoBacklinksImport } from './backlinks-import';
-//# sourceMappingURL=index.d.ts.map
+import { Payload } from 'payload';
+import { NextRequest, NextResponse } from 'next/server';
+
+declare function handleSeoRun(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoRunStream(payload: Payload, request: NextRequest): Promise<Response>;
+
+declare function handleSeoSnapshots(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoSnapshotReport(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoPageResults(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoPageResult(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoTrend(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoCron(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+declare function handleSeoBacklinksImport(payload: Payload, request: NextRequest): Promise<NextResponse>;
+
+type SEOIssueSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+type SEOPageScore = {
+    metadata: number;
+    indexability: number;
+    structure: number;
+    links: number;
+    media: number;
+    structuredData: number;
+    performance: number;
+    overall: number;
+};
+
+type SeoApiErrorResponse = {
+    error: string;
+};
+type SeoRunResponse = {
+    completedAt: string;
+    issueCounts: Record<SEOIssueSeverity, number>;
+    overallScore: number;
+    pagesChecked: number;
+    snapshotID: number | string;
+    status: 'completed';
+    success: true;
+};
+type SeoSnapshotsResponse = {
+    latestIssues: Array<{
+        message?: string;
+        recommendation?: string;
+        severity?: string;
+        url?: string;
+    }>;
+    snapshots: Array<Record<string, unknown>>;
+};
+type SeoTrendResponse = {
+    points: Array<{
+        issueCounts: Record<string, unknown>;
+        metrics: Record<string, unknown>;
+        runLabel: string;
+        scores: Partial<SEOPageScore>;
+        snapshotId: number | string;
+        startedAt: string;
+    }>;
+};
+type SeoPageResultsResponse = {
+    docs: Array<Record<string, unknown>>;
+    hasNextPage?: boolean;
+    hasPrevPage?: boolean;
+    limit?: number;
+    nextPage?: number | null;
+    page?: number;
+    prevPage?: number | null;
+    totalDocs?: number;
+    totalPages?: number;
+};
+type SeoPageResultResponse = Record<string, unknown>;
+type SeoSnapshotReportResponse = Record<string, unknown>;
+type SeoCronResponse = {
+    runType: string;
+    success: true;
+} & Record<string, unknown>;
+type SeoBacklinksImportResponse = {
+    success: true;
+} & Record<string, unknown>;
+
+export { type SeoApiErrorResponse, type SeoBacklinksImportResponse, type SeoCronResponse, type SeoPageResultResponse, type SeoPageResultsResponse, type SeoRunResponse, type SeoSnapshotReportResponse, type SeoSnapshotsResponse, type SeoTrendResponse, handleSeoBacklinksImport, handleSeoCron, handleSeoPageResult, handleSeoPageResults, handleSeoRun, handleSeoRunStream, handleSeoSnapshotReport, handleSeoSnapshots, handleSeoTrend };