@lunora/client 1.0.0-alpha.16 → 1.0.0-alpha.17

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-CPMaTnsC.mjs";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/auth/index.d.ts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-CPMaTnsC.js";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-CPMaTnsC.mjs";
-export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-CPMaTnsC.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-Bl3z1rPo.mjs";
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-Bpi7xweC.mjs";
 export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-CPMaTnsC.js";
-export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-CPMaTnsC.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-DH0CqSxy.js";
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DPLSlPiP.js";
+export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-DPLSlPiP.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-CmFdZFQi.js";
 export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —

package/dist/index.mjs

@@ -3,13 +3,13 @@ export { default as createInMemoryBookmarkStorage } from './packem_shared/create
 export { applyDelta, isMutationDelta } from './packem_shared/applyDelta-4jFGTPA3.mjs';
 export { CONFLICT_ERROR_CODE, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from './packem_shared/CONFLICT_ERROR_CODE-B8gQ8tyU.mjs';
 export { c as createLocalStore } from './packem_shared/local-store-BNgN3Dw3.mjs';
-export { LunoraClient } from './packem_shared/LunoraClient-Zb_AVP5H.mjs';
+export { LunoraClient } from './packem_shared/LunoraClient-jOfAmV8f.mjs';
 export { createMutationRunner } from './packem_shared/createMutationRunner-BqsavzvG.mjs';
 export { createMutatorRunner } from './packem_shared/createMutatorRunner-BETvCd0p.mjs';
 export { O as OfflineQueue } from './packem_shared/offline-queue-B9vfdSqp.mjs';
-export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-CY6F0ZvQ.mjs';
+export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-Ds7z8n8d.mjs';
 export { preloadQuery, preloadedQueryResult } from './packem_shared/preloadQuery-lobFkD2Z.mjs';
-export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-Bv4Ruv6n.mjs';
+export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-iWtKPrid.mjs';
 export { createReconnect } from './packem_shared/createReconnect-Di_-oHH7.mjs';
 export { DEFAULT_MAX_BUFFER, createStream } from './packem_shared/DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
 export { S as SubscriptionRegistry } from './packem_shared/subscription-DoyO04-2.mjs';

package/dist/packem_shared/{LunoraClient-Zb_AVP5H.mjs → LunoraClient-jOfAmV8f.mjs}

@@ -1,10 +1,11 @@
+import { LunoraError } from '@lunora/errors';
 import { S as SubscriptionRegistry, s as stableStringify } from './subscription-DoyO04-2.mjs';
 import createInMemoryBookmarkStorage from './createInMemoryBookmarkStorage-BoN7a7TH.mjs';
 import { isMutationDelta, applyDelta } from './applyDelta-4jFGTPA3.mjs';
 import { a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, f as foldOptimistic, c as createLocalStore } from './local-store-BNgN3Dw3.mjs';
 import { O as OfflineQueue, n as nextId, i as isStaleVersion, r as reportPersistenceError } from './offline-queue-B9vfdSqp.mjs';
-import { resolvePersistenceAdapter } from './createInMemoryPersistence-CY6F0ZvQ.mjs';
-import { resolveQueryCacheAdapter, queryCacheKey } from './createInMemoryQueryCache-Bv4Ruv6n.mjs';
+import { resolvePersistenceAdapter } from './createInMemoryPersistence-Ds7z8n8d.mjs';
+import { resolveQueryCacheAdapter, queryCacheKey } from './createInMemoryQueryCache-iWtKPrid.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
 import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
 
@@ -406,6 +407,12 @@ const reconstructError = (errorBody) => {
   if (errorBody.data !== void 0) {
     error.data = decodeWire(errorBody.data);
   }
+  if (errorBody.hint !== void 0) {
+    error.hint = errorBody.hint;
+  }
+  if (errorBody.docsUrl !== void 0) {
+    error.docsUrl = errorBody.docsUrl;
+  }
   return error;
 };
 const encodeCallArgs = (payload, label) => {
@@ -692,7 +699,7 @@ class LunoraClient {
   async callMutator(functionPath, args, options) {
     const clientSeq = options?.clientSeq;
     if (clientSeq !== void 0 && (!Number.isInteger(clientSeq) || clientSeq <= 0)) {
-      throw new Error(`callMutator: clientSeq must be a positive integer, got ${String(clientSeq)}`);
+      throw new LunoraError("INTERNAL", `callMutator: clientSeq must be a positive integer, got ${String(clientSeq)}`);
     }
     const bucket = options?.shardKey ?? "";
     let ackWatermark;
@@ -976,7 +983,7 @@ class LunoraClient {
   // --- RPC ---------------------------------------------------------------
   async query(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.rpc(function_.__lunoraRef, args, options.shardKey, { attachBookmark: true });
   }
@@ -996,10 +1003,10 @@ class LunoraClient {
    */
   async batch(calls) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     if (!this.fetchImpl) {
-      throw new Error("LunoraClient: no `fetch` implementation available");
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
     }
     if (calls.length === 0) {
       return [];
@@ -1026,13 +1033,13 @@ class LunoraClient {
     try {
       body = await response.json();
     } catch {
-      throw new Error(`LunoraClient: batch response was not JSON (status ${response.status.toString()})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: batch response was not JSON (status ${response.status.toString()})`);
     }
     if (!response.ok || body.error && !body.results) {
       if (body.error) {
         throw reconstructError(body.error);
       }
-      throw new Error(`LunoraClient: batch request failed (status ${response.status.toString()})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: batch request failed (status ${response.status.toString()})`);
     }
     return demuxBatchResults(body.results ?? [], calls.length);
   }
@@ -1048,7 +1055,7 @@ class LunoraClient {
    */
   async mutation(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const argsRecord = args;
     const mutationId = options.mutationId ?? nextId();
@@ -1092,7 +1099,7 @@ class LunoraClient {
   }
   async action(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.rpc(function_.__lunoraRef, args, options.shardKey);
   }
@@ -1109,7 +1116,7 @@ class LunoraClient {
    */
   async shardTraffic(table) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SHARD_TRAFFIC_PATH, "POST", { table });
     return { failed: body.failed ?? 0, ok: body.ok ?? 0, shards: body.shards ?? [] };
@@ -1124,7 +1131,7 @@ class LunoraClient {
    */
   async listScheduledJobs() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_PATH, "GET");
     return body.records ?? [];
@@ -1140,7 +1147,7 @@ class LunoraClient {
    */
   async schedulerStatus() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_STATUS_PATH, "GET");
     return {
@@ -1152,7 +1159,7 @@ class LunoraClient {
   /** Cancel a pending scheduled job by id. Returns whether a job was removed. */
   async cancelScheduledJob(id) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_CANCEL_PATH, "POST", { id });
     return { cancelled: body.cancelled === true };
@@ -1167,7 +1174,7 @@ class LunoraClient {
    */
   async listDeadJobs() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_DEAD_PATH, "GET");
     return body.records ?? [];
@@ -1179,7 +1186,7 @@ class LunoraClient {
    */
   async retryDeadJob(id) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_DEAD_RETRY_PATH, "POST", { id });
     return { retried: body.retried === true };
@@ -1191,7 +1198,7 @@ class LunoraClient {
    */
   async removeDeadJob(id) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_DEAD_CANCEL_PATH, "POST", { id });
     return { removed: body.removed === true };
@@ -1209,7 +1216,7 @@ class LunoraClient {
    */
   async listWorkflowInstances(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const query = new URLSearchParams({ name: options.name });
     if (options.status !== void 0) {
@@ -1233,7 +1240,7 @@ class LunoraClient {
   /** Read one workflow instance with its step timeline (`/_lunora/admin/workflows/instance`). */
   async getWorkflowInstance(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const query = new URLSearchParams({ id: options.id, name: options.name });
     const body = await this.adminFetch(`${WORKFLOWS_INSTANCE_PATH}?${query.toString()}`, "GET");
@@ -1252,7 +1259,7 @@ class LunoraClient {
   /** Pause / resume / terminate a workflow instance (`/_lunora/admin/workflows/status`). Needs an Edit-scoped Cloudflare token. */
   async setWorkflowInstanceStatus(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(WORKFLOWS_STATUS_PATH, "POST", { action: options.action, id: options.id, name: options.name });
     return { status: body.status ?? "unknown" };
@@ -1267,7 +1274,7 @@ class LunoraClient {
    */
   subscribeScheduledJobs(onJobs) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     if (this.WebSocketImpl === void 0) {
       return () => void 0;
@@ -1323,7 +1330,7 @@ class LunoraClient {
    */
   async listFunctions() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(FUNCTIONS_PATH, "GET");
     return body.functions ?? [];
@@ -1339,7 +1346,7 @@ class LunoraClient {
    */
   async getCronJobs() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(CRON_JOBS_PATH, "GET");
     return body.jobs ?? [];
@@ -1355,7 +1362,7 @@ class LunoraClient {
    */
   async runCronJob(name) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(CRON_JOBS_RUN_PATH, "POST", { name });
     return { name: body.name ?? name, ran: body.ran === true };
@@ -1370,7 +1377,7 @@ class LunoraClient {
    */
   async fetchOpenApi() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.adminFetch(OPENAPI_PATH, "GET");
   }
@@ -1386,7 +1393,7 @@ class LunoraClient {
    */
   async fetchOpenRpc() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.adminFetch(OPENRPC_PATH, "GET");
   }
@@ -1400,7 +1407,7 @@ class LunoraClient {
    */
   async listStorageObjects(options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams();
     if (options.prefix !== void 0 && options.prefix !== "") {
@@ -1428,7 +1435,7 @@ class LunoraClient {
    */
   async deleteStorageObject(key, options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = `${STORAGE_PATH}?key=${encodeURIComponent(key)}${bucketQuery(options?.bucket)}`;
     const body = await this.adminFetch(path, "DELETE");
@@ -1442,7 +1449,7 @@ class LunoraClient {
    */
   async listStorageBuckets() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(STORAGE_BUCKETS_PATH, "GET");
     return body.buckets ?? [];
@@ -1456,7 +1463,7 @@ class LunoraClient {
    */
   async uploadStorageObject(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = `${STORAGE_PATH}?key=${encodeURIComponent(options.key)}${bucketQuery(options.bucket)}`;
     const body = await this.adminFetch(path, "PUT", options.body, options.contentType);
@@ -1475,7 +1482,7 @@ class LunoraClient {
    */
   async signedStorageUrl(key, options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const expiresInSeconds = options?.expiresInSeconds;
     const expiryQuery = expiresInSeconds === void 0 ? "" : `&expiresIn=${encodeURIComponent(expiresInSeconds.toString())}`;
@@ -1495,7 +1502,7 @@ class LunoraClient {
    */
   async listGlobalTables() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.adminFetch(GLOBAL_TABLES_PATH, "GET");
   }
@@ -1507,7 +1514,7 @@ class LunoraClient {
    */
   async readGlobalTablePage(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams({ table: options.table });
     if (options.limit !== void 0) {
@@ -1530,7 +1537,7 @@ class LunoraClient {
    */
   async facetGlobalColumn(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams({ column: options.column, table: options.table });
     if (options.limit !== void 0) {
@@ -1553,7 +1560,7 @@ class LunoraClient {
    */
   async listVectorIndexes() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(VECTOR_INDEXES_PATH, "GET");
     return body.indexes ?? [];
@@ -1567,7 +1574,7 @@ class LunoraClient {
    */
   async queryVectorIndex(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(VECTOR_QUERY_PATH, "POST", options);
     return body.matches ?? [];
@@ -1581,7 +1588,7 @@ class LunoraClient {
    */
   async listKvNamespaces() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(KV_NAMESPACES_PATH, "GET");
     return body.namespaces ?? [];
@@ -1593,7 +1600,7 @@ class LunoraClient {
    */
   async listKvKeys(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = withQuery(KV_KEYS_PATH, {
       cursor: options.cursor,
@@ -1610,7 +1617,7 @@ class LunoraClient {
    */
   async getKvValue(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = withQuery(KV_VALUE_PATH, { key: options.key, namespace: options.namespace });
     return await this.adminFetch(path, "GET");
@@ -1623,7 +1630,7 @@ class LunoraClient {
    */
   async putKvValue(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     await this.adminFetch(KV_VALUE_PATH, "PUT", options);
   }
@@ -1633,7 +1640,7 @@ class LunoraClient {
    */
   async deleteKvKey(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = withQuery(KV_VALUE_PATH, { key: options.key, namespace: options.namespace });
     await this.adminFetch(path, "DELETE");
@@ -1647,7 +1654,7 @@ class LunoraClient {
    */
   async listAuthUsers(options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = withQuery(AUTH_USERS_PATH, {
       filterField: options.filterField,
@@ -1762,7 +1769,7 @@ class LunoraClient {
   /** List auth sessions, paged and optionally filtered to one user. */
   async listAuthSessions(options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams();
     if (options.userId !== void 0 && options.userId !== "") {
@@ -1780,7 +1787,7 @@ class LunoraClient {
   // --- Subscriptions ------------------------------------------------------
   subscribe(function_, args, callback, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const argsRecord = args ?? {};
     const key = SubscriptionRegistry.key(function_.__lunoraRef, argsRecord, options.shardKey);
@@ -1858,7 +1865,7 @@ class LunoraClient {
    */
   subscribeShape(shape, callback, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     this.nextShapeId += 1;
     const id = `shape_${this.nextShapeId.toString()}`;
@@ -1904,10 +1911,10 @@ class LunoraClient {
    */
   stream(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     if (this.WebSocketImpl === void 0) {
-      throw new Error("LunoraClient: streams require a WebSocket implementation");
+      throw new LunoraError("INTERNAL", "LunoraClient: streams require a WebSocket implementation");
     }
     this.nextStreamId += 1;
     const id = `stream_${this.nextStreamId.toString()}`;
@@ -2357,7 +2364,7 @@ class LunoraClient {
   }
   async rpc(functionPath, args, shardKey, flags = {}) {
     if (!this.fetchImpl) {
-      throw new Error("LunoraClient: no `fetch` implementation available");
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
     }
     const headers = this.rpcRequestHeaders(flags);
     const response = await this.fetchImpl(joinUrl(this.url, RPC_PATH), {
@@ -2379,14 +2386,14 @@ class LunoraClient {
       body = await response.json();
     } catch {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
     }
     if ("error" in body) {
       throw reconstructError(body.error);
     }
     if (!response.ok) {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
     }
     flags.onMutationAck?.(body.lastMutationId);
     flags.onCommitCursor?.(body.commitCursor);
@@ -2400,7 +2407,7 @@ class LunoraClient {
    */
   async adminFetch(path, method, payload, contentType) {
     if (!this.fetchImpl) {
-      throw new Error("LunoraClient: no `fetch` implementation available");
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
     }
     const headers = {};
     if (this.authToken) {
@@ -2429,7 +2436,7 @@ class LunoraClient {
       body = await response.json();
     } catch {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
     }
     if (typeof body === "object" && body !== null && "error" in body) {
       const envelope = body.error;
@@ -2439,7 +2446,7 @@ class LunoraClient {
     }
     if (!response.ok) {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: admin request failed (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: admin request failed (status ${response.status.toString()}${statusText})`);
     }
     return body;
   }

package/dist/packem_shared/{createInMemoryPersistence-CY6F0ZvQ.mjs → createInMemoryPersistence-Ds7z8n8d.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const createInMemoryPersistence = () => {
   const entries = /* @__PURE__ */ new Map();
   const clone = (mutation) => {
@@ -39,7 +41,7 @@ const promisifyRequest = (request) => new Promise((resolve, reject) => {
 const createIndexedDbPersistence = (options = {}) => {
   const factory = options.indexedDB ?? (typeof indexedDB === "undefined" ? void 0 : indexedDB);
   if (!factory) {
-    throw new Error("createIndexedDbPersistence: no IndexedDB available — pass `indexedDB` or use createInMemoryPersistence()");
+    throw new LunoraError("INTERNAL", "createIndexedDbPersistence: no IndexedDB available — pass `indexedDB` or use createInMemoryPersistence()");
   }
   const databaseName = options.databaseName ?? DEFAULT_DATABASE;
   const storeName = options.storeName ?? DEFAULT_STORE;

package/dist/packem_shared/{createInMemoryQueryCache-Bv4Ruv6n.mjs → createInMemoryQueryCache-iWtKPrid.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const queryCacheKey = (functionPath, argsKey, shardKey) => `${functionPath}::${argsKey}::${shardKey ?? ""}`;
 const DEFAULT_MAX_ENTRIES = 500;
 const createInMemoryQueryCache = (options = {}) => {
@@ -50,7 +52,7 @@ const promisifyRequest = (request) => new Promise((resolve, reject) => {
 const createIndexedDbQueryCache = (options = {}) => {
   const factory = options.indexedDB ?? (typeof indexedDB === "undefined" ? void 0 : indexedDB);
   if (!factory) {
-    throw new Error("createIndexedDbQueryCache: no IndexedDB available — pass `indexedDB` or use createInMemoryQueryCache()");
+    throw new LunoraError("INTERNAL", "createIndexedDbQueryCache: no IndexedDB available — pass `indexedDB` or use createInMemoryQueryCache()");
   }
   const databaseName = options.databaseName ?? DEFAULT_DATABASE;
   const storeName = options.storeName ?? DEFAULT_STORE;

package/dist/packem_shared/{createServerClient-CFrM8ZQO.mjs → createServerClient-Blht8tLm.mjs}

@@ -1,4 +1,4 @@
-import { LunoraClient } from './LunoraClient-Zb_AVP5H.mjs';
+import { LunoraClient } from './LunoraClient-jOfAmV8f.mjs';
 
 const createServerClient = (options) => {
   const client = new LunoraClient({ fetch: options.fetch, url: options.url });

package/dist/packem_shared/{lunora-client.d-CPMaTnsC.d.mts → lunora-client.d-DPLSlPiP.d.mts}

@@ -1207,10 +1207,20 @@ interface SyncWatermark {
   checkpoint?: number;
   mutationId?: number;
 }
-/** An `Error` carrying the server's machine-readable `code` and (for a `LunoraError`) structured `data`. The client's public error contract for RPC/batch failures. The `(string & {})` arm keeps forward-compat/unknown server codes assignable without losing autocomplete on the known {@link LunoraErrorCode} union. */
+/**
+* An `Error` carrying the server's machine-readable `code` and (for a
+* `LunoraError`) structured `data`, plus an optional actionable `hint` (Markdown)
+* and `docsUrl` resolved from the central error catalog. The client's public
+* error contract for RPC/batch failures — a UI can render `hint`/`docsUrl` to
+* tell the user how to fix the error. The `(string & {})` arm keeps
+* forward-compat/unknown server codes assignable without losing autocomplete on
+* the known {@link LunoraErrorCode} union.
+*/
 type LunoraClientError = Error & {
   code?: LunoraErrorCode | (string & {});
   data?: unknown;
+  docsUrl?: string;
+  hint?: string | string[];
 };
 /** One demuxed result slot of a {@link LunoraClient.batch} call (plan 088). */
 type BatchSlot = {

package/dist/packem_shared/{lunora-client.d-CPMaTnsC.d.ts → lunora-client.d-DPLSlPiP.d.ts}

@@ -1207,10 +1207,20 @@ interface SyncWatermark {
   checkpoint?: number;
   mutationId?: number;
 }
-/** An `Error` carrying the server's machine-readable `code` and (for a `LunoraError`) structured `data`. The client's public error contract for RPC/batch failures. The `(string & {})` arm keeps forward-compat/unknown server codes assignable without losing autocomplete on the known {@link LunoraErrorCode} union. */
+/**
+* An `Error` carrying the server's machine-readable `code` and (for a
+* `LunoraError`) structured `data`, plus an optional actionable `hint` (Markdown)
+* and `docsUrl` resolved from the central error catalog. The client's public
+* error contract for RPC/batch failures — a UI can render `hint`/`docsUrl` to
+* tell the user how to fix the error. The `(string & {})` arm keeps
+* forward-compat/unknown server codes assignable without losing autocomplete on
+* the known {@link LunoraErrorCode} union.
+*/
 type LunoraClientError = Error & {
   code?: LunoraErrorCode | (string & {});
   data?: unknown;
+  docsUrl?: string;
+  hint?: string | string[];
 };
 /** One demuxed result slot of a {@link LunoraClient.batch} call (plan 088). */
 type BatchSlot = {

package/dist/packem_shared/{preload.d-Bl3z1rPo.d.mts → preload.d-Bpi7xweC.d.mts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CPMaTnsC.mjs";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-DPLSlPiP.mjs";
 /**
 * Run a query once on the server (during SSR) and capture its result in a
 * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/packem_shared/{preload.d-DH0CqSxy.d.ts → preload.d-CmFdZFQi.d.ts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CPMaTnsC.js";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-DPLSlPiP.js";
 /**
 * Run a query once on the server (during SSR) and capture its result in a
 * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/query/index.d.mts

@@ -1,5 +1,5 @@
-import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CPMaTnsC.mjs";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CPMaTnsC.mjs";
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
 import '@lunora/runtime';
 /**
 * The sentinel a framework adapter resolves its reactive args to when it wants

package/dist/query/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CPMaTnsC.js";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CPMaTnsC.js";
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
 import '@lunora/runtime';
 /**
 * The sentinel a framework adapter resolves its reactive args to when it wants

package/dist/ssr/index.d.mts

@@ -1,6 +1,6 @@
-import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CPMaTnsC.mjs";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CPMaTnsC.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-Bl3z1rPo.mjs";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-Bpi7xweC.mjs";
 import '@lunora/runtime';
 /**
 * Structural shape of a better-auth `getSession` call's resolved value.

package/dist/ssr/index.d.ts

@@ -1,6 +1,6 @@
-import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CPMaTnsC.js";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CPMaTnsC.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-DH0CqSxy.js";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-CmFdZFQi.js";
 import '@lunora/runtime';
 /**
 * Structural shape of a better-auth `getSession` call's resolved value.

package/dist/ssr/index.mjs

@@ -1,4 +1,4 @@
 export { getServerSession } from '../packem_shared/getServerSession-8jXewqxd.mjs';
 export { deserializePreloaded, serializePreloaded } from '../packem_shared/deserializePreloaded-C0eJTY_W.mjs';
-export { createServerClient } from '../packem_shared/createServerClient-CFrM8ZQO.mjs';
+export { createServerClient } from '../packem_shared/createServerClient-Blht8tLm.mjs';
 export { preloadQuery, preloadedQueryResult } from '../packem_shared/preloadQuery-lobFkD2Z.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/client",
-  "version": "1.0.0-alpha.16",
+  "version": "1.0.0-alpha.17",
   "description": "Lunora browser SDK: WebSocket transport, optimistic updates, and an offline mutation queue",
   "keywords": [
     "cloudflare",
@@ -61,6 +61,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@lunora/errors": "1.0.0-alpha.1"
+  },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"
   }