@superblocksteam/cli 2.0.0-next.106 → 2.0.0-next.108

package/README.md

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

package/dist/{generated-PCEDCUUW.js → generated-KL6WAJNI.js}

@@ -27,7 +27,7 @@ init_cjs_shims();
 
 // ../../../vite-plugin-file-sync/dist/ai-service/prompts/generated/subprompts/superblocks-api.js
 init_cjs_shims();
-var content = '### 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#### Example of creating and then registering a Superblocks API:\n\nCRITICAL: 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.\n\nCreate the API by adding the myApi.ts file:\n\n```ts\n// Path to this API definition: /pages/Page1/apis/myApi.ts\n\nimport { Api, JavaScript } 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\nimport { createSbScope, SbApi } from "@superblocksteam/library";\n\nexport const Page1Scope = createSbScope(\n  () => ({\n    // Register the API in the scope\n    myApi: 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  // Destructure the API from the scope entities to access its response\n  const { myApi } = 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([myApi])}\n            label="Fetch Data"\n          />\n          {/* Access API response using sbComputed */}\n          <SbTable tableData={sbComputed(() => myApi.response)} />\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\n#### Example 2: API where a step references the output of a previous step\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/getOrders.ts\n\nimport { JavaScript, Api } from "@superblocksteam/library";\n\nexport default new Api("getOrders", [\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    getOrders: 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 { getOrders } = 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(() => getOrders.response)} />\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\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/types\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    // If you\'re using a path from an integration that has an OpenAPI spec, you MUST set this to true.\n    fromOpenApiSpec: boolean = false,\n  ) {\n    super(name, integration);\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(name: string, steps: Block[]) {}\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#### Example Usage\n\nBelow are examples of how you create Superblocks APIs, along with annotations to describe different pieces of functinality and expectations.\n\n##### Example 1: Simple API with conditional\n\n```ts\n// Path to this api would be: /pages/Page1/apis/getOrders.ts\n\nimport {\n  Conditional,\n  Condition,\n  PostgreSQL,\n  JavaScript,\n  Api,\n} from "@superblocksteam/library";\n\nexport default new Api("getOrders", [\n  new Conditional("my_conditional", {\n    if: {\n      when: true,\n      then: [\n        new PostgreSQL(\n          "retrieve_orders",\n          "" /* <- integration uuid goes here */,\n          {\n            statement: "SELECT * FROM orders",\n          },\n        ),\n      ],\n    },\n    else: [\n      new JavaScript("fallthrough", {\n        fn: () => "we did not execute the sql query",\n      }),\n    ],\n  }),\n]);\n```\n\nTo run register and run the API we defined above:\n\n```tsx\n// /pages/Page1/index.tsx\n\nimport {\n  SbPage,\n  SbApi,\n  SbSection,\n  SbColumn,\n  SbTable,\n  SbButton,\n  SbEventFlow,\n  registerPage,\n  showAlert,\n} from "@superblocksteam/library";\n\nimport getOrders from "./apis/getOrders";\n\nconst Page1 = () => (\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([getOrders])}\n        />\n        // ...\n        <SbTable>\n          // APIs are part of the state object just like components. tableData=\n          {(state) => state.getOrders.response}\n        </SbTable>\n      </SbColumn>\n    </SbSection>\n  </SbPage>\n);\n\nexport default registerPage(Page1, {\n  name: "MyPage",\n  // You register APIs just like you would SbVariables.\n  getOrders: SbApi(getOrders),\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 state object as the function parameter for dynamic block fields. The valid keys are (1) Superblocks entities (components, variables, etc) and (2) previous block outputs that are in the lexical scope. Example below:\n\n```ts\n// CORRECT: uses destructured state\n({ Dropdown1, TextInput1 }) => Dropdown1.selectedOptionsValue + TextInput1.value\n\n// INCORRECT: uses state object directly\n(state) => state.Dropdown1.selectedOptionsValue + state.TextInput1.value\n```\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("sendEmail", [\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```tsx\nimport {\n  SbPage,\n  SbSection,\n  SbColumn,\n  SbTable,\n  sbComputed,\n  registerPage,\n  SbApi,\n} from "@superblocksteam/library";\n\nconst scope = createSbScope<{\n  Table1: any;\n}>(\n  () => ({\n    sendEmail: SbApi({}),\n  }),\n  { name: "Page1" },\n);\n\nexport default registerPage(\n  () => (\n    <SbPage name="Page1" height={Dim.fill()} width={Dim.fill()}>\n      <SbSection height={Dim.fill()}>\n        <SbColumn width={Dim.fill()}>\n          // ...\n          <SbTable\n            bind={scope.entities.Table1}\n            tableData={sbComputed(() => API1.response)}\n          />\n          // ...\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  ),\n  scope,\n);\n```\n\n- Block outputs are immutable. Do not mutate the output of a block.\n\n- DO NOT reference variables that are not in scope. The ONLY things in scope in an API block are the outputs of previous steps and page entities.\n\n```tsx\nconst scope = createSbScope<{\n  someInput: any; // This is a state variable\n}>(\n  () => ({\n    someApi: SbApi(/* ... */),\n    someStateVariable: SbVariable(/* ... */),\n  }),\n  { name: "Page1" },\n);\n\nexport default registerPage(\n  () => (\n    <SbPage name="Page1" /* ... */>\n      <SbInput bind={scope.entities.someInput} /* ... */ />\n    </SbPage>\n  ),\n  scope,\n);\n```\n\n```ts\nexport default new Api("log_component_value", [\n  new JavaScript("log", {\n    fn: ({ someStateVariable, someInput }) => {\n      console.log(someStateVariable.value);\n      console.log(someInput.value);\n    },\n  }),\n]);\n```\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 content = '### 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#### Examples\n\n##### Creating and registering a Superblocks API\n\nCRITICAL: 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.\n\nCreate the API by adding the myApi.ts file:\n\n```ts\n// /pages/Page1/apis/myApi.ts\n\nimport { Api, JavaScript } 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    myApi: 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  // Destructure the API from the scope entities to access its response\n  const { myApi } = 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([myApi])}\n            label="Fetch Data"\n          />\n          {/* Access API response using sbComputed */}\n          <SbTable tableData={sbComputed(() => myApi.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/getOrders.ts\n\nimport { JavaScript, Api } from "@superblocksteam/library";\n\nexport default new Api("getOrders", [\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    getOrders: 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 { getOrders } = 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(() => getOrders.response)} />\n        </SbColumn>\n      </SbSection>\n    </SbPage>\n  );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\n##### Ensuring variable existance in application\n\nTo fullfill the user\'s request, you have created an api that updates a person\'s information. You are referencing `firstName`, `lastName`, and `userId` in the API. Since these variables are not previous blocks or variables from a variables block, you MUST ensure that they exist as part of the page\'s entities when you generate the `scope.ts` and `index.tsx` files.\n\n```ts\n// /pages/Page1/apis/handlePeopleUpdates.ts\n\nimport { Api, PostgreSQL } from "@superblocksteam/library";\n\nexport default new Api("handlePeopleUpdates", [\n  new Conditional("validate", {\n    if: {\n      when: ({ firstName, lastName }): boolean =>\n        !firstName.isValid || !lastName.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", "" /* <- integration uuid goes here */, {\n    statement: ({ firstName, lastName, userId }) =>\n      `UPDATE people SET first_name = \'${firstName.value}\', last_name = \'${lastName.value}\' WHERE id = ${userId.value}`,\n  }),\n]);\n```\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```tsx\n// /pages/Page1/scope.tsx\n\nimport { createSbScope, SbApi, SbVariable, Global } from "@superblocksteam/library";\n\nexport const Scope = createSbScope<{\n  firstName: any;\n  lastName: any;\n}>(\n  // register non-component entities in the scope\n  () => ({\n    handlePeopleUpdates: SbApi(/* ... */),\n    userId: 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 = Scope.entities;\n```\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\nexport default registerPage(\n  () => (\n    <SbPage name="Page1">\n      <SbInput\n        label="First Name"\n        bind={scope.entities.firstName}\n        minLength={1}\n        inputType="TEXT"\n      />\n      <SbInput\n        label="Last Name"\n        bind={scope.entities.lastName}\n        minLength={1}\n        inputType="TEXT"\n      />\n      /** * The rest of the page... */\n    </SbPage>\n  ),\n  scope,\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    // If you\'re using a path from an integration that has an OpenAPI spec, you MUST set this to true.\n    fromOpenApiSpec: boolean = false,\n  ) {\n    super(name, integration);\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(name: string, steps: Block[]) {}\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 state object as the function parameter for dynamic block fields.\n\n```ts\n// CORRECT: uses destructured state\n({ Dropdown1, TextInput1 }) => Dropdown1.selectedOptionsValue + TextInput1.value\n\n// INCORRECT: uses state object directly\n(state) => state.Dropdown1.selectedOptionsValue + state.TextInput1.value\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("sendEmail", [\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

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

package/oclif.manifest.json

@@ -571,5 +571,5 @@
       "strict": true
     }
   },
-  "version": "2.0.0-next.106"
+  "version": "2.0.0-next.108"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/cli",
-  "version": "2.0.0-next.106",
+  "version": "2.0.0-next.108",
   "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.0-next.106",
+    "@superblocksteam/sdk": "2.0.0-next.108",
     "@superblocksteam/shared": "0.9149.0",
-    "@superblocksteam/util": "2.0.0-next.106",
+    "@superblocksteam/util": "2.0.0-next.108",
     "@types/babel__core": "^7.20.0",
     "@types/chai": "^4",
     "@types/fs-extra": "^11.0.1",