Olostep Bubble Lab Integration

Typed Bubbles for the full Olostep API (scrape, batch, crawl, maps, answers) plus a drop-in research workflow you can import into Bubble Lab. Everything is ready to hand off to the Bubble Lab team or publish on npm.

What you get

• Bubbles for each Olostep endpoint with Zod validation and logging hooks.
• Thin HTTP client with sane defaults and error surfacing.
• Example end-to-end workflow (runResearchFlow) chaining map → batch scrape → answer.
• Ready to build and ship as an npm package (@olostep/bubblelab).

Install

npm install @olostep/bubblelab
# peer deps expected in your Bubble Lab app:
# npm install @bubblelab/bubble-core @bubblelab/bubble-runtime

Usage (add to a Bubble Lab project)

import { createOlostepBubbles } from '@olostep/bubblelab';

const apiKey = process.env.OLOSTEP_API_KEY!;
const bubbles = createOlostepBubbles(apiKey);

// Example: scrape a page
const scrape = await bubbles.scrapeWebsite.run({
  url_to_scrape: 'https://example.com',
  formats: ['markdown'],
});

// Example: batch scrape + citations
const answer = await bubbles.answerQuestion.run({
  task: 'Summarize this site',
  context_urls: ['https://example.com'],
  format: 'markdown',
  include_citations: true,
});

Bundled workflow

runResearchFlow (see src/workflows/researchFlow.ts) discovers URLs, batch-scrapes them, and answers a question. You can drop this into a Bubble Lab template or expose it via the generated API.

import { runResearchFlow } from '@olostep/bubblelab/dist/workflows/researchFlow';

await runResearchFlow({
  apiKey: process.env.OLOSTEP_API_KEY!,
  targetUrl: 'https://example.com',
  question: 'What are the main products and prices?',
});

Exposed Bubbles

• scrapeWebsite – single URL scrape, formats: markdown/html/json/text, optional country, wait, parser.
• batchScrape – scrape many URLs in parallel with optional parser and wait.
• createCrawl – start a crawl with optional follow_links, formats, country, parser.
• createMap – discover URLs with include/exclude patterns and search query.
• answerQuestion – AI-powered search/answer with optional citations, format, top_k_sources, json_schema.

Environment

• OLOSTEP_API_KEY (required): bearer token for the Olostep API.
• OLOSTEP_BASE_URL (optional): override https://api.olostep.com/v1.

Build & test

npm run build
npm test

How to hand this off to Bubble Lab

1. Publish @olostep/bubblelab to npm (or give them a tarball).
2. Send them this README plus a short note that createOlostepBubbles exposes the five nodes above and runResearchFlow is a ready-made template.
3. (Optional) Open a PR to their examples/templates repo pointing to runResearchFlow.

Roadmap (optional)

• Add MCP passthrough bubble for calling any Olostep MCP tool directly.
• Add live-test matrix against Bubble Lab starter templates once their CI contract is clear.