[spruce] Regenerate OpenAPI core, update query and fetch to return us…

…age / readUnits (#183)

## Problem
The backend is now support `readUnits` in responses for the `query` and
`fetch` operations. We've updated the `vector_service.proto` file to
include the new response shapes, and this needs to be pulled into the
clients: pinecone-io/pinecone-protos#105

## Solution
- Regenerate `pinecone-generated-ts-fetch` core and drop it in. This
includes @haruska's updates to our tags, thus the renaming of
`ManagePodIndexesApi` -> `ManageIndexesApi`.
- Add new `OperationUsage` type to `/src/data/types.ts` (open to
changing the name `OperationUsage`).
- Update our custom types for `QueryResponse` and `FetchResponse` to
include `usage`.

## Type of Change
- [X] New feature (non-breaking change which adds functionality)
- [X] This change requires a documentation update

## Test Plan
You will need to call either `fetch()` or `query()` and validate the
field is returned in the response.

```
await client.index('test-dim-2').fetch(['1', '2'])

// {
//   records: {
//     '1': {
//       id: '1',
//       values: [Array],
//       sparseValues: undefined,
//       metadata: undefined
//     },
//     '2': {
//       id: '2',
//       values: [Array],
//       sparseValues: undefined,
//       metadata: undefined
//     }
//   },
//   namespace: '',
//   usage: { readUnits: 1 }
// }

await client.index('test-dim-2').query({ vector: [0.2, 0.3], topK: 5, includeValues: true })

// {
//   matches: [
//     {
//       id: '1',
//       score: 1.00242746,
//       values: [Array],
//       sparseValues: undefined,
//       metadata: undefined
//     },
//     {
//       id: '2',
//       score: 1.00034547,
//       values: [Array],
//       sparseValues: undefined,
//       metadata: undefined
//     }
//   ],
//   namespace: '',
//   usage: { readUnits: 5 }
// }
```

src/control/__tests__/configureIndex.test.ts

@@ -1,5 +1,5 @@
 import { configureIndex } from '../configureIndex';
-import { ManagePodIndexesApi } from '../../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../../pinecone-generated-ts-fetch';
 import type {
   ConfigureIndexOperationRequest,
   IndexModel,
@@ -29,7 +29,7 @@ describe('configureIndex', () => {
     const fakeConfigure: (
       req: ConfigureIndexOperationRequest
     ) => Promise<IndexModel> = jest.fn().mockResolvedValue(indexModel);
-    const IOA = { configureIndex: fakeConfigure } as ManagePodIndexesApi;
+    const IOA = { configureIndex: fakeConfigure } as ManageIndexesApi;
 
     const returned = await configureIndex(IOA)('index-name', {
       replicas: 4,

src/control/__tests__/configureIndex.validation.test.ts

@@ -6,10 +6,10 @@
 
 import { configureIndex } from '../configureIndex';
 import { PineconeArgumentError } from '../../errors';
-import { ManagePodIndexesApi } from '../../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../../pinecone-generated-ts-fetch';
 
 describe('configureIndex argument validations', () => {
-  let MPIA: ManagePodIndexesApi;
+  let MPIA: ManageIndexesApi;
   beforeEach(() => {
     MPIA = { configureIndex: jest.fn() };
     jest.mock('../../pinecone-generated-ts-fetch', () => ({

src/control/__tests__/createCollection.test.ts

@@ -1,6 +1,6 @@
 import { createCollection } from '../createCollection';
 import { PineconeArgumentError } from '../../errors';
-import { ManagePodIndexesApi } from '../../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../../pinecone-generated-ts-fetch';
 import type {
   CollectionModel,
   CreateCollectionOperationRequest,
@@ -56,7 +56,7 @@ const setOpenAPIResponse = (fakeCreateCollectionResponse) => {
   const IOA = {
     createCollection: fakeCreateCollection,
     listIndexes: fakeListIndexes,
-  } as ManagePodIndexesApi;
+  } as ManageIndexesApi;
 
   return IOA;
 };

src/control/__tests__/createIndex.test.ts

@@ -1,5 +1,5 @@
 import { createIndex } from '../createIndex';
-import { ManagePodIndexesApi } from '../../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../../pinecone-generated-ts-fetch';
 import type {
   CreateIndexOperationRequest,
   DescribeIndexRequest,
@@ -43,7 +43,7 @@ const setupCreateIndexResponse = (
   const MPIA = {
     createIndex: fakeCreateIndex,
     describeIndex: fakeDescribeIndex,
-  } as ManagePodIndexesApi;
+  } as ManageIndexesApi;
 
   return MPIA;
 };

src/control/__tests__/createIndex.validation.test.ts

@@ -6,15 +6,15 @@
 
 import { createIndex } from '../createIndex';
 import { PineconeArgumentError } from '../../errors';
-import { ManagePodIndexesApi } from '../../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../../pinecone-generated-ts-fetch';
 
 // TODO: Update tests to cover all nested properties inside spec once validator.ts is updated
 describe('createIndex argument validations', () => {
-  let MPIA: ManagePodIndexesApi;
+  let MPIA: ManageIndexesApi;
   beforeEach(() => {
     MPIA = { createIndex: jest.fn() };
     jest.mock('../../pinecone-generated-ts-fetch', () => ({
-      ManagePodIndexesApi: MPIA,
+      ManageIndexesApi: MPIA,
     }));
   });
 

src/control/__tests__/deleteCollection.test.ts

@@ -1,6 +1,6 @@
 import { deleteCollection } from '../deleteCollection';
 import { PineconeArgumentError } from '../../errors';
-import { ManagePodIndexesApi } from '../../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../../pinecone-generated-ts-fetch';
 import type {
   DeleteCollectionRequest,
   CollectionList,
@@ -20,7 +20,7 @@ const setupMocks = (
     deleteCollection: fakeDeleteCollection,
     listCollections: fakeListCollections,
   };
-  return IOA as ManagePodIndexesApi;
+  return IOA as ManageIndexesApi;
 };
 
 describe('deleteCollection', () => {

src/control/__tests__/describeCollection.test.ts

@@ -1,6 +1,6 @@
 import { describeCollection } from '../describeCollection';
 import { PineconeArgumentError } from '../../errors';
-import { ManagePodIndexesApi } from '../../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../../pinecone-generated-ts-fetch';
 import type {
   DescribeCollectionRequest,
   CollectionList,
@@ -23,7 +23,7 @@ const setupMocks = (
     describeCollection: fakeDescribeCollection,
     listCollections: fakeListCollections,
   };
-  return IOA as ManagePodIndexesApi;
+  return IOA as ManageIndexesApi;
 };
 
 describe('describeCollection', () => {

src/control/configureIndex.ts

@@ -1,5 +1,5 @@
 import {
-  ManagePodIndexesApi,
+  ManageIndexesApi,
   IndexModel,
   ConfigureIndexRequestSpecPod,
 } from '../pinecone-generated-ts-fetch';
@@ -18,7 +18,7 @@ const ConfigureIndexOptionsSchema = Type.Object(
   { additionalProperties: false }
 );
 
-export const configureIndex = (api: ManagePodIndexesApi) => {
+export const configureIndex = (api: ManageIndexesApi) => {
   const indexNameValidator = buildValidator(
     'The first argument to configureIndex',
     IndexNameSchema

src/control/createCollection.ts

@@ -1,7 +1,7 @@
 import {
   CollectionModel,
   CreateCollectionRequest,
-  ManagePodIndexesApi,
+  ManageIndexesApi,
 } from '../pinecone-generated-ts-fetch';
 import { buildConfigValidator } from '../validator';
 import { CollectionNameSchema, IndexNameSchema } from './types';
@@ -15,7 +15,7 @@ const CreateCollectionOptionsSchema = Type.Object(
   { additionalProperties: false }
 );
 
-export const createCollection = (api: ManagePodIndexesApi) => {
+export const createCollection = (api: ManageIndexesApi) => {
   const validator = buildConfigValidator(
     CreateCollectionOptionsSchema,
     'createCollection'

src/control/createIndex.ts

@@ -1,7 +1,7 @@
 import {
   CreateIndexRequest,
   IndexModel,
-  ManagePodIndexesApi,
+  ManageIndexesApi,
   CreateIndexRequestMetricEnum,
 } from '../pinecone-generated-ts-fetch';
 import { buildConfigValidator } from '../validator';
@@ -69,7 +69,7 @@ const CreateIndexOptionsSchema = Type.Object(
   { additionalProperties: false }
 );
 
-export const createIndex = (api: ManagePodIndexesApi) => {
+export const createIndex = (api: ManageIndexesApi) => {
   const validator = buildConfigValidator(
     CreateIndexOptionsSchema,
     'createIndex'
@@ -105,7 +105,7 @@ export const createIndex = (api: ManagePodIndexesApi) => {
 };
 
 const waitUntilIndexIsReady = async (
-  api: ManagePodIndexesApi,
+  api: ManageIndexesApi,
   indexName: string,
   seconds: number = 0
 ): Promise<IndexModel> => {

src/control/deleteCollection.ts

@@ -1,4 +1,4 @@
-import { ManagePodIndexesApi } from '../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../pinecone-generated-ts-fetch';
 import { buildConfigValidator } from '../validator';
 import { CollectionNameSchema } from './types';
 import type { CollectionName } from './types';
@@ -8,7 +8,7 @@ import type { CollectionName } from './types';
  */
 export type DeleteCollectionOptions = CollectionName;
 
-export const deleteCollection = (api: ManagePodIndexesApi) => {
+export const deleteCollection = (api: ManageIndexesApi) => {
   const validator = buildConfigValidator(
     CollectionNameSchema,
     'deleteCollection'

src/control/deleteIndex.ts

@@ -1,11 +1,11 @@
-import { ManagePodIndexesApi } from '../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../pinecone-generated-ts-fetch';
 import { buildConfigValidator } from '../validator';
 import { IndexName, IndexNameSchema } from './types';
 
 /** The name of index to delete */
 export type DeleteIndexOptions = IndexName;
 
-export const deleteIndex = (api: ManagePodIndexesApi) => {
+export const deleteIndex = (api: ManageIndexesApi) => {
   const validator = buildConfigValidator(IndexNameSchema, 'deleteIndex');
 
   return async (indexName: DeleteIndexOptions): Promise<void> => {

src/control/describeCollection.ts

@@ -1,5 +1,5 @@
 import {
-  ManagePodIndexesApi,
+  ManageIndexesApi,
   CollectionModel,
 } from '../pinecone-generated-ts-fetch';
 import { buildConfigValidator } from '../validator';
@@ -11,7 +11,7 @@ import type { CollectionName } from './types';
  */
 export type DescribeCollectionOptions = CollectionName;
 
-export const describeCollection = (api: ManagePodIndexesApi) => {
+export const describeCollection = (api: ManageIndexesApi) => {
   const validator = buildConfigValidator(
     CollectionNameSchema,
     'describeCollection'

src/control/describeIndex.ts

@@ -1,15 +1,12 @@
 import { buildConfigValidator } from '../validator';
-import {
-  IndexModel,
-  ManagePodIndexesApi,
-} from '../pinecone-generated-ts-fetch';
+import { IndexModel, ManageIndexesApi } from '../pinecone-generated-ts-fetch';
 import { IndexNameSchema } from './types';
 import type { IndexName } from './types';
 
 /** The name of the index to describe */
 export type DescribeIndexOptions = IndexName;
 
-export const describeIndex = (api: ManagePodIndexesApi) => {
+export const describeIndex = (api: ManageIndexesApi) => {
   const validator = buildConfigValidator(IndexNameSchema, 'describeIndex');
 
   const removeDeprecatedFields = (result: any) => {

src/control/indexOperationsBuilder.ts

@@ -1,5 +1,5 @@
 import {
-  ManagePodIndexesApi,
+  ManageIndexesApi,
   Configuration,
 } from '../pinecone-generated-ts-fetch';
 import {
@@ -14,7 +14,7 @@ import type { ConfigurationParameters as IndexOperationsApiConfigurationParamete
 
 export const indexOperationsBuilder = (
   config: PineconeConfiguration
-): ManagePodIndexesApi => {
+): ManageIndexesApi => {
   const { apiKey } = config;
   const controllerPath =
     normalizeUrl(config.controllerHostUrl) || 'https://api.pinecone.io';
@@ -31,5 +31,5 @@ export const indexOperationsBuilder = (
     middleware,
   };
 
-  return new ManagePodIndexesApi(new Configuration(apiConfig));
+  return new ManageIndexesApi(new Configuration(apiConfig));
 };

src/control/listCollections.ts

@@ -1,9 +1,9 @@
 import {
-  ManagePodIndexesApi,
+  ManageIndexesApi,
   CollectionList,
 } from '../pinecone-generated-ts-fetch';
 
-export const listCollections = (api: ManagePodIndexesApi) => {
+export const listCollections = (api: ManageIndexesApi) => {
   return async (): Promise<CollectionList> => {
     const results = await api.listCollections();
 

src/control/listIndexes.ts

@@ -1,6 +1,6 @@
-import { ManagePodIndexesApi, IndexList } from '../pinecone-generated-ts-fetch';
+import { ManageIndexesApi, IndexList } from '../pinecone-generated-ts-fetch';
 
-export const listIndexes = (api: ManagePodIndexesApi) => {
+export const listIndexes = (api: ManageIndexesApi) => {
   return async (): Promise<IndexList> => {
     const response = await api.listIndexes();
 

src/data/fetch.ts

@@ -1,7 +1,12 @@
 import { buildConfigValidator } from '../validator';
 import { VectorOperationsProvider } from './vectorOperationsProvider';
 import { RecordIdSchema } from './types';
-import type { PineconeRecord, RecordId, RecordMetadata } from './types';
+import type {
+  OperationUsage,
+  PineconeRecord,
+  RecordId,
+  RecordMetadata,
+} from './types';
 import { Type } from '@sinclair/typebox';
 
 const RecordIdsArray = Type.Array(RecordIdSchema, { minItems: 1 });
@@ -21,6 +26,9 @@ export type FetchResponse<T extends RecordMetadata = RecordMetadata> = {
 
   /** The namespace where records were fetched. */
   namespace: string;
+
+  /** The usage information for the fetch operation. */
+  usage?: OperationUsage;
 };
 
 export class FetchCommand<T extends RecordMetadata = RecordMetadata> {
@@ -46,6 +54,7 @@ export class FetchCommand<T extends RecordMetadata = RecordMetadata> {
     return {
       records: response.vectors ? response.vectors : {},
       namespace: response.namespace ? response.namespace : '',
+      ...(response.usage && { usage: response.usage }),
     } as FetchResponse<T>;
   }
 }

src/data/indexHostSingleton.ts

@@ -1,4 +1,4 @@
-import { ManagePodIndexesApi } from '../pinecone-generated-ts-fetch';
+import { ManageIndexesApi } from '../pinecone-generated-ts-fetch';
 import type { PineconeConfiguration } from './types';
 import type { IndexName } from '../control';
 import { describeIndex, indexOperationsBuilder } from '../control';
@@ -10,8 +10,7 @@ import { normalizeUrl } from '../utils';
 // and index, so we cache them in a singleton for reuse.
 export const IndexHostSingleton = (function () {
   const hostUrls = {}; // map of apiKey-indexName to hostUrl
-  let indexOperationsApi: InstanceType<typeof ManagePodIndexesApi> | null =
-    null;
+  let indexOperationsApi: InstanceType<typeof ManageIndexesApi> | null = null;
 
   const _describeIndex = async (
     config: PineconeConfiguration,

src/data/query.ts

@@ -1,5 +1,6 @@
 import { buildConfigValidator } from '../validator';
 import {
+  OperationUsage,
   RecordIdSchema,
   RecordSparseValuesSchema,
   RecordValues,
@@ -125,6 +126,9 @@ export type QueryResponse<T extends RecordMetadata = RecordMetadata> = {
 
   /** The namespace where the query was executed. */
   namespace: string;
+
+  /** The usage information for the query operation. */
+  usage?: OperationUsage;
 };
 
 export class QueryCommand<T extends RecordMetadata = RecordMetadata> {
@@ -150,6 +154,7 @@ export class QueryCommand<T extends RecordMetadata = RecordMetadata> {
     return {
       matches: matches as Array<ScoredPineconeRecord<T>>,
       namespace: this.namespace,
+      ...(results.usage && { usage: results.usage }),
     };
   }
 }

src/data/types.ts

@@ -120,3 +120,13 @@ export type PineconeRecord<T extends RecordMetadata = RecordMetadata> = {
    */
   metadata?: T;
 };
+
+/**
+ * Metadata detailing usage units for a specific operation.
+ */
+export type OperationUsage = {
+  /**
+   * The number of read units consumed by this operation.
+   */
+  readUnits?: string;
+};

src/pinecone-generated-ts-fetch/.openapi-generator/FILES

@@ -1,5 +1,5 @@
 .openapi-generator-ignore
-apis/ManagePodIndexesApi.ts
+apis/ManageIndexesApi.ts
 apis/VectorOperationsApi.ts
 apis/index.ts
 index.ts
@@ -40,6 +40,7 @@ models/SparseValues.ts
 models/UpdateRequest.ts
 models/UpsertRequest.ts
 models/UpsertResponse.ts
+models/Usage.ts
 models/Vector.ts
 models/index.ts
 runtime.ts

src/pinecone-generated-ts-fetch/apis/ManagePodIndexesApi.ts → src/pinecone-generated-ts-fetch/apis/ManageIndexesApi.ts

@@ -75,7 +75,7 @@ export interface DescribeIndexRequest {
 /**
  * 
  */
-export class ManagePodIndexesApi extends runtime.BaseAPI {
+export class ManageIndexesApi extends runtime.BaseAPI {
 
     /**
      * This operation specifies the pod type and number of replicas for an index.

src/pinecone-generated-ts-fetch/apis/index.ts

@@ -1,4 +1,4 @@
 /* tslint:disable */
 /* eslint-disable */
-export * from './ManagePodIndexesApi';
+export * from './ManageIndexesApi';
 export * from './VectorOperationsApi';