wirl 0.1.1 → 0.2.1

package/README.md

@@ -1,106 +1,58 @@
-# Wirl
+# wirl
 
-Email sequence automation for developers.
-
-## Installation
+Deploy an internal app somewhere real, privately. One command puts the folder you are in on a URL that only your company can open.
 
 ```bash
-npm install wirl
+npx wirl login            # a link and a code; approve in the browser
+npx wirl init my-tool --server
+cd my-tool
+npx wirl dev              # runs it here, signed in as a stub user
+npx wirl preview          # a private address to look at it before it is live
+npx wirl deploy           # builds, scans, deploys; prints the URL
+npx wirl share dana@company.com
 ```
 
-## Quick Start
-
-```typescript
-import Wirl from 'wirl';
-
-const wirl = new Wirl({
-  apiKey: 'sk_test_...',
-  baseUrl: 'https://your-wirl-instance.vercel.app'
-});
-
-// Track events
-await wirl.track({
-  email: 'user@example.com',
-  event: 'user.signup',
-  properties: { plan: 'pro' }
-});
-
-// Update contact properties
-await wirl.identify({
-  email: 'user@example.com',
-  properties: {
-    name: 'John Doe',
-    company: 'Acme Inc'
-  }
-});
-
-// Manually trigger a sequence
-await wirl.trigger({
-  email: 'user@example.com',
-  sequence: 'Welcome Sequence'
-});
-
-// Remove from a sequence
-await wirl.exit({
-  email: 'user@example.com',
-  sequence: 'Welcome Sequence'
-});
-```
+`npx` fetches the CLI from npm the first time and needs no install beyond Node 22.13 or later; in a terminal npm first asks "Ok to proceed? (y)": answer y. Elsewhere in this README a command is written `wirl <command>`, for short: run it as `npx wirl <command>`, or run `npm install -g wirl` once and use plain `wirl`. If your npm registry does not carry wirl, or to run exactly the build app.wirl.dev serves, install from app.wirl.dev instead: `npm install -g https://app.wirl.dev/cli/wirl.tgz`, and run plain `wirl`.
 
-## API
+Sign in with your work Google account and you are in your company's workspace. Anything a colleague deploys there is yours to open, and nobody outside the company can. A personal account gets a space of its own.
 
-### `new Wirl(options)`
+## What an app is
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `apiKey` | string | Yes | Your Wirl API key |
-| `baseUrl` | string | No | API base URL (default: `https://api.wirl.dev`) |
+A static folder needs nothing. A server-side app is one JavaScript module exporting `fetch(request, env)`:
 
-### `wirl.track(params)`
+- `env.DB` is a SQLite database that belongs to this app, in D1's prepared-statement shape. Rolling back code never rolls back data.
+- `x-wirl-user-id`, `x-wirl-role` and `x-wirl-org` say who the visitor is. wirl sets them after verifying the person; the browser cannot forge them.
+- Third-party APIs are called by their real URL. Declare the connection in `wirl.json`, and wirl attaches the key on the way out. The key never reaches the app, the agent that wrote it, or this machine.
+- A `public_paths` entry in `wirl.json` opens one path to the internet with no sign-in — for a Slack, Stripe or GitHub webhook — and wirl checks the sender's signature before the app is ever called.
 
-Track an event for a contact. Creates the contact if they don't exist.
+`wirl dev` runs the same bundle under Node, with the same database shape and headers, so what you see locally is what ships.
 
-```typescript
-await wirl.track({
-  email: 'user@example.com',
-  event: 'purchase.completed',
-  properties: { amount: 99.99 }
-});
-```
+## For coding agents
 
-### `wirl.identify(params)`
+`wirl init` writes `.claude/skills/wirl/SKILL.md` so Claude Code knows wirl is there. Agents that speak MCP can connect directly:
 
-Create or update a contact with properties.
-
-```typescript
-await wirl.identify({
-  email: 'user@example.com',
-  properties: { name: 'John', plan: 'enterprise' }
-});
+```bash
+claude mcp add --transport http wirl https://app.wirl.dev/mcp
 ```
 
-### `wirl.trigger(params)`
+That opens the browser once to sign in. The token an agent gets can deploy, roll back and pull, and cannot share apps, change who can open them, or touch connections, members or tokens. Ticking one box at consent grants full access. See the docs for what each scope covers.
 
-Manually enroll a contact in a sequence.
+## Everything else
 
-```typescript
-await wirl.trigger({
-  email: 'user@example.com',
-  sequence: 'Onboarding'
-});
+```bash
+npx wirl --help
 ```
 
-### `wirl.exit(params)`
+Orgs, members, connections, transfer, move, versions, rollback, pull, previews, logs, schedules, run.
 
-Remove a contact from an active sequence.
+## Versions
 
-```typescript
-await wirl.exit({
-  email: 'user@example.com',
-  sequence: 'Onboarding'
-});
-```
+The npm package and the control plane are versioned separately. `npx wirl` runs the latest CLI published to npm, and app.wirl.dev runs the build it was last deployed with, so either can be the newer. A CLI newer than the control plane says so where it can tell: `its control plane is older than this copy of wirl` (from `wirl migrations` and `wirl migrations adopt`), or `this control plane is older than sending wirl.json in the body, so it cannot take it` when a `wirl.json` is too large for a header. A CLI older than the control plane sends your whole `wirl.json` and says of a key it does not read that it `is not a key this version of wirl reads, so it is ignored`, though the control plane may read it; it checks `wirl.json` against its own rules before it uploads, so update the CLI (`npm install -g wirl@latest`, or `npx wirl@latest <command>`) when a deploy is refused on your machine for something the docs allow.
+
+## Requirements
+
+Node 22.13 or later. Credentials live in `~/.config/wirl/credentials.json` after `wirl login`, or in `WIRL_TOKEN` for CI and sandboxes.
 
-## License
+Docs: https://docs.wirl.dev. Site: https://wirl.dev. Issues: https://github.com/Brycce/wirl-platform/issues.
 
-MIT
+wirl is a hosted service; use of the CLI is governed by the terms at https://wirl.dev/terms.