integration-tour 0.0.0-stage → 1.0.6

package/LICENSE.md

@@ -0,0 +1,17 @@
+# integration-tour license
+
+Copyright (c) 2026 Tyler Gelinas. All rights reserved.
+
+integration-tour is commercial software. You may install and run it free of charge for non-commercial purposes only, such as personal projects and learning. Commercial use, such as making videos for a company's docs, marketing, sales or support, or for a client, needs a current, paid license key. Videos made without a current key carry its "Made with integrationtour.com" watermark; a current key removes it.
+
+You may not:
+
+- remove, hide or change the watermark on videos made without a current license key, or get around its license check, or run a copy that has been changed to do so;
+- share your license key with anyone outside your organization;
+- copy, sell, sublicense or redistribute the package, or a changed copy of it, except as installed from npm for your own builds.
+
+Each license key is good through the last day it was sold for. After that day it stops working: the videos the package makes from then on carry the watermark, and commercial use needs a new key. The videos it made while the key was current stay yours, without it.
+
+The package includes open-source work under its own licenses: the Inter and JetBrains Mono fonts, under the SIL Open Font License 1.1 (see `fonts/`); js-yaml, under the MIT License (see `dist/js-yaml-LICENSE.txt`); and h264-mp4-encoder, under the MIT License (see `dist/h264-mp4-encoder-LICENSE.txt`), whose WebAssembly is built from minih264, dedicated to the public domain under CC0 1.0, and from libmp4v2, under the Mozilla Public License 1.1, whose source code is available under that license at https://github.com/TrevorSundberg/libmp4v2. It also installs `@resvg/resvg-js`, under the Mozilla Public License 2.0.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# integration-tour
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your API's integration videos, built from your OpenAPI spec in your own build pipeline, so they stay in step with the spec. An MCP server's work too, from the tools it lists. When the API changes, the videos change with it, and your edits stay.
+
+It's the command-line side of [Integration Tour](https://integrationtour.com/), the web app that turns a spec into an animated walkthrough of the calls a client makes. The app is where you build and edit a video; this package renders it again whenever your spec changes. It's free for non-commercial use: without a license key, its videos carry the "Made with integrationtour.com" watermark, as the app's do. Commercial use needs a paid key, which also removes it.
+
+## Try it with just your spec
+
+```
+integration-tour render openapi.yaml --out docs/videos
+integration-tour render https://mcp.context7.com/mcp
+```
+
+Given a spec, it makes a video of each of the top three flows the web app suggests for it, unedited, named after the flow: `create-customer-create-payment.mp4`. The app offers up to six to pick from: for any of the others, pick it there and pass its flow file with `--edits`. The spec can be a URL, and so can an MCP server's address, whose tools it reads by connecting to it; those videos go in the current folder unless `--out` says otherwise. For an Arazzo file, it's one per workflow. A Postman collection (format 2.0 or 2.1) works as a spec too, with its own variables' values. A video keeps its name however the spec comes to rank its flows; flows that share a short name take their whole name. A spec change can still add or drop flows; to keep a video and your edits, save a flow file from the app and pass it with `--edits`.
+
+## A video you've edited
+
+1. In the web app, load your spec, pick a flow, edit and brand it, then click **Generate from a command** under Export and **Download the flow file**. It holds your edits.
+2. Make the video from your spec, file or URL, with the flow file after `--edits`: `integration-tour render openapi.yaml --edits checkout.flow.yaml`. The app shows that command, with your spec's name or URL in it.
+
+## Keep it up to date
+
+Commit the flow file next to your spec, and run the same command in your build. `--edits` takes several flow files, or a folder of them: `--edits docs/flows/`. To leave off the watermark, give it your license key in `INTEGRATION_TOUR_LICENSE`, on GitHub as a repository secret. Without it the command runs all the same, and the videos carry the watermark.
+
+On GitHub, the workflow on [integrationtour.com/cli](https://integrationtour.com/cli) does it: a push that changes the spec or a flow file renders the videos again and commits them, and a pull request runs `check`, which fails when a spec change would lose part of a video.
+
+The workflow keeps the two apart. Pull requests, forks' included, are checked in a job that can only read the repo and never gets the key. Pushes are rendered in a job that can commit, and only its render step gets the key. The workflow runs an exact version of the package, so a new release reaches your repo only when you change the version in it.
+
+Other pipelines run the same commands, with the key in `INTEGRATION_TOUR_LICENSE`. A docs site built on Vercel, Netlify or Cloudflare Pages can render in its own build, with nothing committed:
+
+```json
+{ "scripts": { "prebuild": "integration-tour render openapi.yaml --edits docs/flows/ --out public/videos" } }
+```
+
+## Commands
+
+```
+integration-tour render <spec file or URL> [--edits <flow files or folder>] [--formats mp4,gif,html] [--out <folder>] [--allow-private-refs]
+integration-tour check <spec file or URL> [--edits <flow files or folder>] [--allow-private-refs]
+```
+
+Every command starts with the spec: a file or a URL (a GitHub file page works too), or an MCP server's URL. `--edits` takes the flow files of your edits, as many as you like, or a folder of them. `--out` is a folder, made if it isn't there:
+
+```
+integration-tour render openapi.yaml
+integration-tour render https://api.example.com/openapi.json --formats gif,mp4 --out videos/
+integration-tour render https://mcp.example.com/mcp --out docs/videos/
+integration-tour render openapi.yaml --edits checkout.flow.yaml
+integration-tour render openapi.yaml --edits docs/flows/ --formats gif --out docs/videos/
+integration-tour check openapi.yaml --edits docs/flows/
+```
+
+- `render` builds a video of each of the top three flows the spec suggests (an Arazzo file's workflows, every one), or with `--edits`, of each flow file, from the spec as it is now with the file's edits, and writes it into `--out` (by default, next to the flow file, or the spec; a URL's in the current folder). An edited video is named after its flow file: `checkout.flow.yaml` makes `checkout.mp4` (or `checkout.gif` and `checkout.html` when `--formats` asks for them), so links to them never break. It prints what didn't fit, and renders what's left. It says how many videos it's making and numbers each as it starts (`Video 2 of 3`), then lists each file as it's written; on a terminal it also says how far a GIF or an MP4 has got, which a pipeline's log leaves out.
+- `check` builds each video and exits with an error when a spec change lost a call, an edit or the failure a flow file shows. Without `--edits`, it checks that the spec's top three flows still build.
+
+`mp4`, what `render` makes unless `--formats` says otherwise, is an H.264 video at the flow file's resolution and 30 frames a second, for docs, slides, social posts and video players; it's silent. It draws every frame at full size: on a laptop, it takes about as long as the video lasts at 720p, and twice that at 1080p. `gif` is a looping, silent animation for READMEs. `html` is one self-contained file with its own player: text stays sharp at any size and payloads can be copied. Name the ones you want with `--formats`: `--formats gif`, or several, as in `--formats mp4,gif,html`. The workflow on the site makes HTML and GIF, which a repo shows as they are; add `mp4` to its `--formats` for an MP4 too.
+
+`--allow-private-refs` lets the spec's references reach this machine and private networks, which they otherwise don't (see below): pass it for a spec you trust that references an internal schema server.
+
+Both commands exit with 1 when something failed, and 2 when the command itself is wrong. `--help`, alone or after a command, prints a summary of them, and `--version` the package's version.
+
+## The flow file
+
+```yaml
+look: { resolution: 1080, code: curl }
+brand: { theme: light, color: "#4f46e5", logo: acme-logo.png }
+names: { client: Your checkout }
+scenes:
+  - title: Accept your first payment
+    subtitle: Three calls from sign-up to charge
+  - auth
+  - call: POST /v1/customers
+    operation: createCustomer
+    caption: Create the customer once, when they sign up.
+    request: { email: jenny@rosen.example }
+  - call: POST /v1/payment_intents
+    operation: createPaymentIntent
+    failure: 429
+  - call: POST /v1/payment_intents/{intent}/confirm
+    operation: confirmPaymentIntent
+  - webhook: payment_intent.succeeded
+  - summary
+```
+
+- The spec isn't in it: the command names the spec, so the same edits go with its file, its URL or a newer copy. Files the spec references are read from its repo, and only JSON and YAML files there; a link in the repo is followed only to one of those in the repo too. References written as full URLs are downloaded, but not from this machine or a private network, such as a cloud's metadata address, even by a redirect: a spec in a pull request could otherwise have your build fetch what only it can reach. References on the spec's own host are, and `--allow-private-refs` allows the rest. If a referenced file doesn't load, the run stops rather than make a video with parts missing, and says why. An older flow file's `spec:` line is read past.
+- An MCP server works as a spec: a file of the tools it lists (its `tools/list` result, or a merged document of its lists), or the server's own URL, which the run connects to as an MCP client to read its tools as they are now.
+- `scenes` is the video, in order. Each scene holds only what someone changed; everything else comes from the spec each time, so a new field or a reworded summary shows up on its own.
+- A call is named by its method and path, and by its operation id when the spec has one, so a renamed operation is still found. An MCP server's calls are named by method and name: `tools/list`, `tools/call search_flights`, `resources/read wayfare://airports`, `prompts/get plan_trip`. The same call can appear more than once.
+- Payload edits (`request`, `response`, a webhook's `payload`) are merged into what the spec gives, key by key: an edited field and a field the spec added both show. `null` removes a field.
+- `failure` shows that status failing on the call's first try, before it succeeds. It can also carry the failed attempt's own `caption`, payloads and `recovery` note.
+- The title, auth and summary scenes are made by the builder. One the list leaves out comes back when the spec still makes it, unless `deleted:` names it. An auth scene for security the spec adds later is added, and the report says so.
+- `brand.logo` is a PNG, JPEG, GIF or SVG file next to the flow file or in a folder below it, and in the repo, however a link leads to it. An SVG logo has to hold all it shows: one that links to an image file or another site is turned away.
+- `names` holds only the nodes someone renamed; the API's node otherwise keeps the spec's title.
+- For a flow from an Arazzo file, the spec to give is the Arazzo file, and `flow: arazzo:<workflowId>` names the workflow: its steps are the calls.
+- `version` is left out while the format is version 1. A later format will write it, and an older `integration-tour` that reads one asks to be upgraded rather than guessing.
+
+## The watermark and the license key
+
+Every video carries the "Made with integrationtour.com" watermark unless the run has a good license key. `render` checks the key in `INTEGRATION_TOUR_LICENSE` before it renders. With no key, or one that isn't ours, has been turned off or is past its last day, it renders all the same, with the watermark, and says why, so a lapsed key never fails your build. In a key's last two weeks, runs warn that it needs renewing. `check` writes no videos, so it never needs a key. Nothing it prints holds the key or the company it's for.
+
+A key is good through the last day it was sold for. The same key takes the watermark off videos exported from the web app: paste it under **Export** there.
+
+## Requirements
+
+Node 22 or later, on macOS, Linux or Windows: frames are drawn with resvg, which installs prebuilt. The fonts (Inter and JetBrains Mono) come with the package, so every machine draws the same frames. MP4s are encoded with minih264, compiled to WebAssembly and bundled into the package, so there's no ffmpeg or anything else to install. Logos can be PNG, JPEG, GIF or SVG.
+
+See [LICENSE.md](LICENSE.md) for the terms.