Package Exports

claude-code-notion
claude-code-notion/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (claude-code-notion) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Notion Roadmap Manager

A TypeScript library for managing project roadmaps in Notion databases. Easily update task statuses, track completion dates, and manage multiple project roadmaps from your code.

Features

✅ Type-safe - Full TypeScript support with comprehensive types
🚀 Easy to use - Simple, intuitive API
📅 Auto-dating - Automatically sets dates for completed/in-progress tasks
🔍 Search & filter - Find tasks by name, status, or custom filters
🎯 Multi-project - Support for multiple roadmaps with different configurations
🛡️ Error handling - Comprehensive error messages and validation

Installation

npm install @danielharris/notion-roadmap-manager

Quick Start

import { createRoadmapFromEnv } from '@danielharris/notion-roadmap-manager';

// Using environment variables (recommended)
const roadmap = createRoadmapFromEnv('your-database-id');

// Mark a task as completed
await roadmap.complete("Authentication System");

// Mark a task as in progress  
await roadmap.start("User Dashboard");

// Set custom status
await roadmap.updateTask("API Integration", "Planned");

Configuration

Method 1: Environment Variables (Recommended)

# .env
NOTION_API_KEY=your_notion_api_key_here

import { createRoadmapFromEnv } from '@danielharris/notion-roadmap-manager';

const roadmap = createRoadmapFromEnv('24c697dd-0e1b-8079-8a95-cab8bd49eadd');

Method 2: Direct Configuration

import { createRoadmapManager } from '@danielharris/notion-roadmap-manager';

const roadmap = createRoadmapManager({
  apiKey: 'your_notion_api_key',
  databaseId: '24c697dd-0e1b-8079-8a95-cab8bd49eadd',
  titleProperty: 'Project name', // Optional: defaults to "Project name"
  statusProperty: 'Status',      // Optional: defaults to "Status"  
  dateProperty: 'Date'          // Optional: defaults to "Date"
});

API Reference

Core Methods

`getFullProjectData(taskIdentifier)` - NEW!

Get complete project information including all properties and page content.

const fullData = await roadmap.getFullProjectData("Agent License Renewal");

// Returns:
{
  id: "page-id",
  title: "Agent License Renewal",
  url: "https://notion.so/...",
  properties: {
    status: "In progress",
    priority: "Medium",
    effort: "M",
    team: ["Backend", "Frontend"],
    owner: ["Daniel Harris"],
    category: ["Compliance"],
    role: ["Student"],
    quarter: ["Q1 2025"],
    date: "2025-08-14",
    docs: "Documentation text"
  },
  content: {
    objective: "The primary goal is to make Lurnor...",
    userFlow: "Step 1 – Profile Setup...",
    fullText: "Complete page content..."
  }
}

`updateTask(taskIdentifier, status)`

Update a task's status by name or page ID.

await roadmap.updateTask("Feature Name", "Completed");
await roadmap.updateTask("page-id-123", "In progress");

`complete(taskName)`

Mark a task as completed (automatically sets completion date).

await roadmap.complete("Authentication System");

`start(taskName)`

Mark a task as in progress (automatically sets start date).

await roadmap.start("User Dashboard");

`plan(taskName)`

Mark a task as planned.

await roadmap.plan("Future Feature");

Query Methods

`search(query)`

Find tasks containing the search term.

const tasks = await roadmap.search("authentication");
console.log(tasks); // Array of matching tasks

`list()`

Get all tasks in the roadmap.

const allTasks = await roadmap.list();

`getByStatus(status)`

Get all tasks with a specific status.

const completedTasks = await roadmap.getByStatus("Completed");
const inProgressTasks = await roadmap.getByStatus("In progress");

`getTaskDetails(taskIdentifier)`

Get project objective, user flow, and full content.

const details = await roadmap.getTaskDetails("Agent License Renewal");
console.log(details.objective);   // Project objective text
console.log(details.userFlow);    // User flow steps
console.log(details.fullContent); // Complete page content

`updatePageContent(taskIdentifier, content)`

Update project objective and user flow content.

await roadmap.updatePageContent("Agent License Renewal", {
  objective: "Updated project objective...",
  userFlow: "Step 1: New user flow...\nStep 2: Next step..."
});

`createTask(title, status, properties)`

Create a new task in the roadmap.

await roadmap.createTask("New Feature", "Planned", {
  Priority: { select: { name: "High" } },
  Effort: { select: { name: "Large" } }
});

Practical Examples

Complete Project Analysis

// Get ALL information about a project
const projectData = await roadmap.getFullProjectData("Agent License Renewal");

// Display comprehensive project info
console.log("=== PROJECT: " + projectData.title + " ===");
console.log("Status:", projectData.properties.status);
console.log("Priority:", projectData.properties.priority);
console.log("Effort:", projectData.properties.effort);
console.log("Due Date:", projectData.properties.date);

console.log("\n📋 OBJECTIVE:");
console.log(projectData.content.objective);

console.log("\n🔄 USER FLOW:");
console.log(projectData.content.userFlow);

console.log("\n👥 TEAM:", projectData.properties.team?.join(", "));
console.log("👤 OWNER:", projectData.properties.owner?.join(", "));
console.log("📂 CATEGORY:", projectData.properties.category?.join(", "));

Project Status Report

// Generate status report for all in-progress projects
const allTasks = await roadmap.list();
const inProgress = allTasks.filter(t => t.status === "In progress");

for (const task of inProgress) {
  const fullData = await roadmap.getFullProjectData(task.title);
  
  console.log(`\n📊 ${task.title}`);
  console.log(`   Priority: ${fullData.properties.priority}`);
  console.log(`   Effort: ${fullData.properties.effort}`);
  console.log(`   Objective: ${fullData.content.objective?.substring(0, 100)}...`);
}

Bulk Content Update

// Update multiple projects with new format
const projectsToUpdate = ["Agent License Renewal", "Course Licensing", "Student Sign-up"];

for (const projectName of projectsToUpdate) {
  const current = await roadmap.getTaskDetails(projectName);
  
  // Add structured formatting to objectives
  await roadmap.updatePageContent(projectName, {
    objective: `## Main Goal\n${current.objective}\n\n## Success Criteria\n- [ ] Metric 1\n- [ ] Metric 2`,
    userFlow: current.userFlow // Keep existing user flow
  });
}

Multi-Project Usage

// Different projects with different databases
const lurnorRoadmap = createRoadmapFromEnv('lurnor-database-id');
const otherProjectRoadmap = createRoadmapFromEnv('other-database-id');

// Update different roadmaps independently
await lurnorRoadmap.complete("Payment Integration");
await otherProjectRoadmap.start("User Authentication");

Integration Examples

With npm scripts

Add to your project's package.json:

{
  "scripts": {
    "roadmap:complete": "node -e \"require('./scripts/roadmap-update.js').complete(process.argv[2])\"",
    "roadmap:start": "node -e \"require('./scripts/roadmap-update.js').start(process.argv[2])\"" 
  }
}

Create scripts/roadmap-update.js:

const { createRoadmapFromEnv } = require('@danielharris/notion-roadmap-manager');

const roadmap = createRoadmapFromEnv(process.env.NOTION_DATABASE_ID);

module.exports = {
  async complete(taskName) {
    await roadmap.complete(taskName);
    console.log(`✅ "${taskName}" marked as completed!`);
  },
  
  async start(taskName) {
    await roadmap.start(taskName);
    console.log(`🔄 "${taskName}" marked as in progress!`);
  }
};

Usage:

npm run roadmap:complete "Feature Name"
npm run roadmap:start "New Feature"

With CI/CD Integration

# .github/workflows/deploy.yml
- name: Update roadmap on deploy
  run: |
    npm install @danielharris/notion-roadmap-manager
    node -e "
      const { createRoadmapFromEnv } = require('@danielharris/notion-roadmap-manager');
      const roadmap = createRoadmapFromEnv('${{ secrets.NOTION_DATABASE_ID }}');
      roadmap.complete('${{ github.event.head_commit.message }}');
    "
  env:
    NOTION_API_KEY: ${{ secrets.NOTION_API_KEY }}

Setup Guide

1. Create Notion Integration

Go to Notion Integrations
Click "New integration"
Give it a name (e.g., "Roadmap Manager")
Copy the Internal Integration Token

Open your roadmap database in Notion
Click "Share" → "Add connections"
Select your integration

3. Get Database ID

From your database URL: https://notion.so/workspace/DatabaseName-{DATABASE_ID}?v=...

4. Set Environment Variable

NOTION_API_KEY=ntn_your_token_here

TypeScript Types

interface RoadmapTask {
  id: string;
  title: string; 
  status: string;
  priority?: string;
  url: string;
  properties: Record<string, any>;
}

interface RoadmapConfig {
  apiKey: string;
  databaseId: string;
  titleProperty?: string;   // Default: "Project name"
  statusProperty?: string;  // Default: "Status" 
  dateProperty?: string;    // Default: "Date"
}

Error Handling

try {
  await roadmap.complete("Non-existent Task");
} catch (error) {
  if (error.message.includes('not found')) {
    console.log('Task does not exist in the roadmap');
  }
}

Requirements

Node.js 16+
A Notion integration with database access
TypeScript 4+ (for TypeScript projects)

License

MIT

claude-code-notion