add support for embeddable canvas in notebook (#18)

* notebook canvas updates

* notebook canvas readme updates

* notebook canvas missing update

* switch to CanvasCreatedWebhookV2Beta webhook

* fix unit test

* Update examples/chem-sync-local-flask/local_app/benchling_app/handler.py

Co-authored-by: damola-benchling <damola.shomoye@benchling.com>

---------

Co-authored-by: damola-benchling <damola.shomoye@benchling.com>

Author: keithmacaulay

examples/chem-sync-local-flask/README.md

@@ -79,7 +79,7 @@ https://brave-wombats-poke.loca.lt
 ### Benchling Prerequisites
 1. Access to a Benchling tenant, like `https://my-tenant.benchling.com`
 2. Ensure you've been granted access to the [Benchling Developer Platform Capability](https://help.benchling.com/hc/en-us/articles/9714802977805-Access-the-Benchling-Developer-Platform).
-3. This example also requires a [Lab Automation](https://www.benchling.com/resources/benchling-lab-automation) license.
+3. [Optional] If you'd like to render the App's UI in a Run, you'll need a [Benchling Connect](https://www.benchling.com/connect) license.
 4. [Molecule entities](https://help.benchling.com/hc/en-us/articles/9684254682893-Molecule-entity-overview) will need to be enabled on your tenant.
 5. [Global Apps](https://docs.benchling.com/docs/global-apps-faq) will need to be enabled on your tenant.
 
@@ -196,8 +196,8 @@ expects a few configuration items:
 1. A folder
 2. A molecule entity schema with two decimal fields
 
-The `features` section of `manifest.yaml` also states that our App will render
-its UI on an `ASSAY_RUN`. So we'll also need:
+We declare two `features` in the `manifest.yaml` so that our App can render
+its UI as a `CANVAS` (e.g. within the Notebook) or on an `ASSAY_RUN`. If you'd like to use a Run, we'll also need:
 1. An Lab Automation run schema
 
 #### Folder
@@ -221,9 +221,9 @@ The created molecule schema should look something like this:
 _Note: The names can be different, and the schema is allowed to have additional fields.
 As long as it's for a `Molecule` entity, and has at least two `Decimal` fields._
 
-#### Lab Automation Run Schema
+#### [Optional] Lab Automation Run Schema
 
-Create a new lab automation run schema in the registry.
+If using a Run, create a new lab automation run schema in the registry.
 
 ![image info](./docs/create-run-schema.gif)
 
@@ -235,7 +235,7 @@ The values of the data in Benchling can then be changed without updating App cod
 Let's update our configuration to:
 1. Specify a folder for syncing sequences
 2. Link a molecule schema and fields for the synced chemicals
-3. Select an assay run schema to associate with our Benchling App
+3. [Optional] If using a Run, select an assay run schema to associate with our Benchling App
 
 ![image info](./docs/update-app-config.gif)
 
@@ -249,12 +249,19 @@ Let's grant some access by adding the Benchling App to an organization.
 ## Running the App - Syncing a Chemical
 
 1. Create a new notebook entry
-2. Insert a run of the schema linked in App Config
-3. Create the Run
-4. Enter a valid chemical name to search for, such as `acetaminophen`
-5. Click "Search Chemicals"
-6. After reviewing the preview, click "Create Molecule"
-7. Click the linked entity to view it in Benchling
+2. Insert a Canvas  
+3. Enter a valid chemical name to search for, such as `acetaminophen`
+4. Click "Search Chemicals"
+5. After reviewing the preview, click "Create Molecule"
+6. Click the linked entity to view it in Benchling
+
+![image info](./docs/demo-notebook.gif)
+
+## [Optional] Running the App - via a Run
+
+1. Insert a Run of the schema linked in App Config
+2. Create the Run
+3. Continue with steps 3-6 above
 
 ![image info](./docs/demo.gif)
 

examples/chem-sync-local-flask/docs/demo-notebook.gif

@@ -25,7 +25,7 @@ def receive_webhooks(target: str) -> tuple[str, int]:  # noqa: ARG001
 
         # Important! To verify webhooks, we need to pass the body as an unmodified string
         # Flask's request.data is bytes, so decode to string. Passing bytes or JSON won't work
-        verify(app_def_id, request.data.decode("utf-8"), request.headers)
+        verify(app_def_id, request.data.decode("utf-8"), request.headers) # type: ignore[arg-type]
 
         logger.debug("Received webhook message: %s", request.json)
         # Dispatch work and ACK webhook as quickly as possible

examples/chem-sync-local-flask/local_app/app.py

@@ -2,14 +2,18 @@
 
 from benchling_sdk.apps.status.errors import AppUserFacingError
 from benchling_sdk.models.webhooks.v0 import (
+    CanvasCreatedWebhookV2Beta,
     CanvasInitializeWebhookV2,
     CanvasInteractionWebhookV2,
     WebhookEnvelopeV0,
 )
 
 from local_app.benchling_app.canvas_interaction import route_interaction_webhook
 from local_app.benchling_app.setup import init_app_from_webhook
-from local_app.benchling_app.views.canvas_initialize import render_search_canvas
+from local_app.benchling_app.views.canvas_initialize import (
+    render_search_canvas,
+    render_search_canvas_for_created_canvas,
+)
 from local_app.lib.logger import get_logger
 
 logger = get_logger()
@@ -31,6 +35,8 @@ def handle_webhook(webhook_dict: dict[str, Any]) -> None:
             render_search_canvas(app, webhook.message)
         elif isinstance(webhook.message, CanvasInteractionWebhookV2):
             route_interaction_webhook(app, webhook.message)
+        elif isinstance(webhook.message, CanvasCreatedWebhookV2Beta):
+            render_search_canvas_for_created_canvas(app, webhook.message.canvas_id)
         else:
             # Should only happen if the app's manifest requests webhooks that aren't handled in its code paths
             raise UnsupportedWebhookError(f"Received an unsupported webhook type: {webhook}")

examples/chem-sync-local-flask/local_app/benchling_app/handler.py

@@ -14,6 +14,10 @@
 from local_app.benchling_app.views.constants import SEARCH_BUTTON_ID, SEARCH_TEXT_ID
 
 
+def _canvas_builder_from_canvas_id(app: App, canvas_id: str) -> CanvasBuilder:
+    current_canvas = app.benchling.apps.get_canvas_by_id(canvas_id)
+    return CanvasBuilder.from_canvas(current_canvas)
+
 def render_search_canvas(app: App, canvas_initialized: CanvasInitializeWebhookV2) -> None:
     with app.create_session_context("Show Sync Search", timeout_seconds=20):
         canvas_builder = CanvasBuilder(
@@ -25,6 +29,13 @@ def render_search_canvas(app: App, canvas_initialized: CanvasInitializeWebhookV2
         app.benchling.apps.create_canvas(canvas_builder.to_create())
 
 
+def render_search_canvas_for_created_canvas(app: App, canvas_id: str) -> None:
+    with app.create_session_context("Show Sync Search", timeout_seconds=20):
+        canvas_builder = _canvas_builder_from_canvas_id(app, canvas_id)
+        canvas_builder.blocks.append(input_blocks())
+        app.benchling.apps.update_canvas(canvas_id, canvas_builder.to_update())
+
+
 def input_blocks() -> list[UiBlock]:
     return [
         MarkdownUiBlock(

examples/chem-sync-local-flask/local_app/benchling_app/views/canvas_initialize.py

@@ -7,11 +7,15 @@ features:
   - name: Sync Step
     id: sync_step
     type: ASSAY_RUN
+  - name: Sync Step
+    id: canvas_sync_step
+    type: CANVAS
 subscriptions:
   deliveryMethod: WEBHOOK
   messages:
   - type: v2.canvas.initialized
   - type: v2.canvas.userInteracted
+  - type: v2-beta.canvas.created
 configuration:
   - name: Sync Folder
     type: folder

examples/chem-sync-local-flask/manifest.yaml

@@ -1,3 +1,3 @@
 flask~=3.0.2
 # Cryptography extra needed for webhook verification
-benchling-sdk[cryptography]==1.13.0
+benchling-sdk[cryptography]==1.19.0

examples/chem-sync-local-flask/requirements.txt

@@ -2,15 +2,15 @@
 
 from benchling_sdk.apps.canvas.framework import CanvasBuilder
 from benchling_sdk.apps.framework import App
-from benchling_sdk.models.webhooks.v0 import CanvasInitializeWebhookV0
+from benchling_sdk.models.webhooks.v0 import CanvasInitializeWebhookV2
 
 from local_app.benchling_app.views.canvas_initialize import input_blocks, render_search_canvas
 
 
 class TestCanvasInitialize:
 
     def test_render_search_canvas(self) -> None:
-        initialize_webhook = MagicMock(CanvasInitializeWebhookV0)
+        initialize_webhook = MagicMock(CanvasInitializeWebhookV2)
         initialize_webhook.feature_id = "feature_id"
         initialize_webhook.resource_id = "resource_id"
         app = MagicMock(App)