@amplifyup/sdk 0.1.21 → 0.1.23

package/README.md

@@ -1,6 +1,8 @@
 # @amplifyup/sdk
 
-Official JavaScript SDK for [AmplifyUp](https://amplifyup.ai) — event tracking, page layouts, personalization, and Composer preview on your site.
+Official JavaScript SDK for [AmplifyUp](https://amplifyup.ai) — event tracking, Edge-resolved page layouts, personalization, and Composer preview on your site.
+
+**Full guide:** [docs/sdk-site-setup.md](../../docs/sdk-site-setup.md)
 
 ## Install
 
@@ -8,11 +10,11 @@ Official JavaScript SDK for [AmplifyUp](https://amplifyup.ai) — event tracking
 npm install @amplifyup/sdk
 ```
 
-## Quick start
+## Quick start (production)
 
-### React / Next.js
+Production is the default. You only need a **tracking ID** from the AmplifyUp dashboard.
 
-Wrap your app with the provider and pass your site **tracking ID** from the AmplifyUp dashboard:
+### 1. Provider
 
 ```tsx
 import { AmplifyUpProvider } from '@amplifyup/sdk/react';
@@ -26,61 +28,86 @@ export default function RootLayout({ children }) {
 }
 ```
 
-### Track events
+### 2. Page content
 
-```typescript
-import { init, page, track, identify } from '@amplifyup/sdk';
+```tsx
+import { AmplifyPageContent, ComponentContextProvider } from '@amplifyup/sdk/react';
+import { Hero } from '@/components/Hero';
 
-await init({ trackingId: 'your-tracking-id' });
+const registry = { Hero };
 
-page('/home');
+function renderComponent(componentId, props, slots, context) {
+  const Component = registry[componentId];
+  if (!Component) return null;
+  return (
+    <ComponentContextProvider
+      props={props}
+      slots={slots}
+      layoutNodeId={context?.layoutNodeId}
+      componentId={componentId}
+    >
+      <Component {...props} />
+    </ComponentContextProvider>
+  );
+}
 
-track('Product Viewed', { productId: '123' });
+export default function Page() {
+  return (
+    <AmplifyPageContent
+      renderComponent={renderComponent}
+      fallback={<YourStaticPage />}
+    />
+  );
+}
+```
 
-identify('user-123', { email: 'user@example.com' });
+### 3. Components use Field / Slot
+
+```tsx
+import { Field, Slot } from '@amplifyup/sdk/react';
+
+export function Hero() {
+  return (
+    <section>
+      <h1>
+        <Field name="heading" fallback="Welcome" />
+      </h1>
+    </section>
+  );
+}
 ```
 
-## Composer and hybrid pages
+Field names must match the component registry in AmplifyUp. Connect CMS documents in Composer, then **Deploy** so Edge can serve the page.
 
-If a page has its own native content **and** can be edited in Composer, use `AmplifyPageContent`:
+## Content sources
 
-- **Visitors** see your AmplifyUp layout, or your native content when no layout is configured yet.
-- **Composer preview** shows only the layout canvas — native fallback content is hidden.
+| Mode | Source | When |
+|------|--------|------|
+| Production visitors | Edge `/v1/resolve` | Default |
+| Composer preview | Orchestrator layout provider | `?preview=true` / Composer iframe |
 
-```tsx
-import { isPreviewRequest } from '@amplifyup/sdk';
-import { AmplifyPageContent } from '@amplifyup/sdk/react';
+The SDK maps Edge’s resolved tree into `layoutTree` and renders it. Edge already applies personalization and CMS projection — the site does not call CMS or Decision APIs for layout.
 
-export default async function Page({ searchParams }) {
-  const params = await searchParams;
+## Track events
 
-  if (isPreviewRequest(params)) {
-    return (
-      <Layout>
-        <AmplifyPageContent renderComponent={renderAmplifyComponent} />
-      </Layout>
-    );
-  }
+```typescript
+import { init, page, track, identify } from '@amplifyup/sdk';
 
-  return (
-    <Layout>
-      <AmplifyPageContent
-        fallback={<YourNativePage />}
-        renderComponent={renderAmplifyComponent}
-      />
-    </Layout>
-  );
-}
+await init({ trackingId: 'your-tracking-id' });
+
+page('/home');
+track('Product Viewed', { productId: '123' });
+identify('user-123', { email: 'user@example.com' });
 ```
 
 ## Debugging
 
-In the browser console (on your site):
-
 ```js
 AmplifyUp.getStatus()
 ```
 
+React context: `useAmplifyUp()` → `{ pageConfig, loading, error, source, meta }`.
+
 ## License
 
 MIT

package/dist/AmplifyRenderer.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { P as PageConfig } from './types-Cy5aWQ5c.mjs';
+import { P as PageConfig } from './types-BxpG9Gsy.mjs';
 
 interface AmplifyRendererProps {
     /**

package/dist/AmplifyRenderer.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { P as PageConfig } from './types-Cy5aWQ5c.js';
+import { P as PageConfig } from './types-BxpG9Gsy.js';
 
 interface AmplifyRendererProps {
     /**

package/dist/AmplifyRenderer.js

@@ -153,17 +153,42 @@ var AWSAdapter = class {
     };
     this.sendEvent("/v1/track", eventData);
   }
-  identify(userId, traits) {
+  identify(userIdOrIdentifiers, traits = {}) {
     if (!this.initialized) {
       console.warn("AmplifyUp SDK: Not initialized. Call init() first.");
       return;
     }
+    const isMap = userIdOrIdentifiers !== null && typeof userIdOrIdentifiers === "object" && !Array.isArray(userIdOrIdentifiers);
+    const identifiers = isMap ? userIdOrIdentifiers : traits.identifiers;
+    const userId = isMap ? void 0 : String(userIdOrIdentifiers);
     const eventData = {
       type: "identify",
-      userId,
       anonymousId: traits.instanceId,
       traits: {
-        ...traits
+        ...traits,
+        ...identifiers ? { identifiers } : {}
+      },
+      ...identifiers ? { identifiers } : {},
+      ...userId ? { userId } : {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.sendEvent("/v1/track", eventData);
+  }
+  setProfileFields(fields, context = {}) {
+    if (!this.initialized) {
+      console.warn("AmplifyUp SDK: Not initialized. Call init() first.");
+      return;
+    }
+    const eventData = {
+      type: "set_fields",
+      anonymousId: context.instanceId,
+      fields,
+      traits: {
+        instanceId: context.instanceId,
+        trackingId: context.trackingId
+      },
+      properties: {
+        trackingId: context.trackingId
       },
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
@@ -225,6 +250,7 @@ function clearIds() {
 var AWS_DEV_API = "https://api-dev.amplifyup.ai";
 var AWS_PROD_API = "https://api.amplifyup.ai";
 var PROD_ORCHESTRATOR = "https://amplifyup.ai";
+var PROD_EDGE = "https://edge.amplifyup.ai";
 function isAmplifyUpTarget(value) {
   return value === "local" || value === "dev" || value === "production";
 }
@@ -260,6 +286,10 @@ function localAwsApiUrl() {
   const fromEnv = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_AMPLIFYUP_API_URL : void 0;
   return (fromEnv || AWS_DEV_API).replace(/\/$/, "");
 }
+function localEdgeUrl() {
+  const fromEnv = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_EDGE_URL : void 0;
+  return (fromEnv || "http://localhost:8787").replace(/\/$/, "");
+}
 function resolveAmplifyUpUrls(target) {
   if (target === "local") {
     const orchestratorUrl2 = localOrchestratorUrl();
@@ -270,18 +300,22 @@ function resolveAmplifyUpUrls(target) {
       orchestratorUrl: orchestratorUrl2,
       // Events + personalize → AWS development stack
       apiGatewayUrl,
-      decisionApiUrl: `${apiGatewayUrl}/v1/personalize`
+      decisionApiUrl: `${apiGatewayUrl}/v1/personalize`,
+      edgeUrl: localEdgeUrl()
     };
   }
   const resolvedApi = typeof process !== "undefined" && process.env.NEXT_PUBLIC_AMPLIFYUP_API_URL?.replace(/\/$/, "") || AWS_PROD_API;
   const orchestratorFromEnv = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_ORCHESTRATOR_URL : void 0;
   const isLocalOrchestrator = !!orchestratorFromEnv && (orchestratorFromEnv.includes("localhost") || orchestratorFromEnv.includes("127.0.0.1"));
   const orchestratorUrl = isLocalOrchestrator || !orchestratorFromEnv ? PROD_ORCHESTRATOR : orchestratorFromEnv.replace(/\/$/, "");
+  const edgeFromEnv = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_EDGE_URL?.replace(/\/$/, "") : void 0;
+  const edgeUrl = edgeFromEnv && !edgeFromEnv.includes("localhost") && !edgeFromEnv.includes("127.0.0.1") ? edgeFromEnv : PROD_EDGE;
   return {
     target: "production",
     apiGatewayUrl: resolvedApi,
     orchestratorUrl,
-    decisionApiUrl: `${resolvedApi}/v1/personalize`
+    decisionApiUrl: `${resolvedApi}/v1/personalize`,
+    edgeUrl
   };
 }
 
@@ -312,6 +346,7 @@ function isComposerPreview() {
 }
 
 // src/index.ts
+var SESSION_IDLE_GAP_MS = 30 * 60 * 1e3;
 function readPreviewQueryOverrides() {
   if (typeof window === "undefined") return {};
   const params = new URLSearchParams(window.location.search);
@@ -339,6 +374,8 @@ var AmplifyUpSDK = class {
     this.apiGatewayUrl = "";
     this.orchestratorUrl = "";
     this.decisionApiUrl = "";
+    this.edgeUrl = "";
+    this.siteId = "";
     this.target = "local";
     this.initialized = false;
     /** Prevents overlapping init() from React Strict Mode double-mount */
@@ -378,7 +415,9 @@ var AmplifyUpSDK = class {
       reached: /* @__PURE__ */ new Set(),
       visibleMs: 0,
       visibleSince: null,
-      lastDwellSecondsSent: 0
+      lastDwellSecondsSent: 0,
+      /** When the tab last became hidden — used for idle-resume re-page. */
+      hiddenAt: null
     };
     this.adapter = adapter || new AWSAdapter();
     if (typeof window !== "undefined") {
@@ -493,7 +532,8 @@ var AmplifyUpSDK = class {
       isInitialized: () => this.isInitialized(),
       page: (url, properties) => this.page(url, properties),
       track: (eventName, properties) => this.track(eventName, properties),
-      identify: (userId, traits) => this.identify(userId, traits)
+      identify: (userIdOrIdentifiers, traits) => this.identify(userIdOrIdentifiers, traits),
+      setProfileFields: (fields) => this.setProfileFields(fields)
     };
   }
   async performInit(config) {
@@ -508,6 +548,8 @@ var AmplifyUpSDK = class {
     this.apiGatewayUrl = urls.apiGatewayUrl;
     this.orchestratorUrl = urls.orchestratorUrl;
     this.decisionApiUrl = urls.decisionApiUrl;
+    this.edgeUrl = urls.edgeUrl;
+    this.siteId = config.siteId || "";
     const previewOverrides = readPreviewQueryOverrides();
     if (previewOverrides.orchestratorUrl) {
       this.orchestratorUrl = previewOverrides.orchestratorUrl;
@@ -516,6 +558,7 @@ var AmplifyUpSDK = class {
         this.target = "production";
         this.apiGatewayUrl = prodUrls.apiGatewayUrl;
         this.decisionApiUrl = prodUrls.decisionApiUrl;
+        this.edgeUrl = prodUrls.edgeUrl;
       }
     }
     this.config = {
@@ -523,7 +566,8 @@ var AmplifyUpSDK = class {
       debug: config.debug ?? true,
       // Enable debug by default
       target: this.target,
-      dev: config.dev
+      dev: config.dev,
+      ...config.siteId ? { siteId: config.siteId } : {}
     };
     try {
       const adapterConfig = {
@@ -609,6 +653,7 @@ var AmplifyUpSDK = class {
     state.visibleMs = 0;
     state.visibleSince = document.visibilityState === "visible" ? Date.now() : null;
     state.lastDwellSecondsSent = 0;
+    state.hiddenAt = document.visibilityState === "hidden" ? Date.now() : null;
     let scrollRaf = null;
     const path = () => this.currentPath();
     const measureScrollPercent = () => {
@@ -651,12 +696,12 @@ var AmplifyUpSDK = class {
       state.visibleMs += Date.now() - state.visibleSince;
       state.visibleSince = Date.now();
     };
-    const emitDwell = (force = false) => {
+    const emitDwell = (_force = false) => {
       if (this.isPreviewMode()) return;
       accumulateVisible();
       const seconds = Math.floor(state.visibleMs / 1e3);
       if (seconds <= 0) return;
-      if (!force && seconds <= state.lastDwellSecondsSent) return;
+      if (seconds <= state.lastDwellSecondsSent) return;
       state.lastDwellSecondsSent = seconds;
       this.track("Time on Page", {
         seconds,
@@ -666,14 +711,34 @@ var AmplifyUpSDK = class {
     this._emitPageDwell = emitDwell;
     const onVisibility = () => {
       if (document.visibilityState === "visible") {
+        const idleMs = state.hiddenAt != null ? Date.now() - state.hiddenAt : 0;
+        state.hiddenAt = null;
+        if (idleMs >= SESSION_IDLE_GAP_MS) {
+          this.resetEngagementQuiet();
+          const resumePath = path();
+          this.page(resumePath, { resumed: true });
+          this.lastTrackedPath = resumePath;
+          if (this.config?.debug) {
+            console.log(
+              "[AmplifyUp SDK] Idle resume page view",
+              resumePath,
+              `(hidden ${Math.round(idleMs / 6e4)}m)`
+            );
+          }
+        }
         state.visibleSince = Date.now();
       } else {
         emitDwell(true);
+        state.hiddenAt = Date.now();
         state.visibleSince = null;
       }
     };
     const onPageHide = () => {
       emitDwell(true);
+      if (state.hiddenAt == null) {
+        state.hiddenAt = Date.now();
+      }
+      state.visibleSince = null;
     };
     window.addEventListener("scroll", onScroll, { passive: true });
     document.addEventListener("visibilitychange", onVisibility);
@@ -702,13 +767,19 @@ var AmplifyUpSDK = class {
       console.log("[AmplifyUp SDK] Page engagement tracking enabled");
     }
   }
+  /** Flush dwell then reset — used on SPA route changes. */
   resetEngagementForNewPage() {
     const emit = this._emitPageDwell;
     emit?.(true);
+    this.resetEngagementQuiet();
+  }
+  /** Reset dwell/scroll state without emitting (idle resume already flushed on hide). */
+  resetEngagementQuiet() {
     const state = this.pageEngagementState;
     state.reached = /* @__PURE__ */ new Set();
     state.visibleMs = 0;
     state.lastDwellSecondsSent = 0;
+    state.hiddenAt = null;
     state.visibleSince = typeof document !== "undefined" && document.visibilityState === "visible" ? Date.now() : null;
     this.componentViewSeen.clear();
   }
@@ -894,12 +965,17 @@ var AmplifyUpSDK = class {
     });
   }
   /**
-   * Identify user (when they sign up or log in)
+   * Identify a visitor.
+   * - identify('user_123') — bare string; server maps via org default type
+   * - identify({ email: '...', crm_id: '...' }) — explicit types
+   * - identify('user_123', traits) — legacy form
    */
-  identify(userId, traits) {
+  identify(userIdOrIdentifiers, traits) {
     if (this.isPreviewMode()) {
       if (this.config?.debug) {
-        console.log("AmplifyUp SDK: Identify tracking disabled in preview mode", { userId });
+        console.log("AmplifyUp SDK: Identify tracking disabled in preview mode", {
+          userIdOrIdentifiers
+        });
       }
       return;
     }
@@ -915,10 +991,45 @@ var AmplifyUpSDK = class {
       trackingId: this.config?.trackingId,
       ...traits
     };
-    this.adapter.identify(userId, identifyTraits);
-    setUserId(userId);
+    this.adapter.identify(userIdOrIdentifiers, identifyTraits);
+    if (typeof userIdOrIdentifiers === "string") {
+      setUserId(userIdOrIdentifiers);
+    }
     if (this.config?.debug) {
-      console.log("AmplifyUp SDK: User identified", { userId, instanceId });
+      console.log("AmplifyUp SDK: User identified", {
+        userIdOrIdentifiers,
+        instanceId
+      });
+    }
+  }
+  /**
+   * Set profile fields (partial update). Omitted keys are left alone;
+   * an explicit empty value clears the field.
+   */
+  setProfileFields(fields) {
+    if (this.isPreviewMode()) {
+      if (this.config?.debug) {
+        console.log("AmplifyUp SDK: setProfileFields disabled in preview mode", {
+          fields
+        });
+      }
+      return;
+    }
+    if (!this.isInitialized()) {
+      if (this.config?.debug) {
+        console.warn("AmplifyUp SDK: Not initialized. setProfileFields not called.");
+      }
+      return;
+    }
+    const instanceId = getInstanceId();
+    if (typeof this.adapter.setProfileFields === "function") {
+      this.adapter.setProfileFields(fields, {
+        instanceId: instanceId || void 0,
+        trackingId: this.config?.trackingId
+      });
+    }
+    if (this.config?.debug) {
+      console.log("AmplifyUp SDK: Profile fields set", { fields, instanceId });
     }
   }
   /**
@@ -1093,6 +1204,18 @@ Available Console Commands:
   getDecisionApiUrl() {
     return this.decisionApiUrl || void 0;
   }
+  /**
+   * Get Edge Worker URL (production content resolve)
+   */
+  getEdgeUrl() {
+    return this.edgeUrl || void 0;
+  }
+  /**
+   * Optional site id from config (Edge can resolve via trackingId alone).
+   */
+  getSiteId() {
+    return this.siteId || this.config?.siteId || void 0;
+  }
   /**
    * Build API URL for fetching page config from the Layout Provider
    */
@@ -2398,6 +2521,7 @@ function AmplifyRenderer({
   const pageConfig = serverPageConfig || clientHook.pageConfig || null;
   const loading = serverPageConfig ? false : clientHook.loading;
   const error = serverPageConfig ? null : clientHook.error;
+  const contentSource = clientHook.source;
   const [variantCache, setVariantCache] = react.useState({});
   react.useEffect(() => {
     if (typeof window !== "undefined") {
@@ -2539,6 +2663,9 @@ function AmplifyRenderer({
   }, [pageConfig]);
   react.useEffect(() => {
     if (!pageConfig?.layoutTree || !pageConfig.layoutId) return;
+    const roots = pageConfig.layoutTree;
+    const fromEdge = contentSource === "edge" || roots.some((n) => n._contentSource === "edge");
+    if (fromEdge) return;
     const sdk = getSDK();
     const instanceId = sdk.getInstanceId();
     const decisionApiUrl = sdk.getDecisionApiUrl();
@@ -2633,7 +2760,7 @@ function AmplifyRenderer({
       setVariantCache(newCache);
     };
     fetchVariants();
-  }, [pageConfig?.layoutTree, pageConfig?.layoutId, pageConfig?.route]);
+  }, [pageConfig?.layoutTree, pageConfig?.layoutId, pageConfig?.route, contentSource]);
   if (loading) {
     return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: loadingComponent || /* @__PURE__ */ jsxRuntime.jsx("div", { className: "min-h-screen bg-gray-50", children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "container mx-auto px-4 py-16", children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "animate-pulse", children: [
       /* @__PURE__ */ jsxRuntime.jsx("div", { className: "h-8 bg-gray-200 rounded w-1/4 mb-4" }),