podscan 1.0.0

package/dist/index.cjs

@@ -0,0 +1,630 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AlertsResource: () => AlertsResource,
+  EntitiesResource: () => EntitiesResource,
+  EpisodesResource: () => EpisodesResource,
+  ListsResource: () => ListsResource,
+  Paginator: () => Paginator,
+  PodcastsResource: () => PodcastsResource,
+  PodscanClient: () => PodscanClient,
+  PodscanError: () => PodscanError,
+  PublishersResource: () => PublishersResource,
+  TopicsResource: () => TopicsResource,
+  periods: () => periods
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/http.ts
+var PodscanError = class extends Error {
+  code;
+  status;
+  details;
+  constructor({ code, message, status, details }) {
+    super(message);
+    this.name = "PodscanError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+var HttpClient = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  rateLimit = null;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl ?? "https://podscan.fm/api/v1";
+    this.timeout = options.timeout ?? 3e4;
+  }
+  async get(path, params) {
+    const url = this.buildUrl(path, params);
+    return this.request(url, { method: "GET" });
+  }
+  async post(path, body) {
+    const url = this.buildUrl(path);
+    return this.request(url, {
+      method: "POST",
+      body: body ? JSON.stringify(body) : void 0
+    });
+  }
+  buildUrl(path, params) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0 && value !== null) {
+          const serialized = typeof value === "object" ? JSON.stringify(value) : String(value);
+          url.searchParams.set(key, serialized);
+        }
+      }
+    }
+    return url.toString();
+  }
+  async request(url, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort();
+    }, this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: controller.signal,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          Accept: "application/json"
+        }
+      });
+      this.parseRateLimitHeaders(response.headers);
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => null);
+        throw new PodscanError({
+          code: typeof errorBody?.code === "string" ? errorBody.code : "api_error",
+          message: typeof errorBody?.message === "string" ? errorBody.message : `HTTP ${String(response.status)}: ${response.statusText}`,
+          status: response.status,
+          details: errorBody?.details
+        });
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof PodscanError) throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new PodscanError({
+          code: "timeout",
+          message: `Request timed out after ${String(this.timeout)}ms`,
+          status: 0
+        });
+      }
+      throw new PodscanError({
+        code: "network_error",
+        message: error instanceof Error ? error.message : "Unknown network error",
+        status: 0
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  parseRateLimitHeaders(headers) {
+    const limit = headers.get("x-ratelimit-limit");
+    const remaining = headers.get("x-ratelimit-remaining");
+    const used = headers.get("x-ratelimit-used");
+    const resetsAt = headers.get("x-ratelimit-reset");
+    if (limit ?? remaining) {
+      this.rateLimit = {
+        limit: limit ? parseInt(limit, 10) : 0,
+        remaining: remaining ? parseInt(remaining, 10) : 0,
+        used: used ? parseInt(used, 10) : 0,
+        resetsAt: resetsAt ?? null
+      };
+    }
+  }
+};
+
+// src/paginator.ts
+function extractTimestamp(item) {
+  if (item && typeof item === "object") {
+    const record = item;
+    if (typeof record.posted_at === "string") return record.posted_at;
+    if (typeof record.created_at === "string") return record.created_at;
+  }
+  return null;
+}
+function extractId(item) {
+  if (item && typeof item === "object") {
+    const record = item;
+    for (const key of [
+      "episode_id",
+      "podcast_id",
+      "topic_id",
+      "entity_id",
+      "alert_id",
+      "mention_id"
+    ]) {
+      if (typeof record[key] === "string") return record[key];
+    }
+  }
+  return null;
+}
+var Paginator = class {
+  fetcher;
+  _totalSeen = 0;
+  _lastSeenAt = null;
+  _lastSeenId = null;
+  constructor(fetcher) {
+    this.fetcher = fetcher;
+  }
+  async *[Symbol.asyncIterator]() {
+    let currentPage = 1;
+    let lastPage = 1;
+    do {
+      const result = await this.fetcher(currentPage);
+      lastPage = result.pagination.last_page;
+      for (const item of result.items) {
+        this._totalSeen++;
+        const ts = extractTimestamp(item);
+        const id = extractId(item);
+        if (ts) this._lastSeenAt = ts;
+        if (id) this._lastSeenId = id;
+        yield item;
+      }
+      currentPage++;
+    } while (currentPage <= lastPage);
+  }
+  /**
+   * Returns a checkpoint representing the sync position after iteration.
+   * Save this and pass `checkpoint.lastSeenAt` as `since` on the next run
+   * to only fetch new items.
+   */
+  checkpoint() {
+    return {
+      lastSeenAt: this._lastSeenAt ?? "",
+      lastSeenId: this._lastSeenId ?? "",
+      totalSeen: this._totalSeen
+    };
+  }
+  /** Total number of items yielded so far. */
+  get totalSeen() {
+    return this._totalSeen;
+  }
+};
+
+// src/resources/episodes.ts
+var EpisodesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Full-text search across podcast episode transcripts, titles, and descriptions.
+   */
+  async search(params) {
+    return this.http.get("/episodes/search", params);
+  }
+  /**
+   * Auto-paginating search that yields every matching episode across all pages.
+   *
+   * ```ts
+   * for await (const episode of client.episodes.searchAll({ query: 'AI', ...periods.thisWeek() })) {
+   *   console.log(episode.episode_title);
+   * }
+   * ```
+   */
+  searchAll(params) {
+    return new Paginator(async (page) => {
+      const res = await this.search({ ...params, page });
+      return { items: res.episodes, pagination: res.pagination };
+    });
+  }
+  /**
+   * Get detailed information about a specific episode.
+   */
+  async get(params) {
+    const { episode_id, ...query } = params;
+    return this.http.get(`/episodes/${episode_id}`, query);
+  }
+  /**
+   * Get the most recently published podcast episodes.
+   */
+  async getRecent(params) {
+    return this.http.get("/episodes/recent", params);
+  }
+  /**
+   * List all episodes for a specific podcast.
+   */
+  async getByPodcast(params) {
+    const { podcast_id, ...query } = params;
+    return this.http.get(`/podcasts/${podcast_id}/episodes`, query);
+  }
+  /**
+   * Auto-paginating version of `getByPodcast()` that yields every episode.
+   *
+   * ```ts
+   * for await (const ep of client.episodes.getByPodcastAll({
+   *   podcast_id: 'pd_abc',
+   *   ...periods.thisMonth(),
+   * })) {
+   *   console.log(ep.episode_title);
+   * }
+   * ```
+   */
+  getByPodcastAll(params) {
+    return new Paginator(async (page) => {
+      const res = await this.getByPodcast({ ...params, page });
+      return { items: res.episodes, pagination: res.pagination };
+    });
+  }
+};
+
+// src/resources/podcasts.ts
+var PodcastsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Search podcasts by name, topic, or characteristics.
+   */
+  async search(params) {
+    return this.http.get("/podcasts/search", params);
+  }
+  /**
+   * Auto-paginating search that yields every matching podcast across all pages.
+   */
+  searchAll(params) {
+    return new Paginator(async (page) => {
+      const res = await this.search({ ...params, page });
+      return { items: res.podcasts, pagination: res.pagination };
+    });
+  }
+  /**
+   * Get detailed information about a specific podcast.
+   */
+  async get(params) {
+    const { podcast_id, ...query } = params;
+    return this.http.get(`/podcasts/${podcast_id}`, query);
+  }
+};
+
+// src/resources/alerts.ts
+var AlertsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List your team's content monitoring alerts.
+   */
+  async list(params) {
+    return this.http.get("/alerts", params);
+  }
+  /**
+   * Get mentions found by a specific alert.
+   */
+  async getMentions(params) {
+    const { alert_id, ...query } = params;
+    return this.http.get(`/alerts/${alert_id}/mentions`, query);
+  }
+  /**
+   * Create a new content monitoring alert.
+   */
+  async create(params) {
+    return this.http.post("/alerts", params);
+  }
+};
+
+// src/resources/topics.ts
+var TopicsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Discover topics and subjects discussed across podcasts.
+   */
+  async search(params) {
+    return this.http.get("/topics/search", params);
+  }
+  /**
+   * Auto-paginating search that yields every matching topic across all pages.
+   */
+  searchAll(params) {
+    return new Paginator(async (page) => {
+      const res = await this.search({ ...params, page });
+      return { items: res.topics, pagination: res.pagination };
+    });
+  }
+  /**
+   * Get detailed information about a specific topic.
+   */
+  async get(params) {
+    const { topic_id, ...query } = params;
+    return this.http.get(`/topics/${topic_id}`, query);
+  }
+  /**
+   * Get episodes where a specific topic was mentioned.
+   */
+  async getEpisodes(params) {
+    const { topic_id, ...query } = params;
+    return this.http.get(`/topics/${topic_id}/episodes`, query);
+  }
+  /**
+   * Auto-paginating version of `getEpisodes()` that yields every episode for a topic.
+   */
+  getEpisodesAll(params) {
+    return new Paginator(async (page) => {
+      const res = await this.getEpisodes({ ...params, page });
+      return { items: res.episodes, pagination: res.pagination };
+    });
+  }
+  /**
+   * Get currently trending topics across podcasts.
+   */
+  async getTrending(params) {
+    return this.http.get("/topics/trending", params);
+  }
+};
+
+// src/resources/entities.ts
+var EntitiesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Search for people and organizations mentioned across podcasts.
+   */
+  async search(params) {
+    return this.http.get("/entities/search", params);
+  }
+  /**
+   * Auto-paginating search that yields every matching entity across all pages.
+   */
+  searchAll(params) {
+    return new Paginator(async (page) => {
+      const res = await this.search({ ...params, page });
+      return { items: res.entities, pagination: res.pagination };
+    });
+  }
+  /**
+   * Get detailed information about a person or organization.
+   */
+  async get(params) {
+    const { entity_id, ...query } = params;
+    return this.http.get(`/entities/${entity_id}`, query);
+  }
+  /**
+   * Get all podcast appearances for a specific entity.
+   */
+  async getAppearances(params) {
+    const { entity_id, ...query } = params;
+    return this.http.get(`/entities/${entity_id}/appearances`, query);
+  }
+};
+
+// src/resources/lists.ts
+var ListsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get all lists/collections for your team.
+   */
+  async list(params) {
+    return this.http.get("/lists", params);
+  }
+  /**
+   * Get contents of a specific list.
+   */
+  async getItems(params) {
+    const { list_id, ...query } = params;
+    return this.http.get(`/lists/${list_id}/items`, query);
+  }
+  /**
+   * Add items to a list. Accepts mixed item types (podcasts, episodes, entities, topics).
+   */
+  async addItems(params) {
+    const { list_id, ...body } = params;
+    return this.http.post(`/lists/${list_id}/items`, body);
+  }
+};
+
+// src/resources/publishers.ts
+var PublishersResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get publisher information with their podcast portfolio.
+   */
+  async get(params) {
+    const { publisher_id, ...query } = params;
+    return this.http.get(`/publishers/${publisher_id}`, query);
+  }
+};
+
+// src/client.ts
+var PodscanClient = class {
+  http;
+  /** Search and retrieve podcast episodes and recent content. */
+  episodes;
+  /** Search and retrieve podcast metadata. */
+  podcasts;
+  /** Create and manage keyword monitoring alerts and their mentions. */
+  alerts;
+  /** Search, retrieve, and track trending topics across podcasts. */
+  topics;
+  /** Search and retrieve people and organizations mentioned in podcasts. */
+  entities;
+  /** Manage curated collections of podcasts, episodes, entities, and topics. */
+  lists;
+  /** Retrieve publisher information and podcast portfolios. */
+  publishers;
+  constructor(options) {
+    this.http = new HttpClient(options);
+    this.episodes = new EpisodesResource(this.http);
+    this.podcasts = new PodcastsResource(this.http);
+    this.alerts = new AlertsResource(this.http);
+    this.topics = new TopicsResource(this.http);
+    this.entities = new EntitiesResource(this.http);
+    this.lists = new ListsResource(this.http);
+    this.publishers = new PublishersResource(this.http);
+  }
+  /** Current rate-limit info from the most recent API response, or null if no request has been made. */
+  get rateLimit() {
+    return this.http.rateLimit;
+  }
+};
+
+// src/periods.ts
+function toISO(d) {
+  return d.toISOString();
+}
+function startOfDayUTC(d) {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+}
+function startOfWeekUTC(d) {
+  const day = d.getUTCDay();
+  const diff = day === 0 ? 6 : day - 1;
+  const monday = new Date(d);
+  monday.setUTCDate(d.getUTCDate() - diff);
+  return startOfDayUTC(monday);
+}
+function startOfMonthUTC(d) {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1));
+}
+var periods = {
+  /**
+   * From midnight today (UTC) until now.
+   */
+  today() {
+    const now = /* @__PURE__ */ new Date();
+    return {
+      since: toISO(startOfDayUTC(now))
+    };
+  },
+  /**
+   * From midnight yesterday (UTC) to midnight today (UTC).
+   */
+  yesterday() {
+    const now = /* @__PURE__ */ new Date();
+    const todayStart = startOfDayUTC(now);
+    const yesterdayStart = new Date(todayStart);
+    yesterdayStart.setUTCDate(yesterdayStart.getUTCDate() - 1);
+    return {
+      since: toISO(yesterdayStart),
+      before: toISO(todayStart)
+    };
+  },
+  /**
+   * Rolling window: now minus 24 hours.
+   */
+  last24Hours() {
+    const now = /* @__PURE__ */ new Date();
+    const past = new Date(now.getTime() - 24 * 60 * 60 * 1e3);
+    return {
+      since: toISO(past)
+    };
+  },
+  /**
+   * From Monday 00:00 UTC of the current week until now.
+   */
+  thisWeek() {
+    const now = /* @__PURE__ */ new Date();
+    return {
+      since: toISO(startOfWeekUTC(now))
+    };
+  },
+  /**
+   * From Monday 00:00 UTC of last week to Monday 00:00 UTC of this week.
+   */
+  lastWeek() {
+    const now = /* @__PURE__ */ new Date();
+    const thisMonday = startOfWeekUTC(now);
+    const lastMonday = new Date(thisMonday);
+    lastMonday.setUTCDate(lastMonday.getUTCDate() - 7);
+    return {
+      since: toISO(lastMonday),
+      before: toISO(thisMonday)
+    };
+  },
+  /**
+   * From the 1st of the current month (UTC) until now.
+   */
+  thisMonth() {
+    const now = /* @__PURE__ */ new Date();
+    return {
+      since: toISO(startOfMonthUTC(now))
+    };
+  },
+  /**
+   * From the 1st of last month to the 1st of this month (UTC).
+   */
+  lastMonth() {
+    const now = /* @__PURE__ */ new Date();
+    const thisMonth = startOfMonthUTC(now);
+    const lastMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
+    return {
+      since: toISO(lastMonth),
+      before: toISO(thisMonth)
+    };
+  },
+  /**
+   * Rolling window: now minus N days.
+   */
+  lastNDays(n) {
+    const now = /* @__PURE__ */ new Date();
+    const past = new Date(now.getTime() - n * 24 * 60 * 60 * 1e3);
+    return {
+      since: toISO(past)
+    };
+  },
+  /**
+   * Rolling window: now minus N hours.
+   */
+  lastNHours(n) {
+    const now = /* @__PURE__ */ new Date();
+    const past = new Date(now.getTime() - n * 60 * 60 * 1e3);
+    return {
+      since: toISO(past)
+    };
+  },
+  /**
+   * Everything after a given date. Accepts an ISO string or Date object.
+   */
+  since(date) {
+    const d = typeof date === "string" ? new Date(date) : date;
+    return {
+      since: toISO(d)
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AlertsResource,
+  EntitiesResource,
+  EpisodesResource,
+  ListsResource,
+  Paginator,
+  PodcastsResource,
+  PodscanClient,
+  PodscanError,
+  PublishersResource,
+  TopicsResource,
+  periods
+});
+//# sourceMappingURL=index.cjs.map