From 5da199b39428efb1510f20e9646a07597afe6673 Mon Sep 17 00:00:00 2001 From: Patrick Bradshaw Date: Tue, 27 Oct 2020 09:37:11 -0500 Subject: [PATCH] Response definitions for R2 apis --- src/service/R2/commonTypes.js | 27 ++++ src/service/R2/delivery.js | 17 ++- src/service/R2/legal.js | 52 ++++++-- src/service/R2/query.js | 21 ++- src/service/R2/storage.js | 76 +++++++---- types/service/R2/commonTypes.d.ts | 69 ++++++++++ types/service/R2/delivery.d.ts | 41 +++++- types/service/R2/legal.d.ts | 205 +++++++++++++++++++++++++++--- types/service/R2/query.d.ts | 104 ++++++++++++++- types/service/R2/storage.d.ts | 186 +++++++++++++++++++++++---- 10 files changed, 714 insertions(+), 84 deletions(-) create mode 100644 src/service/R2/commonTypes.js create mode 100644 types/service/R2/commonTypes.d.ts diff --git a/src/service/R2/commonTypes.js b/src/service/R2/commonTypes.js new file mode 100644 index 0000000..8f3e777 --- /dev/null +++ b/src/service/R2/commonTypes.js @@ -0,0 +1,27 @@ +/** + * Access control list for OSDU records + * @typedef {Object} OsduAccessControlList + * @property {string[]} viewers - Users and groups that can view the record + * @property {string[]} owners - Users and groups that own the record + */ + +/** + * Legal information for OSDU records + * @typedef {Object} OsduLegalInformation + * @property {string[]} legaltags - Legal tags associated with the record + * @property {string[]} otherRelevantDataCountries - Other countries associated with the data that are legally relevant + * @property {string} status - The legal status of the record's data + */ + +/** + * Single record returned by a query result + * @typedef {Object} OsduRecord + * @property {Object.} data - Freeform data for the record. Refer to schema definitions for available properties + * @property {string} kind - Schema that the record conforms to + * @property {string} namespace - Grouping that schema comes from + * @property {OsduLegalInformation} legal - Legal information for the record. Refer to schema definitions for available properties + * @property {string} id - Record identifier + * @property {OsduAccessControlList} acl - Access control list + * @property {string} type - Record type + * @property {number} version - The version of this record + */ \ No newline at end of file diff --git a/src/service/R2/delivery.js b/src/service/R2/delivery.js index b16b1fe..367d17b 100644 --- a/src/service/R2/delivery.js +++ b/src/service/R2/delivery.js @@ -17,11 +17,24 @@ class OsduR2DeliveryService extends OsduR2BaseService { constructor(osdu_client, data_partition) { super(osdu_client, data_partition); } - + + /** + * Individual processed file + * @typedef {Object} ProcessedFile + * @property {string} signedUrl - The signed url to retrieve this file + * @property {string} unsignedUrl - The storage url for the file that does not have presigned permissions + * @property {string} kind - The kind for this file + */ + /** + * Response to delivery of requested files + * @typedef {Object} SignedUrls + * @property {Object.} processed - Dictionary of processed file + * @property {string[]} unprocessed - List of srns for the files that have not been processed + */ /** * Get signed urls for the data file underlying the specified OSDU File records * @param {string[]} srns - SRN identifiers of the files for which you wish to retrieve signed urls - * @returns {Object} The API Response + * @returns {SignedUrls} The API Response */ async getSignedUrls(srns) { return await this._client.post(`/api/delivery/v2/GetFileSignedUrl`, { srns }, this._dataPartition); diff --git a/src/service/R2/legal.js b/src/service/R2/legal.js index ba8d440..8f49d34 100644 --- a/src/service/R2/legal.js +++ b/src/service/R2/legal.js @@ -17,11 +17,36 @@ class OsduR2LegalService extends OsduR2BaseService { constructor(osdu_client, data_partition) { super(osdu_client, data_partition); } + + /** + * Legal tag properties + * @typedef {Object} LegalTagProperties + * @property {string[]} countryOfOrigin + * @property {string} contractId + * @property {string} expirationDate + * @property {string} originator + * @property {string} dataType + * @property {string} securityClassification + * @property {string} personalData + * @property {string} exportClassification + */ + /** + * Legal tag model + * @typedef {Object} LegalTag + * @property {string} name - Name identifier for the legal tag + * @property {string} description - Brief description of what the legal tag represents + * @property {LegalTagProperties} properties - Properties of the legal tag + */ + /** + * Response to retieval of multiple legal tags + * @typedef {Object} LegalTagList + * @property {LegalTag[]} legalTags - List of available legal tags + */ // TODO: Define response types /** * Get all supported legal tags in the given data partition - * @returns {Object} The API Response + * @returns {LegalTagList} The API Response */ async listLegalTags() { return await this._client.get(`/api/legal/v1/legaltags`, this._dataPartition); @@ -29,15 +54,26 @@ class OsduR2LegalService extends OsduR2BaseService { /** * Get requested legal tags in the given data partition * @param {string[]} names - The list of tag names you wish to retrieve - * @returns {Object} The API Response + * @returns {LegalTagList} The API Response */ async getLegalTags(names) { return await this._client.post(`/api/legal/v1/legaltags:batchRetrieve`, { names }, this._dataPartition); } + /** + * Legal tag model + * @typedef {Object} InvalidLegalTag + * @property {string} name - Name identifier for the legal tag + * @property {string} reason - Reason why the legal tag is invalid + */ + /** + * Response to retieval of multiple legal tags + * @typedef {Object} ValidateLegalTagsResponse + * @property {InvalidLegalTag[]} invalidLegalTags - List of invalid legal tags + */ /** * Validate requested legal tags in the given data partition * @param {string[]} names - The list of tag names you wish to validate - * @returns {Object} The API Response + * @returns {ValidateLegalTagsResponse} The API Response */ async validateLegalTags(names) { return await this._client.post(`/api/legal/v1/legaltags:validate`, { names }, this._dataPartition); @@ -45,14 +81,14 @@ class OsduR2LegalService extends OsduR2BaseService { /** * Retrieve a specific legal tag in the given data partition * @param {string} name - The name of the tag you wish to retrieve - * @returns {Object} The API Response + * @returns {LegalTag} The API Response */ async getLegalTag(name) { return await this._client.get(`/api/legal/v1/legaltags/${name}`, this._dataPartition); } /** * List the allowed legal tag properties and values in the given data partition - * @returns {Object} The API Response + * @returns {Object.|string>} The API Response */ async getLegalTagProperties() { return await this._client.get(`/api/legal/v1/legaltags:properties`, this._dataPartition); @@ -60,7 +96,7 @@ class OsduR2LegalService extends OsduR2BaseService { /** * Create a new legal tag in the given data partition * @param {Object} tagData - The JSON representation of the tag you wish to create - * @returns {Object} The API Response + * @returns {LegalTag} The API Response */ async createLegalTag(tagData) { return await this._client.get(`/api/legal/v1/legaltags`, tagData, this._dataPartition); @@ -68,7 +104,7 @@ class OsduR2LegalService extends OsduR2BaseService { /** * Update an existing legal tag in the given data partition * @param {Object} tagData - The JSON representation of the tag you wish to update - * @returns {Object} The API Response + * @returns {LegalTag} The API Response */ async updateLegalTag(tagData) { return await this._client.put(`/api/legal/v1/legaltags`, tagData, this._dataPartition); @@ -76,7 +112,7 @@ class OsduR2LegalService extends OsduR2BaseService { /** * Delete an existing legal tag in the given data partition * @param {string} tagData - The name of the tag you wish to delete - * @returns {Object} The API Response + * @returns {number} The API Response */ async deleteLegalTag(name) { return await this._client.delete(`/api/legal/v1/legaltags/${name}`, this._dataPartition); diff --git a/src/service/R2/query.js b/src/service/R2/query.js index 0a51b1c..71b5701 100644 --- a/src/service/R2/query.js +++ b/src/service/R2/query.js @@ -18,10 +18,25 @@ class OsduR2QueryService extends OsduR2BaseService { super(osdu_client, data_partition); } + /** + * Results for particular aggregation grouping within the given query + * @typedef {Object} OsduAggregationItem + * @property {string} key - Identifier for the aggregation + * @property {number} count - Number of items that match this aggregation key + */ + /** + * Response to OSDU query + * @typedef {Object} OsduQueryResults + * @property {OsduRecord[]} results - List of query result records + * @property {OsduAggregationItem[]|null} aggregations - List of aggregated records + * @property {number} totalCount - Total number of records matched by the query + * @property {string} [cursor] - Page marker to resume query at next page + */ + /** * Get OSDU records that match the given query constraints * @param {Object} query_params - Query parameters built using the [OsduQueryBuilder]{@link OsduQueryBuilder} - * @returns {Object} The API Response + * @returns {OsduQueryResults} The API Response */ async query(query_params) { if (!query_params.offset) { @@ -33,7 +48,7 @@ class OsduR2QueryService extends OsduR2BaseService { * Get OSDU records that match the given query constraints * - Allow specification of a cursor for paged queries * @param {Object} query_params - Query parameters built using the [OsduQueryBuilder]{@link OsduQueryBuilder} - * @returns {Object} The API Response + * @returns {OsduQueryResults} The API Response */ async queryWithPaging(query_params, cursor) { if (!query_params.limit) { @@ -50,7 +65,7 @@ class OsduR2QueryService extends OsduR2BaseService { * - Will page internally and aggregate results until no more pages are found * - Note that this may make multiple network requests if multiple pages are found * @param {Object} query_params - Query parameters built using the [OsduQueryBuilder]{@link OsduQueryBuilder} - * @returns {Object} The API Response + * @returns {OsduQueryResults} The API Response */ async queryAll(query_params) { var output = { diff --git a/src/service/R2/storage.js b/src/service/R2/storage.js index adbcbae..b94c8e2 100644 --- a/src/service/R2/storage.js +++ b/src/service/R2/storage.js @@ -20,10 +20,17 @@ class OsduR2StorageService extends OsduR2BaseService { // Records // TODO: Define response types + /** + * API response for GetRecords + * @typedef {Object} OsduGetRecordsResponse + * @property {OsduRecord[]} records - List of valid records + * @property {string[]} invalidRecords - List of IDs for invalid records + * @property {string[]} retryRecords - List of records that failed to retrieve and should be retried + */ /** * Get OSDU records for the specified ids * @param {string[]} record_ids - Record identifiers of the OSDU records to retrieve - * @returns {Object} The API Response + * @returns {OsduGetRecordsResponse} The API Response */ async getRecords(record_ids) { return await this._client.post(`/api/storage/v2/query/records`, { @@ -33,15 +40,21 @@ class OsduR2StorageService extends OsduR2BaseService { /** * Get OSDU records for the specified id * @param {string} record_id - Record identifier of the OSDU record to retrieve - * @returns {Object} The API Response + * @returns {OsduRecord} The API Response */ async getRecord(record_id) { return await this._client.get(`/api/storage/v2/records/${record_id}`, this._dataPartition); } + /** + * API response for GetRecordVersions + * @typedef {Object} GetRecordVersionsResponse + * @property {string} recordId - The id of the record requested + * @property {number[]} versions - Available versions for this record + */ /** * Get OSDU record versions for the specified id * @param {string} record_id - Record identifier of the OSDU record to retrieve version data - * @returns {Object} The API Response + * @returns {GetRecordVersionsResponse} The API Response */ async getRecordVersions(record_id) { return await this._client.get(`/api/storage/v2/records/versions/${record_id}`, this._dataPartition); @@ -50,15 +63,22 @@ class OsduR2StorageService extends OsduR2BaseService { * Get OSDU record for the specified id at the specified version * @param {string} record_id - Record identifier of the OSDU record to retrieve * @param {string} version - Version id to retrieve - * @returns {Object} The API Response + * @returns {OsduRecord} The API Response */ async getRecordVersion(record_id, version) { return await this._client.get(`/records/${record_id}/${version}`, this._dataPartition); } + /** + * API response for StoreRecords + * @typedef {Object} OsduStoreRecordsResponse + * @property {number} recordCount - Number of records stored + * @property {string[]} recordIds - IDs of the records stored + * @property {string[]} skippedRecordIds - IDs of records skipped and not stored + */ /** * Upsert the provided records * @param {Object[]} records - List of JSON representations of the records to upsert - * @returns {Object} The API Response + * @returns {OsduStoreRecordsResponse} The API Response */ async storeRecords(records) { return await this._client.post(`/api/storage/v2/records`, records, this._dataPartition) @@ -66,34 +86,46 @@ class OsduR2StorageService extends OsduR2BaseService { /** * Delete OSDU record * @param {string} record_id - Record identifier of the OSDU record to delete - * @returns {Object} The API Response + * @returns {number} The API Response */ async deleteRecord(record_id) { return await this._client.delete(`/api/storage/v2/records/${record_id}`, this._dataPartition); } - // Manifest + // Schemas /** - * Ingest a manifest containing linked records - * @param {Object} manifest - JSON representation of the manifest to process and ingest - * @returns {Object} The API Response + * API response to QueryAllKinds + * @typedef {Object} OsduQueryAllKindsResponse + * @property {string|null} cursor - Marker to resume query for all kinds from end of this query + * @property {string[]} results - List of available kinds */ - async ingestManifest(manifest) { - return await this._client.post(`/api/storage/v2/manifest`, manifest, this._dataPartition); - } - - // Schemas /** * Retrieve a list of all supported record kinds * @returns {Object} The API Response + * @param {number} [limit=100] - The maximum number of kinds to return (up to 100) + * @param {string} [cursor=""] - Marker to resume query for all kinds from end of previous query */ - async queryAllKinds() { - return await this._client.get(`/api/storage/v2/query/kinds`, this._dataPartition); + async queryAllKinds(limit = 100, cursor = "") { + return await this._client.get(`/api/storage/v2/query/kinds?limit=${limit}${cursor ? `&cursor=${cursor}` : ''}`, this._dataPartition); } + /** + * Property definition for an OSDU schema + * @typedef {Object} OsduSchemaProperty + * @property {string} path - Flat path to access the property + * @property {string} kind - Type of the property + * @property {Object} ext - Extensions + */ + /** + * API response to GetSchema + * @typedef {Object} OsduGetSchemaResponse + * @property {string} kind - Name of the kind for this schema + * @property {OsduSchemaProperty[]} schema - List of schema properties + * @property {OsduSchemaProperty[]|null} ext - List of extension properties + */ /** * Get OSDU schema for a given kind * @param {string} kind - Name of the kind to retrieve the schema - * @returns {Object} The API Response + * @returns {OsduGetSchemaResponse} The API Response */ async getSchema(kind) { return await this._client.get(`/api/storage/v2/schemas/${kind}`, this._dataPartition); @@ -101,9 +133,9 @@ class OsduR2StorageService extends OsduR2BaseService { /** * Create a new schema to register a new kind * @param {string} kind - Name of the new kind to create - * @param {Object} schema - JSON representation of the kind's schema - * @param {Object} ext - JSON representation of the schema extensions - * @returns {Object} The API Response + * @param {OsduSchemaProperty[]} schema - JSON representation of the kind's schema + * @param {OsduSchemaProperty[]|null} ext - JSON representation of the schema extensions + * @returns {number} The API Response. 201 for successful creation */ async createSchema(kind, schema, ext) { return await this._client.post(`/api/storage/v2/schemas`, { kind, schema, ext }, this._dataPartition); @@ -111,7 +143,7 @@ class OsduR2StorageService extends OsduR2BaseService { /** * Delete a kind and it's associated schema * @param {string} kind - Name of the kind to delete - * @returns {Object} The API Response + * @returns {number} The API Response. 204 for successful deletion */ async deleteSchema(kind) { return await this._client.delete(`/api/storage/v2/schemas/${kind}`, this._dataPartition); diff --git a/types/service/R2/commonTypes.d.ts b/types/service/R2/commonTypes.d.ts new file mode 100644 index 0000000..26b3ba2 --- /dev/null +++ b/types/service/R2/commonTypes.d.ts @@ -0,0 +1,69 @@ +/** + * Access control list for OSDU records + */ +type OsduAccessControlList = { + /** + * - Users and groups that can view the record + */ + viewers: string[]; + /** + * - Users and groups that own the record + */ + owners: string[]; +}; +/** + * Legal information for OSDU records + */ +type OsduLegalInformation = { + /** + * - Legal tags associated with the record + */ + legaltags: string[]; + /** + * - Other countries associated with the data that are legally relevant + */ + otherRelevantDataCountries: string[]; + /** + * - The legal status of the record's data + */ + status: string; +}; +/** + * Single record returned by a query result + */ +type OsduRecord = { + /** + * - Freeform data for the record. Refer to schema definitions for available properties + */ + data: { + [x: string]: string; + }; + /** + * - Schema that the record conforms to + */ + kind: string; + /** + * - Grouping that schema comes from + */ + namespace: string; + /** + * - Legal information for the record. Refer to schema definitions for available properties + */ + legal: OsduLegalInformation; + /** + * - Record identifier + */ + id: string; + /** + * - Access control list + */ + acl: OsduAccessControlList; + /** + * - Record type + */ + type: string; + /** + * - The version of this record + */ + version: number; +}; diff --git a/types/service/R2/delivery.d.ts b/types/service/R2/delivery.d.ts index 9a13d1c..235818d 100644 --- a/types/service/R2/delivery.d.ts +++ b/types/service/R2/delivery.d.ts @@ -15,10 +15,47 @@ declare class OsduR2DeliveryService extends OsduR2DeliveryService_base { * @param {string} data_partition - The data partition against which requests will be made */ constructor(osdu_client: any, data_partition: string); + /** + * Individual processed file + * @typedef {Object} ProcessedFile + * @property {string} signedUrl - The signed url to retrieve this file + * @property {string} unsignedUrl - The storage url for the file that does not have presigned permissions + * @property {string} kind - The kind for this file + */ + /** + * Response to delivery of requested files + * @typedef {Object} SignedUrls + * @property {Object.} processed - Dictionary of processed file + * @property {string[]} unprocessed - List of srns for the files that have not been processed + */ /** * Get signed urls for the data file underlying the specified OSDU File records * @param {string[]} srns - SRN identifiers of the files for which you wish to retrieve signed urls - * @returns {Object} The API Response + * @returns {SignedUrls} The API Response */ - getSignedUrls(srns: string[]): any; + getSignedUrls(srns: string[]): { + /** + * - Dictionary of processed file + */ + processed: { + [x: string]: { + /** + * - The signed url to retrieve this file + */ + signedUrl: string; + /** + * - The storage url for the file that does not have presigned permissions + */ + unsignedUrl: string; + /** + * - The kind for this file + */ + kind: string; + }; + }; + /** + * - List of srns for the files that have not been processed + */ + unprocessed: string[]; + }; } diff --git a/types/service/R2/legal.d.ts b/types/service/R2/legal.d.ts index db0c638..421b344 100644 --- a/types/service/R2/legal.d.ts +++ b/types/service/R2/legal.d.ts @@ -15,50 +15,223 @@ declare class OsduR2LegalService extends OsduR2LegalService_base { * @param {string} data_partition - The data partition against which requests will be made */ constructor(osdu_client: any, data_partition: string); + /** + * Legal tag properties + * @typedef {Object} LegalTagProperties + * @property {string[]} countryOfOrigin + * @property {string} contractId + * @property {string} expirationDate + * @property {string} originator + * @property {string} dataType + * @property {string} securityClassification + * @property {string} personalData + * @property {string} exportClassification + */ + /** + * Legal tag model + * @typedef {Object} LegalTag + * @property {string} name - Name identifier for the legal tag + * @property {string} description - Brief description of what the legal tag represents + * @property {LegalTagProperties} properties - Properties of the legal tag + */ + /** + * Response to retieval of multiple legal tags + * @typedef {Object} LegalTagList + * @property {LegalTag[]} legalTags - List of available legal tags + */ /** * Get all supported legal tags in the given data partition - * @returns {Object} The API Response + * @returns {LegalTagList} The API Response */ - listLegalTags(): any; + listLegalTags(): { + /** + * - List of available legal tags + */ + legalTags: { + /** + * - Name identifier for the legal tag + */ + name: string; + /** + * - Brief description of what the legal tag represents + */ + description: string; + /** + * - Properties of the legal tag + */ + properties: { + countryOfOrigin: string[]; + contractId: string; + expirationDate: string; + originator: string; + dataType: string; + securityClassification: string; + personalData: string; + exportClassification: string; + }; + }[]; + }; /** * Get requested legal tags in the given data partition * @param {string[]} names - The list of tag names you wish to retrieve - * @returns {Object} The API Response + * @returns {LegalTagList} The API Response + */ + getLegalTags(names: string[]): { + /** + * - List of available legal tags + */ + legalTags: { + /** + * - Name identifier for the legal tag + */ + name: string; + /** + * - Brief description of what the legal tag represents + */ + description: string; + /** + * - Properties of the legal tag + */ + properties: { + countryOfOrigin: string[]; + contractId: string; + expirationDate: string; + originator: string; + dataType: string; + securityClassification: string; + personalData: string; + exportClassification: string; + }; + }[]; + }; + /** + * Legal tag model + * @typedef {Object} InvalidLegalTag + * @property {string} name - Name identifier for the legal tag + * @property {string} reason - Reason why the legal tag is invalid + */ + /** + * Response to retieval of multiple legal tags + * @typedef {Object} ValidateLegalTagsResponse + * @property {InvalidLegalTag[]} invalidLegalTags - List of invalid legal tags */ - getLegalTags(names: string[]): any; /** * Validate requested legal tags in the given data partition * @param {string[]} names - The list of tag names you wish to validate - * @returns {Object} The API Response + * @returns {ValidateLegalTagsResponse} The API Response */ - validateLegalTags(names: string[]): any; + validateLegalTags(names: string[]): { + /** + * - List of invalid legal tags + */ + invalidLegalTags: { + /** + * - Name identifier for the legal tag + */ + name: string; + /** + * - Reason why the legal tag is invalid + */ + reason: string; + }[]; + }; /** * Retrieve a specific legal tag in the given data partition * @param {string} name - The name of the tag you wish to retrieve - * @returns {Object} The API Response + * @returns {LegalTag} The API Response */ - getLegalTag(name: string): any; + getLegalTag(name: string): { + /** + * - Name identifier for the legal tag + */ + name: string; + /** + * - Brief description of what the legal tag represents + */ + description: string; + /** + * - Properties of the legal tag + */ + properties: { + countryOfOrigin: string[]; + contractId: string; + expirationDate: string; + originator: string; + dataType: string; + securityClassification: string; + personalData: string; + exportClassification: string; + }; + }; /** * List the allowed legal tag properties and values in the given data partition - * @returns {Object} The API Response + * @returns {Object.|string>} The API Response */ - getLegalTagProperties(): any; + getLegalTagProperties(): { + [x: string]: { + [x: string]: string; + } | string; + }; /** * Create a new legal tag in the given data partition * @param {Object} tagData - The JSON representation of the tag you wish to create - * @returns {Object} The API Response + * @returns {LegalTag} The API Response */ - createLegalTag(tagData: any): any; + createLegalTag(tagData: any): { + /** + * - Name identifier for the legal tag + */ + name: string; + /** + * - Brief description of what the legal tag represents + */ + description: string; + /** + * - Properties of the legal tag + */ + properties: { + countryOfOrigin: string[]; + contractId: string; + expirationDate: string; + originator: string; + dataType: string; + securityClassification: string; + personalData: string; + exportClassification: string; + }; + }; /** * Update an existing legal tag in the given data partition * @param {Object} tagData - The JSON representation of the tag you wish to update - * @returns {Object} The API Response + * @returns {LegalTag} The API Response */ - updateLegalTag(tagData: any): any; + updateLegalTag(tagData: any): { + /** + * - Name identifier for the legal tag + */ + name: string; + /** + * - Brief description of what the legal tag represents + */ + description: string; + /** + * - Properties of the legal tag + */ + properties: { + countryOfOrigin: string[]; + contractId: string; + expirationDate: string; + originator: string; + dataType: string; + securityClassification: string; + personalData: string; + exportClassification: string; + }; + }; /** * Delete an existing legal tag in the given data partition * @param {string} tagData - The name of the tag you wish to delete - * @returns {Object} The API Response + * @returns {number} The API Response */ - deleteLegalTag(name: any): any; + deleteLegalTag(name: any): number; } diff --git a/types/service/R2/query.d.ts b/types/service/R2/query.d.ts index 1ced3ec..7b7b4ce 100644 --- a/types/service/R2/query.d.ts +++ b/types/service/R2/query.d.ts @@ -15,25 +15,117 @@ declare class OsduR2QueryService extends OsduR2QueryService_base { * @param {string} data_partition - The data partition against which requests will be made */ constructor(osdu_client: any, data_partition: string); + /** + * Results for particular aggregation grouping within the given query + * @typedef {Object} OsduAggregationItem + * @property {string} key - Identifier for the aggregation + * @property {number} count - Number of items that match this aggregation key + */ + /** + * Response to OSDU query + * @typedef {Object} OsduQueryResults + * @property {OsduRecord[]} results - List of query result records + * @property {OsduAggregationItem[]|null} aggregations - List of aggregated records + * @property {number} totalCount - Total number of records matched by the query + * @property {string} [cursor] - Page marker to resume query at next page + */ /** * Get OSDU records that match the given query constraints * @param {Object} query_params - Query parameters built using the [OsduQueryBuilder]{@link OsduQueryBuilder} - * @returns {Object} The API Response + * @returns {OsduQueryResults} The API Response */ - query(query_params: any): any; + query(query_params: any): { + /** + * - List of query result records + */ + results: OsduRecord[]; + /** + * - List of aggregated records + */ + aggregations: { + /** + * - Identifier for the aggregation + */ + key: string; + /** + * - Number of items that match this aggregation key + */ + count: number; + }[]; + /** + * - Total number of records matched by the query + */ + totalCount: number; + /** + * - Page marker to resume query at next page + */ + cursor?: string; + }; /** * Get OSDU records that match the given query constraints * - Allow specification of a cursor for paged queries * @param {Object} query_params - Query parameters built using the [OsduQueryBuilder]{@link OsduQueryBuilder} - * @returns {Object} The API Response + * @returns {OsduQueryResults} The API Response */ - queryWithPaging(query_params: any, cursor: any): any; + queryWithPaging(query_params: any, cursor: any): { + /** + * - List of query result records + */ + results: OsduRecord[]; + /** + * - List of aggregated records + */ + aggregations: { + /** + * - Identifier for the aggregation + */ + key: string; + /** + * - Number of items that match this aggregation key + */ + count: number; + }[]; + /** + * - Total number of records matched by the query + */ + totalCount: number; + /** + * - Page marker to resume query at next page + */ + cursor?: string; + }; /** * Get all OSDU records that match the given query constraints * - Will page internally and aggregate results until no more pages are found * - Note that this may make multiple network requests if multiple pages are found * @param {Object} query_params - Query parameters built using the [OsduQueryBuilder]{@link OsduQueryBuilder} - * @returns {Object} The API Response + * @returns {OsduQueryResults} The API Response */ - queryAll(query_params: any): any; + queryAll(query_params: any): { + /** + * - List of query result records + */ + results: OsduRecord[]; + /** + * - List of aggregated records + */ + aggregations: { + /** + * - Identifier for the aggregation + */ + key: string; + /** + * - Number of items that match this aggregation key + */ + count: number; + }[]; + /** + * - Total number of records matched by the query + */ + totalCount: number; + /** + * - Page marker to resume query at next page + */ + cursor?: string; + }; } diff --git a/types/service/R2/storage.d.ts b/types/service/R2/storage.d.ts index a7c1ccb..63f2619 100644 --- a/types/service/R2/storage.d.ts +++ b/types/service/R2/storage.d.ts @@ -15,72 +15,208 @@ declare class OsduR2StorageService extends OsduR2StorageService_base { * @param {string} data_partition - The data partition against which requests will be made */ constructor(osdu_client: any, data_partition: string); + /** + * API response for GetRecords + * @typedef {Object} OsduGetRecordsResponse + * @property {OsduRecord[]} records - List of valid records + * @property {string[]} invalidRecords - List of IDs for invalid records + * @property {string[]} retryRecords - List of records that failed to retrieve and should be retried + */ /** * Get OSDU records for the specified ids * @param {string[]} record_ids - Record identifiers of the OSDU records to retrieve - * @returns {Object} The API Response + * @returns {OsduGetRecordsResponse} The API Response */ - getRecords(record_ids: string[]): any; + getRecords(record_ids: string[]): { + /** + * - List of valid records + */ + records: OsduRecord[]; + /** + * - List of IDs for invalid records + */ + invalidRecords: string[]; + /** + * - List of records that failed to retrieve and should be retried + */ + retryRecords: string[]; + }; /** * Get OSDU records for the specified id * @param {string} record_id - Record identifier of the OSDU record to retrieve - * @returns {Object} The API Response + * @returns {OsduRecord} The API Response + */ + getRecord(record_id: string): OsduRecord; + /** + * API response for GetRecordVersions + * @typedef {Object} GetRecordVersionsResponse + * @property {string} recordId - The id of the record requested + * @property {number[]} versions - Available versions for this record */ - getRecord(record_id: string): any; /** * Get OSDU record versions for the specified id * @param {string} record_id - Record identifier of the OSDU record to retrieve version data - * @returns {Object} The API Response + * @returns {GetRecordVersionsResponse} The API Response */ - getRecordVersions(record_id: string): any; + getRecordVersions(record_id: string): { + /** + * - The id of the record requested + */ + recordId: string; + /** + * - Available versions for this record + */ + versions: number[]; + }; /** * Get OSDU record for the specified id at the specified version * @param {string} record_id - Record identifier of the OSDU record to retrieve * @param {string} version - Version id to retrieve - * @returns {Object} The API Response + * @returns {OsduRecord} The API Response + */ + getRecordVersion(record_id: string, version: string): OsduRecord; + /** + * API response for StoreRecords + * @typedef {Object} OsduStoreRecordsResponse + * @property {number} recordCount - Number of records stored + * @property {string[]} recordIds - IDs of the records stored + * @property {string[]} skippedRecordIds - IDs of records skipped and not stored */ - getRecordVersion(record_id: string, version: string): any; /** * Upsert the provided records * @param {Object[]} records - List of JSON representations of the records to upsert - * @returns {Object} The API Response + * @returns {OsduStoreRecordsResponse} The API Response */ - storeRecords(records: any[]): any; + storeRecords(records: any[]): { + /** + * - Number of records stored + */ + recordCount: number; + /** + * - IDs of the records stored + */ + recordIds: string[]; + /** + * - IDs of records skipped and not stored + */ + skippedRecordIds: string[]; + }; /** * Delete OSDU record * @param {string} record_id - Record identifier of the OSDU record to delete - * @returns {Object} The API Response + * @returns {number} The API Response */ - deleteRecord(record_id: string): any; + deleteRecord(record_id: string): number; /** - * Ingest a manifest containing linked records - * @param {Object} manifest - JSON representation of the manifest to process and ingest - * @returns {Object} The API Response + * API response to QueryAllKinds + * @typedef {Object} OsduQueryAllKindsResponse + * @property {string|null} cursor - Marker to resume query for all kinds from end of this query + * @property {string[]} results - List of available kinds */ - ingestManifest(manifest: any): any; /** * Retrieve a list of all supported record kinds * @returns {Object} The API Response + * @param {number} [limit=100] - The maximum number of kinds to return (up to 100) + * @param {string} [cursor=""] - Marker to resume query for all kinds from end of previous query + */ + queryAllKinds(limit?: number, cursor?: string): any; + /** + * Property definition for an OSDU schema + * @typedef {Object} OsduSchemaProperty + * @property {string} path - Flat path to access the property + * @property {string} kind - Type of the property + * @property {Object} ext - Extensions + */ + /** + * API response to GetSchema + * @typedef {Object} OsduGetSchemaResponse + * @property {string} kind - Name of the kind for this schema + * @property {OsduSchemaProperty[]} schema - List of schema properties + * @property {OsduSchemaProperty[]|null} ext - List of extension properties */ - queryAllKinds(): any; /** * Get OSDU schema for a given kind * @param {string} kind - Name of the kind to retrieve the schema - * @returns {Object} The API Response + * @returns {OsduGetSchemaResponse} The API Response */ - getSchema(kind: string): any; + getSchema(kind: string): { + /** + * - Name of the kind for this schema + */ + kind: string; + /** + * - List of schema properties + */ + schema: { + /** + * - Flat path to access the property + */ + path: string; + /** + * - Type of the property + */ + kind: string; + /** + * - Extensions + */ + ext: any; + }[]; + /** + * - List of extension properties + */ + ext: { + /** + * - Flat path to access the property + */ + path: string; + /** + * - Type of the property + */ + kind: string; + /** + * - Extensions + */ + ext: any; + }[]; + }; /** * Create a new schema to register a new kind * @param {string} kind - Name of the new kind to create - * @param {Object} schema - JSON representation of the kind's schema - * @param {Object} ext - JSON representation of the schema extensions - * @returns {Object} The API Response + * @param {OsduSchemaProperty[]} schema - JSON representation of the kind's schema + * @param {OsduSchemaProperty[]|null} ext - JSON representation of the schema extensions + * @returns {number} The API Response. 201 for successful creation */ - createSchema(kind: string, schema: any, ext: any): any; + createSchema(kind: string, schema: { + /** + * - Flat path to access the property + */ + path: string; + /** + * - Type of the property + */ + kind: string; + /** + * - Extensions + */ + ext: any; + }[], ext: { + /** + * - Flat path to access the property + */ + path: string; + /** + * - Type of the property + */ + kind: string; + /** + * - Extensions + */ + ext: any; + }[]): number; /** * Delete a kind and it's associated schema * @param {string} kind - Name of the kind to delete - * @returns {Object} The API Response + * @returns {number} The API Response. 204 for successful deletion */ - deleteSchema(kind: string): any; + deleteSchema(kind: string): number; }