{"_id":"@demi-valerith/gsc-opportunity-analyzer","_rev":"2-bb7a77cbc051c45f420c5d19020487d0","name":"@demi-valerith/gsc-opportunity-analyzer","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@demi-valerith/gsc-opportunity-analyzer","version":"1.0.0","keywords":["google-search-console","gsc","seo","github-action","csv"],"author":{"name":"Demi Valerith"},"license":"MIT","_id":"@demi-valerith/gsc-opportunity-analyzer@1.0.0","maintainers":[{"name":"demi-valerith","email":"demi@aix4u.com"}],"homepage":"https://seoreportkit.com/tools/gsc-opportunity-analysis/","bugs":{"url":"https://github.com/demi-valerith/gsc-opportunity-analyzer/issues"},"bin":{"gsc-opportunity":"bin/gsc-opportunity.mjs"},"dist":{"shasum":"8703a08563aa9877044824898c79ddbf749275d3","tarball":"https://registry.npmjs.org/@demi-valerith/gsc-opportunity-analyzer/-/gsc-opportunity-analyzer-1.0.0.tgz","fileCount":12,"integrity":"sha512-kYheyTOheroxjUHysHmYD4G0cMJ3qYTvlDy0rGrZS2PuK/Vssh9IpueJ4FVO1IYy7M6RzdYyj2l8i3mDs+p8BA==","signatures":[{"sig":"MEYCIQCrrez9MGqzIwCqV3sfTR2qAmVNybrftQ54LntS1OVm7wIhAPh1LTlGLwr7D16JJCk+r+wj25GvCcTOrGEaFPhR38YJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27751},"main":"./src/index.mjs","type":"module","types":"./src/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.mjs","default":"./src/index.mjs"}},"gitHead":"800985e461676997700a15839ae2ceba5fa361b5","scripts":{"test":"node --test","check":"node --check src/csv.mjs && node --check src/engine.mjs && node --check src/format.mjs && node --check src/index.mjs && node --check bin/gsc-opportunity.mjs && node --check action/index.mjs"},"_npmUser":{"name":"demi-valerith","email":"demi@aix4u.com"},"repository":{"url":"git+https://github.com/demi-valerith/gsc-opportunity-analyzer.git","type":"git"},"_npmVersion":"10.9.8","description":"Find striking-distance queries, CTR gaps, rising demand, decay, and page opportunities in Google Search Console CSV exports.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gsc-opportunity-analyzer_1.0.0_1784532378293_0.6542810224426245","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@demi-valerith/gsc-opportunity-analyzer","version":"1.0.1","description":"Find striking-distance queries, CTR gaps, rising demand, decay, and page opportunities in Google Search Console CSV exports.","type":"module","main":"./src/index.mjs","types":"./src/index.d.ts","bin":{"gsc-opportunity":"bin/gsc-opportunity.mjs"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.mjs","default":"./src/index.mjs"}},"scripts":{"check":"node --check src/csv.mjs && node --check src/engine.mjs && node --check src/format.mjs && node --check src/index.mjs && node --check bin/gsc-opportunity.mjs && node --check action/index.mjs","test":"node --test"},"keywords":["google-search-console","gsc","seo","github-action","csv"],"author":{"name":"Demi Valerith"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/demi-valerith/gsc-opportunity-analyzer.git"},"homepage":"https://seoreportkit.com/tools/gsc-opportunity-analysis/","bugs":{"url":"https://github.com/demi-valerith/gsc-opportunity-analyzer/issues"},"engines":{"node":">=20"},"sideEffects":false,"publishConfig":{"access":"public"},"gitHead":"13d1e22565f77ced31f9a4169a2534ef12f0c0a4","_id":"@demi-valerith/gsc-opportunity-analyzer@1.0.1","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-coJUkY5cpGn+9VBidL353/ONpVo2hR8gd0sKTR4w2p+uwWvMtPWFwcehmx/aWLN74GQiAgrW73VAgb6ZAMtZEQ==","shasum":"ca19715c102fe4a81ee39bdc8425f94b1e5698e8","tarball":"https://registry.npmjs.org/@demi-valerith/gsc-opportunity-analyzer/-/gsc-opportunity-analyzer-1.0.1.tgz","fileCount":12,"unpackedSize":27751,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@demi-valerith%2fgsc-opportunity-analyzer@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC9T7+2bsgdgA8YMcXWurXnp6D4Rz5T0iV6/3ty9oxvVAiBH7gUlw8S4SKQPzKCyj3shD/4erWRdHyu9ynqIs5oCLw=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cefa68cc-f93a-4c76-ba15-90dea6c830ab"}},"directories":{},"maintainers":[{"name":"demi-valerith","email":"demi@aix4u.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gsc-opportunity-analyzer_1.0.1_1784534024257_0.917860945769956"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-20T07:26:18.155Z","modified":"2026-07-20T07:53:44.783Z","1.0.0":"2026-07-20T07:26:18.432Z","1.0.1":"2026-07-20T07:53:44.432Z"},"bugs":{"url":"https://github.com/demi-valerith/gsc-opportunity-analyzer/issues"},"author":{"name":"Demi Valerith"},"license":"MIT","homepage":"https://seoreportkit.com/tools/gsc-opportunity-analysis/","keywords":["google-search-console","gsc","seo","github-action","csv"],"repository":{"type":"git","url":"git+https://github.com/demi-valerith/gsc-opportunity-analyzer.git"},"description":"Find striking-distance queries, CTR gaps, rising demand, decay, and page opportunities in Google Search Console CSV exports.","maintainers":[{"name":"demi-valerith","email":"demi@aix4u.com"}],"readme":"# GSC Opportunity Analyzer\n\nTurn Google Search Console Performance CSV exports into a deterministic SEO triage queue. The analyzer flags striking-distance queries, site-relative CTR gaps, rising demand, decay, and page-level opportunities while keeping query and URL data in your own process.\n\n[Use the browser tool](https://seoreportkit.com/tools/gsc-opportunity-analysis/) | [Read the methodology](https://seoreportkit.com/tools/gsc-opportunity-analysis/#rules) | [Report an issue](https://github.com/demi-valerith/gsc-opportunity-analyzer/issues)\n\n## Why this exists\n\nA Search Console export can contain hundreds of rows but still leave the operational question unanswered: which existing signal deserves the next hour of work? This tool produces a small evidence ledger with a priority score, confidence label, observed evidence, and a recommended verification step.\n\nIt does not forecast traffic, estimate keyword difficulty, infer query-to-page relationships from separate exports, or claim that an SEO edit caused a movement.\n\n## GitHub Action\n\nCommit or generate your Search Console exports inside a private repository, then add this workflow step:\n\n```yaml\n- name: Analyze GSC opportunities\n  id: gsc\n  uses: demi-valerith/gsc-opportunity-analyzer@v1\n  with:\n    current: data/gsc/current-queries.csv\n    previous: data/gsc/previous-queries.csv\n    pages: data/gsc/current-pages.csv\n    format: markdown\n    output: gsc-opportunities.md\n\n- name: Upload evidence ledger\n  uses: actions/upload-artifact@v4\n  with:\n    name: gsc-opportunities\n    path: ${{ steps.gsc.outputs.output-file }}\n```\n\nThe action logs only the finding count and output path. It does not log imported rows or send them to SEO Report Kit. Search queries can still be sensitive, so use a private repository and a suitable artifact retention policy.\n\n### Inputs\n\n| Input | Required | Default | Meaning |\n|---|---:|---:|---|\n| `current` | yes | - | Current-period Queries CSV |\n| `previous` | no | - | Equal-length prior-period Queries CSV |\n| `pages` | no | - | Current-period Pages CSV with the same filters |\n| `minimum-impressions` | no | `20` | Minimum query impressions |\n| `range` | no | `8-20` | Striking-distance average-position range |\n| `format` | no | `markdown` | `markdown`, `json`, or `csv` |\n| `output` | no | `gsc-opportunities.md` | Generated ledger path |\n\nOutputs are `finding-count` and `output-file`.\n\n## Command line\n\nNode.js 20 or newer is required. Install the public npm package:\n\n```bash\nnpm install --save-dev @demi-valerith/gsc-opportunity-analyzer\n```\n\nThen run the packaged CLI:\n\n```bash\nnpx gsc-opportunity current-queries.csv \\\n  --previous previous-queries.csv \\\n  --pages current-pages.csv \\\n  --format markdown \\\n  --output gsc-opportunities.md\n```\n\nThe analysis API is also available to ESM projects and includes TypeScript declarations:\n\n```js\nimport { analyzeFiles } from \"@demi-valerith/gsc-opportunity-analyzer\";\n\nconst findings = await analyzeFiles({\n  currentPath: \"current-queries.csv\",\n  previousPath: \"previous-queries.csv\",\n});\n```\n\nRun directly from GitHub without installing:\n\n```bash\nnpx github:demi-valerith/gsc-opportunity-analyzer current-queries.csv \\\n  --previous previous-queries.csv \\\n  --pages current-pages.csv \\\n  --format markdown \\\n  --output gsc-opportunities.md\n```\n\nOr clone the repository and run:\n\n```bash\nnode bin/gsc-opportunity.mjs test/fixtures/current.csv \\\n  --previous test/fixtures/previous.csv \\\n  --pages test/fixtures/pages.csv \\\n  --minimum 20 \\\n  --range 8-20 \\\n  --format json\n```\n\nUse `--help` for the complete option list. Without `--output`, the result is written to standard output. This makes it straightforward to pipe JSON or CSV into another local workflow.\n\n## Input contract\n\nExport the Search results Performance table from Google Search Console as CSV. The current Queries file is required; the prior Queries and current Pages files are optional.\n\nSupported English headers:\n\n- Query: `Top queries`, `Query`, or `Queries`\n- Page: `Top pages`, `Page`, or `Pages`\n- Metrics: `Clicks`, `Impressions`, `CTR`, and `Position` or `Average position`\n\nUse complete, equal-length periods with identical search type, country, device, query, and page filters. Separate Queries and Pages exports do not contain a query-to-page relationship, so the analyzer never invents one.\n\n## Transparent rules\n\nRules version: `1.0.0`.\n\n| Finding | Rule |\n|---|---|\n| Striking distance | Minimum impressions and average position inside the selected range, default 8-20 |\n| CTR gap | Position 10 or better, at least 50 impressions, and CTR below 70% of the uploaded property's pooled position-band baseline |\n| Rising | Impressions increased at least 30% and by at least 20 versus the prior period, with current position 40 or better |\n| Decay | Clicks fell at least 30% with five lost clicks, or impressions fell at least 40% with 50 lost impressions |\n| Page opportunity | Page has at least 50 impressions and average position 20 or better |\n\nPriority is a deterministic logarithmic impression score plus a fixed rule bonus. Confidence reflects sample strength and comparison availability. Neither value is a forecast or causal conclusion.\n\n## Development\n\n```bash\nnpm test\nnpm run check\n```\n\nThe test fixtures are original synthetic data. The analyzer has no runtime dependencies and makes no network requests.\n\n## License\n\nCode is available under the [MIT License](LICENSE).\n","readmeFilename":"README.md"}