pi-twitterapi.io 0.1.1

package/src/twitterapi/tweet.ts

@@ -0,0 +1,112 @@
+import { isObject, type Tweet, type TweetMedia, type UserProfile } from "./core.js";
+
+
+function asMedia(raw: unknown): TweetMedia | undefined {
+  if (!isObject(raw)) return undefined;
+  const str = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+  const variants = isObject(raw.video_info) && Array.isArray(raw.video_info.variants) ? raw.video_info.variants : [];
+  const playable = variants
+    .filter((v) => isObject(v) && typeof v.url === "string" && v.content_type === "video/mp4")
+    .sort((a, b) => Number((a as Record<string, unknown>).bitrate ?? 0) - Number((b as Record<string, unknown>).bitrate ?? 0))
+    .map((v) => String((v as Record<string, unknown>).url));
+  const duration = isObject(raw.video_info) && typeof raw.video_info.duration_millis === "number" ? raw.video_info.duration_millis : undefined;
+  const media: TweetMedia = {
+    type: str(raw.type),
+    url: str(raw.media_url_https) ?? str(raw.media_url),
+    videoVariants: playable.length > 0 ? playable : undefined,
+    durationMillis: duration,
+  };
+  return media.url || media.videoVariants ? media : undefined;
+}
+
+function asMediaList(raw: unknown): TweetMedia[] | undefined {
+  if (!isObject(raw) || !Array.isArray(raw.media)) return undefined;
+  const list = raw.media.map(asMedia).filter((m): m is TweetMedia => m !== undefined);
+  return list.length > 0 ? list : undefined;
+}
+
+export function asTweet(raw: unknown): Tweet | undefined {
+  if (!isObject(raw) || typeof raw.text !== "string") return undefined;
+  const author = isObject(raw.author) ? raw.author : undefined;
+  const num = (v: unknown) => (typeof v === "number" ? v : undefined);
+  const str = (v: unknown) => (typeof v === "string" ? v : undefined);
+  const extended = isObject(raw.extendedEntities)
+    ? asMediaList(raw.extendedEntities)
+    : isObject(raw.extended_entities)
+      ? asMediaList(raw.extended_entities)
+      : undefined;
+  const media = extended ?? (isObject(raw.entities) ? asMediaList(raw.entities) : undefined);
+  return {
+    id: str(raw.id),
+    url: str(raw.url),
+    text: raw.text,
+    createdAt: str(raw.createdAt),
+    likeCount: num(raw.likeCount),
+    retweetCount: num(raw.retweetCount),
+    replyCount: num(raw.replyCount),
+    viewCount: num(raw.viewCount),
+    author: author ? {
+      userName: str(author.userName),
+      name: str(author.name),
+      followers: num(author.followers),
+    } : undefined,
+    media,
+  };
+}
+
+/**
+ * Status id from an X/Twitter permalink.
+ *
+ * Only validated x.com / twitter.com hosts are considered, and the id must be a
+ * whole path segment, so `https://x.com/search?q=/status/111` and
+ * `.../status/111garbage` cannot masquerade as a real post. Real suffixes such
+ * as `/photo/1` still resolve. This is the single X-URL parser for the package:
+ * `synthesize.ts` re-exports it for citation matching.
+ */
+export function statusIdFromUrl(url: string): string | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const host = parsed.hostname.toLowerCase();
+  const isX = host === "x.com" || host.endsWith(".x.com") || host === "twitter.com" || host.endsWith(".twitter.com");
+  if (!isX) return undefined;
+  const match = /\/status(?:es)?\/(\d+)(?:\/|$)/.exec(parsed.pathname);
+  return match?.[1];
+}
+
+/**
+ * Accept either a bare post id or an X permalink and return the id.
+ * Rejects anything else so a malformed reference fails before the request.
+ */
+export function tweetIdFromInput(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  if (/^\d{1,25}$/.test(trimmed)) return trimmed;
+  return statusIdFromUrl(trimmed);
+}
+
+// --------------------------------------------------------------------- users
+
+export function asUser(raw: unknown): UserProfile | undefined {
+  if (!isObject(raw)) return undefined;
+  const str = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+  const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+  const handle = str(raw.screen_name) ?? str(raw.userName) ?? str(raw.username);
+  if (!handle) return undefined;
+  return {
+    id: str(raw.id),
+    handle,
+    name: str(raw.name),
+    bio: str(raw.description) ?? (isObject(raw.profile_bio) ? str(raw.profile_bio.description) : undefined),
+    followers: num(raw.followers_count) ?? num(raw.followers),
+    following: num(raw.following_count) ?? num(raw.following),
+    verified: raw.isBlueVerified === true || raw.verified === true,
+    profileUrl: `https://x.com/${handle}`,
+    location: str(raw.location),
+    createdAt: str(raw.created_at) ?? str(raw.createdAt),
+  };
+}
+

package/src/twitterapi/window.ts

@@ -0,0 +1,184 @@
+import type { LocalWindow, NormalizedSearchParams } from "./core.js";
+
+/**
+ * twitterapi.io evaluates X `since:` / `until:` day boundaries at 04:00 UTC
+ * (verified empirically: `until:2026-09-25` returned tweets up to
+ * 2026-09-26T03:59:59Z, i.e. a UTC-4 day boundary rather than UTC midnight).
+ * Time-of-day components (`until:2026-09-29_12:00:00_UTC`) are not honored.
+ *
+ * Consequences for local calendar days (offset = local - UTC):
+ *  - start: the upstream bound may fall after the local one, so pad `since:`
+ *    backwards by the whole days needed. Padding the start only adds older
+ *    tweets to the tail of a newest-first scan, which is harmless.
+ *  - end: the upstream bound may fall before the local one, leaving a gap of
+ *    max(0, -offset - 4) hours at the end of the day. We deliberately do NOT
+ *    pad `until:` forward: that pushes a full extra day of newer tweets ahead
+ *    of the requested range and starves `count` on any busy topic (observed:
+ *    0 results for a single local day).
+ */
+/**
+ * Hour (UTC) at which twitterapi.io resolves `since:`/`until:` day boundaries.
+ * Probed in September, when US Eastern is UTC-4, so a fixed 04:00Z and New York
+ * local midnight are indistinguishable. Start padding therefore adds one extra
+ * hour (see {@link UPSTREAM_START_PAD_HOURS}): over-padding only adds older tail
+ * posts that are trimmed client-side, while under-padding would silently drop
+ * the first hour of the local day if the boundary is really 05:00Z in winter.
+ */
+export const UPSTREAM_BOUNDARY_UTC_HOUR = 4;
+/** Conservative start-padding boundary; see {@link UPSTREAM_BOUNDARY_UTC_HOUR}. */
+export const UPSTREAM_START_PAD_HOURS = UPSTREAM_BOUNDARY_UTC_HOUR + 1;
+export const MS_PER_HOUR = 3_600_000;
+export const MS_PER_DAY = 86_400_000;
+
+function wallClockAsUtc(y: number, m: number, d: number): number {
+  return Date.UTC(y, m - 1, d, 0, 0, 0);
+}
+
+/**
+ * UTC instant at which a local calendar day begins, resolved against the host
+ * timezone.
+ *
+ * Rather than trusting one offset probe, both plausible offsets (well before and
+ * well after the boundary) are turned into candidate instants, each candidate is
+ * checked for actually reading as the target local date, and the earliest valid
+ * one wins. A single probe is not enough: transitions happen at local midnight in
+ * some zones (America/Sao_Paulo) and at 02:00/03:00 in others
+ * (Australia/Sydney, America/New_York), so any fixed probe distance is wrong for
+ * one of those shapes. Validating candidates also gives the correct answers when
+ * local midnight does not exist (spring forward) or happens twice (fall back).
+ */
+function hostLocalMidnightUtc(y: number, m: number, d: number): number {
+  const wall = wallClockAsUtc(y, m, d);
+  const dayIndex = Math.floor(wall / MS_PER_DAY);
+  const probeOffsets = [
+    new Date(wall - 12 * MS_PER_HOUR).getTimezoneOffset() * 60_000,
+    new Date(wall + 12 * MS_PER_HOUR).getTimezoneOffset() * 60_000,
+  ];
+  const candidates = [...new Set(probeOffsets)].map((offset) => wall + offset).sort((a, b) => a - b);
+
+  for (const candidate of candidates) {
+    const localWall = candidate - new Date(candidate).getTimezoneOffset() * 60_000;
+    if (Math.floor(localWall / MS_PER_DAY) === dayIndex) return candidate;
+  }
+  // Both candidates land on another local day: the requested day is unreachable
+  // (a whole skipped day), so the earliest candidate is the closest boundary.
+  return candidates[0];
+}
+
+function fixedLocalMidnightUtc(y: number, m: number, d: number, offsetMinutes: number): number {
+  return wallClockAsUtc(y, m, d) - offsetMinutes * 60_000;
+}
+
+function parseDateParts(date: string): [number, number, number] {
+  const [y, m, d] = date.split("-").map(Number);
+  return [y, m, d];
+}
+
+function addDaysToDate(date: string, days: number): [number, number, number] {
+  const [y, m, d] = parseDateParts(date);
+  const shifted = new Date(wallClockAsUtc(y, m, d) + days * MS_PER_DAY);
+  return [shifted.getUTCFullYear(), shifted.getUTCMonth() + 1, shifted.getUTCDate()];
+}
+
+/**
+ * Latest upstream `since:` date whose 04:00 UTC boundary is at or before the
+ * window start, so the requested window is always covered.
+ */
+export function upstreamStartDateString(startMs: number): string {
+  return new Date(startMs - UPSTREAM_START_PAD_HOURS * MS_PER_HOUR).toISOString().slice(0, 10);
+}
+
+/** UTC instant where the upstream `until:` bound for a date stops returning posts. */
+export function upstreamEndMs(toDate: string): number {
+  const [y, m, d] = addDaysToDate(toDate, 1);
+  return wallClockAsUtc(y, m, d) + UPSTREAM_BOUNDARY_UTC_HOUR * MS_PER_HOUR;
+}
+
+function shiftDateString(date: string, days: number): string {
+  const [y, m, d] = addDaysToDate(date, days);
+  return `${String(y).padStart(4, "0")}-${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
+}
+
+const X_DATE_RE = /^[A-Za-z]{3} ([A-Za-z]{3}) (\d{2}) (\d{2}):(\d{2}):(\d{2}) ([+-]\d{4}) (\d{4})$/;
+const MONTHS: Record<string, number> = {
+  Jan: 0, Feb: 1, Mar: 2, Apr: 3, May: 4, Jun: 5,
+  Jul: 6, Aug: 7, Sep: 8, Oct: 9, Nov: 10, Dec: 11,
+};
+
+/** Parse X's `Thu Oct 01 04:02:43 +0000 2026` (and ISO-8601) into epoch ms. */
+export function parseTweetDate(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const match = X_DATE_RE.exec(value.trim());
+  if (match) {
+    const month = MONTHS[match[1]];
+    if (month === undefined) return undefined;
+    const [, , day, hour, minute, second, offset, year] = match;
+    const sign = offset.startsWith("-") ? -1 : 1;
+    const offsetMinutes = sign * (Number(offset.slice(1, 3)) * 60 + Number(offset.slice(3, 5)));
+    const utc = Date.UTC(Number(year), month, Number(day), Number(hour), Number(minute), Number(second));
+    return utc - offsetMinutes * 60_000;
+  }
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+
+/**
+ * Resolve `from_date` / `to_date` (local calendar days) into a UTC window.
+ * One-sided filters stay one-sided: an absent bound is left unbounded.
+ * Passing an explicit `localUtcOffsetMinutes` selects fixed-offset mode;
+ * otherwise each boundary uses the host's offset at that date (DST-correct).
+ */
+export function resolveLocalWindow(
+  params: NormalizedSearchParams,
+  localUtcOffsetMinutes?: number,
+): LocalWindow | undefined {
+  if (!params.from_date && !params.to_date) return undefined;
+  const fixed = localUtcOffsetMinutes !== undefined;
+  const midnight = (date: string): number => {
+    const [y, m, d] = parseDateParts(date);
+    return fixed
+      ? fixedLocalMidnightUtc(y, m, d, localUtcOffsetMinutes)
+      : hostLocalMidnightUtc(y, m, d);
+  };
+
+  const startMs = params.from_date ? midnight(params.from_date) : Number.NEGATIVE_INFINITY;
+  const endMs = params.to_date ? midnight(shiftDateString(params.to_date, 1)) : Number.POSITIVE_INFINITY;
+
+  let zone: string;
+  if (fixed) {
+    const sign = localUtcOffsetMinutes < 0 ? "-" : "+";
+    const abs = Math.abs(localUtcOffsetMinutes);
+    zone = `UTC${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")} (fixed)`;
+  } else {
+    const reference = Number.isFinite(startMs) ? startMs : endMs;
+    const offsetMinutes = -new Date(reference).getTimezoneOffset();
+    const sign = offsetMinutes < 0 ? "-" : "+";
+    const abs = Math.abs(offsetMinutes);
+    zone = `host timezone, UTC${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")} at window ${Number.isFinite(startMs) ? "start" : "end"}`;
+  }
+
+  const shortfallHours = params.to_date ? Math.max(0, (endMs - upstreamEndMs(params.to_date)) / MS_PER_HOUR) : 0;
+  const trimHours = params.to_date ? Math.max(0, (upstreamEndMs(params.to_date) - endMs) / MS_PER_HOUR) : 0;
+
+  return {
+    startMs,
+    endMs,
+    fromDate: params.from_date,
+    toDate: params.to_date,
+    zone,
+    shortfallHours,
+    trimHours,
+  };
+}
+
+/**
+ * Pad the upstream `since:` back so the requested window start is always
+ * covered. The `until:` bound is never padded forward: that would push a full
+ * extra day of newer posts ahead of the range and starve `count` on busy topics.
+ */
+export function withPaddedStart(params: NormalizedSearchParams, window: LocalWindow | undefined): NormalizedSearchParams {
+  if (!params.from_date || !window || !Number.isFinite(window.startMs)) return params;
+  const padded = upstreamStartDateString(window.startMs);
+  return padded === params.from_date ? params : { ...params, from_date: padded };
+}

package/src/twitterapi.ts

@@ -0,0 +1,16 @@
+/**
+ * twitterapi.io backend — pure request/response logic (no pi imports).
+ * Testable with an injected fetcher.
+ *
+ * Barrel: internal wiring for the split modules (core types, params, tweet/user
+ * mapping, date window, transport, search and endpoint readers). The *published*
+ * surface is `src/index.ts`; `export *` here also exposes sibling-module helpers
+ * to the rest of the source tree by design.
+ */
+export * from "./twitterapi/core.js";
+export * from "./twitterapi/params.js";
+export * from "./twitterapi/tweet.js";
+export * from "./twitterapi/window.js";
+export * from "./twitterapi/http.js";
+export * from "./twitterapi/search.js";
+export * from "./twitterapi/endpoints.js";

package/src/types.ts

@@ -0,0 +1,16 @@
+/**
+ * Result shape shared by the format, synthesis and tool layers.
+ *
+ * `pi-twitterapi.io` returns an answer plus citation URLs: the retrieved posts
+ * are synthesized into `text` and `citations` before being rendered.
+ */
+export interface TwitterSearchDetails {
+  query: string;
+  model: string;
+  text: string;
+  citations: string[];
+  /** Synthesis completions run while answering (0 when nothing was synthesized). */
+  synthesisCalls?: number;
+  /** Disclosures worth surfacing to the user; rendered as a trailing `## Notes` section. */
+  notes?: string[];
+}