@proveanything/smartlinks 2.0.5 → 2.0.9

package/docs/sequences.md

@@ -1,6 +1,6 @@
 # Sequences & claim-order allocation
 
-> **Preview — SmartLinks SDK 2.0.0-alpha.** APIs may change before 2.0.0 stable.
+> **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
 
 A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it
 onto a record. It's the primitive behind raffle tickets, "you're the Nth to claim", queue

package/docs/server-functions.md

@@ -1,8 +1,7 @@
 # Server functions ("edge functions")
 
-> **Preview — SmartLinks SDK 2.0.0-alpha.** Part of the installable-app platform being built
-> toward 2.0.0 stable (author → register → install → run → test). These APIs may change before
-> then. Published under the npm `next` tag; `latest` remains 1.x.
+> **SmartLinks SDK 2.x** (current `latest`). Part of the installable-app platform
+> (author → register → install → run → test). Install `@proveanything/smartlinks@^2`.
 
 A **server function** is arbitrary server-side JavaScript your app deploys directly into
 SmartLinks. It runs on the SmartLinks servers — with access to the full SDK, to your app's

package/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/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/package.json

@@ -1,37 +1,48 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.5",
+  "version": "2.0.9",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
       "default": "./dist/testing/index.js"
-    }
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "smartlinks-register-release": "scripts/register-release.mjs",
-    "smartlinks-publish": "scripts/publish.mjs"
+    "smartlinks-publish": "scripts/publish.mjs",
+    "smartlinks-doctor": "scripts/doctor.mjs"
   },
   "files": [
     "dist/",
     "docs/",
     "scripts/register-release.mjs",
     "scripts/publish.mjs",
+    "scripts/doctor.mjs",
     "openapi.yaml",
     "README.md"
   ],
   "scripts": {
     "test": "node test/run.cjs",
-    "build": "tsc && node generate-api-summary.js && node generate-openapi.js && node scripts/copy-docs-to-dist.js",
+    "build": "tsc && node scripts/fix-esm-extensions.mjs && node generate-api-summary.cjs && node generate-openapi.cjs && node scripts/copy-docs-to-dist.cjs",
     "docs": "typedoc",
-    "docs:summary": "node generate-api-summary.js",
-    "docs:openapi": "node generate-openapi.js",
+    "docs:summary": "node generate-api-summary.cjs",
+    "docs:openapi": "node generate-openapi.cjs",
     "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js",
     "prepublishOnly": "npm run build"
   },

package/scripts/doctor.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// =============================================================================
+// smartlinks doctor — verify an app's ESM bundles against the shared-dependency
+// contract, so a modern (esm/dual) app can't ship a bare import the host won't
+// resolve.
+//
+// A correctly-built externalized ESM bundle inlines everything EXCEPT the host's
+// shared singletons. So every *bare* import left in the output must be a contract
+// entry — anything else will either fail to resolve through the import map at
+// runtime, or silently pull in a second copy (the duplicate-React class of bug).
+//
+// Usage:
+//   smartlinks-doctor [appDir]      # defaults to cwd
+//   npx @proveanything/smartlinks doctor   (once a unified `smartlinks` bin exists)
+//
+// Exit code: 0 = clean, 1 = violations (CI-friendly).
+// =============================================================================
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+// Read the contract from THIS SDK build — one source of truth with the runtime.
+const contractUrl = pathToFileURL(resolve(here, '../dist/shared-dependencies.js')).href;
+const { SHARED_DEPENDENCY_SPECIFIERS, SHARED_DEPENDENCY_CONTRACT_VERSION } = await import(contractUrl);
+const CONTRACT = new Set(SHARED_DEPENDENCY_SPECIFIERS);
+
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+function die(msg) {
+  console.error(`${RED}smartlinks doctor: ${msg}${RESET}`);
+  process.exit(1);
+}
+
+const appDir = resolve(process.argv[2] || process.cwd());
+if (!existsSync(appDir)) die(`app directory not found: ${appDir}`);
+
+// Locate the manifest.
+const manifestPath = ['public/app.manifest.json', 'app.manifest.json', 'dist/app.manifest.json']
+  .map((p) => join(appDir, p))
+  .find(existsSync);
+if (!manifestPath) die(`no app.manifest.json found under ${appDir} (looked in public/, ., dist/)`);
+
+let manifest;
+try {
+  manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+} catch (e) {
+  die(`could not parse ${manifestPath}: ${e.message}`);
+}
+const manifestDir = dirname(manifestPath);
+const meta = manifest.meta || {};
+
+console.log(`${BOLD}SmartLinks doctor${RESET} ${DIM}— ${appDir}${RESET}`);
+console.log(`${DIM}manifest:${RESET} ${manifestPath.replace(appDir + '\\', '').replace(appDir + '/', '')}`);
+console.log(`${DIM}contract:${RESET} ${SHARED_DEPENDENCY_CONTRACT_VERSION} (${CONTRACT.size} shared deps)`);
+console.log(`${DIM}moduleFormat:${RESET} ${meta.moduleFormat || '(absent → umd)'} · ${DIM}sharedDependencies:${RESET} ${meta.sharedDependencies || '(none)'}\n`);
+
+const problems = [];
+const warnings = [];
+
+// Manifest-level sanity.
+const format = meta.moduleFormat || 'umd';
+const checkEsm = format === 'esm' || format === 'dual';
+if (checkEsm && !meta.sharedDependencies) {
+  warnings.push(`meta.moduleFormat is "${format}" but meta.sharedDependencies is not declared — set it to "${SHARED_DEPENDENCY_CONTRACT_VERSION}".`);
+}
+if (meta.sharedDependencies && meta.sharedDependencies !== SHARED_DEPENDENCY_CONTRACT_VERSION) {
+  warnings.push(`built against contract ${meta.sharedDependencies}, but this SDK ships ${SHARED_DEPENDENCY_CONTRACT_VERSION} — host may not serve a matching import map.`);
+}
+
+// Pull the bare imports out of a bundle (handles minified `from"x"` too).
+function bareImportsOf(code) {
+  const specs = new Set();
+  const patterns = [
+    /\bfrom\s*["']([^"']+)["']/g, // static import/export ... from "x"
+    /\bimport\s*["']([^"']+)["']/g, // side-effect import "x"
+    /\bimport\(\s*["']([^"']+)["']\s*\)/g, // dynamic import("x")
+  ];
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(code))) {
+      const spec = m[1];
+      if (spec.startsWith('.') || spec.startsWith('/')) continue; // internal/relative
+      if (/^https?:/.test(spec)) continue; // absolute URL import
+      specs.add(spec);
+    }
+  }
+  return [...specs];
+}
+
+// Resolve a manifest-relative bundle path against the likely roots (dist paths
+// are sometimes relative to the app root, sometimes to the manifest dir).
+function resolveBundle(rel) {
+  const bases = [manifestDir, appDir, join(appDir, 'public'), join(appDir, 'dist')];
+  for (const b of bases) {
+    const p = resolve(b, rel);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+// Check each ESM surface declared in the manifest.
+const surfaces = [
+  ['widgets', manifest.widgets],
+  ['containers', manifest.containers],
+  ['mobileAdmin', manifest.mobileAdmin],
+];
+
+let checkedAny = false;
+for (const [name, block] of surfaces) {
+  const esm = block?.files?.js?.esm;
+  if (!esm) continue;
+
+  // UMD-format app that still declares an ESM bundle: the host won't load it, so
+  // it's dead weight and a common scaffold-confusion source — warn, don't fail.
+  if (!checkEsm) {
+    warnings.push(`${name}: ESM bundle "${esm}" is declared but meta.moduleFormat is "${format}", so the host never loads it. Set moduleFormat to "dual" to use it, or drop the esm entry.`);
+    continue;
+  }
+
+  checkedAny = true;
+  const bundlePath = resolveBundle(esm);
+  if (!bundlePath) {
+    console.log(`${RED}✗${RESET} ${name} ${DIM}(${esm})${RESET} — declared ESM bundle not found on disk`);
+    problems.push({ surface: name, spec: null, msg: `declared ESM bundle not found: ${esm}` });
+    continue;
+  }
+  const code = readFileSync(bundlePath, 'utf8');
+  const imports = bareImportsOf(code);
+  const offenders = imports.filter((s) => !CONTRACT.has(s));
+  const ok = imports.length - offenders.length;
+
+  if (offenders.length === 0) {
+    console.log(`${GREEN}✓${RESET} ${name} ${DIM}(${esm})${RESET} — ${ok} bare import${ok === 1 ? '' : 's'}, all in contract`);
+  } else {
+    console.log(`${RED}✗${RESET} ${name} ${DIM}(${esm})${RESET} — ${offenders.length} outside the contract:`);
+    for (const spec of offenders) {
+      const hint = spec.startsWith('node:')
+        ? 'node built-in — must not appear in a browser bundle'
+        : 'not host-provided — bundle it (don\'t externalize) or it will fail to resolve / double-load';
+      console.log(`    ${RED}${spec}${RESET} ${DIM}— ${hint}${RESET}`);
+      problems.push({ surface: name, spec, msg: hint });
+    }
+  }
+}
+
+if (checkEsm && !checkedAny) {
+  warnings.push(`moduleFormat is "${format}" but no surface declares files.js.esm — nothing to check.`);
+}
+if (!checkEsm && problems.length === 0) {
+  console.log(`${DIM}moduleFormat "${format}" — ESM path not in use; UMD bundles resolve shared deps from window globals.${RESET}`);
+}
+
+console.log('');
+for (const w of warnings) console.log(`${YELLOW}⚠ ${w}${RESET}`);
+
+if (problems.length) {
+  console.log(`\n${RED}${BOLD}FAIL${RESET} — ${problems.length} problem${problems.length === 1 ? '' : 's'} outside the shared-dependency contract.`);
+  console.log(`${DIM}Externalize only the ${CONTRACT.size} contract specifiers (import { SHARED_DEPENDENCY_SPECIFIERS } from '@proveanything/smartlinks'); bundle everything else.${RESET}`);
+  process.exit(1);
+}
+
+console.log(`${GREEN}${BOLD}OK${RESET} — bundles conform to shared-dependency contract ${SHARED_DEPENDENCY_CONTRACT_VERSION}.`);
+process.exit(0);

package/docs/analytics-metadata-conventions.md

@@ -1,88 +0,0 @@
-# Analytics Metadata Conventions
-
-Use these as the recommended standard analytics keys.
-
-Some of these are now promoted top-level analytics fields. Others remain good metadata keys for custom dimensions.
-
----
-
-## Recommended Keys
-
-### Promoted top-level fields
-
-- `visitorId`
-- `referrerHost`
-- `entryType`
-- `pageId`
-- `scanMethod`
-- `source` - collection/web-events only. Free-form client app identifier, e.g. `'portal'`, `'hub'`. No enum/whitelist. Not available on tag events - see the `analytics.tag.track(event)` section in [docs/analytics.md](analytics.md) for why.
-- `redirectMode` - tag-events only. Usually server-written; only set this yourself if you're logging a redirect-style event.
-
-These should be sent as top-level analytics fields, not inside `metadata`.
-
-### Metadata-friendly keys
-
-- `referrer`
-- `utmSource`
-- `utmMedium`
-- `utmCampaign`
-- `utmContent`
-- `utmTerm`
-- `group`
-- `tag`
-- `campaign`
-- `placement`
-- `linkGroup`
-- `linkPlacement`
-- `linkPosition`
-- `linkTitle`
-- `destinationDomain`
-- `pagePath`
-- `qrCodeId`
-
----
-
-## Why These Matter
-
-These keys give teams a shared vocabulary for:
-
-- inbound traffic attribution
-- outbound link analysis
-- link placement and link-tree performance
-- QR and page-level traffic grouping
-- physical scan source analysis
-
----
-
-## Recommendation
-
-- Treat these as reserved standard keys.
-- Prefer these names before inventing custom alternatives.
-- Send promoted fields at top level.
-- Keep values flat and scalar where possible so they are easier to filter and break down later.
-- Promote a field to a first-class backend column only when it becomes a hot platform-wide dimension.
-- Note: `source` (the event column) and the query-time `source` parameter (`'events' | 'tag'`, which table to query) are unrelated fields that happen to share a name. When filtering by the `source` column, use the plural `sources` array - there is no singular `source` filter, precisely to avoid colliding with the table selector.
-
----
-
-## Example
-
-```typescript
-analytics.collection.track({
-  sessionId: 1234567890,
-  eventType: 'click_link',
-  collectionId: 'demo-collection',
-  visitorId: 'visitor_123',
-  linkId: 'hero-cta',
-  href: 'https://example.com/buy',
-  referrerHost: 'instagram.com',
-  placement: 'hero',
-  campaign: 'summer-launch',
-  utmSource: 'email',
-  pageId: 'QR123',
-  source: 'portal',
-  metadata: {
-    pagePath: '/c/demo-collection',
-  },
-})
-```