Evernote Rate Limits

Overview

Evernote enforces rate limits per API key, per user. When exceeded, the API throws EDAMSystemException with errorCode: RATE_LIMIT_REACHED and rateLimitDuration (seconds to wait). Production integrations must handle this gracefully.

Prerequisites

• Evernote SDK setup
• Understanding of async/await patterns
• Error handling implementation

Instructions

Step 1: Rate Limit Handler

Catch EDAMSystemException and check for rateLimitDuration. Implement exponential backoff: wait the specified duration, then retry. Track retry attempts to avoid infinite loops.

async function withRateLimitRetry(operation, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (error.rateLimitDuration && attempt < maxRetries - 1) {
        const waitMs = error.rateLimitDuration * 1000;
        console.log(`Rate limited. Waiting ${error.rateLimitDuration}s...`);
        await new Promise(r => setTimeout(r, waitMs));
        continue;
      }
      throw error;
    }
  }
}

Step 2: Rate-Limited Client Wrapper

Wrap the NoteStore with a class that adds configurable delays between API calls. Use a request queue to prevent bursts. Track request timestamps for monitoring.

class RateLimitedClient {
  constructor(noteStore, minDelayMs = 100) {
    this.noteStore = noteStore;
    this.minDelayMs = minDelayMs;
    this.lastRequestTime = 0;
  }

  async call(method, ...args) {
    const elapsed = Date.now() - this.lastRequestTime;
    if (elapsed < this.minDelayMs) {
      await new Promise(r => setTimeout(r, this.minDelayMs - elapsed));
    }
    this.lastRequestTime = Date.now();
    return withRateLimitRetry(() => this.noteStoremethod);
  }
}

Step 3: Batch Operations with Rate Limiting

Process items sequentially with delay between each operation. On rate limit, wait and retry the failed item. Report progress via callback. Collect successes and failures.

Step 4: Avoiding Rate Limits

Strategies to minimize API calls: cache listNotebooks() and listTags() results, use findNotesMetadata() instead of getNote() for listings, request only needed fields in NotesMetadataResultSpec, batch reads with sync chunks instead of individual fetches.

Step 5: Rate Limit Monitoring

Track request counts, rate limit hits, average response times, and wait times. Log statistics periodically to identify optimization opportunities.

For the complete rate limiter, batch processor, monitoring dashboard, and optimization examples, see Implementat

Evernote Reference Architecture

Overview

Production-ready architecture patterns for building scalable, maintainable Evernote integrations. Covers service layer design, caching strategy, sync architecture, and deployment topology.

Prerequisites

• Understanding of microservices or modular monolith architecture
• Cloud platform familiarity (AWS, GCP, or Azure)
• Knowledge of message queues and caching

Instructions

Architecture Layers

Client Layer    [Web App / Mobile / CLI]
                        |
API Layer       [Express/Fastify REST API]
                        |
Service Layer   [NoteService | SearchService | SyncService]
                        |
Integration     [EvernoteClient (rate-limited, instrumented)]
                        |
Infrastructure  [Redis Cache | PostgreSQL | Message Queue]

Service Layer Design

Separate concerns into focused services:

• NoteService: CRUD operations, ENML formatting, tag management
• SearchService: Query building, pagination, result enrichment
• SyncService: Webhook handling, incremental sync, conflict resolution
• AuthService: OAuth flow, token storage, refresh logic

// services/index.js - Service registry
class ServiceRegistry {
  constructor(noteStore, cache, db) {
    this.notes = new NoteService(noteStore);
    this.search = new SearchService(noteStore, cache);
    this.sync = new SyncService(noteStore, db);
  }
}

Caching Strategy

Cache at two levels: in-memory LRU for hot data (note metadata, user info) and Redis for shared state (notebook lists, tag lists, sync checkpoints). Invalidate on webhook notification.

Sync Architecture

Use webhooks as the primary change notification channel. Fall back to polling when webhooks are unavailable. Process changes through a message queue for reliability and retry. Store sync state (USN) in the database for crash recovery.

Evernote Webhook → API Gateway → Message Queue → Sync Worker → Database
                                                      ↓
                                              Evernote API (fetch changes)

Database Schema

Store mirrored Evernote data locally for fast reads. Key tables: users (token, expiration), notebooks, notes (content, metadata), tags, resources (metadata, file path), sync_state (user_id, last_usn).

For the complete architecture diagrams, service implementations, database schema, and scaling guidelines, see Implementation Guide.

Output

• Layered architecture with clear separation of concerns
• Service registry pattern for dependenc

Evernote SDK Patterns

Overview

Production-ready patterns for working with the Evernote SDK, including search with NoteFilter, pagination, attachments, tags, error handling wrappers, and batch operations with rate limit handling.

Prerequisites

• Completed evernote-install-auth and evernote-hello-world
• Understanding of Evernote data model (Notes, Notebooks, Tags, Resources)
• Familiarity with async/await and Promises

Instructions

Pattern 1: Search with NoteFilter

Use NoteFilter for query terms and sort order, paired with NotesMetadataResultSpec to select returned fields. This avoids fetching full note content when only metadata is needed.

const filter = new Evernote.NoteStore.NoteFilter({
  words: 'tag:important notebook:Work',
  ascending: false,
  order: Evernote.Types.NoteSortOrder.UPDATED
});

const spec = new Evernote.NoteStore.NotesMetadataResultSpec({
  includeTitle: true, includeUpdated: true,
  includeTagGuids: true, includeNotebookGuid: true
});

const result = await noteStore.findNotesMetadata(filter, 0, 100, spec);

Pattern 2: Creating Notes with Attachments

Compute the MD5 hash of the file buffer, create a Resource with the binary data and MIME type, embed it in ENML with <en-media type="..." hash="..."/>, and attach it to the note.

const hash = crypto.createHash('md5').update(fileBuffer).digest('hex');
const resource = new Evernote.Types.Resource();
resource.data = new Evernote.Types.Data();
resource.data.body = fileBuffer;
resource.mime = 'image/png';

const note = new Evernote.Types.Note();
note.title = 'Note with Attachment';
note.content = wrapInENML(`<en-media type="image/png" hash="${hash}"/>`);
note.resources = [resource];
await noteStore.createNote(note);

Pattern 3: Error Handling Wrapper

Wrap API calls to distinguish EDAMUserException (client errors), EDAMSystemException (rate limits, maintenance), and EDAMNotFoundException (invalid GUIDs). Use error.rateLimitDuration for automatic retry delays.

Pattern 4: Batch Operations

Process items sequentially with configurable delay between operations. On rate limit errors, wait for rateLimitDuration seconds then retry. Track progress with callbacks.

Pattern 5: Tag and Notebook Management

Implement getOrCreateTag() and getOrCreateNotebook() for idempotent operations. Use listTags() / listNotebooks() to check existence before creating.

For all nine patterns with complete implementations, see Implementation Gu

Evernote Security Basics

Overview

Security best practices for Evernote API integrations, covering credential management, OAuth hardening, token storage, data protection, and secure logging patterns.

Prerequisites

• Evernote SDK setup
• Understanding of OAuth 1.0a
• Basic cryptography concepts (AES encryption, hashing)

Instructions

Step 1: Credential Management

Store consumerKey, consumerSecret, and access tokens in environment variables or a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault). Never commit credentials to source control. Add .env to .gitignore.

// Load from environment, fail fast if missing
const requiredVars = ['EVERNOTE_CONSUMER_KEY', 'EVERNOTE_CONSUMER_SECRET'];
for (const v of requiredVars) {
  if (!process.env[v]) throw new Error(`Missing required env var: ${v}`);
}

Step 2: Secure OAuth Flow

Add CSRF protection with a state parameter stored in the session. Validate the callback URL matches your registered domain. Use HTTPS-only for all OAuth endpoints. Set secure cookie flags for session tokens.

// Generate CSRF token for OAuth state
const csrfToken = crypto.randomBytes(32).toString('hex');
req.session.oauthCsrf = csrfToken;

// Verify on callback
if (req.query.state !== req.session.oauthCsrf) {
  return res.status(403).send('CSRF validation failed');
}

Step 3: Encrypted Token Storage

Encrypt access tokens at rest using AES-256-GCM before storing in your database. Decrypt only when making API calls. Store the encryption key separately from the database.

Step 4: Input Validation

Sanitize all user input before embedding in ENML. Validate note titles (max 255 chars), tag names (max 100 chars, no commas), and notebook names (max 100 chars). Strip forbidden HTML elements and attributes.

Step 5: Secure Logging

Redact access tokens, consumer secrets, and user email addresses from log output. Log only the first 8 characters of tokens for debugging correlation.

function redactToken(token) {
  if (!token || token.length < 12) return '***';
  return token.slice(0, 8) + '...[REDACTED]';
}

Step 6: Token Lifecycle Management

Track token expiration (edam_expires), implement proactive refresh before expiry, and handle AUTH_EXPIRED errors gracefully. Tokens default to 1-year validity but users can set shorter durations.

For the complete security implementation including encrypted storage, CSRF-protected OAuth, input validation, and audit logging, see Implementation Guide.

Output

• Environment-based credential m

Evernote Upgrade & Migration

Current State

!npm list evernote 2>/dev/null || echo 'evernote SDK not installed'

Overview

Guide for upgrading Evernote SDK versions, converting callback-based code to Promises, handling breaking changes, and maintaining backward compatibility during gradual migration.

Prerequisites

• Existing Evernote integration to upgrade
• Test environment for validation
• Understanding of current implementation patterns

Instructions

Step 1: Check Current Version

Identify your current SDK version and compare against the latest release. Check the changelog for breaking changes between versions.

# Check installed version
npm list evernote

# Check latest available
npm view evernote version

# View changelog
npm view evernote repository.url

Step 2: Review Breaking Changes

Common breaking changes across Evernote SDK versions:

• Constructor changes: new Evernote.Note() became new Evernote.Types.Note()
• Callback to Promise: Older versions used callbacks, newer versions return Promises
• Import path changes: Module structure may change between major versions
• Thrift version updates: Underlying Thrift protocol may change serialization

Step 3: Convert Callbacks to Promises

Wrap callback-based SDK calls in Promise wrappers for modern async/await usage.

// OLD: Callback pattern
noteStore.getNote(guid, true, false, false, false, (error, note) => {
  if (error) return handleError(error);
  processNote(note);
});

// NEW: Promise/async pattern
const note = await noteStore.getNote(guid, true, false, false, false);
processNote(note);

Step 4: Compatibility Layer

Build a compatibility layer that supports both old and new SDK patterns during gradual migration. This allows upgrading module by module instead of a big-bang rewrite.

class EvernoteCompat {
  constructor(noteStore) {
    this.noteStore = noteStore;
  }

  // Works with both callback and Promise-based SDK
  async getNote(guid, opts = {}) {
    const { withContent = true, withResources = false } = opts;
    return this.noteStore.getNote(guid, withContent, withResources, false, false);
  }

  async createNote(title, content, notebookGuid) {
    const Note = Evernote.Types?.Note || Evernote.Note;
    const note = new Note();
    note.title = title;
    note.content = content;
    if (notebookGuid) note.notebookGuid = notebookGuid;
    return this.noteStore.createNote(note);
  }
}

Step 5: Test Suite Updates

Update test assertions for new SDK response shapes. Add tests for the compatibility layer. Run both unit and integration te

Evernote Webhooks & Events

Overview

Implement Evernote webhook notifications for real-time change detection. Evernote webhooks notify your endpoint that changes occurred, but you must use the sync API to retrieve the actual changed data.

Prerequisites

• Evernote API key with webhook permissions
• HTTPS endpoint accessible from the internet
• Understanding of Evernote sync API

Instructions

Step 1: Webhook Endpoint

Create an Express endpoint that receives webhook POST requests. Evernote sends userId, guid (notebook GUID), and reason (create, update, notebook) as query parameters. Respond with HTTP 200 immediately, then process asynchronously.

app.post('/evernote/webhook', (req, res) => {
  const { userId, guid, reason } = req.query;
  res.sendStatus(200); // Respond immediately

  // Process asynchronously
  processWebhook({ userId, notebookGuid: guid, reason })
    .catch(err => console.error('Webhook processing failed:', err));
});

Step 2: Webhook Reasons

Handle three webhook reasons: create (new note created), update (note modified), and notebook (notebook-level change). Each triggers a sync of the affected notebook.

Step 3: Sync State Management

Store the last sync USN per user. On webhook receipt, call getSyncState() to get the current server USN, then getFilteredSyncChunk() to fetch only the changes since your last sync.

const syncState = await noteStore.getSyncState();
const chunk = await noteStore.getFilteredSyncChunk(
  lastUSN,
  100,  // maxEntries
  new Evernote.NoteStore.SyncChunkFilter({
    includeNotes: true,
    includeNotebooks: true,
    includeTags: true
  })
);

Step 4: Event Processing and Handlers

Route sync chunk entries to typed handlers: onNoteCreated, onNoteUpdated, onNoteDeleted, onNotebookChanged. Implement idempotency by tracking processed USNs to handle duplicate webhook deliveries.

Step 5: Polling Fallback

Implement a polling fallback for environments where webhooks are unavailable. Poll getSyncState() on a timer (e.g., every 5 minutes) and sync when updateCount changes.

For the full webhook server, sync manager, event handlers, and polling implementations, see Implementation Guide.

Output

• Express webhook endpoint with async processing
• Sync state manager with USN tracking
• Event router for create, update, and delete operations
• Idempotent event processing (handles duplicate deliveries)
• Polling fallback for non-webhook environments

Error Handling