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

package/content/plugins/posthog.md

@@ -1,275 +0,0 @@
-# PostHog
-
-The `@lowdefy/plugin-posthog` plugin adds [PostHog](https://posthog.com) product analytics to a Lowdefy app. It wraps the `posthog-js` browser SDK in a set of actions: initialise PostHog, capture events, identify people and groups, manage consent and read feature flags.
-
-The plugin bundles `posthog-js` as a module, so no script tag, snippet or reverse proxy configuration is needed.
-
-## Install
-
-The `@lowdefy/plugin-posthog` package is included by default, so no `plugins` entry is needed in `lowdefy.yaml`. The `posthog-js` SDK is loaded lazily: it is downloaded the first time [`PostHogInit`](/PostHogInit) runs with PostHog enabled, so an app with analytics switched off never downloads or runs it.
-
-## Initialise PostHog
-
-The [`PostHogInit`](/PostHogInit) action loads and configures `posthog-js`. Every other action in this package does nothing until it has run. A user can open the app on any page, so run it from the `onInit` event of every page. Keep the actions in one file and reference it from each page with `_ref`:
-
-```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
-- id: identify_person
-  type: PostHogIdentify
-  params:
-    id:
-      _user: id
-```
-
-```yaml
-# pages/reports.yaml
-id: reports
-type: PageHeaderMenu
-events:
-  onInit:
-    _ref: shared/posthog_init.yaml
-```
-
-When a page has `onInit` actions of its own, concatenate the lists at build time:
-
-```yaml
-events:
-  onInit:
-    _build.array.concat:
-      - _ref: shared/posthog_init.yaml
-      - - id: get_report
-          type: Request
-          params: get_report
-```
-
-`PostHogInit` is idempotent. The first call downloads and initialises `posthog-js`; later calls with the same `apiKey` do nothing, so running it on every page is safe. Calling it with a different `apiKey` throws, because a second PostHog instance would split the session.
-
-The PostHog project API key is a public, write only key that is meant to ship in the browser bundle, so [`_build.env`](/_build) is the right operator for it. Never use a personal API key here.
-
-###### Turning analytics off
-
-With `enabled: false`, `PostHogInit` does not load `posthog-js` and every other action in this package becomes a silent no-op, so `apiKey` is not required. The example above sets `enabled` from the key itself: leave `POSTHOG_API_KEY` unset in local development and set it in the deployments that should send data. Any other build time switch works too, for example a `POSTHOG_ENABLED` environment variable:
-
-```yaml
-enabled:
-  _build.eq:
-    - _build.env: POSTHOG_ENABLED
-    - 'true'
-```
-
-A later `PostHogInit` call with `enabled: true` and an `apiKey` still loads PostHog after a disabled call. The reverse throws: once PostHog is running, use [`PostHogOptOut`](/PostHogOptOut) to stop capturing for a person.
-
-## Analytics never breaks the app
-
-Every action in this package, except `PostHogInit`, does nothing and returns `null` when PostHog is disabled or `posthog-js` could not be downloaded. A disabled environment or a flaky network can never throw from an analytics action and can never stop an event chain. [`PostHogFeatureFlag`](/PostHogFeatureFlag) returns its configured `default` instead of `null`, so flag driven config keeps working with PostHog switched off, and [`PostHogReloadFeatureFlags`](/PostHogReloadFeatureFlags) returns `{ flags: [], variants: {} }`.
-
-Two kinds of config mistake are still reported:
-
-- __Invalid params__ always throw, whether PostHog is enabled or not, so a mistake shows up in development even when analytics is switched off there.
-- __A PostHog action that runs before `PostHogInit`__ does nothing, and logs a warning to the browser console once.
-
-An action that runs while `PostHogInit` is still downloading `posthog-js` waits for it to finish.
-
-## Never send personal data
-
-Never send personally identifiable information to PostHog: no names, no email addresses, no phone numbers, and no free text a user typed into a form. Send stable ids and low cardinality attributes such as a plan name, a role, a locale or an organization id.
-
-## Pageviews
-
-A Lowdefy app routes on the client without a page load, so the `posthog-js` default, `capture_pageview: true`, only captures the first page. Set `capture_pageview: history_change` in the `PostHogInit` options, as in the example above, and `posthog-js` captures a `$pageview` every time the path changes. It also captures a `$pageleave` when the tab is closed, which PostHog needs for bounce rate and time on page.
-
-To capture pageviews by hand instead, for example to add properties to them, set `capture_pageview: false` and run [`PostHogPageview`](/PostHogPageview) from each page's `onMountAsync` event, which runs every time the page is shown without holding it in a loading state:
-
-```yaml
-# pages/reports.yaml
-id: reports
-type: PageHeaderMenu
-events:
-  onInit:
-    _ref: shared/posthog_init.yaml
-  onMountAsync:
-    - id: capture_pageview
-      type: PostHogPageview
-      params:
-        properties:
-          section: reports
-```
-
-With automatic pageviews off, `posthog-js` also stops capturing pageleaves, because `capture_pageleave` defaults to `if_capture_pageview`. Set `capture_pageleave: true` in the options to keep them, or capture one by hand with [`PostHogCapturePageLeave`](/PostHogCapturePageLeave), for example before a `Link` or `Logout` action. The page `onHidden` event is not a page leave: it also fires when the browser window loses focus.
-
-## Identify a person
-
-[`PostHogIdentify`](/PostHogIdentify) ties the current browser session to a person. Run it once the user is known, usually right after `PostHogInit` in the shared page `onInit` actions, as in the example above, or after a successful login.
-
-```yaml
-- id: identify_person
-  type: PostHogIdentify
-  params:
-    id:
-      _user: id
-    properties:
-      role:
-        _user: role
-      locale:
-        _locale: active
-```
-
-A missing or empty `id` is a no-op, so on a public page the anonymous session is left alone. That anonymous session is what a later `PostHogIdentify` merges into the person, which is what makes signup funnels work. `null` and `undefined` property values are dropped, so an absent value never overwrites one PostHog already has.
-
-The action is safe to run on every page. It reads the identity `posthog-js` already holds:
-
-- __Same person__: when the id is already the current `distinct_id`, it only updates the person properties, if any are given. `posthog-js` skips a property update identical to the previous one.
-- __Person swap__: PostHog refuses to move an identified `distinct_id` onto a different person, so when the browser is identified as someone else, `PostHogIdentify` calls `reset()` before identifying the new person.
-- __Anonymous visitor__: identified without a reset, so the anonymous session merges into the person.
-
-Use [`PostHogSetPersonProperties`](/PostHogSetPersonProperties) to update a person's properties on their own, and [`PostHogAlias`](/PostHogAlias) to point a second id at the person PostHog already knows.
-
-## Sign out
-
-[`PostHogReset`](/PostHogReset) 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.
-
-```yaml
-- id: reset_posthog
-  type: PostHogReset
-- id: logout
-  type: Logout
-```
-
-## Capture events
-
-[`PostHogCapture`](/PostHogCapture) captures a named product event.
-
-```yaml
-- id: submit_report
-  type: Button
-  properties:
-    title: Submit report
-  events:
-    onClick:
-      - id: submit
-        type: Request
-        params: submit_report
-      - id: capture_event
-        type: PostHogCapture
-        params:
-          event: report_submitted
-          properties:
-            report_type:
-              _state: report_type
-```
-
-Autocapture already records clicks and pageviews, so keep the set of named events small. Every event is billable, and a funnel of thirty near identical events tells you less than one of five.
-
-## Groups
-
-[`PostHogGroup`](/PostHogGroup) associates the current person with a group, so events can be analysed per organization, team or account. The association sticks until `PostHogReset` is called, so run it after `PostHogIdentify`.
-
-```yaml
-- id: set_group
-  type: PostHogGroup
-  params:
-    type: organization
-    key:
-      _user: organizationId
-```
-
-## Feature flags
-
-[`PostHogFeatureFlag`](/PostHogFeatureFlag) reads a feature flag and returns its value, so it can be used further down the action chain with the [`_actions`](/_actions) operator. The value is whatever PostHog resolved for this person when flags were last loaded; the action does not wait for a network call. When the person or their groups just changed, reload the flags first with [`PostHogReloadFeatureFlags`](/PostHogReloadFeatureFlags), which resolves once the new flags have arrived.
-
-```yaml
-events:
-  onMount:
-    - id: read_flag
-      type: PostHogFeatureFlag
-      params:
-        key: new-checkout
-        default: control
-    - id: store_flag
-      type: SetState
-      params:
-        checkout_variant:
-          _actions: read_flag.response
-```
-
-After a change that affects flag targeting, reload before reading:
-
-```yaml
-- id: switch_organization
-  type: Button
-  events:
-    onClick:
-      - id: set_group
-        type: PostHogGroup
-        params:
-          type: organization
-          key:
-            _state: organization_id
-      - id: reload_flags
-        type: PostHogReloadFeatureFlags
-      - id: store_flags
-        type: SetState
-        params:
-          feature_flags:
-            _actions: reload_flags.response.variants
-```
-
-## Consent
-
-When consent is required before any data is sent, initialise PostHog with capturing switched off, and turn it on with [`PostHogOptIn`](/PostHogOptIn) when the user accepts, or keep it off with [`PostHogOptOut`](/PostHogOptOut):
-
-```yaml
-# shared/posthog_init.yaml
-- id: init_posthog
-  type: PostHogInit
-  params:
-    apiKey:
-      _build.env: POSTHOG_API_KEY
-    options:
-      capture_pageview: history_change
-      opt_out_capturing_by_default: true
-```
-
-```yaml
-# the consent banner
-- id: accept_analytics
-  type: Button
-  properties:
-    title: Accept
-  events:
-    onClick:
-      - id: opt_in
-        type: PostHogOptIn
-```
-
-The choice is remembered in the persistence store configured on `PostHogInit`.
-
-## Actions
-
-| Action | Params | Response |
-| --- | --- | --- |
-| [`PostHogInit`](/PostHogInit) | `apiKey`, `apiHost`, `options`, `debug`, `enabled` | `null` |
-| [`PostHogCapture`](/PostHogCapture) | `event`, `properties`, `groups` | `null` |
-| [`PostHogPageview`](/PostHogPageview) | `properties` | `null` |
-| [`PostHogCapturePageLeave`](/PostHogCapturePageLeave) | `properties` | `null` |
-| [`PostHogIdentify`](/PostHogIdentify) | `id`, `properties`, `propertiesOnce` | `null` |
-| [`PostHogSetPersonProperties`](/PostHogSetPersonProperties) | `set`, `setOnce` | `null` |
-| [`PostHogAlias`](/PostHogAlias) | `alias` | `null` |
-| [`PostHogGroup`](/PostHogGroup) | `type`, `key`, `properties` | `null` |
-| [`PostHogReset`](/PostHogReset) | `resetDeviceId` | `null` |
-| [`PostHogOptIn`](/PostHogOptIn) | none | `null` |
-| [`PostHogOptOut`](/PostHogOptOut) | none | `null` |
-| [`PostHogFeatureFlag`](/PostHogFeatureFlag) | `key`, `default`, `enabled`, `payload` | the flag value, or `default` |
-| [`PostHogReloadFeatureFlags`](/PostHogReloadFeatureFlags) | `timeout` | `{ flags, variants }` |

package/content/provider-reference/auth-js-providers.md

@@ -1,107 +0,0 @@
-# Auth.js Providers
-
-All Auth.js preconfigured OAuth providers can be used in a Lowdefy app. The provider properties are mapped through directly, so the Auth.js documentation can be used as reference. They usually only need a few configuration properties to be used. Since these properties include secrets, the [`_secret`](/_secret) operator should be used to configure these properties.
-
-For most OAuth providers, a callback URL must be configured with the provider for security reasons. This URL is the URL to which the user will be redirected to complete the login flow. This URL should be set to `<app-domain>/api/auth/callback/<providerId>` where the `providerId` is the Lowdefy providerId.
-
-> This is not the same as the callback URL specified in the Login action, which is where the user is redirected by the Lowdefy app once login is complete.
-
-The providers that can be used are:
-
-- [FortyTwoProvider](https://authjs.dev/reference/core/providers/42-school)
-- [AppleProvider](https://authjs.dev/reference/core/providers/apple)
-- [AtlassianProvider](https://authjs.dev/reference/core/providers/atlassian)
-- [Auth0Provider](https://authjs.dev/reference/core/providers/auth0)
-- [AuthentikProvider](https://authjs.dev/reference/core/providers/authentik)
-- [AzureADB2CProvider](https://authjs.dev/reference/core/providers/azure-ad-b2c)
-- [AzureADProvider](https://authjs.dev/reference/core/providers/azure-ad)
-- [BattleNetProvider](https://authjs.dev/reference/core/providers/battlenet)
-- [BoxProvider](https://authjs.dev/reference/core/providers/box)
-- [BoxyHQSAMLProvider](https://authjs.dev/reference/core/providers/boxyhq-saml)
-- [BungieProvider](https://authjs.dev/reference/core/providers/bungie)
-- [CognitoProvider](https://authjs.dev/reference/core/providers/cognito)
-- [CoinbaseProvider](https://authjs.dev/reference/core/providers/coinbase)
-- [DiscordProvider](https://authjs.dev/reference/core/providers/discord)
-- [DropboxProvider](https://authjs.dev/reference/core/providers/dropbox)
-- [EVEOnlineProvider](https://authjs.dev/reference/core/providers/eveonline)
-- [FacebookProvider](https://authjs.dev/reference/core/providers/facebook)
-- [FaceItProvider](https://authjs.dev/reference/core/providers/faceit)
-- [FourSquareProvider](https://authjs.dev/reference/core/providers/foursquare)
-- [FreshbooksProvider](https://authjs.dev/reference/core/providers/freshbooks)
-- [FusionAuthProvider](https://authjs.dev/reference/core/providers/fusionauth)
-- [GitHubProvider](https://authjs.dev/reference/core/providers/github)
-- [GitlabProvider](https://authjs.dev/reference/core/providers/gitlab)
-- [GoogleProvider](https://authjs.dev/reference/core/providers/google)
-- [HubspotProvider](https://authjs.dev/reference/core/providers/hubspot)
-- [InstagramProvider](https://authjs.dev/reference/core/providers/instagram)
-- [KakaoProvider](https://authjs.dev/reference/core/providers/kakao)
-- [KeycloakProvider](https://authjs.dev/reference/core/providers/keycloak)
-- [LineProvider](https://authjs.dev/reference/core/providers/line)
-- [LinkedInProvider](https://authjs.dev/reference/core/providers/linkedin)
-- [MailchimpProvider](https://authjs.dev/reference/core/providers/mailchimp)
-- [MailRuProvider](https://authjs.dev/reference/core/providers/mailru)
-- [MediumProvider](https://authjs.dev/reference/core/providers/medium)
-- [NaverProvider](https://authjs.dev/reference/core/providers/naver)
-- [NetlifyProvider](https://authjs.dev/reference/core/providers/netlify)
-- [OktaProvider](https://authjs.dev/reference/core/providers/okta)
-- [OneLoginProvider](https://authjs.dev/reference/core/providers/onelogin)
-- [OssoProvider](https://authjs.dev/reference/core/providers/osso)
-- [OsuProvider](https://authjs.dev/reference/core/providers/osu)
-- [PassageProvider](https://authjs.dev/reference/core/providers/passage)
-- [PatreonProvider](https://authjs.dev/reference/core/providers/patreon)
-- [PinterestProvider](https://authjs.dev/reference/core/providers/pinterest)
-- [PipedriveProvider](https://authjs.dev/reference/core/providers/pipedrive)
-- [RedditProvider](https://authjs.dev/reference/core/providers/reddit)
-- [SalesforceProvider](https://authjs.dev/reference/core/providers/salesforce)
-- [SlackProvider](https://authjs.dev/reference/core/providers/slack)
-- [SpotifyProvider](https://authjs.dev/reference/core/providers/spotify)
-- [StravaProvider](https://authjs.dev/reference/core/providers/strava)
-- [TodoistProvider](https://authjs.dev/reference/core/providers/todoist)
-- [TraktProvider](https://authjs.dev/reference/core/providers/trakt)
-- [TwitchProvider](https://authjs.dev/reference/core/providers/twitch)
-- [TwitterProvider](https://authjs.dev/reference/core/providers/twitter)
-- [UnitedEffects](https://authjs.dev/reference/core/providers/united-effects)
-- [VkProvider](https://authjs.dev/reference/core/providers/vk)
-- [WikimediaProvider](https://authjs.dev/reference/core/providers/wikimedia)
-- [WordpressProvider](https://authjs.dev/reference/core/providers/wordpress)
-- [WorkOSProvider](https://authjs.dev/reference/core/providers/workos)
-- [YandexProvider](https://authjs.dev/reference/core/providers/yandex)
-- [ZitadelProvider](https://authjs.dev/reference/core/providers/zitadel)
-- [ZohoProvider](https://authjs.dev/reference/core/providers/zoho)
-- [ZoomProvider](https://authjs.dev/reference/core/providers/zoom)
-
-#### Examples
-
-###### Auth0 configuration:
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  providers:
-    - id: auth0
-      type: Auth0Provider
-      properties:
-        clientId:
-          _secret: AUTH0_CLIENT_ID
-        clientSecret:
-          _secret: AUTH0_CLIENT_SECRET
-        issuer:
-          _secret: AUTH0_ISSUER
-```
-
-In Auth0, the callback URL should be configured to `https://example.com/api/auth/callback/auth0` for production and `http://localhost:3000/api/auth/callback/auth0` for development.
-
-###### GitHub configuration:
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  providers:
-    - id: github
-      type: GitHubProvider
-      properties:
-        clientId:
-          _secret: GITHUB_CLIENT_ID
-        clientSecret:
-          _secret: GITHUB_CLIENT_SECRET
-```

package/content/provider-reference/openidconnectprovider.md

@@ -1,44 +0,0 @@
-# OpenIDConnectProvider
-
-The OpenIDConnectProvider can be used to authenticate with a OpenID Connect compliant identity provider that is not already included as a default Auth.js provider, without the need to develop a custom provider plugin.
-
-#### Properties
-
-###### object
-  - `wellKnown: string`
-  - `authorization: string | object`: The default is `{ params: { scope: 'openid email profile' } }`.
-  - `token: string | object`
-  - `userinfo: string | object`
-  - `version: string`
-  - `checks: string | string[]`: The default is `['pkce', 'state']`
-  - `clientId: string`
-  - `clientSecret: string`
-  - `idToken: boolean`: The default is `true`.
-  - `region: string`
-  - `issuer: string`
-  - `allowDangerousEmailAccountLinking: boolean`
-  - `style: object`
-
-###### See the [Auth.js OAuth provider guide](https://authjs.dev/guides/configuring-oauth-providers) for more details on provider properties.
-
-#### Examples
-
-###### Simple configuration.
-
-Usually only the `wellKnown`, `clientId` and `clientSecret` properties need to be configured:
-
-```yaml
-lowdefy: 6.0.0
-providers:
-  - id: my_provider
-    type: OpenIDConnectProvider
-    properties:
-      wellKnown:
-        _secret: OPENID_CONNECT_WELLKNOWN
-      clientId:
-        _secret: OPENID_CONNECT_CLIENT_ID
-      clientSecret:
-        _secret: OPENID_CONNECT_CLIENT_SECRET
-```
-
-where `LOWDEFY_SECRET_OPENID_CONNECT_WELLKNOWN` usually has the format `https://my-provider.com/.well-known/openid-configuration`