Merge pull request #312 from harisarang/v30-analytics

add: v30 analytics + synonym_set/items APIs

Author: jasonbosco

doc/examples/server/synonymSets.ts

@@ -17,7 +17,7 @@ async function synonymSetsExample(): Promise<void> {
     // Create a synonym set
     const synonymSet = await client.synonymSets().upsert({
       name: "foobar",
-      synonyms: [
+      items: [
         {
           id: "dummy",
           synonyms: ["foo", "bar", "baz"],

src/Typesense/AnalyticsEvent.ts

@@ -1,5 +1,5 @@
 export interface AnalyticsEventCreateSchema {
-  type: string;
+  type?: string;
   name: string;
   data: Record<string, unknown>;
 }

src/Typesense/AnalyticsEvents.ts

@@ -3,6 +3,19 @@ import { AnalyticsEventCreateSchema } from "./AnalyticsEvent";
 
 const RESOURCEPATH = "/analytics/events";
 
+export interface AnalyticsEventsRetrieveSchema {
+  events: {
+    name: string;
+    event_type: string;
+    collection: string;
+    timestamp: number;
+    user_id: string;
+    doc_id?: string;
+    doc_ids?: string[];
+    query?: string;
+  }[];
+}
+
 export default class AnalyticsEvents {
   constructor(private readonly apiCall: ApiCall) {
     this.apiCall = apiCall;
@@ -17,6 +30,17 @@ export default class AnalyticsEvents {
     );
   }
 
+  async retrieve(params: {
+    user_id: string;
+    name: string;
+    n: number;
+  }): Promise<AnalyticsEventsRetrieveSchema> {
+    return this.apiCall.get<AnalyticsEventsRetrieveSchema>(
+      this.endpointPath(),
+      params,
+    );
+  }
+
   private endpointPath(operation?: string): string {
     return `${AnalyticsEvents.RESOURCEPATH}${
       operation === undefined ? "" : "/" + encodeURIComponent(operation)

src/Typesense/AnalyticsRule.ts

@@ -2,23 +2,36 @@ import ApiCall from "./ApiCall";
 import AnalyticsRules from "./AnalyticsRules";
 
 export interface AnalyticsRuleCreateSchema {
-  type: "popular_queries" | "nohits_queries" | "counter" | "log";
-  params: {
-    enable_auto_aggregation?: boolean;
-    source: {
-      collections: string[];
-      events?: Array<{
-        type: string;
-        weight?: number;
-        name: string;
-      }>;
-    };
+  name: string;
+  type: string;
+  collection: string;
+  event_type: string;
+  rule_tag?: string;
+  params?: {
+    destination_collection?: string;
+    limit?: number;
+    capture_search_requests?: boolean;
+    meta_fields?: string[];
     expand_query?: boolean;
-    destination?: {
-      collection: string;
-      counter_field?: string;
-    };
+    counter_field?: string;
+    weight?: number;
+  };
+}
+
+export interface AnalyticsRuleUpsertSchema {
+  name?: string;
+  type?: string;
+  collection?: string;
+  event_type?: string;
+  rule_tag?: string;
+  params?: {
+    destination_collection?: string;
     limit?: number;
+    capture_search_requests?: boolean;
+    meta_fields?: string[];
+    expand_query?: boolean;
+    counter_field?: string;
+    weight?: number;
   };
 }
 

src/Typesense/AnalyticsRuleV1.ts

@@ -0,0 +1,52 @@
+import ApiCall from "./ApiCall";
+import AnalyticsRulesV1 from "./AnalyticsRulesV1";
+
+export interface AnalyticsRuleCreateSchemaV1 {
+  type: "popular_queries" | "nohits_queries" | "counter" | "log";
+  params: {
+    enable_auto_aggregation?: boolean;
+    source: {
+      collections: string[];
+      events?: {
+        type: string;
+        weight?: number;
+        name: string;
+      }[];
+    };
+    expand_query?: boolean;
+    destination?: {
+      collection: string;
+      counter_field?: string;
+    };
+    limit?: number;
+  };
+}
+
+export interface AnalyticsRuleDeleteSchemaV1 {
+  name: string;
+}
+
+export interface AnalyticsRuleSchemaV1 extends AnalyticsRuleCreateSchemaV1 {
+  name: string;
+}
+
+export default class AnalyticsRuleV1 {
+  constructor(
+    private name: string,
+    private apiCall: ApiCall,
+  ) {}
+
+  async retrieve(): Promise<AnalyticsRuleSchemaV1> {
+    return this.apiCall.get<AnalyticsRuleSchemaV1>(this.endpointPath());
+  }
+
+  async delete(): Promise<AnalyticsRuleDeleteSchemaV1> {
+    return this.apiCall.delete<AnalyticsRuleDeleteSchemaV1>(this.endpointPath());
+  }
+
+  private endpointPath(): string {
+    return `${AnalyticsRulesV1.RESOURCEPATH}/${encodeURIComponent(this.name)}`;
+  }
+}
+
+

src/Typesense/AnalyticsRules.ts

@@ -2,6 +2,7 @@ import ApiCall from "./ApiCall";
 import {
   AnalyticsRuleCreateSchema,
   AnalyticsRuleSchema,
+  AnalyticsRuleUpsertSchema,
 } from "./AnalyticsRule";
 
 export interface AnalyticsRulesRetrieveSchema {
@@ -15,18 +16,46 @@ export default class AnalyticsRules {
     this.apiCall = apiCall;
   }
 
+  async create(
+    params:
+      | AnalyticsRuleCreateSchema
+      | AnalyticsRuleCreateSchema[],
+  ): Promise<
+    | AnalyticsRuleSchema
+    | (
+        | AnalyticsRuleSchema
+        | {
+            error?: string;
+          }
+      )[]
+  > {
+    return this.apiCall.post(
+      this.endpointPath(),
+      params,
+      {},
+      {},
+    );
+  }
+
   async upsert(
     name: string,
-    params: AnalyticsRuleCreateSchema
+    params: AnalyticsRuleUpsertSchema
   ): Promise<AnalyticsRuleSchema> {
     return this.apiCall.put<AnalyticsRuleSchema>(
       this.endpointPath(name),
       params
     );
   }
 
-  async retrieve(): Promise<AnalyticsRulesRetrieveSchema> {
-    return this.apiCall.get<AnalyticsRulesRetrieveSchema>(this.endpointPath());
+  async retrieve(ruleTag?: string): Promise<AnalyticsRulesRetrieveSchema> {
+    const query: Record<string, string> = {};
+    if (ruleTag) {
+      query["rule_tag"] = ruleTag;
+    }
+    return this.apiCall.get<AnalyticsRulesRetrieveSchema>(
+      this.endpointPath(),
+      query,
+    );
   }
 
   private endpointPath(operation?: string): string {

src/Typesense/AnalyticsRulesV1.ts

@@ -0,0 +1,43 @@
+import ApiCall from "./ApiCall";
+import {
+  AnalyticsRuleCreateSchemaV1,
+  AnalyticsRuleSchemaV1,
+} from "./AnalyticsRuleV1";
+
+export interface AnalyticsRulesRetrieveSchemaV1 {
+  rules: AnalyticsRuleSchemaV1[];
+}
+
+const RESOURCEPATH = "/analytics/rules";
+
+export default class AnalyticsRulesV1 {
+  constructor(private readonly apiCall: ApiCall) {
+    this.apiCall = apiCall;
+  }
+
+  async upsert(
+    name: string,
+    params: AnalyticsRuleCreateSchemaV1
+  ): Promise<AnalyticsRuleSchemaV1> {
+    return this.apiCall.put<AnalyticsRuleSchemaV1>(
+      this.endpointPath(name),
+      params
+    );
+  }
+
+  async retrieve(): Promise<AnalyticsRulesRetrieveSchemaV1> {
+    return this.apiCall.get<AnalyticsRulesRetrieveSchemaV1>(this.endpointPath());
+  }
+
+  private endpointPath(operation?: string): string {
+    return `${AnalyticsRulesV1.RESOURCEPATH}${
+      operation === undefined ? "" : "/" + encodeURIComponent(operation)
+    }`;
+  }
+
+  static get RESOURCEPATH() {
+    return RESOURCEPATH;
+  }
+}
+
+

src/Typesense/AnalyticsV1.ts

@@ -0,0 +1,52 @@
+import ApiCall from "./ApiCall";
+import AnalyticsRulesV1 from "./AnalyticsRulesV1";
+import AnalyticsRuleV1 from "./AnalyticsRuleV1";
+import AnalyticsEvents from "./AnalyticsEvents";
+
+const RESOURCEPATH = "/analytics";
+
+/**
+ * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `client.analytics` (new Analytics APIs).
+ */
+export default class AnalyticsV1 {
+  private static hasWarnedDeprecation = false;
+  private readonly _analyticsRules: AnalyticsRulesV1;
+  private readonly individualAnalyticsRules: Record<string, AnalyticsRuleV1> = {};
+  private readonly _analyticsEvents: AnalyticsEvents;
+
+  constructor(private readonly apiCall: ApiCall) {
+    this.apiCall = apiCall;
+    this._analyticsRules = new AnalyticsRulesV1(this.apiCall);
+    this._analyticsEvents = new AnalyticsEvents(this.apiCall);
+  }
+
+  rules(): AnalyticsRulesV1;
+  rules(id: string): AnalyticsRuleV1;
+  rules(id?: string): AnalyticsRulesV1 | AnalyticsRuleV1 {
+    if (!AnalyticsV1.hasWarnedDeprecation) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[typesense] 'analyticsV1' is deprecated starting with Typesense Server v30 and will be removed in a future release. Please use 'analytics' instead.",
+      );
+      AnalyticsV1.hasWarnedDeprecation = true;
+    }
+    if (id === undefined) {
+      return this._analyticsRules;
+    } else {
+      if (this.individualAnalyticsRules[id] === undefined) {
+        this.individualAnalyticsRules[id] = new AnalyticsRuleV1(id, this.apiCall);
+      }
+      return this.individualAnalyticsRules[id];
+    }
+  }
+
+  events(): AnalyticsEvents {
+    return this._analyticsEvents;
+  }
+
+  static get RESOURCEPATH() {
+    return RESOURCEPATH;
+  }
+}
+
+

src/Typesense/Client.ts

@@ -16,6 +16,7 @@ import Operations from "./Operations";
 import MultiSearch from "./MultiSearch";
 import Presets from "./Presets";
 import Preset from "./Preset";
+import AnalyticsV1 from "./AnalyticsV1";
 import Analytics from "./Analytics";
 import Stopwords from "./Stopwords";
 import Stopword from "./Stopword";
@@ -37,6 +38,7 @@ export default class Client {
   operations: Operations;
   multiSearch: MultiSearch;
   analytics: Analytics;
+  analyticsV1: AnalyticsV1;
   stemming: Stemming;
   private readonly _collections: Collections;
   private readonly individualCollections: Record<string, Collection>;
@@ -77,6 +79,7 @@ export default class Client {
     this._stopwords = new Stopwords(this.apiCall);
     this.individualStopwords = {};
     this.analytics = new Analytics(this.apiCall);
+    this.analyticsV1 = new AnalyticsV1(this.apiCall);
     this.stemming = new Stemming(this.apiCall);
     this._conversations = new Conversations(this.apiCall);
     this.individualConversations = {};

src/Typesense/Synonym.ts

@@ -10,7 +10,11 @@ export interface SynonymDeleteSchema {
   id: string;
 }
 
+/**
+ * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `client.synonymSets` (new Synonym Sets APIs).
+ */
 export default class Synonym {
+  private static hasWarnedDeprecation = false;
   constructor(
     private collectionName: string,
     private synonymId: string,
@@ -26,6 +30,13 @@ export default class Synonym {
   }
 
   private endpointPath(): string {
+    if (!Synonym.hasWarnedDeprecation) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[typesense] 'synonym' APIs are deprecated starting with Typesense Server v30. Please migrate to synonym sets 'synonym_sets'.",
+      );
+      Synonym.hasWarnedDeprecation = true;
+    }
     return `${Collections.RESOURCEPATH}/${encodeURIComponent(this.collectionName)}${Synonyms.RESOURCEPATH}/${encodeURIComponent(this.synonymId)}`;
   }
 }