use IO::Async::Loop;
use Net::Async::Firecrawl;

my $loop = IO::Async::Loop->new;
my $fc = Net::Async::Firecrawl->new(
  base_url      => 'http://localhost:3002',  # self-hosted
  poll_interval => 3,
);
$loop->add($fc);

# Single scrape
my $doc = $fc->scrape( url => 'https://example.com', formats => ['markdown'] )->get;

# Crawl and collect all pages (polls + follows pagination)
my $result = $fc->crawl_and_collect(
  url   => 'https://example.com',
  limit => 100,
)->get;
# $result->{data}     — ok pages
# $result->{failed}   — failed pages (url/statusCode/error/page)
# $result->{raw_data} — all pages (original order)
# $result->{stats}    — { ok, failed, total }

# Batch scrape and wait
my $batch = $fc->batch_scrape_and_wait(
  urls    => ['https://a', 'https://b'],
  formats => ['markdown'],
)->get;

# Structured extraction
my $extract = $fc->extract_and_wait(
  urls   => ['https://example.com/*'],
  prompt => 'extract pricing and product names',
)->get;

# Concurrent scrape (partial-success)
my $many = $fc->scrape_many(
  ['https://a', 'https://b', 'https://c'],
  formats => ['markdown'],
)->get;
# $many->{ok}     — [{ url, data }, ...]
# $many->{failed} — [{ url, error }, ...]

# Retry failed pages from a previous crawl
my $retried = $fc->retry_failed_pages( $result, formats => ['markdown'] )->get;

my $f = $fc->scrape( url => 'https://example.com' );
my ($err) = $f->failure;
if ($err && ref $err && $err->isa('WWW::Firecrawl::Error')) {
  if ($err->is_transport) { ... }
  if ($err->is_api)       { ... }
  if ($err->is_job)       { ... }  # crawl/extract/agent completed with status=failed
}

$fc->scrape(...)          $fc->crawl(...)
$fc->crawl_status($id)   $fc->crawl_cancel($id)
$fc->map(...)             $fc->search(...)
$fc->batch_scrape(...)    $fc->extract(...)
$fc->agent(...)           $fc->credit_usage
# ... and more