@proveanything/smartlinks 2.0.3 → 2.0.4

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.3  |  Generated: 2026-09-20T09:34:31.596Z
+Version: 2.0.4  |  Generated: 2026-09-20T10:21:15.062Z
 
 This is a concise summary of all available API functions and types.
 

package/dist/docs/app-manifest.md

@@ -312,6 +312,24 @@ See the **[Executor Model guide](executor.md)** for the full build setup, SEO co
 | `llmContent.function` | string | Name of the `getLLMContent` export |
 | `llmContent.timeout` | number | Timeout in ms (default 500) |
 
+#### `functions`
+
+Declares app-authored **server functions** — server-side handlers `(ctx, event) ⇒ result`
+(http / event / cron), shipped in a self-contained UMD bundle. Omit if the app has no server
+functions. The security model (`visibility`/`authority`/`capabilities`), the runtime surface, how
+to build the bundle, and how to invoke are all in the **[Server Functions guide](server-functions.md)** —
+this is just the manifest shape.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `files.js.umd` | string | UMD bundle path (e.g. `dist/functions.umd.js`) — a self-contained bundle exporting each handler by name |
+| `definitions[]` | object[] | One entry per function |
+| `definitions[].name` | string | Function name; also the handler export name (override with `handler`) |
+| `definitions[].trigger` | object | `{ type: "http"|"event"|"cron", … }` |
+| `definitions[].visibility` | string | `admin` \| `public` (http only) — who may call it |
+| `definitions[].authority` | string | `caller` \| `collection` — whose authority it runs as |
+| `definitions[].capabilities` | string[] | Least-privilege grants (`sl:<res>:<read\|write>`, `network[:<host>]`, `secrets:<ref>`) |
+
 ---
 
 ## `app.admin.json`

package/dist/docs/deploying-apps.md

@@ -16,6 +16,31 @@ This guide covers registration and how to wire it into your build.
 
 ---
 
+## Fast dev publish (recommended for dev)
+
+For the **dev** channel there's a one-step path that does *both* halves — SmartLinks **hosts and
+registers** — so you don't host bundles anywhere yourself (no Lovable, no CDN of your own) and
+don't run a separate register step:
+
+```bash
+# build your app first (produces dist/ with app.manifest.json), then:
+smartlinks-publish                 # uploads dist/ → SmartLinks hosts it + registers the dev release
+smartlinks-publish --watch         # re-publish on every change (save → live)
+```
+
+Env: `SMARTLINKS_APP_ID` (your platform id), `SMARTLINKS_DEPLOY_KEY` (dev key — dev-only, safe to
+keep locally), optional `SMARTLINKS_API` / `--dir`. It uploads the built files to
+`POST /api/v1/apps/{appId}/publish?channel=dev`; the server validates the manifest + functions,
+writes the bundle to `smartlinks.app/apps/{appId}/dev/…` with **`no-store` caching** (every reload
+is instantly fresh — no cache-busting, no invalidation), and registers the release. It works from
+**anywhere** — local, Claude, CI, or a build step — because the builder builds and the platform
+hosts; there's no dependency on any external host for dev.
+
+Use this for dev. Use the **register-a-URL** flow below when *you* host the bundle (a beta/stable
+CDN deploy, or an external host) and just want to register where it lives + its manifest.
+
+---
+
 ## Two "wheres": the API host vs the bundle CDN
 
 Deploying touches two different locations — keep them distinct:

package/dist/docs/overview.md

@@ -63,6 +63,8 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Containers** | `docs/containers.md` | Building full-app embeddable containers (lazy-loaded) |
 | **Mobile Admin Container** | `docs/mobile-admin-container.md` | Building a separate Capacitor-aware mobile admin bundle for field operators |
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
+| **Server Functions** | `docs/server-functions.md` | App-authored server-side functions `(ctx, event) ⇒ result`: security model, runtime surface, invoking |
+| **Deploying & Registering** | `docs/deploying-apps.md` | Getting your app into the platform: fast dev publish, channels, deploy keys, registering releases |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
 | **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |

package/dist/docs/server-functions.md

@@ -63,6 +63,47 @@ in a bundle alongside your widgets/containers:
 
 Each definition maps to an exported handler of the same `name` (override with `handler`).
 
+## Building the functions bundle
+
+The handlers ship as a **self-contained UMD** — one file, all dependencies compiled in, no
+`require`/`import` of platform or Node modules (see [Runtime](#runtime--what-your-function-can-use)).
+Your functions entry just **named-exports** each handler:
+
+```js
+// src/functions/index.js — the functions entry
+export async function submitCompetitionEntry(ctx, event) { /* … */ }
+export async function onProofCreated(ctx, event) { /* … */ }
+```
+
+Build it to `dist/functions.umd.js` with a Vite lib build — **UMD format, nothing externalised**
+(so it's self-contained), and don't wipe the widgets you built into the same `dist/`:
+
+```ts
+// vite.functions.config.ts
+import { defineConfig } from 'vite'
+export default defineConfig({
+  build: {
+    lib: { entry: 'src/functions/index.js', formats: ['umd'], name: 'functions',
+           fileName: () => 'functions.umd.js' },
+    outDir: 'dist',
+    emptyOutDir: false,            // co-exist with the widgets/containers build
+    rollupOptions: { external: [] } // bundle everything — no Node/platform externals
+  },
+})
+```
+
+```jsonc
+// package.json — build widgets/containers as usual, then the functions bundle
+"scripts": {
+  "build": "vite build && vite build --config vite.functions.config.ts"
+}
+```
+
+That emits `dist/functions.umd.js` (matching `functions.files.js.umd`), whose named exports the
+platform pairs with your manifest `definitions`. Then **deploy** it — for dev,
+`smartlinks-publish` uploads `dist/` and registers in one step (see
+[Deploying & registering](deploying-apps.md)).
+
 ---
 
 ## The two security questions every function answers

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.3  |  Generated: 2026-09-20T09:34:31.596Z
+Version: 2.0.4  |  Generated: 2026-09-20T10:21:15.062Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/app-manifest.md

@@ -312,6 +312,24 @@ See the **[Executor Model guide](executor.md)** for the full build setup, SEO co
 | `llmContent.function` | string | Name of the `getLLMContent` export |
 | `llmContent.timeout` | number | Timeout in ms (default 500) |
 
+#### `functions`
+
+Declares app-authored **server functions** — server-side handlers `(ctx, event) ⇒ result`
+(http / event / cron), shipped in a self-contained UMD bundle. Omit if the app has no server
+functions. The security model (`visibility`/`authority`/`capabilities`), the runtime surface, how
+to build the bundle, and how to invoke are all in the **[Server Functions guide](server-functions.md)** —
+this is just the manifest shape.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `files.js.umd` | string | UMD bundle path (e.g. `dist/functions.umd.js`) — a self-contained bundle exporting each handler by name |
+| `definitions[]` | object[] | One entry per function |
+| `definitions[].name` | string | Function name; also the handler export name (override with `handler`) |
+| `definitions[].trigger` | object | `{ type: "http"|"event"|"cron", … }` |
+| `definitions[].visibility` | string | `admin` \| `public` (http only) — who may call it |
+| `definitions[].authority` | string | `caller` \| `collection` — whose authority it runs as |
+| `definitions[].capabilities` | string[] | Least-privilege grants (`sl:<res>:<read\|write>`, `network[:<host>]`, `secrets:<ref>`) |
+
 ---
 
 ## `app.admin.json`

package/docs/deploying-apps.md

@@ -16,6 +16,31 @@ This guide covers registration and how to wire it into your build.
 
 ---
 
+## Fast dev publish (recommended for dev)
+
+For the **dev** channel there's a one-step path that does *both* halves — SmartLinks **hosts and
+registers** — so you don't host bundles anywhere yourself (no Lovable, no CDN of your own) and
+don't run a separate register step:
+
+```bash
+# build your app first (produces dist/ with app.manifest.json), then:
+smartlinks-publish                 # uploads dist/ → SmartLinks hosts it + registers the dev release
+smartlinks-publish --watch         # re-publish on every change (save → live)
+```
+
+Env: `SMARTLINKS_APP_ID` (your platform id), `SMARTLINKS_DEPLOY_KEY` (dev key — dev-only, safe to
+keep locally), optional `SMARTLINKS_API` / `--dir`. It uploads the built files to
+`POST /api/v1/apps/{appId}/publish?channel=dev`; the server validates the manifest + functions,
+writes the bundle to `smartlinks.app/apps/{appId}/dev/…` with **`no-store` caching** (every reload
+is instantly fresh — no cache-busting, no invalidation), and registers the release. It works from
+**anywhere** — local, Claude, CI, or a build step — because the builder builds and the platform
+hosts; there's no dependency on any external host for dev.
+
+Use this for dev. Use the **register-a-URL** flow below when *you* host the bundle (a beta/stable
+CDN deploy, or an external host) and just want to register where it lives + its manifest.
+
+---
+
 ## Two "wheres": the API host vs the bundle CDN
 
 Deploying touches two different locations — keep them distinct:

package/docs/overview.md

@@ -63,6 +63,8 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Containers** | `docs/containers.md` | Building full-app embeddable containers (lazy-loaded) |
 | **Mobile Admin Container** | `docs/mobile-admin-container.md` | Building a separate Capacitor-aware mobile admin bundle for field operators |
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
+| **Server Functions** | `docs/server-functions.md` | App-authored server-side functions `(ctx, event) ⇒ result`: security model, runtime surface, invoking |
+| **Deploying & Registering** | `docs/deploying-apps.md` | Getting your app into the platform: fast dev publish, channels, deploy keys, registering releases |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
 | **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |

package/docs/server-functions.md

@@ -63,6 +63,47 @@ in a bundle alongside your widgets/containers:
 
 Each definition maps to an exported handler of the same `name` (override with `handler`).
 
+## Building the functions bundle
+
+The handlers ship as a **self-contained UMD** — one file, all dependencies compiled in, no
+`require`/`import` of platform or Node modules (see [Runtime](#runtime--what-your-function-can-use)).
+Your functions entry just **named-exports** each handler:
+
+```js
+// src/functions/index.js — the functions entry
+export async function submitCompetitionEntry(ctx, event) { /* … */ }
+export async function onProofCreated(ctx, event) { /* … */ }
+```
+
+Build it to `dist/functions.umd.js` with a Vite lib build — **UMD format, nothing externalised**
+(so it's self-contained), and don't wipe the widgets you built into the same `dist/`:
+
+```ts
+// vite.functions.config.ts
+import { defineConfig } from 'vite'
+export default defineConfig({
+  build: {
+    lib: { entry: 'src/functions/index.js', formats: ['umd'], name: 'functions',
+           fileName: () => 'functions.umd.js' },
+    outDir: 'dist',
+    emptyOutDir: false,            // co-exist with the widgets/containers build
+    rollupOptions: { external: [] } // bundle everything — no Node/platform externals
+  },
+})
+```
+
+```jsonc
+// package.json — build widgets/containers as usual, then the functions bundle
+"scripts": {
+  "build": "vite build && vite build --config vite.functions.config.ts"
+}
+```
+
+That emits `dist/functions.umd.js` (matching `functions.files.js.umd`), whose named exports the
+platform pairs with your manifest `definitions`. Then **deploy** it — for dev,
+`smartlinks-publish` uploads `dist/` and registers in one step (see
+[Deploying & registering](deploying-apps.md)).
+
 ---
 
 ## The two security questions every function answers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,12 +15,14 @@
     }
   },
   "bin": {
-    "smartlinks-register-release": "scripts/register-release.mjs"
+    "smartlinks-register-release": "scripts/register-release.mjs",
+    "smartlinks-publish": "scripts/publish.mjs"
   },
   "files": [
     "dist/",
     "docs/",
     "scripts/register-release.mjs",
+    "scripts/publish.mjs",
     "openapi.yaml",
     "README.md"
   ],

package/scripts/publish.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * publish — the FAST dev publish for a SmartLinks app. Builds nothing itself: it takes an already-
+ * built `dist/`, uploads it to the SmartLinks publish endpoint, which writes it straight to the CDN
+ * (dev = no-store, instantly fresh) and registers the release. One call = host + register, no Cloud
+ * Build, no Lovable. Works from anywhere: local, Claude, CI, or a build step.
+ *
+ *   smartlinks-publish                 # build dist/ yourself first, then this
+ *   smartlinks-publish --watch         # re-publish on file change (save → live)
+ *
+ * Env:
+ *   SMARTLINKS_APP_ID       the platform app id (required)
+ *   SMARTLINKS_DEPLOY_KEY   channel-scoped deploy key (dev key is dev-only, safe to keep locally)
+ *   SMARTLINKS_API          API host (default https://smartlinks.app)
+ *   SMARTLINKS_CHANNEL      channel (default dev; only dev is supported by this fast path today)
+ * Flags: --dir <dist>  --watch  --channel <dev>
+ */
+
+import { readFileSync, readdirSync, statSync, watch } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+const args = process.argv.slice(2)
+const flag = (name, def) => { const i = args.indexOf(name); return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : true) : def }
+
+const API = process.env.SMARTLINKS_API || 'https://smartlinks.app'
+const KEY = process.env.SMARTLINKS_DEPLOY_KEY
+const APP_ID = process.env.SMARTLINKS_APP_ID
+const CHANNEL = flag('--channel', process.env.SMARTLINKS_CHANNEL || 'dev')
+const DIR = flag('--dir', 'dist')
+const WATCH = args.includes('--watch')
+
+// Mirror of the server's write allowlist — a bundle is static web assets only.
+const ALLOWED = new Set(['.js', '.mjs', '.css', '.json', '.map', '.wasm', '.html', '.txt',
+  '.svg', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.ico', '.woff', '.woff2', '.ttf', '.otf'])
+const extOf = (p) => { const i = p.lastIndexOf('.'); return i < 0 ? '' : p.slice(i).toLowerCase() }
+
+function fail(msg) { console.error(`❌ ${msg}`); process.exit(1) }
+if (!APP_ID) fail('SMARTLINKS_APP_ID is required')
+if (!KEY) fail('SMARTLINKS_DEPLOY_KEY is required')
+
+function collectFiles(dir) {
+  const out = {}
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, e.name)
+      if (e.isDirectory()) { walk(full); continue }
+      if (!ALLOWED.has(extOf(e.name))) continue
+      const rel = relative(dir, full).split(sep).join('/') // forward slashes for the bucket
+      out[rel] = readFileSync(full).toString('base64')
+    }
+  }
+  walk(dir)
+  return out
+}
+
+async function publishOnce() {
+  let stat
+  try { stat = statSync(DIR) } catch { fail(`build dir not found: ${DIR} (build first)`) }
+  if (!stat.isDirectory()) fail(`${DIR} is not a directory`)
+
+  const files = collectFiles(DIR)
+  if (!files['app.manifest.json']) fail(`${DIR}/app.manifest.json not found — is this a built app bundle?`)
+
+  const t0 = Date.now()
+  const res = await fetch(`${API}/api/v1/apps/${APP_ID}/publish?channel=${encodeURIComponent(CHANNEL)}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-smartlinks-deploy-key': KEY },
+    body: JSON.stringify({ files }),
+  }).catch((e) => fail(`request failed — ${e.message}`))
+
+  const b = await res.json().catch(() => ({}))
+  if (!res.ok || !b.ok) {
+    console.error(`❌ publish failed (${res.status}):`)
+    for (const e of b.errors || []) console.error(`   • ${e.path || ''}: ${e.message}`)
+    if (WATCH) return false // keep watching; don't exit
+    process.exit(1)
+  }
+  for (const w of b.warnings || []) console.warn(`   ⚠︎ ${w.path}: ${w.message}`)
+  console.log(`✅ ${APP_ID}@${b.version} → ${CHANNEL} (${Object.keys(files).length} files, ${Date.now() - t0}ms) — functions: ${(b.functions || []).join(', ') || 'none'}`)
+  console.log(`   ${b.bundleBaseUrl}`)
+  return true
+}
+
+if (!WATCH) {
+  await publishOnce()
+} else {
+  console.log(`👀 watching ${DIR} — publishing ${APP_ID} to ${CHANNEL} on change (Ctrl+C to stop)`)
+  await publishOnce()
+  let timer = null
+  let publishing = false
+  watch(DIR, { recursive: true }, () => {
+    clearTimeout(timer)
+    timer = setTimeout(async () => {
+      if (publishing) return
+      publishing = true
+      try { await publishOnce() } finally { publishing = false }
+    }, 300) // debounce a burst of file writes from one build
+  })
+}