@lunora/bindings 1.0.0-alpha.92 → 1.0.0-alpha.93

package/README.md

@@ -6,7 +6,7 @@
 
 </a>
 
-<h3 align="center">Lightweight Cloudflare binding helpers for Lunora — ctx.kv, ctx.images, ctx.analytics, ctx.pipelines, ctx.vectors, ctx.r2sql, ctx.artifacts, ctx.aiSearch — one install, per-binding subpaths</h3>
+<h3 align="center">Lightweight Cloudflare binding helpers for Lunora — ctx.kv, ctx.images, ctx.analytics, ctx.pipelines, ctx.vectors, ctx.r2sql, ctx.artifacts, ctx.aiSearch, ctx.analyticsSql — one install, per-binding subpaths</h3>
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
@@ -16,16 +16,17 @@ The lightweight Cloudflare binding helpers for Lunora, in one install with
 per-binding subpaths — each is a thin, zero-dependency `ctx.*` facade over its
 Cloudflare binding:
 
-| Subpath                      | `ctx.*`         | Cloudflare binding     |
-| ---------------------------- | --------------- | ---------------------- |
-| `@lunora/bindings/kv`        | `ctx.kv`        | Workers KV             |
-| `@lunora/bindings/images`    | `ctx.images`    | Cloudflare Images      |
-| `@lunora/bindings/analytics` | `ctx.analytics` | Analytics Engine       |
-| `@lunora/bindings/pipelines` | `ctx.pipelines` | Pipelines              |
-| `@lunora/bindings/vectors`   | `ctx.vectors`   | Vectorize              |
-| `@lunora/bindings/r2sql`     | `ctx.r2sql`     | R2 SQL                 |
-| `@lunora/bindings/artifacts` | `ctx.artifacts` | Artifacts (Git repos)  |
-| `@lunora/bindings/ai-search` | `ctx.aiSearch`  | AI Search (types only) |
+| Subpath                          | `ctx.*`            | Cloudflare binding     |
+| -------------------------------- | ------------------ | ---------------------- |
+| `@lunora/bindings/kv`            | `ctx.kv`           | Workers KV             |
+| `@lunora/bindings/images`        | `ctx.images`       | Cloudflare Images      |
+| `@lunora/bindings/analytics`     | `ctx.analytics`    | Analytics Engine       |
+| `@lunora/bindings/pipelines`     | `ctx.pipelines`    | Pipelines              |
+| `@lunora/bindings/vectors`       | `ctx.vectors`      | Vectorize              |
+| `@lunora/bindings/r2sql`         | `ctx.r2sql`        | R2 SQL                 |
+| `@lunora/bindings/artifacts`     | `ctx.artifacts`    | Artifacts (Git repos)  |
+| `@lunora/bindings/ai-search`     | `ctx.aiSearch`     | AI Search (types only) |
+| `@lunora/bindings/analytics-sql` | `ctx.analyticsSql` | Analytics SQL          |
 
 ```ts
 import { createKv } from "@lunora/bindings/kv";

package/dist/analytics/index.d.mts

@@ -1,6 +1,5 @@
 import { AnalyticsEngineDataPoint, AnalyticsEngineDatasetLike } from '@lunora/platform';
 export type { AnalyticsEngineDataPoint, AnalyticsEngineDatasetLike } from '@lunora/platform';
-import { LunoraError } from '@lunora/errors';
 /**
  * Structural types for the Analytics Engine write path.
  *
@@ -80,65 +79,4 @@ interface AnalyticsClient {
  * the field→column mapping the read side uses to reconstruct named columns.
  */
 declare const createAnalytics: (binding: AnalyticsEngineDatasetLike) => AnalyticsClient;
-/** Configuration for an {@link AnalyticsSqlClient}. */
-interface AnalyticsSqlConfig {
-  /** Cloudflare account id that owns the dataset. */
-  accountId: string;
-  /** API token with Analytics Engine read scope. A secret — never a binding. */
-  apiToken: string;
-  /**
-   * `fetch` implementation. Defaults to the global `fetch`; injected in tests
-   * so the SQL path never touches the network.
-   */
-  fetch?: typeof globalThis.fetch;
-  /**
-   * Milliseconds before an in-flight query (the fetch AND its body read) is
-   * aborted and surfaced as an `AnalyticsSqlError` with status 504. Defaults
-   * to 60_000 — analytical scans legitimately run tens of seconds.
-   * `undefined` means the default, not unbounded.
-   *
-   * The deadline is carried by the request's `signal`, so a custom `fetch`
-   * (above) that ignores `signal` leaves the query unbounded.
-   */
-  timeoutMs?: number;
-}
-/**
- * One column descriptor in a SQL-API response's `meta` array: the column `name`
- * and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
- */
-interface AnalyticsSqlColumnMeta {
-  name: string;
-  type: string;
-}
-/**
- * Parsed SQL-API result. AE returns `{ meta, data, rows, rows_before_limit_at_least }`;
- * we surface `columns` (from `meta`), the `rows` array of column→value records,
- * and the total `rowCount`.
- */
-interface AnalyticsSqlResult {
-  columns: AnalyticsSqlColumnMeta[];
-  rowCount: number;
-  rows: Record<string, unknown>[];
-}
-/**
- * Thrown when the SQL API responds with a non-2xx status; a `LunoraError`
- * subclass carrying the HTTP `status` + a capped body preview, with the full
- * body on `cause`.
- *
- * The preview is capped because AE's SQL error text quotes the query back, and
- * `ANALYTICS_SQL_ERROR` is non-internal — the message reaches the browser.
- */
-declare class AnalyticsSqlError extends LunoraError {
-  constructor(status: number, body: string);
-}
-/** The read client: a single `query(sql)` over the AE SQL API. */
-interface AnalyticsSqlClient {
-  query: (sql: string) => Promise<AnalyticsSqlResult>;
-}
-/**
- * Build an {@link AnalyticsSqlClient}. Each `query` POSTs the raw SQL text to
- * the account's `analytics_engine/sql` endpoint with the bearer token, then
- * normalises AE's `{ meta, data, rows }` body into {@link AnalyticsSqlResult}.
- */
-declare const createAnalyticsSqlClient: (config: AnalyticsSqlConfig) => AnalyticsSqlClient;
-export { type AnalyticsClient, type AnalyticsSqlClient, type AnalyticsSqlColumnMeta, type AnalyticsSqlConfig, AnalyticsSqlError, type AnalyticsSqlResult, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics, createAnalyticsSqlClient };
+export { type AnalyticsClient, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics };

package/dist/analytics/index.d.ts

@@ -1,6 +1,5 @@
 import { AnalyticsEngineDataPoint, AnalyticsEngineDatasetLike } from '@lunora/platform';
 export type { AnalyticsEngineDataPoint, AnalyticsEngineDatasetLike } from '@lunora/platform';
-import { LunoraError } from '@lunora/errors';
 /**
  * Structural types for the Analytics Engine write path.
  *
@@ -80,65 +79,4 @@ interface AnalyticsClient {
  * the field→column mapping the read side uses to reconstruct named columns.
  */
 declare const createAnalytics: (binding: AnalyticsEngineDatasetLike) => AnalyticsClient;
-/** Configuration for an {@link AnalyticsSqlClient}. */
-interface AnalyticsSqlConfig {
-  /** Cloudflare account id that owns the dataset. */
-  accountId: string;
-  /** API token with Analytics Engine read scope. A secret — never a binding. */
-  apiToken: string;
-  /**
-   * `fetch` implementation. Defaults to the global `fetch`; injected in tests
-   * so the SQL path never touches the network.
-   */
-  fetch?: typeof globalThis.fetch;
-  /**
-   * Milliseconds before an in-flight query (the fetch AND its body read) is
-   * aborted and surfaced as an `AnalyticsSqlError` with status 504. Defaults
-   * to 60_000 — analytical scans legitimately run tens of seconds.
-   * `undefined` means the default, not unbounded.
-   *
-   * The deadline is carried by the request's `signal`, so a custom `fetch`
-   * (above) that ignores `signal` leaves the query unbounded.
-   */
-  timeoutMs?: number;
-}
-/**
- * One column descriptor in a SQL-API response's `meta` array: the column `name`
- * and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
- */
-interface AnalyticsSqlColumnMeta {
-  name: string;
-  type: string;
-}
-/**
- * Parsed SQL-API result. AE returns `{ meta, data, rows, rows_before_limit_at_least }`;
- * we surface `columns` (from `meta`), the `rows` array of column→value records,
- * and the total `rowCount`.
- */
-interface AnalyticsSqlResult {
-  columns: AnalyticsSqlColumnMeta[];
-  rowCount: number;
-  rows: Record<string, unknown>[];
-}
-/**
- * Thrown when the SQL API responds with a non-2xx status; a `LunoraError`
- * subclass carrying the HTTP `status` + a capped body preview, with the full
- * body on `cause`.
- *
- * The preview is capped because AE's SQL error text quotes the query back, and
- * `ANALYTICS_SQL_ERROR` is non-internal — the message reaches the browser.
- */
-declare class AnalyticsSqlError extends LunoraError {
-  constructor(status: number, body: string);
-}
-/** The read client: a single `query(sql)` over the AE SQL API. */
-interface AnalyticsSqlClient {
-  query: (sql: string) => Promise<AnalyticsSqlResult>;
-}
-/**
- * Build an {@link AnalyticsSqlClient}. Each `query` POSTs the raw SQL text to
- * the account's `analytics_engine/sql` endpoint with the bearer token, then
- * normalises AE's `{ meta, data, rows }` body into {@link AnalyticsSqlResult}.
- */
-declare const createAnalyticsSqlClient: (config: AnalyticsSqlConfig) => AnalyticsSqlClient;
-export { type AnalyticsClient, type AnalyticsSqlClient, type AnalyticsSqlColumnMeta, type AnalyticsSqlConfig, AnalyticsSqlError, type AnalyticsSqlResult, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics, createAnalyticsSqlClient };
+export { type AnalyticsClient, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics };

package/dist/analytics/index.mjs

@@ -1 +1 @@
-import{createAnalytics as e}from"../packem_shared/createAnalytics-BXTNc57d.mjs";import{AnalyticsSqlError as a,createAnalyticsSqlClient as c}from"../packem_shared/AnalyticsSqlError-CeQ3A5Eb.mjs";export{a as AnalyticsSqlError,e as createAnalytics,c as createAnalyticsSqlClient};
+import{createAnalytics as t}from"../packem_shared/createAnalytics-BXTNc57d.mjs";export{t as createAnalytics};

package/dist/analytics-sql/index.d.mts

@@ -0,0 +1,175 @@
+import { LunoraError } from '@lunora/errors';
+/**
+ * Structural types for the Analytics SQL read path.
+ *
+ * The real binding is workers-types' `AnalyticsSQLBinding` (the wrangler
+ * `analytics` key, wrangler ≥ 4.145.0). It is mirrored **structurally**
+ * (`AnalyticsSqlBindingLike`) rather than aliased, like every other bindings
+ * subpath: an alias resolved against an older or absent workers-types install
+ * would degrade to `any`, and plain-object test doubles satisfy a structural
+ * contract without workerd. A type test pins that the real binding still
+ * satisfies the mirror.
+ */
+/** A value bound to a `$1` / `$name` placeholder. */
+type AnalyticsSqlParameter = boolean | number | string | null;
+/** Positional (`$1`, `$2`, …) or named (`$start`, …) placeholder values. */
+type AnalyticsSqlParams = Readonly<Record<string, AnalyticsSqlParameter>> | ReadonlyArray<AnalyticsSqlParameter>;
+/** One Analytics SQL statement and its optional placeholder values. */
+interface AnalyticsSqlRequest {
+  params?: AnalyticsSqlParams;
+  query: string;
+}
+/** Execution statistics the SQL API reports for a query. */
+interface AnalyticsSqlStatistics {
+  bytes_read: number;
+  elapsed_ms: number;
+  rows_read: number;
+}
+/**
+ * The raw result body: `data` rows plus the `rows` count and `statistics`.
+ * `statistics` is optional because the REST endpoint omits it for Log Explorer
+ * datasets; the binding always sets it.
+ */
+interface AnalyticsSqlRawResult<T extends Record<string, unknown> = Record<string, unknown>> {
+  data: T[];
+  rows: number;
+  statistics?: AnalyticsSqlStatistics;
+}
+/**
+ * Anything that answers `query({ query, params })` the way the Analytics SQL
+ * binding does: the real `env.ANALYTICS_SQL` binding, or
+ * `createAnalyticsSqlRest(...)`, the API-token transport over the same SQL API
+ * for a worker with no binding.
+ */
+interface AnalyticsSqlBindingLike {
+  query: <T extends Record<string, unknown> = Record<string, unknown>>(request: AnalyticsSqlRequest) => Promise<AnalyticsSqlRawResult<T>>;
+}
+/** Options for `createAnalyticsSql`. */
+interface AnalyticsSqlOptions {
+  /** The Analytics SQL binding (`env.ANALYTICS_SQL`), or the REST transport from `createAnalyticsSqlRest`. */
+  binding: AnalyticsSqlBindingLike;
+}
+/** A parsed query result: the rows, their count, and the SQL API's execution statistics. */
+interface AnalyticsSqlQueryResult<T extends Record<string, unknown> = Record<string, unknown>> {
+  /** The SQL API's row count (equal to `rows.length` for a complete result). */
+  rowCount: number;
+  rows: T[];
+  /** Absent only when the REST transport queried a dataset that reports none (Log Explorer). */
+  statistics?: AnalyticsSqlStatistics;
+}
+/**
+ * The action-only client bound to `ctx.analyticsSql`: one read-only SQL
+ * statement per call, in the **Analytics SQL** dialect
+ * (`FROM events.analyticsEngine."<dataset>"`, a lower `timestamp` bound
+ * required), with `$1` / `$name` placeholders bound from `params`.
+ */
+interface AnalyticsSql {
+  query: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: AnalyticsSqlParams) => Promise<AnalyticsSqlQueryResult<T>>;
+}
+/** Configuration for `createAnalyticsSqlRest`. */
+interface AnalyticsSqlRestConfig {
+  /** The Cloudflare account id the queries are scoped to (sent as `scope.accountTag`). */
+  accountId: string;
+  /** API token with Account Analytics Read. A secret: never a binding, never shipped to a browser. */
+  apiToken: string;
+  /** `fetch` implementation. Defaults to the global `fetch`; injected in tests so the transport never touches the network. */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Milliseconds before an in-flight query (the fetch AND its body read) is
+   * aborted, surfacing as a retryable query error with status 504.
+   * Defaults to 60_000. Carried by the request's `signal`, so a custom `fetch`
+   * that ignores `signal` leaves the query unbounded.
+   */
+  timeoutMs?: number;
+}
+/**
+ * Build the action-only {@link AnalyticsSql} client bound to `ctx.analyticsSql`.
+ *
+ * `binding` is the Analytics SQL binding (`env.ANALYTICS_SQL`, the wrangler
+ * `analytics` key) or, in a worker without one, the API-token transport from
+ * `createAnalyticsSqlRest`. Both speak the same Analytics SQL dialect, so a
+ * statement written against one runs unchanged on the other; the binding derives
+ * the account from the Worker, the REST transport sends it as `scope.accountTag`.
+ *
+ * ```ts
+ * const analyticsSql = createAnalyticsSql({ binding: env.ANALYTICS_SQL });
+ * const { rows } = await analyticsSql.query<{ calls: number }>(
+ *     `SELECT COUNT(*) AS calls FROM events.analyticsEngine.app WHERE timestamp >= $since`,
+ *     { since: new Date(Date.now() - 3_600_000).toISOString() },
+ * );
+ * ```
+ *
+ * A rejected query surfaces as an {@link AnalyticsSqlQueryError} carrying the
+ * binding's `retryable` flag. Nothing is retried here.
+ */
+declare const createAnalyticsSql: (options: AnalyticsSqlOptions) => AnalyticsSql;
+/** What an {@link AnalyticsSqlQueryError} carries on `data`, so a client can decide to retry. */
+interface AnalyticsSqlQueryErrorData {
+  /** Whether repeating the same query may succeed (rate, concurrency or resource limits, transient outages). */
+  retryable: boolean;
+}
+/**
+ * A failed Analytics SQL query, from either transport: the binding rejecting
+ * (its error's `retryable` flag is kept), or the REST endpoint answering
+ * non-2xx (`429` / `500` / `503` / `507` are retryable, per Cloudflare's SQL
+ * API error reference) or timing out (`504`, retryable).
+ *
+ * Neither transport retries. The message embeds at most a capped preview of the
+ * upstream text, because `ANALYTICS_SQL_QUERY_ERROR` is client-safe and SQL API
+ * errors quote the statement back; the full text stays on `cause`.
+ */
+declare class AnalyticsSqlQueryError extends LunoraError {
+  readonly retryable: boolean;
+  constructor(detail: string, options: {
+    cause?: unknown;
+    retryable: boolean;
+    status?: number;
+  });
+}
+/** The Studio usage panels, in display order. */
+declare const FUNCTION_USAGE_PANELS: readonly ["volume", "latency", "hotShards"];
+/** One Studio usage panel. */
+type FunctionUsagePanel = (typeof FUNCTION_USAGE_PANELS)[number];
+/** Options for {@link functionUsageQuery}. */
+interface FunctionUsageQueryOptions {
+  /** The Analytics Engine dataset (`analytics_engine_datasets[].dataset`). Defaults to `ANALYTICS`, the one reconcile writes. */
+  dataset?: string;
+  /** Lower `timestamp` bound, an ISO-8601 string. Defaults to 24 hours before now. The dialect requires one. */
+  since?: string;
+}
+/** Whether `value` names a {@link FunctionUsagePanel} — for validating the key an action receives. */
+declare const isFunctionUsagePanel: (value: unknown) => value is FunctionUsagePanel;
+/**
+ * The statement and `$since` parameter for one Studio usage panel, to run with
+ * `ctx.analyticsSql.query(request.query, request.params)`.
+ *
+ * The dataset is quoted as an identifier (embedded `"` doubled). It comes from
+ * your code, not from the caller.
+ */
+declare const functionUsageQuery: (panel: FunctionUsagePanel, options?: FunctionUsageQueryOptions) => AnalyticsSqlRequest & {
+  params: {
+    since: string;
+  };
+};
+/**
+ * Build an {@link AnalyticsSqlBindingLike} that runs each query over the REST
+ * endpoint with an account API token (Account Analytics Read). Use it where the
+ * Worker has no `analytics` binding — a wrangler older than 4.145.0, or a host
+ * that is not a Worker — and hand it to `createAnalyticsSql({ binding })` or
+ * `defineApp().analyticsSql((env) => createAnalyticsSqlRest({ … }))`.
+ *
+ * Every failure is an {@link AnalyticsSqlQueryError}: a non-2xx (`429` / `500`
+ * / `503` / `507` retryable), a malformed body (not retryable), the deadline
+ * (`504`, retryable), or the request never reaching the API — DNS, a reset
+ * connection — which is retryable too. Nothing is retried here.
+ *
+ * The token is a secret: read it from `env`, never from a browser.
+ */
+declare const createAnalyticsSqlRest: (config: AnalyticsSqlRestConfig) => AnalyticsSqlBindingLike;
+export { type AnalyticsSql, type AnalyticsSqlBindingLike, type AnalyticsSqlOptions, type AnalyticsSqlParameter, type AnalyticsSqlParams, AnalyticsSqlQueryError, type AnalyticsSqlQueryErrorData, type AnalyticsSqlQueryResult, type AnalyticsSqlRawResult, type AnalyticsSqlRequest, type AnalyticsSqlRestConfig, type AnalyticsSqlStatistics, FUNCTION_USAGE_PANELS, type FunctionUsagePanel, type FunctionUsageQueryOptions,
+/**
+ * `ctx.analyticsSql` — read-only SQL over Cloudflare's Analytics SQL API, through
+ * the Analytics SQL Workers binding (wrangler `analytics` key, ≥ 4.145.0) or the
+ * API-token REST transport where there is no binding.
+ */
+createAnalyticsSql, createAnalyticsSqlRest, functionUsageQuery, isFunctionUsagePanel };

package/dist/analytics-sql/index.d.ts

@@ -0,0 +1,175 @@
+import { LunoraError } from '@lunora/errors';
+/**
+ * Structural types for the Analytics SQL read path.
+ *
+ * The real binding is workers-types' `AnalyticsSQLBinding` (the wrangler
+ * `analytics` key, wrangler ≥ 4.145.0). It is mirrored **structurally**
+ * (`AnalyticsSqlBindingLike`) rather than aliased, like every other bindings
+ * subpath: an alias resolved against an older or absent workers-types install
+ * would degrade to `any`, and plain-object test doubles satisfy a structural
+ * contract without workerd. A type test pins that the real binding still
+ * satisfies the mirror.
+ */
+/** A value bound to a `$1` / `$name` placeholder. */
+type AnalyticsSqlParameter = boolean | number | string | null;
+/** Positional (`$1`, `$2`, …) or named (`$start`, …) placeholder values. */
+type AnalyticsSqlParams = Readonly<Record<string, AnalyticsSqlParameter>> | ReadonlyArray<AnalyticsSqlParameter>;
+/** One Analytics SQL statement and its optional placeholder values. */
+interface AnalyticsSqlRequest {
+  params?: AnalyticsSqlParams;
+  query: string;
+}
+/** Execution statistics the SQL API reports for a query. */
+interface AnalyticsSqlStatistics {
+  bytes_read: number;
+  elapsed_ms: number;
+  rows_read: number;
+}
+/**
+ * The raw result body: `data` rows plus the `rows` count and `statistics`.
+ * `statistics` is optional because the REST endpoint omits it for Log Explorer
+ * datasets; the binding always sets it.
+ */
+interface AnalyticsSqlRawResult<T extends Record<string, unknown> = Record<string, unknown>> {
+  data: T[];
+  rows: number;
+  statistics?: AnalyticsSqlStatistics;
+}
+/**
+ * Anything that answers `query({ query, params })` the way the Analytics SQL
+ * binding does: the real `env.ANALYTICS_SQL` binding, or
+ * `createAnalyticsSqlRest(...)`, the API-token transport over the same SQL API
+ * for a worker with no binding.
+ */
+interface AnalyticsSqlBindingLike {
+  query: <T extends Record<string, unknown> = Record<string, unknown>>(request: AnalyticsSqlRequest) => Promise<AnalyticsSqlRawResult<T>>;
+}
+/** Options for `createAnalyticsSql`. */
+interface AnalyticsSqlOptions {
+  /** The Analytics SQL binding (`env.ANALYTICS_SQL`), or the REST transport from `createAnalyticsSqlRest`. */
+  binding: AnalyticsSqlBindingLike;
+}
+/** A parsed query result: the rows, their count, and the SQL API's execution statistics. */
+interface AnalyticsSqlQueryResult<T extends Record<string, unknown> = Record<string, unknown>> {
+  /** The SQL API's row count (equal to `rows.length` for a complete result). */
+  rowCount: number;
+  rows: T[];
+  /** Absent only when the REST transport queried a dataset that reports none (Log Explorer). */
+  statistics?: AnalyticsSqlStatistics;
+}
+/**
+ * The action-only client bound to `ctx.analyticsSql`: one read-only SQL
+ * statement per call, in the **Analytics SQL** dialect
+ * (`FROM events.analyticsEngine."<dataset>"`, a lower `timestamp` bound
+ * required), with `$1` / `$name` placeholders bound from `params`.
+ */
+interface AnalyticsSql {
+  query: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: AnalyticsSqlParams) => Promise<AnalyticsSqlQueryResult<T>>;
+}
+/** Configuration for `createAnalyticsSqlRest`. */
+interface AnalyticsSqlRestConfig {
+  /** The Cloudflare account id the queries are scoped to (sent as `scope.accountTag`). */
+  accountId: string;
+  /** API token with Account Analytics Read. A secret: never a binding, never shipped to a browser. */
+  apiToken: string;
+  /** `fetch` implementation. Defaults to the global `fetch`; injected in tests so the transport never touches the network. */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Milliseconds before an in-flight query (the fetch AND its body read) is
+   * aborted, surfacing as a retryable query error with status 504.
+   * Defaults to 60_000. Carried by the request's `signal`, so a custom `fetch`
+   * that ignores `signal` leaves the query unbounded.
+   */
+  timeoutMs?: number;
+}
+/**
+ * Build the action-only {@link AnalyticsSql} client bound to `ctx.analyticsSql`.
+ *
+ * `binding` is the Analytics SQL binding (`env.ANALYTICS_SQL`, the wrangler
+ * `analytics` key) or, in a worker without one, the API-token transport from
+ * `createAnalyticsSqlRest`. Both speak the same Analytics SQL dialect, so a
+ * statement written against one runs unchanged on the other; the binding derives
+ * the account from the Worker, the REST transport sends it as `scope.accountTag`.
+ *
+ * ```ts
+ * const analyticsSql = createAnalyticsSql({ binding: env.ANALYTICS_SQL });
+ * const { rows } = await analyticsSql.query<{ calls: number }>(
+ *     `SELECT COUNT(*) AS calls FROM events.analyticsEngine.app WHERE timestamp >= $since`,
+ *     { since: new Date(Date.now() - 3_600_000).toISOString() },
+ * );
+ * ```
+ *
+ * A rejected query surfaces as an {@link AnalyticsSqlQueryError} carrying the
+ * binding's `retryable` flag. Nothing is retried here.
+ */
+declare const createAnalyticsSql: (options: AnalyticsSqlOptions) => AnalyticsSql;
+/** What an {@link AnalyticsSqlQueryError} carries on `data`, so a client can decide to retry. */
+interface AnalyticsSqlQueryErrorData {
+  /** Whether repeating the same query may succeed (rate, concurrency or resource limits, transient outages). */
+  retryable: boolean;
+}
+/**
+ * A failed Analytics SQL query, from either transport: the binding rejecting
+ * (its error's `retryable` flag is kept), or the REST endpoint answering
+ * non-2xx (`429` / `500` / `503` / `507` are retryable, per Cloudflare's SQL
+ * API error reference) or timing out (`504`, retryable).
+ *
+ * Neither transport retries. The message embeds at most a capped preview of the
+ * upstream text, because `ANALYTICS_SQL_QUERY_ERROR` is client-safe and SQL API
+ * errors quote the statement back; the full text stays on `cause`.
+ */
+declare class AnalyticsSqlQueryError extends LunoraError {
+  readonly retryable: boolean;
+  constructor(detail: string, options: {
+    cause?: unknown;
+    retryable: boolean;
+    status?: number;
+  });
+}
+/** The Studio usage panels, in display order. */
+declare const FUNCTION_USAGE_PANELS: readonly ["volume", "latency", "hotShards"];
+/** One Studio usage panel. */
+type FunctionUsagePanel = (typeof FUNCTION_USAGE_PANELS)[number];
+/** Options for {@link functionUsageQuery}. */
+interface FunctionUsageQueryOptions {
+  /** The Analytics Engine dataset (`analytics_engine_datasets[].dataset`). Defaults to `ANALYTICS`, the one reconcile writes. */
+  dataset?: string;
+  /** Lower `timestamp` bound, an ISO-8601 string. Defaults to 24 hours before now. The dialect requires one. */
+  since?: string;
+}
+/** Whether `value` names a {@link FunctionUsagePanel} — for validating the key an action receives. */
+declare const isFunctionUsagePanel: (value: unknown) => value is FunctionUsagePanel;
+/**
+ * The statement and `$since` parameter for one Studio usage panel, to run with
+ * `ctx.analyticsSql.query(request.query, request.params)`.
+ *
+ * The dataset is quoted as an identifier (embedded `"` doubled). It comes from
+ * your code, not from the caller.
+ */
+declare const functionUsageQuery: (panel: FunctionUsagePanel, options?: FunctionUsageQueryOptions) => AnalyticsSqlRequest & {
+  params: {
+    since: string;
+  };
+};
+/**
+ * Build an {@link AnalyticsSqlBindingLike} that runs each query over the REST
+ * endpoint with an account API token (Account Analytics Read). Use it where the
+ * Worker has no `analytics` binding — a wrangler older than 4.145.0, or a host
+ * that is not a Worker — and hand it to `createAnalyticsSql({ binding })` or
+ * `defineApp().analyticsSql((env) => createAnalyticsSqlRest({ … }))`.
+ *
+ * Every failure is an {@link AnalyticsSqlQueryError}: a non-2xx (`429` / `500`
+ * / `503` / `507` retryable), a malformed body (not retryable), the deadline
+ * (`504`, retryable), or the request never reaching the API — DNS, a reset
+ * connection — which is retryable too. Nothing is retried here.
+ *
+ * The token is a secret: read it from `env`, never from a browser.
+ */
+declare const createAnalyticsSqlRest: (config: AnalyticsSqlRestConfig) => AnalyticsSqlBindingLike;
+export { type AnalyticsSql, type AnalyticsSqlBindingLike, type AnalyticsSqlOptions, type AnalyticsSqlParameter, type AnalyticsSqlParams, AnalyticsSqlQueryError, type AnalyticsSqlQueryErrorData, type AnalyticsSqlQueryResult, type AnalyticsSqlRawResult, type AnalyticsSqlRequest, type AnalyticsSqlRestConfig, type AnalyticsSqlStatistics, FUNCTION_USAGE_PANELS, type FunctionUsagePanel, type FunctionUsageQueryOptions,
+/**
+ * `ctx.analyticsSql` — read-only SQL over Cloudflare's Analytics SQL API, through
+ * the Analytics SQL Workers binding (wrangler `analytics` key, ≥ 4.145.0) or the
+ * API-token REST transport where there is no binding.
+ */
+createAnalyticsSql, createAnalyticsSqlRest, functionUsageQuery, isFunctionUsagePanel };

package/dist/analytics-sql/index.mjs

@@ -0,0 +1 @@
+import{createAnalyticsSql as t}from"../packem_shared/createAnalyticsSql-BLoq02Nf.mjs";import{AnalyticsSqlQueryError as a}from"../packem_shared/AnalyticsSqlQueryError-DjoIZv5O.mjs";import{FUNCTION_USAGE_PANELS as c,functionUsageQuery as l,isFunctionUsagePanel as s}from"../packem_shared/FUNCTION_USAGE_PANELS-C5yhnDmF.mjs";import{createAnalyticsSqlRest as f}from"../packem_shared/createAnalyticsSqlRest-3Zndhp1B.mjs";export{a as AnalyticsSqlQueryError,c as FUNCTION_USAGE_PANELS,t as createAnalyticsSql,f as createAnalyticsSqlRest,l as functionUsageQuery,s as isFunctionUsagePanel};

package/dist/packem_shared/AnalyticsSqlQueryError-DjoIZv5O.mjs

@@ -0,0 +1 @@
+import{LunoraError as t}from"@lunora/errors";import{c as s}from"./cap-error-body-YBKO32BF.mjs";class u extends t{retryable;constructor(a,r){const e={retryable:r.retryable};super("ANALYTICS_SQL_QUERY_ERROR",`Analytics SQL query failed: ${s(a)}`,{cause:r.cause??a,data:e,name:"AnalyticsSqlQueryError",...r.status===void 0?{}:{status:r.status}}),this.retryable=r.retryable}}export{u as AnalyticsSqlQueryError};

package/dist/packem_shared/FUNCTION_USAGE_PANELS-C5yhnDmF.mjs

@@ -0,0 +1 @@
+const l=["volume","latency","hotShards"];const a={hotShards:e=>`SELECT blob3 AS shard, COUNT(*) AS calls FROM ${e} WHERE timestamp >= $since AND blob1 = 'function_call' GROUP BY shard ORDER BY calls DESC LIMIT 25`,latency:e=>`SELECT blob2 AS fn, quantileWeighted(0.50, double1, sampleInterval) AS p50, quantileWeighted(0.95, double1, sampleInterval) AS p95 FROM ${e} WHERE timestamp >= $since AND blob1 = 'function_call' GROUP BY fn ORDER BY p95 DESC LIMIT 25`,volume:e=>`SELECT blob2 AS fn, COUNT(*) AS calls FROM ${e} WHERE timestamp >= $since AND blob1 = 'function_call' GROUP BY fn ORDER BY calls DESC LIMIT 25`},c=e=>typeof e=="string"&&l.includes(e),o=(e,n={})=>{const t=n.dataset??"ANALYTICS";return{params:{since:n.since??new Date(Date.now()-864e5).toISOString()},query:a[e](`events.analyticsEngine."${t.replaceAll('"','""')}"`)}};export{l as FUNCTION_USAGE_PANELS,o as functionUsageQuery,c as isFunctionUsagePanel};

package/dist/packem_shared/R2SqlError-5z-ShSB5.mjs

@@ -0,0 +1 @@
+import{LunoraError as d}from"@lunora/errors";import{c as f}from"./cap-error-body-YBKO32BF.mjs";import{s as h}from"./sql-rest-post-CDcOxw4h.mjs";import y from"./SelectBuilder-DJXNSdqC.mjs";import{ident as m,toText as l}from"./Sql-BfnxRway.mjs";const R="https://api.sql.cloudflarestorage.com/api/v1/accounts",w=6e4,E=e=>e[0]===void 0?[]:Object.keys(e[0]).map(s=>({name:s}));class u extends d{constructor(s,c){super("R2_SQL_ERROR",`R2 SQL query failed (${String(s)}): ${f(c)}`,{cause:c,name:"R2SqlError",status:s})}}const A=e=>{const s=e.fetch??globalThis.fetch,p=`${e.endpoint??R}/${encodeURIComponent(e.accountId)}/r2-sql/query/${encodeURIComponent(e.bucket)}`,S=`${e.accountId}_${e.bucket}`,i=e.timeoutMs??w,n=async t=>{const o=await h({apiToken:e.apiToken,body:{query:t,warehouse:S},fetch:s,timeoutMs:i,url:p});if("timedOut"in o)throw new u(504,`query timed out after ${String(i)}ms (R2SqlConfig.timeoutMs)`);if(!o.ok)throw new u(o.status,o.text);const r=o.json;if(r.success===!1||r.errors!==void 0&&r.errors.length>0)throw new u(502,JSON.stringify(r.errors??r));const a=r.result?.rows??[];return{columns:r.result?.schema??E(a),rowCount:a.length,rows:a}};return{describe:async t=>n(`DESCRIBE ${m(t)}`),explain:async(t,o)=>n(`EXPLAIN ${o?.format==="json"?"FORMAT JSON ":""}${l(t)}`),from:t=>new y(n,t),query:async t=>n(l(t)),showDatabases:async()=>n("SHOW DATABASES"),showTables:async t=>n(`SHOW TABLES IN ${m(t)}`)}};export{u as R2SqlError,A as createR2Sql};

package/dist/packem_shared/createAnalyticsSql-BLoq02Nf.mjs

@@ -0,0 +1 @@
+import{AnalyticsSqlQueryError as a}from"./AnalyticsSqlQueryError-DjoIZv5O.mjs";const o=t=>typeof t=="object"&&t!==null&&t.retryable===!0,c=t=>t instanceof Error?t.message:String(t),l=t=>{const{binding:i}=t;return{query:async(n,r)=>{let s;try{s=await i.query({query:n,...r===void 0?{}:{params:r}})}catch(e){throw e instanceof a?e:new a(c(e),{cause:e,retryable:o(e)})}return{rowCount:s.rows,rows:s.data,...s.statistics===void 0?{}:{statistics:s.statistics}}}}};export{l as createAnalyticsSql};

package/dist/packem_shared/createAnalyticsSqlRest-3Zndhp1B.mjs

@@ -0,0 +1 @@
+import{s as c}from"./sql-rest-post-CDcOxw4h.mjs";import{AnalyticsSqlQueryError as a}from"./AnalyticsSqlQueryError-DjoIZv5O.mjs";const u="https://api.cloudflare.com/client/v4/analytics/sql",l=6e4,y=new Set([429,500,503,507]),p=e=>{const n=e.fetch??globalThis.fetch.bind(globalThis),o=e.timeoutMs??l;return{query:async r=>{let t;try{t=await c({apiToken:e.apiToken,body:{query:r.query,...r.params===void 0?{}:{params:r.params},scope:{accountTag:e.accountId}},fetch:n,timeoutMs:o,url:u})}catch(i){throw new a(`the request did not reach the SQL API: ${String(i)}`,{cause:i,retryable:!0,status:502})}if("timedOut"in t)throw new a(`query timed out after ${String(o)}ms (AnalyticsSqlRestConfig.timeoutMs)`,{retryable:!0,status:504});if(!t.ok)throw new a(`${String(t.status)} ${t.text}`,{cause:t.text,retryable:y.has(t.status),status:t.status});const s=t.json;if(s===null||typeof s!="object"||!Array.isArray(s.data))throw new a("the SQL API returned a body without a data array",{cause:t.json,retryable:!1,status:502});return{data:s.data,rows:typeof s.rows=="number"?s.rows:s.data.length,...s.statistics===void 0?{}:{statistics:s.statistics}}}}};export{p as createAnalyticsSqlRest};

package/dist/packem_shared/sql-rest-post-CDcOxw4h.mjs

@@ -0,0 +1 @@
+const u=(o,r,n)=>{if(r===void 0)return{dispose:()=>{},signal:o};const e=new AbortController,s=setTimeout(()=>{e.abort(n())},r);return{dispose:()=>{clearTimeout(s)},signal:e.signal}},l=async({apiToken:o,body:r,fetch:n,timeoutMs:e,url:s})=>{const a=u(void 0,e,()=>new DOMException(`deadline of ${String(e)}ms exceeded`,"TimeoutError")),d=()=>a.signal?.aborted===!0;try{const t=await n(s,{body:JSON.stringify(r),headers:{Authorization:`Bearer ${o}`,"Content-Type":"application/json"},method:"POST",signal:a.signal});if(!t.ok){const i=await t.text().catch(()=>"<error body unavailable: the request deadline fired before it was read>");return{ok:!1,status:t.status,text:i}}try{return{json:await t.json(),ok:!0}}catch(i){return d()?{timedOut:!0}:{ok:!1,status:502,text:`the endpoint returned a non-JSON body (HTTP ${String(t.status)}): ${String(i)}`}}}catch(t){if(d())return{timedOut:!0};throw t}finally{a.dispose()}};export{l as s};

package/dist/r2sql/index.d.mts

@@ -80,8 +80,8 @@ declare const renderOrderTerm: (term: OrderTerm) => string;
  *
  * Everything here is deliberately structural (no hard dependency on
  * `@cloudflare/workers-types`) so unit tests can inject a plain `fetch` double
- * and never touch the network — mirroring `AnalyticsSqlConfig` in
- * `@lunora/bindings/analytics`.
+ * and never touch the network — mirroring the REST transport config in
+ * `@lunora/bindings/analytics-sql`.
  */
 /**
  * Configuration for a {@link import("./client").R2SqlClient | R2SqlClient}.

package/dist/r2sql/index.d.ts

@@ -80,8 +80,8 @@ declare const renderOrderTerm: (term: OrderTerm) => string;
  *
  * Everything here is deliberately structural (no hard dependency on
  * `@cloudflare/workers-types`) so unit tests can inject a plain `fetch` double
- * and never touch the network — mirroring `AnalyticsSqlConfig` in
- * `@lunora/bindings/analytics`.
+ * and never touch the network — mirroring the REST transport config in
+ * `@lunora/bindings/analytics-sql`.
  */
 /**
  * Configuration for a {@link import("./client").R2SqlClient | R2SqlClient}.

package/dist/r2sql/index.mjs

@@ -1 +1 @@
-import{default as o}from"../packem_shared/SelectBuilder-DJXNSdqC.mjs";import{R2SqlError as l,createR2Sql as f}from"../packem_shared/R2SqlError-ZHgOWClB.mjs";import{asc as d,desc as i,renderOrderTerm as n}from"../packem_shared/asc-DP_WFiAE.mjs";import{default as s}from"../packem_shared/SetOperation-kiI5Wnlm.mjs";import{Sql as m,ident as S,isSql as q,joinSql as c,lit as u,raw as w,sql as R,tableRef as E,toText as O}from"../packem_shared/Sql-BfnxRway.mjs";import{WindowFunction as W,fn as b}from"../packem_shared/WindowFunction-CL4jYy2l.mjs";import{default as B}from"../packem_shared/WindowExpression-VX7EEV3h.mjs";export{l as R2SqlError,o as SelectBuilder,s as SetOperation,m as Sql,B as WindowExpression,W as WindowFunction,d as asc,f as createR2Sql,i as desc,b as fn,S as ident,q as isSql,c as joinSql,u as lit,w as raw,n as renderOrderTerm,R as sql,E as tableRef,O as toText};
+import{default as o}from"../packem_shared/SelectBuilder-DJXNSdqC.mjs";import{R2SqlError as l,createR2Sql as f}from"../packem_shared/R2SqlError-5z-ShSB5.mjs";import{asc as d,desc as i,renderOrderTerm as n}from"../packem_shared/asc-DP_WFiAE.mjs";import{default as s}from"../packem_shared/SetOperation-kiI5Wnlm.mjs";import{Sql as m,ident as S,isSql as q,joinSql as c,lit as u,raw as w,sql as R,tableRef as E,toText as O}from"../packem_shared/Sql-BfnxRway.mjs";import{WindowFunction as W,fn as b}from"../packem_shared/WindowFunction-CL4jYy2l.mjs";import{default as B}from"../packem_shared/WindowExpression-VX7EEV3h.mjs";export{l as R2SqlError,o as SelectBuilder,s as SetOperation,m as Sql,B as WindowExpression,W as WindowFunction,d as asc,f as createR2Sql,i as desc,b as fn,S as ident,q as isSql,c as joinSql,u as lit,w as raw,n as renderOrderTerm,R as sql,E as tableRef,O as toText};

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@lunora/bindings",
-  "version": "1.0.0-alpha.92",
-  "description": "Lightweight Cloudflare binding helpers for Lunora — ctx.kv, ctx.images, ctx.analytics, ctx.pipelines, ctx.vectors, ctx.r2sql, ctx.artifacts, ctx.aiSearch — one install, per-binding subpaths",
+  "version": "1.0.0-alpha.93",
+  "description": "Lightweight Cloudflare binding helpers for Lunora — ctx.kv, ctx.images, ctx.analytics, ctx.pipelines, ctx.vectors, ctx.r2sql, ctx.artifacts, ctx.aiSearch, ctx.analyticsSql — one install, per-binding subpaths",
   "keywords": [
     "ai-search",
     "analytics",
+    "analytics-sql",
     "artifacts",
     "cloudflare",
     "images",
@@ -48,6 +49,10 @@
       "types": "./dist/analytics/index.d.ts",
       "import": "./dist/analytics/index.mjs"
     },
+    "./analytics-sql": {
+      "types": "./dist/analytics-sql/index.d.ts",
+      "import": "./dist/analytics-sql/index.mjs"
+    },
     "./pipelines": {
       "types": "./dist/pipelines/index.d.ts",
       "import": "./dist/pipelines/index.mjs"
@@ -74,8 +79,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.49",
-    "@lunora/platform": "1.0.0-alpha.51"
+    "@lunora/errors": "1.0.0-alpha.50",
+    "@lunora/platform": "1.0.0-alpha.52"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"

package/dist/packem_shared/AnalyticsSqlError-CeQ3A5Eb.mjs

@@ -1 +0,0 @@
-import{LunoraError as y}from"@lunora/errors";import{c as h}from"./cap-error-body-YBKO32BF.mjs";const w="https://api.cloudflare.com/client/v4/accounts",S=6e4;class a extends y{constructor(r,o){super("ANALYTICS_SQL_ERROR",`Analytics Engine SQL API returned ${String(r)}: ${h(o)}`,{cause:o,name:"AnalyticsSqlError",status:r})}}const b=e=>{const r=e.fetch??globalThis.fetch,o=`${w}/${encodeURIComponent(e.accountId)}/analytics_engine/sql`,c=e.timeoutMs??S;return{query:async u=>{const n=new AbortController,d=setTimeout(()=>{n.abort()},c);try{const t=await r(o,{body:u,headers:{Authorization:`Bearer ${e.apiToken}`,"Content-Type":"text/plain"},method:"POST",signal:n.signal});if(!t.ok)throw new a(t.status,await t.text().catch(()=>"<error body unavailable: the request deadline fired before it was read>"));let i;try{i=await t.json()}catch(m){throw n.signal.aborted?m:new a(t.status,"Analytics Engine SQL API returned a non-JSON body.")}const s=i,l=s.data??[];return{columns:s.meta??[],rowCount:s.rows??l.length,rows:l}}catch(t){throw n.signal.aborted&&!(t instanceof a)?new a(504,`query timed out after ${String(c)}ms (AnalyticsSqlConfig.timeoutMs)`):t}finally{clearTimeout(d)}}}};export{a as AnalyticsSqlError,b as createAnalyticsSqlClient};

package/dist/packem_shared/R2SqlError-ZHgOWClB.mjs

@@ -1 +0,0 @@
-import{LunoraError as f}from"@lunora/errors";import{c as b}from"./cap-error-body-YBKO32BF.mjs";import R from"./SelectBuilder-DJXNSdqC.mjs";import{ident as m,toText as h}from"./Sql-BfnxRway.mjs";const T="https://api.sql.cloudflarestorage.com/api/v1/accounts",E=6e4,$=e=>e[0]===void 0?[]:Object.keys(e[0]).map(s=>({name:s}));class c extends f{constructor(s,i){super("R2_SQL_ERROR",`R2 SQL query failed (${String(s)}): ${b(i)}`,{cause:i,name:"R2SqlError",status:s})}}const C=e=>{const s=e.fetch??globalThis.fetch,S=`${e.endpoint??T}/${encodeURIComponent(e.accountId)}/r2-sql/query/${encodeURIComponent(e.bucket)}`,p=`${e.accountId}_${e.bucket}`,l=e.timeoutMs??E,n=async t=>{const a=new AbortController,w=setTimeout(()=>{a.abort()},l);try{const r=await s(S,{body:JSON.stringify({query:t,warehouse:p}),headers:{Authorization:`Bearer ${e.apiToken}`,"Content-Type":"application/json"},method:"POST",signal:a.signal});if(!r.ok)throw new c(r.status,await r.text().catch(()=>"<error body unavailable: the request deadline fired before it was read>"));let d;try{d=await r.json()}catch(y){throw a.signal.aborted?y:new c(r.status,"R2 SQL returned a non-JSON body.")}const o=d;if(o.success===!1||o.errors!==void 0&&o.errors.length>0)throw new c(r.status,JSON.stringify(o.errors??o));const u=o.result?.rows??[];return{columns:o.result?.schema??$(u),rowCount:u.length,rows:u}}catch(r){throw a.signal.aborted&&!(r instanceof c)?new c(504,`query timed out after ${String(l)}ms (R2SqlConfig.timeoutMs)`):r}finally{clearTimeout(w)}};return{describe:async t=>n(`DESCRIBE ${m(t)}`),explain:async(t,a)=>n(`EXPLAIN ${a?.format==="json"?"FORMAT JSON ":""}${h(t)}`),from:t=>new R(n,t),query:async t=>n(h(t)),showDatabases:async()=>n("SHOW DATABASES"),showTables:async t=>n(`SHOW TABLES IN ${m(t)}`)}};export{c as R2SqlError,C as createR2Sql};