@adpharm/docsafe-search

A plug-and-play React component library and backend utility for integrating DocSafe's AI-powered vector search and PDF citation highlighting directly into your application.

This package uses a "Dumb UI, Smart Server" architecture. It provides beautiful React components for your frontend and a secure search utility for your backend, ensuring your API keys are never exposed to the browser.

Installation

npm install @adpharm/docsafe-search
# or
bun add @adpharm/docsafe-search

1. Prerequisites (Environment Variables)

Your host application's backend must have the following environment variables set:

OPENAI_API_KEY=your_openai_key
DOCSAFE_API_KEY=your_docsafe_db_key
# DOCSAFE_DB_URL=https://db.docsafe-search.adpharm.digital (Optional: defaults to production)

2. Styling

The components are self-styling — no stylesheet import, no Tailwind setup, no wrapper required. Drop them in and they render with sensible defaults.

To match your app's brand, pass a theme prop. Every field is optional and merges over the defaults:

<SearchBar
  projectId="..."
  onSearch={handleSearch}
  theme={{
    colors: {
      primary: "#7c3aed",
      primaryHover: "#6d28d9",
    },
    radius: { lg: "0.75rem" },
    fontFamily: "Inter, sans-serif",
  }}
/>

The same theme prop is accepted by SearchBar, ResultsPage, and PdfViewer. By default fontFamily is "inherit", so typography picks up your host application automatically.

The full default theme is exported as defaultTheme and its shape as DocSafeTheme if you want to derive your own.

3. Backend Implementation

Create an API route in your host application to securely handle the vector search and LLM generation.

Example (Next.js App Router - app/api/search/route.ts):

import { runDocSafeSearch } from "@adpharm/docsafe-search/server";

export async function POST(req: Request) {
  try {
    const { query, projectId } = await req.json();

    // This utility automatically reads your .env variables, performs the vector
    // search, and asks OpenAI to generate an answer with citations.
    const searchResults = await runDocSafeSearch(query, projectId);

    return Response.json(searchResults);
  } catch (error: any) {
    return Response.json({ error: error.message }, { status: 500 });
  }
}

4. Frontend Implementation

Use the exported UI components to build your search interface.

Example (React / Next.js Client Component):

"use client";

import { useState } from "react";
import {
  SearchBar,
  ResultsPage,
  SearchResultData,
} from "@adpharm/docsafe-search";

export default function DocumentSearch() {
  const [data, setData] = useState<SearchResultData | null>(null);
  const [isLoading, setIsLoading] = useState(false);
  const [query, setQuery] = useState("");
  const [error, setError] = useState<string>();

  const handleSearch = async (searchQuery: string, projectId: string) => {
    setIsLoading(true);
    setQuery(searchQuery);
    setError(undefined);

    try {
      // Call your secure backend route
      const response = await fetch("/api/search", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ query: searchQuery, projectId }),
      });

      if (!response.ok) throw new Error("Search failed");

      const resultData = await response.json();
      setData(resultData);
    } catch (err: any) {
      setError(err.message);
    } finally {
      setIsLoading(false);
    }
  };

  // If we have data (or are loading data), show the Results layout.
  // ResultsPage fills its parent — wrap it in a full-height container.
  if (data || isLoading) {
    return (
      <div style={{ height: "100vh" }}>
        <ResultsPage
          query={query}
          isLoading={isLoading}
          data={data}
          error={error}
        />
      </div>
    );
  }

  // Otherwise, show the initial Search Bar
  return (
    <div className="flex items-center justify-center min-h-screen p-8">
      <div className="w-full max-w-3xl">
        <h1 className="text-3xl font-bold mb-8 text-center">
          Search Clinical Guidelines
        </h1>
        <SearchBar projectId="your-project-uuid-here" onSearch={handleSearch} />
      </div>
    </div>
  );
}

5. Opening the PDF Viewer Directly (Without a Search)

Sometimes the host application already knows which document the user wants to see — for example, opening a file from a library list, an email link, or a bookmarked citation. For these cases the viewer can be driven imperatively, completely independent of the search flow.

Option A — usePdfViewer hook (recommended)

The hook exposes an openDocument(...) function and a viewer node you render wherever you want the PDF to appear (full page, drawer, modal, etc.).

"use client";

import { usePdfViewer } from "@adpharm/docsafe-search";

export function DocumentLibrary({ docs }: { docs: { url: string; name: string }[] }) {
  const { openDocument, close, viewer, isOpen } = usePdfViewer();

  return (
    <div className="flex h-screen">
      <ul className="w-64 border-r">
        {docs.map((d) => (
          <li key={d.url}>
            <button
              onClick={() =>
                openDocument({
                  pdf_url: d.url,
                  document_name: d.name,
                  initial_page: 1, // optional
                })
              }
            >
              {d.name}
            </button>
          </li>
        ))}
      </ul>

      <main className="flex-1 relative">
        {isOpen ? (
          <>
            <button onClick={close} className="absolute top-2 right-2 z-10">Close</button>
            {viewer}
          </>
        ) : (
          <p>Select a document</p>
        )}
      </main>
    </div>
  );
}

Option B — Render <PdfViewer /> directly with a document prop

If you'd rather manage the open document in your own state, pass it straight to the component:

import { PdfViewer, type PdfDocument } from "@adpharm/docsafe-search";

<PdfViewer
  document={{
    pdf_url: "https://...",
    document_name: "Product Monograph.pdf",
    initial_page: 4,
  }}
/>

PdfViewer accepts either document (citation-free mode) or activeCitation (citation-driven mode), but not both.

6. Asking Questions Inside an Open Document

When the user is already looking at a specific document, they often want to query within it rather than across the whole project. Pass an onAskQuestion callback to <PdfViewer /> (or to usePdfViewer) and the viewer renders a collapsible side panel: the user types a question, your backend runs a document-scoped vector search, and the returned citations are highlighted on the PDF.

import { usePdfViewer } from "@adpharm/docsafe-search";

const { openDocument, viewer } = usePdfViewer({
  onAskQuestion: async (query, document) => {
    const res = await fetch("/api/search-in-document", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ query, documentId: document.document_id }),
    });
    return res.json();
  },
});

The backend route should call the document-scoped server utility:

import { runDocSafeSearchInDocument } from "@adpharm/docsafe-search/server";

export async function POST(req: Request) {
  const { query, documentId } = await req.json();
  return Response.json(await runDocSafeSearchInDocument(query, documentId));
}

When opening a document, include its document_id so the callback can scope the search:

openDocument({
  pdf_url: doc.pdf_url,
  document_name: doc.title,
  document_id: doc.id,
});

7. Listing a Project's Documents

For building document-library UIs, the server exports getHcpResources and getPatientResources, which return each document with a presigned pdf_url and thumbnail_url:

import {
  getHcpResources,
  getPatientResources,
  type Resource,
} from "@adpharm/docsafe-search/server";

const hcpDocs: Resource[] = await getHcpResources(projectId);
const patientDocs: Resource[] = await getPatientResources(projectId);

Each Resource includes id, title, pdf_url, thumbnail_url, audience ("hcp" | "patient"), and language ("en" | "fr").