@lowdefy/docs-content 0.0.0-experimental-20260928120643 → 6.1.0

package/content/actions/posthoginit.md

@@ -1,66 +0,0 @@
-# PostHogInit
-
-```
-(params: {
-  apiKey?: string,
-  apiHost?: string,
-  options?: object,
-  debug?: boolean,
-  enabled?: boolean,
-}): Promise<null>
-```
-
-The `PostHogInit` action downloads and initialises the [PostHog](https://posthog.com) `posthog-js` browser SDK. Every other PostHog action does nothing until it has run, so run it from the `onInit` event of every page, sharing the actions between pages with `_ref`.
-
-`PostHogInit` is idempotent: the first call loads PostHog, and later calls with the same `apiKey` do nothing. Calling it with a different `apiKey` throws, because a second PostHog instance would split the session. With `enabled: false`, `posthog-js` is never downloaded and every other PostHog action becomes a silent no-op. A later call with `enabled: true` still loads PostHog; a call with `enabled: false` after PostHog was loaded throws.
-
-Every event carries the deployment environment: when the app declares [`config.environments`](/lowdefy-schema), `PostHogInit` registers the current environment's name (`LOWDEFY_ENVIRONMENT`) as the `environment` super property, so staging and production events can be told apart in one PostHog project.
-
-An environment with `posthog: { enabled: false }` in `config.environments` switches PostHog off there: `PostHogInit` behaves as `enabled: false` whatever its params say, needs no `apiKey`, and every other PostHog action is a no-op.
-
-If `posthog-js` fails to download, for example on a flaky network, a warning is logged to the browser console and the other PostHog actions do nothing.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `apiKey: string`: __Required__ unless `enabled` is `false` - The PostHog project API key. This is a public, write only key that is meant to ship in the browser bundle, so read it with [`_build.env`](/_build). Never use a personal API key here.
-  - `apiHost: string`: The PostHog ingestion host. Defaults to `https://us.i.posthog.com`. Use `https://eu.i.posthog.com` for the EU cloud, or the host of a self hosted instance.
-  - `options: object`: Passed through to `posthog.init` as its config object. Set `capture_pageview: history_change` to capture a pageview on every client side navigation. Other common options are `person_profiles`, `capture_pageleave`, `autocapture`, `disable_session_recording`, `persistence` and `opt_out_capturing_by_default`. See the [posthog-js config reference](https://posthog.com/docs/libraries/js/config).
-  - `debug: boolean`: Log everything PostHog does to the browser console.
-  - `enabled: boolean`: Set to `false` to skip loading PostHog. Defaults to `true`.
-
-#### Response
-
-`null`, once `posthog-js` has loaded.
-
-#### Examples
-
-###### Initialise PostHog on every page:
-```yaml
-# shared/posthog_init.yaml
-- id: init_posthog
-  type: PostHogInit
-  params:
-    apiKey:
-      _build.env: POSTHOG_API_KEY
-    enabled:
-      _build.ne:
-        - _build.env: POSTHOG_API_KEY
-        - null
-    options:
-      capture_pageview: history_change
-      person_profiles: identified_only
-```
-
-```yaml
-# pages/reports.yaml
-id: reports
-type: PageHeaderMenu
-events:
-  onInit:
-    _ref: shared/posthog_init.yaml
-```
-
-With `POSTHOG_API_KEY` unset, for example in local development, `enabled` is `false` and PostHog is never loaded.

package/content/actions/posthogoptin.md

@@ -1,29 +0,0 @@
-# PostHogOptIn
-
-```
-(void): Promise<null>
-```
-
-The `PostHogOptIn` action starts capturing for this person. Pair it with [`PostHogOptOut`](/PostHogOptOut) and a [`PostHogInit`](/PostHogInit) that sets `options.opt_out_capturing_by_default: true` when consent is required before any data is sent. The choice is remembered in the persistence store configured on `PostHogInit`.
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-The `PostHogOptIn` action does not take any parameters.
-
-#### Examples
-
-###### Accept analytics from a consent banner:
-```yaml
-- id: accept_analytics
-  type: Button
-  properties:
-    title: Accept
-  events:
-    onClick:
-      - id: opt_in
-        type: PostHogOptIn
-```

package/content/actions/posthogoptout.md

@@ -1,29 +0,0 @@
-# PostHogOptOut
-
-```
-(void): Promise<null>
-```
-
-The `PostHogOptOut` action stops capturing for this person. The choice is remembered in the persistence store configured on [`PostHogInit`](/PostHogInit). See [`PostHogOptIn`](/PostHogOptIn) for consent flows.
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-The `PostHogOptOut` action does not take any parameters.
-
-#### Examples
-
-###### Reject analytics from a consent banner:
-```yaml
-- id: reject_analytics
-  type: Button
-  properties:
-    title: Reject
-  events:
-    onClick:
-      - id: opt_out
-        type: PostHogOptOut
-```

package/content/actions/posthogpageview.md

@@ -1,37 +0,0 @@
-# PostHogPageview
-
-```
-(params: {
-  properties?: object,
-}): Promise<null>
-```
-
-The `PostHogPageview` action captures a `$pageview` event by hand.
-
-A Lowdefy app routes on the client without a page load, so the `posthog-js` default only captures the first page. The simplest fix is to set `capture_pageview: history_change` in the [`PostHogInit`](/PostHogInit) options, which captures a pageview on every navigation, and not use this action at all. Use `PostHogPageview` when pageviews need extra properties or tighter control: set `capture_pageview: false` and run it from each page's `onMountAsync` event.
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `properties: object`: Properties to add to the `$pageview` event.
-
-#### Examples
-
-###### Capture pageviews by hand:
-```yaml
-id: reports
-type: PageHeaderMenu
-events:
-  onInit:
-    _ref: shared/posthog_init.yaml # PostHogInit with options.capture_pageview: false
-  onMountAsync:
-    - id: capture_pageview
-      type: PostHogPageview
-      params:
-        properties:
-          section: reports
-```

package/content/actions/posthogreloadfeatureflags.md

@@ -1,47 +0,0 @@
-# PostHogReloadFeatureFlags
-
-```
-(params: {
-  timeout?: integer,
-}): Promise<{ flags: string[], variants: object }>
-```
-
-The `PostHogReloadFeatureFlags` action asks PostHog to evaluate this person's feature flags again, and resolves once the new flags have arrived. Run it after [`PostHogIdentify`](/PostHogIdentify) or [`PostHogGroup`](/PostHogGroup) changed the targeting, then read the flags from its response or with [`PostHogFeatureFlag`](/PostHogFeatureFlag).
-
-It resolves with empty results if PostHog does not answer within `timeout` milliseconds, so a flaky network can never stall the action chain. When PostHog is disabled or `posthog-js` could not be loaded, it resolves with empty results straight away.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `timeout: integer`: Milliseconds to wait for PostHog to answer. Defaults to `5000`. Must not be negative.
-
-#### Response
-
-An object:
-  - `flags: string[]`: The keys of the flags enabled for this person.
-  - `variants: object`: Every flag key mapped to its value.
-
-When PostHog does not answer in time, or is disabled, the response is `{ flags: [], variants: {} }`.
-
-#### Examples
-
-###### Reload flags after switching organization:
-```yaml
-- id: set_group
-  type: PostHogGroup
-  params:
-    type: organization
-    key:
-      _state: organization_id
-- id: reload_flags
-  type: PostHogReloadFeatureFlags
-  params:
-    timeout: 3000
-- id: store_flags
-  type: SetState
-  params:
-    feature_flags:
-      _actions: reload_flags.response.variants
-```

package/content/actions/posthogreset.md

@@ -1,28 +0,0 @@
-# PostHogReset
-
-```
-(params: {
-  resetDeviceId?: boolean,
-}): Promise<null>
-```
-
-The `PostHogReset` action forgets the current person and starts a fresh anonymous session. Run it on sign out so the next person on a shared browser is not merged into this one.
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `resetDeviceId: boolean`: Also generate a new device id, so the browser is not recognised as the same device. Defaults to `false`.
-
-#### Examples
-
-###### Reset PostHog on sign out:
-```yaml
-- id: reset_posthog
-  type: PostHogReset
-- id: logout
-  type: Logout
-```

package/content/actions/posthogsetpersonproperties.md

@@ -1,36 +0,0 @@
-# PostHogSetPersonProperties
-
-```
-(params: {
-  set?: object,
-  setOnce?: object,
-}): Promise<null>
-```
-
-The `PostHogSetPersonProperties` action updates the properties of the person [`PostHogIdentify`](/PostHogIdentify) identified. Each call is a billable event; `posthog-js` skips a call identical to the previous one. Never send personally identifiable information.
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-At least one of `set` or `setOnce` is required.
-  - `set: object`: Person properties to set.
-  - `setOnce: object`: Person properties that are only set if the person does not have them yet.
-
-#### Examples
-
-###### Record a plan change:
-```yaml
-- id: set_person_properties
-  type: PostHogSetPersonProperties
-  params:
-    set:
-      plan:
-        _state: selected_plan
-    setOnce:
-      first_plan:
-        _state: selected_plan
-```

package/content/actions/removelocalstorage.md

@@ -1,26 +0,0 @@
-# RemoveLocalStorage
-
-```
-(params: {
-  key: string
-}): void
-```
-
-The `RemoveLocalStorage` action removes a key from the browser's [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). Removing a key that is not set does nothing.
-
-Keys starting with `lowdefy_` or `lf-` are reserved for settings Lowdefy stores itself, such as the dark mode preference, and the action throws an error if one is used. If the browser blocks local storage, the action fails with an error that is shown to the user and triggers the event's `catch` actions, but is not logged as an app error.
-
-#### Parameters
-
-###### object
-  - `key: string`: __Required__ - The local storage key to remove. Keys starting with `lowdefy_` or `lf-` are reserved.
-
-#### Examples
-
-###### Clear a stored preference:
-```yaml
-- id: clear_preference
-  type: RemoveLocalStorage
-  params:
-    key: dashboard_filters
-```

package/content/actions/setlocalstorage.md

@@ -1,32 +0,0 @@
-# SetLocalStorage
-
-```
-(params: {
-  key: string,
-  value: any
-}): void
-```
-
-The `SetLocalStorage` action stores a value in the browser's [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage), under the given key. Values are serialized, so objects, arrays and dates are read back as the same types by the [`GetLocalStorage`](/GetLocalStorage) action.
-
-Local storage is per browser and per origin, and it is not sent to the server. Do not store secrets, tokens or personal data in it.
-
-Keys starting with `lowdefy_` or `lf-` are reserved for settings Lowdefy stores itself, such as the dark mode preference, and the action throws an error if one is used. If the browser blocks local storage, or the storage quota is full, the action fails with an error that is shown to the user and triggers the event's `catch` actions, but is not logged as an app error.
-
-#### Parameters
-
-###### object
-  - `key: string`: __Required__ - The local storage key to write to. Keys starting with `lowdefy_` or `lf-` are reserved.
-  - `value: any`: __Required__ - The value to store.
-
-#### Examples
-
-###### Remember a user preference:
-```yaml
-- id: save_preference
-  type: SetLocalStorage
-  params:
-    key: dashboard_filters
-    value:
-      _state: filters
-```

package/content/adapter-reference/mongodbauthadapter.md

@@ -1,46 +0,0 @@
-# MongoDBAuthAdapter
-
-The MongoDBAuthAdapter stores the auth engine's users, sessions, accounts, organizations and related records in a MongoDB database. It is configured as `auth.database` and ships with the `MongoDBCollection` connection package.
-
-Collection names follow the fixed `user-*` naming convention applied by the auth engine (`users`, `user-sessions`, `user-accounts`, ...) — there is no collection rename configuration. The `attributes` fields on users, members and invitations are stored as native sub-documents, so they can be filtered and aggregated with normal MongoDB queries.
-
-If you are upgrading from the old `MongoDBAdapter`: the type is renamed, `databaseUri` becomes `uri`, and `options.databaseName` folds into the URI path or the `database` property. See the [auth upgrade guide](/auth-upgrade).
-
-#### Properties
-
-###### object
-  - `uri: string`: Required - Connection uri string for the MongoDB deployment. Should be stored using the _secret operator.
-  - `database: string`: Set the MongoDB database name. This is optional if the database name is specified in the `uri`.
-  - `mongoDBClientOptions: object`: See the [driver documentation](https://mongodb.github.io/node-mongodb-native/) for more information.
-
-#### Examples
-
-###### Minimum configuration.
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  database:
-    id: auth_db
-    type: MongoDBAuthAdapter
-    properties:
-      uri:
-        _secret: AUTH_DATABASE_URI
-```
-
-###### Full configuration.
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  database:
-    id: auth_db
-    type: MongoDBAuthAdapter
-    properties:
-      uri:
-        _secret: AUTH_DATABASE_URI
-      database: my-database # Optional
-      # Optional MongoDB client options, only set these if necessary
-      mongoDBClientOptions:
-        connectTimeoutMS: 2000
-```

package/content/agents/agents-introduction.md

@@ -1,107 +0,0 @@
-# Agents
-
-Lowdefy agents add AI chat capabilities to your app. An agent connects to an AI model provider (like Anthropic, OpenAI, or Google), can use tools to interact with your app's APIs, and streams responses to an [`AgentChat`](/AgentChat) block in the browser.
-
-Agents are defined at the root of your Lowdefy configuration, alongside `connections` and `pages`. You define the agent in YAML, and Lowdefy handles the streaming, tool execution, and UI.
-
-## Quick Start
-
-A connection, an agent, and a chat block — that's all you need:
-
-```yaml
-lowdefy: 6.0.0
-
-connections:
-  - id: anthropic
-    type: Anthropic
-    properties:
-      apiKey:
-        _secret: ANTHROPIC_API_KEY
-
-agents:
-  - id: assistant
-    type: ClaudeAgent
-    connectionId: anthropic
-    properties:
-      model: claude-sonnet-4-20250514
-      instructions: |
-        You are a helpful assistant for Acme Corp. Answer questions
-        about our products and services. Be friendly and concise.
-
-pages:
-  - id: chat
-    type: PageHeaderMenu
-    properties:
-      title: Chat
-    blocks:
-      - id: chat
-        type: AgentChat
-        properties:
-          agentId: assistant
-```
-
-Set the `ANTHROPIC_API_KEY` [secret](/secrets) and you have a fully working AI chat — streaming responses, markdown rendering, code highlighting, and editable messages all work out of the box.
-
-## How Agents Work
-
-When a user sends a message in an [`AgentChat`](/AgentChat) block:
-
-1. The message is sent to the Lowdefy server via a streaming API endpoint.
-2. The server loads the agent configuration, creates a connection to the AI provider, and starts a conversation with the model.
-3. If the agent has tools, the model can call them. Tool calls execute server-side (API endpoints, MCP servers, or sub-agents) and the results are sent back to the model.
-4. The model's response streams back to the browser in real time, updating the chat UI as tokens arrive.
-
-This tool loop continues until the model produces a final text response or reaches the `maxSteps` limit.
-
-## Agent Definition
-
-Agents are defined in the top-level `agents` array in your Lowdefy configuration:
-
-- `id: string`: __Required__ - A unique identifier for the agent.
-- `type: string`: __Required__ - The agent type. See [Anthropic](/Anthropic), [OpenAI](/OpenAI-connection), and [Google](/Google) for available types.
-- `connectionId: string`: __Required__ - The `id` of the connection to use.
-- `properties: object`: Model, instructions, and behavior settings. See [Agent Properties](/agent-properties). __Operators are evaluated__.
-- `tools: array`: API endpoint tools. See [Endpoint Tools](/agent-endpoint-tools).
-- `mcp: array`: MCP server tools. See [MCP Tools](/agent-mcp-tools).
-- `agents: array`: Sub-agent tools. See [Multi-Agent](/agent-multi-agent).
-- `hooks: object`: Server-side lifecycle hooks. See [Server Hooks](/agent-server-hooks).
-
-###### Agent with tools, sub-agents, and hooks:
-```yaml
-agents:
-  - id: support_agent
-    type: ClaudeAgent
-    connectionId: anthropic
-    properties:
-      model: claude-sonnet-4-20250514
-      instructions: |
-        You are a customer support agent. Help users find products
-        and answer questions. Be friendly and concise.
-      maxSteps: 5
-    tools:
-      - search-products
-      - endpointId: create-ticket
-        confirm: true
-    mcp:
-      - mcp_knowledge_base
-    agents:
-      - agentId: billing_agent
-        description: Handles billing and payment questions.
-    hooks:
-      onFinish:
-        - save-conversation
-```
-
-## Beyond Chat
-
-Agents can also run headlessly from [API endpoint routines](/api) using the `CallAgent` step — the agent loops through its tools to completion and the result lands in the routine's `_step` results, no chat UI involved. See [Running Agents As A Routine Step](/api) for details.
-
-## What's Next
-
-- [Agent Properties](/agent-properties) — Configure model, temperature, pruning, and more.
-- [Endpoint Tools](/agent-endpoint-tools) — Give the agent access to your database and APIs.
-- [MCP Tools](/agent-mcp-tools) — Connect to external tool providers via the MCP standard.
-- [Multi-Agent](/agent-multi-agent) — Delegate tasks to specialized sub-agents.
-- [Server Hooks](/agent-server-hooks) — Save conversations, generate titles, and run server-side logic.
-- [AgentChat](/AgentChat) — Configure the chat UI block.
-- [AgentConversations](/AgentConversations) — Add a conversation history sidebar.

package/content/callback-reference/auth0logoutcallback.md

@@ -1,54 +0,0 @@
-# Auth0LogoutCallback
-
-The Auth0LogoutCallback can be used to log the user out from Auth0 when logging out of the Lowdefy app. The callback takes a `returnToPageId` property, which is the pageId the user will be directed to after logout from Auth0 is complete. The URL which the user will be directed to needs to be configured with Auth0 as an allowed logout URL.
-
-To trigger the Auth0 logout, the `Logout` action `callbackUrl.url` param should be set to `AUTH0_LOGOUT`.
-
-#### Properties
-
-###### object
-- `issuer: string`: Auth0 issuer URL. This should be the same that was used for the `Auth0Provider`.
-- `clientId: string`: Auth0 client ID. This should be the same that was used for the `Auth0Provider`.
-- `returnToPagedId: string`: The pageId in the Lowdefy application to which the user should be redirected affter logging out from Auth0.
-
-#### Examples
-
-###### Configuring Auth0LogoutCallback.
-
-```yaml
-lowdefy: 6.0.0
-providers:
-  - id: auth0
-    type: Auth0Provider
-    properties:
-      clientId:
-        _secret: AUTH0_CLIENT_ID
-      clientSecret:
-        _secret: AUTH0_CLIENT_SECRET
-      issuer:
-        _secret: AUTH0_ISSUER
-callbacks:
-  - id: auth0_logout
-    type: Auth0LogoutCallback
-    properties:
-      clientId:
-        _secret: AUTH0_CLIENT_ID
-      issuer:
-        _secret: AUTH0_ISSUER
-      returnToPagedId: logged-out
-```
-
-The Auth0 allowed logout URLS should be set to `https://my-app.com/logged-out` for production and `http://localhost:3000/logged-out` for development.
-
-###### Logging out.
-```yaml
-id: logout_button
-type: Button
-events:
-  onClick:
-    - id: logout
-      type: Logout
-      params:
-        callbackUrl:
-          url: AUTH0_LOGOUT
-```