note-api-client

note-api-client is a comprehensive Node.js and TypeScript library for interacting with the note.com API. Build powerful integrations, automate content management, and access note.com's rich features programmatically with ease.

✨ Features

• 🔍 Search & Discovery: Search notes by keyword, username, category, and hashtag
• 📝 Content Management: Create, edit, and manage notes programmatically
• 👥 User Operations: Fetch user profiles, followers, followings, and user content
• 📰 Magazine Support: Access and search magazine content
• 🏷️ Hashtag & Category: Browse trending hashtags and explore categories
• 🔐 Authentication: Built-in sign-in support for authenticated operations
• 🖼️ Media Upload: Upload eyecatch images for your notes
• 💬 Comments: Retrieve note comments and engagement data
• 📊 Recommendations: Access recommended content metadata
• 🎨 MKit Layouts: Fetch creative layout configurations
• 🎯 Contests: Browse note.com contests and campaigns
• ⚡ TypeScript First: Full type safety and IntelliSense support
• 🚀 Promise-based API: Modern async/await syntax
• 📦 Zero Config: Works out of the box with sensible defaults

📦 Installation

Install via npm:

npm install note-api-client

Install via yarn:

yarn add note-api-client

Install via pnpm:

pnpm add note-api-client

🚀 Quick Start

import { NoteAPIClient } from "note-api-client";

// Initialize the client
const client = new NoteAPIClient();

// Search notes by keyword
const notes = await client.searchNotesByKeyword({
  phrase: "JavaScript",
});

// Get user's notes
const userNotes = await client.searchNotesByUsername({
  username: "your_username",
});

// Get note details
const noteDetail = await client.getNoteDetail({
  noteKey: "note_key_here",
});

📚 API Reference

Search Operations

Search Notes by Keyword

const notes = await client.searchNotesByKeyword({
  phrase: "AI technology",
  page: 1,
});

Search Notes by Username

const userNotes = await client.searchNotesByUsername({
  username: "example_user",
  page: 1,
});

Search Notes by Category

const categoryNotes = await client.searchNotesByCategory({
  categoryName: "tech",
  page: 1,
});

Search Notes by Hashtag

const hashtagNotes = await client.searchNotesByHashtag({
  hashtag: "programming",
  page: 1,
});

Content Management

Create Note

const newNote = await client.createNote({
  title: "My First Note",
  body: "<p>This is the content of my note.</p>",
});

Edit Note (Publish)

const published = await client.editNote({
  id: "123456",
  title: "Updated Title",
  body: "<p>Updated content</p>",
  eyecatchImageKey: "optional_image_key", // optional
  index: true, // optional: enable table of contents
});

Save Draft

const draft = await client.saveDraft({
  id: "123456",
  title: "Draft Title",
  body: "<p>Draft content</p>",
  isTempSaved: false, // optional (default: true)
  index: true, // optional: enable table of contents
});

Delete Note

await client.deleteNote({ id: "123456" });

Delete Draft

await client.draftDelete({ id: "123456" });

Publishing Flow (Full Example)

The recommended flow to create and publish a note:

// 1. Sign in
await client.signIn({
  login: "[email protected]",
  password: "your_password",
  g_recaptcha_response: "",
  redirect_path: "/",
});

// 2. Create a draft
const created = await client.createNote({
  title: "My Article",
  body: "",
});

// 3. Save draft with content
await client.saveDraft({
  id: created.id.toString(),
  title: "My Article",
  body: "<p>Article content here</p>",
  isTempSaved: false,
  index: false,
});

// 4. Publish
await client.editNote({
  id: created.id.toString(),
  title: "My Article",
  body: "<p>Article content here</p>",
});

Table of Contents (目次)

To add a table of contents that auto-generates links from headings, use the <table-of-contents> tag and set index: true in both saveDraft and editNote.

Supported HTML Tags

| Tag | Description | Appears in TOC? | | --------------------------------- | ----------------------- | --------------- | | <table-of-contents> | Table of contents block | — | | <h2> | Large heading | Yes | | <h3> | Small heading | No | | <p> | Paragraph | No | | <ul>, <ol>, <li> | Lists | No | | <blockquote> | Quote | No | | <pre><code> | Code block | No | | <figure>, <img> | Image | No | | <hr> | Horizontal rule | No | | <strong>, <em>, <a>, <br> | Inline formatting | No |

Note: <table> HTML tags are not supported and will be stripped by note.com.

Building the Body HTML

Every element should have a unique name and id attribute (UUID v4):

import crypto from "crypto";
const uuid = () => crypto.randomUUID();

const body = [
  // Table of contents (place before headings)
  `<table-of-contents name="${uuid()}" id="${uuid()}"><br></table-of-contents>`,
  // Headings & content
  `<h2 name="${uuid()}" id="${uuid()}">Introduction</h2>`,
  `<p name="${uuid()}" id="${uuid()}">First paragraph.</p>`,
  `<h2 name="${uuid()}" id="${uuid()}">Main Topic</h2>`,
  `<p name="${uuid()}" id="${uuid()}">Second paragraph.</p>`,
  `<h3 name="${uuid()}" id="${uuid()}">Sub Topic</h3>`,
  `<p name="${uuid()}" id="${uuid()}">Details here.</p>`,
  `<h2 name="${uuid()}" id="${uuid()}">Conclusion</h2>`,
  `<p name="${uuid()}" id="${uuid()}">Summary.</p>`,
].join("");

Full Example with TOC

// 1. Create draft
const created = await client.createNote({ title: "My Article", body: "" });

// 2. Save draft with index: true
await client.saveDraft({
  id: created.id.toString(),
  title: "My Article",
  body: body, // HTML with <table-of-contents> and <h2> tags
  isTempSaved: false,
  index: true, // Required for TOC
});

// 3. Publish with index: true
await client.editNote({
  id: created.id.toString(),
  title: "My Article",
  body: body,
  index: true, // Required for TOC
});

User Operations

Search Users by Keyword

const users = await client.searchUsersByKeyword({
  phrase: "developer",
  page: 1,
});

Search User by Username

const user = await client.searchUserByUsername({
  username: "example_user",
});

Get Followers

const followers = await client.getFollowers({
  username: "example_user",
  page: 1,
});

Get Followings

const followings = await client.getFollowings({
  username: "example_user",
  page: 1,
});

Magazine Operations

Search Magazines by Keyword

const magazines = await client.searchMagazinesByKeyword({
  phrase: "technology",
  page: 1,
});

Get Magazine Details

const magazine = await client.getMagazineDetail({
  magazineKey: "magazine_key_here",
});

Hashtag & Category

Get Hashtags

const hashtags = await client.getHashtags();

Get Hashtag Details

const hashtagDetail = await client.getHashtagDetail({
  hashtag: "nodejs",
});

Get Categories

const categories = await client.getCategories();

Authentication

Sign In

const session = await client.signIn({
  login: "[email protected]",
  password: "your_password",
  g_recaptcha_response: "",
  redirect_path: "/",
});

Media & Assets

Upload Eyecatch Image

const eyecatch = await client.uploadEyecatch({
  imageData: buffer,
  filename: "image.jpg",
});

Engagement

Get Comments

const comments = await client.getComments({
  noteKey: "note_key_here",
  page: 1,
});

Additional Features

Get Recommended Metadata

const recommendations = await client.getRecommendMetadata();

Get MKit Layouts

const layouts = await client.getMkitLayouts();

Get Contests

const contests = await client.getContests();

🔧 Advanced Usage

Using Cookies for Authentication

const client = new NoteAPIClient("your_session_cookies_here");

// Now you can perform authenticated operations
const note = await client.createNote({
  title: "Authenticated Note",
  body: "This note is created with authentication.",
});

Error Handling

try {
  const notes = await client.searchNotesByKeyword({ phrase: "test" });
  console.log(notes);
} catch (error) {
  console.error("Error fetching notes:", error);
}

🛠️ Requirements

• Node.js: >= 20.0.0
• TypeScript: 4.0+ (for TypeScript projects)

📖 Use Cases

• Content Automation: Automatically publish and manage notes
• Analytics Tools: Build dashboards to track note performance
• Social Media Integration: Cross-post content to note.com
• Content Aggregation: Collect and curate notes by topic
• Research Tools: Analyze trending topics and hashtags
• Bot Development: Create interactive bots for note.com
• Data Migration: Move content to/from note.com
• Personal Automation: Schedule and manage your writing workflow

🤝 Contributing

Contributions are welcome! We appreciate your help in making this library better.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read our Contributing Guidelines for more details.

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🔗 Links

• npm Package
• GitHub Repository
• Issue Tracker
• note.com Official Site

🌟 Show Your Support

If you find this library useful, please consider giving it a ⭐ on GitHub!

📧 Contact

For questions, suggestions, or feedback, please open an issue on GitHub.