@sylergydigital/issue-pin-sdk 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -0,0 +1,228 @@
+# Changelog
+
+All notable changes to `@sylergydigital/issue-pin-sdk` are documented here.
+
+## [0.6.3] - 2026-04-14
+
+### Added
+- **UUID normalization for non-UUID auth providers** — SDK auto-converts Firebase, Auth0, Cognito, and other non-UUID user IDs to deterministic UUID v5 format at the SDK boundary. Existing UUID-format IDs pass through unchanged.
+- `normalizeUserId()` / `toSupabaseUuid()` — public utility export for converting user IDs outside the SDK component lifecycle.
+- `CSP_REQUIREMENTS` — typed constant exporting all Content Security Policy directives required by the SDK (`connect-src`, `img-src`, `style-src`), usable in server middleware or build-time CSP generation.
+- Runtime CSP violation detection — `subscribeCspDetection()` automatically activates on SDK mount and logs actionable `[IssuePin]` console warnings when CSP blocks SDK functionality. Per-directive deduplication prevents warning spam.
+- CSP documentation section in SDK README with copy-paste directive block, per-directive explanation table, and programmatic access example.
+- Debug logging for ID conversions — when `debug={true}`, logs `[EW SDK] User ID normalized: "{raw}" -> "{effective}"` for converted IDs.
+
+### Fixed
+- Stale closure in identity warning gated on `authReady` state.
+- Missing SSR guard in `subscribeCspDetection` (safe for server-side rendering).
+
+### Dependencies
+- Added `uuid@^11.0.3` as bundled dependency (CommonJS-compatible).
+
+## [0.6.2] - 2026-04-02
+
+### Fixed
+- Replaced `html2canvas` with `html2canvas-pro` to support modern CSS features like `oklab` color space.
+
+## [0.6.1] - 2026-03-24
+
+### Changed
+- Set up public SDK mirror and npm release pipeline.
+
+## [0.6.0] - 2026-03-24
+
+### Changed
+- Set up public SDK mirror and npm release pipeline.
+
+## [0.5.9] - 2026-03-24
+
+### Changed
+- Public SDK mirror and npm registry setup.
+
+## [0.5.8] - 2026-03-23
+
+### Added
+- `showHints` toggle for instructional UI hints in the SDK.
+
+## [0.5.7] - 2026-03-23
+
+### Added
+- Verified LMS federation rollout (patch).
+
+## [0.5.6] - 2026-03-23
+
+### Added
+- LMS federation rollout with verification.
+
+## [0.5.5] - 2026-03-22
+
+### Fixed
+- SDK build and packaging fixes.
+
+## [0.5.4] - 2026-03-22
+
+### Fixed
+- SDK build and packaging fixes.
+
+## [0.5.3] - 2026-03-22
+
+### Changed
+- Aligned SDK docs and package metadata with router-free integration.
+
+## [0.5.2] - 2026-03-22
+
+### Added
+- Iframe review mode for SDK pins (canvas review surface).
+
+## [0.5.1] - 2026-03-22
+
+### Added
+- Anonymous screenshot reads for SDK workspaces via Supabase RLS.
+- ThreadPins test coverage.
+- npm registry publishing.
+
+## [0.5.0] - 2026-03-22
+
+### Changed
+- npm versioning aligned with git tags.
+
+## [0.4.9] - 2026-03-22
+
+### Changed
+- Vite host allowlist and gitignore for local tooling.
+
+## [0.4.8] - 2026-03-17
+
+### Added
+- SDK customization APIs for launcher visibility and pin visibility control.
+
+## [0.4.7] - 2026-03-17
+
+### Fixed
+- SDK publish build for controlled pin mode.
+
+## [0.4.6] - 2026-03-17
+
+### Changed
+- Thread pins open in a new tab.
+
+## [0.4.5] - 2026-03-17
+
+### Changed
+- Rewrote SDK pin positioning lifecycle for stability.
+
+## [0.4.4] - 2026-03-17
+
+### Fixed
+- Stabilized SDK pin rehydration observer.
+
+## [0.4.3] - 2026-03-17
+
+### Changed
+- Allow anonymous `sdk-resolve` calls.
+
+## [0.4.2] - 2026-03-17
+
+### Changed
+- Allow commenter workspace memberships.
+
+## [0.4.1] - 2026-03-17
+
+### Added
+- Documentation for federated first-write gating.
+
+## [0.4.0] - 2026-03-17
+
+### Fixed
+- Federated SDK author attribution.
+
+## [0.3.4] - 2026-03-16
+
+### Added
+- Anonymous update RLS policy.
+
+## [0.3.3] - 2026-03-16
+
+### Changed
+- Enabled React Router v7 future flag.
+
+## [0.3.2] - 2026-03-16
+
+### Changed
+- Relaxed thread comments foreign key constraint.
+
+## [0.3.1] - 2026-03-16
+
+### Added
+- RLS policies for anonymous inserts.
+
+## [0.3.0] - 2026-03-16
+
+### Fixed
+- SDK feedback launcher click behavior.
+
+## [0.2.9] - 2026-03-16
+
+### Added
+- Hardcoded SDK theme for consistent styling.
+
+## [0.2.8] - 2026-03-16
+
+### Fixed
+- FeedbackButton `.d.ts` build ordering.
+
+## [0.2.7] - 2026-03-16
+
+### Added
+- Debug logging for SDK menu state.
+
+### Fixed
+- SDK menu state management hardened.
+
+## [0.2.6] - 2026-03-16
+
+### Fixed
+- SDK feedback launcher click handling.
+
+## [0.2.5] - 2026-03-16
+
+### Fixed
+- FeedbackButton interaction reliability.
+
+## [0.2.4] - 2026-03-16
+
+### Fixed
+- Stabilized `getSignedUrlRef` for screenshot storage.
+
+## [0.2.3] - 2026-03-16
+
+### Added
+- Error boundary wrapping for ThreadPins.
+
+## [0.2.0] - 2026-03-16
+
+### Changed
+- Renamed SDK package to `@sylergydigital/issue-pin-sdk`.
+
+## [0.1.8] - 2026-03-16
+
+### Fixed
+- TS2722 error in ScreenshotFeedback component.
+
+## [0.1.6] - 2026-03-16
+
+### Fixed
+- Viewport auto-screenshot capture.
+
+## [0.1.5] - 2026-03-16
+
+### Fixed
+- Auto-screenshot fetch reliability.
+
+## [0.1.0] - 2026-03-16
+
+### Added
+- Initial SDK release as `@sylergydigital/issue-pin-sdk`.
+- `<IssuePin />` drop-in component with pin annotations, screenshot capture, and threaded discussions.
+- Supabase-backed real-time data layer.
+- Federated user identity for SDK consumers.

package/README.md

@@ -356,6 +356,54 @@ For bulk provisioning or non-Supabase apps, use the `federate-user` edge functio
 
 The API key is a **publishable key** — safe to include in client-side code. It only grants scoped access to create threads and comments for the associated workspace, enforced server-side via Row Level Security.
 
+## Content Security Policy (CSP)
+
+If your app sets a Content Security Policy header, add these directives so the IssuePin SDK can connect to Supabase, render screenshot previews, and apply inline styles:
+
+```
+connect-src https://*.supabase.co wss://*.supabase.co;
+img-src data: blob:;
+style-src 'unsafe-inline';
+```
+
+Merge these with your existing CSP directives — for example, if you already have `connect-src 'self'`, change it to `connect-src 'self' https://*.supabase.co wss://*.supabase.co;`.
+
+> **Narrower alternative:** Replace `*.supabase.co` with your project's specific URL (e.g. `https://abcdef.supabase.co`) for a tighter policy.
+
+### Why each directive is needed
+
+| Directive | Sources | Reason |
+|-----------|---------|--------|
+| `connect-src` | `https://*.supabase.co` | REST API calls to read/write threads and comments |
+| `connect-src` | `wss://*.supabase.co` | WebSocket connections for real-time thread updates |
+| `img-src` | `data:` `blob:` | Screenshot preview thumbnails rendered as data URIs and blob URLs |
+| `style-src` | `'unsafe-inline'` | html2canvas-pro injects inline styles during screenshot capture |
+
+### Programmatic access
+
+The SDK exports a typed constant for use in server-side middleware or build-time CSP generation:
+
+```typescript
+import { CSP_REQUIREMENTS } from "@sylergydigital/issue-pin-sdk";
+
+// CSP_REQUIREMENTS = {
+//   "connect-src": ["https://*.supabase.co", "wss://*.supabase.co"],
+//   "img-src": ["data:", "blob:"],
+//   "style-src": ["'unsafe-inline'"],
+// }
+```
+
+### Runtime detection
+
+When a CSP policy blocks an SDK operation, the browser console shows a warning like:
+
+```
+[IssuePin] CSP violation: connect-src blocked "https://abc.supabase.co/rest/v1/threads".
+Add to your Content-Security-Policy: connect-src https://*.supabase.co wss://*.supabase.co
+```
+
+These warnings appear automatically — no `debug` flag needed.
+
 ## AI Agent Prompt
 
 Paste this into **Claude Code**, **Cursor**, or **Codex** to integrate the SDK automatically:

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CSP_REQUIREMENTS: () => CSP_REQUIREMENTS,
   ElementWhisperer: () => IssuePin,
   FeedbackButton: () => FeedbackButton,
   FeedbackOverlay: () => FeedbackOverlay,
@@ -40,6 +41,7 @@ __export(index_exports, {
   SdkCommentPopover: () => SdkCommentPopover,
   ThreadPins: () => ThreadPins,
   Z: () => Z,
+  normalizeUserId: () => normalizeUserId,
   useFeedback: () => useFeedback,
   useFeedbackSafe: () => useFeedbackSafe,
   useIssuePinAnchor: () => useIssuePinAnchor
@@ -125,6 +127,51 @@ var T = {
   ring: "#6366f1"
 };
 
+// src/uuid.ts
+var import_uuid = require("uuid");
+var NAMESPACE = "8920e263-ef53-4df0-8108-968cd5d8939e";
+var UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function normalizeUserId(userId) {
+  if (UUID_SHAPE.test(userId)) return userId;
+  return (0, import_uuid.v5)(userId, NAMESPACE);
+}
+
+// src/csp.ts
+var CSP_REQUIREMENTS = {
+  "connect-src": ["https://*.supabase.co", "wss://*.supabase.co"],
+  "img-src": ["data:", "blob:"],
+  "style-src": ["'unsafe-inline'"]
+};
+var warnedDirectives = /* @__PURE__ */ new Set();
+function isIssuePinViolation(event) {
+  const blocked = event.blockedURI;
+  const directive = event.violatedDirective;
+  if (directive.startsWith("connect-src") && blocked.includes("supabase.co")) return true;
+  if (directive.startsWith("img-src") && (blocked === "data" || blocked === "blob")) return true;
+  if (directive.startsWith("style-src") && (blocked === "inline" || blocked === "'unsafe-inline'")) return true;
+  return false;
+}
+function handleViolation(event) {
+  if (!isIssuePinViolation(event)) return;
+  const directive = event.violatedDirective.split(" ")[0];
+  if (warnedDirectives.has(directive)) return;
+  warnedDirectives.add(directive);
+  const sources = CSP_REQUIREMENTS[directive];
+  const fix = sources ? sources.join(" ") : event.blockedURI;
+  console.warn(
+    `[IssuePin] CSP violation: ${directive} blocked "${event.blockedURI}". Add to your Content-Security-Policy: ${directive} ${fix}`
+  );
+}
+function subscribeCspDetection() {
+  if (typeof document === "undefined") return () => {
+  };
+  const handler = (e) => handleViolation(e);
+  document.addEventListener("securitypolicyviolation", handler);
+  return () => {
+    document.removeEventListener("securitypolicyviolation", handler);
+  };
+}
+
 // src/FeedbackProvider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var FeedbackContext = (0, import_react2.createContext)(null);
@@ -176,11 +223,11 @@ function setThreadsSchemaMode(workspaceId, mode) {
   threadsSchemaModeByWorkspace.set(workspaceId, mode);
 }
 function resolveIssuePinActorUserId(opts) {
-  if (opts.explicitUserId) return opts.explicitUserId;
+  if (opts.explicitUserId) return normalizeUserId(opts.explicitUserId);
   if (opts.hasApiKey && !opts.skipFederation && opts.autoIdentityUserId) {
     return opts.federatedLocalUserId;
   }
-  return opts.autoIdentityUserId;
+  return opts.autoIdentityUserId ? normalizeUserId(opts.autoIdentityUserId) : opts.autoIdentityUserId;
 }
 function resolveIssuePinActorReady(opts) {
   if (!opts.authReady) return false;
@@ -417,6 +464,10 @@ function FeedbackProvider({
     hasApiKey: !!config.apiKey,
     skipFederation: config.skipFederation
   });
+  const rawUserId = config.userId ?? autoIdentity.userId;
+  if (config.debug && rawUserId && effectiveUserId && rawUserId !== effectiveUserId) {
+    console.log(`[EW SDK] User ID normalized: "${rawUserId}" -> "${effectiveUserId}"`);
+  }
   const actorReady = resolveIssuePinActorReady({
     authReady,
     explicitUserId: config.userId,
@@ -501,12 +552,13 @@ function FeedbackProviderInner({
     console.log(`[EW SDK] ${message}`, extra);
   }, [debug]);
   (0, import_react2.useEffect)(() => {
+    if (!authReady) return;
     if (!userDisplayName && !userEmail) {
       console.warn(
         '[IssuePin] No user identity provided \u2014 comments will appear as "Unknown". Pass supabaseClient={supabase} for automatic identity, or user={{ email, displayName }} for manual attribution. See https://github.com/sylergydigital/issue-pin/blob/main/sdk/README.md#user-identity-avoiding-unknown-comments'
       );
     }
-  }, []);
+  }, [authReady, userDisplayName, userEmail]);
   const client = (0, import_react2.useMemo)(() => {
     try {
       return (0, import_supabase_js.createClient)(supabaseUrl, supabaseAnonKey, {
@@ -613,6 +665,10 @@ function FeedbackProviderInner({
       debugLog("FeedbackProvider unmounted", { workspaceId, path: pathname });
     };
   }, [debugLog, workspaceId, pathname]);
+  (0, import_react2.useEffect)(() => {
+    const unsubscribe = subscribeCspDetection();
+    return unsubscribe;
+  }, []);
   (0, import_react2.useEffect)(() => {
     debugLog("mode / feedbackActive", { mode, feedbackActive });
   }, [debugLog, mode, feedbackActive]);
@@ -2483,6 +2539,7 @@ function PinsSlot() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CSP_REQUIREMENTS,
   ElementWhisperer,
   FeedbackButton,
   FeedbackOverlay,
@@ -2493,6 +2550,7 @@ function PinsSlot() {
   SdkCommentPopover,
   ThreadPins,
   Z,
+  normalizeUserId,
   useFeedback,
   useFeedbackSafe,
   useIssuePinAnchor