/widgets endpoint (#783)

* Add an initial CLAUDE.md file

* Implement `/widgets` endpoint partially generated (incorrectly) by Claude

* Ask Claude to update widgets implementation using API reference (and manually fix some issues)

* Add widgets to api client

* Generate widgets immut tests by Claude (not tested yet)

* Update widgets immutable tests to get them to pass

* Implement create `/widgets` integration tests

* Implement delete `/widgets` integration test, remove trash action

* Implement update `/widgets` integration tests

* Implement `/widgets` error handling integration tests

* Remove `create_widget_with_encoded` test

Author: oguzkocer

CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Rust implementation of the WordPress REST API client library with cross-platform bindings for iOS, Android, and other platforms. The project uses a workspace structure with multiple crates providing modular functionality.
+
+## Build Commands
+
+```bash
+# Start WordPress test instance
+make test-server
+
+# Run unit tests
+cargo test --lib
+
+# Run integration tests
+cargo test -p wp_api_integration_tests
+
+# Run integration tests for a specific file
+cargo test -p wp_api_integration_tests --test '{file_name}'
+
+# Run linting and format checks
+cargo fmt --all -- --check
+cargo clippy --tests --all-targets --all-features -- -D warnings
+
+# Generate API documentation
+cargo doc --no-deps --all-features
+```
+
+## Architecture
+
+### Workspace Structure
+- `wp_api/` - Core REST API implementation
+- `wp_api_integration_tests/` - Integration tests requiring Dockerized WordPress instance
+- `wp_contextual/` - Procedural macro for context-aware types
+- `wp_serde/` - Custom serialization helpers
+- `uniffi-bindgen/` - Cross-platform binding generator
+- `kotlin/` - Kotlin/Android wrapper for generated bindings
+- `native/apple/` - Swift/iOS wrapper for generated bindings
+
+### Testing
+
+Tests require a WordPress instance. Use Docker:
+```bash
+# Start test server (keep running)
+make test-server
+
+# Run the integration tests
+cargo test -p wp_api_integration_tests
+```
+
+Test credentials are configured in:
+- `wp_api_integration_tests/tests/test_credentials.json` (WordPress.org)
+- `wp_api_integration_tests/tests/wp_com_test_credentials.json` (WordPress.com)
+
+### Common Development Tasks
+
+1. **Adding new types that uses WordPress REST API endpoint**:
+   - The API returns different fields depending on the `context` parameter which can be `edit`, `embed` or `view` and defaults to `view`. To support this, we use the `wp_contextual::WpContextual` derive macro and add `#[WpContext(edit, embed, view)]` attribute to each field, using the available contexts.
+   - Each contextual type's name has to start with `Sparse` prefix and all of its fields has to be `Option<T>`. `wp_contextual::WpContextual` derive macro will generate new types from it with the `WithEditContext`, `WithEmbedContext` & `WithViewContext` suffices. These new types will not use `Option<T>` for its fields unless a field in the original `Sparse` type is marked with `#[WpContextualOption]` attribute.
+   - Most types should have the following derive macros `#[derive(Debug, serde::Serialize, serde::Deserialize, uniffi::Record)]`.
+   - To implement new types, use `wp_api/src/posts.rs` as a reference and follow the same style
+   - For a new endpoint, a set of JSONs should be provided to you for each context type, so you can compare them and figure out which field is returned for which contexts.
+
+2. **Error handling for an endpoint**:
+   - The server will return a `crate::WpErrorCode` instance for most error types.
+   - While implementing the errors for a new endpoint, if it's missing from the `crate::WpErrorCode` variants, it needs to be added there. If you need to do this, please add the new variants to the very top of the type and add a comment on top with `// Needs Triage`.
+   - Integration tests for error cases go into `wp_api_integration_tests/tests/test_{endpoint_name}_err.rs` file.
+   - The implementation should follow a similar approach to `wp_api_integration_tests/tests/test_users_err.rs`.
+   - There are several `api_client` helper functions available. The default `api_client` function is authenticated with an admin users. This should be the preferred client if creating the error case doesn't require an inauthenticated or a separate user. There is also `api_client_as_subscriber` function that is authenticated with a subscriber user. Most authentication error types can be triggered using this client type. Another possibility is `api_client_with_auth_provider(WpAuthenticationProvider::none().into())` which doesn't have any authentication headers, so it's useful in specific cases.
+   - Implementing these tests can be difficult without having a full understanding of how to trigger them. So, if you are not sure how to implement it, generate a test function following existing patterns, but leave the implementation empty. Instead, add a comment about what you can find from the implementation related to how one might be able to trigger this error.
+   - The existing tests don't have much documentation, because the test implementation can act as one. However, when you are implementing the test, please add a documentation. This is because we need some context about why you implemented a test in a specific way. If you include a documentation, we can check if what you are trying to do is correct, before reviewing the implementation.
+
+## Important Files
+
+- `Makefile` - Build automation and platform-specific targets
+- `wp_api/src/lib.rs` - Main library entry point
+- `wp_api/src/request.rs` - Core request/response handling
+- `wp_api/src/wp_error.rs` - Error types and handling
+
+## Development Tips
+
+- Platform bindings are generated automatically - don't edit generated files directly

api.sh

@@ -7,4 +7,4 @@ fi
 
 ADMIN_TOKEN=$(jq .admin_password test_credentials.json)
 
-curl --user [email protected]:"$ADMIN_TOKEN" "http://localhost/wp-json$1"
+curl --silent --user [email protected]:"$ADMIN_TOKEN" "http://localhost/wp-json$1" | jq .

wp_api/src/api_client.rs

@@ -24,6 +24,7 @@ use crate::{
             templates_endpoint::{TemplatesRequestBuilder, TemplatesRequestExecutor},
             themes_endpoint::{ThemesRequestBuilder, ThemesRequestExecutor},
             users_endpoint::{UsersRequestBuilder, UsersRequestExecutor},
+            widgets_endpoint::{WidgetsRequestBuilder, WidgetsRequestExecutor},
             wp_site_health_tests_endpoint::{
                 WpSiteHealthTestsRequestBuilder, WpSiteHealthTestsRequestExecutor,
             },
@@ -66,6 +67,7 @@ pub struct WpApiRequestBuilder {
     templates: Arc<TemplatesRequestBuilder>,
     themes: Arc<ThemesRequestBuilder>,
     users: Arc<UsersRequestBuilder>,
+    widgets: Arc<WidgetsRequestBuilder>,
     wp_site_health_tests: Arc<WpSiteHealthTestsRequestBuilder>,
 }
 
@@ -92,6 +94,7 @@ impl WpApiRequestBuilder {
             templates,
             themes,
             users,
+            widgets,
             wp_site_health_tests
         )
     }
@@ -128,6 +131,7 @@ pub struct WpApiClient {
     templates: Arc<TemplatesRequestExecutor>,
     themes: Arc<ThemesRequestExecutor>,
     users: Arc<UsersRequestExecutor>,
+    widgets: Arc<WidgetsRequestExecutor>,
     wp_site_health_tests: Arc<WpSiteHealthTestsRequestExecutor>,
 }
 
@@ -151,6 +155,7 @@ impl WpApiClient {
             templates,
             themes,
             users,
+            widgets,
             wp_site_health_tests
         )
     }
@@ -184,6 +189,7 @@ api_client_generate_endpoint_impl!(WpApi, taxonomies);
 api_client_generate_endpoint_impl!(WpApi, templates);
 api_client_generate_endpoint_impl!(WpApi, themes);
 api_client_generate_endpoint_impl!(WpApi, users);
+api_client_generate_endpoint_impl!(WpApi, widgets);
 api_client_generate_endpoint_impl!(WpApi, wp_site_health_tests);
 
 #[macro_export]

wp_api/src/api_error.rs

@@ -196,6 +196,8 @@ pub enum WpErrorCode {
     CannotManagePlugins,
     #[serde(rename = "rest_cannot_manage_templates")]
     CannotManageTemplates,
+    #[serde(rename = "rest_cannot_manage_widgets")]
+    CannotManageWidgets,
     #[serde(rename = "rest_cannot_read_application_password")]
     CannotReadApplicationPassword,
     #[serde(rename = "rest_cannot_read")]
@@ -264,6 +266,8 @@ pub enum WpErrorCode {
     InvalidParam,
     #[serde(rename = "rest_invalid_template")]
     InvalidTemplate,
+    #[serde(rename = "rest_invalid_widget")]
+    InvalidWidget,
     #[serde(rename = "rest_no_search_term_defined")]
     NoSearchTermDefined,
     #[serde(rename = "rest_orderby_include_missing_include")]
@@ -308,6 +312,8 @@ pub enum WpErrorCode {
     UserInvalidRole,
     #[serde(rename = "rest_user_invalid_slug")]
     UserInvalidSlug,
+    #[serde(rename = "rest_widget_not_found")]
+    WidgetNotFound,
     // ------------------------------------------------------------------------------------
     // Untested, because we are unable to create the necessary conditions for them
     // ------------------------------------------------------------------------------------

wp_api/src/lib.rs

@@ -35,6 +35,8 @@ pub mod themes;
 pub mod url_query;
 pub mod users;
 pub mod uuid;
+pub mod widget_types;
+pub mod widgets;
 pub mod wordpress_org;
 pub mod wp_site_health_tests;
 
@@ -104,7 +106,7 @@ pub enum EnumFromStrParsingError {
     UnknownVariant { value: String },
 }
 
-#[derive(Debug, Serialize, Deserialize, uniffi::Enum)]
+#[derive(Debug, PartialEq, Serialize, Deserialize, uniffi::Enum)]
 #[serde(untagged)]
 pub enum JsonValue {
     Null,

wp_api/src/request/endpoint.rs

@@ -18,6 +18,7 @@ pub mod taxonomies_endpoint;
 pub mod templates_endpoint;
 pub mod themes_endpoint;
 pub mod users_endpoint;
+pub mod widgets_endpoint;
 pub mod wp_site_health_tests_endpoint;
 
 pub const WP_JSON_PATH_SEGMENTS: [&str; 1] = ["wp-json"];

wp_api/src/request/endpoint/widgets_endpoint.rs

@@ -0,0 +1,46 @@
+use super::{AsNamespace, DerivedRequest, WpNamespace};
+use crate::{
+    SparseField,
+    widgets::{
+        SparseWidgetFieldWithEditContext, SparseWidgetFieldWithEmbedContext,
+        SparseWidgetFieldWithViewContext, WidgetId, WidgetListParams, WidgetWithEditContext,
+    },
+};
+use wp_derive_request_builder::WpDerivedRequest;
+
+#[derive(WpDerivedRequest)]
+enum WidgetsRequest {
+    #[contextual_paged(url = "/widgets", params = &WidgetListParams, output = Vec<crate::widgets::SparseWidget>, filter_by = crate::widgets::SparseWidgetField)]
+    List,
+    #[contextual_get(url = "/widgets/<widget_id>", output = crate::widgets::SparseWidget, filter_by = crate::widgets::SparseWidgetField)]
+    Retrieve,
+    #[post(url = "/widgets", params = &crate::widgets::WidgetCreateParams, output = WidgetWithEditContext)]
+    Create,
+    #[post(url = "/widgets/<widget_id>", params = &crate::widgets::WidgetUpdateParams, output = WidgetWithEditContext)]
+    Update,
+    #[delete(url = "/widgets/<widget_id>", output = crate::widgets::WidgetDeleteResponse)]
+    Delete,
+}
+
+impl DerivedRequest for WidgetsRequest {
+    fn additional_query_pairs(&self) -> Vec<(&str, String)> {
+        match &self {
+            Self::Delete => vec![("force", true.to_string())],
+            _ => vec![],
+        }
+    }
+
+    fn namespace() -> impl AsNamespace {
+        WpNamespace::WpV2
+    }
+}
+
+super::macros::default_sparse_field_implementation_from_field_name!(
+    SparseWidgetFieldWithEditContext
+);
+super::macros::default_sparse_field_implementation_from_field_name!(
+    SparseWidgetFieldWithEmbedContext
+);
+super::macros::default_sparse_field_implementation_from_field_name!(
+    SparseWidgetFieldWithViewContext
+);

wp_api/src/widget_types.rs

@@ -0,0 +1,12 @@
+use serde::{Deserialize, Serialize};
+use std::fmt::Display;
+
+uniffi::custom_newtype!(WidgetTypeId, String);
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct WidgetTypeId(pub String);
+
+impl Display for WidgetTypeId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}

wp_api/src/widgets.rs

@@ -0,0 +1,113 @@
+use crate::JsonValue;
+use crate::url_query::{
+    AppendUrlQueryPairs, FromUrlQueryPairs, QueryPairs, QueryPairsExtension, UrlQueryPairsMap,
+};
+use crate::widget_types::WidgetTypeId;
+use serde::{Deserialize, Serialize};
+use std::{collections::HashMap, fmt::Display};
+use strum_macros::IntoStaticStr;
+use wp_contextual::WpContextual;
+
+uniffi::custom_newtype!(WidgetId, String);
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct WidgetId(pub String);
+
+impl Display for WidgetId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+#[derive(Debug, Serialize, Deserialize, uniffi::Record, WpContextual)]
+pub struct SparseWidget {
+    #[WpContext(edit, embed, view)]
+    pub id: Option<WidgetId>,
+    #[WpContext(edit, embed, view)]
+    pub id_base: Option<WidgetTypeId>,
+    #[WpContext(edit, embed, view)]
+    pub sidebar: Option<String>,
+    #[WpContext(edit, embed, view)]
+    pub rendered: Option<String>,
+    #[WpContext(edit)]
+    pub rendered_form: Option<String>,
+    #[WpContext(edit)]
+    pub instance: Option<WidgetInstance>,
+    #[WpContext(edit)]
+    #[WpContextualOption]
+    pub form_data: Option<String>,
+}
+
+#[derive(Debug, Serialize, Deserialize, uniffi::Record)]
+pub struct WidgetInstance {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub encoded: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub hash: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub raw: Option<HashMap<String, JsonValue>>,
+}
+
+#[derive(Debug, Clone, Default, uniffi::Record)]
+pub struct WidgetListParams {
+    pub sidebar: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, IntoStaticStr)]
+enum WidgetListParamsField {
+    #[strum(serialize = "sidebar")]
+    Sidebar,
+}
+
+impl AppendUrlQueryPairs for WidgetListParams {
+    fn append_query_pairs(&self, query_pairs_mut: &mut QueryPairs) {
+        query_pairs_mut
+            .append_option_query_value_pair(WidgetListParamsField::Sidebar, self.sidebar.as_ref());
+    }
+}
+impl FromUrlQueryPairs for WidgetListParams {
+    fn from_url_query_pairs(query_pairs: UrlQueryPairsMap) -> Option<Self> {
+        Some(Self {
+            sidebar: query_pairs.get(WidgetListParamsField::Sidebar),
+        })
+    }
+
+    fn supports_pagination() -> bool {
+        false
+    }
+}
+
+#[derive(Debug, Serialize, Deserialize, uniffi::Record)]
+pub struct WidgetCreateParams {
+    pub id_base: WidgetTypeId,
+    pub sidebar: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub instance: Option<WidgetInstanceParams>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub form_data: Option<String>,
+}
+
+#[derive(Debug, Serialize, Deserialize, uniffi::Enum)]
+#[serde(untagged)]
+pub enum WidgetInstanceParams {
+    Raw { raw: HashMap<String, JsonValue> },
+    Encoded { encoded: String, hash: String },
+}
+
+#[derive(Debug, Default, Serialize, uniffi::Record)]
+pub struct WidgetUpdateParams {
+    // Updating widget type's with `id_base` is not supported by the backend even though the field
+    // is listed in the documentation: https://developer.wordpress.org/rest-api/reference/widgets/#update-a-widget
+    // The field is omitted from the type to avoid confusion.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sidebar: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub instance: Option<WidgetInstanceParams>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub form_data: Option<String>,
+}
+
+#[derive(Debug, Serialize, Deserialize, uniffi::Record)]
+pub struct WidgetDeleteResponse {
+    pub deleted: bool,
+    pub previous: WidgetWithEditContext,
+}

wp_api_integration_tests/src/lib.rs

@@ -79,6 +79,9 @@ pub const POST_TEMPLATE_SINGLE_WITH_SIDEBAR: &str = "single-with-sidebar";
 pub const THEME_TWENTY_TWENTY_FIVE: &str = "twentytwentyfive";
 pub const THEME_TWENTY_TWENTY_FOUR: &str = "twentytwentyfour";
 pub const THEME_TWENTY_TWENTY_THREE: &str = "twentytwentythree";
+pub const WIDGET_ID_BLOCK_2: &str = "block-2";
+pub const WIDGET_INACTIVE_WIDGETS_SIDEBAR: &str = "wp_inactive_widgets";
+pub const WIDGET_TYPE_TEXT: &str = "text";
 
 pub fn api_client() -> WpApiClient {
     WpApiClient::new(