@superblocksteam/cli 2.0.3-next.206 → 2.0.3-next.208

package/README.md

@@ -14,7 +14,7 @@ $ npm install -g @superblocksteam/cli
 $ superblocks COMMAND
 running command...
 $ superblocks (--version)
-@superblocksteam/cli/2.0.3-next.206 linux-x64 node-v20.19.0
+@superblocksteam/cli/2.0.3-next.208 linux-x64 node-v20.19.0
 $ superblocks --help [COMMAND]
 USAGE
   $ superblocks COMMAND

package/dist/{generated-6TNBFOK2.js → generated-W6HVWB2O.js}

@@ -32,7 +32,7 @@ var content = '### FULL EXAMPLES\n\n#### Full example 1:\n\nBelow is a full exam
 
 // ../../../vite-plugin-file-sync/dist/ai-service/prompts/generated/subprompts/superblocks-api.js
 init_cjs_shims();
-var content2 = '### APIs\n\nThe Superblocks framework allows you to create backend APIs. The high level structure for creating APIs is as follows:\n\n1. APIs are defined using TypeScript files that live inside the apis directory inside the page they are scoped to. Example: /pages/Page1/apis/myApi.ts\n2. This pattern is a declarative workflow builder, where you define each API step, its configuration, and its execution order within the API workflow.\n3. To make the API available for use, you must import it into the scope file and register it with `SbApi()`, then import and destructure it in your page component for use.\n\n#### CRITICAL VARIABLE SCOPING RULES\n\n**\u{1F6A8} EXTREMELY IMPORTANT**: Variables referenced in API blocks can ONLY come from these sources:\n\n1. **Outputs of previous blocks** in the same API (accessed via the block name)\n2. **Page entities defined in the scope file** (passed as destructured parameters)\n3. **Never reference variables that don\'t exist** - this is the #1 cause of API generation errors\n\n**\u274C WRONG - Variables that don\'t exist in scope:**\n\n```ts\nnew PostgreSQL("insert_data", "postgres-integration-id", {\n  statement: ({ SelectedCustomerIdVar, ProductNameInput, IssueTypeDropdown }) =>\n    `INSERT INTO issues VALUES (${SelectedCustomerIdVar.value}, \'${ProductNameInput.value}\', \'${IssueTypeDropdown.selectedOptionValue}\')`,\n  // \u274C ERROR: SelectedCustomerIdVar, ProductNameInput, IssueTypeDropdown are not defined anywhere!\n});\n```\n\n**\u2705 CORRECT - Variables from scope entities:**\n\n```ts\n// First, define in scope.ts:\nexport const Page1Scope = createSbScope<{\n  SelectedCustomerIdVar: any;\n  ProductNameInput: any;\n  IssueTypeDropdown: any;\n}>(\n  () => ({\n    // Register the API\n    submitIssueApi: SbApi({}),\n  }),\n  { name: "Page1" },\n);\n\n// Then use in API:\nnew PostgreSQL("insert_data", "postgres-integration-id", {\n  statement: ({ SelectedCustomerIdVar, ProductNameInput, IssueTypeDropdown }) =>\n    `INSERT INTO issues VALUES (${SelectedCustomerIdVar.value}, \'${ProductNameInput.value}\', \'${IssueTypeDropdown.selectedOptionValue}\')`,\n  // \u2705 CORRECT: These are page entities defined in the scope\n});\n```\n\n**\u2705 CORRECT - Variables from previous blocks:**\n\n```ts\nexport default new Api("processOrderApi", [\n  new JavaScript("get_customer_data", {\n    fn: () => ({ customerId: 123, customerName: "John Doe" }),\n  }),\n  new PostgreSQL("insert_order", "postgres-integration-id", {\n    statement: ({ get_customer_data }) =>\n      `INSERT INTO orders VALUES (${get_customer_data.output.customerId}, \'${get_customer_data.output.customerName}\')`,\n    // \u2705 CORRECT: get_customer_data is a previous block in this API\n  }),\n]);\n```\n\n#### CRITICAL MENTAL MODEL: APIs Access Page Scope (They Don\'t Define Parameters)\n\n**\u{1F6A8} FUNDAMENTAL MISCONCEPTION TO AVOID:**\n\n\u274C **WRONG THINKING**: "APIs define their input parameters like traditional backend services"\n\n```ts\n// WRONG - This is NOT how Superblocks APIs work!\nfunction submitOrder(customerId, productName) {\n  // \u274C APIs don\'t define parameters!\n  // API logic here\n}\n```\n\n\u2705 **CORRECT THINKING**: "APIs are frontend-coupled functions that automatically access the page\'s existing scope"\n\n```ts\n// CORRECT - APIs inherit page scope automatically\nnew PostgreSQL("insert_order", "postgres-integration-id", {\n  statement: ({ SelectedCustomerIdVar, ProductNameInput }) =>\n    // \u2191 This is NOT defining parameters - this is accessing existing page scope!\n    // These variables must ALREADY exist in your page scope\n    `INSERT INTO orders VALUES (${SelectedCustomerIdVar.value}, \'${ProductNameInput.value}\')`,\n});\n```\n\n**KEY CONCEPTS:**\n\n1. **APIs are frontend-aware**: They\'re tightly coupled to your page, not independent backend services\n2. **No parameter definition**: APIs cannot define their own input parameters\n3. **Scope inheritance only**: APIs automatically access whatever exists in your page scope\n4. **Mandatory order**: Page Scope \u2192 Components \u2192 APIs (scope must exist first)\n\n**The Flow:**\n\n```\nPage Scope Variables \u2192 APIs Automatically Access \u2192 Use in API Logic\n(Must exist first)   \u2192 (No parameter passing)   \u2192 (Just destructure from scope)\n```\n\n**Contrasting Examples:**\n\n\u274C **Traditional Backend API (NOT how Superblocks works):**\n\n```ts\n// This is how traditional APIs work - NOT Superblocks!\nfunction createOrder(customerId, productName, quantity) {\n  // \u274C Defines own parameters\n  return database.insert({\n    customer_id: customerId,\n    product: productName,\n    qty: quantity,\n  });\n}\n\n// Called like: createOrder(123, "Widget", 5) - parameters passed in\n```\n\n\u2705 **Superblocks API (Frontend-coupled):**\n\n```ts\n// This is how Superblocks APIs work - inherits page scope\nnew PostgreSQL("insert_order", "postgres-integration-id", {\n  statement: ({ CustomerIdInput, ProductNameInput, QuantityInput }) => {\n    // \u2191 NOT defining parameters! These must exist in page scope already\n    return `INSERT INTO orders VALUES (${CustomerIdInput.value}, \'${ProductNameInput.value}\', ${QuantityInput.value})`;\n  },\n});\n\n// No "calling with parameters" - scope variables are automatically available\n```\n\n#### Rules\n\n1. CRITICAL: The name of the API must be consistent across the API\'s TypeScript definition, the API\'s file name, references in page files, and the key used to register it in the scope file. See the consistent use of \'myApi\' below as an example.\n2. ALWAYS import ALL API classes from the superblocks library at the top of every API file. Use this complete import statement for every API file:\n3. When using database integrations (PostgreSQL, Snowflake, Databricks), the integration_id parameter should be the actual integration ID from your Superblocks workspace, not a placeholder string.\n4. **CRITICAL**: DO NOT reference variables that are not in scope. The ONLY things in scope are (1) the outputs of previous blocks that are in lexical scope and (2) page entities defined in the scope file.\n\n```ts\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n```\n\n#### Examples\n\n##### Complete Example: Scope \u2192 Components \u2192 API Flow\n\nThis example shows the complete flow from defining variables in scope, to binding them to components, to using them in APIs.\n\n**Step 1: Define entities in scope file**\n\n```ts\n// /pages/Page1/scope.ts\nimport { createSbScope, SbApi } from "@superblocksteam/library";\n\nexport const Page1Scope = createSbScope<{\n  CustomerNameInput: any;\n  ProductNameInput: any;\n  IssueTypeDropdown: any;\n  IssueNotesInput: any;\n}>(\n  () => ({\n    // Register the API\n    submitProductIssueApi: SbApi({}),\n  }),\n  {\n    name: "Page1",\n  },\n);\n\nexport const Page1 = Page1Scope.entities;\n```\n\n**Step 2: Use entities in page components**\n\n```tsx\n// /pages/Page1/index.tsx\nimport {\n  SbPage,\n  SbSection,\n  SbColumn,\n  SbInput,\n  SbDropdown,\n  SbButton,\n  SbEventFlow,\n  registerPage,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n  const {\n    CustomerNameInput,\n    ProductNameInput,\n    IssueTypeDropdown,\n    IssueNotesInput,\n    submitProductIssueApi,\n  } = Page1;\n\n  return (\n    <SbPage name="Page1" height={Dim.fill()} width={Dim.fill()}>\n      <SbSection height={Dim.fill()}>\n        <SbColumn width={Dim.fill()}>\n          <SbInput bind={CustomerNameInput} label="Customer Name" />\n          <SbInput bind={ProductNameInput} label="Product Name" />\n          <SbDropdown\n            bind={IssueTypeDropdown}\n            label="Issue Type"\n            options={[\n              { label: "Defect", value: "defect" },\n              { label: "Complaint", value: "complaint" },\n              { label: "Return", value: "return" },\n            ]}\n          />\n          <SbInput bind={IssueNotesInput} label="Notes" multiline={true} />\n          <SbButton\n            label="Submit Issue"\n            onClick={SbEventFlow.runApis([submitProductIssueApi])}\n          />\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\n**Step 3: Create API that uses the scope entities**\n\n```ts\n// /pages/Page1/apis/submitProductIssueApi.ts\n\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n\nexport default new Api("submitProductIssueApi", [\n  new Conditional("validate_inputs", {\n    if: {\n      when: ({\n        CustomerNameInput,\n        ProductNameInput,\n        IssueTypeDropdown,\n      }): boolean =>\n        !CustomerNameInput.value ||\n        !ProductNameInput.value ||\n        !IssueTypeDropdown.selectedOptionValue,\n      then: [\n        new Throw("validation_error", {\n          error: "Customer name, product name, and issue type are required",\n        }),\n      ],\n    },\n  }),\n  new PostgreSQL("insert_issue", "your-postgresql-integration-id", {\n    statement: ({\n      CustomerNameInput,\n      ProductNameInput,\n      IssueTypeDropdown,\n      IssueNotesInput,\n    }) =>\n      `INSERT INTO product_issues \n       (customer_name, product_name, issue_type, notes, status, date_reported, created_by)\n       VALUES (\n         \'${CustomerNameInput.value}\', \n         \'${ProductNameInput.value}\', \n         \'${IssueTypeDropdown.selectedOptionValue}\', \n         \'${IssueNotesInput.value || ""}\', \n         \'Open\', \n         NOW(), \n         1\n       )`,\n  }),\n  new JavaScript("return_success", {\n    fn: ({ insert_issue }) => ({\n      success: true,\n      message: "Issue submitted successfully",\n      issueId: insert_issue.output?.insertId || null,\n    }),\n  }),\n]);\n```\n\n##### \u274C COMMON MISTAKES TO AVOID\n\n**\u274C WRONG: Using undefined variables**\n\n```ts\n// This is WRONG - these variables don\'t exist!\nexport default new Api("badExampleApi", [\n  new PostgreSQL("insert_data", "postgres-integration-id", {\n    statement: ({\n      SelectedCustomerIdVar,\n      ProductNameInput,\n      IssueTypeDropdown,\n    }) =>\n      `INSERT INTO issues VALUES (${SelectedCustomerIdVar.value}, \'${ProductNameInput.value}\', \'${IssueTypeDropdown.selectedOptionValue}\')`,\n    // \u274C ERROR: SelectedCustomerIdVar, ProductNameInput, IssueTypeDropdown are not defined in scope!\n  }),\n]);\n```\n\n**\u274C WRONG: Mixing up variable names**\n\n```ts\n// Scope defines CustomerNameInput but API tries to use CustomerName\nexport default new Api("badExampleApi", [\n  new PostgreSQL("insert_data", "postgres-integration-id", {\n    statement: (\n      { CustomerName }, // \u274C ERROR: Should be CustomerNameInput\n    ) => `INSERT INTO issues VALUES (\'${CustomerName.value}\')`,\n  }),\n]);\n```\n\n**\u274C WRONG: Not destructuring function parameters**\n\n```ts\n// This is WRONG - you must destructure the parameters\nexport default new Api("badExampleApi", [\n  new PostgreSQL("insert_data", "postgres-integration-id", {\n    statement: (\n      state, // \u274C ERROR: Should destructure { CustomerNameInput }\n    ) => `INSERT INTO issues VALUES (\'${state.CustomerNameInput.value}\')`,\n  }),\n]);\n```\n\n##### Creating and registering a Superblocks API\n\nCreate the API by adding the myApi.ts file:\n\n```ts\n// /pages/Page1/apis/myApi.ts\n\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n\nexport default new Api("myApi", [\n  new JavaScript("retrieve_orders", {\n    fn: () => {\n      return [\n        {\n          id: "ORD-001",\n          customerName: "John Smith",\n          total: 149.99,\n        },\n        {\n          id: "ORD-002",\n          customerName: "Sarah Jones",\n          total: 89.5,\n        },\n      ];\n    },\n  }),\n]);\n```\n\nThen register the myApi API in the scope file:\n\n```ts\n// /pages/Page1/scope.ts\n\nimport { createSbScope, SbApi } from "@superblocksteam/library";\n\nexport const Page1Scope = createSbScope(\n  () => ({\n    // Register the API in the scope\n    retrieveOrdersApi: SbApi({}),\n  }),\n  {\n    name: "Page1",\n  },\n);\n\nexport const Page1 = Page1Scope.entities;\n```\n\nThen use the API in your page component:\n\n```tsx\n// /pages/Page1/index.tsx\n\nimport {\n  SbPage,\n  SbSection,\n  SbColumn,\n  SbButton,\n  SbTable,\n  sbComputed,\n  SbEventFlow,\n  registerPage,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n  const { retrieveOrdersApi } = Page1;\n\n  return (\n    <SbPage name="Page1" height={Dim.fill()} width={Dim.fill()}>\n      <SbSection height={Dim.fill()}>\n        <SbColumn width={Dim.fill()}>\n          <SbButton\n            // APIs can be invoked with the SbEventFlow API\n            onClick={SbEventFlow.runApis([retrieveOrdersApi])}\n            label="Fetch Data"\n          />\n          {/* Access API response using sbComputed */}\n          <SbTable tableData={sbComputed(() => retrieveOrdersApi.response)} />\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\n##### Referencing the output of a previous block\n\nThink hard about how you access the output of previous steps. You MUST use the output property of the previous step variable. There is no other way to access the output of a previous step (other than using a Variable block, but that is not what you want in this case and should only be used in very specific cases).\n\n```ts\n// Path to this api would be: /pages/Page1/apis/getOrdersApi.ts\n\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n\nexport default new Api("getOrdersApi", [\n  new JavaScript("retrieve_orders", {\n    fn: () => {\n      return [\n        {\n          id: 1,\n          customer: "John Smith",\n          date: "2024-01-15",\n          total: 199.99,\n          status: "Pending",\n        },\n        {\n          id: 2,\n          customer: "Jane Doe",\n          date: "2024-01-14",\n          total: 149.99,\n          status: "Shipped",\n        },\n        {\n          id: 3,\n          customer: "Bob Wilson",\n          date: "2024-01-13",\n          total: 299.99,\n          status: "Delivered",\n        },\n      ];\n    },\n  }),\n  new JavaScript("format_orders", {\n    fn: ({ retrieve_orders }) => {\n      return retrieve_orders.output.map((order) => ({\n        ...order,\n        date: new Date(order.date).toLocaleDateString(),\n      }));\n    },\n  }),\n]);\n```\n\nThen you would register the API in your scope file and use it in your page component:\n\n```ts\n// /pages/Page1/scope.ts\nexport const Page1Scope = createSbScope(\n  () => ({\n    getOrdersApi: SbApi({}),\n  }),\n  {\n    name: "Page1",\n  },\n);\n```\n\n```tsx\n// /pages/Page1/index.tsx\nimport {\n  SbPage,\n  SbSection,\n  SbColumn,\n  SbTable,\n  sbComputed,\n  registerPage,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n  const { getOrdersApi } = Page1;\n\n  return (\n    <SbPage name="Page1" height={Dim.fill()} width={Dim.fill()}>\n      <SbSection height={Dim.fill()}>\n        <SbColumn width={Dim.fill()}>\n          <SbTable tableData={sbComputed(() => getOrdersApi.response)} />\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\n##### Ensuring variable existence in application\n\n**\u{1F6A8} CRITICAL**: APIs cannot create their own variables - they only access what already exists in page scope!\n\nWhen creating an API that references variables like `FirstNameInput`, `LastNameInput`, and `SelectedUserIdVar`, these variables MUST exist in your page scope BEFORE you write the API. APIs don\'t define parameters - they inherit scope.\n\n**Mandatory Flow: Scope \u2192 Components \u2192 APIs**\n\n**STEP 1: Create variables in scope FIRST** (APIs cannot access variables that don\'t exist)\n\nSince you\'ve determined that we\'ll use input components to take in the first name and last name, you MUST ensure that you use the same names for the entities in the `scope.ts` file as the variable names in the API.\n\n```ts\n// /pages/Page1/scope.ts\n\nimport {\n  createSbScope,\n  SbApi,\n  SbVariable,\n  SbVariablePersistence,\n  Global,\n} from "@superblocksteam/library";\n\nexport const Page1Scope = createSbScope<{\n  FirstNameInput: any;\n  LastNameInput: any;\n}>(\n  // register non-component entities in the scope\n  ({\n    entities: {\n      FirstNameInput,\n      LastNameInput,\n      handlePeopleUpdates,\n      SelectedUserIdVar,\n    },\n  }) => ({\n    handlePeopleUpdatesApi: SbApi({}),\n    SelectedUserIdVar: SbVariable({\n      defaultValue: Global.user.id,\n      persistence: SbVariablePersistence.TEMPORARY,\n    }),\n  }),\n  // configure page options\n  {\n    name: "Page1",\n  },\n);\n\nexport const Page1 = Page1Scope.entities;\n```\n\nThen, use the variables in your page component:\n\n```tsx\n// /pages/Page1/index.tsx\n\nimport {\n  SbPage,\n  SbInput,\n  SbEventFlow,\n  registerPage,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n  const {\n    handlePeopleUpdatesApi,\n    FirstNameInput,\n    LastNameInput,\n    SelectedUserIdVar,\n  } = Page1;\n\n  return (\n    <SbPage name="Page1">\n      <SbInput\n        label="First Name"\n        bind={FirstNameInput}\n        minLength={1}\n        inputType="TEXT"\n      />\n      <SbInput\n        label="Last Name"\n        bind={LastNameInput}\n        minLength={1}\n        inputType="TEXT"\n      />\n      {/* The rest of the page... */}\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\nFinally, create the API that references these variables:\n\n```ts\n// /pages/Page1/apis/handlePeopleUpdatesApi.ts\n\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n\nexport default new Api("handlePeopleUpdatesApi", [\n  new Conditional("validate", {\n    if: {\n      when: ({ FirstNameInput, LastNameInput }): boolean =>\n        !FirstNameInput.isValid || !LastNameInput.isValid,\n      then: [\n        new Throw("reject", {\n          error: "either the first name or last name is invalid",\n        }),\n      ],\n    },\n  }),\n  new PostgreSQL("update", "your-postgresql-integration-id", {\n    statement: ({ FirstNameInput, LastNameInput, SelectedUserIdVar }) =>\n      `UPDATE people SET first_name = \'${FirstNameInput.value}\', last_name = \'${LastNameInput.value}\' WHERE id = ${SelectedUserIdVar.value}`,\n  }),\n]);\n```\n\n#### The Superblocks API TypeScript Type\n\nBelow is the full TypeScript spec for the APIs you create:\n\n````ts\n// @superblocksteam/library\n\nexport type JsonValue =\n  | undefined\n  | null\n  | number\n  | string\n  | boolean\n  | JsonValue[]\n  | object;\nexport type State = { [key: string]: JsonValue };\nexport type Binding<T> = T | ((state: State) => T);\ntype Integrations = { id: string; description: string; metadata: JsonValue }[];\n\nclass Block {\n  constructor(name: string) {}\n  public run(): { output: JsonValue } {\n    /* ... */\n  }\n}\n\nclass Integration extends Block {\n  constructor(name: string, integration_id: string) {}\n}\n\ntype State = Record<string, JsonValue>;\n\nclass JavaScript extends Integration {\n  constructor(\n    name: string,\n    config: {\n      fn: (\n        {\n          /* ... */\n        },\n      ) => JsonValue;\n    },\n  ) {\n    super(name, "javascript");\n  }\n}\n\nclass Python extends Integration {\n  constructor(\n    name: string,\n    config: {\n      // We want to just put the python function body here. The scope is the same as it would be if it were a JavaScript integration.\n      fn: string;\n    },\n  ) {\n    super(name, "python");\n  }\n}\n\nclass Databricks extends Integration {\n  static integrations: Integrations = [\n    /* ... */\n  ];\n\n  /**\n   * @param {string} name           The name of the block.\n   * @param {string} integration_id The id of the integration.\n   * @param {object} config         The config object.\n   * @returns {void}\n   */\n  constructor(\n    name: string,\n    integration_id: string,\n    config: {\n      statement: Binding<string>;\n    },\n  ) {\n    super(name, integration_id);\n  }\n}\n\nclass Snowflake extends Integration {\n  static integrations: Integrations = [\n    /* ... */\n  ];\n\n  /**\n   * @param {string} name           The name of the block.\n   * @param {string} integration_id The id of the integration.\n   * @param {object} config         The config object.\n   * @returns {void}\n   */\n  constructor(\n    name: string,\n    integration_id: string,\n    config: {\n      statement: Binding<string>;\n    },\n  ) {\n    super(name, integration_id);\n  }\n}\n\nclass PostgreSQL extends Integration {\n  static integrations: Integrations = [\n    /* ... */\n  ];\n\n  /**\n   * @param {string} name           The name of the block.\n   * @param {string} integration_id The id of the integration.\n   * @param {object} config         The config object.\n   * @returns {void}\n   */\n  constructor(\n    name: string,\n    integration_id: string,\n    config: {\n      statement: Binding<string>;\n    },\n  ) {\n    super(name, integration_id);\n  }\n}\n\nclass RestApi extends Integration {\n  static integrations: Integrations = [\n    /* ... */\n  ];\n\n  constructor(\n    name: string,\n    // If you need to make a request that is detached from an integration, you MUST set this to "restapi".\n    integration: string = "restapi",\n    config: {\n      method: string;\n      url: Binding<string>;\n      headers?: { key: Binding<string>; value: Binding<string> }[];\n      params?: { key: Binding<string>; value: Binding<string> }[];\n      body?: Binding<string>;\n    },\n    openapi?: {\n      path: string; // This is the path exactly as it appears in the OpenAPI spec.\n    },\n  ) {\n    super(name, integration);\n  }\n}\n\nclass GitHub extends RestApi {\n  constructor(\n    name: string,\n    integration: string,\n    config: {\n      method: string;\n      url: Binding<string>;\n      headers?: { key: Binding<string>; value: Binding<string> }[];\n      params?: { key: Binding<string>; value: Binding<string> }[];\n      body?: Binding<string>;\n    },\n    openapi?: {\n      path: string; // This is the path exactly as it appears in the OpenAPI spec.\n    },\n  ) {\n    super(name, integration, config, openapi);\n  }\n}\n\nclass Jira extends RestApi {\n  constructor(\n    name: string,\n    integration: string,\n    config: {\n      method: string;\n      url: Binding<string>;\n      headers?: { key: Binding<string>; value: Binding<string> }[];\n      params?: { key: Binding<string>; value: Binding<string> }[];\n      body?: Binding<string>;\n    },\n    openapi?: {\n      path: string; // This is the path exactly as it appears in the OpenAPI spec.\n    },\n  ) {\n    super(name, integration, config, openapi);\n  }\n}\n\nclass Email extends Integration {\n  constructor(\n    name: string,\n    config: {\n      from: Binding<string>;\n      to: Binding<string>;\n      subject: Binding<string>;\n      cc?: Binding<string>;\n      bcc?: Binding<string>;\n      body?: Binding<string>;\n    },\n  ) {\n    super(name);\n  }\n}\n\nexport type Condition = {\n  when: boolean | ((state: State) => boolean);\n  then: Block[];\n};\n\nexport type Conditions = {\n  if: Condition;\n  elif?: Condition[];\n  else?: Block[];\n};\n\nclass Conditional extends Block {\n  constructor(name: string, config: Conditions) {\n    super(name);\n  }\n}\n\nclass 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    super(name);\n  }\n}\n\n/**\n * A Superblocks variable has the following access pattern:\n *\n * How to retrieve the value of a variable:\n * ```ts\n * CORRECT\n * my_variable.value\n *\n * // INCORRECT\n * my_variable\n * ```\n *\n * How to set the value of a variable:\n * ```ts\n * CORRECT\n * my_variable.set(value)\n *\n * // INCORRECT\n * my_variable = value\n * ```\n *\n */\n\nclass Variables extends Block {\n  constructor(\n    name: string,\n    variables: {\n      // The name of the variable.\n      key: string;\n      // The value of the variable.\n      value: Binding<JsonValue>;\n    }[],\n  ) {\n    super(name);\n  }\n}\n\nclass Loop extends Block {\n  constructor(\n    name: string,\n    config: {\n      over: Binding<JsonValue[]>;\n      variables: {\n        // What the variable name for the current item is.\n        item: string;\n        // What the variable name for the current index is.\n        index: string;\n      };\n      blocks: Block[];\n    },\n  ) {\n    super(name);\n  }\n}\n\nclass Parallel extends Block {\n  constructor(\n    name: string,\n    config: {\n      over: Binding<JsonValue[]>;\n      variables: {\n        // What the variable name for the current item is.\n        item: string;\n      };\n      blocks: Block[];\n    },\n  ) {\n    super(name);\n  }\n}\n\nclass Throw extends Block {\n  constructor(\n    name: string,\n    config: {\n      error: Binding<JsonValue>;\n    },\n  ) {\n    super(name);\n  }\n}\n\nclass Return extends Block {\n  constructor(\n    name: string,\n    config: {\n      data: Binding<JsonValue>;\n    },\n  ) {\n    super(name);\n  }\n}\n\nclass Api {\n  constructor(\n    name: string,\n    steps: Block[],\n    authorization:\n      | {\n          type: "AUTHORIZATION_TYPE_APP_USERS";\n        }\n      | {\n          type: "AUTHORIZATION_TYPE_JS_EXPRESSION";\n          expression: Binding<boolean>;\n        } = { type: "AUTHORIZATION_TYPE_APP_USERS" },\n  ) {\n    /* ... */\n  }\n  public get response(): JsonValue {\n    /* ... */\n  }\n  public get error(): string | undefined {\n    /* ... */\n  }\n  public run(): void {\n    /* ... */\n  }\n  public cancel(): void {\n    /* ... */\n  }\n}\n````\n\n#### Rules for using Superblocks APIs\n\nThink hard about the following important rules for correctly using Superblocks APIs:\n\n- You MUST use a destructured object to access page scope variables in dynamic block fields. This syntax is NOT defining function parameters - it\'s accessing the inherited page scope.\n\n```ts\n// CORRECT: destructuring to access page scope variables that must already exist\n({ Dropdown1, TextInput1 }) => Dropdown1.selectedOptionsValue + TextInput1.value\n// \u2191 These variables (Dropdown1, TextInput1) must exist in your page scope!\n\n// INCORRECT: trying to use scope object directly\n(state) => state.Dropdown1.selectedOptionsValue + state.TextInput1.value\n// \u2191 This syntax doesn\'t work in Superblocks\n```\n\n- DO NOT reference variables that are not in scope or that don\'t exist. The ONLY things in scope are (1) the outputs of previous blocks that are in lexical scope and (2) page entities.\n\n- The result of each scope is the result of the last block in that scope. In the following example, the value of `sendEmail.response` is the result of the `return_summary` block. Use this information to carefully ensure that the last block in your API is the one that returns the value you want.\n\n```ts\nexport default new Api("sendEmailApi", [\n  new Email("send_email", {\n    from: "noreply@company.com",\n    to: "test@test.com",\n    subject: "Test Email",\n    body: "This is a test email",\n  }),\n  new JavaScript("return_summary", {\n    fn: () => "Email sent successfully!",\n  }),\n]);\n```\n\n- Block outputs are immutable. Do not mutate the output of a block.\n\n- Backend APIs CANNOT mutate frontend state inside of the API\n\n- APIs are registered in scope files using `SbApi()` and then accessed in page components by destructuring from the scope entities. Make sure you name the key used in registerScope the same as the imported API, but do not pass the imported Api into the SbApi() call.\n\n- To access API responses in your UI, use `sbComputed(() => apiName.response)` or `sbComputed(() => apiName.error)`.\n\n- You will not always be told which integrations to use in your API; you will have to determine that yourself based on the data you need to fetch.\n\n- Never add comments to code you (the ai) generate. User added comments are fine - leave those!\n';
+var content2 = '### APIs\n\nThe Superblocks framework allows you to create backend APIs. The high level structure for creating APIs is as follows:\n\n1. APIs are defined using TypeScript files that live inside the apis directory inside the page they are scoped to. Example: /pages/Page1/apis/myApi.ts\n2. This pattern is a declarative workflow builder, where you define each API step, its configuration, and its execution order within the API workflow.\n3. To make the API available for use, you must import it into the scope file and register it with `SbApi()`, then import and destructure it in your page component for use.\n\n#### CRITICAL VARIABLE SCOPING RULES\n\n**\u{1F6A8} EXTREMELY IMPORTANT**: Variables referenced in API blocks can ONLY come from these sources:\n\n1. **Outputs of previous blocks** in the same API (accessed via the block name)\n2. **Page entities defined in the scope file** (passed as destructured parameters)\n3. **Never reference variables that don\'t exist** - this is the #1 cause of API generation errors\n\n**\u274C WRONG - Variables that don\'t exist in scope:**\n\n```ts\nnew PostgreSQL("insert_data", "postgres-integration-id", {\n  statement: ({ SelectedCustomerIdVar, ProductNameInput, IssueTypeDropdown }) =>\n    `INSERT INTO issues VALUES (${SelectedCustomerIdVar.value}, \'${ProductNameInput.value}\', \'${IssueTypeDropdown.selectedOptionValue}\')`,\n  // \u274C ERROR: SelectedCustomerIdVar, ProductNameInput, IssueTypeDropdown are not defined anywhere!\n});\n```\n\n**\u2705 CORRECT - Variables from scope entities:**\n\n```ts\n// First, define in scope.ts:\nexport const Page1Scope = createSbScope<{\n  SelectedCustomerIdVar: any;\n  ProductNameInput: any;\n  IssueTypeDropdown: any;\n}>(\n  () => ({\n    // Register the API\n    submitIssueApi: SbApi({}),\n  }),\n  { name: "Page1" },\n);\n\n// Then use in API:\nnew PostgreSQL("insert_data", "postgres-integration-id", {\n  statement: ({ SelectedCustomerIdVar, ProductNameInput, IssueTypeDropdown }) =>\n    `INSERT INTO issues VALUES (${SelectedCustomerIdVar.value}, \'${ProductNameInput.value}\', \'${IssueTypeDropdown.selectedOptionValue}\')`,\n  // \u2705 CORRECT: These are page entities defined in the scope\n});\n```\n\n**\u2705 CORRECT - Variables from previous blocks:**\n\n```ts\nexport default new Api("processOrderApi", [\n  new JavaScript("get_customer_data", {\n    fn: () => ({ customerId: 123, customerName: "John Doe" }),\n  }),\n  new PostgreSQL("insert_order", "postgres-integration-id", {\n    statement: ({ get_customer_data }) =>\n      `INSERT INTO orders VALUES (${get_customer_data.output.customerId}, \'${get_customer_data.output.customerName}\')`,\n    // \u2705 CORRECT: get_customer_data is a previous block in this API\n  }),\n]);\n```\n\n#### CRITICAL MENTAL MODEL: APIs Access Page Scope (They Don\'t Define Parameters)\n\n**\u{1F6A8} FUNDAMENTAL MISCONCEPTION TO AVOID:**\n\n\u274C **WRONG THINKING**: "APIs define their input parameters like traditional backend services"\n\n```ts\n// WRONG - This is NOT how Superblocks APIs work!\nfunction submitOrder(customerId, productName) {\n  // \u274C APIs don\'t define parameters!\n  // API logic here\n}\n```\n\n\u2705 **CORRECT THINKING**: "APIs are frontend-coupled functions that automatically access the page\'s existing scope"\n\n```ts\n// CORRECT - APIs inherit page scope automatically\nnew PostgreSQL("insert_order", "postgres-integration-id", {\n  statement: ({ SelectedCustomerIdVar, ProductNameInput }) =>\n    // \u2191 This is NOT defining parameters - this is accessing existing page scope!\n    // These variables must ALREADY exist in your page scope\n    `INSERT INTO orders VALUES (${SelectedCustomerIdVar.value}, \'${ProductNameInput.value}\')`,\n});\n```\n\n**KEY CONCEPTS:**\n\n1. **APIs are frontend-aware**: They\'re tightly coupled to your page, not independent backend services\n2. **No parameter definition**: APIs cannot define their own input parameters\n3. **Scope inheritance only**: APIs automatically access whatever exists in your page scope\n4. **Mandatory order**: Page Scope \u2192 Components \u2192 APIs (scope must exist first)\n\n**The Flow:**\n\n```\nPage Scope Variables \u2192 APIs Automatically Access \u2192 Use in API Logic\n(Must exist first)   \u2192 (No parameter passing)   \u2192 (Just destructure from scope)\n```\n\n**Contrasting Examples:**\n\n\u274C **Traditional Backend API (NOT how Superblocks works):**\n\n```ts\n// This is how traditional APIs work - NOT Superblocks!\nfunction createOrder(customerId, productName, quantity) {\n  // \u274C Defines own parameters\n  return database.insert({\n    customer_id: customerId,\n    product: productName,\n    qty: quantity,\n  });\n}\n\n// Called like: createOrder(123, "Widget", 5) - parameters passed in\n```\n\n\u2705 **Superblocks API (Frontend-coupled):**\n\n```ts\n// This is how Superblocks APIs work - inherits page scope\nnew PostgreSQL("insert_order", "postgres-integration-id", {\n  statement: ({ CustomerIdInput, ProductNameInput, QuantityInput }) => {\n    // \u2191 NOT defining parameters! These must exist in page scope already\n    return `INSERT INTO orders VALUES (${CustomerIdInput.value}, \'${ProductNameInput.value}\', ${QuantityInput.value})`;\n  },\n});\n\n// No "calling with parameters" - scope variables are automatically available\n```\n\n#### Rules\n\n1. CRITICAL: The name of the API must be consistent across the API\'s TypeScript definition, the API\'s file name, references in page files, and the key used to register it in the scope file. See the consistent use of \'myApi\' below as an example.\n2. ALWAYS import ALL API classes from the superblocks library at the top of every API file. Use this complete import statement for every API file:\n3. When using database integrations (PostgreSQL, Snowflake, Databricks), the integration_id parameter should be the actual integration ID from your Superblocks workspace, not a placeholder string.\n4. **CRITICAL**: DO NOT reference variables that are not in scope. The ONLY things in scope are (1) the outputs of previous blocks that are in lexical scope and (2) page entities defined in the scope file.\n\n```ts\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n```\n\n#### Examples\n\n##### Complete Example: Scope \u2192 Components \u2192 API Flow\n\nThis example shows the complete flow from defining variables in scope, to binding them to components, to using them in APIs.\n\n**Step 1: Define entities in scope file**\n\n```ts\n// /pages/Page1/scope.ts\nimport { createSbScope, SbApi } from "@superblocksteam/library";\n\nexport const Page1Scope = createSbScope<{\n  CustomerNameInput: any;\n  ProductNameInput: any;\n  IssueTypeDropdown: any;\n  IssueNotesInput: any;\n}>(\n  () => ({\n    // Register the API\n    submitProductIssueApi: SbApi({}),\n  }),\n  {\n    name: "Page1",\n  },\n);\n\nexport const Page1 = Page1Scope.entities;\n```\n\n**Step 2: Use entities in page components**\n\n```tsx\n// /pages/Page1/index.tsx\nimport {\n  SbPage,\n  SbSection,\n  SbColumn,\n  SbInput,\n  SbDropdown,\n  SbButton,\n  SbEventFlow,\n  registerPage,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n  const {\n    CustomerNameInput,\n    ProductNameInput,\n    IssueTypeDropdown,\n    IssueNotesInput,\n    submitProductIssueApi,\n  } = Page1;\n\n  return (\n    <SbPage name="Page1" height={Dim.fill()} width={Dim.fill()}>\n      <SbSection height={Dim.fill()}>\n        <SbColumn width={Dim.fill()}>\n          <SbInput bind={CustomerNameInput} label="Customer Name" />\n          <SbInput bind={ProductNameInput} label="Product Name" />\n          <SbDropdown\n            bind={IssueTypeDropdown}\n            label="Issue Type"\n            options={[\n              { label: "Defect", value: "defect" },\n              { label: "Complaint", value: "complaint" },\n              { label: "Return", value: "return" },\n            ]}\n          />\n          <SbInput bind={IssueNotesInput} label="Notes" multiline={true} />\n          <SbButton\n            label="Submit Issue"\n            onClick={SbEventFlow.runApis([submitProductIssueApi])}\n          />\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\n**Step 3: Create API that uses the scope entities**\n\n```ts\n// /pages/Page1/apis/submitProductIssueApi.ts\n\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n\nexport default new Api("submitProductIssueApi", [\n  new Conditional("validate_inputs", {\n    if: {\n      when: ({\n        CustomerNameInput,\n        ProductNameInput,\n        IssueTypeDropdown,\n      }): boolean =>\n        !CustomerNameInput.value ||\n        !ProductNameInput.value ||\n        !IssueTypeDropdown.selectedOptionValue,\n      then: [\n        new Throw("validation_error", {\n          error: "Customer name, product name, and issue type are required",\n        }),\n      ],\n    },\n  }),\n  new PostgreSQL("insert_issue", "your-postgresql-integration-id", {\n    statement: ({\n      CustomerNameInput,\n      ProductNameInput,\n      IssueTypeDropdown,\n      IssueNotesInput,\n    }) =>\n      `INSERT INTO product_issues \n       (customer_name, product_name, issue_type, notes, status, date_reported, created_by)\n       VALUES (\n         \'${CustomerNameInput.value}\', \n         \'${ProductNameInput.value}\', \n         \'${IssueTypeDropdown.selectedOptionValue}\', \n         \'${IssueNotesInput.value || ""}\', \n         \'Open\', \n         NOW(), \n         1\n       )`,\n  }),\n  new JavaScript("return_success", {\n    fn: ({ insert_issue }) => ({\n      success: true,\n      message: "Issue submitted successfully",\n      issueId: insert_issue.output?.insertId || null,\n    }),\n  }),\n]);\n```\n\n##### \u274C COMMON MISTAKES TO AVOID\n\n**\u274C WRONG: Using undefined variables**\n\n```ts\n// This is WRONG - these variables don\'t exist!\nexport default new Api("badExampleApi", [\n  new PostgreSQL("insert_data", "postgres-integration-id", {\n    statement: ({\n      SelectedCustomerIdVar,\n      ProductNameInput,\n      IssueTypeDropdown,\n    }) =>\n      `INSERT INTO issues VALUES (${SelectedCustomerIdVar.value}, \'${ProductNameInput.value}\', \'${IssueTypeDropdown.selectedOptionValue}\')`,\n    // \u274C ERROR: SelectedCustomerIdVar, ProductNameInput, IssueTypeDropdown are not defined in scope!\n  }),\n]);\n```\n\n**\u274C WRONG: Mixing up variable names**\n\n```ts\n// Scope defines CustomerNameInput but API tries to use CustomerName\nexport default new Api("badExampleApi", [\n  new PostgreSQL("insert_data", "postgres-integration-id", {\n    statement: (\n      { CustomerName }, // \u274C ERROR: Should be CustomerNameInput\n    ) => `INSERT INTO issues VALUES (\'${CustomerName.value}\')`,\n  }),\n]);\n```\n\n**\u274C WRONG: Not destructuring function parameters**\n\n```ts\n// This is WRONG - you must destructure the parameters\nexport default new Api("badExampleApi", [\n  new PostgreSQL("insert_data", "postgres-integration-id", {\n    statement: (\n      state, // \u274C ERROR: Should destructure { CustomerNameInput }\n    ) => `INSERT INTO issues VALUES (\'${state.CustomerNameInput.value}\')`,\n  }),\n]);\n```\n\n##### Creating and registering a Superblocks API\n\nCreate the API by adding the myApi.ts file:\n\n```ts\n// /pages/Page1/apis/myApi.ts\n\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n\nexport default new Api("myApi", [\n  new JavaScript("retrieve_orders", {\n    fn: () => {\n      return [\n        {\n          id: "ORD-001",\n          customerName: "John Smith",\n          total: 149.99,\n        },\n        {\n          id: "ORD-002",\n          customerName: "Sarah Jones",\n          total: 89.5,\n        },\n      ];\n    },\n  }),\n]);\n```\n\nThen register the myApi API in the scope file:\n\n```ts\n// /pages/Page1/scope.ts\n\nimport { createSbScope, SbApi } from "@superblocksteam/library";\n\nexport const Page1Scope = createSbScope(\n  () => ({\n    // Register the API in the scope\n    retrieveOrdersApi: SbApi({}),\n  }),\n  {\n    name: "Page1",\n  },\n);\n\nexport const Page1 = Page1Scope.entities;\n```\n\nThen use the API in your page component:\n\n```tsx\n// /pages/Page1/index.tsx\n\nimport {\n  SbPage,\n  SbSection,\n  SbColumn,\n  SbButton,\n  SbTable,\n  sbComputed,\n  SbEventFlow,\n  registerPage,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n  const { retrieveOrdersApi } = Page1;\n\n  return (\n    <SbPage name="Page1" height={Dim.fill()} width={Dim.fill()}>\n      <SbSection height={Dim.fill()}>\n        <SbColumn width={Dim.fill()}>\n          <SbButton\n            // APIs can be invoked with the SbEventFlow API\n            onClick={SbEventFlow.runApis([retrieveOrdersApi])}\n            label="Fetch Data"\n          />\n          {/* Access API response using sbComputed */}\n          <SbTable tableData={sbComputed(() => retrieveOrdersApi.response)} />\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\n##### Referencing the output of a previous block\n\nThink hard about how you access the output of previous steps. You MUST use the output property of the previous step variable. There is no other way to access the output of a previous step (other than using a Variable block, but that is not what you want in this case and should only be used in very specific cases).\n\n```ts\n// Path to this api would be: /pages/Page1/apis/getOrdersApi.ts\n\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n\nexport default new Api("getOrdersApi", [\n  new JavaScript("retrieve_orders", {\n    fn: () => {\n      return [\n        {\n          id: 1,\n          customer: "John Smith",\n          date: "2024-01-15",\n          total: 199.99,\n          status: "Pending",\n        },\n        {\n          id: 2,\n          customer: "Jane Doe",\n          date: "2024-01-14",\n          total: 149.99,\n          status: "Shipped",\n        },\n        {\n          id: 3,\n          customer: "Bob Wilson",\n          date: "2024-01-13",\n          total: 299.99,\n          status: "Delivered",\n        },\n      ];\n    },\n  }),\n  new JavaScript("format_orders", {\n    fn: ({ retrieve_orders }) => {\n      return retrieve_orders.output.map((order) => ({\n        ...order,\n        date: new Date(order.date).toLocaleDateString(),\n      }));\n    },\n  }),\n]);\n```\n\nThen you would register the API in your scope file and use it in your page component:\n\n```ts\n// /pages/Page1/scope.ts\nexport const Page1Scope = createSbScope(\n  () => ({\n    getOrdersApi: SbApi({}),\n  }),\n  {\n    name: "Page1",\n  },\n);\n```\n\n```tsx\n// /pages/Page1/index.tsx\nimport {\n  SbPage,\n  SbSection,\n  SbColumn,\n  SbTable,\n  sbComputed,\n  registerPage,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n  const { getOrdersApi } = Page1;\n\n  return (\n    <SbPage name="Page1" height={Dim.fill()} width={Dim.fill()}>\n      <SbSection height={Dim.fill()}>\n        <SbColumn width={Dim.fill()}>\n          <SbTable tableData={sbComputed(() => getOrdersApi.response)} />\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\n##### Ensuring variable existence in application\n\n**\u{1F6A8} CRITICAL**: APIs cannot create their own variables - they only access what already exists in page scope!\n\nWhen creating an API that references variables like `FirstNameInput`, `LastNameInput`, and `SelectedUserIdVar`, these variables MUST exist in your page scope BEFORE you write the API. APIs don\'t define parameters - they inherit scope.\n\n**Mandatory Flow: Scope \u2192 Components \u2192 APIs**\n\n**STEP 1: Create variables in scope FIRST** (APIs cannot access variables that don\'t exist)\n\nSince you\'ve determined that we\'ll use input components to take in the first name and last name, you MUST ensure that you use the same names for the entities in the `scope.ts` file as the variable names in the API.\n\n```ts\n// /pages/Page1/scope.ts\n\nimport {\n  createSbScope,\n  SbApi,\n  SbVariable,\n  SbVariablePersistence,\n  Global,\n} from "@superblocksteam/library";\n\nexport const Page1Scope = createSbScope<{\n  FirstNameInput: any;\n  LastNameInput: any;\n}>(\n  // register non-component entities in the scope\n  ({\n    entities: {\n      FirstNameInput,\n      LastNameInput,\n      handlePeopleUpdates,\n      SelectedUserIdVar,\n    },\n  }) => ({\n    handlePeopleUpdatesApi: SbApi({}),\n    SelectedUserIdVar: SbVariable({\n      defaultValue: Global.user.id,\n      persistence: SbVariablePersistence.TEMPORARY,\n    }),\n  }),\n  // configure page options\n  {\n    name: "Page1",\n  },\n);\n\nexport const Page1 = Page1Scope.entities;\n```\n\nThen, use the variables in your page component:\n\n```tsx\n// /pages/Page1/index.tsx\n\nimport {\n  SbPage,\n  SbInput,\n  SbEventFlow,\n  registerPage,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n  const {\n    handlePeopleUpdatesApi,\n    FirstNameInput,\n    LastNameInput,\n    SelectedUserIdVar,\n  } = Page1;\n\n  return (\n    <SbPage name="Page1">\n      <SbInput\n        label="First Name"\n        bind={FirstNameInput}\n        minLength={1}\n        inputType="TEXT"\n      />\n      <SbInput\n        label="Last Name"\n        bind={LastNameInput}\n        minLength={1}\n        inputType="TEXT"\n      />\n      {/* The rest of the page... */}\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\nFinally, create the API that references these variables:\n\n```ts\n// /pages/Page1/apis/handlePeopleUpdatesApi.ts\n\nimport {\n  Api,\n  JavaScript,\n  Python,\n  Databricks,\n  Snowflake,\n  PostgreSQL,\n  RestApi,\n  Email,\n  Conditional,\n  TryCatch,\n  Variables,\n  Loop,\n  Parallel,\n  Throw,\n  Return,\n} from "@superblocksteam/library";\n\nexport default new Api("handlePeopleUpdatesApi", [\n  new Conditional("validate", {\n    if: {\n      when: ({ FirstNameInput, LastNameInput }): boolean =>\n        !FirstNameInput.isValid || !LastNameInput.isValid,\n      then: [\n        new Throw("reject", {\n          error: "either the first name or last name is invalid",\n        }),\n      ],\n    },\n  }),\n  new PostgreSQL("update", "your-postgresql-integration-id", {\n    statement: ({ FirstNameInput, LastNameInput, SelectedUserIdVar }) =>\n      `UPDATE people SET first_name = \'${FirstNameInput.value}\', last_name = \'${LastNameInput.value}\' WHERE id = ${SelectedUserIdVar.value}`,\n  }),\n]);\n```\n\n#### The Superblocks API TypeScript Type\n\nBelow is the full TypeScript spec for the APIs you create:\n\n````ts\n// @superblocksteam/library\n\nexport type JsonValue =\n  | undefined\n  | null\n  | number\n  | string\n  | boolean\n  | JsonValue[]\n  | object;\nexport type State = { [key: string]: JsonValue };\nexport type Binding<T> = T | ((state: State) => T);\ntype Integrations = { id: string; description: string; metadata: JsonValue }[];\n\nclass Block {\n  constructor(name: string) {}\n  public run(): { output: JsonValue } {\n    /* ... */\n  }\n}\n\nclass Integration extends Block {\n  constructor(name: string, integration_id: string) {}\n}\n\ntype State = Record<string, JsonValue>;\n\nclass JavaScript extends Integration {\n  constructor(\n    name: string,\n    config: {\n      fn: (\n        {\n          /* ... */\n        },\n      ) => JsonValue;\n    },\n  ) {\n    super(name, "javascript");\n  }\n}\n\nclass Python extends Integration {\n  constructor(\n    name: string,\n    config: {\n      // We want to just put the python function body here. The scope is the same as it would be if it were a JavaScript integration.\n      fn: string;\n    },\n  ) {\n    super(name, "python");\n  }\n}\n\nclass Databricks extends Integration {\n  static integrations: Integrations = [\n    /* ... */\n  ];\n\n  /**\n   * @param {string} name           The name of the block.\n   * @param {string} integration_id The id of the integration.\n   * @param {object} config         The config object.\n   * @returns {void}\n   */\n  constructor(\n    name: string,\n    integration_id: string,\n    config: {\n      statement: Binding<string>;\n    },\n  ) {\n    super(name, integration_id);\n  }\n}\n\nclass Snowflake extends Integration {\n  static integrations: Integrations = [\n    /* ... */\n  ];\n\n  /**\n   * @param {string} name           The name of the block.\n   * @param {string} integration_id The id of the integration.\n   * @param {object} config         The config object.\n   * @returns {void}\n   */\n  constructor(\n    name: string,\n    integration_id: string,\n    config: {\n      statement: Binding<string>;\n    },\n  ) {\n    super(name, integration_id);\n  }\n}\n\nclass PostgreSQL extends Integration {\n  static integrations: Integrations = [\n    /* ... */\n  ];\n\n  /**\n   * @param {string} name           The name of the block.\n   * @param {string} integration_id The id of the integration.\n   * @param {object} config         The config object.\n   * @returns {void}\n   */\n  constructor(\n    name: string,\n    integration_id: string,\n    config: {\n      statement: Binding<string>;\n    },\n  ) {\n    super(name, integration_id);\n  }\n}\n\nclass RestApi extends Integration {\n  static integrations: Integrations = [\n    /* ... */\n  ];\n\n  constructor(\n    name: string,\n    // If you need to make a request that is detached from an integration, you MUST set this to "restapi".\n    integration: string = "restapi",\n    config: {\n      method: string;\n      url: Binding<string>;\n      headers?: { key: Binding<string>; value: Binding<string> }[];\n      params?: { key: Binding<string>; value: Binding<string> }[];\n      body?: Binding<string>;\n    },\n    openapi?: {\n      /**\n       * This is the path exactly as it appears in the OpenAPI spec.\n       *\n       * For example, if we had the following OpenAPI specification.\n       *\n       * paths:\n       *   /resources/{id}:\n       *     get: # ...\n       *\n       * If you determine that this is the path we should use, then the path would be "/resources/{id}".\n       */\n      path: string;\n    },\n  ) {\n    super(name, integration);\n  }\n}\n\nclass GitHub extends RestApi {\n  constructor(\n    name: string,\n    integration: string,\n    config: {\n      method: string;\n      url: Binding<string>;\n      headers?: { key: Binding<string>; value: Binding<string> }[];\n      params?: { key: Binding<string>; value: Binding<string> }[];\n      body?: Binding<string>;\n    },\n    openapi?: {\n      /**\n       * This is the path exactly as it appears in the OpenAPI spec.\n       *\n       * For example, if we had the following OpenAPI specification.\n       *\n       * paths:\n       *   /resources/{id}:\n       *     get: # ...\n       *\n       * If you determine that this is the path we should use, then the path would be "/resources/{id}".\n       */\n      path: string;\n    },\n  ) {\n    super(name, integration, config, openapi);\n  }\n}\n\nclass Jira extends RestApi {\n  constructor(\n    name: string,\n    integration: string,\n    config: {\n      method: string;\n      url: Binding<string>;\n      headers?: { key: Binding<string>; value: Binding<string> }[];\n      params?: { key: Binding<string>; value: Binding<string> }[];\n      body?: Binding<string>;\n    },\n    openapi?: {\n      /**\n       * This is the path exactly as it appears in the OpenAPI spec.\n       *\n       * For example, if we had the following OpenAPI specification.\n       *\n       * paths:\n       *   /resources/{id}:\n       *     get: # ...\n       *\n       * If you determine that this is the path we should use, then the path would be "/resources/{id}".\n       */\n      path: string;\n    },\n  ) {\n    super(name, integration, config, openapi);\n  }\n}\n\nclass Email extends Integration {\n  constructor(\n    name: string,\n    config: {\n      from: Binding<string>;\n      to: Binding<string>;\n      subject: Binding<string>;\n      cc?: Binding<string>;\n      bcc?: Binding<string>;\n      body?: Binding<string>;\n    },\n  ) {\n    super(name);\n  }\n}\n\nexport type Condition = {\n  when: boolean | ((state: State) => boolean);\n  then: Block[];\n};\n\nexport type Conditions = {\n  if: Condition;\n  elif?: Condition[];\n  else?: Block[];\n};\n\nclass Conditional extends Block {\n  constructor(name: string, config: Conditions) {\n    super(name);\n  }\n}\n\nclass 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    super(name);\n  }\n}\n\n/**\n * A Superblocks variable has the following access pattern:\n *\n * How to retrieve the value of a variable:\n * ```ts\n * CORRECT\n * my_variable.value\n *\n * // INCORRECT\n * my_variable\n * ```\n *\n * How to set the value of a variable:\n * ```ts\n * CORRECT\n * my_variable.set(value)\n *\n * // INCORRECT\n * my_variable = value\n * ```\n *\n */\n\nclass Variables extends Block {\n  constructor(\n    name: string,\n    variables: {\n      // The name of the variable.\n      key: string;\n      // The value of the variable.\n      value: Binding<JsonValue>;\n    }[],\n  ) {\n    super(name);\n  }\n}\n\nclass Loop extends Block {\n  constructor(\n    name: string,\n    config: {\n      over: Binding<JsonValue[]>;\n      variables: {\n        // What the variable name for the current item is.\n        item: string;\n        // What the variable name for the current index is.\n        index: string;\n      };\n      blocks: Block[];\n    },\n  ) {\n    super(name);\n  }\n}\n\nclass Parallel extends Block {\n  constructor(\n    name: string,\n    config: {\n      over: Binding<JsonValue[]>;\n      variables: {\n        // What the variable name for the current item is.\n        item: string;\n      };\n      blocks: Block[];\n    },\n  ) {\n    super(name);\n  }\n}\n\nclass Throw extends Block {\n  constructor(\n    name: string,\n    config: {\n      error: Binding<JsonValue>;\n    },\n  ) {\n    super(name);\n  }\n}\n\nclass Return extends Block {\n  constructor(\n    name: string,\n    config: {\n      data: Binding<JsonValue>;\n    },\n  ) {\n    super(name);\n  }\n}\n\nclass Api {\n  constructor(\n    name: string,\n    steps: Block[],\n    authorization:\n      | {\n          type: "AUTHORIZATION_TYPE_APP_USERS";\n        }\n      | {\n          type: "AUTHORIZATION_TYPE_JS_EXPRESSION";\n          expression: Binding<boolean>;\n        } = { type: "AUTHORIZATION_TYPE_APP_USERS" },\n  ) {\n    /* ... */\n  }\n  public get response(): JsonValue {\n    /* ... */\n  }\n  public get error(): string | undefined {\n    /* ... */\n  }\n  public run(): void {\n    /* ... */\n  }\n  public cancel(): void {\n    /* ... */\n  }\n}\n````\n\n#### Rules for using Superblocks APIs\n\nThink hard about the following important rules for correctly using Superblocks APIs:\n\n- You MUST use a destructured object to access page scope variables in dynamic block fields. This syntax is NOT defining function parameters - it\'s accessing the inherited page scope.\n\n```ts\n// CORRECT: destructuring to access page scope variables that must already exist\n({ Dropdown1, TextInput1 }) => Dropdown1.selectedOptionsValue + TextInput1.value\n// \u2191 These variables (Dropdown1, TextInput1) must exist in your page scope!\n\n// INCORRECT: trying to use scope object directly\n(state) => state.Dropdown1.selectedOptionsValue + state.TextInput1.value\n// \u2191 This syntax doesn\'t work in Superblocks\n```\n\n- DO NOT reference variables that are not in scope or that don\'t exist. The ONLY things in scope are (1) the outputs of previous blocks that are in lexical scope and (2) page entities.\n\n- The result of each scope is the result of the last block in that scope. In the following example, the value of `sendEmail.response` is the result of the `return_summary` block. Use this information to carefully ensure that the last block in your API is the one that returns the value you want.\n\n```ts\nexport default new Api("sendEmailApi", [\n  new Email("send_email", {\n    from: "noreply@company.com",\n    to: "test@test.com",\n    subject: "Test Email",\n    body: "This is a test email",\n  }),\n  new JavaScript("return_summary", {\n    fn: () => "Email sent successfully!",\n  }),\n]);\n```\n\n- Block outputs are immutable. Do not mutate the output of a block.\n\n- Backend APIs CANNOT mutate frontend state inside of the API\n\n- APIs are registered in scope files using `SbApi()` and then accessed in page components by destructuring from the scope entities. Make sure you name the key used in registerScope the same as the imported API, but do not pass the imported Api into the SbApi() call.\n\n- To access API responses in your UI, use `sbComputed(() => apiName.response)` or `sbComputed(() => apiName.error)`.\n\n- You will not always be told which integrations to use in your API; you will have to determine that yourself based on the data you need to fetch.\n\n- Never add comments to code you (the ai) generate. User added comments are fine - leave those!\n';
 
 // ../../../vite-plugin-file-sync/dist/ai-service/prompts/generated/subprompts/superblocks-components-rules.js
 init_cjs_shims();

package/dist/index.js

@@ -393072,7 +393072,7 @@ init_cjs_shims();
 init_cjs_shims();
 var generated = {};
 try {
-  generated = await import("./generated-6TNBFOK2.js");
+  generated = await import("./generated-W6HVWB2O.js");
 } catch (_error) {
   getLogger().warn("[ai-service] Generated markdown modules not found. Run `pnpm generate:markdown` first.");
 }
@@ -418482,7 +418482,7 @@ var import_util28 = __toESM(require_dist3(), 1);
 // ../sdk/package.json
 var package_default = {
   name: "@superblocksteam/sdk",
-  version: "2.0.3-next.206",
+  version: "2.0.3-next.208",
   type: "module",
   description: "Superblocks JS SDK",
   homepage: "https://www.superblocks.com",
@@ -418524,8 +418524,8 @@ var package_default = {
     "@rollup/wasm-node": "^4.35.0",
     "@superblocksteam/bucketeer-sdk": "0.5.0",
     "@superblocksteam/shared": "0.9160.0",
-    "@superblocksteam/util": "2.0.3-next.206",
-    "@superblocksteam/vite-plugin-file-sync": "2.0.3-next.206",
+    "@superblocksteam/util": "2.0.3-next.208",
+    "@superblocksteam/vite-plugin-file-sync": "2.0.3-next.208",
     "@vitejs/plugin-react": "^4.3.4",
     axios: "^1.4.0",
     chokidar: "^4.0.3",
@@ -425499,7 +425499,7 @@ async function startVite({ app, httpServer: httpServer2, root: root2, mode, port
   };
   const isCustomBuildEnabled2 = await isCustomComponentsEnabled();
   const customFolder = path35.join(root2, "custom");
-  const cdnUrl = "https://assets-cdn.superblocks.com/library/2.0.3-next.206";
+  const cdnUrl = "https://assets-cdn.superblocks.com/library/2.0.3-next.208";
   const env3 = loadEnv(mode, root2, "");
   const hmrPort = await getFreePort();
   const hmrOptions = {

package/oclif.manifest.json

@@ -571,5 +571,5 @@
       "strict": true
     }
   },
-  "version": "2.0.3-next.206"
+  "version": "2.0.3-next.208"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/cli",
-  "version": "2.0.3-next.206",
+  "version": "2.0.3-next.208",
   "type": "module",
   "description": "Official Superblocks CLI",
   "homepage": "https://www.superblocks.com",
@@ -42,9 +42,9 @@
   "devDependencies": {
     "@eslint/js": "^9.16.0",
     "@oclif/test": "^4.1.11",
-    "@superblocksteam/sdk": "2.0.3-next.206",
+    "@superblocksteam/sdk": "2.0.3-next.208",
     "@superblocksteam/shared": "0.9160.0",
-    "@superblocksteam/util": "2.0.3-next.206",
+    "@superblocksteam/util": "2.0.3-next.208",
     "@types/babel__core": "^7.20.0",
     "@types/chai": "^4",
     "@types/fs-extra": "^11.0.1",