@blotout/qinto-cli 0.1.28 → 0.1.30

package/README.md

@@ -504,6 +504,17 @@ What a publish does, in order:
 Publishing installs nothing. Install the new version with `qinto app install` (below); the last line of the output
 prints that command with the version filled in.
 
+**Source snapshot.** Every publish also uploads the app's source with the version: the text files in the app directory, without
+what a `.gitignore` names (in the app directory, a folder below it, or the enclosing git repository), dot-prefixed folders and files (`.git`, `.qinto`, `.env`, `.wrangler`), `node_modules`, `coverage`, `test-results`,
+`playwright-report`, `*.tsbuildinfo`, `*.log`, `npm-debug.log*`, `wrangler.jsonc`, binary files, and symbolic links. The
+owners and developers of the app's organization can read it in the Qinto platform. When you submit the version to the app store,
+the Blotout reviewers can read it too. A source above 10 MiB is refused, and the error names the largest files so that you can
+add them to `.gitignore`.
+
+The snapshot is the record of the source a version was built from. A version without a source snapshot cannot be submitted to
+the app store. The Qinto platform refuses a publish from an older CLI that uploads no source. A version that an older CLI published
+has none: [update the CLI](#stay-up-to-date), publish again, and submit the new version.
+
 | Flag | What it does |
 | --- | --- |
 | `--bump <level>` | `patch` (default), `minor`, or `major`, from the highest ready version. |
@@ -593,6 +604,81 @@ serialized bytes, and one variable's values across every install of that app on
 manifest, the publish, the install, and the runtime envelope — is listed in
 [Qinto app limits](https://docs.blotout.io).
 
+## Install an app from the app store
+
+The app store lists the apps that Blotout approved for every team. The `store` commands find an app there and install it on
+one of your team's sites. They need a login and no developer organization.
+
+```sh
+qinto store search consent                         # apps that match a word
+qinto store show my-app                            # the store listing and its approved versions
+qinto store install my-app --site example.com      # the newest approved version
+```
+
+To put your own app in the app store, publish a version with `qinto app publish`, then fill in the store listing and submit the
+version in the Qinto platform. [Qinto app limits](https://docs.blotout.io) gives the listing limits, the submission rules, and
+when a submission needs a review by a person.
+
+### Search — `qinto store search [query...]`
+
+`search` lists the apps in the app store, sorted A to Z by name, 50 to a page. Without a query it lists every app. With a
+query, an app matches when its name contains every word, or when its tagline and description together contain every word. A
+query word matches a whole word and not the start of one, and common endings are ignored: `purchases` finds `purchase`, but
+`cons` does not find `consent`.
+
+Each row gives the slug, the name, the publisher, the categories, and the tagline. When more apps match, the last line prints the
+`--cursor` value for the next page.
+
+| Flag | What it does |
+| --- | --- |
+| `--category <category>` | List only the apps in one category: `advertising`, `analytics`, `consent_privacy`, `customer_data`, `email_sms`, `personalization`, `security`, or `developer_tools`. |
+| `--limit <limit>` | Page size, 1 to 200 (default 50). |
+| `--cursor <cursor>` | Start after the page that printed this cursor. |
+| `--json` | Print the apps and the next cursor as JSON. |
+
+### Show — `qinto store show <slug>`
+
+`show` prints one store listing: the name, the publisher, the tagline, the description, the features, and the facts the Qinto
+platform reads from the newest approved version. The facts are the consent category, the Site API scopes, the event data, the flows, the
+vendors, the AI tools, and the roles. A table of the approved versions follows, newest first, with at most 50 versions. `--json`
+prints the listing as JSON.
+
+`show` exits with an error for an app that is not in the app store, even when the app exists. An app is
+not in the app store after its developer or Blotout removes it from the app store, while Blotout has the app suspended, and
+when it has no approved version at or above the minimum version that Blotout set for the app.
+
+### Install — `qinto store install <slug> --site <site>`
+
+`store install` puts an app from the app store on a site. It takes the flags of [`qinto app install`](#install--qinto-app-install-slug---site-site),
+and it asks for the same acceptances. Without `--version` it installs the newest version the site may run.
+
+```sh
+qinto store install my-app --site example.com                  # the newest approved version
+qinto store install my-app --site example.com --version 1.4.1  # a specific approved version
+```
+
+The first install of an app on a site records how the site got the app, and that record decides which versions the site may
+run afterwards:
+
+- When a member of the app's organization installs the app, the site may run every ready version.
+- When the site manager installs through the developer's install link, the site may run every ready version.
+- When the site gets the app from the app store, the site may run only approved versions.
+
+The Qinto platform checks these in that order, and `qinto app install` and `qinto store install` go through the same check. A
+member of the app's organization who runs `store install` therefore gets a site that may run every ready version. When the
+manager of a store site later installs through the developer's install link, the site may run every ready version from then on.
+
+The install fails when the site may not run the version, and the CLI prints the reason the Qinto platform gives. The Qinto
+API returns status 409 with one of these error kinds:
+
+| Error | Meaning |
+| --- | --- |
+| `version_not_approved` | The site got the app from the app store, and the named version is not approved. `qinto store show <slug>` lists the approved versions. |
+| `version_below_minimum` | Blotout set a minimum version for the app, and the named version is below it. |
+| `version_not_offered` | Blotout has suspended the app, and the named version was published during the suspension. |
+| `app_suspended` | Blotout has suspended the app. No site can install it until Blotout lifts the suspension. |
+| `app_taken_down` | Blotout has taken the app down. It takes no new install. |
+
 ## Built for humans and agents alike
 
 Every interactive path has a non-interactive equivalent. This is a standing rule for every current and future command: