@lunora/bindings 1.0.0-alpha.1 → 1.0.0-alpha.10

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/dist/analytics/index.d.mts

@@ -1,19 +1,20 @@
+import { LunoraError } from '@lunora/errors';
 /**
-* Structural types for the Analytics Engine write path.
-*
-* The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
-* **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
-* satisfy the contract without pulling workerd into a unit test — the same
-* approach `@lunora/d1` takes with `D1DatabaseLike`
-* (`packages/d1/src/d1-client.ts`).
-*/
+ * Structural types for the Analytics Engine write path.
+ *
+ * The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
+ * **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
+ * satisfy the contract without pulling workerd into a unit test — the same
+ * approach `@lunora/d1` takes with `D1DatabaseLike`
+ * (`packages/d1/src/d1-client.ts`).
+ */
 /**
-* One Analytics Engine data point, mirroring the positional shape
-* `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
-* `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
-* data point — the SQL API later exposes them as `blob1..blob20`,
-* `double1..double20`, and `index1`.
-*/
+ * One Analytics Engine data point, mirroring the positional shape
+ * `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
+ * `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
+ * data point — the SQL API later exposes them as `blob1..blob20`,
+ * `double1..double20`, and `index1`.
+ */
 interface AnalyticsEngineDataPoint {
   /** String columns, mapped positionally to `blob1..blob20`. */
   blobs?: (ArrayBuffer | null | string)[];
@@ -23,19 +24,19 @@ interface AnalyticsEngineDataPoint {
   indexes?: (ArrayBuffer | string)[];
 }
 /**
-* Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
-* kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
-* fire-and-forget: it returns `void` and never throws on the hot path.
-*/
+ * Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
+ * kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
+ * fire-and-forget: it returns `void` and never throws on the hot path.
+ */
 interface AnalyticsEngineDatasetLike {
   writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
 }
 /**
-* Named-field event handed to {@link AnalyticsClient.track}. Each field is
-* mapped to a positional AE column and the mapping recorded in a returned
-* {@link TrackSchema}, so the read side can reconstruct named columns from the
-* SQL API's positional `blobN`/`doubleN`/`index1` output.
-*/
+ * Named-field event handed to {@link AnalyticsClient.track}. Each field is
+ * mapped to a positional AE column and the mapping recorded in a returned
+ * {@link TrackSchema}, so the read side can reconstruct named columns from the
+ * SQL API's positional `blobN`/`doubleN`/`index1` output.
+ */
 interface TrackEvent {
   /** String dimensions → `blobs` (`blob1..blob20`), in object key order. */
   dimensions?: Record<string, string>;
@@ -52,11 +53,11 @@ interface TrackColumn {
   field: string;
 }
 /**
-* The field→column mapping {@link AnalyticsClient.track} records for one event
-* shape, so the read side can project the SQL API's positional columns back to
-* named fields. `name` is the logical event name; the column arrays are in the
-* same order the dimensions/metrics were written.
-*/
+ * The field→column mapping {@link AnalyticsClient.track} records for one event
+ * shape, so the read side can project the SQL API's positional columns back to
+ * named fields. `name` is the logical event name; the column arrays are in the
+ * same order the dimensions/metrics were written.
+ */
 interface TrackSchema {
   dimensions: TrackColumn[];
   index: TrackColumn | null;
@@ -64,41 +65,41 @@ interface TrackSchema {
   name: string;
 }
 /**
-* The write-side client bound to `ctx.analytics` (the generated context imports
-* this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
-* is fire-and-forget and sampled — never read a data point back in-handler.
-*/
+ * The write-side client bound to `ctx.analytics` (the generated context imports
+ * this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
+ * is fire-and-forget and sampled — never read a data point back in-handler.
+ */
 interface AnalyticsClient {
   /**
-  * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
-  * positional layout, writes it, and returns the {@link TrackSchema} mapping
-  * (the logical `name` is recorded as the first blob, `blob1`).
-  */
+   * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
+   * positional layout, writes it, and returns the {@link TrackSchema} mapping
+   * (the logical `name` is recorded as the first blob, `blob1`).
+   */
   track: (name: string, event?: TrackEvent) => TrackSchema;
   /**
-  * Write a raw positional data point. Enforces AE's per-data-point count
-  * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
-  * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
-  * surfaces in dev rather than being silently rejected by the platform.
-  */
+   * Write a raw positional data point. Enforces AE's per-data-point count
+   * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
+   * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
+   * surfaces in dev rather than being silently rejected by the platform.
+   */
   writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
 }
 /**
-* Wrap an Analytics Engine dataset binding in the write-side
-* {@link AnalyticsClient} bound to `ctx.analytics`.
-*
-* The binding is `env.ANALYTICS` (the self-describing
-* `analytics_engine_datasets` binding the config layer reconciles). Writes are
-* fire-and-forget and sampled — there is no return value to read in-handler.
-*
-* `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
-* caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
-* ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
-* instead of being silently rejected by the platform at the edge. `track` is
-* the ergonomic named-field path: it maps a
-* `{ dimensions, metrics, index }` object to the positional layout and returns
-* the field→column mapping the read side uses to reconstruct named columns.
-*/
+ * Wrap an Analytics Engine dataset binding in the write-side
+ * {@link AnalyticsClient} bound to `ctx.analytics`.
+ *
+ * The binding is `env.ANALYTICS` (the self-describing
+ * `analytics_engine_datasets` binding the config layer reconciles). Writes are
+ * fire-and-forget and sampled — there is no return value to read in-handler.
+ *
+ * `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
+ * caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
+ * ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
+ * instead of being silently rejected by the platform at the edge. `track` is
+ * the ergonomic named-field path: it maps a
+ * `{ dimensions, metrics, index }` object to the positional layout and returns
+ * 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 {
@@ -107,32 +108,31 @@ interface AnalyticsSqlConfig {
   /** 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` implementation. Defaults to the global `fetch`; injected in tests
+   * so the SQL path never touches the network.
+   */
   fetch?: typeof globalThis.fetch;
 }
 /**
-* One column descriptor in a SQL-API response's `meta` array: the column `name`
-* and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
-*/
+ * 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`.
-*/
+ * 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; carries the status + body for the caller to surface. */
-declare class AnalyticsSqlError extends Error {
-  readonly status: number;
+/** Thrown when the SQL API responds with a non-2xx status; a `LunoraError` subclass carrying the HTTP `status` + body for the caller to surface. */
+declare class AnalyticsSqlError extends LunoraError {
   constructor(status: number, body: string);
 }
 /** The read client: a single `query(sql)` over the AE SQL API. */
@@ -140,9 +140,9 @@ 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}.
-*/
+ * 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 AnalyticsEngineDataPoint, type AnalyticsEngineDatasetLike, type AnalyticsSqlClient, type AnalyticsSqlColumnMeta, type AnalyticsSqlConfig, AnalyticsSqlError, type AnalyticsSqlResult, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics, createAnalyticsSqlClient };

package/dist/analytics/index.d.ts

@@ -1,19 +1,20 @@
+import { LunoraError } from '@lunora/errors';
 /**
-* Structural types for the Analytics Engine write path.
-*
-* The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
-* **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
-* satisfy the contract without pulling workerd into a unit test — the same
-* approach `@lunora/d1` takes with `D1DatabaseLike`
-* (`packages/d1/src/d1-client.ts`).
-*/
+ * Structural types for the Analytics Engine write path.
+ *
+ * The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
+ * **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
+ * satisfy the contract without pulling workerd into a unit test — the same
+ * approach `@lunora/d1` takes with `D1DatabaseLike`
+ * (`packages/d1/src/d1-client.ts`).
+ */
 /**
-* One Analytics Engine data point, mirroring the positional shape
-* `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
-* `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
-* data point — the SQL API later exposes them as `blob1..blob20`,
-* `double1..double20`, and `index1`.
-*/
+ * One Analytics Engine data point, mirroring the positional shape
+ * `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
+ * `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
+ * data point — the SQL API later exposes them as `blob1..blob20`,
+ * `double1..double20`, and `index1`.
+ */
 interface AnalyticsEngineDataPoint {
   /** String columns, mapped positionally to `blob1..blob20`. */
   blobs?: (ArrayBuffer | null | string)[];
@@ -23,19 +24,19 @@ interface AnalyticsEngineDataPoint {
   indexes?: (ArrayBuffer | string)[];
 }
 /**
-* Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
-* kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
-* fire-and-forget: it returns `void` and never throws on the hot path.
-*/
+ * Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
+ * kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
+ * fire-and-forget: it returns `void` and never throws on the hot path.
+ */
 interface AnalyticsEngineDatasetLike {
   writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
 }
 /**
-* Named-field event handed to {@link AnalyticsClient.track}. Each field is
-* mapped to a positional AE column and the mapping recorded in a returned
-* {@link TrackSchema}, so the read side can reconstruct named columns from the
-* SQL API's positional `blobN`/`doubleN`/`index1` output.
-*/
+ * Named-field event handed to {@link AnalyticsClient.track}. Each field is
+ * mapped to a positional AE column and the mapping recorded in a returned
+ * {@link TrackSchema}, so the read side can reconstruct named columns from the
+ * SQL API's positional `blobN`/`doubleN`/`index1` output.
+ */
 interface TrackEvent {
   /** String dimensions → `blobs` (`blob1..blob20`), in object key order. */
   dimensions?: Record<string, string>;
@@ -52,11 +53,11 @@ interface TrackColumn {
   field: string;
 }
 /**
-* The field→column mapping {@link AnalyticsClient.track} records for one event
-* shape, so the read side can project the SQL API's positional columns back to
-* named fields. `name` is the logical event name; the column arrays are in the
-* same order the dimensions/metrics were written.
-*/
+ * The field→column mapping {@link AnalyticsClient.track} records for one event
+ * shape, so the read side can project the SQL API's positional columns back to
+ * named fields. `name` is the logical event name; the column arrays are in the
+ * same order the dimensions/metrics were written.
+ */
 interface TrackSchema {
   dimensions: TrackColumn[];
   index: TrackColumn | null;
@@ -64,41 +65,41 @@ interface TrackSchema {
   name: string;
 }
 /**
-* The write-side client bound to `ctx.analytics` (the generated context imports
-* this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
-* is fire-and-forget and sampled — never read a data point back in-handler.
-*/
+ * The write-side client bound to `ctx.analytics` (the generated context imports
+ * this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
+ * is fire-and-forget and sampled — never read a data point back in-handler.
+ */
 interface AnalyticsClient {
   /**
-  * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
-  * positional layout, writes it, and returns the {@link TrackSchema} mapping
-  * (the logical `name` is recorded as the first blob, `blob1`).
-  */
+   * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
+   * positional layout, writes it, and returns the {@link TrackSchema} mapping
+   * (the logical `name` is recorded as the first blob, `blob1`).
+   */
   track: (name: string, event?: TrackEvent) => TrackSchema;
   /**
-  * Write a raw positional data point. Enforces AE's per-data-point count
-  * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
-  * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
-  * surfaces in dev rather than being silently rejected by the platform.
-  */
+   * Write a raw positional data point. Enforces AE's per-data-point count
+   * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
+   * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
+   * surfaces in dev rather than being silently rejected by the platform.
+   */
   writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
 }
 /**
-* Wrap an Analytics Engine dataset binding in the write-side
-* {@link AnalyticsClient} bound to `ctx.analytics`.
-*
-* The binding is `env.ANALYTICS` (the self-describing
-* `analytics_engine_datasets` binding the config layer reconciles). Writes are
-* fire-and-forget and sampled — there is no return value to read in-handler.
-*
-* `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
-* caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
-* ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
-* instead of being silently rejected by the platform at the edge. `track` is
-* the ergonomic named-field path: it maps a
-* `{ dimensions, metrics, index }` object to the positional layout and returns
-* the field→column mapping the read side uses to reconstruct named columns.
-*/
+ * Wrap an Analytics Engine dataset binding in the write-side
+ * {@link AnalyticsClient} bound to `ctx.analytics`.
+ *
+ * The binding is `env.ANALYTICS` (the self-describing
+ * `analytics_engine_datasets` binding the config layer reconciles). Writes are
+ * fire-and-forget and sampled — there is no return value to read in-handler.
+ *
+ * `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
+ * caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
+ * ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
+ * instead of being silently rejected by the platform at the edge. `track` is
+ * the ergonomic named-field path: it maps a
+ * `{ dimensions, metrics, index }` object to the positional layout and returns
+ * 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 {
@@ -107,32 +108,31 @@ interface AnalyticsSqlConfig {
   /** 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` implementation. Defaults to the global `fetch`; injected in tests
+   * so the SQL path never touches the network.
+   */
   fetch?: typeof globalThis.fetch;
 }
 /**
-* One column descriptor in a SQL-API response's `meta` array: the column `name`
-* and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
-*/
+ * 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`.
-*/
+ * 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; carries the status + body for the caller to surface. */
-declare class AnalyticsSqlError extends Error {
-  readonly status: number;
+/** Thrown when the SQL API responds with a non-2xx status; a `LunoraError` subclass carrying the HTTP `status` + body for the caller to surface. */
+declare class AnalyticsSqlError extends LunoraError {
   constructor(status: number, body: string);
 }
 /** The read client: a single `query(sql)` over the AE SQL API. */
@@ -140,9 +140,9 @@ 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}.
-*/
+ * 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 AnalyticsEngineDataPoint, type AnalyticsEngineDatasetLike, type AnalyticsSqlClient, type AnalyticsSqlColumnMeta, type AnalyticsSqlConfig, AnalyticsSqlError, type AnalyticsSqlResult, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics, createAnalyticsSqlClient };

package/dist/analytics/index.mjs

@@ -1,2 +1,2 @@
 export { createAnalytics } from '../packem_shared/createAnalytics-CEEI69o9.mjs';
-export { AnalyticsSqlError, createAnalyticsSqlClient } from '../packem_shared/AnalyticsSqlError-CGTdsi4H.mjs';
+export { AnalyticsSqlError, createAnalyticsSqlClient } from '../packem_shared/AnalyticsSqlError-C2nz3jpH.mjs';