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).