@data-fair/lib-common-types 1.10.6 → 1.12.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
@@ -65,19 +65,68 @@ export type Resource = {
    * The unique identifier of the resource, independent of the folder it is in
    */
   id: string;
+  /**
+   * The title of the resource
+   */
   title: string;
-  type: "resource";
   description?: string;
+  /**
+   * The path to the downloaded resource file.
+   */
+  filePath: string;
+  /**
+   * The format of the resource, e.g. csv, json, xml, etc. It is displayed in the UI of catalogs.
+   */
   format: string;
-  url: string;
-  fileName?: string;
-  mimeType?: string;
-  size?: number;
-  keywords?: string[];
+  /**
+   * The frequency of the resource updates, if available. It can be one of the following values: triennial, biennial, annual, semiannual, threeTimesAYear, quarterly, bimonthly, monthly, semimonthly, biweekly, threeTimesAMonth, weekly, semiweekly, threeTimesAWeek, daily, continuous or irregular.
+   */
+  frequency?:
+    | ""
+    | "triennial"
+    | "biennial"
+    | "annual"
+    | "semiannual"
+    | "threeTimesAYear"
+    | "quarterly"
+    | "bimonthly"
+    | "monthly"
+    | "semimonthly"
+    | "biweekly"
+    | "threeTimesAMonth"
+    | "weekly"
+    | "semiweekly"
+    | "threeTimesAWeek"
+    | "daily"
+    | "continuous"
+    | "irregular";
+  /**
+   * The URL of the image representing the resource, if available
+   */
   image?: string;
   license?: string;
-  frequency?: string;
-  private?: boolean;
+  /**
+   * The list of keywords associated with the resource, if available
+   */
+  keywords?: string[];
+  /**
+   * The Mime type of the resource, if available
+   */
+  mimeType?: string;
+  /**
+   * The URL where the original data can be found
+   */
+  origin?: string;
+  /**
+   * The schema of the resource, if available
+   */
+  schema?: {
+    [k: string]: unknown;
+  };
+  /**
+   * The size of the resource in bytes, if available. It is displayed in the UI of catalogs.
+   */
+  size?: number;
 }
 /**
  * A small object that contains the information needed to publish or update a dataset or a resource
@@ -86,10 +135,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;
-        results: (Folder | Resource)[];
+        /** The list of folders and resources in the current folder, filtered with the search and pagination parameters */
+        results: (Folder | Pick<Resource, 'id' | 'title' | 'description' | 'format' | 'mimeType' | 'origin' | 'size'> & {
+            type: '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>;
     /**
-     * Download the resource to a temporary file from a context
-     * @returns The path to the downloaded resource file, or undefined if the download failed
+     * Download the resource to a temporary file and return the metadata of the resource.
+     * @returns A promise that resolves to the metadata of the resource, including the path to the downloaded file.
      */
-    downloadResource: (context: DownloadResourceContext<TCatalogConfig>) => Promise<string | undefined>;
+    getResource: (context: GetResourceContext<TCatalogConfig>) => Promise<Resource | 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,130 @@ 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;
 };
-export type DownloadResourceContext<TCatalogConfig> = {
+/**
+ * Context for get and 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 GetResourceContext<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

@@ -61,45 +61,54 @@ declare const _default: {
                 };
                 title: {
                     type: string;
-                };
-                type: {
-                    const: string;
+                    description: string;
                 };
                 description: {
                     type: string;
                 };
-                format: {
+                filePath: {
                     type: string;
+                    description: string;
                 };
-                url: {
+                format: {
                     type: string;
+                    description: string;
                 };
-                fileName: {
+                frequency: {
                     type: string;
+                    description: string;
+                    enum: string[];
                 };
-                mimeType: {
+                image: {
                     type: string;
+                    description: string;
                 };
-                size: {
+                license: {
                     type: string;
                 };
                 keywords: {
                     type: string;
+                    description: string;
                     items: {
                         type: string;
                     };
                 };
-                image: {
+                mimeType: {
                     type: string;
+                    description: string;
                 };
-                license: {
+                origin: {
                     type: string;
+                    description: string;
                 };
-                frequency: {
+                schema: {
                     type: string;
+                    additionalProperties: boolean;
+                    description: string;
                 };
-                private: {
+                size: {
                     type: string;
+                    description: string;
                 };
             };
         };
@@ -108,10 +117,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`,
@@ -67,7 +67,7 @@ export default {
     resource: {
       type: 'object',
       description: 'The normalized resource to import from a remote catalog to Data Fair',
-      required: ['id', 'title', 'type', 'format', 'url'],
+      required: ['id', 'title', 'filePath', 'format'],
       additionalProperties: false,
       properties: {
         id: {
@@ -75,46 +75,56 @@ export default {
           description: 'The unique identifier of the resource, independent of the folder it is in'
         },
         title: {
-          type: 'string'
-        },
-        type: {
-          const: 'resource',
+          type: 'string',
+          description: 'The title of the resource'
         },
         description: {
           type: 'string',
         },
+        filePath: {
+          type: 'string',
+          description: 'The path to the downloaded resource file.',
+        },
         format: {
-          type: 'string'
+          type: 'string',
+          description: 'The format of the resource, e.g. csv, json, xml, etc. It is displayed in the UI of catalogs.',
         },
-        url: {
-          type: 'string'
+        // https://www.w3.org/TR/vocab-dcat-2/#Property:dataset_frequency and https://www.dublincore.org/specifications/dublin-core/collection-description/frequency/
+        frequency: {
+          type: 'string',
+          description: 'The frequency of the resource updates, if available. It can be one of the following values: triennial, biennial, annual, semiannual, threeTimesAYear, quarterly, bimonthly, monthly, semimonthly, biweekly, threeTimesAMonth, weekly, semiweekly, threeTimesAWeek, daily, continuous or irregular.',
+          enum: ['', 'triennial', 'biennial', 'annual', 'semiannual', 'threeTimesAYear', 'quarterly', 'bimonthly', 'monthly', 'semimonthly', 'biweekly', 'threeTimesAMonth', 'weekly', 'semiweekly', 'threeTimesAWeek', 'daily', 'continuous', 'irregular']
         },
-        fileName: {
-          type: 'string'
+        image: {
+          type: 'string',
+          description: 'The URL of the image representing the resource, if available'
         },
-        mimeType: {
+        license: {
           type: 'string'
         },
-        size: {
-          type: 'number'
-        },
         keywords: {
           type: 'array',
+          description: 'The list of keywords associated with the resource, if available',
           items: {
             type: 'string'
           }
         },
-        image: {
-          type: 'string'
+        mimeType: {
+          type: 'string',
+          description: 'The Mime type of the resource, if available'
         },
-        license: {
-          type: 'string'
+        origin: {
+          type: 'string',
+          description: 'The URL where the original data can be found'
         },
-        frequency: {
-          type: 'string'
+        schema: {
+          type: 'object',
+          additionalProperties: true,
+          description: 'The schema of the resource, if available'
         },
-        private: {
-          type: 'boolean'
+        size: {
+          type: 'number',
+          description: 'The size of the resource in bytes, if available. It is displayed in the UI of catalogs.'
         }
       }
     },
@@ -123,10 +133,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.12.0",
   "description": "Shared schemas and built type definitions in the data-fair stack.",
   "main": "index.js",
   "scripts": {