Merge pull request #37 from hackmdio/release/2.5.0

Release 2.5.0

Author: Yukaii

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [ master, develop ]
   pull_request:
-    branches: [ master ]
+    branches: [ master, develop ]
 
 jobs:
   test:

.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+          cache-dependency-path: nodejs/package-lock.json
+
+      - name: Install dependencies
+        working-directory: nodejs
+        run: npm ci
+
+      - name: Build
+        working-directory: nodejs
+        run: npm run build
+
+      - name: Publish to NPM
+        working-directory: nodejs
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} 

.gitignore

@@ -0,0 +1,5 @@
+# Environment variables
+.env
+.env.*
+!.env.example 
+node_modules

README.md

@@ -6,6 +6,30 @@ This repository contains a set of packages for interacting with the [HackMD API]
 
 See [README](./nodejs)
 
+## Examples
+
+To help you get started quickly, we provide comprehensive usage examples in the `examples/` directory:
+
+### Node.js Example
+
+The `examples/nodejs/` directory contains a complete example project demonstrating:
+
+- User information retrieval
+- Note creation and management
+- ETag support for caching
+- Content updates
+- Error handling with retry logic
+- Environment variable configuration
+
+To run the Node.js example:
+
+1. Navigate to the example directory: `cd examples/nodejs`
+2. Follow the setup instructions in [examples/nodejs/README.md](./examples/nodejs/README.md)
+3. Set your HackMD access token
+4. Run `npm start`
+
+The example includes detailed comments and demonstrates best practices for using the HackMD API client.
+
 ## LICENSE
 
 MIT

examples/nodejs/.env.example

@@ -0,0 +1 @@
+HACKMD_ACCESS_TOKEN=YOUR_ACCESS_TOKEN

examples/nodejs/README.md

@@ -0,0 +1,63 @@
+# HackMD API Client Example
+
+This is an example project demonstrating the usage of the HackMD API client.
+
+## Setup
+
+1. First, build the HackMD API package:
+```bash
+cd ../../nodejs
+npm install
+npm run build
+cd ../examples/nodejs
+```
+
+2. Install the example dependencies:
+```bash
+npm install
+```
+
+3. Set up your HackMD access token using one of these methods:
+
+   a. Set it as an environment variable:
+   ```bash
+   # For Unix/Linux/macOS
+   export HACKMD_ACCESS_TOKEN=your_access_token_here
+   
+   # For Windows PowerShell
+   $env:HACKMD_ACCESS_TOKEN="your_access_token_here"
+   ```
+
+   b. Or create a `.env` file in the project root (not tracked by git):
+   ```
+   HACKMD_ACCESS_TOKEN=your_access_token_here
+   ```
+
+You can get your access token from [HackMD API documentation](https://hackmd.io/@hackmd-api/developer-portal).
+
+## Running the Example
+
+To run the example:
+
+```bash
+npm start
+```
+
+## What's Demonstrated
+
+The example demonstrates several features of the HackMD API client:
+
+1. Getting user information
+2. Creating a new note
+3. Using ETag support for caching
+4. Updating note content
+5. Getting raw response data
+6. Deleting notes
+
+## Features Shown
+
+- Retry configuration with exponential backoff
+- ETag support for caching
+- Response data unwrapping
+- Error handling
+- Environment variable configuration 

examples/nodejs/index.js

@@ -0,0 +1,77 @@
+import HackMDAPI from '@hackmd/api';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+// Check for required environment variable
+if (!process.env.HACKMD_ACCESS_TOKEN) {
+  console.error('Error: HACKMD_ACCESS_TOKEN environment variable is not set.');
+  console.error('Please set your HackMD access token using one of these methods:');
+  console.error('1. Create a .env file with HACKMD_ACCESS_TOKEN=your_token_here');
+  console.error('2. Set the environment variable directly: export HACKMD_ACCESS_TOKEN=your_token_here');
+  process.exit(1);
+}
+
+// Create API client with retry configuration
+const client = new HackMDAPI(process.env.HACKMD_ACCESS_TOKEN, 'https://api.hackmd.io/v1', {
+  retryConfig: {
+    maxRetries: 3,
+    baseDelay: 100
+  }
+});
+
+async function main() {
+  try {
+    // Example 1: Get user information
+    console.log('Getting user information...');
+    const me = await client.getMe();
+    console.log('User email:', me.email);
+    console.log('User name:', me.name);
+
+    // Example 2: Create a new note
+    console.log('\nCreating a new note...');
+    const newNote = await client.createNote({
+      title: 'Test Note',
+      content: '# Hello from HackMD API\n\nThis is a test note created using the API client.',
+      readPermission: 'guest',
+      writePermission: 'owner'
+    });
+    console.log('Created note ID:', newNote.id);
+    console.log('Note URL:', newNote.publishLink);
+
+    // Example 3: Get note with ETag support
+    console.log('\nGetting note with ETag support...');
+    const note = await client.getNote(newNote.id);
+    console.log('Note content:', note.content);
+    
+    // Second request with ETag
+    const updatedNote = await client.getNote(newNote.id, { etag: note.etag });
+    console.log('Note status:', updatedNote.status);
+
+    // Example 4: Update note content
+    console.log('\nUpdating note content...');
+    const updatedContent = await client.updateNoteContent(newNote.id, '# Updated Content\n\nThis note has been updated!');
+    console.log('Updated note content:', updatedContent.content);
+
+    // Example 5: Get raw response (unwrapData: false)
+    console.log('\nGetting raw response...');
+    const rawResponse = await client.getNote(newNote.id, { unwrapData: false });
+    console.log('Response headers:', rawResponse.headers);
+    console.log('Response status:', rawResponse.status);
+
+    // Example 6: Delete the test note
+    console.log('\nCleaning up - deleting test note...');
+    await client.deleteNote(newNote.id);
+    console.log('Note deleted successfully');
+
+  } catch (error) {
+    console.error('Error:', error.message);
+    if (error.response) {
+      console.error('Response status:', error.response.status);
+      console.error('Response data:', error.response.data);
+    }
+  }
+}
+
+main(); 

examples/nodejs/package-lock.json

@@ -0,0 +1,14 @@
+{
+  "name": "hackmd-api-example",
+  "version": "1.0.0",
+  "description": "Example usage of HackMD API client",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@hackmd/api": "file:../../nodejs",
+    "dotenv": "^16.4.5"
+  }
+} 

examples/nodejs/package.json

@@ -22,7 +22,7 @@ const config = {
       ]
     },
     "ignorePatterns": [
-      ".eslintrc.js"
+      ".eslintrc.cjs"
     ],
 }