@ziprack/sdk 0.1.1 → 0.2.0

package/dist/broadcast/index.d.ts

@@ -1,5 +1,5 @@
 import type { Link } from '../core/link';
-import type { AckResult, JsonObject, LaunchRoom, RackEvent, RoomMember, RoomRole, RoomStatus } from '../core/types';
+import type { AckResult, JsonObject, LaunchRoom, RackEvent, RoomInvite, RoomMember, RoomRole, RoomStatus } from '../core/types';
 export declare const ROOM_CHANNEL = "$room";
 export type RoomEventName = 'presence' | 'state' | 'role' | 'status';
 export interface RoomEvents {
@@ -68,6 +68,13 @@ export declare class BroadcastApi {
         /** Locally known state (launch snapshot plus pushed updates). */
         snapshot: () => JsonObject;
     };
+    /**
+     * Where the next person scans to get in. Only the Rack knows its own host
+     * and join prefix, so it hands back the code and the URL; rendering them as
+     * a slide, a link or a QR is yours. Refused with `conflict` once the room is
+     * locked or closed, so a stale QR can be taken down.
+     */
+    invite(): Promise<AckResult<RoomInvite>>;
     /** Claim the facilitator role (opt_in rooms). */
     claim(): Promise<AckResult<{
         role: RoomRole;

package/dist/core/mock/MockRack.d.ts

@@ -131,6 +131,12 @@ export declare class MockRack {
     /** An earlier facilitator wins; a later optimistic one steps down. */
     private reconcileFacilitator;
     private onRoomMessage;
+    /**
+     * A mock room is two tabs of the dev server, so the invite is this page:
+     * scan it and the second tab joins over BroadcastChannel, exactly as the
+     * real join URL would.
+     */
+    private invite;
     private setRole;
     private publish;
     private stateSet;

package/dist/core/types.d.ts

@@ -69,6 +69,10 @@ export interface LaunchRoom {
     status: RoomStatus;
     mode: 'opt_in' | 'first_in' | 'roster';
 }
+export interface RoomInvite {
+    code: string;
+    url: string;
+}
 export interface LaunchBroadcast {
     room: LaunchRoom;
     role: RoomRole;

package/dist/docs/README.md

@@ -0,0 +1,52 @@
+# zipRACK Documentation
+
+zipRACK is a micro app framework: a Laravel host — **the Rack** — that runs sandboxed static web
+apps — **applets** — and services their capability requests over `postMessage`. An applet owns
+everything the participant sees. The Rack owns login, persistence, AI access, real-time coordination
+and reporting.
+
+These docs cover both halves. If you are building an applet, start with
+[Applet Packages](applet-packages.md). If you are standing up or maintaining a Rack, start with
+[Installation](installation.md).
+
+## Prologue
+
+- [Introduction](introduction.md) — the trust boundary, the core model, the objects
+- [Versioning](versioning.md) — the three version axes and why they never couple
+
+## Building an applet
+
+- [Applet Packages](applet-packages.md) — the zip, the installer rules, the starter
+- [The Manifest](manifest.md) — every field, every rule the validator enforces
+- [The JavaScript SDK](sdk.md) — `Rack.init()`, acks, errors, mock mode, testing
+- [zipRACK Studio](studio.md) — the visual builder, the derived manifest, the MCP server
+- [The Bridge Protocol](protocol.md) — the envelope, for anyone not using the SDK
+
+## Capabilities
+
+- [Authentication](auth.md) — `auth@1`
+- [Attempts](attempts.md) — `attempt@1`
+- [Activity](activity.md) — `activity@1`
+- [Database](database.md) — `db@1`
+- [Storage](storage.md) — `storage@1`
+- [AI](ai.md) — `ai@1`
+- [Broadcast](broadcast.md) — `broadcast@1`
+- [Media](media.md) — declared embeds, no capability required
+
+## Running a Rack
+
+- [Installation](installation.md) — composing a Rack from capability packages
+- [Security](security.md) — the sandbox, the CSP, the threats it does not cover
+- [Publishing](publishing.md) — install, capability diff, review queue, promotion, kill switch
+- [Reporting](reporting.md) — the admin API, CSV export, metrics
+- [Conformance](conformance.md) — proving a deployment is still a Rack
+
+## Extending
+
+- [Writing a Capability](extending.md) — the `Capability` interface, end to end
+
+---
+
+Also in this repository: [`ziprack-1-authoring.md`](ziprack-1-authoring.md), a one-page condensed
+brief suitable for dropping into an applet project as `CLAUDE.md`. The same content, expanded, is
+published to the CN IDEAS skills library as an instruction set.

package/dist/docs/activity.md

@@ -0,0 +1,140 @@
+# Activity — `activity@1`
+
+- [Introduction](#introduction)
+- [Declaring Activities](#declaring-activities)
+- [Emitting Statements](#emitting-statements)
+- [Activity Types](#activity-types)
+- [Metrics](#metrics)
+- [Designing for the Export](#designing-for-the-export)
+
+<a name="introduction"></a>
+## Introduction
+
+A **statement** is an append-only record that *an actor did a verb on an activity with a result*.
+It is the audit trail, and because every statement has the same shape, it is also the one export
+that works identically for every applet on every Rack.
+
+Statements are never updated and never deleted. Re-answering is normal: reporting reads the **last**
+`answered` statement per activity per attempt.
+
+`db@1` does not replace this. Statements are what happened; [records](database.md) are what is
+currently true.
+
+<a name="declaring-activities"></a>
+## Declaring Activities
+
+Every question you report on must be declared. At least one activity is required.
+
+```json
+"activities": [
+    { "id": "intro.connection", "type": "rating", "label": "How connected do you feel to patients?",
+      "scale": { "min": 1, "max": 6 }, "sequence": 1 },
+    { "id": "rd.corine.reaction", "type": "text", "label": "What stood out to you about Corine's story?",
+      "segment": "track", "sequence": 2 }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `id` | Required, max 150, unique. **This is the data contract.** |
+| `type` | Required, max 100. Drives how the admin renders and exports the value. |
+| `label` | Required, max 1000. Becomes the CSV header and the analysis heading. |
+| `scale` | Optional object, for `rating` and `scale` types. |
+| `segment` | Optional. Must name a declared [segment](attempts.md#segments) key, or be `null` for shared. |
+| `sequence` | Optional integer ≥ 0. Controls export column order; defaults to array position. |
+
+Use stable, dotted, lowercase ids: `{phase}.{topic}.{question}`. An undeclared id still records, but
+it exports unlabeled and appended after every declared column — useful as a safety net, never as a
+plan.
+
+<a name="emitting-statements"></a>
+## Emitting Statements
+
+```ts
+// The common case: a committed answer.
+await Rack.activity.answer('intro.connection', 5);
+
+// Navigation and progress. Fire and forget.
+void Rack.activity.progress('rd.chapter_2');
+
+// Anything else.
+void Rack.activity.statement({
+    verb: 'viewed',
+    activity: { id: 'rd.corine.video', type: 'media' },
+    result: { duration_seconds: 184 },
+    context: { autoplay: false },
+});
+```
+
+`answer()` emits `verb: 'answered'` with the value in `result.response` — **the only field reporting
+reads** — and fills `activity.type` from your manifest declaration. `progress()` emits
+`verb: 'progressed'` with `activity.type: 'step'`.
+
+Verbs match `^[a-z][a-z0-9_.:-]*$`. `occurred_at` defaults to now, in ISO 8601; pass it yourself only
+when replaying something that genuinely happened earlier.
+
+Read your own declarations when you need them:
+
+```ts
+Rack.activity.activities();                  // LaunchActivity[]
+Rack.activity.activity('intro.connection');  // { id, type, label, scale, … } | null
+```
+
+Rendering a question from its declared `label` and `scale` keeps the participant's wording and the
+CSV header identical by construction — a small discipline that pays for itself the first time
+someone edits a question.
+
+<a name="activity-types"></a>
+## Activity Types
+
+`type` is free text, but the admin understands these:
+
+| `type` | `result.response` | Used for |
+|---|---|---|
+| `text` | string | Free text. Feeds admin AI response analysis. |
+| `rating` | number within `scale` | Likert or self-rating. Eligible for metrics. |
+| `scale` | number within `scale` | Semantic alias of `rating`. |
+| `choice` | string key, or array of keys | Single or multi-select. |
+| `custom` | any JSON | Anything else. Exported JSON-encoded. |
+
+<a name="metrics"></a>
+## Metrics
+
+A metric pairs a pre and a post rating of the same thing, and gives the admin a shift card rather
+than two columns to eyeball.
+
+```json
+"reporting": {
+    "metrics": [
+        { "key": "connection", "label": "Connection",
+          "pre": "intro.connection", "post": "outro.connection" }
+    ]
+}
+```
+
+`pre` and `post` must be declared activity ids, and metrics require `attempt@1`, because they are
+computed over completed attempts. Both activities should use the same `scale`, or the shift means
+nothing.
+
+<a name="designing-for-the-export"></a>
+## Designing for the Export
+
+The CSV an admin downloads is:
+
+```
+ID, Name, Email, {first segment label}, Status, Started At, Completed At,
+{declared activities in sequence order, headed by label},
+{undeclared activity ids, appended}
+```
+
+Each cell is the last `result.response` for that activity in that attempt; non-scalars are
+JSON-encoded. Which yields three rules worth writing on the wall:
+
+1. **`id` is the data contract.** Renaming one between versions splits a column: old attempts keep
+   the old column, new attempts fill a new one.
+2. **`label` is the header.** Renaming one is free, and changes only how the column reads.
+3. **`sequence` is the column order.** Set it deliberately; the export reads top to bottom the way
+   the experience does.
+
+Write labels as full sentences, exactly as the participant sees them. An admin reading a
+spreadsheet six months later has no other copy of the question.

package/dist/docs/ai.md

@@ -0,0 +1,159 @@
+# AI — `ai@1`
+
+- [Introduction](#introduction)
+- [Declaring Prompts](#declaring-prompts)
+- [Analysis](#analysis)
+- [Chat](#chat)
+- [Budgets](#budgets)
+- [Untrusted Variables](#untrusted-variables)
+- [Not This Capability](#not-this-capability)
+
+<a name="introduction"></a>
+## Introduction
+
+**The applet never sees a key and never sends a prompt.** It calls a prompt template the manifest
+declared and the Rack stores, supplying *variables*, never instructions.
+
+```ts
+const { data } = await Rack.ai.ask('score_pitch', { pitch, track });
+```
+
+Four things fall out of that design at once:
+
+- Prompt injection *from the applet* is structurally impossible — there is no instruction channel.
+- Model, system prompt and output schema are Rack-owned, so they can be tuned or swapped without
+  republishing the applet.
+- Cost is governable: hard caps per prompt, per attempt, per participant, per applet, enforced
+  server-side.
+- **No CSP change is required.** The call travels as a `postMessage`, not a `fetch`.
+
+<a name="declaring-prompts"></a>
+## Declaring Prompts
+
+```json
+"prompts": [
+    {
+        "id": "score_pitch",
+        "mode": "analysis",
+        "template": "Score this team pitch for clarity and specificity.\n\nPitch: {{pitch}}\nTrack: {{track}}",
+        "vars": {
+            "type": "object",
+            "properties": { "pitch": { "type": "string" }, "track": { "type": "string" } },
+            "required": ["pitch"]
+        },
+        "output_schema": {
+            "type": "object",
+            "properties": {
+                "clarity":  { "type": "integer", "minimum": 1, "maximum": 5 },
+                "feedback": { "type": "string" }
+            },
+            "required": ["clarity", "feedback"]
+        },
+        "budget": { "max_calls_per_attempt": 3, "max_output_tokens": 400 }
+    }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `id` | Required. `^[a-z][a-z0-9_.-]*$`, max 100, unique. |
+| `mode` | Required. `analysis` or `chat`. |
+| `template` | Required, max 20 000. `{{placeholder}}` for each variable. |
+| `vars` | Optional JSON Schema (`type: object`). **If present, every placeholder must be declared in it.** |
+| `output_schema` | Required for `analysis`, `type: object`. |
+| `budget` | Optional. `max_calls_per_attempt`, `max_calls_per_participant`, `max_output_tokens`. |
+| `model` | Optional hint. Honoured only if the deployment allowlists it. |
+
+<a name="analysis"></a>
+## Analysis
+
+Structured output, conforming to the declared `output_schema`. For scoring a response, summarising
+back to the participant, or branching on what someone wrote.
+
+```ts
+interface Score { clarity: number; feedback: string }
+
+const result = await Rack.ai.ask<Score>('score_pitch', { pitch, track: 'rd' });
+
+if (! result.ok) {
+    return result.error === 'budget_exceeded'
+        ? showGenericFeedback()
+        : showRetry();
+}
+
+render(result.data.output.feedback, result.data.output.clarity);
+result.data.usage;   // { input_tokens, output_tokens }
+```
+
+The Rack validates the model's output against your schema before it acks, so `output` either matches
+the schema or the call fails. You do not need defensive parsing — you do need a path for the failure
+case, because a model can be unavailable.
+
+Always write the non-AI fallback. An applet whose experience stalls when a call fails has made an
+LLM into a dependency the framework was designed to keep optional.
+
+<a name="chat"></a>
+## Chat
+
+Conversational, with history held by the Rack and scoped to the attempt or room. The applet never
+holds the transcript.
+
+```ts
+const chat = Rack.ai.chat('coach');
+
+const reply = await chat.send(message, (delta, soFar) => {
+    bubble.textContent = soFar;          // streams as it arrives
+});
+
+if (reply.ok) {
+    bubble.textContent = reply.data.text;
+    reply.data.message_id;
+}
+
+await chat.reset();                      // start a fresh conversation
+```
+
+Streaming works through chunked acks: partials carry `delta`, the terminal ack carries the full
+`text` and `usage`. Each chunk resets the ack timeout, and the whole call allows 60 s.
+
+Messages cap at 4000 characters and history at 40 messages (`ziprack-ai.max_message_length`,
+`history_messages`); older turns fall off rather than failing the call.
+
+<a name="budgets"></a>
+## Budgets
+
+Every layer is enforced server-side, and the applet cannot raise any of them:
+
+| Limit | Declared in | Default | Ceiling |
+|---|---|---|---|
+| Calls per attempt | `budget.max_calls_per_attempt` | 20 | — |
+| Calls per participant | `budget.max_calls_per_participant` | 200 | — |
+| Output tokens | `budget.max_output_tokens` | 800 | 2000 (`ziprack-ai.budget.max_output_tokens_cap`) |
+| Calls per applet per day | deployment | 5000 | — |
+| Calls per Rack per month | deployment | 100 000 | — |
+| Variable payload | deployment | 16 KB | — |
+
+Exceeding any of them returns `budget_exceeded`. Declare the budget your experience actually needs:
+a lower cap is a smaller incident, and the number is visible to whoever reviews the capability diff.
+
+Spend is reported per prompt in the admin API (`/ziprack/admin/applets/{applet}/ai/spend`).
+
+<a name="untrusted-variables"></a>
+## Untrusted Variables
+
+Variables still reach a model. Assume a participant will type adversarial text into any field you
+pass through, and design the template so that it would not matter:
+
+- Put participant text **after** the instructions, clearly delimited, and say what it is.
+- Never ask the model to follow instructions found inside a variable.
+- Prefer `analysis` with a tight `output_schema` over free-form text you will parse yourself — a
+  schema-constrained answer is a much smaller blast radius.
+- Show model output as model output. Do not render it as if it were Rack-authored guidance.
+
+<a name="not-this-capability"></a>
+## Not This Capability
+
+The admin console's **AI Response Analysis** — summaries of free-text answers across attempts — is a
+Rack feature operating on collected [statements](activity.md). It works for any applet declaring
+`activity@1`, whether or not that applet uses `ai@1` at all, and it is configured and budgeted
+separately. See [Reporting](reporting.md).

package/dist/docs/applet-packages.md

@@ -0,0 +1,118 @@
+# Applet Packages
+
+- [The Zip](#the-zip)
+- [Installer Rules](#installer-rules)
+- [The Starter](#the-starter)
+- [Relative URLs](#relative-urls)
+- [The SBOM](#the-sbom)
+- [Building and Packaging](#building-and-packaging)
+
+<a name="the-zip"></a>
+## The Zip
+
+An applet ships as a single zip, named for the applet and the version it contains:
+
+```
+{slug}-{version}.zip
+├── manifest.json        required, at the zip root
+├── sbom.json            required — CycloneDX, or package-lock.json
+├── index.html           the entry (configurable via manifest.entry)
+└── assets/…             everything the entry references, by RELATIVE path
+```
+
+Nothing else is special. The Rack extracts the archive, keeps the file tree intact, and serves it
+through a token-prefixed path. There is no build step on the server, no server-side templating, no
+framework to satisfy — whatever your bundler emits is what runs.
+
+<a name="installer-rules"></a>
+## Installer Rules
+
+`PackageInstaller` is security code, identical on every Rack, and it refuses the whole upload rather
+than skipping a bad file:
+
+- **Static extensions only.** `html js mjs css map json wasm txt vtt svg png jpg jpeg gif webp ico
+  woff woff2 ttf mp3 mp4 wav webm ogg pdf`. A `.php` in your `dist/` rejects the package.
+- **No `..`, no absolute paths, no symlinks, no NUL bytes.** Dotfiles and `__MACOSX/` are skipped
+  silently, so a zip built on macOS is fine.
+- **50 MB by default** (`ziprack.max_upload_mb`).
+- **`manifest.entry` must exist** in the zip and end in `.html`.
+- **The slug must match** the applet you are uploading to, and it is immutable once created.
+- **A `version` string uploads once per applet.** Bump it every time, including during testing.
+
+Installation runs inside a transaction: the version row is created, every declared capability's
+`onInstall()` hook runs — this is where `db@1` creates the collection tables and their generated
+columns — and only then are files extracted. A failure anywhere rolls the whole thing back and
+deletes the extracted directory.
+
+<a name="the-starter"></a>
+## The Starter
+
+`starter/` is a minimal, working `ziprack/1` applet: plain Vite and TypeScript, `@ziprack/sdk`, one
+question, one statement, one completion.
+
+```sh
+npm install
+npm run dev        # mock mode: the whole experience runs standalone
+npm run package    # dist-zip/{slug}-{version}.zip, ready to upload
+```
+
+Edit `public/manifest.json` first — `slug`, `name`, `version`, and the capabilities you intend to
+call. Everything else follows from there.
+
+<a name="relative-urls"></a>
+## Relative URLs
+
+The Rack serves your package from `/ziprack/pkg/{token}/…`, where `{token}` is a signed, expiring
+value. A root-relative URL like `/assets/app.js` therefore 404s in production while working
+perfectly on your dev server — the single most common packaging mistake.
+
+With Vite, one line prevents it:
+
+```ts
+export default defineConfig({
+    base: './',                  // required
+    build: { outDir: 'dist', emptyOutDir: true },
+});
+```
+
+The same applies to anything you hand-write: `./assets/logo.svg`, never `/assets/logo.svg`.
+
+<a name="the-sbom"></a>
+## The SBOM
+
+Every package carries a `sbom.json` (CycloneDX) or a `package-lock.json` at its root. An applet is
+*built output*, so there is nothing to audit unless the lockfile comes with it — the same reason
+`npm audit` reads a lockfile rather than code.
+
+On install the Rack extracts the purl list and batches it against OSV.dev. Findings land in the
+[review queue](publishing.md) rather than blocking the upload.
+
+Be clear about the limit: the SBOM is self-attested. A hostile publisher can ship an accurate
+lockfile alongside a tampered bundle. This catches negligence, not malice — which is still worth
+having, because negligence is the common case.
+
+<a name="building-and-packaging"></a>
+## Building and Packaging
+
+`npm run package` in the starter does the whole job:
+
+```js
+// scripts/package.js — abbreviated
+const manifest = JSON.parse(readFileSync('dist/manifest.json', 'utf8'));
+
+execSync('npm sbom --sbom-format cyclonedx --omit dev', { cwd: lockDir })  // → dist/sbom.json
+execSync(`zip -r -X "${zipPath}" . -x ".*" -x "__MACOSX*"`, { cwd: 'dist' });
+```
+
+Two details worth keeping if you write your own: `-X` drops extra file attributes, and excluding
+dotfiles keeps `.DS_Store` out of an archive the installer would otherwise skip anyway.
+
+Upload the result through the admin API, or from the deployment:
+
+```sh
+php artisan ziprack:install dist-zip/my-applet-1.0.0.zip
+php artisan ziprack:promote my-applet 1.0.0
+```
+
+Uploads land **unpublished**. Promotion is always a separate, deliberate action — see
+[Publishing](publishing.md).