@data-fair/lib-common-types 1.10.6 → 1.11.0

package/catalog/.type/index.d.ts

@@ -5,9 +5,9 @@ export const schemaExports: string[]
 /**
  * The list of capabilities that a catalog can have.
  *  - import: The plugin can list some resources organized in folders and import them
- *  - search: The plugin can use a search param in the listResources method
- *  - pagination: The plugin can paginate the results of the listResources method
- *  - additionalFilters: The plugin can use additional filters in the listResources method
+ *  - search: The plugin can use the search param 'q' in the list method
+ *  - pagination: The plugin can paginate the results of the list method
+ *  - additionalFilters: The plugin can use additional filters in the list method
  *  - importConfig: The plugin gives an import configuration schema
  *  - publishDataset: The plugin can publish a dataset
  *  - deletePublication: The plugin can delete a dataset or a resource published in a remote catalog
@@ -86,10 +86,6 @@ export type Resource = {
  * via the `definition` "publication".
  */
 export type Publication = {
-  /**
-   * The URL of the publication site where the user will be redirected from the remote catalog
-   */
-  publicationSite?: string;
   /**
    * Dataset from the remote catalog, used if a local dataset is published as a dataset on a remote catalog. If it is defined during publication, then the remote dataset must be updated.
    */

package/catalog/index.d.ts

@@ -13,6 +13,29 @@ type BaseCatalogPlugin<TCatalogConfig, TCapabilities extends Capability[]> = {
     configSchema: TCatalogConfig;
     /** Function to validates the catalog configuration. */
     assertConfigValid(catalogConfig: any): asserts catalogConfig is TCatalogConfig;
+    /**
+     * Prepare function to extract secrets to cipher from the configuration,
+     * and dynamically update capabilities.
+     * This function is called when the catalog configuration is updated.
+     * It can be used to:
+     * - throw additional errors to validate the config
+     * - remove secrets from the config and store them in the secrets object :<br>
+     *      This function must copy the configuration fields to be encrypted into the secret object,
+     *      then replace these fields in the configuration with ****.
+     *      If the received configuration already contains ****, the secret should not be copied.
+     *      If the field is empty, it should delete the secret.
+     * - update the capabilities of the catalog based on the configuration
+     *
+     * @param context.catalogConfig The catalog configuration, that can contain secrets to extract
+     * @param context.capabilities The actuals capabilities of the catalog
+     * @param context.secrets The actuals deciphered secrets of the catalog
+     * @returns A promise that resolves to an object containing the catalog configuration, capabilities, and secrets.
+     */
+    prepare: (context: PrepareContext<TCatalogConfig, TCapabilities>) => Promise<{
+        catalogConfig?: TCatalogConfig;
+        capabilities?: TCapabilities;
+        secrets?: Record<string, string>;
+    }>;
 };
 /**
  * Type for catalog implementations that support listing and retrieving resources.
@@ -24,19 +47,22 @@ type BaseCatalogPlugin<TCatalogConfig, TCapabilities extends Capability[]> = {
 type WithImport<TCatalogConfig, TCapabilities extends Capability[]> = {
     /** List available folders and resources in the catalog. */
     list: (context: ListContext<TCatalogConfig, TCapabilities>) => Promise<{
+        /** The total number of items in the current folder */
         count: number;
+        /** The list of folders and resources in the current folder, filtered with the search and pagination parameters */
         results: (Folder | Resource)[];
+        /** The path to the current folder, including the current folder itself, used to navigate back */
         path: Folder[];
     }>;
     /** Get informations about a specific resource. */
-    getResource: (catalogConfig: TCatalogConfig, resourceId: string) => Promise<Resource | undefined>;
+    getResource: (context: GetResourceContext<TCatalogConfig>) => Promise<Resource | undefined>;
     /**
      * Download the resource to a temporary file from a context
      * @returns The path to the downloaded resource file, or undefined if the download failed
      */
     downloadResource: (context: DownloadResourceContext<TCatalogConfig>) => Promise<string | undefined>;
 } & (Includes<TCapabilities, 'additionalFilters'> extends true ? {
-    filtersSchema: Record<string, any>;
+    listFiltersSchema: Record<string, any>;
 } : {}) & (Includes<TCapabilities, 'importConfig'> extends true ? {
     importConfigSchema: Record<string, any>;
 } : {});
@@ -46,9 +72,10 @@ type WithPublishDataset<TCatalogConfig> = {
      * @param catalogConfig The configuration of the catalog
      * @param dataset The datafair dataset to publish
      * @param publication The publication to process
+     * @param publicationSite The site where the user will be redirected from the remote dataset
      * @returns A promise that is resolved when the dataset is published
      */
-    publishDataset: (catalogConfig: TCatalogConfig, dataset: object, publication: Publication) => Promise<Publication>;
+    publishDataset: (context: PublishDatasetContext<TCatalogConfig>) => Promise<Publication>;
 };
 type WithDeletePublication<TCatalogConfig> = {
     /**
@@ -57,39 +84,145 @@ type WithDeletePublication<TCatalogConfig> = {
      * @param datasetId The id of the remoteDataset to delete, or the dataset where the resource to delete is
      * @param resourceId The id of the resource to delete
      */
-    deleteDataset: (catalogConfig: TCatalogConfig, datasetId: string, resourceId?: string) => Promise<void>;
+    deleteDataset: (context: DeletePublicationContext<TCatalogConfig>) => Promise<void>;
+};
+/**
+ * Context for preparing a catalog configuration.
+ * @template TCatalogConfig - The type of the catalog configuration.
+ * @template TCapabilities - The capabilities of the catalog.
+ * @property catalogConfig - The catalog configuration, that can contain secrets to extract.
+ * @property capabilities - The actuals capabilities of the catalog.
+ * @property secrets - The actuals deciphered secrets of the catalog, if any.
+ */
+export type PrepareContext<TCatalogConfig, TCapabilities extends Capability[]> = {
+    /** The catalog configuration, that can contain secrets to extract */
+    catalogConfig: TCatalogConfig;
+    /** The actuals capabilities of the catalog */
+    capabilities: TCapabilities;
+    /** The actuals deciphered secrets of the catalog */
+    secrets: Record<string, string>;
 };
 export type ListContext<TCatalogConfig, TCapabilities extends Capability[]> = {
     /** The catalog configuration */
     catalogConfig: TCatalogConfig;
+    /** The deciphered secrets of the catalog */
+    secrets: Record<string, string>;
     /** The specific import configuration, if applicable */
     params: ListParams<TCapabilities>;
 };
+/**
+ * Parameters for listing resources in a catalog.
+ * @template TCapabilities - The capabilities of the catalog.
+ * @property currentFolderId - The ID of the current folder used to list subfolders and resources.
+ * @property q - The search field to filter resources when the 'search' capability is included.
+ * @property page - The page number for pagination when the 'pagination' capability is included.
+ * @property size - The number of items per page for pagination when the 'pagination' capability is included.
+ * @property others - Additional filters for the list method when the 'additionalFilters' capability is included.
+ */
 type ListParams<TCapabilities extends Capability[]> = {
     /** The current level folder is used to list subfolders and resources. */
     currentFolderId?: string;
-} & (Includes<TCapabilities, 'search'> extends true ? SearchParams : {}) & (Includes<TCapabilities, 'pagination'> extends true ? PaginationParams : {}) & (Includes<TCapabilities, 'additionalFilters'> extends true ? Record<string, string> : {});
+} & (Includes<TCapabilities, 'search'> extends true ? SearchParams : {}) & (Includes<TCapabilities, 'pagination'> extends true ? PaginationParams : {}) & (Includes<TCapabilities, 'additionalFilters'> extends true ? Record<string, string | number> : {});
+/** The params q is used to search resources */
 type SearchParams = {
     q?: string;
 };
+/** The params page and size are used for pagination */
 type PaginationParams = {
     page?: number;
     size?: number;
 };
+/**
+ * Context for getting a resource.
+ * @template TCatalogConfig - The type of the catalog configuration.
+ * @property catalogConfig - The catalog configuration.
+ * @property secrets - The deciphered secrets of the catalog.
+ * @property resourceId - The ID of the remote resource to get.
+ */
+export type GetResourceContext<TCatalogConfig> = {
+    /** The catalog configuration */
+    catalogConfig: TCatalogConfig;
+    /** The deciphered secrets of the catalog */
+    secrets: Record<string, string>;
+    /** The ID of the remote resource to get */
+    resourceId: string;
+};
+/**
+ * Context for downloading a resource.
+ * @template TCatalogConfig - The type of the catalog configuration.
+ * @property catalogConfig - The catalog configuration.
+ * @property secrets - The deciphered secrets of the catalog.
+ * @property importConfig - The specific import configuration, if applicable.
+ * @property resourceId - The ID of the remote resource to download.
+ * @property tmpDir - The path to the working directory where the resource will be downloaded.
+ */
 export type DownloadResourceContext<TCatalogConfig> = {
     /** The catalog configuration */
     catalogConfig: TCatalogConfig;
+    /** The deciphered secrets of the catalog */
+    secrets: Record<string, string>;
     /** The specific import configuration, if applicable */
     importConfig: Record<string, any>;
     /** The ID of the remote resource to download */
     resourceId: string;
-    /** The path to the working directory */
+    /** The path to the working directory where the resource will be downloaded */
     tmpDir: string;
 };
+/**
+ * Context for publishing a dataset.
+ * @template TCatalogConfig - The type of the catalog configuration.
+ * @property catalogConfig - The catalog configuration.
+ * @property secrets - The deciphered secrets of the catalog.
+ * @property dataset - The datafair dataset to publish.
+ * @property publication - The publication to process.
+ * @property publicationSite - The site where the user will be redirected from the remote dataset.
+ * @property publicationSite.title - The title of the publication site.
+ * @property publicationSite.url - The URL of the publication site.
+ * @property publicationSite.datasetUrlTemplate - The template for the URL to view the dataset in the publication site, using url-template syntax.
+ */
+export type PublishDatasetContext<TCatalogConfig> = {
+    /** The catalog configuration */
+    catalogConfig: TCatalogConfig;
+    /** The deciphered secrets of the catalog */
+    secrets: Record<string, string>;
+    /** The datafair dataset to publish */
+    dataset: Record<string, any>;
+    /** The publication to process */
+    publication: Publication;
+    /** The site where the user will be redirected from the remote dataset. */
+    publicationSite: {
+        /** The title of the publication site */
+        title: string;
+        /** The URL of the publication site */
+        url: string;
+        /** The template for the URL to view the dataset in the publication site, using url-template syntax. */
+        datasetUrlTemplate: string;
+    };
+};
+/**
+ * Context for deleting a publication.
+ * @template TCatalogConfig - The type of the catalog configuration.
+ * @property catalogConfig - The catalog configuration.
+ * @property secrets - The deciphered secrets of the catalog.
+ * @property datasetId - The ID of the remote dataset to delete, or the dataset where the resource to delete is.
+ * @property resourceId - The ID of the resource to delete, if applicable.
+ */
+export type DeletePublicationContext<TCatalogConfig> = {
+    /** The catalog configuration */
+    catalogConfig: TCatalogConfig;
+    /** The deciphered secrets of the catalog */
+    secrets: Record<string, string>;
+    /** The ID of the remote dataset to delete, or the dataset where the resource to delete is */
+    datasetId: string;
+    /** The ID of the resource to delete, if applicable */
+    resourceId?: string;
+};
 /**
  * The metadata of the catalog plugin.
  * @template TCapabilities - This ensures that the `capabilities` field in the metadata is of the same type as `TCapabilities`.
+ * @property capabilities - The capabilities of the catalog plugin, which is an array of `Capability` types.
  */
 export type CatalogMetadata<TCapabilities extends Capability[]> = Metadata & {
+    /** The capabilities of the catalog plugin */
     capabilities: TCapabilities;
 };

package/catalog/schema.d.ts

@@ -108,10 +108,6 @@ declare const _default: {
             additionalProperties: boolean;
             description: string;
             properties: {
-                publicationSite: {
-                    type: string;
-                    description: string;
-                };
                 remoteDataset: {
                     type: string;
                     required: string[];

package/catalog/schema.js

@@ -9,9 +9,9 @@ export default {
       type: 'string',
       description: `The list of capabilities that a catalog can have.
  - import: The plugin can list some resources organized in folders and import them
- - search: The plugin can use a search param in the listResources method
- - pagination: The plugin can paginate the results of the listResources method
- - additionalFilters: The plugin can use additional filters in the listResources method
+ - search: The plugin can use the search param 'q' in the list method
+ - pagination: The plugin can paginate the results of the list method
+ - additionalFilters: The plugin can use additional filters in the list method
  - importConfig: The plugin gives an import configuration schema
  - publishDataset: The plugin can publish a dataset
  - deletePublication: The plugin can delete a dataset or a resource published in a remote catalog`,
@@ -123,10 +123,6 @@ export default {
       additionalProperties: false,
       description: 'A small object that contains the information needed to publish or update a dataset or a resource',
       properties: {
-        publicationSite: {
-          type: 'string',
-          description: 'The URL of the publication site where the user will be redirected from the remote catalog'
-        },
         remoteDataset: {
           type: 'object',
           required: ['id'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@data-fair/lib-common-types",
-  "version": "1.10.6",
+  "version": "1.11.0",
   "description": "Shared schemas and built type definitions in the data-fair stack.",
   "main": "index.js",
   "scripts": {