1
/**
2
 * Evaluation context for targeting rules.
3
 * Keys are attribute names (e.g. "userId", "country"), values are the attribute values.
4
 */
5
export type FlagshipEvaluationContext = Record<
6
  string,
7
  string | number | boolean
8
>;
9
 
10
export interface FlagshipEvaluationDetails<T> {
11
  flagKey: string;
12
  value: T;
13
  variant?: string | undefined;
14
  reason?: string | undefined;
15
  errorCode?: string | undefined;
16
  errorMessage?: string | undefined;
17
}
18
 
19
export interface FlagshipEvaluationError extends Error {}
20
 
21
/**
22
 * Feature flags binding for evaluating feature flags from a Cloudflare Workers script.
23
 *
24
 * @example
25
 * ```typescript
26
 * // Get a boolean flag value with a default
27
 * const enabled = await env.FLAGS.getBooleanValue('my-feature', false);
28
 *
29
 * // Get a flag value with evaluation context for targeting
30
 * const variant = await env.FLAGS.getStringValue('experiment', 'control', {
31
 *   userId: 'user-123',
32
 *   country: 'US',
33
 * });
34
 *
35
 * // Get full evaluation details including variant and reason
36
 * const details = await env.FLAGS.getBooleanDetails('my-feature', false);
37
 * console.log(details.variant, details.reason);
38
 * ```
39
 */
40
export declare abstract class Flagship {
41
  /**
42
   * Get a flag value without type checking.
43
   * @param flagKey The key of the flag to evaluate.
44
   * @param defaultValue Optional default value returned when evaluation fails.
45
   * @param context Optional evaluation context for targeting rules.
46
   */
47
  get(
48
    flagKey: string,
49
    defaultValue?: unknown,
50
    context?: FlagshipEvaluationContext
51
  ): Promise<unknown>;
52
 
53
  /**
54
   * Get a boolean flag value.
55
   * @param flagKey The key of the flag to evaluate.
56
   * @param defaultValue Default value returned when evaluation fails or the flag type does not match.
57
   * @param context Optional evaluation context for targeting rules.
58
   */
59
  getBooleanValue(
60
    flagKey: string,
61
    defaultValue: boolean,
62
    context?: FlagshipEvaluationContext
63
  ): Promise<boolean>;
64
 
65
  /**
66
   * Get a string flag value.
67
   * @param flagKey The key of the flag to evaluate.
68
   * @param defaultValue Default value returned when evaluation fails or the flag type does not match.
69
   * @param context Optional evaluation context for targeting rules.
70
   */
71
  getStringValue(
72
    flagKey: string,
73
    defaultValue: string,
74
    context?: FlagshipEvaluationContext
75
  ): Promise<string>;
76
 
77
  /**
78
   * Get a number flag value.
79
   * @param flagKey The key of the flag to evaluate.
80
   * @param defaultValue Default value returned when evaluation fails or the flag type does not match.
81
   * @param context Optional evaluation context for targeting rules.
82
   */
83
  getNumberValue(
84
    flagKey: string,
85
    defaultValue: number,
86
    context?: FlagshipEvaluationContext
87
  ): Promise<number>;
88
 
89
  /**
90
   * Get an object flag value.
91
   * @param flagKey The key of the flag to evaluate.
92
   * @param defaultValue Default value returned when evaluation fails or the flag type does not match.
93
   * @param context Optional evaluation context for targeting rules.
94
   */
95
  getObjectValue<T extends object>(
96
    flagKey: string,
97
    defaultValue: T,
98
    context?: FlagshipEvaluationContext
99
  ): Promise<T>;
100
 
101
  /**
102
   * Get a boolean flag value with full evaluation details.
103
   * @param flagKey The key of the flag to evaluate.
104
   * @param defaultValue Default value returned when evaluation fails or the flag type does not match.
105
   * @param context Optional evaluation context for targeting rules.
106
   */
107
  getBooleanDetails(
108
    flagKey: string,
109
    defaultValue: boolean,
110
    context?: FlagshipEvaluationContext
111
  ): Promise<FlagshipEvaluationDetails<boolean>>;
112
 
113
  /**
114
   * Get a string flag value with full evaluation details.
115
   * @param flagKey The key of the flag to evaluate.
116
   * @param defaultValue Default value returned when evaluation fails or the flag type does not match.
117
   * @param context Optional evaluation context for targeting rules.
118
   */
119
  getStringDetails(
120
    flagKey: string,
121
    defaultValue: string,
122
    context?: FlagshipEvaluationContext
123
  ): Promise<FlagshipEvaluationDetails<string>>;
124
 
125
  /**
126
   * Get a number flag value with full evaluation details.
127
   * @param flagKey The key of the flag to evaluate.
128
   * @param defaultValue Default value returned when evaluation fails or the flag type does not match.
129
   * @param context Optional evaluation context for targeting rules.
130
   */
131
  getNumberDetails(
132
    flagKey: string,
133
    defaultValue: number,
134
    context?: FlagshipEvaluationContext
135
  ): Promise<FlagshipEvaluationDetails<number>>;
136
 
137
  /**
138
   * Get an object flag value with full evaluation details.
139
   * @param flagKey The key of the flag to evaluate.
140
   * @param defaultValue Default value returned when evaluation fails or the flag type does not match.
141
   * @param context Optional evaluation context for targeting rules.
142
   */
143
  getObjectDetails<T extends object>(
144
    flagKey: string,
145
    defaultValue: T,
146
    context?: FlagshipEvaluationContext
147
  ): Promise<FlagshipEvaluationDetails<T>>;
148
}