Notion for Non-Technical Founders: What No One Tells You

// Notion API v2 Rate Limit Benchmark Tool
// Dependencies: @notionhq/client@2.2.13 (https://github.com/notionhq/client), dotenv@16.3.1, csv-writer@1.6.0
require('dotenv').config();
const { Client } = require('@notionhq/client');
const fs = require('fs');
const createCsvWriter = require('csv-writer').createObjectCsvWriter;

// Validate required environment variables
if (!process.env.NOTION_TOKEN) {
  throw new Error('NOTION_TOKEN environment variable is required. Get it from https://www.notion.so/my-integrations');
}
if (!process.env.NOTION_DATABASE_ID) {
  throw new Error('NOTION_DATABASE_ID environment variable is required. Use a test database with at least 1 row.');
}

// Initialize Notion client with timeout and retry config
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  timeout: 10000, // 10 second timeout per request
  retryOptions: {
    maxRetries: 0, // We handle retries manually to measure rate limits accurately
  },
});

// CSV writer to log benchmark results
const csvWriter = createCsvWriter({
  path: `notion-rate-limit-benchmark-${Date.now()}.csv`,
  header: [
    { id: 'requestId', title: 'Request ID' },
    { id: 'timestamp', title: 'Timestamp (ISO)' },
    { id: 'status', title: 'HTTP Status' },
    { id: 'latencyMs', title: 'Latency (ms)' },
    { id: 'retryAfter', title: 'Retry-After Header (sec)' },
    { id: 'error', title: 'Error Message' },
  ],
});

/**
 * Executes a single Notion API request to query a database, measures latency,
 * and handles rate limit (429) responses manually.
 * @param {number} requestId - Sequential ID of the request
 * @returns {Object} Benchmark result object
 */
async function benchmarkRequest(requestId) {
  const startTime = Date.now();
  let status = null;
  let retryAfter = null;
  let errorMsg = null;

  try {
    // Query the test database with a limit of 1 to minimize payload size
    const response = await notion.databases.query({
      database_id: process.env.NOTION_DATABASE_ID,
      page_size: 1,
    });
    status = response.status; // Should be 200 for successful requests
  } catch (err) {
    // Handle Notion API error responses
    if (err.code === 'rate_limited') {
      status = 429;
      retryAfter = err.headers?.['retry-after'] ? parseInt(err.headers['retry-after'], 10) : null;
      errorMsg = `Rate limited: ${err.message}`;
    } else if (err.status) {
      status = err.status;
      errorMsg = `API Error: ${err.message}`;
    } else {
      status = 500;
      errorMsg = `Network Error: ${err.message}`;
    }
  } finally {
    const latencyMs = Date.now() - startTime;
    return {
      requestId,
      timestamp: new Date().toISOString(),
      status,
      latencyMs,
      retryAfter,
      error: errorMsg,
    };
  }
}

/**
 * Runs the full benchmark suite: 100 sequential requests to measure baseline rate limits
 */
async function runBenchmark() {
  const TOTAL_REQUESTS = 100;
  const results = [];
  console.log(`Starting Notion API rate limit benchmark: ${TOTAL_REQUESTS} sequential requests...`);

  for (let i = 0; i < TOTAL_REQUESTS; i++) {
    const result = await benchmarkRequest(i + 1);
    results.push(result);
    // Log progress every 10 requests
    if ((i + 1) % 10 === 0) {
      console.log(`Completed ${i + 1}/${TOTAL_REQUESTS} requests...`);
    }
  }

  // Write results to CSV
  await csvWriter.writeRecords(results);
  console.log(`Benchmark complete. Results written to ${csvWriter.path}`);

  // Calculate summary metrics
  const rateLimited = results.filter(r => r.status === 429).length;
  const avgLatency = results.reduce((sum, r) => sum + r.latencyMs, 0) / results.length;
  const p99Latency = results.map(r => r.latencyMs).sort((a,b) => a - b)[Math.floor(results.length * 0.99)];

  console.log('\n=== Benchmark Summary ===');
  console.log(`Total Requests: ${TOTAL_REQUESTS}`);
  console.log(`Rate Limited Requests (429): ${rateLimited} (${((rateLimited/TOTAL_REQUESTS)*100).toFixed(1)}%)`);
  console.log(`Average Latency: ${avgLatency.toFixed(2)}ms`);
  console.log(`P99 Latency: ${p99Latency}ms`);
}

// Execute benchmark if run directly
if (require.main === module) {
  runBenchmark().catch(err => {
    console.error('Benchmark failed:', err.message);
    process.exit(1);
  });
}

// Notion to PostgreSQL Sync Engine with Schema Mapping & Conflict Resolution
// Dependencies: @notionhq/client@2.2.13 (https://github.com/notionhq/client), pg@8.11.3, dotenv@16.3.1
require('dotenv').config();
const { Client: NotionClient } = require('@notionhq/client');
const { Client: PgClient } = require('pg');

// Validate environment variables
const requiredEnvVars = ['NOTION_TOKEN', 'NOTION_DATABASE_ID', 'PG_HOST', 'PG_PORT', 'PG_USER', 'PG_PASSWORD', 'PG_DATABASE'];
for (const varName of requiredEnvVars) {
  if (!process.env[varName]) {
    throw new Error(`Missing required environment variable: ${varName}`);
  }
}

// Initialize clients
const notion = new NotionClient({ auth: process.env.NOTION_TOKEN });
const pg = new PgClient({
  host: process.env.PG_HOST,
  port: process.env.PG_PORT,
  user: process.env.PG_USER,
  password: process.env.PG_PASSWORD,
  database: process.env.PG_DATABASE,
});

// Schema mapping: Notion property type -> PostgreSQL column type
const SCHEMA_MAP = {
  title: 'TEXT',
  rich_text: 'TEXT',
  number: 'NUMERIC',
  select: 'TEXT',
  multi_select: 'TEXT[]',
  date: 'TIMESTAMPTZ',
  checkbox: 'BOOLEAN',
  url: 'TEXT',
  email: 'TEXT',
  phone_number: 'TEXT',
  formula: 'TEXT', // Simplified: store formula result as text
};

/**
 * Converts a Notion property value to a PostgreSQL-compatible value
 * @param {Object} property - Notion property object
 * @param {string} type - Notion property type
 * @returns {*} PostgreSQL-compatible value
 */
function convertNotionValue(property, type) {
  try {
    switch (type) {
      case 'title':
        return property?.title?.[0]?.plain_text || null;
      case 'rich_text':
        return property?.rich_text?.[0]?.plain_text || null;
      case 'number':
        return property?.number || null;
      case 'select':
        return property?.select?.name || null;
      case 'multi_select':
        return property?.multi_select?.map(opt => opt.name) || [];
      case 'date':
        return property?.date?.start ? new Date(property.date.start) : null;
      case 'checkbox':
        return property?.checkbox || false;
      case 'url':
        return property?.url || null;
      case 'email':
        return property?.email || null;
      case 'phone_number':
        return property?.phone_number || null;
      case 'formula':
        // Handle formula result types
        const formulaResult = property?.formula;
        if (!formulaResult) return null;
        if (formulaResult.type === 'string') return formulaResult.string;
        if (formulaResult.type === 'number') return formulaResult.number;
        if (formulaResult.type === 'boolean') return formulaResult.boolean;
        return JSON.stringify(formulaResult);
      default:
        return JSON.stringify(property);
    }
  } catch (err) {
    console.error(`Error converting ${type} property:`, err.message);
    return null;
  }
}

/**
 * Syncs all pages from a Notion database to PostgreSQL
 */
async function syncNotionToPostgres() {
  await pg.connect();
  console.log('Connected to PostgreSQL. Starting sync...');

  // 1. Create PostgreSQL table if not exists
  const dbId = process.env.NOTION_DATABASE_ID.replace(/-/g, '');
  const tableName = `notion_${dbId}`;
  console.log(`Syncing to table: ${tableName}`);

  // Fetch Notion database schema to create columns
  const dbSchema = await notion.databases.retrieve({ database_id: process.env.NOTION_DATABASE_ID });
  const properties = dbSchema.properties;

  // Build CREATE TABLE query
  const columnDefs = Object.entries(properties).map(([name, prop]) => {
    const pgType = SCHEMA_MAP[prop.type] || 'JSONB';
    // Sanitize column name: replace spaces with underscores, lowercase
    const colName = name.toLowerCase().replace(/\s+/g, '_').replace(/[^a-z0-9_]/g, '');
    return `"${colName}" ${pgType}`;
  });

  const createTableQuery = `
    CREATE TABLE IF NOT EXISTS "${tableName}" (
      notion_page_id TEXT PRIMARY KEY,
      notion_created_time TIMESTAMPTZ,
      notion_last_edited_time TIMESTAMPTZ,
      ${columnDefs.join(',\n      ')}
    );
  `;
  await pg.query(createTableQuery);
  console.log('Table created or already exists.');

  // 2. Fetch all pages from Notion with pagination
  let hasMore = true;
  let startCursor = null;
  let totalSynced = 0;

  while (hasMore) {
    try {
      const response = await notion.databases.query({
        database_id: process.env.NOTION_DATABASE_ID,
        start_cursor: startCursor,
        page_size: 100,
      });

      const pages = response.results;
      console.log(`Fetched ${pages.length} pages. Syncing...`);

      for (const page of pages) {
        // Map Notion page to PostgreSQL row
        const row = {
          notion_page_id: page.id,
          notion_created_time: page.created_time,
          notion_last_edited_time: page.last_edited_time,
        };

        // Map each property
        for (const [name, prop] of Object.entries(properties)) {
          const colName = name.toLowerCase().replace(/\s+/g, '_').replace(/[^a-z0-9_]/g, '');
          row[colName] = convertNotionValue(page.properties[name], prop.type);
        }

        // Upsert into PostgreSQL (conflict on primary key)
        const columns = Object.keys(row);
        const values = Object.values(row);
        const placeholders = columns.map((_, i) => `$${i + 1}`).join(', ');
        const updateSet = columns.filter(col => col !== 'notion_page_id')
          .map(col => `"${col}" = EXCLUDED."${col}"`)
          .join(', ');

        const upsertQuery = `
          INSERT INTO "${tableName}" (${columns.map(col => `"${col}"`).join(', ')})
          VALUES (${placeholders})
          ON CONFLICT (notion_page_id)
          DO UPDATE SET ${updateSet};
        `;
        await pg.query(upsertQuery, values);
        totalSynced++;
      }

      // Update pagination
      hasMore = response.has_more;
      startCursor = response.next_cursor;
      console.log(`Synced ${totalSynced} total pages.`);

      // Respect rate limits
      await new Promise(resolve => setTimeout(resolve, 340)); // 3 req/sec max

    } catch (err) {
      if (err.code === 'rate_limited') {
        const retryAfter = err.headers?.['retry-after'] || 1;
        console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      console.error('Sync error:', err.message);
      throw err;
    }
  }

  await pg.end();
  console.log(`Sync complete. Total pages synced: ${totalSynced}`);
}

// Run sync if executed directly
if (require.main === module) {
  syncNotionToPostgres().catch(err => {
    console.error('Fatal sync error:', err.message);
    process.exit(1);
  });
}

# Notion Block Exporter with Pagination & Error Handling
# Dependencies: notion-client==2.0.1 (https://github.com/notionhq/client-py), python-dotenv==1.0.0
import os
import json
import time
from datetime import datetime
from dotenv import load_dotenv
from notion_client import Client
from notion_client.errors import APIResponseError, RateLimitedError

# Load environment variables
load_dotenv()
NOTION_TOKEN = os.getenv('NOTION_TOKEN')
PAGE_ID = os.getenv('NOTION_PAGE_ID')

# Validate config
if not NOTION_TOKEN:
    raise ValueError('NOTION_TOKEN not found in environment variables. Get from https://www.notion.so/my-integrations')
if not PAGE_ID:
    raise ValueError('NOTION_PAGE_ID not found. Use a root page ID to export all child blocks.')

# Initialize Notion client with 10s timeout
notion = Client(auth=NOTION_TOKEN, timeout=10)

def export_blocks_to_json(output_path: str, max_blocks: int = 10000) -> dict:
    """
    Recursively exports all blocks from a Notion page, handling pagination and rate limits.
    Returns export metrics: total blocks, elapsed time, error count.
    """
    metrics = {
        'total_blocks': 0,
        'elapsed_sec': 0,
        'error_count': 0,
        'rate_limit_count': 0
    }
    start_time = time.time()
    exported_blocks = []
    has_more = True
    start_cursor = None

    print(f'Starting block export for page {PAGE_ID}...')

    while has_more and metrics['total_blocks'] < max_blocks:
        try:
            # Fetch block children with pagination
            response = notion.blocks.children.list(
                block_id=PAGE_ID,
                start_cursor=start_cursor,
                page_size=100  # Max page size per Notion API
            )

            blocks = response['results']
            exported_blocks.extend(blocks)
            metrics['total_blocks'] += len(blocks)

            # Update pagination cursor
            has_more = response['has_more']
            start_cursor = response['next_cursor']

            print(f'Exported {len(blocks)} blocks. Total: {metrics["total_blocks"]}')

            # Respect rate limits: 3 req/sec for free workspaces
            time.sleep(0.34)  # 1/3 sec per request to stay under limit

        except RateLimitedError as e:
            metrics['rate_limit_count'] += 1
            retry_after = int(e.headers.get('retry-after', 1))
            print(f'Rate limited. Retrying after {retry_after} seconds...')
            time.sleep(retry_after)
        except APIResponseError as e:
            metrics['error_count'] += 1
            print(f'API Error: {e.message} (Status: {e.status})')
            # Retry once for transient errors
            if e.status in (500, 502, 503, 504):
                time.sleep(2)
                continue
            raise
        except Exception as e:
            metrics['error_count'] += 1
            print(f'Unexpected error: {str(e)}')
            raise

    # Calculate elapsed time
    metrics['elapsed_sec'] = round(time.time() - start_time, 2)

    # Write exported blocks to JSON
    with open(output_path, 'w') as f:
        json.dump(exported_blocks, f, indent=2)
    print(f'Export complete. Blocks written to {output_path}')

    return metrics

if __name__ == '__main__':
    output_file = f'notion-export-{datetime.now().strftime("%Y%m%d-%H%M%S")}.json'
    try:
        metrics = export_blocks_to_json(output_file)
        print('\n=== Export Metrics ===')
        print(f'Total Blocks Exported: {metrics["total_blocks"]}')
        print(f'Elapsed Time: {metrics["elapsed_sec"]} seconds')
        print(f'Rate Limit Hits: {metrics["rate_limit_count"]}')
        print(f'Errors: {metrics["error_count"]}')
        print(f'Throughput: {metrics["total_blocks"] / metrics["elapsed_sec"]:.2f} blocks/sec')
    except Exception as e:
        print(f'Export failed: {str(e)}')
        exit(1)

// Circuit breaker example for Notion API calls
const CircuitBreaker = require('opossum');
const notion = new (require('@notionhq/client')).Client({ auth: process.env.NOTION_TOKEN });

const breaker = new CircuitBreaker(async (databaseId) => {
  return await notion.databases.query({ database_id: databaseId, page_size: 10 });
}, {
  timeout: 2000, // 2s timeout
  errorThresholdPercentage: 10, // Trip if 10% requests fail
  resetTimeout: 30000, // Try again after 30s
});

breaker.fallback(() => fetchFromPostgresFallback());

# Cron job for nightly Notion export (runs at 2am daily)
0 2 * * * /usr/bin/python3 /opt/notion-exporter.py >> /var/log/notion-export.log 2>&1

// Prometheus metric for Notion API latency
const prometheus = require('prom-client');
const notionLatency = new prometheus.Histogram({
  name: 'notion_api_latency_ms',
  help: 'Latency of Notion API requests in milliseconds',
  buckets: [50, 100, 150, 200, 300, 500, 1000],
});

// Wrap Notion API calls with latency metric
async function trackedNotionQuery(databaseId) {
  const end = notionLatency.startTimer();
  try {
    return await notion.databases.query({ database_id: databaseId });
  } finally {
    end();
  }
}