doohly 0.1.0

data/docs/example/PUT_creatives.json

@@ -0,0 +1,4 @@
+{
+    "id": "b0324f10-14d8-41ca-8ae5-d03e6d6c37bf",
+    "uploadUrl": "https://doohly-production-file-uploads.s3.ap-southeast-2.amazonaws.com/creative/winboard-adverto/add04745-d007-4dfb-a856-0e53eca0a28b/b0324f10-14d8-41ca-8ae5-d03e6d6c37bf.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIAV6CZOKOV5MUX2UG4%2F20250820%2Fap-southeast-2%2Fs3%2Faws4_request&X-Amz-Date=20250820T044932Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEIX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkgwRgIhAItpbnNxukjLdf9gSFrQvfa3ZAzzWNO8I7APJlR2K0t4AiEAjVMz36tsWPr6ptaW3sJuqIQhncJXMUinSWQ89fFz%2FFQq0gUIzv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARACGgw0MDgyMDk0Nzg1NzEiDNy0%2BI2Vi9xkv44dWCqmBTH%2BJ6av3wsnOPe9xPNLyPMqaSWAdIl4q3Mz4t%2BE9brbakVTGo6pHPyuNAgdybx%2FEzqVnJ0DDwiXOlaiXpe4GhFRXtknBwz4GK6paDl2IqZEYWFDkjZuhzGpnu2z2sAeaZu4%2F6NjoIVFypWtUbtecAHzGUpXZWbLBAPLTGV4MpkR5owho8zsbBcQBXUSok4n5WOSTI39%2FvyKAinzsay%2BbQeBgBZBPHaDUOQ%2FopOwfm6qe50DSFXgxeV%2F2qPwWjeUXs1TXxHradB6L9wk3ut%2FKJocnVC%2F7WSHTedLrbynn4q%2F48EW2EzHVdXUruU0WsoesrGSa%2FWcgwLCtqg1hhOrb4V2ByDagRQBmaQWwaGD%2FTsQ%2FnshMgwqmbm7X4ZO%2FY22yiaCFlMzrqwl1xKpoBA5YYRu1CN68DcDNPrD8mPxgn6GBIqgm6lnkwId5lsP7d086POzTi2zv4UIBhjOMazhSfD1SyxcT22m5ZtHywYtL27kGn3%2FhxnTkvQnpOay64LmhQXXkIifFvzC6OY2iMFn3u9cWtk2oaBU3sU3DPmFTp0bDbhUb5AWztHbtuaB2jQlJRNE2EaLopH%2FRrhqQlazLQ132yPXzhXijTd7y1pIegZ9hqHq%2FJFHceP8osWkAMOxssM%2BzFVLy7WdeAFYwi2X30hJXn%2Fh1o4jM7G6QRWTclGBa%2BVUkynL4oATjXAmht%2B4ukr2ZsQQG9vdpphSF53ZzW1kejeOt7JUTB8eNSWYvpG4PRdLioZREaldo8DtUx85fMiKYDo0lKVhYBVsOabjkLr0KtML9X0h2u7uwTv0P8OtIT8AgyM5May4F01UbnGMpqj8B8tyCpoBZ%2BHIhGWnAlfR9oEWcVbtG8n8%2FZdv5y5gxWLOmKpw4UbGEH%2B0QWHbI4YDn5Tr3DDJppXFBjqwAR2K8QDwQuGg10sfj6%2FUE0eDnA3lrWNYFn6%2BW%2FDmTc6N3bUJAJJQ%2FH3OWPMgEN6mkBN8qgJ7OzQ6%2B5ueo%2FFTm%2FbauiO1EEEjBLD8P6KuLNI4SNL0V1QhlbCoBq8yvDrbtGXA9VyE%2FGi2sV197my6UM0gYXdWVnwvuyFTHyXOo%2Fzjr7F5WJJE6Ou7RzbIIOKtdfMmZmLXS6Fw8xcd9tdvPsjqlcIu2KGCbd5vre1ZJ3C9&X-Amz-Signature=a92086f6b872d1ec77fa2d8a0e12750d3749fca1d06dedfdfa3df39f22fe98a7&X-Amz-SignedHeaders=content-length%3Bhost&x-id=PutObject"
+}

data/doohly.gemspec

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "lib/doohly/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "doohly"
+  spec.version = Doohly::VERSION
+  spec.authors = ["Sentia"]
+  spec.email = ["developer@sentia.com.au"]
+
+  spec.summary = "Ruby client for the Doohly DOOH advertising platform API"
+  spec.description = "A Ruby client library for interacting with the Doohly (Digital Out-of-Home) " \
+                     "advertising platform API. Supports managing bookings, devices, creatives, and more."
+  spec.homepage = "https://github.com/Sentia/doohly"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/Sentia/doohly"
+  spec.metadata["changelog_uri"] = "https://github.com/Sentia/doohly/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/Sentia/doohly/issues"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/doohly"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "vcr", "~> 6.1"
+  spec.add_development_dependency "webmock", "~> 3.18"
+end

data/examples/usage.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "doohly"
+
+# Configure with your API token
+api_token = ENV.fetch("DOOHLY_API_TOKEN", "your_api_token_here")
+
+# Option 1: Global configuration
+Doohly.configure do |config|
+  config.api_token = api_token
+  config.timeout = 30
+end
+
+client = Doohly::Client.new
+
+# Option 2: Direct client initialization
+# client = Doohly::Client.new(api_token: api_token)
+
+puts "=" * 80
+puts "Doohly Ruby Client - Usage Examples"
+puts "=" * 80
+
+# List devices
+puts "\n📱 Fetching devices..."
+begin
+  devices = client.devices
+  device_count = devices.is_a?(Array) ? devices.count : 0
+  puts "Found #{device_count} devices"
+  if devices.is_a?(Array) && devices.any?
+    first_device = devices.first
+    puts "  First device: #{first_device["name"]} (#{first_device["id"]})"
+  end
+rescue Doohly::APIError => e
+  puts "Error fetching devices: #{e.message}"
+end
+
+# List bookings
+puts "\n📅 Fetching bookings..."
+begin
+  bookings = client.bookings
+  booking_list = bookings.is_a?(Hash) ? bookings["bookings"] : bookings
+  booking_count = booking_list.is_a?(Array) ? booking_list.count : 0
+  puts "Found #{booking_count} bookings"
+  if booking_list.is_a?(Array) && booking_list.any?
+    first_booking = booking_list.first
+    puts "  First booking: #{first_booking["name"]} (#{first_booking["status"]})"
+  end
+rescue Doohly::APIError => e
+  puts "Error fetching bookings: #{e.message}"
+end
+
+# Get signed upload URL
+puts "\n🎨 Getting signed upload URL for creative..."
+begin
+  upload_info = client.get_signed_upload_url(
+    name: "example-creative.png",
+    mime_type: "image/png",
+    file_size: 100_000,
+    playback_scaling: "contain"
+  )
+  puts "Upload ID: #{upload_info["id"]}"
+  puts "Upload URL: #{upload_info["uploadUrl"][0..50]}..."
+rescue Doohly::APIError => e
+  puts "Error getting upload URL: #{e.message}"
+end
+
+puts "\n✅ Example completed!"

data/lib/doohly/client.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+module Doohly
+  # Main API client for Doohly
+  class Client
+    attr_reader :api_token, :api_base_url
+
+    def initialize(api_token: nil, api_base_url: nil)
+      @api_token = api_token || Doohly.configuration.api_token
+      @api_base_url = api_base_url || Doohly.configuration.api_base_url
+
+      raise ConfigurationError, "API token is required" if @api_token.nil? || @api_token.empty?
+
+      @connection = build_connection
+    end
+
+    # Bookings API
+
+    # GET /v2/bookings
+    # @param status [String, nil] Filter by status (e.g., 'booked', 'paused', 'completed')
+    # @return [Hash] List of bookings
+    def bookings(status: nil)
+      params = {}
+      params[:status] = status if status
+      get("v2/bookings", params)
+    end
+
+    # GET /v2/bookings/:id
+    # @param id [String] Booking ID
+    # @return [Hash] Booking details
+    def booking(id)
+      get("v2/bookings/#{id}")
+    end
+
+    # POST /v2/bookings - Create a new booking
+    # @param name [String] Booking name
+    # @param external_id [String, nil] External reference ID
+    # @param plays_per_loop [Integer, nil] Number of plays per loop
+    # @param loops_per_play [Integer, nil] Number of loops per play
+    # @param play_consecutively [Boolean, nil] Whether to play consecutively
+    # @param purchase_type [String, nil] Purchase type (e.g., 'Sold', 'Bonus')
+    # @param campaign [Hash, nil] Campaign details
+    # @param schedule [Hash, nil] Schedule configuration
+    # @param assigned_creatives [Array<Hash>, nil] Array of creative assignments
+    # @param assigned_frames [Array<Hash>, nil] Array of frame assignments
+    # @param tags [Array<String>, nil] Tags for the booking
+    # @param seedooh [Hash, nil] SeeDooh configuration
+    # @param status [String, nil] Booking status
+    # @return [Hash] Created booking details
+    def create_booking(name:, external_id: nil, plays_per_loop: nil, loops_per_play: nil,
+                       play_consecutively: nil, purchase_type: nil, campaign: nil,
+                       schedule: nil, assigned_creatives: nil, assigned_frames: nil,
+                       tags: nil, seedooh: nil, status: nil)
+      body = { name: name }
+      body[:externalId] = external_id if external_id
+      body[:playsPerLoop] = plays_per_loop if plays_per_loop
+      body[:loopsPerPlay] = loops_per_play if loops_per_play
+      body[:playConsecutively] = play_consecutively unless play_consecutively.nil?
+      body[:purchaseType] = purchase_type if purchase_type
+      body[:campaign] = campaign if campaign
+      body[:schedule] = schedule if schedule
+      body[:assignedCreatives] = assigned_creatives if assigned_creatives
+      body[:assignedFrames] = assigned_frames if assigned_frames
+      body[:tags] = tags if tags
+      body[:seedooh] = seedooh if seedooh
+      body[:status] = status if status
+
+      post("v2/bookings", body)
+    end
+
+    # PATCH /v2/bookings/:id - Update an existing booking
+    # @param id [String] Booking ID
+    # @param name [String, nil] Booking name
+    # @param external_id [String, nil] External reference ID
+    # @param plays_per_loop [Integer, nil] Number of plays per loop
+    # @param loops_per_play [Integer, nil] Number of loops per play
+    # @param play_consecutively [Boolean, nil] Whether to play consecutively
+    # @param purchase_type [String, nil] Purchase type
+    # @param campaign [Hash, nil] Campaign details
+    # @param schedule [Hash, nil] Schedule configuration
+    # @param assigned_creatives [Array<Hash>, nil] Array of creative assignments
+    # @param assigned_frames [Array<Hash>, nil] Array of frame assignments
+    # @param tags [Array<String>, nil] Tags for the booking
+    # @param seedooh [Hash, nil] SeeDooh configuration
+    # @param status [String, nil] Booking status
+    # @return [Hash] Updated booking details
+    def update_booking(id, name: nil, external_id: nil, plays_per_loop: nil, loops_per_play: nil,
+                       play_consecutively: nil, purchase_type: nil, campaign: nil,
+                       schedule: nil, assigned_creatives: nil, assigned_frames: nil,
+                       tags: nil, seedooh: nil, status: nil)
+      body = {}
+      body[:name] = name if name
+      body[:externalId] = external_id unless external_id.nil?
+      body[:playsPerLoop] = plays_per_loop if plays_per_loop
+      body[:loopsPerPlay] = loops_per_play if loops_per_play
+      body[:playConsecutively] = play_consecutively unless play_consecutively.nil?
+      body[:purchaseType] = purchase_type if purchase_type
+      body[:campaign] = campaign unless campaign.nil?
+      body[:schedule] = schedule if schedule
+      body[:assignedCreatives] = assigned_creatives if assigned_creatives
+      body[:assignedFrames] = assigned_frames if assigned_frames
+      body[:tags] = tags if tags
+      body[:seedooh] = seedooh if seedooh
+      body[:status] = status if status
+
+      patch("v2/bookings/#{id}", body)
+    end
+
+    # DELETE /v2/bookings/:id - Delete an existing booking
+    # @param id [String] Booking ID
+    # @return [Hash] Deletion result
+    def delete_booking(id)
+      delete("v2/bookings/#{id}")
+    end
+
+    # Devices API
+
+    # GET /v1/devices
+    # @return [Hash] List of devices
+    def devices
+      get("v1/devices")
+    end
+
+    # GET /v2/devices/:id
+    # @param id [String] Device ID
+    # @return [Hash] Device details
+    def device(id)
+      get("v2/devices/#{id}")
+    end
+
+    # Creatives API
+
+    # GET /v1/library/creatives/upload/:id - Get creative upload status
+    # @param id [String] Upload ID
+    # @return [Hash] Upload status
+    def creative_upload_status(id)
+      get("v1/library/creatives/upload/#{id}")
+    end
+
+    # POST /v1/library/creatives/upload - Get signed upload URL
+    # @param name [String] Creative name
+    # @param mime_type [String] MIME type (e.g., 'image/png', 'video/mp4')
+    # @param file_size [Integer] File size in bytes
+    # @param playback_scaling [String, nil] Playback scaling mode (e.g., 'contain', 'cover')
+    # @param path [Array<String>, nil] Folder path for organization
+    # @return [Hash] Upload information including signed URL
+    def get_signed_upload_url(name:, mime_type:, file_size:, playback_scaling: nil, path: nil)
+      body = {
+        name: name,
+        mimeType: mime_type,
+        fileSize: file_size
+      }
+      body[:playbackScaling] = playback_scaling if playback_scaling
+      body[:path] = path if path
+
+      post("v1/library/creatives/upload", body)
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: @api_base_url) do |conn|
+        conn.request :authorization, "Bearer", @api_token
+        conn.request :json
+        conn.response :json, content_type: /json$/
+        conn.response :logger, Doohly.configuration.logger if Doohly.configuration.logger
+        conn.options.timeout = Doohly.configuration.timeout
+        conn.options.open_timeout = Doohly.configuration.open_timeout
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def get(path, params = {})
+      response = @connection.get(path, params)
+      handle_response(response)
+    end
+
+    def post(path, body)
+      response = @connection.post(path) do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.body = body.to_json
+      end
+      handle_response(response)
+    end
+
+    def patch(path, body)
+      response = @connection.patch(path) do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.body = body.to_json
+      end
+      handle_response(response)
+    end
+
+    def delete(path)
+      response = @connection.delete(path)
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body
+      when 400
+        raise BadRequestError.new(
+          "Bad Request: #{response.body}",
+          status: response.status,
+          body: response.body,
+          response: response
+        )
+      when 401
+        raise AuthenticationError.new(
+          "Authentication failed: #{response.body}",
+          status: response.status,
+          body: response.body,
+          response: response
+        )
+      when 404
+        raise NotFoundError.new(
+          "Resource not found: #{response.body}",
+          status: response.status,
+          body: response.body,
+          response: response
+        )
+      when 429
+        raise RateLimitError.new(
+          "Rate limit exceeded: #{response.body}",
+          status: response.status,
+          body: response.body,
+          response: response
+        )
+      when 500..599
+        raise ServerError.new(
+          "Server error: #{response.body}",
+          status: response.status,
+          body: response.body,
+          response: response
+        )
+      else
+        raise APIError.new(
+          "API Error: #{response.status} - #{response.body}",
+          status: response.status,
+          body: response.body,
+          response: response
+        )
+      end
+    end
+  end
+end

data/lib/doohly/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Doohly
+  # Configuration management for Doohly client
+  class Configuration
+    attr_accessor :api_token, :api_base_url, :timeout, :open_timeout, :logger
+
+    DEFAULT_API_BASE_URL = "https://api.dooh.ly/api/public"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+
+    def initialize
+      @api_token = nil
+      @api_base_url = DEFAULT_API_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @logger = nil
+    end
+
+    def validate!
+      raise ConfigurationError, "API token is required" if api_token.nil? || api_token.empty?
+
+      true
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration.validate!
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/doohly/error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Doohly
+  # Base error class for all Doohly errors
+  class Error < StandardError; end
+
+  # Raised when API request fails
+  class APIError < Error
+    attr_reader :status, :body, :response
+
+    def initialize(message, status: nil, body: nil, response: nil)
+      @status = status
+      @body = body
+      @response = response
+      super(message)
+    end
+  end
+
+  # Raised when configuration is invalid
+  class ConfigurationError < Error; end
+
+  # Raised when authentication fails
+  class AuthenticationError < APIError; end
+
+  # Raised when resource is not found
+  class NotFoundError < APIError; end
+
+  # Raised when request is invalid
+  class BadRequestError < APIError; end
+
+  # Raised when rate limit is exceeded
+  class RateLimitError < APIError; end
+
+  # Raised when server error occurs
+  class ServerError < APIError; end
+end

data/lib/doohly/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Doohly
+  VERSION = "0.1.0"
+end

data/lib/doohly.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "doohly/version"
+require_relative "doohly/error"
+require_relative "doohly/configuration"
+require_relative "doohly/client"
+
+# Main module for Doohly Ruby client
+module Doohly
+  class << self
+    # Quick client initialization
+    # @param api_token [String] Doohly API token
+    # @return [Doohly::Client] Configured client instance
+    def client(api_token: nil)
+      Client.new(api_token: api_token)
+    end
+  end
+end

data/sig/doohly.rbs

@@ -0,0 +1,4 @@
+module Doohly
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/test_api.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "doohly"
+
+api_token = ENV.fetch("DOOHLY_API_TOKEN")
+
+client = Doohly::Client.new(api_token: api_token)
+
+puts "Testing API connection..."
+puts
+
+begin
+  devices = client.devices
+  puts "✅ API connection successful!"
+  puts "Response type: #{devices.class}"
+  puts "Response: #{devices.inspect}"
+rescue Doohly::AuthenticationError => e
+  puts "❌ Authentication failed: #{e.message}"
+rescue Doohly::APIError => e
+  puts "❌ API error: #{e.message} (Status: #{e.status})"
+rescue StandardError => e
+  puts "❌ Error: #{e.class} - #{e.message}"
+  puts e.backtrace.first(5)
+end