@vertesia/client 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260804.124748Z

package/src/store/AgentsApi.ts

@@ -143,8 +143,8 @@ export class AgentsApi extends ApiTopic {
         }
         if (query?.interaction) params.interaction = query.interaction;
         if (query?.started_by) params.started_by = query.started_by;
-        if (query?.since) params.since = query.since.toISOString();
-        if (query?.until) params.until = query.until.toISOString();
+        if (query?.since) params.since = query.since;
+        if (query?.until) params.until = query.until;
         if (query?.schedule_id) params.schedule_id = query.schedule_id;
         if (query?.type) params.type = query.type;
         if (query?.run_type)
@@ -172,8 +172,8 @@ export class AgentsApi extends ApiTopic {
         if (query?.categories?.length) params.categories = query.categories.join(',');
         if (query?.tags?.length) params.tags = query.tags.join(',');
         if (query?.content_type_name) params.content_type_name = query.content_type_name;
-        if (query?.since) params.since = query.since.toISOString();
-        if (query?.until) params.until = query.until.toISOString();
+        if (query?.since) params.since = query.since;
+        if (query?.until) params.until = query.until;
         if (query?.limit) params.limit = String(query.limit);
         if (query?.offset) params.offset = String(query.offset);
         if (query?.sort?.length) params.sort = query.sort.join(',');
@@ -326,6 +326,10 @@ export class AgentsApi extends ApiTopic {
         let currentSse: EventSource | null = null;
         let interval: ReturnType<typeof setInterval> | null = null;
         let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+        let pollTimer: ReturnType<typeof setTimeout> | null = null;
+        let sseRetryTimer: ReturnType<typeof setTimeout> | null = null;
+        let isPolling = false;
+        let consecutivePollFailures = 0;
         let abortHandler: (() => void) | null = null;
 
         const maxReconnectAttempts = 10;
@@ -338,11 +342,24 @@ export class AgentsApi extends ApiTopic {
             return exponentialDelay + jitter;
         };
 
+        const stopPolling = () => {
+            isPolling = false;
+            if (pollTimer) {
+                clearTimeout(pollTimer);
+                pollTimer = null;
+            }
+            if (sseRetryTimer) {
+                clearTimeout(sseRetryTimer);
+                sseRetryTimer = null;
+            }
+        };
+
         const cleanup = () => {
             if (reconnectTimer) {
                 clearTimeout(reconnectTimer);
                 reconnectTimer = null;
             }
+            stopPolling();
             if (interval) {
                 clearInterval(interval);
                 interval = null;
@@ -372,52 +389,101 @@ export class AgentsApi extends ApiTopic {
         // for any messages we missed and exit cleanly once the run is terminal,
         // even if the terminal message never streamed.
         const POLL_INTERVAL_MS = 5000;
+        // Polling is a degraded mode: retry the real-time channel periodically so a transient
+        // outage (proxy restart, expired credentials that the auth callback later refreshes)
+        // does not permanently downgrade the stream.
+        const SSE_RETRY_INTERVAL_MS = 60000;
         const isTerminalStatus = (status: unknown): boolean =>
             typeof status === 'string' && ['completed', 'failed', 'cancelled'].includes(status);
-        const degradeToPolling = (reason: unknown) => {
-            if (isClosed) return;
-            cleanup();
+
+        // Never swallow a poll failure: while polling, it is the only channel left, so a silent
+        // catch turns a recoverable error (expired token, network blip) into an endless silence.
+        const warnPollFailure = (what: string, error: unknown) => {
+            consecutivePollFailures++;
             console.warn(
-                `Agent stream ${id}: SSE unavailable after ${maxReconnectAttempts} attempts; falling back to /updates polling.`,
-                reason instanceof Error ? reason.message : reason,
+                `Agent stream ${id}: ${what} failed while polling (consecutive failures: ${consecutivePollFailures}); retrying in ${Math.round(POLL_INTERVAL_MS / 1000)}s:`,
+                error instanceof Error ? error.message : error,
             );
-            const tick = async () => {
-                if (isClosed) return;
-                try {
-                    const recent = await this.retrieveMessages(id, lastMessageTimestamp || undefined);
-                    for (const msg of recent) {
-                        if (isClosed) return;
-                        if ((msg.timestamp || 0) <= lastMessageTimestamp) continue;
-                        lastMessageTimestamp = msg.timestamp || lastMessageTimestamp;
-                        if (onMessage) onMessage(msg, exit);
-                        if (isClosed) return;
-                        if (shouldCloseAgentRunStream(msg, id)) {
-                            exit(null);
-                            return;
-                        }
-                    }
-                } catch {
-                    // transient poll error — retry next tick
-                }
-                if (isClosed) return;
-                // Exit even when no terminal message ever streams, by reading the run record.
-                try {
-                    const run = (await this.get(`/${id}`)) as { status?: unknown };
-                    if (isTerminalStatus(run?.status)) {
+        };
+
+        const pollTick = async () => {
+            if (isClosed || !isPolling) return;
+            let polledMessages = false;
+            try {
+                // Resume from the last message we handed to the caller, whether it came from
+                // history, SSE, or an earlier poll. The server returns messages with ts > since.
+                const recent = await this.retrieveMessages(id, lastMessageTimestamp || undefined);
+                polledMessages = true;
+                for (const msg of recent) {
+                    if (isClosed) return;
+                    const timestamp = msg.timestamp || 0;
+                    if (timestamp <= lastMessageTimestamp) continue;
+                    lastMessageTimestamp = timestamp;
+                    if (onMessage) onMessage(msg, exit);
+                    if (isClosed) return;
+                    if (shouldCloseAgentRunStream(msg, id)) {
                         exit(null);
                         return;
                     }
-                } catch {
-                    // ignore — retry next tick
                 }
-                if (!isClosed) {
-                    reconnectTimer = setTimeout(() => {
-                        reconnectTimer = null;
-                        void tick();
-                    }, POLL_INTERVAL_MS);
+            } catch (err) {
+                warnPollFailure('GET /updates', err);
+            }
+            if (isClosed || !isPolling) return;
+            // Exit even when no terminal message ever streams, by reading the run record.
+            try {
+                const run = (await this.get(`/${id}`)) as { status?: unknown };
+                if (isTerminalStatus(run?.status)) {
+                    exit(null);
+                    return;
                 }
-            };
-            void tick();
+                if (polledMessages) consecutivePollFailures = 0;
+            } catch (err) {
+                warnPollFailure('run status check', err);
+            }
+            if (isClosed || !isPolling) return;
+            pollTimer = setTimeout(() => {
+                pollTimer = null;
+                void pollTick();
+            }, POLL_INTERVAL_MS);
+        };
+
+        const retrySseAfterPolling = () => {
+            sseRetryTimer = null;
+            if (isClosed || !isPolling) return;
+            stopPolling();
+            reconnectAttempts = 0;
+            console.log(`Agent stream ${id}: retrying the SSE connection after the polling fallback.`);
+            void setupStream('resume');
+        };
+
+        const degradeToPolling = (reason: unknown) => {
+            if (isClosed || isPolling) return;
+            cleanup();
+            isPolling = true;
+            consecutivePollFailures = 0;
+            console.warn(
+                `Agent stream ${id}: SSE unavailable after ${maxReconnectAttempts} attempts; falling back to GET /updates polling every ${Math.round(POLL_INTERVAL_MS / 1000)}s (SSE retried every ${Math.round(SSE_RETRY_INTERVAL_MS / 1000)}s).`,
+                reason instanceof Error ? reason.message : reason,
+            );
+            sseRetryTimer = setTimeout(retrySseAfterPolling, SSE_RETRY_INTERVAL_MS);
+            void pollTick();
+        };
+
+        // Schedules attempt N of `maxReconnectAttempts`. `reconnectAttempts` holds the number of
+        // the attempt about to run, so the announced counter never exceeds the announced maximum.
+        const scheduleReconnect = (reason: unknown) => {
+            if (isClosed) return;
+            if (reconnectAttempts >= maxReconnectAttempts) {
+                degradeToPolling(reason);
+                return;
+            }
+            const delay = calculateBackoffDelay(reconnectAttempts);
+            reconnectAttempts++;
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = null;
+                if (!isClosed) void setupStream('reconnect');
+            }, delay);
         };
 
         if (signal) {
@@ -468,7 +534,7 @@ export class AgentsApi extends ApiTopic {
         }
 
         // 2. Connect to SSE for real-time updates
-        const setupStream = async (isReconnect: boolean = false) => {
+        const setupStream = async (mode: 'initial' | 'reconnect' | 'resume' = 'initial') => {
             if (isClosed) return;
             try {
                 const EventSourceImpl = await EventSourceProvider();
@@ -481,6 +547,10 @@ export class AgentsApi extends ApiTopic {
                 }
                 streamUrl.searchParams.set('skipHistory', 'true');
 
+                // Resolve the credential on every attempt (never reuse the one captured when the
+                // stream started): a stream can stay open far longer than the access token TTL,
+                // so a pinned token makes every reconnect fail with 401/403 until the retry
+                // budget is exhausted. The auth callback owns refreshing.
                 const bearerToken = client._auth ? await client._auth() : undefined;
                 if (isClosed) return;
                 if (!bearerToken) {
@@ -493,9 +563,9 @@ export class AgentsApi extends ApiTopic {
                 const token = bearerToken.split(' ')[1];
                 streamUrl.searchParams.set('access_token', token);
 
-                if (isReconnect) {
+                if (mode === 'reconnect') {
                     console.log(
-                        `Reconnecting to agent stream ${id} (attempt ${reconnectAttempts + 1}/${maxReconnectAttempts})`,
+                        `Reconnecting to agent stream ${id} (attempt ${reconnectAttempts}/${maxReconnectAttempts})`,
                     );
                 }
 
@@ -507,7 +577,7 @@ export class AgentsApi extends ApiTopic {
                 let connectionOpenedAt = 0;
 
                 sse.onopen = () => {
-                    if (isReconnect) console.log(`Reconnected to agent stream ${id}`);
+                    if (mode !== 'initial') console.log(`Reconnected to agent stream ${id}`);
                     connectionOpenedAt = Date.now();
                 };
 
@@ -549,35 +619,17 @@ export class AgentsApi extends ApiTopic {
                         reconnectAttempts = 0;
                     }
 
-                    if (reconnectAttempts < maxReconnectAttempts) {
-                        const delay = calculateBackoffDelay(reconnectAttempts);
-                        reconnectAttempts++;
-                        reconnectTimer = setTimeout(() => {
-                            reconnectTimer = null;
-                            if (!isClosed) void setupStream(true);
-                        }, delay);
-                    } else {
-                        degradeToPolling(
-                            new Error(`SSE connection failed after ${maxReconnectAttempts} reconnection attempts`),
-                        );
-                    }
+                    scheduleReconnect(
+                        new Error(`SSE connection failed after ${maxReconnectAttempts} reconnection attempts`),
+                    );
                 };
             } catch (err) {
                 if (isClosed) return;
-                if (reconnectAttempts < maxReconnectAttempts) {
-                    const delay = calculateBackoffDelay(reconnectAttempts);
-                    reconnectAttempts++;
-                    reconnectTimer = setTimeout(() => {
-                        reconnectTimer = null;
-                        if (!isClosed) void setupStream(true);
-                    }, delay);
-                } else {
-                    degradeToPolling(err);
-                }
+                scheduleReconnect(err);
             }
         };
 
-        void setupStream(false);
+        void setupStream('initial');
         return promise;
     }
 

package/src/store/ObjectsApi.ts

@@ -1,7 +1,9 @@
 import { ApiTopic } from '@vertesia/api-fetch-client';
 import {
+    type BulkObjectCreateOptions,
     type BulkObjectCreateResult,
     type BulkObjectDeleteResult,
+    type BulkObjectUpdateOptions,
     type BulkObjectUpdateResult,
     type Collection,
     type ComplexSearchPayload,
@@ -458,23 +460,21 @@ export class ObjectsApi extends ApiTopic {
         return this.del(`/${idOrIds}`);
     }
 
-    bulkUpdate(updates: Record<string, Record<string, unknown>>): Promise<BulkObjectUpdateResult> {
+    bulkUpdate(
+        updates: Record<string, Record<string, unknown>>,
+        options?: BulkObjectUpdateOptions,
+    ): Promise<BulkObjectUpdateResult> {
         const ids = Object.keys(updates);
         return this.client.runOperation({
             name: 'update',
             ids,
-            params: updates,
+            params: options ? { updates, ...options } : updates,
         }) as Promise<BulkObjectUpdateResult>;
     }
 
     bulkCreate(
         objects: CreateContentObjectPayload[],
-        options?: {
-            collection_id?: string;
-            /** @deprecated Events are now always emitted. This suppresses the Temporal-backed delivery targets (workflow, agent, and process) — webhook deliveries still fire. */
-            skip_workflows?: boolean;
-            processing_priority?: ContentObjectProcessingPriority;
-        },
+        options?: BulkObjectCreateOptions,
     ): Promise<BulkObjectCreateResult> {
         return this.client.runOperation({
             name: 'create',

package/src/store/TaskApi.ts

@@ -6,17 +6,17 @@ export class TaskApi extends ApiTopic {
         super(parent, '/api/v1/tasks');
     }
 
-    list(query?: ListTasksQuery): Promise<Task[]> {
-        const params: Record<string, string> = {};
-        if (query?.status) {
-            params.status = Array.isArray(query.status) ? query.status.join(',') : query.status;
-        }
-        if (query?.assignee) params.assignee = query.assignee;
-        if (query?.run_id) params.run_id = query.run_id;
-        if (query?.source_type) params.source_type = query.source_type;
-        if (query?.limit != null) params.limit = String(query.limit);
-        if (query?.offset != null) params.offset = String(query.offset);
-        return this.get('/', { query: params });
+    /**
+     * Lists tasks.
+     *
+     * `status` accepts one value or several, and several go out as a repeated key
+     * (`status=a&status=b`) — which is what the parameter publishes: `style: form`, `explode: true`.
+     * This used to comma-join the array before sending it. Servers still split each occurrence on
+     * commas so SDKs pinned to an older version keep working, but that form was never in the spec,
+     * so newly published clients send the declared one.
+     */
+    list(query: ListTasksQuery = {}): Promise<Task[]> {
+        return this.get('/', { query });
     }
 
     retrieve(id: string): Promise<Task> {

package/src/store/TypeCatalogApi.ts

@@ -1,5 +1,5 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
-import type { ContentObjectTypeItem, ContentObjectTypeRef } from '@vertesia/common';
+import type { ContentObjectTypeCatalogEntry, ContentObjectTypeItem, ContentObjectTypeRef } from '@vertesia/common';
 
 export class TypeCatalogApi extends ApiTopic {
     constructor(parent: ClientBase) {
@@ -7,18 +7,22 @@ export class TypeCatalogApi extends ApiTopic {
     }
 
     /**
-     * List all content types (system + app + stored)
+     * List all content types (system + app + stored).
+     *
+     * Returns `ContentObjectTypeCatalogEntry`, not `ContentObjectTypeItem`, for the same reason
+     * {@link resolve} does: the listing includes system and app types, which are declared in code
+     * rather than authored, so they carry none of the four audit fields.
      */
     list(
         query: { tag?: string; limit?: number; offset?: number; layout?: boolean; schema?: boolean } = {},
-    ): Promise<ContentObjectTypeItem[]> {
+    ): Promise<ContentObjectTypeCatalogEntry[]> {
         return this.get('/', { query });
     }
 
     /**
      * List system types only
      */
-    listSysTypes(tag?: string): Promise<ContentObjectTypeItem[]> {
+    listSysTypes(tag?: string): Promise<ContentObjectTypeCatalogEntry[]> {
         return this.get('/sys', {
             query: { tag },
         });
@@ -27,14 +31,17 @@ export class TypeCatalogApi extends ApiTopic {
     /**
      * List all app types from all installed apps
      */
-    listAppTypes(tag?: string): Promise<ContentObjectTypeItem[]> {
+    listAppTypes(tag?: string): Promise<ContentObjectTypeCatalogEntry[]> {
         return this.get('/apps', {
             query: { tag },
         });
     }
 
     /**
-     * List stored types only
+     * List stored types only.
+     *
+     * Stored types are real records, so this one does return `ContentObjectTypeItem` with its audit
+     * fields required.
      */
     listStoredTypes(
         query: { tag?: string; limit?: number; offset?: number; layout?: boolean; schema?: boolean } = {},
@@ -47,9 +54,16 @@ export class TypeCatalogApi extends ApiTopic {
     /**
      * Resolve a type to its full definition.
      * Accepts a string (type ID or code) or a ContentObjectTypeRef.
+     *
+     * Returns a `ContentObjectTypeCatalogEntry`, which is what the endpoint publishes and is NOT
+     * `ContentObjectTypeItem`: the catalog resolves in-code types contributed by plugins, which no
+     * user created and no user has modified, so its four audit fields are optional. Declaring the
+     * stored type here told callers `created_by` was always a string when resolving `sys:Invoice`
+     * hands back a record that has none.
+     *
      * @param typeOrRef Type identifier string, or a ContentObjectTypeRef from a content object
      */
-    resolve(typeOrRef: string | ContentObjectTypeRef): Promise<ContentObjectTypeItem> {
+    resolve(typeOrRef: string | ContentObjectTypeRef): Promise<ContentObjectTypeCatalogEntry> {
         const typeId = typeof typeOrRef === 'string' ? typeOrRef : typeOrRef.id;
         return this.get(`/resolve/${typeId}`);
     }

package/src/store/TypesApi.ts

@@ -6,6 +6,7 @@ import type {
     FindPayload,
     ObjectTypeSearchPayload,
     ObjectTypeSearchQuery,
+    UpdateContentObjectTypePayload,
 } from '@vertesia/common';
 import { TypeCatalogApi } from './TypeCatalogApi.js';
 
@@ -58,7 +59,7 @@ export class TypesApi extends ApiTopic {
         return this.get(`/name/${typeName}`);
     }
 
-    update(typeId: string, payload: Partial<CreateContentObjectTypePayload>): Promise<ContentObjectType> {
+    update(typeId: string, payload: UpdateContentObjectTypePayload): Promise<ContentObjectType> {
         return this.put(`/${typeId}`, {
             payload,
         });

package/src/store/version.ts

@@ -1,3 +1,4 @@
 export const VERSION = '20260319'; // YYYYMMDD, client versioning for API endpoints. Increment manually for breaking changes
-export const VERSION_HEADER = 'x-api-version';
-export { APP_VERSION_HEADER } from '@vertesia/common';
+// Re-exported, not redeclared: the servers read the same constant when deciding how strictly to
+// hold a request to its schema, so a name only this side knew could not stay a negotiation.
+export { APP_VERSION_HEADER, VERSION_HEADER } from '@vertesia/common';