snuggly-nudger 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moonfloss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# snuggly-nudger
+
+[![npm version](https://img.shields.io/npm/v/snuggly-nudger)](https://www.npmjs.com/package/snuggly-nudger)
+[![license](https://img.shields.io/npm/l/snuggly-nudger)](./LICENSE)
+
+`snuggly-nudger` is a lightweight React + server utility package extracted from [https://catacombs.9lives.quest](CATacombs) for a snuggly approach to:
+
+- polling your deployed app version and showing update notifications
+- collecting feedback/bug reports in a reusable modal
+- providing server handlers for `/api/version` and `/api/report`
+
+It is designed for modern full-stack apps (for example, Next.js App Router on Vercel), while staying framework-agnostic on the server side through standard Web `Request`/`Response` handlers.
+
+The flow the original is built on uses Vercel serverless functions to interact with a Neon psql database (Neon is super cute, btw) on a droplet to post bug reports to a private channel in my discord server so I can click a button to create a github issue in the offending repository. Since I have a bunch of projects I'm prototyping at once, this is how I chose to centralize feedback from all of them. I'm moving it part of it here for re-use in other apps.
+
+## Install
+
+```bash
+npm install snuggly-nudger react
+```
+
+## Package Exports
+
+The main entry `snuggly-nudger/client` re-exports everything for convenience. If you are the kind of person who still side-eyes bundle size reports because you've been hurt before, import only what you need from granular subpaths instead (your bundler should tree-shake the barrel too when configured correctly):
+
+```ts
+import { useVersionPoll } from 'snuggly-nudger/client/useVersionPoll';
+import { UpdateAvailableToast } from 'snuggly-nudger/client/UpdateAvailableToast';
+```
+
+Available subpaths: `client/useVersionPoll`, `client/UpdateAvailableToast`, `client/FeedbackModal`, `client/ModalCloseButton`, `client/useIsMobile`.
+
+### `snuggly-nudger/client`
+
+- `useVersionPoll(currentVersion, options?)`
+- `UpdateAvailableToast`
+- `FeedbackModal`
+- `ModalCloseButton`
+- `useIsMobile(breakpoint?)`
+
+Type exports:
+
+- `UseVersionPollOptions`
+- `UpdateAvailableToastProps`
+- `FeedbackModalProps`
+- `ModalCloseButtonProps`
+
+### `snuggly-nudger/server`
+
+- `createVersionHandler({ version })`
+- `createReportHandler({ projectId, reportsApiUrl? })`
+
+Type exports:
+
+- `VersionHandlerConfig`
+- `ReportHandlerConfig`
+
+## Client Usage
+
+```tsx
+import { useState } from 'react';
+import { FeedbackModal, UpdateAvailableToast, useVersionPoll } from 'snuggly-nudger/client';
+
+declare const __APP_VERSION__: string;
+
+export function App() {
+  const [showFeedback, setShowFeedback] = useState(false);
+  const { updateAvailable, dismissUpdate } = useVersionPoll(__APP_VERSION__);
+
+  return (
+    <>
+      {updateAvailable && (
+        <UpdateAvailableToast
+          deployedVersion={updateAvailable}
+          onRefresh={() => window.location.reload()}
+          onDismiss={dismissUpdate}
+        />
+      )}
+
+      <button type="button" onClick={() => setShowFeedback(true)}>
+        Send Feedback
+      </button>
+
+      {showFeedback && (
+        <FeedbackModal
+          version={__APP_VERSION__}
+          appMetadata={{ route: window.location.pathname }}
+          appMetadataLabel="App State"
+          onClose={() => setShowFeedback(false)}
+        />
+      )}
+    </>
+  );
+}
+```
+
+### `useVersionPoll` options
+
+```ts
+useVersionPoll(currentVersion, {
+  apiPath: '/api/version',
+  pollIntervalMs: 5 * 60 * 1000,
+});
+```
+
+While the tab is **hidden**, scheduled interval polls are skipped; an extra check still runs when the tab becomes visible again. No need to wake up the network just because someone left a tab open next to twelve others.
+
+### Lazy-loading `FeedbackModal` (Next.js)
+
+To avoid loading the modal until it is actually needed, because not every page load needs the whole kitchen sink:
+
+```tsx
+import dynamic from 'next/dynamic';
+
+const FeedbackModal = dynamic(
+  () => import('snuggly-nudger/client/FeedbackModal').then((m) => m.FeedbackModal),
+  { ssr: false }
+);
+```
+
+## Server Usage
+
+### `/api/version`
+
+```ts
+import { createVersionHandler } from 'snuggly-nudger/server';
+import pkg from '../../../package.json';
+
+export const { GET } = createVersionHandler({ version: pkg.version });
+```
+
+### `/api/report`
+
+```ts
+import { createReportHandler } from 'snuggly-nudger/server';
+
+export const { POST } = createReportHandler({
+  projectId: 'my-app',
+});
+```
+
+## Report Handler Architecture
+
+`createReportHandler` validates and sanitizes client payloads before proxying to your reports service. In other words: it tries to keep the useful signal and filter out the nonsense before your backend has to deal with it.
+
+Request bodies are limited to **64 KiB** by default (reject with `413`). The upstream `fetch` uses a **15s** timeout by default (response `502` with `Upstream request timed out`). Override via `maxBodyBytes` / `upstreamTimeoutMs` on the handler config if needed.
+
+Resolution order for destination base URL:
+
+1. `reportsApiUrl` passed to `createReportHandler(...)`
+2. `process.env.REPORTS_API_URL`
+
+Final upstream URL:
+
+`{reportsApiUrl}/api/reports`
+
+Request payload forwarded upstream:
+
+```json
+{
+  "projectId": "my-app",
+  "description": "sanitized message",
+  "version": "safe-version-string",
+  "category": "bug",
+  "metadata": {
+    "app": {},
+    "browser": {},
+    "device": {}
+  }
+}
+```
+
+Only `app`, `browser`, and `device` metadata objects are forwarded.
+
+## Environment Variables
+
+See `.env.example` for expected values. It is brief, on purpose, and does not require a decoding ring:
+
+- `REPORTS_API_URL` - Base URL for your reports ingestion service
+
+## Notes
+
+- `FeedbackModal` sends metadata keys as `app`, `browser`, and `device`.
+- `createReportHandler` validates `type` (`feedback`, `bug`, `other`) and sanitizes message + version before proxying.
+- The package does not implement app-specific state restoration on refresh; pass your own `onRefresh` callback. We provide the nudge, not a full state-management philosophy.
+
+## Demo App
+
+A runnable demo is available in `demo/` and shows the whole thing working end-to-end, without requiring interpretive dance:
+
+- update polling UI
+- feedback modal submission
+- `/api/version`, `/api/report`, and a mock `/api/reports` upstream endpoint

package/dist/client/FeedbackModal.d.ts

@@ -0,0 +1,8 @@
+export interface FeedbackModalProps {
+    version: string;
+    appMetadata?: Record<string, unknown> | null;
+    appMetadataLabel?: string;
+    reportEndpoint?: string;
+    onClose: () => void;
+}
+export declare function FeedbackModal({ version, appMetadata, appMetadataLabel, reportEndpoint, onClose, }: FeedbackModalProps): import("react/jsx-runtime").JSX.Element;

package/dist/client/FeedbackModal.js

@@ -0,0 +1,188 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMemo, useState } from 'react';
+import { ModalCloseButton } from './ModalCloseButton';
+import { useIsMobile } from './useIsMobile';
+function getBrowserMetadata() {
+    if (typeof navigator === 'undefined')
+        return {};
+    const isMobile = typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+        ? window.matchMedia('(max-width: 640px)').matches
+        : false;
+    return {
+        userAgent: navigator.userAgent,
+        language: navigator.language,
+        languages: Array.isArray(navigator.languages) ? [...navigator.languages] : [],
+        platform: navigator.platform,
+        isMobile,
+        maxTouchPoints: navigator.maxTouchPoints ?? 0,
+    };
+}
+function getDeviceMetadata() {
+    if (typeof window === 'undefined' || typeof screen === 'undefined')
+        return {};
+    return {
+        viewportWidth: window.innerWidth,
+        viewportHeight: window.innerHeight,
+        screenWidth: screen.width,
+        screenHeight: screen.height,
+        devicePixelRatio: window.devicePixelRatio ?? 1,
+    };
+}
+function sanitizeClientInput(value) {
+    const withoutControl = Array.from(value)
+        .filter((ch) => {
+        const code = ch.codePointAt(0) ?? 0;
+        return code >= 32 && code !== 127;
+    })
+        .join('');
+    return withoutControl.slice(0, 1000);
+}
+export function FeedbackModal({ version, appMetadata, appMetadataLabel = 'App', reportEndpoint = '/api/report', onClose, }) {
+    const [type, setType] = useState('bug');
+    const [message, setMessage] = useState('');
+    const [submitting, setSubmitting] = useState(false);
+    const [statusText, setStatusText] = useState(null);
+    const [includeApp, setIncludeApp] = useState(true);
+    const [includeBrowser, setIncludeBrowser] = useState(false);
+    const [includeDevice, setIncludeDevice] = useState(false);
+    const [showPreview, setShowPreview] = useState(false);
+    const isMobile = useIsMobile();
+    const remaining = useMemo(() => 1000 - message.length, [message.length]);
+    const sanitizedMessage = useMemo(() => sanitizeClientInput(message).trim(), [message]);
+    const metadata = useMemo(() => {
+        const parts = {};
+        if (includeApp && appMetadata)
+            parts.app = appMetadata;
+        if (includeBrowser)
+            parts.browser = getBrowserMetadata();
+        if (includeDevice)
+            parts.device = getDeviceMetadata();
+        return Object.keys(parts).length > 0 ? parts : undefined;
+    }, [includeApp, includeBrowser, includeDevice, appMetadata]);
+    const requestBody = useMemo(() => {
+        const body = {
+            type,
+            message: sanitizedMessage || '(empty)',
+            version,
+        };
+        if (metadata)
+            body.metadata = metadata;
+        return body;
+    }, [type, sanitizedMessage, version, metadata]);
+    const canSubmit = sanitizedMessage.length > 0;
+    const submit = async () => {
+        if (!canSubmit || submitting)
+            return;
+        setSubmitting(true);
+        setStatusText(null);
+        const body = { ...requestBody, message: sanitizedMessage };
+        try {
+            const res = await fetch(reportEndpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok)
+                throw new Error('Failed to send');
+            setStatusText('Thanks! Your report was sent.');
+            setTimeout(() => onClose(), 700);
+        }
+        catch {
+            setStatusText('Could not send report. Please try again.');
+        }
+        finally {
+            setSubmitting(false);
+        }
+    };
+    const previewJson = JSON.stringify(requestBody, null, 2);
+    const codeBlockStyle = {
+        margin: 0,
+        fontSize: 11,
+        fontFamily: '"Courier New", monospace',
+        color: '#ccc',
+        whiteSpace: 'pre-wrap',
+        wordBreak: 'break-all',
+    };
+    const modalContent = (_jsxs(_Fragment, { children: [_jsxs("div", { style: {
+                    display: 'flex',
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                    marginBottom: 14,
+                }, children: [_jsx("span", { id: "snuggly-nudger-feedback-title", style: { color: '#00ffcc', fontSize: 14, fontWeight: 'bold' }, children: "Send report" }), _jsx(ModalCloseButton, { onClick: onClose, ariaLabel: "Close feedback form" })] }), _jsxs("fieldset", { style: { border: 'none', margin: 0, padding: 0, marginBottom: 12 }, children: [_jsx("legend", { style: { fontSize: 11, color: '#789', marginBottom: 8 }, children: "Type" }), _jsxs("label", { style: { display: 'block', fontSize: 12, color: '#bbb', marginBottom: 6 }, children: [_jsx("input", { type: "radio", name: "feedback-type", value: "feedback", checked: type === 'feedback', onChange: () => setType('feedback'), style: { marginRight: 8 } }), "Feedback"] }), _jsxs("label", { style: { display: 'block', fontSize: 12, color: '#bbb', marginBottom: 6 }, children: [_jsx("input", { type: "radio", name: "feedback-type", value: "bug", checked: type === 'bug', onChange: () => setType('bug'), style: { marginRight: 8 } }), "Bug report"] }), _jsxs("label", { style: { display: 'block', fontSize: 12, color: '#bbb' }, children: [_jsx("input", { type: "radio", name: "feedback-type", value: "other", checked: type === 'other', onChange: () => setType('other'), style: { marginRight: 8 } }), "Other (explain)"] })] }), _jsx("textarea", { value: message, onChange: (e) => setMessage(sanitizeClientInput(e.target.value)), placeholder: type === 'other' ? 'Please explain...' : 'Tell us what happened...', maxLength: 1000, rows: 7, style: {
+                    width: '100%',
+                    resize: 'vertical',
+                    minHeight: 110,
+                    background: '#080810',
+                    border: '1px solid #2a2a50',
+                    color: '#ccc',
+                    borderRadius: 6,
+                    padding: 10,
+                    fontFamily: 'inherit',
+                    fontSize: 12,
+                    boxSizing: 'border-box',
+                    outline: 'none',
+                } }), _jsxs("div", { style: { marginTop: 12, marginBottom: 8 }, children: [_jsx("div", { style: { fontSize: 11, color: '#789', marginBottom: 8 }, children: "Include Data for Debugging Purposes (Optional):" }), appMetadata && (_jsxs("label", { style: { display: 'block', fontSize: 12, color: '#bbb', marginBottom: 6 }, children: [_jsx("input", { type: "checkbox", checked: includeApp, onChange: (e) => setIncludeApp(e.target.checked), style: { marginRight: 8 } }), appMetadataLabel] })), _jsxs("label", { style: { display: 'block', fontSize: 12, color: '#bbb', marginBottom: 6 }, children: [_jsx("input", { type: "checkbox", checked: includeBrowser, onChange: (e) => setIncludeBrowser(e.target.checked), style: { marginRight: 8 } }), "Browser"] }), _jsxs("label", { style: { display: 'block', fontSize: 12, color: '#bbb' }, children: [_jsx("input", { type: "checkbox", checked: includeDevice, onChange: (e) => setIncludeDevice(e.target.checked), style: { marginRight: 8 } }), "Device"] })] }), _jsxs("div", { style: {
+                    display: 'flex',
+                    flexWrap: 'wrap',
+                    gap: 8,
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                    marginTop: 8,
+                }, children: [_jsxs("span", { style: { fontSize: 11, color: '#667' }, children: [remaining, " chars left"] }), _jsxs("div", { style: { display: 'flex', gap: 8, alignItems: 'center' }, children: [_jsx("button", { type: "button", onClick: () => setShowPreview(!showPreview), style: {
+                                    background: '#1a1a30',
+                                    border: '1px solid #2a2a50',
+                                    color: '#8cf',
+                                    borderRadius: 4,
+                                    padding: '7px 10px',
+                                    fontSize: 11,
+                                    cursor: 'pointer',
+                                    fontFamily: 'inherit',
+                                }, children: "Preview Data" }), _jsx("button", { type: "button", onClick: submit, disabled: submitting || !canSubmit, style: {
+                                    background: submitting || !canSubmit ? '#111325' : '#142235',
+                                    border: '1px solid #2a4a6a',
+                                    color: submitting || !canSubmit ? '#556' : '#8cf',
+                                    borderRadius: 4,
+                                    padding: '7px 10px',
+                                    fontSize: 11,
+                                    cursor: submitting || !canSubmit ? 'default' : 'pointer',
+                                    fontFamily: 'inherit',
+                                }, children: submitting ? 'Sending...' : 'Send report' })] })] }), statusText && (_jsx("div", { style: { marginTop: 10, fontSize: 11, color: '#8cf' }, role: "status", children: statusText })), showPreview && isMobile && (_jsx("div", { style: {
+                    marginTop: 12,
+                    padding: 10,
+                    background: '#080810',
+                    border: '1px solid #2a2a50',
+                    borderRadius: 6,
+                    overflow: 'auto',
+                    maxHeight: 240,
+                }, children: _jsx("pre", { style: codeBlockStyle, children: _jsx("code", { children: previewJson }) }) }))] }));
+    const modalWidth = showPreview && !isMobile ? 800 : 420;
+    const innerStyle = {
+        background: '#0c0c1e',
+        border: '1px solid #2a2a50',
+        borderRadius: 8,
+        padding: 18,
+        width: modalWidth,
+        maxWidth: '95vw',
+        maxHeight: '85vh',
+        overflowY: 'auto',
+        boxSizing: 'border-box',
+    };
+    return (_jsx("div", { role: "presentation", style: {
+            position: 'fixed',
+            inset: 0,
+            background: 'rgba(0,0,0,0.88)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            zIndex: 300,
+        }, onClick: onClose, children: _jsx("div", { role: "dialog", "aria-modal": "true", "aria-labelledby": "snuggly-nudger-feedback-title", style: innerStyle, onClick: (e) => e.stopPropagation(), children: showPreview && !isMobile ? (_jsxs("div", { style: { display: 'flex', gap: 20, alignItems: 'flex-start' }, children: [_jsx("div", { style: { flex: '0 0 380px', minWidth: 0 }, children: modalContent }), _jsx("div", { style: {
+                            flex: 1,
+                            minWidth: 0,
+                            padding: 10,
+                            background: '#080810',
+                            border: '1px solid #2a2a50',
+                            borderRadius: 6,
+                            overflow: 'auto',
+                            maxHeight: '70vh',
+                        }, children: _jsx("pre", { style: codeBlockStyle, children: _jsx("code", { children: previewJson }) }) })] })) : (modalContent) }) }));
+}

package/dist/client/ModalCloseButton.d.ts

@@ -0,0 +1,5 @@
+export interface ModalCloseButtonProps {
+    onClick: () => void;
+    ariaLabel?: string;
+}
+export declare function ModalCloseButton({ onClick, ariaLabel }: ModalCloseButtonProps): import("react/jsx-runtime").JSX.Element;

package/dist/client/ModalCloseButton.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function ModalCloseButton({ onClick, ariaLabel = 'Close dialog' }) {
+    return (_jsx("button", { type: "button", "aria-label": ariaLabel, onClick: onClick, style: {
+            background: 'none',
+            border: '1px solid #2a2a40',
+            color: '#666',
+            borderRadius: 4,
+            cursor: 'pointer',
+            fontSize: 14,
+            lineHeight: 1,
+            padding: '2px 8px',
+            fontFamily: 'monospace',
+        }, children: "\u2715" }));
+}

package/dist/client/UpdateAvailableToast.d.ts

@@ -0,0 +1,6 @@
+export interface UpdateAvailableToastProps {
+    deployedVersion: string;
+    onRefresh: () => void;
+    onDismiss: () => void;
+}
+export declare function UpdateAvailableToast({ deployedVersion, onRefresh, onDismiss, }: UpdateAvailableToastProps): import("react/jsx-runtime").JSX.Element;

package/dist/client/UpdateAvailableToast.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function UpdateAvailableToast({ deployedVersion, onRefresh, onDismiss, }) {
+    return (_jsxs("div", { role: "alert", "aria-live": "polite", style: {
+            position: 'fixed',
+            top: 12,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            background: 'rgba(10,12,24,0.96)',
+            border: '1px solid #2a4a6a',
+            borderRadius: 8,
+            padding: '10px 16px',
+            boxShadow: '0 0 20px rgba(0,180,255,0.2)',
+            maxWidth: '90vw',
+            zIndex: 300,
+            display: 'flex',
+            alignItems: 'center',
+            gap: 12,
+        }, children: [_jsx("span", { style: { fontSize: 18 }, children: "\uD83D\uDD04" }), _jsxs("div", { style: { flex: 1 }, children: [_jsx("div", { style: { fontSize: 12, color: '#8cf', fontWeight: 'bold' }, children: "Update available" }), _jsxs("div", { style: { fontSize: 11, color: '#6a8' }, children: ["v", deployedVersion, " is deployed. Refresh to get the latest."] })] }), _jsx("button", { type: "button", onClick: onRefresh, style: {
+                    background: '#0d2236',
+                    border: '1px solid #2a4a6a',
+                    borderRadius: 4,
+                    color: '#8cf',
+                    fontSize: 11,
+                    padding: '6px 8px',
+                    cursor: 'pointer',
+                    fontFamily: 'inherit',
+                }, children: "Refresh" }), _jsx("button", { type: "button", "aria-label": "Dismiss update notification", onClick: onDismiss, style: {
+                    background: 'transparent',
+                    border: '1px solid #2a4a6a',
+                    borderRadius: 4,
+                    color: '#8cf',
+                    fontSize: 11,
+                    width: 24,
+                    height: 24,
+                    cursor: 'pointer',
+                    fontFamily: 'inherit',
+                    lineHeight: 1,
+                }, children: "\u00D7" })] }));
+}

package/dist/client/index.d.ts

@@ -0,0 +1,9 @@
+export { useVersionPoll } from './useVersionPoll';
+export { UpdateAvailableToast } from './UpdateAvailableToast';
+export { FeedbackModal } from './FeedbackModal';
+export { ModalCloseButton } from './ModalCloseButton';
+export { useIsMobile } from './useIsMobile';
+export type { UseVersionPollOptions } from './useVersionPoll';
+export type { UpdateAvailableToastProps } from './UpdateAvailableToast';
+export type { FeedbackModalProps } from './FeedbackModal';
+export type { ModalCloseButtonProps } from './ModalCloseButton';

package/dist/client/index.js

@@ -0,0 +1,6 @@
+'use client';
+export { useVersionPoll } from './useVersionPoll';
+export { UpdateAvailableToast } from './UpdateAvailableToast';
+export { FeedbackModal } from './FeedbackModal';
+export { ModalCloseButton } from './ModalCloseButton';
+export { useIsMobile } from './useIsMobile';

package/dist/client/useIsMobile.d.ts

@@ -0,0 +1 @@
+export declare function useIsMobile(breakpoint?: number): boolean;

package/dist/client/useIsMobile.js

@@ -0,0 +1,18 @@
+import { useSyncExternalStore } from 'react';
+const DEFAULT_BREAKPOINT = 768;
+function subscribe(query, cb) {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+        return () => { };
+    const mql = window.matchMedia(query);
+    mql.addEventListener('change', cb);
+    return () => mql.removeEventListener('change', cb);
+}
+function getSnapshot(query) {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+        return false;
+    return window.matchMedia(query).matches;
+}
+export function useIsMobile(breakpoint = DEFAULT_BREAKPOINT) {
+    const query = `(max-width: ${breakpoint - 1}px)`;
+    return useSyncExternalStore((cb) => subscribe(query, cb), () => getSnapshot(query), () => false);
+}

package/dist/client/useVersionPoll.d.ts

@@ -0,0 +1,8 @@
+export interface UseVersionPollOptions {
+    apiPath?: string;
+    pollIntervalMs?: number;
+}
+export declare function useVersionPoll(currentVersion: string, options?: UseVersionPollOptions): {
+    updateAvailable: string | null;
+    dismissUpdate: () => void;
+};

package/dist/client/useVersionPoll.js

@@ -0,0 +1,70 @@
+import { useEffect, useRef, useState } from 'react';
+const DEFAULT_POLL_INTERVAL_MS = 5 * 60 * 1000;
+export function useVersionPoll(currentVersion, options = {}) {
+    const [updateAvailable, setUpdateAvailable] = useState(null);
+    const dismissedVersionRef = useRef(null);
+    const apiPath = options.apiPath ?? '/api/version';
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        let abortController = null;
+        const check = async () => {
+            if (document.visibilityState === 'hidden')
+                return;
+            abortController?.abort();
+            abortController = new AbortController();
+            const { signal } = abortController;
+            try {
+                const base = window.location.origin;
+                const res = await fetch(`${base}${apiPath}`, { cache: 'no-store', signal });
+                if (!res.ok)
+                    return;
+                const data = (await res.json());
+                const deployed = data.version?.trim();
+                if (!deployed)
+                    return;
+                const current = currentVersion.trim();
+                if (!current || deployed === current) {
+                    setUpdateAvailable(null);
+                    return;
+                }
+                if (dismissedVersionRef.current !== deployed) {
+                    setUpdateAvailable(deployed);
+                }
+            }
+            catch (err) {
+                const aborted = (err instanceof DOMException && err.name === 'AbortError') ||
+                    (typeof err === 'object' &&
+                        err !== null &&
+                        'name' in err &&
+                        err.name === 'AbortError');
+                if (aborted)
+                    return;
+                // ignore other network errors
+            }
+        };
+        void check();
+        const id = setInterval(() => {
+            if (document.visibilityState !== 'hidden') {
+                void check();
+            }
+        }, pollIntervalMs);
+        const onVisibilityChange = () => {
+            if (document.visibilityState === 'visible') {
+                void check();
+            }
+        };
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return () => {
+            abortController?.abort();
+            clearInterval(id);
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [apiPath, currentVersion, pollIntervalMs]);
+    const dismissUpdate = () => {
+        dismissedVersionRef.current = updateAvailable;
+        setUpdateAvailable(null);
+    };
+    return { updateAvailable, dismissUpdate };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,4 @@
+export { createVersionHandler } from './version';
+export { createReportHandler } from './report';
+export type { VersionHandlerConfig } from './version';
+export type { ReportHandlerConfig } from './report';

package/dist/server/index.js

@@ -0,0 +1,2 @@
+export { createVersionHandler } from './version';
+export { createReportHandler } from './report';

package/dist/server/report.d.ts

@@ -0,0 +1,11 @@
+export interface ReportHandlerConfig {
+    projectId: string;
+    reportsApiUrl?: string;
+    /** Max request body size in bytes (default 65536). */
+    maxBodyBytes?: number;
+    /** Upstream fetch timeout in ms (default 15000). */
+    upstreamTimeoutMs?: number;
+}
+export declare function createReportHandler(config: ReportHandlerConfig): {
+    POST(request: Request): Promise<Response>;
+};

package/dist/server/report.js

@@ -0,0 +1,200 @@
+const VALID_TYPES = ['feedback', 'bug', 'other'];
+const DEFAULT_MAX_BODY_BYTES = 65536;
+const DEFAULT_UPSTREAM_TIMEOUT_MS = 15000;
+function jsonResponse(body, status) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+function isAbortOrTimeout(err) {
+    if (err instanceof DOMException && (err.name === 'AbortError' || err.name === 'TimeoutError'))
+        return true;
+    return (typeof err === 'object' &&
+        err !== null &&
+        'name' in err &&
+        err.name === 'TimeoutError');
+}
+async function readReportJsonBody(request, maxBytes) {
+    const lenHeader = request.headers.get('content-length');
+    if (lenHeader !== null && lenHeader !== '') {
+        const n = Number(lenHeader);
+        if (!Number.isFinite(n) || n < 0 || n > maxBytes) {
+            return { ok: false, response: jsonResponse({ error: 'Request body too large' }, 413) };
+        }
+    }
+    if (!request.body) {
+        return { ok: false, response: jsonResponse({ error: 'Invalid JSON body' }, 400) };
+    }
+    const reader = request.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel();
+                return { ok: false, response: jsonResponse({ error: 'Request body too large' }, 413) };
+            }
+            chunks.push(value);
+        }
+    }
+    catch {
+        return { ok: false, response: jsonResponse({ error: 'Invalid JSON body' }, 400) };
+    }
+    if (total === 0) {
+        return { ok: false, response: jsonResponse({ error: 'Invalid JSON body' }, 400) };
+    }
+    const buf = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        buf.set(c, offset);
+        offset += c.byteLength;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(buf));
+    }
+    catch {
+        return { ok: false, response: jsonResponse({ error: 'Invalid JSON body' }, 400) };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, response: jsonResponse({ error: 'Invalid JSON body' }, 400) };
+    }
+    return { ok: true, body: parsed };
+}
+function asMetadata(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const obj = value;
+    const out = {};
+    if (Object.prototype.hasOwnProperty.call(obj, 'app') &&
+        obj.app !== null &&
+        typeof obj.app === 'object' &&
+        !Array.isArray(obj.app)) {
+        out.app = obj.app;
+    }
+    if (Object.prototype.hasOwnProperty.call(obj, 'browser') &&
+        obj.browser !== null &&
+        typeof obj.browser === 'object' &&
+        !Array.isArray(obj.browser)) {
+        out.browser = obj.browser;
+    }
+    if (Object.prototype.hasOwnProperty.call(obj, 'device') &&
+        obj.device !== null &&
+        typeof obj.device === 'object' &&
+        !Array.isArray(obj.device)) {
+        out.device = obj.device;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function sanitizeMessage(input) {
+    const withoutControl = Array.from(input)
+        .filter((ch) => {
+        const code = ch.codePointAt(0) ?? 0;
+        return code >= 32 && code !== 127;
+    })
+        .join('');
+    return withoutControl
+        .replace(/<[^>]*>/g, '')
+        .replace(/\s+/g, ' ')
+        .replace(/@/g, '@\u200b')
+        .trim()
+        .slice(0, 1000);
+}
+function asReportType(value) {
+    if (typeof value !== 'string')
+        return null;
+    return VALID_TYPES.includes(value) ? value : null;
+}
+function asSafeVersion(value) {
+    if (typeof value !== 'string')
+        return 'unknown';
+    return value.replace(/[^0-9A-Za-z.\-_]/g, '').slice(0, 40) || 'unknown';
+}
+export function createReportHandler(config) {
+    const maxBodyBytes = config.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const upstreamTimeoutMs = config.upstreamTimeoutMs ?? DEFAULT_UPSTREAM_TIMEOUT_MS;
+    return {
+        async POST(request) {
+            const reportsApiUrl = config.reportsApiUrl ?? process.env.REPORTS_API_URL;
+            if (!reportsApiUrl) {
+                return new Response(JSON.stringify({ error: 'Reports API not configured' }), {
+                    status: 500,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            const read = await readReportJsonBody(request, maxBodyBytes);
+            if (!read.ok)
+                return read.response;
+            const body = read.body;
+            const type = asReportType(body.type);
+            if (!type) {
+                return new Response(JSON.stringify({ error: 'Invalid report type' }), {
+                    status: 400,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            if (typeof body.message !== 'string') {
+                return new Response(JSON.stringify({ error: 'Message is required' }), {
+                    status: 400,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            const message = sanitizeMessage(body.message);
+            if (!message) {
+                return new Response(JSON.stringify({ error: 'Message is empty after sanitization' }), {
+                    status: 400,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            const version = asSafeVersion(body.version);
+            const metadata = asMetadata(body.metadata);
+            const payload = {
+                projectId: config.projectId,
+                description: message,
+                version,
+                category: type,
+            };
+            if (metadata !== undefined)
+                payload.metadata = metadata;
+            const url = `${reportsApiUrl.trim().replace(/\/$/, '')}/api/reports`;
+            let reportsResponse;
+            try {
+                reportsResponse = await fetch(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(payload),
+                    signal: AbortSignal.timeout(upstreamTimeoutMs),
+                });
+            }
+            catch (err) {
+                if (isAbortOrTimeout(err)) {
+                    return new Response(JSON.stringify({ error: 'Upstream request timed out' }), {
+                        status: 502,
+                        headers: { 'Content-Type': 'application/json' },
+                    });
+                }
+                return new Response(JSON.stringify({ error: 'Upstream request failed' }), {
+                    status: 502,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            if (!reportsResponse.ok) {
+                return new Response(JSON.stringify({ error: 'Failed to send report' }), {
+                    status: 502,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            return new Response(JSON.stringify({ ok: true }), {
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Cache-Control': 'no-store, max-age=0',
+                },
+            });
+        },
+    };
+}

package/dist/server/version.d.ts

@@ -0,0 +1,6 @@
+export interface VersionHandlerConfig {
+    version: string;
+}
+export declare function createVersionHandler(config: VersionHandlerConfig): {
+    GET(): Response;
+};

package/dist/server/version.js

@@ -0,0 +1,12 @@
+const headers = {
+    'Content-Type': 'application/json',
+    'Cache-Control': 'no-store, max-age=0',
+};
+export function createVersionHandler(config) {
+    return {
+        GET() {
+            const version = config.version?.trim() || '0.0.0';
+            return new Response(JSON.stringify({ version }), { headers });
+        },
+    };
+}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "snuggly-nudger",
+  "version": "0.1.0",
+  "description": "Reusable client and server utilities for update notifications and in-app feedback reporting.",
+  "license": "MIT",
+  "author": "moonfloss",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moonfloss/snuggly-nudger.git"
+  },
+  "homepage": "https://github.com/moonfloss/snuggly-nudger",
+  "bugs": {
+    "url": "https://github.com/moonfloss/snuggly-nudger/issues"
+  },
+  "keywords": [
+    "feedback",
+    "bug-report",
+    "release-notifications",
+    "vercel",
+    "nextjs",
+    "react"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./client/useVersionPoll": {
+      "types": "./dist/client/useVersionPoll.d.ts",
+      "import": "./dist/client/useVersionPoll.js"
+    },
+    "./client/UpdateAvailableToast": {
+      "types": "./dist/client/UpdateAvailableToast.d.ts",
+      "import": "./dist/client/UpdateAvailableToast.js"
+    },
+    "./client/FeedbackModal": {
+      "types": "./dist/client/FeedbackModal.d.ts",
+      "import": "./dist/client/FeedbackModal.js"
+    },
+    "./client/ModalCloseButton": {
+      "types": "./dist/client/ModalCloseButton.d.ts",
+      "import": "./dist/client/ModalCloseButton.js"
+    },
+    "./client/useIsMobile": {
+      "types": "./dist/client/useIsMobile.d.ts",
+      "import": "./dist/client/useIsMobile.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run clean && tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "size-limit": "npm run build && size-limit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@size-limit/file": "^11.2.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.5.2",
+    "@types/react": "^19.1.13",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "jsdom": "^29.0.1",
+    "prettier": "^3.8.1",
+    "size-limit": "^11.2.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^4.1.2"
+  }
+}