binect-chrome/specs/ProductRequirementsDocument.md

BinectChromePrd

*Product Requirements Document*

# **Product Requirements Document (PRD)**

## **Project: BinectChrome**

---

> **Revision note — scope evolution (2026-06).**
> This PRD originally specified a minimal *detect → send* tool. The shipped
> implementation has grown into a **document-lifecycle** assistant: it not only
> uploads PDFs but tracks each one through its Binect server-side states
> (in-basket → ordered → in production → sent), reconciles local records against
> what Binect actually holds, and lets the user order and manage documents from
> the popup. Sections **4.3a (Document Lifecycle & Ordering)** and **4.6
> (Local Tracking)** below have been reconciled with this reality. The growth is
> in-scope **only** because it never violates the inviolable principles in
> [`INTENT.md`](../INTENT.md) §4 — in particular, the lifecycle is represented by
> *metadata proxies that never hold PDF content*, and every server action (upload,
> order, delete) remains user-initiated. The companion [`SCOPE.md`](../SCOPE.md)
> records exactly what is implemented today.

---

## 1. Product Overview

### 1.1 Purpose

**BinectChrome** is a Google Chrome extension that enables users to send PDF documents generated in arbitrary cloud applications directly to Binect for physical printing and postal delivery.

It eliminates the manual **download → upload** workflow by adding a lightweight, privacy-preserving integration layer in the browser — without requiring changes to the originating application (A).

---

### 1.2 Problem Statement

Users frequently generate PDF documents (letters, invoices, notices) in cloud applications that are **not integrated** with postal mail services.

Today, the workflow requires:

1. Downloading the PDF from application A
2. Uploading the PDF to application B (Binect)
3. Repeating this for every document

This causes friction, errors, and unnecessary time loss.

---

### 1.3 Solution Summary

BinectChrome:

* Detects PDF downloads (and supported in-browser PDF views)
* Offers a **“Send PDF to Binect”** action
* Securely transfers the PDF to Binect via its API
* Tracks each sent document through its Binect lifecycle (in-basket → ordered → in production → sent) and lets the user place the print/delivery **order** with explicit confirmation
* Reconciles local records against the documents Binect actually holds (server sync)
* Requires explicit user intent for every send, order, and delete
* Stores no PDF content — only lightweight metadata proxies
* Tracks transfers locally for transparency and support

---

## 2. Goals & Non-Goals

### 2.1 Goals

* Reduce friction when sending PDFs to physical mail
* Require **no integration changes** in source systems (A)
* Preserve user privacy and trust
* Be simple, reliable, and auditable
* Minimize permissions and attack surface

### 2.2 Non-Goals

* No automation or RPA of third-party websites
* No shared identity or credential federation
* No document content storage or analysis
* No backend relay service
* No multi-browser support in v1 (Chrome only)

---

## 3. Target Users

* Business users producing PDFs in cloud applications
* Office workers sending recurring physical mail
* Compliance-conscious users who require explicit control
* Chrome-based desktop workflows

---

## 4. Functional Requirements

### 4.1 PDF Detection

#### 4.1.1 PDF Downloads (MUST)

* Detect completed PDF downloads using Chrome Downloads API
* Identification via:

  * `.pdf` filename extension
  * or response headers (`Content-Type: application/pdf`)

#### 4.1.2 PDF Viewed in Browser (SHOULD)

* Detect navigation to resources with `Content-Type: application/pdf`
* Applies when PDFs are loaded as normal URLs

**Accepted limitation:**
PDFs rendered via blob URLs or complex JavaScript viewers may not be detectable or retrievable.

---

### 4.2 User Interaction & Sending

#### 4.2.1 Toolbar & Popup (MUST)

* Chrome toolbar icon opens popup
* Popup shows:

  * Last detected PDF (filename, size, timestamp, source domain)
  * Primary action: **Send PDF to Binect**

#### 4.2.2 Explicit User Intent (MUST)

* PDFs are only sent after a deliberate user click
* No automatic sending by default

---

### 4.3 PDF Transfer

#### 4.3.1 PDF Acquisition (MUST for downloads)

* Extension retrieves PDF bytes for transfer:

  * Prefer re-fetching from original URL using user session
  * Fallback mechanisms may be implemented as needed

#### 4.3.2 Upload to Binect (MUST)

* Transfer PDF to Binect via official API
* Show clear progress and result states:

  * Uploading
  * Success
  * Failure (with actionable error message)

---

### 4.3a Document Lifecycle & Ordering

*(Added in the 2026-06 reconciliation. Distinguishes "uploaded to Binect" from
"actually sent as physical mail," which the original PRD conflated.)*

#### 4.3a.1 Document Proxies (MUST)

* Each detected/sent PDF is represented locally by a **proxy**: a metadata-only
  record (filename, size, source, content hash, Binect document ID, status). The
  proxy **never contains PDF content**.
* Proxies are deduplicated by filename + content hash so the same document is not
  tracked twice.

#### 4.3a.2 Lifecycle States (MUST)

* A proxy carries a status mirroring the Binect server lifecycle:
  `pending` → `uploading` → `in_basket` (uploaded, shippable) → `ordering` →
  `in_production` → `sent`, plus the off-path states `failed` and `canceled`.
* The popup groups documents by lifecycle stage and shows the current status,
  price (when known), and recipient where available.

#### 4.3a.3 Ordering / Dispatch (MUST)

* Uploading a PDF places it in the Binect **basket** (shippable) but does **not**
  send physical mail.
* Physically sending requires a **separate, explicit user action** ("order") with
  clear confirmation, because dispatch costs money and is irreversible.

#### 4.3a.4 Erroneous Documents (SHOULD)

* If Binect reports a document as erroneous, the extension surfaces the error and
  offers to refresh its status (the server may resolve it) or delete it.

#### 4.3a.5 Status Refresh & Server Sync (SHOULD)

* The user can refresh a document's status on demand.
* The extension can **sync from the server**: list the documents Binect actually
  holds and reconcile them with local proxies — adopting server-discovered
  documents, updating statuses, and clearing server fields for documents deleted
  upstream.

#### 4.3a.6 Server-Side Deletion (MUST for delete actions)

* Deleting a document from Binect requires explicit user action; on success the
  local proxy is archived rather than silently dropped.

---

### 4.4 Authentication & Credential Handling

#### 4.4.1 Authentication Method (MUST)

* Username + password authentication to Binect API

#### 4.4.2 Secure Storage (MUST)

* Credentials stored encrypted at rest in extension storage
* Decrypted credentials only held in memory during use

#### 4.4.3 Retention Policy (MUST)

* Credentials retained for **60 days since last successful use**
* “Use” = successful authentication or successful send
* After 60 days of inactivity:

  * Credentials are automatically deleted
  * User must re-enter credentials

#### 4.4.4 Manual Controls (MUST)

* User can manually wipe stored credentials at any time
* Optional “Lock now” to clear decrypted credentials from memory

---

### 4.5 Privacy & Data Handling

#### 4.5.1 PDF Content (MUST)

* Extension never stores PDF files
* Extension never reports PDF content
* PDFs are only transmitted to Binect upon explicit send

#### 4.5.2 Metadata Minimization (MUST)

* No content inspection
* No filename persistence required
* Only filesize and technical metadata are tracked

---

### 4.6 Local Tracking (“Score”)

#### 4.6.1 Tracking Scope (MUST)

Tracking data stored **locally only**:

* Timestamp
* Source A identifier (URL or domain)
* Destination B URL
* PDF filesize
* Result (success / failure + error class)

#### 4.6.2 Tracking Access (MUST)

* Tracking view accessible via **“?” Info/Help** link in popup
* Shows:

  * Summary counts
  * Chronological list of transfers

#### 4.6.3 Retention (SHOULD)

* Cap number of entries to prevent unbounded growth.
* **Two distinct stores exist** after the lifecycle reconciliation, each capped
  independently:

  * **Document proxy queue** (active lifecycle records): live vs. archived views;
    archived proxies age out after ~30 days; capped at ~100 entries.
  * **Tracking log** ("Score", append-only transfer events for transparency/CSV
    export): capped at the last ~500 events.

  *(The original PRD named a single "≤ 500 events" cap. The implementation
  splits short-lived lifecycle proxies from the long-lived transfer log; the
  numbers above reflect the shipped behavior and may be tuned.)*

---

### 4.7 Feature Requests & Feedback

#### 4.7.1 Feedback Mechanism (MUST)

* “Request features / report issue” link
* Opens email draft to:
  **[bernd.worsch@binect.de](mailto:bernd.worsch@binect.de)**

#### 4.7.2 Tracking Export (MUST)

* Tracking data prepared as CSV
* CSV data:

  * Embedded in email body and/or
  * Copied to clipboard automatically
* Optional “Download CSV” button

**Note:**
Direct file attachments via `mailto:` are not reliably supported by browsers and are therefore not required.

---

## 5. Installation & Distribution

### 5.1 Distribution Channel (MUST)

* Automated publication via **Chrome Web Store**

### 5.2 Installation Requirements

* Chrome browser (desktop)
* User installs extension from Chrome Web Store
* User grants required permissions explicitly

### 5.3 Permissions (Principle of Least Privilege)

Expected permissions include:

* `downloads`
* `storage`
* `activeTab` (optional)
* Host permission for Binect API endpoint

---

## 6. Deinstallation & Cleanup

### 6.1 User-Initiated Deinstallation (MUST)

* When extension is removed:

  * All stored credentials are deleted
  * All local tracking data is deleted
  * No data remains outside the browser

### 6.2 No External State (MUST)

* No server-side state tied to installation
* No orphaned accounts or tokens

---

## 7. Technical Constraints

* Chrome Extension Manifest V3
* No background persistence beyond service worker lifecycle
* No external backend services
* No cross-browser guarantees in v1

---

## 8. Security Considerations

* Encrypted credential storage
* No silent background transfers
* Clear user confirmation before sending
* No hidden data flows
* Minimal permissions to pass Chrome Web Store review

---

## 9. Success Metrics

* Reduction in manual upload steps
* Successful sends per active user
* Low error rate
* No privacy or security incidents
* Positive user feedback via feature request channel

---

## 10. Future Considerations (Out of Scope for v1)

* Multi-profile destinations
* Rule-based automation (opt-in)
* Multi-browser support (Firefox, Edge)
* Token-based authentication (if API evolves)
* Organization-level deployment policies

---

**BinectChrome** is intentionally focused in scope:
a trustworthy bridge between modern cloud software and physical mail —
implemented where the user already works: the browser. It has grown from a pure
*detect → send* tool into one that also follows each document through its Binect
lifecycle, but it has not crossed its founding boundaries: no stored documents,
no backend, no automatic dispatch. Those boundaries are recorded as inviolable
principles in [`INTENT.md`](../INTENT.md), and the concrete delivered surface in
[`SCOPE.md`](../SCOPE.md).