django-snapnote 0.1.1__tar.gz

django_snapnote-0.1.1/.gitignore

@@ -0,0 +1,55 @@
+# These are some examples of commonly ignored file patterns.
+# You should customize this list as applicable to your project.
+# Learn more about .gitignore:
+#     https://www.atlassian.com/git/tutorials/saving-changes/gitignore
+
+# Node artifact files
+node_modules/
+dist/
+
+# Compiled Java class files
+*.class
+
+# Compiled Python bytecode
+*.py[cod]
+
+# Log files
+*.log
+
+# Package files
+*.jar
+
+# Maven
+target/
+dist/
+
+# JetBrains IDE
+.idea/
+
+# Unit test reports
+TEST*.xml
+
+# Generated by MacOS
+.DS_Store
+
+# Generated by Windows
+Thumbs.db
+
+# Applications
+*.app
+*.exe
+*.war
+
+# Large media files
+*.mp4
+*.tiff
+*.avi
+*.flv
+*.mov
+*.wmv
+
+.venv/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/
+build/

django_snapnote-0.1.1/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.1
+
+- First release on PyPI (0.1.0 was a TestPyPI dry run).
+
+## 0.1.0
+
+- First release: floating report button with tab capture (or image upload fallback), annotation
+  editor, ticket model, report endpoint, management views, admin, notifiers, purge command.

django_snapnote-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magnet SpA
+
+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.

django_snapnote-0.1.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: django-snapnote
+Version: 0.1.1
+Summary: Report problems from any page of a Django site: screenshot, annotations and a ticket list.
+License: MIT
+License-File: LICENSE
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Requires-Dist: pillow>=9.0
+Description-Content-Type: text/markdown
+
+# django-snapnote
+
+Let your users report a problem from any page: a floating button captures the tab, lets them
+draw on it and creates a ticket you can review in the admin or in built-in views.
+
+Requires only Django (4.2–5.2) and Pillow. No DRF, no Node, no build step for you. The widget is a
+self-contained bundle rendered in a Shadow DOM, so your CSS and ours don't interfere.
+
+## Install
+
+```bash
+pip install django-snapnote
+```
+
+```python
+# settings.py
+INSTALLED_APPS += ["snapnote"]          # needs django.contrib.auth and staticfiles
+
+# urls.py
+path("snapnote/", include("snapnote.urls")),   # report endpoint + management views
+```
+
+```django
+{# in your base template (the view needs the request context processor) #}
+{% load snapnote_tags %}
+{% snapnote_button %}
+```
+
+Then `python manage.py migrate`. Uploaded images use your `MEDIA_ROOT`/storage.
+
+## Settings
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `SNAPNOTE_CAN_REPORT` | `"snapnote.permissions.is_authenticated"` | Dotted path to `user -> bool`: who sees the button and may report |
+| `SNAPNOTE_NOTIFIERS` | `["snapnote.notifiers.email"]` | Callables `(ticket, absolute_url)` run after a ticket is created |
+| `SNAPNOTE_NOTIFY_EMAILS` | `[]` | Recipients of the email notifier (nothing is sent if empty) |
+| `SNAPNOTE_BASE_TEMPLATE` | `None` | Template the management views extend; it only needs `{% block content %}` |
+| `SNAPNOTE_ENABLE_MANAGEMENT_VIEWS` | `True` | List/detail views (the admin is always registered) |
+| `SNAPNOTE_SEARCH_UNACCENT` | `False` | Accent-insensitive search (PostgreSQL + `django.contrib.postgres` only) |
+| `SNAPNOTE_MAX_UPLOAD_MB` | `5` | Per-image size limit |
+| `SNAPNOTE_MAX_DIMENSION` | `8000` | Max width/height in pixels |
+| `SNAPNOTE_UPLOAD_TO` | `"snapnote/"` | Prefix in the storage |
+| `SNAPNOTE_THROTTLE` | `"10/hour"` | Reports per user (`second`, `minute`, `hour`, `day`); uses Django's cache. `None` disables |
+| `SNAPNOTE_AUTO_INJECT` | `False` | Also add `snapnote.middleware.AutoInjectMiddleware` to `MIDDLEWARE` to insert the button automatically. Incompatible with strict CSP and streaming responses |
+
+Customise the look by overriding CSS variables on `#snapnote-root`
+(`--snapnote-accent`, `--snapnote-accent-text`, `--snapnote-z-index`, `--snapnote-font`).
+
+## Permissions
+
+Reporting follows `SNAPNOTE_CAN_REPORT`. Managing uses the model permissions
+`snapnote.view_ticket`, `change_ticket` and `delete_ticket` (superusers have them all).
+Anonymous users are redirected to `LOGIN_URL`; authenticated users without permission get 403.
+
+## Notifiers
+
+The signal `snapnote.signals.ticket_created(sender, ticket, request_url)` is sent after commit.
+A notifier is any callable; a failing one is logged and never breaks the report:
+
+```python
+# myproject/notifiers.py — Slack recipe
+import requests
+def slack(ticket, url):
+    requests.post(settings.SLACK_WEBHOOK, json={"text": f"New ticket: {ticket.title} {url}"}, timeout=5)
+
+SNAPNOTE_NOTIFIERS = ["snapnote.notifiers.email", "myproject.notifiers.slack"]
+```
+
+## Security and deployment notes
+
+- **Screenshots can contain sensitive data.** Serve `MEDIA_ROOT` only to authenticated staff (or use a
+  private storage); do not expose it publicly. Purge old reports with
+  `python manage.py snapnote_purge --older-than 90` (`--dry-run` to preview).
+- **Permissions-Policy**: the browser needs `display-capture=(self)`. With `display-capture=()`
+  (also sent by some proxies) capture never works and users get the upload fallback.
+- **CSP**: allow `img-src blob: data:` and `style-src 'unsafe-inline'` (the Shadow DOM stylesheet
+  is inline) and `script-src` for the static bundle.
+- Uploads are validated (PNG/JPEG/WebP only, no SVG), size/dimension limited and re-encoded with Pillow.
+- `page_url` must be http(s) and is never rendered as a clickable link otherwise.
+- The report endpoint uses Django's CSRF protection; the template tag sets the cookie.
+- Capture uses `getDisplayMedia` (desktop browsers). On mobile the user attaches an image.
+
+## Development
+
+```bash
+pip install -e . pytest pytest-django
+pytest                      # SQLite; SNAPNOTE_TEST_DB=postgres for PostgreSQL
+cd frontend && npm ci && npm run build   # writes src/snapnote/static/snapnote/snapnote.js
+npm test && npm run e2e
+```
+
+The built `snapnote.js` is committed/packaged so installing the wheel never needs Node.

django_snapnote-0.1.1/README.md

@@ -0,0 +1,93 @@
+# django-snapnote
+
+Let your users report a problem from any page: a floating button captures the tab, lets them
+draw on it and creates a ticket you can review in the admin or in built-in views.
+
+Requires only Django (4.2–5.2) and Pillow. No DRF, no Node, no build step for you. The widget is a
+self-contained bundle rendered in a Shadow DOM, so your CSS and ours don't interfere.
+
+## Install
+
+```bash
+pip install django-snapnote
+```
+
+```python
+# settings.py
+INSTALLED_APPS += ["snapnote"]          # needs django.contrib.auth and staticfiles
+
+# urls.py
+path("snapnote/", include("snapnote.urls")),   # report endpoint + management views
+```
+
+```django
+{# in your base template (the view needs the request context processor) #}
+{% load snapnote_tags %}
+{% snapnote_button %}
+```
+
+Then `python manage.py migrate`. Uploaded images use your `MEDIA_ROOT`/storage.
+
+## Settings
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `SNAPNOTE_CAN_REPORT` | `"snapnote.permissions.is_authenticated"` | Dotted path to `user -> bool`: who sees the button and may report |
+| `SNAPNOTE_NOTIFIERS` | `["snapnote.notifiers.email"]` | Callables `(ticket, absolute_url)` run after a ticket is created |
+| `SNAPNOTE_NOTIFY_EMAILS` | `[]` | Recipients of the email notifier (nothing is sent if empty) |
+| `SNAPNOTE_BASE_TEMPLATE` | `None` | Template the management views extend; it only needs `{% block content %}` |
+| `SNAPNOTE_ENABLE_MANAGEMENT_VIEWS` | `True` | List/detail views (the admin is always registered) |
+| `SNAPNOTE_SEARCH_UNACCENT` | `False` | Accent-insensitive search (PostgreSQL + `django.contrib.postgres` only) |
+| `SNAPNOTE_MAX_UPLOAD_MB` | `5` | Per-image size limit |
+| `SNAPNOTE_MAX_DIMENSION` | `8000` | Max width/height in pixels |
+| `SNAPNOTE_UPLOAD_TO` | `"snapnote/"` | Prefix in the storage |
+| `SNAPNOTE_THROTTLE` | `"10/hour"` | Reports per user (`second`, `minute`, `hour`, `day`); uses Django's cache. `None` disables |
+| `SNAPNOTE_AUTO_INJECT` | `False` | Also add `snapnote.middleware.AutoInjectMiddleware` to `MIDDLEWARE` to insert the button automatically. Incompatible with strict CSP and streaming responses |
+
+Customise the look by overriding CSS variables on `#snapnote-root`
+(`--snapnote-accent`, `--snapnote-accent-text`, `--snapnote-z-index`, `--snapnote-font`).
+
+## Permissions
+
+Reporting follows `SNAPNOTE_CAN_REPORT`. Managing uses the model permissions
+`snapnote.view_ticket`, `change_ticket` and `delete_ticket` (superusers have them all).
+Anonymous users are redirected to `LOGIN_URL`; authenticated users without permission get 403.
+
+## Notifiers
+
+The signal `snapnote.signals.ticket_created(sender, ticket, request_url)` is sent after commit.
+A notifier is any callable; a failing one is logged and never breaks the report:
+
+```python
+# myproject/notifiers.py — Slack recipe
+import requests
+def slack(ticket, url):
+    requests.post(settings.SLACK_WEBHOOK, json={"text": f"New ticket: {ticket.title} {url}"}, timeout=5)
+
+SNAPNOTE_NOTIFIERS = ["snapnote.notifiers.email", "myproject.notifiers.slack"]
+```
+
+## Security and deployment notes
+
+- **Screenshots can contain sensitive data.** Serve `MEDIA_ROOT` only to authenticated staff (or use a
+  private storage); do not expose it publicly. Purge old reports with
+  `python manage.py snapnote_purge --older-than 90` (`--dry-run` to preview).
+- **Permissions-Policy**: the browser needs `display-capture=(self)`. With `display-capture=()`
+  (also sent by some proxies) capture never works and users get the upload fallback.
+- **CSP**: allow `img-src blob: data:` and `style-src 'unsafe-inline'` (the Shadow DOM stylesheet
+  is inline) and `script-src` for the static bundle.
+- Uploads are validated (PNG/JPEG/WebP only, no SVG), size/dimension limited and re-encoded with Pillow.
+- `page_url` must be http(s) and is never rendered as a clickable link otherwise.
+- The report endpoint uses Django's CSRF protection; the template tag sets the cookie.
+- Capture uses `getDisplayMedia` (desktop browsers). On mobile the user attaches an image.
+
+## Development
+
+```bash
+pip install -e . pytest pytest-django
+pytest                      # SQLite; SNAPNOTE_TEST_DB=postgres for PostgreSQL
+cd frontend && npm ci && npm run build   # writes src/snapnote/static/snapnote/snapnote.js
+npm test && npm run e2e
+```
+
+The built `snapnote.js` is committed/packaged so installing the wheel never needs Node.

django_snapnote-0.1.1/frontend/e2e/smoke.mjs

@@ -0,0 +1,107 @@
+// Browser smoke test. Run from frontend/: npm run e2e (needs the Python venv at ../.venv
+// and a Chrome/Chromium; set CHROME_PATH or let Playwright use channel "chrome").
+import { spawn, execFileSync } from 'node:child_process';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { chromium } from 'playwright';
+
+const root = new URL('../..', import.meta.url).pathname;
+const python = join(root, '.venv/bin/python');
+const dir = mkdtempSync(join(tmpdir(), 'snapnote-e2e-'));
+const env = {
+  ...process.env,
+  SNAPNOTE_E2E: '1',
+  SNAPNOTE_E2E_DB: join(dir, 'db.sqlite3'),
+  DJANGO_SETTINGS_MODULE: 'tests.testproject.settings',
+  PYTHONPATH: root,
+};
+const PORT = 8765;
+const base = `http://127.0.0.1:${PORT}`;
+
+execFileSync(python, ['-m', 'django', 'migrate', '-v0'], { env, cwd: root });
+const server = spawn(python, ['-m', 'django', 'runserver', `${PORT}`, '--noreload'], {
+  env, cwd: root, stdio: 'ignore',
+});
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+for (let i = 0; i < 50; i++) {
+  try { await fetch(base); break; } catch { await sleep(200); }
+}
+
+const results = [];
+const check = (name, ok) => { results.push([name, ok]); console.log(`${ok ? 'PASS' : 'FAIL'} ${name}`); };
+
+// Stubs getDisplayMedia with a canvas stream (the real share prompt can't be automated).
+const STUB = `
+  navigator.mediaDevices.getDisplayMedia = async () => {
+    const c = document.createElement('canvas'); c.width = 640; c.height = 360;
+    const x = c.getContext('2d'); x.fillStyle = '#2b6cb0'; x.fillRect(0, 0, 640, 360);
+    setInterval(() => x.fillRect(0, 0, 640, 360), 50);
+    return c.captureStream(20);
+  };`;
+
+async function scenario(browser, { capture }) {
+  const label = capture ? 'with capture' : 'without getDisplayMedia';
+  const context = await browser.newContext({ viewport: { width: 1000, height: 700 } });
+  const page = await context.newPage();
+  await page.addInitScript(capture ? STUB : "Object.defineProperty(navigator.mediaDevices, 'getDisplayMedia', { value: undefined });");
+  await page.goto(`${base}/e2e-login/`);
+  const fab = page.locator('#snapnote-root .snapnote-fab');
+  await fab.waitFor();
+  check(`${label}: button renders inside shadow DOM`, (await fab.count()) === 1);
+  await fab.click();
+
+  const title = `E2E ${label}`;
+  if (capture) {
+    await page.locator('.snapnote-editor').waitFor();
+    const canvas = page.locator('.snapnote-editor-canvas');
+    await canvas.waitFor();
+    const box = await canvas.boundingBox();
+    await page.mouse.move(box.x + 100, box.y + 100);
+    await page.mouse.down();
+    await page.mouse.move(box.x + 250, box.y + 180, { steps: 5 });
+    await page.mouse.up();
+    await page.getByRole('button', { name: 'Done' }).click();
+    check(`${label}: file input hidden when capture worked`, (await page.locator('input[type=file]').count()) === 0);
+    check(`${label}: annotations layer previewed`, (await page.locator('.snapnote-preview-annotations').count()) === 1);
+  } else {
+    await page.locator('input[type=file]').waitFor();
+    check(`${label}: file input shown`, true);
+    const { writeFileSync } = await import('node:fs');
+    const png = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mP8z8BQz0AEYBxVSF+FABJADveWkH6oAAAAAElFTkSuQmCC', 'base64');
+    const file = join(dir, 'm.png'); writeFileSync(file, png);
+    await page.locator('input[type=file]').setInputFiles(file);
+    await page.locator('.snapnote-editor-canvas').waitFor();
+    await page.getByRole('button', { name: 'Done' }).click();
+    check(`${label}: uploaded image reaches the preview`, (await page.locator('.snapnote-preview img').count()) >= 1);
+  }
+  await page.locator('.snapnote-field input:not([type=file])').first().fill(title);
+  await page.getByRole('button', { name: 'Send' }).click();
+  await page.locator('.snapnote-toast').waitFor();
+  check(`${label}: success notice`, true);
+
+  await page.goto(`${base}/snapnote/`);
+  check(`${label}: ticket listed`, (await page.getByText(title).count()) === 1);
+  await page.getByText(title).click();
+  const imgs = await page.locator('.snapnote-shot-frame img').count();
+  check(`${label}: detail shows screenshot${capture ? ' + annotations' : ''}`, imgs === (capture ? 2 : 1));
+  if (capture) {
+    await page.locator('#snapnote-ann-toggle').uncheck();
+    check(`${label}: annotations switch hides layer`, !(await page.locator('.snapnote-annotations').isVisible()));
+  }
+  await context.close();
+}
+
+let browser;
+try {
+  browser = await chromium.launch({
+    channel: process.env.CHROME_PATH ? undefined : 'chrome',
+    executablePath: process.env.CHROME_PATH,
+  });
+  await scenario(browser, { capture: true });
+  await scenario(browser, { capture: false });
+} finally {
+  await browser?.close();
+  server.kill();
+}
+process.exit(results.every(([, ok]) => ok) ? 0 : 1);