Listen Notes Podcast API JavaScript Library

Common errors

• API key is missing

  cause The `apiKey` parameter was not provided during client initialization, or the `process.env.LISTEN_API_KEY` (or `LISTEN_API_KEY` for Workers) environment variable was not set.
  fix Initialize the client with `Client({ apiKey: 'YOUR_API_KEY' })` or ensure your `LISTEN_API_KEY` environment variable is correctly configured and accessible in your application's environment.

• TypeError: (0 , podcast_api__WEBPACK_IMPORTED_MODULE_0__.Client) is not a function

  cause This error often occurs in environments using module bundlers or transpilers when a default import is attempted for a library that only provides named exports, or when CommonJS `require` is used and then the result is incorrectly called directly as a function.
  fix Ensure you are using named imports for ESM (`import { Client } from 'podcast-api';`) or destructuring for CommonJS (`const { Client } = require('podcast-api');`). Do not attempt `import Client from 'podcast-api';` or `const Client = require('podcast-api'); Client(...)`.

Warnings

• gotcha Directly using the Podcast API client with an exposed API key in client-side browser JavaScript is strongly discouraged. This can lead to your API key being compromised.
  Fix: Proxy requests through your own backend server or a serverless function (like Cloudflare Workers) to keep your API key secure.
• gotcha Two distinct client classes exist: `Client` for Node.js/browser environments and `ClientForWorkers` for Cloudflare Workers/Pages functions. Using the wrong client can lead to unexpected behavior or errors, especially concerning API key handling.
  Fix: For Node.js or browser, use `import { Client } from 'podcast-api';`. For Cloudflare Workers, use `import { ClientForWorkers } from 'podcast-api';` and ensure your API key is stored as a Worker secret.
• gotcha The library requires Node.js version 10 or higher. Running it on older Node.js versions may result in compatibility issues or runtime errors.
  Fix: Ensure your Node.js environment is updated to version 10 or newer. Check your `node` version using `node -v`.

Install

• npm install podcast-api npm
• yarn add podcast-api yarn
• pnpm add podcast-api pnpm

Imports

• Client
  wrong:

  const Client = require('podcast-api');

  correct:

  import { Client } from 'podcast-api';
  const client = Client({ apiKey: process.env.LISTEN_API_KEY ?? '' });

  Use named import for ESM. For CommonJS, `require` returns an object with named exports, so destructuring `const { Client } = require('podcast-api');` is correct. Trying to instantiate the entire `require` result directly as `Client` is incorrect.
• ClientForWorkers
  wrong:

  const { ClientForWorkers } = require('podcast-api');

  correct:

  import { ClientForWorkers } from 'podcast-api';
  const client = ClientForWorkers({ apiKey: LISTEN_API_KEY });

  This client is specifically designed for Cloudflare Workers and assumes `LISTEN_API_KEY` is available as a secret in the Worker's scope. While a CommonJS `require` might technically work in some build environments for Workers, ESM `import` is the idiomatic and recommended approach for Cloudflare Workers.
• Client

  const { Client } = require('podcast-api');
  const client = Client({ apiKey: process.env.LISTEN_API_KEY ?? '' });

  This is the recommended CommonJS pattern for Node.js and browser environments. Ensure `LISTEN_API_KEY` is securely managed via environment variables.

Quickstart

This quickstart initializes the `podcast-api` client and demonstrates a basic full-text search for podcasts, logging the results. It highlights API key configuration and error handling.

import { Client } from 'podcast-api';

// Initialize the client with your API key.
// For Node.js, use process.env.LISTEN_API_KEY.
// For Cloudflare Workers, use LISTEN_API_KEY from secrets.
// For browser-side, handle key securely (e.g., via a proxy).
const apiKey = process.env.LISTEN_API_KEY ?? 'YOUR_LISTEN_NOTES_API_KEY'; // Replace or ensure env var is set

if (!apiKey || apiKey === 'YOUR_LISTEN_NOTES_API_KEY') {
  console.error('API Key is missing. Please set LISTEN_API_KEY environment variable or replace the placeholder.');
  process.exit(1);
}

const client = Client({ apiKey });

async function searchPodcasts(query) {
  try {
    const response = await client.search({
      q: query,
      sort_by: 'relevance',
      type: 'podcast',
      offset: 0,
      len_min: 10,
      len_max: 30,
      genre_ids: '68,82',
      published_before: 1580172454000,
      published_after: 0,
      only_in: 'title,description',
      language: 'English',
      safe_mode: 0
    });
    console.log(`Found ${response.data.total} podcasts for "${query}":`);
    response.data.results.slice(0, 3).forEach(podcast => {
      console.log(`- ${podcast.title_original} (ID: ${podcast.id})`);
    });
  } catch (error) {
    console.error('Error searching podcasts:', error.message);
  }
}

// Example usage
searchPodcasts('web development');