Callback used by the OCR worker to push incremental, per-page results while a job is still being processed. It is not intended for end-user clients. The page is upserted into the BookTextPage collection keyed by (BookText, pageNumber), and the parent BookText is updated: status is set to "processing", metadata.pagesProcessed and metadata.lastPageUpdate are written, and pageCount is updated when provided. If no BookText exists for the jobId (an orphaned job) one is created with status "processing" and language "ar". When status is "failed" and an error string is supplied, the error is recorded in the BookText metadata.pageErrors array (replacing any existing entry for the same page number). No page credits are recorded by this endpoint.

Callback used by the OCR worker to post the final result of a job once processing finishes (or fails). It is not intended for end-user clients. The BookText for the jobId is updated (or created if the job is orphaned). If extractedText is longer than 10,000 characters it is uploaded to S3 as ocr-results/<jobId>.txt, metadata.textS3Key and metadata.textLength are set, and only a 1,000-character preview is kept in the database; shorter text is stored inline. Supplied metadata is merged into the existing metadata. Each entry in pages is upserted into the BookTextPage collection by pageNumber. Page-credit accounting happens here: when status is "completed" and the page count (pageCount, else pages.length, else the stored pageCount) is greater than 0, usage is recorded against the userId given in the body. Pages are first taken from the remaining monthly tier credits; any pages beyond that are billed immediately at $0.02/page through a Stripe invoice, and a usage log is written. Owners with the editor or admin role are never charged. The free/overage breakdown is saved to metadata.usageInfo. A failure while recording usage does not fail the request: it is stored in metadata.usageError and usageInfo is returned as null. Usage is recorded on every call that reports status "completed".

Starts the asynchronous OCR flow. Requires an active subscription (users with the editor or admin role bypass the subscription check); the check runs before the upload is parsed. The uploaded file is stored in S3 under ocr/<uuid>-<originalname>, a File record is created, a BookText is created with status "pending", and a job message (jobId, fileId, userId, S3 location, file name/type/size, language, customPrompt, metadata) is sent to the OCR SQS queue. The call returns immediately with the jobId: poll GET /ocr/status/:jobId until status is "completed" or "failed", then fetch the text with GET /ocr/text/:jobId or GET /ocr/books/:bookTextId. Having remaining credits is not required to upload: no credits are deducted at upload time. Pages are counted when the worker reports the job as completed; pages beyond the monthly tier credits are billed at $0.02/page. usageInfo in the response is a snapshot of the caller's credits at upload time (for editors/admins remainingCredits and tierCredits are null, meaning unlimited). Note that visibility is stored on the File record only; the BookText is always created private and can be made public with PATCH /ocr/books/:bookTextId. If the SQS send fails the request returns 500 although the File and pending BookText records have already been created.

Send the body as multipart/form-data.

Poll this endpoint after POST /ocr. Returns the job state without any text. status is one of pending, processing, completed, failed or submission_failed. hasFullText is true when the full text was large enough to be stored in S3. Only the user who created the job can view it; admins and editors can view any job.

Returns the full extracted text and every page of a job in a single response (pages are not paginated; use GET /ocr/books/:bookTextId for paginated pages with image URLs). If the full text was stored in S3 it is fetched and returned in extractedText instead of the truncated preview. Pages come from the BookTextPage collection sorted by pageNumber, falling back to the legacy embedded pages array for old documents. The endpoint does not check the job status, so text may be empty or partial while the job is still processing. Only the user who created the job can read it; admins and editors can read any job.

Returns the OCR jobs created by the authenticated user, newest first, with offset pagination. Always scoped to the caller, including for admins and editors.

Full-text search over OCR results, in two modes. Without bookTextId it searches across books (both the book-level extracted text and individual pages) and returns matching books, each with up to 5 match excerpts (pageNumber is null for a match in the book-level text). With bookTextId it searches the pages of that single book and returns the matching pages, including their full text, an excerpt, a highlightedExcerpt (search-engine highlight, or the excerpt with matches wrapped in <mark> tags) and a presigned page image URL valid for 1 hour. Visibility rules: anonymous callers only see public books; signed-in members see public books plus their own; admins and editors see everything. In single-book mode an inaccessible book returns 403 and a missing one 404. OpenSearch is used when enabled, with a case-insensitive MongoDB regex search as fallback when it is disabled or returns nothing. limit is capped at 50. In single-book mode total is the number of results in the returned page, not the overall match count.

Returns one digitized book with file details, owner, optional full text and a paginated slice of its pages. Public books are readable by anyone, including anonymous callers; private books only by their owner, admins and editors. The owner's userEmail, the source file's s3Key (the book-level s3Key) and the internal metadata object are only returned to the book's owner, admins and editors; for every other caller — including anonymous readers of a public book — those three keys are absent from the response. The example below shows the owner's view. The page-level s3Key inside pages[] is returned to every caller. When includeText is "true" the full text is returned in extractedText (fetched from S3 if it was stored there); any other value omits the field. Pages are sorted by pageNumber and paginated with pageLimit/pageOffset; totalPages and hasMore describe the pagination. Each page with an s3Key gets imageUrl, a presigned URL of the page image valid for 1 hour (null if there is no image or signing fails). Old documents without BookTextPage records fall back to the legacy embedded pages array.

Updates book details, visibility, text and/or pages. Only the owner of the book, editors and admins may update it. All fields are optional and only supplied fields change. fileName and author are written to the linked File record. visibility is only applied when it is "public" or "private" (other values are silently ignored). tags and categories accept an array or a comma-separated string. pages can be an array of page objects, each upserted by pageNumber (text defaults to empty, s3Key to null and isAIGenerated to true when omitted; pages not listed are left untouched), or an object keyed by page number for partial updates where only the supplied fields of each page change. The response returns a summary of the book without text or pages.

Lists digitized books with offset pagination, without text or pages. Visibility rules: anonymous callers only see public books; signed-in members see public books plus their own; admins and editors see all books. Each item includes the owner (userId, username) and hasFullText (true when the full text is stored in S3), which are always present. userEmail and the internal metadata object are only included on items whose book the caller owns, or on every item when the caller is an admin or editor; for other callers — including anonymous ones — those two keys are absent from the item. The example below shows an item as seen by its owner. Default order is newest first. The name_asc/name_desc sort options sort on the referenced file name at the database level, where the book only holds a reference to the file, so they do not reliably order by name.

Creates a new Book (the bilingual, line-based format used by the /books API) from a digitized book. Every OCR page becomes one line with the page text in the Arabic field and empty English, commentary and rootwords fields. The new book takes its title from the file name and its author from the file, is owned by the caller, and records metadata.importedFromVision = bookTextId. Only the owner of the digitized book, editors and admins may import it. Callers who are not editors or admins must additionally have an active Stripe subscription on the $50/month tier, otherwise 403 with error "subscription_required" is returned. The request has no body.

Generates a .docx file from all pages of a digitized book (sorted by page number) and returns it as a download. Only the owner of the book, editors and admins may export it; a public book cannot be exported by other users. Callers who are not editors or admins must also have an active subscription (checked before the book is looked up). The document is laid out right-to-left with an Arabic font when the book language is ar, ur, fa or he, otherwise left-to-right. Options control an optional title page (file name, author, language, page count, creation date), a "Page N" heading before each page, whether each page starts on a new page, and the body font size.