@proveanything/smartlinks 2.0.35 → 2.0.37

package/dist/api/ai.d.ts

@@ -111,8 +111,8 @@ declare namespace aiInternal {
         }>;
     }
     /**
-     * AI usage / cost report for a collection, grouped by any of model/serviceTier/appId/feature/mode
-     * over an optional date window. `costUnits` are OPAQUE internal units, never provider currency.
+     * AI usage for a collection (daily totals), grouped by any of model/appId/feature/mode/surface/provider/day
+     * over an optional date window (YYYY-MM-DD). Usage only — requests, tokens, images; no cost figures.
      */
     function usage(collectionId: string, params?: {
         groupBy?: string | string[];

package/dist/api/ai.js

@@ -224,8 +224,8 @@ var aiInternal;
         sessions.clear = clear;
     })(sessions = aiInternal.sessions || (aiInternal.sessions = {}));
     /**
-     * AI usage / cost report for a collection, grouped by any of model/serviceTier/appId/feature/mode
-     * over an optional date window. `costUnits` are OPAQUE internal units, never provider currency.
+     * AI usage for a collection (daily totals), grouped by any of model/appId/feature/mode/surface/provider/day
+     * over an optional date window (YYYY-MM-DD). Usage only — requests, tokens, images; no cost figures.
      */
     async function usage(collectionId, params) {
         const groupBy = Array.isArray(params === null || params === void 0 ? void 0 : params.groupBy) ? params.groupBy.join(',') : params === null || params === void 0 ? void 0 : params.groupBy;

package/dist/api/collection.d.ts

@@ -27,7 +27,7 @@ export declare namespace collection {
      * The server derives the requesting domain from the request headers
      * (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is
      * passed — this is the call a Hub frontend makes on load to find out which
-     * collection it is serving, whether it's reached via `{brand}.mysmartlinks.app`
+     * collection it is serving, whether it's reached via `{brand}.smartlinks.host`
      * or a bring-your-own custom domain (e.g. `hub.acme.com`).
      *
      * @returns Promise resolving to the CollectionResponse mapped to the domain
@@ -39,9 +39,9 @@ export declare namespace collection {
      *
      * Unlike {@link getByHub}, the domain is passed explicitly rather than derived
      * from request headers — use this for raw/cross-origin calls where the Hub
-     * frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+     * frontend knows its own hostname (e.g. "erbauer.smartlinks.host").
      *
-     * @param domain – The Hub domain to resolve (custom domain or {brand}.mysmartlinks.app)
+     * @param domain – The Hub domain to resolve (custom domain or {brand}.smartlinks.host)
      * @returns Promise resolving to the CollectionResponse mapped to the domain
      * @throws ErrorResponse (404) if no collection is mapped to the domain
      */
@@ -57,7 +57,7 @@ export declare namespace collection {
     /**
      * Claim or rename the Hub subdomain for a collection (admin only).
      *
-     * Maps `{hubName}.mysmartlinks.app` to the collection. If the collection
+     * Maps `{hubName}.smartlinks.host` to the collection. If the collection
      * already had a different hub name, the previous subdomain is released
      * automatically.
      *

package/dist/api/collection.js

@@ -43,7 +43,7 @@ export var collection;
      * The server derives the requesting domain from the request headers
      * (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is
      * passed — this is the call a Hub frontend makes on load to find out which
-     * collection it is serving, whether it's reached via `{brand}.mysmartlinks.app`
+     * collection it is serving, whether it's reached via `{brand}.smartlinks.host`
      * or a bring-your-own custom domain (e.g. `hub.acme.com`).
      *
      * @returns Promise resolving to the CollectionResponse mapped to the domain
@@ -59,9 +59,9 @@ export var collection;
      *
      * Unlike {@link getByHub}, the domain is passed explicitly rather than derived
      * from request headers — use this for raw/cross-origin calls where the Hub
-     * frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+     * frontend knows its own hostname (e.g. "erbauer.smartlinks.host").
      *
-     * @param domain – The Hub domain to resolve (custom domain or {brand}.mysmartlinks.app)
+     * @param domain – The Hub domain to resolve (custom domain or {brand}.smartlinks.host)
      * @returns Promise resolving to the CollectionResponse mapped to the domain
      * @throws ErrorResponse (404) if no collection is mapped to the domain
      */
@@ -86,7 +86,7 @@ export var collection;
     /**
      * Claim or rename the Hub subdomain for a collection (admin only).
      *
-     * Maps `{hubName}.mysmartlinks.app` to the collection. If the collection
+     * Maps `{hubName}.smartlinks.host` to the collection. If the collection
      * already had a different hub name, the previous subdomain is released
      * automatically.
      *

package/dist/api/functions.d.ts

@@ -29,7 +29,37 @@ export interface FunctionCallOptions {
 export declare function resolveFunctionChannel(opts?: FunctionCallOptions, appId?: string): string | undefined;
 /** The API path a function call goes to (exported for hosts/tests that need the exact URL). */
 export declare function functionPath(surface: 'public' | 'admin', collectionId: string, name: string, opts?: FunctionCallOptions): string;
+/** Options for {@link functions.siteUrl}. */
+export interface FunctionSiteUrlOptions {
+    /** Release channel ('dev' | 'alpha' | 'beta' | 'stable'); omit for the collection's installed release. */
+    channel?: string;
+    /** Sub-path after the function name, e.g. "/orders/123" (the function must declare trigger.path). */
+    path?: string;
+    /** Query parameters to append. */
+    query?: Record<string, string>;
+    /** Use this host instead of the collection's siteHost (e.g. its connected custom domain). */
+    host?: string;
+}
 export declare namespace functions {
+    /**
+     * The PUBLIC address of an app function on the collection's own site — what you give a third party
+     * as a webhook URL, or call from the collection's public pages:
+     * `https://<siteHost>/_fn/<appId>[/<channel>]/<name>[/<path>]`.
+     * Every HTTP method the function declares works there, with the raw body for signature checks.
+     * Pass the collection (or its siteHost). This address is for public/integration calls; signed-in
+     * calls from your app keep using {@link call} / {@link callAdmin}, so the user's SmartLinks session
+     * never goes to a tenant hostname.
+     *
+     * @example
+     * const col = await SL.collection.get(collectionId)
+     * const hookUrl = SL.functions.siteUrl(col, 'stripeWebhook', { appId: 'my-shop' })
+     * // → https://acme.smartlinks.host/_fn/my-shop/stripeWebhook
+     */
+    function siteUrl(collection: {
+        siteHost?: string | null;
+    } | string, name: string, opts?: FunctionSiteUrlOptions & {
+        appId?: string;
+    }): string;
     /**
      * Call a PUBLIC app server function inline (surface `'public'`).
      * App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`.

package/dist/api/functions.js

@@ -64,6 +64,34 @@ export function functionPath(surface, collectionId, name, opts = {}) {
 const fnPath = functionPath;
 export var functions;
 (function (functions) {
+    /**
+     * The PUBLIC address of an app function on the collection's own site — what you give a third party
+     * as a webhook URL, or call from the collection's public pages:
+     * `https://<siteHost>/_fn/<appId>[/<channel>]/<name>[/<path>]`.
+     * Every HTTP method the function declares works there, with the raw body for signature checks.
+     * Pass the collection (or its siteHost). This address is for public/integration calls; signed-in
+     * calls from your app keep using {@link call} / {@link callAdmin}, so the user's SmartLinks session
+     * never goes to a tenant hostname.
+     *
+     * @example
+     * const col = await SL.collection.get(collectionId)
+     * const hookUrl = SL.functions.siteUrl(col, 'stripeWebhook', { appId: 'my-shop' })
+     * // → https://acme.smartlinks.host/_fn/my-shop/stripeWebhook
+     */
+    function siteUrl(collection, name, opts = {}) {
+        var _a, _b;
+        const host = opts.host || (typeof collection === 'string' ? collection : collection && collection.siteHost);
+        if (!host)
+            throw new Error('functions.siteUrl: the collection has no siteHost (fetch it with SL.collection.get)');
+        const app = (_a = opts.appId) !== null && _a !== void 0 ? _a : getAppContext();
+        if (!app)
+            throw new Error('functions.siteUrl: appId required (pass it, or initializeApi({ appId }))');
+        const ch = resolveFunctionChannel({ channel: (_b = opts.channel) !== null && _b !== void 0 ? _b : null }, app);
+        const sub = opts.path ? '/' + String(opts.path).replace(/^\/+/, '') : '';
+        const qs = opts.query && Object.keys(opts.query).length ? '?' + new URLSearchParams(opts.query).toString() : '';
+        return `https://${String(host).replace(/^https?:\/\//, '').replace(/\/+$/, '')}/_fn/${encodeURIComponent(app)}${ch ? `/${ch}` : ''}/${encodeURIComponent(name)}${sub}${qs}`;
+    }
+    functions.siteUrl = siteUrl;
     /**
      * Call a PUBLIC app server function inline (surface `'public'`).
      * App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`.

package/dist/context.js

@@ -40,6 +40,21 @@ export function readContext(overrides) {
             if (window.location.search)
                 readSearchParamsInto(out, new URLSearchParams(window.location.search));
         }
+        // 4. the SITE the page is served as (lowest precedence). When an app runs as a public website at
+        //    its own hostname (an "app site"), the host page injects window.__SMARTLINKS_SITE__ =
+        //    { collectionId, appId, channel, host } — so a site knows its collection with no URL params.
+        const site = globalThis.__SMARTLINKS_SITE__;
+        if (site && typeof site === 'object') {
+            const fill = (key, value) => { if (out[key] == null && typeof value === 'string' && value)
+                out[key] = value; };
+            fill('collectionId', site.collectionId);
+            fill('appId', site.appId);
+            // A site on a pre-release channel calls that channel's server functions (stable needs no channel).
+            if (site.channel && site.channel !== 'stable') {
+                fill('appChannel', site.channel);
+                fill('appChannelApp', site.appId);
+            }
+        }
     }
     catch (_a) {
         /* non-browser / bad URL — return what we have */

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.35  |  Generated: 2026-10-03T12:37:51.058Z
+Version: 2.0.37  |  Generated: 2026-10-04T09:59:59.885Z
 
 This is a concise summary of all available API functions and types.
 
@@ -918,8 +918,20 @@ interface AiUsageReport {
   groupBy: string[]
   from?: string | null
   to?: string | null
-  totals: { promptTokens: number; outputTokens: number; totalTokens: number; requests: number; costUnits: number }
-  groups: Array<Record<string, any> & { promptTokens: number; outputTokens: number; totalTokens: number; requests: number; costUnits: number }>
+  totals: AiUsageTotals
+  groups: Array<Record<string, any> & AiUsageTotals>
+}
+```
+
+**AiUsageTotals** (interface)
+```typescript
+interface AiUsageTotals {
+  promptTokens: number
+  outputTokens: number
+  cachedTokens: number
+  totalTokens: number
+  requests: number
+  images: number
 }
 ```
 
@@ -4839,6 +4851,7 @@ interface Collection {
   redirectUrl?: string // Whether the collection has a custom domain
   hubName?: string
   hubCustomDomain?: string
+  siteHost?: string | null
   shortId: string, // The shortId of this collection
   dark?: boolean // if dark mode is enabled for this collection
   primaryColor?: string
@@ -9594,6 +9607,16 @@ interface FunctionCallOptions {
 }
 ```
 
+**FunctionSiteUrlOptions** (interface)
+```typescript
+interface FunctionSiteUrlOptions {
+  channel?: string
+  path?: string
+  query?: Record<string, string>
+  host?: string
+}
+```
+
 **FunctionCallResult** = `any`
 
 ### sequence (api)
@@ -10722,16 +10745,16 @@ Retrieves all Collections.
 Retrieve a collection by its shortId (public endpoint).
 
 **getByHub**() → `Promise<CollectionResponse>`
-Resolve the collection for the current Hub domain (public endpoint). The server derives the requesting domain from the request headers (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is passed — this is the call a Hub frontend makes on load to find out which collection it is serving, whether it's reached via `{brand}.mysmartlinks.app` or a bring-your-own custom domain (e.g. `hub.acme.com`).
+Resolve the collection for the current Hub domain (public endpoint). The server derives the requesting domain from the request headers (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is passed — this is the call a Hub frontend makes on load to find out which collection it is serving, whether it's reached via `{brand}.smartlinks.host` or a bring-your-own custom domain (e.g. `hub.acme.com`).
 
 **getByDomain**(domain: string) → `Promise<CollectionResponse>`
-Resolve the collection for an explicit Hub domain (public endpoint). Unlike {@link getByHub}, the domain is passed explicitly rather than derived from request headers — use this for raw/cross-origin calls where the Hub frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+Resolve the collection for an explicit Hub domain (public endpoint). Unlike {@link getByHub}, the domain is passed explicitly rather than derived from request headers — use this for raw/cross-origin calls where the Hub frontend knows its own hostname (e.g. "erbauer.smartlinks.host").
 
 **checkHubAvailability**(collectionId: string, name: string) → `Promise<HubAvailabilityResponse>`
 Check whether a Hub subdomain name is available to claim (admin only).
 
 **claimHub**(collectionId: string, hubName: string) → `Promise<CollectionResponse>`
-Claim or rename the Hub subdomain for a collection (admin only). Maps `{hubName}.mysmartlinks.app` to the collection. If the collection already had a different hub name, the previous subdomain is released automatically.
+Claim or rename the Hub subdomain for a collection (admin only). Maps `{hubName}.smartlinks.host` to the collection. If the collection already had a different hub name, the previous subdomain is released automatically.
 
 **registerDomain**(collectionId: string, domain: string, target: DomainTarget = "smartlinks") → `Promise<any>`
 Register a custom domain for a collection and provision its managed certificate (admin only). `"smartlinks"` (the id.smartlinks.app load balancer). Pass `"hub"` to register a bring-your-own Hub domain.
@@ -11108,6 +11131,11 @@ The release channel a call targets, or undefined for "the collection's installed
 **functionPath**(surface: 'public' | 'admin', collectionId: string, name: string, opts: FunctionCallOptions = {}) → `string`
 The API path a function call goes to (exported for hosts/tests that need the exact URL).
 
+**siteUrl**(collection: { siteHost?: string | null } | string,
+    name: string,
+    opts: FunctionSiteUrlOptions & { appId?: string } = {}) → `string`
+The PUBLIC address of an app function on the collection's own site — what you give a third party as a webhook URL, or call from the collection's public pages: `https://<siteHost>/_fn/<appId>[/<channel>]/<name>[/<path>]`. Every HTTP method the function declares works there, with the raw body for signature checks. Pass the collection (or its siteHost). This address is for public/integration calls; signed-in calls from your app keep using {@link call} / {@link callAdmin}, so the user's SmartLinks session never goes to a tenant hostname. const col = await SL.collection.get(collectionId) const hookUrl = SL.functions.siteUrl(col, 'stripeWebhook', { appId: 'my-shop' }) // → https://acme.smartlinks.host/_fn/my-shop/stripeWebhook
+
 **call**(collectionId: string,
     name: string,
     body: Record<string, any> = {},

package/dist/docs/server-functions.md

@@ -251,10 +251,15 @@ await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'some-other-a
 **Where it runs.** A function runs on a collection when the app is **installed** there (enabled in
 the collection's apps); or the app is **restricted** to a list of collections (what publishing from
 Forge sets for every developer) and this collection is on it, e.g. your own sandbox; or the app is
-**public**, meaning a registered, non-development app with no restriction list, which only platform
-admins can publish. Anything else gets `404 APP_NOT_INSTALLED`: a function can run with the
-collection's own authority and secrets, so a developer's app can't reach a collection that hasn't
-taken it on.
+**public**, meaning a registered app with no restriction list, which only platform admins can
+publish. Anything else gets `404 APP_NOT_INSTALLED`: a function can run with the collection's own
+authority and secrets, so a developer's app can't reach a collection that hasn't taken it on.
+
+**Who may run server code at all.** Until functions move to an isolated runner, only TRUSTED apps
+execute: public (unrestricted) apps, or apps a platform admin has marked `functionsTrusted: true`.
+Developer apps — restricted to their own collections, which includes every app published from
+self-serve Forge — get `403 FUNCTIONS_NOT_ENABLED` until they're trusted. A platform admin can also
+switch any app's functions off with `functionsTrusted: false`.
 
 **Which release.** With no channel, the server runs the release the collection has **installed** (stable for a
 public app that isn't installed) — what production wants, so app code just calls `SL.functions.call(collectionId, name)`. To run
@@ -269,6 +274,40 @@ await SL.functions.call(collectionId, 'pressCounter', {}, { channel: 'beta' }) /
 await SL.functions.call(collectionId, 'pressCounter', {}, { channel: null })   // force the installed release
 ```
 
+**Public address on the collection's own site (webhooks, integrations).** Every collection has a
+site host — `<name>.smartlinks.host` once a name is claimed, else `c-<collectionId>.smartlinks.host` —
+returned as `collection.siteHost`. App functions are reachable there:
+
+```
+https://<siteHost>/_fn/<appId>[/<channel>]/<function>[/<sub-path…>]
+```
+
+```ts
+const col = await SL.collection.get(collectionId)
+const webhookUrl = SL.functions.siteUrl(col, 'stripeWebhook', { appId: 'my-shop' })
+// → https://acme.smartlinks.host/_fn/my-shop/stripeWebhook   (give this to Stripe)
+```
+
+Built for integrations: **every HTTP method** the function declares in `trigger.methods` (default
+POST only), **any content type** with the exact bytes in `event.rawBody` (verify signatures with
+`crypto.subtle`), **sub-paths** after the name when the function declares `trigger.path` (`"/*"`, or a
+pattern like `"/orders/:id"` → `event.params.id`), and the function's own `Response` — status, headers,
+CORS — goes back unchanged (the platform adds no CORS headers there; declare `OPTIONS` and answer
+preflights yourself if browsers call you cross-origin). Bodies up to 6 MB.
+
+```js
+// manifest: { name: 'orders', trigger: { type: 'http', methods: ['GET', 'PUT'], path: '/orders/:id' }, visibility: 'public' }
+export async function orders(ctx, event) {
+  if (event.method === 'GET') return ctx.sl.appRecords.get(event.params.id)
+  // PUT: verify the sender first — e.g. an HMAC over event.rawBody with a secret
+}
+```
+
+Security: the platform never hands a caller's SmartLinks credential to function code (if it signed
+the caller in from `Authorization`, that header is removed and you get `ctx.caller`); your OWN
+`Authorization` scheme for webhooks passes through. `siteUrl` only includes a channel you ask for —
+point production webhooks at the bare address and test ones at `/dev/`.
+
 The channel is never a query parameter: the function owns its query string (`?channel=sms` reaches
 your handler untouched), and a configured URL — a webhook, a third-party callback — can only ever
 hit the channel it names. Point production webhooks at the bare path and test ones at `/dev/`.

package/dist/openapi.yaml

@@ -1347,7 +1347,7 @@ paths:
     get:
       tags:
         - sessions
-      summary: AI usage / cost report for a collection, grouped by any of model/serviceTier/appId/feature/mode over an optional date window.
+      summary: AI usage for a collection (daily totals), grouped by any of model/appId/feature/mode/surface/provider/day over an optional date window (YYYY-MM-DD).
       operationId: sessions_usage
       security:
         - bearerAuth: []
@@ -16327,17 +16327,37 @@ components:
         to:
           type: string
         totals:
-          type: object
-          additionalProperties: true
+          $ref: "#/components/schemas/AiUsageTotals"
         groups:
           type: array
           items:
-            type: object
-            additionalProperties: true
+            $ref: "#/components/schemas/AiUsageTotals"
       required:
         - groupBy
         - totals
         - groups
+    AiUsageTotals:
+      type: object
+      properties:
+        promptTokens:
+          type: number
+        outputTokens:
+          type: number
+        cachedTokens:
+          type: number
+        totalTokens:
+          type: number
+        requests:
+          type: number
+        images:
+          type: number
+      required:
+        - promptTokens
+        - outputTokens
+        - cachedTokens
+        - totalTokens
+        - requests
+        - images
     VoiceSessionRequest:
       type: object
       properties:
@@ -23052,6 +23072,8 @@ components:
           type: string
         hubCustomDomain:
           type: string
+        siteHost:
+          type: string
         shortId:
           type: string
         dark:
@@ -30539,6 +30561,19 @@ components:
         appId:
           type: object
           additionalProperties: true
+    FunctionSiteUrlOptions:
+      type: object
+      properties:
+        channel:
+          type: string
+        path:
+          type: string
+        query:
+          type: object
+          additionalProperties:
+            type: string
+        host:
+          type: string
     AllocateSequenceInput:
       type: object
       properties:

package/dist/types/ai.d.ts

@@ -412,25 +412,22 @@ export interface AiSessionCreate {
     /** Seed items (e.g. a system/instruction turn). */
     items?: ResponseInputItem[];
 }
-/** Per-collection AI usage/cost report. `costUnits` are OPAQUE internal units, never provider currency. */
+/** Per-collection AI usage report (daily totals). Usage only — requests, tokens, images; no cost figures. */
 export interface AiUsageReport {
     groupBy: string[];
     from?: string | null;
     to?: string | null;
-    totals: {
-        promptTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-        requests: number;
-        costUnits: number;
-    };
-    groups: Array<Record<string, any> & {
-        promptTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-        requests: number;
-        costUnits: number;
-    }>;
+    totals: AiUsageTotals;
+    groups: Array<Record<string, any> & AiUsageTotals>;
+}
+/** Summed usage for a report group (or the whole window). */
+export interface AiUsageTotals {
+    promptTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    totalTokens: number;
+    requests: number;
+    images: number;
 }
 /** Voice session request */
 export interface VoiceSessionRequest {

package/dist/types/collection.d.ts

@@ -42,10 +42,17 @@ export interface Collection {
     groupTags?: string[];
     /** Whether the collection has a custom domain */
     redirectUrl?: string;
-    /** The claimed Hub subdomain prefix (e.g. "acme" → acme.mysmartlinks.app) */
+    /** The claimed Hub subdomain prefix (e.g. "acme" → acme.smartlinks.host) */
     hubName?: string;
     /** The collection's bring-your-own custom Hub domain (e.g. "hub.acme.com") */
     hubCustomDomain?: string;
+    /**
+     * The collection's SITE HOST on the tenant domain — computed by the server, never stored:
+     * `<hubName>.smartlinks.host` when a name is claimed, else the default `c-<collectionId>.smartlinks.host`.
+     * Hub serves it, and app functions are reachable under it at `https://<siteHost>/_fn/…`
+     * (see SL.functions.siteUrl).
+     */
+    siteHost?: string | null;
     /** The shortId of this collection */
     shortId: string;
     /** if dark mode is enabled for this collection */
@@ -97,7 +104,7 @@ export type DomainTarget = "smartlinks" | "hub";
 export interface HubAvailabilityResponse {
     /** Whether the name can be claimed by this collection */
     available: boolean;
-    /** The full domain that was checked (e.g. "acme.mysmartlinks.app") */
+    /** The full domain that was checked (e.g. "acme.smartlinks.host") */
     domain: string;
 }
 /**

package/dist/utils/paths.js

@@ -2,7 +2,7 @@
 // URL on any of these is NOT a custom domain, so non-master GTINs still need the
 // `/gc/{shortId}` collection prefix. `portalUrl` is only ever set to the platform
 // default or a collection's custom domain, so exact-host matching is sufficient here.
-const PLATFORM_HOSTS = ['smartlinks.app', 'mysmartlinks.app', 'zt.smartlinks.io'];
+const PLATFORM_HOSTS = ['smartlinks.app', 'smartlinks.host', 'mysmartlinks.app', 'zt.smartlinks.io'];
 /** True when `baseUrl`'s host is a collection's own custom domain (not a platform host). */
 function baseIsCustomDomain(baseUrl) {
     if (!baseUrl)

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.35  |  Generated: 2026-10-03T12:37:51.058Z
+Version: 2.0.37  |  Generated: 2026-10-04T09:59:59.885Z
 
 This is a concise summary of all available API functions and types.
 
@@ -918,8 +918,20 @@ interface AiUsageReport {
   groupBy: string[]
   from?: string | null
   to?: string | null
-  totals: { promptTokens: number; outputTokens: number; totalTokens: number; requests: number; costUnits: number }
-  groups: Array<Record<string, any> & { promptTokens: number; outputTokens: number; totalTokens: number; requests: number; costUnits: number }>
+  totals: AiUsageTotals
+  groups: Array<Record<string, any> & AiUsageTotals>
+}
+```
+
+**AiUsageTotals** (interface)
+```typescript
+interface AiUsageTotals {
+  promptTokens: number
+  outputTokens: number
+  cachedTokens: number
+  totalTokens: number
+  requests: number
+  images: number
 }
 ```
 
@@ -4839,6 +4851,7 @@ interface Collection {
   redirectUrl?: string // Whether the collection has a custom domain
   hubName?: string
   hubCustomDomain?: string
+  siteHost?: string | null
   shortId: string, // The shortId of this collection
   dark?: boolean // if dark mode is enabled for this collection
   primaryColor?: string
@@ -9594,6 +9607,16 @@ interface FunctionCallOptions {
 }
 ```
 
+**FunctionSiteUrlOptions** (interface)
+```typescript
+interface FunctionSiteUrlOptions {
+  channel?: string
+  path?: string
+  query?: Record<string, string>
+  host?: string
+}
+```
+
 **FunctionCallResult** = `any`
 
 ### sequence (api)
@@ -10722,16 +10745,16 @@ Retrieves all Collections.
 Retrieve a collection by its shortId (public endpoint).
 
 **getByHub**() → `Promise<CollectionResponse>`
-Resolve the collection for the current Hub domain (public endpoint). The server derives the requesting domain from the request headers (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is passed — this is the call a Hub frontend makes on load to find out which collection it is serving, whether it's reached via `{brand}.mysmartlinks.app` or a bring-your-own custom domain (e.g. `hub.acme.com`).
+Resolve the collection for the current Hub domain (public endpoint). The server derives the requesting domain from the request headers (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is passed — this is the call a Hub frontend makes on load to find out which collection it is serving, whether it's reached via `{brand}.smartlinks.host` or a bring-your-own custom domain (e.g. `hub.acme.com`).
 
 **getByDomain**(domain: string) → `Promise<CollectionResponse>`
-Resolve the collection for an explicit Hub domain (public endpoint). Unlike {@link getByHub}, the domain is passed explicitly rather than derived from request headers — use this for raw/cross-origin calls where the Hub frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+Resolve the collection for an explicit Hub domain (public endpoint). Unlike {@link getByHub}, the domain is passed explicitly rather than derived from request headers — use this for raw/cross-origin calls where the Hub frontend knows its own hostname (e.g. "erbauer.smartlinks.host").
 
 **checkHubAvailability**(collectionId: string, name: string) → `Promise<HubAvailabilityResponse>`
 Check whether a Hub subdomain name is available to claim (admin only).
 
 **claimHub**(collectionId: string, hubName: string) → `Promise<CollectionResponse>`
-Claim or rename the Hub subdomain for a collection (admin only). Maps `{hubName}.mysmartlinks.app` to the collection. If the collection already had a different hub name, the previous subdomain is released automatically.
+Claim or rename the Hub subdomain for a collection (admin only). Maps `{hubName}.smartlinks.host` to the collection. If the collection already had a different hub name, the previous subdomain is released automatically.
 
 **registerDomain**(collectionId: string, domain: string, target: DomainTarget = "smartlinks") → `Promise<any>`
 Register a custom domain for a collection and provision its managed certificate (admin only). `"smartlinks"` (the id.smartlinks.app load balancer). Pass `"hub"` to register a bring-your-own Hub domain.
@@ -11108,6 +11131,11 @@ The release channel a call targets, or undefined for "the collection's installed
 **functionPath**(surface: 'public' | 'admin', collectionId: string, name: string, opts: FunctionCallOptions = {}) → `string`
 The API path a function call goes to (exported for hosts/tests that need the exact URL).
 
+**siteUrl**(collection: { siteHost?: string | null } | string,
+    name: string,
+    opts: FunctionSiteUrlOptions & { appId?: string } = {}) → `string`
+The PUBLIC address of an app function on the collection's own site — what you give a third party as a webhook URL, or call from the collection's public pages: `https://<siteHost>/_fn/<appId>[/<channel>]/<name>[/<path>]`. Every HTTP method the function declares works there, with the raw body for signature checks. Pass the collection (or its siteHost). This address is for public/integration calls; signed-in calls from your app keep using {@link call} / {@link callAdmin}, so the user's SmartLinks session never goes to a tenant hostname. const col = await SL.collection.get(collectionId) const hookUrl = SL.functions.siteUrl(col, 'stripeWebhook', { appId: 'my-shop' }) // → https://acme.smartlinks.host/_fn/my-shop/stripeWebhook
+
 **call**(collectionId: string,
     name: string,
     body: Record<string, any> = {},

package/docs/server-functions.md

@@ -251,10 +251,15 @@ await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'some-other-a
 **Where it runs.** A function runs on a collection when the app is **installed** there (enabled in
 the collection's apps); or the app is **restricted** to a list of collections (what publishing from
 Forge sets for every developer) and this collection is on it, e.g. your own sandbox; or the app is
-**public**, meaning a registered, non-development app with no restriction list, which only platform
-admins can publish. Anything else gets `404 APP_NOT_INSTALLED`: a function can run with the
-collection's own authority and secrets, so a developer's app can't reach a collection that hasn't
-taken it on.
+**public**, meaning a registered app with no restriction list, which only platform admins can
+publish. Anything else gets `404 APP_NOT_INSTALLED`: a function can run with the collection's own
+authority and secrets, so a developer's app can't reach a collection that hasn't taken it on.
+
+**Who may run server code at all.** Until functions move to an isolated runner, only TRUSTED apps
+execute: public (unrestricted) apps, or apps a platform admin has marked `functionsTrusted: true`.
+Developer apps — restricted to their own collections, which includes every app published from
+self-serve Forge — get `403 FUNCTIONS_NOT_ENABLED` until they're trusted. A platform admin can also
+switch any app's functions off with `functionsTrusted: false`.
 
 **Which release.** With no channel, the server runs the release the collection has **installed** (stable for a
 public app that isn't installed) — what production wants, so app code just calls `SL.functions.call(collectionId, name)`. To run
@@ -269,6 +274,40 @@ await SL.functions.call(collectionId, 'pressCounter', {}, { channel: 'beta' }) /
 await SL.functions.call(collectionId, 'pressCounter', {}, { channel: null })   // force the installed release
 ```
 
+**Public address on the collection's own site (webhooks, integrations).** Every collection has a
+site host — `<name>.smartlinks.host` once a name is claimed, else `c-<collectionId>.smartlinks.host` —
+returned as `collection.siteHost`. App functions are reachable there:
+
+```
+https://<siteHost>/_fn/<appId>[/<channel>]/<function>[/<sub-path…>]
+```
+
+```ts
+const col = await SL.collection.get(collectionId)
+const webhookUrl = SL.functions.siteUrl(col, 'stripeWebhook', { appId: 'my-shop' })
+// → https://acme.smartlinks.host/_fn/my-shop/stripeWebhook   (give this to Stripe)
+```
+
+Built for integrations: **every HTTP method** the function declares in `trigger.methods` (default
+POST only), **any content type** with the exact bytes in `event.rawBody` (verify signatures with
+`crypto.subtle`), **sub-paths** after the name when the function declares `trigger.path` (`"/*"`, or a
+pattern like `"/orders/:id"` → `event.params.id`), and the function's own `Response` — status, headers,
+CORS — goes back unchanged (the platform adds no CORS headers there; declare `OPTIONS` and answer
+preflights yourself if browsers call you cross-origin). Bodies up to 6 MB.
+
+```js
+// manifest: { name: 'orders', trigger: { type: 'http', methods: ['GET', 'PUT'], path: '/orders/:id' }, visibility: 'public' }
+export async function orders(ctx, event) {
+  if (event.method === 'GET') return ctx.sl.appRecords.get(event.params.id)
+  // PUT: verify the sender first — e.g. an HMAC over event.rawBody with a secret
+}
+```
+
+Security: the platform never hands a caller's SmartLinks credential to function code (if it signed
+the caller in from `Authorization`, that header is removed and you get `ctx.caller`); your OWN
+`Authorization` scheme for webhooks passes through. `siteUrl` only includes a channel you ask for —
+point production webhooks at the bare address and test ones at `/dev/`.
+
 The channel is never a query parameter: the function owns its query string (`?channel=sms` reaches
 your handler untouched), and a configured URL — a webhook, a third-party callback — can only ever
 hit the channel it names. Point production webhooks at the bare path and test ones at `/dev/`.

package/openapi.yaml

@@ -1347,7 +1347,7 @@ paths:
     get:
       tags:
         - sessions
-      summary: AI usage / cost report for a collection, grouped by any of model/serviceTier/appId/feature/mode over an optional date window.
+      summary: AI usage for a collection (daily totals), grouped by any of model/appId/feature/mode/surface/provider/day over an optional date window (YYYY-MM-DD).
       operationId: sessions_usage
       security:
         - bearerAuth: []
@@ -16327,17 +16327,37 @@ components:
         to:
           type: string
         totals:
-          type: object
-          additionalProperties: true
+          $ref: "#/components/schemas/AiUsageTotals"
         groups:
           type: array
           items:
-            type: object
-            additionalProperties: true
+            $ref: "#/components/schemas/AiUsageTotals"
       required:
         - groupBy
         - totals
         - groups
+    AiUsageTotals:
+      type: object
+      properties:
+        promptTokens:
+          type: number
+        outputTokens:
+          type: number
+        cachedTokens:
+          type: number
+        totalTokens:
+          type: number
+        requests:
+          type: number
+        images:
+          type: number
+      required:
+        - promptTokens
+        - outputTokens
+        - cachedTokens
+        - totalTokens
+        - requests
+        - images
     VoiceSessionRequest:
       type: object
       properties:
@@ -23052,6 +23072,8 @@ components:
           type: string
         hubCustomDomain:
           type: string
+        siteHost:
+          type: string
         shortId:
           type: string
         dark:
@@ -30539,6 +30561,19 @@ components:
         appId:
           type: object
           additionalProperties: true
+    FunctionSiteUrlOptions:
+      type: object
+      properties:
+        channel:
+          type: string
+        path:
+          type: string
+        query:
+          type: object
+          additionalProperties:
+            type: string
+        host:
+          type: string
     AllocateSequenceInput:
       type: object
       properties:

package/package.json

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