@superblocksteam/sdk-api 0.0.4 → 0.0.5

package/dist/files.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Canonical file schemas and types for SDK API inputs.
+ *
+ * These helpers model the file objects that Superblocks injects for FilePicker
+ * inputs. Use the minimal file-ref contract when you want to pass files by
+ * reference to storage integrations, and the readable file contract when your
+ * API needs to call `readContentsAsync()` or `readContents()`.
+ */
+import { z } from "zod";
+/**
+ * Minimal file reference contract.
+ *
+ * Good for by-reference uploads where the storage plugin resolves the file
+ * bytes using `$superblocksId`, such as S3 or GCS `uploadMultipleObjects()`.
+ */
+export declare const fileRefSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    $superblocksId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    $superblocksId: string;
+    type?: string | undefined;
+}, {
+    name: string;
+    $superblocksId: string;
+    type?: string | undefined;
+}>;
+/**
+ * Runtime-readable file contract.
+ *
+ * Good for APIs that need to inspect file contents in code via
+ * `readContentsAsync()` or `readContents()`.
+ */
+export declare const readableFileSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    $superblocksId: z.ZodString;
+} & {
+    size: z.ZodOptional<z.ZodNumber>;
+    extension: z.ZodOptional<z.ZodString>;
+    previewUrl: z.ZodOptional<z.ZodString>;
+    readContentsAsync: z.ZodType<(mode?: string) => Promise<string | Buffer>, z.ZodTypeDef, (mode?: string) => Promise<string | Buffer>>;
+    readContents: z.ZodType<(mode?: string) => string | Buffer, z.ZodTypeDef, (mode?: string) => string | Buffer>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    $superblocksId: z.ZodString;
+} & {
+    size: z.ZodOptional<z.ZodNumber>;
+    extension: z.ZodOptional<z.ZodString>;
+    previewUrl: z.ZodOptional<z.ZodString>;
+    readContentsAsync: z.ZodType<(mode?: string) => Promise<string | Buffer>, z.ZodTypeDef, (mode?: string) => Promise<string | Buffer>>;
+    readContents: z.ZodType<(mode?: string) => string | Buffer, z.ZodTypeDef, (mode?: string) => string | Buffer>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    $superblocksId: z.ZodString;
+} & {
+    size: z.ZodOptional<z.ZodNumber>;
+    extension: z.ZodOptional<z.ZodString>;
+    previewUrl: z.ZodOptional<z.ZodString>;
+    readContentsAsync: z.ZodType<(mode?: string) => Promise<string | Buffer>, z.ZodTypeDef, (mode?: string) => Promise<string | Buffer>>;
+    readContents: z.ZodType<(mode?: string) => string | Buffer, z.ZodTypeDef, (mode?: string) => string | Buffer>;
+}, z.ZodTypeAny, "passthrough">>;
+export type FileRef = z.infer<typeof fileRefSchema>;
+export type ReadableFile = z.infer<typeof readableFileSchema>;
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;EAIxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;yCA9BrB,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,wBAAnC,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;oCAKK,MAAM,KAAK,MAAM,GAAG,MAAM,wBAA1B,MAAM,KAAK,MAAM,GAAG,MAAM;;;;;;;;;yCALlE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,wBAAnC,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;oCAKK,MAAM,KAAK,MAAM,GAAG,MAAM,wBAA1B,MAAM,KAAK,MAAM,GAAG,MAAM;;;;;;;;;yCALlE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,wBAAnC,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;oCAKK,MAAM,KAAK,MAAM,GAAG,MAAM,wBAA1B,MAAM,KAAK,MAAM,GAAG,MAAM;gCAiC5D,CAAC;AAEjB,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/files.js

@@ -0,0 +1,42 @@
+/**
+ * Canonical file schemas and types for SDK API inputs.
+ *
+ * These helpers model the file objects that Superblocks injects for FilePicker
+ * inputs. Use the minimal file-ref contract when you want to pass files by
+ * reference to storage integrations, and the readable file contract when your
+ * API needs to call `readContentsAsync()` or `readContents()`.
+ */
+import { z } from "zod";
+const readableAsyncMethodSchema = z.custom((value) => typeof value === "function", {
+    message: "Expected readContentsAsync to be a function",
+});
+const readableSyncMethodSchema = z.custom((value) => typeof value === "function", {
+    message: "Expected readContents to be a function",
+});
+/**
+ * Minimal file reference contract.
+ *
+ * Good for by-reference uploads where the storage plugin resolves the file
+ * bytes using `$superblocksId`, such as S3 or GCS `uploadMultipleObjects()`.
+ */
+export const fileRefSchema = z.object({
+    name: z.string(),
+    type: z.string().optional(),
+    $superblocksId: z.string(),
+});
+/**
+ * Runtime-readable file contract.
+ *
+ * Good for APIs that need to inspect file contents in code via
+ * `readContentsAsync()` or `readContents()`.
+ */
+export const readableFileSchema = fileRefSchema
+    .extend({
+    size: z.number().optional(),
+    extension: z.string().optional(),
+    previewUrl: z.string().optional(),
+    readContentsAsync: readableAsyncMethodSchema,
+    readContents: readableSyncMethodSchema,
+})
+    .passthrough();
+//# sourceMappingURL=files.js.map

package/dist/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAExC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,UAAU,EAAE;IACxC,OAAO,EAAE,6CAA6C;CACvD,CAAC,CAAC;AAEH,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CACvC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,UAAU,EACtC;IACE,OAAO,EAAE,wCAAwC;CAClD,CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;CAC3B,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa;KAC5C,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,iBAAiB,EAAE,yBAAyB;IAC5C,YAAY,EAAE,wBAAwB;CACvC,CAAC;KACD,WAAW,EAAE,CAAC"}

package/dist/index.d.ts

@@ -51,6 +51,8 @@
  * @packageDocumentation
  */
 export { z } from "zod";
+export { fileRefSchema, readableFileSchema } from "./files.js";
+export type { FileRef, ReadableFile } from "./files.js";
 export { api, __setEntryPoint, type CompiledApi, streamingApi, isStreamingApi, type StreamingApiConfig, type CompiledStreamingApi, } from "./api/index.js";
 export type { ExtractApiInput, ExtractApiOutput } from "./api/definition.js";
 export type { ApiConfig, ApiContext, ApiUser, Logger, BaseIntegrationClient, IntegrationRef, AnyIntegrationRef, IntegrationsMap, } from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -52,6 +52,8 @@
  */
 // Re-export Zod for convenience
 export { z } from "zod";
+// Canonical file contracts
+export { fileRefSchema, readableFileSchema } from "./files.js";
 // API definition and registry
 export { api, __setEntryPoint, 
 // Streaming API support

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,gCAAgC;AAChC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8BAA8B;AAC9B,OAAO,EACL,GAAG,EACH,eAAe;AAEf,wBAAwB;AACxB,YAAY,EACZ,cAAc,GAGf,MAAM,gBAAgB,CAAC;AAiBxB,oCAAoC;AACpC,OAAO,EACL,QAAQ,EACR,KAAK,EACL,MAAM,EACN,SAAS,EACT,MAAM,EACN,MAAM,EACN,MAAM,EACN,SAAS,EACT,eAAe,EACf,QAAQ,EACR,KAAK,EACL,SAAS,EACT,GAAG,EACH,QAAQ,EACR,MAAM,EACN,UAAU,EACV,OAAO,EACP,OAAO,EACP,aAAa,EACb,SAAS,EACT,KAAK,EACL,MAAM,EACN,eAAe,EACf,WAAW,EACX,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,YAAY,EACZ,OAAO,EACP,SAAS,EACT,UAAU,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EACX,MAAM,EACN,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,UAAU,EACV,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,EAAE,EACF,GAAG,EACH,YAAY,EACZ,KAAK,EACL,OAAO,EACP,UAAU,EACV,KAAK,EACL,cAAc,EACd,MAAM,EACN,kBAAkB,EAClB,0BAA0B,EAC1B,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,iBAAiB,EACjB,IAAI,GAsEL,MAAM,yBAAyB,CAAC;AAwEjC,iCAAiC;AACjC,OAAO;AACL,sEAAsE;AACtE,OAAO;AACP,4DAA4D;AAC5D,UAAU,EACV,mBAAmB,EACnB,2BAA2B;AAC3B,oBAAoB;AACpB,gBAAgB,EAChB,yBAAyB;AACzB,cAAc;AACd,QAAQ,EACR,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,SAAS,GACV,MAAM,oBAAoB,CAAC;AAqB5B,8CAA8C;AAC9C,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC;AAYjC,wBAAwB;AACxB,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,0BAA0B,EAC1B,WAAW,GACZ,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,gCAAgC;AAChC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,2BAA2B;AAC3B,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAG/D,8BAA8B;AAC9B,OAAO,EACL,GAAG,EACH,eAAe;AAEf,wBAAwB;AACxB,YAAY,EACZ,cAAc,GAGf,MAAM,gBAAgB,CAAC;AAiBxB,oCAAoC;AACpC,OAAO,EACL,QAAQ,EACR,KAAK,EACL,MAAM,EACN,SAAS,EACT,MAAM,EACN,MAAM,EACN,MAAM,EACN,SAAS,EACT,eAAe,EACf,QAAQ,EACR,KAAK,EACL,SAAS,EACT,GAAG,EACH,QAAQ,EACR,MAAM,EACN,UAAU,EACV,OAAO,EACP,OAAO,EACP,aAAa,EACb,SAAS,EACT,KAAK,EACL,MAAM,EACN,eAAe,EACf,WAAW,EACX,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,YAAY,EACZ,OAAO,EACP,SAAS,EACT,UAAU,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EACX,MAAM,EACN,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,UAAU,EACV,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,EAAE,EACF,GAAG,EACH,YAAY,EACZ,KAAK,EACL,OAAO,EACP,UAAU,EACV,KAAK,EACL,cAAc,EACd,MAAM,EACN,kBAAkB,EAClB,0BAA0B,EAC1B,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,iBAAiB,EACjB,IAAI,GAsEL,MAAM,yBAAyB,CAAC;AAwEjC,iCAAiC;AACjC,OAAO;AACL,sEAAsE;AACtE,OAAO;AACP,4DAA4D;AAC5D,UAAU,EACV,mBAAmB,EACnB,2BAA2B;AAC3B,oBAAoB;AACpB,gBAAgB,EAChB,yBAAyB;AACzB,cAAc;AACd,QAAQ,EACR,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,SAAS,GACV,MAAM,oBAAoB,CAAC;AAqB5B,8CAA8C;AAC9C,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC;AAYjC,wBAAwB;AACxB,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,0BAA0B,EAC1B,WAAW,GACZ,MAAM,aAAa,CAAC"}

package/dist/integrations/cosmosdb/client.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unit tests for CosmosDB client.
+ *
+ * Validates the exact proto JSON structure passed to executeQuery for each
+ * CosmosDB operation: query, read, create, replace, upsert, deleteItem.
+ */
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/integrations/cosmosdb/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../../src/integrations/cosmosdb/client.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/integrations/cosmosdb/client.test.js

@@ -0,0 +1,141 @@
+/**
+ * Unit tests for CosmosDB client.
+ *
+ * Validates the exact proto JSON structure passed to executeQuery for each
+ * CosmosDB operation: query, read, create, replace, upsert, deleteItem.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import { CosmosDBClientImpl } from "./client.js";
+/** Minimal integration config for testing. */
+const TEST_CONFIG = {
+    id: "cosmosdb-test-id",
+    name: "Test CosmosDB",
+    pluginId: "cosmosdb",
+    configuration: {},
+};
+function createClient(mockResult = []) {
+    const executeQuery = vi.fn().mockResolvedValue(mockResult);
+    const client = new CosmosDBClientImpl(TEST_CONFIG, executeQuery);
+    return { client, executeQuery };
+}
+describe("CosmosDBClientImpl", () => {
+    describe("query", () => {
+        it("passes the correct proto JSON structure to executeQuery", async () => {
+            const { client, executeQuery } = createClient([{ id: "doc-1" }]);
+            await client.query("my-container", "SELECT * FROM c", z.array(z.object({ id: z.string() }).passthrough()), { crossPartition: true, partitionKey: "pk-1" });
+            expect(executeQuery).toHaveBeenCalledOnce();
+            expect(executeQuery).toHaveBeenCalledWith({
+                sql: {
+                    singleton: {
+                        containerId: "my-container",
+                        query: "SELECT * FROM c",
+                        crossPartition: true,
+                        partitionKey: "pk-1",
+                    },
+                },
+            }, undefined, undefined);
+        });
+        it("defaults crossPartition to false when not specified", async () => {
+            const { client, executeQuery } = createClient([]);
+            await client.query("container-1", "SELECT TOP 1 * FROM c", z.array(z.unknown()));
+            const request = executeQuery.mock.calls[0][0];
+            expect(request.sql.singleton.crossPartition).toBe(false);
+            expect(request.sql.singleton.partitionKey).toBeUndefined();
+        });
+    });
+    describe("read", () => {
+        it("passes the correct proto JSON structure to executeQuery", async () => {
+            const { client, executeQuery } = createClient({
+                id: "doc-1",
+                name: "test",
+            });
+            await client.read("my-container", "doc-1", z.object({ id: z.string(), name: z.string() }), "pk-value");
+            expect(executeQuery).toHaveBeenCalledOnce();
+            expect(executeQuery).toHaveBeenCalledWith({
+                pointOperation: {
+                    containerId: "my-container",
+                    read: { id: "doc-1", partitionKey: "pk-value" },
+                },
+            }, undefined, undefined);
+        });
+    });
+    describe("create", () => {
+        it("passes the correct proto JSON structure with object body", async () => {
+            const body = { id: "new-doc", value: 42 };
+            const { client, executeQuery } = createClient(body);
+            await client.create("my-container", body, "pk-value");
+            expect(executeQuery).toHaveBeenCalledOnce();
+            expect(executeQuery).toHaveBeenCalledWith({
+                pointOperation: {
+                    containerId: "my-container",
+                    create: {
+                        body: JSON.stringify(body),
+                        partitionKey: "pk-value",
+                    },
+                },
+            }, undefined, undefined);
+        });
+        it("passes string body as-is", async () => {
+            const bodyStr = '{"id":"doc-str"}';
+            const { client, executeQuery } = createClient({});
+            await client.create("my-container", bodyStr);
+            const request = executeQuery.mock.calls[0][0];
+            expect(request.pointOperation.create.body).toBe(bodyStr);
+        });
+    });
+    describe("replace", () => {
+        it("passes the correct proto JSON structure to executeQuery", async () => {
+            const body = { id: "doc-1", value: "updated" };
+            const { client, executeQuery } = createClient(body);
+            await client.replace("my-container", body, "pk-value");
+            expect(executeQuery).toHaveBeenCalledOnce();
+            expect(executeQuery).toHaveBeenCalledWith({
+                pointOperation: {
+                    containerId: "my-container",
+                    replace: {
+                        body: JSON.stringify(body),
+                        partitionKey: "pk-value",
+                    },
+                },
+            }, undefined, undefined);
+        });
+    });
+    describe("upsert", () => {
+        it("passes the correct proto JSON structure to executeQuery", async () => {
+            const body = { id: "doc-1", value: "upserted" };
+            const { client, executeQuery } = createClient(body);
+            await client.upsert("my-container", body, "pk-value");
+            expect(executeQuery).toHaveBeenCalledOnce();
+            expect(executeQuery).toHaveBeenCalledWith({
+                pointOperation: {
+                    containerId: "my-container",
+                    upsert: {
+                        body: JSON.stringify(body),
+                        partitionKey: "pk-value",
+                    },
+                },
+            }, undefined, undefined);
+        });
+    });
+    describe("deleteItem", () => {
+        it("passes the correct proto JSON structure to executeQuery", async () => {
+            const { client, executeQuery } = createClient({});
+            await client.deleteItem("my-container", "doc-to-delete", "pk-value");
+            expect(executeQuery).toHaveBeenCalledOnce();
+            expect(executeQuery).toHaveBeenCalledWith({
+                pointOperation: {
+                    containerId: "my-container",
+                    delete: { id: "doc-to-delete", partitionKey: "pk-value" },
+                },
+            }, undefined, undefined);
+        });
+        it("passes undefined partitionKey when not specified", async () => {
+            const { client, executeQuery } = createClient({});
+            await client.deleteItem("my-container", "doc-1");
+            const request = executeQuery.mock.calls[0][0];
+            expect(request.pointOperation.delete.partitionKey).toBeUndefined();
+        });
+    });
+});
+//# sourceMappingURL=client.test.js.map

package/dist/integrations/cosmosdb/client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../../../src/integrations/cosmosdb/client.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk-api",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Superblocks SDK for TypeScript-based API definitions",
   "license": "Superblocks Community Software License",
   "files": [

package/src/files.ts

@@ -0,0 +1,54 @@
+/**
+ * Canonical file schemas and types for SDK API inputs.
+ *
+ * These helpers model the file objects that Superblocks injects for FilePicker
+ * inputs. Use the minimal file-ref contract when you want to pass files by
+ * reference to storage integrations, and the readable file contract when your
+ * API needs to call `readContentsAsync()` or `readContents()`.
+ */
+
+import { z } from "zod";
+
+const readableAsyncMethodSchema = z.custom<
+  (mode?: string) => Promise<string | Buffer>
+>((value) => typeof value === "function", {
+  message: "Expected readContentsAsync to be a function",
+});
+
+const readableSyncMethodSchema = z.custom<(mode?: string) => string | Buffer>(
+  (value) => typeof value === "function",
+  {
+    message: "Expected readContents to be a function",
+  },
+);
+
+/**
+ * Minimal file reference contract.
+ *
+ * Good for by-reference uploads where the storage plugin resolves the file
+ * bytes using `$superblocksId`, such as S3 or GCS `uploadMultipleObjects()`.
+ */
+export const fileRefSchema = z.object({
+  name: z.string(),
+  type: z.string().optional(),
+  $superblocksId: z.string(),
+});
+
+/**
+ * Runtime-readable file contract.
+ *
+ * Good for APIs that need to inspect file contents in code via
+ * `readContentsAsync()` or `readContents()`.
+ */
+export const readableFileSchema = fileRefSchema
+  .extend({
+    size: z.number().optional(),
+    extension: z.string().optional(),
+    previewUrl: z.string().optional(),
+    readContentsAsync: readableAsyncMethodSchema,
+    readContents: readableSyncMethodSchema,
+  })
+  .passthrough();
+
+export type FileRef = z.infer<typeof fileRefSchema>;
+export type ReadableFile = z.infer<typeof readableFileSchema>;

package/src/index.ts

@@ -54,6 +54,10 @@
 // Re-export Zod for convenience
 export { z } from "zod";
 
+// Canonical file contracts
+export { fileRefSchema, readableFileSchema } from "./files.js";
+export type { FileRef, ReadableFile } from "./files.js";
+
 // API definition and registry
 export {
   api,

package/src/integrations/cosmosdb/client.test.ts

@@ -0,0 +1,209 @@
+/**
+ * Unit tests for CosmosDB client.
+ *
+ * Validates the exact proto JSON structure passed to executeQuery for each
+ * CosmosDB operation: query, read, create, replace, upsert, deleteItem.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import { CosmosDBClientImpl } from "./client.js";
+import type { IntegrationConfig } from "../types.js";
+
+/** Minimal integration config for testing. */
+const TEST_CONFIG: IntegrationConfig = {
+  id: "cosmosdb-test-id",
+  name: "Test CosmosDB",
+  pluginId: "cosmosdb",
+  configuration: {},
+};
+
+function createClient(mockResult: unknown = []) {
+  const executeQuery = vi.fn().mockResolvedValue(mockResult);
+  const client = new CosmosDBClientImpl(TEST_CONFIG, executeQuery);
+  return { client, executeQuery };
+}
+
+describe("CosmosDBClientImpl", () => {
+  describe("query", () => {
+    it("passes the correct proto JSON structure to executeQuery", async () => {
+      const { client, executeQuery } = createClient([{ id: "doc-1" }]);
+
+      await client.query(
+        "my-container",
+        "SELECT * FROM c",
+        z.array(z.object({ id: z.string() }).passthrough()),
+        { crossPartition: true, partitionKey: "pk-1" },
+      );
+
+      expect(executeQuery).toHaveBeenCalledOnce();
+      expect(executeQuery).toHaveBeenCalledWith(
+        {
+          sql: {
+            singleton: {
+              containerId: "my-container",
+              query: "SELECT * FROM c",
+              crossPartition: true,
+              partitionKey: "pk-1",
+            },
+          },
+        },
+        undefined,
+        undefined,
+      );
+    });
+
+    it("defaults crossPartition to false when not specified", async () => {
+      const { client, executeQuery } = createClient([]);
+
+      await client.query(
+        "container-1",
+        "SELECT TOP 1 * FROM c",
+        z.array(z.unknown()),
+      );
+
+      const request = executeQuery.mock.calls[0][0];
+      expect(request.sql.singleton.crossPartition).toBe(false);
+      expect(request.sql.singleton.partitionKey).toBeUndefined();
+    });
+  });
+
+  describe("read", () => {
+    it("passes the correct proto JSON structure to executeQuery", async () => {
+      const { client, executeQuery } = createClient({
+        id: "doc-1",
+        name: "test",
+      });
+
+      await client.read(
+        "my-container",
+        "doc-1",
+        z.object({ id: z.string(), name: z.string() }),
+        "pk-value",
+      );
+
+      expect(executeQuery).toHaveBeenCalledOnce();
+      expect(executeQuery).toHaveBeenCalledWith(
+        {
+          pointOperation: {
+            containerId: "my-container",
+            read: { id: "doc-1", partitionKey: "pk-value" },
+          },
+        },
+        undefined,
+        undefined,
+      );
+    });
+  });
+
+  describe("create", () => {
+    it("passes the correct proto JSON structure with object body", async () => {
+      const body = { id: "new-doc", value: 42 };
+      const { client, executeQuery } = createClient(body);
+
+      await client.create("my-container", body, "pk-value");
+
+      expect(executeQuery).toHaveBeenCalledOnce();
+      expect(executeQuery).toHaveBeenCalledWith(
+        {
+          pointOperation: {
+            containerId: "my-container",
+            create: {
+              body: JSON.stringify(body),
+              partitionKey: "pk-value",
+            },
+          },
+        },
+        undefined,
+        undefined,
+      );
+    });
+
+    it("passes string body as-is", async () => {
+      const bodyStr = '{"id":"doc-str"}';
+      const { client, executeQuery } = createClient({});
+
+      await client.create("my-container", bodyStr);
+
+      const request = executeQuery.mock.calls[0][0];
+      expect(request.pointOperation.create.body).toBe(bodyStr);
+    });
+  });
+
+  describe("replace", () => {
+    it("passes the correct proto JSON structure to executeQuery", async () => {
+      const body = { id: "doc-1", value: "updated" };
+      const { client, executeQuery } = createClient(body);
+
+      await client.replace("my-container", body, "pk-value");
+
+      expect(executeQuery).toHaveBeenCalledOnce();
+      expect(executeQuery).toHaveBeenCalledWith(
+        {
+          pointOperation: {
+            containerId: "my-container",
+            replace: {
+              body: JSON.stringify(body),
+              partitionKey: "pk-value",
+            },
+          },
+        },
+        undefined,
+        undefined,
+      );
+    });
+  });
+
+  describe("upsert", () => {
+    it("passes the correct proto JSON structure to executeQuery", async () => {
+      const body = { id: "doc-1", value: "upserted" };
+      const { client, executeQuery } = createClient(body);
+
+      await client.upsert("my-container", body, "pk-value");
+
+      expect(executeQuery).toHaveBeenCalledOnce();
+      expect(executeQuery).toHaveBeenCalledWith(
+        {
+          pointOperation: {
+            containerId: "my-container",
+            upsert: {
+              body: JSON.stringify(body),
+              partitionKey: "pk-value",
+            },
+          },
+        },
+        undefined,
+        undefined,
+      );
+    });
+  });
+
+  describe("deleteItem", () => {
+    it("passes the correct proto JSON structure to executeQuery", async () => {
+      const { client, executeQuery } = createClient({});
+
+      await client.deleteItem("my-container", "doc-to-delete", "pk-value");
+
+      expect(executeQuery).toHaveBeenCalledOnce();
+      expect(executeQuery).toHaveBeenCalledWith(
+        {
+          pointOperation: {
+            containerId: "my-container",
+            delete: { id: "doc-to-delete", partitionKey: "pk-value" },
+          },
+        },
+        undefined,
+        undefined,
+      );
+    });
+
+    it("passes undefined partitionKey when not specified", async () => {
+      const { client, executeQuery } = createClient({});
+
+      await client.deleteItem("my-container", "doc-1");
+
+      const request = executeQuery.mock.calls[0][0];
+      expect(request.pointOperation.delete.partitionKey).toBeUndefined();
+    });
+  });
+});