Search Operations

/**
 * Performs search within Notion workspace
 * @param params - Search parameters including query and filters
 * @param kyOptions - HTTP client options
 * @returns Promise resolving to search results
 */
async search(params: SearchParams, kyOptions?: KyOptions): Promise<SearchResults>;

interface SearchParams {
  /** The ancestor page ID to search within */
  ancestorId: string;
  /** The search query string */
  query: string;
  /** Maximum number of results to return (default: 20) */
  limit?: number;
  /** Additional search filters */
  filters?: SearchFilters;
}

interface SearchFilters {
  /** Whether to include only deleted items (default: false) */
  isDeletedOnly?: boolean;
  /** Whether to include only navigable items (default: false) */
  isNavigableOnly?: boolean;
  /** Whether to exclude template pages (default: true) */
  excludeTemplates?: boolean;
  /** Whether to require edit permissions (default: false) */
  requireEditPermissions?: boolean;
  /** Whether to include public pages without explicit access (default: true) */
  includePublicPagesWithoutExplicitAccess?: boolean;
  /** Filter by ancestor page IDs */
  ancestors?: string[];
  /** Filter by creator user IDs */
  createdBy?: string[];
  /** Filter by editor user IDs */
  editedBy?: string[];
  /** Filter by last edited time range */
  lastEditedTime?: DateRange;
  /** Filter by creation time range */
  createdTime?: DateRange;
}

interface SearchResults {
  recordMap: RecordMap;
  results: SearchResult[];
  total: number;
}

interface SearchResult {
  id: string;
  isNavigable: boolean;
  score: number;
  highlight: {
    pathText: string;
    text: string;
  };
}

import { NotionAPI } from "notion-client";

const api = new NotionAPI();

// Basic search within a workspace
const results = await api.search({
  ancestorId: "workspace-root-page-id",
  query: "project management",
  limit: 20
});

// Search with filters
const filteredResults = await api.search({
  ancestorId: "workspace-root-page-id",
  query: "meeting notes",
  limit: 10,
  filters: {
    excludeTemplates: true,
    isNavigableOnly: true,
    createdBy: ["user-id-1", "user-id-2"]
  }
});

// Search within specific time range
const recentResults = await api.search({
  ancestorId: "workspace-root-page-id", 
  query: "quarterly review",
  filters: {
    lastEditedTime: {
      start_date: "2024-01-01",
      end_date: "2024-03-31"
    }
  }
});

// Process search results
results.results.forEach(result => {
  console.log(`Found: ${result.id} (Score: ${result.score})`);
  console.log(`Navigable: ${result.isNavigable}`);
  if (result.highlight) {
    console.log(`Highlight: ${result.highlight.text}`);
    console.log(`Path: ${result.highlight.pathText}`);
  }
});

console.log(`Total results: ${results.total}`);

const results = await api.search({
  ancestorId: "workspace-id",
  query: "database design"
});

// Sort results by score
const sortedResults = results.results.sort((a, b) => b.score - a.score);

// Filter high-confidence results
const highConfidenceResults = results.results.filter(r => r.score > 0.8);

// Extract page IDs for further processing
const pageIds = results.results.map(r => r.id);

// Get full page data for top results
const topResult = results.results[0];
if (topResult) {
  const fullPage = await api.getPage(topResult.id);
  console.log("Full page data:", fullPage);
}

// Search only within a specific project folder
const projectResults = await api.search({
  ancestorId: "project-folder-page-id",
  query: "task status",
  filters: {
    ancestors: ["project-folder-page-id"]
  }
});

const oneWeekAgo = new Date();
oneWeekAgo.setDate(oneWeekAgo.getDate() - 7);

const recentChanges = await api.search({
  ancestorId: "workspace-id",
  query: "", // Empty query to get all recent changes
  filters: {
    lastEditedTime: {
      start_date: oneWeekAgo.toISOString().split('T')[0],
      end_date: new Date().toISOString().split('T')[0]
    }
  }
});

const authorResults = await api.search({
  ancestorId: "workspace-id",
  query: "documentation",
  filters: {
    createdBy: ["author-user-id"],
    excludeTemplates: true
  }
});

interface SearchConfiguration {
  /** Search type - typically 'BlocksInAncestor' for workspace search */
  type: string;
  /** Search source identifier */
  source: string;
  /** Sort configuration */
  sort: {
    /** Sort field - typically 'relevance' */
    field: string;
  };
}

try {
  const results = await api.search({
    ancestorId: "invalid-page-id",
    query: "test"
  });
} catch (error) {
  if (error.message.includes("not found")) {
    console.error("Page not found or not accessible");
  } else if (error.message.includes("permission")) {
    console.error("Insufficient permissions to search");
  } else {
    console.error("Search failed:", error.message);
  }
}

interface DateRange {
  start_date?: string;
  end_date?: string;
}