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

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

@@ -11,6 +11,7 @@ export const schemaExports: string[]
  *  - 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
+ *  - thumbnail: The plugin provides a thumbnail image
  *
  * This interface was referenced by `CatalogsCommonTypes`'s JSON-Schema
  * via the `definition` "capability".
@@ -22,7 +23,8 @@ export type Capability =
   | "additionalFilters"
   | "importConfig"
   | "publishDataset"
-  | "deletePublication";
+  | "deletePublication"
+  | "thumbnail";
 
 export type CatalogsCommonTypes = {}
 /**
@@ -44,6 +46,10 @@ export type Metadata = {
    * The list of capabilities that a catalog can have.
    */
   capabilities: Capability[];
+  /**
+   * Optional path of the thumbnail image from the root of the plugin to be displayed in the UI.
+   */
+  thumbnailPath?: string;
 }
 /**
  * This interface was referenced by `CatalogsCommonTypes`'s JSON-Schema
@@ -65,19 +71,77 @@ 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;
+  /**
+   * 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?: {
+    /**
+     * Short title for the license
+     */
+    title: string;
+    /**
+     * The URL where the license can be read
+     */
+    href: string;
+  };
+  /**
+   * 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;
-  keywords?: string[];
-  image?: string;
-  license?: string;
-  frequency?: string;
-  private?: boolean;
 }
 /**
  * A small object that contains the information needed to publish or update a dataset or a resource

package/catalog/index.d.ts

@@ -50,17 +50,17 @@ type WithImport<TCatalogConfig, TCapabilities extends Capability[]> = {
         /** 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)[];
+        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: (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
+     * 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 ? {
     listFiltersSchema: Record<string, any>;
 } : {}) & (Includes<TCapabilities, 'importConfig'> extends true ? {
@@ -133,22 +133,7 @@ type PaginationParams = {
     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.
+ * 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.
@@ -156,7 +141,7 @@ export type GetResourceContext<TCatalogConfig> = {
  * @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> = {
+export type GetResourceContext<TCatalogConfig> = {
     /** The catalog configuration */
     catalogConfig: TCatalogConfig;
     /** The deciphered secrets of the catalog */
@@ -225,4 +210,6 @@ export type DeletePublicationContext<TCatalogConfig> = {
 export type CatalogMetadata<TCapabilities extends Capability[]> = Metadata & {
     /** The capabilities of the catalog plugin */
     capabilities: TCapabilities;
-};
+} & (Includes<TCapabilities, 'thumbnail'> extends true ? {
+    thumbnailPath: string;
+} : {});

package/catalog/schema.d.ts

@@ -31,6 +31,10 @@ declare const _default: {
                         $ref: string;
                     };
                 };
+                thumbnailPath: {
+                    description: string;
+                    type: string;
+                };
             };
         };
         folder: {
@@ -61,45 +65,66 @@ 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;
+                    additionalProperties: boolean;
+                    required: string[];
+                    properties: {
+                        title: {
+                            type: string;
+                            description: string;
+                        };
+                        href: {
+                            type: string;
+                            description: 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;
                 };
             };
         };

package/catalog/schema.js

@@ -14,7 +14,8 @@ export default {
  - 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`,
+ - deletePublication: The plugin can delete a dataset or a resource published in a remote catalog
+ - thumbnail: The plugin provides a thumbnail image`,
       enum: [
         'import',
         'search',
@@ -22,7 +23,8 @@ export default {
         'additionalFilters',
         'importConfig',
         'publishDataset',
-        'deletePublication'
+        'deletePublication',
+        'thumbnail'
       ]
     },
     metadata: {
@@ -45,6 +47,10 @@ export default {
           items: {
             $ref: '#/$defs/capability'
           }
+        },
+        thumbnailPath: {
+          description: 'Optional path of the thumbnail image from the root of the plugin to be displayed in the UI.',
+          type: 'string',
         }
       }
     },
@@ -67,7 +73,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 +81,68 @@ 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',
         },
-        format: {
-          type: 'string'
+        filePath: {
+          type: 'string',
+          description: 'The path to the downloaded resource file.',
         },
-        url: {
-          type: 'string'
+        format: {
+          type: 'string',
+          description: 'The format of the resource, e.g. csv, json, xml, etc. It is displayed in the UI of catalogs.',
         },
-        fileName: {
-          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']
         },
-        mimeType: {
-          type: 'string'
+        image: {
+          type: 'string',
+          description: 'The URL of the image representing the resource, if available'
         },
-        size: {
-          type: 'number'
+        license: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['title', 'href'],
+          properties: {
+            title: {
+              type: 'string',
+              description: 'Short title for the license'
+            },
+            href: {
+              type: 'string',
+              description: 'The URL where the license can be read'
+            }
+          }
         },
         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.'
         }
       }
     },

package/package.json

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

package/processings.js

@@ -1 +1 @@
-export {}
+export {};

package/ws.js

@@ -1 +1 @@
-export {}
+export {};