Pluga developer platform toolbox
npm install pluga-plgPluga developer platform toolbox
``bash`
npm install pluga-plg🔧 Configuration
If you are using the storageService (>= 0.2.0), define the following in the environment:
`env`
AWS_S3_BUCKET=bucket-name
AWS_REGION=region
AWS_ACCESS_KEY_ID=access-key
AWS_SECRET_ACCESS_KEY=secret-keyplg.errors
AuthError
Authentication error, usually requires manual action from the client. Should be used in cases where an authentication issue prevents the integration from functioning.
`javascript`
plg.errors.authError(message: String)
Error
Generic error type. Errors of this type put the event in a failed state. Should be used when an integration issue requires manual correction by the client.
`javascript`
plg.errors.error(message: String)
RateLimitError
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.
`javascript`
plg.errors.rateLimitError(message: String, remaining: Integer(seconds))
TransientError
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.
`javascript`
plg.errors.transientError(message: String)
The files.remote module provides integration with Amazon S3 for file management.
async upload
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
`json`
{
"fileKey": "string"
}
#### Errors
| type | When it occurs | Example message |
|--------------|---------------|-------------------|
| Error | Local path does not exist | - |Error
| | Internal errors in the AWS SDK | - |
async download
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
`json`
{
"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. |
async getSignedUrl
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:
`json`
{
"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 | - |
async fileExists
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
`json`
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 | - |
The files.local module enables local file handling.
async downloadStream
Download a file from a URL as a stream and save it locally.
`javascript`
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
`json`
{
"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": |onEndCallback
| | Error thrown inside callbacks.onEnd | { "type": "onEndCallback", "error": |StreamPipelineError
| | Stream pipeline fails (connection drop, timeout, write error, etc.) | { "type": "StreamPipelineError", "error":