@proveanything/smartlinks 1.17.5 → 1.17.6

package/docs/server-functions.md

@@ -0,0 +1,234 @@
+# Server functions ("edge functions")
+
+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
+        "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.
+
+---
+
+## 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.
+
+## 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.

package/openapi.yaml

@@ -38,6 +38,7 @@ tags:
   - name: crate
   - name: facets
   - name: form
+  - name: integrations
   - name: interactions
   - name: jobs
   - name: journeys
@@ -4164,6 +4165,33 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/integrations/record-types:
+    get:
+      tags:
+        - integrations
+      summary: Discover the app-record types present in a collection + which app owns each (introspected), for picking a sub-record source/trigger.
+      operationId: integrations_listRecordTypes
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RecordTypesResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/interactions:
     get:
       tags:
@@ -17215,6 +17243,107 @@ components:
       required:
         - files
         - function
+    AppFunctionTrigger:
+      type: object
+      properties:
+        type:
+          $ref: "#/components/schemas/AppFunctionTriggerType"
+        eventTypes:
+          type: array
+          items:
+            type: string
+        schedule:
+          type: string
+        route:
+          type: string
+        methods:
+          type: array
+          items:
+            type: string
+            enum:
+              - GET
+              - POST
+              - PUT
+              - PATCH
+              - DELETE
+      required:
+        - type
+    AppFunctionDef:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        trigger:
+          $ref: "#/components/schemas/AppFunctionTrigger"
+        visibility:
+          $ref: "#/components/schemas/AppFunctionVisibility"
+        authority:
+          $ref: "#/components/schemas/AppFunctionAuthority"
+        capabilities:
+          type: array
+          items:
+            type: string
+        apiVersion:
+          type: string
+        handler:
+          type: string
+      required:
+        - name
+        - trigger
+    AppManifestFunctions:
+      type: object
+      properties:
+        files:
+          $ref: "#/components/schemas/AppManifestFiles"
+        definitions:
+          type: array
+          items:
+            $ref: "#/components/schemas/AppFunctionDef"
+      required:
+        - files
+        - definitions
+    ServerFunctionCaller:
+      type: object
+      properties:
+        userId:
+          type: string
+        anonymous:
+          type: boolean
+        origin:
+          type: string
+        ip:
+          type: string
+        via:
+          $ref: "#/components/schemas/AppFunctionTriggerType"
+      required:
+        - userId
+        - anonymous
+        - via
+    ServerFunctionContext:
+      type: object
+      properties:
+        collectionId:
+          type: string
+        appId:
+          type: string
+        sl: {}
+        secrets:
+          type: object
+          additionalProperties: true
+        caller:
+          $ref: "#/components/schemas/ServerFunctionCaller"
+        fetch:
+          type: object
+          additionalProperties: true
+      required:
+        - collectionId
+        - appId
+        - sl
+        - secrets
+        - caller
+        - fetch
     AppAdminConfig:
       type: object
       properties:
@@ -17357,6 +17486,8 @@ components:
             $ref: "#/components/schemas/DeepLinkEntry"
         executor:
           $ref: "#/components/schemas/AppManifestExecutor"
+        functions:
+          $ref: "#/components/schemas/AppManifestFunctions"
       required:
         - name
         - version
@@ -17397,6 +17528,22 @@ components:
       properties:
         force:
           type: boolean
+    AppFunctionTriggerType:
+      type: string
+      enum:
+        - http
+        - event
+        - cron
+    AppFunctionVisibility:
+      type: string
+      enum:
+        - admin
+        - public
+    AppFunctionAuthority:
+      type: string
+      enum:
+        - caller
+        - collection
     PaginatedResponse:
       type: object
       properties:
@@ -23429,6 +23576,28 @@ components:
       properties:
         purpose:
           type: string
+    RecordTypeInfo:
+      type: object
+      properties:
+        appId:
+          type: string
+        recordType:
+          type: string
+        count:
+          type: number
+      required:
+        - appId
+        - recordType
+        - count
+    RecordTypesResponse:
+      type: object
+      properties:
+        recordTypes:
+          type: array
+          items:
+            $ref: "#/components/schemas/RecordTypeInfo"
+      required:
+        - recordTypes
     RunFlowResult:
       type: object
       additionalProperties: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.17.5",
+  "version": "1.17.6",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",