@functional-systems/lambdadb 0.4.3 → 0.5.0-rc.2

package/src/funcs/collectionsUpdate.ts

@@ -40,6 +40,11 @@ export function collectionsUpdate(
     | errors.ResourceNotFoundError
     | errors.TooManyRequestsError
     | errors.InternalServerError
+    | errors.CatalogConflictError
+    | errors.PayloadTooLargeError
+    | errors.BadGatewayError
+    | errors.ServiceUnavailableError
+    | errors.GatewayTimeoutError
     | LambdaDBError
     | ResponseValidationError
     | ConnectionError
@@ -70,6 +75,11 @@ async function $do(
       | errors.ResourceNotFoundError
       | errors.TooManyRequestsError
       | errors.InternalServerError
+      | errors.CatalogConflictError
+      | errors.PayloadTooLargeError
+      | errors.BadGatewayError
+      | errors.ServiceUnavailableError
+      | errors.GatewayTimeoutError
       | LambdaDBError
       | ResponseValidationError
       | ConnectionError
@@ -173,6 +183,11 @@ async function $do(
     | errors.ResourceNotFoundError
     | errors.TooManyRequestsError
     | errors.InternalServerError
+    | errors.CatalogConflictError
+    | errors.PayloadTooLargeError
+    | errors.BadGatewayError
+    | errors.ServiceUnavailableError
+    | errors.GatewayTimeoutError
     | LambdaDBError
     | ResponseValidationError
     | ConnectionError
@@ -186,8 +201,10 @@ async function $do(
     M.jsonErr(400, errors.BadRequestError$inboundSchema),
     M.jsonErr(401, errors.UnauthenticatedError$inboundSchema),
     M.jsonErr(404, errors.ResourceNotFoundError$inboundSchema),
+    M.jsonErr(409, errors.CatalogConflictError$inboundSchema),
     M.jsonErr(429, errors.TooManyRequestsError$inboundSchema),
     M.jsonErr(500, errors.InternalServerError$inboundSchema),
+    ...M.gatewayErrorMatchers(),
     M.fail("4XX"),
     M.fail("5XX"),
   )(response, req, { extraFields: responseFields });

package/src/index.ts

@@ -12,12 +12,29 @@ export * from "./sdk/sdk.js";
 export {
   LambdaDBClient,
   CollectionHandle,
+  CollectionDocs,
   DEFAULT_BASE_URL,
   DEFAULT_PROJECT_NAME,
   type RequestOptions as ClientRequestOptions,
   type LambdaDBClientOptions,
 } from "./client.js";
 
+/** Data Versioning lifecycle clients and validated ref/source/target helpers. */
+export {
+  CollectionAliases,
+  CollectionBranches,
+  CollectionTags,
+  DATA_VERSIONING_CONTRACT_REVISION,
+  aliasRef,
+  branchRef,
+  branchSource,
+  branchTarget,
+  tagRef,
+  tagSource,
+  tagTarget,
+} from "./versioning.js";
+export type { VersioningError } from "./versioning.js";
+
 /** Public API types (inputs and responses for the collection-scoped client). */
 export type * from "./types/public.js";
 

package/src/lib/collectionContract.ts

@@ -0,0 +1,42 @@
+import * as z from "zod/v3";
+
+// Mirrors Java String.isBlank, which is the server-side contract. In
+// particular, NBSP (U+00A0), figure space (U+2007), and narrow NBSP (U+202F)
+// are not considered blank by Java.
+const javaWhitespaceCodePoints = new Set([
+  ...Array.from({ length: 5 }, (_, index) => 0x0009 + index),
+  ...Array.from({ length: 5 }, (_, index) => 0x001c + index),
+  0x1680,
+  ...Array.from({ length: 7 }, (_, index) => 0x2000 + index),
+  ...Array.from({ length: 3 }, (_, index) => 0x2008 + index),
+  0x2028,
+  0x2029,
+  0x205f,
+  0x3000,
+]);
+
+function isJavaBlank(value: string): boolean {
+  return Array.from(value).every((character) =>
+    javaWhitespaceCodePoints.has(character.codePointAt(0) ?? -1)
+  );
+}
+
+const collectionTagValueSchema = z.string()
+  .min(1)
+  .max(127)
+  .regex(/^[^:#,]+$/)
+  .refine((value) => !isJavaBlank(value), {
+    message: "Collection tag values must contain a non-whitespace character",
+  });
+
+/** @internal */
+export const collectionTagsSchema = z.record(collectionTagValueSchema)
+  .refine((value) => Object.keys(value).length <= 5, {
+    message: "Collection tags support at most five entries",
+  })
+  .refine(
+    (value) => Object.keys(value).every((key) =>
+      /^[A-Za-z0-9_.-]{1,63}$/.test(key)
+    ),
+    { message: "Invalid collection tag key" },
+  );

package/src/lib/config.ts

@@ -73,8 +73,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "1.1.1",
-  sdkVersion: "0.4.3",
+  sdkVersion: "0.5.0-rc.2",
   genVersion: "2.798.0",
   userAgent:
-    "speakeasy-sdk/typescript 0.4.3 2.798.0 1.1.1 @functional-systems/lambdadb",
+    "speakeasy-sdk/typescript 0.5.0-rc.2 2.798.0 1.1.1 @functional-systems/lambdadb",
 } as const;

package/src/lib/matchers.ts

@@ -3,6 +3,16 @@
  */
 
 import { LambdaDBDefaultError } from "../models/errors/lambdadbdefaulterror.js";
+import {
+  BadGatewayError$inboundSchema,
+  GatewayTimeoutError$inboundSchema,
+  PayloadTooLargeError$inboundSchema,
+  ServiceUnavailableError$inboundSchema,
+  type BadGatewayError,
+  type GatewayTimeoutError,
+  type PayloadTooLargeError,
+  type ServiceUnavailableError,
+} from "../models/errors/gatewayerrors.js";
 import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
 import { ERR, OK, Result } from "../types/fp.js";
 import { matchResponse, matchStatusCode, StatusCodePredicate } from "./http.js";
@@ -167,6 +177,23 @@ export function fail(codes: StatusCodePredicate): FailMatcher {
   return { enc: "fail", codes };
 }
 
+/** Standard JSON Gateway failures shared by public API operations. */
+export function gatewayErrorMatchers(): Array<
+  ErrorMatcher<
+    | PayloadTooLargeError
+    | BadGatewayError
+    | ServiceUnavailableError
+    | GatewayTimeoutError
+  >
+> {
+  return [
+    jsonErr(413, PayloadTooLargeError$inboundSchema),
+    jsonErr(502, BadGatewayError$inboundSchema),
+    jsonErr(503, ServiceUnavailableError$inboundSchema),
+    jsonErr(504, GatewayTimeoutError$inboundSchema),
+  ];
+}
+
 export type MatchedValue<Matchers> = Matchers extends Matcher<infer T, any>[]
   ? T
   : never;

package/src/lib/queryInput.ts

@@ -2,20 +2,13 @@
  * Helper to build QueryCollectionInput for collection.query() / collection.querySafe().
  */
 
-import type { FieldsSelectorUnion, PartitionFilter } from "../models/index.js";
 import type { QueryCollectionInput } from "../types/public.js";
 
 /**
  * Options for createQueryInput (all optional except query).
  */
-export type CreateQueryInputOptions = {
-  size?: number;
-  consistentRead?: boolean;
-  includeVectors?: boolean;
-  sort?: Array<{ [k: string]: unknown }>;
-  fields?: FieldsSelectorUnion;
-  partitionFilter?: PartitionFilter;
-};
+type WithoutQuery<T> = T extends unknown ? Omit<T, "query"> : never;
+export type CreateQueryInputOptions = WithoutQuery<QueryCollectionInput>;
 
 /**
  * Build a query input object for collection.query() or collection.querySafe().
@@ -29,5 +22,5 @@ export function createQueryInput(
   query: { [k: string]: unknown },
   options?: CreateQueryInputOptions,
 ): QueryCollectionInput {
-  return { query, ...options };
+  return { query, ...options } as QueryCollectionInput;
 }

package/src/models/collectionresponse.ts

@@ -14,7 +14,6 @@ import {
   PartitionConfig,
   PartitionConfig$inboundSchema,
 } from "./partitionconfig.js";
-import { Status, Status$inboundSchema } from "./status.js";
 
 export type CollectionResponse = {
   /**
@@ -26,43 +25,38 @@ export type CollectionResponse = {
    */
   collectionName: string;
   indexConfigs: { [k: string]: IndexConfigsUnion };
+  /** Collection description. */
+  description: string;
+  /** Collection metadata tags. */
+  tags: Record<string, string>;
   partitionConfig?: PartitionConfig | undefined;
   /**
    * Total number of partitions including the default partition.
    */
   numPartitions: number;
   /**
-   * Total number of documents.
+   * Document count in the default main Branch's committed head. This is not a
+   * sum across Branches or the count of a selected ref.
    */
   numDocs: number;
+  /** Default writable Branch. */
+  defaultBranchName: "main";
+  /** Number of days that committed snapshots are retained. */
+  snapshotRetentionInDays: number;
   /**
-   * Source project name.
-   */
-  sourceProjectName?: string | undefined;
-  /**
-   * Source collection name.
-   */
-  sourceCollectionName?: string | undefined;
-  /**
-   * Source collection version.
-   */
-  sourceCollectionVersionId?: string | undefined;
-  /**
-   * Status
-   */
-  collectionStatus: Status;
-  /**
-   * Collection creation time in seconds since the Unix epoch.
+   * Collection creation time in milliseconds since the Unix epoch.
    */
   createdAt: number;
   /**
-   * Collection last update time in seconds since the Unix epoch.
+   * Collection last update time in milliseconds since the Unix epoch.
    */
   updatedAt: number;
   /**
-   * Collection data last update time in seconds since the Unix epoch.
+   * Last data update recorded in the default main Branch's committed head, in
+   * milliseconds since the Unix epoch. Commits without data mutations retain
+   * the previous value. Absent before a committed head exists.
    */
-  dataUpdatedAt: number;
+  dataUpdatedAt?: number | undefined;
 };
 
 /** @internal */
@@ -73,17 +67,20 @@ export const CollectionResponse$inboundSchema: z.ZodType<
 > = z.object({
   projectName: z.string(),
   collectionName: z.string(),
-  indexConfigs: z.record(IndexConfigsUnion$inboundSchema),
+  indexConfigs: z.record(IndexConfigsUnion$inboundSchema).refine(
+    (value) => Object.keys(value).length > 0,
+    { message: "Collection indexConfigs must contain at least one field" },
+  ),
+  description: z.string(),
+  tags: z.record(z.string()),
   partitionConfig: nullToUndefined(PartitionConfig$inboundSchema.optional()),
   numPartitions: z.number().int(),
   numDocs: z.number().int(),
-  sourceProjectName: nullToUndefined(z.string().optional()),
-  sourceCollectionName: nullToUndefined(z.string().optional()),
-  sourceCollectionVersionId: nullToUndefined(z.string().optional()),
-  collectionStatus: Status$inboundSchema,
+  defaultBranchName: z.literal("main"),
+  snapshotRetentionInDays: z.number().int().min(1).max(31),
   createdAt: z.number().int(),
   updatedAt: z.number().int(),
-  dataUpdatedAt: z.number().int(),
+  dataUpdatedAt: nullToUndefined(z.number().int().optional()),
 });
 
 export function collectionResponseFromJSON(

package/src/models/errors/gatewayerrors.ts

@@ -0,0 +1,104 @@
+import * as z from "zod/v3";
+
+import { nullToUndefined } from "../../lib/schemas.js";
+import { LambdaDBError } from "./lambdadberror.js";
+
+export type GatewayErrorData = {
+  message?: string | undefined;
+};
+
+type HTTPMeta = {
+  response: Response;
+  request: Request;
+  body: string;
+};
+
+class GatewayResponseError extends LambdaDBError {
+  /** The structured JSON error returned by the Gateway. */
+  readonly data$: GatewayErrorData;
+
+  protected constructor(name: string, err: GatewayErrorData, httpMeta: HTTPMeta) {
+    super(
+      err.message || `API error occurred: ${JSON.stringify(err)}`,
+      httpMeta,
+    );
+    this.data$ = err;
+    this.name = name;
+  }
+}
+
+/** HTTP 409 conditional catalog conflict. */
+export class CatalogConflictError extends GatewayResponseError {
+  constructor(err: GatewayErrorData, httpMeta: HTTPMeta) {
+    super("CatalogConflictError", err, httpMeta);
+  }
+}
+
+/** HTTP 413 Gateway transport limit exceeded. */
+export class PayloadTooLargeError extends GatewayResponseError {
+  constructor(err: GatewayErrorData, httpMeta: HTTPMeta) {
+    super("PayloadTooLargeError", err, httpMeta);
+  }
+}
+
+/** HTTP 502 unexpected downstream failure. */
+export class BadGatewayError extends GatewayResponseError {
+  constructor(err: GatewayErrorData, httpMeta: HTTPMeta) {
+    super("BadGatewayError", err, httpMeta);
+  }
+}
+
+/** HTTP 503 transient catalog or storage dependency failure. */
+export class ServiceUnavailableError extends GatewayResponseError {
+  constructor(err: GatewayErrorData, httpMeta: HTTPMeta) {
+    super("ServiceUnavailableError", err, httpMeta);
+  }
+}
+
+/** HTTP 504 Gateway request deadline exceeded. */
+export class GatewayTimeoutError extends GatewayResponseError {
+  constructor(err: GatewayErrorData, httpMeta: HTTPMeta) {
+    super("GatewayTimeoutError", err, httpMeta);
+  }
+}
+
+type GatewayErrorConstructor<T extends GatewayResponseError> = new (
+  err: GatewayErrorData,
+  httpMeta: HTTPMeta,
+) => T;
+
+function gatewayErrorSchema<T extends GatewayResponseError>(
+  ErrorClass: GatewayErrorConstructor<T>,
+): z.ZodType<T, z.ZodTypeDef, unknown> {
+  return z.object({
+    message: nullToUndefined(z.string().optional()),
+    request$: z.instanceof(Request),
+    response$: z.instanceof(Response),
+    body$: z.string(),
+  }).transform((value) =>
+    new ErrorClass(value, {
+      request: value.request$,
+      response: value.response$,
+      body: value.body$,
+    })
+  );
+}
+
+/** @internal */
+export const CatalogConflictError$inboundSchema = gatewayErrorSchema(
+  CatalogConflictError,
+);
+/** @internal */
+export const PayloadTooLargeError$inboundSchema = gatewayErrorSchema(
+  PayloadTooLargeError,
+);
+/** @internal */
+export const BadGatewayError$inboundSchema = gatewayErrorSchema(BadGatewayError);
+/** @internal */
+export const ServiceUnavailableError$inboundSchema = gatewayErrorSchema(
+  ServiceUnavailableError,
+);
+/** @internal */
+export const GatewayTimeoutError$inboundSchema = gatewayErrorSchema(
+  GatewayTimeoutError,
+);

package/src/models/errors/index.ts

@@ -3,6 +3,7 @@
  */
 
 export * from "./badrequesterror.js";
+export * from "./gatewayerrors.js";
 export * from "./httpclienterrors.js";
 export * from "./internalservererror.js";
 export * from "./lambdadbdefaulterror.js";

package/src/models/errors/lambdadberror.ts

@@ -15,6 +15,11 @@ export class LambdaDBError extends Error {
   /** Raw response */
   public readonly rawResponse: Response;
 
+  /** Optional Retry-After response header, commonly returned with HTTP 429. */
+  public get retryAfter(): string | undefined {
+    return this.headers.get("retry-after") ?? undefined;
+  }
+
   constructor(
     message: string,
     httpMeta: {

package/src/models/index.ts

@@ -10,3 +10,4 @@ export * from "./partitionconfig.js";
 export * from "./partitionfilter.js";
 export * from "./security.js";
 export * from "./status.js";
+export * from "./versioning.js";

package/src/models/operations/bulkupsertdocs.ts

@@ -10,6 +10,10 @@ export type BulkUpsertDocsRequestBody = {
    * Object key uploaded based on bulk upsert info.
    */
   objectKey: string;
+  /** Content type supplied by the bulk-upload info response. */
+  type?: "application/json" | undefined;
+  /** Write target Branch. Must match the bulk-upload info request. */
+  branch?: string | undefined;
 };
 
 export type BulkUpsertDocsRequest = {
@@ -23,6 +27,8 @@ export type BulkUpsertDocsRequest = {
 /** @internal */
 export type BulkUpsertDocsRequestBody$Outbound = {
   objectKey: string;
+  type: "application/json";
+  branch?: string | undefined;
 };
 
 /** @internal */
@@ -32,7 +38,9 @@ export const BulkUpsertDocsRequestBody$outboundSchema: z.ZodType<
   BulkUpsertDocsRequestBody
 > = z.object({
   objectKey: z.string(),
-});
+  type: z.literal("application/json").default("application/json"),
+  branch: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
+}).strict();
 
 export function bulkUpsertDocsRequestBodyToJSON(
   bulkUpsertDocsRequestBody: BulkUpsertDocsRequestBody,

package/src/models/operations/createcollection.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { collectionTagsSchema } from "../../lib/collectionContract.js";
 import { safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
@@ -13,30 +14,38 @@ export type CreateCollectionRequest = {
    * Collection name must be unique within a project and the supported maximum length is 52.
    */
   collectionName: string;
-  indexConfigs?: { [k: string]: models.IndexConfigsUnion } | undefined;
+  indexConfigs: { [k: string]: models.IndexConfigsUnion };
+  description?: string | undefined;
+  tags?: Record<string, string> | undefined;
   partitionConfig?: models.PartitionConfig | undefined;
-  sourceProjectName?: string | undefined;
-  sourceCollectionName?: string | undefined;
-  sourceDatetime?: string | undefined;
-  sourceProjectApiKey?: string | undefined;
+  snapshotRetentionInDays?: number | undefined;
+};
+
+export type CreatedCollection = {
+  collectionName: string;
+  description: string;
+  tags: Record<string, string>;
+  defaultBranchName: "main";
+  snapshotRetentionInDays: number;
+  /** Collection creation time as Unix epoch milliseconds. */
+  createdAt: number;
 };
 
 /**
  * Created collection
  */
 export type CreateCollectionResponse = {
-  collection: models.CollectionResponse;
+  collection: CreatedCollection;
 };
 
 /** @internal */
 export type CreateCollectionRequest$Outbound = {
   collectionName: string;
-  indexConfigs?: { [k: string]: models.IndexConfigsUnion$Outbound } | undefined;
+  indexConfigs: { [k: string]: models.IndexConfigsUnion$Outbound };
+  description?: string | undefined;
+  tags?: Record<string, string> | undefined;
   partitionConfig?: models.PartitionConfig$Outbound | undefined;
-  sourceProjectName?: string | undefined;
-  sourceCollectionName?: string | undefined;
-  sourceDatetime?: string | undefined;
-  sourceProjectApiKey?: string | undefined;
+  snapshotRetentionInDays?: number | undefined;
 };
 
 /** @internal */
@@ -45,14 +54,16 @@ export const CreateCollectionRequest$outboundSchema: z.ZodType<
   z.ZodTypeDef,
   CreateCollectionRequest
 > = z.object({
-  collectionName: z.string(),
-  indexConfigs: z.record(models.IndexConfigsUnion$outboundSchema).optional(),
+  collectionName: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/),
+  indexConfigs: z.record(models.IndexConfigsUnion$outboundSchema).refine(
+    (value) => Object.keys(value).length > 0,
+    { message: "Collection indexConfigs must contain at least one field" },
+  ),
+  description: z.string().max(255).optional(),
+  tags: collectionTagsSchema.optional(),
   partitionConfig: models.PartitionConfig$outboundSchema.optional(),
-  sourceProjectName: z.string().optional(),
-  sourceCollectionName: z.string().optional(),
-  sourceDatetime: z.string().optional(),
-  sourceProjectApiKey: z.string().optional(),
-});
+  snapshotRetentionInDays: z.number().int().min(1).max(31).optional(),
+}).strict();
 
 export function createCollectionRequestToJSON(
   createCollectionRequest: CreateCollectionRequest,
@@ -68,7 +79,14 @@ export const CreateCollectionResponse$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  collection: models.CollectionResponse$inboundSchema,
+  collection: z.object({
+    collectionName: z.string(),
+    description: z.string(),
+    tags: z.record(z.string()),
+    defaultBranchName: z.literal("main"),
+    snapshotRetentionInDays: z.number().int().min(1).max(31),
+    createdAt: z.number().int(),
+  }),
 });
 
 export function createCollectionResponseFromJSON(

package/src/models/operations/deletedocs.ts

@@ -6,7 +6,7 @@ import * as z from "zod/v3";
 import { remap as remap$ } from "../../lib/primitives.js";
 import * as models from "../index.js";
 
-export type DeleteDocsRequestBody = {
+type DeleteDocsRequestFields = {
   /**
    * A list of document IDs.
    */
@@ -16,8 +16,21 @@ export type DeleteDocsRequestBody = {
    */
   filter?: { [k: string]: any } | undefined;
   partitionFilter?: models.PartitionFilter | undefined;
+  /** Write target Branch. Omitting it writes to main. */
+  branch?: string | undefined;
 };
 
+/** Delete by exactly one selector. partitionFilter only narrows that selector. */
+export type DeleteDocsRequestBody =
+  | (DeleteDocsRequestFields & {
+    ids: Array<string>;
+    filter?: never;
+  })
+  | (DeleteDocsRequestFields & {
+    ids?: never;
+    filter: { [k: string]: any };
+  });
+
 export type DeleteDocsRequest = {
   /**
    * Collection name.
@@ -27,12 +40,24 @@ export type DeleteDocsRequest = {
 };
 
 /** @internal */
-export type DeleteDocsRequestBody$Outbound = {
+type DeleteDocsRequestFields$Outbound = {
   ids?: Array<string> | undefined;
   filter?: { [k: string]: any } | undefined;
   partitionFilter?: models.PartitionFilter$Outbound | undefined;
+  branch?: string | undefined;
 };
 
+/** @internal */
+export type DeleteDocsRequestBody$Outbound =
+  | (DeleteDocsRequestFields$Outbound & {
+    ids: Array<string>;
+    filter?: never;
+  })
+  | (DeleteDocsRequestFields$Outbound & {
+    ids?: never;
+    filter: { [k: string]: any };
+  });
+
 /** @internal */
 export const DeleteDocsRequestBody$outboundSchema: z.ZodType<
   DeleteDocsRequestBody$Outbound,
@@ -42,7 +67,15 @@ export const DeleteDocsRequestBody$outboundSchema: z.ZodType<
   ids: z.array(z.string()).optional(),
   filter: z.record(z.any()).optional(),
   partitionFilter: models.PartitionFilter$outboundSchema.optional(),
-});
+  branch: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
+}).strict().refine(
+  (value) => (value.ids === undefined) !== (value.filter === undefined),
+  { message: "Specify exactly one of ids or filter", path: ["ids"] },
+) as unknown as z.ZodType<
+  DeleteDocsRequestBody$Outbound,
+  z.ZodTypeDef,
+  DeleteDocsRequestBody
+>;
 
 export function deleteDocsRequestBodyToJSON(
   deleteDocsRequestBody: DeleteDocsRequestBody,

package/src/models/operations/fetchdocs.ts

@@ -15,7 +15,7 @@ export type FetchDocsRequestBody = {
    */
   ids: Array<string>;
   /**
-   * If your application requires a strongly consistent read, set consistentRead to true. Although a strongly consistent read might take more time than an eventually consistent read, it always returns the last updated value.
+   * Overlay eligible pending writes on a directly selected Branch. Tag and Alias reads reject true, pending bulk imports are excluded, and an oversized pending overlay can return HTTP 429.
    */
   consistentRead?: boolean | undefined;
   /**
@@ -27,6 +27,8 @@ export type FetchDocsRequestBody = {
    */
   fields?: models.FieldsSelectorUnion | undefined;
   partitionFilter?: models.PartitionFilter | undefined;
+  /** Read target. Omitting it reads from main. */
+  ref?: models.ReadRef | undefined;
 };
 
 export type FetchDocsRequest = {
@@ -72,6 +74,7 @@ export type FetchDocsRequestBody$Outbound = {
   includeVectors: boolean;
   fields?: models.FieldsSelectorUnion$Outbound | undefined;
   partitionFilter?: models.PartitionFilter$Outbound | undefined;
+  ref?: models.ReadRef | undefined;
 };
 
 /** @internal */
@@ -85,6 +88,15 @@ export const FetchDocsRequestBody$outboundSchema: z.ZodType<
   includeVectors: z.boolean().default(false),
   fields: models.FieldsSelectorUnion$outboundSchema.optional(),
   partitionFilter: models.PartitionFilter$outboundSchema.optional(),
+  ref: models.ReadRef$schema.optional(),
+}).strict().superRefine((value, context) => {
+  if (value.consistentRead && value.ref != null && value.ref.kind !== "branch") {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "consistentRead is supported only for direct Branch reads",
+      path: ["consistentRead"],
+    });
+  }
 });
 
 export function fetchDocsRequestBodyToJSON(