@aventurevc/api-schemas 0.8.340 → 0.8.342

package/dist/entity/natural-search.d.ts

@@ -226,6 +226,7 @@ declare const EntityNaturalSearchSchemaDefinition: z.ZodObject<{
     search: z.ZodType<{
         answerModel?: string | null | undefined;
         cacheMode?: "bypass" | "refresh" | "use" | undefined;
+        freshness?: "auto" | "cached" | undefined;
         mode?: string | undefined;
         model?: string | null | undefined;
         modelCatalogRevision?: number | null | undefined;
@@ -236,6 +237,7 @@ declare const EntityNaturalSearchSchemaDefinition: z.ZodObject<{
     }, import("../natural/search.ts").NaturalSearchSchemaInput, z.core.$ZodTypeInternals<{
         answerModel?: string | null | undefined;
         cacheMode?: "bypass" | "refresh" | "use" | undefined;
+        freshness?: "auto" | "cached" | undefined;
         mode?: string | undefined;
         model?: string | null | undefined;
         modelCatalogRevision?: number | null | undefined;

package/dist/federated/natural-search.d.ts

@@ -229,6 +229,10 @@ declare const FederatedNaturalSearchSchemaDefinition: z.ZodObject<{
             min?: number | null | undefined;
         }, import("../int/range.ts").IntRangeSchemaInput>>>>;
     }, z.core.$strict>>;
+    freshness: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        cached: "cached";
+    }>>>;
     mode: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
         auto: "auto";
         exact: "exact";

package/dist/federated/natural-search.js

@@ -3,6 +3,7 @@ import { z } from "zod/v4";
 import { EntityFilterSchema } from "../entity/filter.js";
 import { ReasoningEffortSchema } from "../reasoning/effort.js";
 import { SearchCacheModeSchema } from "../search/cache-mode.js";
+import { SearchFreshnessSchema } from "../search/freshness.js";
 import { SearchModeSchema } from "../search/mode.js";
 const FederatedNaturalSearchSchemaDefinition = z.object({
     /** Optional supported model for the written answer, which also supplies the page heading, title, and description. Omit it to use the default; an unsupported model answers 422. */
@@ -11,6 +12,8 @@ const FederatedNaturalSearchSchemaDefinition = z.object({
     cacheMode: SearchCacheModeSchema.default("use").optional(),
     /** Explicit entity constraints for the entity scope only, as on POST /v1/search/natural/entities: caller-supplied fields override planner values. The person and news scopes ignore it. Omitted defaults suppress non-operating entities, matching the aventure.vc search page; natural entity search is unchanged. */
     entityFilter: EntityFilterSchema.optional(),
+    /** auto refreshes date-sensitive queries before cache admission; cached permits ordinary cache reuse. Explicit admitted bypass or refresh wins. */
+    freshness: SearchFreshnessSchema.default("auto").optional(),
     /** Search strategy to run. Defaults to `auto`: the fast name layer runs first (a single-token query as keyword search, a multiword query as an exact normalized name) and the language-model planner runs only on a miss, so name lookups never pay for planning. Any other value forces exactly that strategy: `exact` and `keyword` skip planner model resolution and its rate limit. Entity and person natural-search take every value but `hybrid`; news and federated search accept only `auto` and `keyword`; content search accepts `auto`, `keyword`, `semantic`, and `hybrid` (`semantic` and `hybrid` only for one entity's or person's content). */
     mode: SearchModeSchema.default("auto").optional(),
     /** Optional supported model for planning the search. Omit it to use the default; an unsupported model answers 422. */

package/dist/natural/search.d.ts

@@ -6,6 +6,10 @@ declare const NaturalSearchSchemaDefinition: z.ZodObject<{
         refresh: "refresh";
         use: "use";
     }>>>;
+    freshness: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        cached: "cached";
+    }>>>;
     mode: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
         auto: "auto";
         exact: "exact";

package/dist/natural/search.js

@@ -2,12 +2,15 @@
 import { z } from "zod/v4";
 import { ReasoningEffortSchema } from "../reasoning/effort.js";
 import { SearchCacheModeSchema } from "../search/cache-mode.js";
+import { SearchFreshnessSchema } from "../search/freshness.js";
 import { SearchModeSchema } from "../search/mode.js";
 const NaturalSearchSchemaDefinition = z.object({
     /** Optional supported model for the written answer, which also supplies the page heading, title, and description. Omit it to use the default; an unsupported model answers 422. */
     answerModel: z.string().nullish(),
     /** Cache policy. use reuses earlier search work; bypass and refresh compute fresh results and are honored only for accounts with private-data access. */
     cacheMode: SearchCacheModeSchema.default("use").optional(),
+    /** auto refreshes date-sensitive queries before cache admission; cached permits ordinary cache reuse. Explicit admitted bypass or refresh wins. */
+    freshness: SearchFreshnessSchema.default("auto").optional(),
     /** Search strategy to run. Defaults to `auto`: the fast name layer runs first (a single-token query as keyword search, a multiword query as an exact normalized name) and the language-model planner runs only on a miss, so name lookups never pay for planning. Any other value forces exactly that strategy: `exact` and `keyword` skip planner model resolution and its rate limit. Entity and person natural-search take every value but `hybrid`; news and federated search accept only `auto` and `keyword`; content search accepts `auto`, `keyword`, `semantic`, and `hybrid` (`semantic` and `hybrid` only for one entity's or person's content). */
     mode: SearchModeSchema.default("auto").optional(),
     /** Optional supported model for planning the search. Omit it to use the default; an unsupported model answers 422. */

package/dist/openapi-component-manifest.js

@@ -1173,6 +1173,7 @@ export const OPENAPI_COMPONENT_MANIFEST = Object.freeze({
         modulePath: "search/evidence-source",
         schemaName: "SearchEvidenceSourceSchema",
     },
+    SearchFreshness: { modulePath: "search/freshness", schemaName: "SearchFreshnessSchema" },
     SearchHit: { modulePath: "search/hit", schemaName: "SearchHitSchema" },
     SearchIntent: { modulePath: "search/intent", schemaName: "SearchIntentSchema" },
     SearchInterpretation: {

package/dist/person/natural-search.d.ts

@@ -551,6 +551,7 @@ declare const PersonNaturalSearchSchemaDefinition: z.ZodObject<{
     search: z.ZodType<{
         answerModel?: string | null | undefined;
         cacheMode?: "bypass" | "refresh" | "use" | undefined;
+        freshness?: "auto" | "cached" | undefined;
         mode?: string | undefined;
         model?: string | null | undefined;
         modelCatalogRevision?: number | null | undefined;
@@ -561,6 +562,7 @@ declare const PersonNaturalSearchSchemaDefinition: z.ZodObject<{
     }, import("../natural/search.ts").NaturalSearchSchemaInput, z.core.$ZodTypeInternals<{
         answerModel?: string | null | undefined;
         cacheMode?: "bypass" | "refresh" | "use" | undefined;
+        freshness?: "auto" | "cached" | undefined;
         mode?: string | undefined;
         model?: string | null | undefined;
         modelCatalogRevision?: number | null | undefined;

package/dist/search/cache-mode.d.ts

@@ -3,14 +3,17 @@ import { z } from "zod/v4";
  * Search-stage cache policy: use reuses completed and in-flight work; bypass computes independently without retaining search outputs; refresh computes independently and replaces the normal cache entry. Immutable query vectors and canonical record caches retain their own cache policy.
  *
  * @openapiSchema SearchCacheMode
+ * @endpoint GET /v1/web/searches/jobs/{jobId}
  * @endpoint POST /v1/content/search
  * @endpoint POST /v1/entities/{entityId}/content/search
  * @endpoint POST /v1/people/{personId}/content/search
  * @endpoint POST /v1/search
  * @endpoint POST /v1/search/natural/entities
  * @endpoint POST /v1/search/natural/people
+ * @endpoint POST /v1/web/search
  * @usedBySchema FederatedNaturalSearchSchema
  * @usedBySchema NaturalSearchSchema
+ * @usedBySchema SearchSchema
  * @contractShape search.cache-mode
  * @contractRole canonical
  */

package/dist/search/cache-mode.js

@@ -4,14 +4,17 @@ import { z } from "zod/v4";
  * Search-stage cache policy: use reuses completed and in-flight work; bypass computes independently without retaining search outputs; refresh computes independently and replaces the normal cache entry. Immutable query vectors and canonical record caches retain their own cache policy.
  *
  * @openapiSchema SearchCacheMode
+ * @endpoint GET /v1/web/searches/jobs/{jobId}
  * @endpoint POST /v1/content/search
  * @endpoint POST /v1/entities/{entityId}/content/search
  * @endpoint POST /v1/people/{personId}/content/search
  * @endpoint POST /v1/search
  * @endpoint POST /v1/search/natural/entities
  * @endpoint POST /v1/search/natural/people
+ * @endpoint POST /v1/web/search
  * @usedBySchema FederatedNaturalSearchSchema
  * @usedBySchema NaturalSearchSchema
+ * @usedBySchema SearchSchema
  * @contractShape search.cache-mode
  * @contractRole canonical
  */

package/dist/search/freshness.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod/v4";
+/**
+ * auto refreshes relative/current queries and explicit dates from the last 90 days through tomorrow, using UTC. cached permits normal cache reuse for those queries. Explicit bypass or refresh always wins.
+ *
+ * @openapiSchema SearchFreshness
+ * @endpoint GET /v1/web/searches/jobs/{jobId}
+ * @endpoint POST /v1/content/search
+ * @endpoint POST /v1/entities/{entityId}/content/search
+ * @endpoint POST /v1/people/{personId}/content/search
+ * @endpoint POST /v1/search
+ * @endpoint POST /v1/search/natural/entities
+ * @endpoint POST /v1/search/natural/people
+ * @endpoint POST /v1/web/search
+ * @usedBySchema FederatedNaturalSearchSchema
+ * @usedBySchema NaturalSearchSchema
+ * @usedBySchema SearchSchema
+ * @contractShape search.freshness
+ * @contractRole canonical
+ */
+export declare const SearchFreshnessSchema: z.ZodEnum<{
+    auto: "auto";
+    cached: "cached";
+}>;
+export type SearchFreshness = z.infer<typeof SearchFreshnessSchema>;
+//# sourceMappingURL=freshness.d.ts.map

package/dist/search/freshness.js

@@ -0,0 +1,22 @@
+// LLM AGENTS MAY NOT EDIT THIS FILE UNDER ANY CIRCUMSTANCES. DO NOT EDIT - generated from Kotlin data classes via OpenAPI. Edit the backend owner and run: make docs-openapi && make docs-zod
+import { z } from "zod/v4";
+/**
+ * auto refreshes relative/current queries and explicit dates from the last 90 days through tomorrow, using UTC. cached permits normal cache reuse for those queries. Explicit bypass or refresh always wins.
+ *
+ * @openapiSchema SearchFreshness
+ * @endpoint GET /v1/web/searches/jobs/{jobId}
+ * @endpoint POST /v1/content/search
+ * @endpoint POST /v1/entities/{entityId}/content/search
+ * @endpoint POST /v1/people/{personId}/content/search
+ * @endpoint POST /v1/search
+ * @endpoint POST /v1/search/natural/entities
+ * @endpoint POST /v1/search/natural/people
+ * @endpoint POST /v1/web/search
+ * @usedBySchema FederatedNaturalSearchSchema
+ * @usedBySchema NaturalSearchSchema
+ * @usedBySchema SearchSchema
+ * @contractShape search.freshness
+ * @contractRole canonical
+ */
+export const SearchFreshnessSchema = z.enum(["auto", "cached"]);
+//# sourceMappingURL=freshness.js.map

package/dist/search/search.d.ts

@@ -3,12 +3,21 @@ declare const SearchSchemaDefinition: z.ZodObject<{
     allowSuspectedShellStrip: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     bypassCache: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     cacheKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cacheMode: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        bypass: "bypass";
+        refresh: "refresh";
+        use: "use";
+    }>>>;
     cacheSource: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
         ANY: "ANY";
         PROVIDER: "PROVIDER";
     }>>>;
     deep: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     deferredAiOverview: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    freshness: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        cached: "cached";
+    }>>>;
     language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     provider: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodEnum<{
         BRIGHT_DATA: "BRIGHT_DATA";

package/dist/search/search.js

@@ -1,6 +1,8 @@
 // LLM AGENTS MAY NOT EDIT THIS FILE UNDER ANY CIRCUMSTANCES. DO NOT EDIT - generated from Kotlin data classes via OpenAPI. Edit the backend owner and run: make docs-openapi && make docs-zod
 import { z } from "zod/v4";
 import { EntityPersonOwnerSchema } from "../entity/person-owner.js";
+import { SearchCacheModeSchema } from "./cache-mode.js";
+import { SearchFreshnessSchema } from "./freshness.js";
 import { WebSearchCacheSourceSchema } from "../web/search-cache-source.js";
 import { WebSearchProviderSchema } from "../web/search-provider.js";
 import { WebSearchRecencySchema } from "../web/search-recency.js";
@@ -11,12 +13,16 @@ const SearchSchemaDefinition = z.object({
     bypassCache: z.boolean().default(false).optional(),
     /** Stable lookup text for cache keying when generated search text varies between runs */
     cacheKey: z.string().nullish(),
+    /** use permits cached provider evidence; bypass and refresh require a new provider search. Captured evidence is always archived. Legacy bypassCache=true wins. */
+    cacheMode: SearchCacheModeSchema.default("use").optional(),
     /** Permit compatible cached results from ANY provider by default, or restrict to PROVIDER. The provider field independently selects live misses; bypassCache skips every provider's cache. document.provider identifies the serving source. */
     cacheSource: WebSearchCacheSourceSchema.default("ANY").optional(),
     /** Deprecated alias for `provider: EXA_DEEP`; `true` with any other `provider` is refused with 400. */
     deep: z.boolean().default(false).optional(),
     /** Wait in-request for Google's AI Overview when Google defers it to a follow-up request, as it does for most company and person lookups: one extra SerpAPI search per overview not already stored. An explicit `true` also reruns a stored search older than SerpAPI's one-hour cache to get a fresh token (its one-minute overview token expired and the cache would return it unchanged). Without it, no deferred overview is fetched; one an earlier fetch stored still comes back at no extra cost. A fetch that returns no overview is not retried for six hours. An overview Google returns inline always comes back in `aiOverview` at no extra cost. Exa results never carry one. */
     deferredAiOverview: z.boolean().default(false).optional(),
+    /** auto refreshes date-sensitive queries before cache admission; cached permits ordinary cache reuse. Explicit cacheMode bypass/refresh or bypassCache wins. */
+    freshness: SearchFreshnessSchema.default("auto").optional(),
     /** Search language code */
     language: z.string().nullish(),
     /** Provider to search; omitted keeps the default, SerpAPI. EXA runs Exa's instant search with highlights and never falls back to SerpAPI: an Exa failure answers 503. EXA_DEEP runs Exa's slower, broader deep search (higher recall for market and provider questions, about 3-6 s) and falls back to SerpAPI on an Exa failure. Both Exa providers answer synchronously (`Prefer: respond-async` does not apply), are stored apart from SerpAPI results, and are charged like any search. */

package/dist/web/search.d.ts

@@ -104,9 +104,11 @@ declare const WebSearchSchemaDefinition: z.ZodObject<{
         allowSuspectedShellStrip?: boolean | null | undefined;
         bypassCache?: boolean | undefined;
         cacheKey?: string | null | undefined;
+        cacheMode?: "bypass" | "refresh" | "use" | undefined;
         cacheSource?: "ANY" | "PROVIDER" | undefined;
         deep?: boolean | undefined;
         deferredAiOverview?: boolean | undefined;
+        freshness?: "auto" | "cached" | undefined;
         language?: string | null | undefined;
         provider?: string | null | undefined;
         recency?: "DAY" | "MONTH" | "WEEK" | "YEAR" | null | undefined;
@@ -122,9 +124,11 @@ declare const WebSearchSchemaDefinition: z.ZodObject<{
         allowSuspectedShellStrip?: boolean | null | undefined;
         bypassCache?: boolean | undefined;
         cacheKey?: string | null | undefined;
+        cacheMode?: "bypass" | "refresh" | "use" | undefined;
         cacheSource?: "ANY" | "PROVIDER" | undefined;
         deep?: boolean | undefined;
         deferredAiOverview?: boolean | undefined;
+        freshness?: "auto" | "cached" | undefined;
         language?: string | null | undefined;
         provider?: string | null | undefined;
         recency?: "DAY" | "MONTH" | "WEEK" | "YEAR" | null | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventurevc/api-schemas",
-  "version": "0.8.340",
+  "version": "0.8.342",
   "private": false,
   "description": "Zod v4 schemas and TypeScript types for the aVenture API.",
   "license": "Apache-2.0",