@wtfalch/foundry 0.66.0 → 0.67.0

package/dist/catalogue/copy-en.js

@@ -77,6 +77,11 @@ const INTEGRATION_COPY = {
         meters: { tokens: 'AI use' },
         outputs: { address: 'The address the app calls for AI tasks.' },
     },
+    analytics: {
+        name: 'Count visitors',
+        summary: 'We count how many people visit the app and which pages they open, for each release.',
+        ours: 'Run by us',
+    },
     organisations: {
         name: 'Sign-in for organisations',
         summary: 'Companies sign their own people in to the app.',

package/dist/catalogue/integrations.js

@@ -76,6 +76,11 @@ const EXTRA = {
         price: { class: 'usage', meters: [meter('audit', 'entries', 'entries')] },
         advanced: [],
     },
+    analytics: {
+        providers: [ours('analytics')],
+        price: { class: 'free', meters: [] },
+        advanced: [],
+    },
     organisations: {
         providers: [ours('organisations')],
         price: { class: 'free', meters: [] },

package/dist/index.d.ts

@@ -63,7 +63,7 @@ export type { FilesHostInput, JobsHostDeps, JobsHostInput, OwnAuthInstance, Plan
 export { OWN_AUTH_APPLIED_GIT_REF_SCOPE_KEY, OWN_AUTH_APPLIED_HOSTNAME_SCOPE_KEY, OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY, OWN_JOBS_BLOCKED_KEY, OWN_MAIL_BLOCKED_KEY, planOwnAuth, planOwnFiles, planOwnFilesR2, planOwnJobs, planOwnMail, provisionFilesHost, provisionJobsHost, provisionMailServer, } from './plan/index.js';
 export type { PlanOwnSfuOptions, SfuAppDeps, SfuAppInput } from './plan/index.js';
 export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu, provisionSfuApp, sfuConfig, sfuCompose, } from './plan/index.js';
-export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, KeysRegistrarPort, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, LoginHostBinding, LoginHostBindingsPort, LoginHostDiscoveryPort, } from './plan/index.js';
+export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, KeysRegistrarPort, AnalyticsPort, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, LoginHostBinding, LoginHostBindingsPort, LoginHostDiscoveryPort, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export type { StageProbePort, ReleasePreviewMembers } from './plan/stage-guards.js';
 export type { StageCopyHostConfig } from './plan/stage-copy-host.js';
@@ -75,6 +75,7 @@ export type { OwnHostnames } from './plan/index.js';
 export type { EnsureSignInOrgOptions } from './plan/index.js';
 export { ZITADEL_ORG_DOMAIN_SCOPE_KEY, ensureSignInOrg, registerSignInDomain, signInOrgDomain, } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
+export { httpAnalytics } from './plan/index.js';
 export { httpKeysRegistrar, keysRegistrarFromConfig, KEYS_PLATFORM_TOKEN_ENV, KEYS_SERVICE_URL_ENV, } from './plan/index.js';
 export type { HealthTarget, HealthTargetDepth, HealthTargetExpect } from './plan/index.js';
 export { healthTargets, platformHealthTargets } from './plan/index.js';

package/dist/index.js

@@ -41,6 +41,7 @@ export { NO_DOMAIN_ZONE, entryMachinePaths, ownHostnames, privatePageGateKey, wo
 export { hostedLabelRefusal } from './hosted-label.js';
 export { ZITADEL_ORG_DOMAIN_SCOPE_KEY, ensureSignInOrg, registerSignInDomain, signInOrgDomain, } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
+export { httpAnalytics } from './plan/index.js';
 export { httpKeysRegistrar, keysRegistrarFromConfig, KEYS_PLATFORM_TOKEN_ENV, KEYS_SERVICE_URL_ENV, } from './plan/index.js';
 export { healthTargets, platformHealthTargets } from './plan/index.js';
 export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeLoginHostResolver, storeScopeResolver, storeRecordedIds, } from './plan/index.js';

package/dist/modules/analytics.d.ts

@@ -0,0 +1,8 @@
+import type { AppModule } from './types.js';
+/**
+ * `uses.analytics` on a Worker app: the app counts its visitors and page views. Boule installs a site key of the
+ * company's own analytics backend on each copy of the app (`ANALYTICS_URL`, `ANALYTICS_SITE_KEY`, and the
+ * `CF_VERSION_METADATA` binding the app reads its release from); foundry only sets up the backend. One on/off
+ * module, no fields. A server app declares `uses.analytics` itself and gets its key from foundry.
+ */
+export declare const analytics: AppModule;

package/dist/modules/analytics.js

@@ -0,0 +1,28 @@
+import { setUse } from './entry-parts.js';
+/**
+ * `uses.analytics` on a Worker app: the app counts its visitors and page views. Boule installs a site key of the
+ * company's own analytics backend on each copy of the app (`ANALYTICS_URL`, `ANALYTICS_SITE_KEY`, and the
+ * `CF_VERSION_METADATA` binding the app reads its release from); foundry only sets up the backend. One on/off
+ * module, no fields. A server app declares `uses.analytics` itself and gets its key from foundry.
+ */
+export const analytics = {
+    view: {
+        id: 'analytics',
+        name: 'Count visitors',
+        line: 'We count how many people visit the app and which pages they open, for each release.',
+        category: 'Data',
+        icon: 'chart',
+        runtimes: ['worker'],
+        requires: [],
+        availability: 'ready',
+        fields: [],
+        adds: [
+            {
+                name: 'Visitor numbers',
+                hint: 'Visitors and page views for every release, on the release page. Kept in your own company only.',
+            },
+        ],
+    },
+    toEntry: (entry, values) => setUse(entry, 'analytics', values === null ? undefined : true),
+    fromEntry: (entry) => (entry.uses?.analytics === true ? {} : null),
+};

package/dist/modules/index.js

@@ -1,5 +1,6 @@
 import { SECRET_LIKE_NAME, WORKER_APP_ENV_NAME, WORKER_APP_RESERVED_NAMES, } from '../entry-rules.js';
 import { ai } from './ai.js';
+import { analytics } from './analytics.js';
 import { assistants } from './assistants.js';
 import { audit } from './audit.js';
 import { customerGrants } from './customer-grants.js';
@@ -28,6 +29,7 @@ export const MODULES = [
     files,
     email,
     jobs,
+    analytics,
     ai,
     organisations,
     audit,

package/dist/org.d.ts

@@ -301,7 +301,7 @@ export type AccessRule = {
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export declare const APP_ENTRY_KEY = "app";
 /** Why a validator refused. `code` is stable and never reworded; `message` is for people. */
-export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'entry_image_invalid' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
+export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'entry_image_invalid' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'analytics_not_true' | 'analytics_needs_hosting' | 'analytics_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
 /**
  * One refusal: a stable `code`, the dotted `path` into {@link DeclaredOrg} it is about
  * (`hosting.entries.terminal.uses.auth.registration`) and the sentence for people.
@@ -732,9 +732,17 @@ export interface HostingEntryUses {
     repo?: {
         access: 'read' | 'write';
     };
+    /**
+     * The app counts its visitors in the company's own analytics backend. A server entry gets its own site key
+     * (`ANALYTICS_URL`, `ANALYTICS_SITE_KEY`; `plan/entry-analytics-key.ts`), and its stage another. A Worker
+     * app gets its keys from Boule, which installs them per copy, so foundry only plans the backend for it.
+     */
+    analytics?: true;
 }
 /** The env names `uses.edge` writes; `env` may not name them (#317). */
 export declare const EDGE_ENTRY_ENV_NAMES: readonly ["EDGE_URL", "EDGE_API_KEY"];
+/** The env names `uses.analytics` writes on a server entry; `env` may not name them. */
+export declare const ANALYTICS_ENTRY_ENV_NAMES: readonly ["ANALYTICS_URL", "ANALYTICS_SITE_KEY"];
 /** The env names `uses.mail` writes; `env` may not name them. */
 export declare const MAIL_ENTRY_ENV_NAMES: readonly ["LETTERMINT_API_TOKEN", "MAIL_FROM"];
 /** The env names `uses.jobs` writes; `env` may not name them. */

package/dist/org.js

@@ -60,6 +60,8 @@ export const FILES_ENTRY_ENV_NAMES = [
 export const filesCollectionEnvName = (name) => `FILES_COLLECTION_${name}_ID`;
 /** The env names `uses.edge` writes; `env` may not name them (#317). */
 export const EDGE_ENTRY_ENV_NAMES = ['EDGE_URL', 'EDGE_API_KEY'];
+/** The env names `uses.analytics` writes on a server entry; `env` may not name them. */
+export const ANALYTICS_ENTRY_ENV_NAMES = ['ANALYTICS_URL', 'ANALYTICS_SITE_KEY'];
 /** The env names `uses.mail` writes; `env` may not name them. */
 export const MAIL_ENTRY_ENV_NAMES = ['LETTERMINT_API_TOKEN', 'MAIL_FROM'];
 /** The env names `uses.jobs` writes; `env` may not name them. */
@@ -1275,11 +1277,12 @@ function validateEntryCustomerGrants(entry) {
     }
     return null;
 }
-/** `uses.mail` and `uses.jobs`: `true`, `hosting.enabled`, and no `env` entry that names a value they write. */
+/** `uses.mail`, `uses.jobs` and `uses.analytics`: `true`, `hosting.enabled`, and no `env` entry that names a value they write. */
 function validateEntryMailJobs(entry, hosting) {
     for (const [use, written, code] of [
         ['mail', MAIL_ENTRY_ENV_NAMES, 'mail'],
         ['jobs', JOBS_ENTRY_ENV_NAMES, 'jobs'],
+        ['analytics', ANALYTICS_ENTRY_ENV_NAMES, 'analytics'],
     ]) {
         const value = entry.uses?.[use];
         if (value === undefined)

package/dist/plan/analytics-boule.d.ts

@@ -0,0 +1,17 @@
+import { type DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * C2: while the company's Boule runs apps (`org.boule.apps`) and its analytics backend is applied, Boule's env
+ * holds `ANALYTICS_URL` and `ANALYTICS_OPERATOR_KEY`. Boule mints a site key for each app copy with the
+ * operator key and reads each release's visitors and page views with it. The key is read from the backend's own
+ * env and written to Boule's env; it is never held, recorded or planned. Without the backend Boule installs
+ * apps without analytics.
+ *
+ * One `coolify:analytics-boule` step keyed by the org id. `analytics_boule_applied` holds
+ * `<address>|<backend app id>` and is recorded last, so a new backend app (a new key) writes again. Turning
+ * apps off takes both names out of Boule's env.
+ */
+export declare const ANALYTICS_BOULE_APPLIED_SCOPE_KEY = "analytics_boule_applied";
+export declare const ANALYTICS_BOULE_ENV_NAMES: readonly ["ANALYTICS_URL", "ANALYTICS_OPERATOR_KEY"];
+export declare const analyticsBouleMarker: (org: DeclaredOrg, backendAppId: string) => string;
+export declare function planAnalyticsBoule(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[]): DraftStep[];

package/dist/plan/analytics-boule.js

@@ -0,0 +1,43 @@
+import { appsOn } from '../org.js';
+import { ANALYTICS_DEPLOYED_SCOPE_KEY, analyticsUrlFor } from './analytics.js';
+/**
+ * C2: while the company's Boule runs apps (`org.boule.apps`) and its analytics backend is applied, Boule's env
+ * holds `ANALYTICS_URL` and `ANALYTICS_OPERATOR_KEY`. Boule mints a site key for each app copy with the
+ * operator key and reads each release's visitors and page views with it. The key is read from the backend's own
+ * env and written to Boule's env; it is never held, recorded or planned. Without the backend Boule installs
+ * apps without analytics.
+ *
+ * One `coolify:analytics-boule` step keyed by the org id. `analytics_boule_applied` holds
+ * `<address>|<backend app id>` and is recorded last, so a new backend app (a new key) writes again. Turning
+ * apps off takes both names out of Boule's env.
+ */
+export const ANALYTICS_BOULE_APPLIED_SCOPE_KEY = 'analytics_boule_applied';
+export const ANALYTICS_BOULE_ENV_NAMES = ['ANALYTICS_URL', 'ANALYTICS_OPERATOR_KEY'];
+export const analyticsBouleMarker = (org, backendAppId) => `${analyticsUrlFor(org)}|${backendAppId}`;
+export function planAnalyticsBoule(org, recordedIds, plannedSteps) {
+    const draft = (mode, description) => ({
+        action: { system: 'coolify', kind: 'analytics-boule', key: org.id, desired: { mode } },
+        step: { description, destroys: mode === 'retire', migrates: false },
+    });
+    const planned = (kind) => plannedSteps.some((p) => p.action.system === 'coolify' && p.action.kind === kind && p.action.key === org.id);
+    const bouleKnown = Boolean(recordedIds[`coolify:boule:${org.id}`]) || planned('boule');
+    const marker = recordedIds[ANALYTICS_BOULE_APPLIED_SCOPE_KEY];
+    if (!appsOn(org)) {
+        if (!marker || !recordedIds[`coolify:boule:${org.id}`])
+            return [];
+        return [
+            draft('retire', `take the analytics address and key out of ${org.slug}'s Boule env (the company's Boule runs no apps)`),
+        ];
+    }
+    if (!bouleKnown)
+        return [];
+    const backendApp = recordedIds[`coolify:analytics:${org.id}`];
+    const applied = Boolean(backendApp) && Boolean(recordedIds[ANALYTICS_DEPLOYED_SCOPE_KEY]);
+    if (!applied && !planned('analytics'))
+        return [];
+    if (applied && marker === analyticsBouleMarker(org, backendApp))
+        return [];
+    return [
+        draft('write', `write ANALYTICS_URL and ANALYTICS_OPERATOR_KEY to ${org.slug}'s Boule env, restart Boule`),
+    ];
+}

package/dist/plan/analytics.d.ts

@@ -0,0 +1,58 @@
+import { type DeclaredOrg } from '../org.js';
+/**
+ * A company's own analytics backend (https://github.com/wtfalch/analytics): one Coolify app and one database
+ * per company, built from that repo's root Dockerfile. It is planned only while something uses it: a hosting
+ * entry declares `uses.analytics`, or the company's Boule runs apps (`org.boule.apps`).
+ *
+ * What the host (`apps/host`) reads to start: `DATABASE_URL` and `DATABASE_URL_OWNER` (written by
+ * `pushDatabaseUrl`), `ANALYTICS_OPERATOR_KEY` (generated once here) and `AUTH_ORGANIZATION_ID` (the company's
+ * sign-in organisation; the tenant id of every key and row derives from it, and without it minting answers 503
+ * and the release series answers `not_configured`). It reads no other `AUTH_*` name yet, so no sign-in client is
+ * made for it. When its screens need `AUTH_ISSUER` and `AUTH_CLIENT_ID`, add the client then.
+ */
+/** True while some entry declares `uses.analytics`, or Boule runs apps: the backend is wanted. */
+export declare const analyticsWanted: (org: Pick<DeclaredOrg, "boule" | "hosting">) => boolean;
+/** `analytics.<domain>`, or `<slug>-analytics.oikos.host` for a company without a domain. */
+export declare function analyticsHostnameFor(org: Pick<DeclaredOrg, 'domain' | 'slug'>): string;
+/** The public address apps and Boule send to, `ANALYTICS_URL`. */
+export declare const analyticsUrlFor: (org: Pick<DeclaredOrg, "domain" | "slug">) => string;
+/** The backend's database uuid, recorded beside the app's own id. */
+export declare const ANALYTICS_DATABASE_SCOPE_KEY = "coolify_analytics_database";
+/** Recorded once the app was deployed, as `coolify_boule_deployed` is for Boule. */
+export declare const ANALYTICS_DEPLOYED_SCOPE_KEY = "coolify_analytics_deployed";
+/** The env name the backend reads its operator key from; also Boule's name for it (C2). */
+export declare const ANALYTICS_OPERATOR_KEY_ENV = "ANALYTICS_OPERATOR_KEY";
+/** The env names `desiredAnalyticsEnv` writes, so the live reader knows which to read back. */
+export declare const ANALYTICS_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ORGANIZATION_ID"];
+export declare function desiredAnalyticsEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): {
+    env: Record<string, string>;
+    missing: string[];
+};
+export declare function analyticsEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];
+/** The backend's operator API. Every call carries the company's own base URL and operator key. */
+export interface AnalyticsPort {
+    /** Mints a site key; the secret is shown once. The same `name` again replaces the older key. */
+    mintSiteKey(input: {
+        baseUrl: string;
+        operatorKey: string;
+        name: string;
+        environment: 'production' | 'stage';
+    }): Promise<{
+        id: string;
+        secret: string;
+    }>;
+    /** Revokes a key. An unknown id is not an error. */
+    revokeSiteKey(input: {
+        baseUrl: string;
+        operatorKey: string;
+        keyId: string;
+    }): Promise<void>;
+}
+/**
+ * The real {@link AnalyticsPort}: `POST <baseUrl>/v1/site-keys` with `{ name, environment }` answers 201
+ * `{ id, secret }`; `DELETE <baseUrl>/v1/site-keys/<id>` answers 204. Errors carry the status only, never a
+ * body, the key or the secret.
+ */
+export declare function httpAnalytics(options?: {
+    fetch?: typeof fetch;
+}): AnalyticsPort;

package/dist/plan/analytics.js

@@ -0,0 +1,89 @@
+import { appsOn } from '../org.js';
+import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
+/**
+ * A company's own analytics backend (https://github.com/wtfalch/analytics): one Coolify app and one database
+ * per company, built from that repo's root Dockerfile. It is planned only while something uses it: a hosting
+ * entry declares `uses.analytics`, or the company's Boule runs apps (`org.boule.apps`).
+ *
+ * What the host (`apps/host`) reads to start: `DATABASE_URL` and `DATABASE_URL_OWNER` (written by
+ * `pushDatabaseUrl`), `ANALYTICS_OPERATOR_KEY` (generated once here) and `AUTH_ORGANIZATION_ID` (the company's
+ * sign-in organisation; the tenant id of every key and row derives from it, and without it minting answers 503
+ * and the release series answers `not_configured`). It reads no other `AUTH_*` name yet, so no sign-in client is
+ * made for it. When its screens need `AUTH_ISSUER` and `AUTH_CLIENT_ID`, add the client then.
+ */
+/** True while some entry declares `uses.analytics`, or Boule runs apps: the backend is wanted. */
+export const analyticsWanted = (org) => appsOn(org) || org.hosting.entries.some((e) => e.uses?.analytics === true);
+/** `analytics.<domain>`, or `<slug>-analytics.oikos.host` for a company without a domain. */
+export function analyticsHostnameFor(org) {
+    return org.domain ? `analytics.${org.domain}` : `${org.slug}-analytics.oikos.host`;
+}
+/** The public address apps and Boule send to, `ANALYTICS_URL`. */
+export const analyticsUrlFor = (org) => `https://${analyticsHostnameFor(org)}`;
+/** The backend's database uuid, recorded beside the app's own id. */
+export const ANALYTICS_DATABASE_SCOPE_KEY = 'coolify_analytics_database';
+/** Recorded once the app was deployed, as `coolify_boule_deployed` is for Boule. */
+export const ANALYTICS_DEPLOYED_SCOPE_KEY = 'coolify_analytics_deployed';
+/** The env name the backend reads its operator key from; also Boule's name for it (C2). */
+export const ANALYTICS_OPERATOR_KEY_ENV = 'ANALYTICS_OPERATOR_KEY';
+/** The env names `desiredAnalyticsEnv` writes, so the live reader knows which to read back. */
+export const ANALYTICS_MANAGED_ENV_KEYS = ['APP_URL', 'AUTH_ORGANIZATION_ID'];
+export function desiredAnalyticsEnv(org, recorded) {
+    const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const env = { APP_URL: analyticsUrlFor(org) };
+    if (zitadelOrgId)
+        env.AUTH_ORGANIZATION_ID = zitadelOrgId;
+    return { env, missing: zitadelOrgId ? [] : ['zitadelOrgId'] };
+}
+export function analyticsEnvDrift(desired, live) {
+    return Object.entries(desired)
+        .filter(([key, value]) => live[key] !== value)
+        .map(([key]) => key);
+}
+const CALL_TIMEOUT_MS = 20_000;
+/**
+ * The real {@link AnalyticsPort}: `POST <baseUrl>/v1/site-keys` with `{ name, environment }` answers 201
+ * `{ id, secret }`; `DELETE <baseUrl>/v1/site-keys/<id>` answers 204. Errors carry the status only, never a
+ * body, the key or the secret.
+ */
+export function httpAnalytics(options = {}) {
+    const fetchImpl = options.fetch ?? fetch;
+    const call = async (url, init, what) => {
+        try {
+            return await fetchImpl(url, {
+                ...init,
+                redirect: 'error',
+                signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+            });
+        }
+        catch {
+            throw new Error(`the analytics backend did not answer when asked to ${what}`);
+        }
+    };
+    return {
+        async mintSiteKey({ baseUrl, operatorKey, name, environment }) {
+            const response = await call(`${baseUrl}/v1/site-keys`, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${operatorKey}`, 'content-type': 'application/json' },
+                body: JSON.stringify({ name, environment }),
+            }, 'mint a site key');
+            if (response.status !== 201) {
+                throw Object.assign(new Error(`the analytics backend refused to mint a site key (status ${response.status})`), { status: response.status });
+            }
+            const body = await response.json().catch(() => undefined);
+            const fields = typeof body === 'object' && body !== null ? body : {};
+            if (typeof fields.id !== 'string' ||
+                !fields.id ||
+                typeof fields.secret !== 'string' ||
+                !fields.secret) {
+                throw new Error('the analytics backend answered 201 but sent no key id and secret');
+            }
+            return { id: fields.id, secret: fields.secret };
+        },
+        async revokeSiteKey({ baseUrl, operatorKey, keyId }) {
+            const response = await call(`${baseUrl}/v1/site-keys/${encodeURIComponent(keyId)}`, { method: 'DELETE', headers: { authorization: `Bearer ${operatorKey}` } }, 'revoke a site key');
+            if (response.status !== 204) {
+                throw Object.assign(new Error(`the analytics backend refused to revoke a site key (status ${response.status})`), { status: response.status });
+            }
+        },
+    };
+}

package/dist/plan/company-backups.js

@@ -1,4 +1,5 @@
 import { ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, orgServiceDatabase, } from '../org.js';
+import { ANALYTICS_DATABASE_SCOPE_KEY } from './analytics.js';
 import { BOULE_DATABASE_SCOPE_KEY } from './boule.js';
 import { CHAT_REKEY_MAS_DB_SCOPE_KEY, CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY } from './executor.js';
 import { MAIL_DATABASE_NAME, MAIL_DATABASE_SCOPE_KEY } from './mail-store.js';
@@ -29,6 +30,7 @@ export function companyDatabaseKeys(org) {
         chat_synapse: 'coolify_chat_synapse_database',
         chat_mas: 'coolify_chat_mas_database',
         boule: BOULE_DATABASE_SCOPE_KEY,
+        analytics: ANALYTICS_DATABASE_SCOPE_KEY,
         chat_rekey_synapse: CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY,
         chat_rekey_mas: CHAT_REKEY_MAS_DB_SCOPE_KEY,
         postgres: ORG_POSTGRES_SERVER_SCOPE_KEY,

package/dist/plan/diff.d.ts

@@ -83,6 +83,8 @@ export interface PlanOrgOptions {
     workerAppKeysUrl?: string;
     /** F7: the keys service's registrar address, when the executor has a `KeysRegistrarPort`. */
     keysRegistrarUrl?: string;
+    /** The executor was built with an `analytics` port; without it each `uses.analytics` key is blocked. */
+    analyticsPort?: boolean;
     /** C2: true when the executor was built with a `WorkerAppDatabasePort`; a `workerApp.database` is blocked without it. */
     workerAppDatabase?: boolean;
     /** True when that port has `deletableTables`; a `workerApp.database.noDelete` is blocked without it. */

package/dist/plan/diff.js

@@ -3,6 +3,8 @@ import { NATIVE_BUILD_KEY_ENV } from '../native-build.js';
 import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, heldEnvRef, kosmosOn, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownerNameProblem, ownsServices, } from '../org.js';
 import { entryHasDatabase } from '../worker-app-config.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, entryClientIdScopeKey, withRecordedMessagingProject, } from './agora.js';
+import { planAnalyticsBoule } from './analytics-boule.js';
+import { analyticsEnvDrift, analyticsWanted, desiredAnalyticsEnv } from './analytics.js';
 import { planAppsDbRoute } from './apps-db-route.js';
 import { planAppsZones } from './apps-zones.js';
 import { bgKey, planBlueGreen, } from './blue-green.js';
@@ -16,6 +18,7 @@ import { DESKTOP_AUTH_HOME, planDesktopAuth } from './desktop-auth.js';
 import { planDesktopCallbacks } from './desktop-callback.js';
 import { onPlatformNetwork } from './destinations.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
+import { planEntryAnalyticsKeys } from './entry-analytics-key.js';
 import { planEntryAudit } from './entry-audit.js';
 import { CUSTOMER_GRANTS_ENV, CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY, customerGrantsEntries, customerGrantsShapeMatches, customerGrantsToDrop, wantedCustomerGrants, } from './entry-customer-grants.js';
 import { planEdgeReservedLabels, planEdgeSlug, planEntryEdgeKeys } from './entry-edge-key.js';
@@ -723,6 +726,14 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     const kosmos = planKosmos(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? []);
     if (kosmos.step)
         plannedSteps.push(kosmos.step);
+    // The company's analytics backend, only while something uses it (an entry's `uses.analytics`, or Boule's
+    // apps); never parked once made. Before the site keys and Boule's env, which need its operator key.
+    const analytics = planAnalyticsBackend(org, byKey, claimed, recordedIds, options.otherSlugs ?? []);
+    if (analytics.step)
+        plannedSteps.push(analytics.step);
+    plannedSteps.push(...planAnalyticsBoule(org, recordedIds, plannedSteps));
+    const entryAnalyticsKeys = planEntryAnalyticsKeys(org, recordedIds, plannedSteps, options.analyticsPort ?? false);
+    plannedSteps.push(...entryAnalyticsKeys.steps);
     // Boule's, Agora's and kosmos's blue/green: after their own steps, which make the app it copies.
     plannedSteps.push(...blueGreen.steps.filter((x) => x.phase === 'last').map(blueGreenDraft()));
     // Boule owners, after the Boule step: needs the app deployed and the seeding secret in its env.
@@ -995,6 +1006,9 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     }
     if (kosmos.blocked)
         unmanaged.push({ description: kosmos.blocked, key: 'coolify:kosmos' });
+    if (analytics.blocked)
+        unmanaged.push({ description: analytics.blocked, key: 'coolify:analytics' });
+    unmanaged.push(...entryAnalyticsKeys.blocked);
     // Same for an ai key minted but never delivered: planning a new mint would
     // orphan a second live key.
     if (aiKey.blocked)
@@ -3212,6 +3226,78 @@ function planKosmos(org, byKey, claimed, recordedIds, issuer, otherSlugs) {
         blocked: null,
     };
 }
+/**
+ * The company's analytics backend: a per-org singleton keyed by the org id under its own `analytics` kind, built
+ * from https://github.com/wtfalch/analytics's root Dockerfile (`executor.ts`'s `coolifyAnalytics`) with a
+ * database of its own. Planned only while `analyticsWanted(org)`; once live it is kept and never parked. A live
+ * app is planned again when its `APP_URL` or `AUTH_ORGANIZATION_ID` is missing or different. It needs no
+ * sign-in client and no issuer; only the company's sign-in organisation id (recorded by an earlier step).
+ */
+function planAnalyticsBackend(org, byKey, claimed, recordedIds, otherSlugs) {
+    const key = resourceKey('coolify', 'analytics', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    if (!analyticsWanted(org))
+        return { step: null, blocked: null };
+    const tooLong = [
+        [`${org.slug}-analytics`, 'the analytics host label and app name'],
+        [`${org.slug}_analytics_db_rt`, 'the analytics database role'],
+    ].filter(([name]) => name.length > 63);
+    if (tooLong.length > 0) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s analytics backend is blocked, not planned: ${tooLong.map(([n, what]) => `${what} '${n}' is over 63 characters`).join(', ')}; shorten the slug`,
+        };
+    }
+    if (otherSlugs.includes(`${org.slug}-analytics`)) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s analytics backend is blocked, not planned: another declared org has the slug '${org.slug}-analytics', which is this backend's hostname`,
+        };
+    }
+    // `coolifyAnalytics` writes nothing without the sign-in organisation, so the step waits for it here.
+    const { env, missing } = desiredAnalyticsEnv(org, recordedIds);
+    if (missing.length > 0) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s analytics backend is blocked, not planned: the company's sign-in organisation is not recorded yet`,
+        };
+    }
+    const action = {
+        system: 'coolify',
+        kind: 'analytics',
+        key: org.id,
+        desired: {},
+    };
+    if (!live) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `provision ${org.slug}'s analytics backend`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+        };
+    }
+    const drift = analyticsEnvDrift(env, (live.config.env ?? {}));
+    if (drift.length === 0)
+        return { step: null, blocked: null };
+    return {
+        step: {
+            action,
+            step: {
+                description: `update ${org.slug}'s analytics backend config (${drift.join(', ')} missing or different)`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 /**
  * C3: which credentials the org's Boule is given, and why one is not. Archon's credential goes to every
  * Boule the host can mint it for; the customers directory credential only while `customers.enabled`. Each

package/dist/plan/entry-analytics-key.d.ts

@@ -0,0 +1,35 @@
+import type { DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * `uses.analytics` on a server entry: one site key of its own at the company's analytics backend, minted
+ * through `POST /v1/site-keys` with the operator key and written as `ANALYTICS_URL` and `ANALYTICS_SITE_KEY` to
+ * the entry's env. The backend shows the secret once, so this follows rule 1 of CLAUDE.md "Platform steps":
+ *
+ * 1. the key's id is recorded as `analytics_key_undelivered.<entry>` and persisted before the env is written;
+ * 2. the env write is tried 3 times with the same secret; the id is the main id `analytics:key:<orgId>:<entry>`
+ *    and the applied marker only after it worked, and the undelivered marker is cleared then;
+ * 3. a marker left behind (every try failed) is reported blocked and never minted again.
+ *
+ * A Worker app entry is skipped: Boule installs its keys per copy. The entry's stage gets its own key through
+ * `plan/stage-services.ts` (service `analytics`, environment `stage`), so the two differ. Removing
+ * `uses.analytics` or the entry plans the retire form: revoke the key, take both env names away.
+ */
+export declare const entryAnalyticsUndeliveredScopeKey: (entryKey: string) => string;
+/** The address the entry's env was last written with; a change rewrites the address only. */
+export declare const entryAnalyticsAppliedScopeKey: (entryKey: string) => string;
+/** The id of a key that was revoked, so a stale main id is not revoked again. */
+export declare const entryAnalyticsRetiredScopeKey: (entryKey: string) => string;
+export declare const ENTRY_ANALYTICS_KEY_DELIVERY_ATTEMPTS = 3;
+/** The name the backend knows the key by; its site derives from it. */
+export declare const entryAnalyticsKeyName: (org: Pick<DeclaredOrg, "slug">, entryKey: string) => string;
+/** The stage copy's key name: the backend reads the `-stage` suffix as the stage environment. */
+export declare const stageAnalyticsKeyName: (org: Pick<DeclaredOrg, "slug">, entryKey: string) => string;
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+export declare function planEntryAnalyticsKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], analyticsPort: boolean): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+export {};