Collection Operations

/**
 * Fetches data for a specific collection instance
 * @param collectionId - The collection (database) ID
 * @param collectionViewId - The specific view ID within the collection
 * @param collectionView - The collection view configuration object
 * @param options - Options for controlling data fetching
 * @returns Promise resolving to collection instance data
 */
async getCollectionData(
  collectionId: string,
  collectionViewId: string,
  collectionView: any,
  options?: GetCollectionDataOptions
): Promise<CollectionInstance>;

interface GetCollectionDataOptions {
  /** Type of collection view (e.g., 'table', 'board', 'list') */
  type?: CollectionViewType;
  /** Maximum number of items to fetch (default: 999) */
  limit?: number;
  /** Search query to filter results (default: '') */
  searchQuery?: string;
  /** User timezone for date formatting */
  userTimeZone?: string;
  /** Whether to load content cover images (default: true) */
  loadContentCover?: boolean;
  /** HTTP client options for this request */
  kyOptions?: KyOptions;
}

interface CollectionInstance {
  result: CollectionQueryResult;
  recordMap: RecordMap;
}

import { NotionAPI } from "notion-client";

const api = new NotionAPI();

// First get page data to find collection info
const page = await api.getPage("database-page-id");
const collectionId = "2d8aec23-8281-4a94-9090-caaf823dd21a";
const collectionViewId = "ab639a5a-853e-45e1-9ef7-133b486c0acf";
const collectionView = page.collection_view[collectionViewId]?.value;

// Fetch collection data with default options
const collectionData = await api.getCollectionData(
  collectionId,
  collectionViewId,
  collectionView
);

// Fetch limited collection data with search
const filteredCollection = await api.getCollectionData(
  collectionId,
  collectionViewId,
  collectionView,
  {
    limit: 50,
    searchQuery: "important",
    loadContentCover: false
  }
);

// Fetch collection data for specific timezone
const localizedCollection = await api.getCollectionData(
  collectionId,
  collectionViewId,
  collectionView,
  {
    userTimeZone: "Europe/London"
  }
);

// Access collection results
console.log("Collection items:", collectionData.result);
console.log("Collection blocks:", Object.keys(collectionData.recordMap.block));

/**
 * Fetches pages referenced in collection relations
 * @param recordMap - The extended record map containing collection data
 * @param kyOptions - HTTP client options
 * @returns Promise resolving to additional block data
 */
async fetchRelationPages(
  recordMap: ExtendedRecordMap,
  kyOptions?: KyOptions
): Promise<BlockMap>;

interface BlockMap {
  [blockId: string]: BlockRecord;
}

import { NotionAPI } from "notion-client";

const api = new NotionAPI();

// Get page with collections
const page = await api.getPage("database-page-id");

// Fetch additional relation pages
const relationBlocks = await api.fetchRelationPages(page);

// Merge relation pages into main record map
page.block = { ...page.block, ...relationBlocks };

console.log("Total blocks after relations:", Object.keys(page.block).length);

/**
 * Extracts relation page IDs from a block value
 * @param blockValue - The block value containing properties
 * @param collectionSchema - The collection schema defining property types
 * @returns Set of page IDs found in relation properties
 */
extractRelationPageIdsFromBlock(
  blockValue: any,
  collectionSchema: any
): Set<string>;

import { NotionAPI } from "notion-client";

const api = new NotionAPI();

// Get collection data
const page = await api.getPage("database-page-id");
const collectionId = "collection-id";
const collection = page.collection[collectionId]?.value;
const schema = collection?.schema;

// Extract relation IDs from a specific block
const blockValue = page.block["some-block-id"]?.value;
const relationIds = api.extractRelationPageIdsFromBlock(blockValue, schema);

console.log("Related page IDs:", Array.from(relationIds));

type CollectionViewType = 
  | "table"      // Table view with rows and columns
  | "board"      // Kanban board view
  | "list"       // List view
  | "gallery"    // Gallery/card view
  | "calendar"   // Calendar view
  | "timeline";  // Timeline view

// Example of accessing collection filters from a view
const collectionView = page.collection_view[collectionViewId]?.value;

// Property filters (simple filters)
const propertyFilters = collectionView?.format?.property_filters || [];
console.log("Property filters:", propertyFilters);

// Query filters (advanced filters)
const queryFilters = collectionView?.query2?.filter?.filters || [];
console.log("Query filters:", queryFilters);

// Sorting configuration
const sorts = collectionView?.query2?.sort || [];
console.log("Sort configuration:", sorts);

const collectionData = await api.getCollectionData(
  collectionId,
  collectionViewId,
  collectionView
);

// Access different result types
const result = collectionData.result as any;

// For table/list views
if (result.type === "results") {
  console.log("Block IDs:", result.blockIds);
  console.log("Total items:", result.total);
}

// For board views
if (result.reducerResults) {
  const boardColumns = result.reducerResults;
  Object.keys(boardColumns).forEach(columnKey => {
    const columnData = boardColumns[columnKey];
    console.log(`Column ${columnKey}:`, columnData);
  });
}

// Access the actual page/block data
const blocks = collectionData.recordMap.block;
Object.keys(blocks).forEach(blockId => {
  const block = blocks[blockId]?.value;
  if (block?.type === "page") {
    console.log("Page properties:", block.properties);
  }
});