@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/skills/system/superblocks-api/references/sql-databases.generated.js

@@ -0,0 +1,412 @@
+// Auto-generated from src/ai-service/skills/system/superblocks-api/references/sql-databases.md
+// Do not edit directly - edit the .md file instead
+export const content = `# SQL Database Integrations
+
+Reference documentation for working with SQL databases in Superblocks APIs.
+
+## Supported Databases
+
+- PostgreSQL, MySQL, MariaDB, MSSQL
+- Snowflake, Redshift, BigQuery, Athena
+- Databricks, SingleStore, Lakebase
+- CockroachDB, YugabyteDB, OracleDB
+
+## SQL Block Classes
+
+\`\`\`typescript
+// Available SQL integrations
+import {
+  PostgreSQL,
+  MySQL,
+  MariaDB,
+  MSSQL,
+  Snowflake,
+  Redshift,
+  BigQuery,
+  Athena,
+  Databricks,
+  SingleStore,
+  OracleDB,
+} from "@superblocksteam/library";
+\`\`\`
+
+## Basic Usage
+
+\`\`\`typescript
+new PostgreSQL("get_users", "postgres-integration-id", {
+  statement: "SELECT * FROM users WHERE active = true LIMIT 100",
+});
+\`\`\`
+
+## Parameterized Queries
+
+### SQL Security Priority
+
+**ALWAYS prefer parameterized queries over string interpolation for user input values.**
+
+Use \`parameters: "[var1, var2]"\` with the database-specific SQL placeholders:
+
+| Database                                    | Placeholder Syntax     | Example                                     |
+| ------------------------------------------- | ---------------------- | ------------------------------------------- |
+| PostgreSQL, Redshift, CockroachDB           | \`$1\`, \`$2\`, \`$3\`       | \`WHERE id = $1 AND status = $2\`             |
+| MySQL, MariaDB, Snowflake, BigQuery, Athena | \`?\`, \`?\`, \`?\`          | \`WHERE id = ? AND status = ?\`               |
+| MSSQL                                       | \`@PARAM_1\`, \`@PARAM_2\` | \`WHERE id = @PARAM_1 AND status = @PARAM_2\` |
+| Databricks                                  | \`:PARAM_1\`, \`:PARAM_2\` | \`WHERE id = :PARAM_1 AND status = :PARAM_2\` |
+| OracleDB                                    | \`:1\`, \`:2\`, \`:3\`       | \`WHERE id = :1 AND status = :2\`             |
+
+Only use binding functions for truly dynamic SQL elements like table/column names.
+
+### Parameters Syntax vs Statement Syntax
+
+**Important:** \`parameters\` is a JavaScript expression string that gets evaluated directly. Do NOT use \`\${}\` interpolation or binding functions.
+
+\`\`\`typescript
+// ❌ WRONG - Don't use \${} interpolation in parameters
+parameters: "[\${build_query.output.userId}, \${searchTerm}]";
+
+// ❌ WRONG - Don't use binding functions for parameters
+parameters: ({ build_query }) => JSON.stringify(build_query.output.params);
+
+// ✅ CORRECT - Write expressions directly (they get evaluated as JS)
+parameters: "[build_query.output.userId, searchTerm, limit]";
+
+// ✅ CORRECT - Reference block output array directly
+parameters: "build_query.output.params";
+\`\`\`
+
+This is different from \`statement\`, where binding functions with \`\${}\` ARE used to interpolate values into SQL.
+
+### String Interpolation (Alternative)
+
+For simpler cases, string interpolation also works:
+
+\`\`\`typescript
+// ✅ CORRECT - String interpolation for WHERE clauses
+new PostgreSQL("search", "postgres-id", {
+  statement: ({ searchTerm, limit }: { searchTerm: string; limit: number }) =>
+    \`SELECT * FROM users WHERE name ILIKE '%\${searchTerm}%' LIMIT \${limit}\`,
+});
+
+// ✅ CORRECT - For INSERT statements
+new PostgreSQL("insert_user", "postgres-id", {
+  statement: ({ name, email }: { name: string; email: string }) =>
+    \`INSERT INTO users (name, email) VALUES ('\${name}', '\${email}') RETURNING *\`,
+});
+\`\`\`
+
+### Dynamic SQL with Optional Filters
+
+Use the \`parameters\` array with the "OR NULL" pattern for optional filters:
+
+- \`WHERE (column = $1 OR $1::type IS NULL)\` makes the condition a no-op when parameter is null
+- Cast parameters to their type when checking for NULL (PostgreSQL can't infer types from NULL values)
+- Always pass all parameters, using null for unused filters
+- NEVER interpolate user values directly into SQL strings
+
+## Best Practices
+
+### 1. ONE Query Per Block Rule
+
+Each SQL block (PostgreSQL, Snowflake, MySQL, MicrosoftSql, Databricks) can execute **ONLY ONE SQL query**.
+
+❌ **WRONG - Multiple queries in one block:**
+
+\`\`\`sql
+UPDATE users SET status = 'active';
+DELETE FROM logs WHERE created < '2023-01-01';
+INSERT INTO audit VALUES ('done');
+\`\`\`
+
+✅ **CORRECT - One query per block:**
+
+\`\`\`typescript
+(new PostgreSQL("update_status", "postgres-id", {
+  statement: "UPDATE users SET status = 'active'",
+}),
+  new PostgreSQL("clean_logs", "postgres-id", {
+    statement: "DELETE FROM logs WHERE created < '2023-01-01'",
+  }));
+\`\`\`
+
+### 2. Use Meaningful Block Names
+
+\`\`\`typescript
+// ✅ GOOD
+new PostgreSQL("fetch_active_users", "pg-id", { ... })
+new PostgreSQL("insert_order_item", "pg-id", { ... })
+
+// ❌ BAD
+new PostgreSQL("query1", "pg-id", { ... })
+new PostgreSQL("sql", "pg-id", { ... })
+\`\`\`
+
+### 3. Always Specify Columns
+
+\`\`\`typescript
+// ✅ PREFERRED - Explicit columns
+SELECT id, name, email, created_at FROM users
+
+// ⚠️ AVOID - Select all
+SELECT * FROM users
+\`\`\`
+
+### 4. Always Add Defensive Row Limits
+
+Always include a row limit clause to prevent runaway queries. Use 100 as the default unless user specifies otherwise.
+
+Different SQL dialects have different syntax:
+
+- **MySQL/PostgreSQL/SQLite**: \`LIMIT N\`
+- **SQL Server**: \`SELECT TOP N\`
+- **ANSI SQL (SQL Server, Oracle, DB2)**: \`OFFSET 0 ROWS FETCH NEXT N ROWS ONLY\`
+
+\`\`\`sql
+-- ✅ PostgreSQL/MySQL
+SELECT * FROM orders ORDER BY created_at DESC LIMIT 100;
+
+-- ✅ SQL Server
+SELECT TOP 100 * FROM orders ORDER BY created_at DESC;
+
+-- ✅ ANSI SQL (SQL Server with ORDER BY)
+SELECT * FROM orders ORDER BY created_at DESC OFFSET 0 ROWS FETCH NEXT 100 ROWS ONLY;
+
+-- ❌ Avoid unlimited queries
+SELECT * FROM orders ORDER BY created_at DESC;  -- Can timeout or crash
+\`\`\`
+
+### 5. Sort, Don't Filter by Date (Default)
+
+Do NOT add automatic date filters (e.g., "last 90 days") unless the user explicitly requests them. This is a common cause of unexpected empty SQL results.
+
+\`\`\`sql
+-- ✅ Default approach
+SELECT * FROM orders ORDER BY created_at DESC LIMIT 100;
+
+-- ❌ Avoid automatic filtering
+SELECT * FROM orders WHERE created_at >= CURRENT_DATE - INTERVAL '90 days';  -- Can return empty results
+\`\`\`
+
+Only add date WHERE clauses when users explicitly ask for time-based filtering.
+
+### 6. Handle NULL Values
+
+\`\`\`typescript
+// ✅ Use COALESCE for default values
+SELECT COALESCE(description, 'No description') as description FROM products
+
+// ✅ Use IS NULL / IS NOT NULL
+SELECT * FROM users WHERE deleted_at IS NULL
+\`\`\`
+
+## Database-Specific Notes
+
+### PostgreSQL
+
+\`\`\`typescript
+// Array operations
+new PostgreSQL("array_query", "pg-id", {
+  statement: ({ tags }: { tags: string[] }) =>
+    \`SELECT * FROM posts WHERE tags && ARRAY[\${tags.map((t) => \`'\${t}'\`).join(",")}]\`,
+});
+
+// JSON operations
+new PostgreSQL("json_query", "pg-id", {
+  statement: "SELECT data->>'name' as name FROM json_data",
+});
+\`\`\`
+
+- Use schema-qualified names: \`schema.table\` or \`"schema"."table"\`
+- Case sensitivity: Unquoted identifiers are lowercase
+- Use \`::type\` for type casting
+
+#### Custom Type Casts (Enums, Composite Types)
+
+**When casting parameters, always use the actual column type — not \`text\` or other generic types.**
+
+PostgreSQL columns can use custom types such as enums (\`billing_plan_enum\`, \`order_status_enum\`) or composite types. When \`grepMetadata\` reports a column type that is not a built-in type, you **must** use that exact type in SQL casts. Casting to \`text\` or \`text[]\` will fail with an \`operator does not exist\` error.
+
+**Rule:** Before writing any \`::type\` cast, check the actual column type via \`grepMetadata\`. If the column type is a custom type (e.g., \`billing_plan_enum\`), cast to that type, not \`text\`.
+
+\`\`\`sql
+-- grepMetadata shows: billing.plan has type "billing_plan_enum"
+
+-- ✅ CORRECT - Cast to the actual column type
+WHERE bf.plan = ANY($3::billing_plan_enum[])
+
+-- ❌ WRONG - Casting to text[] for an enum column
+WHERE bf.plan = ANY($3::text[])
+-- ERROR: operator does not exist: billing_plan_enum = text
+\`\`\`
+
+This applies to all custom types, not just enums:
+
+\`\`\`sql
+-- Column type is "order_status_enum"
+WHERE o.status = ANY($1::order_status_enum[])  -- ✅
+WHERE o.status = ANY($1::text[])               -- ❌
+
+-- Column type is "priority_level" (custom enum)
+WHERE t.priority = $2::priority_level           -- ✅
+WHERE t.priority = $2::text                     -- ❌
+\`\`\`
+
+**Why this matters:** PostgreSQL does not implicitly cast between custom types and \`text\`. Even though enum values look like strings and \`SELECT DISTINCT\` returns them as plain strings, the column's actual type must be used in parameter casts. The \`grepMetadata\` tool returns the real type name — always use it.
+
+### Snowflake
+
+\`\`\`typescript
+// Use QUALIFY for window function filtering
+new Snowflake("ranked_query", "snowflake-id", {
+  statement: \`
+    SELECT *, ROW_NUMBER() OVER (PARTITION BY category ORDER BY sales DESC) as rank
+    FROM products
+    QUALIFY rank <= 3
+  \`,
+});
+\`\`\`
+
+**Snowflake Two-Part Naming:** Snowflake uses \`schema.table\`
+
+When you see Snowflake metadata where tables have a \`schema\` property, **you MUST qualify table names**:
+
+\`\`\`sql
+-- If table has schema property "MASTERDATA"
+SELECT * FROM MASTERDATA.PRODUCTLINE  -- ✅ Fully qualified
+SELECT * FROM PRODUCTLINE             -- ❌ Will fail if no default schema
+\`\`\`
+
+**Rule**: If a table object has a non-empty \`schema\` property, use \`{schema}.{name}\` format in your SQL queries.
+
+### Databricks
+
+**Databricks Three-Part Naming:** Databricks uses \`catalog.schema.table\`
+
+When you see Databricks metadata like:
+
+- \`uber.default.orders\` - Use the FULL path: \`uber.default.orders\`
+- \`production.analytics.users\` - Use: \`production.analytics.users\`
+
+\`\`\`sql
+-- Metadata shows: uber.default.orders
+SELECT * FROM uber.default.orders     -- ✅ Full path
+SELECT * FROM uber.orders            -- ❌ Missing schema part
+SELECT * FROM orders                 -- ❌ Missing catalog and schema
+\`\`\`
+
+**Note:** The word "default" in Databricks paths is NOT optional - it's the actual schema name. Always include all three parts exactly as shown in the metadata.
+
+### BigQuery
+
+\`\`\`typescript
+// Use backticks for table names, ? placeholders for parameters
+new BigQuery("get_events", "bq-id", {
+  sqlBody:
+    "SELECT * FROM \\\`project.dataset.events\\\` WHERE status = ? LIMIT 100",
+  parameters: "[statusFilter]",
+});
+
+// Without parameters
+new BigQuery("get_all", "bq-id", {
+  sqlBody: "SELECT * FROM \\\`project.dataset.table\\\` LIMIT 100",
+});
+\`\`\`
+
+## Common Patterns
+
+### Pagination
+
+\`\`\`typescript
+new PostgreSQL("paginated_fetch", "pg-id", {
+  statement: ({ page, pageSize }: { page: number; pageSize: number }) =>
+    \`SELECT * FROM orders ORDER BY created_at DESC LIMIT \${pageSize} OFFSET \${(page - 1) * pageSize}\`,
+});
+\`\`\`
+
+### Search with Multiple Conditions
+
+\`\`\`typescript
+new PostgreSQL("advanced_search", "pg-id", {
+  statement: ({
+    name,
+    status,
+    minAmount,
+  }: {
+    name?: string;
+    status?: string;
+    minAmount?: number;
+  }) => {
+    const conditions = ["1=1"];
+    if (name) conditions.push(\`name ILIKE '%\${name}%'\`);
+    if (status) conditions.push(\`status = '\${status}'\`);
+    if (minAmount !== undefined) conditions.push(\`amount >= \${minAmount}\`);
+    return \`SELECT * FROM orders WHERE \${conditions.join(" AND ")} LIMIT 100\`;
+  },
+});
+\`\`\`
+
+### Batch Insert
+
+\`\`\`typescript
+new PostgreSQL("batch_insert", "pg-id", {
+  statement: ({ items }: { items: Array<{ name: string; value: number }> }) => {
+    const values = items
+      .map((item) => \`('\${item.name}', \${item.value})\`)
+      .join(", ");
+    return \`INSERT INTO items (name, value) VALUES \${values} RETURNING *\`;
+  },
+});
+\`\`\`
+
+### Upsert (Insert or Update)
+
+\`\`\`typescript
+// PostgreSQL
+new PostgreSQL("upsert_user", "pg-id", {
+  statement: ({
+    id,
+    name,
+    email,
+  }: {
+    id: string;
+    name: string;
+    email: string;
+  }) =>
+    \`INSERT INTO users (id, name, email) 
+     VALUES ('\${id}', '\${name}', '\${email}')
+     ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, email = EXCLUDED.email
+     RETURNING *\`,
+});
+\`\`\`
+
+## Error Handling
+
+SQL errors are returned in the block's output. Common errors:
+
+- Syntax errors in SQL
+- Table/column doesn't exist
+- Constraint violations
+- Connection timeouts
+
+For critical operations, wrap in TryCatch:
+
+\`\`\`typescript
+new TryCatch("safe_delete", {
+  try: [
+    new PostgreSQL("delete_record", "pg-id", {
+      statement: ({ id }: { id: string }) =>
+        \`DELETE FROM sensitive_data WHERE id = '\${id}'\`,
+    }),
+  ],
+  catch: [
+    new JavaScript("log_error", {
+      fn: ({ deleteError }) => ({
+        success: false,
+        error: deleteError.value.message,
+      }),
+    }),
+  ],
+  variables: { error: "deleteError" },
+});
+\`\`\`
+`;
+//# sourceMappingURL=sql-databases.generated.js.map

package/dist/ai-service/skills/system/superblocks-api/references/sql-databases.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-databases.generated.js","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-api/references/sql-databases.generated.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwZtB,CAAC"}

package/dist/ai-service/skills/system/superblocks-api/skill.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const content = "---\nname: superblocks-api\ndescription: |\n  Build backend APIs using Superblocks workflow blocks.\n  Use when creating or modifying APIs, working with integrations, explaining API patterns, or troubleshooting API issues.\nreadOnly: true\nmetadata:\n  author: superblocks\n  version: \"1.0\"\n---\n\n# Superblocks API Development\n\nThis skill covers building backend APIs using Superblocks workflow blocks, integrations, and control flow patterns.\n\n## Mental Model\n\nAPIs in Superblocks are backend logic blocks that run in a secure server environment. They:\n\n- Execute integrations (database queries, API calls, etc.)\n- Process data with JavaScript or Python\n- Return data to the frontend\n- **Cannot** directly modify UI state\n\n**Superblocks APIs are NOT traditional backend services.** They are frontend-coupled workflow builders that:\n\n- Build declarative workflows using a chain of blocks\n- Receive input parameters passed from the frontend\n- Are visualized in the Superblocks editor\n\n## API File Structure\n\n```typescript\n// Path: /apis/apiName.ts\n\n// \u2705 ALWAYS import required types from the library\nimport {\n  Api,\n  JavaScript,\n  Python,\n  PostgreSQL,\n  Snowflake,\n  RestApi,\n  OpenApi,\n  GraphQL,\n  S3,\n  Email,\n  Conditional,\n  TryCatch,\n  Loop,\n  Parallel,\n  Variables,\n  Throw,\n  Return,\n  Break,\n} from \"@superblocksteam/library\";\n\n// \u274C NEVER define constants here - they won't be serialized!\n\n// \u2705 ALL logic must be inside new Api()\nexport default new Api(\"apiName\", [\n  // Workflow blocks here\n]);\n```\n\n**\uD83D\uDEA8 CRITICAL:** Only code inside `new Api()` is serialized. Constants/helpers defined outside cause `ReferenceError` at runtime.\n\n## Getting Integration-Specific Types\n\n**BEFORE building APIs with integrations, call the `getIntegrationTypes` tool** with the integration IDs you plan to use.\n\nThis tool provides dynamic, integration-specific information that cannot be included in skill files:\n\n- TypeScript class definitions (constructor signatures, config options, methods)\n- Integration-specific examples and patterns\n- SQL parameterized query syntax (for database integrations, if supported)\n\n**Example:**\n\n```\ngetIntegrationTypes({ integrationIds: [\"postgres-abc123\", \"snowflake-xyz789\"] })\n```\n\nThe core patterns in this skill file (scoping rules, control flow, best practices) apply to ALL integrations.\nThe `getIntegrationTypes` tool provides the specific TypeScript types for the integration classes you're using.\n\n## \uD83D\uDD0D Integration Exploration Workflow (CRITICAL)\n\nWhen exploring integrations and data sources, use `grepMetadata` to understand schema before querying:\n\n### 1. Start with metadata exploration\n\nUse `grepMetadata` to understand:\n\n- What tables/endpoints exist\n- Schema structure and\n- Available fields and data types\n\n**\uD83D\uDCA1 KEY PRINCIPLE:** For \"tell me about the data\" questions, metadata exploration is usually sufficient and more efficient.\n\n### 2. NEVER use SQL/API queries for metadata exploration\n\n\u274C **WRONG**: `SHOW COLUMNS FROM users`, `DESCRIBE table`, `SELECT * FROM INFORMATION_SCHEMA`\n\u2705 **CORRECT**: `grepMetadata({ grepPattern: \"\\\\.columns\\\\[\\\\d+\\\\]\\\\.name\" })` to find all columns\n\n### 3. Database vs OpenAPI key formats\n\n**DATABASE integrations** (Postgres, MySQL, Snowflake, Databricks):\n\n- Use **numeric array indices**: `[0]`, `[1]`, `[2]`, etc.\n- Pattern: Use `\\\\d+` to match any number\n- Structure: All databases use `json.dbSchema.schemas[]` and `json.dbSchema.tables[]`\n- **\u26A0\uFE0F CRITICAL**: It's `dbSchema` (NOT `schema`!) - the field name is `dbSchema`\n- Examples:\n  - \u2705 `\"\\\\.dbSchema\\\\.schemas\\\\[\\\\d+\\\\]\\\\.name\"` - Find schema names\n  - \u2705 `\"\\\\.tables\\\\[\\\\d+\\\\]\\\\.name = \\\\\".*user.*\\\\\"\"` - Find tables\n  - \u274C `\"\\\\.schema\\\\.tables\"` - WRONG! It's `dbSchema` not `schema`\n\n**OPENAPI integrations** (REST APIs with OpenAPI specs):\n\n- Use **string object keys**: `[\"/users\"]`, `[\"/repos\"]`\n- Pattern: Use `.*` to match any key (NOT `\\\\d+`!)\n- Examples:\n  - \u2705 `\"\\\\.paths\\\\[\\\\\".*repos.*\\\\\"\\\\]\"` - Find paths with \"repos\"\n  - \u274C `\"\\\\.paths\\\\[\\\\d+\\\\]\"` - WRONG! OpenAPI doesn't use numeric indices\n\n### 4. REST API vs OpenAPI Selection\n\n**\uD83D\uDEA8 CRITICAL: When working with REST API integrations:**\n\n1. ALWAYS call `grepMetadata` first to determine if the REST API is OpenAPI-backed\n2. If metadata shows it's an OpenAPI-backed API, you MUST use the `OpenApi` class with `openapi.path`\n3. Only use `RestApi` class for non-OpenAPI REST integrations\n\n## Core Type Definitions\n\n```typescript\nexport type JsonValue = any;\nexport type State = { [key: string]: JsonValue };\nexport type Binding<T> = T | ((state: State) => T);\n\n// Control Flow Blocks\nexport declare class Conditional extends Block {\n  constructor(\n    name: string,\n    config: {\n      if: { when: Binding<boolean>; then: Block[] };\n      elif?: { when: Binding<boolean>; then: Block[] }[];\n      else?: Block[];\n    },\n  );\n}\n\nexport declare class Loop extends Block {\n  constructor(\n    name: string,\n    config:\n      | {\n          type?: \"TYPE_FOREACH\";\n          over: Binding<JsonValue[]>;\n          variables: { item: string; index: string };\n          blocks: Block[];\n        }\n      | { type: \"TYPE_WHILE\"; condition: Binding<boolean>; blocks: Block[] },\n  );\n}\n\nexport declare class Parallel extends Block {\n  constructor(\n    name: string,\n    config:\n      | { mode: \"dynamic\"; over: Binding<JsonValue[]>; blocks: Block[] }\n      | { mode: \"static\"; paths: Record<string, Block[]> },\n  );\n}\n\nexport declare class Variables extends Block {\n  constructor(\n    name: string,\n    variables: { key: string; value: Binding<JsonValue> }[],\n  );\n}\n\nexport declare class TryCatch extends Block {\n  constructor(\n    name: string,\n    config: {\n      try: Block[];\n      catch: Block[];\n      finally?: Block[];\n      variables: { error: string };\n    },\n  );\n}\n\nexport declare class Throw extends Block {\n  constructor(name: string, config: { error: Binding<JsonValue> });\n}\n\nexport declare class Return extends Block {\n  constructor(name: string, config: { data: Binding<JsonValue> });\n}\n\nexport declare class Break extends Block {\n  constructor(name: string, config: { condition: Binding<JsonValue> });\n}\n\n// API Authorization\nexport type Authorization =\n  | { type: \"AUTHORIZATION_TYPE_APP_USERS\" }\n  | { type: \"AUTHORIZATION_TYPE_JS_EXPRESSION\"; expression: Binding<boolean> };\n\nexport declare class Api {\n  constructor(name: string, blocks?: Block[], authorization?: Authorization);\n}\n```\n\n## Block Output Scoping Rules\n\n**CRITICAL: Blocks can only access outputs from specific scopes.**\n\n### What blocks CAN access:\n\n1. **Previous sibling blocks** at the same level (executed before them)\n2. **ALL ancestor block outputs** (parent, grandparent, etc.)\n3. **Parent control flow variables** (e.g., `item` and `index` in Loop)\n4. **Control flow block outputs** (equals output of their last child block)\n\n### What blocks CANNOT access:\n\n- \u274C Outputs from blocks nested inside other control flow blocks\n- \u274C Outputs from blocks in other Conditional branches\n- \u274C Outputs from blocks that come after them\n\n### Variable Access Patterns\n\n```typescript\n// \u2705 CORRECT: Destructure variables/blocks you need\nwhen: ({ hasMore }) => !hasMore.value;\nover: ({ items }) => items.output;\ncondition: ({ counter }) => counter.value < 10;\n\n// \u2705 Multiple variables in one function\nfn: ({ results, page, hasMore }) => {\n  results.set([...results.value, ...newItems]);\n  page.set(page.value + 1);\n};\n\n// \u274C WRONG: Single param pattern causes runtime error!\nwhen: (p) => !p.hasMore.value; // TypeError!\n```\n\n**Access patterns by type:**\n\n- **API Inputs**: Access directly (no `.value`)\n- **Step Outputs**: Use `.output`\n- **Loop Variables**: Use `.value`\n- **TryCatch Error Variables**: Use `.value`\n- **GraphQL Outputs**: Use `.output.data` (GraphQL returns `{ data: {...}, errors?: [...] }`)\n\n## Input Discovery Rules\n\n**You do NOT need to explicitly declare API inputs.** They are automatically discovered when:\n\n1. Destructured in block functions but not defined elsewhere\n2. Referenced but not produced by any previous block\n\n### \uD83D\uDEA8 CRITICAL: Always Type Your Input Parameters\n\n```typescript\n// \u2705 CORRECT - Typed parameters\nnew JavaScript(\"validate_email\", {\n  fn: ({ email }: { email: string }) => email.includes(\"@\"),\n});\n\nnew PostgreSQL(\"search_users\", \"postgres-id\", {\n  statement: ({ searchTerm, limit }: { searchTerm: string; limit: number }) =>\n    `SELECT * FROM users WHERE name ILIKE '%${searchTerm}%' LIMIT ${limit}`,\n});\n\n// \u274C WRONG - Untyped parameters\nnew JavaScript(\"validate_email\", {\n  fn: ({ email }) => email.includes(\"@\"), // \u274C No type!\n});\n```\n\n## SQL Best Practices\n\n### 1. \uD83D\uDEA8 ALWAYS Add Defensive Row Limits\n\n**Every SELECT query MUST include a row limit to prevent timeouts and crashes.** Always include a row limit clause to prevent runaway queries. Use 100 as the default unless user specifies otherwise.\n\nDifferent SQL dialects have different syntax:\n\n| Database                                                  | Syntax                    | Example                                                                  |\n| --------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------ |\n| PostgreSQL, MySQL, MariaDB, Snowflake, Redshift, BigQuery | `LIMIT N`                 | `SELECT * FROM users LIMIT 100`                                          |\n| SQL Server (MSSQL)                                        | `SELECT TOP N`            | `SELECT TOP 100 * FROM users`                                            |\n| SQL Server with ORDER BY                                  | `OFFSET...FETCH`          | `SELECT * FROM users ORDER BY id OFFSET 0 ROWS FETCH NEXT 100 ROWS ONLY` |\n| Oracle                                                    | `FETCH FIRST N ROWS ONLY` | `SELECT * FROM users FETCH FIRST 100 ROWS ONLY`                          |\n\n**Examples:**\n\n```sql\n-- \u2705 PostgreSQL/MySQL/Snowflake\nSELECT * FROM orders ORDER BY created_at DESC LIMIT 100;\n\n-- \u2705 SQL Server\nSELECT TOP 100 * FROM orders ORDER BY created_at DESC;\n\n-- \u2705 SQL Server with OFFSET (for pagination)\nSELECT * FROM orders ORDER BY created_at DESC OFFSET 0 ROWS FETCH NEXT 100 ROWS ONLY;\n\n-- \u274C WRONG - No limit! Can timeout or crash on large tables\nSELECT * FROM orders ORDER BY created_at DESC;\n```\n\n**Why this matters:**\n\n- Tables can have millions of rows\n- Queries without limits can timeout (30+ seconds)\n- Large result sets crash the browser/app\n- Even \"small\" tables can grow unexpectedly\n\n### 2. ONE Query Per Block Rule\n\nEach SQL block can execute **ONLY ONE SQL query**.\n\n\u274C **WRONG:**\n\n```sql\nUPDATE users SET status = 'active';\nDELETE FROM logs WHERE created < '2023-01-01';\n```\n\n\u2705 **CORRECT:**\n\n```typescript\n(new PostgreSQL(\"update_status\", \"pg-id\", {\n  statement: \"UPDATE users SET status = 'active'\",\n}),\n  new PostgreSQL(\"clean_logs\", \"pg-id\", {\n    statement: \"DELETE FROM logs WHERE created < '2023-01-01'\",\n  }));\n```\n\n### 3. Sort, Don't Filter by Date (Default)\n\nDo NOT add automatic date filters unless explicitly requested.\n\n\u2705 **Default:** `SELECT * FROM orders ORDER BY created_at DESC LIMIT 100`\n\u274C **Avoid:** `SELECT * FROM orders WHERE created_at >= CURRENT_DATE - INTERVAL '90 days'`\n\n### 4. Always Specify Columns When Possible\n\n```sql\n-- \u2705 PREFERRED - Explicit columns\nSELECT id, name, email, created_at FROM users LIMIT 100\n\n-- \u26A0\uFE0F AVOID when possible - Select all\nSELECT * FROM users LIMIT 100\n```\n\n## Database Naming Conventions\n\n### Databricks Three-Part Naming\n\nDatabricks uses: `catalog.schema.table`\n\n```sql\n-- Metadata shows: uber.default.orders\nSELECT * FROM uber.default.orders LIMIT 100     -- \u2705 Full path + LIMIT\nSELECT * FROM uber.orders LIMIT 100            -- \u274C Missing schema part\n```\n\n**Note:** The word \"default\" in Databricks paths is NOT optional - it's the actual schema name.\n\n### Snowflake Two-Part Naming\n\nSnowflake uses: `schema.table`\n\n```sql\n-- If table has schema property \"MASTERDATA\"\nSELECT * FROM MASTERDATA.PRODUCTLINE LIMIT 100  -- \u2705 Fully qualified + LIMIT\nSELECT * FROM PRODUCTLINE LIMIT 100             -- \u274C Will fail if no default schema\n```\n\n## Runtime Safety and Defensive Coding\n\n- Use optional chaining and nullish coalescing when producing outputs\n- For REST/OpenAPI/GraphQL responses, treat non-required fields as optional\n- Default to empty arrays/objects when inputs are absent\n\n```typescript\n// \u2705 Defensive transformation\nnew JavaScript(\"normalize_users\", {\n  fn: ({ fetch_users }) =>\n    (Array.isArray(fetch_users.output) ? fetch_users.output : []).map((u) => ({\n      id: u.id,\n      name: (u.name ?? \"Unknown\").toString(),\n    })),\n});\n```\n\n## Common API Patterns\n\n### Simple Data Retrieval\n\n```typescript\nexport default new Api(\"getUsersApi\", [\n  new PostgreSQL(\"fetch_users\", \"postgres-id\", {\n    // \u2705 ALWAYS include LIMIT clause to prevent timeouts\n    statement:\n      \"SELECT id, name, email FROM users ORDER BY created_at DESC LIMIT 100\",\n  }),\n]);\n\n// With dynamic limit from input\nexport default new Api(\"getUsersWithLimitApi\", [\n  new PostgreSQL(\"fetch_users\", \"postgres-id\", {\n    statement: ({ pageSize }: { pageSize?: number }) =>\n      `SELECT id, name, email FROM users ORDER BY created_at DESC LIMIT ${pageSize || 100}`,\n  }),\n]);\n```\n\n### Input Validation + Processing\n\n```typescript\nexport default new Api(\"createUserApi\", [\n  new Conditional(\"validate_inputs\", {\n    if: {\n      when: ({\n        FirstNameInput,\n        EmailInput,\n      }: {\n        FirstNameInput: string;\n        EmailInput: string;\n      }) => !FirstNameInput || !EmailInput,\n      then: [\n        new Throw(\"validation_error\", {\n          error: \"First name and email are required\",\n        }),\n      ],\n    },\n  }),\n  new JavaScript(\"create_user\", {\n    fn: ({\n      FirstNameInput,\n      EmailInput,\n    }: {\n      FirstNameInput: string;\n      EmailInput: string;\n    }) => ({\n      id: Math.floor(Math.random() * 1000),\n      name: FirstNameInput,\n      email: EmailInput,\n      created_at: new Date().toISOString(),\n    }),\n  }),\n]);\n```\n\n### Loop with Data Processing\n\n```typescript\nexport default new Api(\"processOrdersApi\", [\n  new JavaScript(\"get_orders\", {\n    fn: () => [\n      { id: 1, status: \"pending\", amount: 100 },\n      { id: 2, status: \"pending\", amount: 200 },\n    ],\n  }),\n  new Loop(\"process_each_order\", {\n    over: ({ get_orders }) => get_orders.output,\n    variables: { item: \"order\", index: \"i\" },\n    blocks: [\n      new JavaScript(\"calculate_tax\", {\n        fn: ({ order, i }) => ({\n          ...order.value,\n          tax: order.value.amount * 0.1,\n          total: order.value.amount * 1.1,\n          position: i.value,\n        }),\n      }),\n    ],\n  }),\n]);\n```\n\n### Variables for Pagination State\n\n```typescript\nexport default new Api(\"paginatedFetchApi\", [\n  new Variables(\"pagination_state\", [\n    { key: \"allResults\", value: () => [] },\n    { key: \"cursor\", value: () => null },\n    { key: \"hasMore\", value: () => true },\n  ]),\n\n  new Loop(\"fetch_all_pages\", {\n    type: \"TYPE_FOREACH\",\n    over: () => [...Array(100).keys()], // Max iterations safety\n    variables: { item: \"_\", index: \"i\" },\n    blocks: [\n      new Conditional(\"check_done\", {\n        if: {\n          when: ({ hasMore }) => !hasMore.value,\n          then: [new Break(\"exit_loop\", { condition: () => true })],\n        },\n      }),\n      new RestApi(\"fetch_page\", \"rest-api-id\", {\n        method: \"GET\",\n        url: ({ cursor }) =>\n          `https://api.example.com/items${cursor.value ? `?cursor=${cursor.value}` : \"\"}`,\n      }),\n      new JavaScript(\"accumulate\", {\n        fn: ({ fetch_page, allResults, cursor, hasMore }) => {\n          const response = fetch_page.output;\n          allResults.set([...allResults.value, ...response.items]);\n          cursor.set(response.nextCursor);\n          hasMore.set(response.hasMore);\n          return allResults.value;\n        },\n      }),\n    ],\n  }),\n\n  new JavaScript(\"return_results\", {\n    fn: ({ allResults }) => allResults.value,\n  }),\n]);\n```\n\n### File Uploads to S3/GCS\n\n**Frontend wraps files in `{ files: [...] }` format:**\n\n```typescript\nconst response = await runUploadApi({ userFiles: { files: selectedFiles } });\n```\n\n**Backend API - pass files directly:**\n\n```typescript\nexport default new Api(\"uploadFilesApi\", [\n  new S3(\"upload_files\", \"your-s3-integration-id\", {\n    action: \"UPLOAD_MULTIPLE_OBJECTS\",\n    resource: ({ bucketName }) => bucketName,\n    fileObjects: ({ userFiles }) => userFiles.files, // Direct pass-through\n  }),\n]);\n```\n\n### Reading File Content in JavaScript\n\n```typescript\nnew JavaScript(\"parse_csv\", {\n  fn: async ({ csvFile }) => {\n    const file = csvFile.files[0];\n    const content = await file.readContentsAsync();\n    const headers = content\n      .split(\"\\n\")[0]\n      .split(\",\")\n      .map((h) => h.trim());\n    return { fileName: file.name, headers };\n  },\n});\n```\n\n## Error Handling Guidelines\n\n**IMPORTANT: Do NOT use TryCatch blocks by default.** Only use when truly necessary.\n\n### \u274C DO NOT use TryCatch for:\n\n- Standard database queries\n- Simple data transformations\n\n### \u2705 DO use TryCatch when:\n\n- User explicitly requests error handling\n- Continuing execution after failure is business-critical\n- Partial failure recovery in loops\n- Graceful degradation with fallback data\n\n## Error Recovery Strategies\n\nWhen you encounter errors while building APIs:\n\n### Read Error Messages Carefully\n\nError messages contain specific guidance on how to fix the problem. Pay close attention to:\n\n- What operation failed (compilation, validation, execution)\n- Suggestions for how to resolve the issue\n- Whether metadata is missing\n\n### When to Check Integration Metadata\n\nIf you encounter errors mentioning:\n\n- \"unknown column\", \"table not found\", \"invalid field\"\n- \"check integration metadata\"\n- Integration type mismatches\n\nYou MUST call `grepMetadata` to get the correct schema/table structure before retrying.\n\n## Loop Control\n\n### Loop Types\n\n- **TYPE_FOREACH** (default): Iterates over an array using `over`. Provides `item` and `index` variables.\n- **TYPE_WHILE**: Repeats while `condition` is true. Provides only `index` variable.\n\n**Breaking out of loops:**\n\n```typescript\nnew Loop(\"process_until_complete\", {\n  over: ({ items }) => items.output,\n  variables: { item: \"current\", index: \"i\" },\n  blocks: [\n    new Conditional(\"check_stop_condition\", {\n      if: {\n        when: ({ current }) => current.value.status === \"complete\",\n        then: [\n          new Break(\"exit_loop\", { condition: () => true }), // \u2705 Only way to exit\n        ],\n      },\n    }),\n    new JavaScript(\"process_item\", {\n      fn: ({ current, i }) => ({\n        processed: current.value,\n        position: i.value,\n      }),\n    }),\n  ],\n});\n```\n\n## Response Interface Guidelines\n\nThe `responseInterface` describes what external code gets from `apiName.response`. Internal blocks/steps are NOT visible externally.\n\n### Direct Response Types\n\n\u2705 **CORRECT**: Direct array response\n\n```typescript\ninterface GetUsersApiResponse {\n  id: number;\n  name: string;\n  email: string;\n}\n[];\n```\n\n\u2705 **CORRECT**: Direct data structure\n\n```typescript\ninterface GetOrdersApiResponse {\n  orders: Order[];\n  totalCount: number;\n}\n```\n\n\u274C **WRONG**: Exposing internal steps\n\n```typescript\ninterface GetOrdersApiResponse {\n  fetchStep: { output: Order[] }; // \u274C Steps are internal\n  countStep: { output: number }; // \u274C Not visible outside\n}\n```\n\n### Type Safety for API Response Interfaces\n\n**CRITICAL: When defining response interfaces, consider runtime reality, not just happy-path data.**\n\nWhen uncertain if an API field will always be present, mark it optional:\n\n```typescript\n// \u2705 CORRECT - Accounts for real-world API behavior\ninterface GitHubPRResponse {\n  id: number;\n  title: string;\n  user?: {\n    // \u2190 Optional, can be null for deleted users\n    login: string;\n    avatar_url: string;\n  } | null;\n  labels?: Label[]; // \u2190 Optional, might be omitted in response\n}\n```\n\nMark fields optional when:\n\n1. **User/account references** - Can be null for deleted/deactivated accounts\n2. **Nested objects** - May be omitted in partial responses\n3. **Third-party APIs** - GitHub, Stripe, etc. often have nullable fields\n4. **Loading states** - Data may not be available during initial render\n5. **Uncertain API behavior** - When in doubt, mark optional\n\n## Permissions (Global Object)\n\nFor user-specific operations, use the `Global` object (injected by backend):\n\n```typescript\ntype Global = {\n  user: {\n    email: string;\n    username: string;\n    id: string;\n    name: string;\n    groups: Group[];\n  };\n};\n```\n\n### Groups Check Pattern\n\n```typescript\nnew JavaScript(\"check_groups\", {\n  fn: ({ Global }) => {\n    const isFieldEngUser = Global.groups.some(\n      (group) => group.name === \"FieldEngineer\",\n    );\n    if (isFieldEngUser) {\n      // Perform actions for FieldEngineer\n    } else {\n      // Perform actions for non-FieldEngineer\n    }\n    return {\n      isAdmin: Global.groups.some((g) => g.name === \"Admin\"),\n      userId: Global.user.id,\n    };\n  },\n});\n```\n\n**NEVER rely on frontend data for security-critical operations.**\n\n## Critical Mistakes to Avoid\n\n### 1. Defining Constants Outside the API\n\n```typescript\n// \u274C WRONG - Not serialized!\nconst MAX_BATCHES = 100;\nexport default new Api(\"MyApi\", [\n  new Loop(\"loop\", {\n    condition: ({ count }) => count.value < MAX_BATCHES,  // ReferenceError!\n    blocks: [...]\n  })\n]);\n\n// \u2705 CORRECT - Use Variables block\nexport default new Api(\"MyApi\", [\n  new Variables(\"state\", [\n    { key: \"maxBatches\", value: () => 100 },\n  ]),\n  new Loop(\"loop\", {\n    condition: ({ count, maxBatches }) => count.value < maxBatches.value,\n    blocks: [...]\n  })\n]);\n```\n\n### 2. Wrong Language for Integration Type\n\n```typescript\n// \u274C WRONG - JavaScript in SQL block\nnew PostgreSQL(\"bad\", \"id\", {\n  statement: ({ userId }) => `SELECT * FROM users WHERE id = ${userId}`,\n});\n\n// \u274C WRONG - SQL in JavaScript block\nnew JavaScript(\"bad\", {\n  fn: \"SELECT * FROM users\", // This is SQL!\n});\n\n// \u2705 CORRECT\nnew PostgreSQL(\"good\", \"id\", {\n  statement: ({ userId }: { userId: string }) =>\n    `SELECT * FROM users WHERE id = '${userId}' LIMIT 1`,\n});\n```\n\n### 3. Fake Integration IDs\n\n```typescript\n// \u274C NEVER make up integration IDs\nnew PostgreSQL(\"query\", \"fake-postgres-id\", { ... })\n```\n\n### 4. APIs Cannot Set Frontend State\n\n```typescript\n// \u274C WRONG - Cannot set state in APIs\nnew JavaScript(\"update\", {\n  fn: ({ userData }) => {\n    userNameVar.value = userData.name; // \u274C Cannot do this!\n    return userData;\n  },\n});\n\n// \u2705 CORRECT - Return data, frontend handles state\nnew JavaScript(\"update\", {\n  fn: ({ userData }) => ({\n    ...userData,\n    fullName: `${userData.firstName} ${userData.lastName}`,\n  }),\n});\n```\n\n### 5. Return Blocks Cannot Contain Statements\n\n```typescript\n// \u2705 CORRECT - Returns data immediately\nnew Return(\"test_return\", {\n  data: (({ records }) => ({ records, totalCount: records.length }))(),\n});\n\n// \u274C WRONG - Contains statements\nnew Return(\"test_return\", {\n  data: (({ records }) => {\n    const totalCount = records.length; // \u274C Statement not allowed\n    return { records, totalCount };\n  })(),\n});\n```\n\n### 6. Missing LIMIT Clause (Causes Timeouts)\n\n```typescript\n// \u274C WRONG - No LIMIT, can timeout or crash\nnew PostgreSQL(\"fetch_all\", \"pg-id\", {\n  statement: \"SELECT * FROM orders\",\n});\n\nnew Snowflake(\"fetch_data\", \"sf-id\", {\n  statement: \"SELECT * FROM SCHEMA.LARGE_TABLE ORDER BY date\",\n});\n\n// \u2705 CORRECT - Always include LIMIT\nnew PostgreSQL(\"fetch_orders\", \"pg-id\", {\n  statement: \"SELECT * FROM orders ORDER BY created_at DESC LIMIT 100\",\n});\n\nnew Snowflake(\"fetch_data\", \"sf-id\", {\n  statement: \"SELECT * FROM SCHEMA.LARGE_TABLE ORDER BY date LIMIT 100\",\n});\n\n// \u2705 CORRECT - SQL Server syntax\nnew MicrosoftSql(\"fetch_orders\", \"mssql-id\", {\n  statement: \"SELECT TOP 100 * FROM orders ORDER BY created_at DESC\",\n});\n```\n\n## When to Load References\n\nFor integration-specific guidance, load the appropriate reference file:\n\n- SQL databases (PostgreSQL, MySQL, Snowflake, etc.) \u2192 `references/sql-databases.md`\n- REST APIs and OpenAPI \u2192 `references/rest-apis.md`\n- GraphQL \u2192 `references/graphql.md`\n- JavaScript/Python blocks \u2192 `references/code-blocks.md`\n\n## API Checklist\n\nWhen creating APIs:\n\n1. \u2705 Correct language for each integration type\n2. \u2705 Use `OpenApi` class when `grepMetadata` shows OpenAPI spec\n3. \u2705 All imports included\n4. \u2705 Correct variable access patterns (`.value`, `.output`, `.output.data` for GraphQL)\n5. \u2705 No fake integration IDs\n6. \u2705 No placeholder logic\n7. \u2705 Descriptive block names\n8. \u2705 Error handling only where appropriate\n9. \u2705 NEVER change API name when editing existing API\n10. \u2705 ALWAYS test after building\n11. \u2705 **ALL SELECT queries have LIMIT clauses** (default 100) - use dialect-appropriate syntax\n\n## Interpreting testApi tool Results\n\n**CRITICAL**: \\`success: false\\` or missing = FAILURE. Never show success toast. Even when \\`success: true\\`, verify the output data is valid before confirming success to the user.\n";
+//# sourceMappingURL=skill.generated.d.ts.map

package/dist/ai-service/skills/system/superblocks-api/skill.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.generated.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/superblocks-api/skill.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,89zBAu3BnB,CAAC"}