palbase 0.8.1 → 0.9.0

package/types/internal/src/modules/flags.d.ts

@@ -15,10 +15,52 @@ export type Condition = {
      */
     value: unknown;
     /**
-     * The expression: comparisons over client.platform, client.locale, client.app_version, client.os_version, percentile, server.country and server.now, combined with && || and parentheses (512 characters, 16 comparisons at most).
+     * The expression: comparisons over client.platform, client.locale, client.app_version, client.os_version, percentile, server.country, server.now and server.audience, combined with && || and parentheses (512 characters, 16 comparisons at most). server.audience == '<id>' (or in ['<id>', …]) is a reader analytics has in that audience, and only one who allowed personalization: no one else is in any, and there is no "not in".
      */
     when: string;
 };
+/**
+ * What calling a leader takes — every variant seen by min_viewers people, the leader's chance to win min_chance — and what the results still lack, reason by reason: none, they are confident.
+ */
+export type Confidence = {
+    /**
+     * The chance to win the leader needs (0 to 1).
+     */
+    min_chance: number;
+    /**
+     * The people each variant needs to have been seen by.
+     */
+    min_viewers: number;
+    /**
+     * What is still lacking; empty when confident.
+     */
+    reasons: ConfidenceReason[];
+};
+/**
+ * One thing the results lack to call their leader.
+ */
+export type ConfidenceReason = {
+    /**
+     * Its chance to win, for leader_unsure.
+     */
+    chance?: number;
+    /**
+     * no_viewers: no one saw a variant yet; too_few_viewers: a variant was seen by fewer than min_viewers (variant, viewers); no_leader: no variant leads yet — one no one saw, or the likeliest even with the next (no leader is named); leader_unsure: the leader's chance to win is under min_chance (variant, chance). A client says a code it does not know in the reason's message.
+     */
+    code: "no_viewers" | "too_few_viewers" | "no_leader" | "leader_unsure";
+    /**
+     * The reason in words ("variant b has 40 viewers (needs 100)").
+     */
+    message: string;
+    /**
+     * The variant it is about.
+     */
+    variant?: string;
+    /**
+     * Its viewers, for too_few_viewers.
+     */
+    viewers?: number;
+};
 export type DailyBucket = {
     /**
      * The app version.
@@ -54,6 +96,7 @@ export type Delta = {
     sync_version: string;
 };
 export type DeltaOp = {
+    experiment?: FlagAssignment;
     /**
      * The flag's key.
      */
@@ -65,7 +108,7 @@ export type DeltaOp = {
     /**
      * Where the value came from.
      */
-    source: "system" | "override";
+    source: "system" | "override" | "experiment";
     /**
      * The value (put only).
      */
@@ -143,6 +186,189 @@ export type EvaluationsBucket = {
      */
     value?: string;
 };
+/**
+ * An experiment on a flag: while it runs, each of its people — everyone a read names (a user, or the installation of someone signed in as no one), or the people of an analytics audience who allowed personalization — gets one variant's value, the same on every read, until it is stopped or a variant is declared the winner.
+ */
+export type Experiment = {
+    /**
+     * The analytics audience it is for; absent: everyone a read names.
+     */
+    audience_id?: string;
+    /**
+     * When it ended; absent while it runs.
+     */
+    ended_at?: string;
+    /**
+     * Who ended it: the API key, or who deleted its flag.
+     */
+    ended_by?: string;
+    /**
+     * The analytics event its people are counted for doing after they first saw their variant.
+     */
+    goal_event: string;
+    /**
+     * The experiment's id.
+     */
+    id: string;
+    /**
+     * Its flag's key.
+     */
+    key: string;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * When it started.
+     */
+    started_at: string;
+    /**
+     * Who started it: the API key.
+     */
+    started_by: string;
+    /**
+     * running; stopped (its people get the flag's own value again); won (the winner's value became the flag's).
+     */
+    status: "running" | "stopped" | "won";
+    /**
+     * Its variants.
+     */
+    variants: ExperimentVariant[];
+    /**
+     * The variant declared the winner.
+     */
+    winner?: string;
+};
+/**
+ * A page of the project's experiments, newest first.
+ */
+export type ExperimentPage = {
+    /**
+     * The experiments.
+     */
+    experiments: Experiment[];
+    /**
+     * The next page's cursor; absent on the last.
+     */
+    next_cursor?: string;
+};
+/**
+ * An experiment to start on a flag.
+ */
+export type ExperimentRequest = {
+    /**
+     * An analytics audience: only its people who allowed personalization are in the experiment, everyone else gets the flag's own value. Absent: everyone a read names.
+     */
+    audience_id?: string;
+    /**
+     * The analytics event that counts as converting: a letter or $, then letters, digits and _ . : - $, at most 64.
+     */
+    goal_event: string;
+    /**
+     * The flag's key (not a Palbase-managed one).
+     */
+    key: string;
+    /**
+     * Its name, 1 to 100 characters.
+     */
+    name: string;
+    /**
+     * 2 to 4 variants.
+     */
+    variants: ExperimentVariant[];
+};
+/**
+ * What each variant's people did, counted where their events are (analytics).
+ */
+export type ExperimentResults = {
+    /**
+     * When they were counted.
+     */
+    computed_at: string;
+    confidence: Confidence;
+    /**
+     * Whether declaring the leader the winner is sound: confidence lacks nothing.
+     */
+    confident: boolean;
+    /**
+     * The experiment.
+     */
+    experiment_id: string;
+    /**
+     * The event counted as converting.
+     */
+    goal_event: string;
+    /**
+     * The variant likeliest to convert best; absent while none leads.
+     */
+    leader?: string;
+    /**
+     * The experiment's status.
+     */
+    status: "running" | "stopped" | "won";
+    /**
+     * Each variant's numbers, in the experiment's order.
+     */
+    variants: ExperimentVariantResult[];
+    /**
+     * The days after a person's first exposure the goal counted within.
+     */
+    window_days: number;
+};
+/**
+ * One value of the experiment's flag, to its share of the people: weight over the variants' weights together.
+ */
+export type ExperimentVariant = {
+    /**
+     * The variant's key: lowercase letters, digits and _, starting with a letter, at most 20.
+     */
+    key: string;
+    /**
+     * The value its people get: one the flag takes (its type, 8 KB at most, inside its choices); each variant's its own.
+     */
+    value: unknown;
+    /**
+     * Its share: 1 to 1000, over the variants' weights together.
+     */
+    weight: number;
+};
+/**
+ * One variant's numbers.
+ */
+export type ExperimentVariantResult = {
+    /**
+     * Its probability of converting best (0 to 1), Bayesian: how often its rate, drawn from what was seen, is the highest.
+     */
+    chance_to_win: number;
+    /**
+     * converters over viewers; 0 with no viewers.
+     */
+    conversion_rate: number;
+    /**
+     * The people exposed who did the goal event within window_days after their first exposure.
+     */
+    converters: number;
+    /**
+     * The exposures its people's apps reported ($flag_exposure, once a session).
+     */
+    exposures: number;
+    /**
+     * The variant's value.
+     */
+    value: unknown;
+    /**
+     * The variant's key.
+     */
+    variant: string;
+    /**
+     * The people exposed to it: each user, or installation of someone signed in as no one, once.
+     */
+    viewers: number;
+    /**
+     * Its weight.
+     */
+    weight: number;
+};
 export type Flag = {
     /**
      * Targeting, in order, first match wins (8 at most).
@@ -189,6 +415,28 @@ export type Flag = {
      */
     version: number;
 };
+/**
+ * The experiment variant a value is.
+ */
+export type FlagAssignment = {
+    /**
+     * The experiment.
+     */
+    experiment_id: string;
+    /**
+     * The variant's key.
+     */
+    variant: string;
+};
+/**
+ * flag.changed: the project's flag definitions changed; readers read them again.
+ */
+export type FlagChangedEvent = {
+    /**
+     * The definitions' new version.
+     */
+    sync_version: number;
+};
 export type FlagDefinition = {
     /**
      * Targeting, in order, first match wins (8 at most).
@@ -229,6 +477,19 @@ export type FlagEvaluations = {
  * The project's flags, by key.
  */
 export type FlagList = Flag[];
+/**
+ * flag.override_changed: a user's own flag values changed.
+ */
+export type FlagOverrideChangedEvent = {
+    /**
+     * The new version.
+     */
+    sync_version: number;
+    /**
+     * The user.
+     */
+    user_id: string;
+};
 export type FlagValues = {
     /**
      * When the answer was made.
@@ -284,18 +545,24 @@ export type ReadsBucket = {
 };
 export type Snapshot = {
     /**
-     * The hash of what the answer depends on besides the flags (client context, country, user, time conditions).
+     * The hash of what the answer depends on besides the flags (client context, country, user, time conditions, the audiences the reader is in).
      */
     context_hash: string;
+    /**
+     * The experiment variant each value an experiment gave is, by key; absent when none. When the app reads such a flag, the SDK sends the analytics event $flag_exposure {flag, experiment, variant} once a session: what the experiment's results count.
+     */
+    experiments?: {
+        [key: string]: FlagAssignment;
+    };
     /**
      * When the answer was made.
      */
     fetched_at: string;
     /**
-     * Where each value came from: the flag (system) or the user's own (override).
+     * Where each value came from: the flag (system), the user's own (override), or an experiment's variant (experiment).
      */
     sources: {
-        [key: string]: "system" | "override";
+        [key: string]: "system" | "override" | "experiment";
     };
     /**
      * The version the answer is current as of: the delta's since.
@@ -536,9 +803,9 @@ export type UserValueAnswer = {
      */
     key: string;
     /**
-     * override: the user's own; system: the flag's, resolved for the user.
+     * override: the user's own; experiment: an experiment's variant for the user; system: the flag's, resolved for the user.
      */
-    source: "system" | "override";
+    source: "system" | "override" | "experiment";
     /**
      * The value.
      */
@@ -584,15 +851,41 @@ export type VersionBucket = {
      */
     platform: string;
 };
+/**
+ * The variant that won.
+ */
+export type WinnerRequest = {
+    /**
+     * Roll it out as a condition at the top of the flag's — server.audience == the experiment's audience — and keep the flag's default; for an experiment for an audience only. Absent or false: its value becomes the flag's default.
+     */
+    as_rule?: boolean;
+    /**
+     * The variant's key.
+     */
+    variant: string;
+};
+/** The events this module sends the project's webhooks (x-palbase-events), by type: each one's payload, the event's data. */
+export interface Events {
+    /**
+     * flag.changed: the project's flag definitions changed.
+     */
+    "flag.changed": FlagChangedEvent;
+    /**
+     * flag.override_changed: a user's own flag values changed.
+     */
+    "flag.override_changed": FlagOverrideChangedEvent;
+}
 /** Palbase Flags */
 export declare function client(t: Transport): {
     /**
      * Read the flags' values
      *
-     * Every flag's value for the reader, alone. Resolved for the reader: a signed-in user's token (with the publishable key) makes the answer theirs — their own values first, then the first condition of each flag that matches, then its default. Conditions read what the client declares (platform, versions, locale), the share of users a percentile picks (signed-in users only), the country of the address the edge saw, and the server's clock.
+     * Every flag's value for the reader, alone. Resolved for the reader: a signed-in user's token (with the publishable key) makes the answer theirs — their own values first, then the variant of the experiment running on a flag when they are one of its people, then the first condition of each flag that matches, then its default. Conditions read what the client declares (platform, versions, locale), the share of users a percentile picks (signed-in users only), the country of the address the edge saw, the server's clock, and the analytics audiences the reader — the user or, signed in as no one, the installation proven with its secret — is in, having allowed personalization.
      */
     getValues(input?: {
         headers?: {
+            "X-Palbase-Installation"?: string; /** The installation's secret (kernel/installclaim; 43 to 256 characters): proves the X-Palbase-Installation it was made into. Without it, an installation named is no one for audiences and experiments. */
+            "X-Palbase-Installation-Secret"?: string; /** The client's platform (client.platform). */
             "X-Platform"?: string; /** The operating system's version (client.os_version). */
             "X-OS-Version"?: string; /** The app's version (client.app_version). */
             "X-Palbase-Client-Version"?: string; /** The client's languages; the first is client.locale. */
@@ -612,14 +905,16 @@ export declare function client(t: Transport): {
     /**
      * Read what changed
      *
-     * What changed for the reader since a version, in order: a value put, or a flag deleted. A client whose answer may no longer be its own — its context, country or user changed, or a time condition turned (its If-None-Match says) — or whose version is older than the deletions still kept (30 days), is answered 410 and takes a snapshot. Resolved for the reader: a signed-in user's token (with the publishable key) makes the answer theirs — their own values first, then the first condition of each flag that matches, then its default. Conditions read what the client declares (platform, versions, locale), the share of users a percentile picks (signed-in users only), the country of the address the edge saw, and the server's clock.
+     * What changed for the reader since a version, in order: a value put (with its experiment variant, when an experiment gave it), or a flag deleted; an experiment started or ended on a flag is a change of it. A client whose answer may no longer be its own — its context, country or user changed, a time condition turned, or the reader entered or left an audience (its If-None-Match says) — or whose version is older than the deletions still kept (30 days), is answered 410 and takes a snapshot. Resolved for the reader: a signed-in user's token (with the publishable key) makes the answer theirs — their own values first, then the variant of the experiment running on a flag when they are one of its people, then the first condition of each flag that matches, then its default. Conditions read what the client declares (platform, versions, locale), the share of users a percentile picks (signed-in users only), the country of the address the edge saw, the server's clock, and the analytics audiences the reader — the user or, signed in as no one, the installation proven with its secret — is in, having allowed personalization.
      */
     getDelta(input?: {
         query?: {
             since?: number;
         };
         headers?: {
-            "If-None-Match"?: string; /** The client's platform (client.platform). */
+            "If-None-Match"?: string; /** The app installation's id (64 characters at most): signed in as no one and proven with X-Palbase-Installation-Secret, whom an audience condition asks about and an experiment places. */
+            "X-Palbase-Installation"?: string; /** The installation's secret (kernel/installclaim; 43 to 256 characters): proves the X-Palbase-Installation it was made into. Without it, an installation named is no one for audiences and experiments. */
+            "X-Palbase-Installation-Secret"?: string; /** The client's platform (client.platform). */
             "X-Platform"?: string; /** The operating system's version (client.os_version). */
             "X-OS-Version"?: string; /** The app's version (client.app_version). */
             "X-Palbase-Client-Version"?: string; /** The client's languages; the first is client.locale. */
@@ -648,6 +943,76 @@ export declare function client(t: Transport): {
         }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, Evaluations>>;
+    /**
+     * List experiments
+     *
+     * The project's experiments, newest first, a page at a time; one flag's with key.
+     */
+    listExperiments(input?: {
+        query?: {
+            key?: string; /** How many experiments a page holds (20 unless said). */
+            limit?: number; /** The `next_cursor` of the page before. */
+            cursor?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ExperimentPage>>;
+    /**
+     * Start an experiment
+     *
+     * Starts an experiment on a flag: from the next read on, each of its people — everyone a read names (a user, or signed in as no one the installation proven with its secret: X-Palbase-Installation, X-Palbase-Installation-Secret), or the people of audience_id who allowed personalization — gets one variant's value, the same on every read (a hash of the experiment and the person over the weights: nothing is stored per person). A user's own value still comes first. A read carries the variant (Snapshot.experiments, DeltaOp.experiment); the app reports reading it as the analytics event $flag_exposure {flag, experiment, variant}, once a session. Every variant's value is one the flag takes; one experiment runs on a flag at a time; every reader is told (flags:<ref>).
+     */
+    startExperiment(input: {
+        body: ExperimentRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, Experiment>>;
+    /**
+     * Read an experiment
+     *
+     * One experiment.
+     */
+    getExperiment(input: {
+        path: {
+            experiment_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Experiment>>;
+    /**
+     * Read an experiment's results
+     *
+     * What each variant's people did, counted by analytics where their events are: the exposures their apps reported ($flag_exposure), the people exposed (each user, or installation of someone signed in as no one, once — counted for the variant they saw first), and those of them who did the goal event within `window_days` (7 unless said) after their first exposure; the conversion rate; and each variant's chance to convert best. `leader` is the likeliest best, `confident` whether declaring it the winner is sound. Analytics not answering is a 503: retrying is safe.
+     */
+    getExperimentResults(input: {
+        path: {
+            experiment_id: string;
+        };
+        query?: {
+            window_days?: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ExperimentResults>>;
+    /**
+     * Stop an experiment
+     *
+     * Stops a running experiment, at once: from the next read on its people get the flag's own value again; the flag stays as it was. Its results stay. Every reader is told (flags:<ref>).
+     */
+    stopExperiment(input: {
+        path: {
+            experiment_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Experiment>>;
+    /**
+     * Declare an experiment's winner
+     *
+     * Ends a running experiment with a winner: its value becomes the flag's default — or, as_rule (an experiment for an audience), the first of the flag's conditions, server.audience == the audience, and the default stays. With publishing on, that is the next published version (its note names the experiment). Every reader is told (flags:<ref>).
+     */
+    declareExperimentWinner(input: {
+        path: {
+            experiment_id: string;
+        };
+        body: WinnerRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Experiment>>;
     /**
      * Read the builds in use
      *
@@ -670,12 +1035,13 @@ export declare function client(t: Transport): {
     /**
      * Take a snapshot
      *
-     * Every flag's value for the reader, where each came from, and the version it is current as of — what a client starts from, then keeps up to date with deltas. Resolved for the reader: a signed-in user's token (with the publishable key) makes the answer theirs — their own values first, then the first condition of each flag that matches, then its default. Conditions read what the client declares (platform, versions, locale), the share of users a percentile picks (signed-in users only), the country of the address the edge saw, and the server's clock. The answer's ETag names the version and everything else it depends on; sent back as If-None-Match, an unchanged answer is 304. Each read is metered (flags.reads).
+     * Every flag's value for the reader, where each came from, and the version it is current as of — what a client starts from, then keeps up to date with deltas. Resolved for the reader: a signed-in user's token (with the publishable key) makes the answer theirs — their own values first, then the variant of the experiment running on a flag when they are one of its people, then the first condition of each flag that matches, then its default. Conditions read what the client declares (platform, versions, locale), the share of users a percentile picks (signed-in users only), the country of the address the edge saw, the server's clock, and the analytics audiences the reader is in — asked of auth (did they allow personalization) and analytics once per read, for the user or, signed in as no one, the installation proven with its secret (X-Palbase-Installation, X-Palbase-Installation-Secret); a reader they cannot answer for is in none. The answer's ETag names the version and everything else it depends on — the audiences the reader is in too: one who entered or left one gets the new answer; sent back as If-None-Match, an unchanged answer is 304. A value an experiment gave names its variant (experiments): the app reports reading it as the analytics event $flag_exposure. Each read is metered (flags.reads).
      */
     getSnapshot(input?: {
         headers?: {
-            "If-None-Match"?: string; /** The app installation's id (64 characters at most): counted for version adoption. */
-            "X-Palbase-Installation"?: string; /** The client's platform (client.platform). */
+            "If-None-Match"?: string; /** The app installation's id (64 characters at most): counted for version adoption; signed in as no one and proven with X-Palbase-Installation-Secret, whom an audience condition asks about and an experiment places. */
+            "X-Palbase-Installation"?: string; /** The installation's secret (kernel/installclaim; 43 to 256 characters): proves the X-Palbase-Installation it was made into. Without it, an installation named is no one for audiences and experiments. */
+            "X-Palbase-Installation-Secret"?: string; /** The client's platform (client.platform). */
             "X-Platform"?: string; /** The operating system's version (client.os_version). */
             "X-OS-Version"?: string; /** The app's version (client.app_version). */
             "X-Palbase-Client-Version"?: string; /** The client's languages; the first is client.locale. */
@@ -705,7 +1071,7 @@ export declare function client(t: Transport): {
     /**
      * Define a flag
      *
-     * Defines a flag, or changes one (a deleted one comes back): its type, its default, the choices a string flag allows, and the conditions — first match wins — that give another value. Refused while publishing is on (templates), when it would change the type under users' values or leave a user's value outside the choices, and past 200 flags. Every reader is told (flags:<ref>).
+     * Defines a flag, or changes one (a deleted one comes back): its type, its default, the choices a string flag allows, and the conditions — first match wins — that give another value. Refused while publishing is on (templates), when it would change the type under users' values or leave a user's value outside the choices, past 200 flags, and when it would change the type or choices under the experiment running on the flag. Every reader is told (flags:<ref>).
      */
     putDefinition(input: {
         path: {