@gscdump/sdk 5.6.0 → 5.7.1

package/dist/lifecycle.d.mts

@@ -1,12 +1,60 @@
-import { GscdumpSyncStatusResponse, GscdumpUserSite, PartnerLifecycleSite } from "@gscdump/contracts";
+import { GscdumpSyncStatusResponse, LifecycleProgress, PartnerLifecycleSite, SiteHoldReason } from "@gscdump/contracts";
 /**
  * Stable lifecycle fields shared by the legacy partner response and public v1.
  * Keeping the adapters structural lets consumers migrate to v1 without
  * re-introducing legacy-only fields such as `intId` or `lifecycleRevision`.
  */
 export type LifecycleSiteLike = Pick<PartnerLifecycleSite, 'siteId' | 'externalSiteId' | 'requestedUrl' | 'gscPropertyUrl' | 'permissionLevel' | 'analytics' | 'indexing' | 'latestError' | 'updatedAt'>;
-export declare function analyticsStatusToSyncStatus(status: LifecycleSiteLike['analytics']['status']): GscdumpUserSite['syncStatus'];
-export declare function lifecycleSiteToSyncStatus(site: LifecycleSiteLike): GscdumpSyncStatusResponse;
+/**
+ * A Site's Backfill, read from the lifecycle. Only `Ready` says the record
+ * serves reads: gscdump.com reports `ready` only once the Team catalog serves
+ * them.
+ *
+ * `analytics.queryable` never decides it. That flag is also true for
+ * `queryable_live`, where a partner reads Google live while the record holds
+ * 0 days, so a status-only mapping called a Site connected a second ago synced.
+ *
+ * - `Starting`: registered, and no Sync job has finished yet.
+ * - `Running`: Sync jobs are open.
+ * - `PreparingRecord`: the Backfill finished, and the record does not serve reads yet.
+ * - `Ready`: the record serves reads.
+ * - `NoRows`: every Sync job finished and none failed, but the host has no
+ *   Search Console rows, so the record never gets a synced range and the
+ *   lifecycle stays `queryable_live`.
+ * - `Partial`: some days failed to sync.
+ * - `Held`: no Backfill starts until the user acts. `size_pending` is still
+ *   measuring, so it reads as `Starting`.
+ * - `Failed`: the Backfill stopped.
+ */
+export type LifecycleBackfill = {
+  _tag: 'Starting';
+} | {
+  _tag: 'Running';
+} | {
+  _tag: 'PreparingRecord';
+} | {
+  _tag: 'Ready';
+} | {
+  _tag: 'NoRows';
+} | {
+  _tag: 'Partial';
+} | {
+  _tag: 'Held';
+  hold: Exclude<SiteHoldReason, 'size_pending'>;
+} | {
+  _tag: 'Failed';
+};
+/** The lifecycle fields the Backfill reader needs. A host older than contracts 4.7.0 sends no `hold`. */
+export interface LifecycleBackfillInput {
+  analytics: Pick<LifecycleSiteLike['analytics'], 'status'> & {
+    progress: Pick<LifecycleProgress, 'completed' | 'failed' | 'total'>;
+  };
+  hold?: SiteHoldReason | null;
+}
+export declare function resolveLifecycleBackfill(site: LifecycleBackfillInput): LifecycleBackfill;
+/** Whether the first Backfill is done: the record serves reads, or the host has no rows to read. */
+export declare function isLifecycleBackfillComplete(backfill: LifecycleBackfill): boolean;
+export declare function lifecycleSiteToSyncStatus(site: LifecycleSiteLike & Pick<LifecycleBackfillInput, 'hold'>): GscdumpSyncStatusResponse;
 export declare function findLifecycleSite<TSite extends LifecycleSiteLike>(lifecycle: {
   sites: readonly TSite[];
 }, siteIdOrPropertyUrl: string): TSite | null;

package/dist/lifecycle.mjs

@@ -8,26 +8,57 @@ function normalizeGscPropertyKey(url) {
 	if (!/^https?:\/\//.test(value)) return "";
 	return `url:${normalizeLifecycleUrl(value)}`;
 }
-function analyticsStatusToSyncStatus(status) {
+function resolveLifecycleBackfill(site) {
+	const { status, progress } = site.analytics;
+	const open = progress.total > 0 && progress.completed + progress.failed < progress.total;
+	const hold = site.hold && site.hold !== "size_pending" ? site.hold : null;
 	switch (status) {
-		case "ready":
+		case "ready": return { _tag: "Ready" };
+		case "failed": return { _tag: "Failed" };
+		case "syncing": return { _tag: "Running" };
+		case "preparing": return { _tag: "PreparingRecord" };
 		case "queryable_live":
-		case "queryable_partial": return "synced";
-		case "syncing":
-		case "preparing": return "syncing";
-		case "failed": return "error";
-		default: return "pending";
+			if (open) return { _tag: "Running" };
+			if (progress.failed > 0) return { _tag: "Partial" };
+			if (progress.total > 0 && progress.completed >= progress.total) return { _tag: "NoRows" };
+			return hold ? {
+				_tag: "Held",
+				hold
+			} : { _tag: "Starting" };
+		case "queryable_partial":
+			if (open) return { _tag: "Running" };
+			return progress.failed > 0 ? { _tag: "Partial" } : { _tag: "Running" };
+		default: return hold ? {
+			_tag: "Held",
+			hold
+		} : { _tag: "Starting" };
+	}
+}
+function isLifecycleBackfillComplete(backfill) {
+	return backfill._tag === "Ready" || backfill._tag === "NoRows";
+}
+function backfillSyncStatus(backfill) {
+	switch (backfill._tag) {
+		case "Starting":
+		case "Held": return "pending";
+		case "Running":
+		case "PreparingRecord": return "syncing";
+		case "Ready":
+		case "NoRows": return "synced";
+		case "Partial":
+		case "Failed": return "error";
 	}
 }
 function lifecycleSiteToSyncStatus(site) {
-	const syncStatus = analyticsStatusToSyncStatus(site.analytics.status);
+	const backfill = resolveLifecycleBackfill(site);
+	const isSyncing = backfill._tag === "Starting" || backfill._tag === "Running" || backfill._tag === "PreparingRecord";
 	const completed = site.analytics.progress.completed;
 	const failed = site.analytics.progress.failed;
 	const total = site.analytics.progress.total;
 	const queued = Math.max(total - completed - failed, 0);
 	return {
 		siteUrl: site.gscPropertyUrl || site.requestedUrl,
-		syncStatus,
+		syncStatus: backfillSyncStatus(backfill),
 		oldestDateAvailable: site.analytics.syncedRange.oldest,
 		oldestDateSynced: site.analytics.syncedRange.oldest,
 		newestDateSynced: site.analytics.syncedRange.newest,
@@ -35,11 +66,7 @@ function lifecycleSiteToSyncStatus(site) {
 		lastError: site.latestError?.message ?? null,
 		jobs: {
 			queued,
-			processing: [
-				"queued",
-				"preparing",
-				"syncing"
-			].includes(site.analytics.status) ? 1 : 0,
+			processing: isSyncing ? 1 : 0,
 			completed,
 			failed
 		},
@@ -47,13 +74,9 @@ function lifecycleSiteToSyncStatus(site) {
 		jobProgress: site.analytics.progress.percent,
 		daysSynced: completed,
 		daysAvailable: total,
-		isSyncing: [
-			"queued",
-			"preparing",
-			"syncing"
-		].includes(site.analytics.status),
+		isSyncing,
 		hasData: site.analytics.queryable,
-		isComplete: site.analytics.queryable && site.analytics.status === "ready",
+		isComplete: isLifecycleBackfillComplete(backfill),
 		tables: {}
 	};
 }
@@ -62,4 +85,4 @@ function findLifecycleSite(lifecycle, siteIdOrPropertyUrl) {
 	const propertyKey = normalizeGscPropertyKey(siteIdOrPropertyUrl);
 	return lifecycle.sites.find((site) => site.siteId === siteIdOrPropertyUrl || site.externalSiteId === siteIdOrPropertyUrl || !!propertyKey && normalizeGscPropertyKey(site.gscPropertyUrl) === propertyKey || !site.gscPropertyUrl && normalizeLifecycleUrl(site.requestedUrl) === normalized || !propertyKey && normalizeLifecycleUrl(site.requestedUrl) === normalized) ?? null;
 }
-export { analyticsStatusToSyncStatus, findLifecycleSite, lifecycleSiteToSyncStatus };
+export { findLifecycleSite, isLifecycleBackfillComplete, lifecycleSiteToSyncStatus, resolveLifecycleBackfill };

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "5.6.0";
+var version = "5.7.1";
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/sdk",
   "type": "module",
-  "version": "5.6.0",
+  "version": "5.7.1",
   "description": "Consumer SDK for hosted gscdump.com integrations.",
   "author": {
     "name": "Harlan Wilton",
@@ -144,8 +144,8 @@
     "node": ">=22.13.0"
   },
   "dependencies": {
-    "@gscdump/contracts": "^5.6.0",
-    "gscdump": "^5.6.0",
+    "@gscdump/contracts": "^5.7.1",
+    "gscdump": "^5.7.1",
     "ofetch": "^1.5.1",
     "zod": "^4.6.5"
   },