deepspace 0.3.8 → 0.3.9

package/dist/worker.d.ts

@@ -1208,6 +1208,20 @@ declare const SYSTEM_MANAGED_COLUMNS: Set<string>;
 /** Standard user columns. Apps spread these into their users schema. */
 declare const USERS_COLUMNS: ColumnDefinition[];
 declare const BASE_USERS_SCHEMA: CollectionSchema;
+/**
+ * Lint a CollectionSchema for declarations that look like they should
+ * enforce something but don't, due to interactions between top-level
+ * fields (visibilityField, ownerField) and per-role permission levels.
+ *
+ * The SDK has historically silently accepted schemas that imply more
+ * enforcement than they actually deliver — e.g., `visibilityField` set
+ * but every role's `read: true` means "anyone can read everything"
+ * regardless of `visibility`. Warn loudly at registration so app
+ * authors notice before shipping a privacy bug.
+ *
+ * Returns an array of warning messages. Empty = clean.
+ */
+declare function lintSchema(schema: CollectionSchema): string[];
 declare class SchemaRegistry {
     private trusted;
     constructor(schemas?: CollectionSchema[]);
@@ -1341,6 +1355,7 @@ interface YjsAttachment extends UserAttachment {
 declare class YjsRoom<E = Record<string, unknown>> extends BaseRoom<E> {
     private doc;
     private initialized;
+    private awarenessStates;
     constructor(state: DurableObjectState, env: unknown);
     private ensureInitialized;
     private getDoc;
@@ -1354,6 +1369,9 @@ declare class YjsRoom<E = Record<string, unknown>> extends BaseRoom<E> {
     protected onDisconnect(ws: WebSocket, user: UserAttachment): void;
     private handleSync;
     private handleAwareness;
+    private readAwarenessUpdates;
+    private encodeAwarenessMessage;
+    private sendAwarenessSnapshot;
     private broadcastRaw;
 }
 
@@ -1550,6 +1568,12 @@ declare class PresenceRoom<E = Record<string, unknown>> extends BaseRoom<E> {
     private peers;
     private peerSockets;
     constructor(state: DurableObjectState, env: unknown);
+    /**
+     * Durable Objects can hibernate and clear heap while Cloudflare keeps
+     * WebSocket connections. Deserialize attachments from already-connected
+     * sockets so `peers` matches reality before we send PRESENCE_SYNC.
+     */
+    private hydratePeersFromLiveSockets;
     protected onConnect(ws: WebSocket, user: UserAttachment): PresenceAttachment;
     protected onMessage(ws: WebSocket, user: UserAttachment, message: {
         type: string;
@@ -2326,15 +2350,14 @@ interface GetActionData<T = Record<string, unknown>> {
 interface MutateActionData {
     recordId: string;
 }
-/** Shape of the data field for `tools.integration`. */
-interface IntegrationActionData<T = unknown> {
-    /** The integration endpoint's response body, parsed as JSON when possible. */
-    response: T;
-    /** HTTP status the api-worker forwarded back. */
-    status?: number;
-}
 interface ActionTools {
-    create<T extends Record<string, unknown> = Record<string, unknown>>(collection: string, data: T): Promise<ActionResult<MutateActionData>>;
+    /**
+     * Insert a new record. When `recordId` is omitted the DO generates one
+     * (typical). Pass `recordId` to upsert against a known key — useful
+     * for `users` where the row id must equal the auth user's id so
+     * `tools.get('users', userId)` resolves.
+     */
+    create<T extends Record<string, unknown> = Record<string, unknown>>(collection: string, data: T, recordId?: string): Promise<ActionResult<MutateActionData>>;
     update<T extends Record<string, unknown> = Record<string, unknown>>(collection: string, recordId: string, data: Partial<T>): Promise<ActionResult<MutateActionData>>;
     remove(collection: string, recordId: string): Promise<ActionResult<MutateActionData>>;
     get<T extends Record<string, unknown> = Record<string, unknown>>(collection: string, recordId: string): Promise<ActionResult<GetActionData<T>>>;
@@ -2344,8 +2367,41 @@ interface ActionTools {
         orderDir?: 'asc' | 'desc';
         limit?: number;
     }): Promise<ActionResult<QueryActionData<T>>>;
-    /** Call an integration endpoint (e.g. 'openai/completions') via the API worker */
-    integration<T = unknown>(endpoint: string, data?: unknown): Promise<ActionResult<IntegrationActionData<T>>>;
+    /**
+     * Call an integration endpoint (e.g. 'openai/chat-completion') via the
+     * api-worker. On success, `result.data` is the integration's response
+     * body directly — there is no `.response` wrapper. So an OpenAI call
+     * yields `result.data.choices`, a Freepik image call yields
+     * `result.data.images`, etc.
+     */
+    integration<T = unknown>(endpoint: string, data?: unknown): Promise<ActionResult<T>>;
+    /**
+     * Insert or refresh the `users` row for an authenticated caller.
+     * Mirrors the WS-connect registerUser flow — useful for CLI-only
+     * actions (e.g. publishing via `deepspace foo publish`) where the
+     * caller may never have opened the web app and has no `users` row
+     * yet. Bypasses SYSTEM_MANAGED column stripping so name/email/
+     * imageUrl are actually written.
+     *
+     * Defaults `userId` to the action's caller. Pass `isAdmin: true` only
+     * if the caller's platform-tier role is admin (worker.ts should
+     * derive this from the verified JWT — never trust client input).
+     */
+    registerUser(opts: {
+        userId?: string;
+        name?: string;
+        email?: string;
+        imageUrl?: string;
+        isAdmin?: boolean;
+    }): Promise<ActionResult<{
+        user: {
+            id: string;
+            name: string;
+            email: string;
+            imageUrl?: string;
+            role: string;
+        };
+    }>>;
 }
 /**
  * `TEnv` lets apps type the worker-scoped env object passed to the
@@ -2364,6 +2420,13 @@ interface ActionContext<TEnv = Record<string, unknown>> {
      * (e.g. for owner-only action gating).
      */
     env: TEnv;
+    /**
+     * The caller's raw JWT. Forward this on outbound requests that need to
+     * impersonate the user (e.g. checking `/api/apps` ownership on the
+     * deploy worker, where the user — not the app owner — should be billed
+     * / authorized).
+     */
+    callerJwt: string;
 }
 type ActionHandler<TEnv = Record<string, unknown>> = (ctx: ActionContext<TEnv>) => Promise<ActionResult>;
 
@@ -2401,7 +2464,7 @@ interface CronContext {
 interface CronEnv {
     RECORD_ROOMS: DurableObjectNamespace;
     INTERNAL_STORAGE_HMAC_SECRET?: string;
-    /** Override API base URL for local dev (defaults to https://api.deep.space) */
+    /** Override API base URL for local dev or custom platform deployments. */
     API_BASE_URL?: string;
 }
 /**
@@ -2570,6 +2633,56 @@ interface DeepSpaceAIOptions {
  */
 declare function createDeepSpaceAI(env: DeepSpaceAIEnv, provider: Provider, options?: DeepSpaceAIOptions): DeepSpaceModelFactory;
 
+/**
+ * captureScreenshot — call platform-worker /internal/screenshot.
+ *
+ * Apps don't ship CF Browser Rendering bindings or puppeteer in their
+ * own bundle. The platform holds the binding; consumers call this
+ * helper to get PNG bytes for a URL.
+ *
+ * The platform enforces: a host allowlist (*.app.space / *.deep.space),
+ * a per-app sliding rate limit, and viewport/timeout clamping. Returns
+ * `null` on any non-2xx — callers should treat as "no preview available"
+ * and surface their own fallback UX.
+ *
+ * Auth is the same HMAC-of-appName pattern `/internal/files` uses:
+ *   x-app-identity-token = hmac(PLATFORM_IDENTITY_SECRET, APP_NAME)
+ *   x-app-name           = APP_NAME
+ *
+ * Apps already have both as bindings (APP_IDENTITY_TOKEN + APP_NAME),
+ * so this helper is a thin wrapper — no extra secrets to manage.
+ */
+
+interface ScreenshotOptions {
+    url: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+    timeoutMs?: number;
+    fullPage?: boolean;
+}
+interface ScreenshotEnv extends PlatformWorkerEnv {
+    APP_NAME: string;
+    APP_IDENTITY_TOKEN: string;
+}
+interface ScreenshotResult {
+    /** PNG bytes. */
+    body: ArrayBuffer;
+    /** `image/png`. */
+    contentType: string;
+}
+/**
+ * Capture a screenshot of `opts.url` and return the PNG bytes.
+ *
+ * Returns null on capture failure (target unreachable, timeout, BR
+ * binding misconfigured platform-side). The platform endpoint logs the
+ * underlying error; callers should treat null as "no preview available"
+ * and surface their own UX fallback.
+ */
+declare function captureScreenshot(env: ScreenshotEnv, opts: ScreenshotOptions): Promise<ScreenshotResult | null>;
+
 /**
  * Chat context pipeline — keeps the per-request payload to the LLM bounded.
  *
@@ -2810,7 +2923,12 @@ declare function meterUsage(env: MeteringEnv, kind: string, fields?: {
  *
  * For a pure embedding call (outputChars=0), only the input event fires.
  * Pass `inputChars` and `outputChars` raw — the rough chars-to-token
- * conversion happens at price time using `COST_RATES.ai.embedPerChar`.
+ * conversion happens at price time using `COST_RATES.ai.embedInputPerChar`.
+ *
+ * Note: only embedding-input has an authoritative rate today. LLM-output
+ * pricing varies wildly per model so `priceBindingUsageEvent` returns 0
+ * for `op='output'` until per-model rates are wired. The events are still
+ * recorded so the dashboard can show that the calls happened.
  */
 declare function meterAi(env: MeteringEnv, model: string, fields?: {
     inputChars?: number;
@@ -2859,8 +2977,12 @@ declare function meterVectorize(env: MeteringEnv, indexName: string, op: 'query'
  */
 declare const COST_RATES: {
     readonly ai: {
-        /** USD per character (input or output). */
-        readonly perChar: number;
+        /**
+         * USD per character of *embedding input* (bge-m3 / qwen3-embedding tier).
+         * Renamed from `perChar` to make explicit that this rate does NOT
+         * apply to LLM-generation output — see `priceBindingUsageEvent`.
+         */
+        readonly embedInputPerChar: number;
     };
     readonly vectorize: {
         /** USD per queried dimension (per query, per stored vector compared). */
@@ -2869,6 +2991,20 @@ declare const COST_RATES: {
         readonly storedPerDimPerMonth: number;
     };
 };
+/**
+ * Price a single rolled-up `deepspace_binding_usage` row. Lives next to
+ * `COST_RATES` so the (kind, op) → rate mapping stays paired with the schema
+ * the meter helpers write.
+ *
+ * Returns 0 for combinations without an authoritative per-unit rate; the row
+ * still surfaces in dashboards for observability. Notable zeros:
+ *   - `ai/output`: LLM-output prices vary per model and `meterAi` doesn't
+ *     carry a model-family signal. Pricing it at the embedding rate would
+ *     silently under-bill chat-LLM use.
+ *   - `vectorize.storedPerDimPerMonth`: events are per-call deltas, not
+ *     monthly snapshots, so a windowed SUM isn't meaningful here.
+ */
+declare function priceBindingUsageEvent(kind: string, op: string, units: number): number;
 
 /**
  * Lightweight D1 schema bootstrapping for apps that use auto-provisioned
@@ -2949,7 +3085,7 @@ interface JwtVerifierConfig {
     publicKey: string;
     /** Expected issuer (e.g. "https://auth.deep.space") */
     issuer: string;
-    /** Expected audience (e.g. "https://api.deep.space") */
+    /** Expected audience (usually the configured platform API URL) */
     audience?: string | string[];
     /** Allowed origins / authorized parties (supports wildcards like "https://*.app.space") */
     authorizedParties?: string[];
@@ -3890,4 +4026,4 @@ type DeepSpaceAuth = ReturnType<typeof createDeepSpaceAuth>;
 /** Collections that bypass schema checks (permissive access) */
 declare const SYSTEM_COLLECTIONS: Set<string>;
 
-export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, Awareness, type AwarenessState, type AwarenessStates, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, type BaseMessage, BaseRoom, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CONVERSATION_SCHEMAS, COST_RATES, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type ClientMessage, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, type ConnectionAttachment, type ConvMemberData, type ConvMessageData, type ConvReactionData, type ConvReadCursorData, type ConvVoteData, type ConversationStateData, type CronContext, type CronExecution, CronRoom, type CronRoomConfig, type CronTask, type CustomBinding, type CustomBindingManifest, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DEFAULT_MAX_SKEW_MS, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DeepSpaceAIEnv, type DeepSpaceAIOptions, type DeepSpaceAuth, type DeepSpaceAuthConfig, type DirectoryCommunityData, type DirectoryConversationData, type DirectoryMembershipData, type DirectoryPostData, type DoMigrationDirective, type DoMigrationPlan, type ExistingDOBinding, GLOBAL_DO_TYPES, GLOBAL_DO_TYPE_NAMES, type GameInput, GameRoom, type GameRoomConfig, type GetActionData, type GlobalDOType, type HandlerContext, type IntegrationActionData, type InternalSignature, type JwtClaims, type JwtVerifierConfig, MESSAGES_SCHEMA, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MessageHandlers, type MsgType, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type ProtocolMessage, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_DEFAULT, RecordRoom, type RecordRoomConfig, type ResolvedColumn, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, SYSTEM_COLLECTIONS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ServerMessage, type SharedConnection, type SignInternalPayloadInput, type StoredRecord, type Summarizer, type SyncResult, type TokenDebugInfo, type ToolResult, type ToolSchema, USERS_COLUMNS, type User, type UserAttachment, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyInternalSignatureInput, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, buildCronContext, buildInternalPayload, buildTableSelect, buildUiParts, canCreate, canDelete, canRead, canUpdate, capToolResultSize, checkFieldPermissions, clientBuild, coerceValue, collectionTableName, columnId, computeDoMigration, computeHmacHex, createChat, createDecoder, createDeepSpaceAI, createDeepSpaceAuth, createEncoder, createScopedR2Handler, dataToColumnValues, decodeJwtPayload, deleteChatCascade, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, getChat, getGlobalDOSchemas, getGlobalDOType, getMessageType, getRolePermissions, handleAwarenessMessage, handleSyncMessage, hasContent, isAutoProvision, isOwner, loadMessages, makeDefaultSummarizer, meterAi, meterUsage, meterVectorize, noopPermissionContext, platformWorkerFetch, prepareMessagesWithCompaction, readVarUint, readVarUint8Array, resolveAppName, resolveColumn, rowToData, runMigrations, serverBuild, signInternalPayload, timingSafeEqualHex, toUint8Array, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppName, validateBindingManifest, validateDoManifest, verifyInternalSignature, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema, writeVarUint, writeVarUint8Array };
+export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, Awareness, type AwarenessState, type AwarenessStates, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, type BaseMessage, BaseRoom, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CONVERSATION_SCHEMAS, COST_RATES, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type ClientMessage, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, type ConnectionAttachment, type ConvMemberData, type ConvMessageData, type ConvReactionData, type ConvReadCursorData, type ConvVoteData, type ConversationStateData, type CronContext, type CronExecution, CronRoom, type CronRoomConfig, type CronTask, type CustomBinding, type CustomBindingManifest, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DEFAULT_MAX_SKEW_MS, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DeepSpaceAIEnv, type DeepSpaceAIOptions, type DeepSpaceAuth, type DeepSpaceAuthConfig, type DirectoryCommunityData, type DirectoryConversationData, type DirectoryMembershipData, type DirectoryPostData, type DoMigrationDirective, type DoMigrationPlan, type ExistingDOBinding, GLOBAL_DO_TYPES, GLOBAL_DO_TYPE_NAMES, type GameInput, GameRoom, type GameRoomConfig, type GetActionData, type GlobalDOType, type HandlerContext, type InternalSignature, type JwtClaims, type JwtVerifierConfig, MESSAGES_SCHEMA, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MessageHandlers, type MsgType, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type ProtocolMessage, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_DEFAULT, RecordRoom, type RecordRoomConfig, type ResolvedColumn, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, SYSTEM_COLLECTIONS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ScreenshotEnv, type ScreenshotOptions, type ScreenshotResult, type ServerMessage, type SharedConnection, type SignInternalPayloadInput, type StoredRecord, type Summarizer, type SyncResult, type TokenDebugInfo, type ToolResult, type ToolSchema, USERS_COLUMNS, type User, type UserAttachment, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyInternalSignatureInput, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, buildCronContext, buildInternalPayload, buildTableSelect, buildUiParts, canCreate, canDelete, canRead, canUpdate, capToolResultSize, captureScreenshot, checkFieldPermissions, clientBuild, coerceValue, collectionTableName, columnId, computeDoMigration, computeHmacHex, createChat, createDecoder, createDeepSpaceAI, createDeepSpaceAuth, createEncoder, createScopedR2Handler, dataToColumnValues, decodeJwtPayload, deleteChatCascade, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, getChat, getGlobalDOSchemas, getGlobalDOType, getMessageType, getRolePermissions, handleAwarenessMessage, handleSyncMessage, hasContent, isAutoProvision, isOwner, lintSchema, loadMessages, makeDefaultSummarizer, meterAi, meterUsage, meterVectorize, noopPermissionContext, platformWorkerFetch, prepareMessagesWithCompaction, priceBindingUsageEvent, readVarUint, readVarUint8Array, resolveAppName, resolveColumn, rowToData, runMigrations, serverBuild, signInternalPayload, timingSafeEqualHex, toUint8Array, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppName, validateBindingManifest, validateDoManifest, verifyInternalSignature, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema, writeVarUint, writeVarUint8Array };