@lunora/bindings 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/analytics/index.d.mts

@@ -1,3 +1,4 @@
+import { LunoraError } from '@lunora/errors';
 /**
 * Structural types for the Analytics Engine write path.
 *
@@ -130,9 +131,8 @@ interface AnalyticsSqlResult {
   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. */

package/dist/analytics/index.d.ts

@@ -1,3 +1,4 @@
+import { LunoraError } from '@lunora/errors';
 /**
 * Structural types for the Analytics Engine write path.
 *
@@ -130,9 +131,8 @@ interface AnalyticsSqlResult {
   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. */

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';

package/dist/images/index.mjs

@@ -1,3 +1,3 @@
-export { createImages } from '../packem_shared/createImages-CJrvqX0u.mjs';
-export { buildImageDeliveryUrl } from '../packem_shared/buildImageDeliveryUrl-D1sVfIOP.mjs';
-export { buildSignedImageUrl, verifySignedImageUrl } from '../packem_shared/buildSignedImageUrl-Otdgc_jO.mjs';
+export { createImages } from '../packem_shared/createImages-BzRnsz3H.mjs';
+export { buildImageDeliveryUrl } from '../packem_shared/buildImageDeliveryUrl-B6_QU91n.mjs';
+export { buildSignedImageUrl, verifySignedImageUrl } from '../packem_shared/buildSignedImageUrl-6iibA9v1.mjs';

package/dist/kv/index.d.mts

@@ -174,4 +174,98 @@ interface Kv {
 */
 declare const scopeKey: (prefix: string, key: string) => string;
 declare const createKv: (options: LunoraKvOptions) => Kv;
-export { type KVNamespaceLike, type Kv, type KvGetOptions, type KvListKey, type KvListOptions, type KvListResult, type KvNamespaceListResult, type KvNamespacePutOptions, type KvPutOptions, type KvValue, type KvValueType, type KvValueWithMetadata, type LunoraKvOptions, createKv, scopeKey };
+/** One KV namespace as the studio's KV browser surfaces it (mirrors the runtime's KvNamespaceSummary). */
+interface KvNamespaceSummaryLike {
+  binding: string;
+}
+/** One key entry as surfaced by the KV admin browser (mirrors the runtime's KvKeyEntry). */
+interface KvKeyEntryLike {
+  expiration?: number;
+  metadata?: unknown;
+  name: string;
+}
+/** A paginated page of KV keys (mirrors the runtime's KvKeyListResult). */
+interface KvKeyListResultLike {
+  cursor?: string;
+  keys: KvKeyEntryLike[];
+  listComplete: boolean;
+}
+/** A value together with its metadata (mirrors the runtime's KvValueResult). */
+interface KvValueResultLike {
+  metadata: unknown;
+  value: null | string;
+}
+/**
+* The structural shape of a KV introspector — mirrors `KvIntrospector` from
+* `@lunora/runtime` without importing it, keeping the dependency graph clean.
+*/
+interface KvIntrospectorLike {
+  deleteKey: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<void>;
+  getValue: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<KvValueResultLike>;
+  listKeys: (options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }) => Promise<KvKeyListResultLike>;
+  listNamespaces: () => Promise<KvNamespaceSummaryLike[]>;
+  putValue: (options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }) => Promise<void>;
+}
+/** Construction options for {@link createKvIntrospector}. */
+interface CreateKvIntrospectorOptions {
+  /**
+  * Map of binding name → bound KV namespace. Each entry becomes one
+  * namespace the studio can browse. Example:
+  * ```ts
+  * createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } })
+  * ```
+  */
+  namespaces: Record<string, KVNamespaceLike>;
+}
+/**
+* Build a `KvIntrospector`-compatible object from a map of bound KV namespaces.
+* Pass the result as `kvIntrospector` on `WorkerOptions` to enable the studio's
+* KV browser (`/_lunora/admin/kv/*` endpoints).
+* @example
+* ```ts
+* createWorker({
+*   // …
+*   kvIntrospector: createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } }),
+* });
+* ```
+*/
+declare const createKvIntrospector: (options: CreateKvIntrospectorOptions) => KvIntrospectorLike;
+/**
+* Zero-config KV introspector: scan a worker `env` for every bound Workers KV
+* namespace and register each under its binding name. Every `kv_namespaces` entry
+* in `wrangler.jsonc` then appears in the studio's KV browser automatically — no
+* hand-written `createKvIntrospector({ namespaces: … })` call, and any binding
+* name (not just `KV`) and any number of namespaces light up. Non-KV bindings
+* (R2, Durable Objects, queues, secrets, …) are skipped via {@link isKvNamespace}.
+*
+* Returns an introspector even when `env` holds no KV namespaces — its
+* `listNamespaces()` resolves to `[]`, so the studio renders an empty state
+* rather than a "not configured" error.
+* @example
+* ```ts
+* createWorker({
+*   // …
+*   kvIntrospector: createKvIntrospectorFromEnv(env),
+* });
+* ```
+*/
+declare const createKvIntrospectorFromEnv: (env: unknown) => KvIntrospectorLike;
+export { type CreateKvIntrospectorOptions, type KVNamespaceLike, type Kv, type KvGetOptions, type KvIntrospectorLike, type KvListKey, type KvListOptions, type KvListResult, type KvNamespaceListResult, type KvNamespacePutOptions, type KvPutOptions, type KvValue, type KvValueType, type KvValueWithMetadata, type LunoraKvOptions, createKv, createKvIntrospector, createKvIntrospectorFromEnv, scopeKey };

package/dist/kv/index.d.ts

@@ -174,4 +174,98 @@ interface Kv {
 */
 declare const scopeKey: (prefix: string, key: string) => string;
 declare const createKv: (options: LunoraKvOptions) => Kv;
-export { type KVNamespaceLike, type Kv, type KvGetOptions, type KvListKey, type KvListOptions, type KvListResult, type KvNamespaceListResult, type KvNamespacePutOptions, type KvPutOptions, type KvValue, type KvValueType, type KvValueWithMetadata, type LunoraKvOptions, createKv, scopeKey };
+/** One KV namespace as the studio's KV browser surfaces it (mirrors the runtime's KvNamespaceSummary). */
+interface KvNamespaceSummaryLike {
+  binding: string;
+}
+/** One key entry as surfaced by the KV admin browser (mirrors the runtime's KvKeyEntry). */
+interface KvKeyEntryLike {
+  expiration?: number;
+  metadata?: unknown;
+  name: string;
+}
+/** A paginated page of KV keys (mirrors the runtime's KvKeyListResult). */
+interface KvKeyListResultLike {
+  cursor?: string;
+  keys: KvKeyEntryLike[];
+  listComplete: boolean;
+}
+/** A value together with its metadata (mirrors the runtime's KvValueResult). */
+interface KvValueResultLike {
+  metadata: unknown;
+  value: null | string;
+}
+/**
+* The structural shape of a KV introspector — mirrors `KvIntrospector` from
+* `@lunora/runtime` without importing it, keeping the dependency graph clean.
+*/
+interface KvIntrospectorLike {
+  deleteKey: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<void>;
+  getValue: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<KvValueResultLike>;
+  listKeys: (options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }) => Promise<KvKeyListResultLike>;
+  listNamespaces: () => Promise<KvNamespaceSummaryLike[]>;
+  putValue: (options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }) => Promise<void>;
+}
+/** Construction options for {@link createKvIntrospector}. */
+interface CreateKvIntrospectorOptions {
+  /**
+  * Map of binding name → bound KV namespace. Each entry becomes one
+  * namespace the studio can browse. Example:
+  * ```ts
+  * createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } })
+  * ```
+  */
+  namespaces: Record<string, KVNamespaceLike>;
+}
+/**
+* Build a `KvIntrospector`-compatible object from a map of bound KV namespaces.
+* Pass the result as `kvIntrospector` on `WorkerOptions` to enable the studio's
+* KV browser (`/_lunora/admin/kv/*` endpoints).
+* @example
+* ```ts
+* createWorker({
+*   // …
+*   kvIntrospector: createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } }),
+* });
+* ```
+*/
+declare const createKvIntrospector: (options: CreateKvIntrospectorOptions) => KvIntrospectorLike;
+/**
+* Zero-config KV introspector: scan a worker `env` for every bound Workers KV
+* namespace and register each under its binding name. Every `kv_namespaces` entry
+* in `wrangler.jsonc` then appears in the studio's KV browser automatically — no
+* hand-written `createKvIntrospector({ namespaces: … })` call, and any binding
+* name (not just `KV`) and any number of namespaces light up. Non-KV bindings
+* (R2, Durable Objects, queues, secrets, …) are skipped via {@link isKvNamespace}.
+*
+* Returns an introspector even when `env` holds no KV namespaces — its
+* `listNamespaces()` resolves to `[]`, so the studio renders an empty state
+* rather than a "not configured" error.
+* @example
+* ```ts
+* createWorker({
+*   // …
+*   kvIntrospector: createKvIntrospectorFromEnv(env),
+* });
+* ```
+*/
+declare const createKvIntrospectorFromEnv: (env: unknown) => KvIntrospectorLike;
+export { type CreateKvIntrospectorOptions, type KVNamespaceLike, type Kv, type KvGetOptions, type KvIntrospectorLike, type KvListKey, type KvListOptions, type KvListResult, type KvNamespaceListResult, type KvNamespacePutOptions, type KvPutOptions, type KvValue, type KvValueType, type KvValueWithMetadata, type LunoraKvOptions, createKv, createKvIntrospector, createKvIntrospectorFromEnv, scopeKey };

package/dist/kv/index.mjs

@@ -1 +1,2 @@
-export { createKv, scopeKey } from '../packem_shared/createKv-DTiSt216.mjs';
+export { createKv, scopeKey } from '../packem_shared/createKv-7lNrS1W2.mjs';
+export { createKvIntrospector, createKvIntrospectorFromEnv } from '../packem_shared/createKvIntrospector-CrAgQp1w.mjs';

package/dist/packem_shared/{AnalyticsSqlError-CGTdsi4H.mjs → AnalyticsSqlError-C2nz3jpH.mjs}

@@ -1,10 +1,9 @@
+import { LunoraError } from '@lunora/errors';
+
 const SQL_API_BASE = "https://api.cloudflare.com/client/v4/accounts";
-class AnalyticsSqlError extends Error {
-  status;
+class AnalyticsSqlError extends LunoraError {
   constructor(status, body) {
-    super(`Analytics Engine SQL API returned ${String(status)}: ${body}`);
-    this.name = "AnalyticsSqlError";
-    this.status = status;
+    super("ANALYTICS_SQL_ERROR", `Analytics Engine SQL API returned ${String(status)}: ${body}`, { name: "AnalyticsSqlError", status });
   }
 }
 const createAnalyticsSqlClient = (config) => {

package/dist/packem_shared/{R2SqlError-DlDd_SrE.mjs → R2SqlError-Boygg3S0.mjs}

@@ -1,3 +1,4 @@
+import { LunoraError } from '@lunora/errors';
 import SelectBuilder from './SelectBuilder-DHaXZwn_.mjs';
 import { ident, toText } from './Sql-DceGtcUd.mjs';
 
@@ -10,12 +11,9 @@ const inferColumns = (rows) => {
     return { name };
   });
 };
-class R2SqlError extends Error {
-  status;
+class R2SqlError extends LunoraError {
   constructor(status, body) {
-    super(`R2 SQL query failed (${String(status)}): ${body}`);
-    this.name = "R2SqlError";
-    this.status = status;
+    super("R2_SQL_ERROR", `R2 SQL query failed (${String(status)}): ${body}`, { name: "R2SqlError", status });
   }
 }
 const createR2Sql = (config) => {

package/dist/packem_shared/{buildImageDeliveryUrl-D1sVfIOP.mjs → buildImageDeliveryUrl-B6_QU91n.mjs}

@@ -1,10 +1,13 @@
+import { LunoraError } from '@lunora/errors';
+
 const ABSOLUTE_URL_RE = /^[a-z][a-z\d+\-.]*:\/\//i;
 const stripTrailingSlash = (value) => value.endsWith("/") ? value.slice(0, -1) : value;
 const stripLeadingSlash = (value) => value.startsWith("/") ? value.slice(1) : value;
 const serializeTransform = (transform) => Object.entries(transform).filter(([, value]) => value !== void 0 && (typeof value === "string" || typeof value === "number")).map(([key, value]) => {
   const serialized = String(value);
   if (serialized.includes(",") || serialized.includes("=")) {
-    throw new Error(
+    throw new LunoraError(
+      "INTERNAL",
       `@lunora/bindings/images: transform option \`${key}\` value \`${serialized}\` contains a \`,\` or \`=\`, which the /cdn-cgi/image/ option list cannot represent (these are the option/key-value separators). For colors, use the hex form (e.g. \`#RRGGBB\`/\`%23RRGGBB\`) instead of \`rgb(r,g,b)\`.`
     );
   }
@@ -18,7 +21,7 @@ const buildImageDeliveryUrl = (options) => {
     return `${base}/${encodeURIComponent(options.imageId)}/${encodeURIComponent(variant)}`;
   }
   if (options.key === void 0) {
-    throw new Error("@lunora/bindings/images: buildImageDeliveryUrl requires either `imageId` or `key`");
+    throw new LunoraError("INTERNAL", "@lunora/bindings/images: buildImageDeliveryUrl requires either `imageId` or `key`");
   }
   const optionString = options.transform === void 0 ? "" : serializeTransform(options.transform);
   const isAbsolute = ABSOLUTE_URL_RE.test(options.key);

package/dist/packem_shared/{buildSignedImageUrl-Otdgc_jO.mjs → buildSignedImageUrl-6iibA9v1.mjs}

@@ -54,10 +54,10 @@ const encodeKey = (key) => key.split("/").map((segment) => encodeURIComponent(se
 const buildSignedImageUrl = async (options) => {
   const expiresInSeconds = options.expiresInSeconds ?? 60 * 60;
   if (!Number.isFinite(expiresInSeconds) || expiresInSeconds <= 0) {
-    throw new Error("@lunora/bindings/images: expiresInSeconds must be a positive finite number");
+    throw new TypeError("@lunora/bindings/images: expiresInSeconds must be a positive finite number");
   }
   if (expiresInSeconds > MAX_EXPIRES_IN_SECONDS) {
-    throw new Error(`@lunora/bindings/images: expiresInSeconds must not exceed ${String(MAX_EXPIRES_IN_SECONDS)} (7 days)`);
+    throw new TypeError(`@lunora/bindings/images: expiresInSeconds must not exceed ${String(MAX_EXPIRES_IN_SECONDS)} (7 days)`);
   }
   const exp = Math.floor(Date.now() / 1e3) + expiresInSeconds;
   const host = extractHost(options.baseUrl);

package/dist/packem_shared/{createImages-CJrvqX0u.mjs → createImages-BzRnsz3H.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const ALLOWED_OUTPUT_FORMATS = /* @__PURE__ */ new Set(["image/avif", "image/gif", "image/jpeg", "image/png", "image/webp"]);
 const DEFAULT_MAX_DIMENSION = 1e4;
 const DEFAULT_OUTPUT_FORMAT = "image/webp";
@@ -14,7 +16,7 @@ const toStream = (input) => {
   }
   if (isR2ObjectBody(input)) {
     if (input.body === null) {
-      throw new Error("@lunora/bindings/images: R2 object body is null (object missing or already consumed)");
+      throw new LunoraError("INTERNAL", "@lunora/bindings/images: R2 object body is null (object missing or already consumed)");
     }
     return input.body;
   }
@@ -35,7 +37,7 @@ const sanitizeTransform = (transform, maxDimension) => {
   }
   const clampDimension = (value) => {
     if (!Number.isFinite(value) || value <= 0) {
-      throw new Error("@lunora/bindings/images: width/height must be a positive finite number");
+      throw new TypeError("@lunora/bindings/images: width/height must be a positive finite number");
     }
     return Math.min(Math.floor(value), maxDimension);
   };
@@ -54,7 +56,10 @@ const splitOverlay = (overlay) => {
 const resolveOutput = (output) => {
   const format = output?.format ?? DEFAULT_OUTPUT_FORMAT;
   if (!ALLOWED_OUTPUT_FORMATS.has(format)) {
-    throw new Error(`@lunora/bindings/images: unsupported output format "${format}" (allowed: ${[...ALLOWED_OUTPUT_FORMATS].join(", ")})`);
+    throw new LunoraError(
+      "INTERNAL",
+      `@lunora/bindings/images: unsupported output format "${format}" (allowed: ${[...ALLOWED_OUTPUT_FORMATS].join(", ")})`
+    );
   }
   return { ...output, format };
 };

package/dist/packem_shared/{createKv-DTiSt216.mjs → createKv-7lNrS1W2.mjs}

@@ -1,19 +1,21 @@
+import { LunoraError } from '@lunora/errors';
+
 const MAX_KEY_LENGTH = 512;
 const MAX_LIST_LIMIT = 1e3;
 const validateKey = (key) => {
   if (typeof key !== "string" || key.length === 0) {
-    throw new Error("@lunora/bindings/kv: key must be a non-empty string");
+    throw new TypeError("@lunora/bindings/kv: key must be a non-empty string");
   }
   if (key.length > MAX_KEY_LENGTH) {
-    throw new Error(`@lunora/bindings/kv: key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
+    throw new LunoraError("INTERNAL", `@lunora/bindings/kv: key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
   }
   if (key.includes("\0")) {
-    throw new Error("@lunora/bindings/kv: key contains NUL byte");
+    throw new LunoraError("INTERNAL", "@lunora/bindings/kv: key contains NUL byte");
   }
   const segments = key.split("/");
   for (const segment of segments) {
     if (segment === "." || segment === "..") {
-      throw new Error("@lunora/bindings/kv: key contains a `.`/`..` path component");
+      throw new LunoraError("INTERNAL", "@lunora/bindings/kv: key contains a `.`/`..` path component");
     }
   }
 };
@@ -22,15 +24,15 @@ const validatePrefix = (prefix) => {
     return;
   }
   if (prefix.length > MAX_KEY_LENGTH) {
-    throw new Error(`@lunora/bindings/kv: prefix exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
+    throw new LunoraError("INTERNAL", `@lunora/bindings/kv: prefix exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
   }
   if (prefix.includes("\0")) {
-    throw new Error("@lunora/bindings/kv: prefix contains NUL byte");
+    throw new LunoraError("INTERNAL", "@lunora/bindings/kv: prefix contains NUL byte");
   }
   const segments = prefix.split("/");
   for (const segment of segments) {
     if (segment === "." || segment === "..") {
-      throw new Error("@lunora/bindings/kv: prefix contains a `.`/`..` path component");
+      throw new LunoraError("INTERNAL", "@lunora/bindings/kv: prefix contains a `.`/`..` path component");
     }
   }
 };
@@ -40,14 +42,14 @@ const scopeKey = (prefix, key) => {
   const trimmedPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
   const composed = `${trimmedPrefix}/${key}`;
   if (composed.length > MAX_KEY_LENGTH) {
-    throw new Error(`@lunora/bindings/kv: scoped key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
+    throw new LunoraError("INTERNAL", `@lunora/bindings/kv: scoped key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
   }
   return composed;
 };
 const toPutOptions = (options) => {
   const out = {};
   if (options.expiration !== void 0 && options.expirationTtl !== void 0) {
-    throw new Error("@lunora/bindings/kv: `expiration` and `expirationTtl` are mutually exclusive");
+    throw new LunoraError("INTERNAL", "@lunora/bindings/kv: `expiration` and `expirationTtl` are mutually exclusive");
   }
   if (options.expiration !== void 0) {
     out.expiration = options.expiration;
@@ -62,7 +64,7 @@ const toPutOptions = (options) => {
 };
 const createKv = (options) => {
   if (!options.namespace) {
-    throw new Error("@lunora/bindings/kv: `namespace` is required");
+    throw new TypeError("@lunora/bindings/kv: `namespace` is required");
   }
   const { keyPrefix, namespace } = options;
   if (keyPrefix !== void 0) {
@@ -103,7 +105,7 @@ const createKv = (options) => {
   };
   const list = async (listOptions = {}) => {
     if (listOptions.limit !== void 0 && (!Number.isInteger(listOptions.limit) || listOptions.limit <= 0)) {
-      throw new Error("@lunora/bindings/kv: `limit` must be a positive integer");
+      throw new TypeError("@lunora/bindings/kv: `limit` must be a positive integer");
     }
     let { prefix } = listOptions;
     if (prefix !== void 0) {

package/dist/packem_shared/createKvIntrospector-CrAgQp1w.mjs

@@ -0,0 +1,77 @@
+import { LunoraError } from '@lunora/errors';
+
+const createKvIntrospector = (options) => {
+  const { namespaces } = options;
+  const resolveNamespace = (binding) => {
+    const ns = namespaces[binding];
+    if (ns === void 0) {
+      throw new LunoraError("BAD_REQUEST", `@lunora/bindings/kv: no namespace registered under binding "${binding}"`);
+    }
+    return ns;
+  };
+  const listNamespaces = () => Promise.resolve(
+    Object.keys(namespaces).map((binding) => {
+      return { binding };
+    })
+  );
+  const listKeys = async (listOptions) => {
+    const ns = resolveNamespace(listOptions.namespace);
+    const result = await ns.list({ cursor: listOptions.cursor, limit: listOptions.limit, prefix: listOptions.prefix });
+    const keys = result.keys.map((entry) => {
+      return {
+        expiration: entry.expiration,
+        metadata: entry.metadata,
+        name: entry.name
+      };
+    });
+    return {
+      cursor: result.list_complete ? void 0 : result.cursor,
+      keys,
+      listComplete: result.list_complete
+    };
+  };
+  const getValue = async (getOptions) => {
+    const ns = resolveNamespace(getOptions.namespace);
+    const result = await ns.getWithMetadata(getOptions.key, "text");
+    return { metadata: result.metadata ?? null, value: result.value ?? null };
+  };
+  const putValue = async (putOptions) => {
+    const ns = resolveNamespace(putOptions.namespace);
+    await ns.put(putOptions.key, putOptions.value, {
+      expiration: putOptions.expiration,
+      expirationTtl: putOptions.expirationTtl,
+      metadata: putOptions.metadata
+    });
+  };
+  const deleteKey = async (deleteOptions) => {
+    const ns = resolveNamespace(deleteOptions.namespace);
+    await ns.delete(deleteOptions.key);
+  };
+  return {
+    deleteKey,
+    getValue,
+    listKeys,
+    listNamespaces,
+    putValue
+  };
+};
+const isKvNamespace = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.getWithMetadata === "function" && typeof candidate.list === "function" && typeof candidate.put === "function" && typeof candidate.delete === "function";
+};
+const createKvIntrospectorFromEnv = (env) => {
+  const namespaces = {};
+  if (typeof env === "object" && env !== null) {
+    for (const [binding, value] of Object.entries(env)) {
+      if (isKvNamespace(value)) {
+        namespaces[binding] = value;
+      }
+    }
+  }
+  return createKvIntrospector({ namespaces });
+};
+
+export { createKvIntrospector, createKvIntrospectorFromEnv };

package/dist/packem_shared/{createVectorAdminIntrospector-BJUOM6VW.mjs → createVectorAdminIntrospector-C-qTDWA1.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const MAX_TOP_K = 20;
 const DEFAULT_TOP_K = 10;
 const createVectorAdminIntrospector = (options) => {
@@ -28,11 +30,11 @@ const createVectorAdminIntrospector = (options) => {
   const queryIndex = async ({ name, text, topK }) => {
     const binding = indexes[name];
     if (binding === void 0) {
-      throw new Error(`@lunora/bindings/vectors: no Vectorize binding registered for index "${name}"`);
+      throw new LunoraError("INTERNAL", `@lunora/bindings/vectors: no Vectorize binding registered for index "${name}"`);
     }
     const embed = embedders[name];
     if (embed === void 0) {
-      throw new Error(`@lunora/bindings/vectors: no embedder registered for index "${name}" — it lists read-only`);
+      throw new LunoraError("INTERNAL", `@lunora/bindings/vectors: no embedder registered for index "${name}" — it lists read-only`);
     }
     const vector = await embed(text);
     const result = await binding.query(vector, {

package/dist/packem_shared/{createVectors-LSpGoKCd.mjs → createVectors-DqxgEPQb.mjs}

@@ -1,9 +1,13 @@
+import { LunoraError } from '@lunora/errors';
 import { c as concurrentMap, U as UPSERT_EMBED_CONCURRENCY } from './concurrent-Dj5sOibv.mjs';
 
 const resolveIndex = (indexes, name) => {
   const index = indexes[name];
   if (!index) {
-    throw new Error(`@lunora/bindings/vectors: no index registered for "${name}". Known indexes: ${Object.keys(indexes).join(", ") || "(none)"}`);
+    throw new LunoraError(
+      "INTERNAL",
+      `@lunora/bindings/vectors: no index registered for "${name}". Known indexes: ${Object.keys(indexes).join(", ") || "(none)"}`
+    );
   }
   return index;
 };
@@ -22,7 +26,7 @@ const MAX_ID_BATCH = 1e3;
 const MAX_UPSERT_BATCH = 1e3;
 const createVectors = (options) => {
   if (Object.keys(options.indexes).length === 0) {
-    throw new Error("@lunora/bindings/vectors: at least one index binding is required");
+    throw new TypeError("@lunora/bindings/vectors: at least one index binding is required");
   }
   const upsert = async (indexName, input) => {
     const index = resolveIndex(options.indexes, indexName);
@@ -52,7 +56,7 @@ const createVectors = (options) => {
       values = input.vector;
     } else {
       if (!input.embed || input.input === void 0) {
-        throw new Error("@lunora/bindings/vectors: query requires either `vector` or both `input` and `embed`");
+        throw new TypeError("@lunora/bindings/vectors: query requires either `vector` or both `input` and `embed`");
       }
       values = await input.embed(input.input);
     }
@@ -81,7 +85,7 @@ const createVectors = (options) => {
   const describe = async (indexName) => {
     const index = resolveIndex(options.indexes, indexName);
     if (!index.describe) {
-      throw new Error(`@lunora/bindings/vectors: binding for "${indexName}" does not implement describe()`);
+      throw new LunoraError("INTERNAL", `@lunora/bindings/vectors: binding for "${indexName}" does not implement describe()`);
     }
     return index.describe();
   };

package/dist/r2sql/index.d.mts

@@ -1,3 +1,4 @@
+import { LunoraError } from '@lunora/errors';
 /**
 * A composed SQL fragment. Carries the finished `text`; `toString()` returns it
 * so a fragment can be dropped straight into a template or `String(...)`.
@@ -265,8 +266,7 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
 * envelope, or an unparseable body; carries the HTTP `status` and the raw body
 * for the caller to surface.
 */
-declare class R2SqlError extends Error {
-  readonly status: number;
+declare class R2SqlError extends LunoraError {
   constructor(status: number, body: string);
 }
 /**

package/dist/r2sql/index.d.ts

@@ -1,3 +1,4 @@
+import { LunoraError } from '@lunora/errors';
 /**
 * A composed SQL fragment. Carries the finished `text`; `toString()` returns it
 * so a fragment can be dropped straight into a template or `String(...)`.
@@ -265,8 +266,7 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
 * envelope, or an unparseable body; carries the HTTP `status` and the raw body
 * for the caller to surface.
 */
-declare class R2SqlError extends Error {
-  readonly status: number;
+declare class R2SqlError extends LunoraError {
   constructor(status: number, body: string);
 }
 /**

package/dist/r2sql/index.mjs

@@ -1,5 +1,5 @@
 export { default as SelectBuilder } from '../packem_shared/SelectBuilder-DHaXZwn_.mjs';
-export { R2SqlError, createR2Sql } from '../packem_shared/R2SqlError-DlDd_SrE.mjs';
+export { R2SqlError, createR2Sql } from '../packem_shared/R2SqlError-Boygg3S0.mjs';
 export { asc, desc, renderOrderTerm } from '../packem_shared/asc-Cur-xO8v.mjs';
 export { default as SetOperation } from '../packem_shared/SetOperation-RDHcxccj.mjs';
 export { Sql, isSql, joinSql, lit, raw, sql, toText } from '../packem_shared/Sql-DceGtcUd.mjs';

package/dist/vectors/index.mjs

@@ -1,3 +1,3 @@
 export { createContextVectors, createVectorSyncHook } from '../packem_shared/createContextVectors-BSizpmu5.mjs';
-export { createVectorAdminIntrospector } from '../packem_shared/createVectorAdminIntrospector-BJUOM6VW.mjs';
-export { default as createVectors } from '../packem_shared/createVectors-LSpGoKCd.mjs';
+export { createVectorAdminIntrospector } from '../packem_shared/createVectorAdminIntrospector-C-qTDWA1.mjs';
+export { default as createVectors } from '../packem_shared/createVectors-DqxgEPQb.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/bindings",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "Lightweight Cloudflare binding helpers for Lunora — ctx.kv, ctx.images, ctx.analytics, ctx.pipelines, ctx.vectors, ctx.r2sql — one install, per-binding subpaths",
   "keywords": [
     "analytics",
@@ -63,6 +63,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@lunora/errors": "1.0.0-alpha.1"
+  },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"
   }