Add Analytics API (#68)

* fetch & codegen

* fix extra lifetime error

* fix: use `oneOf` instead of `anyOf`

* feat: analytics API

* fix incorrect typesense options passed

* feat: analytics events retrieve

Author: haydenhoang

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
           ]
     services:
       typesense:
-        image: typesense/typesense:30.0.rc26
+        image: typesense/typesense:30.0.rca33
         ports:
           - 8108:8108/tcp
         volumes:
@@ -35,6 +35,8 @@ jobs:
           TYPESENSE_API_KEY: 'xyz'
           TYPESENSE_ENABLE_CORS: true
           TYPESENSE_URL: 'http://localhost:8108'
+          TYPESENSE_ENABLE_SEARCH_ANALYTICS: 'true'
+          TYPESENSE_ANALYTICS_DIR: '/analytics-data'
     steps:
       - uses: actions/checkout@v4
       - name: Cache .cargo and target

compose.yml

@@ -1,9 +1,9 @@
 services:
   typesense:
-    image: typesense/typesense:30.0.rc26
+    image: typesense/typesense:30.0.rca33
     restart: on-failure
     ports:
       - '8108:8108'
     volumes:
       - ./typesense-data:/data
-    command: '--data-dir /data --api-key=xyz --enable-cors'
+    command: '--data-dir /data --api-key=xyz --enable-cors --enable-search-analytics=true --analytics-dir=/analytics-data'

openapi.yml

@@ -502,7 +502,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ApiResponse"
-    
+
     put:
       tags:
         - synonyms
@@ -650,7 +650,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/SynonymItemSchema"
+              $ref: "#/components/schemas/SynonymItemUpsertSchema"
         required: true
       responses:
         "200":
@@ -1647,7 +1647,7 @@ paths:
                 {"log-slow-requests-time-ms": 2000}
       responses:
         '200':
-          description: Compacting the on-disk database succeeded.
+          description: Toggle Slow Request Log database succeeded.
           content:
             application/json:
               schema:
@@ -1805,7 +1805,7 @@ paths:
                   - $ref: "#/components/schemas/AnalyticsRule"
                   - type: array
                     items:
-                      anyOf:
+                      oneOf:
                         - $ref: "#/components/schemas/AnalyticsRule"
                         - type: object
                           properties:
@@ -3975,8 +3975,7 @@ components:
         name:
           type: string
         type:
-          type: string
-          enum: [popular_queries, nohits_queries, counter, log]
+          $ref: "#/components/schemas/AnalyticsRuleType"
         collection:
           type: string
         event_type:
@@ -4001,6 +4000,9 @@ components:
               type: string
             weight:
               type: integer
+    AnalyticsRuleType:
+      type: string
+      enum: [popular_queries, nohits_queries, counter, log]
     AnalyticsRuleUpdate:
       type: object
       description: Fields allowed to update on an analytics rule
@@ -4041,7 +4043,7 @@ components:
         query_counter_events: { type: integer }
         doc_log_events: { type: integer }
         doc_counter_events: { type: integer }
-    
+
     APIStatsResponse:
       type: object
       properties:
@@ -4364,15 +4366,11 @@ components:
           type: string
           description: ID of the deleted NL search model
 
-    SynonymItemSchema:
+    SynonymItemUpsertSchema:
       type: object
       required:
-        - id
         - synonyms
       properties:
-        id:
-          type: string
-          description: Unique identifier for the synonym item
         synonyms:
           type: array
           description: Array of words that should be considered as synonyms
@@ -4390,6 +4388,17 @@ components:
           items:
             type: string
 
+    SynonymItemSchema:
+      allOf:
+        - type: object
+          required:
+            - id
+          properties:
+            id:
+              type: string
+              description: Unique identifier for the synonym item
+        - $ref: "#/components/schemas/SynonymItemUpsertSchema"
+
     SynonymSetCreateSchema:
       type: object
       required:

preprocessed_openapi.yml

@@ -1036,7 +1036,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/SynonymItemSchema'
+              $ref: '#/components/schemas/SynonymItemUpsertSchema'
       responses:
         '200':
           description: Synonym item successfully created/updated
@@ -2003,7 +2003,7 @@ paths:
               x-rust-has-borrowed-data: true
       responses:
         '200':
-          description: Compacting the on-disk database succeeded.
+          description: Toggle Slow Request Log database succeeded.
           content:
             application/json:
               schema:
@@ -2528,7 +2528,7 @@ paths:
                 - $ref: '#/components/schemas/AnalyticsRule'
                 - type: array
                   items:
-                    anyOf:
+                    oneOf:
                     - $ref: '#/components/schemas/AnalyticsRule'
                     - type: object
                       properties:
@@ -4441,12 +4441,7 @@ components:
         name:
           type: string
         type:
-          type: string
-          enum:
-          - popular_queries
-          - nohits_queries
-          - counter
-          - log
+          $ref: '#/components/schemas/AnalyticsRuleType'
         collection:
           type: string
         event_type:
@@ -4474,6 +4469,13 @@ components:
               type: integer
           x-rust-has-borrowed-data: true
       x-rust-has-borrowed-data: true
+    AnalyticsRuleType:
+      type: string
+      enum:
+      - popular_queries
+      - nohits_queries
+      - counter
+      - log
     AnalyticsRuleUpdate:
       type: object
       description: Fields allowed to update on an analytics rule
@@ -4859,15 +4861,11 @@ components:
         id:
           type: string
           description: ID of the deleted NL search model
-    SynonymItemSchema:
+    SynonymItemUpsertSchema:
       type: object
       required:
-      - id
       - synonyms
       properties:
-        id:
-          type: string
-          description: Unique identifier for the synonym item
         synonyms:
           type: array
           description: Array of words that should be considered as synonyms
@@ -4885,6 +4883,16 @@ components:
           items:
             type: string
       x-rust-has-borrowed-data: true
+    SynonymItemSchema:
+      allOf:
+      - type: object
+        required:
+        - id
+        properties:
+          id:
+            type: string
+            description: Unique identifier for the synonym item
+      - $ref: '#/components/schemas/SynonymItemUpsertSchema'
     SynonymSetCreateSchema:
       type: object
       required:

typesense/src/client/analytics/events.rs

@@ -0,0 +1,48 @@
+//! Provides access to the API endpoint for posting analytics events.
+//!
+//! An `Events` instance is created via the `client.analytics().events()` method.
+
+use crate::{Client, Error, execute_wrapper, models};
+use typesense_codegen::apis::analytics_api;
+
+/// Provides methods for interacting with analytics events.
+///
+/// This struct is created by calling `client.analytics().events()`.
+pub struct Events<'a> {
+    pub(super) client: &'a Client,
+}
+
+impl<'a> Events<'a> {
+    /// Creates a new `Events` instance.
+    #[inline]
+    pub(super) fn new(client: &'a Client) -> Self {
+        Self { client }
+    }
+
+    /// Posts an analytics event for tracking user behavior.
+    ///
+    /// # Arguments
+    /// * `schema` - An `AnalyticsEvent` object representing the event.
+    pub async fn create(
+        &self,
+        schema: models::AnalyticsEvent<'_>,
+    ) -> Result<models::AnalyticsEventCreateResponse, Error<analytics_api::CreateAnalyticsEventError>>
+    {
+        let params = analytics_api::CreateAnalyticsEventParams {
+            analytics_event: schema,
+        };
+        execute_wrapper!(self, analytics_api::create_analytics_event, params)
+    }
+
+    /// Retrieve the most recent analytics events for a specific user and analytics rule name.
+    ///
+    /// # Arguments
+    /// * `params` - `GetAnalyticsEventsParams`.
+    pub async fn retrieve(
+        &self,
+        params: models::GetAnalyticsEventsParams<'_>,
+    ) -> Result<models::AnalyticsEventsResponse, Error<analytics_api::GetAnalyticsEventsError>>
+    {
+        execute_wrapper!(self, analytics_api::get_analytics_events, params)
+    }
+}

typesense/src/client/analytics/mod.rs

@@ -0,0 +1,46 @@
+//! Provides access to the analytics API endpoints for managing rules and posting events.
+//!
+//! An `Analytics` instance is created via the main `client.analytics()` method.
+mod events;
+mod rule;
+mod rules;
+use crate::Client;
+use events::Events;
+use rule::Rule;
+use rules::Rules;
+
+/// Provides methods for interacting with Typesense analytics rules and events.
+///
+/// This struct is created by calling `client.analytics()`.
+pub struct Analytics<'a> {
+    pub(super) client: &'a Client,
+}
+
+impl<'a> Analytics<'a> {
+    /// Creates a new `Analytics` instance.
+    #[inline]
+    pub(super) fn new(client: &'a Client) -> Self {
+        Self { client }
+    }
+
+    /// Provides access to endpoints for managing a collection of analytics rules.
+    #[inline]
+    pub fn rules(&self) -> Rules<'a> {
+        Rules::new(self.client)
+    }
+
+    /// Provides access to endpoints for managing a single analytics rule.
+    ///
+    /// # Arguments
+    /// * `rule_name` - The name of the analytics rule to manage.
+    #[inline]
+    pub fn rule(&self, rule_name: &'a str) -> Rule<'a> {
+        Rule::new(self.client, rule_name)
+    }
+
+    /// Provides access to the endpoint for creating analytics events.
+    #[inline]
+    pub fn events(&self) -> Events<'a> {
+        Events::new(self.client)
+    }
+}

typesense/src/client/analytics/rule.rs

@@ -0,0 +1,42 @@
+//! Provides access to the API endpoints for managing a single analytics rule.
+//!
+//! An `Rule` instance is created via the `client.analytics().rule("rule_name")` method.
+
+use crate::{Client, Error, execute_wrapper, models};
+use typesense_codegen::apis::analytics_api;
+
+/// Provides methods for interacting with a specific analytics rule.
+///
+/// This struct is created by calling `client.analytics().rule("rule_name")`.
+pub struct Rule<'a> {
+    pub(super) client: &'a Client,
+    pub(super) rule_name: &'a str,
+}
+
+impl<'a> Rule<'a> {
+    /// Creates a new `Rule` instance for a specific rule name.
+    #[inline]
+    pub(super) fn new(client: &'a Client, rule_name: &'a str) -> Self {
+        Self { client, rule_name }
+    }
+
+    /// Retrieves the details of this specific analytics rule.
+    pub async fn retrieve(
+        &self,
+    ) -> Result<models::AnalyticsRule, Error<analytics_api::RetrieveAnalyticsRuleError>> {
+        let params = analytics_api::RetrieveAnalyticsRuleParams {
+            rule_name: self.rule_name.into(),
+        };
+        execute_wrapper!(self, analytics_api::retrieve_analytics_rule, params)
+    }
+
+    /// Permanently deletes this specific analytics rule.
+    pub async fn delete(
+        &self,
+    ) -> Result<models::AnalyticsRule, Error<analytics_api::DeleteAnalyticsRuleError>> {
+        let params = analytics_api::DeleteAnalyticsRuleParams {
+            rule_name: self.rule_name.into(),
+        };
+        execute_wrapper!(self, analytics_api::delete_analytics_rule, params)
+    }
+}