labre-mcp 0.1.0

package/dist/lib/patent/bigquery-client.mjs

@@ -0,0 +1,298 @@
+import { toErrorMessage } from '../errors.mjs';
+// BigQuery client configuration and authentication helper.
+//
+// Isolated module responsible for:
+//   1. Service account authentication (GOOGLE_APPLICATION_CREDENTIALS or ADC)
+//   2. Project/dataset configuration (BIGQUERY_PROJECT_ID env var)
+//   3. Connection pooling via singleton BigQuery client instance
+//   4. Configuration validation with clear error messages
+//
+// This module is consumed by BigQueryPatentSource (bigquery-patent-source.mjs)
+// and should NOT be imported directly by strategy code.
+//
+// Required environment variables:
+//   BIGQUERY_PROJECT_ID            - GCP project ID hosting BigQuery access
+//   GOOGLE_APPLICATION_CREDENTIALS - Path to service account JSON key file (standard GCP)
+//
+// Optional environment variables:
+//   BIGQUERY_DATASET       - Dataset override (default: 'patents-public-data')
+//   BIGQUERY_LOCATION      - BigQuery job location (default: 'US')
+//   BIGQUERY_MAX_BYTES     - Maximum bytes billed per query (default: 1GB)
+//   BIGQUERY_TIMEOUT_MS    - Query timeout in ms (default: 30000)
+//   BIGQUERY_SCOPES        - Comma-separated OAuth scopes (default: bigquery.readonly)
+// ─── Default configuration ──────────────────────────────────────────────────
+/**
+ * Default BigQuery configuration values.
+ * Tuned for the Google Patents Public Dataset with conservative billing limits.
+ *
+ * @type {Readonly<BigQueryConfig>}
+ */
+export const DEFAULTS = Object.freeze({
+    /** Google Patents Public Dataset — the primary data source for patent CPC data. */
+    dataset: 'patents-public-data',
+    /** BigQuery job location — US for the public patents dataset. */
+    location: 'US',
+    /** Maximum bytes billed per query (200 GB). Public dataset free tier is 1 TB/month. */
+    maxBytesBilled: String(200 * 1024 * 1024 * 1024), // '214748364800'
+    /** Query timeout in milliseconds (30 seconds). */
+    timeoutMs: 30_000,
+    /** OAuth scopes — read-only access is sufficient for patent queries. */
+    scopes: ['https://www.googleapis.com/auth/bigquery.readonly'],
+});
+// ─── Configuration typedefs ─────────────────────────────────────────────────
+/**
+ * BigQuery client configuration.
+ *
+ * @typedef {Object} BigQueryConfig
+ * @property {string}   projectId     - GCP project ID
+ * @property {string}   [keyFilename] - Path to service account JSON key file
+ * @property {string}   dataset       - BigQuery dataset name
+ * @property {string}   location      - BigQuery job location
+ * @property {string}   maxBytesBilled - Maximum bytes billed per query (string for BQ API)
+ * @property {number}   timeoutMs     - Query timeout in milliseconds
+ * @property {string[]} scopes        - OAuth scopes for authentication
+ */
+/**
+ * Validated and resolved configuration ready for BigQuery client instantiation.
+ *
+ * @typedef {Object} ResolvedConfig
+ * @property {string}   projectId      - Validated GCP project ID
+ * @property {string}   [keyFilename]  - Resolved path to credentials file (if set)
+ * @property {string}   dataset        - Dataset name
+ * @property {string}   location       - Job location
+ * @property {string}   maxBytesBilled - Max bytes as string
+ * @property {number}   timeoutMs      - Query timeout in ms
+ * @property {string[]} scopes         - OAuth scopes
+ */
+// ─── Configuration resolution ───────────────────────────────────────────────
+/**
+ * Resolve BigQuery configuration from explicit options + environment variables + defaults.
+ *
+ * Resolution priority (highest to lowest):
+ *   1. Explicit options passed to the function
+ *   2. Environment variables (BIGQUERY_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS, etc.)
+ *   3. Built-in defaults from DEFAULTS
+ *
+ * @param {Partial<BigQueryConfig>} [options={}] - Explicit config overrides
+ * @returns {ResolvedConfig} Fully resolved configuration
+ * @throws {Error} If BIGQUERY_PROJECT_ID is missing from both options and env
+ */
+export function resolveConfig(options = {}) {
+    const env = typeof process !== 'undefined' ? process.env : {};
+    // ── Project ID (required) ────────────────────────────────────────────────
+    const projectId = options.projectId
+        || env.BIGQUERY_PROJECT_ID
+        || null;
+    if (!projectId) {
+        throw new Error('BigQuery project ID is required. Set BIGQUERY_PROJECT_ID environment variable ' +
+            'or pass { projectId } in options.');
+    }
+    // ── Service account credentials (optional — falls back to ADC) ───────────
+    const keyFilename = options.keyFilename
+        || env.GOOGLE_APPLICATION_CREDENTIALS
+        || undefined;
+    // ── Dataset ──────────────────────────────────────────────────────────────
+    const dataset = options.dataset
+        || env.BIGQUERY_DATASET
+        || DEFAULTS.dataset;
+    // ── Location ─────────────────────────────────────────────────────────────
+    const location = options.location
+        || env.BIGQUERY_LOCATION
+        || DEFAULTS.location;
+    // ── Max bytes billed ─────────────────────────────────────────────────────
+    const maxBytesBilled = options.maxBytesBilled
+        || env.BIGQUERY_MAX_BYTES
+        || DEFAULTS.maxBytesBilled;
+    // ── Query timeout ────────────────────────────────────────────────────────
+    const timeoutMs = options.timeoutMs
+        || (env.BIGQUERY_TIMEOUT_MS ? Number(env.BIGQUERY_TIMEOUT_MS) : null)
+        || DEFAULTS.timeoutMs;
+    // ── OAuth scopes ─────────────────────────────────────────────────────────
+    const scopes = options.scopes
+        || (env.BIGQUERY_SCOPES ? env.BIGQUERY_SCOPES.split(',').map(s => s.trim()) : null)
+        || DEFAULTS.scopes;
+    return {
+        projectId,
+        keyFilename,
+        dataset,
+        location,
+        maxBytesBilled: String(maxBytesBilled),
+        timeoutMs: Number(timeoutMs),
+        scopes,
+    };
+}
+// ─── Configuration validation ───────────────────────────────────────────────
+/**
+ * Validate a resolved BigQuery configuration.
+ * Returns a list of issues (empty if config is valid).
+ *
+ * @param {ResolvedConfig} config - Configuration to validate
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateConfig(config) {
+    const errors = [];
+    if (!config || typeof config !== 'object') {
+        return { valid: false, errors: ['Config must be a non-null object'] };
+    }
+    // projectId: required, must be a non-empty string matching GCP project naming
+    if (!config.projectId || typeof config.projectId !== 'string') {
+        errors.push('projectId is required and must be a non-empty string');
+    }
+    else if (!/^[a-z][a-z0-9-]{4,28}[a-z0-9]$/.test(config.projectId)) {
+        // GCP project IDs: 6–30 chars, lowercase letters/digits/hyphens, starts with letter, ends with letter/digit
+        errors.push(`projectId "${config.projectId}" does not match GCP project ID format ` +
+            '(6-30 chars, lowercase, starts with letter)');
+    }
+    // keyFilename: if provided, must be a non-empty string
+    if (config.keyFilename != null && (typeof config.keyFilename !== 'string' || !config.keyFilename.trim())) {
+        errors.push('keyFilename, if provided, must be a non-empty string path');
+    }
+    // dataset: required non-empty string
+    if (!config.dataset || typeof config.dataset !== 'string') {
+        errors.push('dataset is required and must be a non-empty string');
+    }
+    // location: required non-empty string
+    if (!config.location || typeof config.location !== 'string') {
+        errors.push('location is required and must be a non-empty string');
+    }
+    // maxBytesBilled: must be a numeric string
+    if (!config.maxBytesBilled || isNaN(Number(config.maxBytesBilled))) {
+        errors.push('maxBytesBilled must be a numeric string');
+    }
+    // timeoutMs: positive number
+    if (typeof config.timeoutMs !== 'number' || config.timeoutMs <= 0) {
+        errors.push('timeoutMs must be a positive number');
+    }
+    // scopes: non-empty array of strings
+    if (!Array.isArray(config.scopes) || config.scopes.length === 0) {
+        errors.push('scopes must be a non-empty array of OAuth scope strings');
+    }
+    return { valid: errors.length === 0, errors };
+}
+// ─── Client singleton pool ──────────────────────────────────────────────────
+/**
+ * Pool of BigQuery client instances keyed by projectId.
+ * Reuses existing clients to avoid redundant connection setup and
+ * authentication overhead across multiple queries.
+ *
+ * @type {Map<string, Object>}
+ */
+const clientPool = new Map();
+/**
+ * Create or retrieve a BigQuery client instance for the given configuration.
+ *
+ * Uses a singleton pool keyed by projectId: if a client already exists for
+ * the project, it is reused. This avoids redundant authentication handshakes
+ * and connection setup when multiple queries target the same project.
+ *
+ * The client is lazily created on first call and cached for the process lifetime
+ * (or until destroyClient() is called).
+ *
+ * @param {ResolvedConfig} config - Resolved BigQuery configuration
+ * @returns {Promise<Object>} BigQuery client instance (from @google-cloud/bigquery)
+ * @throws {Error} If @google-cloud/bigquery is not installed
+ * @throws {Error} If configuration is invalid
+ */
+export async function getClient(config = {}) {
+    // Validate config before attempting client creation
+    const validation = validateConfig(config);
+    if (!validation.valid) {
+        throw new Error(`Invalid BigQuery configuration: ${validation.errors.join('; ')}`);
+    }
+    const poolKey = config.projectId;
+    // Return cached client if available
+    if (clientPool.has(poolKey)) {
+        return clientPool.get(poolKey);
+    }
+    // Lazy-load @google-cloud/bigquery to fail gracefully if not installed
+    let BigQuery;
+    try {
+        const module = await import('@google-cloud/bigquery');
+        BigQuery = module.BigQuery;
+    }
+    catch (err) {
+        throw new Error('The @google-cloud/bigquery package is required for patent data access. ' +
+            'Install it with: pnpm add @google-cloud/bigquery\n' +
+            `Original error: ${toErrorMessage(err)}`);
+    }
+    // Build client options
+    const clientOptions = {
+        projectId: config.projectId,
+        location: config.location,
+        scopes: config.scopes,
+    }; // any: BigQuery query options shape varies by SDK version
+    // Add service account key file if provided (otherwise relies on ADC)
+    if (config.keyFilename) {
+        clientOptions.keyFilename = config.keyFilename;
+    }
+    const client = new BigQuery(clientOptions);
+    // Cache the client for reuse
+    clientPool.set(poolKey, client);
+    return client;
+}
+/**
+ * Destroy (remove from pool) the BigQuery client for a given project.
+ * Use this for graceful shutdown or to force re-authentication.
+ *
+ * @param {string} projectId - GCP project ID whose client to destroy
+ * @returns {boolean} true if a client was removed, false if none existed
+ */
+export function destroyClient(projectId) {
+    return clientPool.delete(projectId);
+}
+/**
+ * Destroy all pooled BigQuery clients.
+ * Call this during process shutdown to release all resources.
+ */
+export function destroyAllClients() {
+    clientPool.clear();
+}
+/**
+ * Get the current number of pooled clients (for monitoring/testing).
+ * @returns {number}
+ */
+export function poolSize() {
+    return clientPool.size;
+}
+// ─── Query helper ───────────────────────────────────────────────────────────
+/**
+ * Default query options derived from configuration.
+ * Used by BigQueryPatentSource to run parameterized queries with consistent
+ * billing and timeout controls.
+ *
+ * @param {ResolvedConfig} config - Resolved BigQuery configuration
+ * @returns {Object} Base query options for BigQuery .query() calls
+ */
+export function defaultQueryOptions(config) {
+    return {
+        location: config.location,
+        maximumBytesBilled: config.maxBytesBilled,
+        timeoutMs: config.timeoutMs,
+        useLegacySql: false,
+    };
+}
+// ─── Environment check helper ───────────────────────────────────────────────
+/**
+ * Check whether the required environment variables are set for BigQuery access.
+ * Returns a diagnostic object (does not throw) — useful for health checks and
+ * graceful degradation in the strategy pipeline.
+ *
+ * @returns {{ ready: boolean, projectId: string|null, hasCredentials: boolean, missing: string[] }}
+ */
+export function checkEnvironment() {
+    const env = typeof process !== 'undefined' ? process.env : {};
+    const missing = [];
+    const projectId = env.BIGQUERY_PROJECT_ID || null;
+    const hasCredentials = !!env.GOOGLE_APPLICATION_CREDENTIALS;
+    if (!projectId)
+        missing.push('BIGQUERY_PROJECT_ID');
+    if (!hasCredentials)
+        missing.push('GOOGLE_APPLICATION_CREDENTIALS');
+    return {
+        ready: missing.length === 0,
+        projectId,
+        hasCredentials,
+        missing,
+    };
+}
+//# sourceMappingURL=bigquery-client.mjs.map

package/dist/lib/patent/bigquery-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigquery-client.mjs","sourceRoot":"","sources":["../../../src/lib/patent/bigquery-client.mts"],"names":[],"mappings":"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"}

package/dist/lib/patent/bigquery-patent-constants.d.mts

@@ -0,0 +1,10 @@
+/** Default minimum filing year — limits scan size and cost. */
+export declare const DEFAULT_MIN_YEAR = 2000;
+/** Maximum patent families to scan per query (cost control). */
+export declare const DEFAULT_MAX_PATENTS = 100000;
+/**
+ * Patent term in years (US post-1995 = 20 years from filing).
+ * Used by the expiration query to classify expired vs active patents.
+ */
+export declare const PATENT_TERM_YEARS = 20;
+//# sourceMappingURL=bigquery-patent-constants.d.mts.map

package/dist/lib/patent/bigquery-patent-constants.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigquery-patent-constants.d.mts","sourceRoot":"","sources":["../../../src/lib/patent/bigquery-patent-constants.mts"],"names":[],"mappings":"AASA,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,SAAU,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC"}

package/dist/lib/patent/bigquery-patent-constants.mjs

@@ -0,0 +1,18 @@
+// BigQuery patent constants.
+//
+// Extracted from bigquery-patent-source.mts to break the circular
+// dependency it formed with bigquery-query-builders.mts (the source
+// owned the constants while the query builders imported them, and the
+// source in turn imported `buildAllQueries` from the builders module).
+//
+// Constants live here as the shared leaf both files depend on.
+/** Default minimum filing year — limits scan size and cost. */
+export const DEFAULT_MIN_YEAR = 2000;
+/** Maximum patent families to scan per query (cost control). */
+export const DEFAULT_MAX_PATENTS = 100_000;
+/**
+ * Patent term in years (US post-1995 = 20 years from filing).
+ * Used by the expiration query to classify expired vs active patents.
+ */
+export const PATENT_TERM_YEARS = 20;
+//# sourceMappingURL=bigquery-patent-constants.mjs.map

package/dist/lib/patent/bigquery-patent-constants.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigquery-patent-constants.mjs","sourceRoot":"","sources":["../../../src/lib/patent/bigquery-patent-constants.mts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,EAAE;AACF,kEAAkE;AAClE,oEAAoE;AACpE,sEAAsE;AACtE,uEAAuE;AACvE,EAAE;AACF,+DAA+D;AAE/D,+DAA+D;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC"}

package/dist/lib/patent/bigquery-patent-source.d.mts

@@ -0,0 +1,216 @@
+import { PatentDataSource } from './patent-data-source.mjs';
+import type { PatentData, BigQueryRow, CpcDistributionEntry, YearlyClassification, CitationData, ClaimsTimelineEntry, AssigneeData, GeoData, SectorData, ExpirationData } from '../../types/patent.mjs';
+export { createQueryContext, buildCpcDistributionQuery, buildYearlyClassificationsQuery, buildCitationDataQuery, buildClaimsTimelineQuery, buildAssigneeDataQuery, buildGeoDataQuery, buildSectorDataQuery, buildExpirationDataQuery, buildTotalPatentsQuery, QUERY_BUILDERS, buildAllQueries, } from './bigquery-query-builders.mjs';
+import { DEFAULT_MIN_YEAR, DEFAULT_MAX_PATENTS, PATENT_TERM_YEARS } from './bigquery-patent-constants.mjs';
+export { DEFAULT_MIN_YEAR, DEFAULT_MAX_PATENTS, PATENT_TERM_YEARS, };
+/** Default number of retry attempts for transient BigQuery errors. */
+export declare const DEFAULT_MAX_RETRIES = 3;
+/** Default base delay in ms for exponential backoff (doubles each retry). */
+export declare const DEFAULT_BASE_DELAY_MS = 1000;
+/** Maximum backoff delay cap in ms (prevents excessive waits). */
+export declare const MAX_BACKOFF_MS = 30000;
+/**
+ * Classify whether a BigQuery error is transient and safe to retry.
+ *
+ * Retryable conditions:
+ *   - HTTP 429 (rate limit), 500/502/503/504 (server errors)
+ *   - Network errors (ETIMEDOUT, ECONNRESET, EAI_AGAIN, etc.)
+ *   - Timeout/AbortError
+ *   - BigQuery quota exceeded (temporary)
+ *
+ * Non-retryable (permanent):
+ *   - HTTP 400 (bad request — query syntax error)
+ *   - HTTP 401/403 (auth/permission — won't change on retry)
+ *   - HTTP 404 (dataset/table not found)
+ *   - Invalid configuration errors
+ *
+ * @param {Error} error - The error to classify
+ * @returns {boolean} true if the error is transient and should be retried
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Execute an async function with exponential backoff retry for transient errors.
+ *
+ * Retry strategy:
+ *   - Base delay doubles each attempt: 1s, 2s, 4s, 8s, ...
+ *   - Jitter: ±25% randomization to prevent thundering herd
+ *   - Max backoff cap: 30 seconds
+ *   - Only retries errors classified as transient by isRetryableError()
+ *   - Non-retryable errors are thrown immediately
+ *
+ * @param {() => Promise<T>} fn - Async function to execute
+ * @param {Object} [options]
+ * @param {number} [options.maxRetries=3] - Maximum retry attempts (0 = no retries)
+ * @param {number} [options.baseDelayMs=1000] - Initial backoff delay in ms
+ * @param {string} [options.label='query'] - Human-readable label for log messages
+ * @returns {Promise<T>} Result of the function
+ * @throws {Error} The last error if all retries are exhausted, or non-retryable error immediately
+ * @template T
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    label?: string;
+}): Promise<T>;
+/**
+ * Transform BigQuery rows from cpc-distribution query to CpcDistributionEntry[].
+ * @param {Object[]} rows - BigQuery result rows
+ * @returns {Array<{cpc: string, count: number}>}
+ */
+export declare function transformCpcDistribution(rows: BigQueryRow[]): CpcDistributionEntry[];
+/**
+ * Transform BigQuery rows from yearly-classifications query to YearlyClassification[].
+ * @param {Object[]} rows - BigQuery result rows
+ * @returns {Array<{year: number, cpcCodes: string[]}>}
+ */
+export declare function transformYearlyClassifications(rows: BigQueryRow[]): YearlyClassification[];
+/**
+ * Transform BigQuery rows from citation-data query to CitationData.
+ * @param {Object[]} rows - BigQuery result rows (single row expected)
+ * @returns {{totalForwardCitations: number, patentCount: number}}
+ */
+export declare function transformCitationData(rows: BigQueryRow[]): CitationData;
+/**
+ * Transform BigQuery rows from claims-timeline query to ClaimsTimelineEntry[].
+ * @param {Object[]} rows - BigQuery result rows
+ * @returns {Array<{year: number, avgIndependentClaims: number}>}
+ */
+export declare function transformClaimsTimeline(rows: BigQueryRow[]): ClaimsTimelineEntry[];
+/**
+ * Transform BigQuery rows from assignee-data query to AssigneeData.
+ * @param {Object[]} rows - BigQuery result rows (single row expected)
+ * @returns {{uniqueAssignees: number, totalPatents: number}}
+ */
+export declare function transformAssigneeData(rows: BigQueryRow[]): AssigneeData;
+/**
+ * Transform BigQuery rows from geo-data query to GeoData.
+ * @param {Object[]} rows - BigQuery result rows (single row expected)
+ * @returns {{jurisdictionCount: number, jurisdictions: string[]}}
+ */
+export declare function transformGeoData(rows: BigQueryRow[]): GeoData;
+/**
+ * Transform BigQuery rows from sector-data query to SectorData.
+ * @param {Object[]} rows - BigQuery result rows (single row expected)
+ * @returns {{uniqueSections: number, uniqueClasses: number}}
+ */
+export declare function transformSectorData(rows: BigQueryRow[]): SectorData;
+/**
+ * Transform BigQuery rows from expiration-data query to ExpirationData.
+ * @param {Object[]} rows - BigQuery result rows (single row expected)
+ * @returns {{expiredCount: number, totalPatents: number}}
+ */
+export declare function transformExpirationData(rows: BigQueryRow[]): ExpirationData;
+/**
+ * Map of indicator keys to their result transformer functions.
+ * Keys match QUERY_BUILDERS and PatentData fields.
+ *
+ * @type {Record<string, (rows: Object[]) => *>}
+ */
+export declare const RESULT_TRANSFORMERS: Record<string, (rows: BigQueryRow[]) => unknown>;
+/**
+ * BigQuery-backed implementation of PatentDataSource.
+ *
+ * Executes the 8 indicator SQL queries in parallel against the Google Patents
+ * Public Dataset, transforms the results into the canonical PatentData shape,
+ * and returns it for consumption by patent-indicators.mjs.
+ *
+ * @extends PatentDataSource
+ *
+ * @example
+ *   const source = new BigQueryPatentSource({ projectId: 'my-gcp-project' });
+ *   const data = await source.fetchByCpc(['G06F', 'H04L']);
+ *   // data: PatentData with all 8 indicator fields populated
+ *
+ * @example
+ *   // Using factory function (resolves config from env):
+ *   const source = createPatentSource();
+ *   const data = await source.fetchByCpc(['H04W']);
+ */
+export declare class BigQueryPatentSource extends PatentDataSource {
+    _config: any;
+    _client: any;
+    _dataset: string;
+    _minYear: number;
+    _maxPatents: number;
+    _exclude: Set<string>;
+    _maxRetries: number;
+    _baseDelayMs: number;
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.projectId]   - GCP project ID (or env: BIGQUERY_PROJECT_ID)
+     * @param {string} [options.keyFilename] - Service account key path (or env: GOOGLE_APPLICATION_CREDENTIALS)
+     * @param {string} [options.dataset]     - BigQuery dataset (default: 'patents-public-data')
+     * @param {number} [options.minYear]     - Minimum filing year (default: 2000)
+     * @param {number} [options.maxPatents]  - Max patents per query (default: 100,000)
+     * @param {Set<string>} [options.exclude] - Indicator keys to skip
+     * @param {number} [options.maxRetries]  - Max retry attempts for transient errors (default: 3)
+     * @param {number} [options.baseDelayMs] - Base backoff delay in ms (default: 1000)
+     */
+    constructor(options?: any);
+    /**
+     * Get or create the BigQuery client instance.
+     * @returns {Promise<Object>}
+     */
+    _getClient(): Promise<any>;
+    /**
+     * Execute a single built query against BigQuery (no retry).
+     *
+     * @param {BuiltQuery} builtQuery - Query object from a builder function
+     * @returns {Promise<Object[]>} Array of result rows
+     * @throws {Error} On query failure (auth, syntax, network, etc.)
+     */
+    _executeQuery(builtQuery: {
+        sql: string;
+        params: Record<string, unknown>;
+        types: Record<string, unknown>;
+        name?: string;
+    }): Promise<BigQueryRow[]>;
+    /**
+     * Execute a single built query with exponential backoff retry for transient errors.
+     *
+     * Wraps _executeQuery() with withRetry() to handle transient BigQuery failures:
+     *   - HTTP 429 (rate limit) — backed off automatically
+     *   - HTTP 500/502/503/504 (server errors) — retried
+     *   - Network errors (ETIMEDOUT, ECONNRESET) — retried
+     *   - Non-retryable errors (400, 401, 403, 404) — thrown immediately
+     *
+     * @param {BuiltQuery} builtQuery - Query object from a builder function
+     * @returns {Promise<Object[]>} Array of result rows
+     * @throws {Error} Non-retryable error immediately, or last error after all retries exhausted
+     */
+    _executeQueryWithRetry(builtQuery: {
+        sql: string;
+        params: Record<string, unknown>;
+        types: Record<string, unknown>;
+        name?: string;
+    }): Promise<BigQueryRow[]>;
+    /**
+     * Fetch raw patent data for the given CPC sub-class codes.
+     *
+     * Executes all 8 indicator queries in parallel with retry logic for transient
+     * errors. Each query is independently retried up to maxRetries times with
+     * exponential backoff. Queries that fail after all retries are gracefully
+     * degraded to empty results, with errors tracked in the _queryErrors metadata.
+     *
+     * @param {string[]} cpcCodes - Array of 4-char CPC sub-class codes (e.g. ['H04L', 'G06F'])
+     * @returns {Promise<import('./patent-data-source.mjs').PatentData>} Patent data with optional _queryErrors metadata
+     */
+    fetchByCpc(cpcCodes: string[]): Promise<PatentData>;
+    /**
+     * Release the BigQuery client from the pool.
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create a BigQueryPatentSource with configuration resolved from environment.
+ *
+ * Convenience factory that resolves config from env vars:
+ *   BIGQUERY_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS, BIGQUERY_DATASET, etc.
+ *
+ * @param {Object} [options] - Additional options passed to BigQueryPatentSource
+ * @returns {BigQueryPatentSource}
+ * @throws {Error} If required env vars are missing
+ */
+export declare function createPatentSource(options?: {}): BigQueryPatentSource;
+//# sourceMappingURL=bigquery-patent-source.d.mts.map

package/dist/lib/patent/bigquery-patent-source.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigquery-patent-source.d.mts","sourceRoot":"","sources":["../../../src/lib/patent/bigquery-patent-source.mts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,gBAAgB,EAAmB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,OAAO,EACP,UAAU,EACV,cAAc,EACf,MAAM,wBAAwB,CAAC;AAUhC,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,+BAA+B,EAC/B,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACtB,cAAc,EACd,eAAe,GAChB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,CAAC;AAIF,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,kEAAkE;AAClE,eAAO,MAAM,cAAc,QAAS,CAAC;AA4BrC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAgBxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CA0ChJ;AAMD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,oBAAoB,EAAE,CAKpF;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,oBAAoB,EAAE,CAQ1F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,YAAY,CASvE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,mBAAmB,EAAE,CAQlF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,YAAY,CASvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO,CAS7D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,UAAU,CASnE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,cAAc,CAS3E;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,OAAO,CAShF,CAAC;AAMF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,oBAAqB,SAAQ,gBAAgB;IACxD,OAAO,EAAE,GAAG,CAAC;IACb,OAAO,EAAE,GAAG,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;OAUG;gBAES,OAAO,GAAE,GAAQ;IAY7B;;;OAGG;IACG,UAAU;IAOhB;;;;;;OAMG;IACG,aAAa,CAAC,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAaxJ;;;;;;;;;;;;OAYG;IACG,sBAAsB,CAAC,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAWjK;;;;;;;;;;OAUG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IA8FzD;;;OAGG;IACG,KAAK;CAOZ;AAID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,KAAK,wBAE9C"}