@vibexp/api-client 0.59.0 → 0.61.0

package/dist/schema.d.ts

@@ -3231,6 +3231,121 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/{team_id}/freshness/metrics/over-time": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        /**
+         * Freshness activity over time
+         * @description Daily marked/cleared counts and the reconstructed stale level over the requested window, zero-filled so every day in the range is present.
+         */
+        get: operations["getFreshnessOverTimeMetrics"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/{team_id}/freshness/metrics/by-type": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        /**
+         * Stale resources by resource type
+         * @description Current stale counts per resource type. All four types are always present; one with nothing stale reports 0.
+         */
+        get: operations["getFreshnessByTypeMetrics"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/{team_id}/freshness/metrics/by-project": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        /**
+         * Stale resources by project
+         * @description Current stale counts per project in the team, including projects with nothing stale.
+         */
+        get: operations["getFreshnessByProjectMetrics"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/{team_id}/freshness/metrics/by-rule": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        /**
+         * Resources marked by each rule
+         * @description How many resources each of the team's rules currently marks, including rules that match nothing. This is how an over-broad rule is spotted.
+         */
+        get: operations["getFreshnessByRuleMetrics"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/{team_id}/freshness/audit": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        /**
+         * List the team's freshness audit log
+         * @description Every recorded mark and clear for the team, newest first and paginated. Readable by any member. The list is empty, never null, past the last page.
+         */
+        get: operations["listFreshnessAudit"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/{team_id}/settings/embedding-providers": {
         parameters: {
             query?: never;
@@ -4687,6 +4802,7 @@ export interface components {
             related?: components["schemas"]["RelatedResource"][];
             /** @description Computed embedding-similarity neighborhood of this resource (up to 5), derived live at read time from vector similarity — NOT stored edges and distinct from `related`. Populated on the detail GET; empty otherwise. */
             similar?: components["schemas"]["SimilarResource"][];
+            freshness?: components["schemas"]["ResourceFreshnessState"];
         };
         CreatePromptRequest: {
             /** @example Code Review Template */
@@ -5998,6 +6114,7 @@ export interface components {
             related?: components["schemas"]["RelatedResource"][];
             /** @description Computed embedding-similarity neighborhood of this resource (up to 5), derived live at read time from vector similarity — NOT stored edges and distinct from `related`. Populated on the detail GET; empty otherwise. */
             similar?: components["schemas"]["SimilarResource"][];
+            freshness?: components["schemas"]["ResourceFreshnessState"];
         };
         CreateArtifactRequest: {
             /**
@@ -6776,6 +6893,7 @@ export interface components {
             related?: components["schemas"]["RelatedResource"][];
             /** @description Computed embedding-similarity neighborhood of this resource (up to 5), derived live at read time from vector similarity — NOT stored edges and distinct from `related`. Populated on the detail GET; empty otherwise. */
             similar?: components["schemas"]["SimilarResource"][];
+            freshness?: components["schemas"]["ResourceFreshnessState"];
         };
         CreateMemoryRequest: {
             /**
@@ -7075,6 +7193,7 @@ export interface components {
             related?: components["schemas"]["RelatedResource"][];
             /** @description Computed embedding-similarity neighborhood of this resource (up to 5), derived live at read time from vector similarity — NOT stored edges and distinct from `related`. Populated on the detail GET; empty otherwise. */
             similar?: components["schemas"]["SimilarResource"][];
+            freshness?: components["schemas"]["ResourceFreshnessState"];
         };
         /** @description Read-only import provenance; present only for imported blueprints. */
         BlueprintSource: {
@@ -8924,6 +9043,209 @@ export interface components {
             interval_seconds: number;
             reversibility_enabled: boolean;
         };
+        /**
+         * @description The reporting window for a time-series metric. The options mirror the other analytics endpoints so one range selector drives every chart.
+         * @example 30d
+         * @enum {string}
+         */
+        FreshnessMetricsRange: "7d" | "14d" | "30d" | "60d" | "90d" | "180d";
+        /** @description One calendar day (UTC) of freshness activity, zero-filled: every day in the window is present even when nothing happened. */
+        FreshnessDailyStaleCount: {
+            /**
+             * Format: date
+             * @example 2026-05-01
+             */
+            date: string;
+            /**
+             * Format: int32
+             * @description Resources that became stale on this day.
+             */
+            marked: number;
+            /**
+             * Format: int32
+             * @description Resources that stopped being stale on this day, for any reason.
+             */
+            cleared: number;
+            /**
+             * Format: int32
+             * @description How many resources were stale at the END of this day — the level, not the flow. It is reconstructed by walking today's live count backwards through the recorded transitions, so it is exact only for the period the audit log covers; days before freshness evaluation first ran on this team read as the earliest known level rather than as zero. The most recent day reports the live count as of the request. The reconstruction is clamped at zero, so on a team whose rows were removed by a project or team deletion — which writes no audit entry — the series can flatten at 0 instead of satisfying stale_total[i] = stale_total[i-1] + marked[i] - cleared[i].
+             */
+            stale_total: number;
+            /**
+             * Format: int32
+             * @description The day's total ACTIVITY, marked + cleared — the sum of the two series, not the level. It is the field the shared time-series chart reads for its per-day total, which is why it is a flow rather than stale_total.
+             */
+            total: number;
+        };
+        FreshnessOverTimeMetricsData: {
+            range: components["schemas"]["FreshnessMetricsRange"];
+            /**
+             * Format: int32
+             * @description Resources marked stale across the whole window.
+             */
+            total_marked: number;
+            /**
+             * Format: int32
+             * @description Resources cleared across the whole window.
+             */
+            total_cleared: number;
+            /** @description One entry per day in the window, oldest first. Serializes as `[]`, never `null`. */
+            counts: components["schemas"]["FreshnessDailyStaleCount"][];
+        };
+        FreshnessOverTimeMetricsResponse: {
+            /** @example success */
+            status: string;
+            /** @example Freshness over-time metrics retrieved successfully */
+            message: string;
+            data: components["schemas"]["FreshnessOverTimeMetricsData"];
+        };
+        /** @description How many of one resource type are stale right now. */
+        FreshnessTypeCount: {
+            resource_type: components["schemas"]["FreshnessRuleResourceType"];
+            /** Format: int32 */
+            count: number;
+        };
+        FreshnessByTypeMetricsData: {
+            /**
+             * Format: int32
+             * @description Total stale resources in the team, across every type.
+             */
+            total_stale: number;
+            /** @description One entry per resource type, always all four, in a stable order — a type with nothing stale reports 0 rather than being omitted, so the chart's bars never move. Serializes as `[]`, never `null`. */
+            counts: components["schemas"]["FreshnessTypeCount"][];
+        };
+        FreshnessByTypeMetricsResponse: {
+            /** @example success */
+            status: string;
+            /** @example Freshness by-type metrics retrieved successfully */
+            message: string;
+            data: components["schemas"]["FreshnessByTypeMetricsData"];
+        };
+        /** @description How many resources are stale right now in one project. `name` and `slug` are carried so the client can label and deep-link the bar without a second request. */
+        FreshnessProjectCount: {
+            /** Format: uuid */
+            project_id: string;
+            name: string;
+            slug: string;
+            /** Format: int32 */
+            count: number;
+        };
+        FreshnessByProjectMetricsData: {
+            /** Format: int32 */
+            total_stale: number;
+            /** @description One entry per project in the team, including projects with nothing stale (0), ordered by count descending then name. Serializes as `[]`, never `null`. */
+            counts: components["schemas"]["FreshnessProjectCount"][];
+        };
+        FreshnessByProjectMetricsResponse: {
+            /** @example success */
+            status: string;
+            /** @example Freshness by-project metrics retrieved successfully */
+            message: string;
+            data: components["schemas"]["FreshnessByProjectMetricsData"];
+        };
+        /** @description How many resources one rule currently marks. Rules have no name, so the defining fields travel with the count for the client to label the bar. */
+        FreshnessRuleImpact: {
+            /** Format: uuid */
+            rule_id: string;
+            /**
+             * Format: uuid
+             * @description The project the rule is scoped to, or null for every project in the team.
+             */
+            project_id: string | null;
+            resource_types: components["schemas"]["FreshnessRuleResourceType"][];
+            /** Format: int32 */
+            threshold_days: number;
+            /** @description A disabled rule reports 0 — it is listed so its absence from the chart is not mistaken for deletion. */
+            enabled: boolean;
+            /** Format: int32 */
+            count: number;
+        };
+        FreshnessByRuleMetricsData: {
+            /**
+             * Format: int32
+             * @description Distinct stale resources in the team. It is NOT the sum of the per-rule counts: a resource matched by two rules is counted once here and once under each rule, because staleness is a union across rules.
+             */
+            total_stale: number;
+            /** @description One entry per rule the team has defined, including rules matching nothing, ordered by count descending then rule id. Serializes as `[]`, never `null`. */
+            counts: components["schemas"]["FreshnessRuleImpact"][];
+        };
+        FreshnessByRuleMetricsResponse: {
+            /** @example success */
+            status: string;
+            /** @example Freshness by-rule metrics retrieved successfully */
+            message: string;
+            data: components["schemas"]["FreshnessByRuleMetricsData"];
+        };
+        /** @description One recorded freshness transition. The log is append-only. */
+        FreshnessAuditEntry: {
+            /** Format: uuid */
+            id: string;
+            resource_type: components["schemas"]["FreshnessRuleResourceType"];
+            /** Format: uuid */
+            resource_id: string;
+            /**
+             * Format: uuid
+             * @description The rule that caused the change, when exactly one did. Null for a reversal (caused by a read or an edit) and for a mark attributable to several rules at once — the resource's own state carries the full set.
+             */
+            rule_id: string | null;
+            /**
+             * @description Whether the resource became stale or stopped being stale.
+             * @enum {string}
+             */
+            action: "marked" | "cleared";
+            /**
+             * @description What caused it — a scheduled evaluation, a read, or an edit.
+             * @enum {string}
+             */
+            reason: "rule_run" | "accessed" | "edited";
+            /** Format: date-time */
+            created_at: string;
+        };
+        /** @description A page of the team's freshness audit log, newest first. */
+        FreshnessAuditListResponse: {
+            /** @description Serializes as `[]` when the page is empty, never `null`. */
+            entries: components["schemas"]["FreshnessAuditEntry"][];
+            /**
+             * @description Total entries in the team's log, ignoring pagination.
+             * @example 142
+             */
+            total_count: number;
+            /**
+             * @description Current page number (1-based)
+             * @example 1
+             */
+            page: number;
+            /**
+             * @description Number of entries per page
+             * @example 20
+             */
+            per_page: number;
+            /**
+             * @description Total number of pages
+             * @example 8
+             */
+            total_pages: number;
+        };
+        /** @description The resource's staleness state. Present only when the resource is stale; absent means fresh. */
+        ResourceFreshnessState: {
+            /**
+             * @description Today the only state a resource can be in while it has freshness state at all. It is modelled as an enum rather than a boolean so a future state can be added without changing the field's type.
+             * @enum {string}
+             */
+            status: "stale";
+            /**
+             * Format: date-time
+             * @description When the resource was FIRST marked stale. It is preserved across re-evaluations that keep it stale, so it is the age a client can show.
+             */
+            since: string;
+            /** @description Every rule that currently marks this resource — staleness is a union across rules, so this answers "why is this stale". Serializes as `[]`, never `null`. */
+            matched_rule_ids: string[];
+            /**
+             * @description What produced the current state.
+             * @enum {string}
+             */
+            reason: "rule_run" | "accessed" | "edited";
+        };
         /** @description The search ranking settings in effect for a team, with enough context for a client to render the whole settings surface from this one response: the effective values, where they came from, the instance defaults to preview a reset against, and the instance-owned candidate cap. */
         TeamSearchSettings: {
             /**
@@ -10814,6 +11136,8 @@ export interface operations {
     listArtifacts: {
         parameters: {
             query?: {
+                /** @description Filter to resources currently flagged stale by the team's freshness rules (epic #726). Omit for no freshness filtering. Returns 400 for any other value — a silently ignored filter would return the full list, which looks like a legitimate answer. */
+                freshness?: "stale";
                 /** @description Filter by project ID */
                 project_id?: string;
                 /** @description Filter by status */
@@ -10990,6 +11314,8 @@ export interface operations {
     listArtifactsByProject: {
         parameters: {
             query?: {
+                /** @description Filter to resources currently flagged stale by the team's freshness rules (epic #726). Omit for no freshness filtering. Returns 400 for any other value — a silently ignored filter would return the full list, which looks like a legitimate answer. */
+                freshness?: "stale";
                 /** @description Filter by status */
                 status?: "active" | "draft" | "archived";
                 /** @description Filter by type. An open string matched against the team's registered types (the system defaults work_reports, static_contexts and general, plus any custom types the team has added), not a fixed enum. */
@@ -12058,6 +12384,8 @@ export interface operations {
     listMemories: {
         parameters: {
             query?: {
+                /** @description Filter to resources currently flagged stale by the team's freshness rules (epic #726). Omit for no freshness filtering. Returns 400 for any other value — a silently ignored filter would return the full list, which looks like a legitimate answer. */
+                freshness?: "stale";
                 /** @description Filter memories by project ID */
                 project_id?: string;
                 /** @description Search in memory text */
@@ -12589,6 +12917,8 @@ export interface operations {
     listSpecLibraries: {
         parameters: {
             query?: {
+                /** @description Filter to resources currently flagged stale by the team's freshness rules (epic #726). Omit for no freshness filtering. Returns 400 for any other value — a silently ignored filter would return the full list, which looks like a legitimate answer. */
+                freshness?: "stale";
                 /** @description Filter by project name */
                 project_name?: string;
                 /** @description Filter by project ID. On this team-scoped variant the backend reads it only when a project is not already selected via a path parameter (i.e. not on listSpecLibrariesByProject). */
@@ -12783,6 +13113,8 @@ export interface operations {
     listSpecLibrariesByProject: {
         parameters: {
             query?: {
+                /** @description Filter to resources currently flagged stale by the team's freshness rules (epic #726). Omit for no freshness filtering. Returns 400 for any other value — a silently ignored filter would return the full list, which looks like a legitimate answer. */
+                freshness?: "stale";
                 /** @description Filter by status */
                 status?: "active" | "expired";
                 /** @description Filter by type */
@@ -13250,6 +13582,8 @@ export interface operations {
     listPrompts: {
         parameters: {
             query?: {
+                /** @description Filter to resources currently flagged stale by the team's freshness rules (epic #726). Omit for no freshness filtering. Returns 400 for any other value — a silently ignored filter would return the full list, which looks like a legitimate answer. */
+                freshness?: "stale";
                 /** @description Page number for pagination */
                 page?: number;
                 /** @description Number of items per page */
@@ -21255,6 +21589,309 @@ export interface operations {
             };
         };
     };
+    getFreshnessOverTimeMetrics: {
+        parameters: {
+            query?: {
+                /** @description The reporting window. Defaults to 30d. */
+                range?: components["schemas"]["FreshnessMetricsRange"];
+            };
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Metrics retrieved successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FreshnessOverTimeMetricsResponse"];
+                };
+            };
+            /** @description Invalid team_id or query parameter */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Caller is not a member of the team */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Failed to build the team's freshness over-time metrics */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    getFreshnessByTypeMetrics: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Metrics retrieved successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FreshnessByTypeMetricsResponse"];
+                };
+            };
+            /** @description Invalid team_id or query parameter */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Caller is not a member of the team */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Failed to build the team's freshness by-type metrics */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    getFreshnessByProjectMetrics: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Metrics retrieved successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FreshnessByProjectMetricsResponse"];
+                };
+            };
+            /** @description Invalid team_id or query parameter */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Caller is not a member of the team */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Failed to build the team's freshness by-project metrics */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    getFreshnessByRuleMetrics: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Metrics retrieved successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FreshnessByRuleMetricsResponse"];
+                };
+            };
+            /** @description Invalid team_id or query parameter */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Caller is not a member of the team */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Failed to build the team's freshness by-rule metrics */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    listFreshnessAudit: {
+        parameters: {
+            query?: {
+                /** @description Page number (1-based). The upper bound is not a storage limit — it keeps page * limit inside the range the offset arithmetic can represent, so an absurd page is rejected rather than silently wrapping around to the first one. */
+                page?: number;
+                /** @description Entries per page */
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                /** @description Team identifier */
+                team_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Audit log retrieved successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FreshnessAuditListResponse"];
+                };
+            };
+            /** @description Invalid team_id or query parameter */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Caller is not a member of the team */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Failed to list the team's freshness audit log */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listEmbeddingProvidersSettings: {
         parameters: {
             query?: never;