floopfloop

Official Ruby SDK for the FloopFloop API. Build, refine, and manage FloopFloop projects from any Ruby codebase (Ruby ≥ 3.0). Zero runtime dependencies — stdlib net/http + json.

gem install floopfloop

Or in your Gemfile:

gem "floopfloop", "~> 0.1.0.alpha.1"

Grab an API key: floop keys create my-sdk (via the floop CLI) or the dashboard → Account → API Keys. Business plan required to mint new keys.

require "floopfloop"

client = FloopFloop::Client.new(api_key: ENV.fetch("FLOOP_API_KEY"))

# Create a project and wait for it to go live.
created = client.projects.create(
  prompt:    "A landing page for a cat cafe with a sign-up form",
  name:      "Cat Cafe",
  subdomain: "cat-cafe",
  bot_type:  "site",
)

live = client.projects.wait_for_live(created.fetch("project").fetch("id"))
puts "Live at: #{live['url']}"

client.projects.stream(project_id) do |ev|
  printf("%s (%d/%d) — %s\n", ev["status"], ev["step"], ev["totalSteps"], ev["message"])
end

The block is called for every unique status snapshot; duplicates (same status / step / progress / queuePosition) are filtered out so you don't see dozens of identical "queued" events. On success returns the final live event; raises FloopFloop::Error on BUILD_FAILED / BUILD_CANCELLED / TIMEOUT.

If you just want to block until live, wait_for_live wraps stream and fetches the hydrated project hash:

live = client.projects.wait_for_live(project_id)

Every call raises FloopFloop::Error on non-2xx. Inspect #code:

begin
  client.projects.status("my-project")
rescue FloopFloop::Error => e
  case e.code
  when "RATE_LIMITED"  then sleep(e.retry_after || 5); retry
  when "UNAUTHORIZED"  then abort "Check your FLOOP_API_KEY."
  else
    warn "[#{e.code} #{e.status}] #{e.message} (request #{e.request_id})"
    raise
  end
end

Known codes: UNAUTHORIZED, FORBIDDEN, VALIDATION_ERROR, RATE_LIMITED, NOT_FOUND, CONFLICT, SERVICE_UNAVAILABLE, SERVER_ERROR, NETWORK_ERROR, TIMEOUT, BUILD_FAILED, BUILD_CANCELLED, UNKNOWN. Unknown server codes pass through verbatim in #code.

Method-for-method parity with @floopfloop/sdk (Node), floopfloop (Python), floopfloop (Rust), and floop-go-sdk (Go).

For longer end-to-end patterns — streaming a build, refining mid-deploy, attachment uploads, key rotation, retry-with-backoff — see the cookbook.

# From bytes
att = client.uploads.create(
  file_name: "screenshot.png",
  bytes:     File.binread("./screenshot.png"),
)

# Or the one-shot helper — reads the file for you
att = client.uploads.create_from_path("./screenshot.png")

# Drop into a refine call:
client.projects.refine(project_id,
  message: "Redo the landing page based on this screenshot.",
  attachments: [att],
)

Max 5 MB per file; allowed: png, jpg, gif, svg, webp, ico, pdf, txt, csv, doc, docx.

client = FloopFloop::Client.new(
  api_key:          ENV.fetch("FLOOP_API_KEY"),
  base_url:         "https://staging.floopfloop.com",  # default production URL
  timeout:          60,                                # default 30s
  user_agent_suffix: "myapp/1.2",                      # appended after floopfloop-ruby-sdk/<v>
)

FloopFloop::Client is thread-safe — each request opens its own Net::HTTP session. Reuse a single client across threads / workers without contention.

Follows Semantic Versioning. Breaking changes in 0.x are called out in CHANGELOG.md and a new tag is cut with v<version>. Tag push triggers the release workflow which publishes to RubyGems.

MIT