@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/connections/postgresql.md

@@ -0,0 +1,200 @@
+# PostgreSQL
+
+The [Knex](/Knex) connection can be used to connect to a [PostgreSQL](https://www.postgresql.org) database.
+
+## Connections
+
+Connection types:
+  - Knex
+
+### Knex
+
+#### Properties
+- `client: enum`: __Required__ - The database client to use. To connect to PostgreSQL, use one of:
+  - `postgres`
+  - `pg` (alias of `postgres`)
+  - `postgresql` (alias of `postgres`)
+- `connection: object | string`: __Required__ - Connection string or object to pass to the [`pg`](https://www.npmjs.com/package/pg) database client.
+- `searchPath: string`:  Set PostgreSQL search path.
+- `version: string`:  Set database version.
+- `useNullAsDefault: boolean`: If true, undefined keys are replaced with NULL instead of DEFAULT.
+
+#### Examples
+
+###### Connection Object:
+```yaml
+connections:
+  - id: postgres
+    type: Knex
+    properties:
+      client: postgres
+      connection:
+        user:
+          _secret: PG_USER
+        host:
+          _secret: PG_HOST
+        database:
+          _secret: PG_DB
+        password:
+          _secret: PG_PASSWORD
+```
+Environment variables:
+```
+LOWDEFY_SECRET_PG_HOST = database.server.com
+LOWDEFY_SECRET_PG_DB = db
+LOWDEFY_SECRET_PG_USER = user
+LOWDEFY_SECRET_PG_PASSWORD = password
+```
+
+###### Secret connection string, with version and searchPath:
+```yaml
+connections:
+  - id: postgres
+    type: Knex
+    properties:
+      client: postgres
+      connection:
+        _secret: PG_CONNECTION_STRING
+      version: '7.2'
+      searchPath:
+        - knex
+        - public
+```
+Environment variables:
+```
+LOWDEFY_SECRET_PG_CONNECTION_STRING = postgresql://user:password@database.server.com:5432/db
+```
+
+## Requests
+
+Request types:
+
+- KnexBuilder
+- KnexRaw
+
+### KnexBuilder
+
+#### Properties
+
+- `query: object[]`: **Required** - SQL query builder array. An array of objects, with a single key which is the name of the knex builder function. The value should be an array of arguments to pass to the builder function.
+- `tableName: string | object`: The name of the table to query from.
+
+#### Examples
+
+###### Build a query:
+
+```yaml
+id: knexBuilder
+type: KnexBuilder
+connectionId: knex
+payload:
+  name:
+    _state: name
+properties:
+  query:
+    - select:
+        - '*'
+    - from:
+        - users
+    - where:
+        - name
+        - _payload: name
+```
+
+###### Using `tableName`:
+
+```yaml
+id: knexBuilder
+type: KnexBuilder
+connectionId: knex
+payload:
+  name:
+    _state: name
+properties:
+  tableName: users
+  query:
+    - select:
+        - '*'
+    - where:
+        - name
+        - _payload: name
+```
+
+###### Aliases:
+
+```yaml
+id: knexBuilder
+type: KnexBuilder
+connectionId: knex
+properties:
+  tableName:
+    a: tableA
+    b: tableB
+  query:
+    - select:
+        - aField: 'a.field'
+        - bField: 'b.field'
+    - limit:
+        - 1
+```
+
+### KnexRaw
+
+#### Properties
+
+- `query: string`: **Required** - SQL query string.
+- `parameters: string | number | array | object`: SQL query parameters.
+
+#### Examples
+
+###### Simple raw query:
+
+```yaml
+id: knexRaw
+type: KnexRaw
+connectionId: knex
+properties:
+  query: SELECT * FROM "my_table";
+```
+
+###### Query with named parameters:
+
+```yaml
+id: knexRaw
+type: KnexRaw
+connectionId: knex
+payload:
+  selected_name:
+    _state: selected_name
+properties:
+  query: select * from users where name = :name
+  parameters:
+    name:
+      _payload: selected_name
+```
+
+###### Query with positional parameters:
+
+```yaml
+id: knexRaw
+type: KnexRaw
+connectionId: knex
+payload:
+  selected_name:
+    _state: selected_name
+properties:
+  query: select * from users where name = ?
+  parameters:
+    - _payload: selected_name
+```
+
+###### Reference a `.sql` file:
+
+```yaml
+id: knexRaw
+type: KnexRaw
+connectionId: knex
+properties:
+  query:
+    _ref: my_query.sql
+```

package/content/connections/redis.md

@@ -0,0 +1,116 @@
+# Redis
+
+[`Redis`](http://redis.io/) is an open-source, in-memory key-value data structure store. Redis offers a set of versatile in-memory data structures (strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs, geospatial indexes, and streams) that allow the creation of many custom applications. Key use cases for Redis include database, caching, session management and message broker.
+
+Lowdefy integrates with Redis using the one of the recommended [Node.js clients (node-redis)](https://github.com/redis/node-redis).
+
+## Connections
+
+Connection types:
+  - Redis
+
+### Redis
+
+#### Properties
+- `connection: object | string `: __Required__ - Connection object or string to pass to the [`redis client`](https://github.com/redis/node-redis) redis client.
+
+The connection object accepts will be passed to the redis client verbatim, so check out the [configuration instructions](https://github.com/redis/node-redis/blob/master/docs/client-configuration.md).
+
+#### Examples
+
+###### Redis with connection object:
+```yaml
+connections:
+  - id: redis
+    type: Redis
+    properties:
+      connection:
+        username:
+          _secret: REDIS_USERNAME
+        password:
+          _secret: REDIS_PASSWORD
+        database:
+          _secret: REDIS_DATABASE
+        socket:
+          host:
+            _secret: REDIS_HOST
+          port:
+            _secret: REDIS_PORT
+```
+Environment variables:
+```
+LOWDEFY_SECRET_REDIS_USERNAME = user
+LOWDEFY_SECRET_REDIS_PASSWORD = password
+LOWDEFY_SECRET_REDIS_DATABASE = 4
+LOWDEFY_SECRET_REDIS_HOST = redis.server.com
+LOWDEFY_SECRET_REDIS_PORT = 5000
+```
+
+###### Redis with connection string:
+```yaml
+connections:
+  - id: redis
+    type: Redis
+    properties:
+      connection:
+        _secret: REDIS_CONNECTION_STRING
+```
+Environment variables:
+```
+LOWDEFY_SECRET_REDIS_CONNECTION_STRING = redis://user:password@redis:server.com:5000/4'
+```
+
+## Requests
+
+Request types:
+  - Redis
+
+### Redis
+
+#### Properties
+
+- `command: string`: **Required** - Redis command to be executed, accepts all of the [out-of-the-box Redis commands](https://redis.io/commands).
+- `parameters: array`: An array of parameters to be passed to the redis command.
+- `modifiers: object`: The redis modififers to be passed to the redis command.
+
+#### Examples
+
+###### Setting a key-value pair in redis:
+
+```yaml
+id: redisRequest
+type: Redis
+connectionId: redis
+properties:
+  command: set
+  parameters:
+    - key
+    - value
+```
+
+###### Getting a value from redis:
+
+```yaml
+id: redisRequest
+type: Redis
+connectionId: redis
+properties:
+  command: get
+  parameters:
+    - key
+```
+
+###### Setting a key-value pair only if key does not exist:
+
+```yaml
+id: redisRequest
+type: Redis
+connectionId: redis
+properties:
+  command: set
+  parameters:
+    - key
+    - value
+  modififers:
+    nx: true
+```

package/content/connections/sendgridmail.md

@@ -0,0 +1,94 @@
+# SendGrid Email
+
+[SendGrid](https://sendgrid.com/) is a popular email API provider which allows you to easily setup a email service. The `SendGridMail` connection can be used to connect to an existing SendGrid API account.
+
+The `SendGridMail` connector uses the [@sendgrid/mail](https://github.com/@sendgrid/mail) library.
+
+In order to use the `SendGridMail` connector, you first need to create a [SendGrid](https://sendgrid.com/) account and setup an API key.
+
+> Secrets like API keys should be stored using the [`_secret`](operators/secret.md) operator.
+
+In order to send from your custom domain your will need to [authenticate your domain](https://app.sendgrid.com/settings/sender_auth) through SendGrid. See the [SendGrid Docs](https://sendgrid.com/docs) for help on getting started with SendGrid.
+
+## Connections
+
+Connection types:
+  - SendGridMail
+
+## Requests
+
+Request types:
+  - SendGridMailSend
+
+### Types
+
+- `email: string | object`:  SendGrid accepts emails as either a `string` or an `object`.
+  - `string`: Can be in the following format; `someone@example.org` or `Some One <someone@example.org>`.
+  - `object`: With `name' and `email` properties, for example: `{"name": "Some One", "email": "someone@example.org"}`.
+
+### SendGridMail
+
+#### Properties
+
+- `apiKey: string`: __Required__ - SendGrid API key.
+- `from: email`: __Required__ - Email address to send email from.
+- `replyTo: email`: Default email address replies should be sent to.
+- `mailSettings: object`: SendGrid mail settings. See [SendGrid API-Reference](https://sendgrid.com/docs/api-reference/)
+  - `sandboxMode: object`: SendGrid mail sandbox mode settings.
+    - `enable: boolean`: Sandbox mode enabled when `true`.
+- `templateId: string`: SendGrid email template ID to render email when sending.
+- `filter: object`: Environment-aware delivery filter, applied to every send. Filter values are usually supplied by [`_secret`](operators/secret.md); a field that resolves to `null` is ignored, so one config serves every environment (a dev catch-all, a sandbox allowlist, nothing in production).
+  - `replaceAddress: string`: Redirect all mail to this single address. When set, it takes precedence — every message goes to this address only, with `cc` and `bcc` dropped.
+  - `allowlist: string[]`: A list of domains. Only recipients whose domain is in the list are sent to.
+  - `regex: string`: A regular expression. Only recipient addresses matching the pattern are sent to.
+
+### SendGridMailSend
+
+#### Properties
+
+##### object
+A `mail description`:
+- `to: email | email[]`: __Required__ - Email address or addresses to send to.
+- `cc: email | email[]`: Email address to cc in communication.
+- `bcc: email | email[]`: Email address to bcc in communication.
+- `replyTo: email | email[]`: Email address to reply to.
+- `subject: string`: Email subject.
+- `text: string`: Email message in plain text format.
+- `html: string`: Email message in html format.
+- `dynamicTemplateData: object`: SendGrid template data to render into email template.
+- `sendAt: integer`: A unix timestamp allowing you to specify when you want your email to be delivered. You can't schedule more than 72 hours in advance.
+- `attachments: object[]`: List of email attachments to include with email. See [SendGrid API-Reference](https://d2w67tjf43xwdp.cloudfront.net/Classroom/Build/Add_Content/attachments.html]).
+  - `content: string`: __Required__ - Base 64 encoded attachment content.
+  - `filename: string`: __Required__ - Name of the attachment file.
+  - `type: string`: The mime type of the content you are attaching. For example, `text/plain` or `text/html`.
+
+##### array
+An array of `mail description` objects can also be provided.
+
+### Examples
+
+###### Send a reminder email
+```yaml
+connections:
+  - id: my_sendgrid
+    type: SendGridMail
+    properties:
+      apiKey:
+        _secret: SENDGRID_API_KEY
+      from: reminders@example.org
+# ...
+requests:
+  - id: send_reminder
+    type: SendGridMailSend
+    connectionId: my_sendgrid
+    properties:
+      to: Harry Potter <harry@example.org>
+      subject: Reminder for Mr. Potter to water the 🌱
+      text: |
+        Hi Harry
+
+        Please remember to water the magic plants today :)
+
+        Thank you
+# ...
+```

package/content/connections/smtp.md

@@ -0,0 +1,149 @@
+# SMTP Email
+
+The `SMTP` connection sends email over any SMTP server — Amazon SES, Postmark, Mailgun, Resend, SendGrid's SMTP relay, or a self-hosted server. One connection type covers every provider.
+
+The `SMTP` connector uses the [nodemailer](https://nodemailer.com/) library. Connection properties are passed through to nodemailer's transport, so any [transport option](https://nodemailer.com/smtp/) nodemailer accepts (pooling, TLS options, a `service` shortcut, a connection `url`) can be set alongside the documented properties.
+
+> Secrets like passwords and API keys should be stored using the [`_secret`](operators/secret.md) operator.
+
+## Connections
+
+Connection types:
+  - SMTP
+
+## Requests
+
+Request types:
+  - SMTPMailSend
+
+### Types
+
+- `email: string | object`: An email address as either a `string` or an `object`.
+  - `string`: In the format `someone@example.org` or `Some One <someone@example.org>`.
+  - `object`: With `name` and `email` properties, for example `{ "name": "Some One", "email": "someone@example.org" }`.
+- `emails: email | email[]`: A single email address or a list of email addresses.
+
+### SMTP
+
+#### Properties
+
+- `host: string`: Hostname or IP address of the SMTP server to connect to.
+- `port: integer`: Port to connect to. Defaults to `587` when `secure` is `false`, or `465` when `secure` is `true`.
+- `secure: boolean`: If `true`, the connection uses TLS when connecting to the server.
+- `auth: object`: Authentication credentials for the SMTP server.
+  - `user: string`: Username to authenticate with.
+  - `pass: string`: Password to authenticate with.
+- `from: emails`: __Required__ - Default email address to send email from.
+- `replyTo: emails`: Default email address replies should be sent to.
+- `filter: object`: Environment-aware delivery filter, applied to every send. See [Delivery filter](#delivery-filter) below.
+
+Additional nodemailer transport options (for example `service`, `url`, `pool`, `tls`) are passed through unchanged.
+
+### SMTPMailSend
+
+Sends one email, or an array of emails. When an array is given, each message is sent in turn.
+
+#### Properties
+
+##### object
+
+A `mail description`:
+- `to: emails`: __Required__ - Email address or addresses to send to.
+- `cc: emails`: Email address to cc in communication.
+- `bcc: emails`: Email address to bcc in communication.
+- `replyTo: emails`: Email address to reply to. Overrides the connection `replyTo`.
+- `subject: string`: Email subject.
+- `text: string`: Email message in plain text format.
+- `html: string`: Email message in html format.
+- `attachments: object[]`: List of email attachments to include with the email.
+  - `filename: string`: Name of the attachment file.
+  - `content: string`: String content of the attachment.
+  - `path: string`: File path or URL to stream the attachment from.
+  - `contentType: string`: The mime type of the content you are attaching. For example, `text/plain` or `text/html`.
+  - `encoding: string`: Encoding used to decode string `content` into a buffer. For example, `base64` or `hex`.
+  - `cid: string`: Content id to reference the attachment as an embedded image in html.
+
+##### array
+
+An array of `mail description` objects can also be provided.
+
+### Delivery filter
+
+The connection's `filter` is applied to every message before it is sent — from `SMTPMailSend` requests, notification pipelines, and any other send over the connection. It has one enforcement point, so no send can bypass it. Because filter values are usually supplied by [`_secret`](operators/secret.md), any field that resolves to `null` or `undefined` is ignored — an unset filter is disabled. This lets one connection config serve every environment: development sets a catch-all, a sandbox sets a domain allowlist or regex, production sets nothing.
+
+- `replaceAddress: string`: Redirect all mail to this single address. When set, it takes precedence — every message is delivered to this address only, with `cc` and `bcc` dropped. Use it to catch all outbound mail in development.
+- `allowlist: string[]`: A list of domains. Only recipients whose domain is in the list are sent to; others are dropped. When every `to` recipient is filtered out, the message is not sent.
+- `regex: string`: A regular expression. Only recipient addresses matching the pattern are sent to.
+
+`allowlist` and `regex` combine — a recipient must satisfy both to receive mail.
+
+### Examples
+
+###### Send a reminder email
+
+```yaml
+connections:
+  - id: my_smtp
+    type: SMTP
+    properties:
+      host: smtp.example.com
+      port: 465
+      secure: true
+      auth:
+        user: my-smtp-user
+        pass:
+          _secret: SMTP_PASS
+      from: Reminders <reminders@example.org>
+# ...
+requests:
+  - id: send_reminder
+    type: SMTPMailSend
+    connectionId: my_smtp
+    properties:
+      to: Harry Potter <harry@example.org>
+      subject: Reminder for Mr. Potter to water the 🌱
+      text: |
+        Hi Harry
+
+        Please remember to water the magic plants today :)
+
+        Thank you
+# ...
+```
+
+###### Catch all mail in a development environment
+
+```yaml
+connections:
+  - id: my_smtp
+    type: SMTP
+    properties:
+      host: smtp.example.com
+      auth:
+        user: my-smtp-user
+        pass:
+          _secret: SMTP_PASS
+      from: App <no-reply@example.org>
+      filter:
+        # In dev, DEV_CATCH_ALL is set and all mail is redirected to it.
+        # In production the secret is unset, so the filter is disabled.
+        replaceAddress:
+          _secret: DEV_CATCH_ALL
+```
+
+###### Send over SendGrid's SMTP relay
+
+```yaml
+connections:
+  - id: my_smtp
+    type: SMTP
+    properties:
+      host: smtp.sendgrid.net
+      port: 465
+      secure: true
+      auth:
+        user: apikey
+        pass:
+          _secret: SENDGRID_API_KEY
+      from: App <notify@example.org>
+```