@flytedesk/app-kit 0.3.1 → 0.4.0

package/README.md

@@ -3,13 +3,16 @@
 Shared platform package for every flytedesk app — the Node/TypeScript equivalent of
 what `danx` is for the PHP apps.
 
-Two subpath modules, one npm package:
+Five subpath modules, one npm package:
 
 - `@flytedesk/app-kit/auth` — the flytedesk-id BFF/OIDC client (PKCE, session issuance,
   live per-request authorization).
 - `@flytedesk/app-kit/trace` — a Postgres-native trace/audit layer (HTTP request → job →
   DB write → logs, one queryable trace), buffered through Pub/Sub, with a scheduled
   retention/prune job.
+- `@flytedesk/app-kit/rate-limit` — request rate-limiting and quota enforcement.
+- `@flytedesk/app-kit/profile` — user profile and preferences management.
+- `@flytedesk/app-kit/flags` — feature flags and A/B testing.
 
 Status: **bootstrapping.** Both modules are placeholders. See media-planner's published
 "Media Planner Backend" architecture doc for the full design (DEC-25 through DEC-34) and
@@ -25,5 +28,5 @@ pnpm add @flytedesk/app-kit
 ## Publishing
 
 Published to the public npm registry under the `@flytedesk` org, access `restricted`.
-Auth is a token in `~/.npmrc` (`//registry.npmjs.org/:_authToken=...`) — no CI publish
-workflow yet; that's still open (see the artifact's Needs Attention tab).
+The CI publish workflow (`.github/workflows/release.yml`) automatically publishes on pushes
+to main using OIDC Trusted Publishing — no manual token or NPM_TOKEN secret required.

package/dist/bigquery/client.d.ts

@@ -0,0 +1,18 @@
+import type { BigQueryLike, DryRunEstimate, EstimateQueryBytesOptions, ExtractJobHandle, ExtractJobStatus, ExtractTableToGCSInput, JobLabelInput, QueryPage, RunQueryOptions, WaitForExtractJobOptions } from "./types.js";
+export interface CreateBigQueryReadClientOptions {
+    /** Merged under any per-call `labels`/`extra` — e.g. `{app: "sms-app"}`. */
+    defaultLabels?: Record<string, string>;
+}
+export interface BigQueryReadClient {
+    query<T = Record<string, unknown>>(options: RunQueryOptions): Promise<QueryPage<T>>;
+    queryAllPages<T = Record<string, unknown>>(options: RunQueryOptions): AsyncGenerator<T[], void, void>;
+    estimateQueryBytes(options: EstimateQueryBytesOptions): Promise<DryRunEstimate>;
+    extractTableToGCS(input: ExtractTableToGCSInput): Promise<ExtractJobHandle>;
+    getExtractJobStatus(jobId: string): Promise<ExtractJobStatus>;
+    waitForExtractJob(jobId: string, options?: WaitForExtractJobOptions): Promise<ExtractJobStatus>;
+    /** Builds a `{actor, purpose, ...extra}` label set, pre-merged with this
+     *  client's `defaultLabels` — pass the result as `labels` to `query`/
+     *  `extractTableToGCS`. */
+    buildJobLabels(input: JobLabelInput): Record<string, string>;
+}
+export declare function createBigQueryReadClient(bq: BigQueryLike, options?: CreateBigQueryReadClientOptions): BigQueryReadClient;

package/dist/bigquery/client.js

@@ -0,0 +1,37 @@
+/**
+ * createBigQueryReadClient(bq) — bundles query/dry-run/extract into one
+ * object bound to the caller's BigQueryLike (a real `@google-cloud/bigquery`
+ * `BigQuery` instance satisfies this structurally — see types.ts), same
+ * binder shape as src/trace/client.ts's createTraceClient. `defaultLabels`
+ * (e.g. `{app: "sms-app"}`) are merged under any per-call `labels`, so a
+ * caller only needs to supply what's specific to that call.
+ */
+import { buildJobLabels } from "./labels.js";
+import { extractTableToGCS, getExtractJobStatus, waitForExtractJob, } from "./extract.js";
+import { estimateQueryBytes, runQuery, runQueryAllPages } from "./query.js";
+export function createBigQueryReadClient(bq, options = {}) {
+    const defaultLabels = options.defaultLabels ?? {};
+    const withDefaults = (labels) => ({
+        ...defaultLabels,
+        ...labels,
+    });
+    return {
+        query: (queryOptions) => runQuery(bq, {
+            ...queryOptions,
+            labels: withDefaults(queryOptions.labels),
+        }),
+        queryAllPages: (queryOptions) => runQueryAllPages(bq, {
+            ...queryOptions,
+            labels: withDefaults(queryOptions.labels),
+        }),
+        estimateQueryBytes: (estimateOptions) => estimateQueryBytes(bq, estimateOptions),
+        extractTableToGCS: (input) => extractTableToGCS(bq, { ...input, labels: withDefaults(input.labels) }),
+        getExtractJobStatus: (jobId) => getExtractJobStatus(bq, jobId),
+        waitForExtractJob: (jobId, waitOptions) => waitForExtractJob(bq, jobId, waitOptions),
+        buildJobLabels: (input) => ({
+            ...defaultLabels,
+            ...buildJobLabels(input),
+        }),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/bigquery/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/bigquery/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAyC5E,MAAM,UAAU,wBAAwB,CACtC,EAAgB,EAChB,UAA2C,EAAE;IAE7C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;IAClD,MAAM,YAAY,GAAG,CAAC,MAA+B,EAAE,EAAE,CAAC,CAAC;QACzD,GAAG,aAAa;QAChB,GAAG,MAAM;KACV,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,CAAC,YAAY,EAAE,EAAE,CACtB,QAAQ,CAAC,EAAE,EAAE;YACX,GAAG,YAAY;YACf,MAAM,EAAE,YAAY,CAAC,YAAY,CAAC,MAAM,CAAC;SAC1C,CAAC;QACJ,aAAa,EAAE,CAAC,YAAY,EAAE,EAAE,CAC9B,gBAAgB,CAAC,EAAE,EAAE;YACnB,GAAG,YAAY;YACf,MAAM,EAAE,YAAY,CAAC,YAAY,CAAC,MAAM,CAAC;SAC1C,CAAC;QACJ,kBAAkB,EAAE,CAAC,eAAe,EAAE,EAAE,CACtC,kBAAkB,CAAC,EAAE,EAAE,eAAe,CAAC;QACzC,iBAAiB,EAAE,CAAC,KAAK,EAAE,EAAE,CAC3B,iBAAiB,CAAC,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACzE,mBAAmB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,EAAE,EAAE,KAAK,CAAC;QAC9D,iBAAiB,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CACxC,iBAAiB,CAAC,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC;QAC3C,cAAc,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC1B,GAAG,aAAa;YAChB,GAAG,cAAc,CAAC,KAAK,CAAC;SACzB,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/bigquery/errors.d.ts

@@ -0,0 +1,26 @@
+export declare class BigQueryReadError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Malformed / unparseable SQL, or a bad parameter binding. */
+export declare class BadQueryError extends BigQueryReadError {
+    constructor(message: string, cause?: unknown);
+}
+/** The caller's credentials don't have access to the dataset/table/job. */
+export declare class PermissionDeniedError extends BigQueryReadError {
+    constructor(message: string, cause?: unknown);
+}
+/** A dry-run estimate exceeded the caller-supplied byte budget — thrown
+ *  before any billable query actually runs. */
+export declare class DryRunBudgetExceededError extends BigQueryReadError {
+    readonly totalBytesProcessed: number;
+    readonly maxBytesBilled: number;
+    constructor(totalBytesProcessed: number, maxBytesBilled: number);
+}
+/**
+ * Normalizes anything a BigQueryLike call can throw/reject with (a Google API
+ * client error, a job's `status.errorResult`/`status.errors`, or an already-
+ * classified BigQueryReadError) into a BigQueryReadError subclass. Never
+ * throws itself — always returns an Error to `throw` at the call site.
+ */
+export declare function classifyBigQueryError(err: unknown): BigQueryReadError;

package/dist/bigquery/errors.js

@@ -0,0 +1,80 @@
+export class BigQueryReadError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "BigQueryReadError";
+    }
+}
+/** Malformed / unparseable SQL, or a bad parameter binding. */
+export class BadQueryError extends BigQueryReadError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = "BadQueryError";
+    }
+}
+/** The caller's credentials don't have access to the dataset/table/job. */
+export class PermissionDeniedError extends BigQueryReadError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = "PermissionDeniedError";
+    }
+}
+/** A dry-run estimate exceeded the caller-supplied byte budget — thrown
+ *  before any billable query actually runs. */
+export class DryRunBudgetExceededError extends BigQueryReadError {
+    totalBytesProcessed;
+    maxBytesBilled;
+    constructor(totalBytesProcessed, maxBytesBilled) {
+        super(`Dry-run estimate of ${totalBytesProcessed} bytes exceeds the ${maxBytesBilled} byte budget`);
+        this.totalBytesProcessed = totalBytesProcessed;
+        this.maxBytesBilled = maxBytesBilled;
+        this.name = "DryRunBudgetExceededError";
+    }
+}
+/** Reason codes the Google APIs client library attaches to a rejected job
+ *  promise's `.errors[]` — see
+ *  https://cloud.google.com/bigquery/docs/error-messages for the full list.
+ *  Anything not in these two sets falls through to the generic
+ *  BigQueryReadError rather than being mis-classified. */
+const PERMISSION_DENIED_REASONS = new Set([
+    "accessDenied",
+    "forbidden",
+    "insufficientPermissions",
+]);
+const BAD_QUERY_REASONS = new Set([
+    "invalidQuery",
+    "invalid",
+    "parseError",
+    "invalidQueryParameter",
+]);
+/**
+ * Normalizes anything a BigQueryLike call can throw/reject with (a Google API
+ * client error, a job's `status.errorResult`/`status.errors`, or an already-
+ * classified BigQueryReadError) into a BigQueryReadError subclass. Never
+ * throws itself — always returns an Error to `throw` at the call site.
+ */
+export function classifyBigQueryError(err) {
+    if (err instanceof BigQueryReadError)
+        return err;
+    const apiErr = err;
+    const detail = apiErr?.errors?.[0];
+    const reason = detail?.reason;
+    const message = detail?.message ??
+        apiErr?.message ??
+        (err instanceof Error ? err.message : String(err));
+    if (reason && PERMISSION_DENIED_REASONS.has(reason)) {
+        return new PermissionDeniedError(message, err);
+    }
+    if (apiErr?.code === 403) {
+        return new PermissionDeniedError(message, err);
+    }
+    if (reason && BAD_QUERY_REASONS.has(reason)) {
+        return new BadQueryError(message, err);
+    }
+    if (apiErr?.code === 400) {
+        return new BadQueryError(message, err);
+    }
+    return new BigQueryReadError(message, err);
+}
+//# sourceMappingURL=errors.js.map

package/dist/bigquery/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/bigquery/errors.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAGxB;IAFlB,YACE,OAAe,EACC,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,OAAO,aAAc,SAAQ,iBAAiB;IAClD,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,OAAO,qBAAsB,SAAQ,iBAAiB;IAC1D,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;+CAC+C;AAC/C,MAAM,OAAO,yBAA0B,SAAQ,iBAAiB;IAE5C;IACA;IAFlB,YACkB,mBAA2B,EAC3B,cAAsB;QAEtC,KAAK,CACH,uBAAuB,mBAAmB,sBAAsB,cAAc,cAAc,CAC7F,CAAC;QALc,wBAAmB,GAAnB,mBAAmB,CAAQ;QAC3B,mBAAc,GAAd,cAAc,CAAQ;QAKtC,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAQD;;;;0DAI0D;AAC1D,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC;IACxC,cAAc;IACd,WAAW;IACX,yBAAyB;CAC1B,CAAC,CAAC;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,cAAc;IACd,SAAS;IACT,YAAY;IACZ,uBAAuB;CACxB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,IAAI,GAAG,YAAY,iBAAiB;QAAE,OAAO,GAAG,CAAC;IAEjD,MAAM,MAAM,GAAG,GAAyB,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC;IAC9B,MAAM,OAAO,GACX,MAAM,EAAE,OAAO;QACf,MAAM,EAAE,OAAO;QACf,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAErD,IAAI,MAAM,IAAI,yBAAyB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACpD,OAAO,IAAI,qBAAqB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,MAAM,EAAE,IAAI,KAAK,GAAG,EAAE,CAAC;QACzB,OAAO,IAAI,qBAAqB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,MAAM,IAAI,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,MAAM,EAAE,IAAI,KAAK,GAAG,EAAE,CAAC;QACzB,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,IAAI,iBAAiB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC"}

package/dist/bigquery/extract.d.ts

@@ -0,0 +1,15 @@
+import type { BigQueryLike, ExtractJobHandle, ExtractJobStatus, ExtractTableToGCSInput, WaitForExtractJobOptions } from "./types.js";
+/** Submits a table extract job and returns immediately with its job id — does
+ *  NOT wait for completion. Use `getExtractJobStatus`/`waitForExtractJob` to
+ *  observe it. */
+export declare function extractTableToGCS(bq: BigQueryLike, input: ExtractTableToGCSInput): Promise<ExtractJobHandle>;
+/** Reads the current status of a previously-submitted extract job by id —
+ *  a single, non-blocking status check. */
+export declare function getExtractJobStatus(bq: BigQueryLike, jobId: string): Promise<ExtractJobStatus>;
+/**
+ * Polls an extract job until it reaches `DONE`, or throws once
+ * `timeoutMs` elapses without that happening. Throws a classified
+ * BigQueryReadError if the job finishes with `status.errorResult`/`errors`
+ * set (e.g. permission denied on the destination bucket).
+ */
+export declare function waitForExtractJob(bq: BigQueryLike, jobId: string, options?: WaitForExtractJobOptions): Promise<ExtractJobStatus>;

package/dist/bigquery/extract.js

@@ -0,0 +1,88 @@
+/**
+ * Extract-to-Cloud-Storage for large table exports, with job-status polling —
+ * the other generic capability out of media-planner's inventoryWarehouse.ts
+ * (AK-11).
+ */
+import { BigQueryReadError, classifyBigQueryError } from "./errors.js";
+const DEFAULT_FORMAT = "NEWLINE_DELIMITED_JSON";
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const KNOWN_STATES = new Set([
+    "PENDING",
+    "RUNNING",
+    "DONE",
+]);
+function toExtractJobStatus(metadata) {
+    const rawState = metadata.status?.state;
+    const state = KNOWN_STATES.has(rawState ?? "")
+        ? rawState
+        : "UNKNOWN";
+    const errors = metadata.status?.errors ??
+        (metadata.status?.errorResult ? [metadata.status.errorResult] : undefined);
+    return {
+        jobId: metadata.id ?? "",
+        state,
+        done: state === "DONE",
+        errors,
+    };
+}
+/** Submits a table extract job and returns immediately with its job id — does
+ *  NOT wait for completion. Use `getExtractJobStatus`/`waitForExtractJob` to
+ *  observe it. */
+export async function extractTableToGCS(bq, input) {
+    try {
+        const table = bq.dataset(input.datasetId).table(input.tableId);
+        const [job] = await table.createExtractJob(input.destination, {
+            format: input.format ?? DEFAULT_FORMAT,
+            gzip: input.gzip,
+            labels: input.labels,
+        });
+        return { jobId: job.id };
+    }
+    catch (err) {
+        throw classifyBigQueryError(err);
+    }
+}
+/** Reads the current status of a previously-submitted extract job by id —
+ *  a single, non-blocking status check. */
+export async function getExtractJobStatus(bq, jobId) {
+    try {
+        const job = bq.job(jobId);
+        const [metadata] = await job.getMetadata();
+        return toExtractJobStatus({ ...metadata, id: metadata.id ?? jobId });
+    }
+    catch (err) {
+        throw classifyBigQueryError(err);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Polls an extract job until it reaches `DONE`, or throws once
+ * `timeoutMs` elapses without that happening. Throws a classified
+ * BigQueryReadError if the job finishes with `status.errorResult`/`errors`
+ * set (e.g. permission denied on the destination bucket).
+ */
+export async function waitForExtractJob(bq, jobId, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const status = await getExtractJobStatus(bq, jobId);
+        if (status.done) {
+            if (status.errors && status.errors.length > 0) {
+                throw classifyBigQueryError({
+                    errors: status.errors,
+                    message: status.errors[0]?.message,
+                });
+            }
+            return status;
+        }
+        if (Date.now() >= deadline) {
+            throw new BigQueryReadError(`Extract job ${jobId} did not complete within ${timeoutMs}ms (last state: ${status.state})`);
+        }
+        await sleep(pollIntervalMs);
+    }
+}
+//# sourceMappingURL=extract.js.map

package/dist/bigquery/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/bigquery/extract.ts"],"names":[],"mappings":"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"}

package/dist/bigquery/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Read-only BigQuery client (AK-11): parameterised queries, dry-run byte
+ * estimation, job labels, paged results, and extract-to-Cloud-Storage with
+ * job-status polling — generalized out of media-planner's
+ * `apps/api/src/services/inventoryWarehouse.ts`. Inventory-specific SQL stays
+ * in media-planner; this module only ever runs SQL/params the caller supplies.
+ *
+ * No hard dependency on `@google-cloud/bigquery` — every function takes a
+ * structural `BigQueryLike` (see types.ts), which a real `new BigQuery()`
+ * instance already satisfies:
+ *
+ *   import { BigQuery } from "@google-cloud/bigquery";
+ *   import { createBigQueryReadClient } from "@flytedesk/app-kit/bigquery";
+ *
+ *   const client = createBigQueryReadClient(new BigQuery(), {
+ *     defaultLabels: { app: "sms-app" },
+ *   });
+ *
+ *   const estimate = await client.estimateQueryBytes({
+ *     sql: "SELECT * FROM `project.dataset.contacts` WHERE campaign_id = @campaignId",
+ *     params: { campaignId },
+ *     maxBytesBilled: 10 * 1024 ** 3, // throws DryRunBudgetExceededError past 10 GiB
+ *   });
+ *
+ *   const page = await client.query({
+ *     sql: "SELECT * FROM `project.dataset.contacts` WHERE campaign_id = @campaignId",
+ *     params: { campaignId },
+ *     labels: client.buildJobLabels({ actor: userId, purpose: "audience-export" }),
+ *     pageSize: 500,
+ *   });
+ *   // page.nextPageToken, if present, resumes with { ...same options, pageToken }
+ *
+ *   const { jobId } = await client.extractTableToGCS({
+ *     datasetId: "dataset",
+ *     tableId: "campaign_results",
+ *     destination: storage.bucket("exports").file("campaign_results.json.gz"),
+ *     gzip: true,
+ *   });
+ *   const status = await client.waitForExtractJob(jobId);
+ */
+export { createBigQueryReadClient } from "./client.js";
+export type { BigQueryReadClient, CreateBigQueryReadClientOptions, } from "./client.js";
+export { runQuery, runQueryAllPages, estimateQueryBytes } from "./query.js";
+export { extractTableToGCS, getExtractJobStatus, waitForExtractJob, } from "./extract.js";
+export { buildJobLabels, sanitizeLabelValue } from "./labels.js";
+export { BadQueryError, BigQueryReadError, DryRunBudgetExceededError, PermissionDeniedError, classifyBigQueryError, } from "./errors.js";
+export type { BigQueryApiErrorDetail, BigQueryCreateQueryJobOptions, BigQueryDatasetLike, BigQueryExtractOptions, BigQueryJobLike, BigQueryJobMetadata, BigQueryLike, BigQueryNextQuery, BigQueryQueryResultsOptions, BigQueryTableLike, DryRunEstimate, EstimateQueryBytesOptions, ExtractJobHandle, ExtractJobState, ExtractJobStatus, ExtractTableToGCSInput, GcsFileLike, JobLabelInput, QueryPage, RunQueryOptions, WaitForExtractJobOptions, } from "./types.js";

package/dist/bigquery/index.js

@@ -0,0 +1,46 @@
+/**
+ * Read-only BigQuery client (AK-11): parameterised queries, dry-run byte
+ * estimation, job labels, paged results, and extract-to-Cloud-Storage with
+ * job-status polling — generalized out of media-planner's
+ * `apps/api/src/services/inventoryWarehouse.ts`. Inventory-specific SQL stays
+ * in media-planner; this module only ever runs SQL/params the caller supplies.
+ *
+ * No hard dependency on `@google-cloud/bigquery` — every function takes a
+ * structural `BigQueryLike` (see types.ts), which a real `new BigQuery()`
+ * instance already satisfies:
+ *
+ *   import { BigQuery } from "@google-cloud/bigquery";
+ *   import { createBigQueryReadClient } from "@flytedesk/app-kit/bigquery";
+ *
+ *   const client = createBigQueryReadClient(new BigQuery(), {
+ *     defaultLabels: { app: "sms-app" },
+ *   });
+ *
+ *   const estimate = await client.estimateQueryBytes({
+ *     sql: "SELECT * FROM `project.dataset.contacts` WHERE campaign_id = @campaignId",
+ *     params: { campaignId },
+ *     maxBytesBilled: 10 * 1024 ** 3, // throws DryRunBudgetExceededError past 10 GiB
+ *   });
+ *
+ *   const page = await client.query({
+ *     sql: "SELECT * FROM `project.dataset.contacts` WHERE campaign_id = @campaignId",
+ *     params: { campaignId },
+ *     labels: client.buildJobLabels({ actor: userId, purpose: "audience-export" }),
+ *     pageSize: 500,
+ *   });
+ *   // page.nextPageToken, if present, resumes with { ...same options, pageToken }
+ *
+ *   const { jobId } = await client.extractTableToGCS({
+ *     datasetId: "dataset",
+ *     tableId: "campaign_results",
+ *     destination: storage.bucket("exports").file("campaign_results.json.gz"),
+ *     gzip: true,
+ *   });
+ *   const status = await client.waitForExtractJob(jobId);
+ */
+export { createBigQueryReadClient } from "./client.js";
+export { runQuery, runQueryAllPages, estimateQueryBytes } from "./query.js";
+export { extractTableToGCS, getExtractJobStatus, waitForExtractJob, } from "./extract.js";
+export { buildJobLabels, sanitizeLabelValue } from "./labels.js";
+export { BadQueryError, BigQueryReadError, DryRunBudgetExceededError, PermissionDeniedError, classifyBigQueryError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/bigquery/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bigquery/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAMvD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist/bigquery/labels.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Job-label helpers — BigQuery job labels are billing/audit metadata attached
+ * to every query/extract job ("who ran it, for what"), constrained to keys and
+ * values matching `[a-z0-9_-]{1,63}` (lowercase only, no spaces). Ported from
+ * media-planner's inventoryWarehouse job-labeling convention, generalized to
+ * take an arbitrary actor/purpose pair rather than inventory-specific fields.
+ */
+import type { JobLabelInput } from "./types.js";
+/** Coerces an arbitrary string into a valid BigQuery label value: lowercased,
+ *  invalid characters replaced with `-`, truncated to 63 characters. Falls
+ *  back to `"unknown"` for an empty/all-invalid input, since an empty label
+ *  value is itself rejected by BigQuery. */
+export declare function sanitizeLabelValue(value: string): string;
+/** Builds a `{actor, purpose, ...extra}` label set for a job, sanitizing
+ *  every key and value to BigQuery's label format. */
+export declare function buildJobLabels(input: JobLabelInput): Record<string, string>;

package/dist/bigquery/labels.js

@@ -0,0 +1,26 @@
+const MAX_LABEL_LENGTH = 63;
+const INVALID_LABEL_CHARS = /[^a-z0-9_-]/g;
+/** Coerces an arbitrary string into a valid BigQuery label value: lowercased,
+ *  invalid characters replaced with `-`, truncated to 63 characters. Falls
+ *  back to `"unknown"` for an empty/all-invalid input, since an empty label
+ *  value is itself rejected by BigQuery. */
+export function sanitizeLabelValue(value) {
+    const sanitized = value
+        .toLowerCase()
+        .replace(INVALID_LABEL_CHARS, "-")
+        .slice(0, MAX_LABEL_LENGTH);
+    return sanitized.length > 0 ? sanitized : "unknown";
+}
+/** Builds a `{actor, purpose, ...extra}` label set for a job, sanitizing
+ *  every key and value to BigQuery's label format. */
+export function buildJobLabels(input) {
+    const labels = {
+        actor: sanitizeLabelValue(input.actor),
+        purpose: sanitizeLabelValue(input.purpose),
+    };
+    for (const [key, value] of Object.entries(input.extra ?? {})) {
+        labels[sanitizeLabelValue(key)] = sanitizeLabelValue(value);
+    }
+    return labels;
+}
+//# sourceMappingURL=labels.js.map

package/dist/bigquery/labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.js","sourceRoot":"","sources":["../../src/bigquery/labels.ts"],"names":[],"mappings":"AASA,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAE3C;;;4CAG4C;AAC5C,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,MAAM,SAAS,GAAG,KAAK;SACpB,WAAW,EAAE;SACb,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC;SACjC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC9B,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;AACtD,CAAC;AAED;sDACsD;AACtD,MAAM,UAAU,cAAc,CAAC,KAAoB;IACjD,MAAM,MAAM,GAA2B;QACrC,KAAK,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC;QACtC,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC;KAC3C,CAAC;IACF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QAC7D,MAAM,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/bigquery/query.d.ts

@@ -0,0 +1,16 @@
+import type { BigQueryLike, DryRunEstimate, EstimateQueryBytesOptions, QueryPage, RunQueryOptions } from "./types.js";
+/** Runs one page of a parameterised, read-only query. Always bind
+ *  user-supplied values through `options.params`/`options.types` — never
+ *  string-interpolate them into `options.sql`. */
+export declare function runQuery<T = Record<string, unknown>>(bq: BigQueryLike, options: RunQueryOptions): Promise<QueryPage<T>>;
+/** Pages through every result of a query, yielding one row-array per page.
+ *  Stops once BigQuery reports no further `nextPageToken`. */
+export declare function runQueryAllPages<T = Record<string, unknown>>(bq: BigQueryLike, options: RunQueryOptions): AsyncGenerator<T[], void, void>;
+/**
+ * Dry-runs a query to get its billed-byte estimate without actually running
+ * it (BigQuery does not execute a `dryRun: true` job). When
+ * `options.maxBytesBilled` is given, throws `DryRunBudgetExceededError`
+ * instead of returning once the estimate exceeds it — the caller-facing
+ * "don't let a user run an unbounded scan" guard.
+ */
+export declare function estimateQueryBytes(bq: BigQueryLike, options: EstimateQueryBytesOptions): Promise<DryRunEstimate>;

package/dist/bigquery/query.js

@@ -0,0 +1,86 @@
+/**
+ * Parameterised, paged querying + dry-run byte estimation against an injected
+ * BigQueryLike — the generic half of media-planner's inventoryWarehouse.ts
+ * (AK-11). Inventory-specific SQL stays in media-planner; this module only
+ * ever takes SQL + params from the caller and runs it.
+ */
+import { classifyBigQueryError } from "./errors.js";
+import { DryRunBudgetExceededError } from "./errors.js";
+/** Runs one page of a parameterised, read-only query. Always bind
+ *  user-supplied values through `options.params`/`options.types` — never
+ *  string-interpolate them into `options.sql`. */
+export async function runQuery(bq, options) {
+    let job;
+    try {
+        [job] = await bq.createQueryJob({
+            query: options.sql,
+            params: options.params,
+            types: options.types,
+            labels: options.labels,
+            location: options.location,
+            maxResults: options.pageSize,
+        });
+    }
+    catch (err) {
+        throw classifyBigQueryError(err);
+    }
+    try {
+        const [rows, next] = await job.getQueryResults({
+            maxResults: options.pageSize,
+            pageToken: options.pageToken,
+        });
+        return {
+            rows,
+            jobId: job.id,
+            nextPageToken: next?.pageToken,
+        };
+    }
+    catch (err) {
+        throw classifyBigQueryError(err);
+    }
+}
+/** Pages through every result of a query, yielding one row-array per page.
+ *  Stops once BigQuery reports no further `nextPageToken`. */
+export async function* runQueryAllPages(bq, options) {
+    let pageToken = options.pageToken;
+    for (;;) {
+        const page = await runQuery(bq, { ...options, pageToken });
+        yield page.rows;
+        if (!page.nextPageToken)
+            return;
+        pageToken = page.nextPageToken;
+    }
+}
+/**
+ * Dry-runs a query to get its billed-byte estimate without actually running
+ * it (BigQuery does not execute a `dryRun: true` job). When
+ * `options.maxBytesBilled` is given, throws `DryRunBudgetExceededError`
+ * instead of returning once the estimate exceeds it — the caller-facing
+ * "don't let a user run an unbounded scan" guard.
+ */
+export async function estimateQueryBytes(bq, options) {
+    let metadata;
+    try {
+        [, metadata] = await bq.createQueryJob({
+            query: options.sql,
+            params: options.params,
+            types: options.types,
+            location: options.location,
+            dryRun: true,
+        });
+    }
+    catch (err) {
+        throw classifyBigQueryError(err);
+    }
+    const stats = metadata.statistics?.query;
+    const estimate = {
+        totalBytesProcessed: Number(stats?.totalBytesProcessed ?? 0),
+        cacheHit: stats?.cacheHit ?? false,
+    };
+    if (options.maxBytesBilled !== undefined &&
+        estimate.totalBytesProcessed > options.maxBytesBilled) {
+        throw new DryRunBudgetExceededError(estimate.totalBytesProcessed, options.maxBytesBilled);
+    }
+    return estimate;
+}
+//# sourceMappingURL=query.js.map

package/dist/bigquery/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/bigquery/query.ts"],"names":[],"mappings":"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"}