@proveanything/smartlinks 2.0.20 → 2.0.21

package/dist/api/functions.d.ts

@@ -8,20 +8,30 @@ export interface FunctionListEntry {
 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.
-     * `POST /public/collection/:collectionId/functions/:name` — surface `'public'`.
+     * Call a PUBLIC app server function inline (surface `'public'`).
+     * App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`.
      *
      * @example
-     * const { value } = await SL.functions.call<{ value: number }>(collectionId, 'increment')
+     * // 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>): Promise<T>;
+    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).
-     * `POST /admin/collection/:collectionId/functions/:name`.
+     * 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 callAdmin<T = FunctionCallResult>(collectionId: string, name: string, body?: Record<string, any>): Promise<T>;
-    /** List the public functions available for a collection (discovery). `GET /public/collection/:c/functions`. */
-    function list(collectionId: string): Promise<FunctionListResponse>;
+    function list(collectionId: string, opts?: FunctionCallOptions): Promise<FunctionListResponse>;
 }

package/dist/api/functions.js

@@ -5,33 +5,58 @@
 // 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).
-import { post, request } from "../http.js";
+//
+// 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.
-     * `POST /public/collection/:collectionId/functions/:name` — surface `'public'`.
+     * Call a PUBLIC app server function inline (surface `'public'`).
+     * App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`.
      *
      * @example
-     * const { value } = await SL.functions.call<{ value: number }>(collectionId, 'increment')
+     * // 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 = {}) {
-        const path = `/public/collection/${encodeURIComponent(collectionId)}/functions/${encodeURIComponent(name)}`;
-        return post(path, body);
+    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).
-     * `POST /admin/collection/:collectionId/functions/:name`.
+     * App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
      */
-    async function callAdmin(collectionId, name, body = {}) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/functions/${encodeURIComponent(name)}`;
-        return post(path, body);
+    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). `GET /public/collection/:c/functions`. */
-    async function list(collectionId) {
-        const path = `/public/collection/${encodeURIComponent(collectionId)}/functions`;
+    /**
+     * 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;

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.20  |  Generated: 2026-09-25T11:48:23.950Z
+Version: 2.0.21  |  Generated: 2026-09-25T17:47:14.766Z
 
 This is a concise summary of all available API functions and types.
 
@@ -166,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
@@ -8960,6 +8966,13 @@ interface FunctionListResponse {
 }
 ```
 
+**FunctionCallOptions** (interface)
+```typescript
+interface FunctionCallOptions {
+  appId?: string
+}
+```
+
 **FunctionCallResult** = `any`
 
 ### sequence (api)
@@ -10458,16 +10471,18 @@ Delete a form for a collection (admin only).
 
 **call**(collectionId: string,
     name: string,
-    body: Record<string, any> = {}) → `Promise<T>`
-Call a PUBLIC app server function inline. `POST /public/collection/:collectionId/functions/:name` — surface `'public'`. const { value } = await SL.functions.call<{ value: number }>(collectionId, 'increment')
+    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> = {}) → `Promise<T>`
-Call an ADMIN app server function (surface `'admin'`; requires an admin session). `POST /admin/collection/:collectionId/functions/:name`.
+    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) → `Promise<FunctionListResponse>`
-List the public functions available for a collection (discovery). `GET /public/collection/:c/functions`.
+**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
 

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

@@ -72,8 +72,6 @@ tags:
     description: Product facet querying and aggregation.
   - name: form
     description: Form definitions and submissions.
-  - name: functions
-    description: functions API
   - name: integrations
     description: Third-party integration flows and imports.
   - name: interactions
@@ -12152,32 +12150,6 @@ paths:
           description: Unauthorized
         404:
           description: Not found
-  /public/collection/{collectionId}/functions:
-    get:
-      tags:
-        - functions
-      summary: List the public functions available for a collection (discovery).
-      operationId: functions_list
-      security: []
-      parameters:
-        - name: collectionId
-          in: path
-          required: true
-          schema:
-            type: string
-      responses:
-        200:
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/FunctionListResponse"
-        400:
-          description: Bad request
-        401:
-          description: Unauthorized
-        404:
-          description: Not found
   /public/collection/{collectionId}/interactions:
     get:
       tags:
@@ -29314,6 +29286,11 @@ components:
             $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.20  |  Generated: 2026-09-25T11:48:23.950Z
+Version: 2.0.21  |  Generated: 2026-09-25T17:47:14.766Z
 
 This is a concise summary of all available API functions and types.
 
@@ -166,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
@@ -8960,6 +8966,13 @@ interface FunctionListResponse {
 }
 ```
 
+**FunctionCallOptions** (interface)
+```typescript
+interface FunctionCallOptions {
+  appId?: string
+}
+```
+
 **FunctionCallResult** = `any`
 
 ### sequence (api)
@@ -10458,16 +10471,18 @@ Delete a form for a collection (admin only).
 
 **call**(collectionId: string,
     name: string,
-    body: Record<string, any> = {}) → `Promise<T>`
-Call a PUBLIC app server function inline. `POST /public/collection/:collectionId/functions/:name` — surface `'public'`. const { value } = await SL.functions.call<{ value: number }>(collectionId, 'increment')
+    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> = {}) → `Promise<T>`
-Call an ADMIN app server function (surface `'admin'`; requires an admin session). `POST /admin/collection/:collectionId/functions/:name`.
+    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) → `Promise<FunctionListResponse>`
-List the public functions available for a collection (discovery). `GET /public/collection/:c/functions`.
+**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
 

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

@@ -72,8 +72,6 @@ tags:
     description: Product facet querying and aggregation.
   - name: form
     description: Form definitions and submissions.
-  - name: functions
-    description: functions API
   - name: integrations
     description: Third-party integration flows and imports.
   - name: interactions
@@ -12152,32 +12150,6 @@ paths:
           description: Unauthorized
         404:
           description: Not found
-  /public/collection/{collectionId}/functions:
-    get:
-      tags:
-        - functions
-      summary: List the public functions available for a collection (discovery).
-      operationId: functions_list
-      security: []
-      parameters:
-        - name: collectionId
-          in: path
-          required: true
-          schema:
-            type: string
-      responses:
-        200:
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/FunctionListResponse"
-        400:
-          description: Bad request
-        401:
-          description: Unauthorized
-        404:
-          description: Not found
   /public/collection/{collectionId}/interactions:
     get:
       tags:
@@ -29314,6 +29286,11 @@ components:
             $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.20",
+  "version": "2.0.21",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",