@dmptool/utils 1.0.5 → 1.0.6

package/README.md

@@ -61,14 +61,14 @@ Provides access to CloudFormation stack outputs.
 
 For example, our CloudFormation stack for the S3 buckets outputs the names of each bucket. This code allows a Lambda Function to access those bucket names.
 
-Environment variable requirements:
-- `AWS_REGION` The AWS region where the DynamoDB table is located
-
 ### Example usage
 ```typescript
-import { getExport } from '@dmptool/utils';
+import { getExport, initializeLogger, LogLevelEnum } from '@dmptool/utils';
 
-const tableName = await getExport('DynamoTableNames');
+// Initialize a logger
+const logger: Logger = initializeLogger('exampleSSM', LogLevelEnum.DEBUG);
+
+const tableName = await getExport(logger, 'DynamoTableNames');
 console.log(tableName);
 ```
 
@@ -95,13 +95,6 @@ A DMP SK for a specific version of the DMP Tool extensions looks like this: `EXT
 
 These keys are attached to the DMP JSON when persisting it to DynamoDB and removed when returning it from DynamoDB.
 
-Environment variable requirements:
-- `AWS_REGION` The AWS region where the DynamoDB table is located
-- `DOMAIN_NAME` The domain name of the application
-- `DYNAMODB_TABLE_NAME` The name of the DynamoDB table
-- `DYNAMO_MAX_ATTEMPTS` The maximum number of times to retry a DynamoDB operation (defaults to 3)
-- `VERSION_GRACE_PERIOD` The number of seconds to wait before considering a change should generate a version snapshot (defaults to 7200000 => 2 hours)
-
 ## Example Usage:
 ```typescript
 import { DMPToolDMPType } from '@dmptool/types';
@@ -112,13 +105,23 @@ import {
   DMP_LATEST_VERSION,
   getDMPs,
   getDMPVersions,
+  initializeLogger,
+  LogLevelEnum,
   tombstoneDMP,
   updateDMP
 } from '@dmptool/utils';
 
-process.env.AWS_REGION = 'eu-west-1';
-process.env.DOMAIN_NAME = 'my-application.org';
-process.env.DYNAMODB_TABLE_NAME = 'my-dynamo-table';
+// Initialize a logger
+const logger: Logger = initializeLogger('exampleSSM', LogLevelEnum.DEBUG);
+
+const dynamoConfig = {
+  logger,
+  region: 'us-west-2',
+  tableName: 'my-dynamo-table',
+  maxAttempts: 3
+}
+
+const gracePeriodInMS = 7200000;
 
 const dmpId = '123456789';
 
@@ -159,13 +162,13 @@ const dmpObj: DMPToolDMPType = {
 }
 
 // First make sure the DMP doesn't already exist
-const exists = await DMPExists(dmpId);
+const exists = await DMPExists(dynamoConfig, dmpId);
 if (exists) {
   console.log('DMP already exists');
 
 } else {
   // Create the DMP
-  const created: DMPToolDMPType = await createDMP(dmpId, dmpObj);
+  const created: DMPToolDMPType = await createDMP(dynamoConfig, domainName, dmpId, dmpObj);
   if (!created) { 
     console.log('Failed to create DMP');
   
@@ -174,17 +177,20 @@ if (exists) {
     dmpObj.dmp.modified = '2026-01-10T03:43:11Z';
 
     // Update the DMP
-    const updated: DMPToolDMPType = await updateDMP(dmpObj);
+    const updated: DMPToolDMPType = await updateDMP(dynamoConfig, domainName, dmpObj, gracePeriodInMS);
     if (!updated) { 
       console.log('Failed to update DMP');
       
     } else {
       // Fetch the DMP version timestamps (should only be two)
-      const versions = await getDMPVersions(dmpId);
+      const versions = await getDMPVersions(dynamoConfig, dmpId);
       console.log(versions);
       
-      // Fetch the latest version of the DMP
-      const latest = await getDMP(dmpId, DMP_LATEST_VERSION);
+      // Fetch the latest version of the DMP (RDA Common Standard with DMP Tool extensions)
+      const latest = await getDMPs(dynamoConfig, domainName, dmpId, DMP_LATEST_VERSION);
+      // Fetch the latest version of the DMP (RDA Common Standard only)
+      const rdaOnly = await getDMPs(dynamoConfig, domainName, dmpId, DMP_LATEST_VERSION, false);
+      
       if (!latest) { 
         console.log('Failed to fetch latest version of DMP');
         
@@ -192,11 +198,11 @@ if (exists) {
         // If the DMP has a `registered` timestamp then it is published and can be tombstoned not deleted
         // Since our example is not, we include this code here for reference only
         
-        // const tombstoned = await tombstoneDMP(dmpId);
+        // const tombstoned = await tombstoneDMP(dynamoConfig, domainName, dmpId);
         // console.log( tombstoned
         
         // Delete the DMP (can be done because the DMP is not published)
-        const deleted = await deleteDMP(dmpId);
+        const deleted = await deleteDMP(dynamoConfig, domainName, dmpId);
         console.log(deleted);
       }
     }
@@ -207,31 +213,30 @@ if (exists) {
 
 This code can be used to publish events to the EventBridge.
 
-Environment variable requirements:
-- `AWS_REGION` - The AWS region where the Lambda Function is running
-- `EVENTBRIDGE_BUS_NAME` - The ARN of the EventBridge Bus to publish events to
-
 ### Example usage
 ```typescript
-import { publishMessage } from '@dmptool/utils';
+import { initializeLogger, LogLevelEnum, publishMessage } from '@dmptool/utils';
 
-process.env.AWS_REGION = 'us-west-2';
+const region = 'us-west-2';
 
-const topicArn = 'arn:aws:sns:us-east-1:123456789012:my-topic';
+// Initialize a logger
+const logger: Logger = initializeLogger('exampleSSM', LogLevelEnum.DEBUG);
+
+const busName = 'arn:aws:sns:us-east-1:123456789012:my-topic';
 
 // See the documentation for the AWS Lambda you are trying to invoke to determine what the
 // `detail-type` and `detail` payload should look like.
-const message = {
-  'detail-type': 'my-event',  
-  detail: {
-    property1: 'value1',
-    property2: 'value2'
-  }
-}
+const source = 'my-application';
+const detailType = 'my-event';  
+const detail = { property1: 'value1', property2: 'value2' }
 
 const response = await publishMessage(
-  message,
-  topicArn
+  logger,
+  busName,
+  source,
+  detailType,
+  detail,
+  region
 );
 
 if (response.statusCode === 200) {
@@ -330,12 +335,6 @@ Details about the RDA Common Metadata Standard can be found in the JSON examples
 
 **Current RDA Common Metadata Standard Version:** v1.2
 
-Environment variable requirements:
-- `AWS_REGION` - The AWS region where the Lambda Function is running
-- `ENV`: The AWS environment (e.g. `dev`, `stg`, `prd`)
-- `APPLICATION_NAME`: The name of your application (NO spaces!, this is used to construct identifier namespaces)
-- `DOMAIN_NAME`: The domain name of your application
-
 ### Notes
 
 **DMP IDs:**
@@ -366,15 +365,33 @@ The `narrative` property in the JSON object represents the Template, Sections, Q
 ### Example usage
 ```typescript
 import { DMPToolDMPType } from '@dmptool/types';
-import { planToDMPCommonStandard } from '@dmptool/utils';
+import { EnvironmentEnum, initializeLogger, LogLevelEnum, planToDMPCommonStandard } from '@dmptool/utils';
 
-process.env.AWS_REGION = 'us-west-2';
-process.env.ENV = 'stg';
-process.env.APPLICATION_NAME = 'your-application';
-process.env.DOMAIN_NAME = 'your-domain.com';
+const region = 'us-west-2';
+const env = EnvironmentEnum.DEV;
+const applicationName = 'your-application';
+const domainName = 'your-domain.com';
+
+// Initialize a logger
+const logger: Logger = initializeLogger('exampleSSM', LogLevelEnum.DEBUG);
+
+const rdsConfig = {
+  logger,
+  host: 'some-rds-instance.us-east-1.rds.amazonaws.com',
+  port: 3306,
+  user: 'my_user',
+  password: 'open-sesame',
+  database: 'my_database'
+}
 
 const planId = '12345';
-const dmp: DMPToolDMPType = await planToDMPCommonStandard(planId);
+const dmp: DMPToolDMPType = await planToDMPCommonStandard(
+  rdsConfig,
+  applicationName,
+  domainName,
+  planId,
+  env
+);
 ```
 
 ## Example of a minimal JSON object:
@@ -674,28 +691,25 @@ This code can be used by to provide access to the RDS MySQL database.
 
 It provides a simple `queryTable` function which can be used to query a table. Similar to the way we do so within the Apollo server backend code.
 
-Environment variable requirements:
-- `AWS_REGION` - The AWS region where the Lambda Function is running
-- `RDS_HOST` The endpoint of the RDS instance
-- `RDS_PORT` The port (defaults to 3306)
-- `RDS_USER` The name of the user (defaults to "root")
-- `RDS_PASSWORD` The user's password
-- `RDS_DATABASE` The name of the database
-
 ### Example usage
 ```typescript
-import { queryTable } from '@dmptool/utils';
+import { initializeLogger, LogLevelEnum, queryTable } from '@dmptool/utils';
 
-process.env.AWS_REGION = 'us-west-2';
-process.env.RDS_HOST = 'some-rds-instance.us-east-1.rds.amazonaws.com';
-process.env.RDS_PORT = '3306';
-process.env.RDS_USER = 'my_user';
-process.env.RDS_PASSWORD = 'open-sesame';
-process.env.RDS_DATABASE = 'my_database';
+// Initialize a logger
+const logger: Logger = initializeLogger('exampleSSM', LogLevelEnum.DEBUG);
+
+const config = {
+  logger,
+  host: 'some-rds-instance.us-east-1.rds.amazonaws.com',
+  port: 3306,
+  user: 'my_user',
+  password: 'open-sesame',
+  database: 'my_database',
+}
 
 const sql = 'SELECT * FROM some_table WHERE id = ?';
 const id = 1234;
-const resp = await queryTable(sql, [planId.toString()])
+const resp = await queryTable(config, sql, [planId.toString()])
 
 if (resp && Array.isArray(resp.results) && resp.results.length > 0) {
   console.log('It worked!', resp.results[0]);
@@ -719,9 +733,9 @@ Environment variable requirements:
 
 ### Example usage
 ```typescript
-import { getObject, getPresignedURL, listBuckets, putObject } from '@dmptool/utils';
+import { getObject, getPresignedURL, initializeLogger, listBuckets, LogLevelEnum, putObject } from '@dmptool/utils';
 
-process.env.AWS_REGION = 'us-west-2';
+const region = 'us-west-2';
 
 const bucketName = 'my-bucket';
 const objectKey = 'my-object.txt';
@@ -729,31 +743,37 @@ const objectKey = 'my-object.txt';
 const fileName = 'my-file.json.gz'
 const gzippedData = zlib.gzipSync(JSON.stringify({ testing: { foo: 'bar' } }));
 
+// Initialize a logger
+const logger: Logger = initializeLogger('exampleSSM', LogLevelEnum.DEBUG);
+
 // List the objects to verify that we're able to access the bucket)
-const s3Objects = await listObjects(bucketName, '');
+const s3Objects = await listObjects(logger, bucketName, '', region);
 console.log('Objects in bucket:', s3Objects);
 
 // First put the item into the bucket
 const response = await putObject(
+  logger,
   bucketName, 
   fileName, 
   gzippedData, 
-  'application/json', 'gzip'
+  'application/json', 
+  'gzip',
+  region
 );
 
 if (response) {
   console.log('Object uploaded successfully');
 
   // Get the object we just uploaded from the bucket
-  const object = await getObject(bucketName, objectKey);
+  const object = await getObject(logger, bucketName, objectKey, region);
   console.log('Object fetched from bucket:', object);
   
   // Generate a presigned URL to access the object from outside the VPC
-  const url = await getPresignedURL(bucketName, objectKey);
+  const url = await getPresignedURL(logger, bucketName, objectKey, false, region);
   console.log('Presigned URL to fetch the Object:', url);
   
   // Generate a presigned URL to put an object into the bucket from outside the VPC
-  const putURL = await getPresignedURL(bucketName, `2nd-${objectKey}`, true);
+  const putURL = await getPresignedURL(logger, bucketName, `2nd-${objectKey}`, true, region);
   console.log('Presigned URL to put a new the Object into the bucket', putURL);
 } else {
   console.log('Failed to upload object');
@@ -768,11 +788,11 @@ The code will use that value to construct the appropriate prefix for the key. Fo
 
 ### Example usage
 ```typescript
-import { logger, EnvironmentEnum, getSSMParameter, LogLevelEnum } from '@dmptool/utils';
+import {EnvironmentEnum, initializeLogger, getSSMParameter, LogLevelEnum } from '@dmptool/utils';
 
 process.env.AWS_REGION = 'us-west-2';
 
-// Initialize the logger
+// Initialize a logger
 const logger: Logger = initializeLogger('exampleSSM', LogLevelEnum.DEBUG);
 
 const paramName = 'RdsDatabase';

package/dist/cloudFormation.d.ts

@@ -1,8 +1,11 @@
+import { Logger } from 'pino';
 /**
  * Fetch the value for the specified CloudFormation stack export.
  *
+ * @param logger The logger to use for logging.
  * @param name The name of the CloudFormation stack export to fetch.
  * @returns The value of the CloudFormation stack export, or undefined if the
  * export could not be found.
+ * @throws Error if there was an error fetching the export.
  */
-export declare const getExport: (name: string) => Promise<string | undefined>;
+export declare const getExport: (logger: Logger, name: string) => Promise<string | undefined>;

package/dist/cloudFormation.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getExport = void 0;
+const general_1 = require("./general");
 const client_cloudformation_1 = require("@aws-sdk/client-cloudformation");
 // If you want to make a CloudFormation stack output available for to this Lambda Layer, you need to
 // ensure that your CloudFormation template "exports" the output variable. Note that you should try
@@ -40,15 +41,25 @@ const loadExports = async () => {
 /**
  * Fetch the value for the specified CloudFormation stack export.
  *
+ * @param logger The logger to use for logging.
  * @param name The name of the CloudFormation stack export to fetch.
  * @returns The value of the CloudFormation stack export, or undefined if the
  * export could not be found.
+ * @throws Error if there was an error fetching the export.
  */
-const getExport = async (name) => {
-    await loadExports();
-    const response = cfExports.find((exp) => {
-        return (exp === null || exp === void 0 ? void 0 : exp.Name.toLowerCase().trim()) === name.toLowerCase().trim();
-    });
-    return response ? response.Value : undefined;
+const getExport = async (logger, name) => {
+    try {
+        logger.debug({ name }, 'Fetching CloudFormation export');
+        await loadExports();
+        const response = cfExports.find((exp) => {
+            return (exp === null || exp === void 0 ? void 0 : exp.Name.toLowerCase().trim()) === name.toLowerCase().trim();
+        });
+        return response ? response.Value : undefined;
+    }
+    catch (error) {
+        const errMsg = (0, general_1.toErrorMessage)(error);
+        logger.fatal({ name, error: errMsg }, 'Error fetching CloudFormation export');
+        throw new Error(errMsg);
+    }
 };
 exports.getExport = getExport;

package/dist/dynamo.d.ts

@@ -1,6 +1,13 @@
+import { Logger } from 'pino';
 import { DMPToolDMPType } from '@dmptool/types';
 export declare const DMP_LATEST_VERSION = "latest";
 export declare const DMP_TOMBSTONE_VERSION = "tombstone";
+export interface DynamoConnectionParams {
+    logger: Logger;
+    region: string;
+    tableName: string;
+    maxAttempts: number;
+}
 interface DMPVersionType {
     PK: string;
     SK: string;
@@ -9,24 +16,28 @@ interface DMPVersionType {
 /**
  * Lightweight query just to check if the DMP exists.
  *
- * @param dmpId
+ * @param dynamoConnectionParams the DynamoDB connection parameters
+ * @param dmpId the DMP ID (e.g. 'doi.org/11.12345/A1B2C3D4')
  * @returns true if the DMP exists, false otherwise.
  * @throws DMPToolDynamoError if the record could not be fetched due to an error
  */
-export declare const DMPExists: (dmpId: string) => Promise<boolean>;
+export declare const DMPExists: (dynamoConnectionParams: DynamoConnectionParams, dmpId: string) => Promise<boolean>;
 /**
  * Fetch the version timestamps (including DMP_LATEST_VERSION) for the specified DMP ID.
  *
- * @param dmpId
+ * @param dynamoConnectionParams the DynamoDB connection parameters
+ * @param dmpId the DMP ID (e.g. 'doi.org/11.12345/A1B2C3D4')
  * @returns The timestamps as strings (e.g. '2026-11-01T13:08:19Z' or 'latest')
  * @throws DMPToolDynamoError if the records could not be fetched due to an error
  */
-export declare const getDMPVersions: (dmpId: string) => Promise<DMPVersionType[] | []>;
+export declare const getDMPVersions: (dynamoConnectionParams: DynamoConnectionParams, dmpId: string) => Promise<DMPVersionType[] | []>;
 /**
  * Fetch the RDA Common Standard metadata record with DMP Tool specific extensions
  * for the specified DMP ID.
  *
- * @param dmpId
+ * @param dynamoConnectionParams the DynamoDB connection parameters
+ * @param domainName The domain name of the DMPTool instance (e.g. 'dmptool.org')
+ * @param dmpId the DMP ID (e.g. 'doi.org/11.12345/A1B2C3D4')
  * @param version The version of the DMP metadata record to persist
  * (e.g. '2026-11-01T13:08:19Z').
  * If not provided, the latest version will be used. Defaults to DMP_LATEST_VERSION.
@@ -36,13 +47,15 @@ export declare const getDMPVersions: (dmpId: string) => Promise<DMPVersionType[]
  * metadata or an empty array if none were found.
  * @throws DMPToolDynamoError if the records could not be fetched due to an error
  */
-export declare const getDMPs: (dmpId: string, version: string | null, includeExtensions?: boolean) => Promise<DMPToolDMPType[] | []>;
+export declare const getDMPs: (dynamoConnectionParams: DynamoConnectionParams, domainName: string, dmpId: string, version: string | null, includeExtensions?: boolean) => Promise<DMPToolDMPType[] | []>;
 /**
  * Persists the specified DMP metadata record to the DynamoDB table.
  * This function will handle the separation of RDA Common Standard and DMP Tool
  * specific metadata.
  *
- * @param dmpId The DMP ID (e.g. '123456789')
+ * @param dynamoConnectionParams The DynamoDB connection parameters
+ * @param domainName The domain name of the DMPTool instance (e.g. 'dmptool.org')
+ * @param dmpId the DMP ID (e.g. 'doi.org/11.12345/A1B2C3D4')
  * @param dmp The DMP metadata record to persist as either an RDA Common Standard
  * or the standard with DMP Tool specific extensions.
  * @param version The version of the DMP metadata record to persist
@@ -54,7 +67,7 @@ export declare const getDMPs: (dmpId: string, version: string | null, includeExt
  * metadata record with the DMP Tool specific extensions merged in.
  * @throws DMPToolDynamoError if the record could not be persisted
  */
-export declare const createDMP: (dmpId: string, dmp: DMPToolDMPType, version?: string, includeExtensions?: boolean) => Promise<DMPToolDMPType | undefined>;
+export declare const createDMP: (dynamoConnectionParams: DynamoConnectionParams, domainName: string, dmpId: string, dmp: DMPToolDMPType, version?: string, includeExtensions?: boolean) => Promise<DMPToolDMPType | undefined>;
 /**
  * Update the specified DMP metadata record.
  * This function will handle the separation of RDA Common Standard and DMP Tool
@@ -70,18 +83,25 @@ export declare const createDMP: (dmpId: string, dmp: DMPToolDMPType, version?: s
  * If a snapshot is made, the timestamp and link to retrieve it will appear
  * in the `versions` array
  *
- * @param dmp
+ * @param dynamoConnectionParams the DynamoDB connection parameters
+ * @param domainName The domain name of the DMPTool instance (e.g. 'dmptool.org')
+ * @param dmp The DMP metadata record to persist as either an RDA Common Standard
+ * or the standard with DMP Tool specific extensions.
+ * @param gracePeriodInMS The grace period in milliseconds to wait before creating
  * @param includeExtensions Whether or not to include the DMP Tool specific
  * extensions in the returned record. Defaults to true.
  * @returns The persisted DMP metadata record as an RDA Common Standard DMP
  * metadata record with the DMP Tool specific extensions merged in.
  * @throws DMPToolDynamoError if the record could not be persisted
  */
-export declare const updateDMP: (dmp: DMPToolDMPType, includeExtensions?: boolean) => Promise<DMPToolDMPType>;
+export declare const updateDMP: (dynamoConnectionParams: DynamoConnectionParams, domainName: string, dmp: DMPToolDMPType, gracePeriodInMS?: number, // 2 hours in milliseconds
+includeExtensions?: boolean) => Promise<DMPToolDMPType>;
 /**
  * Create a Tombstone for the specified DMP metadata record
  * (registered/published DMPs only!)
  *
+ * @param dynamoConnectionParams The DynamoDB connection parameters
+ * @param domainName The domain name of the DMPTool instance (e.g. 'dmptool.org')
  * @param dmpId The DMP ID (e.g. '11.12345/A1B2C3')
  * @param includeExtensions Whether or not to include the DMP Tool specific
  * extensions in the returned record. Defaults to true.
@@ -89,11 +109,13 @@ export declare const updateDMP: (dmp: DMPToolDMPType, includeExtensions?: boolea
  * metadata record with the DMP Tool specific extensions merged in.
  * @throws DMPToolDynamoError if a tombstone could not be created
  */
-export declare const tombstoneDMP: (dmpId: string, includeExtensions?: boolean) => Promise<DMPToolDMPType>;
+export declare const tombstoneDMP: (dynamoConnectionParams: DynamoConnectionParams, domainName: string, dmpId: string, includeExtensions?: boolean) => Promise<DMPToolDMPType>;
 /**
  * Delete the specified DMP metadata record and any associated DMP Tool extension records.
  * This will NOT work on DMPs that have been registered/published.
  *
+ * @param dynamoConnectionParams The DynamoDB connection parameters
+ * @param domainName The domain name of the DMPTool instance (e.g. 'dmptool.org')
  * @param dmpId The DMP ID (e.g. '11.12345/A1B2C3')
  * @param includeExtensions Whether or not to include the DMP Tool specific extensions
  * in the returned record. Defaults to true.
@@ -101,5 +123,5 @@ export declare const tombstoneDMP: (dmpId: string, includeExtensions?: boolean)
  * record with the DMP Tool specific extensions merged in.
  * @throws DMPToolDynamoError if the record could not be deleted
  */
-export declare const deleteDMP: (dmpId: string, includeExtensions?: boolean) => Promise<DMPToolDMPType>;
+export declare const deleteDMP: (dynamoConnectionParams: DynamoConnectionParams, domainName: string, dmpId: string, includeExtensions?: boolean) => Promise<DMPToolDMPType>;
 export {};