@proveanything/smartlinks 2.0.1 → 2.0.3

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.1  |  Generated: 2026-09-16T05:23:18.331Z
+Version: 2.0.3  |  Generated: 2026-09-20T09:34:31.596Z
 
 This is a concise summary of all available API functions and types.
 

package/dist/docs/deploying-apps.md

@@ -71,9 +71,13 @@ 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 |
+| `dev`   | **Lovable "Publish"** | Live development / testing |
+| `alpha` | your pipeline | Early internal testing |
+| `beta`  | your pipeline | Staging / preview |
+| `stable`| your **Cloud Build** toolset (from git) | Production |
+
+The canonical channels are **`dev` · `alpha` · `beta` · `stable`**. Legacy `prod`/`production`/
+`live` are accepted and normalise to **`stable`** (there is no separate "prod" channel).
 
 A collection chooses which channel it follows, so you can point a test collection at `dev`
 and exercise a build before it reaches `prod`.
@@ -130,7 +134,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` |
@@ -155,7 +159,11 @@ today.)
 
 ### What gets validated
 
-- `manifest.meta.appId` must match the `{appId}` in the URL.
+- The **app id is the `{appId}` in the URL** — the platform-assigned id, which is authoritative
+  (it's what every collection's config + the CDN path already bind to). `manifest.meta.appId` is
+  **ignored** for identity: if it differs, the release still registers under the URL id and you get
+  a non-blocking `APPID_IGNORED` warning. So pass your **platform id** in the URL (the script below
+  reads it from `SMARTLINKS_APP_ID`), and don't rely on the manifest to declare it.
 - 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
@@ -169,70 +177,42 @@ Registration is the **last step of your build** — after bundles are built and
 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:
+The SDK ships the script, so you don't copy-paste it — run it as your postbuild step. It reads
+your built manifest, POSTs it, prints any warnings, and exits non-zero on failure.
 
 ```jsonc
 // package.json
 "scripts": {
   "build":     "vite build && … && node scripts/hash-bundles.mjs",
-  "postbuild": "node scripts/register-release.mjs"
+  "postbuild": "smartlinks-register-release"   // ships in @proveanything/smartlinks
 }
 ```
 
+It is driven entirely by env vars, so the same command works for dev (Lovable) and prod (CI):
+
+| Env var | Required | What it is |
+|---|---|---|
+| `SMARTLINKS_APP_ID` | **yes** | your **platform** app id — authoritative, assigned by SmartLinks (per-project). Not the manifest's `meta.appId`. |
+| `SMARTLINKS_DEPLOY_KEY` | yes* | channel-scoped deploy key. *dev builds skip quietly if unset; `beta`/`stable` hard-fail. |
+| `SMARTLINKS_CHANNEL` | the gate | `dev` \| `alpha` \| `beta` \| `stable` (legacy `prod` → `stable`). **UNSET ⇒ skip** (preview builds never register). |
+| `SMARTLINKS_BUNDLE_BASE_URL` | recommended | where the files are served — **dev:** your Lovable URL; **prod:** the CDN base. |
+| `SMARTLINKS_API` | no | API host; default `https://smartlinks.app`. A VPC env uses its own. |
+| `SMARTLINKS_MANIFEST` | no | manifest path; default `dist/app.manifest.json`. |
+
+> The full source is at `scripts/register-release.mjs` in the SDK package if you'd rather vendor it.
+
 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** |
+| **Prod (CI)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+
+**Two secrets, two scopes:** the **deploy key** is channel-scoped and can be a *workspace-level*
+Lovable Build Secret shared by every app (a dev key only writes `dev`, so sharing it is safe). The
+**`SMARTLINKS_APP_ID` is per-app** — set it as a *project-level* variable on each app, so each
+registers under its own authoritative platform id.
 
 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

package/dist/docs/server-functions.md

@@ -159,7 +159,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 +173,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 +289,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.1  |  Generated: 2026-09-16T05:23:18.331Z
+Version: 2.0.3  |  Generated: 2026-09-20T09:34:31.596Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/deploying-apps.md

@@ -71,9 +71,13 @@ 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 |
+| `dev`   | **Lovable "Publish"** | Live development / testing |
+| `alpha` | your pipeline | Early internal testing |
+| `beta`  | your pipeline | Staging / preview |
+| `stable`| your **Cloud Build** toolset (from git) | Production |
+
+The canonical channels are **`dev` · `alpha` · `beta` · `stable`**. Legacy `prod`/`production`/
+`live` are accepted and normalise to **`stable`** (there is no separate "prod" channel).
 
 A collection chooses which channel it follows, so you can point a test collection at `dev`
 and exercise a build before it reaches `prod`.
@@ -130,7 +134,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` |
@@ -155,7 +159,11 @@ today.)
 
 ### What gets validated
 
-- `manifest.meta.appId` must match the `{appId}` in the URL.
+- The **app id is the `{appId}` in the URL** — the platform-assigned id, which is authoritative
+  (it's what every collection's config + the CDN path already bind to). `manifest.meta.appId` is
+  **ignored** for identity: if it differs, the release still registers under the URL id and you get
+  a non-blocking `APPID_IGNORED` warning. So pass your **platform id** in the URL (the script below
+  reads it from `SMARTLINKS_APP_ID`), and don't rely on the manifest to declare it.
 - 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
@@ -169,70 +177,42 @@ Registration is the **last step of your build** — after bundles are built and
 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:
+The SDK ships the script, so you don't copy-paste it — run it as your postbuild step. It reads
+your built manifest, POSTs it, prints any warnings, and exits non-zero on failure.
 
 ```jsonc
 // package.json
 "scripts": {
   "build":     "vite build && … && node scripts/hash-bundles.mjs",
-  "postbuild": "node scripts/register-release.mjs"
+  "postbuild": "smartlinks-register-release"   // ships in @proveanything/smartlinks
 }
 ```
 
+It is driven entirely by env vars, so the same command works for dev (Lovable) and prod (CI):
+
+| Env var | Required | What it is |
+|---|---|---|
+| `SMARTLINKS_APP_ID` | **yes** | your **platform** app id — authoritative, assigned by SmartLinks (per-project). Not the manifest's `meta.appId`. |
+| `SMARTLINKS_DEPLOY_KEY` | yes* | channel-scoped deploy key. *dev builds skip quietly if unset; `beta`/`stable` hard-fail. |
+| `SMARTLINKS_CHANNEL` | the gate | `dev` \| `alpha` \| `beta` \| `stable` (legacy `prod` → `stable`). **UNSET ⇒ skip** (preview builds never register). |
+| `SMARTLINKS_BUNDLE_BASE_URL` | recommended | where the files are served — **dev:** your Lovable URL; **prod:** the CDN base. |
+| `SMARTLINKS_API` | no | API host; default `https://smartlinks.app`. A VPC env uses its own. |
+| `SMARTLINKS_MANIFEST` | no | manifest path; default `dist/app.manifest.json`. |
+
+> The full source is at `scripts/register-release.mjs` in the SDK package if you'd rather vendor it.
+
 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** |
+| **Prod (CI)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+
+**Two secrets, two scopes:** the **deploy key** is channel-scoped and can be a *workspace-level*
+Lovable Build Secret shared by every app (a dev key only writes `dev`, so sharing it is safe). The
+**`SMARTLINKS_APP_ID` is per-app** — set it as a *project-level* variable on each app, so each
+registers under its own authoritative platform id.
 
 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

package/docs/server-functions.md

@@ -159,7 +159,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 +173,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 +289,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.1",
+  "version": "2.0.3",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,9 +14,13 @@
       "default": "./dist/testing/index.js"
     }
   },
+  "bin": {
+    "smartlinks-register-release": "scripts/register-release.mjs"
+  },
   "files": [
     "dist/",
     "docs/",
+    "scripts/register-release.mjs",
     "openapi.yaml",
     "README.md"
   ],

package/scripts/register-release.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * register-release — the post-build "register on publish" step for a SmartLinks app.
+ *
+ * Runs at the END of a build (after the bundles are built + hashed): reads the built
+ * app.manifest.json and POSTs it to the SmartLinks install endpoint so the release is
+ * validated + recorded in the registry (push model). Exits non-zero on failure so a bad
+ * manifest / function fails the publish.
+ *
+ * ONE script for both paths:
+ *   - dev from Lovable  → SMARTLINKS_CHANNEL=dev, dev deploy key, bundleBaseUrl = your Lovable URL
+ *   - prod/beta via CI  → SMARTLINKS_CHANNEL=stable|beta, prod key, bundleBaseUrl = the CDN base
+ *
+ * IDENTITY (important): the SmartLinks app id is assigned by the PLATFORM, not self-declared in
+ * the manifest. Pass it as SMARTLINKS_APP_ID. The manifest's meta.appId is ignored by the
+ * backend (the installed id is authoritative); if they differ the backend just warns. If
+ * SMARTLINKS_APP_ID is unset we fall back to manifest.meta.appId with a warning — set it.
+ *
+ * Env:
+ *   SMARTLINKS_APP_ID            the app's platform id (REQUIRED for correctness; per-project)
+ *   SMARTLINKS_DEPLOY_KEY        channel-scoped deploy key (dev key is safe to keep as a Lovable
+ *                                workspace Build Secret — its scope is the dev channel only)
+ *   SMARTLINKS_CHANNEL           dev | alpha | beta | stable (also accepts legacy 'prod' → stable);
+ *                                UNSET ⇒ skip quietly (preview/live-edit builds never register)
+ *   SMARTLINKS_API               API host (default https://smartlinks.app); a VPC env uses its own
+ *   SMARTLINKS_BUNDLE_BASE_URL   where the built files are served (dev: your Lovable URL;
+ *                                prod: https://smartlinks.app/apps/<appId>/<version>)
+ *   SMARTLINKS_MANIFEST          manifest path (default dist/app.manifest.json)
+ */
+
+import { readFileSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+
+const API      = process.env.SMARTLINKS_API || 'https://smartlinks.app'
+const KEY      = process.env.SMARTLINKS_DEPLOY_KEY
+const CHANNEL  = process.env.SMARTLINKS_CHANNEL
+const MANIFEST = process.env.SMARTLINKS_MANIFEST || 'dist/app.manifest.json'
+
+// --- Gate: only register when this build is meant to ship a release ---
+if (!CHANNEL) {
+  console.log('ℹ︎ SmartLinks: SMARTLINKS_CHANNEL unset — skipping release registration (preview build).')
+  process.exit(0)
+}
+if (!KEY) {
+  // A prod/beta build with no key is a real misconfiguration; dev skips quietly.
+  if (CHANNEL !== 'dev') { console.error(`❌ SmartLinks: "${CHANNEL}" build but SMARTLINKS_DEPLOY_KEY is missing`); process.exit(1) }
+  console.log(`ℹ︎ SmartLinks: no deploy key for "${CHANNEL}" — skipping registration.`)
+  process.exit(0)
+}
+
+let manifest
+try {
+  manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'))
+} catch (e) {
+  console.error(`❌ SmartLinks: could not read manifest at ${MANIFEST} — ${e.message}`)
+  process.exit(1)
+}
+
+// The platform id is authoritative. Fall back to the manifest's declared id only if it wasn't
+// injected — and say so, because that self-declared id is exactly what drifts.
+let appId = process.env.SMARTLINKS_APP_ID
+if (!appId) {
+  appId = manifest?.meta?.appId
+  console.warn(`⚠︎ SmartLinks: SMARTLINKS_APP_ID not set — falling back to manifest.meta.appId "${appId}". Set SMARTLINKS_APP_ID to the platform id to be safe.`)
+}
+if (!appId) { console.error('❌ SmartLinks: no app id (set SMARTLINKS_APP_ID)'); process.exit(1) }
+
+const version = String(manifest?.meta?.version || '')
+if (!version) { console.error('❌ SmartLinks: manifest.meta.version is required'); process.exit(1) }
+
+const gitHash = (() => { try { return execSync('git rev-parse --short HEAD').toString().trim() } catch { return null } })()
+const bundleBaseUrl = process.env.SMARTLINKS_BUNDLE_BASE_URL || `${API}/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' },
+  }),
+}).catch((e) => { console.error(`❌ SmartLinks: request failed — ${e.message}`); process.exit(1) })
+
+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
+}
+// Non-blocking warnings (e.g. the manifest declared a different id, which the platform ignores).
+for (const w of body.warnings || []) console.warn(`   ⚠︎ ${w.path}: ${w.message}`)
+console.log(`✅ Registered ${appId}@${version} on "${body.channel || CHANNEL}" — functions: ${(body.functions || []).join(', ') || 'none'}`)