Class: PoliPage::Resources::Render

Inherits:
Object
  • Object
show all
Defined in:
lib/poli_page/render.rb

Overview

‘client.render` namespace. Each method captures a back-reference to the parent `PoliPage::Client` and delegates HTTP execution through it (sdk-ruby-plan.md §3.1).

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Render

Returns a new instance of Render.



12
13
14
 
# File 'lib/poli_page/render.rb', line 12

def initialize(client)
  @client = client
end

Instance Method Details

#document(project:, template:, data:, version: nil, format: nil, orientation: nil, locale: nil, metadata: nil, idempotency_key: nil) ⇒ PoliPage::DocumentDescriptor

POST /v1/render — render and store the document, returning a ‘PoliPage::DocumentDescriptor` with the client back-reference attached so that `#download_pdf` works. Project mode only.

Examples:

doc = client.render.document(
  project:  "billing",
  template: "invoice",
  version:  "1.0.0",
  data:     { invoice_number: "INV-001" },
  metadata: { customer_id: "cust_123" }   # echoed on the descriptor
)
db.invoices.update(id: "INV-001", document_id: doc.document_id)
pdf = doc.download_pdf

Returns:



74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/poli_page/render.rb', line 74

def document(project:, template:, data:, version: nil, format: nil,
             orientation: nil, locale: nil, metadata: nil,
             idempotency_key: nil)
  validate_render_kwargs!(format: format, orientation: orientation)
  body = { project: project, template: template, data: data, version: version,
           format: format, orientation: orientation, locale: locale, metadata: metadata }.compact
  parsed = @client.execute_post(Internal::Constants::PATH_RENDER,
                                body: body, idempotency_key: idempotency_key)
  parsed[:metadata] ||= {}
  PoliPage::DocumentDescriptor.new(**parsed, _client: @client)
end

#pdf(project:, template:, data:, version: nil, format: nil, orientation: nil, locale: nil, metadata: nil, idempotency_key: nil) ⇒ String

Two-hop: render the document, then fetch the presigned PDF URL and return the raw bytes (binary-encoded String). The presigned fetch is unauthenticated and NOT subject to the retry policy.

Examples:

pdf = client.render.pdf(
  project: "billing", template: "invoice", version: "1.0.0",
  data:    { invoice_number: "INV-001" }
)
File.binwrite("invoice.pdf", pdf)

Returns:

  • (String) —

    raw PDF bytes

Raises:



99
100
101
102
103
104
105
 
# File 'lib/poli_page/render.rb', line 99

def pdf(project:, template:, data:, version: nil, format: nil,
        orientation: nil, locale: nil, metadata: nil, idempotency_key: nil)
  desc = document(project: project, template: template, data: data,
                  version: version, format: format, orientation: orientation,
                  locale: locale, metadata: metadata, idempotency_key: idempotency_key)
  desc.download_pdf
end

#pdf_stream(project:, template:, data:, version: nil, format: nil, orientation: nil, locale: nil, metadata: nil, idempotency_key: nil) {|chunk| ... } ⇒ Enumerator?

Streaming form of ‘#pdf`. With a block, yields raw chunks (binary bytes) as they arrive. Without a block, returns an `Enumerator` so the caller can `.each`, `.first(n)`, pipe into `Enumerable` chains, etc.

Examples:

Block form — pipe straight to a file

File.open("invoice.pdf", "wb") do |io|
  client.render.pdf_stream(
    project: "billing", template: "invoice", version: "1.0.0", data: data
  ) { |chunk| io.write(chunk) }
end

Enumerator form

enum = client.render.pdf_stream(
  project: "billing", template: "invoice", version: "1.0.0", data: data
)
total = enum.sum(&:bytesize)

Yield Parameters:

  • chunk (String) —

    raw bytes

Returns:

  • (Enumerator, nil)

Raises:



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/poli_page/render.rb', line 128

def pdf_stream(project:, template:, data:, version: nil, format: nil,
               orientation: nil, locale: nil, metadata: nil, idempotency_key: nil, &block)
  unless block
    return Enumerator.new do |yielder|
      pdf_stream(project: project, template: template, data: data,
                 version: version, format: format, orientation: orientation,
                 locale: locale, metadata: metadata,
                 idempotency_key: idempotency_key) { |chunk| yielder << chunk }
    end
  end

  desc = document(project: project, template: template, data: data,
                  version: version, format: format, orientation: orientation,
                  locale: locale, metadata: metadata, idempotency_key: idempotency_key)
  @client.stream_bytes(desc.presigned_pdf_url, &block)
end

#preview(template:, data:, project: nil, version: nil, format: nil, orientation: nil, locale: nil, metadata: nil, idempotency_key: nil) ⇒ PoliPage::PreviewResult

POST /v1/render/preview — render and return the HTML, total page count, and the environment (“sandbox” / “live”) inferred from the API key. Accepts both project mode and inline mode (the only render-* method that does).

Examples:

Project mode

result = client.render.preview(
  project: "billing", template: "invoice", version: "1.0.0",
  data:    { invoice_number: "INV-001" }
)
puts result.html
puts "#{result.total_pages} page(s) in #{result.environment} mode"

Inline mode (raw HTML; only render.preview accepts this)

result = client.render.preview(
  template: "<h1>Hello {{ name }}</h1>",
  data:     { name: "World" }
)

Parameters:

  • template (String) —

    template slug (project mode) OR raw HTML (inline mode)

  • data (Hash) —

    template data

  • project (String, nil) (defaults to: nil) —

    project slug; required for project mode

  • version (String, nil) (defaults to: nil) —

    exact semver (e.g. “1.0.0”) or “draft”

  • format (String, nil) (defaults to: nil) —

    one of ‘PoliPage::PageFormat::FORMATS`; default A4

  • orientation (String, nil) (defaults to: nil) —

    “portrait” or “landscape”; default portrait

  • locale (String, nil) (defaults to: nil) —

    BCP 47 (e.g. “en-US”)

  • metadata (Hash, nil) (defaults to: nil) —

    primitive-valued metadata echoed on render.document responses

  • idempotency_key (String, nil) (defaults to: nil) —

    caller-supplied UUID; auto-generated if nil

Returns:

Raises:



47
48
49
50
51
52
53
54
55
56
 
# File 'lib/poli_page/render.rb', line 47

def preview(template:, data:, project: nil, version: nil, format: nil,
            orientation: nil, locale: nil, metadata: nil,
            idempotency_key: nil)
  validate_render_kwargs!(format: format, orientation: orientation)
  body = { project: project, template: template, data: data, version: version,
           format: format, orientation: orientation, locale: locale, metadata: metadata }.compact
  parsed = @client.execute_post(Internal::Constants::PATH_RENDER_PREVIEW,
                                body: body, idempotency_key: idempotency_key)
  PoliPage::PreviewResult.new(**parsed)
end