add clean JSON output: --format json (clean) vs --format json-full (raw)

json: per-resource cleanup — drop HAL noise, HTML→md bodies, flatten persons,
drop sentinels/empty fields, hoist embedded sub-resources, rename for clarity.
json-full: unfiltered API pass-through for write operations and debugging.

Author: rmorse

.agents/plans/inbox/json-format-spec.md

@@ -88,7 +88,7 @@ hs inbox auth logout
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--config` | Config file path | `~/.config/hs/config.yaml` |
-| `--format` | Output format: `table`, `json`, `csv` | `table` |
+| `--format` | Output format: `table`, `json`, `json-full`, `csv` | `table` |
 | `--no-paginate` | Fetch all pages (combine all results) | `false` |
 | `--page` | Page number | `1` |
 | `--per-page` | Results per page | `25` |
@@ -125,7 +125,7 @@ hs inbox config path
 | `--client-id` | string | HelpScout Client ID |
 | `--client-secret` | string | HelpScout Client Secret |
 | `--default-mailbox` | int | Default mailbox ID |
-| `--format` | string | Output format: table, json, csv |
+| `--format` | string | Output format: table, json, json-full, csv |
 
 ### Self-update
 
@@ -867,13 +867,31 @@ ID     NAME       EMAIL               SLUG
 Page 1 of 1 (2 total)
 ```
 
-### JSON
+### JSON (clean)
 
 ```bash
 hs inbox mailboxes list --format json
 ```
 
-When using `--format json`, raw API responses are pretty-printed. List commands output a JSON array of objects.
+Read-optimized output. Compared to the raw API response, `--format json` applies per-resource cleanup:
+
+- Drops HAL noise (`_links`, `_embedded` wrappers)
+- Converts HTML bodies to markdown (threads, saved replies)
+- Flattens person objects to `"Name (email)"` strings
+- Drops sentinel values (`closedBy: 0`, `closedByUser: {id: 0, ...}`)
+- Drops empty arrays/strings and default-noise fields (`state: "published"`, `photoUrl`, etc.)
+- Hoists embedded sub-resources to top level (e.g. customer `_embedded.emails` → `emails`)
+- Renames for clarity (`userUpdatedAt` → `updatedAt`, `threads` count → `threadCount`)
+
+**Caveat:** `--format json` is read-only safe. HTML→markdown conversion and field removal make the output unsuitable as input for write operations (e.g. updating saved replies, composing thread bodies). Use `--format json-full` when you need write-safe data.
+
+### JSON-full (raw)
+
+```bash
+hs inbox mailboxes list --format json-full
+```
+
+Unfiltered API pass-through. Identical to the raw HelpScout API response, pretty-printed. Use this for debugging, round-tripping data back into write operations, or when you need the complete response including HAL links and embedded wrappers.
 
 ### CSV
 
@@ -915,7 +933,7 @@ Use `hs inbox config set` to write values, `hs inbox config get` to read them, a
 | `client_id` | `--client-id` | HelpScout Client ID |
 | `client_secret` | `--client-secret` | HelpScout Client Secret |
 | `default_mailbox` | `--default-mailbox` | Auto-filter conversations to this mailbox |
-| `format` | `--format` | Output format: `table`, `json`, or `csv` |
+| `format` | `--format` | Output format: `table`, `json`, `json-full`, or `csv` |
 
 ### Environment variables
 
@@ -1025,6 +1043,7 @@ internal/
     store.go                    OS keyring storage
   cmd/
     root.go                     Root command, global flags, PersistentPreRunE
+    json_clean.go               Per-resource JSON cleanup (json vs json-full)
     auth.go                     login / status / logout
     config.go                   config set / get / path
     update.go                   self-update command

README.md

@@ -78,7 +78,7 @@ func newConversationAttachmentsCmd() *cobra.Command {
 				return err
 			}
 
-			if getFormat() == "json" {
+			if isJSON() {
 				return output.PrintRaw(mustMarshal(attachments))
 			}
 
@@ -105,7 +105,7 @@ func newConversationAttachmentsCmd() *cobra.Command {
 				return err
 			}
 
-			if getFormat() == "json" {
+			if isJSON() {
 				return output.PrintRaw(data)
 			}
 

internal/cmd/attachments.go

@@ -133,12 +133,15 @@ func conversationsListCmd() *cobra.Command {
 				params.Set("embed", v)
 			}
 
-			if getFormat() == "json" {
+			if isJSON() {
 				items, _, err := api.PaginateAll(ctx, apiClient.ListConversations, params, "conversations", noPaginate)
 				if err != nil {
 					return err
 				}
-				return output.PrintRaw(mustMarshal(items))
+				if !isJSONClean() {
+					return output.PrintRaw(mustMarshal(items))
+				}
+				return output.PrintRaw(mustMarshal(cleanRawItems(items, cleanConversation)))
 			}
 
 			items, pageInfo, err := api.PaginateAll(ctx, apiClient.ListConversations, params, "conversations", noPaginate)
@@ -196,8 +199,11 @@ func conversationsGetCmd() *cobra.Command {
 				return err
 			}
 
-			if getFormat() == "json" {
-				return output.PrintRaw(data)
+			if isJSON() {
+				if !isJSONClean() {
+					return output.PrintRaw(data)
+				}
+				return output.PrintRaw(mustMarshal(cleanRawObject(data, cleanConversation)))
 			}
 
 			var c types.Conversation

internal/cmd/conversations.go

@@ -152,12 +152,15 @@ func customersListCmd() *cobra.Command {
 				params.Set("sortOrder", v)
 			}
 
-			if getFormat() == "json" {
+			if isJSON() {
 				items, _, err := api.PaginateAll(ctx, apiClient.ListCustomers, params, "customers", noPaginate)
 				if err != nil {
 					return err
 				}
-				return output.PrintRaw(mustMarshal(items))
+				if !isJSONClean() {
+					return output.PrintRaw(mustMarshal(items))
+				}
+				return output.PrintRaw(mustMarshal(cleanRawItems(items, cleanCustomer)))
 			}
 
 			items, pageInfo, err := api.PaginateAll(ctx, apiClient.ListCustomers, params, "customers", noPaginate)
@@ -205,8 +208,11 @@ func customersGetCmd() *cobra.Command {
 				return err
 			}
 
-			if getFormat() == "json" {
-				return output.PrintRaw(data)
+			if isJSON() {
+				if !isJSONClean() {
+					return output.PrintRaw(data)
+				}
+				return output.PrintRaw(mustMarshal(cleanRawObject(data, cleanCustomer)))
 			}
 
 			var c types.Customer