@proveanything/smartlinks 1.17.5 → 2.0.0-alpha.1

package/dist/docs/deploying-apps.md

@@ -0,0 +1,193 @@
+# Deploying & registering an app
+
+> **Preview — SmartLinks SDK 2.0.0-alpha.** Part of the installable-app platform being built
+> toward 2.0.0 stable. These APIs may change before then. Published under the npm `next` tag;
+> `latest` remains 1.x.
+
+A SmartLinks app is a bundle (widgets, containers, and — new — [server functions](server-functions.md))
+described by an `app.manifest.json`. Deploying an app has two halves:
+
+1. **Publish the bundles** to the SmartLinks app CDN.
+2. **Register the release** — tell the SmartLinks backend a new version exists, hand it the
+   manifest, and let it validate everything. Registration is what makes the app (and its
+   server functions) known, installable, and testable.
+
+This guide covers registration and how to wire it into your build.
+
+---
+
+## Two "wheres": the API host vs the bundle CDN
+
+Deploying touches two different locations — keep them distinct:
+
+1. **The install endpoint (API host)** — *where you register*. This is a SmartLinks
+   **API v1** endpoint, and its **host is the environment** you're installing into (see
+   below). This is the one that varies per deployment.
+2. **The bundle CDN** — *where your files are served from*. **Today always `smartlinks.app`**:
+
+   ```
+   https://smartlinks.app/apps/{appId}/{version}/app.manifest.json
+   https://smartlinks.app/apps/{appId}/{version}/widgets-<hash>.umd.js
+   https://smartlinks.app/apps/{appId}/{version}/functions.umd.js
+   ```
+
+   That base — `https://smartlinks.app/apps/{appId}/{version}` — is your **`bundleBaseUrl`**,
+   which you pass at registration. Always pass it explicitly so nothing breaks if the CDN
+   location changes later.
+
+## Environments & the app registry
+
+Historically an app was **stateless everywhere**: every environment fetched the same CDN
+manifest on the fly, so apps were agnostic to shards, clients, and VPCs. Registration changes
+that — an app is now **installed into an environment's registry**, which is **global to that
+environment (not per-collection / not per-shard)**.
+
+An **environment** is one SmartLinks deployment: the main SaaS, or a client's isolated (VPC)
+instance. Each owns its own app registry, so:
+
+- The **install endpoint's host is the environment** — `POST https://<that-env's-api>/api/v1/apps/…`.
+  Installing into a client's VPC means calling *their* API with *their* deploy key.
+- **Rolling out to several environments = the same call, once per target** (different API host
+  + key each). The registration script below takes the API base as a parameter for exactly this.
+
+> Enabling an app on a specific **collection** (and consenting to its capabilities) is a
+> separate, per-collection step layered on top of the environment's registry.
+
+---
+
+## Channels
+
+A release is registered on one **channel**, matching how you deploy:
+
+| Channel | Deployed from | Typical use |
+|---|---|---|
+| `dev`  | **Lovable "Publish"** | Live development / testing |
+| `beta` | your pipeline | Staging / preview |
+| `prod` | your **Cloud Build** toolset (from git) | Production |
+
+A collection chooses which channel it follows, so you can point a test collection at `dev`
+and exercise a build before it reaches `prod`.
+
+---
+
+## Deploy keys
+
+Registration is authenticated by a **deploy key** — not a user login — scoped to the
+channels it may write. Security comes from the *scope*, so a key that leaks can only affect
+what it was allowed to touch.
+
+| Key | Lives in | May write |
+|---|---|---|
+| **Dev key** | your app's (private) source / build env | `dev` channel only |
+| **Prod master key** | your Cloud Build toolset only — never in app source | all channels |
+| **Per-app key** *(future)* | a client's build | one specific app |
+
+Because a Lovable build has no secret store, the **dev key lives in your app source** — which
+is safe precisely because it can only ever write the `dev` channel. The **prod key stays in
+Cloud Build**. Present the key in the `x-smartlinks-deploy-key` header.
+
+---
+
+## The registration endpoint
+
+```
+POST https://<smartlinks-api>/api/v1/apps/{appId}/releases
+x-smartlinks-deploy-key: <your deploy key>
+Content-Type: application/json
+```
+
+```jsonc
+{
+  "channel": "dev",                 // dev | beta | prod
+  "version": "1.2.3",               // from your manifest meta.version
+  "build":   { "at": "2026-09-14T10:00:00Z", "gitHash": "abc1234", "builder": "lovable" },
+  "manifest": { /* your full app.manifest.json, including the functions block */ },
+  "bundleBaseUrl": "https://smartlinks.app/apps/currys/1.2.3"
+}
+```
+
+### Responses
+
+| Status | Meaning |
+|---|---|
+| `200` | Registered. Body: `{ ok: true, appId, channel, version, functions: [names], registeredAt }` |
+| `422` | Validation failed — **the build should fail**. Body: `{ ok: false, errors: [...] }` |
+| `401` | Missing/invalid deploy key |
+| `403` | Key not permitted for that channel (e.g. a dev key targeting `prod`) — `CHANNEL_FORBIDDEN` |
+
+Each validation error is `{ code, message, path }`, e.g.:
+
+```json
+{ "ok": false, "errors": [
+  { "code": "AUTHORITY_INVALID", "message": "invalid authority \"root\"", "path": "functions.definitions[0].authority" },
+  { "code": "CAPABILITY_INVALID", "message": "invalid capability \"bogus\"", "path": "functions.definitions[0].capabilities[0]" }
+]}
+```
+
+### What gets validated
+
+- `manifest.meta.appId` must match the `{appId}` in the URL.
+- The **`functions` block** is validated with the *same* rules the runtime enforces
+  (names, triggers, `visibility`/`authority`, the capability grammar, duplicate names) — so
+  a malformed server function is caught **at deploy time**, not at runtime. See
+  [server-functions.md](server-functions.md).
+
+---
+
+## Wiring it into your build
+
+Registration is the **last step of your build** — after bundles are built and hashed. Run a
+small script that reads your built manifest and POSTs it, and **exits non-zero on failure**
+so a bad install fails the publish.
+
+```js
+// scripts/register-release.mjs — run as the build's postbuild step
+import { readFileSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+
+const API      = process.env.SMARTLINKS_API      || 'https://api.smartlinks.app'
+const KEY      = process.env.SMARTLINKS_DEPLOY_KEY               // dev key (in source/env) or prod key (Cloud Build)
+const CHANNEL  = process.env.SMARTLINKS_CHANNEL  || 'dev'        // 'prod' in Cloud Build
+
+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 } })()
+
+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,
+    build: { at: new Date().toISOString(), gitHash, builder: CHANNEL === 'dev' ? 'lovable' : 'cloudbuild' },
+    manifest,
+    bundleBaseUrl: `https://smartlinks.app/apps/${appId}/${version}`,
+  }),
+})
+
+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, e.g.:
+
+```jsonc
+// package.json
+"scripts": {
+  "build":     "vite build && … && node scripts/hash-bundles.mjs",
+  "postbuild": "node scripts/register-release.mjs"
+}
+```
+
+- **Dev (Lovable "Publish")** runs `build` → `postbuild` with the **dev key** and
+  `SMARTLINKS_CHANNEL=dev`.
+- **Prod (Cloud Build)** runs the same with the **prod key** and `SMARTLINKS_CHANNEL=prod`.
+
+That's it: hitting Publish now validates and registers your app — and a broken manifest or
+function stops the deploy with an actionable error instead of shipping.

package/dist/docs/server-functions.md

@@ -0,0 +1,306 @@
+# Server functions ("edge functions")
+
+> **Preview — SmartLinks SDK 2.0.0-alpha.** Part of the installable-app platform being built
+> toward 2.0.0 stable (author → register → install → run → test). These APIs may change before
+> then. Published under the npm `next` tag; `latest` remains 1.x.
+
+A **server function** is arbitrary server-side JavaScript your app deploys directly into
+SmartLinks. It runs on the SmartLinks servers — with access to the full SDK, to your app's
+secrets, and to outbound network — so you can do things a browser app can't: validate and
+write on the server, call third-party systems with credentials the client never sees, react
+to events, and run scheduled work.
+
+Every server function has the **same shape**, no matter how it's triggered or where it runs:
+
+```ts
+export async function myFunction(ctx, event) {
+  // ctx  — a SmartLinks SDK pre-scoped to your declared authority, plus secrets, caller, fetch, log
+  // event — the trigger payload (the HTTP body, the event, or the cron tick)
+  return { ok: true }   // returned to the caller (http) or recorded as the run result (event/cron)
+}
+```
+
+You never receive a raw API key or a superuser client. The platform builds `ctx` fresh for
+each invocation and **pre-scopes every handle to exactly what your function declared** — this
+is how a function stays safe even when it runs with elevated authority.
+
+---
+
+## Declaring a function
+
+Functions are declared in your `app.manifest.json` under `functions`, and the handlers ship
+in a bundle alongside your widgets/containers:
+
+```jsonc
+{
+  "functions": {
+    "files": { "js": { "umd": "dist/functions.umd.js" } },
+    "definitions": [
+      {
+        "name": "submitCompetitionEntry",
+        "description": "Validate a competition entry and record it server-side.",
+        "trigger":    { "type": "http", "methods": ["POST"] },
+        "visibility": "public",              // WHO may call it
+        "authority":  "collection",          // WHOSE authority it runs as
+        "elevated":   true,                  // required ack for public + collection
+        "capabilities": ["sl:records:write", "network:api.recaptcha.net"],
+        "apiVersion": "2026-09"
+      },
+      {
+        "name": "onProofCreated",
+        "trigger":    { "type": "event", "eventTypes": ["proof.created"] },
+        "capabilities": ["sl:records:write", "secrets:crm-key", "network"]
+      },
+      {
+        "name": "nightlyReconcile",
+        "trigger":    { "type": "cron", "schedule": "0 2 * * *" },
+        "capabilities": ["sl:products:read", "sl:records:write"]
+      }
+    ]
+  }
+}
+```
+
+Each definition maps to an exported handler of the same `name` (override with `handler`).
+
+---
+
+## The two security questions every function answers
+
+Server-side code needs two questions answered up front. SmartLinks makes both **explicit and
+declarative** — you state them in the manifest, and the platform enforces them. This is the
+same split every extensible platform lands on (Salesforce `with/without sharing`, Shopify
+online/offline tokens, Lambda's invoke-policy vs execution-role).
+
+### 1. `visibility` — who is allowed to call it? *(http only)*
+
+| Value | Meaning |
+|---|---|
+| `admin`  *(default)* | Callable only from an authenticated admin surface. |
+| `public` | Publicly callable — no authenticated user required. |
+
+### 2. `authority` — whose authority does it run as?
+
+This decides what `ctx.sl` can do.
+
+| Value | `ctx.sl` is scoped to | Use when |
+|---|---|---|
+| `caller` *(default)* | The **invoking user** (their session/JWT). Can only do what that user could. | Admin actions that should respect the user's own permissions and be attributed to them. |
+| `collection` | A **collection-admin principal for _this_ collection only** — never a global superuser. | A privileged server-side action a public/anonymous caller can't be trusted to do directly. |
+
+`authority` **defaults to `caller`** — secure by default. `event`- and `cron`-triggered
+functions have no external caller, so they always run as `collection`.
+
+### The combinations
+
+- **`http` + `admin` + `caller`** — a delegated admin function; runs as the signed-in admin.
+- **`http` + `public` + `caller`** — runs as the anonymous/public user (limited). The safe public default.
+- **`http` + `public` + `collection`** — publicly callable, runs with collection authority.
+  The powerful one (e.g. "submit competition entry" needs to validate then write a record no
+  anonymous user may write directly). **Your responsibility:** validate the input and prevent
+  abuse — see below.
+- **`event` / `cron`** — background work; runs as `collection`.
+
+> ### ⚠️ Public + collection authority is the sharp edge
+> A `public` + `collection` function is reachable by anyone and runs with elevated authority.
+> The platform shrinks the blast radius for you — the authority is capped to **this one
+> collection**, and further capped by your declared **capabilities** (a competition-entry
+> function that declares only `sl:records:write` cannot delete products or read other
+> secrets, even though it's "elevated"). But **validating the request is still your job**:
+> check the payload, rate-limit using `ctx.caller`, guard against replay. Treat the function
+> body as a trust boundary.
+>
+> Because it's the sharp edge, a `public` + `collection` function must **explicitly opt in**
+> with `elevated: true` in its declaration — a conscious acknowledgment that you're exposing
+> collection authority to public callers. Without it, install/validation fails.
+
+---
+
+## Capabilities — least privilege, declared and capped
+
+`capabilities` is the allow-list of what your function may reach. It is surfaced at install
+time for consent and **enforced at runtime** — including for `collection`-authority functions.
+Declare the minimum you need.
+
+| Capability | Grants |
+|---|---|
+| `sl:<resource>:read` / `sl:<resource>:write` | SDK access to that resource, e.g. `sl:products:read`, `sl:records:write`, `sl:attestations:write`, `sl:contacts:write`. |
+| `network` | `ctx.fetch` to any host. |
+| `network:<host>` | `ctx.fetch` to that host only (repeat for several). Prefer this over blanket `network`. |
+| `secrets:<ref>` | `ctx.secrets.get('<ref>')` for that one secret ref. |
+
+If you don't declare `network`, `ctx.fetch` is absent. If you don't declare a `secrets:<ref>`,
+`ctx.secrets.get('<ref>')` returns `null`.
+
+---
+
+## The `ctx` object
+
+```ts
+interface ServerFunctionContext {
+  collectionId: string
+  appId: string
+
+  /** SmartLinks SDK, pre-scoped to your declared `authority`. Capabilities cap what it may do. */
+  sl: SmartLinks
+
+  /** Capability-gated secrets. Resolves only refs you declared via `secrets:<ref>`. */
+  secrets: { get(ref: string): Promise<string | null> }
+
+  /** Who invoked this function. */
+  caller: {
+    userId: string | null   // null for anonymous/public/system calls
+    anonymous: boolean
+    origin?: string | null  // http
+    ip?: string | null      // http
+    via: 'http' | 'event' | 'cron'
+  }
+
+  /** 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. */
+  log: (message: string, data?: Record<string, any>) => void
+}
+```
+
+**Use `ctx.sl` for anything SmartLinks** — it is the same SDK surface you use client-side,
+already authenticated as your declared authority and scoped to the collection. Do **not** try
+to construct your own SDK client or carry your own key; that's what `ctx.sl` is for, and it's
+the only way authority stays correct.
+
+---
+
+## Worked example — a public competition entry
+
+```ts
+// dist/functions — handler for the manifest definition above
+export async function submitCompetitionEntry(ctx, event) {
+  const { name, email, answer, captchaToken } = event.body || {}
+
+  // 1. Validate — this is YOUR job on a public function.
+  if (!email || !answer) return { ok: false, error: 'missing_fields' }
+
+  // 2. Use a declared secret + declared host to verify a captcha.
+  const secret = await ctx.secrets.get('recaptcha-secret')
+  const verify = await ctx.fetch('https://api.recaptcha.net/verify', {
+    method: 'POST',
+    body: new URLSearchParams({ secret, response: captchaToken }),
+  }).then(r => r.json())
+  if (!verify.success) return { ok: false, error: 'captcha_failed' }
+
+  // 3. Write with collection authority — something an anonymous caller can't do directly.
+  const entry = await ctx.sl.appRecords.create({
+    recordType: 'competition-entry',
+    data: { name, email, answer, ip: ctx.caller.ip, submittedAt: new Date().toISOString() },
+  })
+
+  ctx.log('entry recorded', { entryId: entry.id })
+  return { ok: true, entryId: entry.id }
+}
+```
+
+Declared as `public` + `collection` + `['sl:records:write', 'secrets:recaptcha-secret',
+'network:api.recaptcha.net']`, this function is publicly callable, verifies the request
+itself, and writes a record no anonymous user could write — but it cannot touch products,
+other secrets, or any other collection.
+
+---
+
+## Invoking an http function
+
+An `http` function is called by POSTing to the collection's functions endpoint on the
+surface that matches its `visibility`:
+
+```
+POST /admin/collection/:collectionId/functions/:name    # visibility: admin  (collection-admin auth)
+POST /public/collection/:collectionId/functions/:name    # visibility: public (auth optional)
+```
+
+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.
+
+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.
+
+## Testing & preview
+
+You don't have to deploy to find out whether a function works. There are three levels of
+fidelity — use them in order.
+
+### 1. Local harness (fast, offline)
+
+`@proveanything/smartlinks/testing` builds a `ctx` that **enforces the declared capability
+envelope**, so a function fails locally the same way it would in production — the common
+"I forgot to declare `sl:records:write`" bug is caught before you deploy, not after.
+
+```ts
+import { createFunctionTestContext } from '@proveanything/smartlinks/testing'
+import manifest from '../public/app.manifest.json'
+import { submitCompetitionEntry } from '../src/functions'
+
+const def = manifest.functions.definitions.find(d => d.name === 'submitCompetitionEntry')
+
+const ctx = createFunctionTestContext({
+  def,                                       // capabilities enforced come from the manifest itself
+  caller: { userId: 'tester' },
+  secrets: { 'recaptcha-secret': 'test-value' },   // fixtures — real secrets are server-only
+})
+
+const res = await submitCompetitionEntry(ctx, { method: 'POST', body: { email: 'a@b.com', answer: '42' } })
+// ctx.sl.appRecords.create(...) throws CapabilityError unless `def` declares sl:records:write
+```
+
+Pass the **`def`** (not a hand-typed capability list) so "tested" can't drift from
+"declared". By default `ctx.sl` methods return a stub result (pure unit test — no network);
+inject `sl` to delegate to your live SDK for real reads/writes:
+
+```ts
+const ctx = createFunctionTestContext({
+  def,
+  sl: { appRecords: { create: (fields) => mySdk.app.records.create(fields) } },
+})
+```
+
+### 2. Deployed test mode (high fidelity, safe)
+
+Register to the `dev` channel and invoke on the real server — real secrets, real data —
+without a live run *(coming next)*: a test invocation is forced to `caller` authority,
+side-effecting writes are dry-run, and the traffic is logged separately from live metrics.
+
+### 3. Live
+
+Point a real collection at the channel and invoke for real.
+
+### What differs across the three
+
+| | Capabilities | `ctx.sl` | Secrets | Authority | Writes |
+|---|---|---|---|---|---|
+| **Local harness** | Enforced (from `def`) | Stub, or your injected SDK | Fixtures you pass | Informational | Whatever your impl does |
+| **Deployed test** | Enforced | Real (test-scoped) | Real | Forced to `caller` | Dry-run |
+| **Live** | Enforced | Real | Real | As declared | Real |
+
+### Recommended CI pattern
+
+1. **Unit** — run each handler through `createFunctionTestContext` (no network); assert
+   behaviour *and* that capabilities are sufficient (an under-declared capability throws).
+2. **Post-deploy smoke** — after registering to `dev`, hit each function once in test mode.
+
+## Where functions run (and why it doesn't change how you write them)
+
+SmartLinks runs first-party (trusted) functions **in-process** and untrusted third-party
+functions in an **isolated runner**. The difference is enforcement, not authoring:
+
+- **In-process** trusts the author; `ctx` is built directly.
+- **Isolated runner** enforces the `authority` boundary and `capabilities` at the container
+  edge — `ctx.sl` is a proxy over the declared authority, `ctx.fetch` is filtered to the
+  declared hosts, and there is no ambient filesystem, network, or environment.
+
+Because the **contract is identical**, a function you write today runs unchanged if it later
+moves lanes. Write to the `ctx` contract and declare your capabilities honestly, and the
+platform takes care of the rest.