pluga-plg

Pluga developer platform toolbox

📦 Setup

  npm install pluga-plg

🔧 Configuration

If you are using the storageService (>= 0.2.0), define the following in the environment:

AWS_S3_BUCKET=bucket-name
AWS_REGION=region
AWS_ACCESS_KEY_ID=access-key
AWS_SECRET_ACCESS_KEY=secret-key

plg.errors

Custom Errors:

There are specific types of errors that are handled differently within the Pluga platform. Details about the supported error types and how they can be used in your code are described below:

  plg.errors.authError(message: String)

  plg.errors.error(message: String)

Errors of this type allow Pluga to process the events automatically at a later time. Should be used when a resource becomes unavailable due to usage limits, for example. You must provide the necessary time (in seconds) for the resource to become available again.

  plg.errors.rateLimitError(message: String, remaining: Integer(seconds))

Temporary or transient errors that may occur due to instabilities, outages, etc., and do not require any manual action for proper functioning. Events with this type of error are automatically reprocessed by the Pluga platform.

  plg.errors.transientError(message: String)

plg.files

plg.files.remote

The files.remote module provides integration with Amazon S3 for file management.

Send a local file to a S3 bucket.

  plg.files.remote.upload({ fileKey: String, filePath: String })

Params

| Name | Type | Required | Description | |----------|--------|-------------|-----------| | fileKey | string | Yes | The unique key (name) for the file in the S3 bucket | | filePath | string | Yes | The local path of the file to upload |

Return

{
  "fileKey": "string"
}

Errors

| type | When it occurs | Example message | |--------------|---------------|-------------------| | Error | Local path does not exist | - | | Error | Internal errors in the AWS SDK | - |

Download a file from an Amazon S3 bucket and save it to a local path.

  plg.files.remote.download({ 
      fileKey: String, 
      pathToWrite: String
      sizeLimit: Number
  })

Params

| Name | Type | Required | Description | |-------------|----------|-------------|-----------| | fileKey | string | Yes | The unique key (name) for the file in the S3 bucket | | pathToWrite | string | Yes | Local path where the downloaded file will be saved | | sizeLimit | number | No | Optional maximum allowed file size in bytes. If exceeded, the download will fail |

Return

{
  "success": true
}

Errors

| type | When it occurs | Example message | |--------------|---------------|-------------------| | Error | Local path does not exist | - | | Error | Internal errors in the AWS SDK | - | | Error | File exceeds size limit specified in the sizeLimit param | File size limit exceeded. File size: ${fileSize} bytes, limit: ${sizeLimit} bytes. |

Generate a temporary signed URL to download a file from S3.

  plg.files.remote.getSignedUrl({ 
      fileKey: String, 
      expiresIn: Number
  })

Params

| Name | Type | Required | Description | |-----------|----------|-------------|-----------| | fileKey | string | Yes | The unique key (name) for the file in the S3 bucket | | expiresIn | number | No | Optional expiration time in seconds. Default: 1800 (30 minutes) |

Return

If the file exists:

{
  "fileKey": "string",
  "signedUrl": "string",
  "expiresIn": "number"
}

If file does not exists returns null

Errors

| type | When it occurs | Example message | |--------------|---------------|-------------------| | Error | Internal errors in the AWS SDK | - |

Checks if a file exists in S3 bucket.

  plg.files.remote.fileExists({ 
      fileKey: String
  })

Params

| Name | Type | Required | Description | |--------|----------|-------------|-----------| | fileKey | string | Yes | The unique key (name) for the file in the S3 bucket |

Retorno

true // if the file exists
false // if the file does not exist

Errors

| type | When it occurs | Example message | |--------------|---------------|-------------------| | Error | Internal errors in the AWS SDK, except for 404, which is treated as false | - |

plg.files.local

The files.local module enables local file handling.

Download a file from a URL as a stream and save it locally.

plg.files.local.downloadStream({
  pathToWrite: String,
  downloadRequestParams: {
    downloadUrl: String,
    headers?: Object,
  },
  callbacks?: {
    onData?: Function,
    onEnd?: Function,
  },
})

Params

| Name | Type | Required | Description | | --------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------- | | pathToWrite | string | Yes | Local path where the downloaded file will be saved. | | downloadRequestParams | object | Yes | Object containing the download URL and optional HTTP headers. | | downloadRequestParams.downloadUrl | string | Yes | Public URL used to download the file. | | downloadRequestParams.headers | object | No | Optional HTTP headers to be sent with the download request. | | callbacks | object | No | Optional callbacks executed during the download lifecycle. | | callbacks.onData | function | No | Executed for each received data chunk. Receives (dataChunk, currentDownloadedBytesCount). | | callbacks.onEnd | function | No | Executed when the download finishes. If it returns a value, the promise resolves with that value. |

Return by default

{
  "success": true
}

• Note: If onEndCallback returns a value, the promise resolves with that value instead

Errors

| Type | When it occurs | Example | | --------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------- | | Error | Local path to write does not exist or is not writable | — | | Error | Download URL provided is not public or request fails | — | | onDataCallback | Error thrown inside callbacks.onData | { "type": "onDataCallback", "error": <original error> } | | onEndCallback | Error thrown inside callbacks.onEnd | { "type": "onEndCallback", "error": <original error> } | | StreamPipelineError | Stream pipeline fails (connection drop, timeout, write error, etc.) | { "type": "StreamPipelineError", "error": <original error> } |