@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/release-flags.d.ts

@@ -0,0 +1,283 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Release flags (AGL-227): platform-level "is this feature launched"
+ * gating backed by Firebase Remote Config. A separate axis from plan
+ * entitlements (`plan-entitlements.ts`) — entitlements ask whether the
+ * tenant's PLAN includes a feature, release flags ask whether the feature
+ * is released to the public at all (or partially, via percentage rollout).
+ * Staff bypass release flags everywhere but see a flagged warning.
+ */
+/** Remote Config parameter keys for release-gated features. */
+import type { OrgPlan } from '../foundation';
+export type ReleaseFlagKey = 'release_crm' | 'release_outreach' | 'release_bookings' | 'release_events' | 'release_data_store' | 'release_workflows' | 'release_redirects' | 'release_commerce_v2' | 'release_member_accounts' | 'release_marketplace' | 'release_marketing' | 'release_email' | 'release_inbox' | 'release_logic' | 'release_addon_store' | 'release_native_checkout' | 'release_edit_bar' | 'release_assist' | 'release_video_uploads' | 'release_video_delivery' | 'release_ai_generative';
+export interface ReleaseFlagDefinition {
+    key: ReleaseFlagKey;
+    label: string;
+    description: string;
+    /**
+     * Fallback verdict when Remote Config is unreachable (offline, blocked,
+     * first paint before activate). MUST match the seeded value in
+     * cloud/firebase-remoteconfig.template.json so environments without a
+     * published template behave like the template intends.
+     */
+    defaultEnabled: boolean;
+    /** Host dashboard tab id (host-nav-tabs.ts) this flag hides, if any. */
+    navTabId?: string;
+}
+/**
+ * The registry: one entry per gated feature. Adding a flag = add it here,
+ * seed it in the Remote Config template, and (optionally) wrap the page in
+ * `<FeatureGate>` — the staff admin editor and nav filtering pick it up
+ * from this list.
+ */
+export declare const RELEASE_FLAGS: readonly ReleaseFlagDefinition[];
+export declare const RELEASE_FLAG_KEYS: readonly ReleaseFlagKey[];
+export declare function isReleaseFlagKey(value: string): value is ReleaseFlagKey;
+export declare function getReleaseFlagDefinition(key: ReleaseFlagKey): ReleaseFlagDefinition;
+/**
+ * The JSON payload stored in each Remote Config parameter. `enabled: true`
+ * turns the feature on for everyone; `enabled: false` with a positive
+ * `rolloutPercent` enables it for that percentage of subjects (stable
+ * per-tenant bucketing, GrowthBook-style); `plans` narrows either of those
+ * to a set of tiers (AGL-2486).
+ */
+export interface ReleaseFlagValue {
+    enabled: boolean;
+    /** 0–100; only consulted while `enabled` is false. */
+    rolloutPercent?: number;
+    /**
+     * Plan/tier targeting (AGL-2486). The tiers this flag is being rolled out
+     * to, or ABSENT for "every tier".
+     *
+     * ABSENT AND EMPTY BOTH MEAN EVERY TIER, and that is load-bearing: every
+     * flag stored before this field existed parses to `undefined` here, and an
+     * operator who unticks every box has plainly not asked for a flag that
+     * reaches nobody. Reading an empty list as "no tiers" would dark-launch
+     * nothing while the console still said the flag was on — the inverted
+     * reading of this field is the whole hazard, so it is closed in the parser
+     * rather than left to each call site.
+     */
+    plans?: OrgPlan[];
+    /** Free-form staff note ("waiting on AGL-199", owner, etc.). */
+    note?: string;
+}
+/**
+ * Every plan a flag may target, cheapest first — `SELF_SERVE_PLANS` then
+ * `enterprise`, the same ladder `planGrantingFeature` walks and the same
+ * order the plan grid renders. Derived, never re-typed: pricing v3 inserted
+ * `scale` mid-ladder and added `agency`, and a second hand-written tier list
+ * here would have missed both.
+ */
+export declare const RELEASE_FLAG_PLAN_LADDER: readonly OrgPlan[];
+/**
+ * The tiers on the ladder at or above `plan` — what the console's "Pro and
+ * above" shortcut expands to before it is STORED as an explicit list.
+ *
+ * Deliberately a UI convenience and not a stored "minimum plan" mode: a
+ * stored threshold would silently re-aim every live flag the day a tier is
+ * inserted into the middle of the ladder (pricing v3 did exactly that with
+ * `scale`). An explicit list means the audience of a published flag only
+ * ever changes because a human changed it.
+ */
+export declare function releaseFlagPlansAtOrAbove(plan: OrgPlan): OrgPlan[];
+/**
+ * Sanitises whatever is stored at `plans`, in ladder order.
+ *
+ * Returns `undefined` — not `[]` — for "no targeting declared", so the
+ * absence survives a round trip through the staff editor and cannot be
+ * written back as a list that means something else. Unknown tier names are
+ * dropped for the same reason `parseOrgReleaseFlagOverrides` drops unknown
+ * keys: a renamed or retired tier must never gate anything. A list that
+ * names ONLY unknown tiers collapses to `undefined` (every tier) rather than
+ * to an empty list, because a typo must inherit, never silently target.
+ */
+export declare function parseReleaseFlagPlans(raw: unknown): OrgPlan[] | undefined;
+/**
+ * Parses a Remote Config parameter string into a `ReleaseFlagValue`.
+ * Tolerant by design — the template is hand-editable in the Firebase
+ * console, so plain "true"/"false" strings and malformed JSON must not
+ * crash gating: anything unreadable falls back to the registry default.
+ */
+export declare function parseReleaseFlagValue(raw: string | null | undefined, fallbackEnabled: boolean): ReleaseFlagValue;
+/**
+ * The longest parameter description Remote Config will publish (AGL-3048).
+ *
+ * One description past it refuses the WHOLE publish with
+ * `DESCRIPTION_EXCEEDS_MAXIMUM_SIZE`, which the staff flags route answered as
+ * a 500. Registry descriptions are written for the staff flags page, and
+ * several run far past the limit, so what the page shows and what a
+ * parameter carries cannot always be the same text.
+ *
+ * Counted in UTF-8 BYTES. Remote Config states the limit in characters
+ * without saying how it counts them, and a UTF-8 byte count is never smaller
+ * than the code-point or UTF-16 count, so text within 256 bytes is within the
+ * limit on every reading. The cost is a few characters of headroom on text
+ * with typographic punctuation.
+ */
+export declare const REMOTE_CONFIG_DESCRIPTION_MAX_BYTES = 256;
+/** Whether Remote Config accepts `text` as a parameter description. */
+export declare function fitsRemoteConfigDescription(text: string): boolean;
+/**
+ * `text` cut to a length Remote Config accepts, at a word boundary, with an
+ * ellipsis marking the cut. Text that already fits comes back unchanged.
+ *
+ * The cut takes whole code points, so a multi-byte character is never split.
+ * It backs up to the last space when it lands inside a word (only a single
+ * word longer than the whole budget is cut hard), and punctuation left
+ * dangling before the ellipsis is dropped.
+ */
+export declare function clampRemoteConfigDescription(text: string): string;
+/**
+ * The description to publish with a release flag's Remote Config parameter
+ * (AGL-3048). Always one Remote Config accepts:
+ *
+ * 1. The registry description, when it fits, so the flags page and the
+ *    parameter say the same thing.
+ * 2. Otherwise the LIVE parameter's description, when it has one that fits.
+ *    Remote Config has already accepted exactly that text, and someone chose
+ *    it for the Firebase console. The first 250 characters of a longer
+ *    paragraph would drop whatever the paragraph says last: for
+ *    `release_assist`, the `/legal/subprocessors` precondition that its
+ *    AGL-1909 suite wants in front of whoever reads the flag there. The full
+ *    registry text stays on the staff flags page either way.
+ * 3. Otherwise, as on a first publish with nothing live to keep, the
+ *    registry description clamped at a word boundary.
+ */
+export declare function releaseFlagParameterDescription(registryDescription: string, liveDescription: string | null | undefined): string;
+/**
+ * FNV-1a 32-bit hash → 0–99 bucket. Deterministic so a subject keeps the
+ * same rollout verdict across sessions and surfaces, and seeded with the
+ * flag key so a subject doesn't land in the same bucket for every flag.
+ */
+export declare function releaseFlagBucket(flagKey: string, subjectId: string): number;
+/**
+ * The gating verdict for one subject.
+ *
+ * `subjectId` is the ORG ID, or nothing. A rollout is a cohort of
+ * workspaces, so a whole workspace has to land on one side of the
+ * percentage: every surface that asks about an org must ask with the same
+ * string, or they answer differently about the same customer.
+ *
+ * This docstring used to sanction falling back to the uid, and the server
+ * gates fell back to a hostId. Since a hostId, a uid and an orgId hash to
+ * three different buckets, a mid-rollout flag could be on in the console
+ * and off on the published site for one workspace — stable per subject, so
+ * it never flickered, it just stayed wrong (AGL-1656).
+ *
+ * An empty subject only passes fully-enabled flags. That is the deliberate
+ * cost: a request with no resolvable org never joins a partial rollout,
+ * which is the conservative answer rather than a confidently wrong one.
+ */
+export declare function isReleaseFlagOn(flagKey: ReleaseFlagKey, value: ReleaseFlagValue, subjectId: string | null | undefined, 
+/**
+ * The subject org's plan, when the caller knows it (AGL-2486). Optional so
+ * every pre-existing call site compiles and answers unchanged: a flag that
+ * declares no tier targeting never reads this.
+ */
+plan?: OrgPlan | null): boolean;
+/**
+ * Does this flag's tier targeting admit `plan`? (AGL-2486)
+ *
+ * THE SEMANTICS, because an operator who cannot predict the audience will
+ * not stage a rollout at all:
+ *
+ *  - The tier list is a FILTER, applied before and independently of the
+ *    percentage. The percentage then picks a cohort WITHIN the admitted
+ *    tiers. "Pro and above at 50%" is therefore both "half of the Pro+
+ *    workspaces" and "the global 50% cohort, restricted to Pro+" — the two
+ *    readings name the same set, and they do so because
+ *    {@link releaseFlagBucket} hashes `flagKey:orgId` and NOTHING ELSE.
+ *  - Which is also why the bucket is stable. Adding, removing or reordering
+ *    tiers cannot reshuffle the bucket, so an org already inside a 50%
+ *    rollout keeps the feature when an unrelated tier joins the list. Had
+ *    the plan been mixed into the hash — the obvious way to write this — a
+ *    tier edit would have re-drawn the cohort under every customer already
+ *    in it, and a plan change would have re-rolled the dice for one.
+ *  - The filter binds the FULLY-ENABLED path too, not just the rollout.
+ *    "On, Enterprise + Agency" is how a launch to the top of the ladder is
+ *    expressed, and it is what was actually asked for. Untargeted flags are
+ *    unaffected: no list means every tier, so `enabled` still means everyone.
+ *  - An UNKNOWN plan fails a declared list. Same conservatism as a missing
+ *    subject on a percentage rollout: a caller that cannot say which
+ *    workspace it is asking about gets the safe answer rather than a
+ *    confidently wrong one. A per-org staff override still wins over all of
+ *    it — see {@link isReleaseFlagOnForOrg} — so a targeted flag can still be
+ *    handed to one org off-ladder.
+ */
+export declare function releaseFlagTargetsPlan(value: ReleaseFlagValue, plan: OrgPlan | null | undefined): boolean;
+/**
+ * Per-org release-flag overrides (AGL-1635), stored on the org doc at
+ * `releaseFlags`. A present key is a staff DECISION about one organization
+ * and wins over both the Remote Config value and the rollout bucket; an
+ * absent key inherits.
+ *
+ * A separate field from `entitlements.features` on purpose: those ask
+ * whether the org's PLAN includes a feature, these ask whether a
+ * not-yet-released feature is switched on for this one customer. Folding
+ * them together would make "granted by the deal" and "previewing an
+ * unreleased build" indistinguishable at the point a support question is
+ * asked.
+ *
+ * Why the org doc and not a Remote Config condition: RC conditions are
+ * template-global and would need one published condition per org, with a
+ * template publish (a manual, separate deploy) for every grant.
+ */
+export type OrgReleaseFlagOverrides = Partial<Record<ReleaseFlagKey, boolean>>;
+/**
+ * Sanitises whatever is actually stored at `org.releaseFlags`.
+ *
+ * Tolerant for the same reason `parseReleaseFlagValue` is: this map is
+ * hand-editable in the Firebase console and survives registry renames, so a
+ * retired flag key or a non-boolean must be dropped rather than allowed to
+ * gate anything. Unknown keys are discarded — a stale key can never grant a
+ * flag that no longer exists, and a typo silently inherits instead of
+ * silently forcing.
+ */
+export declare function parseOrgReleaseFlagOverrides(raw: unknown): OrgReleaseFlagOverrides;
+/**
+ * The gating verdict with a per-org override applied on top of
+ * `isReleaseFlagOn`.
+ *
+ * The override is checked FIRST and short-circuits, so a forced-off flag
+ * stays off for an org even while the flag is globally enabled — the
+ * per-org kill switch is half the point, not just the per-org grant. Every
+ * release-flag gate resolves through here so the console, the tenant
+ * runtime and the API dispatchers cannot disagree about one org.
+ */
+export declare function isReleaseFlagOnForOrg(flagKey: ReleaseFlagKey, value: ReleaseFlagValue, subjectId: string | null | undefined, overrides: OrgReleaseFlagOverrides | null | undefined, 
+/**
+ * The org's plan, for tier targeting (AGL-2486). Checked only AFTER the
+ * override: a staff grant is a decision about one named customer and
+ * outranks the tier filter exactly as it already outranks the rollout
+ * bucket. That ordering is what lets a Free org preview a
+ * Business-targeted flag without widening the flag for every Free org.
+ *
+ * REQUIRED, and `null` has to be typed out. It was optional for one
+ * release and that cost a silent revenue bug: `report-usage` held the org
+ * document, dropped the argument, and every `plans`-declaring flag read
+ * OFF — so the contacts overage went uninvoiced for exactly the orgs
+ * entitled to reach the feature, with nothing thrown and nothing logged.
+ * An unknown tier still refuses, which is the correct conservatism; what
+ * cannot be allowed is a caller MANUFACTURING an unknown out of a tier it
+ * already has in hand. Spelling `null` makes that a statement rather than
+ * an omission, and makes the next call site that forgets fail to compile
+ * instead of failing to bill. `getOrgReleaseFlagTargeting` returns the
+ * plan beside the overrides from ONE document read precisely so that
+ * passing it costs nothing.
+ */
+plan: OrgPlan | null): boolean;