deepspace 0.3.9 → 0.3.11

package/dist/index.d.ts

@@ -424,6 +424,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 +594,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;
@@ -685,6 +698,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 +875,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 +1118,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: {
@@ -5989,6 +6079,75 @@ interface UseCronMonitorResult {
 }
 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 +7553,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 };