@proveanything/smartlinks 1.17.6 → 2.0.0-alpha.1

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.17.6  |  Generated: 2026-09-14T10:25:34.491Z
+Version: 2.0.0-alpha.1  |  Generated: 2026-09-14T11:30:24.015Z
 
 This is a concise summary of all available API functions and types.
 
@@ -22,6 +22,7 @@ For detailed guides on specific features:
 - **[App Configuration Files](app-manifest.md)** - `app.manifest.json` and `app.admin.json` reference — bundles, components, setup questions, import schemas, tunable fields, and metrics
 - **[Executor Model](executor.md)** - Programmatic JS bundles for AI-driven setup, server-side SEO metadata generation, and LLM content for AI crawlers
 - **[Server Functions](server-functions.md)** - App-authored server-side "edge functions" (`async (ctx, event) => result`): http/event/cron triggers, the visibility/authority/capabilities security model, and the pre-scoped `ctx` (authority-scoped SDK, capability-gated secrets + fetch)
+- **[Deploying & Registering an App](deploying-apps.md)** - Publish → build → register: the app CDN layout (smartlinks.app), dev/beta/prod channels, channel-scoped deploy keys, the `POST /apps/:appId/releases` registration endpoint + validation, and how to wire it into your build so a bad manifest fails the deploy
 - **[Realtime](realtime.md)** - Real-time data updates and WebSocket connections
 - **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication
 - **[iframe Streaming Parent Changes](iframe-streaming-parent-changes.md)** - Parent-side changes required to support AI streaming in iframe proxy mode
@@ -1722,6 +1723,7 @@ interface AppFunctionDef {
   trigger: AppFunctionTrigger;
   visibility?: AppFunctionVisibility;
   authority?: AppFunctionAuthority;
+  elevated?: boolean;
   capabilities?: string[];
   apiVersion?: string;
   handler?: string;

package/dist/docs/deploying-apps.md

@@ -0,0 +1,193 @@
+# Deploying & registering an app
+
+> **Preview — SmartLinks SDK 2.0.0-alpha.** Part of the installable-app platform being built
+> toward 2.0.0 stable. These APIs may change before then. Published under the npm `next` tag;
+> `latest` remains 1.x.
+
+A SmartLinks app is a bundle (widgets, containers, and — new — [server functions](server-functions.md))
+described by an `app.manifest.json`. Deploying an app has two halves:
+
+1. **Publish the bundles** to the SmartLinks app CDN.
+2. **Register the release** — tell the SmartLinks backend a new version exists, hand it the
+   manifest, and let it validate everything. Registration is what makes the app (and its
+   server functions) known, installable, and testable.
+
+This guide covers registration and how to wire it into your build.
+
+---
+
+## Two "wheres": the API host vs the bundle CDN
+
+Deploying touches two different locations — keep them distinct:
+
+1. **The install endpoint (API host)** — *where you register*. This is a SmartLinks
+   **API v1** endpoint, and its **host is the environment** you're installing into (see
+   below). This is the one that varies per deployment.
+2. **The bundle CDN** — *where your files are served from*. **Today always `smartlinks.app`**:
+
+   ```
+   https://smartlinks.app/apps/{appId}/{version}/app.manifest.json
+   https://smartlinks.app/apps/{appId}/{version}/widgets-<hash>.umd.js
+   https://smartlinks.app/apps/{appId}/{version}/functions.umd.js
+   ```
+
+   That base — `https://smartlinks.app/apps/{appId}/{version}` — is your **`bundleBaseUrl`**,
+   which you pass at registration. Always pass it explicitly so nothing breaks if the CDN
+   location changes later.
+
+## Environments & the app registry
+
+Historically an app was **stateless everywhere**: every environment fetched the same CDN
+manifest on the fly, so apps were agnostic to shards, clients, and VPCs. Registration changes
+that — an app is now **installed into an environment's registry**, which is **global to that
+environment (not per-collection / not per-shard)**.
+
+An **environment** is one SmartLinks deployment: the main SaaS, or a client's isolated (VPC)
+instance. Each owns its own app registry, so:
+
+- The **install endpoint's host is the environment** — `POST https://<that-env's-api>/api/v1/apps/…`.
+  Installing into a client's VPC means calling *their* API with *their* deploy key.
+- **Rolling out to several environments = the same call, once per target** (different API host
+  + key each). The registration script below takes the API base as a parameter for exactly this.
+
+> Enabling an app on a specific **collection** (and consenting to its capabilities) is a
+> separate, per-collection step layered on top of the environment's registry.
+
+---
+
+## Channels
+
+A release is registered on one **channel**, matching how you deploy:
+
+| Channel | Deployed from | Typical use |
+|---|---|---|
+| `dev`  | **Lovable "Publish"** | Live development / testing |
+| `beta` | your pipeline | Staging / preview |
+| `prod` | your **Cloud Build** toolset (from git) | Production |
+
+A collection chooses which channel it follows, so you can point a test collection at `dev`
+and exercise a build before it reaches `prod`.
+
+---
+
+## Deploy keys
+
+Registration is authenticated by a **deploy key** — not a user login — scoped to the
+channels it may write. Security comes from the *scope*, so a key that leaks can only affect
+what it was allowed to touch.
+
+| Key | Lives in | May write |
+|---|---|---|
+| **Dev key** | your app's (private) source / build env | `dev` channel only |
+| **Prod master key** | your Cloud Build toolset only — never in app source | all channels |
+| **Per-app key** *(future)* | a client's build | one specific app |
+
+Because a Lovable build has no secret store, the **dev key lives in your app source** — which
+is safe precisely because it can only ever write the `dev` channel. The **prod key stays in
+Cloud Build**. Present the key in the `x-smartlinks-deploy-key` header.
+
+---
+
+## The registration endpoint
+
+```
+POST https://<smartlinks-api>/api/v1/apps/{appId}/releases
+x-smartlinks-deploy-key: <your deploy key>
+Content-Type: application/json
+```
+
+```jsonc
+{
+  "channel": "dev",                 // dev | beta | prod
+  "version": "1.2.3",               // from your manifest meta.version
+  "build":   { "at": "2026-09-14T10:00:00Z", "gitHash": "abc1234", "builder": "lovable" },
+  "manifest": { /* your full app.manifest.json, including the functions block */ },
+  "bundleBaseUrl": "https://smartlinks.app/apps/currys/1.2.3"
+}
+```
+
+### Responses
+
+| Status | Meaning |
+|---|---|
+| `200` | Registered. Body: `{ ok: true, appId, channel, version, functions: [names], registeredAt }` |
+| `422` | Validation failed — **the build should fail**. Body: `{ ok: false, errors: [...] }` |
+| `401` | Missing/invalid deploy key |
+| `403` | Key not permitted for that channel (e.g. a dev key targeting `prod`) — `CHANNEL_FORBIDDEN` |
+
+Each validation error is `{ code, message, path }`, e.g.:
+
+```json
+{ "ok": false, "errors": [
+  { "code": "AUTHORITY_INVALID", "message": "invalid authority \"root\"", "path": "functions.definitions[0].authority" },
+  { "code": "CAPABILITY_INVALID", "message": "invalid capability \"bogus\"", "path": "functions.definitions[0].capabilities[0]" }
+]}
+```
+
+### What gets validated
+
+- `manifest.meta.appId` must match the `{appId}` in the URL.
+- The **`functions` block** is validated with the *same* rules the runtime enforces
+  (names, triggers, `visibility`/`authority`, the capability grammar, duplicate names) — so
+  a malformed server function is caught **at deploy time**, not at runtime. See
+  [server-functions.md](server-functions.md).
+
+---
+
+## Wiring it into your build
+
+Registration is the **last step of your build** — after bundles are built and hashed. Run a
+small script that reads your built manifest and POSTs it, and **exits non-zero on failure**
+so a bad install fails the publish.
+
+```js
+// scripts/register-release.mjs — run as the build's postbuild step
+import { readFileSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+
+const API      = process.env.SMARTLINKS_API      || 'https://api.smartlinks.app'
+const KEY      = process.env.SMARTLINKS_DEPLOY_KEY               // dev key (in source/env) or prod key (Cloud Build)
+const CHANNEL  = process.env.SMARTLINKS_CHANNEL  || 'dev'        // 'prod' in Cloud Build
+
+const manifest = JSON.parse(readFileSync('dist/app.manifest.json', 'utf8'))
+const appId    = manifest.meta.appId
+const version  = manifest.meta.version
+const gitHash  = (() => { try { return execSync('git rev-parse --short HEAD').toString().trim() } catch { return null } })()
+
+const res = await fetch(`${API}/api/v1/apps/${appId}/releases`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json', 'x-smartlinks-deploy-key': KEY },
+  body: JSON.stringify({
+    channel: CHANNEL,
+    version,
+    build: { at: new Date().toISOString(), gitHash, builder: CHANNEL === 'dev' ? 'lovable' : 'cloudbuild' },
+    manifest,
+    bundleBaseUrl: `https://smartlinks.app/apps/${appId}/${version}`,
+  }),
+})
+
+const body = await res.json().catch(() => ({}))
+if (!res.ok || !body.ok) {
+  console.error(`❌ SmartLinks registration failed (${res.status}):`)
+  for (const e of body.errors || []) console.error(`   • ${e.path}: ${e.message}`)
+  process.exit(1)  // fail the build
+}
+console.log(`✅ Registered ${appId}@${version} on "${CHANNEL}" — functions: ${(body.functions || []).join(', ') || 'none'}`)
+```
+
+Wire it after your bundle build/hash step, e.g.:
+
+```jsonc
+// package.json
+"scripts": {
+  "build":     "vite build && … && node scripts/hash-bundles.mjs",
+  "postbuild": "node scripts/register-release.mjs"
+}
+```
+
+- **Dev (Lovable "Publish")** runs `build` → `postbuild` with the **dev key** and
+  `SMARTLINKS_CHANNEL=dev`.
+- **Prod (Cloud Build)** runs the same with the **prod key** and `SMARTLINKS_CHANNEL=prod`.
+
+That's it: hitting Publish now validates and registers your app — and a broken manifest or
+function stops the deploy with an actionable error instead of shipping.

package/dist/docs/server-functions.md

@@ -1,5 +1,9 @@
 # Server functions ("edge functions")
 
+> **Preview — SmartLinks SDK 2.0.0-alpha.** Part of the installable-app platform being built
+> toward 2.0.0 stable (author → register → install → run → test). These APIs may change before
+> then. Published under the npm `next` tag; `latest` remains 1.x.
+
 A **server function** is arbitrary server-side JavaScript your app deploys directly into
 SmartLinks. It runs on the SmartLinks servers — with access to the full SDK, to your app's
 secrets, and to outbound network — so you can do things a browser app can't: validate and
@@ -38,6 +42,7 @@ in a bundle alongside your widgets/containers:
         "trigger":    { "type": "http", "methods": ["POST"] },
         "visibility": "public",              // WHO may call it
         "authority":  "collection",          // WHOSE authority it runs as
+        "elevated":   true,                  // required ack for public + collection
         "capabilities": ["sl:records:write", "network:api.recaptcha.net"],
         "apiVersion": "2026-09"
       },
@@ -104,6 +109,10 @@ functions have no external caller, so they always run as `collection`.
 > secrets, even though it's "elevated"). But **validating the request is still your job**:
 > check the payload, rate-limit using `ctx.caller`, guard against replay. Treat the function
 > body as a trust boundary.
+>
+> Because it's the sharp edge, a `public` + `collection` function must **explicitly opt in**
+> with `elevated: true` in its declaration — a conscious acknowledgment that you're exposing
+> collection authority to public callers. Without it, install/validation fails.
 
 ---
 
@@ -219,6 +228,69 @@ at admin level, attributed to the signed-in admin. The public surface resolves a
 token is present (→ `owner`) and treats its absence as anonymous (→ `public`); a
 `collection`-authority function runs elevated regardless.
 
+## Testing & preview
+
+You don't have to deploy to find out whether a function works. There are three levels of
+fidelity — use them in order.
+
+### 1. Local harness (fast, offline)
+
+`@proveanything/smartlinks/testing` builds a `ctx` that **enforces the declared capability
+envelope**, so a function fails locally the same way it would in production — the common
+"I forgot to declare `sl:records:write`" bug is caught before you deploy, not after.
+
+```ts
+import { createFunctionTestContext } from '@proveanything/smartlinks/testing'
+import manifest from '../public/app.manifest.json'
+import { submitCompetitionEntry } from '../src/functions'
+
+const def = manifest.functions.definitions.find(d => d.name === 'submitCompetitionEntry')
+
+const ctx = createFunctionTestContext({
+  def,                                       // capabilities enforced come from the manifest itself
+  caller: { userId: 'tester' },
+  secrets: { 'recaptcha-secret': 'test-value' },   // fixtures — real secrets are server-only
+})
+
+const res = await submitCompetitionEntry(ctx, { method: 'POST', body: { email: 'a@b.com', answer: '42' } })
+// ctx.sl.appRecords.create(...) throws CapabilityError unless `def` declares sl:records:write
+```
+
+Pass the **`def`** (not a hand-typed capability list) so "tested" can't drift from
+"declared". By default `ctx.sl` methods return a stub result (pure unit test — no network);
+inject `sl` to delegate to your live SDK for real reads/writes:
+
+```ts
+const ctx = createFunctionTestContext({
+  def,
+  sl: { appRecords: { create: (fields) => mySdk.app.records.create(fields) } },
+})
+```
+
+### 2. Deployed test mode (high fidelity, safe)
+
+Register to the `dev` channel and invoke on the real server — real secrets, real data —
+without a live run *(coming next)*: a test invocation is forced to `caller` authority,
+side-effecting writes are dry-run, and the traffic is logged separately from live metrics.
+
+### 3. Live
+
+Point a real collection at the channel and invoke for real.
+
+### What differs across the three
+
+| | Capabilities | `ctx.sl` | Secrets | Authority | Writes |
+|---|---|---|---|---|---|
+| **Local harness** | Enforced (from `def`) | Stub, or your injected SDK | Fixtures you pass | Informational | Whatever your impl does |
+| **Deployed test** | Enforced | Real (test-scoped) | Real | Forced to `caller` | Dry-run |
+| **Live** | Enforced | Real | Real | As declared | Real |
+
+### Recommended CI pattern
+
+1. **Unit** — run each handler through `createFunctionTestContext` (no network); assert
+   behaviour *and* that capabilities are sufficient (an under-declared capability throws).
+2. **Post-deploy smoke** — after registering to `dev`, hit each function once in test mode.
+
 ## Where functions run (and why it doesn't change how you write them)
 
 SmartLinks runs first-party (trusted) functions **in-process** and untrusted third-party

package/dist/openapi.yaml

@@ -17281,6 +17281,8 @@ components:
           $ref: "#/components/schemas/AppFunctionVisibility"
         authority:
           $ref: "#/components/schemas/AppFunctionAuthority"
+        elevated:
+          type: boolean
         capabilities:
           type: array
           items:

package/dist/testing/index.d.ts

@@ -0,0 +1,64 @@
+import type { AppFunctionDef, ServerFunctionContext } from '../types/appManifest';
+export declare class CapabilityError extends Error {
+    capability: string;
+    code: string;
+    constructor(capability: string, message?: string);
+}
+/** The surface `ctx.sl` exposes — mirrors the server facade. Provide the methods your test needs. */
+export interface TestSlImpl {
+    appRecords?: {
+        create?(fields: any): any;
+        update?(id: string, fields: any): any;
+        upsert?(fields: any): any;
+        delete?(id: string): any;
+        get?(id: string): any;
+        query?(params: any): any;
+        listTypes?(): any;
+    };
+    products?: {
+        get?(id: string, opts?: any): any;
+        query?(body?: any, opts?: any): any;
+        create?(data: any, opts?: any): any;
+        update?(id: string, data: any, opts?: any): any;
+    };
+    attestations?: {
+        create?(fields: any): any;
+    };
+}
+export interface TestCaller {
+    userId?: string | null;
+    anonymous?: boolean;
+    origin?: string | null;
+    ip?: string | null;
+}
+export interface CreateFunctionTestContextOptions {
+    /** The manifest declaration under test — its `capabilities` are the enforced envelope. */
+    def: Pick<AppFunctionDef, 'capabilities' | 'trigger' | 'visibility' | 'authority'>;
+    collectionId?: string;
+    appId?: string;
+    caller?: TestCaller;
+    /** Fixture secrets, keyed by ref. Real sealed secrets are server-only and never available locally. */
+    secrets?: Record<string, string>;
+    /** Backing impl for ctx.sl. Omit for pure unit tests (methods return a stub echo). */
+    sl?: TestSlImpl;
+    /** Backing fetch (defaults to global fetch). Still gated by the `network` capability. */
+    fetch?: typeof fetch;
+}
+export interface FunctionTestContext extends ServerFunctionContext {
+    /** Captured log lines (also written via ctx.log). */
+    logs: Array<{
+        at: string;
+        message: string;
+        data?: Record<string, any>;
+    }>;
+}
+/**
+ * Build a capability-enforcing test ctx for a server function. Run your handler with it:
+ *
+ *   const ctx = createFunctionTestContext({ def, caller: { userId: 'me' }, secrets: { k: 'v' } })
+ *   const result = await myHandler(ctx, { method: 'POST', body: { … } })
+ *
+ * A ctx.sl / ctx.secrets / ctx.fetch call not covered by `def.capabilities` throws
+ * CapabilityError — exactly as it would in production.
+ */
+export declare function createFunctionTestContext(opts: CreateFunctionTestContextOptions): FunctionTestContext;

package/dist/testing/index.js

@@ -0,0 +1,145 @@
+// src/testing/index.ts
+//
+// Local test harness for SmartLinks server functions — importable as
+// `@proveanything/smartlinks/testing`. It builds a `ctx` that matches the runtime
+// contract AND enforces the declared capability envelope, so a function fails locally
+// the same way it would after deploy — no "deploy and pray".
+//
+// Fidelity (documented in docs/server-functions.md "Testing & preview"):
+//  - Capabilities are enforced EXACTLY as declared in the manifest `def` — pass the def
+//    itself so "tested" can't drift from "declared".
+//  - `ctx.sl` delegates to an impl you inject: your live SDK for real reads/writes, or
+//    omit it for pure unit tests (methods return a stub result instead of hitting the
+//    network — control flow + capability enforcement still run).
+//  - `ctx.secrets` are FIXTURES you provide; real sealed secrets are server-only and
+//    never resolvable locally.
+//  - `ctx.fetch` is gated by the `network` capability just like production.
+export class CapabilityError extends Error {
+    constructor(capability, message) {
+        super(message || `capability not granted: ${capability}`);
+        this.code = 'CAPABILITY_DENIED';
+        this.name = 'CapabilityError';
+        this.capability = capability;
+    }
+}
+// The SAME grammar the server enforces (prove server/services/functions/validate.js).
+function parseCapabilities(list = []) {
+    const sl = new Set();
+    const secrets = new Set();
+    const networkHosts = new Set();
+    let networkAll = false;
+    for (const raw of list || []) {
+        const cap = String(raw || '').trim();
+        if (!cap)
+            continue;
+        if (cap === 'network') {
+            networkAll = true;
+            continue;
+        }
+        if (cap.startsWith('network:')) {
+            networkHosts.add(cap.slice(8).toLowerCase());
+            continue;
+        }
+        if (cap.startsWith('secrets:')) {
+            secrets.add(cap.slice(8));
+            continue;
+        }
+        if (cap.startsWith('sl:')) {
+            sl.add(cap.slice(3));
+            continue;
+        }
+    }
+    return { sl, secrets, networkAll, networkHosts };
+}
+function allowsSl(p, resource, op) {
+    if (p.sl.has(`${resource}:${op}`))
+        return true;
+    if (op === 'read' && p.sl.has(`${resource}:write`))
+        return true; // write implies read
+    return false;
+}
+const stub = (method, args) => ({ __stub: true, method, args });
+/**
+ * Build a capability-enforcing test ctx for a server function. Run your handler with it:
+ *
+ *   const ctx = createFunctionTestContext({ def, caller: { userId: 'me' }, secrets: { k: 'v' } })
+ *   const result = await myHandler(ctx, { method: 'POST', body: { … } })
+ *
+ * A ctx.sl / ctx.secrets / ctx.fetch call not covered by `def.capabilities` throws
+ * CapabilityError — exactly as it would in production.
+ */
+export function createFunctionTestContext(opts) {
+    var _a, _b, _c, _d;
+    const def = opts.def || {};
+    const parsed = parseCapabilities(def.capabilities || []);
+    const impl = opts.sl || {};
+    const logs = [];
+    const gated = (resource, op, fn, name) => async (...args) => {
+        if (!allowsSl(parsed, resource, op))
+            throw new CapabilityError(`sl:${resource}:${op}`);
+        return fn ? fn(...args) : stub(`${resource}.${name}`, args);
+    };
+    const ar = impl.appRecords || {};
+    const pr = impl.products || {};
+    const at = impl.attestations || {};
+    const sl = {
+        appRecords: {
+            create: gated('records', 'write', ar.create && ar.create.bind(ar), 'create'),
+            update: gated('records', 'write', ar.update && ar.update.bind(ar), 'update'),
+            upsert: gated('records', 'write', ar.upsert && ar.upsert.bind(ar), 'upsert'),
+            delete: gated('records', 'write', ar.delete && ar.delete.bind(ar), 'delete'),
+            get: gated('records', 'read', ar.get && ar.get.bind(ar), 'get'),
+            query: gated('records', 'read', ar.query && ar.query.bind(ar), 'query'),
+            listTypes: gated('records', 'read', ar.listTypes && ar.listTypes.bind(ar), 'listTypes'),
+        },
+        products: {
+            get: gated('products', 'read', pr.get && pr.get.bind(pr), 'get'),
+            query: gated('products', 'read', pr.query && pr.query.bind(pr), 'query'),
+            create: gated('products', 'write', pr.create && pr.create.bind(pr), 'create'),
+            update: gated('products', 'write', pr.update && pr.update.bind(pr), 'update'),
+        },
+        attestations: {
+            create: gated('attestations', 'write', at.create && at.create.bind(at), 'create'),
+        },
+    };
+    const secretsMap = opts.secrets || {};
+    const baseFetch = opts.fetch || (typeof fetch !== 'undefined' ? fetch : undefined);
+    const via = (def.trigger && def.trigger.type) || 'http';
+    const caller = opts.caller || {};
+    return {
+        collectionId: opts.collectionId || 'test-collection',
+        appId: opts.appId || 'test-app',
+        sl,
+        secrets: {
+            async get(ref) {
+                if (!parsed.secrets.has(ref))
+                    throw new CapabilityError(`secrets:${ref}`);
+                return Object.prototype.hasOwnProperty.call(secretsMap, ref) ? secretsMap[ref] : null;
+            },
+        },
+        caller: {
+            userId: (_a = caller.userId) !== null && _a !== void 0 ? _a : null,
+            anonymous: (_b = caller.anonymous) !== null && _b !== void 0 ? _b : !caller.userId,
+            origin: (_c = caller.origin) !== null && _c !== void 0 ? _c : null,
+            ip: (_d = caller.ip) !== null && _d !== void 0 ? _d : null,
+            via,
+        },
+        fetch: (async (input, init) => {
+            let host = '';
+            try {
+                host = new URL(typeof input === 'string' ? input : input.url).host;
+            }
+            catch ( /* bad URL → denied */_a) { /* bad URL → denied */ }
+            const allowed = parsed.networkAll || (!!host && parsed.networkHosts.has(host.toLowerCase()));
+            if (!allowed)
+                throw new CapabilityError(host ? `network:${host}` : 'network');
+            if (!baseFetch)
+                throw new Error('fetch is not available in this environment; pass opts.fetch');
+            return baseFetch(input, init);
+        }),
+        log: (message, data) => {
+            logs.push(Object.assign({ at: new Date().toISOString(), message: String(message) }, (data ? { data } : {})));
+        },
+        logs,
+    };
+}

package/dist/types/appManifest.d.ts

@@ -244,6 +244,13 @@ export interface AppFunctionDef {
      * `event`/`cron` functions have no caller and always run as `collection`.
      */
     authority?: AppFunctionAuthority;
+    /**
+     * Required acknowledgment for the sharp edge: a `public` + `collection` function is
+     * publicly callable AND runs with elevated collection authority. Set `elevated: true`
+     * to confirm you intend that and accept responsibility for validating requests —
+     * without it, install/validation fails. Ignored for any other visibility/authority combo.
+     */
+    elevated?: boolean;
     /**
      * Least-privilege capabilities this function needs, surfaced at install for
      * consent and capped at runtime — even for `collection`-authority functions.

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.17.6  |  Generated: 2026-09-14T10:25:34.491Z
+Version: 2.0.0-alpha.1  |  Generated: 2026-09-14T11:30:24.015Z
 
 This is a concise summary of all available API functions and types.
 
@@ -22,6 +22,7 @@ For detailed guides on specific features:
 - **[App Configuration Files](app-manifest.md)** - `app.manifest.json` and `app.admin.json` reference — bundles, components, setup questions, import schemas, tunable fields, and metrics
 - **[Executor Model](executor.md)** - Programmatic JS bundles for AI-driven setup, server-side SEO metadata generation, and LLM content for AI crawlers
 - **[Server Functions](server-functions.md)** - App-authored server-side "edge functions" (`async (ctx, event) => result`): http/event/cron triggers, the visibility/authority/capabilities security model, and the pre-scoped `ctx` (authority-scoped SDK, capability-gated secrets + fetch)
+- **[Deploying & Registering an App](deploying-apps.md)** - Publish → build → register: the app CDN layout (smartlinks.app), dev/beta/prod channels, channel-scoped deploy keys, the `POST /apps/:appId/releases` registration endpoint + validation, and how to wire it into your build so a bad manifest fails the deploy
 - **[Realtime](realtime.md)** - Real-time data updates and WebSocket connections
 - **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication
 - **[iframe Streaming Parent Changes](iframe-streaming-parent-changes.md)** - Parent-side changes required to support AI streaming in iframe proxy mode
@@ -1722,6 +1723,7 @@ interface AppFunctionDef {
   trigger: AppFunctionTrigger;
   visibility?: AppFunctionVisibility;
   authority?: AppFunctionAuthority;
+  elevated?: boolean;
   capabilities?: string[];
   apiVersion?: string;
   handler?: string;

package/docs/deploying-apps.md

@@ -0,0 +1,193 @@
+# Deploying & registering an app
+
+> **Preview — SmartLinks SDK 2.0.0-alpha.** Part of the installable-app platform being built
+> toward 2.0.0 stable. These APIs may change before then. Published under the npm `next` tag;
+> `latest` remains 1.x.
+
+A SmartLinks app is a bundle (widgets, containers, and — new — [server functions](server-functions.md))
+described by an `app.manifest.json`. Deploying an app has two halves:
+
+1. **Publish the bundles** to the SmartLinks app CDN.
+2. **Register the release** — tell the SmartLinks backend a new version exists, hand it the
+   manifest, and let it validate everything. Registration is what makes the app (and its
+   server functions) known, installable, and testable.
+
+This guide covers registration and how to wire it into your build.
+
+---
+
+## Two "wheres": the API host vs the bundle CDN
+
+Deploying touches two different locations — keep them distinct:
+
+1. **The install endpoint (API host)** — *where you register*. This is a SmartLinks
+   **API v1** endpoint, and its **host is the environment** you're installing into (see
+   below). This is the one that varies per deployment.
+2. **The bundle CDN** — *where your files are served from*. **Today always `smartlinks.app`**:
+
+   ```
+   https://smartlinks.app/apps/{appId}/{version}/app.manifest.json
+   https://smartlinks.app/apps/{appId}/{version}/widgets-<hash>.umd.js
+   https://smartlinks.app/apps/{appId}/{version}/functions.umd.js
+   ```
+
+   That base — `https://smartlinks.app/apps/{appId}/{version}` — is your **`bundleBaseUrl`**,
+   which you pass at registration. Always pass it explicitly so nothing breaks if the CDN
+   location changes later.
+
+## Environments & the app registry
+
+Historically an app was **stateless everywhere**: every environment fetched the same CDN
+manifest on the fly, so apps were agnostic to shards, clients, and VPCs. Registration changes
+that — an app is now **installed into an environment's registry**, which is **global to that
+environment (not per-collection / not per-shard)**.
+
+An **environment** is one SmartLinks deployment: the main SaaS, or a client's isolated (VPC)
+instance. Each owns its own app registry, so:
+
+- The **install endpoint's host is the environment** — `POST https://<that-env's-api>/api/v1/apps/…`.
+  Installing into a client's VPC means calling *their* API with *their* deploy key.
+- **Rolling out to several environments = the same call, once per target** (different API host
+  + key each). The registration script below takes the API base as a parameter for exactly this.
+
+> Enabling an app on a specific **collection** (and consenting to its capabilities) is a
+> separate, per-collection step layered on top of the environment's registry.
+
+---
+
+## Channels
+
+A release is registered on one **channel**, matching how you deploy:
+
+| Channel | Deployed from | Typical use |
+|---|---|---|
+| `dev`  | **Lovable "Publish"** | Live development / testing |
+| `beta` | your pipeline | Staging / preview |
+| `prod` | your **Cloud Build** toolset (from git) | Production |
+
+A collection chooses which channel it follows, so you can point a test collection at `dev`
+and exercise a build before it reaches `prod`.
+
+---
+
+## Deploy keys
+
+Registration is authenticated by a **deploy key** — not a user login — scoped to the
+channels it may write. Security comes from the *scope*, so a key that leaks can only affect
+what it was allowed to touch.
+
+| Key | Lives in | May write |
+|---|---|---|
+| **Dev key** | your app's (private) source / build env | `dev` channel only |
+| **Prod master key** | your Cloud Build toolset only — never in app source | all channels |
+| **Per-app key** *(future)* | a client's build | one specific app |
+
+Because a Lovable build has no secret store, the **dev key lives in your app source** — which
+is safe precisely because it can only ever write the `dev` channel. The **prod key stays in
+Cloud Build**. Present the key in the `x-smartlinks-deploy-key` header.
+
+---
+
+## The registration endpoint
+
+```
+POST https://<smartlinks-api>/api/v1/apps/{appId}/releases
+x-smartlinks-deploy-key: <your deploy key>
+Content-Type: application/json
+```
+
+```jsonc
+{
+  "channel": "dev",                 // dev | beta | prod
+  "version": "1.2.3",               // from your manifest meta.version
+  "build":   { "at": "2026-09-14T10:00:00Z", "gitHash": "abc1234", "builder": "lovable" },
+  "manifest": { /* your full app.manifest.json, including the functions block */ },
+  "bundleBaseUrl": "https://smartlinks.app/apps/currys/1.2.3"
+}
+```
+
+### Responses
+
+| Status | Meaning |
+|---|---|
+| `200` | Registered. Body: `{ ok: true, appId, channel, version, functions: [names], registeredAt }` |
+| `422` | Validation failed — **the build should fail**. Body: `{ ok: false, errors: [...] }` |
+| `401` | Missing/invalid deploy key |
+| `403` | Key not permitted for that channel (e.g. a dev key targeting `prod`) — `CHANNEL_FORBIDDEN` |
+
+Each validation error is `{ code, message, path }`, e.g.:
+
+```json
+{ "ok": false, "errors": [
+  { "code": "AUTHORITY_INVALID", "message": "invalid authority \"root\"", "path": "functions.definitions[0].authority" },
+  { "code": "CAPABILITY_INVALID", "message": "invalid capability \"bogus\"", "path": "functions.definitions[0].capabilities[0]" }
+]}
+```
+
+### What gets validated
+
+- `manifest.meta.appId` must match the `{appId}` in the URL.
+- The **`functions` block** is validated with the *same* rules the runtime enforces
+  (names, triggers, `visibility`/`authority`, the capability grammar, duplicate names) — so
+  a malformed server function is caught **at deploy time**, not at runtime. See
+  [server-functions.md](server-functions.md).
+
+---
+
+## Wiring it into your build
+
+Registration is the **last step of your build** — after bundles are built and hashed. Run a
+small script that reads your built manifest and POSTs it, and **exits non-zero on failure**
+so a bad install fails the publish.
+
+```js
+// scripts/register-release.mjs — run as the build's postbuild step
+import { readFileSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+
+const API      = process.env.SMARTLINKS_API      || 'https://api.smartlinks.app'
+const KEY      = process.env.SMARTLINKS_DEPLOY_KEY               // dev key (in source/env) or prod key (Cloud Build)
+const CHANNEL  = process.env.SMARTLINKS_CHANNEL  || 'dev'        // 'prod' in Cloud Build
+
+const manifest = JSON.parse(readFileSync('dist/app.manifest.json', 'utf8'))
+const appId    = manifest.meta.appId
+const version  = manifest.meta.version
+const gitHash  = (() => { try { return execSync('git rev-parse --short HEAD').toString().trim() } catch { return null } })()
+
+const res = await fetch(`${API}/api/v1/apps/${appId}/releases`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json', 'x-smartlinks-deploy-key': KEY },
+  body: JSON.stringify({
+    channel: CHANNEL,
+    version,
+    build: { at: new Date().toISOString(), gitHash, builder: CHANNEL === 'dev' ? 'lovable' : 'cloudbuild' },
+    manifest,
+    bundleBaseUrl: `https://smartlinks.app/apps/${appId}/${version}`,
+  }),
+})
+
+const body = await res.json().catch(() => ({}))
+if (!res.ok || !body.ok) {
+  console.error(`❌ SmartLinks registration failed (${res.status}):`)
+  for (const e of body.errors || []) console.error(`   • ${e.path}: ${e.message}`)
+  process.exit(1)  // fail the build
+}
+console.log(`✅ Registered ${appId}@${version} on "${CHANNEL}" — functions: ${(body.functions || []).join(', ') || 'none'}`)
+```
+
+Wire it after your bundle build/hash step, e.g.:
+
+```jsonc
+// package.json
+"scripts": {
+  "build":     "vite build && … && node scripts/hash-bundles.mjs",
+  "postbuild": "node scripts/register-release.mjs"
+}
+```
+
+- **Dev (Lovable "Publish")** runs `build` → `postbuild` with the **dev key** and
+  `SMARTLINKS_CHANNEL=dev`.
+- **Prod (Cloud Build)** runs the same with the **prod key** and `SMARTLINKS_CHANNEL=prod`.
+
+That's it: hitting Publish now validates and registers your app — and a broken manifest or
+function stops the deploy with an actionable error instead of shipping.

package/docs/server-functions.md

@@ -1,5 +1,9 @@
 # Server functions ("edge functions")
 
+> **Preview — SmartLinks SDK 2.0.0-alpha.** Part of the installable-app platform being built
+> toward 2.0.0 stable (author → register → install → run → test). These APIs may change before
+> then. Published under the npm `next` tag; `latest` remains 1.x.
+
 A **server function** is arbitrary server-side JavaScript your app deploys directly into
 SmartLinks. It runs on the SmartLinks servers — with access to the full SDK, to your app's
 secrets, and to outbound network — so you can do things a browser app can't: validate and
@@ -38,6 +42,7 @@ in a bundle alongside your widgets/containers:
         "trigger":    { "type": "http", "methods": ["POST"] },
         "visibility": "public",              // WHO may call it
         "authority":  "collection",          // WHOSE authority it runs as
+        "elevated":   true,                  // required ack for public + collection
         "capabilities": ["sl:records:write", "network:api.recaptcha.net"],
         "apiVersion": "2026-09"
       },
@@ -104,6 +109,10 @@ functions have no external caller, so they always run as `collection`.
 > secrets, even though it's "elevated"). But **validating the request is still your job**:
 > check the payload, rate-limit using `ctx.caller`, guard against replay. Treat the function
 > body as a trust boundary.
+>
+> Because it's the sharp edge, a `public` + `collection` function must **explicitly opt in**
+> with `elevated: true` in its declaration — a conscious acknowledgment that you're exposing
+> collection authority to public callers. Without it, install/validation fails.
 
 ---
 
@@ -219,6 +228,69 @@ at admin level, attributed to the signed-in admin. The public surface resolves a
 token is present (→ `owner`) and treats its absence as anonymous (→ `public`); a
 `collection`-authority function runs elevated regardless.
 
+## Testing & preview
+
+You don't have to deploy to find out whether a function works. There are three levels of
+fidelity — use them in order.
+
+### 1. Local harness (fast, offline)
+
+`@proveanything/smartlinks/testing` builds a `ctx` that **enforces the declared capability
+envelope**, so a function fails locally the same way it would in production — the common
+"I forgot to declare `sl:records:write`" bug is caught before you deploy, not after.
+
+```ts
+import { createFunctionTestContext } from '@proveanything/smartlinks/testing'
+import manifest from '../public/app.manifest.json'
+import { submitCompetitionEntry } from '../src/functions'
+
+const def = manifest.functions.definitions.find(d => d.name === 'submitCompetitionEntry')
+
+const ctx = createFunctionTestContext({
+  def,                                       // capabilities enforced come from the manifest itself
+  caller: { userId: 'tester' },
+  secrets: { 'recaptcha-secret': 'test-value' },   // fixtures — real secrets are server-only
+})
+
+const res = await submitCompetitionEntry(ctx, { method: 'POST', body: { email: 'a@b.com', answer: '42' } })
+// ctx.sl.appRecords.create(...) throws CapabilityError unless `def` declares sl:records:write
+```
+
+Pass the **`def`** (not a hand-typed capability list) so "tested" can't drift from
+"declared". By default `ctx.sl` methods return a stub result (pure unit test — no network);
+inject `sl` to delegate to your live SDK for real reads/writes:
+
+```ts
+const ctx = createFunctionTestContext({
+  def,
+  sl: { appRecords: { create: (fields) => mySdk.app.records.create(fields) } },
+})
+```
+
+### 2. Deployed test mode (high fidelity, safe)
+
+Register to the `dev` channel and invoke on the real server — real secrets, real data —
+without a live run *(coming next)*: a test invocation is forced to `caller` authority,
+side-effecting writes are dry-run, and the traffic is logged separately from live metrics.
+
+### 3. Live
+
+Point a real collection at the channel and invoke for real.
+
+### What differs across the three
+
+| | Capabilities | `ctx.sl` | Secrets | Authority | Writes |
+|---|---|---|---|---|---|
+| **Local harness** | Enforced (from `def`) | Stub, or your injected SDK | Fixtures you pass | Informational | Whatever your impl does |
+| **Deployed test** | Enforced | Real (test-scoped) | Real | Forced to `caller` | Dry-run |
+| **Live** | Enforced | Real | Real | As declared | Real |
+
+### Recommended CI pattern
+
+1. **Unit** — run each handler through `createFunctionTestContext` (no network); assert
+   behaviour *and* that capabilities are sufficient (an under-declared capability throws).
+2. **Post-deploy smoke** — after registering to `dev`, hit each function once in test mode.
+
 ## Where functions run (and why it doesn't change how you write them)
 
 SmartLinks runs first-party (trusted) functions **in-process** and untrusted third-party

package/openapi.yaml

@@ -17281,6 +17281,8 @@ components:
           $ref: "#/components/schemas/AppFunctionVisibility"
         authority:
           $ref: "#/components/schemas/AppFunctionAuthority"
+        elevated:
+          type: boolean
         capabilities:
           type: array
           items:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.17.6",
+  "version": "2.0.0-alpha.1",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,6 +8,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -37,7 +41,8 @@
   "author": "Glenn Shoosmith",
   "license": "MIT",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "next"
   },
   "dependencies": {
     "cross-fetch": "^3.1.5"