openDocumentUrl

Opens a PDF document from a given URL by downloading the entire file.

Signature


openDocumentUrl(file: PdfFileUrl, options?: PdfOpenDocumentUrlOptions): PdfTask<PdfDocumentObject>;

Description

This function initiates the process of loading a PDF file from a remote URL. It fetches the complete file content into memory before opening it.

💡

Note on Loading Strategy Currently, this function always downloads the entire PDF file. Support for progressive loading via HTTP range requests is planned for a future release. The mode option is reserved for this future enhancement and will have no effect on the current behavior.

Parameters

Name	Type	Description
`file`	`PdfFileUrl`	An object containing a unique `id` you provide and the `url` of the PDF file. Example: `{ id: 'unique-doc-id', url: 'https://example.com/document.pdf' }`
`options`	`PdfOpenDocumentUrlOptions`	(Optional) An object to configure loading. Can include a `password` for encrypted files.

`PdfOpenDocumentUrlOptions`


export interface PdfOpenDocumentUrlOptions {
  password?: string;
  /**
   * NOTE: This option is reserved for future use. Currently, only the 'full-fetch'
   * behavior is implemented regardless of the selected mode.
   */
  mode?: 'auto' | 'range-request' | 'full-fetch';
  /**
   * HTTP request options for fetching the PDF
   */
  requestOptions?: {
    /**
     * Custom HTTP headers to include in all requests
     */
    headers?: Record<string, string>;
    /**
     * Controls whether cookies are sent with requests
     * - 'omit': Never send cookies (default)
     * - 'same-origin': Send cookies for same-origin requests
     * - 'include': Always send cookies (requires CORS)
     */
    credentials?: RequestCredentials;
  };
}

Returns

PdfTask<PdfDocumentObject>

A Task that resolves with a PdfDocumentObject when the document is successfully opened. The PdfDocumentObject contains metadata about the PDF, such as the page count and the dimensions of each page.

If the operation fails (e.g., the URL is invalid, the file is corrupted, or the password is incorrect), the Task will be rejected with a PdfErrorReason.

See Concepts: Tasks for more on how to handle asynchronous operations.

Example


// Assuming 'engine' is an initialized PdfiumEngine instance
 
const fileUrl = { id: 'my-doc', url: '/path/to/document.pdf' };
 
try {
  // Use .toPromise() to work with async/await
  const document = await engine.openDocumentUrl(fileUrl, { password: 'my-secret-password' }).toPromise();
 
  console.log(`Successfully opened document with ${document.pageCount} pages.`);
 
  // Now you can use the 'document' object with other engine methods
  // e.g., engine.renderPage(document, document.pages[0]);
 
} catch (error) {
  console.error('Failed to open document:', error);
}

Using Custom Headers for Authentication


// Load a PDF that requires authentication
const fileUrl = { id: 'secure-doc', url: 'https://api.example.com/documents/123.pdf' };
 
const document = await engine.openDocumentUrl(fileUrl, {
  requestOptions: {
    headers: {
      'Authorization': 'Bearer your-access-token-here',
      'X-Custom-Header': 'custom-value'
    }
  }
}).toPromise();

Using Cookies for Authentication


// Load a PDF using cookie-based authentication
const fileUrl = { id: 'session-doc', url: 'https://example.com/documents/secure.pdf' };
 
const document = await engine.openDocumentUrl(fileUrl, {
  requestOptions: {
    credentials: 'include' // Sends cookies with the request
  }
}).toPromise();
 
console.log(`Opened document with ${document.pageCount} pages using session cookies.`);

⚠️

CORS and Credentials

When using credentials: 'include' to send cookies with cross-origin requests, the server must:

Include Access-Control-Allow-Credentials: true in the response headers
Specify the exact origin in Access-Control-Allow-Origin (wildcards are not allowed)
Properly handle preflight OPTIONS requests for CORS

For same-origin requests, use credentials: 'same-origin' which is more restrictive and secure.