DOCSEARCHbyAlgolia
Submit Docs

SimplePDF Embed

repository·main·Indexed 19 days ago

https://github.com/simplepdf/simplepdf-embed

A client-side PDF editor for web applications designed for privacy-sensitive use cases. It supports white-labeling, bring-your-own-storage (S3, Azure, SharePoint), and AI-driven agentic control. The package includes a Bubble.io plugin for embedding the editor and a reference implementation called SimplePDF Copilot, which integrates an AI chat sidebar using a postMessage bridge to control editor tools such as field detection, page management, and document submission.

Tokens
46.4K
Snippets
142
Records
215
Agent score
61%

What's inside simplepdf-embed

  1. Overview of SimplePDF Copilot

    main

    SimplePDF Copilot is an MIT-licensed reference implementation that integrates an AI chat sidebar with the SimplePDF editor. It allows an AI assistant to interact with PDF documents by reading content, filling form fields, navigating pages, and submitting the PDF via the SimplePDF iframe postMessage bridge.

    To use this in your own product, you can fork the repository, provide your own companyIdentifier, and wire up your preferred AI provider. This avoids the need to manually implement the iframe bridge, tool plumbing, or chat streaming logic.

  2. Handle Outbound Events: PAGE_FOCUSED and SUBMISSION_SENT

    main

    The editor pushes outbound events to notify the host of user actions or state changes:

    • PAGE_FOCUSED: Pushed when the focused page changes (e.g., the user scrolls to a new page or a goTo operation completes). The payload contains the current page.
    • SUBMISSION_SENT: Pushed after a SUBMIT operation completes successfully. Since the SUBMIT operation itself resolves with data: null, you must listen for this event to retrieve the resulting document_id and submission_id.

  3. Configure SimplePDF account features

    main

    The plugin functions with or without a SimplePDF account, but the capabilities differ:

    Without an account

    • Visitors can fill in documents and download the resulting PDFs.
    • All core features are available for free.

    With an account (requires "Company Identifier")

    • Automatic Transmission: Filled-in documents are automatically sent to you.
    • Notifications: You can configure the system to send you email notifications when documents are completed.
    • Custom Branding: You can use your own logo and custom loading animations.

  4. How voice input (dictation) works in SimplePDF Copilot

    main

    Voice input is a deliberate audio egress. When a user records a clip and confirms it (✓), the clip is transcribed. There are two distinct paths for audio data:

    1. Demo Mode (Server-side): If the deployment uses operator keys, the audio clip uploads to /api/transcribe, which forwards it to OpenAI (gpt-4o-transcribe). In this mode, audio leaves the browser to SimplePDF's server and then to OpenAI. The server does not keep the audio or logs.
    2. BYOK Mode (Browser-direct): If a Speech-to-Text provider (OpenAI or a custom OpenAI-compatible endpoint) is configured in the model picker's Speech-to-Text tab, the clip is sent directly from the browser to that endpoint. The audio never touches SimplePDF's servers. The API key is stored in an encrypted vault within the browser.

    Note: PDF bytes always stay on-device, and audio is only sent upon user confirmation.

  5. How SimplePDF architecture works

    main

    SimplePDF uses a fully client-side architecture for PDF processing to ensure privacy, security, and performance.

    Core Workflow

    1. Your App communicates with the SimplePDF Iframe via postMessage events.
    2. PDF editing and filling occurs entirely within the user's browser.
    3. (Paid plans only) If enabled, submissions are sent to SimplePDF servers or directly to your own storage (S3/Azure/SharePoint).

    Key Benefits

    • Privacy: Documents never leave the browser in the free tier.
    • Security: No server-side attack surface for document processing.
    • Performance: No upload/download latency during editing.
    • Offline Capable: Works without internet after the initial load.

    Limitations to Consider

    • No server-side PDF generation: You cannot generate PDFs from templates on your server; use client-side field detection via detectFields() instead.
    • No bulk processing: Cannot process multiple PDFs in a batch.
    • No programmatic PDF retrieval: You cannot get the modified PDF as a Blob/Base64 directly in JS; use webhooks + server storage for programmatic access.
    • No persistent storage: PDFs do not persist without user action unless using a paid plan.

  6. Handle Bridge results and errors

    main

    Most actions return a BridgeResult<TData>, which is a discriminated union representing success or failure.

    Structure of BridgeResult:

    • Success: { success: true, data: TData }
    • Failure: { success: false, error: BridgeError }

    Error Handling:

    • Use the unwrap(result) utility to extract data from a successful result. If the result is a failure, unwrap will throw a BridgeUnwrapError containing the original BridgeError.
    • BridgeError contains a code and a message. Common error codes include bad_request:missing_required_fields, unexpected:timeout, and unexpected:iframe_not_mounted.
    const result = await embed.actions.detectFields();

try {
  const count = unwrap(result);
  console.log(`Detected ${count} fields`);
} catch (e) {
  if (e instanceof BridgeUnwrapError) {
    console.error('Action failed:', e.error.code, e.error.message);
  }
}

  7. Compare SimplePDF plugin usage with and without an account

    main

    The plugin works without a SimplePDF account, but an account unlocks automated workflows:

    Without an account

    • Visitors can fill in documents, add text, checkboxes, pictures, and signatures.
    • Visitors can edit PDFs (merge, rotate, delete pages).
    • Visitors can download the resulting PDF.

    With an account (requires "Company Identifier")

    • Automatic Transmission: Filled-in documents are automatically sent to you.
    • Notifications: You can configure the plugin to send you email notifications when documents are completed.
    • Custom Branding: You can use your own logo and custom loading animations.

  8. How the EmbedPDF component modes work

    main

    The EmbedPDF component operates in two primary modes:

    1. Modal mode (default): The editor opens in a modal when the user clicks on the children provided to the component. You do not need to specify mode="modal" explicitly.
    2. Inline mode: The editor is rendered directly within your application's layout. This requires providing a document and usually a style or className to define its dimensions.

    Viewer mode: To disable editing features and provide a read-only experience, set the companyIdentifier prop to "react-viewer".

    // Modal mode (default)
<EmbedPDF>
  <button>Opens the editor</button>
</EmbedPDF>

// Inline mode
<EmbedPDF
  mode="inline"
  style={{ width: 900, height: 800 }}
  document={{ url: 'https://example.com/sample.pdf' }}
/>

// Viewer mode (read-only)
<EmbedPDF
  companyIdentifier="react-viewer"
  mode="inline"
  style={{ width: 900, height: 800 }}
  document={{ url: 'https://example.com/sample.pdf' }}
/>

  9. Programmatically control the SimplePDF editor

    main

    The @simplepdf/react-embed-pdf package provides the useEmbed hook, which allows you to interact with the PDF editor via code. This enables features like:

    • Triggering document submission.
    • Programmatically selecting specific tools (e.g., text, signatures, or checkboxes).
    • Managing document state from your own custom UI components.

  10. Understand the SimplePDF Copilot architecture and privacy model

    main

    SimplePDF Copilot is designed with a 'privacy by design' architecture that ensures sensitive document data remains under the user's control.

    Core Privacy Principles

    • Document data stays in the browser: SimplePDF processes PDFs client-side. The editor iframe never uploads document bytes to SimplePDF servers.
    • Chat traffic flows through your server: You control the AI provider, API keys, logs, and any RAG/internal data layers.
    • Submission is direct to your storage: On Premium with Bring Your Own Storage (BYOS) (S3, Azure Blob, or SharePoint), completed PDFs upload from the browser directly to your bucket, bypassing SimplePDF servers.

    Voice Input (Dictation) Exception

    Voice input is opt-in and involves sending audio clips out of the browser. There are two routes:

    1. Demo Route: Audio is uploaded to SimplePDF's server and then to OpenAI. SimplePDF does not keep audio or logs of transcript text.
    2. BYOK (Bring Your Own Key) Route: Audio is sent directly to your chosen provider, never to SimplePDF.

    Deployment Models

    • Demo Mode: Uses a shared companyIdentifier. The SimplePDF server acts as an LLM proxy to a hosted AI provider. The SimplePDF server only records telemetry and metadata.
    • Pro/Custom Mode: When forked to a Pro account, you host your own server, AI stack, and storage. The SimplePDF server only sees pre-signed upload URLs for metadata and never sees the actual document content.

  11. Configure Voice Input (Dictation)

    main

    Voice input requires both a Chat model and a Speech-to-Text (STT) provider. There are two ways to handle transcription:

    1. Demo (Server-side): If the deployment is in Demo Mode (configured via DEMO_STT_OPENAI_API_KEY), audio clips are sent to /api/transcribe on the operator's key. This is used when the operator wants to provide voice capabilities to visitors.
    2. BYOK (Browser-direct): Visitors can configure their own STT provider in the Model Picker's Speech-to-Text tab. Supported providers include OpenAI (gpt-4o-mini-transcribe or gpt-4o-transcribe) or any custom OpenAI-compatible endpoint. In this mode, audio is transcribed directly from the browser to the provider, bypassing the SimplePDF server entirely.

  12. Understand the SimplePDF data privacy model

    main

    SimplePDF Embed operates in two distinct modes based on your plan:

    Free Editor

    • Data Locality: All data stays in the browser; documents never leave the user's device.
    • Processing: Entirely client-side with no server communication.
    • Submissions: Not collected. Users can only download their work locally.
    • Branding: Includes "Powered by SimplePDF" branding.
    • Data Locality: Submissions can be stored on SimplePDF servers or in your own storage (S3, Azure Blob Storage, or SharePoint).
    • Automation: Supports webhooks for form automation (Basic plan+).
    • Customization: Supports white-labeling and headless mode (Pro plan+).
    • Compliance: BAA is available for healthcare customers.