@proveanything/smartlinks 2.0.6 → 2.0.10

package/dist/docs/widgets.md

@@ -14,7 +14,7 @@ Widgets are self-contained React components that:
 
 ```text
 ┌─────────────────────────────────────────────────────────────────┐
-│ Parent SmartLinks Portal (React 18)                             │
+│ Parent SmartLinks Portal (React 19)                             │
 │                                                                 │
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
 │  │ Competition  │  │ Music App    │  │ Warranty     │          │
@@ -53,53 +53,7 @@ Widgets are typically single-view components and don't need internal routing. If
 
 ### The `useAppContext()` Pattern
 
-To write widgets that work identically in both modes, use this abstraction pattern:
-
-```tsx
-// src/hooks/useAppContext.ts
-import { useContext, createContext, useMemo } from 'react';
-import { useSearchParams } from 'react-router-dom';
-
-export interface AppContextValue {
-  collectionId: string;
-  appId: string;
-  productId?: string;
-  proofId?: string;
-  pageId?: string;
-  lang?: string;
-  user?: { id: string; email: string; name?: string };
-  SL: typeof import('@proveanything/smartlinks');
-  onNavigate?: (request: any) => void;
-}
-
-export const AppContext = createContext<AppContextValue | null>(null);
-
-/**
- * Returns app context regardless of rendering mode.
- * - Direct component mode: reads from AppContext (props)
- * - Iframe mode: reads from URL search params
- */
-export function useAppContext(): AppContextValue {
-  const ctx = useContext(AppContext);
-  
-  // If context exists, we're in direct-component mode
-  if (ctx) return ctx;
-  
-  // Otherwise, we're in iframe mode — read from URL params
-  const [searchParams] = useSearchParams();
-  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
-
-  return useMemo(() => ({
-    collectionId: searchParams.get('collectionId') ?? '',
-    appId: searchParams.get('appId') ?? '',
-    productId: searchParams.get('productId') ?? undefined,
-    proofId: searchParams.get('proofId') ?? undefined,
-    pageId: searchParams.get('pageId') ?? undefined,
-    lang: searchParams.get('lang') ?? undefined,
-    SL,
-  }), [searchParams, SL]);
-}
-```
+Widgets read their context through the shared **`useAppContext()`** hook so the same code works in both direct-component and iframe modes. The hook and `AppContext` provider are defined once — see **[building-react-components.md](building-react-components.md#the-useappcontext-pattern)** for the full implementation (don't re-define it per app).
 
 **Usage in your widget:**
 
@@ -344,7 +298,7 @@ Declare support in `app.manifest.json`:
     "files": {
       "js": {
         "umd": "dist/widgets.umd.js",
-        "esm": "dist/widgets.es.js"
+        "esm": "dist/widgets.esm.js"
       },
       "css": null
     },
@@ -511,7 +465,7 @@ export { MyWidget } from './MyWidget';
 // Update the manifest
 export const WIDGET_MANIFEST = {
   version: '1.0.0',
-  reactVersion: '18.x',
+  reactVersion: '19.x',
   widgets: [
     // ... existing widgets
     {
@@ -570,7 +524,7 @@ The project includes a separate Vite config for building widgets:
 # Build widgets only
 vite build --config vite.config.widget.ts
 
-# Output: dist/widgets.es.js
+# Output: dist/widgets.esm.js
 ```
 
 ### Build Configuration
@@ -582,23 +536,11 @@ The widget build:
 - Minifies with esbuild for production
 - Outputs to `/dist` alongside the main app (not a separate folder)
 
-### Externalized Dependencies (Peer Dependencies)
-
-The widget bundle does **not** include these libraries—the parent app must provide them:
+### Externalized dependencies
 
-| Package | Why Externalized |
-|---------|------------------|
-| `react`, `react-dom` | Parent's React context |
-| `@proveanything/smartlinks` | Passed via props as `SL` |
-| `@proveanything/smartlinks-auth-ui` | Auth UI components (also available globally as `window.SmartlinksAuthUI`) |
-| `tailwind-merge` | Utility for merging Tailwind classes |
-| `clsx` | Utility for conditional class names |
-| `class-variance-authority` | Utility for component variants |
+The widget bundle does **not** include the host's shared libraries (React, the SDK, Radix, LiquidJS, …) — it **externalizes** them and resolves them from the host at runtime, so the bundle stays tiny and there's exactly one shared instance.
 
-These are standard packages that any modern React + Tailwind app will have. Externalizing them:
-1. Reduces bundle size significantly
-2. Removes JSDoc comments that inflate the bundle
-3. Ensures consistent behavior with parent's versions
+**The canonical, versioned list is the shared-dependency contract — don't hand-maintain your own here.** Import it from the SDK (`SHARED_DEPENDENCY_SPECIFIERS`) for your build's `external` list, and see **[host-dependency-contract.md](host-dependency-contract.md)** for the full table, the Vite `external`/`globals` config, and the *never bundle your own React* rule. `@proveanything/smartlinks-auth-ui` is externalized too (host global `window.SmartlinksAuthUI`) — do not ship a second copy.
 
 ### Enabling Widget Builds
 
@@ -626,7 +568,7 @@ import * as SL from '@proveanything/smartlinks';
 
 // Dynamic import from app's CDN
 const CompetitionWidget = lazy(() => 
-  import('https://competition-app.example.com/widgets.es.js')
+  import('https://competition-app.example.com/widgets.esm.js')
     .then(m => ({ default: m.CompetitionWidget }))
 );
 
@@ -670,7 +612,7 @@ import { WidgetWrapper, CompetitionWidget } from 'competition-app/widgets';
 import { WIDGET_MANIFEST } from 'competition-app/widgets';
 
 // Verify React version compatibility
-if (!WIDGET_MANIFEST.reactVersion.startsWith('18')) {
+if (!WIDGET_MANIFEST.reactVersion.startsWith('19')) {
   console.warn('Widget React version mismatch');
 }
 
@@ -741,7 +683,7 @@ Each app exports a `WIDGET_MANIFEST` for discovery:
 ```typescript
 export const WIDGET_MANIFEST = {
   version: '1.0.0',        // Widget bundle version
-  reactVersion: '18.x',    // Required React version
+  reactVersion: '19.x',    // Required React version
   widgets: [
     {
       name: 'ExampleWidget',

package/dist/http.d.ts

@@ -168,22 +168,38 @@ export declare function configureSdkCache(options: {
     serveStaleOnOffline?: boolean;
     clearOnPageLoad?: boolean;
 }): void;
+/** Options for {@link invalidateCache}. */
+export interface InvalidateCacheOptions {
+    /**
+     * Match the path **exactly** (ignoring any query string) instead of the default
+     * substring match. Use this to clear one resource without wiping everything
+     * nested under it — e.g. `invalidateCache('/collection/abc', { exact: true })`
+     * drops only that entry, not `/collection/abc/settings|widgets|products|proofs`.
+     */
+    exact?: boolean;
+}
 /**
  * Manually invalidate entries in the SDK's GET cache.
  *
- * @param urlPattern - Optional substring match. Every cache entry whose key
- *   *contains* this string is removed. Omit (or pass `undefined`) to wipe the
- *   entire cache.
+ * Note: the GET cache is **in-memory, per page load** (with an optional L2
+ * IndexedDB layer when persistence is enabled) — it does not persist across
+ * reloads unless you opt into persistence, so it rarely needs disabling "for
+ * correctness".
+ *
+ * @param urlPattern - Substring match by default (every entry whose key
+ *   *contains* this string is removed). With `{ exact: true }`, matches the path
+ *   precisely. Omit to wipe the entire cache.
+ * @param options - See {@link InvalidateCacheOptions}.
  *
  * @example
  * ```ts
- * invalidateCache()                     // clear everything
- * invalidateCache('/collection/abc123') // one specific collection
- * invalidateCache('/product/')          // all legacy singular product responses
- * invalidateCache('/products/')         // all canonical plural product responses
+ * invalidateCache()                                  // clear everything
+ * invalidateCache('/collection/abc123')              // that collection AND everything under it
+ * invalidateCache('/collection/abc123', { exact: true }) // ONLY that collection entry
+ * invalidateCache('/products/')                      // all canonical plural product responses
  * ```
  */
-export declare function invalidateCache(urlPattern?: string): void;
+export declare function invalidateCache(urlPattern?: string, options?: InvalidateCacheOptions): void;
 /**
  * Upload a FormData payload via proxy with progress events using chunked postMessage.
  * Parent is expected to implement the counterpart protocol.

package/dist/http.js

@@ -25,8 +25,8 @@ var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _ar
     function reject(value) { resume("throw", value); }
     function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
 };
-import { SmartlinksApiError, SmartlinksOfflineError } from "./types/error";
-import { idbGet, idbSet, idbClear } from './persistentCache';
+import { SmartlinksApiError, SmartlinksOfflineError } from "./types/error.js";
+import { idbGet, idbSet, idbClear } from './persistentCache.js';
 let baseURL = null;
 let apiKey = undefined;
 let bearerToken = undefined;
@@ -424,7 +424,7 @@ function normalizeErrorResponse(responseBody, statusCode) {
  * @property {string} [options.bearerToken] - (Optional) Bearer token for AUTHORIZATION header
  * @property {boolean} [options.proxyMode] - (Optional) Tells the API that it is running in an iframe via parent proxy
  */
-import { iframe } from './iframe';
+import { iframe } from './iframe.js';
 export function initializeApi(options) {
     var _a;
     // Normalize baseURL by removing trailing slashes.
@@ -660,29 +660,47 @@ export function configureSdkCache(options) {
 /**
  * Manually invalidate entries in the SDK's GET cache.
  *
- * @param urlPattern - Optional substring match. Every cache entry whose key
- *   *contains* this string is removed. Omit (or pass `undefined`) to wipe the
- *   entire cache.
+ * Note: the GET cache is **in-memory, per page load** (with an optional L2
+ * IndexedDB layer when persistence is enabled) — it does not persist across
+ * reloads unless you opt into persistence, so it rarely needs disabling "for
+ * correctness".
+ *
+ * @param urlPattern - Substring match by default (every entry whose key
+ *   *contains* this string is removed). With `{ exact: true }`, matches the path
+ *   precisely. Omit to wipe the entire cache.
+ * @param options - See {@link InvalidateCacheOptions}.
  *
  * @example
  * ```ts
- * invalidateCache()                     // clear everything
- * invalidateCache('/collection/abc123') // one specific collection
- * invalidateCache('/product/')          // all legacy singular product responses
- * invalidateCache('/products/')         // all canonical plural product responses
+ * invalidateCache()                                  // clear everything
+ * invalidateCache('/collection/abc123')              // that collection AND everything under it
+ * invalidateCache('/collection/abc123', { exact: true }) // ONLY that collection entry
+ * invalidateCache('/products/')                      // all canonical plural product responses
  * ```
  */
-export function invalidateCache(urlPattern) {
+export function invalidateCache(urlPattern, options) {
     if (!urlPattern) {
         clearHttpCache('invalidateCache(all)');
         if (cachePersistence !== 'none')
             idbClear().catch(() => { });
         return;
     }
-    for (const key of httpCache.keys()) {
-        if (key.includes(urlPattern))
-            httpCache.delete(key);
+    if (options === null || options === void 0 ? void 0 : options.exact) {
+        const exactKey = buildCacheKey(urlPattern);
+        for (const key of httpCache.keys()) {
+            // Compare the path portion (drop query) so exact clears query variants of
+            // the same path but never sub-resources beneath it.
+            if (key.split('?')[0] === exactKey)
+                httpCache.delete(key);
+        }
+    }
+    else {
+        for (const key of httpCache.keys()) {
+            if (key.includes(urlPattern))
+                httpCache.delete(key);
+        }
     }
+    // L2 (IndexedDB) sweep remains substring-based; the exact win is the in-memory L1.
     if (cachePersistence !== 'none')
         idbClear(urlPattern).catch(() => { });
 }

package/dist/iframe.d.ts

@@ -1,5 +1,5 @@
-export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder';
-export type { IframeResponderOptions, CachedData, CollectionApp, RouteChangeMessage, SmartlinksIframeMessage, ProxyRequest, CustomProxyRequest, UploadStartMessage, UploadChunkMessage, UploadEndMessage, } from './types/iframeResponder';
+export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder.js';
+export type { IframeResponderOptions, CachedData, CollectionApp, RouteChangeMessage, SmartlinksIframeMessage, ProxyRequest, CustomProxyRequest, UploadStartMessage, UploadChunkMessage, UploadEndMessage, } from './types/iframeResponder.js';
 export declare namespace iframe {
     interface IframeResizeOptions {
         /** Minimum ms between height postMessages (default 100). */

package/dist/iframe.js

@@ -3,7 +3,7 @@
 // These helpers are optional and safe in non-browser / Node environments.
 // They build on the existing proxyMode infrastructure but can also be used standalone.
 // Re-export IframeResponder for parent-side iframe communication
-export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder';
+export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder.js';
 export var iframe;
 (function (iframe) {
     let autoResizeTimer;

package/dist/iframeResponder.d.ts

@@ -1,4 +1,4 @@
-import type { IframeResponderOptions, CachedData } from './types/iframeResponder';
+import type { IframeResponderOptions, CachedData } from './types/iframeResponder.js';
 /**
  * Parent-side iframe responder for SmartLinks microapp embedding.
  *
@@ -30,6 +30,12 @@ export declare class IframeResponder {
     private iframe;
     private options;
     private cache;
+    /**
+     * Timestamp of the last anonymous (`401`) `/account` result, so a burst of
+     * "am I logged in?" checks on one page load doesn't re-hit the API 3–4 times.
+     * Only used while `cache.user` is unset; cleared the moment a login lands.
+     */
+    private lastAnonAccountAt;
     private uploads;
     private activeStreams;
     private isInitialLoad;

package/dist/iframeResponder.js

@@ -1,9 +1,9 @@
 // =============================================================================
 // IframeResponder - Parent-side iframe communication handler
 // =============================================================================
-import * as cache from './cache';
-import { collection } from './api/collection';
-import { getBaseURL } from './http';
+import * as cache from './cache.js';
+import { collection } from './api/collection.js';
+import { getBaseURL, hasAuthCredentials } from './http.js';
 /**
  * Parent-side iframe responder for SmartLinks microapp embedding.
  *
@@ -34,6 +34,12 @@ import { getBaseURL } from './http';
 export class IframeResponder {
     constructor(options) {
         this.iframe = null;
+        /**
+         * Timestamp of the last anonymous (`401`) `/account` result, so a burst of
+         * "am I logged in?" checks on one page load doesn't re-hit the API 3–4 times.
+         * Only used while `cache.user` is unset; cleared the moment a login lands.
+         */
+        this.lastAnonAccountAt = 0;
         this.uploads = new Map();
         this.activeStreams = new Map();
         this.isInitialLoad = true;
@@ -346,8 +352,10 @@ export class IframeResponder {
                     // TODO: Validate token using SDK auth utilities when available
                     // await auth.verifyToken(token);
                     await this.options.onAuthLogin(token, user, accountData);
-                    // Update cache with new user
+                    // Update cache with new user; drop any stale "anonymous" account marker
+                    // so the next check reflects the fresh login immediately.
                     this.cache.user = user;
+                    this.lastAnonAccountAt = 0;
                     this.sendResponse(event, {
                         type: 'smartlinks:authkit:login-acknowledged',
                         messageId,
@@ -414,6 +422,35 @@ export class IframeResponder {
                     return;
                 }
             }
+            // "Am I logged in?" (GET /account) with no logged-in user cached. The positive
+            // path above already served logged-in users (cache.user set).
+            if (proxyData.method === 'GET' && path.includes('/account') && !this.cache.user) {
+                const notAuthenticated = () => {
+                    response.statusCode = 401;
+                    response.error = 'Not authenticated';
+                    response.errorBody = { account: null, errorCode: 'NOT_AUTHENTICATED' };
+                    this.sendResponse(event, response);
+                };
+                // Pre-emptive gate: will this request carry ANY credential the server could
+                // validate? The portal authenticates by bearer token (not cookie), and the
+                // proxy fetch forwards no cookie, so if neither the parent SDK nor the
+                // forwarded headers carry a token, the call is provably pointless — answer
+                // "not authenticated" locally, zero network calls.
+                const headers = (proxyData.headers || {});
+                const hasHeaderAuth = Object.keys(headers).some((k) => k.toLowerCase() === 'authorization' && !!headers[k]);
+                if (!hasAuthCredentials() && !hasHeaderAuth) {
+                    notAuthenticated();
+                    return;
+                }
+                // A credential IS present but no user is cached (e.g. an expired token):
+                // the first check goes to the network, then its 401 is remembered briefly
+                // so repeat checks in the same page load don't re-hit the API.
+                const ANON_ACCOUNT_TTL_MS = 30000;
+                if (this.lastAnonAccountAt && Date.now() - this.lastAnonAccountAt < ANON_ACCOUNT_TTL_MS) {
+                    notAuthenticated();
+                    return;
+                }
+            }
             // Forward to actual API using SDK's configured baseURL
             const baseUrl = getBaseURL();
             if (!baseUrl) {
@@ -434,6 +471,10 @@ export class IframeResponder {
                 response.error = (responseData === null || responseData === void 0 ? void 0 : responseData.message) || (responseData === null || responseData === void 0 ? void 0 : responseData.errorText) || `Request failed with status ${fetchResponse.status}`;
                 response.statusCode = fetchResponse.status;
                 response.errorBody = responseData;
+                // Remember an anonymous /account result so repeat checks skip the network.
+                if (fetchResponse.status === 401 && path.includes('/account') && !this.cache.user) {
+                    this.lastAnonAccountAt = Date.now();
+                }
             }
             else {
                 response.data = responseData;

package/dist/index.d.ts

@@ -1,29 +1,32 @@
-export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, invalidateCache, getHttpCacheDiagnostics, resetHttpCacheDiagnostics, request, post, put, patch, del, sendCustomProxyMessage, getApiHeaders, getBaseURL, isProxyEnabled, setBearerToken, getBearerToken, setGrantToken, getGrantToken } from "./http";
-export * from "./api";
-export * from "./types";
-export { iframe } from "./iframe";
-export * as cache from './cache';
-export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder';
-export * as utils from './utils';
-export type { PortalPathParams, Gs1DigitalLinkParams, ConditionParams, ConditionDebugOptions, ConditionDebugLogger, ConditionSet, Condition, UserInfo, ProductInfo, ProofInfo, CollectionInfo, } from './utils';
-export type { LoginResponse, VerifyTokenResponse, AccountInfoResponse, AuthLocation, } from "./api/auth";
-export type { UserAccountRegistrationRequest, } from "./types/auth";
-export type { CommunicationEvent, CommsQueryByUser, CommsRecipientIdsQuery, CommsRecipientsWithoutActionQuery, CommsRecipientsWithActionQuery, RecipientId, RecipientWithOutcome, LogCommunicationEventBody, LogBulkCommunicationEventsBody, AppendResult, AppendBulkResult, CommsSettings, TopicConfig, CommsSettingsGetResponse, CommsSettingsPatchBody, CommsPublicTopicsResponse, UnsubscribeQuery, UnsubscribeResponse, CommsConsentUpsertRequest, CommsPreferencesUpsertRequest, CommsSubscribeRequest, CommsSubscribeResponse, CommsSubscriptionCheckQuery, CommsSubscriptionCheckResponse, CommsListMethodsQuery, CommsListMethodsResponse, RegisterEmailMethodRequest, RegisterSmsMethodRequest, RegisterMethodResponse, SubscriptionsResolveRequest, SubscriptionsResolveResponse, } from "./types/comms";
-export type { BatchResponse, BatchCreateRequest, BatchUpdateRequest, } from "./types/batch";
-export type { Lot, LotStatus, LotSelector, LotPayload, LotCreateInput, LotUpdateInput, ListLotsParams, ListLotsResponse, LotMemberDiff, ResolveLotResponse, LotProductSummary, ListLotProductsResponse, LotResolutionResult, } from "./types/lots";
-export type { VariantResponse, VariantCreateRequest, VariantUpdateRequest, } from "./types/variant";
-export type { BroadcastSendRequest } from "./types/broadcasts";
-export type { AppConfigOptions } from "./api/appConfiguration";
-export type { AdditionalGtin, ISODateString, JsonPrimitive, JsonValue, ProductCreateRequest, ProductClaimCreateInput, ProductClaimCreateRequestBody, ProductClaimLookupInput, ProductFacetMap, ProductFacetValue, ProductImageUrlInput, ProductKey, ProductQueryRequest, ProductQueryResponse, ProductUpdateRequest, Product, ProductWriteInput, PublicProduct, } from "./types/product";
-export type { TranslationLookupMode, TranslationContentType, TranslationQuality, TranslationItemStatus, TranslationContextValue, TranslationContext, TranslationLookupRequestBase, TranslationLookupSingleRequest, TranslationLookupBatchRequest, TranslationLookupRequest, TranslationLookupItem, TranslationLookupResponse, ResolvedTranslationItem, ResolvedTranslationResponse, TranslationHashOptions, TranslationResolveOptions, TranslationRecord, TranslationListParams, TranslationListResponse, TranslationUpdateRequest, } from "./types/translations";
-export type { FacetBucket, FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetNamespaceListResponse, FacetQueryRequest, FacetQueryResponse, FacetValue, FacetValueDefinition, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams, } from "./types/facets";
-export type { Collection, CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, DomainTarget, HubAvailabilityResponse, } from "./types/collection";
-export type { Proof, ProofResponse, ProofWrite, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, GrantScope, GrantAudience, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, ProofTransfer, ProofTransferType, ProofTransferState, TransferProofOptions, TransferProofResult, } from "./types/proof";
-export type { QrShortCodeLookupResponse, } from "./types/qr";
-export type { ReverseTagLookupParams, ReverseTagLookupResponse, } from "./types/tags";
+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 * from "./api/index.js";
+export * from "./types/index.js";
+export { iframe } from "./iframe.js";
+export type { InvalidateCacheOptions } from "./http.js";
+export * as cache from './cache.js';
+export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder.js';
+export * as utils from './utils/index.js';
+export { SHARED_DEPENDENCY_CONTRACT_VERSION, SHARED_DEPENDENCIES, SHARED_DEPENDENCY_SPECIFIERS, importMapPathFor, getHostSharedDependencies, } from './shared-dependencies.js';
+export type { SharedDependency, HostSharedDependencies } from './shared-dependencies.js';
+export type { PortalPathParams, Gs1DigitalLinkParams, ConditionParams, ConditionDebugOptions, ConditionDebugLogger, ConditionSet, Condition, UserInfo, ProductInfo, ProofInfo, CollectionInfo, } from './utils/index.js';
+export type { LoginResponse, VerifyTokenResponse, AccountInfoResponse, AuthLocation, } from "./api/auth.js";
+export type { UserAccountRegistrationRequest, } from "./types/auth.js";
+export type { CommunicationEvent, CommsQueryByUser, CommsRecipientIdsQuery, CommsRecipientsWithoutActionQuery, CommsRecipientsWithActionQuery, RecipientId, RecipientWithOutcome, LogCommunicationEventBody, LogBulkCommunicationEventsBody, AppendResult, AppendBulkResult, CommsSettings, TopicConfig, CommsSettingsGetResponse, CommsSettingsPatchBody, CommsPublicTopicsResponse, UnsubscribeQuery, UnsubscribeResponse, CommsConsentUpsertRequest, CommsPreferencesUpsertRequest, CommsSubscribeRequest, CommsSubscribeResponse, CommsSubscriptionCheckQuery, CommsSubscriptionCheckResponse, CommsListMethodsQuery, CommsListMethodsResponse, RegisterEmailMethodRequest, RegisterSmsMethodRequest, RegisterMethodResponse, SubscriptionsResolveRequest, SubscriptionsResolveResponse, } from "./types/comms.js";
+export type { BatchResponse, BatchCreateRequest, BatchUpdateRequest, } from "./types/batch.js";
+export type { Lot, LotStatus, LotSelector, LotPayload, LotCreateInput, LotUpdateInput, ListLotsParams, ListLotsResponse, LotMemberDiff, ResolveLotResponse, LotProductSummary, ListLotProductsResponse, LotResolutionResult, } from "./types/lots.js";
+export type { VariantResponse, VariantCreateRequest, VariantUpdateRequest, } from "./types/variant.js";
+export type { BroadcastSendRequest } from "./types/broadcasts.js";
+export type { AppConfigOptions } from "./api/appConfiguration.js";
+export type { AdditionalGtin, ISODateString, JsonPrimitive, JsonValue, ProductCreateRequest, ProductClaimCreateInput, ProductClaimCreateRequestBody, ProductClaimLookupInput, ProductFacetMap, ProductFacetValue, ProductImageUrlInput, ProductKey, ProductQueryRequest, ProductQueryResponse, ProductUpdateRequest, Product, ProductWriteInput, PublicProduct, } from "./types/product.js";
+export type { TranslationLookupMode, TranslationContentType, TranslationQuality, TranslationItemStatus, TranslationContextValue, TranslationContext, TranslationLookupRequestBase, TranslationLookupSingleRequest, TranslationLookupBatchRequest, TranslationLookupRequest, TranslationLookupItem, TranslationLookupResponse, ResolvedTranslationItem, ResolvedTranslationResponse, TranslationHashOptions, TranslationResolveOptions, TranslationRecord, TranslationListParams, TranslationListResponse, TranslationUpdateRequest, } from "./types/translations.js";
+export type { FacetBucket, FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetNamespaceListResponse, FacetQueryRequest, FacetQueryResponse, FacetValue, FacetValueDefinition, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams, } from "./types/facets.js";
+export type { Collection, CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, DomainTarget, HubAvailabilityResponse, } from "./types/collection.js";
+export type { Proof, ProofResponse, ProofWrite, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, GrantScope, GrantAudience, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, ProofTransfer, ProofTransferType, ProofTransferState, TransferProofOptions, TransferProofResult, } from "./types/proof.js";
+export type { QrShortCodeLookupResponse, } from "./types/qr.js";
+export type { ReverseTagLookupParams, ReverseTagLookupResponse, } from "./types/tags.js";
 export type { AdminMobileCapability, ActionableCapability, AdminMobileHostId, AdminMobileEvent, AdminMobileEventCallback, AdminMobileEventSubscriber, ScannerEventSubscriber, // @deprecated — use AdminMobileEventCallback
 AdminMobileHostContext, AdminMobileComponentManifest, AdminMobileBundleManifest, MobileAdminComponentManifest, // @deprecated — use AdminMobileComponentManifest
-MobileAdminBundleManifest, } from './mobile-admin/types';
-export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors';
-export type { NativeCapability, NativeFacade, ShareFacade, ClipboardFacade, HapticImpactStyle, HapticNotificationStyle, HapticsFacade, NetworkStatus, NetworkFacade, DeviceInfo, DeviceFacade, StorageFacade, QrScanOptions, QrFacade, AuthFacade, NfcReadResult, NfcFacade, RfidScanOptions, RfidFacade, EventsFacade, WebSourceMode, WebSourceConfig, WebSourceFacade, } from './native/types';
-export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, RefreshResponse, LogoutResponse, RefreshErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, AuthKitConfigInput, AuthKitSecurityConfig, AuthKitPasswordPolicy, AuthKitSessionPolicy, AuthKitLockoutPolicy, PasswordPolicyErrorCode, LoginSecurityErrorCode, } from './types/authKit';
+MobileAdminBundleManifest, } from './mobile-admin/types.js';
+export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors.js';
+export type { NativeCapability, NativeFacade, ShareFacade, ClipboardFacade, HapticImpactStyle, HapticNotificationStyle, HapticsFacade, NetworkStatus, NetworkFacade, DeviceInfo, DeviceFacade, StorageFacade, QrScanOptions, QrFacade, AuthFacade, NfcReadResult, NfcFacade, RfidScanOptions, RfidFacade, EventsFacade, WebSourceMode, WebSourceConfig, WebSourceFacade, } from './native/types.js';
+export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, RefreshResponse, LogoutResponse, RefreshErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, AuthKitConfigInput, AuthKitSecurityConfig, AuthKitPasswordPolicy, AuthKitSessionPolicy, AuthKitLockoutPolicy, PasswordPolicyErrorCode, LoginSecurityErrorCode, } from './types/authKit.js';

package/dist/index.js

@@ -1,14 +1,16 @@
 // 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";
-export * from "./api";
-export * from "./types";
+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 * from "./api/index.js";
+export * from "./types/index.js";
 // Iframe namespace
-export { iframe } from "./iframe";
-import * as cache_1 from './cache';
+export { iframe } from "./iframe.js";
+import * as cache_1 from './cache.js';
 export { cache_1 as cache };
 // IframeResponder (also exported via iframe namespace)
-export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder';
-import * as utils_1 from './utils';
+export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder.js';
+import * as utils_1 from './utils/index.js';
 export { utils_1 as utils };
-export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors';
+// Shared dependency contract (host↔app) — one source of truth for externalized deps
+export { SHARED_DEPENDENCY_CONTRACT_VERSION, SHARED_DEPENDENCIES, SHARED_DEPENDENCY_SPECIFIERS, importMapPathFor, getHostSharedDependencies, } from './shared-dependencies.js';
+export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors.js';

package/dist/mobile-admin/errors.d.ts

@@ -5,7 +5,7 @@
  * All three classes call `Object.setPrototypeOf(this, new.target.prototype)` so
  * `instanceof` works correctly when transpiled to ES5.
  */
-import type { ActionableCapability, AdminMobileHostId } from './types';
+import type { ActionableCapability, AdminMobileHostId } from './types.js';
 /**
  * Thrown when a container requests a hardware action that the current host
  * does not support (e.g. calling `requestNfcTap` on a `'pwa'` host).

package/dist/mobile-admin/types.d.ts

@@ -1,4 +1,4 @@
-import type { NativeFacade } from '../native/types';
+import type { NativeFacade } from '../native/types.js';
 /**
  * Hardware/software capability tokens a mobile admin host may advertise.
  * Passed to `AdminMobileHostContext.capabilities` and to
@@ -79,7 +79,7 @@ export interface AdminMobileHostContext {
      * calls — never `import * as SL from '@proveanything/smartlinks'` inside a
      * container, as that would create a second SDK instance.
      */
-    SL: typeof import('../index');
+    SL: typeof import('../index.js');
     /** Capabilities advertised by this host instance. */
     capabilities: AdminMobileCapability[];
     /**

package/dist/openapi.yaml

@@ -17471,6 +17471,18 @@ components:
           type: string
         appId:
           type: string
+        moduleFormat:
+          type: string
+          enum:
+            - umd
+            - esm
+            - dual
+        sharedDependencies:
+          type: string
+        globals:
+          type: object
+          additionalProperties:
+            type: string
         seo:
           type: object
           additionalProperties: true

package/dist/shared-dependencies.d.ts

@@ -0,0 +1,37 @@
+/** Current contract revision. Bumped when the entry list or host versions change. */
+export declare const SHARED_DEPENDENCY_CONTRACT_VERSION: "v5";
+export interface SharedDependency {
+    /** Bare import specifier the app writes, e.g. `react-dom/client`. */
+    specifier: string;
+    /** Window global the host exposes for the UMD (legacy) resolution path. */
+    globalName: string;
+    /** Minimum version whose API the host guarantees — build against `>=` this, `<=` host. */
+    minVersion: string;
+    /** Portal-served ESM shim path this specifier maps to in the import map. */
+    importMapPath: string;
+}
+/**
+ * Canonical import-map path for a specifier: drop the leading `@` scope marker and
+ * turn every `/` into `-`.
+ *   'react-dom/client'      -> '/sl-shared/v5/react-dom-client.js'
+ *   '@radix-ui/react-slot'  -> '/sl-shared/v5/radix-ui-react-slot.js'
+ * Hosts MUST serve shims at these paths so the map the SDK advertises resolves.
+ */
+export declare function importMapPathFor(specifier: string, version?: string): string;
+/** The full shared-dependency contract for {@link SHARED_DEPENDENCY_CONTRACT_VERSION}. */
+export declare const SHARED_DEPENDENCIES: readonly SharedDependency[];
+/** Just the bare specifiers — handy for a bundler `external` list. */
+export declare const SHARED_DEPENDENCY_SPECIFIERS: readonly string[];
+/** What a host advertises at runtime so apps can detect the live contract. */
+export interface HostSharedDependencies {
+    version: string;
+    specifiers: string[];
+}
+/**
+ * Read the shared-dependency contract the current host advertises at runtime
+ * (via `window.__SMARTLINKS_SHARED__`). Returns `null` when there is no host
+ * marker — e.g. an older portal, or the bundle running outside a portal — so an
+ * app can degrade gracefully or fail with an actionable message instead of a
+ * bare-specifier resolution crash.
+ */
+export declare function getHostSharedDependencies(): HostSharedDependencies | null;