deepspace 0.22.1 → 0.23.1

package/dist/index.d.ts

@@ -100,6 +100,16 @@ interface CollectionSchema {
     permissions: Record<string, RolePermissions>;
     /** Default role assigned on the `users` collection. */
     defaultRole?: string;
+    /**
+     * `users` collection only: what the `user.list` roster shows a non-admin
+     * whose `read` policy is row-scoped (`'own'`, `'team'`, …). Default
+     * `'public-identity'`: every registered user's id/name/imageUrl/role — the
+     * row policy keeps guarding full-row reads on the records/query path.
+     * `'read-policy'`: the roster contains only the rows the caller's read
+     * policy grants (still projected to public identity) — for apps that scope
+     * users to a tenant/team and must not show names across it.
+     */
+    roster?: 'public-identity' | 'read-policy';
 }
 interface Query {
     collection: string;
@@ -655,10 +665,26 @@ declare const MSG_YJS_SYNC = 22;
 declare const MSG_YJS_AWARENESS = 23;
 /** Role assigned to unauthenticated WebSocket connections */
 declare const ROLE_ANONYMOUS = "viewer";
+/** Prefix `base-room` mints anonymous socket ids with. */
+declare const ANONYMOUS_USER_ID_PREFIX = "anon-";
+/** The one test for an anonymous socket identity — `ROLE_ANONYMOUS` cannot be
+ *  it, since authenticated users can legitimately hold the same role name. */
+declare function isAnonymousUserId(userId: string): boolean;
 /** Default role for newly registered authenticated users */
 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 +2846,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 +2871,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;
 }
@@ -3113,7 +3144,10 @@ declare function useQuery<T = unknown>(collection: string, options?: {
  * ```
  */
 declare function useMutations<T = unknown>(collection: string): {
-    /** True once the collection's RecordRoom can accept writes. */
+    /** True once the collection's RecordRoom can accept writes. Disable the
+     *  control on it (`disabled={!ready}`) rather than early-returning from
+     *  the handler: an early return drops the user's write silently, while a
+     *  write attempted before `ready` at least raises a `not_ready` error. */
     ready: boolean;
     create: (data: T) => Promise<string>;
     put: (recordId: string, data: Partial<T>) => Promise<void>;
@@ -5057,4 +5091,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, ANONYMOUS_USER_ID_PREFIX, 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, isAnonymousUserId, 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

@@ -613,8 +613,13 @@ var MSG = {
 var MSG_YJS_SYNC = 22;
 var MSG_YJS_AWARENESS = 23;
 var ROLE_ANONYMOUS = "viewer";
+var ANONYMOUS_USER_ID_PREFIX = "anon-";
+function isAnonymousUserId(userId) {
+  return userId.startsWith(ANONYMOUS_USER_ID_PREFIX);
+}
 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 +1381,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 +1426,7 @@ function RecordProviderState({
       refetchUserProfile,
       allowAnonymous,
       getAuthToken: getAuthTokenProp,
-      onPermissionError,
-      onValidationError
+      onWriteError
     }),
     [
       userProfile,
@@ -1436,8 +1434,7 @@ function RecordProviderState({
       refetchUserProfile,
       allowAnonymous,
       getAuthTokenProp,
-      onPermissionError,
-      onValidationError
+      onWriteError
     ]
   );
   return /* @__PURE__ */ jsx6(RecordAuthContext.Provider, { value: authValue, children: /* @__PURE__ */ jsx6(ScopeRegistryProvider, { children }) });
@@ -1533,16 +1530,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 +2199,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 +2225,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 +2509,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 +2521,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();
@@ -6476,6 +6473,7 @@ var APP_LOG_EVENT_KEYS = [
 ];
 export {
   ACCOUNT_STORAGE_LIMIT_BYTES,
+  ANONYMOUS_USER_ID_PREFIX,
   APP_LOG_EVENT_KEYS,
   ASYNC_RESOURCE_DEFAULTS,
   AuthGate,
@@ -6504,6 +6502,7 @@ export {
   PlatformContext,
   PlatformProvider,
   PricingTable,
+  RECORD_NOT_FOUND,
   ROLES,
   ROLE_ADMIN,
   ROLE_ANONYMOUS,
@@ -6558,6 +6557,7 @@ export {
   hasContent,
   installClientErrorReporter,
   integration,
+  isAnonymousUserId,
   isAsyncResourceSlow,
   isDMConversation,
   isDarkColor,