@gscdump/sdk 0.25.13 → 0.26.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { query_d_exports } from "./_chunks/query.mjs";
 import { AddPartnerTeamMemberParams, AnalyticsClient, AnalyticsClient as AnalyticsClient$1, BackfillRange, BackfillResponse, BindPartnerSiteTeamParams, BuilderState, BulkRegisterPartnerSiteResult, BulkRegisterPartnerSitesParams, BulkRegisterPartnerSitesResponse, CANONICAL_WEBHOOK_EVENTS, CanonicalWebhookEventType, CreatePartnerTeamParams, CreateWebhookEnvelopeOptions, DataDetailOptions, DataQueryOptions, DeletePartnerUserResponse, GscComparisonFilter, GscdumpAnalysisParams, GscdumpAnalysisPreset, GscdumpAnalysisResponse, GscdumpAnalysisSourcesResponse, GscdumpAvailableSite, GscdumpCanonicalMismatchesResponse, GscdumpDataDetailResponse, GscdumpDataResponse, GscdumpDataRow, GscdumpDateRangeParams, GscdumpIndexPercentResponse, GscdumpIndexingDiagnosticsResponse, GscdumpIndexingResponse, GscdumpIndexingUrlStatus, GscdumpIndexingUrlsResponse, GscdumpKeywordSparklinesParams, GscdumpKeywordSparklinesResponse, GscdumpMeta, GscdumpPageTrendParams, GscdumpPageTrendResponse, GscdumpPermissionRecovery, GscdumpQueryTrendParams, GscdumpQueryTrendResponse, GscdumpSiteRegistration, GscdumpSitemap, GscdumpSitemapChangesResponse, GscdumpSitemapHistory, GscdumpSitemapsResponse, GscdumpSyncStatusResponse, GscdumpSyncStatusResponse as GscdumpSyncStatusResponse$1, GscdumpTeamMemberRow, GscdumpTeamRow, GscdumpTopAssociationParams, GscdumpTopAssociationResponse, GscdumpTotals, GscdumpUserRegistration, GscdumpUserSettings, GscdumpUserSite, GscdumpUserSite as GscdumpUserSite$1, GscdumpUserStatus, GscdumpUserTokenUpdate, IndexingUrlsParams, InspectionHistoryResponse, InspectionIndex, PartnerClient, PartnerClient as PartnerClient$1, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleResponse as PartnerLifecycleResponse$1, PartnerLifecycleSite, PartnerLifecycleSite as PartnerLifecycleSite$1, PartnerRealtimeEvent, PartnerRealtimeEvent as PartnerRealtimeEvent$1, PartnerRealtimeEventType, PartnerRealtimeMessage, PartnerRealtimeMessage as PartnerRealtimeMessage$1, PartnerWebhookData, PartnerWebhookHeaders, PartnerWebhookHeaders as PartnerWebhookHeaders$1, RealtimeAuthFailedEvent, RealtimeAuthRequiredMessage, RealtimeConnectedMessage, RealtimeEnrichmentCompleteEvent, RealtimeErrorMessage, RealtimeJobFailedEvent, RealtimeNeedsReauthEvent, RealtimePongMessage, RealtimeSiteAddedEvent, RealtimeSiteRemovedEvent, RealtimeSubscribedMessage, RealtimeSyncCompleteEvent, RealtimeSyncFailedEvent, RealtimeSyncJobCompleteEvent, RealtimeSyncProgressEvent, RealtimeSyncSiteCompleteEvent, RegisterPartnerSiteParams, RegisterPartnerUserParams, RollupEnvelope, UpdatePartnerUserTokensParams, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WebhookEnvelope, WebhookEnvelope as WebhookEnvelope$1, WebhookEventType, WhoamiResponse } from "@gscdump/contracts";
+import { Result } from "gscdump/result";
 import { BuilderState as BuilderState$1, Dimension, Metric, SearchType } from "gscdump/query";
 import { ActionSource } from "@gscdump/analysis";
 import { AnalysisTool } from "@gscdump/engine/analysis-types";
@@ -225,6 +226,15 @@ interface TopNBreakdownQuery extends ArchetypeQueryBase {
   limit: number;
   /** Pagination offset. Non-zero may force `duckdb` execution. */
   offset?: number;
+  /**
+   * Request the full unwindowed group count (`meta.totalRows`) so paginated /
+   * load-more tables know how many rows exist beyond the current `limit`.
+   * Computed as `COUNT(*) OVER()` over the grouped result, which requires a
+   * window function — so a query with `includeTotal` is escalated to `duckdb`
+   * on the server tail (R2 SQL cannot express it). Not honoured for the
+   * `device` dimension, which has at most a handful of rows.
+   */
+  includeTotal?: boolean;
 }
 /** One aggregated row for a fully-specified filter. `WHERE` + `GROUP BY`. */
 interface SingleRowLookupQuery extends ArchetypeQueryBase {
@@ -299,7 +309,13 @@ interface ArchetypeResult<R extends ArchetypeResultRow = ArchetypeResultRow> {
   source: ArchetypeResultSource;
   meta?: {
     rowCount: number;
-    queryMs: number; /** Set when `compareRange` was supplied — the comparison-period rows. */
+    queryMs: number;
+    /**
+     * Full unwindowed group count for a `top-n-breakdown` requested with
+     * `includeTotal`. Independent of `limit`/`offset`; lets paginated tables
+     * show "X of Y" and stop loading. Undefined when not requested.
+     */
+    totalRows?: number; /** Set when `compareRange` was supplied — the comparison-period rows. */
     compareRows?: R[];
     truncated?: boolean;
   };
@@ -353,6 +369,17 @@ declare class PartnerApiError extends Error {
   constructor(info: PartnerErrorInfo);
 }
 declare function toPartnerError(error: unknown): PartnerApiError;
+/** Narrow an unknown error to the modelled `PartnerApiError`. */
+declare function isPartnerError(error: unknown): error is PartnerApiError;
+/** Human-readable, log-friendly rendering of a modelled partner failure. */
+declare function formatPartnerError(error: PartnerApiError): string;
+/**
+ * Re-raise a modelled `PartnerApiError` as itself. The error variant of every
+ * `*Result` core already IS the throwable `PartnerApiError`, so the throwing
+ * wrappers preserve the exact identity/message existing call sites and tests
+ * assert (`rejects.toThrow(PartnerApiError)`, `toThrow('Invalid webhook signature')`).
+ */
+declare function partnerErrorToException(error: PartnerApiError): PartnerApiError;
 interface GscConsoleUrlOpts {
   /** The GSC property — either `sc-domain:example.com` or a URL-prefix. */
   siteLabel: string;
@@ -872,6 +899,18 @@ declare function classifyReachStage(input: SiteTriageInput): ReachVerdict;
 declare function classifySiteTriage(input: SiteTriageInput): SiteTriage;
 declare function serializeWebhookPayload(payload: string | object): string;
 declare function verifyWebhookSignature(payload: string | object, signature: string | null | undefined, secret: string): Promise<boolean>;
+/**
+ * Errors-as-values core for {@link parseWebhookPayload}: a failed HMAC signature
+ * check is a caller-actionable `auth` (401) failure at the webhook boundary, so
+ * it is returned as a modelled `PartnerApiError` rather than only thrown. A
+ * malformed envelope (schema parse) is a defect and keeps propagating.
+ */
+declare function parseWebhookPayloadResult<TData extends Record<string, unknown> = Record<string, unknown>>(payload: string | object, options?: {
+  secret?: string;
+  signature?: string | null;
+  headers?: PartnerWebhookHeaders$1 | Headers;
+  validateSignature?: boolean;
+}): Promise<Result<WebhookEnvelope$1<TData>, PartnerApiError>>;
 declare function parseWebhookPayload<TData extends Record<string, unknown> = Record<string, unknown>>(payload: string | object, options?: {
   secret?: string;
   signature?: string | null;
@@ -879,4 +918,4 @@ declare function parseWebhookPayload<TData extends Record<string, unknown> = Rec
   validateSignature?: boolean;
 }): Promise<WebhookEnvelope$1<TData>>;
 declare function readWebhookHeaders(headers: Headers | PartnerWebhookHeaders$1 | null | undefined): Required<PartnerWebhookHeaders$1>;
-export { ARCHETYPE_EXECUTION_CLASS, type AddPartnerTeamMemberParams, type AnalyticsClient, type AnalyticsClientOptions, type AnalyticsFetch, type AnalyticsFetchOptions, type AnalyticsHeaders, type ArbitrarySqlQuery, type ArchetypeExecutionClass, type ArchetypeFacet, type ArchetypeQuery, type ArchetypeQueryBase, type ArchetypeResult, type ArchetypeResultRow, type ArchetypeResultSource, type AuxCloudOnlyQuery, type BackfillRange, type BackfillResponse, type BindPartnerSiteTeamParams, type BuilderState, type BulkRegisterPartnerSiteResult, type BulkRegisterPartnerSitesParams, type BulkRegisterPartnerSitesResponse, CANONICAL_WEBHOOK_EVENTS, COMPARE_OPTIONS, COUNTRY_NAMES, CWV_GOOD_CLS, CWV_GOOD_INP, CWV_GOOD_LCP, CWV_POOR_CLS, CWV_POOR_INP, CWV_POOR_LCP, type CalendarPeriod, type CanonicalDailyRow, type CanonicalWebhookEventType, type ClassifySearchConsoleStageInput, type CompareMode, type CreatePartnerTeamParams, type CreateWebhookEnvelopeOptions, type CustomPeriod, type CwvBucket, type DailyAnonInput, type DataDetailOptions, type DataQueryOptions, type DateRange, type DateRangeResult, type DeletePartnerUserResponse, type EntityDailySparklineQuery, type EntityDailyTimeseriesQuery, GSC_COLUMN_OPTIONS, GSC_PERIOD_OPTIONS, GSC_PERIOD_OPTIONS_LONG, GSC_STABLE_LATENCY_DAYS, type GscAnalyzerAccent, type GscAnalyzerCapabilities, type GscAnalyzerCapability, type GscAnalyzerDefinition, type GscAnalyzerDefinitionWithCapability, type GscAnalyzerInsightCard, type GscAnalyzerKind, type GscAnalyzerPanelResult, type GscAnalyzerPanelSpec, type GscAnalyzerStatTile, type GscClassifiedError, type GscColumn, type GscColumnOption, type GscComparisonFilter, type GscConsoleUrlOpts, type GscDailySummary, type GscErrorStatus, type GscRowTotals, type GscdumpAnalysisParams, type GscdumpAnalysisPreset, type GscdumpAnalysisResponse, type GscdumpAnalysisSourcesResponse, type GscdumpAvailableSite, type GscdumpCanonicalMismatchesResponse, type GscdumpDataDetailResponse, type GscdumpDataResponse, type GscdumpDataRow, type GscdumpDateRangeParams, type GscdumpIndexPercentResponse, type GscdumpIndexingDiagnosticsResponse, type GscdumpIndexingResponse, type GscdumpIndexingUrlStatus, type GscdumpIndexingUrlsResponse, type GscdumpKeywordSparklinesParams, type GscdumpKeywordSparklinesResponse, type GscdumpMeta, type GscdumpPageTrendParams, type GscdumpPageTrendResponse, type GscdumpPermissionRecovery, type GscdumpQueryTrendParams, type GscdumpQueryTrendResponse, type GscdumpSiteRegistration, type GscdumpSitemap, type GscdumpSitemapChangesResponse, type GscdumpSitemapHistory, type GscdumpSitemapsResponse, type GscdumpSyncStatusResponse, type GscdumpTeamMemberRow, type GscdumpTeamRow, type GscdumpTopAssociationParams, type GscdumpTopAssociationResponse, type GscdumpTotals, type GscdumpUserRegistration, type GscdumpUserSettings, type GscdumpUserSite, type GscdumpUserStatus, type GscdumpUserTokenUpdate, type HealthStage, type HealthVerdict, type IndexingIssue, type IndexingIssueDetail, type IndexingUrlsParams, type InspectionHistoryResponse, type InspectionIndex, type IssueGroup, type IssueSeverity, type MultiSeriesStackedDailyQuery, PERIOD_PRESETS, PartnerApiError, type PartnerClient, type PartnerClientOptions, type PartnerErrorInfo, type PartnerErrorKind, type PartnerFetch, type PartnerFetchOptions, type PartnerHeaders, type PartnerLifecycleAccount, type PartnerLifecycleResponse, type PartnerLifecycleSite, type PartnerRealtimeClient, type PartnerRealtimeEvent, type PartnerRealtimeEventType, type PartnerRealtimeHandler, type PartnerRealtimeMessage, type PartnerRealtimeOptions, type PartnerRealtimeScope, type PartnerRealtimeStatus, type PartnerWebSocketConstructor, type PartnerWebSocketLike, type PartnerWebhookData, type PartnerWebhookHeaders, type PeerBaselineInput, type PeerConfidence, type PeerStanding, type Period, type PeriodPreset, type QueryArchetype, type RawDailyRow, type ReachStage, type ReachVerdict, type RealtimeAuthFailedEvent, type RealtimeAuthRequiredMessage, type RealtimeConnectedMessage, type RealtimeEnrichmentCompleteEvent, type RealtimeErrorMessage, type RealtimeJobFailedEvent, type RealtimeNeedsReauthEvent, type RealtimePongMessage, type RealtimeSiteAddedEvent, type RealtimeSiteRemovedEvent, type RealtimeSubscribedMessage, type RealtimeSyncCompleteEvent, type RealtimeSyncFailedEvent, type RealtimeSyncJobCompleteEvent, type RealtimeSyncProgressEvent, type RealtimeSyncSiteCompleteEvent, type RegisterPartnerSiteParams, type RegisterPartnerUserParams, type ResolvedArchetypeQuery, type RollingPeriod, type RollupEnvelope, SITE_TYPE_BASELINE, type SearchConsoleStage, type SearchConsoleStageEvidence, type SearchConsoleStageIssue, type SearchConsoleStageKey, type SearchConsoleStagePage, type SearchConsoleStageSeverity, type SearchConsoleStageSitemap, type SearchConsoleStageSummary, type SearchConsoleStageTrajectory, type SingleRowLookupQuery, type SiteBaseline, type SiteDailyTimeseriesQuery, type SiteTriage, type SiteTriageInput, type SiteType, type SiteTypeBaseline, type TopNBreakdownQuery, type TriageEvidence, type TwoDimensionDetailQuery, type UpdatePartnerUserTokensParams, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, type WebhookEnvelope, type WebhookEventType, type WhoamiResponse, analyticsStatusToSyncStatus, andFilter, classifyGscError, classifyHealthStage, classifyReachStage, classifySearchConsoleStage, classifySiteTriage, coerceRowMetrics, compareRange, countryName, coverageLabel, coverageLabels, createAnalyticsClient, createGscdumpClient, createGscdumpRealtimeClient, createPartnerClient, createPartnerRealtimeClient, cwvBucket, dateFilter, defineGscAnalyzer, derivePeerStanding, deriveSiteBaseline, enrichIssueDetails, findLifecycleSite, getGscUnstableCutoffDate, gscConsoleUrl, investigationStatusConfig, isCustomPeriod, issueDetails, issueGroups, issueTypeToGroup, lifecycleSiteToSyncStatus, lifecycleSiteToUserSite, normalizeSiteType, nuxtSeoTips, parseCustomPeriod, parseWebhookPayload, periodToDateRange, periodToDays, positionFor, reachLivenessRatio, readWebhookHeaders, serializeWebhookPayload, severityOrder, siteTypeBaseline, siteUrlToHostname, splitOpportunityTitle, summarizeDailyRows, toPartnerError, truncateQuery, verifyWebhookSignature, weightedAnonPct };
+export { ARCHETYPE_EXECUTION_CLASS, type AddPartnerTeamMemberParams, type AnalyticsClient, type AnalyticsClientOptions, type AnalyticsFetch, type AnalyticsFetchOptions, type AnalyticsHeaders, type ArbitrarySqlQuery, type ArchetypeExecutionClass, type ArchetypeFacet, type ArchetypeQuery, type ArchetypeQueryBase, type ArchetypeResult, type ArchetypeResultRow, type ArchetypeResultSource, type AuxCloudOnlyQuery, type BackfillRange, type BackfillResponse, type BindPartnerSiteTeamParams, type BuilderState, type BulkRegisterPartnerSiteResult, type BulkRegisterPartnerSitesParams, type BulkRegisterPartnerSitesResponse, CANONICAL_WEBHOOK_EVENTS, COMPARE_OPTIONS, COUNTRY_NAMES, CWV_GOOD_CLS, CWV_GOOD_INP, CWV_GOOD_LCP, CWV_POOR_CLS, CWV_POOR_INP, CWV_POOR_LCP, type CalendarPeriod, type CanonicalDailyRow, type CanonicalWebhookEventType, type ClassifySearchConsoleStageInput, type CompareMode, type CreatePartnerTeamParams, type CreateWebhookEnvelopeOptions, type CustomPeriod, type CwvBucket, type DailyAnonInput, type DataDetailOptions, type DataQueryOptions, type DateRange, type DateRangeResult, type DeletePartnerUserResponse, type EntityDailySparklineQuery, type EntityDailyTimeseriesQuery, GSC_COLUMN_OPTIONS, GSC_PERIOD_OPTIONS, GSC_PERIOD_OPTIONS_LONG, GSC_STABLE_LATENCY_DAYS, type GscAnalyzerAccent, type GscAnalyzerCapabilities, type GscAnalyzerCapability, type GscAnalyzerDefinition, type GscAnalyzerDefinitionWithCapability, type GscAnalyzerInsightCard, type GscAnalyzerKind, type GscAnalyzerPanelResult, type GscAnalyzerPanelSpec, type GscAnalyzerStatTile, type GscClassifiedError, type GscColumn, type GscColumnOption, type GscComparisonFilter, type GscConsoleUrlOpts, type GscDailySummary, type GscErrorStatus, type GscRowTotals, type GscdumpAnalysisParams, type GscdumpAnalysisPreset, type GscdumpAnalysisResponse, type GscdumpAnalysisSourcesResponse, type GscdumpAvailableSite, type GscdumpCanonicalMismatchesResponse, type GscdumpDataDetailResponse, type GscdumpDataResponse, type GscdumpDataRow, type GscdumpDateRangeParams, type GscdumpIndexPercentResponse, type GscdumpIndexingDiagnosticsResponse, type GscdumpIndexingResponse, type GscdumpIndexingUrlStatus, type GscdumpIndexingUrlsResponse, type GscdumpKeywordSparklinesParams, type GscdumpKeywordSparklinesResponse, type GscdumpMeta, type GscdumpPageTrendParams, type GscdumpPageTrendResponse, type GscdumpPermissionRecovery, type GscdumpQueryTrendParams, type GscdumpQueryTrendResponse, type GscdumpSiteRegistration, type GscdumpSitemap, type GscdumpSitemapChangesResponse, type GscdumpSitemapHistory, type GscdumpSitemapsResponse, type GscdumpSyncStatusResponse, type GscdumpTeamMemberRow, type GscdumpTeamRow, type GscdumpTopAssociationParams, type GscdumpTopAssociationResponse, type GscdumpTotals, type GscdumpUserRegistration, type GscdumpUserSettings, type GscdumpUserSite, type GscdumpUserStatus, type GscdumpUserTokenUpdate, type HealthStage, type HealthVerdict, type IndexingIssue, type IndexingIssueDetail, type IndexingUrlsParams, type InspectionHistoryResponse, type InspectionIndex, type IssueGroup, type IssueSeverity, type MultiSeriesStackedDailyQuery, PERIOD_PRESETS, PartnerApiError, type PartnerClient, type PartnerClientOptions, type PartnerErrorInfo, type PartnerErrorKind, type PartnerFetch, type PartnerFetchOptions, type PartnerHeaders, type PartnerLifecycleAccount, type PartnerLifecycleResponse, type PartnerLifecycleSite, type PartnerRealtimeClient, type PartnerRealtimeEvent, type PartnerRealtimeEventType, type PartnerRealtimeHandler, type PartnerRealtimeMessage, type PartnerRealtimeOptions, type PartnerRealtimeScope, type PartnerRealtimeStatus, type PartnerWebSocketConstructor, type PartnerWebSocketLike, type PartnerWebhookData, type PartnerWebhookHeaders, type PeerBaselineInput, type PeerConfidence, type PeerStanding, type Period, type PeriodPreset, type QueryArchetype, type RawDailyRow, type ReachStage, type ReachVerdict, type RealtimeAuthFailedEvent, type RealtimeAuthRequiredMessage, type RealtimeConnectedMessage, type RealtimeEnrichmentCompleteEvent, type RealtimeErrorMessage, type RealtimeJobFailedEvent, type RealtimeNeedsReauthEvent, type RealtimePongMessage, type RealtimeSiteAddedEvent, type RealtimeSiteRemovedEvent, type RealtimeSubscribedMessage, type RealtimeSyncCompleteEvent, type RealtimeSyncFailedEvent, type RealtimeSyncJobCompleteEvent, type RealtimeSyncProgressEvent, type RealtimeSyncSiteCompleteEvent, type RegisterPartnerSiteParams, type RegisterPartnerUserParams, type ResolvedArchetypeQuery, type RollingPeriod, type RollupEnvelope, SITE_TYPE_BASELINE, type SearchConsoleStage, type SearchConsoleStageEvidence, type SearchConsoleStageIssue, type SearchConsoleStageKey, type SearchConsoleStagePage, type SearchConsoleStageSeverity, type SearchConsoleStageSitemap, type SearchConsoleStageSummary, type SearchConsoleStageTrajectory, type SingleRowLookupQuery, type SiteBaseline, type SiteDailyTimeseriesQuery, type SiteTriage, type SiteTriageInput, type SiteType, type SiteTypeBaseline, type TopNBreakdownQuery, type TriageEvidence, type TwoDimensionDetailQuery, type UpdatePartnerUserTokensParams, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, type WebhookEnvelope, type WebhookEventType, type WhoamiResponse, analyticsStatusToSyncStatus, andFilter, classifyGscError, classifyHealthStage, classifyReachStage, classifySearchConsoleStage, classifySiteTriage, coerceRowMetrics, compareRange, countryName, coverageLabel, coverageLabels, createAnalyticsClient, createGscdumpClient, createGscdumpRealtimeClient, createPartnerClient, createPartnerRealtimeClient, cwvBucket, dateFilter, defineGscAnalyzer, derivePeerStanding, deriveSiteBaseline, enrichIssueDetails, findLifecycleSite, formatPartnerError, getGscUnstableCutoffDate, gscConsoleUrl, investigationStatusConfig, isCustomPeriod, isPartnerError, issueDetails, issueGroups, issueTypeToGroup, lifecycleSiteToSyncStatus, lifecycleSiteToUserSite, normalizeSiteType, nuxtSeoTips, parseCustomPeriod, parseWebhookPayload, parseWebhookPayloadResult, partnerErrorToException, periodToDateRange, periodToDays, positionFor, reachLivenessRatio, readWebhookHeaders, serializeWebhookPayload, severityOrder, siteTypeBaseline, siteUrlToHostname, splitOpportunityTitle, summarizeDailyRows, toPartnerError, truncateQuery, verifyWebhookSignature, weightedAnonPct };

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { query_exports } from "./query.mjs";
 import { CANONICAL_WEBHOOK_EVENTS, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_CONTRACT_VERSION_HEADER as WEBHOOK_CONTRACT_VERSION_HEADER$1, WEBHOOK_DELIVERY_HEADER, WEBHOOK_DELIVERY_HEADER as WEBHOOK_DELIVERY_HEADER$1, WEBHOOK_EVENT_HEADER, WEBHOOK_EVENT_HEADER as WEBHOOK_EVENT_HEADER$1, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_HEADER as WEBHOOK_SIGNATURE_HEADER$1, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_TIMESTAMP_HEADER as WEBHOOK_TIMESTAMP_HEADER$1, analyticsRoutes, partnerEndpointSchemas, partnerRoutes, partnerWebhookEnvelopeSchema } from "@gscdump/contracts";
+import { err, ok, unwrapResult } from "gscdump/result";
 import { ofetch } from "ofetch";
 import { resolveWindow } from "@gscdump/engine/period";
 import { endOfMonth, format, startOfMonth, startOfQuarter, startOfWeek, subDays, subMonths } from "date-fns";
@@ -47,6 +48,16 @@ function toPartnerError(error) {
 		data
 	});
 }
+function isPartnerError(error) {
+	return error instanceof PartnerApiError;
+}
+function formatPartnerError(error) {
+	const status = error.statusCode != null ? ` (${error.statusCode})` : "";
+	return `[${error.kind}]${status} ${error.message}`;
+}
+function partnerErrorToException(error) {
+	return error;
+}
 const TRAILING_SLASH_RE$2 = /\/+$/;
 const LEADING_SLASH_RE$1 = /^\/+/;
 const DEFAULT_SEARCH_TYPE$1 = "web";
@@ -120,18 +131,21 @@ function indexingUrlsQuery$1(params = {}) {
 function createAnalyticsClient(options = {}) {
 	const fetchImpl = options.fetch ?? ofetch;
 	const apiBase = trimApiBase$1(options.apiBase);
-	async function request(path, init = {}, responseSchema) {
+	async function requestResult(path, init = {}, responseSchema) {
 		const headers = mergeHeaders$1(await resolveHeaders$1(options), init.headers);
 		try {
 			const out = await fetchImpl(buildPath$1(apiBase, path), {
 				...init,
 				headers
 			});
-			return shouldValidate$1(options, "response") ? parseWith$1(responseSchema, out) : out;
+			return ok(shouldValidate$1(options, "response") ? parseWith$1(responseSchema, out) : out);
 		} catch (error) {
-			throw toPartnerError(error);
+			return err(toPartnerError(error));
 		}
 	}
+	async function request(path, init = {}, responseSchema) {
+		return unwrapResult(await requestResult(path, init, responseSchema), partnerErrorToException);
+	}
 	return {
 		whoami() {
 			return request(analyticsRoutes.whoami, {}, partnerEndpointSchemas.analyticsWhoami.response);
@@ -359,8 +373,16 @@ function dataDetailQuery(state, options) {
 	if (opts?.comparison) query.qc = JSON.stringify(withDefaultSearchType(opts.comparison, scoped.searchType));
 	return query;
 }
+function validateAnalysisParamsResult(params) {
+	if ((params.preset === "non-brand" || params.preset === "brand-only") && !params.brandTerms?.trim()) return err(new PartnerApiError({
+		kind: "validation",
+		statusCode: 400,
+		message: "brandTerms is required for brand/non-brand presets"
+	}));
+	return ok(params);
+}
 function assertAnalysisParams(params) {
-	if ((params.preset === "non-brand" || params.preset === "brand-only") && !params.brandTerms?.trim()) throw new Error("brandTerms is required for brand/non-brand presets");
+	unwrapResult(validateAnalysisParamsResult(params), partnerErrorToException);
 }
 function analysisQuery(params) {
 	const query = {
@@ -442,18 +464,91 @@ function sleep(ms) {
 function createPartnerClient(options = {}) {
 	const fetchImpl = options.fetch ?? ofetch;
 	const apiBase = trimApiBase(options.apiBase);
-	async function request(path, init = {}, responseSchema) {
+	async function requestResult(path, init = {}, responseSchema) {
 		const headers = mergeHeaders(await resolveHeaders(options), init.headers);
 		try {
 			const out = await fetchImpl(buildPath(apiBase, path), {
 				...init,
 				headers
 			});
-			return shouldValidate(options, "response") ? parseWith(responseSchema, out) : out;
+			return ok(shouldValidate(options, "response") ? parseWith(responseSchema, out) : out);
 		} catch (error) {
-			throw toPartnerError(error);
+			return err(toPartnerError(error));
 		}
 	}
+	async function request(path, init = {}, responseSchema) {
+		return unwrapResult(await requestResult(path, init, responseSchema), partnerErrorToException);
+	}
+	async function waitForUserReadyResult(userId, waitOptions = {}) {
+		const attempts = waitOptions.attempts ?? 12;
+		const intervalMs = waitOptions.intervalMs ?? 1e3;
+		let latest = null;
+		for (let attempt = 0; attempt < attempts; attempt++) {
+			const result = await requestResult(partnerRoutes.users.status(userId));
+			if (!result.ok) return result;
+			latest = result.value;
+			if (latest.status === "ready") return ok(latest);
+			if (attempt < attempts - 1) await sleep(intervalMs);
+		}
+		return err(new PartnerApiError({
+			kind: "provisioning",
+			statusCode: 409,
+			message: "gscdump user database is still provisioning",
+			data: latest
+		}));
+	}
+	function waitForUserReadyToException(error) {
+		const e = new Error(error.message);
+		e.data = error.data;
+		return e;
+	}
+	async function waitForUserLifecycleReadyResult(userId, waitOptions = {}) {
+		const attempts = waitOptions.attempts ?? 12;
+		const intervalMs = waitOptions.intervalMs ?? 1e3;
+		let latest = null;
+		for (let attempt = 0; attempt < attempts; attempt++) {
+			const result = await requestResult(partnerRoutes.users.lifecycle(userId));
+			if (!result.ok) return result;
+			latest = result.value;
+			const status = latest.account.status;
+			if (status === "ready") return ok(latest);
+			if (status === "refresh_missing" || status === "scope_missing" || status === "reauth_required") return err(new PartnerApiError({
+				kind: "auth",
+				statusCode: 401,
+				message: "Google Search Console authorization must be refreshed",
+				data: latest.account
+			}));
+			if (status === "disconnected" || status === "oauth_received") return err(new PartnerApiError({
+				kind: "provisioning",
+				statusCode: 409,
+				message: "gscdump user is not fully connected",
+				data: latest.account
+			}));
+			if (attempt < attempts - 1) await sleep(intervalMs);
+		}
+		return err(new PartnerApiError({
+			kind: "provisioning",
+			statusCode: 409,
+			message: "gscdump user database is still provisioning",
+			data: latest
+		}));
+	}
+	async function getSiteSyncStatusResult(siteId, userId) {
+		if (!userId) return requestResult(partnerRoutes.sites.syncStatus(siteId));
+		const lifecycle = await requestResult(partnerRoutes.users.lifecycle(userId));
+		if (!lifecycle.ok) return lifecycle;
+		const site = findLifecycleSite(lifecycle.value, siteId);
+		if (!site) return err(new PartnerApiError({
+			kind: "not-found",
+			statusCode: 404,
+			message: "gscdump lifecycle site not found",
+			data: {
+				siteId,
+				userId
+			}
+		}));
+		return ok(lifecycleSiteToSyncStatus(site));
+	}
 	return {
 		registerUser(params) {
 			const body = shouldValidate(options, "request") ? partnerEndpointSchemas.registerUser.body.parse(params) : params;
@@ -476,46 +571,10 @@ function createPartnerClient(options = {}) {
 			return request(partnerRoutes.users.lifecycle(userId));
 		},
 		async waitForUserReady(userId, waitOptions = {}) {
-			const attempts = waitOptions.attempts ?? 12;
-			const intervalMs = waitOptions.intervalMs ?? 1e3;
-			let latest = null;
-			for (let attempt = 0; attempt < attempts; attempt++) {
-				latest = await request(partnerRoutes.users.status(userId));
-				if (latest.status === "ready") return latest;
-				if (attempt < attempts - 1) await sleep(intervalMs);
-			}
-			const err = /* @__PURE__ */ new Error("gscdump user database is still provisioning");
-			err.data = latest;
-			throw err;
+			return unwrapResult(await waitForUserReadyResult(userId, waitOptions), waitForUserReadyToException);
 		},
 		async waitForUserLifecycleReady(userId, waitOptions = {}) {
-			const attempts = waitOptions.attempts ?? 12;
-			const intervalMs = waitOptions.intervalMs ?? 1e3;
-			let latest = null;
-			for (let attempt = 0; attempt < attempts; attempt++) {
-				latest = await request(partnerRoutes.users.lifecycle(userId));
-				const status = latest.account.status;
-				if (status === "ready") return latest;
-				if (status === "refresh_missing" || status === "scope_missing" || status === "reauth_required") throw new PartnerApiError({
-					kind: "auth",
-					statusCode: 401,
-					message: "Google Search Console authorization must be refreshed",
-					data: latest.account
-				});
-				if (status === "disconnected" || status === "oauth_received") throw new PartnerApiError({
-					kind: "provisioning",
-					statusCode: 409,
-					message: "gscdump user is not fully connected",
-					data: latest.account
-				});
-				if (attempt < attempts - 1) await sleep(intervalMs);
-			}
-			throw new PartnerApiError({
-				kind: "provisioning",
-				statusCode: 409,
-				message: "gscdump user database is still provisioning",
-				data: latest
-			});
+			return unwrapResult(await waitForUserLifecycleReadyResult(userId, waitOptions), partnerErrorToException);
 		},
 		getUserSites(userId) {
 			return request(partnerRoutes.users.sites(userId), {}, partnerEndpointSchemas.getUserSites.response);
@@ -547,18 +606,7 @@ function createPartnerClient(options = {}) {
 			return request(partnerRoutes.sites.analysisSources(siteId), { query: tablesQuery(tables, options) }, partnerEndpointSchemas.getAnalysisSources.response);
 		},
 		async getSiteSyncStatus(siteId, userId) {
-			if (!userId) return request(partnerRoutes.sites.syncStatus(siteId));
-			const site = findLifecycleSite(await request(partnerRoutes.users.lifecycle(userId)), siteId);
-			if (!site) throw new PartnerApiError({
-				kind: "not-found",
-				statusCode: 404,
-				message: "gscdump lifecycle site not found",
-				data: {
-					siteId,
-					userId
-				}
-			});
-			return lifecycleSiteToSyncStatus(site);
+			return unwrapResult(await getSiteSyncStatusResult(siteId, userId), partnerErrorToException);
 		},
 		getData(siteId, state, queryOptions) {
 			if (shouldValidate(options, "request")) {
@@ -2197,18 +2245,21 @@ async function verifyWebhookSignature(payload, signature, secret) {
 	if (!received) return false;
 	return constantTimeEqual(new Uint8Array(await hmacSha256(toPayloadString(payload), secret)), received);
 }
-async function parseWebhookPayload(payload, options = {}) {
+async function parseWebhookPayloadResult(payload, options = {}) {
 	const payloadString = toPayloadString(payload);
 	const signature = options.signature ?? readWebhookHeaders(options.headers).signature;
 	if (options.secret && (options.validateSignature ?? true)) {
-		if (!await verifyWebhookSignature(payloadString, signature, options.secret)) throw new PartnerApiError({
+		if (!await verifyWebhookSignature(payloadString, signature, options.secret)) return err(new PartnerApiError({
 			kind: "auth",
 			statusCode: 401,
 			message: "Invalid webhook signature"
-		});
+		}));
 	}
 	const parsed = typeof payload === "string" ? JSON.parse(payload) : payload;
-	return partnerWebhookEnvelopeSchema.parse(parsed);
+	return ok(partnerWebhookEnvelopeSchema.parse(parsed));
+}
+async function parseWebhookPayload(payload, options = {}) {
+	return unwrapResult(await parseWebhookPayloadResult(payload, options), partnerErrorToException);
 }
 function readWebhookHeaders(headers) {
 	if (!headers) return {
@@ -2233,4 +2284,4 @@ function readWebhookHeaders(headers) {
 		signature: headers.signature ?? null
 	};
 }
-export { ARCHETYPE_EXECUTION_CLASS, CANONICAL_WEBHOOK_EVENTS, COMPARE_OPTIONS, COUNTRY_NAMES, CWV_GOOD_CLS, CWV_GOOD_INP, CWV_GOOD_LCP, CWV_POOR_CLS, CWV_POOR_INP, CWV_POOR_LCP, GSC_COLUMN_OPTIONS, GSC_PERIOD_OPTIONS, GSC_PERIOD_OPTIONS_LONG, GSC_STABLE_LATENCY_DAYS, PERIOD_PRESETS, PartnerApiError, SITE_TYPE_BASELINE, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, analyticsStatusToSyncStatus, andFilter, classifyGscError, classifyHealthStage, classifyReachStage, classifySearchConsoleStage, classifySiteTriage, coerceRowMetrics, compareRange, countryName, coverageLabel, coverageLabels, createAnalyticsClient, createGscdumpClient, createGscdumpRealtimeClient, createPartnerClient, createPartnerRealtimeClient, cwvBucket, dateFilter, defineGscAnalyzer, derivePeerStanding, deriveSiteBaseline, enrichIssueDetails, findLifecycleSite, getGscUnstableCutoffDate, gscConsoleUrl, investigationStatusConfig, isCustomPeriod, issueDetails, issueGroups, issueTypeToGroup, lifecycleSiteToSyncStatus, lifecycleSiteToUserSite, normalizeSiteType, nuxtSeoTips, parseCustomPeriod, parseWebhookPayload, periodToDateRange, periodToDays, positionFor, reachLivenessRatio, readWebhookHeaders, serializeWebhookPayload, severityOrder, siteTypeBaseline, siteUrlToHostname, splitOpportunityTitle, summarizeDailyRows, toPartnerError, truncateQuery, verifyWebhookSignature, weightedAnonPct };
+export { ARCHETYPE_EXECUTION_CLASS, CANONICAL_WEBHOOK_EVENTS, COMPARE_OPTIONS, COUNTRY_NAMES, CWV_GOOD_CLS, CWV_GOOD_INP, CWV_GOOD_LCP, CWV_POOR_CLS, CWV_POOR_INP, CWV_POOR_LCP, GSC_COLUMN_OPTIONS, GSC_PERIOD_OPTIONS, GSC_PERIOD_OPTIONS_LONG, GSC_STABLE_LATENCY_DAYS, PERIOD_PRESETS, PartnerApiError, SITE_TYPE_BASELINE, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, analyticsStatusToSyncStatus, andFilter, classifyGscError, classifyHealthStage, classifyReachStage, classifySearchConsoleStage, classifySiteTriage, coerceRowMetrics, compareRange, countryName, coverageLabel, coverageLabels, createAnalyticsClient, createGscdumpClient, createGscdumpRealtimeClient, createPartnerClient, createPartnerRealtimeClient, cwvBucket, dateFilter, defineGscAnalyzer, derivePeerStanding, deriveSiteBaseline, enrichIssueDetails, findLifecycleSite, formatPartnerError, getGscUnstableCutoffDate, gscConsoleUrl, investigationStatusConfig, isCustomPeriod, isPartnerError, issueDetails, issueGroups, issueTypeToGroup, lifecycleSiteToSyncStatus, lifecycleSiteToUserSite, normalizeSiteType, nuxtSeoTips, parseCustomPeriod, parseWebhookPayload, parseWebhookPayloadResult, partnerErrorToException, periodToDateRange, periodToDays, positionFor, reachLivenessRatio, readWebhookHeaders, serializeWebhookPayload, severityOrder, siteTypeBaseline, siteUrlToHostname, splitOpportunityTitle, summarizeDailyRows, toPartnerError, truncateQuery, verifyWebhookSignature, weightedAnonPct };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/sdk",
   "type": "module",
-  "version": "0.25.13",
+  "version": "0.26.0",
   "description": "Consumer SDK for hosted gscdump.com integrations.",
   "author": {
     "name": "Harlan Wilton",
@@ -40,25 +40,18 @@
   "engines": {
     "node": ">=18"
   },
-  "peerDependencies": {
-    "gscdump": "0.25.13"
-  },
-  "peerDependenciesMeta": {
-    "gscdump": {
-      "optional": true
-    }
-  },
   "dependencies": {
     "date-fns": "^4.4.0",
     "ofetch": "^1.5.1",
     "zod": "^4.4.3",
-    "@gscdump/analysis": "0.25.13",
-    "@gscdump/contracts": "0.25.13",
-    "@gscdump/engine": "0.25.13"
+    "@gscdump/analysis": "0.26.0",
+    "@gscdump/contracts": "0.26.0",
+    "@gscdump/engine": "0.26.0",
+    "gscdump": "0.26.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
   "scripts": {
     "build": "obuild",