DocRaptor (DocRaptor v0.1.2)

Elixir client for the DocRaptor HTML-to-PDF/XLS API.

Built on Req. High-level helpers prepare a %Req.Request{} via DocRaptor.Client.attach/2, then call Req.request/1.

For a compact agent-oriented reference (attrs, errors, sync/async/hosted choice, pitfalls), see the Usage guide. Tutorial-oriented examples live in the README.

Quick start

{:ok, client} = DocRaptor.Client.new(api_key: System.fetch_env!("DOCRAPTOR_API_KEY"))
# test: true by default — watermarked, free quota

{:ok, %DocRaptor.Document{body: pdf}} =
  DocRaptor.create_doc(client, %{
    name: "hello.pdf",
    document_type: :pdf,
    document_content: "<html><body>Hello</body></html>"
  })

Document attrs

Create helpers take a map or keyword list (doc_attrs/0). Required:

name — non-empty string
document_type or type — present and stringified (DocRaptor expects pdf / xls / xlsx)
exactly one of document_content or document_url

Optional test overrides the client default. All other keys (including nested prince_options) are passed through to DocRaptor.

Prefer document_content (with inlined CSS/assets) over document_url when developing against localhost — DocRaptor cannot fetch private hosts without a tunnel.

Returns

Success is always {:ok, struct}; failure is {:error, %DocRaptor.Error{}}. There are no bang variants.

Summary

Types

doc_attrs()

Document creation attributes.

Functions

await_async_doc(client, status_id, opts \\ [])

Polls async status until completed or failed, then downloads the document.

create_async_doc(client, attrs)

Queues an asynchronous document (POST /async_docs).

create_doc(client, attrs)

Creates a document synchronously (POST /docs).

create_hosted_async_doc(client, attrs)

Queues a hosted asynchronous document (POST /hosted_async_docs).

create_hosted_doc(client, attrs)

Creates a hosted document synchronously (POST /hosted_docs).

expire(client, download_id)

Expires a hosted document (PATCH /expire/:id).

get_async_doc(client, download_id)

Downloads a finished async document (GET /download/:id).

get_async_doc_status(client, status_id)

Checks async document status (GET /status/:id).

Types

doc_attrs()

@type doc_attrs() :: map() | keyword()

Document creation attributes.

Required keys: name, document_type (or type), and exactly one of document_content / document_url. See Usage for the pass-through parameter list.

Functions

await_async_doc(client, status_id, opts \\ [])

@spec await_async_doc(DocRaptor.Client.t(), String.t(), keyword()) ::
  {:ok, DocRaptor.Document.t()} | {:error, DocRaptor.Error.t()}

Polls async status until completed or failed, then downloads the document.

Convenient wrapper over get_async_doc_status/2 + get_async_doc/2. On :failed, returns {:error, %DocRaptor.Error{reason: :async_failed}}. On deadline, reason: :timeout.

Blocks the calling process via Process.sleep/1 between polls. Prefer an Oban/worker (or callback_url) over calling this inside a Phoenix request.

Options

:interval_ms — sleep between polls (default 1000)
:timeout_ms — overall deadline (default 600_000)

Examples

{:ok, %DocRaptor.AsyncJob{status_id: id}} = DocRaptor.create_async_doc(client, attrs)
{:ok, %DocRaptor.Document{body: pdf}} = DocRaptor.await_async_doc(client, id)

create_async_doc(client, attrs)

@spec create_async_doc(DocRaptor.Client.t(), doc_attrs()) ::
  {:ok, DocRaptor.AsyncJob.t()} | {:error, DocRaptor.Error.t()}

Queues an asynchronous document (POST /async_docs).

Returns %DocRaptor.AsyncJob{status_id: id}. Poll with get_async_doc_status/2, download with get_async_doc/2, or use await_async_doc/3.

create_doc(client, attrs)

@spec create_doc(DocRaptor.Client.t(), doc_attrs()) ::
  {:ok, DocRaptor.Document.t()} | {:error, DocRaptor.Error.t()}

Creates a document synchronously (POST /docs).

Returns PDF/XLS bytes as %DocRaptor.Document{}. DocRaptor enforces ~60s for sync jobs; use create_async_doc/2 for longer work.

Examples

DocRaptor.create_doc(client, %{
  name: "hello.pdf",
  document_type: :pdf,
  document_content: "<html><body>Hello</body></html>"
})

create_hosted_async_doc(client, attrs)

@spec create_hosted_async_doc(DocRaptor.Client.t(), doc_attrs()) ::
  {:ok, DocRaptor.AsyncJob.t()} | {:error, DocRaptor.Error.t()}

Queues a hosted asynchronous document (POST /hosted_async_docs).

Returns %DocRaptor.AsyncJob{}. When complete, status includes a public download_url. Optional: callback_url, hosted limit/expiry attrs.

create_hosted_doc(client, attrs)

@spec create_hosted_doc(DocRaptor.Client.t(), doc_attrs()) ::
  {:ok, DocRaptor.Status.t()} | {:error, DocRaptor.Error.t()}

Creates a hosted document synchronously (POST /hosted_docs).

Hosted documents are a DocRaptor paid add-on. Success is %DocRaptor.Status{} with download_url / download_id (not raw bytes). Optional attrs: hosted_download_limit, hosted_expires_at.

expire(client, download_id)

@spec expire(DocRaptor.Client.t(), String.t()) :: :ok | {:error, DocRaptor.Error.t()}

Expires a hosted document (PATCH /expire/:id).

download_id is the hosted document id from create/status. Returns :ok on success.

get_async_doc(client, download_id)

@spec get_async_doc(DocRaptor.Client.t(), String.t()) ::
  {:ok, DocRaptor.Document.t()} | {:error, DocRaptor.Error.t()}

Downloads a finished async document (GET /download/:id).

download_id comes from a completed %DocRaptor.Status{} (non-hosted).

get_async_doc_status(client, status_id)

@spec get_async_doc_status(DocRaptor.Client.t(), String.t()) ::
  {:ok, DocRaptor.Status.t()} | {:error, DocRaptor.Error.t()}

Checks async document status (GET /status/:id).

status_id comes from %DocRaptor.AsyncJob{}. Status atoms include :queued, :working, :completed, :failed. On completion, use download_id with get_async_doc/2 (non-hosted) or download_url (hosted).