API Integration Specification

openapi: 3.0.3
info:
  title: YourOwnPDF.com Web Navigation API
  description: >
    YourOwnPDF is a 100% client-side web application suite for PDF and image editing.
    It does not contain backend server endpoints for processing files. All file operations
    occur in memory inside the user's browser tab using WebAssembly and client-side JavaScript.
    
    This specification documents the semantic routes and deep-linking parameters of the SPA
    so that AI agents, crawlers, and assistant tools can direct users to the appropriate tools.
  version: 1.1.0
servers:
  - url: https://yourownpdf.com
    description: Production environment
paths:
  /:
    get:
      summary: Get Homepage / Tools Grid
      description: Returns the main homepage listing all 40+ offline PDF and Image processing utility cards.
      parameters:
        - name: search
          in: query
          description: Pre-filter the tools grid by search queries (e.g., "compress", "merge").
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Main HTML page loaded, displaying filtered or complete list of client-side tools.

  /how-to-use:
    get:
      summary: Beginner guide page
      description: Returns the guide showing client-side mockups of how to upload, adjust settings, and download outputs safely.
      responses:
        '200':
          description: Guide page rendered successfully.

  /api:
    get:
      summary: API & Developer specs page
      description: Returns this API documentation and YAML spec page for bot integrations.
      responses:
        '200':
          description: API page rendered successfully.

  /pricing:
    get:
      summary: Pricing Page
      description: Displays comparative metrics of Free and Pro tiers, explaining local memory allocation guidelines.
      responses:
        '200':
          description: Pricing page rendered successfully.

  /faq:
    get:
      summary: Frequently Asked Questions
      description: Displays indexed accordions mapping technical, security, and integration answers.
      responses:
        '200':
          description: FAQ page rendered successfully.

  /changelog:
    get:
      summary: Release changelogs
      description: Displays details and summary lists of all application build features, fixes, and improvements.
      responses:
        '200':
          description: Changelog page rendered successfully.

  /use-cases:
    get:
      summary: Audience Profiles Hub
      description: Displays target profiles listing how different professionals utilize local PDF utilities.
      responses:
        '200':
          description: Use cases hub page rendered successfully.

  /use-cases/{profileId}:
    get:
      summary: Audience Profile Details
      description: Returns the detailed industry profile containing case studies, why-local justifications, and recommended tools.
      parameters:
        - name: profileId
          in: path
          description: The audience category profile.
          required: true
          schema:
            type: string
            enum: [students, legal, healthcare, designers, business]
      responses:
        '200':
          description: Profile detail page rendered successfully.

  /tools/pdf/{toolId}:
    get:
      summary: Load PDF processing tool
      description: Launches the specific client-side PDF utility. The user interface allows drag-and-drop file inputs which are processed entirely locally.
      parameters:
        - name: toolId
          in: path
          description: The identifier for the PDF tool to load.
          required: true
          schema:
            type: string
            enum:
              - merge-pdf
              - compress-pdf
              - split-pdf
              - rotate-pdf
              - organize-pdf
              - jpg-to-pdf
              - image-to-pdf
              - pdf-to-word
              - pdf-to-jpg
              - pdf-to-png
              - compress-image
              - resize-image
              - crop-image
              - remove-background
              - webp-to-jpg
              - protect-pdf
              - jpg-to-png
              - png-to-jpg
              - flip-image
              - grayscale-image
              - brightness-image
              - contrast-image
              - blur-image
              - sharpen-image
              - filter-image
              - saturation
              - text-overlay
              - invert-image
              - gif-to-png
              - unlock-pdf
              - extract-pages-pdf
              - remove-pages-pdf
              - pdf-to-excel
              - watermark-pdf
              - page-numbers-pdf
              - repair-pdf
              - compare-pdf
              - ppt-to-pdf
              - pdf-to-ppt
              - pdf-to-text
              - pdf-to-html
              - flatten-pdf
              - extract-images-pdf
      responses:
        '200':
          description: Tool interface rendered successfully. File uploads processed locally in RAM.

  /tools/image/{toolId}:
    get:
      summary: Load Image processing tool
      description: Launches the specific client-side image utility. All bitmap calculations and canvas outputs run locally.
      parameters:
        - name: toolId
          in: path
          description: The identifier for the Image tool to load.
          required: true
          schema:
            type: string
            enum:
              - compress-image
              - resize-image
              - crop-image
              - remove-background
              - webp-to-jpg
              - jpg-to-png
              - png-to-jpg
              - flip-image
              - grayscale-image
              - brightness-image
              - contrast-image
              - blur-image
              - sharpen-image
              - filter-image
              - saturation
              - text-overlay
              - invert-image
              - gif-to-png
      responses:
        '200':
          description: Image tool interface rendered successfully.

import { PDFDocument } from 'pdf-lib';

async function mergePdfFiles(fileBufferArray) {
  // Create a brand new PDF document in memory
  const mergedPdf = await PDFDocument.create();
  
  for (const buffer of fileBufferArray) {
    // Load each individual file buffer into a document container
    const pdfDoc = await PDFDocument.load(buffer);
    // Copy all pages into the merged document
    const copiedPages = await mergedPdf.copyPages(pdfDoc, pdfDoc.getPageIndices());
    copiedPages.forEach((page) => mergedPdf.addPage(page));
  }
  
  // Return the compiled bytes as a Uint8Array
  return await mergedPdf.save();
}

function compressImageLocally(file, quality) {
  return new Promise((resolve) => {
    const reader = new FileReader();
    reader.onload = (event) => {
      const img = new Image();
      img.onload = () => {
        const canvas = document.createElement('canvas');
        canvas.width = img.width;
        canvas.height = img.height;
        
        const ctx = canvas.getContext('2d');
        ctx.drawImage(img, 0, 0);
        
        // Convert to blob compressing the layout quality
        canvas.toBlob((blob) => {
          resolve(blob);
        }, 'image/jpeg', quality); // quality parameter between 0.0 and 1.0
      };
      img.src = event.target.result;
    };
    reader.readAsDataURL(file);
  });
}