Class: Apertur::Resources::Sessions

Inherits:
Object
  • Object
show all
Defined in:
lib/apertur/resources/sessions.rb

Overview

Manage upload sessions.

Upload sessions represent a time-limited context in which one or more images can be uploaded. Each session has a unique UUID, optional password protection, and configurable constraints.

Instance Method Summary collapse

Constructor Details

#initialize(http) ⇒ Sessions

Returns a new instance of Sessions.

Parameters:



12
13
14
 
# File 'lib/apertur/resources/sessions.rb', line 12

def initialize(http)
  @http = http
end

Instance Method Details

#create(**options) ⇒ Hash

Create a new upload session.

Parameters:

  • destination_ids (Array<String>, nil) —

    destination IDs to deliver images to

  • long_polling (Boolean, nil) —

    whether to enable long-polling on this session

  • tags (Array<String>, nil) —

    tags to attach to the session

  • expires_in_hours (Integer, nil) —

    hours until the session expires

  • expires_at (String, nil) —

    ISO 8601 expiry timestamp

  • max_images (Integer, nil) —

    maximum number of images allowed

  • allowed_mime_types (Array<String>, nil) —

    allowed MIME types for uploads

  • max_image_dimension (Integer, nil) —

    maximum image dimension in pixels

  • password (String, nil) —

    optional password to protect the session

Returns:

  • (Hash) —

    the created session details including uuid and upload_url



28
29
30
 
# File 'lib/apertur/resources/sessions.rb', line 28

def create(**options)
  @http.request(:post, "/api/v1/upload-sessions", body: options)
end

#delivery_status(uuid, poll_from: nil) ⇒ Hash

Get the delivery status for a session.

Returns a hash with the following shape:

{
  "status"      => "pending" | "active" | "completed" | "expired",
  "files"       => [ { "record_id" => ..., "filename" => ..., "size_bytes" => ...,
                       "destinations" => [ { "destination_id" => ..., "status" => ..., ... } ] } ],
  "lastChanged" => "<ISO 8601>"
}

When poll_from (ISO 8601 timestamp) is provided, the server long-polls for up to 5 minutes waiting for something to change before responding. This call automatically widens the read timeout to 360 s (6 min) in that case so the server releases first under the happy path.

Parameters:

  • uuid (String) —

    the session UUID

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

    ISO 8601 timestamp; when set, enables long-poll mode

Returns:

  • (Hash) —

    delivery status snapshot



122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/apertur/resources/sessions.rb', line 122

def delivery_status(uuid, poll_from: nil)
  query = {}
  query["pollFrom"] = poll_from if poll_from
  read_timeout = poll_from ? 360 : nil
  @http.request(
    :get,
    "/api/v1/upload-sessions/#{uuid}/delivery-status",
    query: query,
    read_timeout: read_timeout,
  )
end

#get(uuid) ⇒ Hash

Retrieve an existing upload session by UUID.

Parameters:

  • uuid (String) —

    the session UUID

Returns:

  • (Hash) —

    session details



36
37
38
 
# File 'lib/apertur/resources/sessions.rb', line 36

def get(uuid)
  @http.request(:get, "/api/v1/upload/#{uuid}/session")
end

#list(**params) ⇒ Hash

List upload sessions with pagination.

Parameters:

  • page (Integer, nil) —

    page number

  • page_size (Integer, nil) —

    number of results per page

Returns:

  • (Hash) —

    paginated list with data and pagination metadata



54
55
56
57
58
59
 
# File 'lib/apertur/resources/sessions.rb', line 54

def list(**params)
  query = {}
  query["page"] = params[:page].to_s if params[:page]
  query["pageSize"] = params[:page_size].to_s if params[:page_size]
  @http.request(:get, "/api/v1/sessions", query: query)
end

#qr(uuid, **options) ⇒ String

Get the QR code image for an upload session.

Parameters:

  • uuid (String) —

    the session UUID

  • format (String, nil) —

    image format (e.g. “png”, “svg”)

  • size (Integer, nil) —

    QR code size in pixels

  • style (String, nil) —

    QR code style

  • fg (String, nil) —

    foreground color

  • bg (String, nil) —

    background color

  • border_size (Integer, nil) —

    border size in pixels

  • border_color (String, nil) —

    border color

Returns:

  • (String) —

    raw binary image data



82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/apertur/resources/sessions.rb', line 82

def qr(uuid, **options)
  query = {}
  query["format"] = options[:format] if options[:format]
  query["size"] = options[:size].to_s if options[:size]
  query["style"] = options[:style] if options[:style]
  query["fg"] = options[:fg] if options[:fg]
  query["bg"] = options[:bg] if options[:bg]
  query["borderSize"] = options[:border_size].to_s if options[:border_size]
  query["borderColor"] = options[:border_color] if options[:border_color]
  @http.request_raw(:get, "/api/v1/upload-sessions/#{uuid}/qr", query: query)
end

#recent(**params) ⇒ Array<Hash>

List recent upload sessions.

Parameters:

  • limit (Integer, nil) —

    maximum number of sessions to return

Returns:

  • (Array<Hash>) —

    recent sessions



65
66
67
68
69
 
# File 'lib/apertur/resources/sessions.rb', line 65

def recent(**params)
  query = {}
  query["limit"] = params[:limit].to_s if params[:limit]
  @http.request(:get, "/api/v1/sessions/recent", query: query)
end

#update(uuid, **options) ⇒ Hash

Update an existing upload session.

Parameters:

  • uuid (String) —

    the session UUID

  • options (Hash) —

    fields to update (same options as #create)

Returns:

  • (Hash) —

    the updated session



45
46
47
 
# File 'lib/apertur/resources/sessions.rb', line 45

def update(uuid, **options)
  @http.request(:patch, "/api/v1/upload-sessions/#{uuid}", body: options)
end

#verify_password(uuid, password) ⇒ Hash

Verify a session password.

Parameters:

  • uuid (String) —

    the session UUID

  • password (String) —

    the password to verify

Returns:

  • (Hash) —

    result with valid boolean



99
100
101
 
# File 'lib/apertur/resources/sessions.rb', line 99

def verify_password(uuid, password)
  @http.request(:post, "/api/v1/upload/#{uuid}/verify-password", body: { password: password })
end