deepspace 0.3.10 → 0.4.0

package/dist/index.d.ts

@@ -396,6 +396,7 @@ declare const MSG: {
     readonly USER_LIST: "user.list";
     readonly SET_ROLE: "user.set_role";
     readonly USER_UPDATE: "user.update";
+    readonly AUTH: "auth";
     readonly YJS_JOIN: "yjs.join";
     readonly YJS_LEAVE: "yjs.leave";
     readonly ACK: "records.ack";
@@ -424,6 +425,10 @@ declare const MSG: {
     readonly CRON_PAUSE: "cron.pause";
     readonly CRON_RESUME: "cron.resume";
     readonly CRON_STATUS: "cron.status";
+    readonly JOB_ENQUEUE: "job.enqueue";
+    readonly JOB_CANCEL: "job.cancel";
+    readonly JOB_RETRY: "job.retry";
+    readonly JOB_UPDATE: "job.update";
     readonly PRESENCE_SYNC: "presence.sync";
     readonly PRESENCE_JOIN: "presence.join";
     readonly PRESENCE_LEAVE: "presence.leave";
@@ -590,6 +595,15 @@ type ClientMessage = BaseMessage<typeof MSG.SUBSCRIBE, {
     taskName: string;
 }> | BaseMessage<typeof MSG.CRON_RESUME, {
     taskName: string;
+}> | BaseMessage<typeof MSG.JOB_ENQUEUE, {
+    requestId: string;
+    type: string;
+    payload?: unknown;
+    maxAttempts?: number;
+}> | BaseMessage<typeof MSG.JOB_CANCEL, {
+    jobId: string;
+}> | BaseMessage<typeof MSG.JOB_RETRY, {
+    jobId: string;
 }> | BaseMessage<typeof MSG.PRESENCE_UPDATE, Record<string, unknown>> | BaseMessage<typeof MSG.GW_SCOPE_CONNECT, {
     scopeType: string;
     scopeId: string;
@@ -626,6 +640,8 @@ type ServerMessage = BaseMessage<typeof MSG.QUERY_RESULT, {
     error: string;
 }> | BaseMessage<typeof MSG.RESUBSCRIBE, EmptyPayload> | BaseMessage<typeof MSG.LIST_SCHEMAS, {
     schemas: unknown;
+}> | BaseMessage<typeof MSG.AUTH, {
+    canWrite: boolean;
 }> | BaseMessage<typeof MSG.USER_INFO, unknown> | BaseMessage<typeof MSG.USER_LIST, {
     users: unknown[];
 }> | BaseMessage<typeof MSG.YJS_JOIN, {
@@ -685,6 +701,12 @@ type ServerMessage = BaseMessage<typeof MSG.QUERY_RESULT, {
 }> | BaseMessage<typeof MSG.CRON_STATUS, {
     tasks: unknown;
     recentHistory: unknown;
+}> | BaseMessage<typeof MSG.JOB_UPDATE, {
+    kind: 'snapshot' | 'enqueued' | 'progress' | 'succeeded' | 'failed' | 'canceled' | 'retried';
+    job?: unknown;
+    jobs?: unknown[];
+    /** Echoes the enqueue requestId when the update is the enqueue ack. */
+    requestId?: string;
 }> | BaseMessage<typeof MSG.PRESENCE_SYNC, {
     peers: unknown[];
 }> | BaseMessage<typeof MSG.PRESENCE_JOIN, {
@@ -856,6 +878,27 @@ declare const clientBuild: {
             readonly taskName: string;
         };
     };
+    jobEnqueue: (requestId: string, type: string, payload?: unknown, maxAttempts?: number) => {
+        readonly type: "job.enqueue";
+        readonly payload: {
+            readonly requestId: string;
+            readonly type: string;
+            readonly payload: unknown;
+            readonly maxAttempts: number | undefined;
+        };
+    };
+    jobCancel: (jobId: string) => {
+        readonly type: "job.cancel";
+        readonly payload: {
+            readonly jobId: string;
+        };
+    };
+    jobRetry: (jobId: string) => {
+        readonly type: "job.retry";
+        readonly payload: {
+            readonly jobId: string;
+        };
+    };
     presenceUpdate: (state: Record<string, unknown>) => {
         readonly type: "presence.update";
         readonly payload: Record<string, unknown>;
@@ -1078,6 +1121,56 @@ declare const serverBuild: {
             readonly recentHistory: unknown;
         };
     };
+    jobSnapshot: (jobs: unknown[]) => {
+        readonly type: "job.update";
+        readonly payload: {
+            readonly kind: "snapshot";
+            readonly jobs: unknown[];
+        };
+    };
+    jobEnqueued: (job: unknown, requestId?: string) => {
+        readonly type: "job.update";
+        readonly payload: {
+            readonly kind: "enqueued";
+            readonly job: unknown;
+            readonly requestId: string | undefined;
+        };
+    };
+    jobProgress: (job: unknown) => {
+        readonly type: "job.update";
+        readonly payload: {
+            readonly kind: "progress";
+            readonly job: unknown;
+        };
+    };
+    jobSucceeded: (job: unknown) => {
+        readonly type: "job.update";
+        readonly payload: {
+            readonly kind: "succeeded";
+            readonly job: unknown;
+        };
+    };
+    jobFailed: (job: unknown) => {
+        readonly type: "job.update";
+        readonly payload: {
+            readonly kind: "failed";
+            readonly job: unknown;
+        };
+    };
+    jobCanceled: (job: unknown) => {
+        readonly type: "job.update";
+        readonly payload: {
+            readonly kind: "canceled";
+            readonly job: unknown;
+        };
+    };
+    jobRetried: (job: unknown) => {
+        readonly type: "job.update";
+        readonly payload: {
+            readonly kind: "retried";
+            readonly job: unknown;
+        };
+    };
     presenceSync: (peers: unknown[]) => {
         readonly type: "presence.sync";
         readonly payload: {
@@ -5882,13 +5975,20 @@ interface UseGameRoomResult {
     running: boolean;
     /** Whether WebSocket is connected */
     connected: boolean;
-    /** Send a game input */
+    /**
+     * Whether this connection has write access. False for viewers /
+     * unauthenticated spectators — they receive state broadcasts but the
+     * send callbacks below no-op. UIs should disable input controls when
+     * false so spectators see why their actions don't take effect.
+     */
+    canWrite: boolean;
+    /** Send a game input (no-op for spectators) */
     sendInput: (action: string, data?: Record<string, unknown>) => void;
-    /** Mark self as ready */
+    /** Mark self as ready (no-op for spectators) */
     setReady: () => void;
-    /** Request game start */
+    /** Request game start (no-op for spectators) */
     startGame: () => void;
-    /** Request game end */
+    /** Request game end (no-op for spectators) */
     endGame: () => void;
 }
 declare function useGameRoom(roomId: string): UseGameRoomResult;
@@ -5929,21 +6029,28 @@ interface UseCanvasResult {
     viewports: ViewportClient[];
     /** Whether WebSocket is connected */
     connected: boolean;
-    /** Add a shape */
+    /**
+     * Whether this connection has write access (member/admin role). The
+     * write callbacks below no-op when this is false; UIs should also use
+     * it to disable controls so viewers see why their clicks do nothing.
+     * Viewport reporting stays available regardless — it's presence info.
+     */
+    canWrite: boolean;
+    /** Add a shape (no-op when canWrite is false) */
     addShape: (shape: Partial<CanvasShapeClient>) => void;
-    /** Move a shape */
+    /** Move a shape (no-op when canWrite is false) */
     moveShape: (shapeId: string, x: number, y: number) => void;
-    /** Resize a shape */
+    /** Resize a shape (no-op when canWrite is false) */
     resizeShape: (shapeId: string, width: number, height: number, x?: number, y?: number) => void;
-    /** Delete a shape */
+    /** Delete a shape (no-op when canWrite is false) */
     deleteShape: (shapeId: string) => void;
-    /** Update shape properties */
+    /** Update shape properties (no-op when canWrite is false) */
     updateShape: (shapeId: string, props: Record<string, unknown>) => void;
-    /** Report local viewport */
+    /** Report local viewport (allowed for viewers — presence-like) */
     setViewport: (viewport: Omit<ViewportClient, 'userId'>) => void;
-    /** Undo last action */
+    /** Undo last action (no-op when canWrite is false) */
     undo: () => void;
-    /** Redo last undone action */
+    /** Redo last undone action (no-op when canWrite is false) */
     redo: () => void;
 }
 declare function useCanvas(roomId: string): UseCanvasResult;
@@ -5980,15 +6087,91 @@ interface UseCronMonitorResult {
     history: CronHistoryEntry[];
     /** Whether WebSocket is connected */
     connected: boolean;
-    /** Manually trigger a task */
+    /**
+     * Whether this connection can mutate cron state (trigger / pause /
+     * resume). False for viewers and unauthenticated connections — the
+     * mutation callbacks below no-op and UIs should disable those
+     * controls. Reading tasks/history stays available either way.
+     */
+    canWrite: boolean;
+    /** Manually trigger a task (no-op when canWrite is false) */
     trigger: (taskName: string) => void;
-    /** Pause a task */
+    /** Pause a task (no-op when canWrite is false) */
     pause: (taskName: string) => void;
-    /** Resume a paused task */
+    /** Resume a paused task (no-op when canWrite is false) */
     resume: (taskName: string) => void;
 }
 declare function useCronMonitor(roomId: string): UseCronMonitorResult;
 
+/**
+ * useJobs — Connect to a JobRoom for enqueueing and tracking background
+ * jobs in real time.
+ *
+ * Opens a WebSocket to /ws/jobs/:roomId. The DO pushes a snapshot on
+ * connect and JOB_UPDATE messages for every state change after that, so
+ * `jobs` stays current without polling. `enqueue` returns a promise that
+ * resolves with the new jobId once the server acks.
+ *
+ * Client-side names (`JobView`, `JobStatusView`) differ from the
+ * server-side equivalents (`Job`, `JobStatus` in `deepspace/worker`) so
+ * apps importing from both ends don't get type collisions.
+ *
+ * @example
+ * const { jobs, enqueue, getJob, cancel } = useJobs(`app:${APP_NAME}`)
+ *
+ * async function onClick() {
+ *   const jobId = await enqueue('ai-summarize', { text })
+ *   // Now `getJob(jobId)` is reactive until the job reaches a terminal state.
+ * }
+ */
+type JobStatusView = 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled';
+interface JobView<P = unknown, R = unknown> {
+    id: string;
+    type: string;
+    status: JobStatusView;
+    payload?: P;
+    result?: R;
+    error?: string;
+    progress?: number;
+    progressMessage?: string;
+    attempts: number;
+    maxAttempts: number;
+    enqueuedAt: string;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    enqueuedBy?: string | null;
+}
+interface UseJobsResult<P = unknown, R = unknown> {
+    /** All jobs the room currently knows about, newest-first. */
+    jobs: JobView<P, R>[];
+    /** WebSocket connection state. */
+    connected: boolean;
+    /**
+     * Enqueue a new job. Resolves with the new jobId once the server acks
+     * (typically <100ms). Rejects if:
+     *   - the WebSocket isn't connected
+     *   - the WebSocket closes before the ack arrives
+     *   - no ack arrives within 10s (server dropped the message)
+     */
+    enqueue(type: string, payload?: P, options?: {
+        maxAttempts?: number;
+    }): Promise<string>;
+    /**
+     * Reactive single-job lookup. Returns undefined while the snapshot is
+     * loading or if the job has been GC'd by the room's TTL sweep.
+     */
+    getJob(jobId: string): JobView<P, R> | undefined;
+    /** Best-effort cancel. The job is marked canceled even if the handler ignores `ctx.signal`. */
+    cancel(jobId: string): void;
+    /** Manually re-queue a failed/canceled job. No-op for other statuses. */
+    retry(jobId: string): void;
+}
+/**
+ * @param roomId DO room id, typically `app:<APP_NAME>`. Apps with sharded
+ *   queues pass different ids — each id maps to its own DO instance.
+ */
+declare function useJobs<P = unknown, R = unknown>(roomId: string): UseJobsResult<P, R>;
+
 /**
  * usePresenceRoom — Connect to a PresenceRoom Durable Object.
  *
@@ -7394,4 +7577,4 @@ interface SearchInputProps extends Omit<React$1.ComponentProps<'input'>, 'type'>
 }
 declare const SearchInput: React$1.ForwardRefExoticComponent<Omit<SearchInputProps, "ref"> & React$1.RefAttributes<HTMLInputElement>>;
 
-export { type AdHocChargeOpts, type AiStreamAction, type AiStreamChunk, Alert, AlertDescription, AlertTitle, AuthGate, type AuthGateProps, AuthOverlay, Avatar, AvatarFallback, AvatarImage, Awareness, type AwarenessState, type AwarenessStates, Badge, type BadgeProps, type BaseMessage, Button, type ButtonProps, type CanvasShapeClient, Card, CardContent, CardDescription, CardFooter, CardGrid, CardHeader, CardTitle, type Channel, type ChannelInvitation, type ChannelMember, type ChargeOnceOpts, type ChargeOnceResult, Checkbox, type ClientMessage, type CollectionSchema, ConfirmModal, type ConnectionAttachment, type ConnectionStatus, type ContentSegment, type ConversationObject, type CronHistoryEntry, type CronTaskState, DEEPSPACE_THEME_PROPERTIES, DEFAULT_USER_COLORS, DeepSpaceAuthProvider, type DeepSpaceThemeConfig, DeepSpaceThemeProvider, type DeepSpaceThemeProviderProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, ENV, EmptyDocuments, EmptyError, EmptyItems, EmptyProjects, EmptySearch, EmptyState, EmptyTeam, type Environment, type FetchUserProfile, type FileAttachment, type GamePlayer, GridCard, type GroupedReaction, GuestBanner, type HandlerContext, type InboxEntry, Input, type IntegrationResponse, Label, type LinkPreviewData, LoadingOverlay, LoadingSpinner, 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, Modal, type MsgType, type PlanInfo, PlatformContext, type PlatformContextValue, PlatformProvider, type PlatformWSOptions, type PlatformWSResult, type PresencePeerClient, PricingTable, type PricingTablePlan, type PricingTablePrice, type ProductChargeOpts, Progress, 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, SearchInput, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, type ServerMessage, SignedIn, SignedOut, Skeleton, SkeletonAvatar, SkeletonCard, SkeletonList, SkeletonTable, SkeletonText, type SubscribeOpts, type SubscribeResult, type SubscriptionState, type SubscriptionStatus, Switch, type SyncResult, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, ToastProvider, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UseCanvasResult, type UseCheckoutOpts, type UseCronMonitorResult, type UseGameRoomResult, type UsePresenceRoomResult, type UseR2FilesReturn, type UseYjsFieldResult, type UseYjsRoomResult, type UseYjsTextResult, type User, type UserCredits, type UserInfo, type UserKarma, type UserProfile, type ViewportClient, applyDeepSpaceTheme, applyUIThemeTokens, authClient, badgeVariants, buttonVariants, clearAuthToken, clearDeepSpaceTheme, clientBuild, cn, createDecoder, createEncoder, decodeAiStreamChunk, detectEnvironment, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, formatFileSize, formatFullTimestamp, formatMessageTime, getApiUrl, getAuthToken, getAuthUrl, getConversationDisplayName, getConversationParticipantIds, getEnvironmentConfig, getMessageType, getPlatformWorkerUrl, getThreadCounts, getUserColor, groupReactionsForMessage, handleAwarenessMessage, handleSyncMessage, hasContent, integration, isDMConversation, isDarkColor, isImageFile, isLocalDev, isProduction, parseMessageMetadata, parseSseLine, readThemeFromDOM, readVarUint, readVarUint8Array, resetEnvironmentCache, serverBuild, shouldGroupMessages, signIn, signOut, toConnectionStatus, toUint8Array, useAuth, useAuthUser, useCanvas, useChannelMembers, useChannels, useCheckout, useCommunities, useConversation, useConversations, useCronMonitor, useDisplayName, useGameRoom, useInbox, useIsDarkTheme, useMessages, useMutations, usePlatform, usePlatformWS, usePosts, usePresence, usePresenceRoom, useQuery, useR2Files, useReactions, useReadReceipts, useRecordContext, useSession, useSubscription, useToast, useUser, useUserLookup, useUsers, useYjsField, useYjsRoom, useYjsText, writeVarUint, writeVarUint8Array };
+export { type AdHocChargeOpts, type AiStreamAction, type AiStreamChunk, Alert, AlertDescription, AlertTitle, AuthGate, type AuthGateProps, AuthOverlay, Avatar, AvatarFallback, AvatarImage, Awareness, type AwarenessState, type AwarenessStates, Badge, type BadgeProps, type BaseMessage, Button, type ButtonProps, type CanvasShapeClient, Card, CardContent, CardDescription, CardFooter, CardGrid, CardHeader, CardTitle, type Channel, type ChannelInvitation, type ChannelMember, type ChargeOnceOpts, type ChargeOnceResult, Checkbox, type ClientMessage, type CollectionSchema, ConfirmModal, type ConnectionAttachment, type ConnectionStatus, type ContentSegment, type ConversationObject, type CronHistoryEntry, type CronTaskState, DEEPSPACE_THEME_PROPERTIES, DEFAULT_USER_COLORS, DeepSpaceAuthProvider, type DeepSpaceThemeConfig, DeepSpaceThemeProvider, type DeepSpaceThemeProviderProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, ENV, EmptyDocuments, EmptyError, EmptyItems, EmptyProjects, EmptySearch, EmptyState, EmptyTeam, type Environment, type FetchUserProfile, type FileAttachment, type GamePlayer, GridCard, type GroupedReaction, GuestBanner, type HandlerContext, type InboxEntry, Input, type IntegrationResponse, type JobStatusView, type JobView, Label, type LinkPreviewData, LoadingOverlay, LoadingSpinner, 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, Modal, type MsgType, type PlanInfo, PlatformContext, type PlatformContextValue, PlatformProvider, type PlatformWSOptions, type PlatformWSResult, type PresencePeerClient, PricingTable, type PricingTablePlan, type PricingTablePrice, type ProductChargeOpts, Progress, 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, SearchInput, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, type ServerMessage, SignedIn, SignedOut, Skeleton, SkeletonAvatar, SkeletonCard, SkeletonList, SkeletonTable, SkeletonText, type SubscribeOpts, type SubscribeResult, type SubscriptionState, type SubscriptionStatus, Switch, type SyncResult, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, ToastProvider, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UseCanvasResult, type UseCheckoutOpts, type UseCronMonitorResult, type UseGameRoomResult, type UseJobsResult, type UsePresenceRoomResult, type UseR2FilesReturn, type UseYjsFieldResult, type UseYjsRoomResult, type UseYjsTextResult, type User, type UserCredits, type UserInfo, type UserKarma, type UserProfile, type ViewportClient, applyDeepSpaceTheme, applyUIThemeTokens, authClient, badgeVariants, buttonVariants, clearAuthToken, clearDeepSpaceTheme, clientBuild, cn, createDecoder, createEncoder, decodeAiStreamChunk, detectEnvironment, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, formatFileSize, formatFullTimestamp, formatMessageTime, getApiUrl, getAuthToken, getAuthUrl, getConversationDisplayName, getConversationParticipantIds, getEnvironmentConfig, getMessageType, getPlatformWorkerUrl, getThreadCounts, getUserColor, groupReactionsForMessage, handleAwarenessMessage, handleSyncMessage, hasContent, integration, isDMConversation, isDarkColor, isImageFile, isLocalDev, isProduction, parseMessageMetadata, parseSseLine, readThemeFromDOM, readVarUint, readVarUint8Array, resetEnvironmentCache, serverBuild, shouldGroupMessages, signIn, signOut, toConnectionStatus, toUint8Array, useAuth, useAuthUser, useCanvas, useChannelMembers, useChannels, useCheckout, useCommunities, useConversation, useConversations, useCronMonitor, useDisplayName, useGameRoom, useInbox, useIsDarkTheme, useJobs, useMessages, useMutations, usePlatform, usePlatformWS, usePosts, usePresence, usePresenceRoom, useQuery, useR2Files, useReactions, useReadReceipts, useRecordContext, useSession, useSubscription, useToast, useUser, useUserLookup, useUsers, useYjsField, useYjsRoom, useYjsText, writeVarUint, writeVarUint8Array };