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

``bash
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)

`ts
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.

`ts
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

`bash
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.