@proveanything/smartlinks 1.15.3 → 1.15.5

package/dist/api/appConfiguration.d.ts

@@ -1,5 +1,6 @@
 import { CollectionWidgetsResponse, GetCollectionWidgetsOptions } from "../types/appManifest";
-import type { GetWidgetInstanceOptions, WidgetInstance, WidgetInstanceSummary } from "../types/appConfiguration";
+import type { AppsConfigResponse } from "../types/collection";
+import type { GetWidgetInstanceOptions, WidgetInstance, WidgetInstanceSummary, SystemBlock } from "../types/appConfiguration";
 /**
  * Options for collection/product-scoped app configuration.
  * This data is set by admins and applies to all users within the scope.
@@ -399,4 +400,92 @@ export declare namespace appConfiguration {
      * ```
      */
     function getWidgets(collectionId: string, options?: GetCollectionWidgetsOptions): Promise<CollectionWidgetsResponse>;
+    /**
+     * Resolve whether a feature flag is on, applying the `accountType` default:
+     * `enterprise` accounts default every flag to **on** unless `features[flag]`
+     * is explicitly `false`; `standard` accounts (or missing `accountType`)
+     * default every flag to **off** unless `features[flag]` is explicitly `true`.
+     * An explicit value always wins over the default either way.
+     *
+     * This is the same logic `isFeatureEnabled()` / `isFeatureEnabledSync()` use
+     * internally — call those instead in normal code. `system.features` and
+     * `accountType` are public data (no admin-only feature-check path exists),
+     * so there's no reason to fetch differently for an admin surface. This is
+     * exposed separately only for the rare case where you already have a
+     * `system` block in hand from somewhere other than `getAppConfig()` (e.g.
+     * server-rendered props) and want to resolve a flag from it directly.
+     *
+     * @example
+     * ```typescript
+     * const enabled = appConfiguration.resolveFeature(someSystemBlock, 'custom_domain');
+     * ```
+     */
+    function resolveFeature(system: SystemBlock | undefined, flag: string): boolean;
+    /**
+     * Fetch the collection's app catalog + `appConfig` entitlements data in one
+     * call — installed modules (`apps`), resolved entitlements (`system.features`,
+     * `system.meters`, etc.), and item-handling settings. This is `/public/collection/:id/app/config`
+     * (`collection.getAppsConfig()`), which now carries both; there's no need to
+     * separately call `appConfiguration.getConfig({ appId: 'appConfig' })` for
+     * public reads. Cached in-memory (and sessionStorage) for `ttl` so repeated
+     * calls across a page/session are cheap; pass `force` to bypass the cache
+     * after a mutation (e.g. after `entitlements-reconcile`).
+     *
+     * For admin-only data (`systemPrivate`), use
+     * `appConfiguration.getConfig({ collectionId, appId: 'appConfig', admin: true })`
+     * directly — this endpoint is public-only and never returns it.
+     *
+     * See docs/appConfig.md for the full contract.
+     *
+     * @example
+     * ```typescript
+     * const cfg = await appConfiguration.getAppConfig(collectionId);
+     * console.log(cfg.system?.features);
+     * ```
+     */
+    function getAppConfig(collectionId: string, options?: {
+        force?: boolean;
+    }): Promise<AppsConfigResponse>;
+    /**
+     * Check whether a feature flag is enabled for a collection, per
+     * `appConfig.system.features` — applying the `accountType` default (see
+     * `resolveFeature()`): enterprise accounts default every flag to on unless
+     * explicitly set to `false`. This is the standard way for subapps to gate
+     * features — it reads through the same cache as `getAppConfig`, so calling
+     * it repeatedly (e.g. once per component) does not re-fetch on every call.
+     *
+     * This is always async because the very first call for a collection has
+     * nothing to read yet. If you need a synchronous check (e.g. inside a
+     * render function), call this once during app init to warm the cache,
+     * then use `isFeatureEnabledSync()` afterwards.
+     *
+     * @example
+     * ```typescript
+     * if (await appConfiguration.isFeatureEnabled(collectionId, 'custom_domain')) {
+     *   enableCustomDomainUI();
+     * }
+     * ```
+     */
+    function isFeatureEnabled(collectionId: string, flag: string, options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Synchronous, cache-only check for a feature flag. Returns `undefined` if
+     * `getAppConfig()` / `isFeatureEnabled()` hasn't been called yet for this
+     * collection this page load (i.e. nothing to read without an await) — treat
+     * `undefined` as "not yet known", not as "disabled".
+     *
+     * @example
+     * ```typescript
+     * // Warm the cache once, e.g. in a top-level effect:
+     * useEffect(() => { appConfiguration.isFeatureEnabled(collectionId, 'custom_domain') }, [collectionId]);
+     *
+     * // Elsewhere, read synchronously without an await:
+     * const enabled = appConfiguration.isFeatureEnabledSync(collectionId, 'custom_domain');
+     * if (enabled === undefined) {
+     *   // not warmed yet — fall back to a loading state or the async version
+     * }
+     * ```
+     */
+    function isFeatureEnabledSync(collectionId: string, flag: string): boolean | undefined;
 }

package/dist/api/appConfiguration.js

@@ -11,6 +11,8 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 // src/api/appConfiguration.ts
 import { request, post, del } from "../http";
+import * as cache from "../cache";
+import { collection as collectionApi } from "./collection";
 function getWidgetsMap(config) {
     if (!config || typeof config !== 'object' || Array.isArray(config))
         return {};
@@ -508,4 +510,119 @@ export var appConfiguration;
         return request(path);
     }
     appConfiguration.getWidgets = getWidgets;
+    const APP_CONFIG_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+    function appConfigCacheKey(collectionId) {
+        // Same key IframeResponder uses for this endpoint — sharing the cache
+        // entry means whichever caller hits it first warms it for the other.
+        return `apps:${collectionId}`;
+    }
+    /**
+     * Resolve whether a feature flag is on, applying the `accountType` default:
+     * `enterprise` accounts default every flag to **on** unless `features[flag]`
+     * is explicitly `false`; `standard` accounts (or missing `accountType`)
+     * default every flag to **off** unless `features[flag]` is explicitly `true`.
+     * An explicit value always wins over the default either way.
+     *
+     * This is the same logic `isFeatureEnabled()` / `isFeatureEnabledSync()` use
+     * internally — call those instead in normal code. `system.features` and
+     * `accountType` are public data (no admin-only feature-check path exists),
+     * so there's no reason to fetch differently for an admin surface. This is
+     * exposed separately only for the rare case where you already have a
+     * `system` block in hand from somewhere other than `getAppConfig()` (e.g.
+     * server-rendered props) and want to resolve a flag from it directly.
+     *
+     * @example
+     * ```typescript
+     * const enabled = appConfiguration.resolveFeature(someSystemBlock, 'custom_domain');
+     * ```
+     */
+    function resolveFeature(system, flag) {
+        var _a;
+        const value = (_a = system === null || system === void 0 ? void 0 : system.features) === null || _a === void 0 ? void 0 : _a[flag];
+        if (value === true)
+            return true;
+        if (value === false)
+            return false;
+        return (system === null || system === void 0 ? void 0 : system.accountType) === 'enterprise';
+    }
+    appConfiguration.resolveFeature = resolveFeature;
+    /**
+     * Fetch the collection's app catalog + `appConfig` entitlements data in one
+     * call — installed modules (`apps`), resolved entitlements (`system.features`,
+     * `system.meters`, etc.), and item-handling settings. This is `/public/collection/:id/app/config`
+     * (`collection.getAppsConfig()`), which now carries both; there's no need to
+     * separately call `appConfiguration.getConfig({ appId: 'appConfig' })` for
+     * public reads. Cached in-memory (and sessionStorage) for `ttl` so repeated
+     * calls across a page/session are cheap; pass `force` to bypass the cache
+     * after a mutation (e.g. after `entitlements-reconcile`).
+     *
+     * For admin-only data (`systemPrivate`), use
+     * `appConfiguration.getConfig({ collectionId, appId: 'appConfig', admin: true })`
+     * directly — this endpoint is public-only and never returns it.
+     *
+     * See docs/appConfig.md for the full contract.
+     *
+     * @example
+     * ```typescript
+     * const cfg = await appConfiguration.getAppConfig(collectionId);
+     * console.log(cfg.system?.features);
+     * ```
+     */
+    async function getAppConfig(collectionId, options) {
+        const key = appConfigCacheKey(collectionId);
+        if (options === null || options === void 0 ? void 0 : options.force)
+            cache.invalidate(key);
+        return cache.getOrFetch(key, () => collectionApi.getAppsConfig(collectionId), { ttl: APP_CONFIG_CACHE_TTL, storage: 'session' });
+    }
+    appConfiguration.getAppConfig = getAppConfig;
+    /**
+     * Check whether a feature flag is enabled for a collection, per
+     * `appConfig.system.features` — applying the `accountType` default (see
+     * `resolveFeature()`): enterprise accounts default every flag to on unless
+     * explicitly set to `false`. This is the standard way for subapps to gate
+     * features — it reads through the same cache as `getAppConfig`, so calling
+     * it repeatedly (e.g. once per component) does not re-fetch on every call.
+     *
+     * This is always async because the very first call for a collection has
+     * nothing to read yet. If you need a synchronous check (e.g. inside a
+     * render function), call this once during app init to warm the cache,
+     * then use `isFeatureEnabledSync()` afterwards.
+     *
+     * @example
+     * ```typescript
+     * if (await appConfiguration.isFeatureEnabled(collectionId, 'custom_domain')) {
+     *   enableCustomDomainUI();
+     * }
+     * ```
+     */
+    async function isFeatureEnabled(collectionId, flag, options) {
+        const cfg = await getAppConfig(collectionId, options);
+        return resolveFeature(cfg === null || cfg === void 0 ? void 0 : cfg.system, flag);
+    }
+    appConfiguration.isFeatureEnabled = isFeatureEnabled;
+    /**
+     * Synchronous, cache-only check for a feature flag. Returns `undefined` if
+     * `getAppConfig()` / `isFeatureEnabled()` hasn't been called yet for this
+     * collection this page load (i.e. nothing to read without an await) — treat
+     * `undefined` as "not yet known", not as "disabled".
+     *
+     * @example
+     * ```typescript
+     * // Warm the cache once, e.g. in a top-level effect:
+     * useEffect(() => { appConfiguration.isFeatureEnabled(collectionId, 'custom_domain') }, [collectionId]);
+     *
+     * // Elsewhere, read synchronously without an await:
+     * const enabled = appConfiguration.isFeatureEnabledSync(collectionId, 'custom_domain');
+     * if (enabled === undefined) {
+     *   // not warmed yet — fall back to a loading state or the async version
+     * }
+     * ```
+     */
+    function isFeatureEnabledSync(collectionId, flag) {
+        const cfg = cache.peek(appConfigCacheKey(collectionId));
+        if (!cfg)
+            return undefined;
+        return resolveFeature(cfg.system, flag);
+    }
+    appConfiguration.isFeatureEnabledSync = isFeatureEnabledSync;
 })(appConfiguration || (appConfiguration = {}));

package/dist/api/collection.d.ts

@@ -101,9 +101,13 @@ export declare namespace collection {
      */
     function getSettings(collectionId: string, settingGroup: string, admin?: boolean): Promise<any>;
     /**
-     * Retrieve all configured app module definitions for a collection (public endpoint).
+     * Retrieve all configured app module definitions for a collection (public endpoint),
+     * plus the collection's `appConfig` entitlements data (`system.features`, `system.meters`,
+     * `entitledAppGroups`, `itemRecordMode`, etc.) in the same response. See docs/appConfig.md.
+     * Prefer `appConfiguration.getAppConfig()` / `isFeatureEnabled()` for entitlement reads —
+     * they call this endpoint under the hood and cache the result.
      * @param collectionId – Identifier of the collection
-     * @returns Promise resolving to an AppsConfigResponse containing all app configurations
+     * @returns Promise resolving to an AppsConfigResponse containing the app catalog and entitlements
      * @throws ErrorResponse if the request fails
      */
     function getAppsConfig(collectionId: string): Promise<AppsConfigResponse>;

package/dist/api/collection.js

@@ -148,9 +148,13 @@ export var collection;
     }
     collection.getSettings = getSettings;
     /**
-     * Retrieve all configured app module definitions for a collection (public endpoint).
+     * Retrieve all configured app module definitions for a collection (public endpoint),
+     * plus the collection's `appConfig` entitlements data (`system.features`, `system.meters`,
+     * `entitledAppGroups`, `itemRecordMode`, etc.) in the same response. See docs/appConfig.md.
+     * Prefer `appConfiguration.getAppConfig()` / `isFeatureEnabled()` for entitlement reads —
+     * they call this endpoint under the hood and cache the result.
      * @param collectionId – Identifier of the collection
-     * @returns Promise resolving to an AppsConfigResponse containing all app configurations
+     * @returns Promise resolving to an AppsConfigResponse containing the app catalog and entitlements
      * @throws ErrorResponse if the request fails
      */
     async function getAppsConfig(collectionId) {

package/dist/cache.d.ts

@@ -22,6 +22,25 @@ export interface CacheOptions {
  * ```
  */
 export declare function getOrFetch<T>(key: string, fetcher: () => Promise<T>, options?: CacheOptions): Promise<T>;
+/**
+ * Synchronously read a cached value without fetching. Returns `undefined` if
+ * the key was never cached, or if its TTL has expired.
+ *
+ * Every write also mirrors into the in-memory store regardless of its
+ * `storage` backend, so the default `storage: 'memory'` here finds entries
+ * cached via `getOrFetch(..., { storage: 'session' | 'local' })` too, as
+ * long as it's the same page load.
+ *
+ * @example
+ * ```typescript
+ * // After warming the cache once with getOrFetch(...):
+ * const cached = cache.peek<AppConfig>(`appConfig:${collectionId}:public`);
+ * if (cached) {
+ *   // render synchronously — no await needed
+ * }
+ * ```
+ */
+export declare function peek<T>(key: string, storage?: 'memory' | 'session' | 'local'): T | undefined;
 /**
  * Invalidate a cached key.
  */

package/dist/cache.js

@@ -59,6 +59,31 @@ export async function getOrFetch(key, fetcher, options = {}) {
     setToStorage(key, entry, storage);
     return value;
 }
+/**
+ * Synchronously read a cached value without fetching. Returns `undefined` if
+ * the key was never cached, or if its TTL has expired.
+ *
+ * Every write also mirrors into the in-memory store regardless of its
+ * `storage` backend, so the default `storage: 'memory'` here finds entries
+ * cached via `getOrFetch(..., { storage: 'session' | 'local' })` too, as
+ * long as it's the same page load.
+ *
+ * @example
+ * ```typescript
+ * // After warming the cache once with getOrFetch(...):
+ * const cached = cache.peek<AppConfig>(`appConfig:${collectionId}:public`);
+ * if (cached) {
+ *   // render synchronously — no await needed
+ * }
+ * ```
+ */
+export function peek(key, storage = 'memory') {
+    const cached = getFromStorage(key, storage);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.value;
+    }
+    return undefined;
+}
 /**
  * Invalidate a cached key.
  */

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.3  |  Generated: 2026-07-11T13:25:50.969Z
+Version: 1.15.5  |  Generated: 2026-07-18T14:07:37.915Z
 
 This is a concise summary of all available API functions and types.
 
@@ -42,6 +42,8 @@ For detailed guides on specific features:
 - **[Portal Back Button](portal-back-button.md)** - `parentPath` contract for hierarchy-aware "up" navigation; `useDeepLinkSync` integration
 - **[Contact Search](contact-search.md)** - Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
+- **[Product/Proof Data Scoping](proof-product-data-scoping.md)** - Canonical spec for `product.data`/`.admin` and `proof.data`/`.admin`/`.values` (owner/personal) buckets, read/write authority, and the `productFields`/`proofFields` collection-settings schemas
+- **[appConfig / Feature Flags](appConfig.md)** - `appConfig` settings contract, entitlements (`system.features`/`entitledAppGroups`/`meters`), and the `isFeatureEnabled()` / `isFeatureEnabledSync()` SDK helpers
 - **[Forms](forms.md)** - Platform-managed form definitions, submissions, and schema-driven React form UI
 - **[App Objects: Cases, Threads & Records](app-objects.md)** - Generic app-scoped building blocks for support cases, discussions, bookings, registrations, and more
 - **[App Records Pattern](app-records-pattern.md)** - Canonical pattern for storing per-product, per-facet, or rule-targeted app data
@@ -1375,6 +1377,81 @@ interface WidgetInstanceSummary {
 }
 ```
 
+**AppEntry** (interface)
+```typescript
+interface AppEntry {
+  id: string
+  uniqueName: string
+  customName?: string
+  active: boolean
+  all?: boolean
+  live?: boolean
+  faIcon?: string
+  versionChannel?: 'stable' | 'beta' | 'dev'
+  reason?: 'not_entitled'
+  [key: string]: unknown
+}
+```
+
+**MeterEntry** (interface)
+```typescript
+interface MeterEntry {
+  included: number
+  stripePriceId?: string
+  stripeMeterId?: string
+}
+```
+
+**AppliedOverridesSummary** (interface)
+```typescript
+interface AppliedOverridesSummary {
+  features?: string[]
+  meters?: string[]
+  entitledAppGroups?: string[]
+  addOnKeys?: string[]
+  apps?: string[]
+  accountType?: boolean
+  note?: string
+}
+```
+
+**SystemBlock** (interface)
+```typescript
+interface SystemBlock {
+  basePlanId?: string
+  addOnKeys?: string[]
+  apps?: string[]
+  * Explicit overrides only — an absent key is NOT "off". Resolve with
+  * `resolveFeature()` / `isFeatureEnabled()`, which apply the accountType
+  * default: `enterprise` defaults every flag to on unless explicitly
+  * `false` here; `standard` defaults every flag to off unless explicitly
+  * `true` here.
+  features?: Record<string, boolean>
+  meters?: Record<string, MeterEntry>
+  entitledAppGroups?: string[]
+  * Explicit account tier. `'enterprise'` flips the default for every
+  * feature flag to on (see `features`), not just an "unlimited baseline" —
+  * absence of a flag no longer means disabled for enterprise accounts.
+  accountType?: 'enterprise' | 'standard'
+  syncedAt?: string
+  syncedFromSubscriptionId?: string
+  appliedOverrides?: AppliedOverridesSummary
+}
+```
+
+**AppConfigSettings** (interface)
+```typescript
+interface AppConfigSettings {
+  id: 'appConfig'
+  apps: AppEntry[]
+  addOns?: string[]
+  requestedBasePlanId?: string
+  itemRecordMode?: 'registered' | 'owned' | null
+  virtualItemsEnabled?: boolean
+  system?: SystemBlock
+}
+```
+
 ### appManifest
 
 **AppBundle** (interface)
@@ -3661,13 +3738,6 @@ interface AppConfig {
 }
 ```
 
-**AppsConfigResponse** (interface)
-```typescript
-interface AppsConfigResponse {
-  apps: AppConfig[]
-}
-```
-
 **CollectionResponse** = `Collection`
 
 **CollectionCreateRequest** = `Omit<Collection, 'id' | 'shortId'>`
@@ -6946,6 +7016,37 @@ interface ProductQueryResponse {
 }
 ```
 
+**ScopedFieldOption** (interface)
+```typescript
+interface ScopedFieldOption {
+  value: string
+  label: string
+}
+```
+
+**ScopedFieldDef** (interface)
+```typescript
+interface ScopedFieldDef {
+  key: string
+  label: string
+  type: ScopedFieldType
+  required?: boolean
+  placeholder?: string
+  help?: string
+  options?: ScopedFieldOption[]
+  defaultValue?: JsonValue
+  showInTable?: boolean
+  showInDetail?: boolean
+}
+```
+
+**ProductFieldsConfig** (interface)
+```typescript
+interface ProductFieldsConfig {
+  fields: ProductFieldDef[]
+}
+```
+
 **JsonPrimitive** = `string | number | boolean | null`
 
 **JsonValue** = ``
@@ -6962,8 +7063,23 @@ interface ProductQueryResponse {
 
 **ProductUpdateRequest** = `Partial<Omit<ProductWriteInput, 'id'>>`
 
+**ScopedFieldType** = ``
+
+**ProductFieldScope** = `'public' | 'admin'`
+
+**ProductFieldDef** = `ScopedFieldDef & { scope?: ProductFieldScope }`
+
 ### proof
 
+**ProofValues** (interface)
+```typescript
+interface ProofValues {
+  [key: string]: JsonValue | Record<string, JsonValue> | Record<string, Record<string, JsonValue>> | undefined
+  owner?: Record<string, JsonValue>
+  personal?: Record<string, Record<string, JsonValue>>
+}
+```
+
 **Proof** (interface)
 ```typescript
 interface Proof {
@@ -6975,25 +7091,40 @@ interface Proof {
   userId: string
   claimable?: boolean
   virtual?: boolean
-  values: Record<string, any>
+  data?: Record<string, JsonValue>
+  admin?: Record<string, JsonValue>
+  values: ProofValues
 }
 ```
 
 **ProofCreateRequest** (interface)
 ```typescript
 interface ProofCreateRequest {
-  values: Record<string, any>
+  values: ProofValues
+  data?: Record<string, JsonValue>
+  admin?: Record<string, JsonValue>
   claimable?: boolean
   virtual?: boolean
 }
 ```
 
+**ProofFieldsConfig** (interface)
+```typescript
+interface ProofFieldsConfig {
+  fields: ProofFieldDef[]
+}
+```
+
 **ProofResponse** = `Proof`
 
 **ProofUpdateRequest** = `Partial<ProofCreateRequest>`
 
 **ProofClaimRequest** = `Record<string, any>`
 
+**ProofFieldScope** = `'public' | 'owner' | 'personal' | 'admin'`
+
+**ProofFieldDef** = `ScopedFieldDef & { scope?: ProofFieldScope }`
+
 ### qr
 
 **QrShortCodeLookupResponse** (interface)
@@ -8109,6 +8240,21 @@ Delete a keyed data item by ID within a scope. Requires admin authentication. ``
     options?: GetCollectionWidgetsOptions) → `Promise<CollectionWidgetsResponse>`
 Fetches ALL widget data (manifests + bundle files) for a collection in one call. Returns everything needed to render widgets with zero additional requests. This solves N+1 query problems by fetching manifests, JavaScript bundles, and CSS files in parallel on the server. ```typescript // Fetch all widget data for a collection const { apps } = await Api.AppConfiguration.getWidgets(collectionId); // Returns: [{ appId, manifestUrl, manifest, bundleSource, bundleCss }, ...] // Convert bundle source to dynamic imports for (const app of apps) { const blob = new Blob([app.bundleSource], { type: 'application/javascript' }); const blobUrl = URL.createObjectURL(blob); const widgetModule = await import(blobUrl); // Inject CSS if present if (app.bundleCss) { const styleTag = document.createElement('style'); styleTag.textContent = app.bundleCss; document.head.appendChild(styleTag); } } // Force refresh all widgets const { apps } = await Api.AppConfiguration.getWidgets(collectionId, { force: true }); ```
 
+**resolveFeature**(system: SystemBlock | undefined, flag: string) → `boolean`
+Resolve whether a feature flag is on, applying the `accountType` default: `enterprise` accounts default every flag to **on** unless `features[flag]` is explicitly `false`; `standard` accounts (or missing `accountType`) default every flag to **off** unless `features[flag]` is explicitly `true`. An explicit value always wins over the default either way. This is the same logic `isFeatureEnabled()` / `isFeatureEnabledSync()` use internally — call those instead in normal code. `system.features` and `accountType` are public data (no admin-only feature-check path exists), so there's no reason to fetch differently for an admin surface. This is exposed separately only for the rare case where you already have a `system` block in hand from somewhere other than `getAppConfig()` (e.g. server-rendered props) and want to resolve a flag from it directly. ```typescript const enabled = appConfiguration.resolveFeature(someSystemBlock, 'custom_domain'); ```
+
+**getAppConfig**(collectionId: string,
+    options?: { force?: boolean }) → `Promise<AppsConfigResponse>`
+Fetch the collection's app catalog + `appConfig` entitlements data in one call — installed modules (`apps`), resolved entitlements (`system.features`, `system.meters`, etc.), and item-handling settings. This is `/public/collection/:id/app/config` (`collection.getAppsConfig()`), which now carries both; there's no need to separately call `appConfiguration.getConfig({ appId: 'appConfig' })` for public reads. Cached in-memory (and sessionStorage) for `ttl` so repeated calls across a page/session are cheap; pass `force` to bypass the cache after a mutation (e.g. after `entitlements-reconcile`). For admin-only data (`systemPrivate`), use `appConfiguration.getConfig({ collectionId, appId: 'appConfig', admin: true })` directly — this endpoint is public-only and never returns it. See docs/appConfig.md for the full contract. ```typescript const cfg = await appConfiguration.getAppConfig(collectionId); console.log(cfg.system?.features); ```
+
+**isFeatureEnabled**(collectionId: string,
+    flag: string,
+    options?: { force?: boolean }) → `Promise<boolean>`
+Check whether a feature flag is enabled for a collection, per `appConfig.system.features` — applying the `accountType` default (see `resolveFeature()`): enterprise accounts default every flag to on unless explicitly set to `false`. This is the standard way for subapps to gate features — it reads through the same cache as `getAppConfig`, so calling it repeatedly (e.g. once per component) does not re-fetch on every call. This is always async because the very first call for a collection has nothing to read yet. If you need a synchronous check (e.g. inside a render function), call this once during app init to warm the cache, then use `isFeatureEnabledSync()` afterwards. ```typescript if (await appConfiguration.isFeatureEnabled(collectionId, 'custom_domain')) { enableCustomDomainUI(); } ```
+
+**isFeatureEnabledSync**(collectionId: string, flag: string) → `boolean | undefined`
+Synchronous, cache-only check for a feature flag. Returns `undefined` if `getAppConfig()` / `isFeatureEnabled()` hasn't been called yet for this collection this page load (i.e. nothing to read without an await) — treat `undefined` as "not yet known", not as "disabled". ```typescript // Warm the cache once, e.g. in a top-level effect: useEffect(() => { appConfiguration.isFeatureEnabled(collectionId, 'custom_domain') }, [collectionId]); // Elsewhere, read synchronously without an await: const enabled = appConfiguration.isFeatureEnabledSync(collectionId, 'custom_domain'); if (enabled === undefined) { // not warmed yet — fall back to a loading state or the async version } ```
+
 ### asset
 
 **upload**(options: UploadAssetOptions) → `Promise<Asset>`
@@ -8657,7 +8803,7 @@ Get the managed-certificate status for a collection's custom domain (admin only)
 Retrieve a specific settings group for a collection. Public reads return the public view of the settings group. If the stored payload contains a top-level `admin` object, that block is omitted from public responses and included when `admin === true`.
 
 **getAppsConfig**(collectionId: string) → `Promise<AppsConfigResponse>`
-Retrieve all configured app module definitions for a collection (public endpoint).
+Retrieve all configured app module definitions for a collection (public endpoint), plus the collection's `appConfig` entitlements data (`system.features`, `system.meters`, `entitledAppGroups`, `itemRecordMode`, etc.) in the same response. See docs/appConfig.md. Prefer `appConfiguration.getAppConfig()` / `isFeatureEnabled()` for entitlement reads — they call this endpoint under the hood and cache the result.
 
 **updateSettings**(collectionId: string, settingGroup: string, settings: any) → `Promise<any>`
 Update a specific settings group for a collection (admin endpoint). This writes through the admin endpoint, but root-level fields are still part of the public settings payload. Put confidential values under `settings.admin` if they should only be returned on admin reads.

package/dist/docs/app-data-storage.md

@@ -2,6 +2,8 @@
 
 The SmartLinks platform provides two distinct types of data storage for apps:
 
+> **Not what you're looking for?** This guide covers app-owned config/records scoped to a collection or product. For the core product/proof documents themselves — `product.data`/`.admin`, `proof.data`/`.admin`/`.values` (owner/personal) — see [proof-product-data-scoping.md](proof-product-data-scoping.md).
+
 ## Choose the Right Model First
 
 There are now two different families of flexible app data in SmartLinks, and they solve different problems: