Merge fix/issue-5-error-handling: error details + rate limit retry (closes #5)

* fix/issue-5-error-handling:
  feat: improved error handling + rate limit retry (closes #5)

Author: JordanCoin

bin/notion.js

@@ -137,11 +137,35 @@ async function resolvePageId(aliasOrId, filterInput) {
 // ─── Lazy Notion client ────────────────────────────────────────────────────────
 
 let _notion = null;
+let _notionWithRetry = null;
+
+function wrapNotionClient(notion) {
+  const wrap = target => new Proxy(target, {
+    get(obj, prop) {
+      const value = obj[prop];
+      if (typeof value === 'function') {
+        return (...args) => withRetry(() => value.apply(obj, args));
+      }
+      if (value && typeof value === 'object') {
+        return wrap(value);
+      }
+      return value;
+    },
+  });
+  return wrap(notion);
+}
+
+function createNotionClient(apiKey) {
+  const notion = new Client({ auth: apiKey });
+  return wrapNotionClient(notion);
+}
+
 function getNotion() {
   if (!_notion) {
     _notion = new Client({ auth: getApiKey() });
+    _notionWithRetry = wrapNotionClient(_notion);
   }
-  return _notion;
+  return _notionWithRetry;
 }
 
 // ─── Helpers (imported from lib/helpers.js) ────────────────────────────────────
@@ -164,6 +188,8 @@ const {
   extractDynamicProps,
   UUID_REGEX,
   paginate,
+  withRetry,
+  getNotionApiErrorDetails,
 } = helpers;
 
 /** Check if --json flag is set anywhere in the command chain */
@@ -184,7 +210,21 @@ async function runCommand(name, fn) {
   try {
     await fn();
   } catch (err) {
-    console.error(`${name} failed:`, err.message);
+    const details = getNotionApiErrorDetails(err);
+    if (details) {
+      console.error(`${name} failed: Notion API error`);
+      if (details.status !== undefined) console.error(`Status: ${details.status}`);
+      if (details.code) console.error(`Code: ${details.code}`);
+      if (details.message) console.error(`Message: ${details.message}`);
+      if (details.body) {
+        const bodyText = typeof details.body === 'string'
+          ? details.body
+          : JSON.stringify(details.body, null, 2);
+        console.error(`Body: ${bodyText}`);
+      }
+    } else {
+      console.error(`${name} failed:`, err.message);
+    }
     process.exit(1);
   }
 }
@@ -300,7 +340,7 @@ program
     console.log('');
 
     // Discover databases
-    const notion = new Client({ auth: apiKey });
+    const notion = createNotionClient(apiKey);
     try {
       const res = await notion.search({
         filter: { value: 'data_source', property: 'object' },

lib/helpers.js

@@ -4,11 +4,13 @@ const filters = require('./filters');
 const format = require('./format');
 const markdown = require('./markdown');
 const paginate = require('./paginate');
+const retry = require('./retry');
 
 module.exports = {
   ...config,
   ...filters,
   ...format,
   ...markdown,
   ...paginate,
+  ...retry,
 };

lib/retry.js

@@ -0,0 +1,76 @@
+// lib/retry.js — Retry helpers for Notion API calls
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function isRateLimitError(err) {
+  if (!err || typeof err !== 'object') return false;
+  return err.status === 429 || err.code === 'rate_limited';
+}
+
+function isNotionApiError(err) {
+  if (!err || typeof err !== 'object') return false;
+  if (err.name === 'APIResponseError') return true;
+  return typeof err.status === 'number' && err.body && typeof err.body === 'object';
+}
+
+function getNotionApiErrorDetails(err) {
+  if (!isNotionApiError(err)) return null;
+  const details = {
+    status: err.status,
+    code: err.code,
+    body: err.body,
+  };
+  if (err.message && (!err.body || err.body.message !== err.message)) {
+    details.message = err.message;
+  }
+  return details;
+}
+
+function calculateDelayMs(baseDelayMs, attempt, jitter, randomFn) {
+  const delayMs = baseDelayMs * (2 ** (attempt - 1));
+  if (!jitter) return delayMs;
+  const rand = typeof randomFn === 'function' ? randomFn() : Math.random();
+  const jittered = delayMs * (0.5 + rand);
+  return Math.max(0, Math.floor(jittered));
+}
+
+async function withRetry(fn, options = {}) {
+  const {
+    maxAttempts = 3,
+    baseDelayMs = 1000,
+    jitter = true,
+    random = Math.random,
+    sleep: sleepFn = sleep,
+    onRetry,
+  } = options;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (!isRateLimitError(err) || attempt === maxAttempts) {
+        throw err;
+      }
+      const delayMs = calculateDelayMs(baseDelayMs, attempt, jitter, random);
+      if (typeof onRetry === 'function') {
+        onRetry({ attempt, maxAttempts, delayMs, error: err });
+      } else {
+        const delaySec = Math.max(0.1, Math.round(delayMs / 100) / 10);
+        console.error(`Rate limited, retrying in ${delaySec}s...`);
+      }
+      await sleepFn(delayMs);
+    }
+  }
+
+  return undefined;
+}
+
+module.exports = {
+  isRateLimitError,
+  isNotionApiError,
+  getNotionApiErrorDetails,
+  withRetry,
+  calculateDelayMs,
+};

test/unit.test.js

@@ -22,6 +22,7 @@ const {
   extractDynamicProps,
   UUID_REGEX,
   paginate,
+  withRetry,
 } = require('../lib/helpers');
 
 // ─── richTextToPlain ───────────────────────────────────────────────────────────
@@ -1146,3 +1147,86 @@ describe('paginate', () => {
     assert.equal(has_more, false);
   });
 });
+
+// ─── withRetry ────────────────────────────────────────────────────────────────
+
+describe('withRetry', () => {
+  function rateLimitError() {
+    const err = new Error('Rate limited');
+    err.status = 429;
+    err.code = 'rate_limited';
+    err.body = { message: 'Rate limited' };
+    return err;
+  }
+
+  it('retries rate limit errors and eventually succeeds', async () => {
+    let calls = 0;
+    const delays = [];
+    const fn = async () => {
+      calls += 1;
+      if (calls < 3) {
+        throw rateLimitError();
+      }
+      return 'ok';
+    };
+
+    const result = await withRetry(fn, {
+      maxAttempts: 3,
+      baseDelayMs: 1000,
+      jitter: false,
+      sleep: async (ms) => {
+        delays.push(ms);
+      },
+      onRetry: () => {},
+    });
+
+    assert.equal(result, 'ok');
+    assert.equal(calls, 3);
+    assert.deepEqual(delays, [1000, 2000]);
+  });
+
+  it('stops after max attempts on repeated rate limits', async () => {
+    let calls = 0;
+    const fn = async () => {
+      calls += 1;
+      throw rateLimitError();
+    };
+
+    await assert.rejects(
+      () => withRetry(fn, {
+        maxAttempts: 3,
+        baseDelayMs: 10,
+        jitter: false,
+        sleep: async () => {},
+        onRetry: () => {},
+      }),
+      /Rate limited/,
+    );
+
+    assert.equal(calls, 3);
+  });
+
+  it('does not retry non-rate-limit errors', async () => {
+    let calls = 0;
+    const err = new Error('Boom');
+    err.status = 400;
+    err.code = 'invalid_request';
+    err.body = { message: 'Boom' };
+
+    await assert.rejects(
+      () => withRetry(async () => {
+        calls += 1;
+        throw err;
+      }, {
+        maxAttempts: 3,
+        baseDelayMs: 10,
+        jitter: false,
+        sleep: async () => {},
+        onRetry: () => {},
+      }),
+      /Boom/,
+    );
+
+    assert.equal(calls, 1);
+  });
+});