feat(restclient): add REST API client for interactive API exploration

restclient.el + restclient-jq integration with SkyFi API templates,
tutorial file, auto key injection from authinfo, 17 ERT tests.

3 files changed, 247 insertions, 0 deletions

diff --git a/tests/test-restclient-config-inject-skyfi-key.el b/tests/test-restclient-config-inject-skyfi-key.el
new file mode 100644
index 00000000..d471b913
--- /dev/null
+++ b/tests/test-restclient-config-inject-skyfi-key.el
@@ -0,0 +1,147 @@
+;;; test-restclient-config-inject-skyfi-key.el --- Tests for cj/restclient--inject-skyfi-key -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Unit tests for cj/restclient--inject-skyfi-key function.
+;; Replaces the :skyfi-key placeholder in a restclient buffer with the real
+;; API key from authinfo. Tests cover Normal, Boundary, and Error cases.
+
+;;; Code:
+
+(when noninteractive
+  (package-initialize))
+
+(require 'ert)
+(require 'restclient-config)
+
+;; ---------------------------------------------------------------------------
+;; Test Helpers
+;; ---------------------------------------------------------------------------
+
+(defvar test-inject--fake-key "sk_test_fake_key_12345"
+  "Fake API key used in tests.")
+
+(defmacro test-inject--with-skyfi-buffer (content &rest body)
+  "Create a temp buffer with CONTENT simulating skyfi-api.rest, then run BODY.
+Sets buffer-file-name to skyfi-api.rest and activates restclient-mode.
+Binds `cj/skyfi-api-key' to return `test-inject--fake-key'."
+  (declare (indent 1))
+  `(with-temp-buffer
+     (insert ,content)
+     (setq buffer-file-name (expand-file-name "data/skyfi-api.rest" user-emacs-directory))
+     (restclient-mode)
+     (cl-letf (((symbol-function 'cj/skyfi-api-key)
+                (lambda () test-inject--fake-key)))
+       ,@body)))
+
+;; ---------------------------------------------------------------------------
+;;; Normal Cases
+;; ---------------------------------------------------------------------------
+
+(ert-deftest test-inject-skyfi-key-replaces-placeholder ()
+  "Replaces :skyfi-key = PLACEHOLDER with real key."
+  (test-inject--with-skyfi-buffer
+      ":skyfi-key = PLACEHOLDER\n#\nGET https://example.com\n"
+    (cj/restclient--inject-skyfi-key)
+    (goto-char (point-min))
+    (should (string-match-p (format ":skyfi-key = %s" test-inject--fake-key)
+                            (buffer-string)))))
+
+(ert-deftest test-inject-skyfi-key-preserves-other-content ()
+  "Rest of buffer content unchanged after injection."
+  (let ((rest-content "# SkyFi API\nGET https://app.skyfi.com/platform-api/\nAPIKey: :skyfi-key\n"))
+    (test-inject--with-skyfi-buffer
+        (concat ":skyfi-key = PLACEHOLDER\n" rest-content)
+      (cj/restclient--inject-skyfi-key)
+      (should (string-match-p "# SkyFi API" (buffer-string)))
+      (should (string-match-p "APIKey: :skyfi-key" (buffer-string))))))
+
+(ert-deftest test-inject-skyfi-key-only-replaces-skyfi-key-line ()
+  "Does not modify other restclient variable lines."
+  (test-inject--with-skyfi-buffer
+      ":skyfi-key = PLACEHOLDER\n:other-var = keep-me\n"
+    (cj/restclient--inject-skyfi-key)
+    (should (string-match-p ":other-var = keep-me" (buffer-string)))))
+
+;; ---------------------------------------------------------------------------
+;;; Boundary Cases
+;; ---------------------------------------------------------------------------
+
+(ert-deftest test-inject-skyfi-key-no-key-line-no-error ()
+  "Buffer with no :skyfi-key line — no change, no error."
+  (test-inject--with-skyfi-buffer
+      "# Just comments\nGET https://example.com\n"
+    (let ((before (buffer-string)))
+      (cj/restclient--inject-skyfi-key)
+      (should (string= before (buffer-string))))))
+
+(ert-deftest test-inject-skyfi-key-already-has-value ()
+  "Buffer where :skyfi-key already has a real value — still replaces (idempotent)."
+  (test-inject--with-skyfi-buffer
+      ":skyfi-key = old_real_key_abc\n"
+    (cj/restclient--inject-skyfi-key)
+    (should (string-match-p (format ":skyfi-key = %s" test-inject--fake-key)
+                            (buffer-string)))))
+
+(ert-deftest test-inject-skyfi-key-empty-buffer ()
+  "Empty buffer — no error."
+  (test-inject--with-skyfi-buffer ""
+    (cj/restclient--inject-skyfi-key)
+    (should (string= "" (buffer-string)))))
+
+(ert-deftest test-inject-skyfi-key-only-first-occurrence ()
+  "Multiple :skyfi-key lines — only first replaced."
+  (test-inject--with-skyfi-buffer
+      ":skyfi-key = PLACEHOLDER\n:skyfi-key = SECOND\n"
+    (cj/restclient--inject-skyfi-key)
+    (let ((content (buffer-string)))
+      (should (string-match-p (format ":skyfi-key = %s" test-inject--fake-key) content))
+      (should (string-match-p ":skyfi-key = SECOND" content)))))
+
+;; ---------------------------------------------------------------------------
+;;; Error Cases
+;; ---------------------------------------------------------------------------
+
+(ert-deftest test-inject-skyfi-key-wrong-mode-no-replacement ()
+  "Wrong major mode — no replacement happens."
+  (with-temp-buffer
+    (insert ":skyfi-key = PLACEHOLDER\n")
+    (setq buffer-file-name (expand-file-name "data/skyfi-api.rest" user-emacs-directory))
+    (fundamental-mode)
+    (let ((before (buffer-string)))
+      (cj/restclient--inject-skyfi-key)
+      (should (string= before (buffer-string))))))
+
+(ert-deftest test-inject-skyfi-key-wrong-filename-no-replacement ()
+  "Wrong filename — no replacement happens."
+  (with-temp-buffer
+    (insert ":skyfi-key = PLACEHOLDER\n")
+    (setq buffer-file-name "/tmp/other-file.rest")
+    (restclient-mode)
+    (let ((before (buffer-string)))
+      (cj/restclient--inject-skyfi-key)
+      (should (string= before (buffer-string))))))
+
+(ert-deftest test-inject-skyfi-key-no-filename-no-replacement ()
+  "No filename (scratch buffer) — no replacement happens."
+  (with-temp-buffer
+    (insert ":skyfi-key = PLACEHOLDER\n")
+    (restclient-mode)
+    (setq buffer-file-name nil)
+    (let ((before (buffer-string)))
+      (cj/restclient--inject-skyfi-key)
+      (should (string= before (buffer-string))))))
+
+(ert-deftest test-inject-skyfi-key-auth-returns-nil-no-error ()
+  "Auth-source returns nil — no error, no replacement."
+  (with-temp-buffer
+    (insert ":skyfi-key = PLACEHOLDER\n")
+    (setq buffer-file-name (expand-file-name "data/skyfi-api.rest" user-emacs-directory))
+    (restclient-mode)
+    (cl-letf (((symbol-function 'cj/skyfi-api-key)
+               (lambda () nil)))
+      (let ((before (buffer-string)))
+        (cj/restclient--inject-skyfi-key)
+        (should (string= before (buffer-string)))))))
+
+(provide 'test-restclient-config-inject-skyfi-key)
+;;; test-restclient-config-inject-skyfi-key.el ends here
diff --git a/tests/test-restclient-config-new-buffer.el b/tests/test-restclient-config-new-buffer.el
new file mode 100644
index 00000000..a89ec3a3
--- /dev/null
+++ b/tests/test-restclient-config-new-buffer.el
@@ -0,0 +1,62 @@
+;;; test-restclient-config-new-buffer.el --- Tests for cj/restclient-new-buffer -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Unit tests for cj/restclient-new-buffer function.
+;; Creates a scratch *restclient* buffer in restclient-mode.
+;; Covers Normal and Boundary cases.
+
+;;; Code:
+
+(when noninteractive
+  (package-initialize))
+
+(require 'ert)
+(require 'restclient-config)
+
+;;; Normal Cases
+
+(ert-deftest test-restclient-new-buffer-creates-buffer ()
+  "Creates a buffer named *restclient*."
+  (unwind-protect
+      (progn
+        (cj/restclient-new-buffer)
+        (should (get-buffer "*restclient*")))
+    (when (get-buffer "*restclient*")
+      (kill-buffer "*restclient*"))))
+
+(ert-deftest test-restclient-new-buffer-sets-mode ()
+  "Buffer is in restclient-mode."
+  (unwind-protect
+      (progn
+        (cj/restclient-new-buffer)
+        (with-current-buffer "*restclient*"
+          (should (eq major-mode 'restclient-mode))))
+    (when (get-buffer "*restclient*")
+      (kill-buffer "*restclient*"))))
+
+(ert-deftest test-restclient-new-buffer-switches-to-buffer ()
+  "Switches to the *restclient* buffer."
+  (unwind-protect
+      (progn
+        (cj/restclient-new-buffer)
+        (should (string= (buffer-name (current-buffer)) "*restclient*")))
+    (when (get-buffer "*restclient*")
+      (kill-buffer "*restclient*"))))
+
+;;; Boundary Cases
+
+(ert-deftest test-restclient-new-buffer-reuses-existing ()
+  "Reuses existing *restclient* buffer instead of creating a duplicate."
+  (unwind-protect
+      (let ((buf (get-buffer-create "*restclient*")))
+        (with-current-buffer buf
+          (restclient-mode)
+          (insert "# existing content"))
+        (cj/restclient-new-buffer)
+        (should (eq (current-buffer) buf))
+        (should (string-match-p "existing content" (buffer-string))))
+    (when (get-buffer "*restclient*")
+      (kill-buffer "*restclient*"))))
+
+(provide 'test-restclient-config-new-buffer)
+;;; test-restclient-config-new-buffer.el ends here
diff --git a/tests/test-restclient-config-skyfi-buffer.el b/tests/test-restclient-config-skyfi-buffer.el
new file mode 100644
index 00000000..7685c77c
--- /dev/null
+++ b/tests/test-restclient-config-skyfi-buffer.el
@@ -0,0 +1,38 @@
+;;; test-restclient-config-skyfi-buffer.el --- Tests for cj/restclient-skyfi-buffer -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Unit tests for cj/restclient-skyfi-buffer function.
+;; Opens the SkyFi API template file.
+;; Covers Normal and Error cases.
+
+;;; Code:
+
+(when noninteractive
+  (package-initialize))
+
+(require 'ert)
+(require 'restclient-config)
+
+;;; Normal Cases
+
+(ert-deftest test-restclient-skyfi-buffer-opens-file ()
+  "Opens existing skyfi-api.rest file and switches to it."
+  (let ((skyfi-file (expand-file-name "data/skyfi-api.rest" user-emacs-directory)))
+    (when (file-exists-p skyfi-file)
+      (unwind-protect
+          (progn
+            (cj/restclient-skyfi-buffer)
+            (should (string-match-p "skyfi-api\\.rest"
+                                    (buffer-file-name (current-buffer)))))
+        (when-let ((buf (get-file-buffer skyfi-file)))
+          (kill-buffer buf))))))
+
+;;; Error Cases
+
+(ert-deftest test-restclient-skyfi-buffer-missing-file-signals-error ()
+  "Signals user-error when skyfi-api.rest does not exist."
+  (let ((cj/restclient-data-dir "/tmp/nonexistent-restclient-test-dir/"))
+    (should-error (cj/restclient-skyfi-buffer) :type 'user-error)))
+
+(provide 'test-restclient-config-skyfi-buffer)
+;;; test-restclient-config-skyfi-buffer.el ends here