@proveanything/smartlinks 2.0.2 → 2.0.4

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.2  |  Generated: 2026-09-19T12:10:30.440Z
+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:
@@ -134,7 +159,7 @@ Content-Type: application/json
 
 | Status | Meaning |
 |---|---|
-| `200` | Registered. Body: `{ ok: true, appId, channel, version, functions: [names], registeredAt }` |
+| `200` | Registered. Body: `{ ok: true, appId, channel, version, functions: [names], registeredAt, warnings? }` — `warnings` is present for non-blocking issues (e.g. `APPID_IGNORED` when the manifest declared a different id). |
 | `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` |

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
@@ -159,7 +200,9 @@ interface ServerFunctionContext {
   /** Outbound HTTP — present only if you declared `network` (host-scoped if `network:<host>`). */
   fetch: typeof fetch
 
-  /** Structured logging, captured into your function's run telemetry. */
+  /** Structured logging — returned inline on the admin surface and recorded as an
+   *  execution activity event (owner Errors & Activity console). See "Seeing your
+   *  function's runs and logs" below. */
   log: (message: string, data?: Record<string, any>) => void
 }
 ```
@@ -171,6 +214,73 @@ the only way authority stays correct.
 
 ---
 
+## Runtime — what your function can use
+
+Your function runs in a **web-standard sandbox** (think Cloudflare Workers / Deno), **not
+Node**. Concretely it targets the **WinterTC Minimum Common Web Platform API** (WinterTC is the
+Ecma International technical committee for this, formerly WinterCG) — the same surface those
+runtimes guarantee — so what you can rely on is portable, and the future isolated runner will
+host the same bundle unchanged.
+
+**Available globals** (no import needed):
+- **Data / encoding:** `JSON`, `URL`, `URLSearchParams`, `TextEncoder` / `TextDecoder`,
+  `atob` / `btoa`, `Buffer`, `structuredClone`.
+- **Crypto:** `crypto` (Web Crypto) — `crypto.subtle` for hashing / HMAC / encrypt / sign /
+  verify, `crypto.getRandomValues`, `crypto.randomUUID`.
+- **HTTP:** `fetch`, `Headers`, `Request`, `Response`, `FormData`, `Blob`, `File`,
+  `AbortController` / `AbortSignal` (use one for **request timeouts**).
+- **Streams & timing:** `ReadableStream` / `WritableStream` / `TransformStream`,
+  `CompressionStream` / `DecompressionStream` (gzip/deflate for third-party payloads), the timer
+  functions, `queueMicrotask`, `performance`, `console`.
+- **Runtime identity:** `navigator.userAgent` reports the runtime key (currently
+  `"SmartLinks-Functions"`) — use it if a portable dependency needs to feature-detect the host.
+  It stays stable when functions move to the isolated runner.
+
+**Not available:** `require` / `import` of platform or Node modules, `process`, `fs`, and the
+Node built-ins (`node:crypto`, `node:http`, …). There is no ambient database, key, or network
+handle — everything the platform gives you comes through **`ctx`**.
+
+**Dependencies:** bundle them. Your build must produce a **self-contained** UMD (deps compiled
+in), and those deps must be **edge-compatible** — pure JS / Web APIs. A library that reaches for
+Node built-ins (e.g. `axios`'s Node adapter, anything using `node:crypto`) will fail to load.
+Prefer the platform primitives above over a dependency; when you do need one, pick edge-safe:
+
+| Need | Native? | Recommended (bundle, edge-safe) |
+|---|---|---|
+| JSON | **native** — `JSON.parse/stringify` | — |
+| XML parse / build | no | `fast-xml-parser` |
+| CSV | no | `papaparse` |
+| Schema validation of inputs | no | `zod` |
+| JWT (sign/verify for a third-party API) | Web Crypto can, verbosely | `jose` |
+| Hash / HMAC / encrypt | **native** — `crypto.subtle` | — |
+
+**The common actions, and how to do each:**
+
+| You want to… | Use | Requires |
+|---|---|---|
+| Call a third-party API (GET/POST) | `ctx.fetch(url, init)` — the standard Fetch API | capability `network` or `network:<host>` |
+| Read a secret (API key, signing key) | `await ctx.secrets.get('<ref>')` | capability `secrets:<ref>` |
+| Hash / HMAC-sign / verify / encrypt | `crypto.subtle` (Web Crypto) | — |
+| Random id / bytes | `crypto.randomUUID()` / `crypto.getRandomValues()` | — |
+| Read or write SmartLinks data | `ctx.sl.*` (records, products, attestations, …) | the matching `sl:<res>:<read\|write>` |
+
+Notes:
+- **Talking to the SmartLinks core is `ctx.sl`, not HTTP.** The common pattern — *validate /
+  process, then act on the core* — is: check the input, then call `ctx.sl.appRecords.create(…)`,
+  `ctx.sl.products.update(…)`, etc. `ctx.sl` is already authenticated as your declared authority
+  and capped by your capabilities, so you never construct a SmartLinks API URL or carry a key.
+  Use `fetch`/`ctx.fetch` for *third-party* servers; use `ctx.sl` for SmartLinks itself.
+- **There is one `fetch`, and it is capability-gated.** Whether you call the global `fetch` or
+  `ctx.fetch`, the behaviour is identical: the call **throws** unless your declared `network`
+  (or `network:<host>`) capability covers the target host — the same way Deno's `fetch` throws
+  without `--allow-net`. There is no ungated escape hatch. Declare the hosts you need.
+- **Secrets are read-only at runtime.** You fetch a secret you declared; you do **not** set or
+  rotate secrets from a function — that's an admin/deploy-time operation on the platform.
+- **Signing a webhook / verifying a signature** is `crypto.subtle` with an HMAC key imported
+  from a secret — no Node `crypto` needed.
+
+---
+
 ## Worked example — a public competition entry
 
 ```ts
@@ -220,14 +330,41 @@ POST /public/collection/:collectionId/functions/:name    # visibility: public (a
 The request body is delivered to the handler as `event.body` (query string as
 `event.query`). A function only runs on its own surface — calling an `admin` function on
 the public endpoint is a `403`. The response is `{ ok: true, result }` on success, or
-`{ error, message }` (HTTP 400) if the handler returned an error. `GET` on either endpoint
-lists the functions callable on that surface.
+`{ error, message }` (HTTP 400) if the handler returned an error. On the **admin surface**
+the response also includes `logs` (your `ctx.log` lines) and `durationMs` for quick
+debugging; the **public surface returns only `result`** (a public caller never sees your
+internal logs). `GET` on either endpoint lists the functions callable on that surface.
 
 The admin surface is collection-admin gated, so an admin function's `caller` authority runs
 at admin level, attributed to the signed-in admin. The public surface resolves auth if a
 token is present (→ `owner`) and treats its absence as anonymous (→ `public`); a
 `collection`-authority function runs elevated regardless.
 
+### Before it will resolve
+
+An http call returns `404 FUNCTION_NOT_FOUND` unless **both** of these are true (this is the
+most common first-run surprise):
+
+1. **The app's release is registered on the channel** the collection follows (see
+   [deploying-apps.md](deploying-apps.md)) — that's what publishes the function bundle into
+   the registry the runtime loads from.
+2. **The app is enabled on the collection** (`appConfig.apps[]`, on that same channel — see
+   [appConfig.md](appConfig.md)).
+
+So the end-to-end path is: *write → register the release → enable on a collection → call.*
+
+### Seeing your function's runs and logs
+
+Every invocation is recorded as an **execution** activity event, carrying your `ctx.log`
+lines. Where to look, easiest first:
+
+- **Admin-surface response** — `logs` + `durationMs` come straight back in the JSON.
+- **Deployed test mode** — see below; real run, isolated logging.
+- **Owner console** — the collection's **Advanced → Errors & Activity → events** tab,
+  filtered to **source = execution**: each run shows as `function <name> ok` (or an error),
+  and the detail carries your `ctx.log` output. (Telemetry is streamed, so allow a few
+  seconds.)
+
 ## Testing & preview
 
 You don't have to deploy to find out whether a function works. There are three levels of

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.2  |  Generated: 2026-09-19T12:10:30.440Z
+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:
@@ -134,7 +159,7 @@ Content-Type: application/json
 
 | Status | Meaning |
 |---|---|
-| `200` | Registered. Body: `{ ok: true, appId, channel, version, functions: [names], registeredAt }` |
+| `200` | Registered. Body: `{ ok: true, appId, channel, version, functions: [names], registeredAt, warnings? }` — `warnings` is present for non-blocking issues (e.g. `APPID_IGNORED` when the manifest declared a different id). |
 | `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` |

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
@@ -159,7 +200,9 @@ interface ServerFunctionContext {
   /** Outbound HTTP — present only if you declared `network` (host-scoped if `network:<host>`). */
   fetch: typeof fetch
 
-  /** Structured logging, captured into your function's run telemetry. */
+  /** Structured logging — returned inline on the admin surface and recorded as an
+   *  execution activity event (owner Errors & Activity console). See "Seeing your
+   *  function's runs and logs" below. */
   log: (message: string, data?: Record<string, any>) => void
 }
 ```
@@ -171,6 +214,73 @@ the only way authority stays correct.
 
 ---
 
+## Runtime — what your function can use
+
+Your function runs in a **web-standard sandbox** (think Cloudflare Workers / Deno), **not
+Node**. Concretely it targets the **WinterTC Minimum Common Web Platform API** (WinterTC is the
+Ecma International technical committee for this, formerly WinterCG) — the same surface those
+runtimes guarantee — so what you can rely on is portable, and the future isolated runner will
+host the same bundle unchanged.
+
+**Available globals** (no import needed):
+- **Data / encoding:** `JSON`, `URL`, `URLSearchParams`, `TextEncoder` / `TextDecoder`,
+  `atob` / `btoa`, `Buffer`, `structuredClone`.
+- **Crypto:** `crypto` (Web Crypto) — `crypto.subtle` for hashing / HMAC / encrypt / sign /
+  verify, `crypto.getRandomValues`, `crypto.randomUUID`.
+- **HTTP:** `fetch`, `Headers`, `Request`, `Response`, `FormData`, `Blob`, `File`,
+  `AbortController` / `AbortSignal` (use one for **request timeouts**).
+- **Streams & timing:** `ReadableStream` / `WritableStream` / `TransformStream`,
+  `CompressionStream` / `DecompressionStream` (gzip/deflate for third-party payloads), the timer
+  functions, `queueMicrotask`, `performance`, `console`.
+- **Runtime identity:** `navigator.userAgent` reports the runtime key (currently
+  `"SmartLinks-Functions"`) — use it if a portable dependency needs to feature-detect the host.
+  It stays stable when functions move to the isolated runner.
+
+**Not available:** `require` / `import` of platform or Node modules, `process`, `fs`, and the
+Node built-ins (`node:crypto`, `node:http`, …). There is no ambient database, key, or network
+handle — everything the platform gives you comes through **`ctx`**.
+
+**Dependencies:** bundle them. Your build must produce a **self-contained** UMD (deps compiled
+in), and those deps must be **edge-compatible** — pure JS / Web APIs. A library that reaches for
+Node built-ins (e.g. `axios`'s Node adapter, anything using `node:crypto`) will fail to load.
+Prefer the platform primitives above over a dependency; when you do need one, pick edge-safe:
+
+| Need | Native? | Recommended (bundle, edge-safe) |
+|---|---|---|
+| JSON | **native** — `JSON.parse/stringify` | — |
+| XML parse / build | no | `fast-xml-parser` |
+| CSV | no | `papaparse` |
+| Schema validation of inputs | no | `zod` |
+| JWT (sign/verify for a third-party API) | Web Crypto can, verbosely | `jose` |
+| Hash / HMAC / encrypt | **native** — `crypto.subtle` | — |
+
+**The common actions, and how to do each:**
+
+| You want to… | Use | Requires |
+|---|---|---|
+| Call a third-party API (GET/POST) | `ctx.fetch(url, init)` — the standard Fetch API | capability `network` or `network:<host>` |
+| Read a secret (API key, signing key) | `await ctx.secrets.get('<ref>')` | capability `secrets:<ref>` |
+| Hash / HMAC-sign / verify / encrypt | `crypto.subtle` (Web Crypto) | — |
+| Random id / bytes | `crypto.randomUUID()` / `crypto.getRandomValues()` | — |
+| Read or write SmartLinks data | `ctx.sl.*` (records, products, attestations, …) | the matching `sl:<res>:<read\|write>` |
+
+Notes:
+- **Talking to the SmartLinks core is `ctx.sl`, not HTTP.** The common pattern — *validate /
+  process, then act on the core* — is: check the input, then call `ctx.sl.appRecords.create(…)`,
+  `ctx.sl.products.update(…)`, etc. `ctx.sl` is already authenticated as your declared authority
+  and capped by your capabilities, so you never construct a SmartLinks API URL or carry a key.
+  Use `fetch`/`ctx.fetch` for *third-party* servers; use `ctx.sl` for SmartLinks itself.
+- **There is one `fetch`, and it is capability-gated.** Whether you call the global `fetch` or
+  `ctx.fetch`, the behaviour is identical: the call **throws** unless your declared `network`
+  (or `network:<host>`) capability covers the target host — the same way Deno's `fetch` throws
+  without `--allow-net`. There is no ungated escape hatch. Declare the hosts you need.
+- **Secrets are read-only at runtime.** You fetch a secret you declared; you do **not** set or
+  rotate secrets from a function — that's an admin/deploy-time operation on the platform.
+- **Signing a webhook / verifying a signature** is `crypto.subtle` with an HMAC key imported
+  from a secret — no Node `crypto` needed.
+
+---
+
 ## Worked example — a public competition entry
 
 ```ts
@@ -220,14 +330,41 @@ POST /public/collection/:collectionId/functions/:name    # visibility: public (a
 The request body is delivered to the handler as `event.body` (query string as
 `event.query`). A function only runs on its own surface — calling an `admin` function on
 the public endpoint is a `403`. The response is `{ ok: true, result }` on success, or
-`{ error, message }` (HTTP 400) if the handler returned an error. `GET` on either endpoint
-lists the functions callable on that surface.
+`{ error, message }` (HTTP 400) if the handler returned an error. On the **admin surface**
+the response also includes `logs` (your `ctx.log` lines) and `durationMs` for quick
+debugging; the **public surface returns only `result`** (a public caller never sees your
+internal logs). `GET` on either endpoint lists the functions callable on that surface.
 
 The admin surface is collection-admin gated, so an admin function's `caller` authority runs
 at admin level, attributed to the signed-in admin. The public surface resolves auth if a
 token is present (→ `owner`) and treats its absence as anonymous (→ `public`); a
 `collection`-authority function runs elevated regardless.
 
+### Before it will resolve
+
+An http call returns `404 FUNCTION_NOT_FOUND` unless **both** of these are true (this is the
+most common first-run surprise):
+
+1. **The app's release is registered on the channel** the collection follows (see
+   [deploying-apps.md](deploying-apps.md)) — that's what publishes the function bundle into
+   the registry the runtime loads from.
+2. **The app is enabled on the collection** (`appConfig.apps[]`, on that same channel — see
+   [appConfig.md](appConfig.md)).
+
+So the end-to-end path is: *write → register the release → enable on a collection → call.*
+
+### Seeing your function's runs and logs
+
+Every invocation is recorded as an **execution** activity event, carrying your `ctx.log`
+lines. Where to look, easiest first:
+
+- **Admin-surface response** — `logs` + `durationMs` come straight back in the JSON.
+- **Deployed test mode** — see below; real run, isolated logging.
+- **Owner console** — the collection's **Advanced → Errors & Activity → events** tab,
+  filtered to **source = execution**: each run shows as `function <name> ok` (or an error),
+  and the detail carries your `ctx.log` output. (Telemetry is streamed, so allow a few
+  seconds.)
+
 ## Testing & preview
 
 You don't have to deploy to find out whether a function works. There are three levels of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.2",
+  "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
+  })
+}