catalyst-smartbrowz — Claude Code skill: what it does, how to install

---
name: catalyst-smartbrowz
description: "Catalyst SmartBrowz — browser automation and document generation service. Includes Headless (connect to remote Chrome/Firefox with Puppeteer/Playwright/Selenium), Browser Logic (serverless functions for browser tasks in Java/Node.js), PDF & Screenshot (generate visual documents from HTML/URL/Template), Templates (design dynamic content templates), Browser Grid (parallel headless browsers with auto-scaling, Early Access), and Dataverse (data scraping APIs). Trigger on 'SmartBrowz', 'headless browser', 'Headless Browser', 'Puppeteer', 'Selenium', 'Playwright', 'Browser Logic', 'PDF generation', 'screenshot', 'PDF/Screenshot generation', 'PDF & Screenshot', 'browser automation', 'Browser Grid', or 'web scraping'. Console + SDK (Java/Node.js/Python for PDF/Screenshot + Browser Grid) + CLI (for Browser Logic functions)."
metadata:
  version: "2.0.1"
---

## Prerequisites

Before using SmartBrowz, activate it once per project in the console:
> Console → your project → **SmartBrowz** (left sidebar) → click **"Start Exploring"**

Skipping this step prevents access to Headless, Browser Logic, PDF & Screenshot, Templates, Browser Grid, and Dataverse components.

**For Browser Logic functions:** Requires Catalyst CLI installation. Initialize and deploy Browser Logic functions via CLI (cannot be created directly in console, but can be uploaded).

---

## How It Works

1. **Multi-component service** — SmartBrowz offers 6 independent components in one unified platform:
   - **Headless**: Connect to remote Chrome/Firefox in Catalyst cloud with automation libraries
   - **Browser Logic**: Serverless functions (Java/Node.js) containing browser automation logic
   - **PDF & Screenshot**: Generate visual documents programmatically
   - **Templates**: Design and store templates for dynamic content
   - **Browser Grid** (Early Access): Parallel headless browsers with auto-scaling
   - **Dataverse**: Data scraping APIs

2. **Choose your workflow:**
   - **Headless mode**: Copy console-provided endpoints and code snippets to connect with Puppeteer/Playwright/Selenium
   - **Browser Logic**: Initialize via CLI, code in IDE, deploy to console — for persistent browser automation tasks
   - **PDF & Screenshot**: Use console Playground, SDKs (Java/Node.js/Python), or API to generate documents
   - **Browser Grid**: Configure node/browser count, connect via CDP/Webdriver endpoints, process requests in parallel

3. **Load `references/smartbrowz-basics.md`** — for component details, automation library setup, Browser Logic structure, PDF/Screenshot SDK usage, Browser Grid configurations, and troubleshooting

4. **SDK-first rule** — When writing implementation code, always prefer SDK methods over raw REST API calls:
   - **Node.js**: `app.smartbrowz()` (lowercase — `app.SmartBrowz()` is not a function) → `smartbrowz.convertToPdf()`, `smartbrowz.generateFromTemplate()`, `app.smartbrowz().browserGrid()` → `grid.getGrid()`, `grid.stopGrid()`
   - **Python**: `app.smart_browz()` → `smart_browz.convert_to_pdf()`, `smart_browz.generate_from_template()`, `app.smart_browz().browser_grid()` → `grid.get_all_grid()`
   - **Java**: `ZCSmartBrowz.getInstance()` → `smartBrowz.convertToPdf()`, `smartBrowz.generateFromTemplate()`
   - Use REST API **only** when no SDK equivalent exists (e.g., checking `free_sessions` on Browser Grid live stats)

5. **Key concepts:**
   - **Remote browsers run in Catalyst cloud** — not local. Endpoints are auto-generated by console.
   - **No api-key in connection code** — Puppeteer/Playwright/Selenium connect using only the endpoint URL. The `api-key` is only used for Browser Grid REST API calls (e.g., live stats).
   - **Chrome browser only** (currently) — Firefox support in Browser Grid (Early Access)
   - **Browser Logic functions = Serverless function type** — created with CLI, not console UI
   - **Browser Grid = auto-scaling** — nodes and browsers spawn on demand based on configuration
   - **Code Recipes** available in console for testing automation library use cases

6. **Security note** — Any browser automation or web scraping is at your own risk. Only use on domains that permit such actions or with proper approval.

## Security Checklist

- **API Key protection**: Endpoints for Headless and Browser Grid are secured with auto-generated API keys. Regenerate keys if compromised (note: this resets grid stats).
- **Browser Logic logs**: All function activity is logged in Console → DevOps → Logs. Review logs for debugging and security audits.
- **Browser Grid queue limits**: Selenium requests queue for 30 seconds, Puppeteer/Playwright for 5 minutes. After timeout, requests are killed.
- **Browser Grid alerts**: Monitor Dashboard for alerts (Browser Creation Rejected, 90% Disk Exhausted, 80% Memory/CPU Exhausted, Nodes Crashed).
- **Default storage**: Browser Grid nodes have 10GB disk limit. Monitor disk usage to prevent failures.
- **Rate considerations**: Browser automation can generate high network traffic. Be mindful of target website rate limits and terms of service.

## Triggers

Use this skill for: "SmartBrowz", "headless browser", "Headless Browser", "remote browser", "Puppeteer", "Playwright", "Selenium", "browser automation", "Browser Logic", "PDF generation", "screenshot webpage", "HTML to PDF", "URL to PDF", "template PDF", "PDF/Screenshot generation", "PDF & Screenshot", "SmartBrowz templates", "Browser Grid", "parallel browsers", "web scraping", "Dataverse", "CDP endpoint", "Webdriver endpoint", "headless Chrome", "headless Firefox", "browser testing", or "automation library".

## References

| Reference | Load when the query is about… |
|-----------|-------------------------------|
| `references/smartbrowz-basics.md` | Headless setup (Puppeteer/Playwright/Selenium code snippets), Browser Logic (CLI commands, function structure, deployment), PDF & Screenshot (console Playground, SDK usage in Java/Node.js/Python, API calls, input formats HTML/URL/Template), Templates (design, storage, dynamic content), Browser Grid (configurations Basic/Light/Moderate/Heavy, node/browser setup, CDP/Webdriver endpoints, workflow, alerts, states Active/Inactive/Idle, dashboard, ideal practices), Dataverse (data scraping APIs), troubleshooting |