@proveanything/smartlinks 2.0.21 → 2.0.24

package/docs/server-functions.md

@@ -248,10 +248,21 @@ To call a *different* app's function, pass the appId explicitly:
 await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'some-other-app' })
 ```
 
+**The app does NOT have to be enabled on the collection.** Because the appId is explicit, the
+function is resolved directly from the app's release — so you can test an app on any collection
+before installing it (and without it showing up in that collection's menus). Enabling an app is
+currently just a UX courtesy (dropdowns/menus), not a gate on running its functions. For a build
+that isn't the default `stable` channel — e.g. a **dev** app you haven't installed — pass the
+channel:
+
+```ts
+await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app', channel: 'dev' })
+```
+
 If no appId is available (not set on init, none passed), the call falls back to the **deprecated
-flat path** `/collection/:c/functions/:name`, which the server resolves by bare name and **rejects
-with `409 AMBIGUOUS_FUNCTION`** when more than one installed app defines that name (a first-party
-builtin still wins). Always prefer an appId.
+flat path** `/collection/:c/functions/:name`, which searches only the collection's **enabled** apps,
+resolves by bare name, and **rejects with `409 AMBIGUOUS_FUNCTION`** when more than one defines that
+name (a first-party builtin still wins). Always prefer an appId.
 
 > There is no such thing as an app-less function. First-party builtins (e.g. the `functions.ping`
 > diagnostic) belong to the reserved `smartlinks` app. A "global" function is just an app enabled on
@@ -309,7 +320,8 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | 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>` |
-| Read/write general or app-wide data (config, URLs, counters, arrays) | `ctx.sl.appData.get()` / `ctx.sl.appData.set({…})` — pass `{ scope: 'global' }` for app-wide (shared by every install; global writes need collection authority) | `sl:data:read` / `sl:data:write` |
+| Read/write your app's own data (config, URLs, counters, arrays) | `ctx.sl.appData.get()` / `ctx.sl.appData.set({…})` — collection-scoped by default; `ctx.sl.appData.global.*` (or `{ scope:'global' }`, or declare `dataScope:'global'`) for the app-wide bucket. It's your OWN namespace, so **any** authority may read/write it | `sl:data:read` / `sl:data:write` |
+| Read ANOTHER app's data (as the caller may see it) | `ctx.sl.app('other-app').data.get()` — caller-authority, this collection, public-filtered, read-only | `sl:data:read` |
 | Guarantee a UNIQUE claim (pool of numbers, one-per-user, idempotency key) | `ctx.sl.appRecords.create({ ref: 'ball:57' })` — the DB unique index rejects a duplicate `ref` (catch = "already taken") | `sl:records:write` |
 
 Notes:
@@ -376,18 +388,41 @@ POST /public/collection/:collectionId/app/:appId/functions/:name   # visibility:
 GET  /{admin|public}/collection/:collectionId/app/:appId/functions # list this app's functions on the surface
 ```
 
+The app-scoped route resolves the app **directly by id**, so the app need not be enabled on the
+collection — handy for testing an un-installed (dev) app. Add `?channel=dev` (default `stable`) to
+pick the release. Enablement (`appConfig.apps[]`) currently only controls menus/discovery, not
+whether a function can run.
+
 The bare-name form (`/collection/:c/functions/:name`, no `/app/:appId`) is a **deprecated alias**:
-it resolves by name across all installed apps, lets a first-party builtin win, and returns
-`409 AMBIGUOUS_FUNCTION` when two apps define the same name. Prefer the app-scoped route (the SDK
-emits it automatically once an appId is set — see "Calling a function from your app").
-
-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. 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.
+it searches only the collection's **enabled** apps, resolves by name, lets a first-party builtin
+win, and returns `409 AMBIGUOUS_FUNCTION` when two enabled apps define the same name. Prefer the
+app-scoped route (the SDK emits it automatically once an appId is set — see "Calling a function
+from your app").
+
+> **Security note (first-party model, today):** because enablement is not an auth gate, any app's
+> function can be invoked on any collection by id. That's fine while all apps are first-party and
+> trusted. When untrusted third-party apps arrive, gate *elevated* (`public` + `collection`)
+> invocation of a **non-enabled** app behind install/consent — the app-scoped resolver is the seam.
+
+The handler receives the request as `event`: `event.body` (parsed JSON), `event.query`,
+`event.headers`, `event.rawBody` (raw bytes, for XML/form/other inputs), and `event.contentType`.
+A function only runs on its own surface — calling an `admin` function on the public endpoint is a
+`403`. `GET` on either endpoint lists the functions callable on that surface.
+
+**Response contract — your return IS the response (no envelope):**
+- Return a **plain value** → it becomes the JSON body, HTTP `200`. (`SL.functions.call()` gives you
+  that value directly — `res.value`, not `res.result.value`.)
+- Return a web-standard **`Response`** → passed through verbatim: your status, headers, content-type
+  and body (XML, CSV, text, binary, redirect, custom status). `Response` is a runtime global.
+  ```js
+  return new Response(toXml(data), { status: 200, headers: { "content-type": "application/xml" } })
+  ```
+- **Throw** → HTTP `500` `{ error: "FUNCTION_ERROR", message, code }`. For *expected* errors (400/404/
+  409…), return a `Response` with your own status + body.
+
+One rule: **plain object ⇒ 200; want any other status/headers/content-type ⇒ return a `Response`.**
+Timing comes back in an `X-SL-Function-Duration-Ms` header (admin surface); your `ctx.log` lines land
+in the collection's Errors & Activity feed — the body stays purely your output.
 
 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
@@ -412,7 +447,7 @@ So the end-to-end path is: *write → register the release → enable on a colle
 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.
+- **Admin-surface response** — timing comes back in the `X-SL-Function-Duration-Ms` header (logs are in Errors & Activity, not the body).
 - **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),

package/openapi.yaml

@@ -18255,6 +18255,11 @@ components:
           type: array
           items:
             type: string
+        dataScope:
+          type: string
+          enum:
+            - collection
+            - global
         apiVersion:
           type: string
         handler:
@@ -18274,6 +18279,41 @@ components:
       required:
         - files
         - definitions
+    AppDataOpts:
+      type: object
+      properties:
+        scope:
+          type: string
+          enum:
+            - collection
+            - global
+        productId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        dataId:
+          type: string
+        queries:
+          type: object
+          additionalProperties: true
+    AppDataHandle:
+      type: object
+      properties: {}
+    ServerFunctionSl:
+      type: object
+      properties:
+        appRecords: {}
+        products: {}
+        attestations: {}
+        appData:
+          $ref: "#/components/schemas/AppDataHandle"
+      required:
+        - appRecords
+        - products
+        - attestations
+        - appData
     ServerFunctionCaller:
       type: object
       properties:
@@ -18298,7 +18338,8 @@ components:
           type: string
         appId:
           type: string
-        sl: {}
+        sl:
+          $ref: "#/components/schemas/ServerFunctionSl"
         secrets:
           type: object
           additionalProperties: true
@@ -18314,6 +18355,30 @@ components:
         - secrets
         - caller
         - fetch
+    ServerFunctionHttpEvent:
+      type: object
+      properties:
+        method:
+          type: string
+        body:
+          type: object
+          additionalProperties: true
+        query:
+          type: object
+          additionalProperties: true
+        headers:
+          type: object
+          additionalProperties: true
+        rawBody:
+          type: object
+          additionalProperties: true
+        contentType:
+          type: string
+      required:
+        - method
+        - body
+        - query
+        - headers
     AppAdminConfig:
       type: object
       properties:
@@ -18397,6 +18462,40 @@ components:
         - scope
         - name
         - type
+    PublicViewParams:
+      type: object
+      properties:
+        required:
+          type: array
+          items:
+            type: string
+        optional:
+          type: array
+          items:
+            type: string
+    PublicView:
+      type: object
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        kind:
+          $ref: "#/components/schemas/PublicViewKind"
+        route:
+          type: string
+        set:
+          type: object
+          additionalProperties:
+            type: string
+        params:
+          $ref: "#/components/schemas/PublicViewParams"
+        default:
+          type: boolean
+      required:
+        - id
+        - title
+        - kind
     AppManifest:
       type: object
       properties:
@@ -18472,6 +18571,10 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/DeepLinkEntry"
+        publicViews:
+          type: array
+          items:
+            $ref: "#/components/schemas/PublicView"
         executor:
           $ref: "#/components/schemas/AppManifestExecutor"
         functions:
@@ -18532,6 +18635,11 @@ components:
       enum:
         - caller
         - collection
+    PublicViewKind:
+      type: string
+      enum:
+        - contextual
+        - standalone
     PaginatedResponse:
       type: object
       properties:
@@ -29290,7 +29398,8 @@ components:
       type: object
       properties:
         appId:
-          type: string
+          type: object
+          additionalProperties: true
     AllocateSequenceInput:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.21",
+  "version": "2.0.24",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",