@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/connections/googlecloudstorage.md

@@ -0,0 +1,139 @@
+# Google Cloud Storage
+
+Google Cloud Storage is the object storage service provided by Google Cloud Platform. Data is stored as objects in buckets, and objects can be public or private. You can read more [here](https://cloud.google.com/storage/docs).
+
+Lowdefy integrates with Google Cloud Storage using signed URLs and signed POST policies — short-lived credentials that let the browser upload and download objects directly, without file content passing through the Lowdefy server. The connection plugs into the provider-neutral <a href="/Upload">Upload</a> and <a href="/Download">Download</a> blocks.
+
+Direct browser uploads require [CORS configuration on the bucket](https://cloud.google.com/storage/docs/using-cors) that allows your app's origin.
+
+## Connections
+
+Connection types:
+  - GoogleCloudStorageBucket
+
+### GoogleCloudStorageBucket
+
+The `GoogleCloudStorageBucket` connection is used to connect to a Google Cloud Storage bucket.
+
+#### Properties
+- `bucket: string`: __Required__ - Google Cloud Storage bucket name.
+- `client_email: string`: The email of your service account. If omitted, Application Default Credentials are used (e.g. the attached service account when running on GCP).
+- `private_key: string`: The private key for your service account. If omitted, Application Default Credentials are used.
+- `projectId: string`: The Google Cloud project ID the bucket belongs to.
+- `publicUrlBase: string`: Base URL used to construct stable public object URLs (e.g. a 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
+
+###### Reads and writes with a service account:
+```yaml
+connections:
+  - id: my_bucket
+    type: GoogleCloudStorageBucket
+    properties:
+      bucket: my-bucket-name
+      projectId: my-project
+      client_email:
+        _secret: GCS_CLIENT_EMAIL
+      private_key:
+        _secret: GCS_PRIVATE_KEY
+      write: true
+```
+Environment variables:
+```
+LOWDEFY_SECRET_GCS_CLIENT_EMAIL = service-account@my-project.iam.gserviceaccount.com
+LOWDEFY_SECRET_GCS_PRIVATE_KEY = -----BEGIN PRIVATE KEY-----\n...
+```
+
+## Requests
+
+Request types:
+  - GcsSignedPostPolicy
+  - GcsSignedGetUrl
+  - GcsGetObject
+  - GcsPutObject
+
+### GcsSignedPostPolicy
+
+The `GcsSignedPostPolicy` request signs a V4 POST policy for direct browser uploads. 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. The connection must set `write: true`.
+
+#### Properties
+- `key: string`: __Required__ - Key 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 policy should be valid.
+- `fields: object`: Additional form fields to include in the POST policy (e.g. `acl`).
+- `conditions: array`: Conditions to be enforced on the request. See [POST policy conditions](https://cloud.google.com/storage/docs/xml-api/post-object-forms#policy_document).
+
+#### Examples
+
+###### Upload a file with the user's filename:
+```yaml
+requests:
+  - id: upload_policy
+    type: GcsSignedPostPolicy
+    connectionId: my_bucket
+    payload:
+      name:
+        _event: file.name
+    properties:
+      key:
+        _string.concat:
+          - 'uploads/'
+          - _payload: name
+```
+
+### GcsSignedGetUrl
+
+The `GcsSignedGetUrl` request signs a V4 read 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 under which the object is stored.
+- `expires: number`: Default: `3600` - Number of seconds for which the signed URL should be valid.
+- `public: boolean`: Default: `false` - Return a stable, non-expiring public URL (`https://storage.googleapis.com/{bucket}/{key}`, or `${publicUrlBase}/${key}` when the connection sets `publicUrlBase`) instead of a signed URL. The object must be publicly readable; this is author-declared and never checked at runtime.
+- `responseDisposition: string`: Sets the Content-Disposition header of the response.
+- `responseType: string`: Sets the Content-Type header of the response.
+
+### GcsGetObject
+
+The `GcsGetObject` 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. The connection must allow reads (`read` is `true` by
+default). Returns `{ bucket, key, content, contentType, size }`.
+
+#### Properties
+- `key: string`: __Required__ - Key under which the object is stored.
+
+### GcsPutObject
+
+The `GcsPutObject` 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).
+- `public: boolean`: Default: `false` - Make the stored object publicly readable.
+
+#### Examples
+
+###### Store a file sent as an endpoint payload:
+```yaml
+api:
+  - id: store_report
+    type: Api
+    routine:
+      - id: put_object
+        type: GcsPutObject
+        connectionId: my_bucket
+        properties:
+          key:
+            _string.concat:
+              - 'reports/'
+              - _payload: name
+          content:
+            _payload: content
+          contentType:
+            _payload: type
+      - ':return':
+          key:
+            _step: put_object.key
+```

package/content/connections/googlesheet.md

@@ -0,0 +1,313 @@
+# Google Sheets
+
+## Connections
+
+Connection types:
+  - GoogleSheet
+
+### GoogleSheet
+
+The `GoogleSheet` connection offers the flexibility to connect to Google Sheets using either an API key or a service account. While an API key is suitable for read-only access to public sheets, most applications will benefit more from using a service account, which offers broader capabilities. For detailed instructions on creating a service account, you can refer to the [Google Sheets API Quickstart Guide](https://developers.google.com/sheets/api/quickstart/js) and the [Google Workspace Guide on Creating a Project](https://developers.google.com/workspace/guides/create-project).
+
+This connection refers to the entire document as the `spreadsheet`, and the individual sheets in the document as `sheets`. The spreadsheet is identified by it's `spreadsheetId`, and sheets can either be identified by their `sheetId` or their `index` (position in the document starting from 0).
+
+When a sheet is accessed in a browser the url either looks like:
+`https://docs.google.com/spreadsheets/d/{spreadsheetId}/edit#gid={sheetId}`
+
+The `GoogleSheet` connection works with sheets as a row based data store. Each row is a data record, and a header row needs to be present to define the column names. This header needs to be created in the Google Sheets web interface. Types can be specified for any of the columns in the sheet. If a type is not specified, the value will be read as a string. The `json` type will stringify a object as JSON before saving it, and parse it again when reading.
+
+#### Properties
+- `apiKey: string`: API key for your google project.
+- `client_email: string`: The email address of your service account.
+- `private_key: string`: The private key for your service account. Base64 encode the string if you have issues with the newline characters in the string.
+- `sheetId: string`: The ID of the worksheet. Can be found in the URL as the "gid" parameter. One of `sheetId` or `sheetIndex` is required.
+- `sheetIndex: number`: The position of the worksheet as they appear in the Google sheets UI. Starts from 0. One of `sheetId` or `sheetIndex` is required.
+- `spreadsheetId: string`: __Required__ - The document ID from the URL of the spreadsheet.
+- `columnTypes: object`: An object that defines the data types for each column. Each key should be the column name, and the value should be one of: `string`, `number`, `boolean`, `date`, or `json`.
+- `read: boolean`: Default: `true` - Allow read operations like find on the sheet.
+- `write: boolean`: Default: `false` - Allow write operations like update on the sheet.
+
+#### Examples
+
+###### Read only access to first sheet in a public spreadsheet:
+```yaml
+connections:
+  - id: public_sheet
+    type: GoogleSheet
+    properties:
+      apiKey:
+        _secret: GOOGLE_SHEETS_API_KEY
+      sheetIndex: 0
+      spreadsheetId: ubQsWYNGRUq0gFB1sAp2r9oYE19lZ8yGA1T6y0yBoLPW
+```
+
+###### Access with a service account, with defined types:
+```yaml
+connections:
+  - id: my_sheet
+    type: GoogleSheet
+    properties:
+      client_email:
+        _secret: GOOGLE_SHEETS_CLIENT_EMAIL
+      private_key:
+        _base64.decode:
+          _secret: GOOGLE_SHEETS_PRIVATE_KEY
+      sheetId: '1199545345'
+      spreadsheetId: ubQsWYNGRUq0gFB1sAp2r9oYE19lZ8yGA1T6y0yBoLPW
+      columnTypes:
+        name: string
+        age: number
+        birthday: date
+        subscribed: boolean
+        address: json
+```
+
+## Requests
+
+Request types:
+  - GoogleSheetAppendMany
+  - GoogleSheetAppendOne
+  - GoogleSheetDeleteOne
+  - GoogleSheetGetMany
+  - GoogleSheetGetOne
+  - GoogleSheetUpdateMany
+  - GoogleSheetUpdateOne
+
+### GoogleSheetAppendMany
+
+The `GoogleSheetAppendMany` request inserts an array of documents as rows in a Google Sheet.
+
+#### Properties
+- `rows: object[]`: __Required__ - The rows to insert into the sheet. An an array of objects where keys are the column names and values are the values to insert.
+- `options: object`: Optional settings. Supported settings are:
+  - `raw: boolean`: Store raw values instead of converting as if typed into the sheets UI.
+
+#### Examples
+
+###### Insert a list of rows.
+```yaml
+requests:
+  - id: append_rows
+    type:  GoogleSheetAppendMany
+    connectionId: google_sheets
+    properties:
+      rows:
+        - name: D.Va
+          role: Tank
+        - name: Tracer
+          role: Damage
+        - name: Genji
+          role: Damage
+        - name: Reinhart
+          role: Tank
+        - name: Mercy
+          role: Support
+```
+
+### GoogleSheetAppendOne
+
+The `GoogleSheetAppendOne` request inserts a documents as a row in a Google Sheet.
+
+#### Properties
+- `row: object`: __Required__ - The row to insert into the sheet. An object where keys are the column names and values are the values to insert.
+- `options: object`: Optional settings. Supported settings are:
+  - `raw: boolean`: Store raw values instead of converting as if typed into the sheets UI.
+
+#### Examples
+
+###### Insert a single row:
+```yaml
+requests:
+  - id: insert_dva
+    type:  GoogleSheetAppendOne
+    connectionId: google_sheets
+    properties:
+      row:
+        name: D.Va
+        role: Tank
+        real_name: Hana Song
+        age: 19
+```
+
+### GoogleSheetDeleteOne
+
+The `GoogleSheetDeleteOne` request deletes a row from a Google Sheet. It deletes the first row matched by the filter, written as a MongoDB query expression.
+
+#### Properties
+- `filter: object`: __Required__ - A MongoDB query expression to filter the data. The first row matched by the filter will be deleted.
+- `options: object`: Optional settings. Supported settings are:
+  - `limit: number`: The maximum number of rows to fetch.
+  - `skip: number`: The number of rows to skip from the top of the sheet.
+
+#### Examples
+
+###### Delete the row where name is "Hanzo".
+```yaml
+requests:
+  - id: delete_hanzo
+    type:  GoogleSheetDeleteOne
+    connectionId: google_sheets
+    properties:
+      filter:
+        name:
+          $eq: Hanzo
+```
+
+### GoogleSheetGetMany
+
+The `GoogleSheetGetMany` request fetches a number of rows from the spreadsheet. The `limit` and `skip` options can be used to control which documents are read from the spreadsheet. The filter or pipeline options can then be used to filter or transform the fetched data.
+
+#### Properties
+- `filter: object`: A MongoDB query expression to filter the data.
+- `pipeline: object[]`: A MongoDB aggregation pipeline to transform the data.
+- `options: object`: Optional settings. Supported settings are:
+  - `limit: number`: The maximum number of rows to fetch.
+  - `skip: number`: The number of rows to skip from the top of the sheet.
+
+#### Examples
+
+###### Get the first 10 rows.
+```yaml
+requests:
+  - id: get_10_rows
+    type:  GoogleSheetGetMany
+    connectionId: google_sheets
+    properties:
+      options:
+        limit: 10
+```
+
+###### Pagination using limit and skip.
+```yaml
+requests:
+  - id: get_10_rows
+    type:  GoogleSheetGetMany
+    connectionId: google_sheets
+    payload:
+      page_size:
+        _state: page_size
+      page_number:
+        _state: page_number
+    properties:
+      options:
+        skip:
+          _product:
+            - _payload: page_size
+            - _subtract:
+                - _payload: page_number
+                - 1
+        limit:
+          _payload: page_size
+```
+
+###### Get all records where age is greater than 25.
+```yaml
+requests:
+  - id: get_10_rows
+    type:  GoogleSheetGetMany
+    connectionId: google_sheets
+    properties:
+      filter:
+        age:
+          $gt: 25
+```
+
+###### Use an aggregation pipeline to aggregate data.
+```yaml
+requests:
+  - id: get_10_rows
+    type:  GoogleSheetGetMany
+    connectionId: google_sheets
+    properties:
+      pipeline:
+        - $group:
+            _id: $region
+            score:
+              $avg: $score
+        - $project:
+            _id: 0
+            region: $_id
+            score: 1
+        - $sort:
+            score: 1
+```
+
+### GoogleSheetGetOne
+
+The `GoogleSheetGetOne` request fetches a single rows from the spreadsheet. The `limit` and `skip` options can be used to control which documents are read from the spreadsheet. The filter option can then be used to filter or select which row is returned.
+
+#### Properties
+- `filter: object`: A MongoDB query expression to filter the data.
+- `options: object`: Optional settings. Supported settings are:
+  - `limit: number`: The maximum number of rows to fetch.
+  - `skip: number`: The number of rows to skip from the top of the sheet.
+
+#### Examples
+
+###### Get row where name is "Zarya".
+```yaml
+requests:
+  - id: get_10_rows
+    type:  GoogleSheetGetOne
+    connectionId: google_sheets
+    properties:
+      filter:
+        name:
+          $eq: Zarya
+```
+
+### GoogleSheetUpdateMany
+
+The `GoogleSheetUpdateMany` request updates all the rows matched by the filter.
+
+#### Properties
+- `filter: object`: A MongoDB query expression to filter the data. . All rows matched by the filter will be updated.
+- `update: object`: The update to apply to the row. An object where keys are the column names and values are the updated values.
+- `options: object`: Optional settings. Supported settings are:
+  - `limit: number`: The maximum number of rows to fetch.
+  - `raw: boolean`: Store raw values instead of converting as if typed into the sheets UI.
+  - `skip: number`: The number of rows to skip from the top of the sheet.
+
+#### Examples
+
+###### Update all rows where age is less than 18.
+```yaml
+requests:
+  - id: get_10_rows
+    type:  GoogleSheetUpdateMany
+    connectionId: google_sheets
+    properties:
+      filter:
+        age:
+          $lt: 18
+      update:
+        minor: true
+```
+### GoogleSheetUpdateOne
+
+The `GoogleSheetUpdateOne` request updates the first row matched by the filter.
+
+#### Properties
+- `filter: object`: A MongoDB query expression to filter the data. . The first row matched by the filter will be updated.
+- `update: object`: The update to apply to the row. An object where keys are the column names and values are the updated values.
+- `options: object`: Optional settings. Supported settings are:
+  - `limit: number`: The maximum number of rows to fetch.
+  - `raw: boolean`: Store raw values instead of converting as if typed into the sheets UI.
+  - `skip: number`: The number of rows to skip from the top of the sheet.
+  - `upsert: boolean`: Insert the row if no rows are matched by the filter.
+
+#### Examples
+
+###### Update the row for "Doomfist"
+```yaml
+requests:
+  - id: get_10_rows
+    type:  GoogleSheetUpdateOne
+    connectionId: google_sheets
+    properties:
+      filter:
+        name:
+          $eq: Doomfist
+      update:
+        overpowered: true
+```

package/content/connections/knex.md

@@ -0,0 +1,206 @@
+# Knex
+
+[`Knex.js`](http://knexjs.org) is a SQL query builder that can be used to connect to [PostgreSQL](/PostgreSQL), [MS SQL Server](/MSSQL), [MySQL](/MySQL), [MariaDB](/MariaDB), [SQLite](/SQLite), Oracle, and [Amazon Redshift](/AmazonRedshift) databases.
+
+The Knex connection can be used to execute raw SQL queries using the `KnexRaw` requests, or the Knex query builder can be used with the `KnexBuilder` request.
+
+For more details on specific databases, see the database documentation:
+
+## Connections
+
+Connection types:
+  - Knex
+
+### Knex
+
+#### Properties
+- `client: enum`: __Required__ - The database client to use. One of:
+  - `better-sqlite3`
+  - `sqlite` (alias of `better-sqlite3`)
+  - `mssql`
+  - `mysql2`
+  - `oracledb`
+  - `postgres`
+  - `pg` (alias of `postgres`)
+  - `postgresql` (alias of `postgres`)
+  - `redshift`
+- `connection: object | string`: __Required__ - Connection string or object to pass to the database client. See the specific client documentation for more details.
+- `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
+
+###### MySQL with connection object:
+```yaml
+connections:
+  - id: mysql
+    type: Knex
+    properties:
+      client: mysql2
+      connection:
+        host:
+          _secret: MYSQL_HOST
+        user:
+          _secret: MYSQL_USER
+        database:
+          _secret: MYSQL_DB
+        password:
+          _secret: MYSQL_PASSWORD
+```
+Environment variables:
+```
+LOWDEFY_SECRET_MYSQL_HOST = database.server.com
+LOWDEFY_SECRET_MYSQL_DB = db
+LOWDEFY_SECRET_MYSQL_USER = user
+LOWDEFY_SECRET_MYSQL_PASSWORD = password
+```
+
+###### PostgreSQL with secret connection string:
+```yaml
+connections:
+  - id: postgres
+    type: Knex
+    properties:
+      client: postgres
+      connection:
+        _secret: PG_CONNECTION_STRING
+```
+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
+```