inbio 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e87a4134eb1ec3417a54fb204fab8c3dad50f156fab628f4b7762f47c2a47b68
+  data.tar.gz: 7f99e07619f0430bd9dbdf8c59ee3d40dd72da3d868ae8da42b772fa99f43ac9
+SHA512:
+  metadata.gz: 7b9e3a91fd7aacf8d31733ee5d9599860d1842b5c431c9c1a66ca494e267436230e71b087a4a977e436cdf9fa8b6551cd39afb00ea537243d2247bbd810b73aa
+  data.tar.gz: dc20ed1d150f129f4927dccf90c7a78c1a14090d9ae96253fd79a246b525676800f8a06200bfd2f18296ad75e5abf77d6fbd9eb2e9d04e816b360027c0d4d735

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 INBIO
+
+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,287 @@
+# inbio — official Ruby SDK for INBIO (in.bio)
+
+The official Ruby SDK for [INBIO](https://in.bio), the premium URL shortener
+with click analytics and customizable QR codes. Shorten links, generate
+styled QR codes, read analytics, and manage folders and tags from Ruby.
+
+- **Free to start** — `Inbio.shorten` and the [QR API](https://docs.in.bio/api/free-qr) need **no account and no API key**
+- **Zero runtime dependencies** — stdlib `net/http` and `openssl` only, Ruby ≥ 3.0
+- **Complete** — covers the entire [INBIO REST API](https://docs.in.bio/api): links CRUD, lazy enumerator pagination, bulk create, QR codes, analytics, webhook signature verification
+
+## Install
+
+```sh
+gem install inbio
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "inbio"
+```
+
+## Shorten a URL — no account needed
+
+```ruby
+require "inbio"
+
+puts Inbio.shorten("https://example.com/very/long/url").short_url
+# => "https://in.bio/abc123"
+```
+
+The free endpoint is keyless and rate-limited (5/min per IP). The result also
+carries `slug`, `qr_url`, `preview_url`, `claim_url` (turn the anonymous link into
+a permanent one on your account) and `expires` — anonymous links are deleted after
+30 days unless claimed.
+
+## Authenticated quickstart
+
+Create a token under **Settings → API tokens** (API access requires Pro or Business).
+
+```ruby
+require "inbio"
+
+client = Inbio::Client.new(token: "YOUR_API_TOKEN")
+
+link = client.links.create("https://example.com/sale", slug: "spring-sale")
+link.short_url    # => "https://in.bio/spring-sale"
+link.total_clicks # => 0
+```
+
+With no `token:` argument the client reads `ENV["INBIO_API_TOKEN"]`:
+
+```ruby
+client = Inbio::Client.new # uses INBIO_API_TOKEN
+```
+
+## Links
+
+### List and iterate
+
+`list` returns one page; `iterate` returns a lazy `Enumerator` that paginates
+through everything for you:
+
+```ruby
+page = client.links.list(status: "active", per_page: 50)
+page.total        # => 57
+page.current_page # => 1
+page.next?        # => true
+page.each { |link| puts link.short_url }
+
+# Every link, across all pages, fetched on demand:
+client.links.iterate(tag: "marketing").each do |link|
+  puts "#{link.slug}: #{link.total_clicks} clicks"
+end
+
+client.links.iterate(search: "sale").first(10) # stops fetching after 10
+```
+
+Filters: `search:`, `folder_id:`, `tag:`, `status:` (`active`, `disabled`,
+`archived`, `expired`, `exhausted`, `blocked`, `pending_review`), `per_page:` (1–100).
+`list_all` is an alias for `iterate`.
+
+### Create with options
+
+Only the destination URL is required:
+
+```ruby
+link = client.links.create(
+  "https://example.com/launch",
+  slug: "launch",                 # 4–64 chars [a-zA-Z0-9-_]; omitted => random
+  title: "Product launch",
+  description: "Fall campaign",
+  notes: "Internal note",
+  redirect_type: 301,             # 301, 302 (default) or 307
+  folder_id: 3,
+  tags: ["marketing", "fall"],    # created on the fly
+  expires_at: "2026-12-31T23:59:59Z", # Pro+
+  fallback_url: "https://example.com/expired", # Pro+
+  click_limit: 10_000,            # Pro+
+  password: "s3cret",             # Pro+
+  utm: { source: "newsletter", medium: "email", campaign: "fall" }
+)
+```
+
+### Read, update, enable/disable, delete
+
+```ruby
+link = client.links.get(42)
+
+link = client.links.update(42, title: "New title", tags: ["archive"])
+# Editing destination_url requires the edit-destination feature (Pro+).
+
+client.links.disable(42) # active   -> disabled
+client.links.enable(42)  # disabled -> active
+# Any other transition raises Inbio::StateConflictError (error.current has the status).
+
+client.links.delete(42)  # => nil (204); the link stops redirecting
+```
+
+### Bulk create (Business)
+
+Up to 100 links per call; rows fail independently:
+
+```ruby
+result = client.links.bulk_create([
+  { destination_url: "https://example.com/a", slug: "promo-a" },
+  { destination_url: "https://example.com/b", slug: "promo-b" }
+])
+result.created.each { |link| puts link.short_url }
+result.failed.each  { |row| warn "row #{row['index']}: #{row['error']}" }
+```
+
+### QR code to file
+
+`qr` returns raw image bytes — write them straight to disk:
+
+```ruby
+File.binwrite("spring-sale.png", client.links.qr(42))
+File.binwrite("spring-sale.svg", client.links.qr(42, format: "svg", size: 1024))
+```
+
+The QR encodes the short URL, so editing the destination never invalidates
+printed codes.
+
+### Analytics
+
+```ruby
+stats = client.links.analytics(42, from: "2026-06-01", to: "2026-06-30")
+
+stats.totals    # => {"clicks"=>1240, "uniques"=>981, "botClicks"=>77}
+stats.series    # => [{"date"=>"2026-06-01", "clicks"=>40, "uniques"=>31}, ...]
+stats.countries # top 10: [{"value"=>"US", "clicks"=>512}, ...]
+stats.devices, stats.browsers, stats.referrers # same shape
+```
+
+Bot traffic is excluded everywhere except `totals["botClicks"]`.
+
+## Folders and tags
+
+```ruby
+client.folders.list.each { |f| puts "#{f.name} (#{f.links_count} links)" }
+client.tags.list.each    { |t| puts "#{t.name} (#{t.links_count} links)" }
+```
+
+## Account usage
+
+```ruby
+usage = client.account.usage
+usage.plan                        # => "pro"
+usage.usage["links_created"]      # => 120
+usage.limits["links_per_month"]   # => 2000
+```
+
+## Webhook verification
+
+in.bio signs every delivery with `X-Inbio-Signature: t=<unix>,v1=<hex>` where
+`v1 = HMAC-SHA256(secret, "<t>.<raw body>")`. Verify with the exact raw request
+body (before parsing) — the comparison is constant-time and deliveries older
+than `tolerance` (default 300s) are rejected to prevent replays.
+
+Rails:
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def inbio
+    event = Inbio::Webhooks.verify(
+      request.raw_post,
+      request.headers["X-Inbio-Signature"],
+      ENV.fetch("INBIO_WEBHOOK_SECRET")
+    )
+
+    case event.event
+    when "link.clicked"            then Metrics.count(event.data["slug"])
+    when "link.click_limit_reached" then AlertMailer.limit(event.data).deliver_later
+    end
+
+    head :ok
+  rescue Inbio::SignatureVerificationError
+    head :bad_request
+  end
+end
+```
+
+Rack/Sinatra:
+
+```ruby
+post "/webhooks/inbio" do
+  event = Inbio::Webhooks.verify(
+    request.body.read,
+    request.env["HTTP_X_INBIO_SIGNATURE"],
+    ENV.fetch("INBIO_WEBHOOK_SECRET")
+  )
+  # handle event.event / event.data ...
+  200
+rescue Inbio::SignatureVerificationError
+  400
+end
+```
+
+`Inbio::Webhooks.construct_event` is an alias; `client.webhooks.verify(...)`
+works too. No HTTP is involved — it is a pure crypto helper.
+
+## Error handling
+
+Every error is a subclass of `Inbio::Error`, which exposes `message`, `status`,
+`error_type` and the parsed response `body`.
+
+| HTTP | Error | Extras |
+|---|---|---|
+| 401 | `Inbio::AuthenticationError` | |
+| 403 | `Inbio::AccessError` | `error_type` (`"plan"`, `"scope"`, `"account"`), `required_scope` |
+| 404 | `Inbio::NotFoundError` | also returned for links you don't own |
+| 409 | `Inbio::StateConflictError` | `current` — the link's current status |
+| 422 | `Inbio::ValidationError` | `errors` — field name → array of messages |
+| 422 (`error.type=entitlement`) | `Inbio::EntitlementError` | plan feature/limit hit |
+| 429 | `Inbio::RateLimitError` | `retry_after` (seconds) |
+| 5xx | `Inbio::ServerError` | |
+| — | `Inbio::SignatureVerificationError` | webhook verification only |
+
+```ruby
+begin
+  client.links.create("https://example.com", slug: "x")
+rescue Inbio::ValidationError => e
+  e.errors # => {"slug"=>["The slug must be at least 3 characters."]}
+rescue Inbio::AccessError => e
+  e.required_scope # => "links:write" when a token scope is missing
+rescue Inbio::RateLimitError => e
+  sleep e.retry_after
+  retry
+end
+```
+
+## Retries and timeouts
+
+```ruby
+client = Inbio::Client.new(
+  token: "...",
+  base_url: "https://in.bio", # default
+  timeout: 30,                # seconds, default 30
+  max_retries: 2              # default 2
+)
+```
+
+Retries apply only to idempotent GET requests (on connection errors and 5xx) and
+to 429 responses that carry `Retry-After` — with exponential backoff capped at
+10 seconds. Everything else fails fast.
+
+## About INBIO
+
+[INBIO](https://in.bio) (`in.bio`) is a URL shortener and link-management
+platform: short links with custom slugs, real-time click analytics
+(countries, devices, browsers, referrers — bots filtered out), a QR code
+studio with dot styles, marker shapes and colors, folders, tags, UTM
+tools, and a REST API with webhooks. Free plan included.
+
+- Website: https://in.bio
+- Documentation: https://docs.in.bio
+- Free shorten API (no key): https://docs.in.bio/api/free-shorten
+- Free QR code API (no key): https://docs.in.bio/api/free-qr
+- MCP server for AI agents: https://docs.in.bio/api/mcp
+- All SDKs (JavaScript, Python, PHP, Ruby, Go): https://docs.in.bio/sdks
+
+## License
+
+MIT © [InBio, Inc.](https://in.bio)

data/lib/inbio/client.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "openssl"
+
+module Inbio
+  # HTTP client for the in.bio API.
+  #
+  #   client = Inbio::Client.new(token: "...")   # or ENV["INBIO_API_TOKEN"]
+  #   client.links.create("https://example.com")
+  class Client
+    DEFAULT_BASE_URL = "https://in.bio"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 2
+    MAX_BACKOFF = 10
+
+    attr_reader :base_url, :timeout, :max_retries,
+                :links, :folders, :tags, :account, :webhooks
+
+    # token::       API bearer token; falls back to ENV["INBIO_API_TOKEN"].
+    #               Only the free +shorten+ call works without one.
+    # base_url::    API origin, default "https://in.bio".
+    # timeout::     per-request timeout in seconds, default 30.
+    # max_retries:: default 2 — retries only idempotent GETs and 429s that
+    #               carry Retry-After, with exponential backoff capped at 10s.
+    # transport::   swap the HTTP layer (any object responding to +call+ like
+    #               Inbio::Transport); used by the offline tests.
+    def initialize(token: nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES, transport: nil)
+      @token = token || ENV["INBIO_API_TOKEN"]
+      @base_url = base_url.to_s.chomp("/")
+      @timeout = timeout
+      @max_retries = max_retries
+      @transport = transport || Transport.new
+
+      @links = Resources::Links.new(self)
+      @folders = Resources::Folders.new(self)
+      @tags = Resources::Tags.new(self)
+      @account = Resources::Account.new(self)
+      @webhooks = Webhooks.new
+    end
+
+    # Free keyless endpoint: POST /api/shorten. Works without a token.
+    def shorten(url)
+      ShortenResult.new(request(:post, "/api/shorten", body: { url: url }))
+    end
+
+    # Single choke point for every HTTP request the SDK makes.
+    # Returns parsed JSON (or nil for empty/204 responses), or the raw body
+    # string when raw: true. Raises an Inbio::Error subclass on failure.
+    def request(method, path, query: nil, body: nil, raw: false)
+      url = build_url(path, query)
+      headers = default_headers
+      payload = nil
+      if body
+        payload = JSON.generate(body)
+        headers["Content-Type"] = "application/json"
+      end
+
+      attempt = 0
+      loop do
+        begin
+          response = @transport.call(method, url, headers: headers, body: payload, timeout: @timeout)
+        rescue Timeout::Error, IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError => e
+          if method == :get && attempt < @max_retries
+            attempt += 1
+            backoff_sleep(backoff_delay(attempt))
+            retry
+          end
+          raise Error.new("Connection error: #{e.class}: #{e.message}")
+        end
+
+        status = response.status
+        if (200..299).cover?(status)
+          return response.body if raw
+
+          return parse_json(response.body)
+        end
+
+        response_headers = normalize_headers(response.headers)
+        retry_after = response_headers["retry-after"]
+
+        if attempt < @max_retries && retryable?(method, status, retry_after)
+          attempt += 1
+          delay = backoff_delay(attempt)
+          delay = [delay, retry_after.to_i].max if status == 429 && retry_after
+          backoff_sleep([delay, MAX_BACKOFF].min)
+          next
+        end
+
+        raise Error.from_response(status, response.body, response_headers)
+      end
+    end
+
+    private
+
+    def build_url(path, query)
+      url = @base_url + path
+      url += "?#{URI.encode_www_form(query)}" if query && !query.empty?
+      url
+    end
+
+    def default_headers
+      headers = {
+        "Accept" => "application/json",
+        "User-Agent" => "inbio-ruby/#{VERSION}"
+      }
+      headers["Authorization"] = "Bearer #{@token}" if @token
+      headers
+    end
+
+    def parse_json(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise Error.new("Invalid JSON in response body", body: body)
+    end
+
+    def normalize_headers(headers)
+      (headers || {}).each_with_object({}) { |(name, value), acc| acc[name.to_s.downcase] = value }
+    end
+
+    # Only idempotent GETs (on 5xx) and rate limits that tell us when to
+    # come back (429 + Retry-After) are retried.
+    def retryable?(method, status, retry_after)
+      return true if method == :get && status >= 500
+      return true if status == 429 && retry_after
+
+      false
+    end
+
+    def backoff_delay(attempt)
+      [2**(attempt - 1), MAX_BACKOFF].min
+    end
+
+    def backoff_sleep(seconds)
+      sleep(seconds) if seconds.positive?
+    end
+  end
+end

data/lib/inbio/errors.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Inbio
+  # Base class for every error raised by this gem.
+  #
+  # Carries the HTTP +status+, the API +error_type+ (e.g. "plan", "scope",
+  # "state", "entitlement", "account") and the parsed response +body+ when
+  # one was present.
+  class Error < StandardError
+    attr_reader :status, :error_type, :body
+
+    def initialize(message = nil, status: nil, error_type: nil, body: nil)
+      super(message || self.class.name)
+      @status = status
+      @error_type = error_type
+      @body = body
+    end
+
+    # Maps an HTTP error response to the matching error subclass.
+    # +headers+ must use lower-case keys.
+    def self.from_response(status, raw_body, headers = {})
+      body = parse_body(raw_body)
+      info = body.is_a?(Hash) ? body : {}
+      error_obj = info["error"].is_a?(Hash) ? info["error"] : {}
+      message = info["message"]
+      message ||= info["error"] if info["error"].is_a?(String)
+      message ||= "HTTP #{status}"
+      common = { status: status, error_type: error_obj["type"], body: body }
+
+      case status
+      when 401
+        AuthenticationError.new(message, **common)
+      when 403
+        AccessError.new(message, required_scope: error_obj["required"], **common)
+      when 404
+        NotFoundError.new(message, **common)
+      when 409
+        StateConflictError.new(message, current: error_obj["current"], **common)
+      when 422
+        if error_obj["type"] == "entitlement"
+          EntitlementError.new(message, **common)
+        else
+          ValidationError.new(message, errors: info["errors"] || {}, **common)
+        end
+      when 429
+        retry_after = headers["retry-after"]
+        RateLimitError.new(message, retry_after: retry_after&.to_i, **common)
+      when 500..599
+        ServerError.new(message, **common)
+      else
+        Error.new(message, **common)
+      end
+    end
+
+    def self.parse_body(raw_body)
+      return raw_body unless raw_body.is_a?(String)
+      return nil if raw_body.empty?
+
+      begin
+        JSON.parse(raw_body)
+      rescue JSON::ParserError
+        raw_body
+      end
+    end
+    private_class_method :parse_body
+  end
+
+  # 401 — missing or invalid API token.
+  class AuthenticationError < Error; end
+
+  # 403 — the token or plan does not allow this action.
+  # +error_type+ is "plan", "scope" or "account"; +required_scope+ carries
+  # the missing token scope when the API reports one.
+  class AccessError < Error
+    attr_reader :required_scope
+    alias required required_scope
+
+    def initialize(message = nil, required_scope: nil, **options)
+      super(message, **options)
+      @required_scope = required_scope
+    end
+  end
+
+  # 404 — resource not found (or not yours).
+  class NotFoundError < Error; end
+
+  # 422 — invalid input. +errors+ maps field names to arrays of messages.
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message = nil, errors: {}, **options)
+      super(message, **options)
+      @errors = errors
+    end
+  end
+
+  # 422 with error.type = "entitlement" — a plan feature or limit was hit.
+  class EntitlementError < Error; end
+
+  # 409 — invalid state transition. +current+ is the link's current status.
+  class StateConflictError < Error
+    attr_reader :current
+
+    def initialize(message = nil, current: nil, **options)
+      super(message, **options)
+      @current = current
+    end
+  end
+
+  # 429 — rate limited. +retry_after+ is the wait in seconds when the API
+  # sent a Retry-After header.
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **options)
+      super(message, **options)
+      @retry_after = retry_after
+    end
+  end
+
+  # 5xx — something went wrong on the in.bio side.
+  class ServerError < Error; end
+
+  # Webhook signature could not be verified.
+  class SignatureVerificationError < Error; end
+end

data/lib/inbio/models.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Inbio
+  # Base for all API models. Subclasses declare their known fields with
+  # +fields+; each becomes an attr_reader populated from the response hash.
+  # The full untouched hash stays available via +raw+ (and +[]+), so unknown
+  # or newly added API fields never crash parsing and are never lost.
+  class Model
+    class << self
+      def fields(*names)
+        @field_names ||= []
+        names.each do |name|
+          @field_names << name
+          attr_reader name
+        end
+        @field_names
+      end
+    end
+
+    attr_reader :raw
+
+    def initialize(attributes = {})
+      @raw = attributes.is_a?(Hash) ? attributes : {}
+      self.class.fields.each do |field|
+        instance_variable_set(:"@#{field}", @raw[field.to_s])
+      end
+    end
+
+    # Access any field by name, including ones this SDK version doesn't
+    # know about yet.
+    def [](key)
+      @raw[key.to_s]
+    end
+
+    def to_h
+      @raw
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.raw == raw
+    end
+
+    def inspect
+      pairs = self.class.fields.map { |f| "#{f}=#{instance_variable_get(:"@#{f}").inspect}" }
+      "#<#{self.class.name} #{pairs.join(' ')}>"
+    end
+  end
+
+  class Link < Model
+    fields :id, :slug, :short_url, :destination_url, :title, :description,
+           :status, :redirect_type, :folder_id, :tags, :expires_at,
+           :click_limit, :has_password, :total_clicks, :unique_clicks,
+           :last_clicked_at, :created_at, :updated_at
+
+    def has_password?
+      !!has_password
+    end
+  end
+
+  class Folder < Model
+    fields :id, :name, :color, :position, :links_count, :created_at
+  end
+
+  class Tag < Model
+    fields :id, :name, :links_count, :created_at
+  end
+
+  # range: {"from" => ..., "to" => ...}
+  # totals: {"clicks" => ..., "uniques" => ..., "botClicks" => ...}
+  # series/countries/devices/browsers/referrers: arrays of hashes as documented.
+  class Analytics < Model
+    fields :range, :totals, :series, :countries, :devices, :browsers, :referrers
+  end
+
+  # usage/limits are hashes, e.g. usage["links_created"], limits["links_per_month"].
+  class Usage < Model
+    fields :plan, :period_start, :usage, :limits
+  end
+
+  # Result of the free keyless POST /api/shorten endpoint.
+  class ShortenResult < Model
+    fields :short_url, :slug, :qr_url, :preview_url, :claim_url, :expires
+  end
+
+  # A verified webhook delivery.
+  class WebhookEvent < Model
+    fields :id, :event, :created_at, :data
+  end
+
+  # Result of links.bulk_create: +created+ is an array of Link, +failed+ an
+  # array of {"index" => i, "error" => "..."} hashes.
+  class BulkResult
+    attr_reader :created, :failed, :raw
+
+    def initialize(attributes = {})
+      @raw = attributes.is_a?(Hash) ? attributes : {}
+      @created = Array(@raw["created"]).map { |link| Link.new(link) }
+      @failed = Array(@raw["failed"])
+    end
+  end
+end

data/lib/inbio/page.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Inbio
+  # One page of a paginated list response ({data, links, meta}).
+  # Enumerable over the models on this page.
+  class Page
+    include Enumerable
+
+    attr_reader :data, :links, :meta, :raw
+
+    def initialize(payload, model:)
+      @raw = payload.is_a?(Hash) ? payload : {}
+      @data = Array(@raw["data"]).map { |item| model.new(item) }
+      @links = @raw["links"].is_a?(Hash) ? @raw["links"] : {}
+      @meta = @raw["meta"].is_a?(Hash) ? @raw["meta"] : {}
+    end
+
+    def each(&block)
+      @data.each(&block)
+    end
+
+    def total
+      @meta["total"]
+    end
+
+    def current_page
+      @meta["current_page"]
+    end
+
+    def per_page
+      @meta["per_page"]
+    end
+
+    # True when the API reports another page after this one.
+    def next?
+      !@links["next"].nil?
+    end
+  end
+end

data/lib/inbio/resources/account.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Inbio
+  module Resources
+    class Account
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /api/v1/account/usage → Inbio::Usage
+      def usage
+        Usage.new(@client.request(:get, "/api/v1/account/usage")["data"])
+      end
+    end
+  end
+end

data/lib/inbio/resources/folders.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Inbio
+  module Resources
+    class Folders
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /api/v1/folders → [Inbio::Folder]
+      def list
+        Array(@client.request(:get, "/api/v1/folders")["data"]).map { |folder| Folder.new(folder) }
+      end
+    end
+  end
+end

data/lib/inbio/resources/links.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Inbio
+  module Resources
+    class Links
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /api/v1/links — one page of links.
+      def list(search: nil, folder_id: nil, tag: nil, status: nil, page: nil, per_page: nil)
+        query = compact(
+          search: search, folder_id: folder_id, tag: tag,
+          status: status, page: page, per_page: per_page
+        )
+        Page.new(@client.request(:get, "/api/v1/links", query: query), model: Link)
+      end
+
+      # Lazily enumerates every link across all pages. Returns an Enumerator;
+      # no request is made until you start consuming it.
+      def iterate(search: nil, folder_id: nil, tag: nil, status: nil, per_page: nil, page: 1)
+        Enumerator.new do |yielder|
+          current = page || 1
+          loop do
+            result = list(
+              search: search, folder_id: folder_id, tag: tag,
+              status: status, per_page: per_page, page: current
+            )
+            result.data.each { |link| yielder << link }
+            break unless result.next?
+
+            current += 1
+          end
+        end
+      end
+      alias list_all iterate
+
+      # POST /api/v1/links
+      def create(destination_url, slug: nil, title: nil, description: nil, notes: nil,
+                 redirect_type: nil, folder_id: nil, tags: nil, expires_at: nil,
+                 fallback_url: nil, click_limit: nil, password: nil, utm: nil)
+        body = compact(
+          destination_url: destination_url, slug: slug, title: title,
+          description: description, notes: notes, redirect_type: redirect_type,
+          folder_id: folder_id, tags: tags, expires_at: expires_at,
+          fallback_url: fallback_url, click_limit: click_limit,
+          password: password, utm: utm
+        )
+        Link.new(@client.request(:post, "/api/v1/links", body: body)["data"])
+      end
+
+      # POST /api/v1/links/bulk — up to 100 link objects; rows fail independently.
+      def bulk_create(links)
+        payload = links.map { |link| link.respond_to?(:to_h) ? link.to_h : link }
+        BulkResult.new(@client.request(:post, "/api/v1/links/bulk", body: { links: payload })["data"])
+      end
+
+      # GET /api/v1/links/{id}
+      def get(id)
+        Link.new(@client.request(:get, "/api/v1/links/#{id}")["data"])
+      end
+
+      # PATCH /api/v1/links/{id} — any subset of the create fields, plus slug.
+      def update(id, **fields)
+        Link.new(@client.request(:patch, "/api/v1/links/#{id}", body: fields)["data"])
+      end
+
+      # DELETE /api/v1/links/{id} — 204, returns nil.
+      def delete(id)
+        @client.request(:delete, "/api/v1/links/#{id}")
+        nil
+      end
+
+      # POST /api/v1/links/{id}/enable
+      def enable(id)
+        Link.new(@client.request(:post, "/api/v1/links/#{id}/enable")["data"])
+      end
+
+      # POST /api/v1/links/{id}/disable
+      def disable(id)
+        Link.new(@client.request(:post, "/api/v1/links/#{id}/disable")["data"])
+      end
+
+      # GET /api/v1/links/{id}/qr — returns raw image bytes (PNG by default).
+      # Write them straight to a file: File.binwrite("qr.png", client.links.qr(id))
+      def qr(id, format: nil, size: nil)
+        @client.request(:get, "/api/v1/links/#{id}/qr", query: compact(format: format, size: size), raw: true)
+      end
+
+      # GET /api/v1/links/{id}/analytics — dates as "YYYY-MM-DD" strings or Date.
+      def analytics(id, from: nil, to: nil)
+        Analytics.new(@client.request(:get, "/api/v1/links/#{id}/analytics", query: compact(from: from, to: to))["data"])
+      end
+
+      private
+
+      def compact(hash)
+        hash.reject { |_, value| value.nil? }
+      end
+    end
+  end
+end

data/lib/inbio/resources/tags.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Inbio
+  module Resources
+    class Tags
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /api/v1/tags → [Inbio::Tag]
+      def list
+        Array(@client.request(:get, "/api/v1/tags")["data"]).map { |tag| Tag.new(tag) }
+      end
+    end
+  end
+end

data/lib/inbio/transport.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "openssl"
+
+module Inbio
+  # Default HTTP transport built on net/http. All HTTP performed by the SDK
+  # goes through a single object with this interface, so tests (or advanced
+  # users) can swap it via <tt>Inbio::Client.new(transport: ...)</tt>.
+  #
+  # The interface is a single method:
+  #
+  #   call(method, url, headers:, body:, timeout:) -> Inbio::Transport::Response
+  class Transport
+    Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+    METHODS = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      patch: Net::HTTP::Patch,
+      put: Net::HTTP::Put,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    def call(method, url, headers:, body: nil, timeout: 30)
+      uri = URI.parse(url)
+      klass = METHODS.fetch(method) { raise ArgumentError, "unsupported HTTP method: #{method.inspect}" }
+
+      request = klass.new(uri)
+      headers.each { |name, value| request[name] = value }
+      request.body = body if body
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+      response = http.start { |conn| conn.request(request) }
+
+      response_headers = {}
+      response.each_header { |name, value| response_headers[name.downcase] = value }
+
+      Response.new(status: response.code.to_i, headers: response_headers, body: response.body)
+    end
+  end
+end

data/lib/inbio/version.rb

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

data/lib/inbio/webhooks.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Inbio
+  # Pure-crypto webhook signature verification — no HTTP involved.
+  #
+  # in.bio signs each delivery with the header
+  #   X-Inbio-Signature: t=<unix>,v1=<hex>
+  # where v1 = HMAC-SHA256(secret, "<t>.<raw body>").
+  class Webhooks
+    DEFAULT_TOLERANCE = 300
+
+    # Verifies a webhook delivery and returns the parsed Inbio::WebhookEvent.
+    #
+    # +payload+ must be the exact raw request body string (before any JSON
+    # parsing), +signature_header+ the value of X-Inbio-Signature, +secret+
+    # your endpoint's signing secret. Deliveries whose timestamp differs from
+    # now by more than +tolerance+ seconds are rejected to prevent replay
+    # attacks (pass tolerance: nil to skip the timestamp check).
+    #
+    # Raises Inbio::SignatureVerificationError when verification fails.
+    def self.verify(payload, signature_header, secret, tolerance: DEFAULT_TOLERANCE)
+      timestamp, signatures = parse_header(signature_header)
+
+      if tolerance
+        age = (Time.now.to_i - timestamp).abs
+        if age > tolerance
+          raise SignatureVerificationError.new(
+            "Webhook timestamp outside the allowed tolerance (#{age}s > #{tolerance}s)"
+          )
+        end
+      end
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{payload}")
+      unless signatures.any? { |signature| secure_compare(expected, signature) }
+        raise SignatureVerificationError.new("Webhook signature does not match the expected signature")
+      end
+
+      WebhookEvent.new(JSON.parse(payload))
+    rescue JSON::ParserError
+      raise SignatureVerificationError.new("Webhook payload is not valid JSON")
+    end
+
+    class << self
+      alias construct_event verify
+    end
+
+    def self.parse_header(header)
+      unless header.is_a?(String) && !header.empty?
+        raise SignatureVerificationError.new("Missing X-Inbio-Signature header")
+      end
+
+      timestamp = nil
+      signatures = []
+      header.split(",").each do |pair|
+        key, _, value = pair.strip.partition("=")
+        case key
+        when "t" then timestamp = value
+        when "v1" then signatures << value unless value.empty?
+        end
+      end
+
+      unless timestamp&.match?(/\A\d+\z/) && !signatures.empty?
+        raise SignatureVerificationError.new("Malformed X-Inbio-Signature header")
+      end
+
+      [timestamp.to_i, signatures]
+    end
+    private_class_method :parse_header
+
+    def self.secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      if OpenSSL.respond_to?(:fixed_length_secure_compare)
+        OpenSSL.fixed_length_secure_compare(a, b)
+      else
+        result = 0
+        a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
+        result.zero?
+      end
+    end
+    private_class_method :secure_compare
+
+    # Instance methods so the helper is also reachable as client.webhooks.
+    def verify(payload, signature_header, secret, tolerance: DEFAULT_TOLERANCE)
+      self.class.verify(payload, signature_header, secret, tolerance: tolerance)
+    end
+    alias construct_event verify
+  end
+end

data/lib/inbio.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "inbio/version"
+require_relative "inbio/errors"
+require_relative "inbio/transport"
+require_relative "inbio/models"
+require_relative "inbio/page"
+require_relative "inbio/webhooks"
+require_relative "inbio/resources/links"
+require_relative "inbio/resources/folders"
+require_relative "inbio/resources/tags"
+require_relative "inbio/resources/account"
+require_relative "inbio/client"
+
+# Official Ruby SDK for the in.bio URL shortener API.
+#
+#   # Free, keyless:
+#   Inbio.shorten("https://example.com/long").short_url
+#
+#   # Authenticated:
+#   client = Inbio::Client.new(token: "...")
+#   client.links.create("https://example.com/sale", slug: "sale")
+module Inbio
+  # Shortens a URL through the free keyless endpoint (POST /api/shorten).
+  # No account or token needed. Accepts the same options as Inbio::Client.new.
+  def self.shorten(url, **options)
+    Client.new(**options).shorten(url)
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: inbio
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- INBIO
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Official Ruby client for the in.bio URL shortener: short links, QR codes,
+  analytics, folders, tags, bulk create and webhook signature verification. Zero runtime
+  dependencies.'
+email:
+- support@in.bio
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/inbio.rb
+- lib/inbio/client.rb
+- lib/inbio/errors.rb
+- lib/inbio/models.rb
+- lib/inbio/page.rb
+- lib/inbio/resources/account.rb
+- lib/inbio/resources/folders.rb
+- lib/inbio/resources/links.rb
+- lib/inbio/resources/tags.rb
+- lib/inbio/transport.rb
+- lib/inbio/version.rb
+- lib/inbio/webhooks.rb
+homepage: https://in.bio
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/getinbio/inbio-ruby
+  bug_tracker_uri: https://github.com/getinbio/inbio-ruby/issues
+  homepage_uri: https://in.bio
+  documentation_uri: https://docs.in.bio
+  rubygems_mfa_required: 'true'
+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: 4.0.3
+specification_version: 4
+summary: Official Ruby SDK for the in.bio URL shortener API
+test_files: []