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 §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 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

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, and the concrete delivered surface in SCOPE.md.