# gscdump

[![npm version](https://img.shields.io/npm/v/gscdump?color=yellow)](https://npmjs.com/package/gscdump)
[![npm downloads](https://img.shields.io/npm/dm/gscdump?color=yellow)](https://npm.chart.dev/gscdump)
[![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)

Direct Google Search Console client with a typed query builder, streaming pagination, URL inspection, sitemap, verification, and Indexing API helpers.

## Install

```bash
npm install gscdump
```

`gscdump` requires Node 22 or newer. It talks to Google over `fetch`; it does not require the Google API client packages.

## Query Search Analytics

Create a client with an access token, an OAuth-like client, or refresh-token credentials:

```ts
import { googleSearchConsole } from 'gscdump'

const client = googleSearchConsole({ accessToken: 'ya29.xxx' })
const sites = await client.sites()
```

Use `gscdump/query` to build a request. `client.query()` paginates through Google's 25,000-row pages and yields each non-empty batch.

```ts
import { googleSearchConsole } from 'gscdump'
import { and, between, date, daysAgo, gsc, page, query, today } from 'gscdump/query'

const client = googleSearchConsole('ya29.xxx')
const siteUrl = 'sc-domain:example.com'

const request = gsc
  .select(page, query)
  .where(and(
    between(date, daysAgo(28), today()),
  ))

for await (const rows of client.query(siteUrl, request)) {
  for (const row of rows)
    console.log(row.page, row.query, row.clicks)
}
```

If you already have a Search Analytics request body, call the direct operation:

```ts
const response = await client.searchAnalytics.query(siteUrl, {
  startDate: '2026-06-01',
  endDate: '2026-06-30',
  dimensions: ['page'],
  rowLimit: 1000,
})
```

## Other Google resources

The same client exposes the Google resources owned by this package:

```ts
const sitemapList = await client.sitemaps.list(siteUrl)
const inspection = await client.inspect(siteUrl, 'https://example.com/docs')

await client.indexing.publish(
  'https://example.com/jobs/frontend-engineer',
  'URL_UPDATED',
)
```

The package root also exports batch and projection helpers such as `fetchSitesWithSitemaps`, `batchInspectUrlsFlatSettled`, `inspectUrlFlat`, and `batchRequestIndexing`.

## Public subpaths

- `gscdump/query`: query builder, columns, operators, Pacific date helpers, and logical query plans
- `gscdump/query/plan`: logical query planning only
- `gscdump/dates`: explicit UTC and Pacific Search Console date helpers
- `gscdump/contracts`: Search Analytics request and response contracts
- `gscdump/result`: `Result` helpers
- `gscdump/normalize`: URL normalization
- `gscdump/tenant`: site ID encoding and normalization

Hosted gscdump.com clients live in [`@gscdump/sdk`](../sdk). Storage engines and analyzers live in [`@gscdump/engine`](../engine) and [`@gscdump/analysis`](../analysis).

## License

[MIT](../../LICENSE)