From a1bf7f2c08663e09d7412627bf3d56264111e093 Mon Sep 17 00:00:00 2001
From: Dan Notestein <dan@syncad.com>
Date: Tue, 30 Dec 2025 18:04:45 -0500
Subject: [PATCH] Add CLAUDE.md for AI-assisted development

---
 CLAUDE.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..751e84b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,123 @@
+# Apiary - Claude Code Guide
+
+## Project Overview
+
+Apiary is a Rust library providing async API bindings for the Hive blockchain. It offers type-safe access to Hive node APIs using JSON-RPC 2.0 protocol. Currently implements 28/89 Condenser API methods.
+
+**Author:** Bora Ülker
+**License:** MIT OR Apache-2.0
+**Upstream:** https://github.com/yokunjon/apiary
+
+## Tech Stack
+
+- **Language:** Rust 2021 edition
+- **Async Runtime:** tokio
+- **HTTP Client:** reqwest (async, JSON)
+- **Serialization:** serde, serde_json, serde_with
+- **Date/Time:** chrono
+
+## Directory Structure
+
+```
+src/
+├── lib.rs                    # Library entry point, integration tests
+├── client/
+│   ├── mod.rs               # Client module exports
+│   ├── hive_client.rs       # HiveClient, HiveNode, HiveNodes, HiveError
+│   └── method.rs            # Method trait definition
+└── methods/
+    ├── mod.rs               # Methods module exports
+    ├── utils.rs             # Shared types (Account, Asset, ObjectId, etc.)
+    └── condenser/
+        ├── mod.rs           # Condenser API exports, ns! macro
+        └── *.rs             # Individual method implementations
+```
+
+## Development Commands
+
+```bash
+# Build
+cargo build
+
+# Run all tests (connects to live Hive nodes)
+cargo test
+
+# Run specific test
+cargo test test_get_account_count
+```
+
+## Key Files
+
+- `Cargo.toml` - Package manifest and dependencies
+- `src/lib.rs` - Library root, re-exports, integration tests
+- `src/client/hive_client.rs` - Core client implementation
+- `src/client/method.rs` - Method trait that all API methods implement
+- `src/methods/utils.rs` - Shared data structures (Account, Asset, etc.)
+- `src/methods/condenser/mod.rs` - Condenser API namespace macro
+
+## Coding Conventions
+
+### Method Trait Pattern
+All API methods implement the `Method` trait:
+```rust
+pub trait Method: Sized {
+    type Params: Serialize;
+    type Result: DeserializeOwned;
+    const NAME: &'static str;
+    fn params(self) -> Self::Params;
+    fn build(self, id: u64) -> String;
+}
+```
+
+### Namespace Macro
+Use `ns!` for condenser method names:
+```rust
+const NAME: &'static str = ns!("get_account_count");
+// Expands to "condenser_api.get_account_count"
+```
+
+### Wrapper Types
+Use transparent wrapper types for type safety:
+```rust
+#[derive(Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct Account(pub String);
+```
+
+### Builder Constructors
+Provide multiple constructors for convenience:
+```rust
+pub fn new(account: Account, from: i64, limit: u16) -> Self { ... }
+pub fn latest(account: Account, limit: u16) -> Self { Self::new(account, 0, limit) }
+pub fn latest_max(account: Account) -> Self { Self::latest(account, LIMIT_MAX) }
+```
+
+### Error Handling
+Use `HiveError` enum for all client errors:
+- `RequestFail` - HTTP request failed
+- `ParseFail` - Response parsing failed
+- `HiveRejected` - Node returned an error
+- `HiveEmptyResponse` - Node returned empty result
+
+### Testing
+Tests connect to live Hive nodes (default: Deathwing):
+```rust
+#[tokio::test]
+async fn test_example() {
+    let client = HiveClient::new(HiveNodes::Deathwing);
+    let result = client.method().send(GetAccountCount::new()).await.unwrap();
+    assert!(result > 0);
+}
+```
+
+## CI/CD Notes
+
+No CI/CD pipeline configured. Standard Rust toolchain commands apply.
+
+## Known TODOs (from code comments)
+
+1. Extract utils into better structured folders
+2. Implement Display trait for utils
+3. Add high-level helpers for querying with limits
+4. Parse Asset from string (currently just a wrapper)
+5. Change EmptyParams from type alias to struct
-- 
GitLab