oss-clarity 0.1.2__tar.gz

oss_clarity-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,133 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install "ruff>=0.6"
+      - run: ruff check .
+      - run: ruff format --check .
+
+  # The core library must install and pass its tests with Django absent.
+  core:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e . pytest
+      - name: Django is not installed
+        run: python -c "import importlib.util, sys; sys.exit(importlib.util.find_spec('django') is not None)"
+      - run: pytest -q
+
+  django:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { django: "5.2", python: "3.11", db: sqlite }
+          - { django: "5.2", python: "3.12", db: sqlite }
+          - { django: "5.2", python: "3.13", db: sqlite }
+          - { django: "5.2", python: "3.14", db: sqlite }
+          - { django: "5.2", python: "3.14", db: postgres }
+          - { django: "6.0", python: "3.12", db: sqlite }
+          - { django: "6.0", python: "3.13", db: sqlite }
+          - { django: "6.0", python: "3.14", db: sqlite }
+          - { django: "6.0", python: "3.14", db: postgres }
+          - { django: "6.1", python: "3.12", db: sqlite }
+          - { django: "6.1", python: "3.13", db: sqlite }
+          - { django: "6.1", python: "3.14", db: sqlite }
+          - { django: "6.1", python: "3.14", db: postgres }
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: oc
+          POSTGRES_PASSWORD: oc
+          POSTGRES_DB: oc
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      DATABASE_URL: ${{ matrix.db == 'postgres' && 'postgres://oc:oc@localhost:5432/oc' || '' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      # The tracker tests run the served tracker in Node.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      - run: pip install -e ".[django,celery]" "Django~=${{ matrix.django }}.0" pytest pytest-django
+      - if: matrix.db == 'postgres'
+        run: pip install "psycopg[binary]>=3.2"
+      - run: python -m django --version
+      - run: pytest -q
+      - name: The example project passes its checks
+        working-directory: example
+        run: python manage.py check
+      - name: Migrations match the models
+        run: >-
+          PYTHONPATH=. DJANGO_SETTINGS_MODULE=tests.django.settings
+          django-admin makemigrations oss_clarity --check --dry-run
+
+  # The committed bundles must be exactly what the lockfile builds.
+  js:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: js
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: js/package-lock.json
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build
+      - name: Committed bundles match a fresh build
+        run: git diff --exit-code -- ../src/oss_clarity/static
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - name: The wheel carries the bundles, migrations, templates and notices
+        run: |
+          unzip -l dist/*.whl > contents.txt
+          for f in static/oss_clarity/recorder.js static/oss_clarity/player.js \
+                   static/oss_clarity/player.css migrations/0001_initial.py \
+                   templates/admin/oss_clarity/site/heatmap.html THIRD_PARTY_NOTICES.md; do
+            grep -q "$f" contents.txt || { echo "missing from wheel: $f"; exit 1; }
+          done

oss_clarity-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish
+
+# Pushing a version tag (v0.1.2) builds the release and uploads it to PyPI through a
+# trusted publisher: no API token is stored anywhere.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: The tag matches the package version
+        run: |
+          version=$(python -c "import re; print(re.search(r'__version__ = \"(.+)\"', open('src/oss_clarity/__init__.py').read())[1])")
+          [ "v$version" = "$GITHUB_REF_NAME" ] || { echo "tag $GITHUB_REF_NAME, version $version"; exit 1; }
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the environment on the PyPI trusted publisher.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/oss-clarity
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

oss_clarity-0.1.2/.gitignore

@@ -0,0 +1,28 @@
+# Private build brief — never committed.
+PLAN.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# JS
+node_modules/
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store
+
+# Example project
+example/db.sqlite3
+example/media/
+example/.cache/

oss_clarity-0.1.2/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+## 0.1.2 — 2026-09-27
+
+First release on PyPI.
+
+Changed
+
+- The README installs from PyPI, and its links and images point at the v0.1.2 tag on GitHub,
+  so they work on the PyPI project page.
+
+## 0.1.1 — 2026-09-26
+
+Fixed
+
+- The recorder lost the events buffered when a page was hidden or closed: it compressed
+  the last chunk before sending it, and a page going away gets no further turn for the
+  compression to finish. Up to five seconds at the end of every page were missing, and a
+  page left within five seconds of loading was missing from its recording altogether. The
+  recorder now sends as soon as the page is hidden or closed, uncompressed, in parts that fit
+  the browser's 64 KB keepalive budget. Chunks sent while the page stays open are still
+  gzipped. The recorder's URL carries a new digest, so browsers fetch the fixed bundle.
+- The example page sets its own background, so it stays readable when the browser prefers a
+  dark colour scheme.
+
+Added
+
+- `npm test` in `js/`: the recorder's uploads, run in Node with rrweb stubbed out. CI runs it.
+
+## 0.1.0 — 2026-09-26
+
+First release.
+
+- `oss_clarity.core`: rules-based signal analysis of rrweb recordings (`analyze`), frozen
+  `Thresholds`, quick backs and loops from page views (`navigation`), a user-agent classifier
+  with a bot test, and a threshold measuring tool (`measure`). No Django required.
+- Django app `oss_clarity`: models for sites, recording settings, hits, recordings and their
+  chunks, heatmap buckets, visit navigation and job runs, in one initial migration. No IP
+  address or raw user agent is stored.
+- `OSS_CLARITY` settings dict with defaults for every key, checked by `manage.py check`.
+- Admin: sites with their recording settings and refusal counters, read-only hits, recordings
+  filterable by signal, favourites, and job runs.
+- Public collector (`oss_clarity.urls.public`): the tracker script per site, the recorder
+  bundle under a content digest, page views, clicks and page leaves, and recording chunks
+  (gzip accepted). Host allow-list, crawler refusal for recordings, sampling by session-id
+  hash, size and session caps, and per-address, per-site and global rate limits. Every
+  refusal answers 204.
+- Client IP for rate limits resolved by `TRUSTED_PROXY_COUNT`, `CLIENT_IP_HEADER` or
+  `CLIENT_IP_FUNCTION`; used in memory only.
+- The tracker honours Global Privacy Control for recording, supports a consent gate, and
+  exposes `ossClarity("visitorId")` and `ossClarity("forget")`. Clicks carry position and a
+  selector only; credential-shaped query values are redacted before any URL is stored.
+- Recorder bundle built from `js/recorder` with esbuild; third-party notices in
+  `THIRD_PARTY_NOTICES.md`.
+- Optional `PublicEndpointsMiddleware` for hosts whose CORS or cache middleware would
+  override the public endpoints' headers.
+- Background jobs in `oss_clarity.jobs`: finalize and analyse quiet recordings, store visits'
+  quick backs and loops, roll up heatmaps per UTC day, and prune by retention window. Each
+  run is claimed in `JobRun` with one conditional update, so overlapping runs never repeat
+  a job. Run them with `manage.py oss_clarity_run_jobs` from cron, or the optional Celery
+  tasks and `BEAT_SCHEDULE` in `oss_clarity.tasks`.
+- Visitor erasure: `retention.erase_visitor`, `manage.py oss_clarity_erase_visitor` and an
+  admin action. Stored chunks are always deleted before rows; a failed delete keeps the rows
+  for the next run.
+- `manage.py oss_clarity_measure` reports how many signals each threshold setting would
+  find, with moments to watch. It writes nothing.
+- Recordings can be deleted from the admin, stored chunks first.
+- Read-only JSON API (`oss_clarity.urls.api`): recordings filterable by any-of signals and
+  favourites, one recording with its pages, a page's events, heatmap pages, one heatmap,
+  and sessions with quick backs and loops on every row. Staff only unless
+  `API_PERMISSION` says otherwise.
+- Admin viewer: a replay on each recording's page, with signals on the timeline and as a
+  list, and a heatmap page per site (page, device and range pickers; click and scroll-depth
+  maps drawn over the newest recorded snapshot of that page). Built from `js/player` on
+  rrweb's replayer, sandboxed without scripts.
+- The replay strips inline event handlers from recorded pages, and the heatmap
+  measures the rebuilt page only after it has been laid out.
+- Documentation (`docs/`), a README with the privacy stance, an example project, and CI
+  for lint, the core without Django, the Django × Python matrix on SQLite and PostgreSQL,
+  bundle reproducibility and the wheel's contents.
+

oss_clarity-0.1.2/LICENSE

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

oss_clarity-0.1.2/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: oss-clarity
+Version: 0.1.2
+Summary: Self-hosted session replay, heatmaps and rules-based behaviour signals for Django
+Project-URL: Homepage, https://github.com/meharaj-007/oss-clarity
+Project-URL: Documentation, https://github.com/meharaj-007/oss-clarity/tree/main/docs
+Project-URL: Changelog, https://github.com/meharaj-007/oss-clarity/blob/main/CHANGELOG.md
+Author: Meharaj Ul Mahmmud
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: analytics,django,heatmaps,privacy,rrweb,session-replay
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Provides-Extra: celery
+Requires-Dist: celery>=5.3; extra == 'celery'
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: celery>=5.3; extra == 'dev'
+Requires-Dist: pytest-django>=4.9; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=5.2; extra == 'django'
+Requires-Dist: rjsmin>=1.2; extra == 'django'
+Provides-Extra: s3
+Requires-Dist: django-storages[s3]>=1.14; extra == 's3'
+Description-Content-Type: text/markdown
+
+# oss-clarity
+
+Self-hosted session replay, heatmaps and rules-based behaviour signals for Django.
+
+Add one script tag to your site. oss-clarity counts page views, clicks and scroll
+depth, records sampled visits with [rrweb](https://github.com/rrweb-io/rrweb), and
+marks where people struggled: rage clicks, dead clicks, hesitations, form
+abandons and more. You watch the replays and heatmaps in your Django admin. Every
+byte stays on your servers.
+
+> Early release (0.1.2).
+> Settings and the JSON API may still change.
+
+![A replay in the Django admin, with signals on the timeline](https://raw.githubusercontent.com/meharaj-007/oss-clarity/v0.1.2/docs/images/replay.png)
+
+## What you get
+
+- **Tracking**: page views (including single-page-app route changes), clicks with
+  their position, and how far each page was scrolled. About 10 KB of JavaScript
+  (4 KB gzipped), reporting after the page loads, with no cookies.
+- **Recording**: sampled session replay, masked in the visitor's browser before
+  anything is sent. Capped per visit by size, pages and minutes.
+- **Signals**: 15 rules, each a documented, deterministic check with named
+  thresholds, and a tool to measure those thresholds against your own recordings.
+  See [signals](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/signals.md).
+- **Heatmaps**: clicks and scroll depth per page and device, drawn over a recorded
+  snapshot of the page.
+- **Viewer**: replay and heatmap pages inside Django admin, and a read-only
+  [JSON API](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/api.md).
+
+![Clicks on a page, drawn over a recorded snapshot](https://raw.githubusercontent.com/meharaj-007/oss-clarity/v0.1.2/docs/images/heatmap-clicks.png)
+
+## Privacy
+
+- **No AI.** Signals are plain rules you can read. Recordings are never sent to
+  any third party or model.
+- **Masked by default.** Form fields are masked in every mode and cannot be
+  unmasked. The default mode also blanks digits and email addresses, and `data:`
+  and `blob:` images (a photo a visitor just picked, say) are never recorded.
+- **Global Privacy Control is honoured.** A browser that sends it is never
+  recorded; its page views are still counted.
+- **Optional consent gate.** Per site, nothing is recorded until your page calls
+  `ossClarity("consent", true)`.
+- **No IP addresses stored.** The address is used in memory for rate limits only.
+  Raw user agents are not stored either, only coarse device, browser and OS.
+- **No text from clicks.** A click records where it landed and a selector for the
+  element, never the element's text or link. Password, token and similar values in
+  page URLs are replaced before storage.
+- **Crawlers are not recorded.** Bots that run JavaScript are refused by the
+  tracker and again by the collector.
+- **Erase on request.** `ossClarity("visitorId")` gives a visitor their id;
+  `manage.py oss_clarity_erase_visitor <id>` deletes everything held about them.
+  `ossClarity("forget")` clears the ids in their browser.
+- **Retention.** Hits and recordings are deleted after 30 days by default.
+
+## Install
+
+```sh
+pip install "oss-clarity[django]"
+```
+
+Python 3.11 to 3.14, Django 5.2, 6.0 and 6.1, SQLite or PostgreSQL.
+
+## Set up
+
+**1. Settings**
+
+```python
+INSTALLED_APPS = [..., "oss_clarity"]
+
+MIDDLEWARE = [
+    "oss_clarity.middleware.PublicEndpointsMiddleware",  # first
+    ...,
+]
+```
+
+The middleware is only needed if something else in your stack (django-cors-headers,
+a no-store cache policy) would override the public endpoints' headers. It is safe
+to always include. Every other setting has a default; see
+[settings](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/settings.md).
+
+**2. URLs**
+
+```python
+urlpatterns = [
+    ...,
+    path("oc/", include("oss_clarity.urls.public")),  # tracker and collector
+    path("oc-api/", include("oss_clarity.urls.api")),  # read-only API, optional
+]
+```
+
+Then `python manage.py migrate`.
+
+**3. Jobs**, every five minutes from cron (or use the
+[Celery tasks](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/jobs.md)):
+
+```cron
+*/5 * * * *  cd /srv/app && python manage.py oss_clarity_run_jobs
+```
+
+**4. The snippet.** Add a site in the admin (Session replay and heatmaps → Sites),
+switch recording on in its recording settings if you want replays, and paste the
+snippet it shows into your pages' `<head>`:
+
+```html
+<script async src="https://your-app.example.com/oc/t/<site key>.js"></script>
+```
+
+Visits appear as hits straight away. Recordings are analysed a few minutes after a
+visit ends, and heatmaps update hourly.
+
+To see it all working on your own machine first, run the
+[example project](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/example/README.md).
+
+## Documentation
+
+- [Signals](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/signals.md): what each one means
+- [Thresholds](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/thresholds.md): the numbers, and how to measure them
+- [Settings](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/settings.md): every key
+- [Storage](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/storage.md): local disk or S3
+- [Jobs](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/jobs.md): cron or Celery
+- [JSON API](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/api.md)
+- [Upgrading](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/upgrading.md)
+
+## Limits
+
+- One recording per visit, at most 10 MiB, 128 pages and 120 minutes by default.
+- Replays load images, fonts and styles from your live site, so ones changed or
+  removed since render differently.
+- Heatmaps group pages by path (query strings ignored, trailing slashes folded)
+  and by device class. Clicks are placed on the element when the snapshot still
+  has it, and by position otherwise.
+- Automated browsers (`navigator.webdriver`, headless Chrome) are treated as
+  crawlers and never recorded.
+- No multi-tenant accounts, billing or quotas: that is your project's business.
+
+## Development
+
+```sh
+pip install -e ".[django,dev]"
+pytest
+ruff check . && ruff format --check .
+cd js && npm ci && npm run typecheck && npm run build   # rebuilds the committed bundles
+```
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/LICENSE).
+The bundled rrweb and its dependencies are listed in
+[THIRD_PARTY_NOTICES.md](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/THIRD_PARTY_NOTICES.md).

oss_clarity-0.1.2/README.md

@@ -0,0 +1,150 @@
+# oss-clarity
+
+Self-hosted session replay, heatmaps and rules-based behaviour signals for Django.
+
+Add one script tag to your site. oss-clarity counts page views, clicks and scroll
+depth, records sampled visits with [rrweb](https://github.com/rrweb-io/rrweb), and
+marks where people struggled: rage clicks, dead clicks, hesitations, form
+abandons and more. You watch the replays and heatmaps in your Django admin. Every
+byte stays on your servers.
+
+> Early release (0.1.2).
+> Settings and the JSON API may still change.
+
+![A replay in the Django admin, with signals on the timeline](https://raw.githubusercontent.com/meharaj-007/oss-clarity/v0.1.2/docs/images/replay.png)
+
+## What you get
+
+- **Tracking**: page views (including single-page-app route changes), clicks with
+  their position, and how far each page was scrolled. About 10 KB of JavaScript
+  (4 KB gzipped), reporting after the page loads, with no cookies.
+- **Recording**: sampled session replay, masked in the visitor's browser before
+  anything is sent. Capped per visit by size, pages and minutes.
+- **Signals**: 15 rules, each a documented, deterministic check with named
+  thresholds, and a tool to measure those thresholds against your own recordings.
+  See [signals](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/signals.md).
+- **Heatmaps**: clicks and scroll depth per page and device, drawn over a recorded
+  snapshot of the page.
+- **Viewer**: replay and heatmap pages inside Django admin, and a read-only
+  [JSON API](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/api.md).
+
+![Clicks on a page, drawn over a recorded snapshot](https://raw.githubusercontent.com/meharaj-007/oss-clarity/v0.1.2/docs/images/heatmap-clicks.png)
+
+## Privacy
+
+- **No AI.** Signals are plain rules you can read. Recordings are never sent to
+  any third party or model.
+- **Masked by default.** Form fields are masked in every mode and cannot be
+  unmasked. The default mode also blanks digits and email addresses, and `data:`
+  and `blob:` images (a photo a visitor just picked, say) are never recorded.
+- **Global Privacy Control is honoured.** A browser that sends it is never
+  recorded; its page views are still counted.
+- **Optional consent gate.** Per site, nothing is recorded until your page calls
+  `ossClarity("consent", true)`.
+- **No IP addresses stored.** The address is used in memory for rate limits only.
+  Raw user agents are not stored either, only coarse device, browser and OS.
+- **No text from clicks.** A click records where it landed and a selector for the
+  element, never the element's text or link. Password, token and similar values in
+  page URLs are replaced before storage.
+- **Crawlers are not recorded.** Bots that run JavaScript are refused by the
+  tracker and again by the collector.
+- **Erase on request.** `ossClarity("visitorId")` gives a visitor their id;
+  `manage.py oss_clarity_erase_visitor <id>` deletes everything held about them.
+  `ossClarity("forget")` clears the ids in their browser.
+- **Retention.** Hits and recordings are deleted after 30 days by default.
+
+## Install
+
+```sh
+pip install "oss-clarity[django]"
+```
+
+Python 3.11 to 3.14, Django 5.2, 6.0 and 6.1, SQLite or PostgreSQL.
+
+## Set up
+
+**1. Settings**
+
+```python
+INSTALLED_APPS = [..., "oss_clarity"]
+
+MIDDLEWARE = [
+    "oss_clarity.middleware.PublicEndpointsMiddleware",  # first
+    ...,
+]
+```
+
+The middleware is only needed if something else in your stack (django-cors-headers,
+a no-store cache policy) would override the public endpoints' headers. It is safe
+to always include. Every other setting has a default; see
+[settings](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/settings.md).
+
+**2. URLs**
+
+```python
+urlpatterns = [
+    ...,
+    path("oc/", include("oss_clarity.urls.public")),  # tracker and collector
+    path("oc-api/", include("oss_clarity.urls.api")),  # read-only API, optional
+]
+```
+
+Then `python manage.py migrate`.
+
+**3. Jobs**, every five minutes from cron (or use the
+[Celery tasks](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/jobs.md)):
+
+```cron
+*/5 * * * *  cd /srv/app && python manage.py oss_clarity_run_jobs
+```
+
+**4. The snippet.** Add a site in the admin (Session replay and heatmaps → Sites),
+switch recording on in its recording settings if you want replays, and paste the
+snippet it shows into your pages' `<head>`:
+
+```html
+<script async src="https://your-app.example.com/oc/t/<site key>.js"></script>
+```
+
+Visits appear as hits straight away. Recordings are analysed a few minutes after a
+visit ends, and heatmaps update hourly.
+
+To see it all working on your own machine first, run the
+[example project](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/example/README.md).
+
+## Documentation
+
+- [Signals](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/signals.md): what each one means
+- [Thresholds](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/thresholds.md): the numbers, and how to measure them
+- [Settings](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/settings.md): every key
+- [Storage](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/storage.md): local disk or S3
+- [Jobs](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/jobs.md): cron or Celery
+- [JSON API](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/api.md)
+- [Upgrading](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/docs/upgrading.md)
+
+## Limits
+
+- One recording per visit, at most 10 MiB, 128 pages and 120 minutes by default.
+- Replays load images, fonts and styles from your live site, so ones changed or
+  removed since render differently.
+- Heatmaps group pages by path (query strings ignored, trailing slashes folded)
+  and by device class. Clicks are placed on the element when the snapshot still
+  has it, and by position otherwise.
+- Automated browsers (`navigator.webdriver`, headless Chrome) are treated as
+  crawlers and never recorded.
+- No multi-tenant accounts, billing or quotas: that is your project's business.
+
+## Development
+
+```sh
+pip install -e ".[django,dev]"
+pytest
+ruff check . && ruff format --check .
+cd js && npm ci && npm run typecheck && npm run build   # rebuilds the committed bundles
+```
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/LICENSE).
+The bundled rrweb and its dependencies are listed in
+[THIRD_PARTY_NOTICES.md](https://github.com/meharaj-007/oss-clarity/blob/v0.1.2/THIRD_PARTY_NOTICES.md).