Merge pull request #13 from ember-nexus/feature/gh-6-implement-search-endpoint

add support for post search endpoint, closes #6

Author: Syndesi

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Added
+- Add support for post search endpoint, closes #6.
 
 ## 0.1.0 - 2026-02-01
 

core/src/Endpoint/Search/PostSearchEndpoint.ts

@@ -0,0 +1,64 @@
+import { FetchHelper, ServiceResolver } from '../../Service/index.js';
+import { LoggerInterface } from '../../Type/Definition/index.js';
+import { ParsedResponse } from '../../Type/Definition/Response/index.js';
+import { Step } from '../../Type/Definition/Search/Step/index.js';
+import { StepResult } from '../../Type/Definition/Search/StepResult/index.js';
+import { ServiceIdentifier } from '../../Type/Enum/index.js';
+
+/**
+ * The post search endpoint executes a search query and returns results.
+ *
+ * @see [Ember Nexus API: Search Endpoint](https://ember-nexus.github.io/api/#/api-endpoints/search/post-search)
+ * @experimental
+ */
+class PostSearchEndpoint {
+  static identifier: ServiceIdentifier = ServiceIdentifier.endpointSearchPostSearchEndpoint;
+  constructor(
+    private logger: LoggerInterface,
+    private fetchHelper: FetchHelper,
+  ) {}
+
+  static constructFromServiceResolver(serviceResolver: ServiceResolver): PostSearchEndpoint {
+    return new PostSearchEndpoint(
+      serviceResolver.getServiceOrFail<LoggerInterface>(ServiceIdentifier.logger),
+      serviceResolver.getServiceOrFail<FetchHelper>(ServiceIdentifier.serviceFetchHelper),
+    );
+  }
+
+  async postSearch(
+    steps: Step[],
+    parameters: null | Record<string, unknown> = null,
+    debug: boolean = false,
+  ): Promise<ParsedResponse<StepResult[]>> {
+    try {
+      const url = this.fetchHelper.buildUrl('/search');
+      this.logger.debug(`Executing HTTP POST request against URL: ${url}`);
+
+      const response = await fetch(
+        url,
+        this.fetchHelper.getDefaultPostOptions(
+          JSON.stringify({
+            steps: steps,
+            parameters: parameters,
+            debug: debug,
+          }),
+        ),
+      ).catch((error) => this.fetchHelper.rethrowErrorAsNetworkError(error));
+
+      const rawData = await this.fetchHelper.parseJsonResponse(response);
+
+      if (!('results' in rawData)) {
+        throw new Error("Search result did not contain property 'results'.");
+      }
+
+      return {
+        data: rawData.results as StepResult[],
+        response: response,
+      };
+    } catch (error) {
+      this.fetchHelper.logAndThrowError(error);
+    }
+  }
+}
+
+export { PostSearchEndpoint };

core/src/Service/ApiWrapper.ts

@@ -17,6 +17,7 @@ import {
   PostIndexEndpoint,
   PutElementEndpoint,
 } from '../Endpoint/Element/index.js';
+import { PostSearchEndpoint } from '../Endpoint/Search/PostSearchEndpoint.js';
 import {
   DeleteTokenEndpoint,
   GetMeEndpoint,
@@ -38,6 +39,8 @@ import {
   Uuid,
 } from '../Type/Definition/index.js';
 import { ParsedResponse } from '../Type/Definition/Response/index.js';
+import { Step } from '../Type/Definition/Search/Step/index.js';
+import { StepResult } from '../Type/Definition/Search/StepResult/index.js';
 import { ServiceIdentifier } from '../Type/Enum/index.js';
 
 class ApiWrapper {
@@ -60,6 +63,7 @@ class ApiWrapper {
     private postTokenEndpoint: PostTokenEndpoint,
     private getTokenEndpoint: GetTokenEndpoint,
     private deleteTokenEndpoint: DeleteTokenEndpoint,
+    private postSearchEndpoint: PostSearchEndpoint,
     private elementCache: ElementCache,
     private elementChildrenCache: ElementChildrenCache,
     private elementParentsCache: ElementParentsCache,
@@ -93,6 +97,7 @@ class ApiWrapper {
       serviceResolver.getServiceOrFail<PostTokenEndpoint>(ServiceIdentifier.endpointUserPostTokenEndpoint),
       serviceResolver.getServiceOrFail<GetTokenEndpoint>(ServiceIdentifier.endpointUserGetTokenEndpoint),
       serviceResolver.getServiceOrFail<DeleteTokenEndpoint>(ServiceIdentifier.endpointUserDeleteTokenEndpoint),
+      serviceResolver.getServiceOrFail<PostSearchEndpoint>(ServiceIdentifier.endpointSearchPostSearchEndpoint),
       serviceResolver.getServiceOrFail<ElementCache>(ServiceIdentifier.cacheElement),
       serviceResolver.getServiceOrFail<ElementChildrenCache>(ServiceIdentifier.cacheElementChildren),
       serviceResolver.getServiceOrFail<ElementParentsCache>(ServiceIdentifier.cacheElementParents),
@@ -537,6 +542,18 @@ class ApiWrapper {
   public async deleteToken(): Promise<void> {
     await this.deleteTokenEndpoint.deleteToken();
   }
+
+  /**
+   * @experimental
+   */
+  public async postSearch(
+    steps: Step[],
+    parameters: null | Record<string, unknown> = null,
+    debug: boolean = false,
+  ): Promise<StepResult[]> {
+    const parsedResponse = await this.postSearchEndpoint.postSearch(steps, parameters, debug);
+    return parsedResponse.data;
+  }
 }
 
 export { ApiWrapper };

core/src/Type/Definition/Search/Step/CypherPathSubsetStep.ts

@@ -0,0 +1,8 @@
+import { Step } from './Step.js';
+
+interface CypherPathSubsetStep extends Step {
+  type: 'cypher-path-subset';
+  query: string;
+}
+
+export { CypherPathSubsetStep };

core/src/Type/Definition/Search/Step/ElasticsearchQueryDSLMixinStep.ts

@@ -0,0 +1,15 @@
+import { Step } from './Step.js';
+
+interface ElasticsearchQueryDSLMixinStep extends Step {
+  type: 'elasticsearch-query-dsl-mixin';
+  query: Record<string, unknown>;
+  parameters?: {
+    nodeTypes?: string[];
+    relationTypes?: string[];
+    page?: number;
+    pageSize?: number;
+    minScore?: null | number;
+  };
+}
+
+export { ElasticsearchQueryDSLMixinStep };

core/src/Type/Definition/Search/Step/ElementHydrationStep.ts

@@ -0,0 +1,11 @@
+import { Step } from './Step.js';
+import { Uuid } from '../../Uuid.js';
+
+interface ElementHydrationStep extends Step {
+  type: 'element-hydration';
+  query: {
+    elementIds: Uuid[] | string;
+  };
+}
+
+export { ElementHydrationStep };

core/src/Type/Definition/Search/Step/Step.ts

@@ -0,0 +1,7 @@
+interface Step {
+  type: string;
+  query?: null | string | Record<string, unknown>;
+  parameters?: Record<string, unknown>;
+}
+
+export { Step };

core/src/Type/Definition/Search/Step/index.ts

@@ -0,0 +1,4 @@
+export * from './CypherPathSubsetStep.js';
+export * from './ElasticsearchQueryDSLMixinStep.js';
+export * from './ElementHydrationStep.js';
+export * from './Step.js';

core/src/Type/Definition/Search/StepResult/CypherPathSubsetStepResult.ts

@@ -0,0 +1,10 @@
+import { Uuid } from '../../Uuid.js';
+
+interface CypherPathSubsetStepResult {
+  paths: {
+    nodeIds: Uuid[];
+    relationIds: Uuid[];
+  };
+}
+
+export { CypherPathSubsetStepResult };

core/src/Type/Definition/Search/StepResult/ElasticsearchQueryDSLMixinStepResult.ts

@@ -0,0 +1,15 @@
+import { Uuid } from '../../Uuid.js';
+
+interface ElasticsearchQueryDSLMixinStepResult {
+  elements: {
+    id: Uuid;
+    type: string;
+    metadata: {
+      score: number;
+    };
+  }[];
+  totalHits: number;
+  maxScore: number;
+}
+
+export { ElasticsearchQueryDSLMixinStepResult };