@gscdump/engine 0.6.1 → 0.6.3

package/dist/_chunks/schema.mjs

@@ -0,0 +1,139 @@
+import { date, doublePrecision, getTableConfig, integer, pgTable, varchar } from "drizzle-orm/pg-core";
+function metricCols() {
+	return {
+		clicks: integer("clicks").notNull(),
+		impressions: integer("impressions").notNull(),
+		sum_position: doublePrecision("sum_position").notNull()
+	};
+}
+const dateCol = () => date("date").notNull();
+const pages = pgTable("pages", {
+	url: varchar("url").notNull(),
+	date: dateCol(),
+	...metricCols()
+});
+const keywords = pgTable("keywords", {
+	query: varchar("query").notNull(),
+	query_canonical: varchar("query_canonical"),
+	date: dateCol(),
+	...metricCols()
+});
+const countries = pgTable("countries", {
+	country: varchar("country").notNull(),
+	date: dateCol(),
+	...metricCols()
+});
+const devices = pgTable("devices", {
+	device: varchar("device").notNull(),
+	date: dateCol(),
+	...metricCols()
+});
+const page_keywords = pgTable("page_keywords", {
+	url: varchar("url").notNull(),
+	query: varchar("query").notNull(),
+	query_canonical: varchar("query_canonical"),
+	date: dateCol(),
+	...metricCols()
+});
+const search_appearance = pgTable("search_appearance", {
+	searchAppearance: varchar("searchAppearance").notNull(),
+	date: dateCol(),
+	...metricCols()
+});
+const drizzleSchema = {
+	pages,
+	keywords,
+	countries,
+	devices,
+	page_keywords,
+	search_appearance
+};
+const TABLE_METADATA = {
+	pages: {
+		sortKey: ["date", "url"],
+		version: 1
+	},
+	keywords: {
+		sortKey: ["date", "query"],
+		version: 2
+	},
+	countries: {
+		sortKey: ["date", "country"],
+		version: 1
+	},
+	devices: {
+		sortKey: ["date", "device"],
+		version: 1
+	},
+	page_keywords: {
+		sortKey: [
+			"date",
+			"url",
+			"query"
+		],
+		version: 2
+	},
+	search_appearance: {
+		sortKey: ["date", "searchAppearance"],
+		version: 1
+	}
+};
+function pgSqlTypeToColumnType(sqlType) {
+	const t = sqlType.toLowerCase();
+	if (t.startsWith("varchar") || t === "text" || t.startsWith("char")) return "VARCHAR";
+	if (t === "date" || t.startsWith("timestamp")) return "DATE";
+	if (t.startsWith("double") || t === "real" || t.startsWith("numeric") || t.startsWith("decimal")) return "DOUBLE";
+	if (t === "bigint" || t === "int8") return "BIGINT";
+	if (t === "integer" || t === "int" || t === "int4" || t === "smallint" || t === "int2") return "INTEGER";
+	throw new Error(`unmapped pg type '${sqlType}' — extend pgSqlTypeToColumnType in @gscdump/engine/schema`);
+}
+function tableSchemaFrom(tableName) {
+	const columns = getTableConfig(drizzleSchema[tableName]).columns.map((col) => ({
+		name: col.name,
+		type: pgSqlTypeToColumnType(col.getSQLType()),
+		nullable: !col.notNull
+	}));
+	const meta = TABLE_METADATA[tableName];
+	return {
+		name: tableName,
+		columns,
+		sortKey: meta.sortKey,
+		version: meta.version
+	};
+}
+const METRIC_TABLES = [
+	"pages",
+	"keywords",
+	"countries",
+	"devices",
+	"page_keywords",
+	"search_appearance"
+];
+const SCHEMAS = Object.fromEntries(METRIC_TABLES.map((t) => [t, tableSchemaFrom(t)]));
+function currentSchemaVersion(table) {
+	return SCHEMAS[table].version;
+}
+function schemaFor(table) {
+	return SCHEMAS[table];
+}
+function allTables() {
+	return METRIC_TABLES;
+}
+function inferTable(dimensions) {
+	const dims = new Set(dimensions);
+	const hasPage = dims.has("page");
+	const hasQuery = dims.has("query");
+	if (hasPage && hasQuery) return "page_keywords";
+	if (hasQuery) return "keywords";
+	if (hasPage) return "pages";
+	if (dims.has("country")) return "countries";
+	if (dims.has("device")) return "devices";
+	if (dims.has("searchAppearance")) return "search_appearance";
+	return "keywords";
+}
+function dimensionToColumn(dim, _table) {
+	if (dim === "page") return "url";
+	if (dim === "queryCanonical") return "query_canonical";
+	return dim;
+}
+export { inferTable as a, countries as c, keywords as d, page_keywords as f, dimensionToColumn as i, devices as l, search_appearance as m, allTables as n, schemaFor as o, pages as p, currentSchemaVersion as r, TABLE_METADATA as s, SCHEMAS as t, drizzleSchema as u };

package/dist/_chunks/storage.d.mts

@@ -0,0 +1,476 @@
+import { t as ComparisonFilter } from "./types.mjs";
+import { Row, Row as Row$1, TableName, TableName as TableName$1, TenantCtx, TenantCtx as TenantCtx$1 } from "gscdump/contracts";
+import { BuilderState, SearchType, SearchType as SearchType$1 } from "gscdump/query";
+/**
+ * Per-tier age threshold in days. Default ladder collapses on these gates:
+ * - raw → d7 once a daily file is older than `raw` days (default 7).
+ * - d7 → d30 once the entire weekly bucket sits behind `d7` days (default 30).
+ * - d30 → d90 once the entire monthly bucket sits behind `d30` days (default 90).
+ */
+interface CompactionThresholds {
+  raw?: number;
+  d7?: number;
+  d30?: number;
+}
+declare function enumeratePartitions(startDate: string, endDate: string): string[];
+/**
+ * Default `searchType` for entries written before the field landed and for
+ * sync paths that don't request a specific type. GSC's own default; the
+ * vast majority of stored data is web-search.
+ */
+declare const DEFAULT_SEARCH_TYPE: SearchType;
+interface WriteCtx extends TenantCtx {
+  table: TableName;
+  date?: string;
+  now?: () => number;
+  /**
+   * GSC search-type partition this write belongs to. Defaults to `'web'`.
+   * Non-web values (`discover`, `news`, `googleNews`, `image`, `video`)
+   * cause the writer to insert the type into the object key path so files
+   * for different search types coexist without colliding.
+   */
+  searchType?: SearchType;
+}
+interface QueryCtx extends TenantCtx {
+  table?: TableName;
+  signal?: AbortSignal;
+}
+interface GcCtx {
+  now?: () => number;
+  userId?: string;
+  siteId?: string;
+}
+/**
+ * Compaction tier of a manifest entry. Determines which compactor stage may
+ * pick it up as input:
+ * - `raw`: per-day file produced by `writeDay`. Eligible for raw→d7 merge at 7d.
+ * - `d7`: weekly compaction output. Eligible for d7→d30 merge at 30d.
+ * - `d30`: monthly compaction output (matches the legacy `monthly/` partition
+ *   shape — pre-tier entries are read as `d30`). Eligible for d30→d90 at 90d.
+ * - `d90`: quarterly cold-tier output. Terminal; never recompacted.
+ *
+ * Without an explicit tier, entries written before this field landed default
+ * to `raw` for `daily/` partitions and `d30` for `monthly/` partitions, so
+ * the tiered compactor picks the right inputs without a backfill rewrite.
+ */
+type CompactionTier = 'raw' | 'd7' | 'd30' | 'd90';
+interface ManifestEntry {
+  userId: string;
+  siteId?: string;
+  table: TableName;
+  partition: string;
+  objectKey: string;
+  rowCount: number;
+  bytes: number;
+  createdAt: number;
+  retiredAt?: number;
+  /** Table schema version at write time. Omitted on pre-#27 entries — treat as 1. */
+  schemaVersion?: number;
+  /**
+   * Compaction tier. Omitted on entries written before tiered compaction —
+   * treat as `raw` for `daily/` partitions and `d30` for `monthly/` partitions
+   * (see {@link inferLegacyTier}).
+   */
+  tier?: CompactionTier;
+  /**
+   * GSC search-type this entry covers (web | discover | news | googleNews |
+   * image | video). Omitted on entries written before per-type partitioning
+   * landed — treat as `web` (see {@link inferSearchType}). Compaction merges
+   * only entries with the same searchType.
+   */
+  searchType?: SearchType;
+}
+/**
+ * Resolve the search type for an entry, defaulting legacy entries to `web`.
+ * Use this anywhere code needs to bucket entries by searchType.
+ */
+declare function inferSearchType(entry: Pick<ManifestEntry, 'searchType'>): SearchType;
+/**
+ * Infer the tier for an entry that pre-dates the `tier` field. Daily files
+ * are `raw`; monthly files are `d30`. Anything else (already migrated, or
+ * a partition shape we haven't seen) returns undefined and the caller must
+ * decide how to handle it.
+ */
+declare function inferLegacyTier(entry: Pick<ManifestEntry, 'partition' | 'tier'>): CompactionTier | undefined;
+interface ListLiveFilter {
+  userId: string;
+  siteId?: string;
+  table?: TableName;
+  partitions?: string[];
+  /**
+   * Narrow to a single compaction tier. Tier-aware compaction stages set this
+   * so the store doesn't have to return (and the caller doesn't have to scan)
+   * the entire manifest just to compact the raw cohort. Legacy entries without
+   * an explicit `tier` field match on {@link inferLegacyTier}.
+   */
+  tier?: CompactionTier;
+}
+interface DataSource {
+  read: (key: string, range?: {
+    offset: number;
+    length: number;
+  }, signal?: AbortSignal) => Promise<Uint8Array>;
+  write: (key: string, bytes: Uint8Array) => Promise<void>;
+  delete: (keys: string[]) => Promise<void>;
+  /**
+   * One-shot listing under a prefix. Implementations may cap the number of
+   * returned keys (typically 10k) — callers iterating full tenant space
+   * should prefer `streamList` when available or narrow the prefix.
+   */
+  list: (prefix: string) => Promise<string[]>;
+  /**
+   * Per-key URI probe. Returns a URI string DuckDB's `httpfs` (or an
+   * equivalent engine that fetches its own I/O) can read directly, or
+   * `undefined` if the key isn't URI-resolvable on this backend and the
+   * caller must fall back to `read(key)` for the bytes.
+   *
+   * Contracts:
+   * - When defined, the returned URI MUST yield byte-identical content to
+   *   `read(key)`. Callers rely on this for correctness.
+   * - Backends with a native URI for every key (filesystem: absolute path,
+   *   R2 via `httpfs`: signed URL) may always return a string.
+   * - Backends without a native URI shape (in-memory) omit the method or
+   *   return `undefined` per call.
+   * - Mixed-per-query is allowed: some keys in one query may return a URI,
+   *   others may not; the executor branches per key.
+   */
+  uri?: (key: string) => string | undefined;
+  /**
+   * Optional — probe the byte size of a key without reading it. Used by
+   * the engine to fill in `WriteResult.bytes` when a codec reports 0 or
+   * unknown but the file is non-trivial.
+   */
+  head?: (key: string) => Promise<{
+    bytes: number;
+  } | undefined>;
+  /**
+   * Optional streaming variant of `list`. Implementations that page
+   * backing-store results (R2, S3) should implement this and yield keys
+   * lazily. `list` may return up to an adapter-defined cap (typically
+   * 10k keys); callers iterating full tenant space must prefer
+   * `streamList` when available, or chunk by narrower prefixes.
+   */
+  streamList?: (prefix: string) => AsyncIterable<string>;
+}
+interface WatermarkScope {
+  userId: string;
+  siteId?: string;
+  table: TableName;
+}
+interface Watermark extends WatermarkScope {
+  newestDateSynced: string;
+  oldestDateSynced: string;
+  lastSyncAt: number;
+}
+interface WatermarkFilter {
+  userId: string;
+  siteId?: string;
+  table?: TableName;
+}
+type SyncStateKind = 'pending' | 'inflight' | 'done' | 'failed';
+interface SyncStateScope {
+  userId: string;
+  siteId?: string;
+  table: TableName;
+  date: string;
+  /**
+   * GSC search-type this sync state covers. Omitted = `web` (the legacy
+   * default; matches pre-#5 sync states stored before per-type sync landed).
+   * Lookups must compare via {@link inferSearchType} so a missing field
+   * matches an explicit `'web'` and vice versa.
+   */
+  searchType?: SearchType;
+}
+interface SyncState extends SyncStateScope {
+  state: SyncStateKind;
+  updatedAt: number;
+  attempts: number;
+  error?: string;
+}
+interface SyncStateFilter {
+  userId: string;
+  siteId?: string;
+  table?: TableName;
+  state?: SyncStateKind;
+  searchType?: SearchType;
+}
+interface SyncStateDetail {
+  at?: number;
+  error?: string;
+}
+interface LockScope {
+  userId: string;
+  siteId?: string;
+  table: TableName;
+  partition: string;
+}
+interface PurgeFilter {
+  userId: string;
+  siteId?: string;
+}
+interface ManifestPurgeResult {
+  entriesRemoved: number;
+  watermarksRemoved: number;
+  syncStatesRemoved: number;
+}
+interface PurgeResult {
+  userId: string;
+  siteId?: string;
+  prefix: string;
+  objectsDeleted: number;
+  entriesRemoved: number;
+  watermarksRemoved: number;
+  syncStatesRemoved: number;
+  at: number;
+}
+interface PurgeUrlsResult {
+  userId: string;
+  siteId?: string;
+  urlsRequested: number;
+  entriesRewritten: number;
+  rowsRemoved: number;
+  bytesAfter: number;
+  at: number;
+}
+interface ManifestStore {
+  listLive: (filter: ListLiveFilter) => Promise<ManifestEntry[]>;
+  listAll: (filter: ListLiveFilter) => Promise<ManifestEntry[]>;
+  registerVersion: (entry: ManifestEntry, superseding?: ManifestEntry[]) => Promise<void>;
+  registerVersions: (entries: ManifestEntry[], superseding?: ManifestEntry[]) => Promise<void>;
+  listRetired: (olderThan: number) => Promise<ManifestEntry[]>;
+  delete: (entries: ManifestEntry[]) => Promise<void>;
+  getWatermarks: (filter: WatermarkFilter) => Promise<Watermark[]>;
+  bumpWatermark: (scope: WatermarkScope, date: string, at?: number) => Promise<void>;
+  getSyncStates: (filter: SyncStateFilter) => Promise<SyncState[]>;
+  setSyncState: (scope: SyncStateScope, state: SyncStateKind, detail?: SyncStateDetail) => Promise<void>;
+  /**
+   * Serialize concurrent writers against the same scope. Held across the
+   * write+register window so GC (orphan sweep) won't delete bytes that are
+   * midway between `dataSource.write` and `manifestStore.registerVersion`.
+   * Scope = tenant × table × partition.
+   */
+  withLock: <T>(scope: LockScope, fn: () => Promise<T>) => Promise<T>;
+  /**
+   * GDPR-grade tenant purge. Removes every manifest entry, watermark, and
+   * sync-state record matching the filter. Does NOT touch the underlying
+   * data-source bytes; callers (typically {@link StorageEngine.purgeTenant})
+   * must sweep the tenant prefix separately before invoking this so that
+   * mid-flight failures can't leave orphan parquet with no manifest record.
+   *
+   * On stores with CAS-backed sharding (R2 manifest) this may issue one
+   * mutation per shard. On read-only stores (HTTP) this throws.
+   */
+  purgeTenant: (filter: PurgeFilter) => Promise<ManifestPurgeResult>;
+}
+interface WriteResult {
+  bytes: number;
+  rowCount: number;
+}
+interface CodecCtx {
+  table: TableName;
+}
+/**
+ * Key-oriented codec. Each method owns its I/O through `dataSource`:
+ * - Node / browser codecs read/write bytes via `dataSource.read` / `.write`.
+ * - Workers codecs let DuckDB's httpfs read/write remote URIs directly (via
+ *   `dataSource.uri`) and never materialise bytes in JS.
+ *
+ * The engine never touches bytes; it just hands rows + keys to the codec.
+ *
+ * Invariants every implementation MUST uphold:
+ * - `writeRows` with an empty `rows` array MUST still write a file
+ *   carrying the canonical column set for `ctx.table` — a schema-correct
+ *   empty file. No placeholder-column shortcuts; readers depend on the
+ *   schema being present for `union_by_name` merges.
+ * - `WriteResult.bytes` MUST be the real byte size written to the
+ *   data source (not 0, not an estimate) so the engine can enforce the
+ *   payload ceiling without a second `head` round-trip.
+ * - `WriteResult.rowCount` MUST equal `rows.length` (or, for
+ *   `compactRows`, the sum of input row counts).
+ */
+interface ParquetCodec {
+  writeRows: (ctx: CodecCtx, rows: Row[], key: string, dataSource: DataSource) => Promise<WriteResult>;
+  readRows: (ctx: CodecCtx, key: string, dataSource: DataSource) => Promise<Row[]>;
+  compactRows: (ctx: CodecCtx, inputKeys: string[], outputKey: string, dataSource: DataSource) => Promise<WriteResult>;
+}
+interface QueryResult {
+  rows: Row[];
+  sql: string;
+  objectKeys: string[];
+}
+interface ComparisonResult {
+  rows: Row[];
+  totalCount: number;
+  totals: Record<string, unknown>;
+}
+interface ExtraResult {
+  key: string;
+  rows: Row[];
+}
+interface QueryExecuteOptions {
+  sql: string;
+  params: unknown[];
+  /**
+   * Named placeholder → object keys. The executor substitutes `{{NAME}}`
+   * occurrences in the SQL with the matching `read_parquet([...])` list,
+   * choosing between virtual-FS names or native URIs based on whether
+   * `dataSource.uri` is available.
+   */
+  fileKeys: Record<string, string[]>;
+  dataSource: DataSource;
+  table: TableName;
+  signal?: AbortSignal;
+  /**
+   * Optional callback invoked by the executor when it detects the DuckDB
+   * process is approaching a memory ceiling (e.g. ingesting rows after
+   * httpfs decode, or materialising a large temp relation). Callers can
+   * shed work, warm a spillover path, or warn the user. Advisory only —
+   * not all executors implement it.
+   */
+  onMemoryPressure?: (info: {
+    bytes?: number;
+    reason: string;
+  }) => void;
+}
+interface QueryExecuteResult {
+  rows: Row[];
+  /** The final SQL actually run (after placeholder substitution). */
+  sql: string;
+  /**
+   * Optional diagnostics the executor may emit for observability + capacity
+   * planning. Undefined on executors that don't instrument their runtime.
+   *
+   * - `peakBytes`: highest resident memory the engine reported during the
+   *   query. Callers may use this to decide whether to drop / compact state
+   *   before the next call.
+   * - `resetRecommended`: executor thinks the underlying connection should
+   *   be recycled (fragmented, near ceiling). Caller-owned decision —
+   *   honored by `BrowserAnalysisRuntime` consumers but not enforced.
+   */
+  diagnostics?: {
+    peakBytes?: number;
+    resetRecommended?: boolean;
+  };
+}
+interface QueryExecutor {
+  execute: (opts: QueryExecuteOptions) => Promise<QueryExecuteResult>;
+}
+interface FileSetRef {
+  table: TableName;
+  partitions?: string[];
+}
+interface RunSQLOptions {
+  ctx: TenantCtx;
+  /**
+   * Named partition references. Each name becomes a `{{NAME}}` placeholder
+   * substituted into the SQL with the matching list of object keys. The
+   * canonical name is `FILES`; analyzers also use `FILES_PREV` for a prior
+   * window. Providing zero fileSets runs the SQL against no files.
+   */
+  fileSets: Record<string, FileSetRef>;
+  /** Schema-bearing table; defaults to the first fileSet's table. */
+  table?: TableName;
+  sql: string;
+  params?: unknown[];
+  signal?: AbortSignal;
+}
+interface StorageEngine {
+  writeDay: (ctx: WriteCtx, rows: Row[]) => Promise<void>;
+  query: (ctx: QueryCtx, state: BuilderState) => Promise<QueryResult>;
+  /**
+   * Two-window comparison query (resolver-compiled). Joins a `current` and
+   * `previous` window CTE on dimensions, applies an optional row filter
+   * (`new`/`lost`/`improving`/`declining`), and returns the merged rows plus
+   * total count and unfiltered totals.
+   *
+   * Tenant scoping comes from `ctx.userId`/`ctx.siteId` (manifest lookup) —
+   * the SQL itself is single-tenant against the parquet adapter, which has
+   * `includeSiteId: false`.
+   *
+   * Throws if `current` and `previous` resolve to different tables.
+   */
+  queryComparison: (ctx: QueryCtx, current: BuilderState, previous: BuilderState, filter?: ComparisonFilter) => Promise<ComparisonResult>;
+  /**
+   * Canonical-variant enrichment queries. Returns one result per extra
+   * surface; today only `queryCanonical` triggers an extra. Empty array
+   * when the state has no extras-eligible dimensions.
+   */
+  queryExtras: (ctx: QueryCtx, state: BuilderState) => Promise<ExtraResult[]>;
+  /**
+   * Run arbitrary SQL resolved against named partition sets. Composes
+   * manifest lookup + object reads + placeholder substitution + execution
+   * so callers don't need to reach into `ManifestStore`/`DataSource`
+   * directly.
+   */
+  runSQL: (opts: RunSQLOptions) => Promise<QueryResult>;
+  compactTiered: (ctx: WriteCtx, thresholds?: CompactionThresholds) => Promise<void>;
+  gcOrphans: (ctx: GcCtx, graceMs: number) => Promise<{
+    deleted: number;
+  }>;
+  /**
+   * GDPR-grade tenant purge. Deletes every object under the tenant prefix
+   * (parquet, rollups, entity stores), then removes manifest/watermark/
+   * sync-state records via {@link ManifestStore.purgeTenant}.
+   *
+   * Order matters: bytes are deleted before manifest entries, so a
+   * crash mid-purge leaves orphan manifest records (detectable via the
+   * normal orphan sweep) rather than orphan bytes with no record.
+   *
+   * Returns counters suitable for an audit log. Caller is responsible
+   * for persisting the audit entry.
+   */
+  purgeTenant: (ctx: TenantCtx) => Promise<PurgeResult>;
+  /**
+   * GDPR URL-matcher purge. Deletes rows whose `url` column matches one of
+   * `urls` across every live parquet entry for the tenant in tables that
+   * carry a `url` column (`pages`, `page_keywords`). Tables without a `url`
+   * column (`keywords`, `countries`, `devices`, `search_appearance`) are
+   * untouched — they never store per-URL data.
+   *
+   * For each affected entry the engine reads the file, filters the matching
+   * rows out, writes a replacement parquet at a new object key, and registers
+   * the new entry as a supersede of the old. Entries with no matches are
+   * left untouched. Entries with all rows matching are replaced by a
+   * schema-bearing empty-rows file.
+   *
+   * Narrower counterpart to {@link purgeTenant}: use this for a per-URL
+   * takedown request; use `purgeTenant` for full-account deletion.
+   */
+  purgeUrls: (ctx: TenantCtx, urls: readonly string[]) => Promise<PurgeUrlsResult>;
+  listLive: (filter: ListLiveFilter) => Promise<ManifestEntry[]>;
+  listAll: (filter: ListLiveFilter) => Promise<ManifestEntry[]>;
+  getWatermarks: (filter: WatermarkFilter) => Promise<Watermark[]>;
+  getSyncStates: (filter: SyncStateFilter) => Promise<SyncState[]>;
+  setSyncState: (scope: SyncStateScope, state: SyncStateKind, detail?: SyncStateDetail) => Promise<void>;
+  /** Read the raw bytes of a single object. Rarely needed outside the `dump` CLI. */
+  readObject: (key: string) => Promise<Uint8Array>;
+}
+interface EngineOptions {
+  dataSource: DataSource;
+  manifestStore: ManifestStore;
+  codec: ParquetCodec;
+  executor: QueryExecutor;
+  now?: () => number;
+}
+declare function dayPartition(date: string): string;
+declare function monthPartition(month: string): string;
+/**
+ * Weekly partition keyed by the Monday-of-week ISO date (e.g. `weekly/2026-04-20`
+ * for the ISO week containing 2026-04-22). Names are stable + sortable; the
+ * dashboard never parses them, only reads via the manifest.
+ */
+declare function weekPartition(mondayIsoDate: string): string;
+/**
+ * Quarterly partition (e.g. `quarterly/2026-Q2` for Apr-Jun 2026). Used as the
+ * cold-tier shape for `d90` compaction outputs.
+ */
+declare function quarterPartition(quarter: string): string;
+/**
+ * Monday-of-week as a YYYY-MM-DD string for the ISO week containing `isoDate`.
+ * Used by tiered compaction to bucket raw daily files into weekly groups.
+ */
+declare function mondayOfWeek(isoDate: string): string;
+/** YYYY-Qq for the quarter containing the given YYYY-MM month string. */
+declare function quarterOfMonth(month: string): string;
+declare function objectKey(ctx: TenantCtx, table: TableName, partition: string, version: number, searchType?: SearchType): string;
+export { SyncStateFilter as A, dayPartition as B, QueryResult as C, StorageEngine as D, SearchType$1 as E, Watermark as F, objectKey as G, inferSearchType as H, WatermarkFilter as I, weekPartition as J, quarterOfMonth as K, WatermarkScope as L, SyncStateScope as M, TableName$1 as N, SyncState as O, TenantCtx$1 as P, WriteCtx as R, QueryExecutor as S, RunSQLOptions as T, mondayOfWeek as U, inferLegacyTier as V, monthPartition as W, enumeratePartitions as X, CompactionThresholds as Y, PurgeResult as _, DataSource as a, QueryExecuteOptions as b, FileSetRef as c, LockScope as d, ManifestEntry as f, PurgeFilter as g, ParquetCodec as h, DEFAULT_SEARCH_TYPE as i, SyncStateKind as j, SyncStateDetail as k, GcCtx as l, ManifestStore as m, CompactionTier as n, EngineOptions as o, ManifestPurgeResult as p, quarterPartition as q, ComparisonResult as r, ExtraResult as s, CodecCtx as t, ListLiveFilter as u, PurgeUrlsResult as v, Row$1 as w, QueryExecuteResult as x, QueryCtx as y, WriteResult as z };

package/dist/_chunks/storage.mjs

@@ -0,0 +1,39 @@
+import { MS_PER_DAY, toIsoDate } from "gscdump";
+const DEFAULT_SEARCH_TYPE = "web";
+function inferSearchType(entry) {
+	return entry.searchType ?? "web";
+}
+function inferLegacyTier(entry) {
+	if (entry.tier !== void 0) return entry.tier;
+	if (entry.partition.startsWith("daily/")) return "raw";
+	if (entry.partition.startsWith("monthly/")) return "d30";
+}
+function dayPartition(date) {
+	return `daily/${date}`;
+}
+function monthPartition(month) {
+	return `monthly/${month}`;
+}
+function weekPartition(mondayIsoDate) {
+	return `weekly/${mondayIsoDate}`;
+}
+function quarterPartition(quarter) {
+	return `quarterly/${quarter}`;
+}
+function mondayOfWeek(isoDate) {
+	const ms = Date.parse(`${isoDate}T00:00:00Z`);
+	const dow = new Date(ms).getUTCDay();
+	const offset = dow === 0 ? -6 : 1 - dow;
+	return toIsoDate(new Date(ms + offset * MS_PER_DAY));
+}
+function quarterOfMonth(month) {
+	const [y, m] = month.split("-").map(Number);
+	return `${y}-Q${Math.floor((m - 1) / 3) + 1}`;
+}
+function objectKey(ctx, table, partition, version, searchType) {
+	return `${ctx.siteId ? `u_${ctx.userId}/${ctx.siteId}/${table}` : `u_${ctx.userId}/${table}`}/${searchType !== void 0 && searchType !== "web" ? `${searchType}/` : ""}${partition}__v${version}.parquet`;
+}
+function tenantPrefix(ctx) {
+	return ctx.siteId ? `u_${ctx.userId}/${ctx.siteId}/` : `u_${ctx.userId}/`;
+}
+export { mondayOfWeek as a, quarterOfMonth as c, weekPartition as d, inferSearchType as i, quarterPartition as l, dayPartition as n, monthPartition as o, inferLegacyTier as r, objectKey as s, DEFAULT_SEARCH_TYPE as t, tenantPrefix as u };