Skip to content

Latest commit

 

History

History
733 lines (545 loc) · 26.7 KB

API.md

File metadata and controls

733 lines (545 loc) · 26.7 KB
Raw

Classes

SQS

SQS utility to send messages to SQS

Constants

createFormData ⇒ FormData

Creates and populates a FormData object from key-value pairs.

getGroupMembersEndpoint ⇒ string

Generates the IMS groups endpoint URL.

getImsOrgsApiPath ⇒ string

Generates the IMS organizations endpoint URL.

extractIdAndAuthSource ⇒ Object

Extracts the orgId and authSource from the IMS Org ID.

emailAddressIsAllowed ⇒ boolean

Validates whether the given email address is allowed.

Functions

createClient(log, dbClient, docClient) ⇒ Object

Creates a client object for interacting with DynamoDB.

createResponse(body, [status], [headers]) ⇒ Response

Creates a response with a JSON body if the content-type is JSON. Defaults to 200 status. If a header is already defined and has a different content-type, it is handled accordingly.

isArray(value) ⇒ boolean

Determines if the given parameter is an array.

isBoolean(value) ⇒ boolean

Determines case-insensitively if the given value is a boolean or a string representation of a boolean.

isInteger(value) ⇒ boolean

Checks if the given value is an integer.

isNumber(value) ⇒ boolean

Determines if the given value is a number.

isObject(value) ⇒ boolean

Checks if the given parameter is an object and not an array or null.

isNonEmptyObject(value) ⇒ boolean

Checks if the given value is an object and contains properties of its own.

deepEqual(x, y) ⇒ boolean

Deeply compares two objects or arrays for equality. Supports nested objects and arrays. Does not support circular references. Does not compare functions.

isString(value) ⇒ boolean

Determines if the given parameter is a string.

hasText(str) ⇒ boolean

Checks if the given string is not empty.

isValidDate(value) ⇒ boolean

Checks whether the given object is a valid JavaScript Date.

isIsoDate(str) ⇒ boolean

Validates whether the given string is a JavaScript ISO date string in Zulu (UTC) timezone. Used for persisting system dates, which must be independent of any user timezone.

isIsoTimeOffsetsDate(str) ⇒ boolean

Validates whether the given string is a JavaScript ISO date string following UTC time offsets format.

isValidUrl(urlString) ⇒ boolean

Validates whether the given string is a valid URL with http or https protocol.

toBoolean(value) ⇒ boolean

Converts a given value to a boolean. Throws an error if the value is not a boolean.

arrayEquals(a, b) ⇒ boolean

Compares two arrays for equality. Supports primitive array item types only.

dateAfterDays(days, [dateString]) ⇒ Date

Calculates the date after a specified number of days from the current date.

resolveSecretsName(opts, ctx, defaultPath) ⇒ string

Resolves the name of the secret based on the function version.

resolveCustomerSecretsName(baseURL, ctx) ⇒ string

Resolves the name of the customer secrets based on the baseURL.

generateCSVFile(data) ⇒ Buffer

Generates a CSV file from the provided JSON data.

Each key-value pair in the JSON objects corresponds to a column and its value in the CSV. The output is a UTF-8 encoded Buffer that represents the CSV file content.

logWrapper(fn) ⇒ function

A higher-order function that wraps a given function and enhances logging by appending a jobId to log messages when available. This improves traceability of logs associated with specific jobs or processes.

The wrapper checks if a log object exists in the context and whether the message contains a jobId. If found, log methods (e.g., info, error, etc.) will prepend the jobId to all log statements where context.contextualLog is used. If no jobId is found, logging will remain unchanged.

s3Wrapper(fn) ⇒ function

Adds an S3Client instance and bucket to the context.

sqsEventAdapter(fn) ⇒ function

Wrapper to turn an SQS record into a function param Inspired by https://github.com/adobe/helix-admin/blob/main/src/index.js#L108-L133

createSubsegment(parentSegment, hostname) ⇒ Object

Creates a subsegment for a given hostname based on whether the parent segment is traced or not.

setTraceHeaders(request, parentSegment, subSegment)

Sets the AWS X-Ray trace headers on the request object.

setSubSegmentFlagsByStatusCode(subSegment, status)

Adds flags to the given subsegment based on the status code of the response.

addFetchRequestDataToSegment(segment, request, [response])

Adds request and response data to the given segment for AWS X-Ray tracing.

handleSubSegmentError(subSegment, request, error)

Adds error data to the given segment for AWS X-Ray tracing.

tracingFetch(url, options) ⇒ Promise.<Response>

Performs a fetch request and adds AWS X-Ray tracing, including request/response tracking.

prependSchema(url) ⇒ string

Prepends 'https://' schema to the URL if it's not already present.

stripPort(url) ⇒ string

Strips the port number from the end of the URL.

stripTrailingDot(url) ⇒ string

Strips the trailing dot from the end of the URL.

stripTrailingSlash(url) ⇒ string

Strips the trailing slash from the end of the URL if the path is '/'.

stripWWW(url) ⇒ string

Strips 'www.' from the beginning of the URL if present.

composeBaseURL(domain) ⇒ string

Composes a base URL by applying a series of transformations to the given domain.

SQS

SQS utility to send messages to SQS

Kind: global class

new SQS(region, log)

Param Type Description
region string AWS region
log object log object

sqS.sendMessage(queueUrl, message, messageGroupId) ⇒ Promise.<void>

Send a message to an SQS queue. For FIFO queues, messageGroupId is required.

Kind: instance method of SQS

Param Type Description
queueUrl string The URL of the SQS queue.
message object The message body to send.
messageGroupId string (Optional) The message group ID for FIFO queues.

createFormData ⇒ FormData

Creates and populates a FormData object from key-value pairs.

Kind: global constant
Returns: FormData - A populated FormData object.

Param Type Description
fields Object Object containing key-value pairs to append to FormData.

getGroupMembersEndpoint ⇒ string

Generates the IMS groups endpoint URL.

Kind: global constant
Returns: string - /ims/organizations/$/groups/${string}/members - The IMS groups endpoint URL.

Param Type Description
imsOrgId string The IMS host.
groupId string The IMS client ID.

getImsOrgsApiPath ⇒ string

Generates the IMS organizations endpoint URL.

Kind: global constant
Returns: string - /ims/organizations/$/v2 - The IMS organizations endpoint URL.

Param Type Description
imsOrgId string The IMS host.

extractIdAndAuthSource ⇒ Object

Extracts the orgId and authSource from the IMS Org ID.

Kind: global constant
Returns: Object - - The orgId and authSource.

Param Type Description
imsOrgId string The IMS Org ID.

emailAddressIsAllowed ⇒ boolean

Validates whether the given email address is allowed.

Kind: global constant
Returns: boolean - - True if the email address is allowed, false otherwise.

Param Type Description
email string The email address to validate.

createClient(log, dbClient, docClient) ⇒ Object

Creates a client object for interacting with DynamoDB.

Kind: global function
Returns: Object - A client object with methods to interact with DynamoDB.

Param Type Description
log Object The logging object, defaults to console.
dbClient DynamoDB The AWS SDK DynamoDB client instance.
docClient DynamoDBDocument The AWS SDK DynamoDB Document client instance.

createResponse(body, [status], [headers]) ⇒ Response

Creates a response with a JSON body if the content-type is JSON. Defaults to 200 status. If a header is already defined and has a different content-type, it is handled accordingly.

Kind: global function
Returns: Response - Response.

Param Type Default Description
body object Response body.
[status] number 200 Optional status code.
[headers] object {} Optional headers.

isArray(value) ⇒ boolean

Determines if the given parameter is an array.

Kind: global function
Returns: boolean - True if the parameter is an array, false otherwise.

Param Type Description
value * The value to check.

isBoolean(value) ⇒ boolean

Determines case-insensitively if the given value is a boolean or a string representation of a boolean.

Kind: global function
Returns: boolean - True if the value is a boolean or a string representation of a boolean.

Param Type Description
value * The value to check.

isInteger(value) ⇒ boolean

Checks if the given value is an integer.

Kind: global function
Returns: boolean - True if the value is an integer, false otherwise.

Param Type Description
value * The value to check.

isNumber(value) ⇒ boolean

Determines if the given value is a number.

Kind: global function
Returns: boolean - True if the value is a finite number, false otherwise.

Param Type Description
value * The value to check.

isObject(value) ⇒ boolean

Checks if the given parameter is an object and not an array or null.

Kind: global function
Returns: boolean - True if the parameter is an object, false otherwise.

Param Type Description
value * The value to check.

isNonEmptyObject(value) ⇒ boolean

Checks if the given value is an object and contains properties of its own.

Kind: global function
Returns: boolean - True if the value is a non-empty object, false otherwise.

Param Type Description
value * The value to check.

deepEqual(x, y) ⇒ boolean

Deeply compares two objects or arrays for equality. Supports nested objects and arrays. Does not support circular references. Does not compare functions.

Kind: global function
Returns: boolean - True if the objects or arrays are equal, false otherwise.

Param Type Description
x unknown The first object or array to compare.
y unknown The second object or array to compare.

isString(value) ⇒ boolean

Determines if the given parameter is a string.

Kind: global function
Returns: boolean - True if the parameter is a string, false otherwise.

Param Type Description
value * The value to check.

hasText(str) ⇒ boolean

Checks if the given string is not empty.

Kind: global function
Returns: boolean - True if the string is not empty, false otherwise.

Param Type Description
str * The string to check.

isValidDate(value) ⇒ boolean

Checks whether the given object is a valid JavaScript Date.

Kind: global function
Returns: boolean - True if the given object is a valid Date object, false otherwise.

Param Type Description
value * The value to check.

isIsoDate(str) ⇒ boolean

Validates whether the given string is a JavaScript ISO date string in Zulu (UTC) timezone. Used for persisting system dates, which must be independent of any user timezone.

Kind: global function
Returns: boolean - True if the given string validates successfully.

Param Type Description
str string The string to validate.

isIsoTimeOffsetsDate(str) ⇒ boolean

Validates whether the given string is a JavaScript ISO date string following UTC time offsets format.

Kind: global function
Returns: boolean - True if the given string validates successfully.

Param Type Description
str string The string to validate.

isValidUrl(urlString) ⇒ boolean

Validates whether the given string is a valid URL with http or https protocol.

Kind: global function
Returns: boolean - True if the given string validates successfully.

Param Type Description
urlString string The string to validate.

toBoolean(value) ⇒ boolean

Converts a given value to a boolean. Throws an error if the value is not a boolean.

Kind: global function
Returns: boolean - The converted boolean value.
Throws:

  • Error If the value is not a boolean or a boolean-like string.
Param Type Description
value * The value to convert.

arrayEquals(a, b) ⇒ boolean

Compares two arrays for equality. Supports primitive array item types only.

Kind: global function
Returns: boolean - True if the arrays are equal, false otherwise.

Param Type Description
a Array The first array to compare.
b Array The second array to compare.

dateAfterDays(days, [dateString]) ⇒ Date

Calculates the date after a specified number of days from the current date.

Kind: global function
Returns: Date - A new Date object representing the calculated date after the specified days.
Throws:

  • TypeError If the provided 'days' parameter is not a number.
  • RangeError If the calculated date is outside the valid JavaScript date range.
Param Type Description
days number The number of days to add to the current date.
[dateString] string The reference date in string format.

Example

// Get the date 7 days from now
const sevenDaysLater = dateAfterDays(7);
console.log(sevenDaysLater); // Outputs a Date object representing the date 7 days from now

resolveSecretsName(opts, ctx, defaultPath) ⇒ string

Resolves the name of the secret based on the function version.

Kind: global function
Returns: string - - The resolved secret name.

Param Type Description
opts Object The options object, not used in this implementation.
ctx Object The context object containing the function version.
defaultPath string The default path for the secret.

resolveCustomerSecretsName(baseURL, ctx) ⇒ string

Resolves the name of the customer secrets based on the baseURL.

Kind: global function
Returns: string - - The resolved secret name.

Param Type Description
baseURL string The base URL to resolve the customer secrets name from.
ctx Object The context object containing the function version.

generateCSVFile(data) ⇒ Buffer

Generates a CSV file from the provided JSON data.

Each key-value pair in the JSON objects corresponds to a column and its value in the CSV. The output is a UTF-8 encoded Buffer that represents the CSV file content.

Kind: global function
Returns: Buffer - A Buffer containing the CSV formatted data, encoded in UTF-8.

Param Type Description
data Array.<Object> An array of JSON objects to be converted into CSV format.

logWrapper(fn) ⇒ function

A higher-order function that wraps a given function and enhances logging by appending a jobId to log messages when available. This improves traceability of logs associated with specific jobs or processes.

The wrapper checks if a log object exists in the context and whether the message contains a jobId. If found, log methods (e.g., info, error, etc.) will prepend the jobId to all log statements where context.contextualLog is used. If no jobId is found, logging will remain unchanged.

Kind: global function
Returns: function - - A wrapped function that enhances logging and returns the result of the original function.

context.contextualLog will include logging methods with jobId prefixed, or fall back to the existing log object if no jobId is provided.

Param Type Description
fn function The original function to be wrapped, called with the provided message and context after logging enhancement.

s3Wrapper(fn) ⇒ function

Adds an S3Client instance and bucket to the context.

Kind: global function

Param Type
fn UniversalAction

sqsEventAdapter(fn) ⇒ function

Wrapper to turn an SQS record into a function param Inspired by https://github.com/adobe/helix-admin/blob/main/src/index.js#L108-L133

Kind: global function

Param Type
fn UniversalAction

createSubsegment(parentSegment, hostname) ⇒ Object

Creates a subsegment for a given hostname based on whether the parent segment is traced or not.

Kind: global function
Returns: Object - The created subsegment.

Param Type Description
parentSegment Object The parent X-Ray segment.
hostname string The hostname to associate with the subsegment.

setTraceHeaders(request, parentSegment, subSegment)

Sets the AWS X-Ray trace headers on the request object.

Kind: global function

Param Type Description
request Request The request object on which headers are set.
parentSegment Object The parent X-Ray segment.
subSegment Object The subsegment to include in the headers.

setSubSegmentFlagsByStatusCode(subSegment, status)

Adds flags to the given subsegment based on the status code of the response.

Kind: global function

Param Type Description
subSegment Object The X-Ray subsegment to which flags are added.
status number The status code of the response.

addFetchRequestDataToSegment(segment, request, [response])

Adds request and response data to the given segment for AWS X-Ray tracing.

Kind: global function

Param Type Description
segment Object The X-Ray segment to which request and response data are added.
request Request The original request object.
[response] Response The response object (if available).

handleSubSegmentError(subSegment, request, error)

Adds error data to the given segment for AWS X-Ray tracing.

Kind: global function

Param Type Description
subSegment Object The X-Ray subsegment to which error data is added.
request Request The original request object.
error Error The error object.

tracingFetch(url, options) ⇒ Promise.<Response>

Performs a fetch request and adds AWS X-Ray tracing, including request/response tracking.

Kind: global function
Returns: Promise.<Response> - The response from the fetch request.

Param Type Description
url string The URL for the request.
options Object Options to be passed to the fetch call.

prependSchema(url) ⇒ string

Prepends 'https://' schema to the URL if it's not already present.

Kind: global function
Returns: string - - The URL with 'https://' schema prepended.

Param Type Description
url string The URL to modify.

stripPort(url) ⇒ string

Strips the port number from the end of the URL.

Kind: global function
Returns: string - - The URL with the port removed.

Param Type Description
url string The URL to modify.

stripTrailingDot(url) ⇒ string

Strips the trailing dot from the end of the URL.

Kind: global function
Returns: string - - The URL with the trailing dot removed.

Param Type Description
url string The URL to modify.

stripTrailingSlash(url) ⇒ string

Strips the trailing slash from the end of the URL if the path is '/'.

Kind: global function
Returns: string - - The URL with the trailing slash removed.

Param Type Description
url string The URL to modify.

stripWWW(url) ⇒ string

Strips 'www.' from the beginning of the URL if present.

Kind: global function
Returns: string - - The URL with 'www.' removed.

Param Type Description
url string The URL to modify.

composeBaseURL(domain) ⇒ string

Composes a base URL by applying a series of transformations to the given domain.

Kind: global function
Returns: string - - The composed base URL.

Param Type Description
domain string The domain to compose the base URL from.