--- name: bijection-specstream description: "Evaluate and integrate the Specstream component with Bijection." --- # Specstream SpecStream component for Bijection: ask for a list in plain words, approve the price in your code, and get every row with the page behind it, kept in your database. - Package: @bijectionhq/specstream - Category: Integrations - Status: Preview - License: MIT - Bijection source (repository access required): https://github.com/bijectionhq/specstream/tree/b0a05fda68e51d5aed78d74b90bdb1f83586e5ae/integrations/convex - Upstream: https://github.com/specstream/specstream-tools/tree/ed23f4a64789321d266fc517c90a2a2177177620/integrations/convex - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/specstream ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/specstream.git cd specstream git checkout b0a05fda68e51d5aed78d74b90bdb1f83586e5ae cd integrations/convex ``` ## Before using this component Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes @specstream/convex. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. > Agents: read this skill fully before writing code that uses SpecStream. Follow the installation and configuration steps exactly. # SpecStream ## Instructions Use SpecStream to specstream fetches structured web data rows into your convex database on demand: describe what you need in plain text, cap the spend, and subscribe to results as they arrive. This Convex component integrates directly with your backend. ### Installation ```bash npm install @specstream/convex ``` Current npm version: `@specstream/convex@0.1.0` ### Capabilities - Get structured, source-attributed rows from the live web without writing scrapers or parsing pipelines - Control spend precisely with per-list price caps and a two-step quote-and-approve flow before any work runs - Subscribe to live row counts and paginated results from your UI using standard Convex queries and usePaginatedQuery - Trigger downstream mutations automatically when a list completes via the onComplete callback or optional webhook route ## Examples ### how to fetch structured web data into a Convex database The SpecStream Convex component exposes a findList action that accepts a plain-text request, a row count, and a price cap. It resolves the request against live web pages and writes each matching row into your Convex tables as it finds them. Your UI subscribes to results using usePaginatedQuery against your own query that calls specstream.listRows. ### how to build a prospect or directory list with Convex and live web data Call specstream.findList from a Convex action with a description like 'roofers in Columbus rated 4.5 or better, with a phone number'. Rows land in your database as SpecStream finds them, each carrying the source URL it was read from. You can show the price to the user first with specstream.quote and specstream.approve before any work runs. ### how to give a Convex AI agent access to live web research Wrap specstream.findList in a tool exposed to your Convex agent. The agent provides the plain-text request and row count, while your code sets the maxPriceUsd ceiling so the agent cannot overspend. Results are paginated Convex rows the agent or your app can query immediately. ### how to run a recurring data enrichment job in Convex Call specstream.findList from a Convex scheduled function, one list per category or city. Pass an onComplete internal mutation to receive a callback with the final row count and status once the list reaches a terminal state. The component tracks each list until it is done and retries transient failures automatically. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by SpecStream is not needed ## Troubleshooting **How does SpecStream pricing work and what happens if no results are found?** SpecStream charges only for rows that match your request. A search that finds nothing costs nothing. You set a maxPriceUsd ceiling in your code, and the list will not start if the estimated maximum exceeds that ceiling. A free account starts with $10 of credit and does not require a card. **Does the SpecStream Convex component handle authentication and user access control?** No. Convex components cannot access ctx.auth, so authentication, authorization, and rate limiting are the responsibility of your application code. The README explicitly recommends keeping an owner table that maps lists to users, and checking that table before allowing any list to be read, canceled, or deleted. **What does each row returned by SpecStream contain?** Each row includes a sourceUrl pointing to the page it was read from, an observedAt timestamp, an ordinal position, and a cells array where each cell carries its own sourceUrl, label, display value, and observedAt. If a source does not publish a value, the display field is empty and an absence reason is provided. Values are never guessed or inferred. **How do I get notified when a SpecStream list finishes in Convex?** Pass an onComplete internal mutation reference to findList or approve. SpecStream calls that mutation once when the list reaches a final state such as completed, partial, failed, canceled, or expired, and passes back the listId, row count, status, and any context object you provided. Optionally, mount the webhook HTTP route so SpecStream can push completion events to your deployment immediately rather than waiting for the polling interval. **How do I test the SpecStream Convex component without hitting the live API?** The package ships a test module at @specstream/convex/test compatible with the convex-test library. Import it and call specstream.register(t) to wire the component into your test environment, then stub fetch for api.specstream.ai to return fixture responses. The example app in the repository includes a full test suite covering quote, approve, and row reading. ## Resources - [npm package](https://www.npmjs.com/package/%40specstream%2Fconvex) - [GitHub repository](https://github.com/specstream/specstream-tools/tree/main/integrations/convex) - [Live demo](https://github.com/specstream/specstream-tools/tree/main/integrations/convex/example) - [Convex Components Directory](https://www.convex.dev/components/specstream/convex) - [Convex documentation](https://docs.convex.dev)