gscdump 0.1.1 → 0.1.3

package/README.md

@@ -23,8 +23,8 @@ npm install gscdump
 ## Usage
 
 ```ts
-import { daysAgo, today } from '@gscdump/query'
 import { fetchKeywordsWithComparison, fetchPagesWithComparison } from 'gscdump'
+import { daysAgo, today } from 'gscdump/query'
 
 // Auth accepts token string or object
 const auth = 'ya29.xxx...'
@@ -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,20 @@ result.rows[0].page // type: string (contains doesn't narrow)
 result.rows[0].clicks // type: number
 ```
 
+**With date helpers:**
+
+```ts
+import { and, between, date, daysAgo, gsc, query, regex, today } 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 +108,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 +153,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`, `today`, `daysAgo`
 
 **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 */
@@ -1149,6 +1151,10 @@ declare function extractDateRange(filters: Filter<any>[]): {
   endDate?: string;
 };
 //#endregion
+//#region src/query/index.d.ts
+declare function today(): string;
+declare function daysAgo(n: number): string;
+//#endregion
 //#region src/utils/dayjs.d.ts
 declare function dayjs(date?: _dayjs.ConfigType): Dayjs;
 declare function currentPstDate(): string;
@@ -1170,4 +1176,4 @@ declare function formatDateGsc(d?: Date | string | null): string | null | undefi
  */
 declare function percentDifference(a?: number | null, b?: number | null): number;
 //#endregion
-export { AggregationType, AnalyticsData, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BaseMetrics, BrandSegmentationOptions, BrandSegmentationResult, BrandSummary, type BuilderState, CannibalizationOptions, CannibalizationPage, CannibalizationResult, CannibalizationSortMetric, ClusterType, ClusteringOptions, ClusteringResult, type Column, ComparisonResult, ConcentrationInput, ConcentrationItem, ConcentrationOptions, ConcentrationResult, ConcentrationRiskLevel, Country, type Country as CountryType, CountryData, DataRow, DataState, DataType, DateData, DateMetrics, DateRow, DatesComparisonResult, DecayInput, DecayOptions, DecayResult, DecaySortMetric, Device, type Device as DeviceType, DeviceData, type Dimension, DimensionFilter, DimensionFilterGroup, DimensionKey, type DimensionValueMap, ErrorInfo, FetchKeywordOptions, FetchKeywordResult, FetchPageOptions, FetchPageResult, type Filter, type GSCQueryBuilder, type GSCResult, type GSCRow, GSC_QUOTAS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, IndexStatusResult, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, KeywordCluster, KeywordData, KeywordRow, MobileUsabilityResult, MonthlyData, MoverData, MoversInput, MoversOptions, MoversResult, MoversSortMetric, OpportunityFactors, OpportunityOptions, OpportunityResult, OpportunitySortMetric, OpportunityWeights, Page, PageData, PageRow, Period, PublishUrlNotificationResponse, QueryOptions, QueryPageRow, QueryResultRow, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, SearchAppearanceData, SeasonalityMetric, SeasonalityOptions, SeasonalityResult, Site, SiteAnalytics, SortOrder, StreamRow, StrikingDistanceOptions, StrikingDistanceResult, StrikingDistanceSortMetric, UrlInspectionResult, UrlNotificationMetadata, YoYComparisonOptions, YoYComparisonResult, YoYMetrics, ZeroClickOptions, ZeroClickResult, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeError, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeZeroClick, and, batchInspectUrls, batchRequestIndexing, between, collectStream, contains, _default as countries, country, createAuth, createFetch, createQueryBody, createSorter, currentPstDate, date, dayjs, dayjsPst, deleteSitemap, device, eq, extractDateRange, fetchAnalyticsWithComparison, fetchCountries, fetchCountriesWithComparison, fetchDates, fetchDatesWithComparison, fetchDevices, fetchDevicesWithComparison, fetchKeyword, fetchKeywords, fetchKeywordsWithComparison, fetchPage, fetchPages, fetchPagesWithComparison, fetchSearchAppearance, fetchSearchAppearanceWithComparison, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, fetchYoYComparison, formatDateGsc, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gsc, gt, gte, inArray, inspectUrl, isAuthError, isQuotaError, isRateLimitError, like, lt, lte, ne, not, notRegex, num, or, page, percentDifference, query, queryRecursive, queryRecursiveStream, regex, requestIndexing, searchAppearance, submitSitemap, withDataType, withFinalData, withFreshData, withPropertyAggregation, withSearchAppearance };
+export { AggregationType, AnalyticsData, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BaseMetrics, BrandSegmentationOptions, BrandSegmentationResult, BrandSummary, type BuilderState, CannibalizationOptions, CannibalizationPage, CannibalizationResult, CannibalizationSortMetric, ClusterType, ClusteringOptions, ClusteringResult, type Column, ComparisonResult, ConcentrationInput, ConcentrationItem, ConcentrationOptions, ConcentrationResult, ConcentrationRiskLevel, Country, type Country as CountryType, CountryData, DataRow, DataState, DataType, DateData, DateMetrics, DateRow, DatesComparisonResult, DecayInput, DecayOptions, DecayResult, DecaySortMetric, Device, type Device as DeviceType, DeviceData, type Dimension, DimensionFilter, DimensionFilterGroup, DimensionKey, type DimensionValueMap, ErrorInfo, FetchKeywordOptions, FetchKeywordResult, FetchPageOptions, FetchPageResult, type Filter, type GSCQueryBuilder, type GSCResult, type GSCRow, GSC_QUOTAS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, IndexStatusResult, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, KeywordCluster, KeywordData, KeywordRow, MobileUsabilityResult, MonthlyData, MoverData, MoversInput, MoversOptions, MoversResult, MoversSortMetric, OpportunityFactors, OpportunityOptions, OpportunityResult, OpportunitySortMetric, OpportunityWeights, Page, PageData, PageRow, Period, PublishUrlNotificationResponse, QueryOptions, QueryPageRow, QueryResultRow, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, SearchAppearanceData, SeasonalityMetric, SeasonalityOptions, SeasonalityResult, Site, SiteAnalytics, SortOrder, StreamRow, StrikingDistanceOptions, StrikingDistanceResult, StrikingDistanceSortMetric, UrlInspectionResult, UrlNotificationMetadata, YoYComparisonOptions, YoYComparisonResult, YoYMetrics, ZeroClickOptions, ZeroClickResult, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeError, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeZeroClick, and, batchInspectUrls, batchRequestIndexing, between, collectStream, contains, _default as countries, country, createAuth, createFetch, createQueryBody, createSorter, currentPstDate, date, dayjs, dayjsPst, daysAgo, deleteSitemap, device, eq, extractDateRange, fetchAnalyticsWithComparison, fetchCountries, fetchCountriesWithComparison, fetchDates, fetchDatesWithComparison, fetchDevices, fetchDevicesWithComparison, fetchKeyword, fetchKeywords, fetchKeywordsWithComparison, fetchPage, fetchPages, fetchPagesWithComparison, fetchSearchAppearance, fetchSearchAppearanceWithComparison, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, fetchYoYComparison, formatDateGsc, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gsc, gt, gte, inArray, inspectUrl, isAuthError, isQuotaError, isRateLimitError, like, lt, lte, ne, not, notRegex, num, or, page, percentDifference, query, queryRecursive, queryRecursiveStream, regex, requestIndexing, searchAppearance, submitSitemap, today, withDataType, withFinalData, withFreshData, withPropertyAggregation, withSearchAppearance };

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);
@@ -3771,4 +3778,13 @@ function between(column, start, end) {
 }
 
 //#endregion
-export { Country, Device, GSC_QUOTAS, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeError, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeZeroClick, and, batchInspectUrls, batchRequestIndexing, between, collectStream, contains, countries_default as countries, country, createAuth, createFetch, createQueryBody, createSorter, currentPstDate, date, dayjs, dayjsPst, deleteSitemap, device, eq, extractDateRange, fetchAnalyticsWithComparison, fetchCountries, fetchCountriesWithComparison, fetchDates, fetchDatesWithComparison, fetchDevices, fetchDevicesWithComparison, fetchKeyword, fetchKeywords, fetchKeywordsWithComparison, fetchPage, fetchPages, fetchPagesWithComparison, fetchSearchAppearance, fetchSearchAppearanceWithComparison, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, fetchYoYComparison, formatDateGsc, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gsc, gt, gte, inArray, inspectUrl, isAuthError, isQuotaError, isRateLimitError, like, lt, lte, ne, not, notRegex, num, or, page, percentDifference, query, queryRecursive, queryRecursiveStream, regex, requestIndexing, searchAppearance, submitSitemap, withDataType, withFinalData, withFreshData, withPropertyAggregation, withSearchAppearance };
+//#region src/query/index.ts
+function today() {
+	return currentPstDate();
+}
+function daysAgo(n) {
+	return dayjsPst().subtract(n, "day").format("YYYY-MM-DD");
+}
+
+//#endregion
+export { Country, Device, GSC_QUOTAS, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeError, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeZeroClick, and, batchInspectUrls, batchRequestIndexing, between, collectStream, contains, countries_default as countries, country, createAuth, createFetch, createQueryBody, createSorter, currentPstDate, date, dayjs, dayjsPst, daysAgo, deleteSitemap, device, eq, extractDateRange, fetchAnalyticsWithComparison, fetchCountries, fetchCountriesWithComparison, fetchDates, fetchDatesWithComparison, fetchDevices, fetchDevicesWithComparison, fetchKeyword, fetchKeywords, fetchKeywordsWithComparison, fetchPage, fetchPages, fetchPagesWithComparison, fetchSearchAppearance, fetchSearchAppearanceWithComparison, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, fetchYoYComparison, formatDateGsc, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gsc, gt, gte, inArray, inspectUrl, isAuthError, isQuotaError, isRateLimitError, like, lt, lte, ne, not, notRegex, num, or, page, percentDifference, query, queryRecursive, queryRecursiveStream, regex, requestIndexing, searchAppearance, submitSitemap, today, withDataType, withFinalData, withFreshData, withPropertyAggregation, withSearchAppearance };

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 */
@@ -152,4 +154,8 @@ declare function extractDateRange(filters: Filter<any>[]): {
   endDate?: string;
 };
 //#endregion
-export { type BuilderState, type Column, Country, type Country as CountryType, Device, type Device as DeviceType, type Dimension, type DimensionValueMap, type Filter, type GSCQueryBuilder, type GSCResult, type GSCRow, and, between, contains, country, date, device, eq, extractDateRange, gsc, gt, gte, inArray, like, lt, lte, ne, not, notRegex, or, page, query, regex, searchAppearance };
+//#region src/query/index.d.ts
+declare function today(): string;
+declare function daysAgo(n: number): string;
+//#endregion
+export { type BuilderState, type Column, Country, type Country as CountryType, Device, type Device as DeviceType, type Dimension, type DimensionValueMap, type Filter, type GSCQueryBuilder, type GSCResult, type GSCRow, and, between, contains, country, date, daysAgo, device, eq, extractDateRange, gsc, gt, gte, inArray, like, lt, lte, ne, not, notRegex, or, page, query, regex, searchAppearance, today };

package/dist/query/index.mjs

@@ -1,3 +1,21 @@
+import _dayjs from "dayjs";
+import timezone from "dayjs/plugin/timezone.js";
+import utc from "dayjs/plugin/utc.js";
+
+//#region src/utils/dayjs.ts
+_dayjs.extend(utc);
+_dayjs.extend(timezone);
+function dayjs(date$1) {
+	return _dayjs(date$1);
+}
+function currentPstDate() {
+	return dayjs().tz("America/Los_Angeles").hour(12).minute(0).second(0).format("YYYY-MM-DD");
+}
+function dayjsPst() {
+	return dayjs().tz("America/Los_Angeles").hour(12).minute(0).second(0);
+}
+
+//#endregion
 //#region src/query/resolver.ts
 const DATE_OPERATORS = [
 	"gte",
@@ -71,6 +89,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 +154,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);
@@ -1838,4 +1863,13 @@ function between(column, start, end) {
 }
 
 //#endregion
-export { Country, Device, and, between, contains, country, date, device, eq, extractDateRange, gsc, gt, gte, inArray, like, lt, lte, ne, not, notRegex, or, page, query, regex, searchAppearance };
+//#region src/query/index.ts
+function today() {
+	return currentPstDate();
+}
+function daysAgo(n) {
+	return dayjsPst().subtract(n, "day").format("YYYY-MM-DD");
+}
+
+//#endregion
+export { Country, Device, and, between, contains, country, date, daysAgo, device, eq, extractDateRange, gsc, gt, gte, inArray, like, lt, lte, ne, not, notRegex, or, page, query, regex, searchAppearance, today };

package/package.json

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