@sprinterai/runtime 0.6.0 → 0.8.0

package/dist/feed/ranking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.js","sourceRoot":"","sources":["../../src/feed/ranking.ts"],"names":[],"mappings":"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"}

package/dist/feed/resolver.d.ts

@@ -0,0 +1,76 @@
+import type { ActivityStore } from '@sprinterai/core';
+import type { FeedConfig, FeedItem } from './types.js';
+/**
+ * Resolve a personalized feed for a user.
+ *
+ * Main entry point for feed resolution. Queries activities from storage,
+ * applies filtering and ranking based on configuration, and returns ordered items.
+ *
+ * Flow:
+ * 1. Validate parameters (limits, thresholds)
+ * 2. Query activities from store with filters
+ * 3. Convert ActivityRecords to FeedItems
+ * 4. Apply ranking based on tab type ('for-you', 'all', 'digest')
+ * 5. Sort by score/time
+ * 6. Return final items
+ *
+ * Storage-agnostic: works with any ActivityStore implementation.
+ *
+ * @param store ActivityStore implementation
+ * @param config Feed configuration (filters, limits, personalization)
+ * @returns Array of FeedItems sorted by relevance (for-you) or recency (all/digest)
+ * @throws Error if store query fails
+ */
+export declare function resolveFeed(store: ActivityStore, config: FeedConfig): Promise<FeedItem[]>;
+/**
+ * Resolve feed with time-based filtering.
+ *
+ * Convenience wrapper around resolveFeed that automatically adds time range filtering.
+ * Queries activities created after the start of the specified time window.
+ *
+ * @param store ActivityStore implementation
+ * @param config Feed configuration
+ * @returns Array of FeedItems within the time range
+ */
+export declare function resolveFeedWithTimeFilter(store: ActivityStore, config: FeedConfig): Promise<FeedItem[]>;
+/**
+ * Paginate through feed items using cursor-based pagination.
+ *
+ * Convenience helper for implementing pagination in UIs.
+ * Returns items before the given cursor (ISO timestamp).
+ *
+ * Usage:
+ * ```
+ * const page1 = await resolveFeedPage(store, config); // First page
+ * const page2 = await resolveFeedPage(store, {
+ *   ...config,
+ *   before: page1[page1.length - 1].createdAt, // Use last item as cursor
+ * }); // Next page
+ * ```
+ *
+ * @param store ActivityStore implementation
+ * @param config Feed configuration with optional 'before' cursor
+ * @returns Array of FeedItems for this page
+ */
+export declare function resolveFeedPage(store: ActivityStore, config: FeedConfig): Promise<FeedItem[]>;
+/**
+ * Build a feed update delta for real-time feeds.
+ *
+ * Compares old feed state with new state and returns only changed items.
+ * Useful for real-time updates without re-rendering entire feed.
+ *
+ * Returns an object with:
+ * - added: Items in new but not in old
+ * - removed: Items in old but not in new
+ * - updated: Items that changed (same id, different fields)
+ *
+ * @param oldItems Previous feed state
+ * @param newItems Current feed state
+ * @returns Delta with added/removed/updated items
+ */
+export declare function buildFeedDelta(oldItems: FeedItem[], newItems: FeedItem[]): {
+    added: FeedItem[];
+    removed: FeedItem[];
+    updated: FeedItem[];
+};
+//# sourceMappingURL=resolver.d.ts.map

package/dist/feed/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/feed/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKtD,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAmE/F;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAgBrB;AA+BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAErB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,QAAQ,EAAE,EACpB,QAAQ,EAAE,QAAQ,EAAE,GACnB;IACD,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,OAAO,EAAE,QAAQ,EAAE,CAAC;CACrB,CAeA"}

package/dist/feed/resolver.js

@@ -0,0 +1,173 @@
+import { getTimeRangeStart, validateFeedParams } from './filters.js';
+import { computeForYouScores, sortByScore } from './ranking.js';
+import { rowsToFeedItems } from './transformers.js';
+/**
+ * Resolve a personalized feed for a user.
+ *
+ * Main entry point for feed resolution. Queries activities from storage,
+ * applies filtering and ranking based on configuration, and returns ordered items.
+ *
+ * Flow:
+ * 1. Validate parameters (limits, thresholds)
+ * 2. Query activities from store with filters
+ * 3. Convert ActivityRecords to FeedItems
+ * 4. Apply ranking based on tab type ('for-you', 'all', 'digest')
+ * 5. Sort by score/time
+ * 6. Return final items
+ *
+ * Storage-agnostic: works with any ActivityStore implementation.
+ *
+ * @param store ActivityStore implementation
+ * @param config Feed configuration (filters, limits, personalization)
+ * @returns Array of FeedItems sorted by relevance (for-you) or recency (all/digest)
+ * @throws Error if store query fails
+ */
+export async function resolveFeed(store, config) {
+    const { tab = 'all', entityId, actorId, action, limit, before, userId, includeImportance = true, importanceWeight = 1.0, recencyWeight = 1.0, } = config;
+    // Validate parameters
+    const { limit: safeLimit } = validateFeedParams(limit);
+    // Build activity query options
+    const queryOptions = {
+        limit: safeLimit,
+        entityId,
+        actorId,
+        action,
+        before,
+    };
+    // Query activities from store
+    const records = await store.listActivities(queryOptions);
+    if (records.length === 0) {
+        return [];
+    }
+    // Convert to FeedItems with default scores
+    let feedItems = rowsToFeedItems(records);
+    // Apply ranking if 'for-you' tab
+    if (tab === 'for-you' && userId) {
+        const now = new Date();
+        feedItems = feedItems.map((item) => {
+            const score = computeForYouScores({
+                createdAt: item.createdAt,
+                metadata: item.metadata,
+                importance: includeImportance ? extractImportanceFromMetadata(item.metadata) : undefined,
+                now,
+                recencyWeight,
+                importanceWeight,
+            });
+            return {
+                ...item,
+                score,
+            };
+        });
+        // Sort by score (highest first)
+        feedItems = sortByScore(feedItems);
+    }
+    else if (tab === 'all' || tab === 'digest') {
+        // Sort by creation time (most recent first)
+        feedItems = feedItems.sort((a, b) => {
+            const timeA = new Date(a.createdAt).getTime();
+            const timeB = new Date(b.createdAt).getTime();
+            return timeB - timeA; // Descending (most recent first)
+        });
+    }
+    return feedItems;
+}
+/**
+ * Resolve feed with time-based filtering.
+ *
+ * Convenience wrapper around resolveFeed that automatically adds time range filtering.
+ * Queries activities created after the start of the specified time window.
+ *
+ * @param store ActivityStore implementation
+ * @param config Feed configuration
+ * @returns Array of FeedItems within the time range
+ */
+export async function resolveFeedWithTimeFilter(store, config) {
+    // Get time range start (if specified)
+    const timeRange = config.timeRange ?? 'week';
+    const startISO = getTimeRangeStart(timeRange);
+    // Query returns items created BEFORE the 'before' cursor
+    // To filter by time range, we don't use 'before' -- the store returns
+    // recent items by default (or we trust the store's ordering).
+    // If we want to enforce a time window, consumers can add this logic:
+    // After fetching, filter out items older than startISO
+    const items = await resolveFeed(store, config);
+    // Filter by time range
+    const startTime = new Date(startISO).getTime();
+    return items.filter((item) => new Date(item.createdAt).getTime() >= startTime);
+}
+/**
+ * Extract importance value from activity metadata.
+ * Looks for 'importance' or 'priority' fields (numeric or string).
+ *
+ * @param metadata Activity metadata
+ * @returns Importance value (number, string) or null
+ */
+function extractImportanceFromMetadata(metadata) {
+    if (!metadata)
+        return null;
+    if ('importance' in metadata) {
+        const imp = metadata.importance;
+        if (typeof imp === 'number' || typeof imp === 'string') {
+            return imp;
+        }
+    }
+    if ('priority' in metadata) {
+        const pri = metadata.priority;
+        if (typeof pri === 'number' || typeof pri === 'string') {
+            return pri;
+        }
+    }
+    return null;
+}
+/**
+ * Paginate through feed items using cursor-based pagination.
+ *
+ * Convenience helper for implementing pagination in UIs.
+ * Returns items before the given cursor (ISO timestamp).
+ *
+ * Usage:
+ * ```
+ * const page1 = await resolveFeedPage(store, config); // First page
+ * const page2 = await resolveFeedPage(store, {
+ *   ...config,
+ *   before: page1[page1.length - 1].createdAt, // Use last item as cursor
+ * }); // Next page
+ * ```
+ *
+ * @param store ActivityStore implementation
+ * @param config Feed configuration with optional 'before' cursor
+ * @returns Array of FeedItems for this page
+ */
+export async function resolveFeedPage(store, config) {
+    return resolveFeed(store, config);
+}
+/**
+ * Build a feed update delta for real-time feeds.
+ *
+ * Compares old feed state with new state and returns only changed items.
+ * Useful for real-time updates without re-rendering entire feed.
+ *
+ * Returns an object with:
+ * - added: Items in new but not in old
+ * - removed: Items in old but not in new
+ * - updated: Items that changed (same id, different fields)
+ *
+ * @param oldItems Previous feed state
+ * @param newItems Current feed state
+ * @returns Delta with added/removed/updated items
+ */
+export function buildFeedDelta(oldItems, newItems) {
+    const oldIds = new Map(oldItems.map((item) => [item.id, item]));
+    const newIds = new Map(newItems.map((item) => [item.id, item]));
+    const added = newItems.filter((item) => !oldIds.has(item.id));
+    const removed = oldItems.filter((item) => !newIds.has(item.id));
+    const updated = newItems.filter((newItem) => {
+        const oldItem = oldIds.get(newItem.id);
+        if (!oldItem)
+            return false;
+        // Check if any field changed (shallow comparison)
+        return JSON.stringify(oldItem) !== JSON.stringify(newItem);
+    });
+    return { added, removed, updated };
+}
+//# sourceMappingURL=resolver.js.map

package/dist/feed/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/feed/resolver.ts"],"names":[],"mappings":"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"}

package/dist/feed/transformers.d.ts

@@ -0,0 +1,80 @@
+import type { ActivityRecord } from '@sprinterai/core';
+import type { FeedItem } from './types.js';
+/**
+ * Transform an ActivityRecord to a FeedItem.
+ * Converts storage format to display format with score and preview.
+ *
+ * This is the primary transformer for converting database records to feed display items.
+ * It handles:
+ * - Name extraction from metadata (entity and actor names)
+ * - Score defaulting (if not provided)
+ * - Preview text generation
+ * - Type-safe field mapping
+ *
+ * @param record Activity record from storage
+ * @param score Ranking score (0-1), defaults to 0.5
+ * @param entityName Optional entity name to override metadata lookup
+ * @param actorName Optional actor name to override metadata lookup
+ * @returns FeedItem ready for display
+ */
+export declare function rowToFeedItem(record: ActivityRecord, score?: number, entityName?: string, actorName?: string): FeedItem;
+/**
+ * Transform multiple ActivityRecords to FeedItems.
+ * Convenience bulk version of rowToFeedItem.
+ *
+ * @param records Activity records from storage
+ * @param scores Optional array of scores (must match records length if provided)
+ * @returns Array of FeedItems
+ */
+export declare function rowsToFeedItems(records: ActivityRecord[], scores?: number[]): FeedItem[];
+/**
+ * Extract preview text for display in feed items.
+ * Creates a short human-readable summary of the activity.
+ *
+ * Priority:
+ * 1. If description exists, use it (typically for comments, detailed updates)
+ * 2. If metadata.preview exists, use it (pre-computed display text)
+ * 3. Generate from metadata.field + old/new values (for field changes)
+ * 4. Generate from action type (INSERT → "created", UPDATE → "updated", etc)
+ * 5. Default fallback text
+ *
+ * The preview is typically 1-2 lines and used in list views.
+ *
+ * @param record Activity record
+ * @returns Preview text suitable for display
+ */
+export declare function extractFeedPreview(record: ActivityRecord): string;
+/**
+ * Extract actor display info from record.
+ * Returns name and type suitable for avatar and label display.
+ *
+ * @param record Activity record
+ * @returns Object with name and type for display
+ */
+export declare function extractActorDisplay(record: ActivityRecord): {
+    name: string;
+    type: 'user' | 'agent' | 'system';
+};
+/**
+ * Extract entity display info from record.
+ * Returns name and type suitable for label and badge display.
+ *
+ * @param record Activity record
+ * @returns Object with name and type for display
+ */
+export declare function extractEntityDisplay(record: ActivityRecord): {
+    name?: string;
+    type?: string;
+};
+/**
+ * Format activity for plain text output (logs, exports, etc).
+ * Creates a one-line summary suitable for text-based feeds.
+ *
+ * Format: "[Actor] [action] [entity] at [time]"
+ * Example: "Alice updated Project ABC at 2:45 PM"
+ *
+ * @param record Activity record
+ * @returns Plain text summary
+ */
+export declare function formatActivityPlainText(record: ActivityRecord): string;
+//# sourceMappingURL=transformers.d.ts.map

package/dist/feed/transformers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformers.d.ts","sourceRoot":"","sources":["../../src/feed/transformers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQxC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,EACtB,KAAK,GAAE,MAAsB,EAC7B,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,QAAQ,CAgCV;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,CAKxF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAmCjE;AAwBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;CACnC,CAUA;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAQA;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAYtE"}

package/dist/feed/transformers.js

@@ -0,0 +1,179 @@
+/**
+ * Default score when no ranking has been applied yet.
+ * Used as fallback for items not yet ranked.
+ */
+const DEFAULT_SCORE = 0.5;
+/**
+ * Transform an ActivityRecord to a FeedItem.
+ * Converts storage format to display format with score and preview.
+ *
+ * This is the primary transformer for converting database records to feed display items.
+ * It handles:
+ * - Name extraction from metadata (entity and actor names)
+ * - Score defaulting (if not provided)
+ * - Preview text generation
+ * - Type-safe field mapping
+ *
+ * @param record Activity record from storage
+ * @param score Ranking score (0-1), defaults to 0.5
+ * @param entityName Optional entity name to override metadata lookup
+ * @param actorName Optional actor name to override metadata lookup
+ * @returns FeedItem ready for display
+ */
+export function rowToFeedItem(record, score = DEFAULT_SCORE, entityName, actorName) {
+    const safeScore = Math.max(0, Math.min(1, score));
+    // Extract entity name from metadata if not provided
+    const finalEntityName = entityName ??
+        (typeof record.metadata?.entityName === 'string' ? record.metadata.entityName : undefined);
+    // Extract actor name from metadata if not provided
+    const finalActorName = actorName ??
+        (typeof record.metadata?.actorName === 'string' ? record.metadata.actorName : undefined);
+    // Generate preview text
+    const preview = extractFeedPreview(record);
+    return {
+        id: record.id,
+        entityId: record.entity_id,
+        entityTypeSlug: record.entity_type_slug,
+        entityName: finalEntityName,
+        action: record.action,
+        description: record.description,
+        actorId: record.actor_id,
+        actorName: finalActorName,
+        actorType: record.actor_type,
+        metadata: record.metadata,
+        createdAt: record.created_at,
+        score: safeScore,
+        preview,
+        tenantId: record.tenant_id,
+    };
+}
+/**
+ * Transform multiple ActivityRecords to FeedItems.
+ * Convenience bulk version of rowToFeedItem.
+ *
+ * @param records Activity records from storage
+ * @param scores Optional array of scores (must match records length if provided)
+ * @returns Array of FeedItems
+ */
+export function rowsToFeedItems(records, scores) {
+    return records.map((record, index) => {
+        const score = scores ? (scores[index] ?? DEFAULT_SCORE) : DEFAULT_SCORE;
+        return rowToFeedItem(record, score);
+    });
+}
+/**
+ * Extract preview text for display in feed items.
+ * Creates a short human-readable summary of the activity.
+ *
+ * Priority:
+ * 1. If description exists, use it (typically for comments, detailed updates)
+ * 2. If metadata.preview exists, use it (pre-computed display text)
+ * 3. Generate from metadata.field + old/new values (for field changes)
+ * 4. Generate from action type (INSERT → "created", UPDATE → "updated", etc)
+ * 5. Default fallback text
+ *
+ * The preview is typically 1-2 lines and used in list views.
+ *
+ * @param record Activity record
+ * @returns Preview text suitable for display
+ */
+export function extractFeedPreview(record) {
+    // Use description if available (comments, detailed changes)
+    if (record.description) {
+        return record.description.slice(0, 200); // Cap at 200 chars
+    }
+    // Check metadata for pre-computed preview
+    if (typeof record.metadata?.preview === 'string') {
+        return record.metadata.preview.slice(0, 200);
+    }
+    // Generate from field change data
+    if (record.metadata &&
+        typeof record.metadata.field === 'string' &&
+        record.metadata.oldValue !== undefined &&
+        record.metadata.newValue !== undefined) {
+        const oldVal = String(record.metadata.oldValue).slice(0, 50);
+        const newVal = String(record.metadata.newValue).slice(0, 50);
+        return `${record.metadata.field}: ${oldVal} → ${newVal}`;
+    }
+    // Generate from action type
+    const actionLabel = getActionLabel(record.action);
+    if (actionLabel !== record.action) {
+        // We have a better label
+        if (record.entity_type_slug) {
+            return `${actionLabel} ${record.entity_type_slug}`;
+        }
+        return actionLabel;
+    }
+    // Fallback
+    return record.action.toLowerCase();
+}
+/**
+ * Get human-readable label for an action type.
+ * Maps database action codes to display labels.
+ *
+ * @param action Action code (INSERT, UPDATE, DELETE, etc)
+ * @returns Display label
+ */
+function getActionLabel(action) {
+    const labels = {
+        INSERT: 'Created',
+        UPDATE: 'Updated',
+        DELETE: 'Deleted',
+        comment: 'Commented',
+        status_change: 'Changed status',
+        assigned: 'Assigned',
+        shared: 'Shared',
+        unshared: 'Unshared',
+    };
+    return labels[action] ?? action;
+}
+/**
+ * Extract actor display info from record.
+ * Returns name and type suitable for avatar and label display.
+ *
+ * @param record Activity record
+ * @returns Object with name and type for display
+ */
+export function extractActorDisplay(record) {
+    // Prefer metadata.actorName
+    const nameFromMeta = typeof record.metadata?.actorName === 'string' ? record.metadata.actorName : null;
+    const name = nameFromMeta ?? record.actor_id ?? 'System';
+    const type = record.actor_type === 'user' || record.actor_type === 'agent' ? record.actor_type : 'system';
+    return { name, type };
+}
+/**
+ * Extract entity display info from record.
+ * Returns name and type suitable for label and badge display.
+ *
+ * @param record Activity record
+ * @returns Object with name and type for display
+ */
+export function extractEntityDisplay(record) {
+    const nameFromMeta = typeof record.metadata?.entityName === 'string' ? record.metadata.entityName : null;
+    return {
+        name: nameFromMeta ?? record.entity_id ?? undefined,
+        type: record.entity_type_slug ?? undefined,
+    };
+}
+/**
+ * Format activity for plain text output (logs, exports, etc).
+ * Creates a one-line summary suitable for text-based feeds.
+ *
+ * Format: "[Actor] [action] [entity] at [time]"
+ * Example: "Alice updated Project ABC at 2:45 PM"
+ *
+ * @param record Activity record
+ * @returns Plain text summary
+ */
+export function formatActivityPlainText(record) {
+    const actor = extractActorDisplay(record);
+    const entity = extractEntityDisplay(record);
+    const actionLabel = getActionLabel(record.action);
+    const time = new Date(record.created_at).toLocaleTimeString('en-US', {
+        hour: 'numeric',
+        minute: '2-digit',
+    });
+    const entityPart = entity.name ? ` ${entity.name}` : '';
+    return `${actor.name} ${actionLabel.toLowerCase()}${entityPart} at ${time}`;
+}
+//# sourceMappingURL=transformers.js.map

package/dist/feed/transformers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformers.js","sourceRoot":"","sources":["../../src/feed/transformers.ts"],"names":[],"mappings":"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"}

package/dist/feed/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Feed system types for activity aggregation, ranking, and digest generation.
+ * Supports time-based filtering, personalized ranking, and daily digest summaries.
+ */
+/**
+ * Time range for feed queries.
+ * Allows filtering activities by relative windows (last 24h, 7d, etc).
+ */
+export type FeedTimeRange = 'today' | 'yesterday' | 'week' | 'month' | 'all';
+/**
+ * Available feed tabs/views.
+ * Determines which activities to show and sorting strategy.
+ */
+export type FeedTab = 'all' | 'for-you' | 'digest';
+/**
+ * A feed item combining activity data with ranking score and preview text.
+ * Used for display in activity feeds, digests, and notifications.
+ */
+export interface FeedItem {
+    /** Unique identifier */
+    id: string;
+    /** Entity being acted upon (e.g., document ID) */
+    entityId: string | null;
+    /** Entity type slug (e.g., 'project', 'task') */
+    entityTypeSlug: string | null;
+    /** User-facing entity name for display */
+    entityName?: string;
+    /** Action type: 'INSERT', 'UPDATE', 'DELETE', 'comment', etc. */
+    action: string;
+    /** Short description of what happened */
+    description: string | null;
+    /** Who performed the action */
+    actorId: string | null;
+    /** Actor name for display (may be system) */
+    actorName?: string;
+    /** Actor type: 'user', 'agent', or null for system */
+    actorType: 'user' | 'agent' | null;
+    /** Additional metadata from the activity */
+    metadata?: Record<string, unknown> | null;
+    /** ISO timestamp */
+    createdAt: string;
+    /** Ranking score (0-1). Higher = more relevant. Used in 'for-you' tab. */
+    score: number;
+    /** Short preview text for display (typically description or generated) */
+    preview?: string;
+    /** Tenant ID for scoping */
+    tenantId: string;
+}
+/**
+ * Configuration for feed resolution.
+ * Controls filtering, time range, limit, and personalization.
+ */
+export interface FeedConfig {
+    /** Which feed tab (all, for-you, digest) */
+    tab?: FeedTab;
+    /** Time range filter */
+    timeRange?: FeedTimeRange;
+    /** Filter to specific entity */
+    entityId?: string;
+    /** Filter to specific actor */
+    actorId?: string;
+    /** Filter to specific action type */
+    action?: string;
+    /** Maximum number of items */
+    limit?: number;
+    /** Cursor for pagination (ISO timestamp, return items created before this) */
+    before?: string;
+    /** Tenant ID (required for RLS / scoping) */
+    tenantId: string;
+    /** User ID for personalization (optional, used by 'for-you' ranking) */
+    userId?: string;
+    /** Include importance scores in ranking (if available in metadata) */
+    includeImportance?: boolean;
+    /** Custom importance weight multiplier (0-2). Default 1. */
+    importanceWeight?: number;
+    /** Custom recency weight multiplier (0-2). Default 1. */
+    recencyWeight?: number;
+}
+/**
+ * Ranking input for scoring activities.
+ * Combines activity metadata with temporal decay and optional importance.
+ */
+export interface RankingInput {
+    /** ISO timestamp of activity */
+    createdAt: string;
+    /** Activity metadata which may contain importance signal */
+    metadata?: Record<string, unknown> | null;
+    /** Importance value if available (typically 0-1 or 'high'/'medium'/'low') */
+    importance?: number | string | null;
+    /** Current time for computing temporal decay */
+    now: Date;
+    /** Weight multiplier for recency (0-2) */
+    recencyWeight: number;
+    /** Weight multiplier for importance (0-2) */
+    importanceWeight: number;
+}
+/**
+ * Digest configuration for daily summaries.
+ * Identifies high-impact activities for notification/email.
+ */
+export interface DigestConfig extends FeedConfig {
+    /** Maximum items in digest (typically 5-10) */
+    digestLimit?: number;
+    /** Minimum score threshold to include in digest (0-1) */
+    minScoreThreshold?: number;
+    /** Include low-scoring but recent items (for variety) */
+    includeRecent?: boolean;
+}
+/**
+ * Daily digest result.
+ * Summarizes important activities from the past 24 hours.
+ */
+export interface FeedDigest {
+    /** ISO date string (YYYY-MM-DD) */
+    date: string;
+    /** Tenant ID */
+    tenantId: string;
+    /** High-impact activities (ranked by importance + recency) */
+    items: FeedItem[];
+    /** Summary statistics */
+    summary: {
+        total: number;
+        byAction: Record<string, number>;
+        byActor: Record<string, number>;
+    };
+    /** Suggested email subject line */
+    emailSubject?: string;
+    /** Pre-computed HTML preview for email rendering */
+    emailPreview?: string;
+}
+//# sourceMappingURL=types.d.ts.map