deepspace 0.22.1 → 0.23.0

package/dist/index.d.ts

@@ -659,6 +659,17 @@ declare const ROLE_ANONYMOUS = "viewer";
 declare const ROLE_DEFAULT = "member";
 /** Admin role */
 declare const ROLE_ADMIN = "admin";
+/**
+ * Reported when a record id resolves to nothing.
+ *
+ * This crosses the DO boundary as a response body and callers branch on it,
+ * so it is a contract rather than prose. `getChat` in particular treats it as
+ * "no such chat" and returns null — the same answer it gives for a chat owned
+ * by someone else, which is what stops chat ids being enumerable. If a room
+ * reworded this independently, a miss would start throwing while a cross-user
+ * hit kept returning null, and that difference is an existence oracle.
+ */
+declare const RECORD_NOT_FOUND = "Record not found";
 
 /**
  * Typed wire-protocol layer — discriminated unions, typed builders, and a
@@ -2820,10 +2831,14 @@ interface RoomUser {
     lastSeenAt?: string;
 }
 type RoomConnectionState = 'connecting' | 'connected' | 'disconnected';
-/** A server-rejected optimistic write. */
+/** A rejected optimistic write. */
 interface WriteError {
-    /** RBAC denial or data validation/other rejection. */
-    kind: 'permission' | 'validation';
+    /**
+     * `permission` — RBAC denial; `validation` — data validation/other server
+     * rejection; `not_ready` — rejected client-side because the room could not
+     * accept writes yet (gate the control on `ready` from `useMutations()`).
+     */
+    kind: 'permission' | 'validation' | 'not_ready';
     /** Short human-readable summary, safe to show end users. */
     title: string;
     /** Longer human-readable explanation; may be empty. */
@@ -2841,8 +2856,9 @@ interface RecordProviderProps {
     /** Auth token provider for WS connections. */
     getAuthToken?: () => Promise<string | null>;
     /**
-     * Receives server-rejected optimistic writes. Wire this to app UI so users
-     * see denied or invalid changes. Defaults to a deduplicated console error.
+     * Receives every rejected write — denied or invalid by the server, and
+     * attempted before the room was ready. Wire this to app UI so users see
+     * changes that didn't land. Defaults to a deduplicated console error.
      */
     onWriteError?: (error: WriteError) => void;
 }
@@ -5057,4 +5073,4 @@ declare const ACCOUNT_STORAGE_LIMIT_BYTES: {
 declare function storageLimitForTier(tier: string | null | undefined): number;
 declare function formatBytes(bytes: number): string;
 
-export { ACCOUNT_STORAGE_LIMIT_BYTES, APP_LOG_EVENT_KEYS, ASYNC_RESOURCE_DEFAULTS, type AdHocChargeOpts, type AiStreamAction, type AiStreamChunk, type ApiErrorIssue, type AppLogEvent, type AppLogEventKey, type AppLogsResponse, type AppMigrationIdsValidation, 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 ClientErrorKind, type ClientErrorReport, type ClientErrorReporterOptions, type ClientMessage, type CollectionSchema, type ConnectionAttachment, type ConnectionStatus, type ContentSegment, type ConversationObject, type CronHistoryEntry, type CronMutationResult, type CronTaskState, DEEPSPACE_AGENT_PROFILES, DEEPSPACE_AI_DEFAULTS, DEEPSPACE_AI_MODELS, DEEPSPACE_MODEL_CATALOG_PROVENANCE, DEEPSPACE_THEME_PROPERTIES, DEFAULT_USER_COLORS, type DeepSpaceAIModel, type DeepSpaceAIModelId, type DeepSpaceAIProvider, type DeepSpaceAgentProfile, type DeepSpaceAgentProfileId, type DeepSpaceAgentSupport, DeepSpaceAuthProvider, type DeepSpaceThemeConfig, DeepSpaceThemeProvider, type DeepSpaceThemeProviderProps, type DeriveLoadStateInput, ENV, type Environment, type FileAttachment, type GroupedReaction, GuestBanner, type HandlerContext, type InboxEntry, type IntegrationResponse, type JobStatusView, type JobView, LOG_LEVELS, type LinkPreviewData, type LoadState, type LoadStateAuthInput, type LoadStateStatusInput, type LogLevel, 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 NormalizedApiError, type PagedResourceFetchArgs, type PagedResourcePage, type PagedResourceState, type PagedResourceStatus, type PlanInfo, PlatformApiError, 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 R2FileListPage, 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, RecordRoomNotReadyError, RecordScope, type RequestOptions, type ResolvedDeepSpaceAgentModel, type Role, type RoomUser, SECURE_ROOM_BOUNDARIES_MIGRATION_ID, type ScopeEntry, ScopeRegistryProvider, type ServerMessage, SignedIn, SignedOut, type SubscribeOpts, type SubscribeResult, type SubscriptionState, type SubscriptionStatus, type SyncResult, type UseAsyncResourceOptions, type UseAuthProfileReadyOptions, type UseAuthStatusOptions, type UseCanvasResult, type UseCheckoutOpts, type UseCronMonitorResult, 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, WORKER_OWNED_NOT_FOUND_MIGRATION_ID, type WriteError, applyDeepSpaceTheme, applyUIThemeTokens, authClient, canAutoLoadPagedResource, clampPagedResourceItems, clearAuthToken, clearDeepSpaceTheme, clientBuild, createDecoder, createEncoder, decodeAiStreamChunk, deriveLoadState, detectEnvironment, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, formatBytes, formatFileSize, formatFullTimestamp, formatMessageTime, getApiUrl, getAuthToken, getAuthUrl, getConversationDisplayName, getConversationParticipantIds, getDeepSpaceAIModel, getEnvironmentConfig, getMessageType, getPagedResourceCooldownMs, getPlatformWorkerUrl, getThreadCounts, getUserColor, groupReactionsForMessage, handleAwarenessMessage, handleSyncMessage, hasContent, installClientErrorReporter, integration, isAsyncResourceSlow, isDMConversation, isDarkColor, isImageFile, isLocalDev, isProduction, listDeepSpaceAgentModels, parseMessageMetadata, parseSseLine, readThemeFromDOM, readVarUint, readVarUint8Array, reportClientError, resetEnvironmentCache, resolveDeepSpaceAgentModel, serverBuild, shouldGroupMessages, signIn, signOut, storageLimitForTier, toConnectionStatus, toUint8Array, useAsyncResource, useAuth, useAuthProfileReady, useAuthStatus, useAuthUser, useCanvas, useChannelMembers, useChannels, useCheckout, useCommunities, useConversation, useConversations, useCronMonitor, useDisplayName, 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, validateAppMigrationIds, writeVarUint, writeVarUint8Array };
+export { ACCOUNT_STORAGE_LIMIT_BYTES, APP_LOG_EVENT_KEYS, ASYNC_RESOURCE_DEFAULTS, type AdHocChargeOpts, type AiStreamAction, type AiStreamChunk, type ApiErrorIssue, type AppLogEvent, type AppLogEventKey, type AppLogsResponse, type AppMigrationIdsValidation, 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 ClientErrorKind, type ClientErrorReport, type ClientErrorReporterOptions, type ClientMessage, type CollectionSchema, type ConnectionAttachment, type ConnectionStatus, type ContentSegment, type ConversationObject, type CronHistoryEntry, type CronMutationResult, type CronTaskState, DEEPSPACE_AGENT_PROFILES, DEEPSPACE_AI_DEFAULTS, DEEPSPACE_AI_MODELS, DEEPSPACE_MODEL_CATALOG_PROVENANCE, DEEPSPACE_THEME_PROPERTIES, DEFAULT_USER_COLORS, type DeepSpaceAIModel, type DeepSpaceAIModelId, type DeepSpaceAIProvider, type DeepSpaceAgentProfile, type DeepSpaceAgentProfileId, type DeepSpaceAgentSupport, DeepSpaceAuthProvider, type DeepSpaceThemeConfig, DeepSpaceThemeProvider, type DeepSpaceThemeProviderProps, type DeriveLoadStateInput, ENV, type Environment, type FileAttachment, type GroupedReaction, GuestBanner, type HandlerContext, type InboxEntry, type IntegrationResponse, type JobStatusView, type JobView, LOG_LEVELS, type LinkPreviewData, type LoadState, type LoadStateAuthInput, type LoadStateStatusInput, type LogLevel, 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 NormalizedApiError, type PagedResourceFetchArgs, type PagedResourcePage, type PagedResourceState, type PagedResourceStatus, type PlanInfo, PlatformApiError, 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 R2FileListPage, type R2Scope, type R2UploadResult, RECORD_NOT_FOUND, ROLES, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_CONFIG, ROLE_DEFAULT, type Reaction, type ReactionRecord, type ReadCursorRecord, type ReadReceipt, type RecordData, RecordProvider, type RecordProviderProps, RecordRoomNotReadyError, RecordScope, type RequestOptions, type ResolvedDeepSpaceAgentModel, type Role, type RoomUser, SECURE_ROOM_BOUNDARIES_MIGRATION_ID, type ScopeEntry, ScopeRegistryProvider, type ServerMessage, SignedIn, SignedOut, type SubscribeOpts, type SubscribeResult, type SubscriptionState, type SubscriptionStatus, type SyncResult, type UseAsyncResourceOptions, type UseAuthProfileReadyOptions, type UseAuthStatusOptions, type UseCanvasResult, type UseCheckoutOpts, type UseCronMonitorResult, 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, WORKER_OWNED_NOT_FOUND_MIGRATION_ID, type WriteError, applyDeepSpaceTheme, applyUIThemeTokens, authClient, canAutoLoadPagedResource, clampPagedResourceItems, clearAuthToken, clearDeepSpaceTheme, clientBuild, createDecoder, createEncoder, decodeAiStreamChunk, deriveLoadState, detectEnvironment, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, formatBytes, formatFileSize, formatFullTimestamp, formatMessageTime, getApiUrl, getAuthToken, getAuthUrl, getConversationDisplayName, getConversationParticipantIds, getDeepSpaceAIModel, getEnvironmentConfig, getMessageType, getPagedResourceCooldownMs, getPlatformWorkerUrl, getThreadCounts, getUserColor, groupReactionsForMessage, handleAwarenessMessage, handleSyncMessage, hasContent, installClientErrorReporter, integration, isAsyncResourceSlow, isDMConversation, isDarkColor, isImageFile, isLocalDev, isProduction, listDeepSpaceAgentModels, parseMessageMetadata, parseSseLine, readThemeFromDOM, readVarUint, readVarUint8Array, reportClientError, resetEnvironmentCache, resolveDeepSpaceAgentModel, serverBuild, shouldGroupMessages, signIn, signOut, storageLimitForTier, toConnectionStatus, toUint8Array, useAsyncResource, useAuth, useAuthProfileReady, useAuthStatus, useAuthUser, useCanvas, useChannelMembers, useChannels, useCheckout, useCommunities, useConversation, useConversations, useCronMonitor, useDisplayName, 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, validateAppMigrationIds, writeVarUint, writeVarUint8Array };

package/dist/index.js

@@ -615,6 +615,7 @@ var MSG_YJS_AWARENESS = 23;
 var ROLE_ANONYMOUS = "viewer";
 var ROLE_DEFAULT = "member";
 var ROLE_ADMIN = "admin";
+var RECORD_NOT_FOUND = "Record not found";
 
 // src/shared/protocol/messages.ts
 var EMPTY = Object.freeze({});
@@ -1376,20 +1377,14 @@ function RecordProviderState({
   fetchUser,
   allowAnonymous = false,
   getAuthToken: getAuthTokenProp,
-  onPermissionError: onPermissionErrorProp,
-  onValidationError: onValidationErrorProp
+  onWriteError: onWriteErrorProp
 }) {
   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 onWriteErrorRef = useRef4(onWriteErrorProp);
+  onWriteErrorRef.current = onWriteErrorProp;
+  const onWriteError = useCallback2((error) => {
+    onWriteErrorRef.current(error);
   }, []);
   const refetchUserProfile = useCallback2(async () => {
     try {
@@ -1427,8 +1422,7 @@ function RecordProviderState({
       refetchUserProfile,
       allowAnonymous,
       getAuthToken: getAuthTokenProp,
-      onPermissionError,
-      onValidationError
+      onWriteError
     }),
     [
       userProfile,
@@ -1436,8 +1430,7 @@ function RecordProviderState({
       refetchUserProfile,
       allowAnonymous,
       getAuthTokenProp,
-      onPermissionError,
-      onValidationError
+      onWriteError
     ]
   );
   return /* @__PURE__ */ jsx6(RecordAuthContext.Provider, { value: authValue, children: /* @__PURE__ */ jsx6(ScopeRegistryProvider, { children }) });
@@ -1533,16 +1526,13 @@ function RecordProvider({
     }
     return /* @__PURE__ */ jsx6(Fragment5, { children: null });
   }
-  const onPermissionError = (title, detail) => onWriteError({ kind: "permission", title, detail });
-  const onValidationError = (title, detail) => onWriteError({ kind: "validation", title, detail });
   return /* @__PURE__ */ jsx6(
     RecordProviderState,
     {
       fetchUser,
       allowAnonymous,
       getAuthToken: getAuthTokenFn,
-      onPermissionError,
-      onValidationError,
+      onWriteError,
       children
     }
   );
@@ -2205,12 +2195,8 @@ function ScopeConnection({
   userProfileRef.current = auth?.userProfile ?? null;
   const getAuthTokenRef = useRef5(auth?.getAuthToken ?? null);
   getAuthTokenRef.current = auth?.getAuthToken ?? null;
-  const authCallbacksRef = useRef5({
-    onPermissionError: auth?.onPermissionError,
-    onValidationError: auth?.onValidationError
-  });
-  authCallbacksRef.current.onPermissionError = auth?.onPermissionError;
-  authCallbacksRef.current.onValidationError = auth?.onValidationError;
+  const onWriteErrorRef = useRef5(auth?.onWriteError);
+  onWriteErrorRef.current = auth?.onWriteError;
   const allowAnonymous = auth?.allowAnonymous ?? false;
   const userProfileId = auth?.userProfile?.id ?? null;
   const userProfileLoading = auth?.userProfileLoading ?? false;
@@ -2235,8 +2221,8 @@ function ScopeConnection({
           setUsersLoaded(true);
         },
         onSchemas: setDiscoveredSchemas,
-        onPermissionError: (title, detail) => authCallbacksRef.current.onPermissionError?.(title, detail),
-        onValidationError: (title, detail) => authCallbacksRef.current.onValidationError?.(title, detail)
+        onPermissionError: (title, detail) => onWriteErrorRef.current?.({ kind: "permission", title, detail }),
+        onValidationError: (title, detail) => onWriteErrorRef.current?.({ kind: "validation", title, detail })
       }
     });
     socketRef.current = socket;
@@ -2519,6 +2505,7 @@ import { useCallback as useCallback5, useContext as useContext4, useMemo as useM
 function useMutations(collection) {
   const registry = useScopeRegistry();
   const recordCtx = useContext4(RecordContext);
+  const onWriteError = useRecordAuth()?.onWriteError;
   const scopeEntry = registry?.resolve(collection) ?? null;
   const preferLocal = recordCtx?.registeredCollections?.has(collection) ?? false;
   const sendMessage = preferLocal ? recordCtx.sendMessage : scopeEntry?.sendMessage ?? recordCtx?.sendMessage;
@@ -2530,8 +2517,14 @@ function useMutations(collection) {
     );
   }
   const assertReady = useCallback5(() => {
-    if (!ready) throw new RecordRoomNotReadyError(collection);
-  }, [ready, collection]);
+    if (ready) return;
+    onWriteError?.({
+      kind: "not_ready",
+      title: "Not saved \u2014 still connecting",
+      detail: `The room backing "${collection}" was not ready to accept writes yet, so the change was dropped. Gate the action on the \`ready\` flag from useMutations('${collection}') (e.g. \`disabled={!ready}\`) and retry once it is true.`
+    });
+    throw new RecordRoomNotReadyError(collection);
+  }, [ready, collection, onWriteError]);
   const create = useCallback5(
     async (data) => {
       assertReady();
@@ -6504,6 +6497,7 @@ export {
   PlatformContext,
   PlatformProvider,
   PricingTable,
+  RECORD_NOT_FOUND,
   ROLES,
   ROLE_ADMIN,
   ROLE_ANONYMOUS,