@flipflag/sdk 1.1.2 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +52 -96
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,15 +1,23 @@
1
1
  # FlipFlag SDK
2
2
 
3
- A lightweight client-side SDK for working with **FlipFlag**.
4
- It allows you to:
3
+ A lightweight client-side SDK for working with **FlipFlag** (https://flipflag.dev).
5
4
 
6
- - Declare features programmatically
7
- - Auto-create features on the server
8
- - Check whether a feature is enabled
9
- - Periodically sync feature states
10
- - Manage feature definitions (options + metadata)
5
+ The SDK is designed to be simple, declarative, and safe by default.
6
+ It supports read-only usage as well as full feature management when a private key is provided.
11
7
 
12
- The SDK includes full TypeScript types and a Jest test suite.
8
+ ---
9
+
10
+ ## Features
11
+
12
+ - Load feature flags (`enabled`) using a **public key**
13
+ - Declare feature activation windows via `.flipflag.yml`
14
+ - Automatically create features on the server (requires `privateKey`)
15
+ - Periodically sync:
16
+ - feature flags
17
+ - feature timing declarations
18
+ - feature usage events
19
+ - Local in-memory cache for flags, declarations, and usage
20
+ - Full TypeScript support
13
21
 
14
22
  ---
15
23
 
@@ -23,133 +31,81 @@ yarn add @flipflag/sdk
23
31
 
24
32
  ---
25
33
 
26
- ## Usage
27
-
28
- ### Initialize the manager
34
+ ## Quick Start
29
35
 
30
36
  ```ts
31
- import { FlipFlag } from '@flipflag/sdk';
37
+ import { FlipFlag } from "@flipflag/sdk";
32
38
 
33
39
  const manager = new FlipFlag({
34
- publicKey: 'YOUR_PUBLIC_KEY',
35
- privateKey: 'YOUR_PRIVATE_KEY', // optional for read-only mode
40
+ publicKey: "YOUR_PUBLIC_KEY",
41
+ privateKey: "YOUR_PRIVATE_KEY", // optional (read-only mode without it)
36
42
  });
37
43
 
38
44
  await manager.init();
45
+
46
+ if (manager.isEnabled("newFeature")) {
47
+ console.log("Feature is enabled!");
48
+ }
39
49
  ```
40
50
 
41
- ### Declare a feature
51
+ ---
42
52
 
43
- ```ts
44
- manager.declareFeature('newFeature', {
45
- times: [
46
- {
47
- start: new Date(),
48
- },
49
- ],
50
- });
53
+ ## Configuration via `.flipflag.yml`
54
+
55
+ By default, the SDK looks for a `.flipflag.yml` file in the project root
56
+ (`process.cwd()`), which is loaded during `init()`.
57
+
58
+ ### Example `.flipflag.yml`
59
+
60
+ ```yml
61
+ newFeature:
62
+ contributor: epolevov@emd.one
63
+ times:
64
+ - started: "2025-12-01T00:00:00.000Z"
65
+ finished: "2025-12-31T23:59:59.000Z"
66
+
67
+ anotherFeature:
68
+ contributor: dev@company.com
69
+ times:
70
+ - started: "2026-01-01T00:00:00.000Z"
51
71
  ```
52
72
 
53
- If the feature does not exist on the server and you provided a `privateKey`,
54
- the SDK will automatically create it.
73
+ ---
55
74
 
56
- ### Check if a feature is enabled
75
+ ## Checking Feature State
57
76
 
58
77
  ```ts
59
- if (manager.isEnabled('newFeature')) {
60
- console.log('Feature is enabled!');
61
- }
78
+ manager.isEnabled("newFeature");
62
79
  ```
63
80
 
64
- If the feature has not been declared yet, a placeholder is created automatically
65
- and `false` is returned.
66
-
67
81
  ---
68
82
 
69
83
  ## Automatic Syncing
70
84
 
71
- After calling `init()`, the manager:
85
+ After calling `init()`, the SDK starts a **10-second polling loop**.
72
86
 
73
- - Loads all features using your `publicKey`
74
- - Starts a **10-second interval** that refreshes feature states
75
- - Keeps local cache in `declaredFeatures`
76
-
77
- To stop syncing:
87
+ To stop syncing and clear all local state:
78
88
 
79
89
  ```ts
80
90
  manager.destroy();
81
91
  ```
82
92
 
83
- This clears the interval and resets the cache.
84
-
85
93
  ---
86
94
 
87
- ## TypeScript Types
95
+ ## Manager Options
88
96
 
89
97
  ```ts
90
98
  export interface IManagerOptions {
91
99
  apiUrl?: string;
92
100
  publicKey: string;
93
101
  privateKey?: string;
102
+ configPath?: string;
103
+ ignoreMissingConfig?: boolean;
94
104
  }
95
-
96
- export interface IDeclareFeatureTime {
97
- start: Date;
98
- end?: Date;
99
- }
100
-
101
- export interface IDeclareFeatureOptions {
102
- times: IDeclareFeatureTime[];
103
- }
104
-
105
- export interface IFeatureFlag {
106
- enabled: boolean;
107
- }
108
- ```
109
-
110
- ---
111
-
112
- ## Running Tests
113
-
114
- This SDK comes with full Jest test coverage, including:
115
-
116
- - Mocked `fetch` requests
117
- - Interval polling behavior
118
- - Feature creation
119
- - Error handling
120
- - Local cache logic
121
-
122
- ---
123
-
124
- ## Example: Full Integration
125
-
126
- ```ts
127
- import { FlipFlag } from '@flipflag/sdk';
128
-
129
- async function main() {
130
- const manager = new FlipFlag({
131
- publicKey: 'pk_live_123',
132
- privateKey: 'sk_live_123',
133
- });
134
-
135
- await manager.init();
136
-
137
- manager.declareFeature('demoFeature', {
138
- times: [
139
- { start: new Date() },
140
- ],
141
- });
142
-
143
- if (manager.isEnabled('demoFeature')) {
144
- console.log('Demo feature is active!');
145
- }
146
- }
147
-
148
- main();
149
105
  ```
150
106
 
151
107
  ---
152
108
 
153
109
  ## License
154
110
 
155
- MIT License.
111
+ MIT License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@flipflag/sdk",
3
- "version": "1.1.2",
3
+ "version": "1.1.3",
4
4
  "type": "module",
5
5
  "types": "dist/index.d.ts",
6
6
  "description": "A lightweight client-side SDK for working with FlipFlag",