@superblocksteam/sdk-api 2.0.93 → 2.0.94-next.0

package/src/integrations/redis/README.md

@@ -4,8 +4,8 @@ Execute Redis commands with full type safety and runtime validation.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                     | Description                 |
+| -------------------------- | --------------------------- |
 | `command(command, schema)` | Execute a raw Redis command |
 
 ## Usage
@@ -13,12 +13,15 @@ Execute Redis commands with full type safety and runtime validation.
 ### GET Command
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, redis } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_REDIS = "a1b2c3d4-5678-90ab-cdef-redis0000001";
 
 export default api({
+  integrations: {
+    redis: redis(PROD_REDIS),
+  },
   name: "RedisExample",
   input: z.object({
     key: z.string(),
@@ -27,11 +30,9 @@ export default api({
     value: z.string().nullable(),
   }),
   async run(ctx, { key }) {
-    const redis = ctx.redis(PROD_REDIS);
-
-    const value = await redis.command(
+    const value = await ctx.integrations.redis.command(
       `GET ${key}`,
-      z.string().nullable()
+      z.string().nullable(),
     );
 
     return { value };
@@ -42,41 +43,41 @@ export default api({
 ### SET Command
 
 ```typescript
-await redis.command('SET mykey "hello"', z.string());
+await ctx.integrations.redis.command('SET mykey "hello"', z.string());
 ```
 
 ### SET with Expiration
 
 ```typescript
 // Set with 1 hour TTL
-await redis.command('SET mykey "hello" EX 3600', z.string());
+await ctx.integrations.redis.command('SET mykey "hello" EX 3600', z.string());
 ```
 
 ### DELETE Command
 
 ```typescript
-const deleted = await redis.command("DEL mykey", z.number());
+const deleted = await ctx.integrations.redis.command("DEL mykey", z.number());
 ```
 
 ### Hash Operations
 
 ```typescript
 // HSET
-await redis.command(
+await ctx.integrations.redis.command(
   'HSET user:1 name "John" age "30"',
-  z.number()
+  z.number(),
 );
 
 // HGET
-const name = await redis.command(
+const name = await ctx.integrations.redis.command(
   "HGET user:1 name",
-  z.string().nullable()
+  z.string().nullable(),
 );
 
 // HGETALL
-const user = await redis.command(
+const user = await ctx.integrations.redis.command(
   "HGETALL user:1",
-  z.record(z.string())
+  z.record(z.string()),
 );
 ```
 
@@ -84,34 +85,34 @@ const user = await redis.command(
 
 ```typescript
 // LPUSH
-await redis.command('LPUSH mylist "a" "b" "c"', z.number());
+await ctx.integrations.redis.command('LPUSH mylist "a" "b" "c"', z.number());
 
 // LRANGE
-const items = await redis.command(
+const items = await ctx.integrations.redis.command(
   "LRANGE mylist 0 -1",
-  z.array(z.string())
+  z.array(z.string()),
 );
 
 // LLEN
-const length = await redis.command("LLEN mylist", z.number());
+const length = await ctx.integrations.redis.command("LLEN mylist", z.number());
 ```
 
 ### Set Operations
 
 ```typescript
 // SADD
-await redis.command('SADD myset "a" "b" "c"', z.number());
+await ctx.integrations.redis.command('SADD myset "a" "b" "c"', z.number());
 
 // SMEMBERS
-const members = await redis.command(
+const members = await ctx.integrations.redis.command(
   "SMEMBERS myset",
-  z.array(z.string())
+  z.array(z.string()),
 );
 
 // SISMEMBER
-const isMember = await redis.command(
+const isMember = await ctx.integrations.redis.command(
   'SISMEMBER myset "a"',
-  z.number()
+  z.number(),
 );
 ```
 
@@ -119,20 +120,26 @@ const isMember = await redis.command(
 
 ```typescript
 // INCR
-const newValue = await redis.command("INCR counter", z.number());
+const newValue = await ctx.integrations.redis.command(
+  "INCR counter",
+  z.number(),
+);
 
 // INCRBY
-const newValue2 = await redis.command("INCRBY counter 5", z.number());
+const newValue2 = await ctx.integrations.redis.command(
+  "INCRBY counter 5",
+  z.number(),
+);
 ```
 
 ### TTL Operations
 
 ```typescript
 // Set expiration
-await redis.command("EXPIRE mykey 3600", z.number());
+await ctx.integrations.redis.command("EXPIRE mykey 3600", z.number());
 
 // Get TTL
-const ttl = await redis.command("TTL mykey", z.number());
+const ttl = await ctx.integrations.redis.command("TTL mykey", z.number());
 ```
 
 ## Common Pitfalls
@@ -143,10 +150,10 @@ String values with spaces need quotes:
 
 ```typescript
 // CORRECT
-await redis.command('SET mykey "hello world"', z.string());
+await ctx.integrations.redis.command('SET mykey "hello world"', z.string());
 
 // WRONG - will fail
-await redis.command("SET mykey hello world", z.string());
+await ctx.integrations.redis.command("SET mykey hello world", z.string());
 ```
 
 ### Nullable Results
@@ -154,9 +161,9 @@ await redis.command("SET mykey hello world", z.string());
 GET returns null for non-existent keys:
 
 ```typescript
-const value = await redis.command(
+const value = await ctx.integrations.redis.command(
   "GET nonexistent",
-  z.string().nullable()
+  z.string().nullable(),
 );
 // value is null
 ```
@@ -164,10 +171,16 @@ const value = await redis.command(
 ## Error Handling
 
 ```typescript
-import { RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+import {
+  RestApiValidationError,
+  IntegrationError,
+} from "@superblocksteam/sdk-api";
 
 try {
-  const value = await redis.command("GET mykey", z.string().nullable());
+  const value = await ctx.integrations.redis.command(
+    "GET mykey",
+    z.string().nullable(),
+  );
 } catch (error) {
   if (error instanceof RestApiValidationError) {
     console.error("Validation failed:", error.details.zodError);

package/src/integrations/redis/client.ts

@@ -10,12 +10,12 @@
  * - Structured: `{ structured: { set: { key: "...", value: "..." } } }`
  */
 
-import type { z } from 'zod';
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { RestApiValidationError } from '../../errors.js';
-import { IntegrationError } from '../../runtime/errors.js';
-import type { RedisClient } from './types.js';
+import type { z } from "zod";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { RestApiValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import type { RedisClient } from "./types.js";
 
 /**
  * Build a raw Redis command request matching the proto JSON format.
@@ -98,7 +98,7 @@ export class RedisClientImpl implements RedisClient, IntegrationClientImpl {
 
   async command<T>(command: string, schema: z.ZodSchema<T>): Promise<T> {
     const request = buildRawRequest(command);
-    const result = await this.exec(request, 'command');
+    const result = await this.exec(request, "command");
 
     const parseResult = schema.safeParse(result);
 
@@ -116,56 +116,60 @@ export class RedisClientImpl implements RedisClient, IntegrationClientImpl {
   }
 
   async get(key: string): Promise<unknown> {
-    const request = buildStructuredRequest('get', { key });
-    return this.exec(request, 'get');
+    const request = buildStructuredRequest("get", { key });
+    return this.exec(request, "get");
   }
 
-  async set(key: string, value: string, expirationMs?: number): Promise<unknown> {
+  async set(
+    key: string,
+    value: string,
+    expirationMs?: number,
+  ): Promise<unknown> {
     const params: Record<string, unknown> = { key, value };
     if (expirationMs !== undefined) {
       params.expirationMs = expirationMs;
     }
-    const request = buildStructuredRequest('set', params);
-    return this.exec(request, 'set');
+    const request = buildStructuredRequest("set", params);
+    return this.exec(request, "set");
   }
 
   async del(key: string): Promise<unknown> {
-    const request = buildStructuredRequest('del', { key });
-    return this.exec(request, 'del');
+    const request = buildStructuredRequest("del", { key });
+    return this.exec(request, "del");
   }
 
   async keys(pattern: string): Promise<unknown> {
-    const request = buildStructuredRequest('keys', { pattern });
-    return this.exec(request, 'keys');
+    const request = buildStructuredRequest("keys", { pattern });
+    return this.exec(request, "keys");
   }
 
   async hget(key: string, field: string): Promise<unknown> {
-    const request = buildStructuredRequest('hget', { key, field });
-    return this.exec(request, 'hget');
+    const request = buildStructuredRequest("hget", { key, field });
+    return this.exec(request, "hget");
   }
 
   async hset(key: string, field: string, value: string): Promise<unknown> {
-    const request = buildStructuredRequest('hset', { key, field, value });
-    return this.exec(request, 'hset');
+    const request = buildStructuredRequest("hset", { key, field, value });
+    return this.exec(request, "hset");
   }
 
   async hgetall(key: string): Promise<unknown> {
-    const request = buildStructuredRequest('hgetall', { key });
-    return this.exec(request, 'hgetall');
+    const request = buildStructuredRequest("hgetall", { key });
+    return this.exec(request, "hgetall");
   }
 
   async hdel(key: string, field: string): Promise<unknown> {
-    const request = buildStructuredRequest('hdel', { key, field });
-    return this.exec(request, 'hdel');
+    const request = buildStructuredRequest("hdel", { key, field });
+    return this.exec(request, "hdel");
   }
 
   async expire(key: string, seconds: number): Promise<unknown> {
-    const request = buildStructuredRequest('expire', { key, seconds });
-    return this.exec(request, 'expire');
+    const request = buildStructuredRequest("expire", { key, seconds });
+    return this.exec(request, "expire");
   }
 
   async ttl(key: string): Promise<unknown> {
-    const request = buildStructuredRequest('ttl', { key });
-    return this.exec(request, 'ttl');
+    const request = buildStructuredRequest("ttl", { key });
+    return this.exec(request, "ttl");
   }
 }

package/src/integrations/redis/index.ts

@@ -4,5 +4,5 @@
  * @module
  */
 
-export type { RedisClient } from './types.js';
-export { RedisClientImpl } from './client.js';
+export type { RedisClient } from "./types.js";
+export { RedisClientImpl } from "./client.js";

package/src/integrations/redis/types.ts

@@ -2,8 +2,8 @@
  * Redis client types.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Redis client for executing commands.
@@ -13,7 +13,8 @@ import type { BaseIntegrationClient } from '../../types.js';
  *
  * @example
  * ```typescript
- * const redis = ctx.redis('Production Redis');
+ * // Declare in api(): integrations: { redis: redis(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.redis
  *
  * // Typed string operations
  * await redis.set('user:1', 'Alice');

package/src/integrations/redshift/README.md

@@ -4,17 +4,17 @@ Execute SQL queries and statements against Amazon Redshift data warehouses with
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
-| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results |
-| `execute(sql, params?)` | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+| Method                           | Description                                                                |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results                 |
+| `execute(sql, params?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
 
 ## Usage
 
 ### Basic Query with Schema Validation
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, redshift } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_REDSHIFT = "a1b2c3d4-5678-90ab-cdef-redshift0001";
@@ -27,6 +27,9 @@ const UserSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    redshift: redshift(PROD_REDSHIFT),
+  },
   name: "RedshiftExample",
   input: z.object({
     status: z.string(),
@@ -35,12 +38,10 @@ export default api({
     users: z.array(UserSchema),
   }),
   async run(ctx, { status }) {
-    const redshift = ctx.redshift(PROD_REDSHIFT);
-
-    const users = await redshift.query(
+    const users = await ctx.integrations.redshift.query(
       "SELECT id, name, email, created_at FROM users WHERE status = $1",
       UserSchema,
-      [status]
+      [status],
     );
 
     return { users };
@@ -51,24 +52,22 @@ export default api({
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
-const redshift = ctx.redshift(PROD_REDSHIFT);
-
 // INSERT
-await redshift.execute(
+await ctx.integrations.redshift.execute(
   "INSERT INTO users (name, email) VALUES ($1, $2)",
-  ["John Doe", "john@example.com"]
+  ["John Doe", "john@example.com"],
 );
 
 // UPDATE
-const updateResult = await redshift.execute(
+const updateResult = await ctx.integrations.redshift.execute(
   "UPDATE users SET last_login = GETDATE() WHERE id = $1",
-  [userId]
+  [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
 
 // DELETE
-const deleteResult = await redshift.execute(
-  "DELETE FROM sessions WHERE expires_at < GETDATE()"
+const deleteResult = await ctx.integrations.redshift.execute(
+  "DELETE FROM sessions WHERE expires_at < GETDATE()",
 );
 console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
 ```
@@ -82,7 +81,7 @@ const AnalyticsSchema = z.object({
   unique_customers: z.coerce.number(),
 });
 
-const analytics = await redshift.query(
+const analytics = await ctx.integrations.redshift.query(
   `SELECT
     DATE_TRUNC('day', order_date) as date,
     SUM(total) as total_sales,
@@ -91,7 +90,7 @@ const analytics = await redshift.query(
   WHERE order_date >= DATEADD(day, -30, GETDATE())
   GROUP BY DATE_TRUNC('day', order_date)
   ORDER BY date DESC`,
-  AnalyticsSchema
+  AnalyticsSchema,
 );
 ```
 
@@ -117,7 +116,10 @@ const schema = z.object({
 
 ```typescript
 // CORRECT - Schema is required
-const users = await redshift.query("SELECT * FROM users", UserSchema);
+const users = await ctx.integrations.redshift.query(
+  "SELECT * FROM users",
+  UserSchema,
+);
 ```
 
 ### NULL Handling
@@ -135,7 +137,10 @@ const schema = z.object({
 import { QueryValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const users = await redshift.query("SELECT * FROM users", UserSchema);
+  const users = await ctx.integrations.redshift.query(
+    "SELECT * FROM users",
+    UserSchema,
+  );
 } catch (error) {
   if (error instanceof QueryValidationError) {
     console.error("Row index:", error.details.rowIndex);

package/src/integrations/redshift/client.ts

@@ -5,20 +5,22 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from 'zod';
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { Plugin as RedshiftPlugin } from '@superblocksteam/types/dist/src/plugins/redshift/v1/plugin_pb';
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { QueryValidationError } from '../../errors.js';
-import { IntegrationError } from '../../runtime/errors.js';
-import { describeType } from '../utils.js';
-import type { RedshiftClient } from './types.js';
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as RedshiftPlugin } from "@superblocksteam/types/dist/src/plugins/redshift/v1/plugin_pb";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { QueryValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import { describeType } from "../utils.js";
+import type { RedshiftClient } from "./types.js";
 
 /**
  * Internal implementation of the Redshift client.
  */
-export class RedshiftClientImpl implements RedshiftClient, IntegrationClientImpl {
+export class RedshiftClientImpl
+  implements RedshiftClient, IntegrationClientImpl
+{
   readonly config: IntegrationConfig;
   private readonly executeQuery: QueryExecutor;
 
@@ -71,7 +73,7 @@ export class RedshiftClientImpl implements RedshiftClient, IntegrationClientImpl
       if (!Array.isArray(result)) {
         throw new IntegrationError(
           this.config.name,
-          'query',
+          "query",
           `Expected array result from Redshift query, got: ${describeType(result)}`,
         );
       }
@@ -107,27 +109,30 @@ export class RedshiftClientImpl implements RedshiftClient, IntegrationClientImpl
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'query', error);
+      throw new IntegrationError(this.config.name, "query", error);
     }
   }
 
-  async execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }> {
+  async execute(
+    sql: string,
+    params?: unknown[],
+  ): Promise<{ rowCount: number }> {
     const request = this.buildRequest(sql, params);
 
     try {
       const result = await this.executeQuery(request);
 
       if (
-        typeof result === 'object' &&
+        typeof result === "object" &&
         result !== null &&
-        'rowCount' in result
+        "rowCount" in result
       ) {
         return { rowCount: Number(result.rowCount) || 0 };
       }
 
       return { rowCount: 0 };
     } catch (error) {
-      throw new IntegrationError(this.config.name, 'execute', error);
+      throw new IntegrationError(this.config.name, "execute", error);
     }
   }
 }

package/src/integrations/redshift/index.ts

@@ -4,5 +4,5 @@
  * @module
  */
 
-export type { RedshiftClient } from './types.js';
-export { RedshiftClientImpl } from './client.js';
+export type { RedshiftClient } from "./types.js";
+export { RedshiftClientImpl } from "./client.js";

package/src/integrations/redshift/types.ts

@@ -4,15 +4,16 @@
  * Provides typed methods for executing Redshift queries with runtime validation.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Client for executing Redshift queries with type-safe validation.
  *
  * @example
  * ```typescript
- * const redshift = ctx.redshift('Production Redshift');
+ * // Declare in api(): integrations: { redshift: redshift(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.redshift
  *
  * // Query with validation
  * const UserSchema = z.object({
@@ -40,7 +41,11 @@ export interface RedshiftClient extends BaseIntegrationClient {
    * @throws {QueryValidationError} If results don't match schema
    * @throws {IntegrationError} If query execution fails
    */
-  query<T>(sql: string, schema: z.ZodSchema<T>, params?: unknown[]): Promise<T[]>;
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]>;
 
   /**
    * Execute a SQL statement (INSERT, UPDATE, DELETE) without output validation.

package/src/integrations/registry.test.ts

@@ -1,22 +1,26 @@
-import { describe, expect, it, vi } from 'vitest';
-import { createClient, isPluginSupported, SUPPORTED_PLUGINS } from './registry.js';
-import { SnowflakeCortexClientImpl } from './snowflakecortex/index.js';
+import { describe, expect, it, vi } from "vitest";
+import {
+  createClient,
+  isPluginSupported,
+  SUPPORTED_PLUGINS,
+} from "./registry.js";
+import { SnowflakeCortexClientImpl } from "./snowflakecortex/index.js";
 
-describe('integration registry', () => {
-  it('supports snowflakecortex plugin id', () => {
-    expect(isPluginSupported('snowflakecortex')).toBe(true);
+describe("integration registry", () => {
+  it("supports snowflakecortex plugin id", () => {
+    expect(isPluginSupported("snowflakecortex")).toBe(true);
     expect(isPluginSupported(SUPPORTED_PLUGINS.snowflakecortex)).toBe(true);
   });
 
-  it('creates a SnowflakeCortex client with streaming support', () => {
+  it("creates a SnowflakeCortex client with streaming support", () => {
     const executeQuery = vi.fn();
     const executeStreamingQuery = vi.fn();
 
     const client = createClient({
       config: {
-        id: 'snowflake-cortex-id',
-        name: 'Snowflake Cortex',
-        pluginId: 'snowflakecortex',
+        id: "snowflake-cortex-id",
+        name: "Snowflake Cortex",
+        pluginId: "snowflakecortex",
         configuration: {},
       },
       executeQuery,