@or-sdk/lookup 1.1.0-beta.1830.0

package/src/Lookup.ts

@@ -0,0 +1,353 @@
+import { Base, List, makeList } from '@or-sdk/base';
+import { SERVICE_KEY } from './constants';
+import {
+  LoadDocument, CreateCollection, Search, Ask, UpdateCollection,
+  UpdateDocument, LookupConfig, Document, Collection, SearchResult,
+  AskResults, Find, Property, CreatePassage, Passage, UpdatePassage,
+  DeletedPassage, FindPassages,
+} from './types';
+import { createErrorParser, processors } from './error-parser';
+
+const errorParser = createErrorParser(processors.AXIOS);
+
+export class Lookup extends Base {
+  constructor(params: LookupConfig) {
+    const { token, discoveryUrl, accountId, serviceUrl } = params;
+
+    super({
+      token,
+      discoveryUrl,
+      serviceKey: SERVICE_KEY,
+      accountId,
+      serviceUrl,
+    });
+  }
+
+  parseError(err: unknown) {
+    return errorParser(err);
+  }
+
+  async loadDocument(collectionId: string, params: LoadDocument): Promise<Document> {
+    const response = await this.callApiV2<Document>({
+      method: 'POST',
+      route: `collections/${collectionId}/documents`,
+      data: params,
+    });
+    return response;
+  }
+
+  /**
+   * Create a new collection.
+   * @param params - The collection creation parameters.
+   * @returns The created collection.
+   */
+  async createCollection(params: CreateCollection): Promise<Collection> {
+    const response = await this.callApiV2<Collection>({
+      method: 'POST',
+      route: 'collections',
+      data: params,
+    });
+
+    return response;
+  }
+
+  /**
+   * Create a new passage within the collection.
+   * @param collectionId - The ID of the collection the passage belongs to.
+   * @param passage - The passage creation parameters.
+   * @returns The created passage.
+   */
+  async createPassage<T extends Record<string, unknown>>(
+    collectionId: string,
+    passage: CreatePassage<T>,
+  ): Promise<Passage<T>> {
+    const response = await this.callApiV2<Passage<T>>({
+      method: 'POST',
+      route: `collections/${collectionId}/passages`,
+      data: passage,
+    });
+
+    return response;
+  }
+
+  /**
+   * Create batch of passages within the collection.
+   * @param collectionId - The ID of the collection the passage belongs to.
+   * @param passages - The passages to create.
+   */
+  async createManyPassages<T extends Record<string, unknown>>(
+    collectionId: string,
+    passages: CreatePassage<T>[],
+  ): Promise<void> {
+    await this.callApiV2({
+      method: 'POST',
+      route: `collections/${collectionId}/passages/batch`,
+      data: passages,
+    });
+  }
+
+  /**
+   * Delete a collection by ID.
+   * @param collectionId - The ID of the collection to delete.
+   * @returns The deleted collection.
+   */
+  async deleteCollection(collectionId: string): Promise<Collection> {
+    const response = await this.callApiV2<Collection>({
+      method: 'DELETE',
+      route: `collections/${collectionId}`,
+    });
+
+    return response;
+  }
+
+  /**
+   * Delete a passage from a collection.
+   * @param collectionId - The ID of the collection the passage belongs to.
+   * @param passageId - The ID of the passage to delete.
+   * @returns The deleted passage.
+   */
+  async deletePassage(collectionId: string, passageId: string): Promise<DeletedPassage> {
+    const response = await this.callApiV2<DeletedPassage>({
+      method: 'DELETE',
+      route: `collections/${collectionId}/passages/${passageId}`,
+    });
+
+    return response;
+  }
+
+  /**
+   * Search for documents in a collection.
+   * @param collectionId - The ID of the collection to search in.
+   * @param params - The search parameters.
+   * @returns An array of search results.
+   */
+  async search(collectionId: string, params: Search): Promise<SearchResult[]> {
+    const response = await this.callApiV2<SearchResult[]>({
+      method: 'POST',
+      route: `collections/${collectionId}/search`,
+      data: params,
+    });
+
+    return response;
+  }
+
+  /**
+   * Ask a question and generate an answer based on the documents in a collection.
+   * @param collectionId - The ID of the collection to use for generating the answer.
+   * @param params - The ask question parameters.
+   * @returns The generated answer and search result.
+   */
+  async ask(collectionId: string, params: Ask): Promise<AskResults> {
+    const response = await this.callApiV2<AskResults>({
+      method: 'POST',
+      route: `collections/${collectionId}/ask`,
+      data: params,
+    });
+
+    return response;
+  }
+
+  /**
+   * Update a document's description.
+   * @param collectionId - The ID of the collection the document belongs to.
+   * @param documentId - The ID of the document to update.
+   * @param params - The update document parameters.
+   * @returns The updated document.
+   */
+  async updateDocument(collectionId: string, documentId: string, params: UpdateDocument): Promise<Document> {
+    const response = await this.callApiV2<Document>({
+      method: 'PUT',
+      route: `collections/${collectionId}/documents/${documentId}`,
+      data: params,
+    });
+    return response;
+  }
+
+  /**
+   * Update a passage in a collection.
+   * @param collectionId - The ID of the collection the passage belongs to.
+   * @param passageId - The ID of the passage to update.
+   * @param params - The update passage parameters.
+   * @returns The updated passage.
+   */
+  async updatePassage<T extends Record<string, unknown>>(
+    collectionId: string,
+    passageId: string,
+    params: UpdatePassage<T>,
+  ): Promise<Passage<T>> {
+    const response = await this.callApiV2<Passage<T>>({
+      method: 'PUT',
+      route: `collections/${collectionId}/passages/${passageId}`,
+      data: params,
+    });
+
+    return response;
+  }
+
+  /**
+   * Update a document's description.
+   * @param collectionId - The ID of the collection the document belongs to.
+   * @param documentId - The ID of the document to update.
+   * @param params - The update document parameters.
+   * @returns The updated document.
+   */
+  async updateCollection(collectionId: string, params: UpdateCollection): Promise<Collection> {
+    const response = await this.callApiV2<Collection>({
+      method: 'PUT',
+      route: `collections/${collectionId}`,
+      data: params,
+    });
+    return response;
+  }
+
+  /**
+   * Update a collection's description.
+   * @param collectionId - The ID of the collection to update.
+   * @param params - The update collection parameters.
+   * @returns The updated collection.
+   */
+  async getDocument(collectionId: string, documentId: string): Promise<Document> {
+    const response = await this.callApiV2<Document>({
+      method: 'GET',
+      route: `collections/${collectionId}/documents/${documentId}`,
+    });
+    return response;
+  }
+
+  /**
+   * Get a collection by its ID.
+   * @param collectionId - The ID of the collection to retrieve.
+   * @returns The retrieved collection.
+   */
+  async getCollection(collectionId: string): Promise<Collection> {
+    const response = await this.callApiV2<Collection>({
+      method: 'GET',
+      route: `collections/${collectionId}`,
+    });
+    return response;
+  }
+
+  /**
+   * Get a single passage from a collection.
+   * @param collectionId - The ID of the collection the passage belongs to.
+   * @param passageId - The ID of the passage to retrieve.
+   * @returns The retrieved passage.
+   */
+  async getPassage<T extends Record<string, unknown>>(collectionId: string, passageId: string): Promise<Passage<T>> {
+    const response = await this.callApiV2<Passage<T>>({
+      method: 'GET',
+      route: `collections/${collectionId}/passages/${passageId}`,
+    });
+
+    return response;
+  }
+
+  /**
+   * Add a custom property to an existing collection.
+   * Custom properties can be used to store additional metadata about the collection or its passages.
+   * The available data types for properties can be found https://weaviate.io/developers/weaviate/config-refs/datatypes.
+   * Note that there are reserved property names:
+   *  ['accountId', 'collection', 'document', 'content', 'loaderMetadata', 'sourceUrl']
+   * @param collectionId - The ID of the collection to add the property to.
+   * @param property - The property to add to the collection.
+   * @returns A promise that resolves when the property has been added.
+   */
+  async addProperty(collectionId: string, property: Property): Promise<void> {
+    await this.callApiV2({
+      method: 'POST',
+      route: `collections/${collectionId}/properties`,
+      data: property,
+    });
+  }
+
+  /**
+   * List all documents in a collection with optional pagination and query.
+   * @param collectionId - The ID of the collection to retrieve documents from.
+   * @param find - Optional find parameters.
+   * @returns An array of documents.
+   */
+  async listDocuments(
+    collectionId: string,
+    params: Find = {},
+  ): Promise<List<Document>> {
+    const response = await this.callApiV2<Document[]>({
+      method: 'GET',
+      route: `collections/${collectionId}/documents`,
+      params,
+    });
+
+    return makeList(response);
+  }
+
+  /**
+   * List collections with optional pagination and query.
+   * @param find - Optional find parameters.
+   * @returns An array of collections.
+   */
+  async listCollections(
+    params: Find = {},
+  ): Promise<List<Collection>> {
+    const response = await this.callApiV2<Collection[]>({
+      method: 'GET',
+      route: 'collections',
+      params,
+    });
+
+    return makeList(response);
+  }
+
+  /**
+   * List all passages in a collection with optional pagination and query.
+   * @param collectionId - The ID of the collection to retrieve passages from.
+   * @param find - Optional find parameters.
+   * @returns An array of passages.
+   */
+  async listPassages<T extends Record<string, unknown>>(
+    collectionId: string,
+    params: FindPassages = {},
+  ): Promise<List<Passage<T>>> {
+    const response = await this.callApiV2<Passage<T>[]>({
+      method: 'GET',
+      route: `collections/${collectionId}/passages`,
+      params,
+    });
+
+    return makeList(response);
+  }
+
+  /**
+   * List all passages in a document with optional pagination, query, and ordering.
+   * @param collectionId - The ID of the collection containing the document.
+   * @param documentId - The ID of the document to retrieve passages from.
+   * @param find - Optional find parameters.
+   * @returns An array of passages with pagination info.
+   */
+  async listPassagesInDocument<T extends Record<string, unknown>>(
+    collectionId: string,
+    documentId: string,
+    find: FindPassages = {},
+  ): Promise<List<Passage<T>>> {
+    const response = await this.callApiV2<Passage<T>[]>({
+      method: 'GET',
+      route: `collections/${collectionId}/documents/${documentId}/passages`,
+      params: find,
+    });
+
+    return makeList(response);
+  }
+
+  /**
+   * Delete a document from a collection.
+   * @param collectionId - The ID of the collection to delete the document from.
+   * @param documentId - The ID of the document to delete.
+   * @returns The deleted document.
+   */
+  async deleteDocument(collectionId: string, documentId: string): Promise<Document> {
+    const response = await this.callApiV2<Document>({
+      method: 'DELETE',
+      route: `collections/${collectionId}/documents/${documentId}`,
+    });
+
+    return response;
+  }
+}

package/src/__tests__/QnA.collections.spec.ts

@@ -0,0 +1,108 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { rest } from 'msw';
+import { setupServer } from 'msw/node';
+
+import { Lookup } from '..';
+import type { LookupConfig, CreateCollection } from '..';
+
+import collection from './fixtures/collection.json';
+
+const server = setupServer(
+  rest.post('https://lookup-api.svc.staging.api.onereach.ai/collections', async (req, res, ctx) => {
+    if (req.headers.get('authorization') !== 'valid-auth-token') {
+      return res(ctx.status(401));
+    }
+    const body = await req.json();
+    if (body.ise === true) {
+      return res(
+        ctx.status(500),
+        ctx.json({
+          error: 'Some tech error message here',
+          statusCode: 500,
+        })
+      );
+    }
+    if (typeof body.name === 'string' && body.name.length < 3) {
+      return res(
+        ctx.status(400),
+        ctx.json({
+          error: [
+            'name must be longer than or equal to 5 characters',
+            'Can start only with a letter.',
+          ],
+          statusCode: 400,
+        })
+      );
+    }
+    return res(ctx.json(collection));
+  }),
+);
+
+const createLookupInstance = (opts: Partial<LookupConfig> = {}) => {
+  return new Lookup({
+    serviceUrl: 'https://lookup-api.svc.staging.api.onereach.ai',
+    token: 'valid-auth-token',
+    ...opts,
+  });
+};
+
+describe('Lookup', () => {
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it('should create an instance successfully', () => {
+    const lookup = createLookupInstance();
+    expect(lookup).toBeInstanceOf(Lookup);
+  });
+
+  it('should create a new collection properly', async () => {
+    const lookup = createLookupInstance();
+    const resp = await lookup.createCollection({
+      name: 'dev collection',
+    });
+    expect(resp).toEqual(collection);
+  });
+
+  it('should show UnAuth Error if token is invalid', async () => {
+    const lookup = createLookupInstance({
+      token: 'invalid-token',
+    });
+
+    const promise = lookup.createCollection({
+      name: 'dev collection',
+    });
+
+    await expect(promise).rejects.toMatchObject({
+      status: 401,
+      message: 'We are not able to authenticate you',
+    });
+  });
+
+  it('should show validation errors properly', async () => {
+    const lookup = createLookupInstance();
+
+    const promise = lookup.createCollection({
+      name: '1',
+    });
+
+    await expect(promise).rejects.toMatchObject({
+      status: 400,
+      message: 'name must be longer than or equal to 5 characters. Can start only with a letter.',
+    });
+  });
+
+  it('should show ISE properly', async () => {
+    const lookup = createLookupInstance();
+
+    const promise = lookup.createCollection({
+      ise: true,
+    } as unknown as CreateCollection);
+
+    await expect(promise).rejects.toMatchObject({
+      status: 500,
+      message: 'Internal server error',
+      description: 'Some tech error message here',
+    });
+  });
+});

package/src/__tests__/fixtures/collection.json

@@ -0,0 +1,34 @@
+{
+  "id": "c5cd0f6d-cf98-4f2e-822e-42be148012b1",
+  "accountId": "d40ff964-dd12-4cbd-bb85-6ad35af3f908",
+  "description": "some lorem description here",
+  "name": "dev collection",
+  "createdAt": "2023-06-21T05:38:51.211Z",
+  "updatedAt": "2023-06-21T05:38:51.211Z",
+  "properties": [
+    {
+      "name": "document",
+      "dataType": "Document",
+      "description": "A document the passage belongs to."
+    },
+    {
+      "name": "content",
+      "dataType": "text",
+      "description": "the searchable passage content."
+    },
+    {
+      "name": "loaderMetadata",
+      "dataType": "text",
+      "description": "JSON encoded metadata of the content loader."
+    },
+    {
+      "name": "sourceUrl",
+      "dataType": "text",
+      "description": "The url of the document this passage belongs to."
+    },
+    {
+      "name": "dddddd",
+      "dataType": "date[]"
+    }
+  ]
+}

package/src/constants.ts

@@ -0,0 +1 @@
+export const SERVICE_KEY = 'lookup-api';

package/src/error-parser/OrNetworkError.ts

@@ -0,0 +1,23 @@
+type CtorOptions = {
+  message: string;
+  description?: string;
+  status?: number;
+};
+
+export class OrNetworkError extends Error {
+  private _status: number | undefined;
+  private _description: string | undefined;
+  constructor({ description, message, status }: CtorOptions) {
+    super(message);
+    this._status = status;
+    this._description = description;
+  }
+
+  get status() {
+    return this._status;
+  }
+
+  get description() {
+    return this._description;
+  }
+}

package/src/error-parser/index.ts

@@ -0,0 +1,16 @@
+import type { ErrorProcessor } from './types';
+
+export * from './OrNetworkError';
+export * from './processors';
+
+export function createErrorParser<E>(...processors: ErrorProcessor<E>[]) {
+  return function parseError(error: unknown) {
+    const processor = processors.find((p) => p.guard(error));
+
+    if (processor) {
+      return processor.convertError(error as E);
+    }
+
+    return new Error('Unknown Error');
+  };
+}

package/src/error-parser/parse-axios-error.ts

@@ -0,0 +1,40 @@
+import type { AxiosError } from 'axios';
+
+import { OrNetworkError } from './OrNetworkError';
+
+const MESSAGES: Record<number, string> = {
+  401: 'We are not able to authenticate you',
+  500: 'Internal server error',
+};
+
+export function parseAxiosError(e: AxiosError): Error {
+  if (e.response) {
+    const data = e.response.data as Record<string, unknown>;
+    const status = e.response.status;
+    const generalMessage = MESSAGES[status] || e.message;
+    const message = normalizeMessage(data.message || data.error) || generalMessage;
+
+    if (status < 500) {
+      return new OrNetworkError({
+        message,
+        status,
+      });
+    }
+    return new OrNetworkError({
+      message: generalMessage,
+      status,
+      description: message,
+    });
+  }
+
+  return new Error(e.message);
+}
+
+function normalizeMessage(message: unknown): string | undefined {
+  if (typeof message === 'string') {
+    return message;
+  }
+  if (Array.isArray(message)) {
+    return message.join('. ');
+  }
+}

package/src/error-parser/processors.ts

@@ -0,0 +1,21 @@
+import { parseAxiosError as deprecatedParseAxiosError } from '@or-sdk/base';
+import axios from 'axios';
+import type { AxiosError } from 'axios';
+
+import { parseAxiosError } from './parse-axios-error';
+import type { ErrorParser, ErrorProcessor } from './types';
+
+const DEPRECATED_AXIOS: ErrorProcessor<AxiosError> = {
+  guard: axios.isAxiosError,
+  convertError: deprecatedParseAxiosError as ErrorParser<AxiosError>,
+};
+
+const AXIOS: ErrorProcessor<AxiosError> = {
+  guard: axios.isAxiosError,
+  convertError: parseAxiosError,
+};
+
+export const processors = {
+  AXIOS,
+  DEPRECATED_AXIOS,
+};

package/src/error-parser/types.ts

@@ -0,0 +1,6 @@
+export type ErrorParser<T> = (error: T) => Error;
+
+export type ErrorProcessor<E = unknown> = {
+  guard: (error: unknown) => error is E;
+  convertError: (error: E) => Error;
+};

package/src/guards.ts

@@ -0,0 +1,5 @@
+import { OrNetworkError } from './error-parser';
+
+export function isOrNetworkError(err: unknown): err is OrNetworkError {
+  return err instanceof OrNetworkError;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { Lookup as Lookup } from './Lookup';
+export * from './types';
+export * from './constants';
+export * from './guards';