Add AI agent documentation and clean up dependencies by tonisefton · Pull Request #18 · WORK180/hubspot-api

tonisefton · 2026-04-13T03:20:03Z

Summary

Adds comprehensive documentation for AI agents (Copilot, Claude, etc.), audits and fixes all source doc comments, performs routine dependency maintenance, and adds an llms.txt for external LLM discoverability.

AI Agent Documentation

.github/copilot-instructions.md — Always-on Copilot workspace instructions: crate purpose, module map, key patterns, conventions, known issues
CLAUDE.md — Claude agent entry point with build/test commands and step-by-step extension guide
llms.txt — External LLM index (llmstxt.org standard) linking to crates.io, docs.rs, and all reference docs
docs/architecture.md — Contributor deep-dive: design goals, v3/v4 API endpoint breakdown per operation, core abstractions, HubSpot API reference links
docs/api.md — Consumer quick-start and full API reference (CRUD, batch, associations, engagements, owners, errors)
docs/modules/ — Per-module reference docs for objects, engagements, owners, api_configs, and client

Also corrects the .key() → .token() README mismatch throughout all new docs, and documents the v3/v4 mixed API versioning that was previously undocumented.

Doc Comment Audit

Reviewed all source files and fixed doc comments throughout the crate:

Promoted // regular comments to /// doc comments on 8 fields across owners.rs, builder.rs, api_configs/types.rs, and api_configs/associations.rs
Added missing doc comments to all public structs, enums, variants, and methods (ObjectType, EngagementType, NoteProperties, HubspotErrorContext, HubspotErrorResponse, AssociationsApiCollection, BatchApiCollection, PagingNext, and more)
Fixed inaccurate descriptions (Hubspot::builder(), HubspotBuilder)
cargo doc --no-deps passes with zero warnings

Dependencies

Remove unused async-trait dependency
Replace unmaintained dotenv dev-dep with dotenvy (maintained fork)
Bump strum/strum_macros 0.27 → 0.28

No version bump required — all changes are internal or dev-only.

This change is

…spot crate - Introduced `api.md` for consumer-facing API reference, detailing installation, authentication, client initialization, and usage examples for CRM objects, batch operations, associations, engagements, and error handling. - Created `architecture.md` to outline internal design goals, module dependency flow, core abstractions, and extension points for adding new CRM object types and engagement types. - Added `api_configs.md` to document the generic API infrastructure layer, including `ApiCollection`, `AssociationsApiCollection`, and `BatchApiCollection` functionalities. - Documented the `client` module, detailing the `HubspotClient`, its internal methods, and error handling mechanisms. - Established `engagements.md` to describe the `EngagementType`, `EngagementsManager`, and `NoteProperties` struct, along with examples for creating notes and managing associations. - Provided `objects.md` to explain the `ObjectType` enum and `ObjectsManager`, including methods for CRUD operations and dynamic object type resolution. - Added `owners.md` to outline the `Owner` and `Team` structs, along with the `OwnerApi` for fetching owner details by ID.

- Remove unused async-trait dependency - Replace unmaintained dotenv with dotenvy (maintained fork) in dev-deps - Bump strum/strum_macros from 0.27 to 0.28 reqwest 0.12 → 0.13 deferred (hyper 1.0 change, requires dedicated testing)

…d completeness

Copilot

Pull request overview

Adds AI-agent oriented documentation and expands crate documentation while doing a doc-comment audit and routine dependency cleanup.

Changes:

Adds new top-level and module-level documentation (CLAUDE.md, llms.txt, docs/*, .github/copilot-instructions.md) intended to guide contributors and AI agents.
Promotes/expands Rust doc comments across the public API surface (structs/enums/fields/methods).
Cleans up dependencies (remove unused async-trait, switch dotenv→dotenvy, bump strum).

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 26 comments.

Show a summary per file

File	Description
`src/owners.rs`	Converts field comments to Rustdoc for `Owner`.
`src/objects.rs`	Adds Rustdoc for `ObjectType` and `ObjectsManager::new()`.
`src/lib.rs`	Improves crate-level docs for `Hubspot` and `Hubspot::builder()`.
`src/engagements/notes.rs`	Adds Rustdoc for `NoteProperties` and constructor.
`src/engagements/mod.rs`	Adds Rustdoc for `EngagementType` and `EngagementsManager::new()`.
`src/client/error.rs`	Documents HubSpot structured error response types and fields.
`src/builder.rs`	Improves Rustdoc for `HubspotBuilder` and builder methods.
`src/api_configs/types.rs`	Adds Rustdoc for association/paging/links types.
`src/api_configs/mod.rs`	Documents `ApiCollection` sub-collections.
`src/api_configs/batch.rs`	Adds Rustdoc for `BatchApiCollection`.
`src/api_configs/associations.rs`	Adds Rustdoc for associations types/collection.
`llms.txt`	Adds `llms.txt` index for external LLM discoverability.
`docs/modules/owners.md`	Adds module reference documentation for owners.
`docs/modules/objects.md`	Adds module reference documentation for objects.
`docs/modules/engagements.md`	Adds module reference documentation for engagements/notes.
`docs/modules/client.md`	Adds module reference documentation for client/errors.
`docs/modules/api_configs.md`	Adds module reference documentation for generic API layer.
`docs/architecture.md`	Adds architecture deep-dive and extension guides.
`docs/api.md`	Adds consumer-facing API reference and examples.
`CLAUDE.md`	Adds Claude agent entry point: commands, module map, conventions.
`Cargo.toml`	Removes `async-trait`, bumps `strum`, switches dev-dep to `dotenvy`.
`.github/copilot-instructions.md`	Adds always-on Copilot workspace instructions and conventions.

Comments suppressed due to low confidence (2)

docs/modules/client.md:100

This section claims HubspotErrorResponse/HubspotErrorContext are not part of the public API and that only message is extracted, but in src/client/error.rs both structs are declared pub and From<HubspotErrorResponse> formats "{category}: {message}, {context:?}". Please update the wording/snippet to match the current visibility and formatting behavior.

## `HubspotErrorResponse` (internal)

Used to deserialize HubSpot's structured error JSON before converting to `HubspotError::Hubspot(message)`.

```rust
struct HubspotErrorResponse {
    pub message: String,
    pub context: HubspotErrorContext,
    pub category: String,
}

struct HubspotErrorContext {
    pub properties: Vec<String>,
}

These types are not part of the public API. When HubSpot returns a 4xx/5xx with a JSON body matching this shape, send() extracts message and returns HubspotError::Hubspot(message).

**src/lib.rs:38**
* Several new docs import `hubspot::client::error::HubspotError`, but `client` is a private module (`mod client;`). Consider re-exporting `HubspotError`/`HubspotResult` (and any other intended public types) from the crate root or making `client` a public module so the documented error-handling examples are actually usable by crate consumers.

/// An unofficial async Rust client for the HubSpot CRM API.
///
/// Construct via [Hubspot::builder()].
#[derive(Clone, Debug)]
pub struct Hubspot {
/// The HubSpot portal (account) ID.
pub portal_id: String,
/// Objects represent types of relationships or processes.
pub objects: ObjectsManager,
/// Engagements store data from interactions with records.
pub engagements: EngagementsManager,
/// Owners are specific users assigned to contacts, companies, deals, tickets, or engagements.
pub owners: OwnerApi,
}

</details>



---

💡 <a href="/WORK180/hubspot-api/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

- Fix ApiCollection::list() archived param: bool -> Option<bool> - Fix ApiCollection::update() signature: (id: &str, HubspotRecord) -> (id: String, properties: P) - Fix ApiCollection::archive() id type: &str -> String - Fix AssociationsApiCollection::list() signature: add limit/after params, to_object_type: &str not impl ToPath - Fix AssociationsApiCollection::create() signature: (to_object_type: O, to_object_id, Vec<AssociationCreationDetails>) - Fix BatchResult timestamps: Option<OffsetDateTime> -> String (raw API strings) - Fix AssociationLinks enum: remove incorrect integer discriminants, add build() method note - Fix HubspotRecord: remove broken code snippet fragment, add proper struct definition - Fix ObjectApi::name() return type: &str -> &T - Remove entire duplicate second copy of all sections (297 lines)

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 9 comments.

Comments suppressed due to low confidence (1)

docs/modules/client.md:96

The description of HubspotErrorResponse conversion says send() extracts message and returns HubspotError::Hubspot(message), but HubspotErrorResponse is converted via From<HubspotErrorResponse> which formats category, message, and context. Please align this explanation with the actual conversion.

## `HubspotErrorResponse` (internal)

Used to deserialize HubSpot's structured error JSON before converting to `HubspotError::Hubspot(message)`.

```rust
struct HubspotErrorResponse {
    pub message: String,
    pub context: HubspotErrorContext,
    pub category: String,
}

struct HubspotErrorContext {
    pub properties: Vec<String>,
}

These types are not part of the public API. When HubSpot returns a 4xx/5xx with a JSON body matching this shape, send() extracts message and returns HubspotError::Hubspot(message).

</details>



---

💡 <a href="/WORK180/hubspot-api/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

Copilot · 2026-04-13T04:19:45Z

+### `AssociationLinks` — Hardcoded Built-in Type IDs
+
+HubSpot assigns numeric IDs to standard ("built-in") association types. These are encoded in the `AssociationLinks` enum to eliminate magic numbers in calling code:
+
+```rust
+pub enum AssociationLinks {
+    NoteToContact = 202,
+    NoteToCompany = 190,
+    NoteToDeal    = 214,
+}
+```


This section shows AssociationLinks variants with numeric discriminants, but in code (src/api_configs/types.rs) the IDs are produced via AssociationLinks::build() (the enum has no discriminants). The example should be updated to reflect the actual representation to avoid incorrect extension guidance.

Copilot · 2026-04-13T04:19:45Z

+| Variant | When it occurs |
+|---|---|
+| `Json(serde_json::Error)` | The response body could not be deserialized into the expected type |
+| `Http(reqwest::Error)` | Network failure, connection timeout, or non-success HTTP status from `reqwest` |
+| `Hubspot(String)` | HubSpot returned a structured error response; the `message` field is extracted and stored |
+


This table/section implies HubspotError::Hubspot stores only the API message, but From<HubspotErrorResponse> formats category, message, and context into the string. The docs should reflect that the stored string includes more than just message (or adjust the conversion if the intent is message-only).

- docs/modules/owners.md: fix OwnerApi::read archived param bool -> Option<bool> - docs/modules/client.md: begin() does not pre-apply auth (auth is in send()); fix HubspotErrorResponse conversion format (category: message, context) not just message; fix struct visibility (pub not private) - docs/modules/engagements.md: fix associations.create example — to_object_id is a separate arg; AssociationCreationDetails uses category/type_id fields not association_type - docs/architecture.md: remove AssociationLinks integer discriminants (plain enum + build()); fix begin() description to note auth is in send(); update new association type guidance to reference build() method - CLAUDE.md: fix AssociationLinks bullets to show plain variants with build() IDs; fix ObjectApi::name return type &str -> &T

chanelmoreno

I don't think I've seen this repo before! The docs look aligned to the other repos docs though so

@chanelmoreno made 1 comment.
Reviewable status: 0 of 22 files reviewed, 17 unresolved discussions (waiting on robmarto and tonisefton).

chanelmoreno

@chanelmoreno made 1 comment.
Reviewable status: 0 of 22 files reviewed, 17 unresolved discussions (waiting on robmarto and tonisefton).

robmarto

@robmarto made 1 comment.
Reviewable status: 0 of 22 files reviewed, 18 unresolved discussions (waiting on tonisefton).

.github/copilot-instructions.md line 1 at r3 (raw file):

# Copilot Workspace Instructions — hubspot-api

this should be the same as the CLAUDE.md file as they are both entry points for different tools. claude.md is for ClaudeCode and this is for Github Copilot.
I think its fine to just have copilot instructions reference the claude md file.

… description

tonisefton

@tonisefton made 1 comment and resolved 10 discussions.
Reviewable status: 0 of 22 files reviewed, 1 unresolved discussion (waiting on robmarto).

.github/copilot-instructions.md line 1 at r3 (raw file):

Previously, robmarto (Rob Martin) wrote…

this should be the same as the CLAUDE.md file as they are both entry points for different tools. claude.md is for ClaudeCode and this is for Github Copilot.
I think its fine to just have copilot instructions reference the claude md file.

Done.

robmarto

@robmarto made 1 comment and resolved 1 discussion.
Reviewable status: 0 of 22 files reviewed, all discussions resolved.

tonisefton added 4 commits April 13, 2026 13:11

chore(deps): update and clean up dependencies

08a4522

- Remove unused async-trait dependency - Replace unmaintained dotenv with dotenvy (maintained fork) in dev-deps - Bump strum/strum_macros from 0.27 to 0.28 reqwest 0.12 → 0.13 deferred (hyper 1.0 change, requires dedicated testing)

feat: add initial documentation for hubspot async Rust client library

9b9f92a

docs: enhance API documentation across various modules for clarity an…

33c419e

…d completeness

tonisefton requested review from chanelmoreno, Copilot and robmarto and removed request for robmarto April 13, 2026 03:29

Copilot started reviewing on behalf of tonisefton April 13, 2026 03:30 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

tonisefton and others added 3 commits April 13, 2026 13:44

Apply suggestions from code review

4dd388a

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix: address CI review comments on PR 18

158d21b

tonisefton requested a review from Copilot April 13, 2026 04:15

Copilot started reviewing on behalf of tonisefton April 13, 2026 04:16 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

chanelmoreno reviewed Apr 13, 2026

View reviewed changes

chanelmoreno previously approved these changes Apr 13, 2026

View reviewed changes

robmarto requested changes Apr 14, 2026

View reviewed changes

tonisefton added 2 commits April 14, 2026 12:31

docs: correct typo in package description

71834ac

docs: update Copilot instructions and clarify OptionNotDesired struct…

ca2d79b

… description

tonisefton dismissed chanelmoreno’s stale review via ca2d79b April 14, 2026 03:07

tonisefton commented Apr 14, 2026

View reviewed changes

robmarto approved these changes Apr 14, 2026

View reviewed changes

tonisefton merged commit 8fe1135 into main Apr 15, 2026
4 of 5 checks passed

tonisefton deleted the updates-and-AI-documentation branch April 15, 2026 00:02

Conversation

tonisefton commented Apr 13, 2026 • edited by robmarto Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

AI Agent Documentation

Doc Comment Audit

Dependencies

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chanelmoreno left a comment

Choose a reason for hiding this comment

Uh oh!

chanelmoreno left a comment

Choose a reason for hiding this comment

Uh oh!

robmarto left a comment

Choose a reason for hiding this comment

Uh oh!

tonisefton left a comment

Choose a reason for hiding this comment

Uh oh!

robmarto left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tonisefton commented Apr 13, 2026 •

edited by robmarto

Loading