@sylergydigital/issue-pin-sdk 0.6.0

package/LICENSE

@@ -0,0 +1,74 @@
+Issue Pin SDK Proprietary License
+
+Copyright (c) 2026 Sylergy Digital. All rights reserved.
+
+Permission is granted to any person or entity obtaining a copy of this software
+and associated documentation files (the "Software") to use the Software solely
+as compiled code or as installed from an authorized package registry, subject to
+the conditions below.
+
+1. Permitted Use
+
+You may:
+
+- use the Software internally within your own applications and systems;
+- integrate the unmodified Software into applications you own or operate;
+- make a reasonable number of copies as necessary for backup, deployment, and
+  internal development;
+- modify the Software only for your own internal use, provided such
+  modifications are not distributed or disclosed outside your organization.
+
+2. Restrictions
+
+You may not:
+
+- sell, sublicense, redistribute, publish, or otherwise make the Software
+  available to any third party except as embedded in your own application in a
+  manner that does not expose the Software itself for reuse;
+- distribute source code of the Software, including modified versions;
+- offer the Software on a standalone basis;
+- use the Software to provide a competing SDK, library, or hosted service;
+- remove or alter any copyright, trademark, or proprietary notices;
+- claim that the Software is open source.
+
+3. Ownership
+
+The Software is licensed, not sold. Sylergy Digital and its licensors retain
+all right, title, and interest in and to the Software, including all
+intellectual property rights.
+
+4. Feedback
+
+If you provide feedback, suggestions, or ideas regarding the Software, Sylergy
+Digital may use them without restriction or obligation to you.
+
+5. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+6. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, SYLERGY DIGITAL WILL NOT BE LIABLE FOR
+ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE
+DAMAGES, OR FOR ANY LOSS OF DATA, PROFITS, REVENUE, OR BUSINESS OPPORTUNITY,
+ARISING OUT OF OR RELATED TO THE SOFTWARE OR THIS LICENSE, EVEN IF ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT WILL SYLERGY DIGITAL'S TOTAL
+LIABILITY EXCEED ONE HUNDRED U.S. DOLLARS (USD $100).
+
+7. Termination
+
+This license terminates automatically if you violate any term of this license.
+Upon termination, you must stop using the Software and destroy all copies in
+your possession or control, except where retention is required by law.
+
+8. Governing Law
+
+This license is governed by the laws of the jurisdiction in which Sylergy
+Digital is established, excluding conflict-of-law rules.
+
+9. Contact
+
+For commercial licensing, redistribution, or other permissions, contact
+Sylergy Digital.

package/README.md

@@ -0,0 +1,376 @@
+# @sylergydigital/issue-pin-sdk
+
+In-app visual feedback SDK for Issue Pin.
+
+## Installation
+
+### 1. Install
+
+```bash
+npm install @sylergydigital/issue-pin-sdk
+```
+
+### 2. Peer dependencies
+
+Ensure these are installed in your app:
+
+```bash
+npm install react react-dom @supabase/supabase-js html2canvas lucide-react
+```
+
+The public GitHub repo at `sylergydigital/issue-pin-sdk` is a read-only mirror. Source changes should be made in the private source repo and will sync across automatically.
+
+`react-router-dom` is **not** required. The SDK tracks `window.location` for thread fetching and `?highlight_thread=` without router context.
+
+## Usage
+
+The SDK is **disabled by default**. Pass `enabled={true}` (or bind it to state) to activate the feedback UI.
+
+```tsx
+import { useState } from "react";
+import { IssuePin } from "@sylergydigital/issue-pin-sdk";
+import { supabase } from "./lib/supabase"; // your app's Supabase client
+
+function App() {
+  const [feedbackOn, setFeedbackOn] = useState(false);
+
+  return (
+    <>
+      <nav>
+        <button onClick={() => setFeedbackOn(f => !f)}>
+          💬 Feedback
+        </button>
+      </nav>
+
+      <Home />
+
+      {/* Recommended: pass supabaseClient for automatic user identity */}
+      <IssuePin
+        apiKey="ew_live_..."
+        enabled={feedbackOn}
+        supabaseClient={supabase}
+      />
+    </>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | `string` | — | **Required.** Your workspace API key |
+| `enabled` | `boolean` | `false` | Toggle feedback UI visibility without unmounting |
+| `supabaseClient` | `SupabaseClient` | — | **Recommended.** Your app's Supabase client — auto-extracts user identity from the auth session and auto-federates users into the workspace |
+| `user.id` | `string` | — | Manual user ID for attribution (overrides auto-detect) |
+| `user.email` | `string` | — | Manual user email (overrides auto-detect) |
+| `user.displayName` | `string` | — | Name shown on comments (overrides auto-detect) |
+| `allowPinOnPage` | `boolean` | `true` | Allow creating new element-based pins from the launcher |
+| `allowScreenshot` | `boolean` | `true` | Allow screenshot capture from the launcher |
+| `showHints` | `boolean` | `true` | Show SDK-owned instructional hints and coachmarks, including the "Open Issue Pin" toast |
+| `scrollContainer` | `{ key: string; ref: RefObject<HTMLElement> }` | — | Store and render new element pins in a host-owned scroll container |
+| `resolveAnchor` | `(target: Element) => { key: string; selector?: string \| null } \| null` | — | Resolve a stable logical anchor key for clicked elements |
+| `pinsVisible` | `boolean` | `true` | Show historical thread pins independently from the rest of the SDK UI |
+| `buttonPosition` | `"bottom-right" \| "bottom-left"` | `"bottom-right"` | Floating button position |
+| `renderLauncher` | `(props) => ReactNode` | — | Replace the stock launcher while keeping SDK-owned state/actions |
+| `renderModalCaptureButton` | `(props) => ReactNode` | — | Replace the default screenshot button injected into open dialogs |
+| `showModalCaptureButton` | `boolean` | `true` | Control whether modal screenshot buttons are injected |
+| `mode` | `"view" \| "annotate"` | — | **Controlled** annotate mode — use with `onModeChange` |
+| `onModeChange` | `(mode: FeedbackMode) => void` | — | Called when annotate mode changes |
+| `feedbackActive` | `boolean` | — | **Deprecated.** Use `mode`: `annotate` ↔ `true`, `view` ↔ `false` |
+| `onFeedbackActiveChange` | `(active: boolean) => void` | — | **Deprecated.** Use `onModeChange` |
+
+### Migration (v0.x → coordinate-first pins)
+
+- `x_position` / `y_position` remain the persisted source of truth.
+- Element pins now resolve in this order: `anchor_key` → `selector` → stored coordinates.
+- Without `scrollContainer`, element pins stay document-relative. With `scrollContainer`, new element pins are stored and rendered in that container's coordinate space.
+- Prefer **`mode` / `onModeChange`** instead of **`feedbackActive` / `onFeedbackActiveChange`** for clarity.
+- No `<BrowserRouter>` wrapper is required for the SDK. The SDK listens to `history.pushState` / `replaceState` and `popstate` so thread fetching and `?highlight_thread=` stay in sync in SPAs without importing React Router.
+
+### TypeScript
+
+```ts
+import type { FeedbackMode } from "@sylergydigital/issue-pin-sdk";
+// FeedbackMode = "view" | "annotate"
+```
+
+### Logical anchors in a scroll container
+
+```tsx
+import { useRef } from "react";
+import { IssuePin, useIssuePinAnchor } from "@sylergydigital/issue-pin-sdk";
+
+function VisitRow({ visit }: { visit: { id: string; name: string } }) {
+  const ref = useIssuePinAnchor(`visit-row:${visit.id}`);
+  return <div ref={ref} data-visit-id={visit.id}>{visit.name}</div>;
+}
+
+function AppShell() {
+  const mainRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <>
+      <div ref={mainRef} style={{ overflow: "auto", height: 600 }}>
+        <VisitRow visit={{ id: "123", name: "Annual review" }} />
+      </div>
+
+      <IssuePin
+        apiKey="ew_live_..."
+        enabled
+        scrollContainer={{ key: "dashboard-main", ref: mainRef }}
+        resolveAnchor={(target) => {
+          const row = target.closest("[data-visit-id]");
+          if (!row) return null;
+          return {
+            key: `visit-row:${row.getAttribute("data-visit-id")}`,
+          };
+        }}
+      />
+    </>
+  );
+}
+```
+
+### Layer stacking (z-index)
+
+UI layers use a single internal scale exported as **`Z`** (pins → overlay → popover → launcher → screenshot modal → flash). If your app uses very high `z-index` values (e.g. `99999` modals), raise them above `Z.launcher` (or import `Z` and position relative to it):
+
+```ts
+import { Z } from "@sylergydigital/issue-pin-sdk";
+
+// Example: host modal above the SDK launcher
+<div style={{ zIndex: Z.launcher + 1 }}>...</div>
+```
+
+## Controlling visibility
+
+Since `enabled` defaults to `false`, the SDK mounts its provider (preserving state and subscriptions) but renders no UI until activated. Common patterns:
+
+### Navbar toggle (recommended)
+
+```tsx
+const [feedbackOn, setFeedbackOn] = useState(false);
+
+<button onClick={() => setFeedbackOn(f => !f)}>Feedback</button>
+<IssuePin apiKey="ew_live_..." enabled={feedbackOn} />
+```
+
+### Role-based
+
+```tsx
+{["qa", "admin"].includes(currentUser.role) && (
+  <IssuePin apiKey="ew_live_..." enabled={feedbackOn} user={currentUser} />
+)}
+```
+
+### Environment-based
+
+```tsx
+{import.meta.env.VITE_APP_ENV !== "production" && (
+  <IssuePin apiKey="ew_live_..." enabled={feedbackOn} />
+)}
+```
+
+## Advanced usage
+
+Use the built-in customization props first. Composing low-level SDK internals directly is no longer the recommended way to customize launcher behavior.
+
+### Launcher action flags
+
+```tsx
+<IssuePin
+  apiKey="ew_live_..."
+  supabaseClient={supabase}
+  enabled={feedbackOn}
+  allowPinOnPage={false}
+/>
+```
+
+If only one launcher action is enabled, the stock launcher triggers it directly instead of opening the menu.
+
+### Compose feature flags
+
+```tsx
+<IssuePin
+  apiKey="ew_live_..."
+  enabled={feedbackEnabled}
+  allowPinOnPage={pinOnPageEnabled}
+  allowScreenshot={screenshotEnabled}
+  pinsVisible={pinsVisible}
+  showHints={false}
+/>
+```
+
+### Hide historical pins without disabling feedback
+
+```tsx
+<IssuePin
+  apiKey="ew_live_..."
+  supabaseClient={supabase}
+  enabled
+  pinsVisible={showHistoricalPins}
+/>
+```
+
+### Custom launcher
+
+```tsx
+<IssuePin
+  apiKey="ew_live_..."
+  supabaseClient={supabase}
+  enabled
+  renderLauncher={({ mode, canPinOnPage, canScreenshot, toggleMenu, enterPinMode, exitPinMode, startScreenshotCapture }) => (
+    <div style={{ position: "fixed", right: 24, bottom: 24 }}>
+      {mode === "annotate" ? (
+        <button onClick={exitPinMode}>Exit pin mode</button>
+      ) : canPinOnPage ? (
+        <button onClick={enterPinMode}>Pin on page</button>
+      ) : canScreenshot ? (
+        <button onClick={() => void startScreenshotCapture()}>Screenshot</button>
+      ) : (
+        <button onClick={toggleMenu}>Feedback</button>
+      )}
+    </div>
+  )}
+/>
+```
+
+### Custom modal screenshot button
+
+```tsx
+<IssuePin
+  apiKey="ew_live_..."
+  supabaseClient={supabase}
+  enabled
+  renderModalCaptureButton={({ captureScreenshot }) => (
+    <button
+      onClick={() => void captureScreenshot()}
+      style={{ position: "absolute", top: 12, right: 12 }}
+    >
+      Capture
+    </button>
+  )}
+/>
+```
+
+### Low-level composition (advanced only)
+
+Import individual components only if you need full custom assembly:
+
+```tsx
+import { FeedbackProvider, FeedbackButton, FeedbackOverlay, ThreadPins } from "@sylergydigital/issue-pin-sdk";
+
+function App() {
+  return (
+    <FeedbackProvider apiKey="ew_live_...">
+      <YourApp />
+      <FeedbackOverlay />
+      <ThreadPins />
+      <FeedbackButton />
+    </FeedbackProvider>
+  );
+}
+```
+
+`ThreadPins` renders markers at stored document-percentage coordinates and updates on scroll/resize (no CSS selector resolution).
+
+## User identity & auto-federation
+
+### Supabase auth (recommended — zero config)
+
+If your app uses Supabase for authentication, just pass your existing client. The SDK:
+1. **Auto-detects identity** from `auth.getSession()` — no manual user props needed
+2. **Auto-federates** the user into the Issue Pin workspace as a `commenter` — they appear in the workspace member list and their comments are properly attributed
+3. **Uses the dashboard org `site_url`** for thread deep-links when a user clicks an in-app pin
+
+```tsx
+import { supabase } from "./lib/supabase";
+
+<IssuePin apiKey="ew_live_..." supabaseClient={supabase} enabled={feedbackOn} />
+```
+
+No backend code, edge functions, or sync secrets needed. The SDK handles everything transparently.
+
+### How auto-federation works
+
+When a user is detected via `supabaseClient`:
+1. The SDK calls the `sdk-federate` endpoint with the API key + user identity
+2. The endpoint validates the API key, resolves the workspace, and upserts the user as a `client_federated` workspace member with `commenter` role
+3. An identity source (`sdk:<workspace-slug>`) is auto-created if it doesn't exist
+
+```mermaid
+sequenceDiagram
+    participant App as Host App
+    participant SDK as IssuePin SDK
+    participant EF as sdk-federate (Edge Fn)
+    participant DB as Database
+
+    App->>SDK: Mount with apiKey + supabaseClient
+    SDK->>SDK: auth.getSession() → extract id, email, name
+    SDK->>EF: POST { apiKey, externalId, email, displayName }
+    EF->>DB: SHA-256(apiKey) → resolve_api_key()
+    DB-->>EF: workspace_id
+    EF->>DB: Upsert user_identities
+    EF->>DB: Upsert workspace_members (commenter role)
+    DB-->>EF: OK
+    EF-->>SDK: { success, user_id, workspace_id }
+    SDK-->>App: User can now post feedback
+    Note over SDK: Result cached — runs once per session
+```
+
+### Other auth providers (manual)
+
+For non-Supabase auth systems, pass identity props directly:
+
+```tsx
+// NextAuth / Auth.js
+const { data: session } = useSession();
+<IssuePin apiKey="ew_live_..." user={{ email: session?.user?.email, displayName: session?.user?.name }} />
+```
+
+```tsx
+// Clerk
+const { user } = useUser();
+<IssuePin apiKey="ew_live_..." user={{ id: user?.id, email: user?.primaryEmailAddress?.emailAddress, displayName: user?.fullName }} />
+```
+
+If neither `supabaseClient` nor `user` props are provided, a console warning will remind you during development.
+
+### Server-to-server federation (advanced)
+
+For bulk provisioning or non-Supabase apps, use the `federate-user` edge function with a `sync_secret`. See the [Federation docs](../docs/features/feature-poor-mans-federation.md) for details.
+
+## Security
+
+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.
+
+## AI Agent Prompt
+
+Paste this into **Claude Code**, **Cursor**, or **Codex** to integrate the SDK automatically:
+
+```
+Add the Issue Pin feedback SDK to this React app.
+
+Install: npm install @sylergydigital/issue-pin-sdk
+Peer deps: npm install @supabase/supabase-js html2canvas lucide-react
+
+.npmrc setup (required for GitHub Packages):
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+@sylergydigital:registry=https://npm.pkg.github.com
+
+Integration:
+1. Import { IssuePin } from "@sylergydigital/issue-pin-sdk"
+2. Add a boolean state: const [feedbackOn, setFeedbackOn] = useState(false)
+3. Place <IssuePin apiKey={import.meta.env.VITE_ISSUE_PIN_API_KEY} enabled={feedbackOn} supabaseClient={supabase} /> in your app tree (e.g. layout root)
+4. Add a toggle button: <button onClick={() => setFeedbackOn(f => !f)}>💬 Feedback</button>
+5. Import your app's Supabase client: import { supabase } from "./lib/supabase"
+
+Constraints:
+- enabled defaults to false; SDK mounts but renders no UI until true
+- apiKey is a publishable key (safe for client-side code)
+- Pass supabaseClient for automatic user identity (recommended for Supabase auth apps)
+- Alternative: pass user={{ email: "user@example.com", displayName: "Name" }} for non-Supabase auth
+- Optional feature flags: allowPinOnPage, allowScreenshot, pinsVisible, showHints
+- Use showHints={false} if the host app wants to suppress SDK instructional coachmarks such as the "Open Issue Pin" toast
+```