@mozilla/nimbus-schemas 2024.9.3 → 2024.10.1

package/index.d.ts

@@ -2,13 +2,17 @@
 /* eslint-disable */
 /**
 /* This file was automatically generated from pydantic models.
-/* Do not modify by hand - update the pydantic models and re-run the script
+/* Do not modify by hand - update the pydantic models and re-run
+ * make schemas_build
  */
 
-export type RandomizationUnit = "normandy_id" | "nimbus_id" | "user_id" | "group_id";
-export type Feature = FeatureWithExposure | FeatureWithoutExposure;
+export type DesktopApplication = "firefox-desktop" | "firefox-desktop-background-task";
 export type FeatureVariableType = "int" | "string" | "boolean" | "json";
 export type PrefBranch = "default" | "user";
+/**
+ * A unique, stable indentifier for the user used as an input to bucket hashing.
+ */
+export type RandomizationUnit = "normandy_id" | "nimbus_id" | "user_id" | "group_id";
 export type AnalysisBasis = "enrollments" | "exposures";
 export type LogSource = "jetstream" | "sizing" | "jetstream-preview";
 export type AnalysisErrors = AnalysisError[];
@@ -28,114 +32,407 @@ export type SizingMetricName = "active_hours" | "search_count" | "days_of_use" |
 export type StatisticIngestEnum = "percentage" | "binomial" | "mean" | "count";
 export type Statistics = Statistic[];
 
+/**
+ * A feature.
+ */
+export interface DesktopFeature {
+  /**
+   * The description of the feature.
+   */
+  description: string;
+  /**
+   * Whether or not this feature records exposure telemetry.
+   */
+  hasExposure: boolean;
+  /**
+   * A description of the exposure telemetry collected by this feature.
+   *
+   * Only required if hasExposure is true.
+   */
+  exposureDescription?: string;
+  /**
+   * The owner of the feature.
+   */
+  owner: string;
+  /**
+   * If true, the feature values will be cached in prefs so that they can be read before Nimbus is initialized during Firefox startup.
+   */
+  isEarlyStartup?: boolean;
+  /**
+   * The applications that can enroll in experiments for this feature.
+   *
+   * Defaults to "firefox-desktop".
+   */
+  applications?: DesktopApplication[];
+  /**
+   * The variables that this feature can set.
+   */
+  variables: {
+    [k: string]: DesktopFeatureVariable;
+  };
+  schema?: NimbusFeatureSchema;
+}
+/**
+ * A feature variable.
+ */
+export interface DesktopFeatureVariable {
+  /**
+   * A description of the feature.
+   */
+  description: string;
+  type: FeatureVariableType;
+  /**
+   * An optional list of possible string or integer values.
+   *
+   * Only allowed when type is string or int.
+   *
+   * The types in the enum must match the type of the field.
+   */
+  enum?: string[] | number[];
+  /**
+   * A pref that provides the default value for a feature when none is present.
+   */
+  fallbackPref?: string;
+  /**
+   * A pref that should be set to the value of this variable when enrolling in experiments.
+   *
+   * Using a string is deprecated and unsupported in Firefox 124+.
+   */
+  setPref?: string | SetPref;
+}
+export interface SetPref {
+  branch: PrefBranch;
+  /**
+   * The name of the pref to set.
+   */
+  pref: string;
+}
+/**
+ * Information about a JSON schema.
+ */
+export interface NimbusFeatureSchema {
+  /**
+   * The resource:// or chrome:// URI that can be loaded at runtime within Firefox.
+   *
+   * Required by Firefox so that Nimbus can import the schema for validation.
+   */
+  uri: string;
+  /**
+   * The path to the schema file in the source checkout.
+   *
+   * Required by Experimenter so that it can find schema files in source checkouts.
+   */
+  path: string;
+}
+/**
+ * The Firefox Desktop-specific feature manifest.
+ *
+ * Firefox Desktop requires different fields for its features compared to the general
+ * Nimbus feature manifest.
+ */
+export interface DesktopFeatureManifest {
+  [k: string]: DesktopFeature;
+}
+/**
+ * The experiment definition accessible to:
+ *
+ * 1. The Nimbus SDK via Remote Settings
+ * 2. Jetstream via the Experimenter API
+ */
 export interface NimbusExperiment {
+  /**
+   * Version of the NimbusExperiment schema this experiment refers to
+   */
   schemaVersion: string;
+  /**
+   * Unique identifier for the experiment
+   */
   slug: string;
+  /**
+   * Unique identifier for the experiiment.
+   *
+   * This is a duplicate of slug, but is required field for all Remote Settings records.
+   */
   id: string;
+  /**
+   * A slug identifying the targeted product of this experiment.
+   *
+   * It should be a lowercased_with_underscores name that is short and unambiguous and it should match the app_name found in https://probeinfo.telemetry.mozilla.org/glean/repositories. Examples are "fenix" and "firefox_desktop".
+   */
   appName: string;
+  /**
+   * The platform identifier for the targeted app.
+   *
+   * This should match app's identifier exactly as it appears in the relevant app store listing (for relevant platforms) or the app's Glean initialization (for other platforms).
+   *
+   * Examples are "org.mozilla.firefox_beta" and "firefox-desktop".
+   */
   appId: string;
+  /**
+   * A specific channel of an application such as "nightly", "beta", or "release".
+   */
   channel: string;
+  /**
+   * Public name of the experiment that will be displayed on "about:studies".
+   */
   userFacingName: string;
+  /**
+   * Short public description of the experiment that will be displayed on "about:studies".
+   */
   userFacingDescription: string;
+  /**
+   * When this property is set to true, the SDK should not enroll new users into the experiment that have not already been enrolled.
+   */
   isEnrollmentPaused: boolean;
-  isRollout?: boolean | null;
+  /**
+   * When this property is set to true, treat this experiment as a rollout.
+   *
+   * Rollouts are currently handled as single-branch experiments separated from the bucketing namespace for normal experiments.
+   *
+   * See-also: https://mozilla-hub.atlassian.net/browse/SDK-405
+   */
+  isRollout?: boolean;
   bucketConfig: ExperimentBucketConfig;
-  outcomes?: ExperimentOutcome[] | null;
-  featureIds: string[];
-  branches: (
-    | ExperimentSingleFeatureBranch
-    | ExperimentMultiFeatureDesktopBranch
-    | ExperimentMultiFeatureMobileBranch
-  )[];
+  /**
+   * A list of outcomes relevant to the experiment analysis.
+   */
+  outcomes?: ExperimentOutcome[];
+  /**
+   * A list of featureIds the experiment contains configurations for.
+   */
+  featureIds?: string[];
+  /**
+   * Branch configuration for the experiment.
+   */
+  branches:
+    | ExperimentSingleFeatureBranch[]
+    | ExperimentMultiFeatureDesktopBranch[]
+    | ExperimentMultiFeatureMobileBranch[];
+  /**
+   * A JEXL targeting expression used to filter out experiments.
+   */
   targeting?: string | null;
-  startDate?: string | null;
+  /**
+   * Actual publish date of the experiment.
+   *
+   * Note that this value is expected to be null in Remote Settings.
+   */
+  startDate: string | null;
+  /**
+   * Actual enrollment end date of the experiment.
+   *
+   * Note that this value is expected to be null in Remote Settings.
+   */
   enrollmentEndDate?: string | null;
-  endDate?: string | null;
-  proposedDuration?: number | null;
-  proposedEnrollment?: number | null;
-  referenceBranch?: string | null;
-  featureValidationOptOut?: boolean | null;
+  /**
+   * Actual end date of this experiment.
+   *
+   * Note that this field is expected to be null in Remote Settings.
+   */
+  endDate: string | null;
+  /**
+   * Duration of the experiment from the start date in days.
+   *
+   * Note that this property is only used during the analysis phase (i.e., not by the SDK).
+   */
+  proposedDuration?: number;
+  /**
+   * This represents the number of days that we expect to enroll new users.
+   *
+   * Note that this property is only used during the analysis phase (i.e., not by the SDK).
+   */
+  proposedEnrollment: number;
+  /**
+   * The slug of the reference branch (i.e., the branch we consider "control").
+   */
+  referenceBranch: string | null;
+  /**
+   * Opt out of feature schema validation. Only supported on desktop.
+   */
+  featureValidationOptOut?: boolean;
+  /**
+   * Per-locale localization substitutions.
+   *
+   * The top level key is the locale (e.g., "en-US" or "fr"). Each entry is a mapping of string IDs to their localized equivalents.
+   *
+   * Only supported on desktop.
+   */
   localizations?: {
-    [k: string]: unknown;
+    [k: string]: {
+      [k: string]: string;
+    };
   } | null;
+  /**
+   * The list of locale codes (e.g., "en-US" or "fr") that this experiment is targeting.
+   *
+   * If null, all locales are targeted.
+   */
   locales?: string[] | null;
+  /**
+   * The date that this experiment was first published to Remote Settings.
+   *
+   * If null, it has not yet been published.
+   */
+  publishedDate?: string | null;
 }
 export interface ExperimentBucketConfig {
   randomizationUnit: RandomizationUnit;
+  /**
+   * Additional inputs to the hashing function.
+   */
   namespace: string;
+  /**
+   * Index of the starting bucket of the range.
+   */
   start: number;
+  /**
+   * Number of buckets in the range.
+   */
   count: number;
+  /**
+   * The total number of buckets.
+   *
+   * You can assume this will always be 10000
+   */
   total: number;
 }
 export interface ExperimentOutcome {
+  /**
+   * Identifier for the outcome.
+   */
   slug: string;
+  /**
+   * e.g., "primary" or "secondary".
+   */
   priority: string;
 }
+/**
+ * A single-feature branch definition.
+ *
+ * Supported by Firefox Desktop for versions before 95, Firefox for Android for versions
+ * before 96, and Firefox for iOS for versions before 39.
+ */
 export interface ExperimentSingleFeatureBranch {
+  /**
+   * Identifier for the branch.
+   */
   slug: string;
+  /**
+   * Relative ratio of population for the branch.
+   *
+   * e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.
+   */
   ratio: number;
   feature: ExperimentFeatureConfig;
 }
 export interface ExperimentFeatureConfig {
+  /**
+   * The identifier for the feature flag.
+   */
   featureId: string;
-  enabled?: boolean | null;
+  /**
+   * The values that define the feature configuration.
+   *
+   * This should be validated against a schema.
+   */
   value: {
     [k: string]: unknown;
   };
 }
+/**
+ * The branch definition supported on Firefox Desktop 95+.
+ */
 export interface ExperimentMultiFeatureDesktopBranch {
+  /**
+   * Identifier for the branch.
+   */
   slug: string;
+  /**
+   * Relative ratio of population for the branch.
+   *
+   * e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.
+   */
   ratio: number;
-  feature: ExperimentFeatureConfig;
+  /**
+   * An array of feature configurations.
+   */
   features: ExperimentFeatureConfig[];
+  feature: DesktopTombstoneFeatureConfig;
 }
+export interface DesktopTombstoneFeatureConfig {
+  featureId: "unused-feature-id-for-legacy-support";
+  value: {
+    [k: string]: unknown;
+  };
+  enabled: false;
+}
+/**
+ * The branch definition for mobile browsers.
+ *
+ * Supported on Firefox for Android 96+ and Firefox for iOS 39+.
+ */
 export interface ExperimentMultiFeatureMobileBranch {
+  /**
+   * Identifier for the branch.
+   */
   slug: string;
+  /**
+   * Relative ratio of population for the branch.
+   *
+   * e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.
+   */
   ratio: number;
+  /**
+   * An array of feature configurations.
+   */
   features: ExperimentFeatureConfig[];
 }
-export interface FeatureManifest {
-  [k: string]: Feature;
+/**
+ * The SDK-specific feature manifest.
+ */
+export interface SdkFeatureManifest {
+  [k: string]: SdkFeature;
 }
 /**
- * A feature that has exposure.
+ * A feature.
  */
-export interface FeatureWithExposure {
-  description?: string | null;
-  isEarlyStartup?: boolean | null;
+export interface SdkFeature {
+  /**
+   * The description of the feature.
+   */
+  description: string;
+  /**
+   * Whether or not this feature records exposure telemetry.
+   */
+  hasExposure: boolean;
+  /**
+   * A description of the exposure telemetry collected by this feature.
+   *
+   * Only required if hasExposure is true.
+   */
+  exposureDescription?: string;
+  /**
+   * The variables that this feature can set.
+   */
   variables: {
-    [k: string]: FeatureVariable;
+    [k: string]: SdkFeatureVariable;
   };
-  schema?: NimbusFeatureSchema | null;
-  hasExposure: true;
-  exposureDescription: string;
-}
-export interface FeatureVariable {
-  description?: string | null;
-  enum?: string[] | null;
-  fallbackPref?: string | null;
-  type?: FeatureVariableType | null;
-  setPref?: string | SetPref | null;
-}
-export interface SetPref {
-  branch: PrefBranch;
-  pref: string;
-}
-export interface NimbusFeatureSchema {
-  uri: string;
-  path: string;
 }
 /**
- * A feature without exposure.
+ * A feature variable.
  */
-export interface FeatureWithoutExposure {
-  description?: string | null;
-  isEarlyStartup?: boolean | null;
-  variables: {
-    [k: string]: FeatureVariable;
-  };
-  schema?: NimbusFeatureSchema | null;
-  hasExposure: false;
+export interface SdkFeatureVariable {
+  /**
+   * A description of the feature.
+   */
+  description: string;
+  type: FeatureVariableType;
+  /**
+   * An optional list of possible string values.
+   *
+   * Only allowed when type is string.
+   */
+  enum?: string[];
 }
 export interface AnalysisError {
   analysis_basis?: AnalysisBasis | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mozilla/nimbus-schemas",
-  "version": "2024.9.3",
+  "version": "2024.10.1",
   "description": "Schemas used by Mozilla Nimbus and related projects.",
   "main": "index.d.ts",
   "repository": {
@@ -18,6 +18,7 @@
     "typescript": "^5.1.6"
   },
   "files": [
-    "index.d.ts"
+    "index.d.ts",
+    "schemas"
   ]
 }