Files
TMCandClaude Opus 5.5 8435775a0a
Release / build (push) Successful in 1m4s
Apply a new rule to the current feed right away
A rule only filtered articles that arrived after it was saved, so the
stories it was meant to remove stayed in the feed for up to two days.

- Saving a negative rule now also removes its matches from the feed
  (checkbox, on by default). If the form's dry run of the same rule has
  finished, its results are used; otherwise a check runs and removes the
  matches as soon as it ends.
- A saved rule's dry run has "Remove these N from the feed".
- Removed articles are filtered with the rule and reason (Filtered,
  Rescue), stories left without articles disappear, and "Put back all"
  restores them without recording a correction example.
- Dry runs check what's in the feed: articles published within the
  feed's time window (at least 24 h, up to 400), and honour enabled
  "always keep" rules (keyword exceptions skip the model entirely).

API: POST /api/rules/:id/apply { jobId? }, POST /api/rules/:id/restore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 15:09:43 +01:00

705 lines
23 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* API contract between the server and the web UI.
*
* All endpoints are JSON under /api unless noted. Timestamps are ISO-8601 strings (UTC).
* Errors come back as HTTP 4xx/5xx with body { error: string }.
*
* This file is imported at runtime by the server (for CATEGORIES and defaults) and by the
* web build, so it must stay plain, erasable TypeScript: no enums, no namespaces.
*/
// ───────────────────────────── Constants ─────────────────────────────
export const CATEGORIES = [
'Politika',
'Svijet',
'Gospodarstvo',
'Tehnologija',
'Znanost',
'Sport',
'Kultura',
'Zdravlje',
'Crna kronika',
'Ostalo',
] as const;
export type Category = (typeof CATEGORIES)[number];
/** The digest's own category. Never assigned to a story. */
export const DIGEST_CATEGORY = 'Pregled';
export const PROMPT_KEYS = ['triage', 'sameEvent', 'summarize', 'regenerate', 'digest'] as const;
export type PromptKey = (typeof PROMPT_KEYS)[number];
// ───────────────────────────── States ─────────────────────────────
export type ArticleState = 'new' | 'extracted' | 'kept' | 'grouped' | 'rejected' | 'skipped' | 'failed';
export type StoryState = 'pending' | 'published' | 'updating' | 'failed';
/** none = not published yet; queued = waiting for the next edition. */
export type FeedStatus = 'none' | 'in_feed' | 'queued' | 'left_out';
/**
* Why a story is (or is not) in the feed.
* in_feed: 'auto' | 'breaking' | 'manual'
* left_out: everything else
*/
export type FeedReason =
| 'auto'
| 'breaking'
| 'manual'
| 'daily_limit'
| 'edition_full'
| 'below_min_importance'
| 'category_excluded'
| 'category_limit'
| 'source_limit'
| 'marked_unwanted';
export const FEED_REASON_LABELS: Record<FeedReason, string> = {
auto: 'In feed',
breaking: 'Breaking',
manual: 'Added by hand',
daily_limit: 'Daily limit reached',
edition_full: 'Edition full',
below_min_importance: 'Below minimum importance',
category_excluded: 'Category excluded',
category_limit: 'Category limit reached',
source_limit: 'Source limit reached',
marked_unwanted: 'Marked "should have been filtered"',
};
// ───────────────────────────── Sources ─────────────────────────────
export interface SourceDTO {
id: number;
name: string;
feedUrl: string;
siteUrl: string | null;
enabled: boolean;
pollMinutes: number;
fullText: boolean;
/** ISO 639-1 code or null for auto-detect. */
languageHint: string | null;
lastFetchAt: string | null;
lastSuccessAt: string | null;
lastError: string | null;
failureCount: number;
nextFetchAt: string | null;
/** Articles fetched in the last 24 h, and how many of them were filtered. */
stats24h: { articles: number; filtered: number };
createdAt: string;
}
export interface SourceInput {
feedUrl: string;
name?: string;
siteUrl?: string | null;
enabled?: boolean;
pollMinutes?: number;
fullText?: boolean;
languageHint?: string | null;
}
export interface FeedCandidate {
url: string;
title: string | null;
format: 'rss' | 'atom' | 'rdf' | 'json';
}
/**
* GET /api/sources -> SourceDTO[]
* POST /api/sources/discover {url} -> { candidates: FeedCandidate[] } (url may be a site or a feed)
* POST /api/sources SourceInput -> SourceDTO
* PATCH /api/sources/:id Partial<SourceInput> -> SourceDTO
* DELETE /api/sources/:id -> { ok: true }
* POST /api/sources/:id/fetch -> { ok: true; newItems: number } (fetch now)
* GET /api/sources/opml -> OPML file download (text/x-opml)
* POST /api/sources/opml {opml} -> { added: number; skipped: number }
*/
export interface DiscoverResponse {
candidates: FeedCandidate[];
}
// ───────────────────────────── Rules ─────────────────────────────
export type RuleKind = 'ai' | 'keyword';
/** negative = filter out; exception = always keep (overrides negatives). */
export type RulePolarity = 'negative' | 'exception';
export interface RuleDTO {
id: number;
kind: RuleKind;
polarity: RulePolarity;
/** AI: plain-language description. Keyword: comma/newline separated phrases, or /regex/flags. */
text: string;
enabled: boolean;
/** Empty = applies to all sources. */
sourceIds: number[];
hitCount: number;
lastHitAt: string | null;
createdAt: string;
}
export interface RuleInput {
kind: RuleKind;
polarity: RulePolarity;
text: string;
enabled?: boolean;
sourceIds?: number[];
}
/**
* GET /api/rules -> RuleDTO[]
* POST /api/rules RuleInput -> RuleDTO
* PATCH /api/rules/:id Partial<RuleInput> -> RuleDTO
* DELETE /api/rules/:id -> { ok: true }
* POST /api/rules/dry-run { rule: RuleInput } -> DryRunStatus (starts a job; keyword rules finish instantly)
* GET /api/rules/dry-run/:jobId -> DryRunStatus (poll every ~1 s while status = running)
* POST /api/rules/:id/apply { jobId? } -> DryRunStatus
* Removes the saved rule's matches among recent articles from the feed. With the jobId of a finished
* dry run of the same rule, its results are used as they are; without one, a check starts and its
* matches are removed when it finishes (poll the dry-run status; `applied` is set then).
* POST /api/rules/:id/restore { articleIds } -> { restored: number } (puts removed articles back, no examples)
*
* Dry runs check articles published within the feed's time window (at least 24 h), newest first, and
* honour the enabled "always keep" rules.
*/
export interface DryRunHit {
articleId: number;
title: string;
sourceName: string;
url: string;
reason: string;
confidence: number | null;
/** True when the article is currently published (so this rule would remove something you saw). */
currentlyPublished: boolean;
}
export interface DryRunStatus {
jobId: string;
status: 'running' | 'done' | 'error';
checked: number;
total: number;
/** How far back the check looked. */
windowHours: number;
hits: DryRunHit[];
error: string | null;
/** Set once the matches were removed from the feed. */
applied: { articles: number; stories: number } | null;
}
// ───────────────────────────── Examples (learned corrections) ─────────────────────────────
export interface ExampleDTO {
id: number;
kind: 'filter' | 'clustering';
/** filter: reject | keep. clustering: same | different. */
expected: 'reject' | 'keep' | 'same' | 'different';
/** Short human-readable summary, e.g. the article headline or "A ↔ B". */
label: string;
createdAt: string;
}
/**
* GET /api/examples -> ExampleDTO[]
* DELETE /api/examples/:id -> { ok: true }
*/
// ───────────────────────────── Stories ─────────────────────────────
export interface StorySourceDTO {
articleId: number;
sourceId: number;
sourceName: string;
/** The article's own headline, unchanged. */
originalTitle: string;
url: string;
publishedAt: string | null;
language: string | null;
partial: boolean;
isLead: boolean;
}
export interface StoryListItem {
id: number;
guid: string;
/** Croatian one-sentence title; null until the first version is written. */
title: string | null;
/** Croatian description, at most two sentences. */
description: string | null;
category: Category | null;
/** Effective importance (override, or model score + coverage boost). Null until scored. */
importance: number | null;
modelImportance: number | null;
importanceOverride: number | null;
coverageBoost: number;
sourceCount: number;
leadSourceName: string;
leadUrl: string;
leadOriginalTitle: string;
imageUrl: string | null;
/** True when the lead article could only be read from the feed excerpt. */
partial: boolean;
firstReportedAt: string;
lastReportedAt: string;
/** When the current title/description version was written. */
updatedAt: string | null;
state: StoryState;
feedStatus: FeedStatus;
feedReason: FeedReason | null;
enteredFeedAt: string | null;
editionId: number | null;
read: boolean;
bookmarked: boolean;
}
export interface StoryVersionDTO {
version: number;
title: string;
description: string;
category: Category;
importance: number;
model: string;
promptVersion: string;
formatRetries: number;
tokensIn: number | null;
tokensOut: number | null;
durationMs: number;
createdAt: string;
}
export interface StoryDetail extends StoryListItem {
sources: StorySourceDTO[];
versions: StoryVersionDTO[];
regenerationCount: number;
lastError: string | null;
}
export type StoryView = 'feed' | 'all';
/**
* GET /api/stories?view=feed|all&q=&category=&sourceId=&minImportance=
* &unread=1&bookmarked=1&offset=0&limit=50 -> StoryListResponse
* view=feed: stories in the RSS feed (or queued for an edition).
* view=all: every published story, including the ones feed controls left out.
* Always newest first by publication time (the story's earliest report).
* GET /api/stories/:id -> StoryDetail
* PATCH /api/stories/:id { read?, bookmarked?, importanceOverride?: number | null } -> StoryListItem
* POST /api/stories/mark-read { ids: number[] } -> { ok: true }
* POST /api/stories/:id/regenerate -> { ok: true }
* POST /api/stories/:id/add-to-feed -> StoryListItem
* POST /api/stories/:id/split { articleId } -> { newStoryId: number }
* POST /api/stories/:id/merge { otherStoryId } -> { storyId: number } (other is merged into :id)
* POST /api/stories/:id/unwanted -> { ok: true }
* "Should have been filtered": stores a filter example and hides the story.
*/
export interface StoryListResponse {
items: StoryListItem[];
total: number;
offset: number;
limit: number;
}
// ───────────────────────────── Editions ─────────────────────────────
export interface EditionDTO {
id: number;
/** Local time label, e.g. "07:00". */
label: string;
scheduledFor: string;
releasedAt: string | null;
size: number;
storyCount: number;
}
/** GET /api/editions?limit=20 -> EditionDTO[] (newest first) */
// ───────────────────────────── Filtered ─────────────────────────────
export interface FilteredArticleDTO {
id: number;
title: string;
url: string;
sourceId: number;
sourceName: string;
publishedAt: string | null;
fetchedAt: string;
decidedBy: 'keyword' | 'ai';
ruleId: number | null;
ruleText: string | null;
/** English, one sentence. */
reason: string;
confidence: number | null;
decidedAt: string;
}
/**
* GET /api/filtered?ruleId=&q=&offset=0&limit=50 -> { items: FilteredArticleDTO[]; total: number }
* POST /api/articles/:id/rescue -> { ok: true }
*/
export interface FilteredListResponse {
items: FilteredArticleDTO[];
total: number;
}
// ───────────────────────────── Digest ─────────────────────────────
export interface DigestDTO {
id: number;
/** Local date the digest was published for, YYYY-MM-DD. */
date: string;
/** "Jutarnji pregled — 15. studenoga 2026." */
title: string;
/** Two-sentence opening; null for the fallback version or while pending. */
opening: string | null;
kind: 'llm' | 'fallback' | null;
state: 'pending' | 'published' | 'skipped';
/** Stories in importance order, exactly as published. */
stories: StoryListItem[];
createdAt: string;
publishedAt: string | null;
}
/**
* GET /api/digests?limit=14 -> DigestDTO[] (newest first)
* GET /api/digests/latest -> DigestDTO | null (latest published)
* GET /api/digests/:id -> DigestDTO
* POST /api/digests/run -> DigestDTO (build one now, for testing)
*/
// ───────────────────────────── Settings ─────────────────────────────
export const REASONING_EFFORTS = ['', 'minimal', 'low', 'medium', 'high'] as const;
export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
export interface LlmSettings {
baseUrl: string;
apiKey: string;
triageModel: string;
summaryModel: string;
embeddingModel: string;
concurrency: number;
timeoutSec: number;
maxArticleChars: number;
temperature: number;
/** Sent as `reasoning_effort`; '' = don't send (server default). Lower = fewer hidden thinking tokens. */
reasoningEffort: ReasoningEffort;
}
export interface PipelineSettings {
defaultPollMinutes: number;
/** Items older than this when fetched or processed are skipped. */
maxAgeHours: number;
/** A newly added source imports only items from this many recent hours. */
firstAddHours: number;
/** Reject only when triage confidence is at or above this (0–1). */
rejectThreshold: number;
/** Most recent corrections included in prompts. */
examplesInPrompt: number;
quietHours: QuietHours;
}
/**
* A nightly window with no scheduled fetching and no background processing (extraction or AI).
* Everything waits and catches up when it ends; things you start by hand still run.
*/
export interface QuietHours {
enabled: boolean;
/** Local HH:MM. When end is earlier than start, the window runs past midnight. */
start: string;
end: string;
}
export interface ClusteringSettings {
enabled: boolean;
windowHours: number;
mergeThreshold: number;
reviewThreshold: number;
regenAtSources: number;
regenGapHours: number;
regenCap: number;
preferCroatianLead: boolean;
}
export interface ImportanceSettings {
/** Sources needed for the coverage boost. */
boostSources: number;
/** Points added, capped at 5. 0 disables the boost. */
boost: number;
}
export interface DigestSettings {
enabled: boolean;
/** Local time, HH:MM. */
time: string;
size: number;
minImportance: number;
}
export interface CategoryControl {
include: boolean;
/** Daily maximum; 0 = no maximum. */
max: number;
}
export interface SourceControl {
/** 1–5 replaces the feed's minimum importance for stories this source leads; 0 = the feed's. */
minImportance: number;
/** Stories per day this source may lead; 0 = the per-source limit. */
max: number;
}
export interface FeedControls {
mode: 'live' | 'editions';
/** Live mode; 0 = unlimited. */
storiesPerDay: number;
/** Editions mode: local HH:MM release times. */
editionTimes: string[];
editionSize: number;
minImportance: number;
/** 1–5; 0 disables the breaking bypass. */
breakingLevel: number;
/** Stories per day led by one source; 0 = off. */
perSourceLimit: number;
/**
* Overrides keyed by source id (a story counts for its lead source). Only non-default entries are
* stored; send every source when saving, since objects merge on PUT.
*/
sources: Record<string, SourceControl>;
categories: Record<Category, CategoryControl>;
updatedStories: 'keep' | 'bump';
includeDigest: boolean;
itemSources: boolean;
itemImage: boolean;
feedLength: number;
timeWindowHours: number;
}
export interface RetentionSettings {
publishedDays: number;
rejectedDays: number;
textDays: number;
}
export interface GlossaryEntry {
term: string;
/** Empty string = never translate this term. */
translation: string;
}
export interface AccessSettings {
/** Secret path segment for feeds; null = off. Ignored when RSSFEED_FEED_TOKEN is set. */
feedToken: string | null;
/** e.g. https://rss.example.com; null = derive from forwarded headers. Ignored when RSSFEED_PUBLIC_URL is set. */
publicUrl: string | null;
}
export interface Settings {
llm: LlmSettings;
pipeline: PipelineSettings;
clustering: ClusteringSettings;
importance: ImportanceSettings;
digest: DigestSettings;
feed: FeedControls;
retention: RetentionSettings;
/** null = use the default prompt. */
prompts: Record<PromptKey, string | null>;
glossary: GlossaryEntry[];
access: AccessSettings;
}
export type DeepPartial<T> = {
[K in keyof T]?: T[K] extends (infer U)[] ? U[] : T[K] extends object ? DeepPartial<T[K]> : T[K];
};
/**
* GET /api/settings -> SettingsResponse
* PUT /api/settings DeepPartial<Settings> -> SettingsResponse (arrays and prompt strings replace; objects merge)
* POST /api/settings/feed-preview { feed: FeedControls } -> FeedPreview
*/
export interface SettingsResponse {
settings: Settings;
defaultPrompts: Record<PromptKey, string>;
/** Which values are pinned by environment variables (read-only in the UI). */
env: { llmBaseUrl: boolean; llmApiKey: boolean; feedToken: boolean; publicUrl: boolean };
/** Absolute URLs to subscribe to, built from the public URL / request host. */
feedUrls: { rss: string; json: string; digest: string };
timezone: string;
}
export interface FeedPreviewDay {
date: string;
inFeed: number;
leftOut: number;
byReason: Partial<Record<FeedReason, number>>;
}
export interface FeedPreviewSource {
sourceId: number;
name: string;
/** Stories this source led over the previewed days. */
published: number;
inFeed: number;
}
export interface FeedPreview {
days: FeedPreviewDay[];
averagePerDay: number;
/** Every source, most stories in the feed first. */
bySource: FeedPreviewSource[];
leftOut: { storyId: number; title: string; importance: number | null; category: Category | null; reason: FeedReason; date: string }[];
}
// ───────────────────────────── LLM ─────────────────────────────
export type StructuredMode = 'json_schema' | 'json_object' | 'prompt';
/**
* POST /api/llm/models { baseUrl?, apiKey? } -> { models: string[] } (defaults to saved settings)
* POST /api/llm/test { llm?: Partial<LlmSettings> } -> LlmTestResult
*/
export interface LlmTestStep {
ok: boolean;
ms: number;
error: string | null;
}
export interface LlmTestResult {
reachable: boolean;
models: string[];
latencyMs: number | null;
structuredMode: StructuredMode | null;
triage: LlmTestStep & { decision: string | null };
summary: LlmTestStep & { title: string | null; description: string | null };
embedding: LlmTestStep & { dimensions: number | null };
error: string | null;
}
// ───────────────────────────── Playground ─────────────────────────────
/**
* POST /api/playground/run { url, models?: string[] } -> PlaygroundResult (models: up to 2 summary models; default = settings)
* POST /api/playground/similarity { a: url, b: url } -> SimilarityResult
* Both can take a minute; show a spinner.
*/
export interface PlaygroundSummary {
model: string;
ok: boolean;
/** Tokens billed for this summary (including any retry and hidden reasoning). */
tokensIn: number | null;
tokensOut: number | null;
title: string | null;
description: string | null;
category: Category | null;
importance: number | null;
formatRetries: number;
languageOk: boolean;
ms: number;
error: string | null;
}
export interface PlaygroundResult {
extraction: {
title: string;
text: string;
chars: number;
partial: boolean;
imageUrl: string | null;
language: string | null;
};
triage:
| { skipped: true; note: string }
| { skipped: false; decision: 'keep' | 'reject'; ruleText: string | null; reason: string; confidence: number | null; ms: number };
summaries: PlaygroundSummary[];
}
export interface SimilarityResult {
similarity: number;
mergeThreshold: number;
reviewThreshold: number;
verdict: 'merge' | 'review' | 'new';
titles: { a: string; b: string };
}
// ───────────────────────────── Activity & status ─────────────────────────────
export type LlmState = 'ok' | 'offline' | 'unconfigured';
export interface ActivityFailure {
kind: 'article' | 'story' | 'digest';
id: number;
title: string;
error: string;
attempts: number;
at: string;
}
export interface ActivityDTO {
queue: {
articlesNew: number;
articlesExtracted: number;
articlesKept: number;
storiesPending: number;
storiesUpdating: number;
digestsPending: number;
};
llm: {
state: LlmState;
consecutiveFailures: number;
nextProbeAt: string | null;
inFlight: number;
calls24h: number;
errors24h: number;
avgLatencyMs: number | null;
p95LatencyMs: number | null;
tokensIn24h: number;
tokensOut24h: number;
/** Why LLM work is paused, when the server rejected requests (bad key, unknown model). */
error: string | null;
/** Last 24 h, per pipeline step (triage, story-match, summarize, …). */
byPurpose: { purpose: string; calls: number; errors: number; tokensIn: number; tokensOut: number }[];
/** LLM calls in the last 24 h per story published in the last 24 h. */
callsPerStory: number | null;
};
/** Work saved without AI in the last 7 days. */
savings7d: { duplicatesSkipped: number; groupedByHeadline: number; matchCallsSkipped: number; triageBatched: number };
failures: ActivityFailure[];
importance7d: { score: number; count: number }[];
grouping7d: { articles: number; inMultiSourceStories: number; share: number };
feed7d: FeedPreviewDay[];
formatRetries7d: number;
languageFailures7d: number;
lastRuns: { fetch: string | null; edition: string | null; digest: string | null; cleanup: string | null };
sources: { total: number; enabled: number; failing: number };
}
/**
* GET /api/activity -> ActivityDTO
* POST /api/activity/retry { kind, id } -> { ok: true }
* POST /api/activity/retry-failed -> { retried: number }
* GET /api/status -> StatusDTO (cheap; poll every ~20 s for the offline banner)
* GET /api/health -> HealthDTO
*/
export interface StatusDTO {
llm: LlmState;
/** Set when LLM work is paused because the server rejected requests (bad key, unknown model). */
llmError: string | null;
/** Articles and stories waiting on the LLM. */
waiting: number;
version: string;
latestDigestId: number | null;
feedMode: 'live' | 'editions';
/** Set during quiet hours: the local end time (HH:MM) and the same moment as ISO. */
quiet: { until: string; endsAt: string } | null;
}
export interface HealthDTO {
ok: boolean;
version: string;
db: 'ok' | 'error';
queueDepth: number;
llm: LlmState;
lastEditionAt: string | null;
lastDigestAt: string | null;
}