Class: ScreenshotFreeAPI::Resources::Billing

Inherits:
Object
  • Object
show all
Defined in:
lib/screenshotfreeapi/resources/billing.rb

Overview

Billing, plan, and subscription management.

Most methods require a JWT (obtained via Auth#token) passed in the ‘jwt:` keyword argument. The client will send it as the Bearer token for that single request instead of the API key.

The only exception is ‘plans`, which is publicly accessible.

Instance Method Summary collapse

Constructor Details

#initialize(http) ⇒ Billing

Returns a new instance of Billing.



13
14
15
 
# File 'lib/screenshotfreeapi/resources/billing.rb', line 13

def initialize(http)
  @http = http
end

Instance Method Details

#cancel(jwt:) ⇒ Hash

Cancel the active subscription.

Parameters:

  • jwt (String) —

    Management JWT

Returns:

  • (Hash) —

    { “message”, “effectiveAt” }



72
73
74
 
# File 'lib/screenshotfreeapi/resources/billing.rb', line 72

def cancel(jwt:)
  @http.request(:post, "/billing/cancel", body: {}, auth_header: "Bearer #{jwt}")
end

#plan(jwt:) ⇒ Hash

Get the current user’s active plan and usage summary.

Parameters:

  • jwt (String) —

    Management JWT from Auth#token

Returns:

  • (Hash) —

    { “plan”, “status”, “screenshotsUsed”, “screenshotsLimit”, … }



29
30
31
 
# File 'lib/screenshotfreeapi/resources/billing.rb', line 29

def plan(jwt:)
  @http.request(:get, "/billing/plan", auth_header: "Bearer #{jwt}")
end

#plans ⇒ Array<Hash>

List all available subscription plans (no auth required).

Returns:

  • (Array<Hash>) —

    Array of plan objects with name, price, limits, etc.



20
21
22
 
# File 'lib/screenshotfreeapi/resources/billing.rb', line 20

def plans
  @http.request(:get, "/billing/plans", auth_header: "")
end

#upgrade(jwt:, plan:, **options) ⇒ Hash

Initiate a plan upgrade via Flutterwave checkout.

Parameters:

  • jwt (String) —

    Management JWT

  • plan (String) —

    Target plan tier: “STARTER” | “GROWTH” | “BUSINESS” | “ENTERPRISE”

  • options (Hash) —

    Additional upgrade options

Returns:

  • (Hash) —

    { “checkoutUrl”, “transactionRef” } — redirect user to checkoutUrl



49
50
51
52
 
# File 'lib/screenshotfreeapi/resources/billing.rb', line 49

def upgrade(jwt:, plan:, **options)
  body = { plan: plan }.merge(options)
  @http.request(:post, "/billing/upgrade", body: body, auth_header: "Bearer #{jwt}")
end

#usage(jwt:) ⇒ Hash

Retrieve the 30-day daily usage history.

Parameters:

  • jwt (String) —

    Management JWT

Returns:

  • (Hash) —

    { “usage” => Array of { “date”, “count” } }



38
39
40
 
# File 'lib/screenshotfreeapi/resources/billing.rb', line 38

def usage(jwt:)
  @http.request(:get, "/billing/usage", auth_header: "Bearer #{jwt}")
end

#verify(jwt:, transaction_ref: nil) ⇒ Hash

Server-side verification of a completed Flutterwave payment.

Call this after the user returns from the Flutterwave checkout redirect.

Parameters:

  • jwt (String) —

    Management JWT

  • transaction_ref (String) (defaults to: nil) —

    The transactionRef from ‘upgrade`

Returns:

  • (Hash) —

    { “success”, “plan”, “message” }



62
63
64
65
 
# File 'lib/screenshotfreeapi/resources/billing.rb', line 62

def verify(jwt:, transaction_ref: nil)
  query = transaction_ref ? { transaction_ref: transaction_ref } : {}
  @http.request(:get, "/billing/verify", query: query, auth_header: "Bearer #{jwt}")
end