feat: Add stores.plugins.list API

[chyroc]

Summary by CodeRabbit

• New Features
  • Added Stores functionality to the API client for accessing and browsing available store plugins.
  • Introduced comprehensive plugin listing capabilities with full pagination support.
  • Enabled filtering, sorting, and search functionality for discovering store plugins that meet your needs.
  • Added example CLI tool demonstrating practical usage of the store plugins API.

[coderabbitai]

Walkthrough

The changes extend the CozeAPI client with a new Stores subsystem that provides store plugin listing capabilities. A new stores.go file introduces the stores structure with plugin support, stores_plugins.go implements plugin discovery with pagination, client.go exposes the Stores field, and an example demonstrates the API usage.

Changes

Cohort / File(s)	Summary
Client Integration client.go	Adds public Stores field of type \*stores to CozeAPI struct, initialized via newStores(core) in NewCozeAPI constructor.
Stores Infrastructure stores.go	Introduces unexported stores struct with core and Plugins fields. Adds newStores constructor that initializes both fields.
Plugin Listing Implementation stores_plugins.go	Implements plugin discovery with pagination. Defines ProductPlugin, ProductMetaInfo, ProductPluginInfo, ProductCategory data models. Adds ListStoresPluginsReq/Resp structures for API requests and responses. Implements List method with pagination support (default PageSize 20, PageNum 1) against GET /v1/stores/plugins endpoint.
Example Usage examples/stores/plugins/list/main.go	Adds CLI example demonstrating token-based authentication, ListStoresPlugins request with PageSize 20, and pagination iteration printing plugin EntityID and Name.

Sequence Diagram

sequenceDiagram
    participant Client
    participant CozeAPI
    participant StoresPlugins
    participant API

    Client->>CozeAPI: NewCozeAPI(token)
    CozeAPI->>CozeAPI: newStores(core)
    CozeAPI-->>Client: initialized client

    Client->>StoresPlugins: ListStoresPlugins(req)
    StoresPlugins->>API: GET /v1/stores/plugins
    API-->>StoresPlugins: paginated response<br/>(Items[], HasMore)
    
    rect rgba(100, 150, 200, 0.1)
        Note over Client,StoresPlugins: Pagination Loop
        loop For each page
            Client->>StoresPlugins: listResp.Next()
            StoresPlugins->>StoresPlugins: toReq(page)
            StoresPlugins->>API: GET /v1/stores/plugins
            API-->>StoresPlugins: next page
            Client->>StoresPlugins: listResp.Current()
            StoresPlugins-->>Client: ProductPlugin[]
        end
    end
    
    StoresPlugins-->>Client: final response + error (if any)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–25 minutes

• stores_plugins.go requires careful review of multiple new data structures (ProductPlugin, ProductMetaInfo, ProductPluginInfo, ProductCategory) and pagination logic consistency with framework patterns
• Verify pagination defaults (PageSize 20, PageNum 1) align with API specification and framework conventions
• Confirm API endpoint path (/v1/stores/plugins) and request/response mapping are correct
• Validate error handling in the List method and iterator pattern implementation

Poem

🐰 A warren of stores now opens its door,
With plugins to list and explore!
Through pages we hop, no stopping our pop,
Each plugin we find makes our spirits soar!
🎉✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "feat: Add stores.plugins.list API" directly and accurately describes the main change across all modified files. The changeset adds a complete feature for listing store plugins with pagination support, including API client integration, data models, request/response structures, and a CLI example. The title is concise, uses standard semantic versioning conventions, and is specific enough to convey the primary change without vagueness or noise.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch stores-plugins-list

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b3f1989 and fcc5dc8.

📒 Files selected for processing (4)

• client.go (2 hunks)
• examples/stores/plugins/list/main.go (1 hunks)
• stores.go (1 hunks)
• stores_plugins.go (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

examples/stores/plugins/list/main.go (4)

const.go (1)

• CnBaseURL (5-5)

auth_token.go (1)

• NewTokenAuth (23-27)

client.go (2)

• NewCozeAPI (80-119)
• WithBaseURL (41-45)

stores_plugins.go (1)

• ListStoresPluginsReq (72-79)

stores_plugins.go (4)

client.go (1)

• CozeAPIOption (38-38)

pagination.go (2)

• NumberPaged (12-15)
• NewNumberPaged (77-95)

request.go (1)

• RawRequestReq (27-35)

base_model.go (1)

• HTTPResponse (9-11)

🔇 Additional comments (7)

client.go (1)

24-24: LGTM! Consistent integration of the Stores subsystem.

The new Stores field and its initialization follow the established pattern used by all other subsystems in the codebase.

Also applies to: 115-115

stores.go (1)

1-10: LGTM! Clean subsystem structure.

The stores struct and constructor follow the established patterns in the codebase, with proper initialization of the Plugins field.

examples/stores/plugins/list/main.go (2)

13-22: LGTM! Proper client initialization.

The example correctly demonstrates environment-based configuration with sensible defaults and proper client initialization.

---

24-30: LGTM! Clear API usage demonstration.

The example properly demonstrates the pagination API with appropriate page size and error handling.

stores_plugins.go (3)

35-70: LGTM! Well-structured data models.

The data models are cleanly organized with appropriate types, JSON tags, and comprehensive documentation in Chinese comments. The embedding of baseModel follows the established pattern.

---

72-100: LGTM! Well-designed request/response structures.

The request and response types are properly structured with appropriate tags and field mappings. The toReq helper correctly merges pagination parameters while preserving filter criteria.

---

102-108: LGTM! Standard constructor pattern.

The storesPlugins type and constructor follow the established patterns in the codebase.