@proveanything/smartlinks 2.0.19 → 2.0.21

package/dist/api/functions.d.ts

@@ -0,0 +1,37 @@
+/** A server function's returned value — shape is app-defined, so untyped by default. */
+export type FunctionCallResult = any;
+export interface FunctionListEntry {
+    name: string;
+    visibility?: string;
+    trigger?: string;
+}
+export interface FunctionListResponse {
+    functions: FunctionListEntry[];
+}
+/** Options for a function call. `appId` scopes resolution to one app (recommended). */
+export interface FunctionCallOptions {
+    appId?: string;
+}
+export declare namespace functions {
+    /**
+     * Call a PUBLIC app server function inline (surface `'public'`).
+     * App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`.
+     *
+     * @example
+     * // App calling its own function (appId from initializeApi({ appId })):
+     * const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter')
+     * // Or address another app explicitly:
+     * await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
+     */
+    function call<T = FunctionCallResult>(collectionId: string, name: string, body?: Record<string, any>, opts?: FunctionCallOptions): Promise<T>;
+    /**
+     * Call an ADMIN app server function (surface `'admin'`; requires an admin session).
+     * App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
+     */
+    function callAdmin<T = FunctionCallResult>(collectionId: string, name: string, body?: Record<string, any>, opts?: FunctionCallOptions): Promise<T>;
+    /**
+     * List the public functions available for a collection (discovery). Scoped to one app when an
+     * appId is given (or set as the SDK app context): `GET /public/collection/:c[/app/:appId]/functions`.
+     */
+    function list(collectionId: string, opts?: FunctionCallOptions): Promise<FunctionListResponse>;
+}

package/dist/api/functions.js

@@ -0,0 +1,63 @@
+// Client-side invocation of app SERVER FUNCTIONS.
+//
+// The function itself is authored server-side (one contract: `async (ctx, event) => result`,
+// see docs/server-functions.md). THIS is how a page/UI actually calls one — the missing
+// client half. The PUBLIC route runs a function inline on the caller's own authority (owner if
+// signed in via authKit, else public); the ADMIN route runs on the admin surface (needs an admin
+// session). The returned value is the function's own result (`event.body` is what you pass here).
+//
+// ADDRESSING. A function always belongs to an app, so the canonical route is app-scoped:
+//   /collection/:c/app/:appId/functions/:name
+// The appId comes from `opts.appId`, else the SDK's app context (initializeApi({ appId })) — so an
+// app calling its OWN function just writes `SL.functions.call(collectionId, name)`. With no appId
+// available, 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. Always prefer an appId.
+import { post, request, getAppContext } from "../http.js";
+function fnPath(surface, collectionId, name, appId) {
+    const c = encodeURIComponent(collectionId);
+    const n = encodeURIComponent(name);
+    const app = appId !== null && appId !== void 0 ? appId : getAppContext();
+    return app
+        ? `/${surface}/collection/${c}/app/${encodeURIComponent(app)}/functions/${n}`
+        : `/${surface}/collection/${c}/functions/${n}`; // deprecated flat alias
+}
+export var functions;
+(function (functions) {
+    /**
+     * Call a PUBLIC app server function inline (surface `'public'`).
+     * App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`.
+     *
+     * @example
+     * // App calling its own function (appId from initializeApi({ appId })):
+     * const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter')
+     * // Or address another app explicitly:
+     * await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
+     */
+    async function call(collectionId, name, body = {}, opts = {}) {
+        return post(fnPath('public', collectionId, name, opts.appId), body);
+    }
+    functions.call = call;
+    /**
+     * Call an ADMIN app server function (surface `'admin'`; requires an admin session).
+     * App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
+     */
+    async function callAdmin(collectionId, name, body = {}, opts = {}) {
+        return post(fnPath('admin', collectionId, name, opts.appId), body);
+    }
+    functions.callAdmin = callAdmin;
+    /**
+     * List the public functions available for a collection (discovery). Scoped to one app when an
+     * appId is given (or set as the SDK app context): `GET /public/collection/:c[/app/:appId]/functions`.
+     */
+    async function list(collectionId, opts = {}) {
+        var _a;
+        const c = encodeURIComponent(collectionId);
+        const app = (_a = opts.appId) !== null && _a !== void 0 ? _a : getAppContext();
+        const path = app
+            ? `/public/collection/${c}/app/${encodeURIComponent(app)}/functions`
+            : `/public/collection/${c}/functions`;
+        return request(path);
+    }
+    functions.list = list;
+})(functions || (functions = {}));

package/dist/api/index.d.ts

@@ -28,6 +28,7 @@ export { qr } from "./qr.js";
 export { template } from "./template.js";
 export { interactions } from "./interactions.js";
 export { analytics } from "./analytics.js";
+export { functions } from "./functions.js";
 export { location } from "./location.js";
 export * as realtime from "./realtime.js";
 export { tags } from "./tags.js";

package/dist/api/index.js

@@ -30,6 +30,7 @@ export { qr } from "./qr.js";
 export { template } from "./template.js";
 export { interactions } from "./interactions.js";
 export { analytics } from "./analytics.js";
+export { functions } from "./functions.js";
 export { location } from "./location.js";
 import * as realtime_1 from "./realtime.js";
 export { realtime_1 as realtime };

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.19  |  Generated: 2026-09-24T19:51:28.993Z
+Version: 2.0.21  |  Generated: 2026-09-25T17:47:14.766Z
 
 This is a concise summary of all available API functions and types.
 
@@ -135,6 +135,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **config** - Functions for config operations
 - **containers** - Functions for containers operations
 - **facets** - Functions for facets operations
+- **functions** - Functions for functions operations
 - **http** - Functions for http operations
 - **integrations** - Functions for integrations operations
 - **jobs** - Functions for jobs operations
@@ -165,6 +166,12 @@ Reset the diagnostics counters (does not touch the cache itself).
 **isProxyEnabled**() → `boolean`
 Return whether proxy mode is currently enabled.
 
+**getAppContext**() → `string | undefined`
+The current app context (appId), if the SDK was initialized with one.
+
+**setAppContext**(id: string | undefined) → `void`
+Set (or clear) the current app context — the appId used to scope SL.functions calls.
+
 **initializeApi**(options: {
   baseURL: string
   apiKey?: string
@@ -8943,6 +8950,31 @@ type VerifyTokenResponse = {
 }
 ```
 
+### functions (api)
+
+**FunctionListEntry** (interface)
+```typescript
+interface FunctionListEntry {
+  name: string; visibility?: string; trigger?: string
+}
+```
+
+**FunctionListResponse** (interface)
+```typescript
+interface FunctionListResponse {
+  functions: FunctionListEntry[]
+}
+```
+
+**FunctionCallOptions** (interface)
+```typescript
+interface FunctionCallOptions {
+  appId?: string
+}
+```
+
+**FunctionCallResult** = `any`
+
 ### sequence (api)
 
 **AllocateSequenceInput** (interface)
@@ -10435,6 +10467,23 @@ Update a form for a collection (admin only).
 **remove**(collectionId: string, formId: string) → `Promise<void>`
 Delete a form for a collection (admin only).
 
+### functions
+
+**call**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
+    opts: FunctionCallOptions = {}) → `Promise<T>`
+Call a PUBLIC app server function inline (surface `'public'`). App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`. // App calling its own function (appId from initializeApi({ appId })): const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter') // Or address another app explicitly: await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
+
+**callAdmin**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
+    opts: FunctionCallOptions = {}) → `Promise<T>`
+Call an ADMIN app server function (surface `'admin'`; requires an admin session). App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
+
+**list**(collectionId: string, opts: FunctionCallOptions = {}) → `Promise<FunctionListResponse>`
+List the public functions available for a collection (discovery). Scoped to one app when an appId is given (or set as the SDK app context): `GET /public/collection/:c[/app/:appId]/functions`.
+
 ### http
 
 **get**(path: string) → `Promise<T>`

package/dist/docs/server-functions.md

@@ -181,11 +181,14 @@ interface ServerFunctionContext {
   collectionId: string
   appId: string
 
-  /** SmartLinks SDK, pre-scoped to your declared `authority`. Capabilities cap what it may do. */
+  /** SmartLinks SDK, pre-scoped to your declared `authority`. Capabilities cap what it may do.
+   *  Key resources: `sl.appRecords` (per-app records), `sl.appData` (general/app-wide config +
+   *  data — URLs, flags, counters, arrays), `sl.products`, `sl.attestations`. */
   sl: SmartLinks
 
-  /** Capability-gated secrets. Resolves only refs you declared via `secrets:<ref>`. */
-  secrets: { get(ref: string): Promise<string | null> }
+  /** 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. */
+  secrets: { get(ref: string): Promise<string | null>; app(ref: string): Promise<string | null> }
 
   /** Who invoked this function. */
   caller: {
@@ -211,6 +214,50 @@ already authenticated as your declared authority and scoped to the collection. D
 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.
 
+### Calling a function from your app (client side)
+
+From a page/UI, invoke an `http`-trigger function with the SDK — no manual fetch, no URL building:
+
+```ts
+// public function (runs on the caller's authority — signed-in owner, else public):
+const res = await SL.functions.call(collectionId, 'increment', { /* becomes event.body */ })
+// admin surface (needs an admin session):
+const res = await SL.functions.callAdmin(collectionId, 'recomputeTotals', { … })
+```
+
+`res` is whatever your handler returns. See the `edge-function-test` example for a full page +
+function + manifest.
+
+#### Functions are ALWAYS app-scoped
+
+A function belongs to an app, so the canonical route carries the appId:
+`POST /collection/:collectionId/app/:appId/functions/:name`. Two different installed apps can each
+ship a function of the same name without clashing.
+
+The SDK fills the appId in for you. Initialize with your app's id once, then call by bare name —
+the SDK routes it app-scoped:
+
+```ts
+SL.initializeApi({ baseURL, appId: 'my-counter-app' })   // usually done by the host/bootstrap
+await SL.functions.call(collectionId, 'pressCounter')     // → /collection/:c/app/my-counter-app/functions/pressCounter
+```
+
+To call a *different* app's function, pass the appId explicitly:
+
+```ts
+await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'some-other-app' })
+```
+
+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.
+
+> 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
+> the `global` collection and called at `/collection/global/app/:appId/functions/:name` — same two
+> facets (collection + app), with `global` as the sentinel collection.
+
 ---
 
 ## Runtime — what your function can use
@@ -262,6 +309,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` |
+| 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:
 - **Talking to the SmartLinks core is `ctx.sl`, not HTTP.** The common pattern — *validate /
@@ -318,14 +367,20 @@ 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
+An `http` function is called by POSTing to the app-scoped 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)
+POST /admin/collection/:collectionId/app/:appId/functions/:name    # visibility: admin  (collection-admin auth)
+POST /public/collection/:collectionId/app/:appId/functions/:name   # visibility: public (auth optional)
+GET  /{admin|public}/collection/:collectionId/app/:appId/functions # list this app's functions on the surface
 ```
 
+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

package/dist/http.d.ts

@@ -27,6 +27,10 @@ export declare function getHttpCacheDiagnostics(): {
 export declare function resetHttpCacheDiagnostics(): void;
 /** Return whether proxy mode is currently enabled. */
 export declare function isProxyEnabled(): boolean;
+/** The current app context (appId), if the SDK was initialized with one. */
+export declare function getAppContext(): string | undefined;
+/** Set (or clear) the current app context — the appId used to scope SL.functions calls. */
+export declare function setAppContext(id: string | undefined): void;
 export declare function initializeApi(options: {
     baseURL: string;
     apiKey?: string;
@@ -42,6 +46,12 @@ export declare function initializeApi(options: {
      * across re-initialization when not supplied.
      */
     platform?: 'native' | 'web';
+    /**
+     * The appId of the micro-app initializing the SDK. When set, `SL.functions.call(...)` and
+     * `callAdmin(...)` resolve app-scoped by default (no need to pass appId on every call).
+     * Preserved across re-initialization when not supplied.
+     */
+    appId?: string;
     iframeAutoResize?: boolean;
     logger?: Logger;
     /**

package/dist/http.js

@@ -45,6 +45,13 @@ let clientPlatform = undefined;
  * data call that touches the granted proof (attestations, threads, app data).
  */
 let grantToken = undefined;
+/**
+ * The current app context — the appId of the micro-app this SDK instance belongs to.
+ * Set via initializeApi({ appId }) or setAppContext(). Lets an app call its OWN server
+ * functions without repeating its id: SL.functions.call(collectionId, name) resolves
+ * app-scoped when this is set. Explicit `appId` on a call always overrides it.
+ */
+let appContextId = undefined;
 /** Whether initializeApi has been successfully called at least once. */
 let initialized = false;
 /** Safely returns the current browser hostname, or an empty string in non-browser / Node environments. */
@@ -293,6 +300,14 @@ function logDebug(...args) {
 export function isProxyEnabled() {
     return proxyMode;
 }
+/** The current app context (appId), if the SDK was initialized with one. */
+export function getAppContext() {
+    return appContextId;
+}
+/** Set (or clear) the current app context — the appId used to scope SL.functions calls. */
+export function setAppContext(id) {
+    appContextId = id;
+}
 function maskSensitive(value) {
     if (!value)
         return value;
@@ -443,6 +458,9 @@ export function initializeApi(options) {
     }
     baseURL = normalizedBaseURL;
     apiKey = options.apiKey;
+    // Preserve the app context across re-inits that omit it (mirrors platform/token handling).
+    if (options.appId !== undefined)
+        appContextId = options.appId;
     // Enable token persistence before restoring the token.
     if (options.persistToken !== undefined)
         tokenPersistenceEnabled = options.persistToken;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, invalidateCache, getHttpCacheDiagnostics, resetHttpCacheDiagnostics, request, post, put, patch, del, sendCustomProxyMessage, getApiHeaders, getBaseURL, isProxyEnabled, setBearerToken, getBearerToken, setGrantToken, getGrantToken } from "./http.js";
+export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, invalidateCache, getHttpCacheDiagnostics, resetHttpCacheDiagnostics, request, post, put, patch, del, sendCustomProxyMessage, getApiHeaders, getBaseURL, isProxyEnabled, setBearerToken, getBearerToken, setGrantToken, getGrantToken, getAppContext, setAppContext } from "./http.js";
 export * from "./api/index.js";
 export * from "./types/index.js";
 export { iframe } from "./iframe.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 // Top-level entrypoint of the npm package. Re-export initializeApi + all namespaces.
-export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, invalidateCache, getHttpCacheDiagnostics, resetHttpCacheDiagnostics, request, post, put, patch, del, sendCustomProxyMessage, getApiHeaders, getBaseURL, isProxyEnabled, setBearerToken, getBearerToken, setGrantToken, getGrantToken } from "./http.js";
+export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, invalidateCache, getHttpCacheDiagnostics, resetHttpCacheDiagnostics, request, post, put, patch, del, sendCustomProxyMessage, getApiHeaders, getBaseURL, isProxyEnabled, setBearerToken, getBearerToken, setGrantToken, getGrantToken, getAppContext, setAppContext } from "./http.js";
 export * from "./api/index.js";
 export * from "./types/index.js";
 // Iframe namespace

package/dist/openapi.yaml

@@ -29269,6 +29269,28 @@ components:
           additionalProperties: true
       required:
         - valid
+    FunctionListEntry:
+      type: object
+      properties:
+        name:
+          type: object
+          additionalProperties: true
+      required:
+        - name
+    FunctionListResponse:
+      type: object
+      properties:
+        functions:
+          type: array
+          items:
+            $ref: "#/components/schemas/FunctionListEntry"
+      required:
+        - functions
+    FunctionCallOptions:
+      type: object
+      properties:
+        appId:
+          type: string
     AllocateSequenceInput:
       type: object
       properties:

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.19  |  Generated: 2026-09-24T19:51:28.993Z
+Version: 2.0.21  |  Generated: 2026-09-25T17:47:14.766Z
 
 This is a concise summary of all available API functions and types.
 
@@ -135,6 +135,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **config** - Functions for config operations
 - **containers** - Functions for containers operations
 - **facets** - Functions for facets operations
+- **functions** - Functions for functions operations
 - **http** - Functions for http operations
 - **integrations** - Functions for integrations operations
 - **jobs** - Functions for jobs operations
@@ -165,6 +166,12 @@ Reset the diagnostics counters (does not touch the cache itself).
 **isProxyEnabled**() → `boolean`
 Return whether proxy mode is currently enabled.
 
+**getAppContext**() → `string | undefined`
+The current app context (appId), if the SDK was initialized with one.
+
+**setAppContext**(id: string | undefined) → `void`
+Set (or clear) the current app context — the appId used to scope SL.functions calls.
+
 **initializeApi**(options: {
   baseURL: string
   apiKey?: string
@@ -8943,6 +8950,31 @@ type VerifyTokenResponse = {
 }
 ```
 
+### functions (api)
+
+**FunctionListEntry** (interface)
+```typescript
+interface FunctionListEntry {
+  name: string; visibility?: string; trigger?: string
+}
+```
+
+**FunctionListResponse** (interface)
+```typescript
+interface FunctionListResponse {
+  functions: FunctionListEntry[]
+}
+```
+
+**FunctionCallOptions** (interface)
+```typescript
+interface FunctionCallOptions {
+  appId?: string
+}
+```
+
+**FunctionCallResult** = `any`
+
 ### sequence (api)
 
 **AllocateSequenceInput** (interface)
@@ -10435,6 +10467,23 @@ Update a form for a collection (admin only).
 **remove**(collectionId: string, formId: string) → `Promise<void>`
 Delete a form for a collection (admin only).
 
+### functions
+
+**call**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
+    opts: FunctionCallOptions = {}) → `Promise<T>`
+Call a PUBLIC app server function inline (surface `'public'`). App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`. // App calling its own function (appId from initializeApi({ appId })): const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter') // Or address another app explicitly: await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
+
+**callAdmin**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
+    opts: FunctionCallOptions = {}) → `Promise<T>`
+Call an ADMIN app server function (surface `'admin'`; requires an admin session). App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
+
+**list**(collectionId: string, opts: FunctionCallOptions = {}) → `Promise<FunctionListResponse>`
+List the public functions available for a collection (discovery). Scoped to one app when an appId is given (or set as the SDK app context): `GET /public/collection/:c[/app/:appId]/functions`.
+
 ### http
 
 **get**(path: string) → `Promise<T>`

package/docs/server-functions.md

@@ -181,11 +181,14 @@ interface ServerFunctionContext {
   collectionId: string
   appId: string
 
-  /** SmartLinks SDK, pre-scoped to your declared `authority`. Capabilities cap what it may do. */
+  /** SmartLinks SDK, pre-scoped to your declared `authority`. Capabilities cap what it may do.
+   *  Key resources: `sl.appRecords` (per-app records), `sl.appData` (general/app-wide config +
+   *  data — URLs, flags, counters, arrays), `sl.products`, `sl.attestations`. */
   sl: SmartLinks
 
-  /** Capability-gated secrets. Resolves only refs you declared via `secrets:<ref>`. */
-  secrets: { get(ref: string): Promise<string | null> }
+  /** 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. */
+  secrets: { get(ref: string): Promise<string | null>; app(ref: string): Promise<string | null> }
 
   /** Who invoked this function. */
   caller: {
@@ -211,6 +214,50 @@ already authenticated as your declared authority and scoped to the collection. D
 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.
 
+### Calling a function from your app (client side)
+
+From a page/UI, invoke an `http`-trigger function with the SDK — no manual fetch, no URL building:
+
+```ts
+// public function (runs on the caller's authority — signed-in owner, else public):
+const res = await SL.functions.call(collectionId, 'increment', { /* becomes event.body */ })
+// admin surface (needs an admin session):
+const res = await SL.functions.callAdmin(collectionId, 'recomputeTotals', { … })
+```
+
+`res` is whatever your handler returns. See the `edge-function-test` example for a full page +
+function + manifest.
+
+#### Functions are ALWAYS app-scoped
+
+A function belongs to an app, so the canonical route carries the appId:
+`POST /collection/:collectionId/app/:appId/functions/:name`. Two different installed apps can each
+ship a function of the same name without clashing.
+
+The SDK fills the appId in for you. Initialize with your app's id once, then call by bare name —
+the SDK routes it app-scoped:
+
+```ts
+SL.initializeApi({ baseURL, appId: 'my-counter-app' })   // usually done by the host/bootstrap
+await SL.functions.call(collectionId, 'pressCounter')     // → /collection/:c/app/my-counter-app/functions/pressCounter
+```
+
+To call a *different* app's function, pass the appId explicitly:
+
+```ts
+await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'some-other-app' })
+```
+
+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.
+
+> 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
+> the `global` collection and called at `/collection/global/app/:appId/functions/:name` — same two
+> facets (collection + app), with `global` as the sentinel collection.
+
 ---
 
 ## Runtime — what your function can use
@@ -262,6 +309,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` |
+| 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:
 - **Talking to the SmartLinks core is `ctx.sl`, not HTTP.** The common pattern — *validate /
@@ -318,14 +367,20 @@ 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
+An `http` function is called by POSTing to the app-scoped 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)
+POST /admin/collection/:collectionId/app/:appId/functions/:name    # visibility: admin  (collection-admin auth)
+POST /public/collection/:collectionId/app/:appId/functions/:name   # visibility: public (auth optional)
+GET  /{admin|public}/collection/:collectionId/app/:appId/functions # list this app's functions on the surface
 ```
 
+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

package/openapi.yaml

@@ -29269,6 +29269,28 @@ components:
           additionalProperties: true
       required:
         - valid
+    FunctionListEntry:
+      type: object
+      properties:
+        name:
+          type: object
+          additionalProperties: true
+      required:
+        - name
+    FunctionListResponse:
+      type: object
+      properties:
+        functions:
+          type: array
+          items:
+            $ref: "#/components/schemas/FunctionListEntry"
+      required:
+        - functions
+    FunctionCallOptions:
+      type: object
+      properties:
+        appId:
+          type: string
     AllocateSequenceInput:
       type: object
       properties:

package/package.json

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