fix(images): prevent URL expiration by immediate download

Implemented two-phase fix for Issue #94:

**Phase 1: Reorder image processing (CRITICAL FIX)**
- Moved image download to immediately after markdown conversion
- Images now process before emoji and callout processing
- Reduces time gap from 3-7 seconds to <1 second per page
- In generateBlocks.ts:processSinglePage(), moved processAndReplaceImages()
  from line 320 to line 287 (right after toMarkdownString())

**Phase 2: Expired URL detection and logging**
- Added isExpiredUrlError() helper to detect 403 expired signatures
- Enhanced error logging to identify expired URLs specifically
- Detects AWS S3 "SignatureDoesNotMatch" and other expiration errors
- Provides clear diagnostic message when URLs expire

**Testing**
- Added comprehensive test suite: imageUrlExpiration.test.ts
- Added expired URL detection tests: expiredUrlDetection.test.ts
- All existing tests pass (downloadImage.test.ts: 9/9)
- Expired URL detection tests pass (17/17)

**Impact**
- Notion image URLs expire after 1 hour
- Previous flow: fetch → emoji → callouts → images (3-7s delay)
- New flow: fetch → images → emoji → callouts (<1s delay)
- With 50 pages at 5 concurrent, saves ~30-70 seconds of cumulative delay
- Prevents URLs from expiring during batch processing

Fixes #94

See IMAGE_URL_EXPIRATION_SPEC.md for full technical specification

Author: claude

scripts/notion-fetch/__tests__/expiredUrlDetection.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Tests for Expired URL Detection (Phase 2)
+ *
+ * Tests the isExpiredUrlError() helper function that detects
+ * when a 403 error is specifically due to an expired Notion image URL.
+ */
+
+import { describe, it, expect } from "vitest";
+import { isExpiredUrlError } from "../imageProcessing";
+
+describe("Expired URL Detection", () => {
+  describe("isExpiredUrlError()", () => {
+    it("should return true for 403 with SignatureDoesNotMatch", () => {
+      const error = {
+        response: {
+          status: 403,
+          data: "SignatureDoesNotMatch: The request signature we calculated does not match the signature you provided",
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(true);
+    });
+
+    it("should return true for 403 with Request has expired", () => {
+      const error = {
+        response: {
+          status: 403,
+          data: "Request has expired",
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(true);
+    });
+
+    it("should return true for 403 with expired in message", () => {
+      const error = {
+        response: {
+          status: 403,
+          data: "The URL has expired",
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(true);
+    });
+
+    it("should return true for 403 with Signature expired", () => {
+      const error = {
+        response: {
+          status: 403,
+          data: "Signature expired: 20251127T120000Z is now earlier than 20251127T130000Z",
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(true);
+    });
+
+    it("should return true for expired in error message", () => {
+      const error = {
+        message: "Request failed: URL expired",
+        response: {
+          status: 403,
+          data: "",
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(true);
+    });
+
+    it("should return true for signature in error message", () => {
+      const error = {
+        message: "signature validation failed",
+        response: {
+          status: 403,
+          data: "",
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(true);
+    });
+
+    it("should return false for 403 without expiration indicators", () => {
+      const error = {
+        response: {
+          status: 403,
+          data: "Access Denied",
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(false);
+    });
+
+    it("should return false for 404 error", () => {
+      const error = {
+        response: {
+          status: 404,
+          data: "Not Found",
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(false);
+    });
+
+    it("should return false for 500 error", () => {
+      const error = {
+        response: {
+          status: 500,
+          data: "Internal Server Error",
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(false);
+    });
+
+    it("should return false for network errors without status", () => {
+      const error = {
+        message: "Network Error",
+        code: "ECONNREFUSED",
+      };
+
+      expect(isExpiredUrlError(error)).toBe(false);
+    });
+
+    it("should handle error with no response", () => {
+      const error = {
+        message: "Something went wrong",
+      };
+
+      expect(isExpiredUrlError(error)).toBe(false);
+    });
+
+    it("should handle null/undefined error", () => {
+      expect(isExpiredUrlError(null)).toBe(false);
+      expect(isExpiredUrlError(undefined)).toBe(false);
+    });
+
+    it("should handle error with object response data", () => {
+      const error = {
+        response: {
+          status: 403,
+          data: {
+            error: "SignatureDoesNotMatch",
+            message: "The signature does not match",
+          },
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(true);
+    });
+
+    it("should be case-insensitive for expiration indicators", () => {
+      const error1 = {
+        response: {
+          status: 403,
+          data: "SIGNATUREDOESNOTMATCH",
+        },
+      };
+
+      const error2 = {
+        response: {
+          status: 403,
+          data: "request has EXPIRED",
+        },
+      };
+
+      expect(isExpiredUrlError(error1)).toBe(true);
+      expect(isExpiredUrlError(error2)).toBe(true);
+    });
+  });
+
+  describe("Real-world AWS S3 Error Formats", () => {
+    it("should detect AWS S3 SignatureDoesNotMatch XML response", () => {
+      const error = {
+        response: {
+          status: 403,
+          data: `<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>SignatureDoesNotMatch</Code>
+  <Message>The request signature we calculated does not match the signature you provided.</Message>
+  <RequestId>ABC123</RequestId>
+</Error>`,
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(true);
+    });
+
+    it("should detect AWS S3 RequestTimeTooSkewed error", () => {
+      const error = {
+        response: {
+          status: 403,
+          data: `<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>RequestTimeTooSkewed</Code>
+  <Message>The difference between the request time and the server's time is too large.</Message>
+</Error>`,
+        },
+      };
+
+      // This should be false as it's not an expiration issue
+      expect(isExpiredUrlError(error)).toBe(false);
+    });
+
+    it("should detect AWS S3 AccessDenied without expiration", () => {
+      const error = {
+        response: {
+          status: 403,
+          data: `<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>Access Denied</Message>
+</Error>`,
+        },
+      };
+
+      expect(isExpiredUrlError(error)).toBe(false);
+    });
+  });
+});