webinarjam 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 007f29eaa5a4eeefb046bcfa9b02f3e25e39406acad46b0a395ae969533b91a3
+  data.tar.gz: df1a31482c8dd326010dc2e13ad6d60657a9a57b3502e3a363ff54b511adbd1b
+SHA512:
+  metadata.gz: f223c1847c4e590be08cb8882e08806e04cac0d59f4b341507a06dd4a527a97074a117e658d6c1ffbac94062bfd77d8c228536c0cb4a20c63f0f46d819a26f30
+  data.tar.gz: dcd6b918f3131a4aab6f49f5215787343f8250a8fdc92bc509f4fa6712efa06ad6d8afb5a8d2e1629c895ace00cb2a9d5362ad24226cc1c77170011afe46adf8

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.0.0] - 2026-08-13
+
+- Initial release claiming the gem name.
+- `WebinarJam::Client` covering all documented WebinarJam API endpoints:
+  `#webinars`, `#webinar`, `#register`, `#registrants`, `#unsubscribe`.
+- EverWebinar support via `product: :everwebinar`.
+- Typed errors (`AuthenticationError`, `RateLimitError`, `APIError`) and
+  opt-in automatic retries on HTTP 429.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yi-Ru Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,115 @@
+# WebinarJam
+
+A dependency-free Ruby client for the [WebinarJam / EverWebinar API](https://support.webinarjam.com/en/articles/15370144-connect-to-webinarjam-or-everwebinar-api).
+
+Covers every documented endpoint:
+
+| Method | Endpoint | Purpose |
+|---|---|---|
+| `#webinars` | `POST /webinars` | List all published webinars |
+| `#webinar(id)` | `POST /webinar` | Details for one webinar (schedules, URLs, presenters) |
+| `#register(...)` | `POST /register` | Register a user to a webinar |
+| `#registrants(...)` | `POST /registrants` | List registrants and attendees |
+| `#unsubscribe(...)` | `POST /unsubscribe` | Unsubscribe a lead from notifications |
+
+## Installation
+
+```ruby
+# Gemfile
+gem "webinarjam"
+```
+
+## Usage
+
+```ruby
+require "webinarjam"
+
+client = WebinarJam::Client.new(api_key: ENV["WEBINARJAM_API_KEY"])
+# api_key: defaults to ENV["WEBINARJAM_API_KEY"], so this is equivalent:
+client = WebinarJam::Client.new
+
+# Or configure once, module-wide:
+WebinarJam.configure { |config| config.api_key = "your-key" }
+client = WebinarJam.client
+
+# List all webinars
+client.webinars
+# => { status: "success", webinars: [{ webinar_id: 1, webinar_hash: "abcd1234", ... }] }
+
+# Details for one webinar (schedule ids live here)
+details = client.webinar(1)
+schedule = details[:webinar][:schedules].first[:schedule]
+
+# Register a user
+client.register(
+  webinar_id: 1,
+  schedule: schedule,
+  first_name: "Jane",
+  email: "jane@example.com",
+  # optional: last_name, country, state, timezone_id, ip_address,
+  #           phone_country_code, phone, twilio_consent
+)
+# => { status: "success", user: { user_id: ..., live_room_url: ..., ... } }
+
+# Registrants / attendees for one session (paginated)
+listing = client.registrants(webinar_id: 1, schedule_id: schedule, search: "jane@example.com")
+# => { status: "success", registrants: { current_page: 1, data: [{ lead_id: ..., email: ..., ... }] } }
+# optional filters: attended_live, attended_replay, purchased, page,
+#                   attended_live_timestamp, attended_replay_timestamp, date_range
+
+# Unsubscribe a lead (lead id comes from #registrants)
+client.unsubscribe(webinar_id: 1, lead_id: 818)
+# => true (the API responds 204 No Content)
+```
+
+All responses are parsed JSON with symbolized keys.
+
+### EverWebinar
+
+The EverWebinar API shares the same shape under a different path prefix:
+
+```ruby
+client = WebinarJam::Client.new(product: :everwebinar)
+```
+
+### Errors and rate limiting
+
+Every API failure raises a subclass of `WebinarJam::Error`:
+
+- `WebinarJam::ConfigurationError` — no API key provided.
+- `WebinarJam::AuthenticationError` — HTTP 401/403 (invalid API key).
+- `WebinarJam::RateLimitError` — HTTP 429. The API allows at most
+  **20 calls per second per user**.
+- `WebinarJam::APIError` — any other error, including 2xx responses whose
+  body carries `"status": "error"`. Exposes `#http_status` and `#body`.
+
+Opt into automatic retries on 429 (exponential backoff: 0.5s, 1s, 2s, ...):
+
+```ruby
+client = WebinarJam::Client.new(max_retries: 3)
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec              # unit specs + integration specs (VCR replay)
+bundle exec rspec spec/webinarjam  # unit specs only
+bin/console                    # IRB with the gem and .env loaded
+```
+
+Integration specs replay VCR cassettes committed under
+`spec/fixtures/vcr_cassettes/` — no credentials needed. To re-record against
+the live API, put a real key in `.env` (`WEBINARJAM_API_KEY=...`) and run:
+
+```sh
+VCR_RECORD=all bundle exec rspec spec/integration
+```
+
+The API key is filtered out of cassettes (`<API_KEY>`), but recorded bodies
+still contain your account's webinar names and room URLs — review cassettes
+before publishing them anywhere.
+
+## License
+
+MIT

data/lib/webinarjam/client.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module WebinarJam
+  # HTTP client for the WebinarJam / EverWebinar API.
+  #
+  # Every endpoint is a POST with a form-encoded body and returns JSON,
+  # except +unsubscribe+ which returns 204 No Content.
+  class Client
+    BASE_URL = "https://api.webinarjam.com"
+    PRODUCTS = %i[webinarjam everwebinar].freeze
+
+    attr_reader :product, :max_retries
+
+    # @param api_key [String] account-wide API key (defaults to ENV["WEBINARJAM_API_KEY"])
+    # @param product [Symbol] :webinarjam or :everwebinar
+    # @param max_retries [Integer] automatic retries (with backoff) on HTTP 429
+    def initialize(api_key: ENV["WEBINARJAM_API_KEY"], product: :webinarjam,
+                   base_url: BASE_URL, open_timeout: 10, read_timeout: 30,
+                   max_retries: 0)
+      if api_key.nil? || api_key.to_s.empty?
+        raise ConfigurationError,
+              "api_key is required (pass api_key: or set ENV[\"WEBINARJAM_API_KEY\"])"
+      end
+      product = product.to_sym
+      raise ArgumentError, "product must be one of #{PRODUCTS.inspect}" unless PRODUCTS.include?(product)
+
+      @api_key = api_key
+      @product = product
+      @base_url = base_url
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @max_retries = max_retries
+    end
+
+    # Retrieve the full list of webinars published in the account.
+    # @return [Hash] { status: "success", webinars: [...] }
+    def webinars
+      post("webinars")
+    end
+
+    # Get details about one particular webinar.
+    # @return [Hash] { status: "success", webinar: {...} }
+    def webinar(webinar_id)
+      post("webinar", webinar_id: webinar_id)
+    end
+
+    # Register a user to a webinar.
+    #
+    # Optional params include: last_name, country, state, timezone_id,
+    # ip_address, phone_country_code, phone, twilio_consent.
+    # @return [Hash] { status: "success", user: {...} }
+    def register(webinar_id:, first_name:, email:, schedule:, **params)
+      post("register", params.merge(
+        webinar_id: webinar_id, first_name: first_name, email: email, schedule: schedule
+      ))
+    end
+
+    # Get a list of registrants and attendees for one webinar session.
+    #
+    # Optional params include: attended_live, attended_replay, purchased,
+    # page, attended_live_timestamp, attended_replay_timestamp, date_range,
+    # search.
+    # @return [Hash]
+    def registrants(webinar_id:, schedule_id:, **params)
+      post("registrants", params.merge(webinar_id: webinar_id, schedule_id: schedule_id))
+    end
+
+    # Unsubscribe a lead from a webinar's notification queue.
+    # @return [true] the API responds with 204 No Content on success
+    def unsubscribe(webinar_id:, lead_id:)
+      post("unsubscribe", webinar_id: webinar_id, lead_id: lead_id)
+      true
+    end
+
+    private
+
+    def post(path, params = {})
+      attempts = 0
+      begin
+        handle_response(perform_post(path, params))
+      rescue RateLimitError
+        raise if attempts >= @max_retries
+
+        attempts += 1
+        sleep(retry_backoff(attempts))
+        retry
+      end
+    end
+
+    def perform_post(path, params)
+      uri = URI("#{@base_url}/#{@product}/#{path}")
+      request = Net::HTTP::Post.new(uri)
+      request.set_form_data(params.compact.merge(api_key: @api_key))
+
+      Net::HTTP.start(uri.host, uri.port,
+                      use_ssl: uri.scheme == "https",
+                      open_timeout: @open_timeout,
+                      read_timeout: @read_timeout) do |http|
+        http.request(request)
+      end
+    end
+
+    def handle_response(response)
+      status = response.code.to_i
+      return nil if status == 204
+
+      body = parse_json(response.body)
+
+      if (200..299).cover?(status)
+        return body unless body.is_a?(Hash) && body[:status] == "error"
+
+        raise APIError.new(error_message(body, status), http_status: status, body: body)
+      end
+
+      error_class = case status
+                    when 401, 403 then AuthenticationError
+                    when 429 then RateLimitError
+                    else APIError
+                    end
+      raise error_class.new(error_message(body, status), http_status: status, body: body)
+    end
+
+    def parse_json(raw)
+      JSON.parse(raw, symbolize_names: true)
+    rescue JSON::ParserError, TypeError
+      nil
+    end
+
+    def error_message(body, status)
+      return "HTTP #{status}" unless body.is_a?(Hash)
+
+      errors = body[:errors]
+      detail = case errors
+               when Hash then errors.map { |field, msg| "#{field}: #{msg}" }.join("; ")
+               when Array then errors.join("; ")
+               else body[:message] || body[:error]
+               end
+      detail && !detail.empty? ? detail : "HTTP #{status}"
+    end
+
+    def retry_backoff(attempt)
+      0.5 * (2**(attempt - 1))
+    end
+  end
+end

data/lib/webinarjam/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module WebinarJam
+  class Error < StandardError; end
+
+  # Raised when the client is instantiated without an API key.
+  class ConfigurationError < Error; end
+
+  # Raised when the API returns an error, either as a non-2xx HTTP status or
+  # as a 2xx response whose JSON body carries `"status": "error"`.
+  class APIError < Error
+    attr_reader :http_status, :body
+
+    def initialize(message, http_status: nil, body: nil)
+      @http_status = http_status
+      @body = body
+      super(message)
+    end
+  end
+
+  # HTTP 401/403 — invalid or missing API key.
+  class AuthenticationError < APIError; end
+
+  # HTTP 429 — the API allows at most 20 calls per second per user.
+  class RateLimitError < APIError; end
+end

data/lib/webinarjam/version.rb

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

data/lib/webinarjam.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "webinarjam/version"
+require_relative "webinarjam/errors"
+require_relative "webinarjam/client"
+
+module WebinarJam
+  class << self
+    attr_writer :api_key
+
+    def api_key
+      @api_key || ENV["WEBINARJAM_API_KEY"]
+    end
+
+    # WebinarJam.configure { |config| config.api_key = "..." }
+    def configure
+      yield self
+      self
+    end
+
+    # Convenience constructor honoring the module-level configuration.
+    def client(**options)
+      Client.new(api_key: api_key, **options)
+    end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: webinarjam
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Yi-Ru Lin
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-14 00:00:00.000000000 Z
+dependencies: []
+description: 'A dependency-free Ruby client for the WebinarJam and EverWebinar HTTP
+  API: list webinars, fetch webinar details, register users, list registrants and
+  attendees, and unsubscribe leads.'
+email:
+- lawrence@kaik.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/webinarjam.rb
+- lib/webinarjam/client.rb
+- lib/webinarjam/errors.rb
+- lib/webinarjam/version.rb
+homepage: https://github.com/linyiru/webinarjam
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/linyiru/webinarjam
+  source_code_uri: https://github.com/linyiru/webinarjam
+  changelog_uri: https://github.com/linyiru/webinarjam/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the WebinarJam / EverWebinar API
+test_files: []