@superblocksteam/cli 2.0.3-next.139 → 2.0.3-next.140
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -14,7 +14,7 @@ $ npm install -g @superblocksteam/cli
|
|
|
14
14
|
$ superblocks COMMAND
|
|
15
15
|
running command...
|
|
16
16
|
$ superblocks (--version)
|
|
17
|
-
@superblocksteam/cli/2.0.3-next.
|
|
17
|
+
@superblocksteam/cli/2.0.3-next.140 linux-x64 node-v20.19.0
|
|
18
18
|
$ superblocks --help [COMMAND]
|
|
19
19
|
USAGE
|
|
20
20
|
$ superblocks COMMAND
|
|
@@ -24,7 +24,7 @@ init_cjs_shims();
|
|
|
24
24
|
|
|
25
25
|
// ../../../vite-plugin-file-sync/dist/ai-service/prompts/generated/subprompts/superblocks-api.js
|
|
26
26
|
init_cjs_shims();
|
|
27
|
-
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 SbButton,\n SbTable,\n sbComputed,\n SbEventFlow,\n} from "@superblocksteam/library";\nimport { registerPage } 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>\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 </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 { SbPage, SbTable, sbComputed } from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n const { getOrders } = Page1;\n\n return (\n <SbPage>\n <SbTable tableData={sbComputed(() => getOrders.response)} />\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 Block {\n constructor(\n name: string,\n config: {\n fn: (\n {\n /* ... */\n },\n ) => JsonValue;\n },\n ) {\n super(name);\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 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 Block {\n constructor(\n name: string,\n config: {\n method:\n | "GET"\n | "POST"\n | "PUT"\n | "DELETE"\n | "PATCH"\n | "OPTIONS"\n | "HEAD"\n | "TRACE"\n | "CONNECT";\n url:\n | string\n | ((\n {\n /* ... */\n },\n ) => string);\n },\n ) {\n super(name);\n }\n}\n\nclass Email extends Block {\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 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 { SbPage, SbApi, SbTable, SbButton } from "@superblocksteam/library";\nimport { registerPage, showAlert } from "@superblocksteam/library";\n\nimport getOrders from "./apis/getOrders";\n\nconst Page1 = () => (\n <SbPage>\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 </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\nconst scope = createSbScope<{\n Table1: any;\n}>({ sendEmail: SbApi({}) }, { name: "Page1" });\n\nexport default registerPage(\n () => (\n <SbPage /* ... */>\n // ...\n <SbTable\n bind={scope.entities.Table1}\n tableData={sbComputed(() => API1.response)}\n />\n // ...\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 the state object.\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';
|
|
27
|
+
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 SbButton,\n SbTable,\n sbComputed,\n SbEventFlow,\n} from "@superblocksteam/library";\nimport { registerPage } 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>\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 </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 { SbPage, SbTable, sbComputed } from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n const { getOrders } = Page1;\n\n return (\n <SbPage>\n <SbTable tableData={sbComputed(() => getOrders.response)} />\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 Block {\n constructor(\n name: string,\n config: {\n fn: (\n {\n /* ... */\n },\n ) => JsonValue;\n },\n ) {\n super(name);\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 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 Block {\n constructor(\n name: string,\n config: {\n method:\n | "GET"\n | "POST"\n | "PUT"\n | "DELETE"\n | "PATCH"\n | "OPTIONS"\n | "HEAD"\n | "TRACE"\n | "CONNECT";\n url:\n | string\n | ((\n {\n /* ... */\n },\n ) => string);\n },\n ) {\n super(name);\n }\n}\n\nclass Email extends Block {\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 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 { SbPage, SbApi, SbTable, SbButton } from "@superblocksteam/library";\nimport { registerPage, showAlert } from "@superblocksteam/library";\n\nimport getOrders from "./apis/getOrders";\n\nconst Page1 = () => (\n <SbPage>\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 </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\nconst scope = createSbScope<{\n Table1: any;\n}>({ sendEmail: SbApi({}) }, { name: "Page1" });\n\nexport default registerPage(\n () => (\n <SbPage /* ... */>\n // ...\n <SbTable\n bind={scope.entities.Table1}\n tableData={sbComputed(() => API1.response)}\n />\n // ...\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 the state object.\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';
|
|
28
28
|
|
|
29
29
|
// ../../../vite-plugin-file-sync/dist/ai-service/prompts/generated/subprompts/superblocks-components-rules.js
|
|
30
30
|
init_cjs_shims();
|
|
@@ -36,7 +36,7 @@ var content3 = '# Custom Components\n\n- ULTRA CRITICAL: NEVER use Superblocks c
|
|
|
36
36
|
|
|
37
37
|
// ../../../vite-plugin-file-sync/dist/ai-service/prompts/generated/subprompts/superblocks-event-flow.js
|
|
38
38
|
init_cjs_shims();
|
|
39
|
-
var content4 = '# Event handlers with SbEventFlow\n\nRather than using standard browser event handlers, Superblocks provides a structured event handler action flow that allows you to run a series of events within the Superblocks system.\n\nImporting SbEventFlow:\n\n```jsx\nimport { SbEventFlow } from "@superblocksteam/library";\n```\n\nAll event handlers MUST be written using the `SbEventFlow` object.\n\nFor example, here we set the `isReady` state variable to `true` when the button is clicked:\n\n```jsx\n<SbButton onClick={SbEventFlow.setStateVar("isReady", true)} />\n```\n\n## SbEventFlow builder pattern\n\n`SbEventFlow` provides a number of functions that can be chained together using `SbEventFlow` which correspond to actions in the Superblocks system.\n\nYou should always use these dedicated functions for individual and sequential actions.\n\nImportant: DO NOT use .run() at the end of a chain of SbEventFlow functions, it is not needed and it will throw an error.\n\n```jsx\n<SbButton\n onClick={SbEventFlow.setQueryParams({ filter: "active" }, true)\n .setStateVar("isReady", true)\n .controlModal("loginModal", "close")\n\n // run APIs allows you to run Superblocks APIs by name using string arrays\n // Each runAPIs call executes the list of API names supplied in parallel\n .runApis([
|
|
39
|
+
var content4 = '# Event handlers with SbEventFlow\n\nRather than using standard browser event handlers, Superblocks provides a structured event handler action flow that allows you to run a series of events within the Superblocks system.\n\nImporting SbEventFlow:\n\n```jsx\nimport { SbEventFlow } from "@superblocksteam/library";\n```\n\nAll event handlers MUST be written using the `SbEventFlow` object.\n\nFor example, here we set the `isReady` state variable to `true` when the button is clicked:\n\n```jsx\n<SbButton onClick={SbEventFlow.setStateVar("isReady", true)} />\n```\n\n## SbEventFlow builder pattern\n\n`SbEventFlow` provides a number of functions that can be chained together using `SbEventFlow` which correspond to actions in the Superblocks system.\n\nYou should always use these dedicated functions for individual and sequential actions.\n\nImportant: DO NOT use .run() at the end of a chain of SbEventFlow functions, it is not needed and it will throw an error.\n\n```jsx\n<SbButton\n onClick={SbEventFlow.setQueryParams({ filter: "active" }, true)\n .setStateVar("isReady", true)\n .controlModal("loginModal", "close")\n\n // run APIs allows you to run Superblocks APIs by name using string arrays\n // Each runAPIs call executes the list of API names supplied in parallel\n .runApis([getUserData, getPermissions])\n\n // set a state variable\'s value\n .showAlert("Workflow complete", "success")\n .navigateTo({ url: "/dashboard", newWindow: false })}\n/>\n```\n\n#### Using RunJS (only when needed)\n\n`SbEventFlow` also has a special `runJS` event type that allows you to run any JavaScript in the browser.\n\nThis allows you to write more complex logic such as control flow.\n\nImportant:\n\n- The only things you can do in runJS is set state variables or set the public state of components, like modal.isOpen.\n- You CANNOT use SbEventFlow inside of a SbEventFlow.runJS function. If you do this, it won\'t work!\n- **State access in runJS**: Scope entities are accessible directly by their names, global state is accessible via imported globals (Global, Theme, Embed, Env).\n\nExample accessing scope entities:\n\n```jsx\n<SbButton\n label="Enable"\n buttonStyle={"SECONDARY_BUTTON"}\n onClick={SbEventFlow.runJS(() => {\n // Scope entities (variables, bound components) are accessible directly in runJS\n if (isUserAdmin.value) {\n // isUserAdmin is a bound component from scope\n myStateVar.value = true; // myStateVar is a state variable from scope\n myModal.isOpen = false; // myModal is a bound component from scope\n } else {\n console.log("This user was not an admin");\n }\n })}\n/>\n```\n\nExample accessing global state when needed:\n\n```jsx\n<SbButton\n label="Personalized Action"\n onClick={SbEventFlow.runJS(() => {\n // Import globals and access directly\n if (Global.user.role === "admin") {\n // Also access scope entities (bound components) directly\n adminPanel.isVisible = true; // adminPanel is a bound component from scope\n }\n console.log(`Welcome ${Global.user.name}!`);\n })}\n/>\n```\n\nAs mentioned above, you should only use `runJS` when the flow is too complex to represent using only chained event flow actions.\n\n### SbEvent Flow Usage Examples\n\n```typescript\nimport { SbEventFlow, sbComputed } from "@superblocksteam/library";\nimport { Page1 } from "./scope";\n\nconst { fetchUserData, saveUserData, userDataVariable } = Page1;\n\n// Navigation example\nSbEventFlow.navigateTo({ url: "https://example.com", newWindow: true });\n\n// Control UI components example\nSbEventFlow.controlModal("myModal", "open");\n\n// State management example\nSbEventFlow.setStateVar("userProfile", { name: "John", role: "Admin" });\n\n// Chaining multiple actions\nSbEventFlow.runApis([fetchUserData])\n .setStateVar(\n "userDataVariable",\n sbComputed(() => {\n fetchUserData.response;\n }),\n )\n .showAlert("Data loaded successfully", "success");\n\n// Conditional flow with success/error handlers\nconst successFlow = SbEventFlow.showAlert("Success!", "success");\nconst errorFlow = SbEventFlow.showAlert("An error occurred", "error");\nSbEventFlow.runApis([saveUserData], successFlow, errorFlow);\n```\n\n**SbEventFlow: Managing Events and Side Effects in Superblocks**\n\n## Important Syntax Rules\n\n- Always use function braces with SbEventFlow.runJS. Example: `SbEventFlow.runJS(() => { someFunction(); })` not `SbEventFlow.runJS(() => someFunction())`\n- SbEventFlow.runApis() accepts an array of direct API entity references. Example: `SbEventFlow.runApis([fetchUserData, saveUserData])`\n';
|
|
40
40
|
|
|
41
41
|
// ../../../vite-plugin-file-sync/dist/ai-service/prompts/generated/subprompts/superblocks-layouts.js
|
|
42
42
|
init_cjs_shims();
|
|
@@ -44,7 +44,7 @@ var content5 = '### Layout and Sizing in Superblocks\n\nAll layouts in Superbloc
|
|
|
44
44
|
|
|
45
45
|
// ../../../vite-plugin-file-sync/dist/ai-service/prompts/generated/subprompts/superblocks-page.js
|
|
46
46
|
init_cjs_shims();
|
|
47
|
-
var content6 = '### How to use SbPage\n\n- A page is a file that exports a default React component through the `registerPage` function.\n- Each page consists of two files: `index.tsx` (the page component) and `scope.ts` (the entity definitions).\n- For `export default registerPage(Page1, Page1Scope)`, Page1 is a function that returns a React component, and Page1Scope is the scope containing all entities.\n- A project consists of one or more pages. Each page is a directory in the `pages` directory.\n- Pages are registered in the `routes.json` file.\n\n### Page Structure\n\nEach page should have the following structure:\n\n**scope.ts** - Contains all entity definitions (variables, APIs, etc.):\n\n```ts\nimport {\n createSbScope,\n SbVariable,\n SbVariablePersistence,\n SbApi,\n SbText,\n} from "@superblocksteam/library";\n\nexport const Page1Scope = createSbScope<{\n Text1: any;\n}>(\n {\n // Define your entities here\n myVariable: SbVariable({\n defaultValue: "initial value",\n persistence: SbVariablePersistence.TEMPORARY,\n }),\n myApi: SbApi({}),\n },\n {\n name: "Page1",\n },\n);\n\nexport const Page1 = Page1Scope.entities;\n```\n\n**index.tsx** - Contains the page component:\n\n```tsx\nimport { SbPage, SbText, registerPage } from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nfunction Page() {\n // Destructure entities from the scope for easy access\n const { Text1, myVariable, myApi } = Page1;\n\n return (\n <SbPage>\n {/* Use entities in your components */}\n <SbText bind={Text1} text={sbComputed(() => myVariable.value)} />\n </SbPage>\n );\n}\n\nexport default registerPage(Page, Page1Scope);\n```\n\n## How component bindings work\n\nIf you need to reference a component directly to get access to some of its state, you must use a binding inside the page scope.\n\nComponent bindings allow you to:\n\n- Access component properties and state from other components and APIs\n- Create reactive relationships between components\n- Reference component values in `sbComputed` expressions\n\n### Setting up component bindings\n\n1. **Define the binding type in your scope**: Add the component type to the scope\'s type definitions:\n\n```ts\nexport const Page1Scope = createSbScope<{\n Text1: any;\n UserInput: any;\n}>(\n {\n // Your other entities (variables, APIs, etc.)\n myVariable: SbVariable({ defaultValue: "Hello" }),\n },\n {\n name: "Page1",\n },\n);\n```\n\n2. **Bind the component in your JSX**: Use the `bind` prop to connect the component to the binding:\n\n```tsx\nfunction Page() {\n const { Text1, UserInput, myVariable } = Page1;\n\n return (\n <SbPage>\n <SbInput bind={UserInput} placeholder="Enter your name" />\n <SbText\n bind={Text1}\n text={sbComputed(() => `Hello, ${UserInput.value}!`)}\n />\n </SbPage>\n );\n}\n```\n\n3. **Access component state**: Use `sbComputed` to access properties of bound components:\n\n```tsx\n// Access input value\ntext={sbComputed(() => UserInput.value)}\n\n// Access text content\ntext={sbComputed(() => Text1.text)}\n\n// Combine with other state\ntext={sbComputed(() => `${myVariable.value}: ${UserInput.value}`)}\n```\n\n### Common binding use cases\n\n- **Form inputs**: Access user input values to display or validate\n- **Dynamic content**: Reference one component\'s state to update another\n- **Conditional rendering**: Use component state to control visibility or styling\n\n### Page load events\n\nYou can fire callbacks when a page is loaded using the onLoad property of the Page component. You must use the SbEventFlow API for any actions you want to run inside onLoad.\n\nExample:\n\n```tsx\nimport {\n registerPage,\n SbEventFlow,\n SbPage,\n sbComputed,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n return (\n <SbPage\n onLoad={SbEventFlow.runJS(() => {\n console.log("Page loaded");\n })}\n >\n ...\n </SbPage>\n );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\nA very common and helpful usage of this callback is to run APIs using SbEventFlow to fetch data when the page loads. Example:\n\n```tsx\nimport {\n SbPage,\n registerPage,\n SbEventFlow,\n sbComputed,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n return <SbPage onLoad={SbEventFlow.runApis([
|
|
47
|
+
var content6 = '### How to use SbPage\n\n- A page is a file that exports a default React component through the `registerPage` function.\n- Each page consists of two files: `index.tsx` (the page component) and `scope.ts` (the entity definitions).\n- For `export default registerPage(Page1, Page1Scope)`, Page1 is a function that returns a React component, and Page1Scope is the scope containing all entities.\n- A project consists of one or more pages. Each page is a directory in the `pages` directory.\n- Pages are registered in the `routes.json` file.\n\n### Page Structure\n\nEach page should have the following structure:\n\n**scope.ts** - Contains all entity definitions (variables, APIs, etc.):\n\n```ts\nimport {\n createSbScope,\n SbVariable,\n SbVariablePersistence,\n SbApi,\n SbText,\n} from "@superblocksteam/library";\n\nexport const Page1Scope = createSbScope<{\n Text1: any;\n}>(\n {\n // Define your entities here\n myVariable: SbVariable({\n defaultValue: "initial value",\n persistence: SbVariablePersistence.TEMPORARY,\n }),\n myApi: SbApi({}),\n },\n {\n name: "Page1",\n },\n);\n\nexport const Page1 = Page1Scope.entities;\n```\n\n**index.tsx** - Contains the page component:\n\n```tsx\nimport { SbPage, SbText, registerPage } from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nfunction Page() {\n // Destructure entities from the scope for easy access\n const { Text1, myVariable, myApi } = Page1;\n\n return (\n <SbPage>\n {/* Use entities in your components */}\n <SbText bind={Text1} text={sbComputed(() => myVariable.value)} />\n </SbPage>\n );\n}\n\nexport default registerPage(Page, Page1Scope);\n```\n\n## How component bindings work\n\nIf you need to reference a component directly to get access to some of its state, you must use a binding inside the page scope.\n\nComponent bindings allow you to:\n\n- Access component properties and state from other components and APIs\n- Create reactive relationships between components\n- Reference component values in `sbComputed` expressions\n\n### Setting up component bindings\n\n1. **Define the binding type in your scope**: Add the component type to the scope\'s type definitions:\n\n```ts\nexport const Page1Scope = createSbScope<{\n Text1: any;\n UserInput: any;\n}>(\n {\n // Your other entities (variables, APIs, etc.)\n myVariable: SbVariable({ defaultValue: "Hello" }),\n },\n {\n name: "Page1",\n },\n);\n```\n\n2. **Bind the component in your JSX**: Use the `bind` prop to connect the component to the binding:\n\n```tsx\nfunction Page() {\n const { Text1, UserInput, myVariable } = Page1;\n\n return (\n <SbPage>\n <SbInput bind={UserInput} placeholder="Enter your name" />\n <SbText\n bind={Text1}\n text={sbComputed(() => `Hello, ${UserInput.value}!`)}\n />\n </SbPage>\n );\n}\n```\n\n3. **Access component state**: Use `sbComputed` to access properties of bound components:\n\n```tsx\n// Access input value\ntext={sbComputed(() => UserInput.value)}\n\n// Access text content\ntext={sbComputed(() => Text1.text)}\n\n// Combine with other state\ntext={sbComputed(() => `${myVariable.value}: ${UserInput.value}`)}\n```\n\n### Common binding use cases\n\n- **Form inputs**: Access user input values to display or validate\n- **Dynamic content**: Reference one component\'s state to update another\n- **Conditional rendering**: Use component state to control visibility or styling\n\n### Page load events\n\nYou can fire callbacks when a page is loaded using the onLoad property of the Page component. You must use the SbEventFlow API for any actions you want to run inside onLoad.\n\nExample:\n\n```tsx\nimport {\n registerPage,\n SbEventFlow,\n SbPage,\n sbComputed,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n return (\n <SbPage\n onLoad={SbEventFlow.runJS(() => {\n console.log("Page loaded");\n })}\n >\n ...\n </SbPage>\n );\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\nA very common and helpful usage of this callback is to run APIs using SbEventFlow to fetch data when the page loads. Example:\n\n```tsx\nimport {\n SbPage,\n registerPage,\n SbEventFlow,\n sbComputed,\n} from "@superblocksteam/library";\nimport { Page1, Page1Scope } from "./scope";\n\nconst Page1Component = () => {\n return <SbPage onLoad={SbEventFlow.runApis([getOrders])}>...</SbPage>;\n};\n\nexport default registerPage(Page1Component, Page1Scope);\n```\n\nIn this example, the `getOrders` API would be defined in the scope.ts file like this:\n\n```ts\n// In scope.ts\n\n// We register the api in createSbScope by creating a key\n// with the same name as the file, and SbApi({}) with an empty object\n// Note: We DO NOT import the api file. It\'s not necessary.\nexport const Page1Scope = createSbScope(\n () => ({\n getOrders: SbApi({}),\n }),\n {\n name: "Page1",\n },\n);\n```\n';
|
|
48
48
|
|
|
49
49
|
// ../../../vite-plugin-file-sync/dist/ai-service/prompts/generated/subprompts/superblocks-routes.js
|
|
50
50
|
init_cjs_shims();
|
package/dist/index.js
CHANGED
|
@@ -331012,7 +331012,7 @@ var import_dd_trace = __toESM(require_dd_trace2(), 1);
|
|
|
331012
331012
|
// ../sdk/package.json
|
|
331013
331013
|
var package_default = {
|
|
331014
331014
|
name: "@superblocksteam/sdk",
|
|
331015
|
-
version: "2.0.3-next.
|
|
331015
|
+
version: "2.0.3-next.140",
|
|
331016
331016
|
type: "module",
|
|
331017
331017
|
description: "Superblocks JS SDK",
|
|
331018
331018
|
homepage: "https://www.superblocks.com",
|
|
@@ -331042,8 +331042,8 @@ var package_default = {
|
|
|
331042
331042
|
"@rollup/wasm-node": "^4.35.0",
|
|
331043
331043
|
"@superblocksteam/bucketeer-sdk": "0.4.1",
|
|
331044
331044
|
"@superblocksteam/shared": "0.9108.0",
|
|
331045
|
-
"@superblocksteam/util": "2.0.3-next.
|
|
331046
|
-
"@superblocksteam/vite-plugin-file-sync": "2.0.3-next.
|
|
331045
|
+
"@superblocksteam/util": "2.0.3-next.140",
|
|
331046
|
+
"@superblocksteam/vite-plugin-file-sync": "2.0.3-next.140",
|
|
331047
331047
|
"@vitejs/plugin-react": "^4.3.4",
|
|
331048
331048
|
axios: "^1.4.0",
|
|
331049
331049
|
chokidar: "^4.0.3",
|
|
@@ -375626,7 +375626,7 @@ async function startVite({ app, httpServer: httpServer2, root: root2, mode, port
|
|
|
375626
375626
|
};
|
|
375627
375627
|
const isCustomBuildEnabled2 = await isCustomComponentsEnabled();
|
|
375628
375628
|
const customFolder = path21.join(root2, "custom");
|
|
375629
|
-
const cdnUrl = "https://assets-cdn.superblocks.com/library/2.0.3-next.
|
|
375629
|
+
const cdnUrl = "https://assets-cdn.superblocks.com/library/2.0.3-next.140";
|
|
375630
375630
|
const env3 = loadEnv(mode, root2, "");
|
|
375631
375631
|
const hmrPort = await getFreePort();
|
|
375632
375632
|
const hmrOptions = {
|
|
@@ -382333,7 +382333,7 @@ init_cjs_shims();
|
|
|
382333
382333
|
init_cjs_shims();
|
|
382334
382334
|
var generated = {};
|
|
382335
382335
|
try {
|
|
382336
|
-
generated = await import("./generated-
|
|
382336
|
+
generated = await import("./generated-I3FGMJLA.js");
|
|
382337
382337
|
} catch (_error) {
|
|
382338
382338
|
console.warn("Generated markdown modules not found. Run `pnpm generate:markdown` first.");
|
|
382339
382339
|
}
|
package/oclif.manifest.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@superblocksteam/cli",
|
|
3
|
-
"version": "2.0.3-next.
|
|
3
|
+
"version": "2.0.3-next.140",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Official Superblocks CLI",
|
|
6
6
|
"homepage": "https://www.superblocks.com",
|
|
@@ -42,9 +42,9 @@
|
|
|
42
42
|
"devDependencies": {
|
|
43
43
|
"@eslint/js": "^9.16.0",
|
|
44
44
|
"@oclif/test": "^4.1.11",
|
|
45
|
-
"@superblocksteam/sdk": "2.0.3-next.
|
|
45
|
+
"@superblocksteam/sdk": "2.0.3-next.140",
|
|
46
46
|
"@superblocksteam/shared": "0.9108.0",
|
|
47
|
-
"@superblocksteam/util": "2.0.3-next.
|
|
47
|
+
"@superblocksteam/util": "2.0.3-next.140",
|
|
48
48
|
"@types/babel__core": "^7.20.0",
|
|
49
49
|
"@types/chai": "^4",
|
|
50
50
|
"@types/fs-extra": "^11.0.1",
|