@proveanything/smartlinks 1.17.6 → 2.0.0-alpha.2

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.2  |  Generated: 2026-09-14T14:13:56.533Z
 
 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,244 @@
+# 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*. On the **main SaaS this is
+   `https://smartlinks.app`** (the API lives under `/api/v1` — the same base your app already
+   passes to `initializeApi`). A client's isolated (VPC) environment has its **own** host; you
+   install into it by calling that host. This is the value that varies per deployment.
+2. **The bundle CDN** — *where your built files are actually served from*, which you pass at
+   registration as **`bundleBaseUrl`**. **This depends on the channel:**
+   - **`dev` (Lovable):** your files are served by **Lovable at your published app URL** — that
+     URL is your dev `bundleBaseUrl`. Lovable *is* the CDN for dev; nothing is uploaded to
+     SmartLinks.
+   - **`prod`:** files are published to the SmartLinks app CDN at
+     `https://smartlinks.app/apps/{appId}/{version}/…` by your prod deploy step; that base is
+     your prod `bundleBaseUrl`.
+
+   ```
+   https://smartlinks.app/apps/{appId}/{version}/app.manifest.json   # prod layout
+   https://smartlinks.app/apps/{appId}/{version}/functions.umd.js
+   ```
+
+   Always pass `bundleBaseUrl` explicitly so it keeps working if a location changes.
+
+> **Who publishes the bundles?** The platform does **not** fetch or mirror them for you —
+> `bundleBaseUrl` must already serve the files at registration time. For `dev` that's Lovable
+> (on Publish); for `prod` that's your own CDN deploy step. Registration records *where* the
+> bundles are + the validated manifest; it does not host anything.
+
+## 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*: a leaked key can only do what its scope allows.
+
+| Key | Where to keep it | May write | If it leaks |
+|---|---|---|---|
+| **Dev key** | a **Lovable workspace Build Secret** (below) | `dev` channel, **any app in the environment** | someone can register/overwrite `dev` releases — which are served only to test collections — but **never** `beta`/`prod` |
+| **Prod master key** | your CI/Cloud Build secret store **only** | all channels | full control — so keep it out of app source entirely |
+| **Per-app key** *(future)* | provisioned per app | one specific app | scoped to that one app |
+
+**Keep the dev key in Lovable Build Secrets — do not commit it.** Lovable exposes
+**workspace-level Build Secrets** shared across every project in the workspace: set the dev key
+there **once** and every microapp inherits it, nothing is committed, and there's a single value
+to rotate. (An earlier draft of this guide said to put the key in app source — don't; use Build
+Secrets.)
+
+**Minting (current state, 2.0.0-alpha):** the `dev` and `prod` keys are **shared secrets
+configured on the SmartLinks backend** — one `dev` key and one `prod` key covering all
+first-party apps. There is **no self-service minting UI yet**: ask the platform owner for the
+`dev` key and put it in your workspace Build Secret. Per-app keys, self-service minting, and
+rotation are planned; rotating the shared `dev` key just means updating the one Build Secret
+(registered releases are unaffected — the key authorizes *writes*, it isn't stored on releases).
+
+Present the key in the `x-smartlinks-deploy-key` header.
+
+---
+
+## The registration endpoint
+
+```
+POST https://smartlinks.app/api/v1/apps/{appId}/releases   # main SaaS; a VPC env uses its own host
+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]" }
+]}
+```
+
+### Re-registering & version collisions
+
+Registration is an **upsert keyed by (app, channel)** — the newest registration becomes that
+channel's live release. Registering again **overwrites** it (last write wins); there is **no**
+version-collision error even if `meta.version` is unchanged. So re-publishing to `dev` without
+bumping the version is a normal, intentional overwrite — which is what you want on `dev`. (A
+stricter `prod` policy that rejects a duplicate `version` may come later; it isn't enforced
+today.)
+
+### 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://smartlinks.app'   // a VPC env: set to its host
+const KEY     = process.env.SMARTLINKS_DEPLOY_KEY                         // Lovable Build Secret (dev) / CI secret (prod)
+const CHANNEL = process.env.SMARTLINKS_CHANNEL                           // 'dev' | 'beta' | 'prod'; UNSET ⇒ don't register
+
+// --- Gate: only register when this build is meant to ---
+// A preview / live-edit build (no channel) skips quietly so it never fails. A build that
+// declares a channel but has no key is a hard error IF it's prod; dev skips quietly.
+if (!CHANNEL) {
+  console.log('ℹ︎ SmartLinks: SMARTLINKS_CHANNEL unset — skipping release registration (preview build).')
+  process.exit(0)
+}
+if (!KEY) {
+  if (CHANNEL === 'prod') { console.error('❌ prod build but SMARTLINKS_DEPLOY_KEY is missing'); process.exit(1) }
+  console.log(`ℹ︎ SmartLinks: no deploy key for "${CHANNEL}" — skipping registration.`)
+  process.exit(0)
+}
+
+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 } })()
+// dev: your published Lovable URL; prod: the SmartLinks CDN base. Set SMARTLINKS_BUNDLE_BASE_URL.
+const bundleBaseUrl = process.env.SMARTLINKS_BUNDLE_BASE_URL || `https://smartlinks.app/apps/${appId}/${version}`
+
+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, manifest, bundleBaseUrl,
+    build: { at: new Date().toISOString(), gitHash, builder: CHANNEL === 'dev' ? 'lovable' : 'ci' },
+  }),
+})
+
+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:
+
+```jsonc
+// package.json
+"scripts": {
+  "build":     "vite build && … && node scripts/hash-bundles.mjs",
+  "postbuild": "node scripts/register-release.mjs"
+}
+```
+
+Registration is gated by **`SMARTLINKS_CHANNEL`**, so the three Lovable build types behave correctly:
+
+| Build | `SMARTLINKS_CHANNEL` | Result |
+|---|---|---|
+| **Preview / live-edit** | unset | **skips quietly** — never registers, never fails |
+| **Dev (Publish)** | `dev` | registers to `dev` with the workspace Build-Secret key + your Lovable `SMARTLINKS_BUNDLE_BASE_URL` |
+| **Prod (CI)** | `prod` | registers to `prod` with the prod key; a missing key **hard-fails** |
+
+The gate is `SMARTLINKS_CHANNEL`, so **set it only where you want a release** — i.e. on the
+Publish/CI build, not on preview. If your host exposes a publish-only signal (an env var it sets
+only on Publish), key `SMARTLINKS_CHANNEL` off that; otherwise set it in the Publish build's env
+and leave it unset for preview. That one variable is the difference between "this build ships a
+release" and "this build is just a preview."
+
+That's it: a real Publish validates + registers your app (a broken manifest or function stops
+the deploy with an actionable error), while preview builds stay quiet.

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.2  |  Generated: 2026-09-14T14:13:56.533Z
 
 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,244 @@
+# 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*. On the **main SaaS this is
+   `https://smartlinks.app`** (the API lives under `/api/v1` — the same base your app already
+   passes to `initializeApi`). A client's isolated (VPC) environment has its **own** host; you
+   install into it by calling that host. This is the value that varies per deployment.
+2. **The bundle CDN** — *where your built files are actually served from*, which you pass at
+   registration as **`bundleBaseUrl`**. **This depends on the channel:**
+   - **`dev` (Lovable):** your files are served by **Lovable at your published app URL** — that
+     URL is your dev `bundleBaseUrl`. Lovable *is* the CDN for dev; nothing is uploaded to
+     SmartLinks.
+   - **`prod`:** files are published to the SmartLinks app CDN at
+     `https://smartlinks.app/apps/{appId}/{version}/…` by your prod deploy step; that base is
+     your prod `bundleBaseUrl`.
+
+   ```
+   https://smartlinks.app/apps/{appId}/{version}/app.manifest.json   # prod layout
+   https://smartlinks.app/apps/{appId}/{version}/functions.umd.js
+   ```
+
+   Always pass `bundleBaseUrl` explicitly so it keeps working if a location changes.
+
+> **Who publishes the bundles?** The platform does **not** fetch or mirror them for you —
+> `bundleBaseUrl` must already serve the files at registration time. For `dev` that's Lovable
+> (on Publish); for `prod` that's your own CDN deploy step. Registration records *where* the
+> bundles are + the validated manifest; it does not host anything.
+
+## 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*: a leaked key can only do what its scope allows.
+
+| Key | Where to keep it | May write | If it leaks |
+|---|---|---|---|
+| **Dev key** | a **Lovable workspace Build Secret** (below) | `dev` channel, **any app in the environment** | someone can register/overwrite `dev` releases — which are served only to test collections — but **never** `beta`/`prod` |
+| **Prod master key** | your CI/Cloud Build secret store **only** | all channels | full control — so keep it out of app source entirely |
+| **Per-app key** *(future)* | provisioned per app | one specific app | scoped to that one app |
+
+**Keep the dev key in Lovable Build Secrets — do not commit it.** Lovable exposes
+**workspace-level Build Secrets** shared across every project in the workspace: set the dev key
+there **once** and every microapp inherits it, nothing is committed, and there's a single value
+to rotate. (An earlier draft of this guide said to put the key in app source — don't; use Build
+Secrets.)
+
+**Minting (current state, 2.0.0-alpha):** the `dev` and `prod` keys are **shared secrets
+configured on the SmartLinks backend** — one `dev` key and one `prod` key covering all
+first-party apps. There is **no self-service minting UI yet**: ask the platform owner for the
+`dev` key and put it in your workspace Build Secret. Per-app keys, self-service minting, and
+rotation are planned; rotating the shared `dev` key just means updating the one Build Secret
+(registered releases are unaffected — the key authorizes *writes*, it isn't stored on releases).
+
+Present the key in the `x-smartlinks-deploy-key` header.
+
+---
+
+## The registration endpoint
+
+```
+POST https://smartlinks.app/api/v1/apps/{appId}/releases   # main SaaS; a VPC env uses its own host
+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]" }
+]}
+```
+
+### Re-registering & version collisions
+
+Registration is an **upsert keyed by (app, channel)** — the newest registration becomes that
+channel's live release. Registering again **overwrites** it (last write wins); there is **no**
+version-collision error even if `meta.version` is unchanged. So re-publishing to `dev` without
+bumping the version is a normal, intentional overwrite — which is what you want on `dev`. (A
+stricter `prod` policy that rejects a duplicate `version` may come later; it isn't enforced
+today.)
+
+### 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://smartlinks.app'   // a VPC env: set to its host
+const KEY     = process.env.SMARTLINKS_DEPLOY_KEY                         // Lovable Build Secret (dev) / CI secret (prod)
+const CHANNEL = process.env.SMARTLINKS_CHANNEL                           // 'dev' | 'beta' | 'prod'; UNSET ⇒ don't register
+
+// --- Gate: only register when this build is meant to ---
+// A preview / live-edit build (no channel) skips quietly so it never fails. A build that
+// declares a channel but has no key is a hard error IF it's prod; dev skips quietly.
+if (!CHANNEL) {
+  console.log('ℹ︎ SmartLinks: SMARTLINKS_CHANNEL unset — skipping release registration (preview build).')
+  process.exit(0)
+}
+if (!KEY) {
+  if (CHANNEL === 'prod') { console.error('❌ prod build but SMARTLINKS_DEPLOY_KEY is missing'); process.exit(1) }
+  console.log(`ℹ︎ SmartLinks: no deploy key for "${CHANNEL}" — skipping registration.`)
+  process.exit(0)
+}
+
+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 } })()
+// dev: your published Lovable URL; prod: the SmartLinks CDN base. Set SMARTLINKS_BUNDLE_BASE_URL.
+const bundleBaseUrl = process.env.SMARTLINKS_BUNDLE_BASE_URL || `https://smartlinks.app/apps/${appId}/${version}`
+
+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, manifest, bundleBaseUrl,
+    build: { at: new Date().toISOString(), gitHash, builder: CHANNEL === 'dev' ? 'lovable' : 'ci' },
+  }),
+})
+
+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:
+
+```jsonc
+// package.json
+"scripts": {
+  "build":     "vite build && … && node scripts/hash-bundles.mjs",
+  "postbuild": "node scripts/register-release.mjs"
+}
+```
+
+Registration is gated by **`SMARTLINKS_CHANNEL`**, so the three Lovable build types behave correctly:
+
+| Build | `SMARTLINKS_CHANNEL` | Result |
+|---|---|---|
+| **Preview / live-edit** | unset | **skips quietly** — never registers, never fails |
+| **Dev (Publish)** | `dev` | registers to `dev` with the workspace Build-Secret key + your Lovable `SMARTLINKS_BUNDLE_BASE_URL` |
+| **Prod (CI)** | `prod` | registers to `prod` with the prod key; a missing key **hard-fails** |
+
+The gate is `SMARTLINKS_CHANNEL`, so **set it only where you want a release** — i.e. on the
+Publish/CI build, not on preview. If your host exposes a publish-only signal (an env var it sets
+only on Publish), key `SMARTLINKS_CHANNEL` off that; otherwise set it in the Publish build's env
+and leave it unset for preview. That one variable is the difference between "this build ships a
+release" and "this build is just a preview."
+
+That's it: a real Publish validates + registers your app (a broken manifest or function stops
+the deploy with an actionable error), while preview builds stay quiet.

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.2",
   "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"