@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/tutorial/tutorial-start.md

@@ -0,0 +1,71 @@
+# 1. Getting started
+
+In this tutorial, we will be creating a simple ticketing app that allows users to file new tickets and see a list of outstanding tickets. The app reads product data from [DummyJSON](https://dummyjson.com/) and will write the ticket data to an [SQLite](https://www.sqlite.org/) database.
+
+### Requirements
+
+The Lowdefy CLI (Command Line Interface) is needed to run the development server. To run the Lowdefy CLI you need to install Node.js at version 22 or greater. If you don't have it installed, download Node.js from https://nodejs.org/en/download/, and follow the installation steps for your computer. All of the default settings given by the installer are fine for what we need. You will also need a text editor to modify the Lowdefy configuration files.
+
+Lowdefy also requires [`pnpm`](https://pnpm.io/) to be installed. We recommend making activating [Corepack](https://nodejs.org/api/corepack.html), even though it is an experimental feature, as this is the simplest way to install `pnpm`. Alternative methods to install `pnpm` can also be found [here](https://pnpm.io/installation). To activate Corepack, run the following in your computer's command line interface (Windows CMD, Terminal on MacOS).
+
+$
+
+corepack enable
+
+##### YAML files
+
+If you don't have any experience using YAML, please familiarize yourself YAML before continuing.
+
+[This video is a good introduction to YAML.](https://www.youtube.com/embed/cdLNKUoMc6c?origin=https://docs.lowdefy.com)
+
+Lowdefy apps are written using YAML files. YAML files are useful for storing structured data, like the configuration of all of the elements of your app. YAML files focus on being easily readable by humans, this means they don't use lots of syntactic elements like brackets that make it difficult for humans to read, but instead use __indentation to indicate structure__. While this does make the file easier to read, this means care has to be taken that the data structure is as you intended.
+
+> Lowdefy apps can also be defined using JSON files, or a mix of YAML and JSON. We find YAML files more convenient to write.
+
+#### 1.1. Create a project directory
+
+Create a directory (folder) on your computer where you would like to create the configuration files for your project. We will be referring to this directory as the project directory.
+
+#### 1.2. Open a command line interface
+
+Open your computer's command line interface and change directory (`cd`) to the project directory.
+
+#### 1.3. Initialize an app
+
+Use the Lowdefy CLI to initialize your project. We recommend using [`pnpx`](https://pnpm.io/6.x/pnpx-cli) to run the Lowdefy CLI, since this will always run the latest version of the CLI.
+
+Run the following in your terminal:
+
+$
+
+pnpx lowdefy@5 init
+
+This will create two files in your current working directory. The first file, called `lowdefy.yaml` is the starting point of your app's configuration. The second, called `.gitignore`, is a hidden file that tells `git`, a version control tool, not to version or upload some specific files.
+
+> __Error: A "lowdefy.yaml" file already exists__: Try running the command in a new directory or consider deleting the _lowdefy.yaml_ file in your current working directory.
+
+#### 1.4. Start the development server
+
+Run:
+
+$
+
+pnpx lowdefy@5 dev
+
+Your browser should open on http://localhost:3000, and you should see the following:
+
+Made by a Lowdefy 🤖
+
+> __Error: Could not find "lowdefy.yaml"__: Make sure your current working directory contains the _lowdefy.yaml_ file. You can verify this by running the `dir` (Windows) or `ls` (MacOS) command.
+
+### What happened
+
+The Lowdefy CLI helps you develop a Lowdefy app.
+
+We used the `pnpx lowdefy@5 init` command to initialize a new project. This created all the essential files.
+
+We also used the `pnpx lowdefy@5 dev` command to start a development server. The development server runs a Lowdefy app locally on your computer, which can be accessed at http://localhost:3000. The development server watches your configuration files, and if any of them changes it "builds" (compiles the configuration together for the server to serve) the configuration again and refreshes the browser to show the changes.
+
+### Up next
+
+Let's see how easy it is to create a new page.

package/content/user-authentication/auth-providers.md

@@ -0,0 +1,15 @@
+# Authentication Providers
+
+Providers are used to configure the identity providers that will be used to authenticate users. To add user authentication to your app, at least one provider must be configured. More than one provider can be configured to allow users to sign in using their choice of identity provider.
+
+## OAuth Providers
+
+Auth.js supports a large number of OAuth identity providers. During the OAuth flow, a user is redirected to a webpage hosted by the provider, where they usually authenticate using their credentials if not already signed in. They are then redirected back to the Lowdefy application, and the Lowdefy application interacts with the providers's API to verify the login and get the user details like name and email address.
+
+## Email Provider
+
+Auth.js supports email login, where a link with a token is sent to the user's email address and the user can click on the link to log in (often called "magic links"). To use email authentication an Adapter must be configured, since the verification tokens need to be stored in a database.
+
+## Credentials Provider
+
+Auth.js provides a credentials provider, which can be used to sign in using any other credentials, such as username and password or Web3. Lowdefy does not provide any credential providers, but a credentials provider can be written as a [plugin](/plugins-dev).

package/content/user-authentication/login-and-logout.md

@@ -0,0 +1,122 @@
+# Login and Logout
+
+The [`Login`](/Login) and [`Logout`](/Logout) actions can be used to log users in and out.
+
+## Login
+
+The `Login` action is used to start the user login flow. If only one OAuth provider is configured, or the `Login` action is called with a `providerId`, the `Login` action requests the Provider's authorization URL from the Lowdefy server, and redirects the user to this URL. Otherwise, the action redirects the user to a page where the user can choose which provider to use to sign in.
+
+The authorization url usually hosts a page where the user can input their credentials. After the user has logged in successfully, the user is redirected to the `/api/auth/callback/<provider_id>` route in the Lowdefy app, where the rest of the authorization code flow is completed. This URL usually needs to be configured in the identity provider's settings.
+
+The `callbackUrl` parameters of the Login action specify where the user is redirected after login is complete. If `callbackUrl` parameters not set, the user will return to the page from which the action was called.
+
+The parameters are:
+- `authUrl: object`:
+  - `urlQuery: object`: Query parameters to set for the authorization URL.
+- `callbackUrl: object`:
+  - `home: boolean`: Redirect to the home page after the login flow is complete.
+  - `pageId: string`: The pageId of the page to redirect to after the login flow is complete.
+  - `url: string`: The URL to redirect to after the login flow is complete.
+  - `urlQuery: object`: The urlQuery to set for the page the user is redirected to after login.
+- `providerId: string`: The ID of the provider that should be used for login. If not set and only one provider is configured the configured provider will be used. Else the user will be redirected to a sign in page where they can choose a provider.
+
+## Examples
+
+###### A login page that redirects users in the onMount event:
+```yaml
+id: login
+type: Box
+events:
+  onMount:
+    # Redirect to "page1" if user is already logged in.
+    - id: logged_in_redirect
+      type: Link
+      skip:
+        _eq:
+          - _user: sub
+          - null
+      params:
+        pageId: page1
+    # Call the Login action to log the user in.
+    - id: login
+      type: Login
+      skip:
+        _ne:
+          - _user: sub
+          - null
+      params:
+        # Redirect to "page1" after login is complete.
+        callbackUrl:
+          pageId: page1
+```
+
+###### A set of login and logout buttons:
+```yaml
+id: login_logout
+type: Box
+blocks:
+  - id: Login
+    type: Button
+    visible:
+      _eq:
+        - _user: sub
+        - null
+    events:
+      onClick:
+        - id: login
+          type: Login
+  - id: Logout
+    type: Button
+    visible:
+      _ne:
+        - _user: sub
+        - null
+    events:
+      onClick:
+        - id: logout
+          type: Logout
+```
+
+###### A signup button that uses `authUrl.urlQuery` to request the signup screen:
+```yaml
+id: Signup
+type: Button
+events:
+  onClick:
+    - id: signup
+      type: Login
+      params:
+        authUrl:
+          urlQuery:
+            screen_hint: signup
+```
+
+## Logout
+
+When the `Logout` action is called, the user data and authorization cookies are cleared by the app.
+
+The `callbackUrl` parameters of the Logout action specify where the user is redirected after logout is complete. If `callbackUrl` parameters are not set, the user will return to the page from which the action was called.
+
+The parameters are:
+- `callbackUrl: object`:
+  - `home: boolean`: Redirect to the home page after the login flow is complete.
+  - `pageId: string`: The pageId of the page to redirect to after the login flow is complete.
+  - `url: string`: The URL to redirect to after the login flow is complete.
+  - `urlQuery: object`: The urlQuery to set for the page the user is redirected to after login.
+- `redirect: boolean`: If set to `false` the user session will be cleared, but the page will not be reloaded.
+
+
+#### Examples
+
+###### Redirect to the `logged-out` page in the app after logout:
+```yaml
+id: Logout
+type: Button
+events:
+  onClick:
+    - id: logout
+      type: Logout
+      params:
+        callbackUrl:
+          pageId: logged-out
+```

package/content/user-authentication/users-introduction.md

@@ -0,0 +1,31 @@
+# Introduction
+
+Lowdefy uses the [Auth.js](https://authjs.dev) library to implement user authentication. Auth.js has built in support for many sign-in services, and can be extended using Lowdefy [plugins](/plugins). User authentication can be stateless using JSON Web Tokens (JWT) or can use database sessions.
+
+User authorization is done at the page level. Pages can be set as public or private, and role-based-access control can be used to [restrict access](https://docs.lowdefy.com/protected-pages-apis) to pages and APIs based on a user's [roles](https://docs.lowdefy.com/roles). Authorisation checks are done on the Lowdefy server when executing requests, respecting the same authorization rules as the page the request is defined on.
+
+The authentication system consists of the following components:
+
+## Providers
+
+Providers configure the identity provider used to authenticate the user. These are typically OAuth based identity providers like Google or Auth0. All the default providers in the Auth.js library can be used, and additional providers can be added as plugins. Multiple providers can be configured, but at least one should be configured to have a working authentication system.
+
+## Adapters
+
+Adapters configure the connection to the database if a database is used, allowing for database sessions. This is optional, and JSON Web Tokens will be used if no adapter is configured.
+
+## Callbacks
+
+Callbacks are functions that are executed during certain actions of the authentication process. They are blocking - if an error is thrown they stop the action, so they can be used for access control checks. A few default callbacks are provided, but a [custom plugin](https://docs.lowdefy.com/plugins-dev) will likely need to be written.
+
+## Events
+
+Events are functions that are executed after certain actions of the authentication process. They are not blocking to authentication, and are best used for audit logs/ reporting or other side effects.
+
+## Login and Logout actions
+
+The Login and Logout actions are used to start the login and logout processes.
+
+## \_user operator
+
+The `_user` operator can be used to access data in the user object received from the identity provider. The OpenID Connect standard claims (fields like `name` or `email`) are mapped to the user object by default and addition fields can be configured using the `userFields` configuration option.