@proveanything/smartlinks 2.0.41 → 2.0.43

package/dist/api/secrets.d.ts

@@ -1,8 +1,28 @@
 import type { SecretMeta, SecretList, SetSecretInput, SetSecretResult, ListSecretsQuery } from "../types/integrations.js";
+export interface AppSecretOptions {
+    /** The app whose secret this is. Defaults to the SDK's app context (`initializeApi({ appId })`). */
+    appId?: string;
+}
 export declare namespace secrets {
+    /**
+     * 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
+     */
+    function put(collectionId: string, name: string, value: string, opts?: AppSecretOptions): Promise<SetSecretResult>;
+    /** This app's secrets on the collection: names + masked hints (never values). GET /app/:appId/secrets */
+    function listOwn(collectionId: string, opts?: AppSecretOptions): Promise<SecretList>;
+    /** Delete this app's secret `name`. DELETE /app/:appId/secrets/:name */
+    function removeOwn(collectionId: string, name: string, opts?: AppSecretOptions): Promise<{
+        deleted: boolean;
+    }>;
     /** List secrets as refs + masked hints + metadata (never values). GET /secrets */
     function list(collectionId: string, query?: ListSecretsQuery): Promise<SecretList>;
-    /** 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.
+     */
     function set(collectionId: string, input: SetSecretInput): Promise<SetSecretResult>;
     /** Metadata for one secret (never the value). GET /secrets/:ref */
     function get(collectionId: string, ref: string): Promise<SecretMeta>;

package/dist/api/secrets.js

@@ -5,11 +5,15 @@
 // (refs + masked hints + metadata) and delete, but a value NEVER comes back over the
 // API. It is sealed at rest and resolved server-side only, at execution time.
 //
-// Typical use: `set` a credential, take the returned `ref`, and put it on a flow's
-// config.connection.auth.credentialRef.
+// Two kinds:
+//   - an APP's own secret (`put` / `listOwn` / `removeOwn`): saved by name from the app's admin
+//     screen, read by that app's server functions with ctx.secrets.get('<name>'). Another app's
+//     secret of the same name is a different secret.
+//   - a collection secret (`set` / `rotate` / ...): `set` returns a generated `ref` to put on an
+//     integration flow's config.connection.auth.credentialRef.
 //
-// Endpoints: /admin/collection/:collectionId/secrets
-import { request, post, put, del } from "../http.js";
+// Endpoints: /admin/collection/:collectionId/app/:appId/secrets, /admin/collection/:collectionId/secrets
+import { request, post, put as put_, del, getAppContext } from "../http.js";
 function enc(v) { return encodeURIComponent(v); }
 function encodeQuery(params = {}) {
     const search = new URLSearchParams();
@@ -24,12 +28,42 @@ function encodeQuery(params = {}) {
 export var secrets;
 (function (secrets) {
     const base = (collectionId) => `/admin/collection/${enc(collectionId)}/secrets`;
+    const appBase = (collectionId, opts) => {
+        var _a;
+        const app = (_a = opts.appId) !== null && _a !== void 0 ? _a : getAppContext();
+        if (!app)
+            throw new Error("secrets: no app — pass { appId } or initializeApi({ appId })");
+        return `/admin/collection/${enc(collectionId)}/app/${enc(app)}/secrets`;
+    };
+    /**
+     * 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
+     */
+    async function put(collectionId, name, value, opts = {}) {
+        return put_(`${appBase(collectionId, opts)}/${enc(name)}`, { value });
+    }
+    secrets.put = put;
+    /** This app's secrets on the collection: names + masked hints (never values). GET /app/:appId/secrets */
+    async function listOwn(collectionId, opts = {}) {
+        return request(appBase(collectionId, opts));
+    }
+    secrets.listOwn = listOwn;
+    /** Delete this app's secret `name`. DELETE /app/:appId/secrets/:name */
+    async function removeOwn(collectionId, name, opts = {}) {
+        return del(`${appBase(collectionId, opts)}/${enc(name)}`);
+    }
+    secrets.removeOwn = removeOwn;
     /** List secrets as refs + masked hints + metadata (never values). GET /secrets */
     async function list(collectionId, query = {}) {
         return request(`${base(collectionId)}${encodeQuery(query)}`);
     }
     secrets.list = list;
-    /** 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.
+     */
     async function set(collectionId, input) {
         return post(base(collectionId), input);
     }
@@ -41,7 +75,7 @@ export var secrets;
     secrets.get = get;
     /** Rotate/update a secret's value (and optionally name/purpose). PUT /secrets/:ref → { ref, hint } */
     async function rotate(collectionId, ref, input) {
-        return put(`${base(collectionId)}/${enc(ref)}`, input);
+        return put_(`${base(collectionId)}/${enc(ref)}`, input);
     }
     secrets.rotate = rotate;
     /** Soft-delete a secret. DELETE /secrets/:ref */

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.41  |  Generated: 2026-10-06T07:00:42.791Z
+Version: 2.0.43  |  Generated: 2026-10-06T15:37:31.849Z
 
 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'>;
 }
@@ -9719,6 +9720,15 @@ interface FunctionSiteUrlOptions {
 
 **FunctionCallResult** = `any`
 
+### secrets (api)
+
+**AppSecretOptions** (interface)
+```typescript
+interface AppSecretOptions {
+  appId?: string
+}
+```
+
 ### sequence (api)
 
 **AllocateSequenceInput** (interface)
@@ -12048,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

package/dist/docs/integrations.md

@@ -135,7 +135,7 @@ admin API fires the flow automatically — no manual run needed.
 | `integrations.deleteFlow(collectionId, id)` | `DELETE /integrations/flows/:id` |
 | `integrations.runFlow(collectionId, id, opts?)` | `POST /integrations/flows/:id/run` |
 | `secrets.list(collectionId, query?)` | `GET /secrets` |
-| `secrets.set(collectionId, input)` | `POST /secrets` |
+| `secrets.set(collectionId, input)` | `POST /secrets` (generated ref — for flows; an app's server functions use `secrets.put`, see server-functions.md) |
 | `secrets.get(collectionId, ref)` | `GET /secrets/:ref` |
 | `secrets.rotate(collectionId, ref, input)` | `PUT /secrets/:ref` |
 | `secrets.remove(collectionId, ref)` | `DELETE /secrets/:ref` |

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. */
@@ -561,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/openapi.yaml

@@ -19086,6 +19086,8 @@ components:
             type: string
         schedule:
           type: string
+        timezone:
+          type: string
         route:
           type: string
         methods:
@@ -30781,6 +30783,11 @@ components:
             type: string
         host:
           type: string
+    AppSecretOptions:
+      type: object
+      properties:
+        appId:
+          type: string
     AllocateSequenceInput:
       type: object
       properties:

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']`). */

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.41  |  Generated: 2026-10-06T07:00:42.791Z
+Version: 2.0.43  |  Generated: 2026-10-06T15:37:31.849Z
 
 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'>;
 }
@@ -9719,6 +9720,15 @@ interface FunctionSiteUrlOptions {
 
 **FunctionCallResult** = `any`
 
+### secrets (api)
+
+**AppSecretOptions** (interface)
+```typescript
+interface AppSecretOptions {
+  appId?: string
+}
+```
+
 ### sequence (api)
 
 **AllocateSequenceInput** (interface)
@@ -12048,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

package/docs/integrations.md

@@ -135,7 +135,7 @@ admin API fires the flow automatically — no manual run needed.
 | `integrations.deleteFlow(collectionId, id)` | `DELETE /integrations/flows/:id` |
 | `integrations.runFlow(collectionId, id, opts?)` | `POST /integrations/flows/:id/run` |
 | `secrets.list(collectionId, query?)` | `GET /secrets` |
-| `secrets.set(collectionId, input)` | `POST /secrets` |
+| `secrets.set(collectionId, input)` | `POST /secrets` (generated ref — for flows; an app's server functions use `secrets.put`, see server-functions.md) |
 | `secrets.get(collectionId, ref)` | `GET /secrets/:ref` |
 | `secrets.rotate(collectionId, ref, input)` | `PUT /secrets/:ref` |
 | `secrets.remove(collectionId, ref)` | `DELETE /secrets/:ref` |

package/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. */
@@ -561,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/openapi.yaml

@@ -19086,6 +19086,8 @@ components:
             type: string
         schedule:
           type: string
+        timezone:
+          type: string
         route:
           type: string
         methods:
@@ -30781,6 +30783,11 @@ components:
             type: string
         host:
           type: string
+    AppSecretOptions:
+      type: object
+      properties:
+        appId:
+          type: string
     AllocateSequenceInput:
       type: object
       properties:

package/package.json

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

package/scripts/doctor.mjs

@@ -43,11 +43,14 @@ function die(msg) {
 const appDir = resolve(process.argv[2] || process.cwd());
 if (!existsSync(appDir)) die(`app directory not found: ${appDir}`);
 
-// Locate the manifest.
-const manifestPath = ['public/app.manifest.json', 'app.manifest.json', 'dist/app.manifest.json']
+// Locate the manifest. The BUILT one (dist/) first: it's what ships, and the build's hash step renames
+// bundles (mobile-admin.esm.js → mobile-admin-<hash>.esm.js) and rewrites only dist/app.manifest.json —
+// checking the source manifest after a build looked for files that no longer exist under that name.
+// The source manifest is the fallback for a doctor run before any build.
+const manifestPath = ['dist/app.manifest.json', 'public/app.manifest.json', 'app.manifest.json']
   .map((p) => join(appDir, p))
   .find(existsSync);
-if (!manifestPath) die(`no app.manifest.json found under ${appDir} (looked in public/, ., dist/)`);
+if (!manifestPath) die(`no app.manifest.json found under ${appDir} (looked in dist/, public/, .)`);
 
 let manifest;
 try {