Description
In-App Marketplace Installation lets a Dots user acquire and materialize a compatible Marketplace listing without leaving the Marketplace module. On a listing detail page, the injected storefront environment enables an interactive install buy box rather than the public website’s route-based purchase card. The install modal guides the user through connection, configuration, payment when required, and streamed progress. It can distinguish a first install from an update and exposes cancellation and uninstall operations through the same typed client family.
The browser client talks to the local @dots/api install surface for orchestration and to the hosted Marketplace for identity, purchase, entitlement, and version delivery. Progress arrives as server-sent events adapted into an AsyncIterable, allowing the shared React state machine to render real stages instead of guessing from a single request. The hosted install gateway verifies entitlement and serves the canonical version envelope to the trusted out-of-process consumer.
Selling Points
- Keeps discovery, purchase, configuration, and installation in one in-app workflow.
- Streams meaningful progress events for long-running materialization steps.
- Supports update, cancellation, uninstall, and installed-state reads alongside first install.
- Reuses the same shared listing UI while changing capabilities through an injected environment.
- Preserves hosted entitlement checks without exposing Marketplace storage credentials locally.
User Story
A Dots user opens a Marketplace listing inside the app and clicks Install. If the local app is not connected to the Marketplace account, the modal first presents the connection gate. The user selects required configuration, completes payment if the listing is paid, and watches validation, download, placement, and completion progress. On a later visit, the same surface recognizes the installation and offers an update or uninstall rather than another blind install.
Extension Surface
The capability is extensible because listing-type handlers and configuration behavior are mediated by Dots’ install orchestration, while the browser contract remains stable. packages/marketplace-client/src/install/schema.ts defines the shared install request and progress shapes, and packages/marketplace-storefront/src/environment/types.ts injects commerce and install-account seams for the in-app host. Extensibility is bounded: a listing must use a supported payload type and may not write arbitrary files outside its type’s installer rules.
Capabilities & Limits
The flow can connect a Marketplace identity, configure a supported listing, purchase it, stream installation progress, update an installed version, cancel an active run, uninstall, and read installed state. It keeps public website and in-app actions distinct without forking the listing page.
It does not make the hosted website install into an unknown local workspace, bypass entitlement, or accept arbitrary payload layouts. The website environment intentionally disables the install capability, and a client losing its SSE stream must resolve state through the local install service rather than infer completion.
Implementation Map
packages/marketplace-storefront/src/components/listing/buybox/InstallModal.tsxpackages/marketplace-storefront/src/data/install.tspackages/marketplace-client/src/install/install.tspackages/marketplace-client/src/install/schema.tsapps/marketplace/src/routes/install-gateway.ts