@functional-systems/lambdadb 0.3.2 → 0.3.4-dev.0

package/src/models/indexconfigsunion.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../lib/schemas.js";
+import { nullToUndefined, 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";
@@ -47,15 +47,59 @@ export type Similarity = ClosedEnum<typeof Similarity>;
 export type IndexConfigsVector = {
   type: "vector";
   /**
-   * Vector dimensions.
+   * Set to false or omit for unmanaged vector fields.
+   */
+  managedEmbedding?: false | undefined;
+  /**
+   * Vector dimensions for unmanaged vector fields.
    */
   dimensions: number;
   /**
-   * Vector similarity metric.
+   * Vector similarity metric for unmanaged vector fields.
+   */
+  similarity?: Similarity | undefined;
+};
+
+export const EmbeddingProvider = {
+  Openai: "openai",
+} as const;
+export type EmbeddingProvider = ClosedEnum<typeof EmbeddingProvider>;
+
+/**
+ * Managed embedding configuration for vector fields.
+ */
+export type EmbeddingConfig = {
+  /**
+   * Embedding provider.
+   */
+  provider: EmbeddingProvider;
+  /**
+   * Embedding model name. See /guides/collections/managed-embeddings for the current supported providers and models.
+   */
+  model: string;
+  /**
+   * Source text field name used to generate embeddings.
+   */
+  sourceField: string;
+  /**
+   * Resolved embedding dimensions. Optional in requests and resolved in stored collection metadata.
+   */
+  dimensions?: number | undefined;
+  /**
+   * Resolved vector similarity metric. Optional in requests and resolved in stored collection metadata.
    */
   similarity?: Similarity | undefined;
 };
 
+export type IndexConfigsManagedEmbeddingVector = {
+  type: "vector";
+  /**
+   * Managed embedding vector field.
+   */
+  managedEmbedding: true;
+  embedding: EmbeddingConfig;
+};
+
 export const Analyzer = {
   Standard: "standard",
   Korean: "korean",
@@ -75,6 +119,7 @@ export type IndexConfigsText = {
 export type IndexConfigsUnion =
   | IndexConfigsText
   | IndexConfigsVector
+  | IndexConfigsManagedEmbeddingVector
   | (IndexConfigs & { type: "keyword" })
   | (IndexConfigs & { type: "long" })
   | (IndexConfigs & { type: "double" })
@@ -181,12 +226,14 @@ export const IndexConfigsVector$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   type: z.literal("vector"),
+  managedEmbedding: nullToUndefined(z.literal(false).optional()),
   dimensions: z.number().int(),
-  similarity: Similarity$inboundSchema.default("cosine"),
+  similarity: nullToUndefined(Similarity$inboundSchema.default("cosine")),
 });
 /** @internal */
 export type IndexConfigsVector$Outbound = {
   type: "vector";
+  managedEmbedding?: false | undefined;
   dimensions: number;
   similarity: string;
 };
@@ -198,6 +245,7 @@ export const IndexConfigsVector$outboundSchema: z.ZodType<
   IndexConfigsVector
 > = z.object({
   type: z.literal("vector"),
+  managedEmbedding: z.literal(false).optional(),
   dimensions: z.number().int(),
   similarity: Similarity$outboundSchema.default("cosine"),
 });
@@ -219,6 +267,112 @@ export function indexConfigsVectorFromJSON(
   );
 }
 
+/** @internal */
+export const EmbeddingProvider$inboundSchema: z.ZodNativeEnum<
+  typeof EmbeddingProvider
+> = z.nativeEnum(EmbeddingProvider);
+/** @internal */
+export const EmbeddingProvider$outboundSchema: z.ZodNativeEnum<
+  typeof EmbeddingProvider
+> = EmbeddingProvider$inboundSchema;
+
+/** @internal */
+export const EmbeddingConfig$inboundSchema: z.ZodType<
+  EmbeddingConfig,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  provider: EmbeddingProvider$inboundSchema,
+  model: z.string(),
+  sourceField: z.string(),
+  dimensions: nullToUndefined(z.number().int().optional()),
+  similarity: nullToUndefined(Similarity$inboundSchema.default("cosine")),
+});
+/** @internal */
+export type EmbeddingConfig$Outbound = {
+  provider: string;
+  model: string;
+  sourceField: string;
+  dimensions?: number | undefined;
+  similarity?: string | undefined;
+};
+
+/** @internal */
+export const EmbeddingConfig$outboundSchema: z.ZodType<
+  EmbeddingConfig$Outbound,
+  z.ZodTypeDef,
+  EmbeddingConfig
+> = z.object({
+  provider: EmbeddingProvider$outboundSchema,
+  model: z.string(),
+  sourceField: z.string(),
+  dimensions: z.number().int().optional(),
+  similarity: Similarity$outboundSchema.optional(),
+});
+
+export function embeddingConfigToJSON(
+  embeddingConfig: EmbeddingConfig,
+): string {
+  return JSON.stringify(EmbeddingConfig$outboundSchema.parse(embeddingConfig));
+}
+export function embeddingConfigFromJSON(
+  jsonString: string,
+): SafeParseResult<EmbeddingConfig, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => EmbeddingConfig$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'EmbeddingConfig' from JSON`,
+  );
+}
+
+/** @internal */
+export const IndexConfigsManagedEmbeddingVector$inboundSchema: z.ZodType<
+  IndexConfigsManagedEmbeddingVector,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  type: z.literal("vector"),
+  managedEmbedding: z.literal(true),
+  embedding: z.lazy(() => EmbeddingConfig$inboundSchema),
+});
+/** @internal */
+export type IndexConfigsManagedEmbeddingVector$Outbound = {
+  type: "vector";
+  managedEmbedding: true;
+  embedding: EmbeddingConfig$Outbound;
+};
+
+/** @internal */
+export const IndexConfigsManagedEmbeddingVector$outboundSchema: z.ZodType<
+  IndexConfigsManagedEmbeddingVector$Outbound,
+  z.ZodTypeDef,
+  IndexConfigsManagedEmbeddingVector
+> = z.object({
+  type: z.literal("vector"),
+  managedEmbedding: z.literal(true),
+  embedding: z.lazy(() => EmbeddingConfig$outboundSchema),
+});
+
+export function indexConfigsManagedEmbeddingVectorToJSON(
+  indexConfigsManagedEmbeddingVector: IndexConfigsManagedEmbeddingVector,
+): string {
+  return JSON.stringify(
+    IndexConfigsManagedEmbeddingVector$outboundSchema.parse(
+      indexConfigsManagedEmbeddingVector,
+    ),
+  );
+}
+export function indexConfigsManagedEmbeddingVectorFromJSON(
+  jsonString: string,
+): SafeParseResult<IndexConfigsManagedEmbeddingVector, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) =>
+      IndexConfigsManagedEmbeddingVector$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'IndexConfigsManagedEmbeddingVector' from JSON`,
+  );
+}
+
 /** @internal */
 export const Analyzer$inboundSchema: z.ZodNativeEnum<typeof Analyzer> = z
   .nativeEnum(Analyzer);
@@ -233,7 +387,7 @@ export const IndexConfigsText$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   type: z.literal("text"),
-  analyzers: z.array(Analyzer$inboundSchema).optional(),
+  analyzers: nullToUndefined(z.array(Analyzer$inboundSchema).optional()),
 });
 /** @internal */
 export type IndexConfigsText$Outbound = {
@@ -276,6 +430,7 @@ export const IndexConfigsUnion$inboundSchema: z.ZodType<
 > = z.union([
   z.lazy(() => IndexConfigsText$inboundSchema),
   z.lazy(() => IndexConfigsVector$inboundSchema),
+  z.lazy(() => IndexConfigsManagedEmbeddingVector$inboundSchema),
   z.lazy(() => IndexConfigs$inboundSchema).and(
     z.object({ type: z.literal("keyword") }),
   ),
@@ -300,6 +455,7 @@ export const IndexConfigsUnion$inboundSchema: z.ZodType<
 export type IndexConfigsUnion$Outbound =
   | IndexConfigsText$Outbound
   | IndexConfigsVector$Outbound
+  | IndexConfigsManagedEmbeddingVector$Outbound
   | (IndexConfigs$Outbound & { type: "keyword" })
   | (IndexConfigs$Outbound & { type: "long" })
   | (IndexConfigs$Outbound & { type: "double" })
@@ -316,6 +472,7 @@ export const IndexConfigsUnion$outboundSchema: z.ZodType<
 > = z.union([
   z.lazy(() => IndexConfigsText$outboundSchema),
   z.lazy(() => IndexConfigsVector$outboundSchema),
+  z.lazy(() => IndexConfigsManagedEmbeddingVector$outboundSchema),
   z.lazy(() => IndexConfigs$outboundSchema).and(
     z.object({ type: z.literal("keyword") }),
   ),

package/src/models/operations/fetchdocs.ts

@@ -4,7 +4,7 @@
 
 import * as z from "zod/v3";
 import { remap as remap$ } from "../../lib/primitives.js";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, 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";
@@ -153,7 +153,7 @@ export const FetchDocsResponse$inboundSchema: z.ZodType<
   took: z.number().int(),
   docs: z.array(z.lazy(() => FetchDocsDoc$inboundSchema)),
   isDocsInline: z.boolean(),
-  docsUrl: z.string().optional(),
+  docsUrl: nullToUndefined(z.string().optional()),
 });
 
 export function fetchDocsResponseFromJSON(

package/src/models/operations/getbulkupsertdocs.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, 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";
@@ -101,10 +101,10 @@ export const GetBulkUpsertDocsResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   url: z.string(),
-  type: Type$inboundSchema.default("application/json"),
-  httpMethod: HttpMethod$inboundSchema.default("PUT"),
+  type: nullToUndefined(Type$inboundSchema.default("application/json")),
+  httpMethod: nullToUndefined(HttpMethod$inboundSchema.default("PUT")),
   objectKey: z.string(),
-  sizeLimitBytes: z.number().int().default(209715200),
+  sizeLimitBytes: nullToUndefined(z.number().int().default(209715200)),
 });
 
 export function getBulkUpsertDocsResponseFromJSON(

package/src/models/operations/listcollections.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, 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";
@@ -50,7 +50,7 @@ export const ListCollectionsResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   collections: z.array(models.CollectionResponse$inboundSchema),
-  nextPageToken: z.string().optional(),
+  nextPageToken: nullToUndefined(z.string().optional()),
 });
 
 export function listCollectionsResponseFromJSON(

package/src/models/operations/listdocs.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
@@ -89,9 +89,9 @@ export const ListDocsResponse$inboundSchema: z.ZodType<
 > = z.object({
   total: z.number().int(),
   docs: z.array(ListDocsDoc$inboundSchema),
-  nextPageToken: z.string().optional(),
+  nextPageToken: nullToUndefined(z.string().optional()),
   isDocsInline: z.boolean(),
-  docsUrl: z.string().optional(),
+  docsUrl: nullToUndefined(z.string().optional()),
 });
 
 export function listDocsResponseFromJSON(

package/src/models/operations/querycollection.ts

@@ -4,7 +4,7 @@
 
 import * as z from "zod/v3";
 import { remap as remap$ } from "../../lib/primitives.js";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, 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";
@@ -15,7 +15,7 @@ export type QueryCollectionRequestBody = {
    */
   size?: number | undefined;
   /**
-   * Query object.
+   * Query object. For managed embedding vector fields, use knn.queryText. For unmanaged vector fields, use knn.queryVector.
    */
   query: { [k: string]: any };
   /**
@@ -156,7 +156,7 @@ export const QueryCollectionDoc$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   collection: z.string(),
-  score: z.number().optional(),
+  score: nullToUndefined(z.number().optional()),
   doc: z.record(z.any()),
 });
 
@@ -177,11 +177,11 @@ export const QueryCollectionResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   took: z.number().int(),
-  maxScore: z.number().optional(),
+  maxScore: nullToUndefined(z.number().optional()),
   total: z.number().int(),
   docs: z.array(z.lazy(() => QueryCollectionDoc$inboundSchema)),
   isDocsInline: z.boolean(),
-  docsUrl: z.string().optional(),
+  docsUrl: nullToUndefined(z.string().optional()),
 });
 
 export function queryCollectionResponseFromJSON(

package/src/models/operations/updatedocs.ts

@@ -7,7 +7,7 @@ import { remap as remap$ } from "../../lib/primitives.js";
 
 export type UpdateDocsRequestBody = {
   /**
-   * A list of documents to update. Each document must contain 'id' field to be updated.
+   * 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 }>;
 };

package/src/models/operations/upsertdocs.ts

@@ -7,7 +7,7 @@ import { remap as remap$ } from "../../lib/primitives.js";
 
 export type UpsertDocsRequestBody = {
   /**
-   * A list of documents to upsert.
+   * 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 }>;
 };

package/src/models/partitionconfig.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../lib/schemas.js";
+import { nullToUndefined, 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";
@@ -47,9 +47,9 @@ export const PartitionConfig$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  fieldName: z.string().optional(),
-  dataType: DataType$inboundSchema.optional(),
-  numPartitions: z.number().int().optional(),
+  fieldName: nullToUndefined(z.string().optional()),
+  dataType: nullToUndefined(DataType$inboundSchema.optional()),
+  numPartitions: nullToUndefined(z.number().int().optional()),
 });
 /** @internal */
 export type PartitionConfig$Outbound = {

package/src/sdk/docs.ts

@@ -47,7 +47,7 @@ export class Docs extends ClientSDK {
   }
 
   /**
-   * Request required info to upload documents.
+   * Request required info to upload documents. Bulk upsert is not supported for collections with managed embedding vector fields.
    */
   async getBulkUpsert(
     request: operations.GetBulkUpsertDocsRequest,
@@ -61,7 +61,7 @@ export class Docs extends ClientSDK {
   }
 
   /**
-   * Bulk upsert documents into a collection. Note that the maximum supported object size is 200MB.
+   * Bulk upsert documents into a collection. Note that the maximum supported object size is 200MB. Bulk upsert is not supported for collections with managed embedding vector fields.
    */
   async bulkUpsert(
     request: operations.BulkUpsertDocsRequest,

package/src/types/errors.ts

@@ -94,4 +94,6 @@ export type FetchDocsError = UpdateCollectionError;
 export type BulkUpsertDocsError = UpdateCollectionError;
 
 /** Errors that can occur when getting bulk upsert docs info. */
-export type GetBulkUpsertDocsError = ListCollectionsError;
+export type GetBulkUpsertDocsError =
+  | errors.BadRequestError
+  | ListCollectionsError;

package/src/types/public.ts

@@ -48,6 +48,9 @@ export type { GetBulkUpsertDocsResponse } from "../models/operations/getbulkupse
 // ---- Models referenced by request/response bodies ----
 export type {
   IndexConfigsUnion,
+  IndexConfigsManagedEmbeddingVector,
+  EmbeddingConfig,
+  EmbeddingProvider,
   PartitionConfig,
   PartitionFilter,
   FieldsSelectorUnion,

package/test/null-response.test.mjs

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { LambdaDBClient } from "../dist/esm/index.js";
+import { HTTPClient } from "../dist/esm/lib/http.js";
+import { ResponseValidationError } from "../dist/esm/models/errors/responsevalidationerror.js";
+import { QueryCollectionResponse$inboundSchema } from "../dist/esm/models/operations/querycollection.js";
+
+function jsonResponse(body, init = {}) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+    ...init,
+  });
+}
+
+test("response schemas accept null for optional response fields", () => {
+  const parsed = QueryCollectionResponse$inboundSchema.parse({
+    took: 1,
+    maxScore: null,
+    total: 1,
+    docs: [{ collection: "items", score: null, doc: { id: "a" } }],
+    isDocsInline: false,
+    docsUrl: null,
+  });
+
+  assert.equal(parsed.maxScore, undefined);
+  assert.equal(parsed.docsUrl, undefined);
+  assert.equal(parsed.docs[0].score, undefined);
+});
+
+test("safe methods return ResponseValidationError for invalid JSON bodies", async () => {
+  const httpClient = new HTTPClient({
+    fetcher: async () =>
+      new Response("{", {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+  });
+  const client = new LambdaDBClient({ httpClient, projectApiKey: "test-key" });
+
+  const result = await client.listCollectionsSafe();
+
+  assert.equal(result.ok, false);
+  assert.ok(result.error instanceof ResponseValidationError);
+  assert.equal(result.error.rawValue, "{");
+});
+
+test("docsUrl fetches treat null document payloads as an empty docs array", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => jsonResponse(null);
+
+  try {
+    const httpClient = new HTTPClient({
+      fetcher: async () =>
+        jsonResponse({
+          total: 1,
+          docs: [],
+          isDocsInline: false,
+          docsUrl: "https://example.test/docs.json",
+        }),
+    });
+    const client = new LambdaDBClient({ httpClient, projectApiKey: "test-key" });
+
+    const result = await client.collection("items").docs.listSafe();
+
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.value.docs, []);
+    assert.equal(result.value.isDocsInline, true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});