gscdump 0.1.1 → 0.1.2

package/README.md

@@ -64,16 +64,16 @@ for await (const batch of queryRecursiveStream(client, site, {
 Drizzle-style query builder with full type safety. Filter constraints flow through to result types.
 
 ```ts
-import { and, contains, country, Country, device, Device, eq, gsc, inArray, page } from 'gscdump/query'
+import { and, between, contains, country, Country, date, device, Device, eq, gsc, inArray, page } from 'gscdump/query'
 
 const result = await gsc
   .select('page', 'query', 'device', 'country')
   .where(and(
     eq(device, Device.MOBILE),
     inArray(country, [Country.USA, Country.GBR]),
-    contains(page, '/blog/')
+    contains(page, '/blog/'),
+    between(date, '2024-01-01', '2024-01-31')
   ))
-  .period('2024-01-01', '2024-01-31')
   .siteUrl('https://example.com')
   .execute(client)
 
@@ -84,6 +84,21 @@ result.rows[0].page // type: string (contains doesn't narrow)
 result.rows[0].clicks // type: number
 ```
 
+**With date helpers:**
+
+```ts
+import { daysAgo, today } from '@gscdump/query'
+import { and, between, date, gsc, query, regex } from 'gscdump/query'
+
+const q = gsc
+  .select('query', 'page')
+  .where(and(
+    between(date, daysAgo(28), today()),
+    regex(query, /how to/)
+  ))
+  .limit(100)
+```
+
 **Operators:**
 
 | Operator | Narrows Type? | Description |
@@ -94,6 +109,12 @@ result.rows[0].clicks // type: number
 | `contains(col, str)` | ✗ | String contains |
 | `like(col, '%pattern%')` | ✗ | SQL LIKE pattern |
 | `regex(col, /pattern/)` | ✗ | Regex match |
+| `notRegex(col, /pattern/)` | ✗ | Regex exclusion |
+| `between(col, start, end)` | ✗ | Inclusive range (primarily for date) |
+| `gte(col, val)` | ✗ | Greater than or equal |
+| `lte(col, val)` | ✗ | Less than or equal |
+| `gt(col, val)` | ✗ | Greater than |
+| `lt(col, val)` | ✗ | Less than |
 | `and(...filters)` | ✓ | Merge constraints |
 | `or(...filters)` | ✗ | Any match |
 | `not(filter)` | ✗ | Invert filter |
@@ -133,7 +154,7 @@ const cannibalization = analyzeCannibalization(keywordPageData)
 
 **Low-level:** `gscClient`, `queryRecursive`, `queryRecursiveStream`, `createQueryBody`, `withPropertyAggregation`, `withSearchAppearance`, `withDataType`, `withFreshData`, `withFinalData`
 
-**Query Builder (`gscdump/query`):** `gsc`, `eq`, `ne`, `and`, `or`, `inArray`, `contains`, `like`, `regex`, `notRegex`, `not`, `page`, `query`, `device`, `country`, `searchAppearance`, `Device`, `Country`
+**Query Builder (`gscdump/query`):** `gsc`, `eq`, `ne`, `and`, `or`, `inArray`, `contains`, `like`, `regex`, `notRegex`, `not`, `between`, `gte`, `gt`, `lte`, `lt`, `page`, `query`, `device`, `country`, `date`, `searchAppearance`, `Device`, `Country`
 
 **Error Utilities:** `isQuotaError`, `isRateLimitError`, `isAuthError`, `getErrorCode`, `getErrorMessage`, `getRetryAfter`, `analyzeGscError`, `formatGscErrorForCli`
 

package/dist/index.d.mts

@@ -1100,6 +1100,7 @@ interface BuilderState {
   filters: Filter<any>[];
   siteUrl?: string;
   rowLimit?: number;
+  startRow?: number;
 }
 //#endregion
 //#region src/query/builder.d.ts
@@ -1108,6 +1109,7 @@ interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
   where: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C & F['_constraints']>;
   siteUrl: (url: string) => GSCQueryBuilder<D, C>;
   limit: (n: number) => GSCQueryBuilder<D, C>;
+  offset: (n: number) => GSCQueryBuilder<D, C>;
   execute: (client: GoogleSearchConsoleClient) => Promise<GSCResult<D, C>>;
   toBody: () => SearchAnalyticsQuery;
   /** Expose internal state for analysis functions to merge with */

package/dist/index.mjs

@@ -3503,6 +3503,7 @@ function resolveToBody(state) {
 		endDate
 	};
 	if (state.rowLimit) body.rowLimit = state.rowLimit;
+	if (state.startRow) body.startRow = state.startRow;
 	const filterGroups = resolveFilters(nonDateFilters);
 	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
 	return body;
@@ -3567,6 +3568,12 @@ function createBuilder(state) {
 				rowLimit: n
 			});
 		},
+		offset(n) {
+			return createBuilder({
+				...state,
+				startRow: n
+			});
+		},
 		async execute(client) {
 			const body = resolveToBody(state);
 			return transformResponse(await client.searchAnalytics.query(state.siteUrl, body), state.dimensions);

package/dist/query/index.d.mts

@@ -103,6 +103,7 @@ interface BuilderState {
   filters: Filter<any>[];
   siteUrl?: string;
   rowLimit?: number;
+  startRow?: number;
 }
 //#endregion
 //#region src/query/builder.d.ts
@@ -111,6 +112,7 @@ interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
   where: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C & F['_constraints']>;
   siteUrl: (url: string) => GSCQueryBuilder<D, C>;
   limit: (n: number) => GSCQueryBuilder<D, C>;
+  offset: (n: number) => GSCQueryBuilder<D, C>;
   execute: (client: GoogleSearchConsoleClient) => Promise<GSCResult<D, C>>;
   toBody: () => SearchAnalyticsQuery;
   /** Expose internal state for analysis functions to merge with */

package/dist/query/index.mjs

@@ -71,6 +71,7 @@ function resolveToBody(state) {
 		endDate
 	};
 	if (state.rowLimit) body.rowLimit = state.rowLimit;
+	if (state.startRow) body.startRow = state.startRow;
 	const filterGroups = resolveFilters(nonDateFilters);
 	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
 	return body;
@@ -135,6 +136,12 @@ function createBuilder(state) {
 				rowLimit: n
 			});
 		},
+		offset(n) {
+			return createBuilder({
+				...state,
+				startRow: n
+			});
+		},
 		async execute(client) {
 			const body = resolveToBody(state);
 			return transformResponse(await client.searchAnalytics.query(state.siteUrl, body), state.dimensions);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Google Search Console API wrapper with typed query builder, streaming pagination, and SEO analysis functions",
   "author": {
     "name": "Harlan Wilton",