@superblocksteam/sdk-api 0.0.4

package/src/integrations/redis/README.md

@@ -0,0 +1,200 @@
+# Redis Client
+
+Execute Redis commands with full type safety and runtime validation.
+
+## Methods
+
+| Method                                | Description                 |
+| ------------------------------------- | --------------------------- |
+| `command(command, schema, metadata?)` | Execute a raw Redis command |
+
+## Usage
+
+### GET Command
+
+```typescript
+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(),
+  }),
+  output: z.object({
+    value: z.string().nullable(),
+  }),
+  async run(ctx, { key }) {
+    const value = await ctx.integrations.redis.command(
+      `GET ${key}`,
+      z.string().nullable(),
+    );
+
+    return { value };
+  },
+});
+```
+
+### SET Command
+
+```typescript
+await ctx.integrations.redis.command('SET mykey "hello"', z.string());
+```
+
+### SET with Expiration
+
+```typescript
+// Set with 1 hour TTL
+await ctx.integrations.redis.command('SET mykey "hello" EX 3600', z.string());
+```
+
+### DELETE Command
+
+```typescript
+const deleted = await ctx.integrations.redis.command("DEL mykey", z.number());
+```
+
+### Hash Operations
+
+```typescript
+// HSET
+await ctx.integrations.redis.command(
+  'HSET user:1 name "John" age "30"',
+  z.number(),
+);
+
+// HGET
+const name = await ctx.integrations.redis.command(
+  "HGET user:1 name",
+  z.string().nullable(),
+);
+
+// HGETALL
+const user = await ctx.integrations.redis.command(
+  "HGETALL user:1",
+  z.record(z.string()),
+);
+```
+
+### List Operations
+
+```typescript
+// LPUSH
+await ctx.integrations.redis.command('LPUSH mylist "a" "b" "c"', z.number());
+
+// LRANGE
+const items = await ctx.integrations.redis.command(
+  "LRANGE mylist 0 -1",
+  z.array(z.string()),
+);
+
+// LLEN
+const length = await ctx.integrations.redis.command("LLEN mylist", z.number());
+```
+
+### Set Operations
+
+```typescript
+// SADD
+await ctx.integrations.redis.command('SADD myset "a" "b" "c"', z.number());
+
+// SMEMBERS
+const members = await ctx.integrations.redis.command(
+  "SMEMBERS myset",
+  z.array(z.string()),
+);
+
+// SISMEMBER
+const isMember = await ctx.integrations.redis.command(
+  'SISMEMBER myset "a"',
+  z.number(),
+);
+```
+
+### Counter Operations
+
+```typescript
+// INCR
+const newValue = await ctx.integrations.redis.command(
+  "INCR counter",
+  z.number(),
+);
+
+// INCRBY
+const newValue2 = await ctx.integrations.redis.command(
+  "INCRBY counter 5",
+  z.number(),
+);
+```
+
+### TTL Operations
+
+```typescript
+// Set expiration
+await ctx.integrations.redis.command("EXPIRE mykey 3600", z.number());
+
+// Get TTL
+const ttl = await ctx.integrations.redis.command("TTL mykey", z.number());
+```
+
+## 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
+
+### Quote String Values
+
+String values with spaces need quotes:
+
+```typescript
+// CORRECT
+await ctx.integrations.redis.command('SET mykey "hello world"', z.string());
+
+// WRONG - will fail
+await ctx.integrations.redis.command("SET mykey hello world", z.string());
+```
+
+### Nullable Results
+
+GET returns null for non-existent keys:
+
+```typescript
+const value = await ctx.integrations.redis.command(
+  "GET nonexistent",
+  z.string().nullable(),
+);
+// value is null
+```
+
+## Error Handling
+
+```typescript
+import {
+  RestApiValidationError,
+  IntegrationError,
+} from "@superblocksteam/sdk-api";
+
+try {
+  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);
+  } 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,207 @@
+/**
+ * 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, TraceMetadata } 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,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    try {
+      return await this.executeQuery(request, undefined, metadata);
+    } 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>,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
+    const request = buildRawRequest(command);
+    const rawResult = await this.exec(request, "command", metadata);
+
+    // The Redis plugin wraps raw command results in { response: ... }.
+    // Unwrap to the actual value so callers can validate against the expected type.
+    const result =
+      rawResult !== null &&
+      typeof rawResult === "object" &&
+      "response" in (rawResult as object)
+        ? (rawResult as { response: unknown }).response
+        : rawResult;
+
+    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, metadata?: TraceMetadata): Promise<unknown> {
+    const request = buildStructuredRequest("get", { key });
+    return this.exec(request, "get", metadata);
+  }
+
+  async set(
+    key: string,
+    value: string,
+    expirationMs?: number,
+    metadata?: TraceMetadata,
+  ): 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", metadata);
+  }
+
+  async del(key: string, metadata?: TraceMetadata): Promise<unknown> {
+    const request = buildStructuredRequest("del", { key });
+    return this.exec(request, "del", metadata);
+  }
+
+  async keys(pattern: string, metadata?: TraceMetadata): Promise<unknown> {
+    const request = buildStructuredRequest("keys", { pattern });
+    return this.exec(request, "keys", metadata);
+  }
+
+  async hget(
+    key: string,
+    field: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = buildStructuredRequest("hget", { key, field });
+    return this.exec(request, "hget", metadata);
+  }
+
+  async hset(
+    key: string,
+    field: string,
+    value: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = buildStructuredRequest("hset", { key, field, value });
+    return this.exec(request, "hset", metadata);
+  }
+
+  async hgetall(key: string, metadata?: TraceMetadata): Promise<unknown> {
+    const request = buildStructuredRequest("hgetall", { key });
+    return this.exec(request, "hgetall", metadata);
+  }
+
+  async hdel(
+    key: string,
+    field: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = buildStructuredRequest("hdel", { key, field });
+    return this.exec(request, "hdel", metadata);
+  }
+
+  async expire(
+    key: string,
+    seconds: number,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = buildStructuredRequest("expire", { key, seconds });
+    return this.exec(request, "expire", metadata);
+  }
+
+  async ttl(key: string, metadata?: TraceMetadata): Promise<unknown> {
+    const request = buildStructuredRequest("ttl", { key });
+    return this.exec(request, "ttl", metadata);
+  }
+}

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,166 @@
+/**
+ * Redis client types.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.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
+ * // Declare in api(): integrations: { redis: redis(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.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>,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+
+  /**
+   * Get the value of a key.
+   *
+   * @param key - The key to get
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The value, or null if the key does not exist
+   */
+  get(key: string, metadata?: TraceMetadata): 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
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The result (typically "OK")
+   */
+  set(
+    key: string,
+    value: string,
+    expirationMs?: number,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Delete a key.
+   *
+   * @param key - The key to delete
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The number of keys removed
+   */
+  del(key: string, metadata?: TraceMetadata): Promise<unknown>;
+
+  /**
+   * Find all keys matching a pattern.
+   *
+   * @param pattern - The glob-style pattern to match (e.g., "user:*")
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns Array of matching keys
+   */
+  keys(pattern: string, metadata?: TraceMetadata): Promise<unknown>;
+
+  /**
+   * Get the value of a hash field.
+   *
+   * @param key - The hash key
+   * @param field - The field name
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The field value, or null if the field does not exist
+   */
+  hget(key: string, field: string, metadata?: TraceMetadata): 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
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The number of fields that were added
+   */
+  hset(
+    key: string,
+    field: string,
+    value: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Get all fields and values of a hash.
+   *
+   * @param key - The hash key
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns Object with all field-value pairs
+   */
+  hgetall(key: string, metadata?: TraceMetadata): Promise<unknown>;
+
+  /**
+   * Delete a hash field.
+   *
+   * @param key - The hash key
+   * @param field - The field to delete
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The number of fields that were removed
+   */
+  hdel(key: string, field: string, metadata?: TraceMetadata): Promise<unknown>;
+
+  /**
+   * Set expiration on a key.
+   *
+   * @param key - The key to set expiration on
+   * @param seconds - Time to live in seconds
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns 1 if timeout was set, 0 if key does not exist
+   */
+  expire(
+    key: string,
+    seconds: number,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Get the remaining time to live of a key.
+   *
+   * @param key - The key to check
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns TTL in seconds, -2 if key does not exist, -1 if no expiration
+   */
+  ttl(key: string, metadata?: TraceMetadata): Promise<unknown>;
+}