@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/connections/awss3.md

@@ -0,0 +1,313 @@
+# Amazon S3
+
+AWS S3 is a file or data storage solution, provided by Amazon Web Services. S3 does not work like a traditional file system, data is stored as objects in a collection of objects called a bucket.
+Objects can be read from S3 and stored in S3 using web requests. These objects can be public or private. You can read more [here](https://docs.aws.amazon.com/AmazonS3/latest/dev/Welcome.html).
+
+Lowdefy integrates with AWS S3 using presigned links. These are links that are authorized to give access to private objects, or that allow you to create new objects, and that expire after a certain amount of time. This allows you to upload or download directly from S3 from the browser.
+
+A guide to creating and connecting to an S3 bucket is given at the bottom of this page.
+
+## Connections
+
+Connection types:
+  - AwsS3Bucket
+
+### AwsS3Bucket
+
+The `AwsS3Bucket` connection is used to connect to a AWS S3 bucket. AWS S3 is the file storage solution provided by Amazon Web services.
+
+#### Properties
+- `accessKeyId: string`: __Required__ - AWS IAM access key id with s3 access.
+- `secretAccessKey: string`: __Required__ - AWS IAM secret access key with s3 access.
+- `region: string`: __Required__ - AWS region bucket is located in.
+- `bucket: string`: __Required__ - S3 bucket name.
+- `endpoint: string`: Custom S3 API endpoint for S3-compatible providers like Cloudflare R2, MinIO, DigitalOcean Spaces, Backblaze B2, and Wasabi.
+- `forcePathStyle: boolean`: Force path-style bucket addressing (`https://endpoint/bucket/key`). Required by MinIO and some self-hosted S3-compatible setups.
+- `publicUrlBase: string`: Base URL used to construct stable public object URLs (e.g. a CloudFront or CDN domain in front of the bucket). Used by download requests when the request sets `public: true`.
+- `read: boolean`: Default: `true` - Allow reads from the bucket.
+- `write: boolean`: Default: `false` - Allow writes to the bucket.
+
+#### Examples
+
+###### Read and writes on a bucket:
+```yaml
+connections:
+  - id: my_bucket
+    type: AwsS3Bucket
+    properties:
+      accessKeyId:
+        _secret: S3_ACCESS_KEY_ID
+      secretAccessKey:
+        _secret: S3_SECRET_ACCESS_KEY
+      region: eu-west-1
+      bucket: my-bucket-name
+      write: true
+```
+Environment variables:
+```
+LOWDEFY_SECRET_S3_ACCESS_KEY_ID = AKIAIOSFODNN7EXAMPLE
+LOWDEFY_SECRET_S3_SECRET_ACCESS_KEY = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+```
+
+###### S3-compatible provider (Cloudflare R2):
+```yaml
+connections:
+  - id: r2
+    type: AwsS3Bucket
+    properties:
+      endpoint: https://<account>.r2.cloudflarestorage.com
+      region: auto
+      bucket: my-bucket
+      accessKeyId:
+        _secret: R2_ACCESS_KEY_ID
+      secretAccessKey:
+        _secret: R2_SECRET_ACCESS_KEY
+      write: true
+```
+The same connection and requests work against any S3-compatible service — set `endpoint` (and `forcePathStyle: true` for MinIO and most self-hosted setups). Remember to configure CORS on the provider for direct browser uploads.
+
+## Requests
+
+Request types:
+  - AwsS3GetObject
+  - AwsS3PresignedGetObject
+  - AwsS3PresignedPostPolicy
+  - AwsS3PutObject
+
+### AwsS3PresignedGetObject
+
+The `AwsS3PresignedGetObject` request is used to get a download link for an object in AWS S3. Reference the request id in the <a href="/Download">Download</a> block's `downloadPolicyRequestId` property, or open the returned URL with the `Link` action.
+
+#### Properties
+- `versionId: string`: VersionId used to reference a specific version of the object.
+- `expires: number`: Number of seconds for which the policy should be valid.
+- `key: string`: __Required__ - Key (or filename) under which object will be stored. If another file is saved with the same key, that file will be overwritten, so a random string in this field is probably needed.
+- `responseContentType: string`: Sets the Content-Type header of the response.
+- `responseContentDisposition: string`: Sets the Content-Disposition header of the response.
+- `public: boolean`: Default: `false` - Return a stable, non-expiring public URL instead of a signed URL — virtual-hosted style by default, path-style on a custom `endpoint`, or `${publicUrlBase}/${key}` when the connection sets `publicUrlBase`. The object must be publicly readable (e.g. uploaded with acl `public-read`); this is author-declared and never checked at runtime. `versionId`, `responseContentType` and `responseContentDisposition` do not apply to public URLs (providers only honor them on signed requests).
+
+#### Examples
+
+###### Download a pdf and open in a new tab:
+```yaml
+requests:
+  - id: my_file_link
+    type: AwsS3PresignedGetObject
+    connectionId: my_bucket_connection
+    properties:
+      key: pdf-filename-as4dacd.pdf
+      responseContentType: application/pdf
+
+        ...
+        blocks:
+          - id: getFileButton
+            type: Button
+            events:
+              onClick:
+                - id: open_file
+                  type: Link
+                  params:
+                    url:
+                      _request: my_file_link
+                    newTab: true
+```
+
+### AwsS3PresignedPostPolicy
+
+The `AwsS3PresignedPostPolicy` request is used to create a policy that allows a file to be uploaded to AWS S3. It returns the standard upload-policy descriptor `{ method: 'POST', url, key, bucket, fields }` used by the <a href="/Upload">Upload</a>, <a href="/UploadPhoto">UploadPhoto</a> and <a href="/UploadDragger">UploadDragger</a> blocks — reference the request id in the block's `uploadPolicyRequestId` property.
+
+#### Properties
+- `acl: enum`: Access control lists used to grant read and write access.
+  - private
+  - public-read
+  - public-read-write
+  - aws-exec-read
+  - authenticated-read
+  - bucket-owner-read
+  - bucket-owner-full-control
+- `conditions: object[] | string[][]`: Conditions to be enforced on the request. An array of objects, or condition arrays. See [here](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-HTTPPOSTConstructPolicy.html).
+- `expires: number`: Number of seconds for which the policy should be valid.
+- `key: string`: __Required__ - Key (or filename) under which object will be stored. If another file is saved with the same key, that file will be overwritten, so a random string in this field is probably needed.
+- `fields: object`: Fields to be included in the form. Useful for adding metadata to the object such as `Content-Type`. See [S3 POST policy](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-HTTPPOSTConstructPolicy.html).
+
+#### Examples
+
+###### Upload a file with user filename and random id:
+```yaml
+- id: my_post_policy
+  type: AwsS3PresignedPostPolicy
+  connectionId: my_bucket_connection
+  payload:
+    filename:
+      _args: filename
+    uid:
+      _args: uid
+  properties:
+    key:
+      _nunjucks:
+        template: uploads/{{filename}}-{{uid}}
+        on:
+          filename:
+            _payload: filename
+          uid:
+            _payload: uid
+```
+
+### AwsS3GetObject
+
+The `AwsS3GetObject` request reads an object from the bucket on the server and returns its
+content as a base64 encoded string, so [API endpoint](/lowdefy-api) routine steps can process
+file content with operators and pass it to other steps (e.g. transform an uploaded file and
+store the result with `AwsS3PutObject`). The connection must allow reads (`read` is `true`
+by default). Content rides through the routine as base64, so this suits small and medium files.
+
+#### Properties
+- `key: string`: __Required__ - Key under which the object is stored.
+- `versionId: string`: VersionId used to reference a specific version of the object.
+
+Returns `{ bucket, key, content, contentType, size }` — `content` is the base64 encoded object.
+
+#### Examples
+
+###### Read a stored file and re-store a processed copy:
+```yaml
+api:
+  - id: copy_report
+    type: Api
+    routine:
+      - id: get_object
+        type: AwsS3GetObject
+        connectionId: my_bucket
+        properties:
+          key:
+            _payload: key
+      - id: put_copy
+        type: AwsS3PutObject
+        connectionId: my_bucket
+        properties:
+          key:
+            _string.concat: ['copies/', { _payload: key }]
+          content:
+            _step: get_object.content
+          contentType:
+            _step: get_object.contentType
+      - ':return':
+          key:
+            _step: put_copy.key
+```
+
+### AwsS3PutObject
+
+The `AwsS3PutObject` request writes an object to the bucket from the server. It accepts base64 encoded
+content, which makes it the storage half of the server-side file handling pattern: an upload block with
+`emitFileContent: true` sends the file as a base64 payload to an [API endpoint](/lowdefy-api) with the
+`CallAPI` action, and a routine step stores it. The connection must set `write: true`.
+
+#### Properties
+- `key: string`: __Required__ - Key under which the object will be stored.
+- `content: string`: __Required__ - Object content as a base64 encoded string.
+- `contentType: string`: MIME type of the object (sets the Content-Type of the stored object).
+- `acl: enum`: Access control lists used to grant read and write access (same values as AwsS3PresignedPostPolicy).
+
+#### Examples
+
+###### Store a file sent as an endpoint payload:
+```yaml
+api:
+  - id: store_report
+    type: Api
+    routine:
+      - id: put_object
+        type: AwsS3PutObject
+        connectionId: my_bucket
+        properties:
+          key:
+            _string.concat:
+              - 'reports/'
+              - _payload: name
+          content:
+            _payload: content
+          contentType:
+            _payload: type
+      - ':return':
+          key:
+            _step: put_object.key
+```
+
+## Creating a bucket
+
+###### Step 1 - Create an AWS account
+
+Go to the [AWS homepage](https://aws.amazon.com/) and create an account if you don't already have one. you can find more information [here](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
+
+###### Step 2 - Create an S3 bucket
+
+1. Once logged in, search for S3 in the search box.
+2. Click 'Create Bucket'
+3. Choose a name and AWS region for your bucket
+4. Continue creating the bucket with any extra settings is needed.
+5. Make sure the 'Block all public access' box is ticked if you don't want to allow public access.
+6. Click 'Create Bucket'
+
+###### Step 3 - Set the CORS settings for your bucket
+
+CORS, or Cross-Origin Resource Sharing is a security feature that is used to restrict web applications from accessing resources from different origins, or domain names. To allow your Lowdefy app to access the contents of the bucket, you need to add a CORS rule on the bucket that authorizes your app
+
+1. Click on you bucket.
+2. Click on the 'Permissions' tab.
+3. Click on the 'CORS Configuration' tab.
+4. Paste this configuration and save (Fill in your own Lowdefy domain name).
+
+```json
+[
+    {
+        "AllowedHeaders": [
+            "*"
+        ],
+        "AllowedMethods": [
+            "GET", "PUT", "POST", "DELETE", "HEAD"
+        ],
+        "AllowedOrigins": [
+            "https://YOUR_LOWDEFY_DOMAIN_HERE"
+        ],
+        "ExposeHeaders": []
+    }
+]
+```
+
+###### Step 4 - Create an IAM user
+
+IAM is the AWS identity and access management system. This can be used to give very granular access permissions. We will create a programmatic user that has the rights to read and write objects in the Bucket.
+
+1. In the 'Services' dropdown in the header, search for 'IAM'.
+2. Click on 'Users' in the menu on the left.
+3. Click 'Add User'
+4. Choose a descriptive name for the user.
+5. Choose programmatic access and click next.
+6. Choose 'Attach existing policies directly'.
+7. Choose 'Create Policy'.
+8. Choose the JSON tab and paste the following (Fill in your own bucket name):
+```JSON
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "ListObjectsInBucket",
+            "Effect": "Allow",
+            "Action": ["s3:ListBucket"],
+            "Resource": ["arn:aws:s3:::YOUR_BUCKET_NAME_HERE"]
+        },
+        {
+            "Sid": "AllObjectActions",
+            "Effect": "Allow",
+            "Action": "s3:*Object",
+            "Resource": ["arn:aws:s3:::YOUR_BUCKET_NAME_HERE/*"]
+        }
+    ]
+}
+```
+
+9. Choose review policy and save.
+10. In your previous tab, refresh and search for the policy you just created. Attach it to the user.
+11. Click next, review and create the user.
+12. Set the access key id and secret access key in your Lowdefy secrets store.

package/content/connections/azureblobstorage.md

@@ -0,0 +1,133 @@
+# Azure Blob Storage
+
+Azure Blob Storage is the object storage service provided by Microsoft Azure. Data is stored as blobs in containers within a storage account. You can read more [here](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction).
+
+Lowdefy integrates with Azure Blob Storage using SAS (shared access signature) tokens — short-lived credentials that let the browser upload and download blobs directly, without file content passing through the Lowdefy server. Azure uploads use a `PUT` request with the file as the raw request body, which the provider-neutral <a href="/Upload">Upload</a> and <a href="/Download">Download</a> blocks handle automatically.
+
+Direct browser uploads require [CORS configuration on the storage account](https://learn.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services) that allows your app's origin.
+
+## Connections
+
+Connection types:
+  - AzureBlobContainer
+
+### AzureBlobContainer
+
+The `AzureBlobContainer` connection is used to connect to an Azure Blob Storage container.
+
+#### Properties
+- `account: string`: __Required__ - Azure storage account name.
+- `accountKey: string`: __Required__ - Azure storage account access key.
+- `container: string`: __Required__ - Blob container name.
+- `publicUrlBase: string`: Base URL used to construct stable public object URLs (e.g. a CDN domain in front of the container). Used by download requests when the request sets `public: true`.
+- `read: boolean`: Default: `true` - Allow reads from the container.
+- `write: boolean`: Default: `false` - Allow writes to the container.
+
+#### Examples
+
+###### Reads and writes on a container:
+```yaml
+connections:
+  - id: blob
+    type: AzureBlobContainer
+    properties:
+      account: mystorageacct
+      container: uploads
+      accountKey:
+        _secret: AZURE_STORAGE_KEY
+      write: true
+```
+Environment variables:
+```
+LOWDEFY_SECRET_AZURE_STORAGE_KEY = your-storage-account-key
+```
+
+## Requests
+
+Request types:
+  - AzureBlobUploadSas
+  - AzureBlobDownloadSas
+  - AzureBlobGet
+  - AzureBlobPut
+
+### AzureBlobUploadSas
+
+The `AzureBlobUploadSas` request mints a write SAS URL for direct browser uploads. It returns the standard upload-policy descriptor `{ method: 'PUT', url, key, bucket, headers }` (with the `x-ms-blob-type: BlockBlob` header) used by the <a href="/Upload">Upload</a>, <a href="/UploadPhoto">UploadPhoto</a> and <a href="/UploadDragger">UploadDragger</a> blocks — reference the request id in the block's `uploadPolicyRequestId` property. The connection must set `write: true`.
+
+#### Properties
+- `key: string`: __Required__ - Key (blob name) under which the object will be stored. If another file is saved with the same key, that file will be overwritten, so a random string in this field is probably needed.
+- `expires: number`: Default: `3600` - Number of seconds for which the SAS token should be valid.
+- `contentType: string`: MIME type set as the Content-Type header of the upload.
+
+#### Examples
+
+###### Upload a file with the user's filename:
+```yaml
+requests:
+  - id: upload_policy
+    type: AzureBlobUploadSas
+    connectionId: blob
+    payload:
+      name:
+        _event: file.name
+    properties:
+      key:
+        _string.concat:
+          - 'uploads/'
+          - _payload: name
+```
+
+### AzureBlobDownloadSas
+
+The `AzureBlobDownloadSas` request mints a read SAS URL for downloads. Reference the request id in the <a href="/Download">Download</a> block's `downloadPolicyRequestId` property, or open the returned URL with the `Link` action.
+
+#### Properties
+- `key: string`: __Required__ - Key (blob name) under which the object is stored.
+- `expires: number`: Default: `3600` - Number of seconds for which the SAS token should be valid.
+- `public: boolean`: Default: `false` - Return a stable, non-expiring public URL (`https://{account}.blob.core.windows.net/{container}/{key}`, or `${publicUrlBase}/${key}` when the connection sets `publicUrlBase`) instead of a SAS URL. The blob must be publicly readable (public container access); this is author-declared and never checked at runtime.
+- `contentDisposition: string`: Sets the Content-Disposition header of the response.
+- `contentType: string`: Sets the Content-Type header of the response.
+
+### AzureBlobGet
+
+The `AzureBlobGet` request reads a blob from the container on the server and returns its content
+as a base64 encoded string, so [API endpoint](/lowdefy-api) routine steps can process file content
+with operators and pass it to other steps. The connection must allow reads (`read` is `true` by
+default). Returns `{ bucket, key, content, contentType, size }`.
+
+#### Properties
+- `key: string`: __Required__ - Key (blob name) under which the blob is stored.
+
+### AzureBlobPut
+
+The `AzureBlobPut` request writes a block blob to the container from the server. It accepts base64 encoded content, which makes it the storage half of the server-side file handling pattern: an upload block with `emitFileContent: true` sends the file as a base64 payload to an [API endpoint](/lowdefy-api) with the `CallAPI` action, and a routine step stores it. The connection must set `write: true`.
+
+#### Properties
+- `key: string`: __Required__ - Key (blob name) under which the blob will be stored.
+- `content: string`: __Required__ - Blob content as a base64 encoded string.
+- `contentType: string`: MIME type of the blob (sets the Content-Type of the stored blob).
+
+#### Examples
+
+###### Store a file sent as an endpoint payload:
+```yaml
+api:
+  - id: store_report
+    type: Api
+    routine:
+      - id: put_object
+        type: AzureBlobPut
+        connectionId: blob
+        properties:
+          key:
+            _string.concat:
+              - 'reports/'
+              - _payload: name
+          content:
+            _payload: content
+          contentType:
+            _payload: type
+      - ':return':
+          key:
+            _step: put_object.key
+```