@uniswap/ai-toolkit-notion-publisher 0.0.1 → 0.0.2-next.0

package/README.md

@@ -1,45 +1,425 @@
 # @uniswap/ai-toolkit-notion-publisher
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+A CLI tool to publish release notes and other content to Notion databases with full markdown support. This tool fills a gap in the ecosystem by creating new database entries with custom properties—something existing GitHub Actions don't support.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Features
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+- ✅ **Creates new pages in Notion databases** (not just updates)
+- ✅ **Markdown to Notion blocks conversion** using @tryfabric/martian
+- ✅ **Custom database properties** (Name, Date, Commit Range, Branch)
+- ✅ **Git integration** (track commit ranges and branches)
+- ✅ **CI/CD agnostic** (works with GitHub Actions, GitLab CI, CircleCI, Jenkins, etc.)
+- ✅ **Type-safe** TypeScript implementation
+- ✅ **Comprehensive error handling** with detailed logs
 
-## Purpose
+## Installation
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@uniswap/ai-toolkit-notion-publisher`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+### Global Installation
 
-## What is OIDC Trusted Publishing?
+```bash
+npm install -g @uniswap/ai-toolkit-notion-publisher
+```
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+### Using npx (Recommended)
 
-## Setup Instructions
+No installation required:
 
-To properly configure OIDC trusted publishing for this package:
+```bash
+npx @uniswap/ai-toolkit-notion-publisher --title "My Release" --content "..."
+```
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+### Local Installation
 
-## DO NOT USE THIS PACKAGE
+```bash
+npm install --save-dev @uniswap/ai-toolkit-notion-publisher
+```
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+## Prerequisites
 
-## More Information
+### 1. Create a Notion Integration
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+1. Go to <https://www.notion.so/my-integrations>
+2. Click "New integration"
+3. Give it a name (e.g., "Release Notes Publisher")
+4. Select the workspace
+5. Copy the "Internal Integration Token" (starts with `secret_`)
 
----
+### 2. Create a Notion Database
 
-**Maintained for OIDC setup purposes only**
+1. Create a new page in Notion
+2. Add a database (inline or full-page)
+3. Add these properties:
+   - **Name** (Title) - Required
+   - **Date** (Date) - Required
+   - **Commit Range** (Text) - Optional
+   - **Branch** (Text) - Optional
+4. Share the database with your integration:
+   - Click "..." in the top right
+   - Click "Add connections"
+   - Select your integration
+
+### 3. Get the Database ID
+
+From the database URL: `https://notion.so/workspace/DATABASE_ID?v=VIEW_ID`
+
+The `DATABASE_ID` is the 32-character hex string.
+
+## Usage
+
+### Basic Usage
+
+```bash
+notion-publisher \
+  --title "Release v1.2.0" \
+  --content "# What's New\n\n- Feature A\n- Feature B"
+```
+
+Required environment variables:
+
+- `NOTION_API_KEY` - Your Notion integration token
+- `RELEASE_NOTES_NOTION_DATABASE_ID` - Target database ID
+
+### With All Options
+
+```bash
+notion-publisher \
+  --title "Release v1.2.0" \
+  --content "$(cat CHANGELOG.md)" \
+  --from-ref "v1.1.0" \
+  --to-ref "v1.2.0" \
+  --branch "main"
+```
+
+### Using CLI Flags for Secrets
+
+```bash
+notion-publisher \
+  --api-key "secret_abc123" \
+  --database-id "32-char-hex-id" \
+  --title "Release v1.2.0" \
+  --content "# Release Notes"
+```
+
+**⚠️ Security Warning**: Using `--api-key` flag exposes secrets in process listings. Always prefer environment variables in production.
+
+## GitHub Actions Integration
+
+### Basic Example
+
+```yaml
+name: Publish Release Notes
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-to-notion:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@uniswap'
+
+      - name: Publish to Notion
+        run: |
+          npx @uniswap/ai-toolkit-notion-publisher \
+            --title "${{ github.event.release.name }}" \
+            --content "${{ github.event.release.body }}" \
+            --from-ref "${{ github.event.release.tag_name }}" \
+            --branch "${{ github.ref_name }}"
+        env:
+          NOTION_API_KEY: ${{ secrets.NOTION_API_KEY }}
+          RELEASE_NOTES_NOTION_DATABASE_ID: ${{ secrets.NOTION_DATABASE_ID }}
+```
+
+### With Changelog File
+
+```yaml
+- name: Read Changelog
+  id: changelog
+  run: |
+    echo "content<<EOF" >> $GITHUB_OUTPUT
+    cat CHANGELOG.md >> $GITHUB_OUTPUT
+    echo "EOF" >> $GITHUB_OUTPUT
+
+- name: Publish to Notion
+  run: |
+    npx @uniswap/ai-toolkit-notion-publisher \
+      --title "Release ${{ github.event.release.tag_name }}" \
+      --content "${{ steps.changelog.outputs.content }}" \
+      --from-ref "${{ github.event.release.target_commitish }}" \
+      --to-ref "${{ github.event.release.tag_name }}"
+  env:
+    NOTION_API_KEY: ${{ secrets.NOTION_API_KEY }}
+    RELEASE_NOTES_NOTION_DATABASE_ID: ${{ secrets.NOTION_DATABASE_ID }}
+```
+
+## GitLab CI Integration
+
+```yaml
+publish_to_notion:
+  stage: deploy
+  image: node:22
+  script:
+    - npx @uniswap/ai-toolkit-notion-publisher
+      --title "Release $CI_COMMIT_TAG"
+      --content "$(cat CHANGELOG.md)"
+      --from-ref "$CI_COMMIT_BEFORE_SHA"
+      --to-ref "$CI_COMMIT_SHA"
+      --branch "$CI_COMMIT_BRANCH"
+  variables:
+    NOTION_API_KEY: $NOTION_API_KEY
+    RELEASE_NOTES_NOTION_DATABASE_ID: $NOTION_DATABASE_ID
+  only:
+    - tags
+```
+
+## CircleCI Integration
+
+```yaml
+version: 2.1
+jobs:
+  publish-notion:
+    docker:
+      - image: cimg/node:22.0
+    steps:
+      - checkout
+      - run:
+          name: Publish to Notion
+          command: |
+            npx @uniswap/ai-toolkit-notion-publisher \
+              --title "Release ${CIRCLE_TAG}" \
+              --content "$(cat CHANGELOG.md)" \
+              --from-ref "${CIRCLE_TAG}" \
+              --branch "${CIRCLE_BRANCH}"
+          environment:
+            NOTION_API_KEY: ${NOTION_API_KEY}
+            RELEASE_NOTES_NOTION_DATABASE_ID: ${NOTION_DATABASE_ID}
+
+workflows:
+  release:
+    jobs:
+      - publish-notion:
+          filters:
+            tags:
+              only: /^v.*/
+```
+
+## Jenkins Integration
+
+```groovy
+pipeline {
+    agent any
+    environment {
+        NOTION_API_KEY = credentials('notion-api-key')
+        RELEASE_NOTES_NOTION_DATABASE_ID = credentials('notion-database-id')
+    }
+    stages {
+        stage('Publish to Notion') {
+            steps {
+                sh '''
+                    npx @uniswap/ai-toolkit-notion-publisher \
+                      --title "Release ${GIT_TAG_NAME}" \
+                      --content "$(cat CHANGELOG.md)" \
+                      --from-ref "${GIT_PREVIOUS_COMMIT}" \
+                      --to-ref "${GIT_COMMIT}" \
+                      --branch "${GIT_BRANCH}"
+                '''
+            }
+        }
+    }
+}
+```
+
+## CLI Arguments
+
+| Argument        | Environment Variable               | Required | Description                                         |
+| --------------- | ---------------------------------- | -------- | --------------------------------------------------- |
+| `--api-key`     | `NOTION_API_KEY`                   | Yes      | Notion integration token                            |
+| `--database-id` | `RELEASE_NOTES_NOTION_DATABASE_ID` | Yes      | Target Notion database ID (32-char hex)             |
+| `--title`       | -                                  | Yes      | Page title for the release notes                    |
+| `--content`     | -                                  | Yes      | Page content in markdown format                     |
+| `--from-ref`    | -                                  | No       | Starting git reference (e.g., previous version tag) |
+| `--to-ref`      | -                                  | No       | Ending git reference (e.g., current version tag)    |
+| `--branch`      | -                                  | No       | Branch name where the release was made              |
+
+**Note**: Environment variables take precedence over CLI flags for API key and database ID.
+
+## Markdown Support
+
+The tool uses [@tryfabric/martian](https://github.com/tryfabric/martian) to convert markdown to Notion blocks. Supported markdown features include:
+
+- Headers (H1, H2, H3)
+- **Bold**, _italic_, ~~strikethrough~~ text
+- Lists (ordered and unordered)
+- Code blocks with syntax highlighting
+- Links
+- Images (as external URLs)
+- Blockquotes
+- Tables
+- And more!
+
+### Example Markdown
+
+```markdown
+# Release v1.2.0
+
+## 🚀 New Features
+
+- Added dark mode support
+- Improved performance by 50%
+- New API endpoints for user management
+
+## 🐛 Bug Fixes
+
+- Fixed memory leak in data processing
+- Resolved authentication issues
+
+## 📝 Documentation
+
+Updated the [Getting Started Guide](https://example.com/docs)
+
+## Contributors
+
+Thanks to @user1 and @user2 for their contributions!
+```
+
+## Troubleshooting
+
+### Error: "NOTION_API_KEY is required"
+
+**Cause**: Missing API key
+
+**Solution**: Set the `NOTION_API_KEY` environment variable or use `--api-key` flag
+
+```bash
+export NOTION_API_KEY="secret_abc123"
+notion-publisher --title "..." --content "..."
+```
+
+### Error: "RELEASE_NOTES_NOTION_DATABASE_ID is required"
+
+**Cause**: Missing database ID
+
+**Solution**: Set the environment variable or use `--database-id` flag
+
+```bash
+export RELEASE_NOTES_NOTION_DATABASE_ID="32-char-hex-id"
+```
+
+### Error: "Could not find database"
+
+**Cause**: Database doesn't exist or integration doesn't have access
+
+**Solution**:
+
+1. Verify the database ID is correct
+2. Share the database with your integration:
+   - Open the database in Notion
+   - Click "..." → "Add connections"
+   - Select your integration
+
+### Error: "Validation failed"
+
+**Cause**: Database schema doesn't match expected properties
+
+**Solution**: Ensure your database has these properties:
+
+- **Name** (Title type)
+- **Date** (Date type)
+- **Commit Range** (Text type) - if using `--from-ref` or `--to-ref`
+- **Branch** (Text type) - if using `--branch`
+
+### Rate Limiting
+
+Notion API has rate limits (3 requests per second). If you're publishing multiple pages:
+
+```bash
+# Add delays between calls
+notion-publisher --title "Release 1" --content "..." && \
+  sleep 1 && \
+  notion-publisher --title "Release 2" --content "..."
+```
+
+## Output
+
+The tool outputs the created Notion page URL to stdout:
+
+```bash
+PAGE_URL=$(notion-publisher --title "..." --content "...")
+echo "Published to: $PAGE_URL"
+```
+
+In GitHub Actions, capture it as an output:
+
+```yaml
+- name: Publish to Notion
+  id: publish
+  run: |
+    PAGE_URL=$(npx @uniswap/ai-toolkit-notion-publisher \
+      --title "..." \
+      --content "...")
+    echo "page_url=$PAGE_URL" >> $GITHUB_OUTPUT
+
+- name: Comment on PR
+  run: |
+    echo "Published to Notion: ${{ steps.publish.outputs.page_url }}"
+```
+
+## Development
+
+### Build
+
+```bash
+npx nx build @uniswap/ai-toolkit-notion-publisher
+```
+
+### Test Locally
+
+```bash
+# Build the package
+npx nx build @uniswap/ai-toolkit-notion-publisher
+
+# Test with tsx (no build required)
+npx tsx packages/notion-publisher/src/cli.ts \
+  --title "Test" \
+  --content "# Test content"
+
+# Test built version
+node dist/packages/notion-publisher/cli.js \
+  --title "Test" \
+  --content "# Test content"
+```
+
+### Publishing
+
+This package is automatically published via the repository's CI/CD workflow using Nx release.
+
+## Why This Tool?
+
+Existing GitHub Actions for Notion have limitations:
+
+| Feature                | @uniswap/ai-toolkit-notion-publisher | tryfabric/markdown-to-notion | push-markdown-to-notion |
+| ---------------------- | ------------------------------------ | ---------------------------- | ----------------------- |
+| **Create new pages**   | ✅ Yes                               | ❌ No (updates only)         | ❌ No (updates only)    |
+| **Write to databases** | ✅ Yes                               | ❌ No                        | ❌ No                   |
+| **Custom properties**  | ✅ Yes                               | ❌ No                        | ❌ No                   |
+| **Maintenance**        | 🆕 Active (2024)                     | ⚠️ Stale (2022)              | ⚠️ Low activity         |
+| **CI agnostic**        | ✅ Yes (CLI tool)                    | ❌ GitHub only               | ❌ GitHub only          |
+
+This tool was created to fill the gap: **creating new Notion database entries with structured metadata**, which is essential for release notes and changelog tracking.
+
+## License
+
+See repository LICENSE file.
+
+## Support
+
+For issues, feature requests, or contributions, please visit the [GitHub repository](https://github.com/Uniswap/ai-toolkit).

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { Client } from '@notionhq/client';
+import { markdownToBlocks } from '@tryfabric/martian';
+import minimist from 'minimist';
+// Parse CLI arguments with flags using minimist
+const args = minimist(process.argv.slice(2), {
+    string: ['api-key', 'database-id', 'title', 'content', 'from-ref', 'to-ref', 'branch'],
+    alias: {
+        'api-key': 'apiKey',
+        'database-id': 'databaseId',
+        'from-ref': 'fromRef',
+        'to-ref': 'toRef',
+    },
+});
+// Read from environment variables first, fall back to CLI arguments
+// This prevents secrets from appearing in process listings
+const apiKey = process.env.NOTION_API_KEY || args.apiKey;
+const databaseId = process.env.RELEASE_NOTES_NOTION_DATABASE_ID || args.databaseId;
+const { title, content, fromRef, toRef, branch } = args;
+// Color codes for output
+const RED = '\x1b[0;31m';
+const GREEN = '\x1b[0;32m';
+const NC = '\x1b[0m'; // No Color / Colorless
+// Logging functions
+const logInfo = (message) => {
+    console.error(`${GREEN}[INFO]${NC} ${message}`);
+};
+const logError = (message) => {
+    console.error(`${RED}[ERROR]${NC} ${message}`);
+};
+// Validate required arguments
+if (!apiKey) {
+    logError('NOTION_API_KEY is required (via NOTION_API_KEY env var or --api-key flag)');
+    process.exit(1);
+}
+if (!databaseId) {
+    logError('RELEASE_NOTES_NOTION_DATABASE_ID is required (via RELEASE_NOTES_NOTION_DATABASE_ID env var or --database-id flag)');
+    process.exit(1);
+}
+if (!title) {
+    logError('TITLE is required');
+    process.exit(1);
+}
+if (!content) {
+    logError('CONTENT is required');
+    process.exit(1);
+}
+logInfo(`Preparing to publish to Notion database: ${databaseId}`);
+logInfo(`Page title: ${title}`);
+// Initialize Notion client
+const notion = new Client({ auth: apiKey });
+async function publishToNotion() {
+    try {
+        // Convert markdown content to Notion blocks using Martian
+        logInfo('Converting markdown to Notion blocks...');
+        const blocks = markdownToBlocks(content);
+        // Serialize and deserialize to strip TypeScript type metadata
+        // This is necessary because @tryfabric/martian and @notionhq/client have
+        // incompatible type definitions despite being structurally compatible at runtime
+        const notionBlocks = JSON.parse(JSON.stringify(blocks));
+        // Build properties object for the Notion page
+        const properties = {
+            Name: {
+                title: [{ text: { content: title } }],
+            },
+            Date: {
+                date: { start: new Date().toISOString() },
+            },
+        };
+        // Add optional properties if provided
+        if (fromRef && toRef) {
+            properties['Commit Range'] = {
+                rich_text: [{ text: { content: `${fromRef} → ${toRef}` } }],
+            };
+        }
+        else if (fromRef) {
+            properties['Commit Range'] = {
+                rich_text: [{ text: { content: `From: ${fromRef}` } }],
+            };
+        }
+        else if (toRef) {
+            properties['Commit Range'] = {
+                rich_text: [{ text: { content: `To: ${toRef}` } }],
+            };
+        }
+        if (branch) {
+            properties.Branch = {
+                rich_text: [{ text: { content: branch } }],
+            };
+        }
+        // Create Notion page
+        logInfo('Creating Notion page...');
+        const response = await notion.pages.create({
+            parent: { database_id: databaseId },
+            properties,
+            children: notionBlocks,
+        });
+        logInfo('✅ Successfully created Notion page');
+        // Check if response has url property (full page response vs partial)
+        const pageUrl = 'url' in response ? response.url : 'https://notion.so';
+        logInfo(`Page URL: ${pageUrl}`);
+        // Output the page URL to stdout (for GitHub Actions to capture)
+        console.log(pageUrl);
+        process.exit(0);
+    }
+    catch (error) {
+        logError('Failed to create Notion page');
+        if (error instanceof Error) {
+            logError(error.message);
+            // Log additional details if available
+            if ('body' in error) {
+                logError(`Details: ${JSON.stringify(error.body, null, 2)}`);
+            }
+        }
+        else {
+            logError(String(error));
+        }
+        process.exit(1);
+    }
+}
+// Run the main function
+publishToNotion();

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/notion-publisher.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from './lib/notion-publisher.js';

package/dist/lib/notion-publisher.d.ts

@@ -0,0 +1,2 @@
+export declare function notionPublisher(): string;
+//# sourceMappingURL=notion-publisher.d.ts.map

package/dist/lib/notion-publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-publisher.d.ts","sourceRoot":"","sources":["../../src/lib/notion-publisher.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,IAAI,MAAM,CAExC"}

package/dist/lib/notion-publisher.js

@@ -0,0 +1,3 @@
+export function notionPublisher() {
+    return 'notion-publisher';
+}

package/package.json

@@ -1,10 +1,38 @@
 {
   "name": "@uniswap/ai-toolkit-notion-publisher",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @uniswap/ai-toolkit-notion-publisher",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "version": "0.0.2-next.0",
+  "private": false,
+  "type": "module",
+  "description": "CLI tool to publish release notes to Notion databases with markdown support",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "notion-publisher": "./dist/cli.js"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@ai-toolkit/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "dependencies": {
+    "@notionhq/client": "^2.2.15",
+    "@tryfabric/martian": "^1.2.4",
+    "minimist": "^1.2.8",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@types/minimist": "^1.2.5"
+  }
 }