@superblocksteam/sdk-api 0.0.4

package/src/integrations/snowflakepostgres/types.ts

@@ -0,0 +1,61 @@
+/**
+ * Snowflake Postgres client types.
+ *
+ * Snowflake Postgres is a SQL database integration that supports parameterized
+ * queries via the `body` and `parameters` proto fields.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * Snowflake Postgres client for SQL query and execute operations.
+ *
+ * @example
+ * ```typescript
+ * const sfpg = ctx.integrations.db;
+ *
+ * // Parameterized query
+ * const users = await sfpg.query(
+ *   'SELECT * FROM users WHERE status = $1',
+ *   UserSchema,
+ *   ['active'],
+ * );
+ *
+ * // Execute a mutation
+ * const result = await sfpg.execute(
+ *   'INSERT INTO users (name, email) VALUES ($1, $2)',
+ *   ['Alice', 'alice@example.com'],
+ * );
+ * ```
+ */
+export interface SnowflakePostgresClient extends BaseIntegrationClient {
+  /**
+   * Execute a SQL query and return validated rows.
+   *
+   * @param sql - SQL query string with `$1`, `$2` placeholders for parameters
+   * @param schema - Zod schema for validating each result row
+   * @param params - Optional query parameters for server-side binding
+   * @returns Array of validated rows
+   */
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<T[]>;
+
+  /**
+   * Execute a SQL statement (INSERT, UPDATE, DELETE).
+   *
+   * @param sql - SQL statement with `$1`, `$2` placeholders for parameters
+   * @param params - Optional query parameters for server-side binding
+   * @returns The affected row count
+   */
+  execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }>;
+}

package/src/integrations/stabilityai/README.md

@@ -0,0 +1,460 @@
+# Stability AI Client
+
+Generate, edit, and upscale images using Stability AI's image generation models.
+
+## Methods
+
+| Method                                   | Description                                              |
+| ---------------------------------------- | -------------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Stability AI API request with schema validation |
+
+## Usage
+
+### Generate an Image (Text-to-Image)
+
+```typescript
+import { api, z, stabilityai } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_STABILITY = "a1b2c3d4-5678-90ab-cdef-stabilit0001";
+
+const ImageArtifactSchema = z.object({
+  base64: z.string(),
+  finishReason: z.string(), // SUCCESS, CONTENT_FILTERED, ERROR
+  seed: z.number(),
+});
+
+const GenerationResponseSchema = z.object({
+  artifacts: z.array(ImageArtifactSchema),
+});
+
+export default api({
+  integrations: {
+    stability: stabilityai(PROD_STABILITY),
+  },
+  name: "StabilityAIExample",
+  input: z.object({
+    prompt: z.string(),
+    negativePrompt: z.string().optional(),
+    width: z.number().default(1024),
+    height: z.number().default(1024),
+  }),
+  output: z.object({
+    images: z.array(
+      z.object({
+        base64: z.string(),
+        seed: z.number(),
+      }),
+    ),
+  }),
+  async run(ctx, { prompt, negativePrompt, width, height }) {
+    const result = await ctx.integrations.stability.apiRequest(
+      {
+        method: "POST",
+        path: "/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image",
+        body: {
+          text_prompts: [
+            { text: prompt, weight: 1 },
+            ...(negativePrompt ? [{ text: negativePrompt, weight: -1 }] : []),
+          ],
+          cfg_scale: 7,
+          width: width,
+          height: height,
+          samples: 1,
+          steps: 30,
+        },
+      },
+      { response: GenerationResponseSchema },
+    );
+
+    return {
+      images: result.artifacts
+        .filter((a) => a.finishReason === "SUCCESS")
+        .map((a) => ({
+          base64: a.base64,
+          seed: a.seed,
+        })),
+    };
+  },
+});
+```
+
+### Image-to-Image (Transform Existing Image)
+
+```typescript
+const result = await ctx.integrations.stability.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image",
+    headers: {
+      "Content-Type": "multipart/form-data",
+    },
+    body: {
+      init_image: sourceImageBase64,
+      text_prompts: [{ text: "A vibrant oil painting style", weight: 1 }],
+      image_strength: 0.35, // How much to modify (0-1)
+      cfg_scale: 7,
+      samples: 1,
+      steps: 30,
+    },
+  },
+  { response: GenerationResponseSchema },
+);
+```
+
+### Upscale an Image
+
+```typescript
+const UpscaleResponseSchema = z.object({
+  artifacts: z.array(
+    z.object({
+      base64: z.string(),
+      finishReason: z.string(),
+      seed: z.number(),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.stability.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/generation/esrgan-v1-x2plus/image-to-image/upscale",
+    headers: {
+      "Content-Type": "multipart/form-data",
+    },
+    body: {
+      image: sourceImageBase64,
+      width: 2048, // Target width (optional)
+    },
+  },
+  { response: UpscaleResponseSchema },
+);
+
+const upscaledImage = result.artifacts[0].base64;
+```
+
+### Inpainting (Edit Parts of an Image)
+
+```typescript
+const result = await ctx.integrations.stability.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image/masking",
+    headers: {
+      "Content-Type": "multipart/form-data",
+    },
+    body: {
+      init_image: sourceImageBase64,
+      mask_image: maskImageBase64, // White areas will be regenerated
+      mask_source: "MASK_IMAGE_WHITE",
+      text_prompts: [{ text: "A golden retriever sitting", weight: 1 }],
+      cfg_scale: 7,
+      samples: 1,
+      steps: 30,
+    },
+  },
+  { response: GenerationResponseSchema },
+);
+```
+
+### Generate with Specific Style
+
+```typescript
+const result = await ctx.integrations.stability.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image",
+    body: {
+      text_prompts: [
+        { text: "A serene mountain landscape at sunset", weight: 1 },
+        { text: "photorealistic, detailed, high quality", weight: 0.5 },
+        { text: "blurry, low quality, distorted", weight: -1 },
+      ],
+      cfg_scale: 7,
+      style_preset: "photographic", // See style presets below
+      width: 1024,
+      height: 1024,
+      samples: 1,
+      steps: 30,
+      seed: 12345, // For reproducibility
+    },
+  },
+  { response: GenerationResponseSchema },
+);
+```
+
+### Get Account Balance
+
+```typescript
+const BalanceResponseSchema = z.object({
+  credits: z.number(),
+});
+
+const result = await ctx.integrations.stability.apiRequest(
+  {
+    method: "GET",
+    path: "/v1/user/balance",
+  },
+  { response: BalanceResponseSchema },
+);
+
+console.log(`Available credits: ${result.credits}`);
+```
+
+### List Available Engines
+
+```typescript
+const EngineSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  type: z.string(),
+});
+
+const ListEnginesResponseSchema = z.object({
+  engines: z.array(EngineSchema),
+});
+
+const result = await ctx.integrations.stability.apiRequest(
+  {
+    method: "GET",
+    path: "/v1/engines/list",
+  },
+  { response: ListEnginesResponseSchema },
+);
+
+result.engines.forEach((engine) => {
+  console.log(`${engine.id}: ${engine.name}`);
+});
+```
+
+## 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
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await stability.generateImage({ ... });
+await stability.upscale({ ... });
+
+// CORRECT - Use apiRequest
+await ctx.integrations.stability.apiRequest(
+  { method: "POST", path: "/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image", body: { ... } },
+  { response: GenerationResponseSchema }
+);
+```
+
+### Engine ID in Path
+
+The engine/model ID is part of the URL path:
+
+```typescript
+// Text-to-image with SDXL 1.0
+const path = "/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image";
+
+// Image-to-image
+const path = "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image";
+
+// Upscaling
+const path = "/v1/generation/esrgan-v1-x2plus/image-to-image/upscale";
+
+// Available engines:
+// - stable-diffusion-xl-1024-v1-0 (SDXL 1.0)
+// - stable-diffusion-v1-6
+// - esrgan-v1-x2plus (upscaling)
+```
+
+### Text Prompts Format
+
+Prompts are arrays with weights:
+
+```typescript
+// WRONG - Simple string
+const body = {
+  prompt: "A cat sitting on a couch",
+};
+
+// CORRECT - Array of weighted prompts
+const body = {
+  text_prompts: [{ text: "A cat sitting on a couch", weight: 1 }],
+};
+
+// Negative prompts use negative weight
+const body = {
+  text_prompts: [
+    { text: "A beautiful sunset over mountains", weight: 1 },
+    { text: "blurry, low quality, distorted", weight: -1 }, // Negative prompt
+  ],
+};
+```
+
+### Image Dimensions
+
+SDXL 1.0 requires specific dimensions:
+
+```typescript
+// Valid dimensions for SDXL 1.0 (must be multiples of 64)
+const validDimensions = [
+  { width: 1024, height: 1024 },
+  { width: 1152, height: 896 },
+  { width: 896, height: 1152 },
+  { width: 1216, height: 832 },
+  { width: 832, height: 1216 },
+  { width: 1344, height: 768 },
+  { width: 768, height: 1344 },
+  { width: 1536, height: 640 },
+  { width: 640, height: 1536 },
+];
+
+// WRONG - Arbitrary dimensions
+const body = { width: 1000, height: 800 };
+
+// CORRECT - Valid dimensions
+const body = { width: 1024, height: 1024 };
+```
+
+### CFG Scale
+
+Controls how closely the image follows the prompt:
+
+```typescript
+// cfg_scale: 0-35 (default 7)
+// Lower = more creative, less prompt adherence
+// Higher = more literal, follows prompt closely
+
+const body = {
+  text_prompts: [{ text: "A cat", weight: 1 }],
+  cfg_scale: 7, // Good balance
+  // cfg_scale: 3  // More creative
+  // cfg_scale: 15 // Very literal
+};
+```
+
+### Content Filtering
+
+Check finishReason for filtered content:
+
+```typescript
+const result = await ctx.integrations.stability.apiRequest(
+  { method: "POST", path: "/v1/generation/...", body: { ... } },
+  { response: GenerationResponseSchema }
+);
+
+result.artifacts.forEach((artifact) => {
+  if (artifact.finishReason === "CONTENT_FILTERED") {
+    console.warn("Image was filtered due to content policy");
+  } else if (artifact.finishReason === "SUCCESS") {
+    // Safe to use
+    const image = artifact.base64;
+  }
+});
+```
+
+### Style Presets
+
+Available style presets for consistent results:
+
+```typescript
+const stylePresets = [
+  "3d-model",
+  "analog-film",
+  "anime",
+  "cinematic",
+  "comic-book",
+  "digital-art",
+  "enhance",
+  "fantasy-art",
+  "isometric",
+  "line-art",
+  "low-poly",
+  "modeling-compound",
+  "neon-punk",
+  "origami",
+  "photographic",
+  "pixel-art",
+  "tile-texture",
+];
+
+const body = {
+  text_prompts: [{ text: "A warrior", weight: 1 }],
+  style_preset: "fantasy-art",
+};
+```
+
+### Base64 Image Handling
+
+Response images are base64 encoded:
+
+```typescript
+// Response contains base64 encoded PNG
+const imageBase64 = result.artifacts[0].base64;
+
+// To save or display, you may need to add data URL prefix
+const dataUrl = `data:image/png;base64,${imageBase64}`;
+
+// For input images (image-to-image), provide raw base64 without prefix
+const inputImage = rawBase64WithoutPrefix;
+```
+
+### Seed for Reproducibility
+
+Use the same seed to reproduce results:
+
+```typescript
+// First generation
+const body = {
+  text_prompts: [{ text: "A dragon", weight: 1 }],
+  seed: 0, // Random seed
+};
+
+// Response includes the seed used
+const usedSeed = result.artifacts[0].seed; // e.g., 1234567890
+
+// Reproduce same image
+const body = {
+  text_prompts: [{ text: "A dragon", weight: 1 }],
+  seed: 1234567890, // Same seed = same image
+};
+```
+
+### Steps vs Quality
+
+More steps = better quality but slower and more credits:
+
+```typescript
+// steps: 10-150 (default 30)
+const body = {
+  text_prompts: [{ text: "...", weight: 1 }],
+  steps: 30, // Good balance
+  // steps: 50 // Higher quality
+  // steps: 15 // Faster, lower quality
+};
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.stability.apiRequest(
+    { method: "POST", path: "/v1/generation/...", body: { ... } },
+    { response: GenerationResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Stability AI API Documentation](https://platform.stability.ai/docs/api-reference)
+- [Text-to-Image](https://platform.stability.ai/docs/api-reference#tag/Text-to-Image)
+- [Image-to-Image](https://platform.stability.ai/docs/api-reference#tag/Image-to-Image)
+- [Upscaling](https://platform.stability.ai/docs/api-reference#tag/Image-to-Image/operation/upscaleImage)

package/src/integrations/stabilityai/client.ts

@@ -0,0 +1,23 @@
+/**
+ * StabilityAI client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * StabilityAI integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { StabilityAIClient } from "./types.js";
+
+/**
+ * Internal implementation of StabilityAIClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * StabilityAI API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class StabilityAIClientImpl
+  extends RestApiIntegrationClient
+  implements StabilityAIClient {
+  // Inherits: name, pluginId, config, executeQuery, apiRequest()
+}

package/src/integrations/stabilityai/index.ts

@@ -0,0 +1,2 @@
+export { StabilityAIClientImpl } from "./client.js";
+export type { StabilityAIClient } from "./types.js";

package/src/integrations/stabilityai/types.ts

@@ -0,0 +1,36 @@
+/**
+ * StabilityAI client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
+
+/**
+ * StabilityAI client for API interactions.
+ *
+ * Provides generic API request method for interacting with StabilityAI's API.
+ * Use apiRequest() to make calls to any StabilityAI API endpoint.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { stabilityai: stabilityai(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.stabilityai
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await stabilityai.apiRequest(
+ *   {
+ *     method: 'POST',
+ *     path: '/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface StabilityAIClient
+  extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}