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

package/src/models/operations/getbulkupsertdocs.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { nullToUndefined, safeParse } from "../../lib/schemas.js";
+import { safeParse } from "../../lib/schemas.js";
 import { ClosedEnum } from "../../types/enums.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
@@ -13,6 +13,8 @@ export type GetBulkUpsertDocsRequest = {
    * Collection name.
    */
   collectionName: string;
+  /** Write target Branch. Omitting it writes to main. */
+  branch?: string | undefined;
 };
 
 /**
@@ -61,11 +63,14 @@ export type GetBulkUpsertDocsResponse = {
    * Object size limit in bytes.
    */
   sizeLimitBytes: number;
+  /** Signed headers to forward unchanged to the presigned upload URL. */
+  headers: Record<string, string>;
 };
 
 /** @internal */
 export type GetBulkUpsertDocsRequest$Outbound = {
   collectionName: string;
+  branch?: string | undefined;
 };
 
 /** @internal */
@@ -75,6 +80,7 @@ export const GetBulkUpsertDocsRequest$outboundSchema: z.ZodType<
   GetBulkUpsertDocsRequest
 > = z.object({
   collectionName: z.string(),
+  branch: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
 });
 
 export function getBulkUpsertDocsRequestToJSON(
@@ -101,10 +107,11 @@ export const GetBulkUpsertDocsResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   url: z.string(),
-  type: nullToUndefined(Type$inboundSchema.default("application/json")),
-  httpMethod: nullToUndefined(HttpMethod$inboundSchema.default("PUT")),
+  type: Type$inboundSchema,
+  httpMethod: HttpMethod$inboundSchema,
   objectKey: z.string(),
-  sizeLimitBytes: nullToUndefined(z.number().int().default(209715200)),
+  sizeLimitBytes: z.number().int(),
+  headers: z.record(z.string()),
 });
 
 export function getBulkUpsertDocsResponseFromJSON(

package/src/models/operations/listdocs.ts

@@ -19,13 +19,17 @@ export type ListDocsRequest = {
    */
   size?: number | undefined;
   /**
-   * Next page token.
+   * Opaque search position, not a Snapshot pin. Use one immutable Tag throughout a stable export.
    */
   pageToken?: string | undefined;
   /**
    * Set to true to include vector values in the response. Defaults to false.
    */
   includeVectors?: boolean | undefined;
+  /** Read ref kind. Must be supplied together with refName. */
+  refKind?: models.ReadRef["kind"] | undefined;
+  /** Read ref name. Must be supplied together with refKind. */
+  refName?: string | undefined;
 };
 
 export type ListDocsDoc = {
@@ -59,6 +63,8 @@ export type ListDocsRequest$Outbound = {
   size?: number | undefined;
   pageToken?: string | undefined;
   includeVectors: boolean;
+  refKind?: models.ReadRef["kind"] | undefined;
+  refName?: string | undefined;
 };
 
 /** @internal */
@@ -71,6 +77,16 @@ export const ListDocsRequest$outboundSchema: z.ZodType<
   size: z.number().int().optional(),
   pageToken: z.string().optional(),
   includeVectors: z.boolean().default(false),
+  refKind: z.enum(["branch", "tag", "alias"]).optional(),
+  refName: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
+}).superRefine((value, context) => {
+  if ((value.refKind == null) !== (value.refName == null)) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "refKind and refName must be supplied together",
+      path: [value.refKind == null ? "refKind" : "refName"],
+    });
+  }
 });
 
 export function listDocsRequestToJSON(
@@ -85,7 +101,7 @@ export type ListDocsExtendedRequestBody = {
    */
   size?: number | undefined;
   /**
-   * Next page token.
+   * Opaque search position, not a Snapshot pin. Use one immutable Tag throughout a stable export.
    */
   pageToken?: string | undefined;
   /**
@@ -101,6 +117,8 @@ export type ListDocsExtendedRequestBody = {
    * Set to true to include vector values in the response. Defaults to false.
    */
   includeVectors?: boolean | undefined;
+  /** Read target. Omitting it reads from main. */
+  ref?: models.ReadRef | undefined;
 };
 
 export type ListDocsExtendedRequest = {
@@ -119,6 +137,7 @@ export type ListDocsExtendedRequestBody$Outbound = {
   partitionFilter?: models.PartitionFilter$Outbound | undefined;
   fields?: models.FieldsSelectorUnion$Outbound | undefined;
   includeVectors: boolean;
+  ref?: models.ReadRef | undefined;
 };
 
 /** @internal */
@@ -133,7 +152,8 @@ export const ListDocsExtendedRequestBody$outboundSchema: z.ZodType<
   partitionFilter: models.PartitionFilter$outboundSchema.optional(),
   fields: models.FieldsSelectorUnion$outboundSchema.optional(),
   includeVectors: z.boolean().default(false),
-});
+  ref: models.ReadRef$schema.optional(),
+}).strict();
 
 export function listDocsExtendedRequestBodyToJSON(
   listDocsExtendedRequestBody: ListDocsExtendedRequestBody,

package/src/models/operations/querycollection.ts

@@ -19,7 +19,7 @@ export type QueryCollectionRequestBody = {
    */
   query: { [k: string]: any };
   /**
-   * 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;
   /**
@@ -35,6 +35,8 @@ export type QueryCollectionRequestBody = {
    */
   fields?: models.FieldsSelectorUnion | undefined;
   partitionFilter?: models.PartitionFilter | undefined;
+  /** Read target. Omitting it reads from main. */
+  ref?: models.ReadRef | undefined;
 };
 
 export type QueryCollectionRequest = {
@@ -96,6 +98,7 @@ export type QueryCollectionRequestBody$Outbound = {
   sort?: Array<{ [k: string]: any }> | undefined;
   fields?: models.FieldsSelectorUnion$Outbound | undefined;
   partitionFilter?: models.PartitionFilter$Outbound | undefined;
+  ref?: models.ReadRef | undefined;
 };
 
 /** @internal */
@@ -111,6 +114,15 @@ export const QueryCollectionRequestBody$outboundSchema: z.ZodType<
   sort: z.array(z.record(z.any())).optional(),
   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 queryCollectionRequestBodyToJSON(

package/src/models/operations/updatecollection.ts

@@ -3,16 +3,28 @@
  */
 
 import * as z from "zod/v3";
+import { collectionTagsSchema } from "../../lib/collectionContract.js";
 import { remap as remap$ } from "../../lib/primitives.js";
 import { safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import * as models from "../index.js";
 
-export type UpdateCollectionRequestBody = {
-  indexConfigs: { [k: string]: models.IndexConfigsUnion };
+type UpdateCollectionFields = {
+  indexConfigs?: { [k: string]: models.IndexConfigsUnion } | null | undefined;
+  description?: string | null | undefined;
+  tags?: Record<string, string> | null | undefined;
+  snapshotRetentionInDays?: number | null | undefined;
 };
 
+export type UpdateCollectionRequestBody =
+  | (UpdateCollectionFields & {
+    indexConfigs: { [k: string]: models.IndexConfigsUnion };
+  })
+  | (UpdateCollectionFields & { description: string })
+  | (UpdateCollectionFields & { tags: Record<string, string> })
+  | (UpdateCollectionFields & { snapshotRetentionInDays: number });
+
 export type UpdateCollectionRequest = {
   /**
    * Collection name.
@@ -29,18 +41,45 @@ export type UpdateCollectionResponse = {
 };
 
 /** @internal */
-export type UpdateCollectionRequestBody$Outbound = {
-  indexConfigs: { [k: string]: models.IndexConfigsUnion$Outbound };
+type UpdateCollectionFields$Outbound = {
+  indexConfigs?:
+    | { [k: string]: models.IndexConfigsUnion$Outbound }
+    | null
+    | undefined;
+  description?: string | null | undefined;
+  tags?: Record<string, string> | null | undefined;
+  snapshotRetentionInDays?: number | null | undefined;
 };
 
+export type UpdateCollectionRequestBody$Outbound =
+  | (UpdateCollectionFields$Outbound & {
+    indexConfigs: { [k: string]: models.IndexConfigsUnion$Outbound };
+  })
+  | (UpdateCollectionFields$Outbound & { description: string })
+  | (UpdateCollectionFields$Outbound & { tags: Record<string, string> })
+  | (UpdateCollectionFields$Outbound & { snapshotRetentionInDays: number });
+
 /** @internal */
 export const UpdateCollectionRequestBody$outboundSchema: z.ZodType<
   UpdateCollectionRequestBody$Outbound,
   z.ZodTypeDef,
   UpdateCollectionRequestBody
 > = z.object({
-  indexConfigs: z.record(models.IndexConfigsUnion$outboundSchema),
-});
+  indexConfigs: z.record(models.IndexConfigsUnion$outboundSchema).refine(
+    (value) => Object.keys(value).length > 0,
+    { message: "Collection indexConfigs must contain at least one field" },
+  ).nullable().optional(),
+  description: z.string().max(255).nullable().optional(),
+  tags: collectionTagsSchema.nullable().optional(),
+  snapshotRetentionInDays: z.number().int().min(1).max(31).nullable().optional(),
+}).strict().refine(
+  (value) => Object.values(value).some((item) => item !== undefined && item !== null),
+  { message: "At least one non-null collection field must be provided" },
+) as z.ZodType<
+  UpdateCollectionRequestBody$Outbound,
+  z.ZodTypeDef,
+  UpdateCollectionRequestBody
+>;
 
 export function updateCollectionRequestBodyToJSON(
   updateCollectionRequestBody: UpdateCollectionRequestBody,

package/src/models/operations/updatedocs.ts

@@ -10,6 +10,8 @@ export type UpdateDocsRequestBody = {
    * A list of documents to update. Each document must contain 'id' field to be updated. For managed embedding vector fields, omit the managed vector field and update only the configured source text field.
    */
   docs: Array<{ [k: string]: any }>;
+  /** Write target Branch. Omitting it writes to main. */
+  branch?: string | undefined;
 };
 
 export type UpdateDocsRequest = {
@@ -23,6 +25,7 @@ export type UpdateDocsRequest = {
 /** @internal */
 export type UpdateDocsRequestBody$Outbound = {
   docs: Array<{ [k: string]: any }>;
+  branch?: string | undefined;
 };
 
 /** @internal */
@@ -32,7 +35,8 @@ export const UpdateDocsRequestBody$outboundSchema: z.ZodType<
   UpdateDocsRequestBody
 > = z.object({
   docs: z.array(z.record(z.any())),
-});
+  branch: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
+}).strict();
 
 export function updateDocsRequestBodyToJSON(
   updateDocsRequestBody: UpdateDocsRequestBody,

package/src/models/operations/upsertdocs.ts

@@ -10,6 +10,8 @@ export type UpsertDocsRequestBody = {
    * A list of documents to upsert. For managed embedding vector fields, omit the managed vector field and provide only the configured source text field.
    */
   docs: Array<{ [k: string]: any }>;
+  /** Write target Branch. Omitting it writes to main. */
+  branch?: string | undefined;
 };
 
 export type UpsertDocsRequest = {
@@ -23,6 +25,7 @@ export type UpsertDocsRequest = {
 /** @internal */
 export type UpsertDocsRequestBody$Outbound = {
   docs: Array<{ [k: string]: any }>;
+  branch?: string | undefined;
 };
 
 /** @internal */
@@ -32,7 +35,8 @@ export const UpsertDocsRequestBody$outboundSchema: z.ZodType<
   UpsertDocsRequestBody
 > = z.object({
   docs: z.array(z.record(z.any())),
-});
+  branch: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
+}).strict();
 
 export function upsertDocsRequestBodyToJSON(
   upsertDocsRequestBody: UpsertDocsRequestBody,

package/src/models/versioning.ts

@@ -0,0 +1,118 @@
+import * as z from "zod/v3";
+
+const refNameSchema = z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/);
+
+export type BranchRef = {
+  kind: "branch";
+  name: string;
+};
+
+export type TagRef = {
+  kind: "tag";
+  name: string;
+};
+
+export type AliasRef = {
+  kind: "alias";
+  name: string;
+};
+
+/** A Branch, Tag, or Alias used to select document reads. */
+export type ReadRef = BranchRef | TagRef | AliasRef;
+
+export type BranchSource = BranchRef & {
+  /** Latest committed snapshot cutoff as Unix epoch milliseconds. */
+  asOf?: number | undefined;
+};
+
+export type TagSource = TagRef;
+
+/** A Branch or Tag used as the source of a new Branch or Tag. */
+export type RefSource = BranchSource | TagSource;
+
+/** A Branch or Tag used as the target of an Alias. */
+export type AliasTarget = BranchRef | TagRef;
+
+export type RefDetails = {
+  name: string;
+  snapshotId: string | null;
+  /** Ref creation time as Unix epoch milliseconds. */
+  createdAt: number;
+};
+
+export type AliasTargetKind = "BRANCH" | "TAG";
+
+export type AliasDetails = {
+  aliasId: string;
+  aliasName: string;
+  targetKind: AliasTargetKind;
+  targetName: string;
+  targetId: string;
+  aliasRevision: number;
+  dangling: boolean;
+  /** Alias creation time as Unix epoch milliseconds. */
+  createdAt: number;
+};
+
+/** @internal */
+export const BranchRef$schema = z.object({
+  kind: z.literal("branch"),
+  name: refNameSchema,
+}).strict();
+
+/** @internal */
+export const TagRef$schema = z.object({
+  kind: z.literal("tag"),
+  name: refNameSchema,
+}).strict();
+
+/** @internal */
+export const AliasRef$schema = z.object({
+  kind: z.literal("alias"),
+  name: refNameSchema,
+}).strict();
+
+/** @internal */
+export const ReadRef$schema: z.ZodType<ReadRef> = z.discriminatedUnion("kind", [
+  BranchRef$schema,
+  TagRef$schema,
+  AliasRef$schema,
+]);
+
+/** @internal */
+export const BranchSource$schema = z.object({
+  kind: z.literal("branch"),
+  name: refNameSchema,
+  asOf: z.number().int().optional(),
+}).strict();
+
+/** @internal */
+export const RefSource$schema: z.ZodType<RefSource> = z.union([
+  BranchSource$schema,
+  TagRef$schema,
+]);
+
+/** @internal */
+export const AliasTarget$schema: z.ZodType<AliasTarget> = z.union([
+  BranchRef$schema,
+  TagRef$schema,
+]);
+
+/** @internal */
+export const RefDetails$inboundSchema: z.ZodType<RefDetails> = z.object({
+  name: z.string(),
+  snapshotId: z.string().nullable(),
+  createdAt: z.number().int(),
+});
+
+/** @internal */
+export const AliasDetails$inboundSchema: z.ZodType<AliasDetails> = z.object({
+  aliasId: z.string(),
+  aliasName: z.string(),
+  targetKind: z.enum(["BRANCH", "TAG"]),
+  targetName: z.string(),
+  targetId: z.string(),
+  aliasRevision: z.number().int().nonnegative(),
+  dangling: z.boolean(),
+  createdAt: z.number().int(),
+});

package/src/sdk/docs.ts

@@ -89,7 +89,7 @@ export class Docs extends ClientSDK {
   }
 
   /**
-   * Delete documents by document IDs or query filter from a collection.
+   * Delete documents by exactly one of document IDs or query filter.
    */
   async delete(
     request: operations.DeleteDocsRequest,

package/src/types/errors.ts

@@ -18,9 +18,14 @@ import type {
 // ---- Re-export error classes for instanceof checks and typing ----
 export {
   BadRequestError,
+  BadGatewayError,
+  CatalogConflictError,
+  GatewayTimeoutError,
   UnauthenticatedError,
+  PayloadTooLargeError,
   ResourceNotFoundError,
   ResourceAlreadyExistsError,
+  ServiceUnavailableError,
   TooManyRequestsError,
   InternalServerError,
   LambdaDBError,
@@ -50,12 +55,20 @@ export type LambdaDBClientError =
 
 // ---- API error unions (subset of errors.* per operation) ----
 
-/** Errors that can occur when listing collections, getting a collection, deleting a collection, or getting bulk upsert info. */
+/** Transport errors handled by the shared Gateway response matcher. */
+type GatewayResponseError =
+  | errors.PayloadTooLargeError
+  | errors.BadGatewayError
+  | errors.ServiceUnavailableError
+  | errors.GatewayTimeoutError;
+
+/** Errors that can occur when listing or getting collections. */
 export type ListCollectionsError =
   | errors.UnauthenticatedError
   | errors.ResourceNotFoundError
   | errors.TooManyRequestsError
   | errors.InternalServerError
+  | GatewayResponseError
   | LambdaDBClientError;
 
 /** Errors that can occur when creating a collection. */
@@ -65,6 +78,7 @@ export type CreateCollectionError =
   | errors.ResourceAlreadyExistsError
   | errors.TooManyRequestsError
   | errors.InternalServerError
+  | GatewayResponseError
   | LambdaDBClientError;
 
 /** Errors that can occur when getting a collection. */
@@ -72,26 +86,31 @@ export type GetCollectionError = ListCollectionsError;
 
 /** Errors that can occur when updating a collection. */
 export type UpdateCollectionError =
+  | errors.CatalogConflictError
+  | QueryCollectionError;
+
+/** Errors that can occur when deleting a collection. */
+export type DeleteCollectionError =
+  | errors.CatalogConflictError
+  | ListCollectionsError;
+
+/** Errors that can occur when querying a collection. */
+export type QueryCollectionError =
   | errors.BadRequestError
   | errors.UnauthenticatedError
   | errors.ResourceNotFoundError
   | errors.TooManyRequestsError
   | errors.InternalServerError
+  | GatewayResponseError
   | LambdaDBClientError;
 
-/** Errors that can occur when deleting a collection. */
-export type DeleteCollectionError = ListCollectionsError;
-
-/** Errors that can occur when querying a collection. */
-export type QueryCollectionError = UpdateCollectionError;
-
 /** Errors that can occur when listing, upserting, updating, deleting, or fetching docs, or when calling bulkUpsert. */
-export type ListDocsError = UpdateCollectionError;
-export type UpsertDocsError = UpdateCollectionError;
-export type UpdateDocsError = UpdateCollectionError;
-export type DeleteDocsError = UpdateCollectionError;
-export type FetchDocsError = UpdateCollectionError;
-export type BulkUpsertDocsError = UpdateCollectionError;
+export type ListDocsError = QueryCollectionError;
+export type UpsertDocsError = QueryCollectionError;
+export type UpdateDocsError = QueryCollectionError;
+export type DeleteDocsError = QueryCollectionError;
+export type FetchDocsError = QueryCollectionError;
+export type BulkUpsertDocsError = QueryCollectionError;
 
 /** Errors that can occur when getting bulk upsert docs info. */
 export type GetBulkUpsertDocsError =