Class: Zazu::Page

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/zazu/page.rb

Overview

A single page of a list endpoint’s response.

The Zazu API uses cursor pagination. Every list endpoint returns ‘[…], has_more: bool, next_cursor: string|null`. This class wraps that shape and exposes a cursor-walking helper.

Pages are intentionally not auto-paginating. The SDK refuses to let callers iterate every record across many pages with a single call — that’s the failure mode that caused unbounded fetches in the CLI’s ‘–all` flag. Callers walk pages explicitly:

page = client.invoices.list(limit: 100)
while page
  page.data.each { |inv| ... }
  page = page.next
end

Or with a max-items cap that the caller can reason about:

client.invoices.each_page(max_items: 500) { |inv| ... }

Constant Summary collapse

MAX_PER_PAGE =

Hard ceiling on per-page size. Server enforces this too; we refuse to send a larger value rather than silently get clamped.

100

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(response, fetcher:) ⇒ Page

Returns a new instance of Page.



31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/zazu/page.rb', line 31

def initialize(response, fetcher:)
  @response = response
  @fetcher = fetcher

  body = response.body
  unless body.is_a?(Hash) && body["data"].is_a?(Array)
    raise Zazu::Error.new("List response missing 'data' array",
                          body:)
  end

  @data = body["data"]
  @has_more = body.fetch("has_more", false)
  @next_cursor = body["next_cursor"]
end

Instance Attribute Details

#data ⇒ Object (readonly)

Returns the value of attribute data.



29
30
31
 
# File 'lib/zazu/page.rb', line 29

def data
  @data
end

#has_more ⇒ Object (readonly)

Returns the value of attribute has_more.



29
30
31
 
# File 'lib/zazu/page.rb', line 29

def has_more
  @has_more
end

#next_cursor ⇒ Object (readonly)

Returns the value of attribute next_cursor.



29
30
31
 
# File 'lib/zazu/page.rb', line 29

def next_cursor
  @next_cursor
end

#response ⇒ Object (readonly)

Returns the value of attribute response.



29
30
31
 
# File 'lib/zazu/page.rb', line 29

def response
  @response
end

Instance Method Details

#each ⇒ Object 



57
58
59
 
# File 'lib/zazu/page.rb', line 57

def each(&)
  data.each(&)
end

#inspect ⇒ Object 



63
64
65
 
# File 'lib/zazu/page.rb', line 63

def inspect
  "#<#{self.class.name} count=#{data.size} has_more=#{has_more} next_cursor=#{next_cursor.inspect}>"
end

#next ⇒ Object

Fetches the next page. Returns nil when there are no more pages.



51
52
53
54
55
 
# File 'lib/zazu/page.rb', line 51

def next
  return nil unless has_more && next_cursor

  @fetcher.call(next_cursor)
end

#request_id ⇒ Object 



46
47
48
 
# File 'lib/zazu/page.rb', line 46

def request_id
  response.request_id
end