// Auto-generated from src/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.md
// Do not edit directly - edit the .md file instead
export const content = `# YAML block → TypeScript mapping

Reference for \`superblocks-migration/SKILL.md\`. Covers how each legacy block type in \`api.yaml\` maps to the new \`@superblocksteam/sdk-api\` TypeScript format.

## Integration-backed blocks (SQL, REST, vendor plugins)

Shape in YAML:

\`\`\`yaml
step:
  name: <BlockName>
  integration: <uuid> # OR a plugin key like "restapi"
  <plugin>: # e.g. postgresql, snowflake, restapi, openApiAction
    body: | # SQL, request body, etc.
      ...
    parameters:
      - name: <n>
        value: <expr>
\`\`\`

### SQL integrations (PostgreSQL, MySQL, Snowflake, Databricks, etc.)

- Rows returned (\`SELECT\`, \`SHOW\`, \`RETURNING *\`) → \`await ctx.integrations.<key>.query(sql, Schema, params)\` with a Zod schema.
- No rows actionable (\`INSERT\` w/o \`RETURNING\`, \`UPDATE\`, \`DELETE\`, DDL) → \`await ctx.integrations.<key>.execute(sql, params)\`.
- **Parameterize everything.** Zero \`\${…}\` inside the SQL string. Dynamic lists use \`= ANY($N::<type>[])\`, never string-concatenated \`IN (…)\`.

### REST / OpenAPI / vendor plugin blocks

- \`openApiAction\`, \`restapi:\`, and vendor plugin keys (e.g. \`salesforce:\`, \`stripe:\`, \`openai:\`) → the matching factory from the sdk-api barrel (\`node_modules/@superblocksteam/sdk-api/src/index.ts\`).
- Never emit \`openapi(...)\`, \`http(...)\`, or \`openApiAction(...)\` — those are not sdk-api factories.
- Client method names come from the integration README — never invent them. If the README only documents \`apiRequest\`, use \`apiRequest\`.

## JavaScript blocks

\`\`\`yaml
step:
  name: <BlockName>
  integration: javascript
  javascript:
    body: |
      ...JS code...
\`\`\`

There is **no \`javascript\` integration** in sdk-api. Inline the body as plain TypeScript inside \`run(ctx, input)\`. Any references to prior blocks' \`<PriorBlock>.output\` are replaced by the local \`const\` bound to that block's result.

## Control-flow blocks

| YAML block                        | TS construct                                                             |
| --------------------------------- | ------------------------------------------------------------------------ |
| \`conditional:\` (if / else)        | \`if (...) { ... } else { ... }\` around the nested block TS               |
| \`loop:\` with \`type: TYPE_FOREACH\` | \`for (const x of xs) { ... }\` with **sequential** \`await\` (default)      |
| \`loop:\` with \`type: TYPE_WHILE\`   | \`while (cond) { ... }\`                                                   |
| \`parallel:\` (explicit)            | \`await Promise.all(xs.map(async x => ...))\`                              |
| \`variables:\`                      | \`const\`s in the enclosing scope                                          |
| \`throw:\`                          | \`throw new Error(...)\` (or the sdk-api error class the README documents) |
| \`return:\`                         | \`return ...;\` from \`run\`                                                 |
| \`tryCatch:\`                       | \`try { ... } catch (err) { ... }\`                                        |
| \`break:\`                          | \`break;\`                                                                 |

Only use \`Promise.all\` when the YAML explicitly uses a \`parallel:\` block. A plain \`TYPE_FOREACH\` is sequential by contract — do not silently parallelize it.

## Per-block \`.output\` references

Legacy blocks expose \`<BlockName>.output\` to downstream blocks. In the TS port each block's result is a local \`const\`:

\`\`\`ts
const users = await ctx.integrations.pg.query(USERS_SQL, UsersSchema, [orgId]);
// downstream: reference \`users\`, not \`GetUsers.output\`
\`\`\`

## Metadata mapping

- \`metadata.name\` → the string passed to \`api({ name: "<metadata.name>" })\` and the file base name (kebab-case).
- \`metadata.description\` → the \`description\` field on \`api({ ... })\` if the sdk-api contract supports it (check the README; do not invent fields).
- \`authorization.type: AUTHORIZATION_TYPE_APP_USERS\` → server-enforced; use \`ctx.user\` in TS. Remove any \`userId\`/\`email\` inputs the YAML declared as API input if they are now derivable from \`ctx.user\`.

## Inputs

The YAML's \`apiInputs\` (or equivalent) enumerates the externally-accepted parameters. In the TS port:

- Declare them on the \`input\` shape passed to \`run(ctx, input)\`.
- Drop any input that is now sourced from \`ctx.user\` or from \`ctx.integrations.<key>\` state.
- Keep the **minimal** union of identifiers the YAML actually references downstream.

## Integration UUIDs

Every distinct \`step.integration\` UUID in a YAML becomes a named \`const\` at the top of the TS file — one \`const\` per unique integration, reused by every \`ctx.integrations.<key>\` call. Do not inline UUIDs. Do not carry UUIDs across files.

\`\`\`ts
const PG_MAIN = "550e8400-e29b-41d4-a716-446655440000";

const db = ctx.integrations.pg(PG_MAIN);
const rows = await db.query(...);
\`\`\`

(Exact binding form depends on the sdk-api contract — confirm against the README.)

## What NOT to emit

- \`// TODO\` or \`// FIXME\` comments that silently ship — unresolved items live only as \`failed\` checklist entries.
- Narrative code comments ("this step fetches users"). Code should read directly.
- Retry wrappers, caching layers, or extra logging beyond the single \`ctx.log.info("<ApiName> start", {...})\` at the top of \`run\`.
- Envelope wrappers around the response — the external output shape must mirror the legacy API exactly.
`;
//# sourceMappingURL=yaml-block-mapping.generated.js.map