@superblocksteam/sdk-api 0.0.4

package/src/integrations/cosmosdb/README.md

@@ -0,0 +1,217 @@
+# CosmosDB Client
+
+Interact with Azure CosmosDB with full type safety and runtime validation.
+
+## Methods
+
+| Method                                   | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any CosmosDB API request with schema validation |
+
+## Usage
+
+### Query Documents
+
+```typescript
+import { api, z, cosmosdb } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_COSMOSDB = "a1b2c3d4-5678-90ab-cdef-cosmosdb0001";
+
+const QueryResponseSchema = z.object({
+  Documents: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string(),
+    }),
+  ),
+  _count: z.number(),
+});
+
+export default api({
+  name: "CosmosDBExample",
+  integrations: {
+    cosmosdb: cosmosdb(PROD_COSMOSDB),
+  },
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        email: z.string(),
+      }),
+    ),
+  }),
+  async run(ctx, { status }) {
+    const result = await ctx.integrations.cosmosdb.apiRequest(
+      {
+        method: "POST",
+        path: "/dbs/mydb/colls/users/docs",
+        headers: {
+          "Content-Type": "application/query+json",
+        },
+        body: {
+          query: "SELECT * FROM c WHERE c.status = @status",
+          parameters: [{ name: "@status", value: status }],
+        },
+      },
+      { response: QueryResponseSchema },
+    );
+
+    return { users: result.Documents };
+  },
+});
+```
+
+### Get Document
+
+```typescript
+const GetDocumentResponseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+});
+
+const result = await ctx.integrations.cosmosdb.apiRequest(
+  {
+    method: "GET",
+    path: `/dbs/mydb/colls/users/docs/${documentId}`,
+    headers: {
+      "x-ms-documentdb-partitionkey": `["${partitionKey}"]`,
+    },
+  },
+  { response: GetDocumentResponseSchema },
+);
+```
+
+### Create Document
+
+```typescript
+const CreateResponseSchema = z.object({
+  id: z.string(),
+  _rid: z.string(),
+  _etag: z.string(),
+});
+
+const result = await ctx.integrations.cosmosdb.apiRequest(
+  {
+    method: "POST",
+    path: "/dbs/mydb/colls/users/docs",
+    headers: {
+      "x-ms-documentdb-partitionkey": `["${partitionKey}"]`,
+    },
+    body: {
+      id: "user-123",
+      name: "John Doe",
+      email: "john@example.com",
+      partitionKey: partitionKey,
+    },
+  },
+  { response: CreateResponseSchema },
+);
+```
+
+### Replace Document
+
+```typescript
+const ReplaceResponseSchema = z.object({
+  id: z.string(),
+  _etag: z.string(),
+});
+
+const result = await ctx.integrations.cosmosdb.apiRequest(
+  {
+    method: "PUT",
+    path: `/dbs/mydb/colls/users/docs/${documentId}`,
+    headers: {
+      "x-ms-documentdb-partitionkey": `["${partitionKey}"]`,
+    },
+    body: {
+      id: documentId,
+      name: "Jane Doe",
+      email: "jane@example.com",
+      partitionKey: partitionKey,
+    },
+  },
+  { response: ReplaceResponseSchema },
+);
+```
+
+### Delete Document
+
+```typescript
+const DeleteResponseSchema = z.object({}).passthrough();
+
+await ctx.integrations.cosmosdb.apiRequest(
+  {
+    method: "DELETE",
+    path: `/dbs/mydb/colls/users/docs/${documentId}`,
+    headers: {
+      "x-ms-documentdb-partitionkey": `["${partitionKey}"]`,
+    },
+  },
+  { response: DeleteResponseSchema },
+);
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Common Pitfalls
+
+### Partition Key Header
+
+Always include the partition key header:
+
+```typescript
+headers: {
+  "x-ms-documentdb-partitionkey": `["${partitionKey}"]`,
+}
+```
+
+### Query Content-Type
+
+For queries, use the special content type:
+
+```typescript
+headers: {
+  "Content-Type": "application/query+json",
+}
+```
+
+### Response Schema is Required
+
+```typescript
+// CORRECT - Response schema is required
+await ctx.integrations.cosmosdb.apiRequest(
+  { method: "POST", path: "/...", body: { ... } },
+  { response: ResponseSchema }
+);
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.cosmosdb.apiRequest(
+    { method: "POST", path: "/...", body: { ... } },
+    { response: ResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [CosmosDB REST API](https://docs.microsoft.com/en-us/rest/api/cosmos-db/)
+- [CosmosDB SQL Query](https://docs.microsoft.com/en-us/azure/cosmos-db/sql-query-getting-started)

package/src/integrations/cosmosdb/client.ts

@@ -0,0 +1,232 @@
+/**
+ * CosmosDB client implementation.
+ *
+ * Uses the native CosmosDB plugin type from @superblocksteam/types.
+ * Supports SQL queries and point operations (create, read, replace,
+ * upsert, delete) against CosmosDB containers.
+ */
+
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as CosmosDBPlugin } from "@superblocksteam/types/dist/src/plugins/cosmosdb/v1/plugin_pb";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import { RestApiValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import type { CosmosDBClient, CosmosDBQueryOptions } from "./types.js";
+
+/**
+ * CosmosDB request type derived from proto definition.
+ */
+type CosmosDBRequest = PartialMessage<CosmosDBPlugin>;
+
+/**
+ * Internal implementation of CosmosDBClient.
+ *
+ * Communicates with the orchestrator using the native CosmosDB plugin
+ * proto format, supporting SQL queries and point operations.
+ */
+export class CosmosDBClientImpl
+  implements CosmosDBClient, IntegrationClientImpl
+{
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  /**
+   * Execute a request and wrap errors.
+   */
+  private async exec(
+    request: CosmosDBRequest,
+    operation: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    try {
+      return await this.executeQuery(
+        request as Record<string, unknown>,
+        undefined,
+        metadata,
+      );
+    } catch (error) {
+      if (
+        error instanceof RestApiValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, operation, error);
+    }
+  }
+
+  /**
+   * Validate a result against a schema.
+   */
+  private validate<T>(result: unknown, schema: z.ZodSchema<T>): T {
+    const parseResult = schema.safeParse(result);
+
+    if (!parseResult.success) {
+      throw new RestApiValidationError(
+        `Result validation failed: ${parseResult.error.message}`,
+        {
+          zodError: parseResult.error,
+          data: result,
+        },
+      );
+    }
+
+    return parseResult.data;
+  }
+
+  async query<T>(
+    containerId: string,
+    sql: string,
+    schema: z.ZodSchema<T>,
+    options?: CosmosDBQueryOptions,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
+    // Proto JSON format for: oneof cosmosdb_action { Sql sql = 5; }
+    // Sql.oneof action { Singleton singleton = 1; }
+    const request = {
+      sql: {
+        singleton: {
+          containerId,
+          query: sql,
+          crossPartition: options?.crossPartition ?? false,
+          partitionKey: options?.partitionKey,
+        },
+      },
+    };
+
+    const result = await this.exec(
+      request as unknown as Record<string, unknown>,
+      "query",
+      metadata,
+    );
+    return this.validate(result, schema);
+  }
+
+  async read<T>(
+    containerId: string,
+    id: string,
+    schema: z.ZodSchema<T>,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
+    // Proto JSON format for: oneof cosmosdb_action { PointOperation point_operation = 6; }
+    const request = {
+      pointOperation: {
+        containerId,
+        read: { id, partitionKey },
+      },
+    };
+
+    const result = await this.exec(
+      request as unknown as Record<string, unknown>,
+      "read",
+      metadata,
+    );
+    return this.validate(result, schema);
+  }
+
+  async create(
+    containerId: string,
+    body: unknown,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = {
+      pointOperation: {
+        containerId,
+        create: {
+          body: typeof body === "string" ? body : JSON.stringify(body),
+          partitionKey,
+        },
+      },
+    };
+
+    return this.exec(
+      request as unknown as Record<string, unknown>,
+      "create",
+      metadata,
+    );
+  }
+
+  async replace(
+    containerId: string,
+    body: unknown,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = {
+      pointOperation: {
+        containerId,
+        replace: {
+          body: typeof body === "string" ? body : JSON.stringify(body),
+          partitionKey,
+        },
+      },
+    };
+
+    return this.exec(
+      request as unknown as Record<string, unknown>,
+      "replace",
+      metadata,
+    );
+  }
+
+  async upsert(
+    containerId: string,
+    body: unknown,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = {
+      pointOperation: {
+        containerId,
+        upsert: {
+          body: typeof body === "string" ? body : JSON.stringify(body),
+          partitionKey,
+        },
+      },
+    };
+
+    return this.exec(
+      request as unknown as Record<string, unknown>,
+      "upsert",
+      metadata,
+    );
+  }
+
+  async deleteItem(
+    containerId: string,
+    id: string,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = {
+      pointOperation: {
+        containerId,
+        delete: { id, partitionKey },
+      },
+    };
+
+    return this.exec(
+      request as unknown as Record<string, unknown>,
+      "delete",
+      metadata,
+    );
+  }
+}

package/src/integrations/cosmosdb/index.ts

@@ -0,0 +1,8 @@
+/**
+ * CosmosDB integration client.
+ *
+ * @module
+ */
+
+export type { CosmosDBClient, CosmosDBQueryOptions } from "./types.js";
+export { CosmosDBClientImpl } from "./client.js";

package/src/integrations/cosmosdb/types.ts

@@ -0,0 +1,152 @@
+/**
+ * CosmosDB client types.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * Options for CosmosDB SQL queries.
+ */
+export interface CosmosDBQueryOptions {
+  /** Enable cross-partition queries. Defaults to false. */
+  crossPartition?: boolean;
+  /** Partition key value to scope the query. */
+  partitionKey?: string;
+}
+
+/**
+ * CosmosDB client for SQL queries and point operations.
+ *
+ * Provides methods for querying containers with SQL and performing
+ * CRUD operations on individual documents.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { cosmos: cosmosdb(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.cosmos
+ *
+ * // SQL query
+ * const users = await cosmos.query(
+ *   'users',
+ *   'SELECT * FROM c WHERE c.status = "active"',
+ *   UserSchema,
+ * );
+ *
+ * // Read a document
+ * const user = await cosmos.read('users', 'user-123', UserSchema);
+ *
+ * // Create a document
+ * await cosmos.create('users', { id: 'user-456', name: 'Alice' });
+ *
+ * // Replace a document
+ * await cosmos.replace('users', { id: 'user-456', name: 'Bob' });
+ *
+ * // Upsert a document
+ * await cosmos.upsert('users', { id: 'user-789', name: 'Charlie' });
+ *
+ * // Delete a document
+ * await cosmos.deleteItem('users', 'user-456');
+ * ```
+ */
+export interface CosmosDBClient extends BaseIntegrationClient {
+  /**
+   * Execute a SQL query against a CosmosDB container.
+   *
+   * @param containerId - The container to query
+   * @param sql - The SQL query string
+   * @param schema - Zod schema for validating the result
+   * @param options - Optional query configuration (crossPartition, partitionKey)
+   * @returns The validated query result
+   */
+  query<T>(
+    containerId: string,
+    sql: string,
+    schema: z.ZodSchema<T>,
+    options?: CosmosDBQueryOptions,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+
+  /**
+   * Read a single document by ID.
+   *
+   * @param containerId - The container to read from
+   * @param id - The document ID
+   * @param schema - Zod schema for validating the result
+   * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The validated document
+   */
+  read<T>(
+    containerId: string,
+    id: string,
+    schema: z.ZodSchema<T>,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+
+  /**
+   * Create a new document in a container.
+   *
+   * @param containerId - The container to create in
+   * @param body - The document to create (will be JSON-serialized)
+   * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from CosmosDB
+   */
+  create(
+    containerId: string,
+    body: unknown,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Replace an existing document in a container.
+   *
+   * @param containerId - The container containing the document
+   * @param body - The replacement document (will be JSON-serialized)
+   * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from CosmosDB
+   */
+  replace(
+    containerId: string,
+    body: unknown,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Upsert (create or replace) a document in a container.
+   *
+   * @param containerId - The container to upsert into
+   * @param body - The document to upsert (will be JSON-serialized)
+   * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from CosmosDB
+   */
+  upsert(
+    containerId: string,
+    body: unknown,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Delete a document by ID from a container.
+   *
+   * @param containerId - The container containing the document
+   * @param id - The document ID to delete
+   * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from CosmosDB
+   */
+  deleteItem(
+    containerId: string,
+    id: string,
+    partitionKey?: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+}