@proveanything/smartlinks 2.0.40 → 2.0.42

package/dist/docs/server-functions.md

@@ -167,10 +167,10 @@ Declare the minimum you need.
 | `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. |
+| `secrets:<name>` | `ctx.secrets.get('<name>')` for that one secret (see [Secrets](#secrets--api-keys-per-collection)). |
 
-If you don't declare `network`, `ctx.fetch` is absent. If you don't declare a `secrets:<ref>`,
-`ctx.secrets.get('<ref>')` returns `null`.
+If you don't declare `network`, `ctx.fetch` is absent. Reading a secret you didn't declare with
+`secrets:<name>` throws.
 
 ---
 
@@ -186,8 +186,8 @@ interface ServerFunctionContext {
    *  data — URLs, flags, counters, arrays), `sl.products`, `sl.attestations`. */
   sl: SmartLinks
 
-  /** Capability-gated secrets (need `secrets:<ref>`). `get(ref)` resolves the collection's OWN
-   *  secret first, then the app-level one; `app(ref)` reads the app-level secret only. */
+  /** Capability-gated secrets (need `secrets:<name>`). `get(name)` reads this app's own secret on the
+   *  collection first, then the app-level one; `app(name)` reads the app-level secret only. */
   secrets: { get(ref: string): Promise<string | null>; app(ref: string): Promise<string | null> }
 
   /** Who invoked this function. */
@@ -324,6 +324,40 @@ name (a first-party builtin still wins). Always prefer an appId.
 
 ---
 
+## Inputs — data handed to your function
+
+Declare what your function needs and the platform fetches it **before** the run: read it from `ctx.inputs` instead of calling `ctx.sl` first. One less round trip — and for functions running in the isolated runner, one less network hop.
+
+```jsonc
+// app.manifest.json → functions.definitions[]
+{
+  "name": "onProductChanged",
+  "trigger": { "type": "event", "eventTypes": ["product.updated"] },
+  "capabilities": ["sl:products:read", "sl:data:read"],
+  "inputs": { "appConfig": true }            // entity is on by default for event triggers
+}
+```
+
+```js
+export async function onProductChanged(ctx, event) {
+  const product = ctx.inputs.entity                     // the product that changed
+  const { interactionIds } = ctx.inputs.appConfig || {} // this app's config for the collection
+}
+```
+
+| Input | What you get | Needs | Triggers |
+|---|---|---|---|
+| `entity` | The record the event is about: the product, your app's record, or the interaction event. **On by default**; `"entity": false` opts out. | read on that resource (`sl:products:read`, `sl:records:read`) | event |
+| `collection` | The collection's public record | — | all |
+| `appConfig` | Your app's config for this collection (where setup like `interactionIds` lives) | `sl:data:read` | all |
+| `product` | A product named by the request: `{ "from": "body.productId" }`, `"query.<field>"` or `"path"` | `sl:products:read` | http |
+
+- **Same rules as `ctx.sl`.** Inputs are fetched with your function's authority and capabilities, scoped to the collection it runs in — a product from another collection is never fetched.
+- **Never an error.** Not found, not allowed or larger than 256 KB → that input is `null`. Check before you use it.
+- **Current state.** Event inputs are fetched when your function runs, so you see the record as it is now; `event` still carries the ids.
+- **Checked at publish.** An unknown input, a bad `from`, or a missing capability fails validation.
+- **Testing:** pass `inputs` to the test context — `createFunctionTestContext({ def, inputs: { entity: { id: 'p1', name: 'Kettle' } } })`.
+
 ## Exposing a function to the AI agent
 
 An `http` function can be offered to the AI agent as a **callable tool**, alongside the built-in
@@ -527,6 +561,102 @@ other secrets, or any other collection.
 
 ---
 
+## Secrets — API keys per collection
+
+A function that calls another system needs that system's key, and each collection (each customer)
+has its own. Your app's **admin screen** saves it; your **functions** read it by the same name.
+
+**1. Declare it** on every function that reads it:
+
+```jsonc
+{ "name": "pullOrders", "trigger": { "type": "cron", "schedule": "0,30 * * * *" },
+  "capabilities": ["network:api.example-shop.com", "secrets:shop-api-key"] }
+```
+
+**2. Save it from your admin screen**, signed in as a collection admin:
+
+```ts
+await SL.secrets.put(collectionId, 'shop-api-key', apiKeyFromTheForm)   // create or replace
+const { secrets } = await SL.secrets.listOwn(collectionId)              // names + masked hints, e.g. "••••1234"
+await SL.secrets.removeOwn(collectionId, 'shop-api-key')
+```
+
+The app comes from the SDK's app context (`initializeApi({ appId })`), or pass `{ appId }` as the
+last argument. Secrets are write-only: nothing ever returns the value, so show the hint ("saved,
+ends 1234") and offer "replace", not "edit". Build this into your own settings screen; the platform
+doesn't prompt for it at install.
+
+**3. Read it in the function:**
+
+```ts
+const key = await ctx.secrets.get('shop-api-key')   // null until an admin has saved it
+if (!key) { ctx.log('shop not connected yet'); return { skipped: 'not connected' } }
+```
+
+**Each app's secrets are its own.** `shop-api-key` saved by your app and `shop-api-key` saved by
+another app on the same collection are two different secrets; your functions only ever read yours.
+
+`ctx.secrets.get(name)` looks in this order:
+1. your app's secret on this collection (saved with `SL.secrets.put`);
+2. *SmartLinks' own apps only:* a collection-wide secret of that name. Third-party apps never read these;
+3. your app's shared, app-level secret (the same for every collection), if Forge has one for it.
+
+Don't use `SL.secrets.set` for this. It creates a collection secret with a **generated** ref
+(`sec_…`) for integration flows, which a function can't name in its manifest.
+
+---
+
+## Scheduled functions (cron)
+
+A `cron` function runs on a schedule, on **every collection that has the app installed**, with
+`collection` authority (there's no caller). It's the shape for polling another system ("pull new
+orders every 15 minutes"), nightly reconciles, digests and clean-ups.
+
+```jsonc
+{
+  "name": "pullOrders",
+  "trigger": { "type": "cron", "schedule": "*/15 * * * *" },
+  "capabilities": ["sl:records:write", "network:api.example-shop.com", "secrets:shop-api-key"]
+},
+{
+  "name": "morningDigest",
+  "trigger": { "type": "cron", "schedule": "0 9 * * MON-FRI", "timezone": "Europe/London" },
+  "capabilities": ["sl:records:read", "network:hooks.slack.com", "secrets:slack-webhook"]
+}
+```
+
+- **`schedule`** — standard 5-field cron: minute, hour, day-of-month, month, day-of-week. Lists,
+  ranges and steps (`0,30`, `9-17`, `*/15`), month and day names (`JAN`, `MON-FRI`; Sunday is 0 or 7),
+  and `@hourly` / `@daily` / `@weekly` / `@monthly` / `@yearly`. When both day-of-month and
+  day-of-week are restricted, a day matching either fires (as in cron).
+- **`timezone`** *(optional)* — an IANA zone like `"Europe/London"`; the schedule follows its
+  summer time. Default UTC.
+- **At most every 5 minutes.** A faster schedule, a bad expression or an unknown zone fails the
+  release (`SCHEDULE_INVALID`), so it never silently doesn't run.
+
+**What runs:** each installation runs the current release of the channel it's installed on, so a
+test collection with the app on `dev` runs your dev build on its schedule. Disabled installs and
+expired dev installs don't run.
+
+**The event** your handler receives:
+
+```ts
+{ type: 'cron', schedule: '*/15 * * * *', timezone: null, scheduledAt: '2026-10-06T10:15:00.000Z' }
+```
+
+`scheduledAt` is the minute the run was due, which is not always the moment it starts: runs queue,
+and a late one still carries its own minute. Use it, not `Date.now()`, as the end of the window
+you're syncing.
+
+**Write it to be safe to run twice.** Each (collection, function, minute) is enqueued once, but a
+run that fails part-way can be retried, and a slow run can still be going when the next one starts.
+Keep a cursor (last `scheduledAt` or the other system's own cursor) in the app's records or config,
+and upsert by the other system's ID instead of inserting blindly.
+
+Each run is logged like any other function run, and a failure shows in the collection's Errors view.
+
+---
+
 ## Invoking an http function
 
 An `http` function is called by POSTing to the app-scoped functions endpoint on the

package/dist/http.d.ts

@@ -71,6 +71,11 @@ export declare function initializeApi(options: {
     awaitAuth?: boolean;
     /** How long (ms) to wait for the async token before letting requests proceed anyway. Default 8000. */
     awaitAuthTimeoutMs?: number;
+    /**
+     * proxyMode only: how long (ms) a request waits for the parent host's reply before failing with a
+     * 504 SmartlinksApiError (errorCode PROXY_TIMEOUT). Default 90000. 0 = wait indefinitely.
+     */
+    proxyTimeoutMs?: number;
     iframeAutoResize?: boolean;
     logger?: Logger;
     /**

package/dist/http.js

@@ -31,6 +31,10 @@ let baseURL = null;
 let apiKey = undefined;
 let bearerToken = undefined;
 let proxyMode = false;
+// How long a request through the parent (proxyMode) waits for the host's reply. Without a limit, a host
+// that never answers (no responder, a dropped message) leaves the call pending forever: no network
+// request in the frame, no error. 90 s covers the longest platform call (a 60 s function deadline).
+let proxyTimeoutMs = 90000;
 let ngrokSkipBrowserWarning = false;
 let extraHeadersGlobal = {};
 /**
@@ -522,6 +526,8 @@ export function initializeApi(options) {
         });
     }
     proxyMode = !!options.proxyMode;
+    if (options.proxyTimeoutMs !== undefined)
+        proxyTimeoutMs = Math.max(0, Number(options.proxyTimeoutMs) || 0);
     // Auto-enable ngrok skip header if domain contains .ngrok.io and user did not explicitly set the flag.
     // Infer ngrok usage from common domains (.ngrok.io or .ngrok-free.dev)
     const inferredNgrok = /(\.ngrok\.io|\.ngrok-free\.dev)(\b|\/)/i.test(baseURL);
@@ -1082,11 +1088,30 @@ async function proxyRequest(method, path, body, headers, options) {
     };
     logDebug('[smartlinks] proxy:postMessage', { id, method, path, headers: headers ? redactHeaders(headers) : undefined, hasBody: !!body });
     return new Promise((resolve, reject) => {
-        proxyPending[id] = { resolve, reject };
+        proxyPending[id] = withProxyTimeout(id, `${method} ${path}`, resolve, reject);
         window.parent.postMessage(msg, "*");
-        // Optionally: add a timeout here to reject if no response
     });
 }
+/**
+ * Wrap a pending proxy request's resolve/reject with the proxy timeout (proxyTimeoutMs): if the host
+ * hasn't answered by then, the request fails with a 504 PROXY_TIMEOUT instead of hanging forever.
+ */
+function withProxyTimeout(id, what, resolve, reject) {
+    if (!(proxyTimeoutMs > 0))
+        return { resolve, reject };
+    const timer = setTimeout(() => {
+        if (!proxyPending[id])
+            return;
+        delete proxyPending[id];
+        const message = `The host page did not answer ${what} within ${proxyTimeoutMs >= 1000 ? `${Math.round(proxyTimeoutMs / 1000)}s` : `${proxyTimeoutMs}ms`} (proxyMode). The parent may not be handling SmartLinks proxy requests.`;
+        logDebug('[smartlinks] proxy:timeout', { id, what });
+        reject(new SmartlinksApiError(message, 504, { code: 504, errorCode: 'PROXY_TIMEOUT', message }));
+    }, proxyTimeoutMs);
+    return {
+        resolve: (data) => { clearTimeout(timer); resolve(data); },
+        reject: (err) => { clearTimeout(timer); reject(err); },
+    };
+}
 /**
  * Upload a FormData payload via proxy with progress events using chunked postMessage.
  * Parent is expected to implement the counterpart protocol.
@@ -1794,8 +1819,7 @@ export async function sendCustomProxyMessage(request, params) {
     };
     logDebug('[smartlinks] proxy:custom postMessage', { id, request, params: safeBodyPreview(params) });
     return new Promise((resolve, reject) => {
-        proxyPending[id] = { resolve, reject };
+        proxyPending[id] = withProxyTimeout(id, `custom request ${request}`, resolve, reject);
         window.parent.postMessage(msg, "*");
-        // Optionally: add a timeout here to reject if no response
     });
 }

package/dist/openapi.yaml

@@ -19086,6 +19086,8 @@ components:
             type: string
         schedule:
           type: string
+        timezone:
+          type: string
         route:
           type: string
         methods:
@@ -19124,6 +19126,8 @@ components:
           enum:
             - collection
             - global
+        inputs:
+          $ref: "#/components/schemas/AppFunctionInputs"
         apiVersion:
           type: string
         handler:
@@ -19233,6 +19237,8 @@ components:
         fetch:
           type: object
           additionalProperties: true
+        inputs:
+          $ref: "#/components/schemas/ServerFunctionInputs"
       required:
         - collectionId
         - appId
@@ -19240,6 +19246,34 @@ components:
         - secrets
         - caller
         - fetch
+        - inputs
+    AppFunctionInputs:
+      type: object
+      properties:
+        entity:
+          type: boolean
+        collection:
+          type: boolean
+        appConfig:
+          type: boolean
+        product:
+          type: object
+          additionalProperties: true
+    ServerFunctionInputs:
+      type: object
+      properties:
+        entity:
+          type: object
+          additionalProperties: true
+        collection:
+          type: object
+          additionalProperties: true
+        appConfig:
+          type: object
+          additionalProperties: true
+        product:
+          type: object
+          additionalProperties: true
     ServerFunctionHttpEvent:
       type: object
       properties:
@@ -30749,6 +30783,11 @@ components:
             type: string
         host:
           type: string
+    AppSecretOptions:
+      type: object
+      properties:
+        appId:
+          type: string
     AllocateSequenceInput:
       type: object
       properties:

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import type { AppFunctionDef, ServerFunctionContext } from '../types/appManifest.js';
+import type { AppFunctionDef, ServerFunctionContext, ServerFunctionInputs } from '../types/appManifest.js';
 export declare class CapabilityError extends Error {
     capability: string;
     code: string;
@@ -62,6 +62,8 @@ export interface CreateFunctionTestContextOptions {
     sl?: TestSlImpl;
     /** Backing fetch (defaults to global fetch). Still gated by the `network` capability. */
     fetch?: typeof fetch;
+    /** What the platform would have prefetched as `ctx.inputs` (e.g. `{ entity: product }`). Default `{}`. */
+    inputs?: ServerFunctionInputs;
 }
 export interface FunctionTestContext extends ServerFunctionContext {
     /** Captured log lines (also written via ctx.log). */

package/dist/testing/index.js

@@ -176,6 +176,7 @@ export function createFunctionTestContext(opts) {
         log: (message, data) => {
             logs.push(Object.assign({ at: new Date().toISOString(), message: String(message) }, (data ? { data } : {})));
         },
+        inputs: Object.freeze(Object.assign({}, (opts.inputs || {}))),
         logs,
     };
 }

package/dist/types/appManifest.d.ts

@@ -213,8 +213,13 @@ 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. */
+    /**
+     * `cron`: standard 5-field crontab expression (`"0,30 * * * *"`, `"0 9 * * MON-FRI"`, or `@hourly` /
+     * `@daily` / `@weekly` / `@monthly`), evaluated in UTC unless `timezone` is set. At most every 5 minutes.
+     */
     schedule?: string;
+    /** `cron`: IANA time zone the schedule is read in, e.g. `"Europe/London"` (follows summer time). Default UTC. */
+    timezone?: string;
     /** `http`: URL path segment the function is exposed at (defaults to the function `name`). */
     route?: string;
     /** `http`: accepted HTTP methods (defaults to `['POST']`). */
@@ -268,6 +273,14 @@ export interface AppFunctionDef {
      * Per-call `{ scope }` and the `appData.global` / `appData.collection` handles override this.
      */
     dataScope?: 'collection' | 'global';
+    /**
+     * Data the platform fetches BEFORE the run and hands over as `ctx.inputs` — no round trip from your
+     * code (for isolated functions, no network hop). Same authority and capabilities as the equivalent
+     * `ctx.sl` read; a missing, denied or oversized (> 256 KB) input arrives as `null`, never an error.
+     * Event-trigger functions get `entity` (the record the event is about) by default; `entity: false`
+     * opts out. See server-functions.md → "Inputs".
+     */
+    inputs?: AppFunctionInputs;
     /** SDK/manifest API version this function targets (pinned for runtime compatibility). */
     apiVersion?: string;
     /** Exported handler name in the functions bundle. Defaults to `name`. */
@@ -403,6 +416,29 @@ export interface ServerFunctionContext {
     fetch: typeof fetch;
     /** Structured logging captured into run telemetry. */
     log: (message: string, data?: Record<string, any>) => void;
+    /** Data prefetched for this run, per the definition's `inputs` (read-only; `{}` when none). */
+    inputs: Readonly<ServerFunctionInputs>;
+}
+/** What a function asks to have prefetched (`AppFunctionDef.inputs`). */
+export interface AppFunctionInputs {
+    /** Event triggers: the record the event is about — product (needs `sl:products:read`), app record of
+     *  this app (`sl:records:read`), or the interaction event itself. On by default; `false` opts out. */
+    entity?: boolean;
+    /** The collection's public record. */
+    collection?: boolean;
+    /** This app's config for the collection — e.g. its `interactionIds`. Needs `sl:data:read`. */
+    appConfig?: boolean;
+    /** Http triggers: a product named by the request. Needs `sl:products:read`. */
+    product?: {
+        from: `body.${string}` | `query.${string}` | 'path';
+    };
+}
+/** `ctx.inputs` — what was prefetched for this run (keys you declared; `null` when unavailable). */
+export interface ServerFunctionInputs {
+    entity?: Record<string, any> | null;
+    collection?: Record<string, any> | null;
+    appConfig?: Record<string, any> | null;
+    product?: Record<string, any> | null;
 }
 /** The HTTP request handed to an `http`-trigger function as `event`. */
 export interface ServerFunctionHttpEvent<TBody = any> {

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.40  |  Generated: 2026-10-05T14:51:09.158Z
+Version: 2.0.42  |  Generated: 2026-10-06T15:17:04.562Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2523,6 +2523,7 @@ interface AppFunctionTrigger {
   type: AppFunctionTriggerType;
   eventTypes?: string[];
   schedule?: string;
+  timezone?: string;
   route?: string;
   methods?: Array<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'>;
 }
@@ -2539,6 +2540,7 @@ interface AppFunctionDef {
   elevated?: boolean;
   capabilities?: string[];
   dataScope?: 'collection' | 'global';
+  inputs?: AppFunctionInputs;
   apiVersion?: string;
   handler?: string;
   agent?: AppFunctionAgentExposure;
@@ -2622,6 +2624,27 @@ interface ServerFunctionContext {
   caller: ServerFunctionCaller;
   fetch: typeof fetch;
   log: (message: string, data?: Record<string, any>) => void;
+  inputs: Readonly<ServerFunctionInputs>;
+}
+```
+
+**AppFunctionInputs** (interface)
+```typescript
+interface AppFunctionInputs {
+  entity?: boolean;
+  collection?: boolean;
+  appConfig?: boolean;
+  product?: { from: `body.${string}` | `query.${string}` | 'path' };
+}
+```
+
+**ServerFunctionInputs** (interface)
+```typescript
+interface ServerFunctionInputs {
+  entity?: Record<string, any> | null;
+  collection?: Record<string, any> | null;
+  appConfig?: Record<string, any> | null;
+  product?: Record<string, any> | null;
 }
 ```
 
@@ -9697,6 +9720,15 @@ interface FunctionSiteUrlOptions {
 
 **FunctionCallResult** = `any`
 
+### secrets (api)
+
+**AppSecretOptions** (interface)
+```typescript
+interface AppSecretOptions {
+  appId?: string
+}
+```
+
 ### sequence (api)
 
 **AllocateSequenceInput** (interface)
@@ -12026,11 +12058,20 @@ Fetch + extract a web page: clean markdown, page metadata, and any schema.org JS
 
 ### secrets
 
+**put**(collectionId: string, name: string, value: string, opts: AppSecretOptions = {}) → `Promise<SetSecretResult>`
+Save this app's secret `name` on the collection (create or replace) — what the app's server functions read with `ctx.secrets.get(name)` (declare `secrets:<name>` in the manifest). Call it from your admin screen as a collection admin. Write-only: returns `{ ref: name, hint }`, never the value. PUT /app/:appId/secrets/:name
+
+**listOwn**(collectionId: string, opts: AppSecretOptions = {}) → `Promise<SecretList>`
+This app's secrets on the collection: names + masked hints (never values). GET /app/:appId/secrets
+
+**removeOwn**(collectionId: string, name: string, opts: AppSecretOptions = {}) → `Promise<`
+Delete this app's secret `name`. DELETE /app/:appId/secrets/:name
+
 **list**(collectionId: string, query: ListSecretsQuery = {}) → `Promise<SecretList>`
 List secrets as refs + masked hints + metadata (never values). GET /secrets
 
 **set**(collectionId: string, input: SetSecretInput) → `Promise<SetSecretResult>`
-Create a secret. POST /secrets → { ref, hint }. Store the ref on a flow.
+Create a collection secret with a GENERATED ref. POST /secrets → { ref, hint }. Store the ref on a flow. For a secret your app's server functions read by name, use `put` instead.
 
 **get**(collectionId: string, ref: string) → `Promise<SecretMeta>`
 Metadata for one secret (never the value). GET /secrets/:ref