@proveanything/smartlinks 2.0.6 → 2.0.10

package/package.json

@@ -1,37 +1,48 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.6",
+  "version": "2.0.10",
   "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',
-  },
-})
-```

package/docs/iframe-streaming-parent-changes.md

@@ -1,308 +0,0 @@
-# Iframe Streaming Parent Changes
-
-This note describes the parent-side changes needed to support AI streaming when an embedded SmartLinks app is running in iframe proxy mode.
-
-If you are using the SDK `IframeResponder` directly, this is already implemented in the SDK changes. You only need this document if your parent application has its own iframe proxy handler and does not rely on `IframeResponder`.
-
-## Goal
-
-Keep the existing architecture:
-
-- local mode: child calls API directly
-- iframe proxy mode: child never owns auth state and streams through the parent
-
-This keeps user/session authority in the parent while making AI streaming behave like the rest of the SDK transport.
-
-## What changed
-
-Previously, proxy mode only supported one-shot request/response messages:
-
-- `_smartlinksProxyRequest`
-- `_smartlinksProxyResponse`
-
-Streaming now adds a second protocol for long-lived responses:
-
-- `_smartlinksProxyStreamRequest`
-- `_smartlinksProxyStream`
-- `_smartlinksProxyStreamAbort`
-
-## New parent message handling
-
-### 1. Listen for stream requests
-
-The iframe child may now send this message:
-
-```ts
-{
-  _smartlinksProxyStreamRequest: true,
-  id: string,
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
-  path: string,
-  body?: any,
-  headers?: Record<string, string>
-}
-```
-
-Parent behavior:
-
-- treat this like a proxied API request
-- build the real API URL from your configured base URL plus `path`
-- send the request using the parent's current auth/session context
-- expect an SSE / streaming response body
-- keep the request open until the stream ends or is aborted
-
-### 2. Forward stream lifecycle messages back to the child
-
-The parent should send messages back to the iframe using this envelope:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id: string,
-  phase: 'open' | 'event' | 'end' | 'error',
-  data?: any,
-  error?: string,
-  status?: number
-}
-```
-
-Phases:
-
-- `open`
-  - optional but recommended
-  - indicates the upstream streaming request was accepted and a body exists
-- `event`
-  - contains one parsed JSON event from an SSE `data:` frame
-  - send one message per logical event payload
-- `end`
-  - sent once when the stream finishes normally
-- `error`
-  - sent if the upstream request fails before or during streaming
-
-### 3. Support abort from the child
-
-The child may stop reading early and send:
-
-```ts
-{
-  _smartlinksProxyStreamAbort: true,
-  id: string
-}
-```
-
-Parent behavior:
-
-- look up the active stream by `id`
-- abort the underlying fetch / reader
-- clean up any local state for that stream
-- do not keep streaming after abort
-
-## SSE forwarding rules
-
-The upstream AI endpoints return SSE-like frames. The parent should:
-
-- read the response body as a stream
-- buffer text until line boundaries
-- collect `data:` lines for a single event
-- join multi-line `data:` payloads with `\n`
-- ignore blank events
-- stop on `data: [DONE]`
-- JSON-parse each event payload
-- forward parsed payloads to the iframe as `_smartlinksProxyStream` with `phase: 'event'`
-
-Minimal parsing behavior:
-
-1. accumulate bytes into text
-2. split on `\r?\n`
-3. collect each `data:` line
-4. on blank line, finalize the event
-5. if payload is `[DONE]`, finish
-6. otherwise `JSON.parse(payload)` and forward
-
-## Auth and session expectations
-
-The parent remains the source of truth for auth.
-
-That means the parent stream handler should:
-
-- use the same auth headers/token source as normal proxied requests
-- not require the iframe to know the bearer token or API key
-- naturally pick up the current logged-in user when the stream starts
-- cancel active streams if your app invalidates session state on logout or account switch
-
-In practice, the stream request should use the same header-building logic as your normal parent proxy transport.
-
-## Error handling expectations
-
-If the upstream fetch returns a non-2xx status:
-
-- try to read the JSON error body
-- derive a useful message
-- send one `_smartlinksProxyStream` message with `phase: 'error'`
-- include `status` when available
-- do not send `end` afterward
-
-If the stream body is missing unexpectedly:
-
-- send `phase: 'error'`
-
-If JSON parsing fails for a single event chunk:
-
-- safest behavior is to ignore that malformed chunk and continue
-
-## State the parent should keep
-
-Track active streams in a map keyed by `id`:
-
-```ts
-Map<string, AbortController>
-```
-
-Recommended cleanup points:
-
-- on normal stream end
-- on error
-- on child abort
-- on iframe detach/unmount
-- on parent auth reset/logout if you want all in-flight streams cancelled immediately
-
-## Parent implementation outline
-
-```ts
-const activeStreams = new Map<string, AbortController>()
-
-window.addEventListener('message', async (event) => {
-  const msg = event.data
-
-  if (msg?._smartlinksProxyStreamAbort && msg.id) {
-    activeStreams.get(msg.id)?.abort()
-    activeStreams.delete(msg.id)
-    return
-  }
-
-  if (msg?._smartlinksProxyStreamRequest && msg.id) {
-    const controller = new AbortController()
-    activeStreams.set(msg.id, controller)
-
-    try {
-      const response = await fetch(buildUrl(msg.path), {
-        method: msg.method,
-        headers: msg.headers,
-        body: msg.body ? JSON.stringify(msg.body) : undefined,
-        signal: controller.signal,
-      })
-
-      if (!response.ok || !response.body) {
-        postError(...)
-        return
-      }
-
-      postOpen(...)
-      await forwardSse(response.body, parsed => postEvent(...parsed))
-      postEnd(...)
-    } catch (err) {
-      if (err?.name !== 'AbortError') postError(...)
-    } finally {
-      activeStreams.delete(msg.id)
-    }
-  }
-})
-```
-
-## Exact protocol summary
-
-### Child → parent
-
-Standard stream request:
-
-```ts
-{
-  _smartlinksProxyStreamRequest: true,
-  id,
-  method,
-  path,
-  body,
-  headers
-}
-```
-
-Abort request:
-
-```ts
-{
-  _smartlinksProxyStreamAbort: true,
-  id
-}
-```
-
-### Parent → child
-
-Open:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id,
-  phase: 'open'
-}
-```
-
-Event:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id,
-  phase: 'event',
-  data: parsedJsonEvent
-}
-```
-
-End:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id,
-  phase: 'end'
-}
-```
-
-Error:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id,
-  phase: 'error',
-  error: 'message',
-  status?: number
-}
-```
-
-## What does not change
-
-These parts of the parent iframe integration stay the same:
-
-- normal `_smartlinksProxyRequest` request/response flow
-- upload proxy flow
-- auth login/logout postMessage handling
-- route/deep-link handling
-- resize handling
-
-This is an additive protocol, not a replacement.
-
-## Current SDK reference
-
-The SDK implementation lives in:
-
-- [src/http.ts](src/http.ts)
-- [src/iframeResponder.ts](src/iframeResponder.ts)
-- [src/types/iframeResponder.ts](src/types/iframeResponder.ts)
-- [src/api/ai.ts](src/api/ai.ts)
-
-## Practical recommendation
-
-If your parent already uses `IframeResponder`, prefer upgrading to the SDK version with these changes instead of re-implementing the protocol manually.
-
-If your parent has a custom iframe bridge, implement exactly the three new message types above and reuse your existing auth/header logic from normal proxied requests.