deepspace 0.6.0 → 0.6.1

package/dist/index.d.ts

@@ -2778,6 +2778,21 @@ interface RecordContextValue {
     }, timeoutMs?: number) => Promise<unknown>;
 }
 declare function useRecordContext(): RecordContextValue;
+/**
+ * A server-rejected write, delivered to `RecordProvider`'s `onWriteError`.
+ * One structured object rather than positional strings so future rejection
+ * kinds (rate-limit, quota, dropped-while-offline) and correlation fields
+ * (collection, recordId, the raw server string) can be added without
+ * breaking the callback signature.
+ */
+interface WriteError {
+    /** 'permission' — an RBAC denial; 'validation' — missing/immutable/invalid field or any other rejection. */
+    kind: 'permission' | 'validation';
+    /** Short human-readable summary, safe to show end users. */
+    title: string;
+    /** Longer human-readable explanation; may be empty. */
+    detail: string;
+}
 /**
  * RecordProvider - Main entry point for storage.
  *
@@ -2803,7 +2818,7 @@ declare function useRecordContext(): RecordContextValue;
  * </RecordProvider>
  * ```
  */
-declare function RecordProvider({ roomId, wsUrl, children, allowAnonymous, getAuthToken: getAuthTokenProp, }: {
+declare function RecordProvider({ roomId, schemas, wsUrl, children, allowAnonymous, getAuthToken: getAuthTokenProp, onWriteError, }: {
     roomId?: string;
     /**
      * Accepted for API compatibility with `RecordScope` and documented usage,
@@ -2815,6 +2830,14 @@ declare function RecordProvider({ roomId, wsUrl, children, allowAnonymous, getAu
     children: ReactNode;
     allowAnonymous?: boolean;
     getAuthToken?: () => Promise<string | null>;
+    /**
+     * Called when the server rejects a write. Optimistic mutations
+     * (`create`/`put`/`remove`) resolve before the server answers, so this
+     * callback is the only place a denied or invalid write surfaces — wire it
+     * to your toast/alert system and branch on `error.kind`. Defaults to a
+     * deduped console.error so rejections are never fully silent.
+     */
+    onWriteError?: (error: WriteError) => void;
 }): React__default.ReactElement;
 
 interface SharedScopeConfig {
@@ -3315,7 +3338,7 @@ declare function useCronMonitor(roomId: string): UseCronMonitorResult;
  * apps importing from both ends don't get type collisions.
  *
  * @example
- * const { jobs, enqueue, getJob, cancel } = useJobs(`app:${APP_NAME}`)
+ * const { jobs, enqueue, getJob, cancel } = useJobs(SCOPE_ID) // `app:${APP_ID}`
  *
  * async function onClick() {
  *   const jobId = await enqueue('ai-summarize', { text })
@@ -4616,4 +4639,4 @@ interface UseCheckoutReturn {
 }
 declare function useCheckout(opts?: UseCheckoutOpts): UseCheckoutReturn;
 
-export { ASYNC_RESOURCE_DEFAULTS, type AdHocChargeOpts, type AiStreamAction, type AiStreamChunk, type AsyncResourceDefaults, type AsyncResourceState, type AsyncResourceStatus, AuthGate, type AuthGateProps, AuthOverlay, Awareness, type AwarenessState, type AwarenessStates, type BaseMessage, type CanvasShapeClient, type Channel, type ChannelInvitation, type ChannelMember, type ChargeOnceOpts, type ChargeOnceResult, type ClientMessage, type CollectionSchema, type ConnectionAttachment, type ConnectionStatus, type ContentSegment, type ConversationObject, type CronHistoryEntry, type CronTaskState, DEEPSPACE_THEME_PROPERTIES, DEFAULT_USER_COLORS, DeepSpaceAuthProvider, type DeepSpaceThemeConfig, DeepSpaceThemeProvider, type DeepSpaceThemeProviderProps, type DeriveLoadStateInput, ENV, type Environment, type FetchUserProfile, type FileAttachment, type GamePlayer, type GroupedReaction, GuestBanner, type HandlerContext, type InboxEntry, type IntegrationResponse, type JobStatusView, type JobView, type LinkPreviewData, type LoadState, type LoadStateAuthInput, type LoadStateStatusInput, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MemberRecord, type Message, type MessageHandlers, type MessageRecord, type MsgType, type PagedResourceFetchArgs, type PagedResourcePage, type PagedResourceState, type PagedResourceStatus, type PlanInfo, PlatformContext, type PlatformContextValue, PlatformProvider, type PlatformWSOptions, type PlatformWSResult, type PresencePeerClient, PricingTable, type PricingTablePlan, type PricingTablePrice, type ProductChargeOpts, type ProtocolMessage, type Purchase, type Query, type R2FileInfo, type R2Scope, type R2UploadResult, ROLES, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_CONFIG, ROLE_DEFAULT, type Reaction, type ReactionRecord, type ReadCursorRecord, type ReadReceipt, type RecordData, RecordProvider, type RecordProviderProps, RecordScope, type RequestOptions, type Role, type RoomUser, type ScopeEntry, ScopeRegistryProvider, type ServerMessage, SignedIn, SignedOut, type SubscribeOpts, type SubscribeResult, type SubscriptionState, type SubscriptionStatus, type SyncResult, type UseAsyncResourceOptions, type UseAuthProfileReadyOptions, type UseAuthReadyOptions, type UseAuthStatusOptions, type UseCanvasResult, type UseCheckoutOpts, type UseCronMonitorResult, type UseGameRoomResult, type UseJobsResult, type UsePagedResourceOptions, type UsePresenceRoomResult, type UseR2FilesReturn, type UseVoiceAgentOptions, type UseVoiceAgentResult, type UseYjsFieldResult, type UseYjsRoomResult, type UseYjsTextResult, type User, type UserCredits, type UserInfo, type UserKarma, type UserProfile, type ViewportClient, type VoiceStatus, type VoiceTranscriptEntry, applyDeepSpaceTheme, applyUIThemeTokens, authClient, canAutoLoadPagedResource, clampPagedResourceItems, clearAuthToken, clearDeepSpaceTheme, clientBuild, createDecoder, createEncoder, decodeAiStreamChunk, deriveLoadState, detectEnvironment, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, formatFileSize, formatFullTimestamp, formatMessageTime, getApiUrl, getAuthToken, getAuthUrl, getConversationDisplayName, getConversationParticipantIds, getEnvironmentConfig, getMessageType, getPagedResourceCooldownMs, getPlatformWorkerUrl, getThreadCounts, getUserColor, groupReactionsForMessage, handleAwarenessMessage, handleSyncMessage, hasContent, integration, isAsyncResourceSlow, isDMConversation, isDarkColor, isImageFile, isLocalDev, isProduction, parseMessageMetadata, parseSseLine, readThemeFromDOM, readVarUint, readVarUint8Array, resetEnvironmentCache, serverBuild, shouldGroupMessages, signIn, signOut, toConnectionStatus, toUint8Array, useAsyncResource, useAuth, useAuthProfileReady, useAuthReady, useAuthStatus, useAuthUser, useCanvas, useChannelMembers, useChannels, useCheckout, useCommunities, useConversation, useConversations, useCronMonitor, useDisplayName, useGameRoom, useInbox, useIsDarkTheme, useJobs, useMessages, useMutations, usePagedResource, usePlatform, usePlatformWS, usePosts, usePresence, usePresenceRoom, useQuery, useR2Files, useReactions, useReadReceipts, useRecordContext, useSession, useSubscription, useUser, useUserLookup, useUsers, useVoiceAgent, useYjsField, useYjsRoom, useYjsText, writeVarUint, writeVarUint8Array };
+export { ASYNC_RESOURCE_DEFAULTS, type AdHocChargeOpts, type AiStreamAction, type AiStreamChunk, type AsyncResourceDefaults, type AsyncResourceState, type AsyncResourceStatus, AuthGate, type AuthGateProps, AuthOverlay, Awareness, type AwarenessState, type AwarenessStates, type BaseMessage, type CanvasShapeClient, type Channel, type ChannelInvitation, type ChannelMember, type ChargeOnceOpts, type ChargeOnceResult, type ClientMessage, type CollectionSchema, type ConnectionAttachment, type ConnectionStatus, type ContentSegment, type ConversationObject, type CronHistoryEntry, type CronTaskState, DEEPSPACE_THEME_PROPERTIES, DEFAULT_USER_COLORS, DeepSpaceAuthProvider, type DeepSpaceThemeConfig, DeepSpaceThemeProvider, type DeepSpaceThemeProviderProps, type DeriveLoadStateInput, ENV, type Environment, type FetchUserProfile, type FileAttachment, type GamePlayer, type GroupedReaction, GuestBanner, type HandlerContext, type InboxEntry, type IntegrationResponse, type JobStatusView, type JobView, type LinkPreviewData, type LoadState, type LoadStateAuthInput, type LoadStateStatusInput, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MemberRecord, type Message, type MessageHandlers, type MessageRecord, type MsgType, type PagedResourceFetchArgs, type PagedResourcePage, type PagedResourceState, type PagedResourceStatus, type PlanInfo, PlatformContext, type PlatformContextValue, PlatformProvider, type PlatformWSOptions, type PlatformWSResult, type PresencePeerClient, PricingTable, type PricingTablePlan, type PricingTablePrice, type ProductChargeOpts, type ProtocolMessage, type Purchase, type Query, type R2FileInfo, type R2Scope, type R2UploadResult, ROLES, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_CONFIG, ROLE_DEFAULT, type Reaction, type ReactionRecord, type ReadCursorRecord, type ReadReceipt, type RecordData, RecordProvider, type RecordProviderProps, RecordScope, type RequestOptions, type Role, type RoomUser, type ScopeEntry, ScopeRegistryProvider, type ServerMessage, SignedIn, SignedOut, type SubscribeOpts, type SubscribeResult, type SubscriptionState, type SubscriptionStatus, type SyncResult, type UseAsyncResourceOptions, type UseAuthProfileReadyOptions, type UseAuthReadyOptions, type UseAuthStatusOptions, type UseCanvasResult, type UseCheckoutOpts, type UseCronMonitorResult, type UseGameRoomResult, type UseJobsResult, type UsePagedResourceOptions, type UsePresenceRoomResult, type UseR2FilesReturn, type UseVoiceAgentOptions, type UseVoiceAgentResult, type UseYjsFieldResult, type UseYjsRoomResult, type UseYjsTextResult, type User, type UserCredits, type UserInfo, type UserKarma, type UserProfile, type ViewportClient, type VoiceStatus, type VoiceTranscriptEntry, type WriteError, applyDeepSpaceTheme, applyUIThemeTokens, authClient, canAutoLoadPagedResource, clampPagedResourceItems, clearAuthToken, clearDeepSpaceTheme, clientBuild, createDecoder, createEncoder, decodeAiStreamChunk, deriveLoadState, detectEnvironment, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, formatFileSize, formatFullTimestamp, formatMessageTime, getApiUrl, getAuthToken, getAuthUrl, getConversationDisplayName, getConversationParticipantIds, getEnvironmentConfig, getMessageType, getPagedResourceCooldownMs, getPlatformWorkerUrl, getThreadCounts, getUserColor, groupReactionsForMessage, handleAwarenessMessage, handleSyncMessage, hasContent, integration, isAsyncResourceSlow, isDMConversation, isDarkColor, isImageFile, isLocalDev, isProduction, parseMessageMetadata, parseSseLine, readThemeFromDOM, readVarUint, readVarUint8Array, resetEnvironmentCache, serverBuild, shouldGroupMessages, signIn, signOut, toConnectionStatus, toUint8Array, useAsyncResource, useAuth, useAuthProfileReady, useAuthReady, useAuthStatus, useAuthUser, useCanvas, useChannelMembers, useChannels, useCheckout, useCommunities, useConversation, useConversations, useCronMonitor, useDisplayName, useGameRoom, useInbox, useIsDarkTheme, useJobs, useMessages, useMutations, usePagedResource, usePlatform, usePlatformWS, usePosts, usePresence, usePresenceRoom, useQuery, useR2Files, useReactions, useReadReceipts, useRecordContext, useSession, useSubscription, useUser, useUserLookup, useUsers, useVoiceAgent, useYjsField, useYjsRoom, useYjsText, writeVarUint, writeVarUint8Array };

package/dist/index.js

@@ -712,6 +712,20 @@ var DEBUG = readDebugFlag();
 function debugLog(...args) {
   if (DEBUG) console.log(...args);
 }
+function isLocalDevHost() {
+  try {
+    const g = globalThis;
+    if (g.DEEPSPACE_DEV === true || g.DEEPSPACE_DEV === "1" || g.DEEPSPACE_DEV === "true" || g.DEEPSPACE_DEV === 1)
+      return true;
+    if (g.DEEPSPACE_DEV === false || g.DEEPSPACE_DEV === "0" || g.DEEPSPACE_DEV === "false" || g.DEEPSPACE_DEV === 0)
+      return false;
+    const host = g.location?.hostname;
+    if (!host) return false;
+    return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost");
+  } catch {
+    return false;
+  }
+}
 
 // src/client/auth/DeepSpaceAuthProvider.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -1712,7 +1726,7 @@ function ScopeRegistryProvider({ children }) {
 }
 
 // src/client/storage/context.tsx
-import { Fragment as Fragment5, jsx as jsx6 } from "react/jsx-runtime";
+import { Fragment as Fragment5, jsx as jsx6, jsxs as jsxs4 } from "react/jsx-runtime";
 var RecordContext = createContext2(null);
 function useRecordContext() {
   const ctx = useContext2(RecordContext);
@@ -1731,7 +1745,9 @@ function RecordProviderCore({
   children,
   fetchUser,
   allowAnonymous = false,
-  getAuthToken: getAuthTokenProp
+  getAuthToken: getAuthTokenProp,
+  onPermissionError: onPermissionErrorProp,
+  onValidationError: onValidationErrorProp
 }) {
   const [userProfile, setUserProfile] = useState3(null);
   const [userProfileLoading, setUserProfileLoading] = useState3(true);
@@ -1746,6 +1762,8 @@ function RecordProviderCore({
   const onValidationErrorRef = useRef4(
     void 0
   );
+  onPermissionErrorRef.current = onPermissionErrorProp;
+  onValidationErrorRef.current = onValidationErrorProp;
   const storeRef = useRef4(new RecordStore());
   const socketRef = useRef4(null);
   const subscriptionsRef = useRef4(/* @__PURE__ */ new Map());
@@ -1954,10 +1972,22 @@ function RecordProviderAuthOnly({
   children,
   fetchUser,
   allowAnonymous = false,
-  getAuthToken: getAuthTokenProp
+  getAuthToken: getAuthTokenProp,
+  onPermissionError: onPermissionErrorProp,
+  onValidationError: onValidationErrorProp
 }) {
   const [userProfile, setUserProfile] = useState3(null);
   const [userProfileLoading, setUserProfileLoading] = useState3(true);
+  const onPermissionErrorRef = useRef4(onPermissionErrorProp);
+  onPermissionErrorRef.current = onPermissionErrorProp;
+  const onValidationErrorRef = useRef4(onValidationErrorProp);
+  onValidationErrorRef.current = onValidationErrorProp;
+  const onPermissionError = useCallback2((title, detail) => {
+    onPermissionErrorRef.current?.(title, detail);
+  }, []);
+  const onValidationError = useCallback2((title, detail) => {
+    onValidationErrorRef.current?.(title, detail);
+  }, []);
   const refetchUserProfile = useCallback2(async () => {
     try {
       const profile = await fetchUser();
@@ -1993,20 +2023,86 @@ function RecordProviderAuthOnly({
       userProfileLoading,
       refetchUserProfile,
       allowAnonymous,
-      getAuthToken: getAuthTokenProp
+      getAuthToken: getAuthTokenProp,
+      onPermissionError,
+      onValidationError
     }),
-    [userProfile, userProfileLoading, refetchUserProfile, allowAnonymous, getAuthTokenProp]
+    [
+      userProfile,
+      userProfileLoading,
+      refetchUserProfile,
+      allowAnonymous,
+      getAuthTokenProp,
+      onPermissionError,
+      onValidationError
+    ]
   );
   return /* @__PURE__ */ jsx6(RecordAuthContext.Provider, { value: authValue, children: /* @__PURE__ */ jsx6(ScopeRegistryProvider, { children }) });
 }
+var seenWriteErrors = /* @__PURE__ */ new Set();
+function defaultOnWriteError(error) {
+  const key = JSON.stringify([error.kind, error.title, error.detail]);
+  if (seenWriteErrors.has(key)) return;
+  if (seenWriteErrors.size >= 100) seenWriteErrors.clear();
+  seenWriteErrors.add(key);
+  console.error(
+    `[deepspace] Write rejected \u2014 ${error.title}: ${error.detail}
+This error reached no UI. Pass onWriteError to <RecordProvider> (e.g. wire it to a toast) so users see rejected writes. (Further repeats of this error are suppressed.)`
+  );
+}
+var warnedIgnoredSchemas = false;
+var warnedSignedOutNull = false;
+function SignedOutDiagnostic() {
+  return /* @__PURE__ */ jsxs4(
+    "div",
+    {
+      role: "alert",
+      "data-deepspace-diagnostic": "signed-out",
+      style: {
+        margin: "24px auto",
+        maxWidth: 560,
+        padding: "16px 20px",
+        border: "1px solid #d97706",
+        borderRadius: 8,
+        background: "#fffbeb",
+        color: "#78350f",
+        fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+        fontSize: 13,
+        lineHeight: 1.5
+      },
+      children: [
+        /* @__PURE__ */ jsx6("strong", { children: "DeepSpace: nothing rendered because you're signed out." }),
+        /* @__PURE__ */ jsxs4("p", { style: { margin: "8px 0 0" }, children: [
+          "This page is inside a ",
+          "<RecordProvider>",
+          " without ",
+          /* @__PURE__ */ jsx6("code", { children: "allowAnonymous" }),
+          ", which renders nothing for signed-out visitors. Either add",
+          " ",
+          /* @__PURE__ */ jsx6("code", { children: "<RecordProvider allowAnonymous>" }),
+          " to show the page publicly, or require sign-in before this point (e.g. a protected route / AuthGate)."
+        ] }),
+        /* @__PURE__ */ jsx6("p", { style: { margin: "8px 0 0", opacity: 0.8 }, children: "This notice only appears on localhost \u2014 a deployed app renders nothing here." })
+      ]
+    }
+  );
+}
 function RecordProvider({
   roomId,
+  schemas,
   wsUrl,
   children,
   allowAnonymous = false,
-  getAuthToken: getAuthTokenProp
+  getAuthToken: getAuthTokenProp,
+  onWriteError = defaultOnWriteError
 }) {
   const { isLoaded, isSignedIn } = useAuth();
+  if (schemas && roomId && isLocalDevHost() && !warnedIgnoredSchemas) {
+    warnedIgnoredSchemas = true;
+    console.warn(
+      "[deepspace] RecordProvider received a `schemas` prop alongside `roomId`, but the single-scope provider ignores it \u2014 schemas are resolved server-side in this mode. Remove the `schemas` prop, or adopt the multi-scope shape and pass schemas to <RecordScope>."
+    );
+  }
   const fetchUser = useCallback2(async () => {
     if (!isSignedIn) return null;
     const token = await getAuthToken();
@@ -2033,8 +2129,19 @@ function RecordProvider({
     return /* @__PURE__ */ jsx6(Fragment5, { children: null });
   }
   if (!isSignedIn && !allowAnonymous) {
+    if (isLocalDevHost()) {
+      if (!warnedSignedOutNull) {
+        warnedSignedOutNull = true;
+        console.warn(
+          "[deepspace] RecordProvider rendered nothing: signed out and allowAnonymous is off. Add `allowAnonymous` to show this page to signed-out visitors, or require sign-in before this point."
+        );
+      }
+      return /* @__PURE__ */ jsx6(SignedOutDiagnostic, {});
+    }
     return /* @__PURE__ */ jsx6(Fragment5, { children: null });
   }
+  const onPermissionError = (title, detail) => onWriteError({ kind: "permission", title, detail });
+  const onValidationError = (title, detail) => onWriteError({ kind: "validation", title, detail });
   if (roomId) {
     return /* @__PURE__ */ jsx6(
       RecordProviderCore,
@@ -2044,6 +2151,8 @@ function RecordProvider({
         fetchUser,
         allowAnonymous,
         getAuthToken: getAuthTokenFn,
+        onPermissionError,
+        onValidationError,
         children
       }
     );
@@ -2054,6 +2163,8 @@ function RecordProvider({
       fetchUser,
       allowAnonymous,
       getAuthToken: getAuthTokenFn,
+      onPermissionError,
+      onValidationError,
       children
     }
   );
@@ -2071,7 +2182,7 @@ function wsLog(event, label) {
 }
 
 // src/client/storage/RecordScope.tsx
-import { Fragment as Fragment6, jsx as jsx7, jsxs as jsxs4 } from "react/jsx-runtime";
+import { Fragment as Fragment6, jsx as jsx7, jsxs as jsxs5 } from "react/jsx-runtime";
 function HeadlessScope({
   roomId,
   schemas,
@@ -2325,7 +2436,7 @@ function RecordScope({
   wsPathPrefix = "/ws",
   isolated = false
 }) {
-  return /* @__PURE__ */ jsxs4(Fragment6, { children: [
+  return /* @__PURE__ */ jsxs5(Fragment6, { children: [
     sharedScopes?.map((shared) => /* @__PURE__ */ jsx7(
       HeadlessScope,
       {
@@ -5789,7 +5900,7 @@ function useSubscription() {
 }
 
 // src/client/subscriptions/PricingTable.tsx
-import { jsx as jsx10, jsxs as jsxs5 } from "react/jsx-runtime";
+import { jsx as jsx10, jsxs as jsxs6 } from "react/jsx-runtime";
 function PricingTable(props) {
   const interval = props.interval ?? "month";
   return /* @__PURE__ */ jsx10("div", { className: "grid gap-4 md:grid-cols-3", children: props.plans.map((plan) => {
@@ -5802,14 +5913,14 @@ function PricingTable(props) {
     const unavailableLabel = onlyInterval ? onlyInterval === "month" ? "Monthly only" : "Yearly only" : "Unavailable";
     const priceLabel = price ? `$${(price.priceCents / 100).toFixed(0)}` : isTrueFree ? "Free" : unavailableLabel;
     const disabled = selected || intervalUnavailable;
-    return /* @__PURE__ */ jsxs5("section", { className: "rounded-lg border border-border p-5", children: [
-      /* @__PURE__ */ jsxs5("div", { className: "space-y-1", children: [
+    return /* @__PURE__ */ jsxs6("section", { className: "rounded-lg border border-border p-5", children: [
+      /* @__PURE__ */ jsxs6("div", { className: "space-y-1", children: [
         /* @__PURE__ */ jsx10("h3", { className: "text-lg font-semibold", children: plan.name }),
-        /* @__PURE__ */ jsxs5("p", { className: "text-3xl font-semibold", children: [
+        /* @__PURE__ */ jsxs6("p", { className: "text-3xl font-semibold", children: [
           priceLabel,
           /* @__PURE__ */ jsx10("span", { className: "text-sm font-normal text-muted-foreground", children: price ? `/${interval}` : "" })
         ] }),
-        plan.trialDays ? /* @__PURE__ */ jsxs5("p", { className: "text-xs text-muted-foreground", children: [
+        plan.trialDays ? /* @__PURE__ */ jsxs6("p", { className: "text-xs text-muted-foreground", children: [
           plan.trialDays,
           "-day free trial"
         ] }) : null