@superblocksteam/sdk-api 0.0.5 → 0.0.7

package/src/integrations/snowflakecortex/types.ts

@@ -3,22 +3,14 @@
  */
 
 import type { BaseIntegrationClient } from "../../types.js";
-import type {
-  SupportsApiRequest,
-  SupportsStreamingApiRequest,
-} from "../base/index.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * Snowflake Cortex client for inference interactions.
  *
- * Provides the generic apiRequest() method for any Snowflake Cortex API endpoint,
- * and streamApiRequest() for streaming responses.
+ * Provides the generic apiRequest() method for any Snowflake Cortex API endpoint.
  */
 export interface SnowflakeCortexClient
-  extends
-    BaseIntegrationClient,
-    SupportsApiRequest,
-    SupportsStreamingApiRequest {
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
-  // streamApiRequest() method inherited from SupportsStreamingApiRequest
 }

package/src/integrations/snowflakepostgres/README.md

@@ -0,0 +1,233 @@
+# Snowflake Postgres Client
+
+Execute SQL queries and statements against Snowflake databases using the PostgreSQL wire protocol, with full type safety and runtime validation.
+
+Snowflake Postgres uses the same API contract as the PostgreSQL integration. If you are familiar with the Postgres client, this works identically.
+
+## Methods
+
+| Method                                      | Description                                                                |
+| ------------------------------------------- | -------------------------------------------------------------------------- |
+| `query<T>(sql, schema, params?, metadata?)` | Execute a SELECT query and return validated, typed results                 |
+| `execute(sql, params?, metadata?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+
+## Usage
+
+### Basic Query with Schema Validation
+
+```typescript
+import { api, z, snowflakePostgres } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const SNOWFLAKE_PG = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const SalesSchema = z.object({
+  region: z.string(),
+  total_revenue: z.string(), // NUMERIC returned as string
+  order_count: z.coerce.number(),
+});
+
+export default api({
+  name: "GetSalesByRegion",
+  integrations: {
+    db: snowflakePostgres(SNOWFLAKE_PG),
+  },
+  input: z.object({
+    region: z.string(),
+  }),
+  output: z.object({
+    sales: z.array(SalesSchema),
+  }),
+  async run(ctx, { region }) {
+    const sales = await ctx.integrations.db.query(
+      "SELECT region, total_revenue, order_count FROM sales_summary WHERE region = $1",
+      SalesSchema,
+      [region],
+    );
+
+    return { sales };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+import { api, z, snowflakePostgres } from "@superblocksteam/sdk-api";
+
+const SNOWFLAKE_PG = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+export default api({
+  name: "ManageRecords",
+  integrations: {
+    db: snowflakePostgres(SNOWFLAKE_PG),
+  },
+  input: z.object({
+    name: z.string(),
+    email: z.string(),
+  }),
+  output: z.object({ success: z.boolean() }),
+
+  async run(ctx, { name, email }) {
+    // INSERT
+    await ctx.integrations.db.execute(
+      "INSERT INTO users (name, email) VALUES ($1, $2)",
+      [name, email],
+    );
+
+    // UPDATE
+    const updateResult = await ctx.integrations.db.execute(
+      "UPDATE users SET last_login = CURRENT_TIMESTAMP() WHERE email = $1",
+      [email],
+    );
+    console.log(`Updated ${updateResult.rowCount} rows`);
+
+    return { success: true };
+  },
+});
+```
+
+### Query with JOIN
+
+```typescript
+const OrderSchema = z.object({
+  order_id: z.string(),
+  customer_name: z.string(),
+  total: z.string(), // NUMERIC as string
+});
+
+const orders = await ctx.integrations.db.query(
+  `SELECT o.id as order_id, c.name as customer_name, o.total
+   FROM orders o
+   JOIN customers c ON o.customer_id = c.id
+   WHERE o.status = $1`,
+  OrderSchema,
+  ["pending"],
+);
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling:
+
+```typescript
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE status = $1",
+  UserSchema,
+  ["active"],
+  { label: "Fetch active users" },
+);
+
+await ctx.integrations.db.execute(
+  "DELETE FROM sessions WHERE expires_at < CURRENT_TIMESTAMP()",
+  undefined, // no params
+  { label: "Clean expired sessions" },
+);
+```
+
+When `includeDiagnostics` is enabled, `label` and `description` appear in the trace view. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Common Pitfalls
+
+### Schema Parameter is Required
+
+The `query()` method requires a Zod schema for runtime validation:
+
+```typescript
+// WRONG - Missing schema parameter
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users",
+  [
+    /* params */
+  ], // This is wrong - params are 3rd argument
+);
+
+// CORRECT - Schema is the second parameter
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE id = $1",
+  UserSchema, // Schema is required
+  [userId], // Params are optional, third argument
+);
+```
+
+### Use Parameterized Queries to Prevent SQL Injection
+
+Always use `$1, $2, ...` placeholders instead of string interpolation:
+
+```typescript
+// WRONG - SQL injection vulnerability
+const users = await ctx.integrations.db.query(
+  `SELECT * FROM users WHERE name = '${userName}'`, // DANGEROUS!
+  UserSchema,
+);
+
+// CORRECT - Use parameterized queries
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE name = $1",
+  UserSchema,
+  [userName], // Safe - value is escaped
+);
+```
+
+### NUMERIC/DECIMAL Values Returned as Strings
+
+Large `NUMERIC` and `DECIMAL` columns are returned as strings to preserve precision:
+
+```typescript
+// WRONG - May lose precision
+const schema = z.object({ price: z.number() });
+
+// CORRECT - Keep as string or transform
+const schema = z.object({
+  price: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Aggregate Functions (COUNT, SUM) Return Strings
+
+Use `z.coerce.number()` to convert:
+
+```typescript
+const StatsSchema = z.object({
+  total_orders: z.coerce.number(),
+  total_revenue: z.coerce.number(),
+});
+```
+
+### Handling NULL Values
+
+```typescript
+// WRONG - Will fail if column contains NULL
+const schema = z.object({ bio: z.string() });
+
+// CORRECT - Mark nullable columns
+const schema = z.object({ bio: z.string().nullable() });
+```
+
+## Error Handling
+
+### QueryValidationError
+
+Thrown when query results fail schema validation:
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const users = await ctx.integrations.db.query(
+    "SELECT * FROM users",
+    UserSchema,
+  );
+} catch (error) {
+  if (error instanceof QueryValidationError) {
+    console.error("Row index:", error.details.rowIndex);
+    console.error("Validation errors:", error.details.errors);
+    console.error("Actual row data:", error.details.row);
+  }
+}
+```
+
+## API Reference
+
+- [Snowflake SQL Reference](https://docs.snowflake.com/en/sql-reference)
+- [Snowflake Data Types](https://docs.snowflake.com/en/sql-reference/data-types)

package/src/integrations/snowflakepostgres/client.ts

@@ -6,8 +6,8 @@
  * implementation.
  */
 
-import type { SnowflakePostgresClient } from "./types.js";
 import { PostgresClientImpl } from "../postgres/client.js";
+import type { SnowflakePostgresClient } from "./types.js";
 
 export class SnowflakePostgresClientImpl
   extends PostgresClientImpl

package/src/integrations/snowflakepostgres/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "snowflakepostgres",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/snowflakepostgres/types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/stabilityai/README.md

@@ -13,7 +13,7 @@ Generate, edit, and upscale images using Stability AI's image generation models.
 ### Generate an Image (Text-to-Image)
 
 ```typescript
-import { api, z, stabilityai } from "@superblocksteam/sdk-api";
+import { api, z, stabilityAI } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_STABILITY = "a1b2c3d4-5678-90ab-cdef-stabilit0001";
@@ -30,7 +30,7 @@ const GenerationResponseSchema = z.object({
 
 export default api({
   integrations: {
-    stability: stabilityai(PROD_STABILITY),
+    stability: stabilityAI(PROD_STABILITY),
   },
   name: "StabilityAIExample",
   input: z.object({

package/src/integrations/stabilityai/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "stabilityai",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/stripe/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "stripe",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/superblocks-ocr/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "superblocks-ocr",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/twilio/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "twilio",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/zendesk/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "zendesk",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/zoom/README.md

@@ -50,7 +50,7 @@ export default api({
     const result = await ctx.integrations.zoom.apiRequest(
       {
         method: "POST",
-        path: "/v2/users/me/meetings",
+        path: "/users/me/meetings",
         body: {
           topic: topic,
           type: 2, // Scheduled meeting
@@ -99,7 +99,7 @@ const ListMeetingsResponseSchema = z.object({
 const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "GET",
-    path: "/v2/users/me/meetings",
+    path: "/users/me/meetings",
     params: {
       type: "scheduled", // upcoming, live, scheduled
       page_size: 30,
@@ -137,7 +137,7 @@ const MeetingDetailSchema = z.object({
 const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "GET",
-    path: `/v2/meetings/${meetingId}`,
+    path: `/meetings/${meetingId}`,
   },
   { response: MeetingDetailSchema },
 );
@@ -149,7 +149,7 @@ const result = await ctx.integrations.zoom.apiRequest(
 await ctx.integrations.zoom.apiRequest(
   {
     method: "PATCH",
-    path: `/v2/meetings/${meetingId}`,
+    path: `/meetings/${meetingId}`,
     body: {
       topic: "Updated Meeting Topic",
       duration: 60,
@@ -168,7 +168,7 @@ await ctx.integrations.zoom.apiRequest(
 await ctx.integrations.zoom.apiRequest(
   {
     method: "DELETE",
-    path: `/v2/meetings/${meetingId}`,
+    path: `/meetings/${meetingId}`,
     params: {
       schedule_for_reminder: true,
     },
@@ -196,7 +196,7 @@ const WebinarSchema = z.object({
 const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "POST",
-    path: "/v2/users/me/webinars",
+    path: "/users/me/webinars",
     body: {
       topic: "Product Launch Webinar",
       type: 5, // Scheduled webinar
@@ -234,7 +234,7 @@ const UserSchema = z.object({
 const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "GET",
-    path: "/v2/users/me",
+    path: "/users/me",
   },
   { response: UserSchema },
 );
@@ -265,7 +265,7 @@ const ListUsersResponseSchema = z.object({
 const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "GET",
-    path: "/v2/users",
+    path: "/users",
     params: {
       status: "active",
       page_size: 30,
@@ -289,7 +289,7 @@ const RegistrantSchema = z.object({
 const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "POST",
-    path: `/v2/meetings/${meetingId}/registrants`,
+    path: `/meetings/${meetingId}/registrants`,
     body: {
       email: "attendee@example.com",
       first_name: "John",
@@ -316,7 +316,7 @@ await zoom.listMeetings();
 
 // CORRECT - Use apiRequest
 await ctx.integrations.zoom.apiRequest(
-  { method: "POST", path: "/v2/users/me/meetings", body: { ... } },
+  { method: "POST", path: "/users/me/meetings", body: { ... } },
   { response: MeetingSchema }
 );
 ```
@@ -346,10 +346,10 @@ Use "me" for the authenticated user:
 
 ```typescript
 // Current user's meetings
-const path = "/v2/users/me/meetings";
+const path = "/users/me/meetings";
 
 // Specific user's meetings (requires admin scope)
-const path = `/v2/users/${userId}/meetings`;
+const path = `/users/${userId}/meetings`;
 ```
 
 ### Date/Time Format
@@ -372,7 +372,7 @@ Many operations return empty responses:
 ```typescript
 // PATCH and DELETE often return 204 No Content
 await ctx.integrations.zoom.apiRequest(
-  { method: "PATCH", path: `/v2/meetings/${id}`, body: { ... } },
+  { method: "PATCH", path: `/meetings/${id}`, body: { ... } },
   { response: z.object({}).optional() }  // Handle empty response
 );
 ```
@@ -415,7 +415,7 @@ async function getAllMeetings(zoom: ZoomClient) {
     const result = await ctx.integrations.zoom.apiRequest(
       {
         method: "GET",
-        path: "/v2/users/me/meetings",
+        path: "/users/me/meetings",
         params: {
           page_size: 300,
           page_number: pageNumber,
@@ -441,7 +441,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.zoom.apiRequest(
-    { method: "POST", path: "/v2/users/me/meetings", body: { ... } },
+    { method: "POST", path: "/users/me/meetings", body: { ... } },
     { response: MeetingSchema }
   );
 } catch (error) {

package/src/integrations/zoom/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "zoom",
+  "base": "README.md",
+  "overlays": []
+}

package/src/runtime/context.ts

@@ -5,22 +5,22 @@
  * providing access to integrations, logging, and environment.
  */
 
-import type {
-  ApiContext,
-  ApiUser,
-  Logger,
-  AnyIntegrationRef,
-} from "../types.js";
-import type {
-  IntegrationConfig,
-  IntegrationClientImpl,
-} from "../integrations/types.js";
 import type { IntegrationDeclaration } from "../integrations/declarations.js";
 import {
   createClient,
   type QueryExecutor,
   type TraceMetadata,
 } from "../integrations/registry.js";
+import type {
+  IntegrationConfig,
+  IntegrationClientImpl,
+} from "../integrations/types.js";
+import type {
+  ApiContext,
+  ApiUser,
+  Logger,
+  AnyIntegrationRef,
+} from "../types.js";
 import { createDefaultLogger } from "./logger.js";
 
 /**
@@ -41,7 +41,7 @@ export interface CreateContextOptions {
   /**
    * Function to execute integration operations.
    *
-   * For language plugins (Python, JavaScript), pass the bindings parameter
+   * For language plugins (JavaScript), pass the bindings parameter
    * to the API execution request as `input` field for binding resolution.
    */
   executeQuery: (

package/src/runtime/executor.ts

@@ -46,13 +46,13 @@ export interface ExecuteApiRequest {
    * The request object should match the protobuf Plugin schema for the
    * specific integration type (e.g., postgresql.v1.Plugin for Postgres).
    *
-   * For language plugins (Python, JavaScript), the bindings parameter should be
+   * For language plugins (JavaScript), the bindings parameter should be
    * passed to the API execution request as `input` or `inputs` field for
    * binding resolution.
    *
    * @param integrationId - The integration ID
    * @param request - Plugin-specific request object matching the proto schema
-   * @param bindings - Optional bindings data for binding resolution (e.g., Python/JavaScript bindings)
+   * @param bindings - Optional bindings data for binding resolution (e.g., JavaScript bindings)
    * @returns Promise resolving to the operation result
    */
   executeQuery: (

package/src/runtime/index.ts

@@ -5,15 +5,7 @@
  * including context creation, validation, and error handling.
  */
 
-// Unified executor (recommended)
-export {
-  execute,
-  isStreamingApi,
-  type UnifiedExecuteApiRequest,
-  type AnyCompiledApi,
-} from "./execute.js";
-
-// Main executor (for non-streaming APIs)
+// Main executor
 export {
   executeApi,
   type ExecuteApiRequest,
@@ -22,22 +14,8 @@ export {
   type ExecuteApiErrorResponse,
 } from "./executor.js";
 
-// Streaming executor (for streaming APIs)
-export {
-  executeStreamingApi,
-  createStreamingApiGenerator,
-  type ExecuteStreamingApiRequest,
-  type StreamingApiCallbacks,
-  type StreamingApiError,
-  type ExecuteStreamingApiResult,
-} from "./streaming-executor.js";
-
 // Context factories
 export { createApiContext, type CreateContextOptions } from "./context.js";
-export {
-  createStreamingApiContext,
-  type CreateStreamingContextOptions,
-} from "./streaming-context.js";
 
 // Error types
 export {

package/src/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type {
   IntegrationRef,
   AnyIntegrationRef,
@@ -43,10 +44,13 @@ import type {
  *     if (users.length === 0) {
  *       throw new Error('User not found');
  *     }
- *     await ctx.integrations.notifier.postMessage({
- *       channel: '#alerts',
- *       text: `Fetched user ${users[0].name}`,
- *     });
+ *     const notifyResult = await ctx.integrations.notifier.apiRequest(
+ *       { method: 'POST', path: '/chat.postMessage', body: { channel: '#alerts', text: `Fetched user ${users[0].name}` } },
+ *       { response: z.object({ channel: z.string(), ts: z.string() }) }
+ *     );
+ *     if (!notifyResult.ok) {
+ *       throw new Error(`Slack API error: ${notifyResult.error}`);
+ *     }
  *     return { user: users[0] };
  *   },
  * });
@@ -85,7 +89,7 @@ export interface ApiConfig<
    * ```typescript
    * integrations: {
    *   db: postgres('Production Postgres'),
-   *   cache: redis('Cache Redis'),
+   *   cache: mongodb('Cache MongoDB'),
    * }
    * ```
    */
@@ -161,7 +165,13 @@ export interface ApiContext<
    * const users = await ctx.integrations.db.query('SELECT * FROM users', UserSchema);
    *
    * // ctx.integrations.notifier is SlackClient
-   * await ctx.integrations.notifier.postMessage({ channel: '#alerts', text: 'Hello!' });
+   * const notifyResult = await ctx.integrations.notifier.apiRequest(
+   *   { method: 'POST', path: '/chat.postMessage', body: { channel: '#alerts', text: 'Hello!' } },
+   *   { response: z.object({ channel: z.string(), ts: z.string() }) }
+   * );
+   * if (!notifyResult.ok) {
+   *   throw new Error(`Slack API error: ${notifyResult.error}`);
+   * }
    * ```
    */
   readonly integrations: IntegrationsMap<TIntegrations>;