@proveanything/smartlinks 2.0.2 → 2.0.3

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.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

@@ -134,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` |

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.2  |  Generated: 2026-09-19T12:10:30.440Z
+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

@@ -134,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` |

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.2",
+  "version": "2.0.3",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",