stophy

Stophy for TypeScript

Get public web data in your TypeScript or JavaScript code: search results, videos, social posts, places, products, jobs, homes, and more. Every method and result is typed.

Install

npm install stophy

Try it without a key

import { Stophy } from "stophy";

const result = await new Stophy().web.search({ query: "bun runtime" });
console.log(result.data.results);

Web search, YouTube search, and YouTube transcripts work without a key, with a small free allowance. Every other method throws a StophyError with the code unauthorized.

Use an API key

Get a key from the dashboard. Keys start with st_. Set it as STOPHY_API_KEY, or pass it in:

const stophy = new Stophy({ apiKey: "st_..." });

const videos = await stophy.youtube.search({ query: "bun runtime", limit: 5 });
console.log(videos.data.results);

new Stophy("st_...") works too.

Methods follow the source and the command: stophy.maps.search(...), stophy.reddit.subreddit(...), stophy.youtube.comments.replies(...). Each result has data, creditsUsed, and requestId.

Get markdown for a model

const markdown = await stophy.youtube.search(
  { query: "bun runtime", limit: 5 },
  { format: "markdown" },
);

With format: "markdown", the method returns a string.

Get the next page

When there are more results, data.cursor is set. Pass it back to get the next page:

const first = await stophy.reddit.search({ query: "bun" });
const next = await stophy.reddit.search({ query: "bun", cursor: first.data.cursor });

Handle errors

import { StophyError } from "stophy";

try {
  await stophy.reddit.search({ query: "bun" });
} catch (error) {
  if (error instanceof StophyError) {
    console.log(error.code, error.retryable, error.retryAfterSeconds);
  }
}

StophyError has code, message, retryable, retryAfterSeconds, status, and requestId.

The SDK retries network errors and the HTTP statuses 429, 500, 502, 503, and 504, and it waits as long as the API asks. If the API asks for a wait longer than 60 seconds, the SDK throws right away with retryAfterSeconds set.

Options

Option	Default	What it does
apiKey	STOPHY_API_KEY	Your API key
baseUrl	STOPHY_BASE_URL, or the Stophy API	The server to call
maxRetries	2	Retries per request. 0 turns retries off.
timeoutMs	30000	Time limit for each attempt. A timed-out attempt is not retried.

Each method also takes signal to cancel the request.

Check your account

const usage = await stophy.usage();
const logs = await stophy.logs({ days: 7, page: 0 });

usage returns your balance and your all-time usage. logs returns your recent requests. Both need an API key.

License

MIT