@superblocksteam/sdk-api 0.0.6 → 0.0.7

package/src/integrations/redis/README.md

@@ -1,200 +0,0 @@
-# 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

@@ -1,207 +0,0 @@
-/**
- * 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

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

package/src/integrations/redis/types.ts

@@ -1,166 +0,0 @@
-/**
- * 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>;
-}