@proveanything/smartlinks 1.17.4 → 1.17.6

package/dist/docs/ai-tools-and-skills.md

@@ -147,7 +147,7 @@ _Capabilities: web:read_
 
 ### `image.generate`
 
-Generate a new image from a text prompt. Returns the generated image (url or base64).
+Generate a new image from a text prompt. Returns a stable hosted image URL (hostedUrl).
 
 _Capabilities: ai:image_
 
@@ -156,6 +156,18 @@ _Capabilities: ai:image_
 - `size` — string: e.g. "1024x1024".
 - `provider` — `openai` | `gemini`: Image model provider.
 
+### `image.fromReference`
+
+Generate a new image guided by one or more reference images plus a prompt (image-to-image). Use to restyle, combine, or vary existing images. Returns a stable hosted image URL (hostedUrl).
+
+_Capabilities: ai:image_
+
+**Parameters**
+- `prompt` _(required)_ — string: How to transform / what to create from the reference(s).
+- `imageUrls` _(required)_ — array: Reference image URL(s) to guide generation.
+- `size` — string: e.g. "1024x1024".
+- `model` — string: Image model (default gpt-image-1).
+
 ### `image.searchStock`
 
 Search stock photography (Unsplash) for real photos matching a query. Returns candidate image URLs.

package/dist/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/dist/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/dist/types/appManifest.d.ts

@@ -204,6 +204,106 @@ export interface AppManifestExecutor {
         responseShape?: Record<string, any>;
     };
 }
+/** What causes a server function to run. */
+export type AppFunctionTriggerType = 'http' | 'event' | 'cron';
+export interface AppFunctionTrigger {
+    type: AppFunctionTriggerType;
+    /** `event`: event types this function subscribes to, e.g. `['interaction.submitted:comp-entry']`. */
+    eventTypes?: string[];
+    /** `cron`: standard 5-field crontab expression, evaluated in UTC. */
+    schedule?: string;
+    /** `http`: URL path segment the function is exposed at (defaults to the function `name`). */
+    route?: string;
+    /** `http`: accepted HTTP methods (defaults to `['POST']`). */
+    methods?: Array<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'>;
+}
+/** Who is allowed to invoke an `http`-triggered function. */
+export type AppFunctionVisibility = 'admin' | 'public';
+/**
+ * Whose authority the function runs with — i.e. what `ctx.sl` can do.
+ * - `caller`     — runs as the invoking user (their session/JWT). The secure default.
+ * - `collection` — runs with collection-admin authority over THIS collection only
+ *                  (never a global superuser). Required for `public` functions that
+ *                  must perform a privileged server-side action; the author is then
+ *                  responsible for validating input and preventing abuse.
+ */
+export type AppFunctionAuthority = 'caller' | 'collection';
+/** One server function declared in the manifest. */
+export interface AppFunctionDef {
+    /** Stable identifier, unique within the app, e.g. `'submitCompetitionEntry'`. */
+    name: string;
+    description?: string;
+    trigger: AppFunctionTrigger;
+    /**
+     * `http` only. `admin` = authenticated admin surface; `public` = publicly callable.
+     * Ignored for `event`/`cron` (no external caller). Defaults to `admin`.
+     */
+    visibility?: AppFunctionVisibility;
+    /**
+     * Whose authority `ctx.sl` carries. Defaults to `caller` (secure by default).
+     * `event`/`cron` functions have no caller and always run as `collection`.
+     */
+    authority?: AppFunctionAuthority;
+    /**
+     * Least-privilege capabilities this function needs, surfaced at install for
+     * consent and capped at runtime — even for `collection`-authority functions.
+     * e.g. `['sl:records:write', 'network:api.example.com', 'secrets:syndigo-key']`.
+     * Grammar: `sl:<resource>:<read|write>`, `network` (or `network:<host>`), `secrets:<ref>`.
+     */
+    capabilities?: string[];
+    /** SDK/manifest API version this function targets (pinned for runtime compatibility). */
+    apiVersion?: string;
+    /** Exported handler name in the functions bundle. Defaults to `name`. */
+    handler?: string;
+}
+/** The `functions` block in `app.manifest.json`. Presence means the app ships server functions. */
+export interface AppManifestFunctions {
+    files: AppManifestFiles;
+    definitions: AppFunctionDef[];
+}
+/** Identity of whoever invoked a server function. */
+export interface ServerFunctionCaller {
+    /** Authenticated user id, or `null` for anonymous/public/system invocations. */
+    userId: string | null;
+    /** True when no authenticated user is present (public/anonymous call, or event/cron). */
+    anonymous: boolean;
+    /** Request origin/referer, when available (`http` trigger). */
+    origin?: string | null;
+    /** Client IP, when available (`http` trigger). */
+    ip?: string | null;
+    /** How the function was triggered. */
+    via: AppFunctionTriggerType;
+}
+/**
+ * The context handed to every SmartLinks server function. The platform builds a
+ * fresh one per invocation and pre-scopes each handle to the function's declared
+ * authority + capabilities. The function receives only handles already narrowed
+ * to what it declared — no raw keys, no ambient superuser client.
+ */
+export interface ServerFunctionContext {
+    collectionId: string;
+    appId: string;
+    /**
+     * SmartLinks SDK, pre-scoped to the function's declared `authority`:
+     *  - `caller`     → scoped to the invoking user (their JWT).
+     *  - `collection` → scoped to a collection-admin principal for THIS collection
+     *                   only — never a global superuser.
+     * Declared `capabilities` cap what these calls may do.
+     */
+    sl: any;
+    /** Capability-gated secret access. `get(ref)` resolves only refs granted via `secrets:<ref>`. */
+    secrets: {
+        get(ref: string): Promise<string | null>;
+    };
+    /** Who invoked this function. */
+    caller: ServerFunctionCaller;
+    /** Outbound HTTP — present only when the `network` capability is declared (host-scoped if `network:<host>`). */
+    fetch: typeof fetch;
+    /** Structured logging captured into run telemetry. */
+    log: (message: string, data?: Record<string, any>) => void;
+}
+/** The signature every SmartLinks server function implements. */
+export type ServerFunctionHandler<TEvent = any, TResult = any> = (ctx: ServerFunctionContext, event: TEvent) => Promise<TResult> | TResult;
 /**
  * Shape of `app.admin.json` -- the separate admin configuration file pointed to
  * by `AppManifest.admin`. Fetch this file yourself when you need setup / import /
@@ -342,6 +442,13 @@ export interface AppManifest {
      * @see AppManifestExecutor
      */
     executor?: AppManifestExecutor;
+    /**
+     * Server functions ("edge functions") this app deploys into SmartLinks —
+     * arbitrary server-side code triggered by http, events, or cron, each running
+     * with a declared authority + least-privilege capabilities.
+     * @see AppManifestFunctions
+     */
+    functions?: AppManifestFunctions;
     [key: string]: any;
 }
 /**

package/dist/types/integrations.d.ts

@@ -134,3 +134,11 @@ export interface SetSecretResult {
 export interface ListSecretsQuery {
     purpose?: string;
 }
+export interface RecordTypeInfo {
+    appId: string;
+    recordType: string;
+    count: number;
+}
+export interface RecordTypesResponse {
+    recordTypes: RecordTypeInfo[];
+}