nolo-cli 0.1.40 → 0.1.41

package/integrations/xhs-reader/types.ts

@@ -0,0 +1,244 @@
+// XHS Desktop Connector - Read-only types
+
+export type XhsFailureCode =
+  | "not_logged_in"
+  | "login_required"
+  | "blocked"
+  | "empty_profile_state"
+  | "profile_not_found"
+  | "note_not_found"
+  | "rate_limited"
+  | "network_error"
+  | "parse_error"
+  | "comment_disabled"
+  | "unknown";
+
+export type XhsReadFailure = {
+  ok: false;
+  code: XhsFailureCode;
+  message: string;
+  fetchedAt: string;
+};
+
+export type XhsReadSuccess<T> = {
+  ok: true;
+  data: T;
+  fetchedAt: string;
+};
+
+export type XhsReadResult<T> = XhsReadSuccess<T> | XhsReadFailure;
+
+// --- Collector diagnostics (redacted, no secrets) ---
+
+export type XhsCollectorDiagnostic = {
+  /** Why the collector returned empty or failed data. */
+  code: XhsFailureCode;
+  /** Human-readable explanation. */
+  message: string;
+  /** Page title at the time of collection (may be empty). */
+  pageTitle?: string;
+  /** Final page URL after navigation (may differ if redirected). */
+  finalUrl?: string;
+  /** Whether a login wall / prompt was detected on the page. */
+  loginDetected?: boolean;
+  /** Whether a captcha / verification wall was detected. */
+  captchaDetected?: boolean;
+  /** Whether __INITIAL_STATE__ was present and non-empty. */
+  initialStatePresent?: boolean;
+  /** Number of note-like keys found inside __INITIAL_STATE__. */
+  initialStateNoteCount?: number;
+  /** Number of user_posted API responses captured. */
+  capturedApiResponseCount?: number;
+  /** HTTP status of the first captured user_posted response (if any). */
+  firstApiResponseStatus?: number;
+  /** Whether the page URL after navigation looks like a redirect to login. */
+  redirectedToLogin?: boolean;
+};
+
+// --- Profile ---
+
+export type XhsProfile = {
+  userId: string;
+  nickname: string;
+  redId?: string;
+  avatarUrl?: string;
+  desc?: string;
+  ipLocation?: string;
+  gender?: string; // "male" | "female" | "0" (unknown)
+  interactionCounts?: {
+    follows?: number;
+    fans?: number;
+    likesAndCollects?: number;
+  };
+};
+
+export type XhsNoteSummary = {
+  noteId: string;
+  title?: string;
+  coverUrl?: string;
+  type?: "normal" | "video";
+  likedCount?: number;
+  // kept from initial state / user_posted page
+  xsecToken?: string; // internal use only - must not appear in public exports
+};
+
+// --- Note Detail ---
+
+export type XhsNoteDetail = {
+  noteId: string;
+  title: string;
+  desc: string;
+  type: "normal" | "video";
+  userId: string;
+  nickname: string;
+  avatarUrl?: string;
+  imageUrls?: string[];
+  videoUrl?: string;
+  tagList?: string[];
+  ipLocation?: string;
+  metrics: {
+    likedCount: number;
+    collectedCount: number;
+    commentCount: number;
+    shareCount: number;
+  };
+  createdAt?: string;
+  lastUpdateTime?: string;
+};
+
+// --- Comments ---
+
+export type XhsComment = {
+  commentId: string;
+  userId: string;
+  nickname: string;
+  avatarUrl?: string;
+  content: string;
+  likeCount: number;
+  subCommentCount: number;
+  subComments?: XhsComment[]; // embedded samples only
+  ipLocation?: string;
+  createdAt?: string;
+};
+
+export type XhsCommentPage = {
+  comments: XhsComment[];
+  hasMore: boolean;
+  cursor?: string;
+};
+
+// --- Analyzed Result ---
+
+export type XhsTopNote = {
+  noteId: string;
+  title?: string;
+  count: number;
+};
+
+export type XhsCommentBucket = {
+  label: string;
+  count: number;
+  sampleCommentIds: string[];
+};
+
+export type XhsProfileAnalysis = {
+  totalNotes: number;
+  highestLikedNote: XhsTopNote | null;
+  highestCommentedNote: XhsTopNote | null;
+  highestCollectedNote: XhsTopNote | null;
+  highestSharedNote: XhsTopNote | null;
+  commentBuckets: XhsCommentBucket[];
+  topLikedComments: XhsComment[];
+};
+
+// --- Collection Status (assisted mode) ---
+
+export type XhsCollectionMode = "conservative" | "assisted";
+export type XhsAssistedAction = "snapshot" | "read_more_notes" | "read_comments";
+
+export type XhsNextSuggestedAction = {
+  action: "read_more_notes" | "read_comments" | "save_to_table" | "manual_login";
+  label: string;
+  reason: string;
+};
+
+export type XhsCollectionStatus = {
+  mode: XhsCollectionMode;
+  action: XhsAssistedAction;
+  extendedCollectionConsent: boolean;
+  assistedStepCount: number;
+  limits: {
+    maxAssistedSteps: number;
+    maxScrollPages: number;
+    maxCommentPagesPerNote: number;
+    includeComments: boolean;
+  };
+  nextSuggestedAction?: XhsNextSuggestedAction;
+};
+
+// --- Full collection result ---
+
+export type XhsProfileCollection = {
+  profile: XhsProfile;
+  notes: XhsNoteSummary[];
+  noteDetails: XhsNoteDetail[];
+  commentsByNote: Record<string, XhsComment[]>;
+  analysis: XhsProfileAnalysis;
+  /** Present only when the collector detected an issue. Never contains secrets. */
+  diagnostic?: XhsCollectorDiagnostic;
+  /** Collection status for assisted automation mode. */
+  collectionStatus?: XhsCollectionStatus;
+};
+
+// --- URL parsing result ---
+
+export type XhsParsedProfileUrl = {
+  userId: string;
+  canonicalUrl: string;
+};
+
+export type XhsParsedNoteUrl = {
+  noteId: string;
+  canonicalUrl: string;
+  xsecToken?: string; // preserved internally only
+};
+
+// --- Redaction ---
+
+export type XhsConnectorOptions = {
+  profileUrl: string;
+  maxScrollPages?: number; // default 0
+  enrichDetails?: boolean; // default false
+  includeComments?: boolean; // default false
+  maxCommentPagesPerNote?: number; // default 1
+  headless?: boolean; // default true
+  cookieDir?: string;
+  fetchImpl?: typeof fetch;
+  /** Assisted mode: "conservative" (default) or "assisted" */
+  collectionMode?: XhsCollectionMode;
+  /** Which action to perform in assisted mode */
+  assistedAction?: XhsAssistedAction;
+  /** Max assisted steps (1..3), bounds scroll/comment pages */
+  maxAssistedSteps?: number;
+};
+
+// Helper to create failure
+export function createXhsFailure(args: {
+  code: XhsFailureCode;
+  message: string;
+}): XhsReadFailure {
+  return {
+    ok: false,
+    code: args.code,
+    message: args.message,
+    fetchedAt: new Date().toISOString(),
+  };
+}
+
+export function createXhsSuccess<T>(data: T): XhsReadSuccess<T> {
+  return {
+    ok: true,
+    data,
+    fetchedAt: new Date().toISOString(),
+  };
+}

package/integrations/xhs-reader/url.ts

@@ -0,0 +1,57 @@
+import type { XhsParsedProfileUrl, XhsParsedNoteUrl } from "./types";
+
+const PROFILE_RE =
+  /(?:(?:https?:\/\/)?(?:www\.)?xiaohongshu\.com)?\/user\/profile\/([a-f0-9]{24})(?:\?[^#]*)?/i;
+
+const NOTE_RE =
+  /(?:(?:https?:\/\/)?(?:www\.)?xiaohongshu\.com)?\/(?:explore|discovery\/item)\/([a-f0-9]{24})(?:\?[^#]*)?/i;
+
+/**
+ * Parse a XHS profile URL and return userId + canonical URL.
+ * Accepts full URLs and path-only forms.
+ */
+export function parseXhsProfileUrl(input: string): XhsParsedProfileUrl {
+  const match = input.match(PROFILE_RE);
+  if (!match) {
+    throw new Error(`Invalid XHS profile URL: ${input}`);
+  }
+  const userId = match[1];
+  return {
+    userId,
+    canonicalUrl: `https://www.xiaohongshu.com/user/profile/${userId}`,
+  };
+}
+
+/**
+ * Parse a XHS note URL and return noteId + canonical URL.
+ * The xsecToken query param is preserved in the result for internal use only.
+ */
+export function parseXhsNoteUrl(input: string): XhsParsedNoteUrl {
+  const match = input.match(NOTE_RE);
+  if (!match) {
+    throw new Error(`Invalid XHS note URL: ${input}`);
+  }
+  const noteId = match[1];
+
+  // Extract xsec_token if present (internal use only)
+  let xsecToken: string | undefined;
+  try {
+    const urlObj = new URL(input.startsWith("http") ? input : `https://www.xiaohongshu.com${input}`);
+    xsecToken = urlObj.searchParams.get("xsec_token") ?? undefined;
+  } catch {
+    // ignore parse errors
+  }
+
+  return {
+    noteId,
+    canonicalUrl: `https://www.xiaohongshu.com/explore/${noteId}`,
+    xsecToken,
+  };
+}
+
+/**
+ * Validate that a string looks like a valid XHS note ID (24 hex chars).
+ */
+export function isValidXhsId(id: string): boolean {
+  return /^[a-f0-9]{24}$/i.test(id);
+}