@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/redis/README.md

@@ -0,0 +1,183 @@
+# Redis Client
+
+Execute Redis commands with full type safety and runtime validation.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `command(command, schema)` | Execute a raw Redis command |
+
+## Usage
+
+### GET Command
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_REDIS = "a1b2c3d4-5678-90ab-cdef-redis0000001";
+
+export default api({
+  name: "RedisExample",
+  input: z.object({
+    key: z.string(),
+  }),
+  output: z.object({
+    value: z.string().nullable(),
+  }),
+  async run(ctx, { key }) {
+    const redis = ctx.redis(PROD_REDIS);
+
+    const value = await redis.command(
+      `GET ${key}`,
+      z.string().nullable()
+    );
+
+    return { value };
+  },
+});
+```
+
+### SET Command
+
+```typescript
+await 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());
+```
+
+### DELETE Command
+
+```typescript
+const deleted = await redis.command("DEL mykey", z.number());
+```
+
+### Hash Operations
+
+```typescript
+// HSET
+await redis.command(
+  'HSET user:1 name "John" age "30"',
+  z.number()
+);
+
+// HGET
+const name = await redis.command(
+  "HGET user:1 name",
+  z.string().nullable()
+);
+
+// HGETALL
+const user = await redis.command(
+  "HGETALL user:1",
+  z.record(z.string())
+);
+```
+
+### List Operations
+
+```typescript
+// LPUSH
+await redis.command('LPUSH mylist "a" "b" "c"', z.number());
+
+// LRANGE
+const items = await redis.command(
+  "LRANGE mylist 0 -1",
+  z.array(z.string())
+);
+
+// LLEN
+const length = await redis.command("LLEN mylist", z.number());
+```
+
+### Set Operations
+
+```typescript
+// SADD
+await redis.command('SADD myset "a" "b" "c"', z.number());
+
+// SMEMBERS
+const members = await redis.command(
+  "SMEMBERS myset",
+  z.array(z.string())
+);
+
+// SISMEMBER
+const isMember = await redis.command(
+  'SISMEMBER myset "a"',
+  z.number()
+);
+```
+
+### Counter Operations
+
+```typescript
+// INCR
+const newValue = await redis.command("INCR counter", z.number());
+
+// INCRBY
+const newValue2 = await redis.command("INCRBY counter 5", z.number());
+```
+
+### TTL Operations
+
+```typescript
+// Set expiration
+await redis.command("EXPIRE mykey 3600", z.number());
+
+// Get TTL
+const ttl = await redis.command("TTL mykey", z.number());
+```
+
+## Common Pitfalls
+
+### Quote String Values
+
+String values with spaces need quotes:
+
+```typescript
+// CORRECT
+await redis.command('SET mykey "hello world"', z.string());
+
+// WRONG - will fail
+await redis.command("SET mykey hello world", z.string());
+```
+
+### Nullable Results
+
+GET returns null for non-existent keys:
+
+```typescript
+const value = await redis.command(
+  "GET nonexistent",
+  z.string().nullable()
+);
+// value is null
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+
+try {
+  const value = await redis.command("GET mykey", z.string().nullable());
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  } else if (error instanceof IntegrationError) {
+    console.error("Redis error:", error.message);
+  }
+}
+```
+
+## API Reference
+
+- [Redis Commands](https://redis.io/commands/)
+- [Redis Data Types](https://redis.io/docs/data-types/)

package/src/integrations/redis/client.ts

@@ -0,0 +1,171 @@
+/**
+ * Redis client implementation.
+ *
+ * Uses the native Redis plugin type from @superblocksteam/types.
+ * Supports raw Redis commands and typed structured operations
+ * (get, set, del, keys, hget, hset, hgetall, etc.).
+ *
+ * Request format matches the Redis plugin proto's oneof structure:
+ * - Raw: `{ raw: { singleton: { query: "..." } } }`
+ * - 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';
+
+/**
+ * Build a raw Redis command request matching the proto JSON format.
+ *
+ * Proto structure: `oneof command_type { Raw raw = 3; }`
+ * Raw structure: `oneof action { Singleton singleton = 1; }`
+ */
+function buildRawRequest(command: string): Record<string, unknown> {
+  return {
+    raw: {
+      singleton: {
+        query: command,
+      },
+    },
+  };
+}
+
+/**
+ * Build a structured Redis command request matching the proto JSON format.
+ *
+ * Proto structure: `oneof command_type { Structured structured = 4; }`
+ * Structured structure: `oneof action { Get get = 6; Set set = 7; ... }`
+ *
+ * @param actionName - The structured action name (e.g., 'get', 'set')
+ * @param value - The action-specific parameters
+ */
+function buildStructuredRequest(
+  actionName: string,
+  value: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    structured: {
+      [actionName]: value,
+    },
+  };
+}
+
+/**
+ * Internal implementation of RedisClient.
+ *
+ * Provides both raw and structured Redis command execution.
+ */
+export class RedisClientImpl implements RedisClient, 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: Record<string, unknown>,
+    operation: string,
+  ): Promise<unknown> {
+    try {
+      return await this.executeQuery(request);
+    } catch (error) {
+      if (
+        error instanceof RestApiValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, operation, error);
+    }
+  }
+
+  async command<T>(command: string, schema: z.ZodSchema<T>): Promise<T> {
+    const request = buildRawRequest(command);
+    const result = await this.exec(request, 'command');
+
+    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 get(key: string): Promise<unknown> {
+    const request = buildStructuredRequest('get', { key });
+    return this.exec(request, 'get');
+  }
+
+  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');
+  }
+
+  async del(key: string): Promise<unknown> {
+    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');
+  }
+
+  async hget(key: string, field: string): Promise<unknown> {
+    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');
+  }
+
+  async hgetall(key: string): Promise<unknown> {
+    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');
+  }
+
+  async expire(key: string, seconds: number): Promise<unknown> {
+    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');
+  }
+}

package/src/integrations/redis/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Redis integration client.
+ *
+ * @module
+ */
+
+export type { RedisClient } from './types.js';
+export { RedisClientImpl } from './client.js';

package/src/integrations/redis/types.ts

@@ -0,0 +1,136 @@
+/**
+ * Redis client types.
+ */
+
+import type { z } from 'zod';
+import type { BaseIntegrationClient } from '../../types.js';
+
+/**
+ * Redis client for executing commands.
+ *
+ * Provides typed methods for common Redis operations as well as a
+ * generic command() method for executing raw Redis commands.
+ *
+ * @example
+ * ```typescript
+ * const redis = ctx.redis('Production Redis');
+ *
+ * // Typed string operations
+ * await redis.set('user:1', 'Alice');
+ * const name = await redis.get('user:1');
+ *
+ * // Typed hash operations
+ * await redis.hset('user:1', 'name', 'Alice');
+ * const val = await redis.hget('user:1', 'name');
+ * const all = await redis.hgetall('user:1');
+ *
+ * // Key operations
+ * await redis.del('user:1');
+ * const userKeys = await redis.keys('user:*');
+ *
+ * // Raw command for anything not covered by typed methods
+ * const result = await redis.command(
+ *   'LRANGE mylist 0 -1',
+ *   z.array(z.string())
+ * );
+ * ```
+ */
+export interface RedisClient extends BaseIntegrationClient {
+  /**
+   * Execute a raw Redis command.
+   *
+   * Use this for commands not covered by the typed methods.
+   *
+   * @param command - The Redis command string (e.g., "LRANGE mylist 0 -1")
+   * @param schema - Zod schema for validating the result
+   * @returns The validated result
+   */
+  command<T>(command: string, schema: z.ZodSchema<T>): Promise<T>;
+
+  /**
+   * Get the value of a key.
+   *
+   * @param key - The key to get
+   * @returns The value, or null if the key does not exist
+   */
+  get(key: string): Promise<unknown>;
+
+  /**
+   * Set the value of a key.
+   *
+   * @param key - The key to set
+   * @param value - The value to set
+   * @param expirationMs - Optional expiration time in milliseconds
+   * @returns The result (typically "OK")
+   */
+  set(key: string, value: string, expirationMs?: number): Promise<unknown>;
+
+  /**
+   * Delete a key.
+   *
+   * @param key - The key to delete
+   * @returns The number of keys removed
+   */
+  del(key: string): Promise<unknown>;
+
+  /**
+   * Find all keys matching a pattern.
+   *
+   * @param pattern - The glob-style pattern to match (e.g., "user:*")
+   * @returns Array of matching keys
+   */
+  keys(pattern: string): Promise<unknown>;
+
+  /**
+   * Get the value of a hash field.
+   *
+   * @param key - The hash key
+   * @param field - The field name
+   * @returns The field value, or null if the field does not exist
+   */
+  hget(key: string, field: string): Promise<unknown>;
+
+  /**
+   * Set the value of a hash field.
+   *
+   * @param key - The hash key
+   * @param field - The field name
+   * @param value - The value to set
+   * @returns The number of fields that were added
+   */
+  hset(key: string, field: string, value: string): Promise<unknown>;
+
+  /**
+   * Get all fields and values of a hash.
+   *
+   * @param key - The hash key
+   * @returns Object with all field-value pairs
+   */
+  hgetall(key: string): Promise<unknown>;
+
+  /**
+   * Delete a hash field.
+   *
+   * @param key - The hash key
+   * @param field - The field to delete
+   * @returns The number of fields that were removed
+   */
+  hdel(key: string, field: string): Promise<unknown>;
+
+  /**
+   * Set expiration on a key.
+   *
+   * @param key - The key to set expiration on
+   * @param seconds - Time to live in seconds
+   * @returns 1 if timeout was set, 0 if key does not exist
+   */
+  expire(key: string, seconds: number): Promise<unknown>;
+
+  /**
+   * Get the remaining time to live of a key.
+   *
+   * @param key - The key to check
+   * @returns TTL in seconds, -2 if key does not exist, -1 if no expiration
+   */
+  ttl(key: string): Promise<unknown>;
+}

package/src/integrations/redshift/README.md

@@ -0,0 +1,151 @@
+# Redshift Client
+
+Execute SQL queries and statements against Amazon Redshift data warehouses with full type safety and runtime validation.
+
+## 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 |
+
+## Usage
+
+### Basic Query with Schema Validation
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_REDSHIFT = "a1b2c3d4-5678-90ab-cdef-redshift0001";
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email(),
+  created_at: z.string(),
+});
+
+export default api({
+  name: "RedshiftExample",
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: z.array(UserSchema),
+  }),
+  async run(ctx, { status }) {
+    const redshift = ctx.redshift(PROD_REDSHIFT);
+
+    const users = await redshift.query(
+      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      UserSchema,
+      [status]
+    );
+
+    return { users };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+const redshift = ctx.redshift(PROD_REDSHIFT);
+
+// INSERT
+await redshift.execute(
+  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  ["John Doe", "john@example.com"]
+);
+
+// UPDATE
+const updateResult = await redshift.execute(
+  "UPDATE users SET last_login = GETDATE() WHERE id = $1",
+  [userId]
+);
+console.log(`Updated ${updateResult.rowCount} rows`);
+
+// DELETE
+const deleteResult = await redshift.execute(
+  "DELETE FROM sessions WHERE expires_at < GETDATE()"
+);
+console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
+```
+
+### Analytics Query
+
+```typescript
+const AnalyticsSchema = z.object({
+  date: z.string(),
+  total_sales: z.string(),
+  unique_customers: z.coerce.number(),
+});
+
+const analytics = await redshift.query(
+  `SELECT
+    DATE_TRUNC('day', order_date) as date,
+    SUM(total) as total_sales,
+    COUNT(DISTINCT customer_id) as unique_customers
+  FROM orders
+  WHERE order_date >= DATEADD(day, -30, GETDATE())
+  GROUP BY DATE_TRUNC('day', order_date)
+  ORDER BY date DESC`,
+  AnalyticsSchema
+);
+```
+
+## Common Pitfalls
+
+### BIGINT Values Returned as Strings
+
+```typescript
+const schema = z.object({
+  count: z.coerce.number(),
+});
+```
+
+### DECIMAL Values Returned as Strings
+
+```typescript
+const schema = z.object({
+  amount: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Schema Parameter is Required
+
+```typescript
+// CORRECT - Schema is required
+const users = await redshift.query("SELECT * FROM users", UserSchema);
+```
+
+### NULL Handling
+
+```typescript
+const schema = z.object({
+  name: z.string(),
+  bio: z.string().nullable(),
+});
+```
+
+## Error Handling
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const users = await redshift.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);
+  }
+}
+```
+
+## API Reference
+
+- [Amazon Redshift Documentation](https://docs.aws.amazon.com/redshift/)
+- [Redshift SQL Reference](https://docs.aws.amazon.com/redshift/latest/dg/c_SQL_commands.html)
+- [Redshift Data Types](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html)