@productcraft/flags 0.4.0 → 0.6.0
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.
- package/README.md +51 -13
- package/api.md +577 -20
- package/dist/{chunk-7237IZU3.js → browser/chunk-OUAC4WID.js} +589 -24
- package/dist/browser/chunk-OUAC4WID.js.map +1 -0
- package/dist/browser/{chunk-CXYODDHM.cjs → chunk-UYL3NMDA.cjs} +589 -24
- package/dist/browser/chunk-UYL3NMDA.cjs.map +1 -0
- package/dist/browser/{chunk-72WU42RU.js → chunk-WUZAG2E3.js} +11 -4
- package/dist/browser/chunk-WUZAG2E3.js.map +1 -0
- package/dist/browser/{chunk-4XCQBTYE.cjs → chunk-YM5K4NHA.cjs} +11 -4
- package/dist/browser/chunk-YM5K4NHA.cjs.map +1 -0
- package/dist/browser/index.cjs +9 -9
- package/dist/browser/index.cjs.map +1 -1
- package/dist/browser/index.js +3 -3
- package/dist/browser/index.js.map +1 -1
- package/dist/browser/management.cjs +2 -2
- package/dist/browser/management.js +1 -1
- package/dist/browser/testing.cjs +848 -3
- package/dist/browser/testing.cjs.map +1 -1
- package/dist/browser/testing.js +846 -1
- package/dist/browser/testing.js.map +1 -1
- package/dist/{chunk-NSAKFGTJ.cjs → chunk-5SDZWOUP.cjs} +589 -24
- package/dist/chunk-5SDZWOUP.cjs.map +1 -0
- package/dist/{chunk-NB7OGN6R.js → chunk-7BOM23MI.js} +12 -5
- package/dist/chunk-7BOM23MI.js.map +1 -0
- package/dist/{browser/chunk-TCVKCN3S.js → chunk-JGSMXA3G.js} +589 -24
- package/dist/chunk-JGSMXA3G.js.map +1 -0
- package/dist/{chunk-Q3P66XRI.cjs → chunk-SHMDNO4G.cjs} +12 -5
- package/dist/chunk-SHMDNO4G.cjs.map +1 -0
- package/dist/{client-K2zALPGD.d.cts → client-BBiIKiGW.d.cts} +18 -14
- package/dist/{client-K2zALPGD.d.ts → client-BBiIKiGW.d.ts} +18 -14
- package/dist/{client-BwoMpm8_.d.cts → client-DVKdRqhR.d.cts} +7628 -3034
- package/dist/{client-BwoMpm8_.d.ts → client-DVKdRqhR.d.ts} +7628 -3034
- package/dist/index.cjs +9 -9
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/management.cjs +2 -2
- package/dist/management.d.cts +1 -1
- package/dist/management.d.ts +1 -1
- package/dist/management.js +1 -1
- package/dist/testing.cjs +848 -3
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +5 -5
- package/dist/testing.d.ts +5 -5
- package/dist/testing.js +846 -1
- package/dist/testing.js.map +1 -1
- package/manifest.json +317 -2
- package/package.json +2 -2
- package/dist/browser/chunk-4XCQBTYE.cjs.map +0 -1
- package/dist/browser/chunk-72WU42RU.js.map +0 -1
- package/dist/browser/chunk-CXYODDHM.cjs.map +0 -1
- package/dist/browser/chunk-TCVKCN3S.js.map +0 -1
- package/dist/chunk-7237IZU3.js.map +0 -1
- package/dist/chunk-NB7OGN6R.js.map +0 -1
- package/dist/chunk-NSAKFGTJ.cjs.map +0 -1
- package/dist/chunk-Q3P66XRI.cjs.map +0 -1
package/README.md
CHANGED
|
@@ -45,6 +45,23 @@ await flags.getValue("new_checkout", false); // uses the default user
|
|
|
45
45
|
await flags.getValue("new_checkout", false, { identifier: "user-456" }); // replaces it as a whole (no merge)
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
+
Your own user type works as it is, no spread needed: any interface with `identifier` / `email` / `country` / `custom` (and any other attributes) is accepted (`UserInput`).
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
import { FlagsClient } from "@productcraft/flags";
|
|
52
|
+
const flags = new FlagsClient({ sdkKey: process.env.PRODUCTCRAFT_FLAGS_SDK_KEY });
|
|
53
|
+
|
|
54
|
+
interface AppUser {
|
|
55
|
+
identifier: string;
|
|
56
|
+
email?: string;
|
|
57
|
+
plan: "free" | "pro";
|
|
58
|
+
}
|
|
59
|
+
declare const me: AppUser;
|
|
60
|
+
await flags.getValue("new_checkout", false, me);
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
A rule on an attribute the user does not have is skipped for that user (a soft miss, in `getValueDetails().warnings`). The client logs each such warning once per attribute for its lifetime, so anonymous traffic does not flood your logs; pass `logger: null` to log nothing.
|
|
64
|
+
|
|
48
65
|
Text comparisons are by codepoint with no Unicode normalisation: pass emails and names in **NFC** (`email.normalize("NFC")`), or two spellings of the same address can match different rules and buckets.
|
|
49
66
|
|
|
50
67
|
### Why a value? Details, all values, snapshots
|
|
@@ -116,6 +133,24 @@ const flags = new FlagsClient({
|
|
|
116
133
|
|
|
117
134
|
The client refuses a download over 2 MiB, never moves back to an older revision of the config, and only follows delivery hints that point at `https://*.productcraft.co`.
|
|
118
135
|
|
|
136
|
+
### Your own delivery host: `baseUrl`
|
|
137
|
+
|
|
138
|
+
By default the client downloads from `https://api.flags.productcraft.co` and then follows the delivery hosts the config itself names (`delivery.base_urls`). Set `baseUrl` when your servers must reach Flags somewhere else:
|
|
139
|
+
|
|
140
|
+
- **in-cluster or self-hosted**: the delivery service's internal address, when your pods cannot reach the public ingress (for example a load balancer that does not hairpin);
|
|
141
|
+
- **behind an egress proxy or your own CDN** in front of the delivery URL.
|
|
142
|
+
|
|
143
|
+
With `baseUrl` set, the client downloads only from that host and **ignores the config's `delivery.base_urls` hint**, so it never switches to a public host your network cannot reach. Everything else (polling, cache, bootstrap, fail-safe defaults) works the same.
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
import { FlagsClient } from "@productcraft/flags";
|
|
147
|
+
|
|
148
|
+
const flags = new FlagsClient({
|
|
149
|
+
sdkKey: process.env.PRODUCTCRAFT_FLAGS_SDK_KEY,
|
|
150
|
+
baseUrl: process.env.PRODUCTCRAFT_FLAGS_URL, // e.g. http://flags-api.flags.svc.cluster.local
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
119
154
|
## Serverless and edge functions
|
|
120
155
|
|
|
121
156
|
Timers do not survive between invocations, so use **lazy polling with the shared cache and `bootstrap`**: a cold start reads the cache (one Redis round trip, no download while the cached config is younger than `ttlSeconds`), and only one invocation per TTL downloads, with `If-None-Match`.
|
|
@@ -236,13 +271,16 @@ The user object has the same shape (`identifier`, `email`, `country`, `custom`);
|
|
|
236
271
|
|
|
237
272
|
Full reference: [api.md](./api.md).
|
|
238
273
|
|
|
274
|
+
- `flags.changeRequests`: `apply`, `approve`, `cancel`, `list`, `rebase`, `reject`, `retrieve`, `schedule`
|
|
239
275
|
- `flags.changes`: `retrieve`, `revert`
|
|
240
276
|
- `flags.configs`: `compare`, `delete`, `environments.copy`, `environments.evaluate`, `environments.revisions.list`, `environments.revisions.retrieve`, `environments.sdkKeys.endGracePeriod`, `environments.sdkKeys.list`, `environments.sdkKeys.reveal`, `environments.sdkKeys.rotate`, `environments.values.list`, `retrieve`, `settings.create`, `settings.list`, `update`
|
|
241
277
|
- `flags.imports`: `create`
|
|
242
278
|
- `flags.limits`: `retrieve`
|
|
243
|
-
- `flags.projects`: `changes.export`, `changes.list`, `configs.create`, `configs.list`, `create`, `delete`, `environments.create`, `environments.delete`, `environments.list`, `environments.retrieve`, `environments.update`, `list`, `retrieve`, `segments.create`, `segments.list`, `update`
|
|
279
|
+
- `flags.projects`: `changes.export`, `changes.list`, `configs.create`, `configs.list`, `create`, `delete`, `environments.create`, `environments.delete`, `environments.list`, `environments.retrieve`, `environments.update`, `list`, `retrieve`, `segments.create`, `segments.list`, `staleFlags.list`, `staleFlags.sendDigest`, `update`
|
|
280
|
+
- `flags.ramps`: `cancel`, `list`, `pause`, `resume`, `retrieve`
|
|
281
|
+
- `flags.scheduledChanges`: `cancel`, `list`, `retrieve`
|
|
244
282
|
- `flags.segments`: `delete`, `retrieve`, `revealConfidential`, `update`
|
|
245
|
-
- `flags.settings`: `delete`, `retrieve`, `update`, `values.replace`, `values.retrieve`, `values.revealConfidential`, `values.update`
|
|
283
|
+
- `flags.settings`: `delete`, `retrieve`, `update`, `values.changeRequests.create`, `values.ramps.create`, `values.replace`, `values.retrieve`, `values.revealConfidential`, `values.scheduledChanges.create`, `values.update`
|
|
246
284
|
- `flags.stats`: `retrieve`
|
|
247
285
|
- `flags.webhooks`: `endpoints.create`, `endpoints.delete`, `endpoints.list`, `endpoints.retrieve`, `endpoints.rotateSecret`, `endpoints.test`, `endpoints.update`, `eventTypes.list`, `events.list`, `events.replay`, `events.retrieve`
|
|
248
286
|
|
|
@@ -253,10 +291,10 @@ List methods return a `PagePromise`: `for await` walks every item across pages,
|
|
|
253
291
|
```ts
|
|
254
292
|
import { Flags } from "@productcraft/flags";
|
|
255
293
|
const flags = new Flags({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
|
|
256
|
-
for await (const item of flags.
|
|
257
|
-
const page = await flags.
|
|
294
|
+
for await (const item of flags.changeRequests.list({ limit: 50 })) console.log(item);
|
|
295
|
+
const page = await flags.changeRequests.list();
|
|
258
296
|
if (page.hasNextPage()) await page.getNextPage();
|
|
259
|
-
const all = await flags.
|
|
297
|
+
const all = await flags.changeRequests.list().toArray({ maxItems: 500 });
|
|
260
298
|
```
|
|
261
299
|
|
|
262
300
|
## Errors
|
|
@@ -267,7 +305,7 @@ Every failure is a class you can catch. `APIError` carries `status`, `code`, `me
|
|
|
267
305
|
import { Flags, NotFoundError, RateLimitError, APIError } from "@productcraft/flags";
|
|
268
306
|
const flags = new Flags();
|
|
269
307
|
try {
|
|
270
|
-
await flags.
|
|
308
|
+
await flags.changeRequests.retrieve("00000000-0000-0000-0000-000000000000");
|
|
271
309
|
} catch (err) {
|
|
272
310
|
if (err instanceof NotFoundError) console.log(err.code, err.requestId, err.docUrl);
|
|
273
311
|
else if (err instanceof RateLimitError) console.log(err.retryAfter);
|
|
@@ -283,7 +321,7 @@ Network errors, 408, 429, 5xx and `409 IDEMPOTENCY_IN_PROGRESS` are retried twic
|
|
|
283
321
|
```ts
|
|
284
322
|
import { Flags } from "@productcraft/flags";
|
|
285
323
|
const flags = new Flags({ maxRetries: 3, timeout: 20_000 });
|
|
286
|
-
await flags.
|
|
324
|
+
await flags.changeRequests.list({}, { maxRetries: 0, signal: AbortSignal.timeout(5_000) });
|
|
287
325
|
```
|
|
288
326
|
|
|
289
327
|
## Idempotency
|
|
@@ -308,7 +346,7 @@ const flags = new Flags();
|
|
|
308
346
|
export async function POST(req: Request) {
|
|
309
347
|
const event = await flags.webhooks.unwrap({ payload: await req.text(), headers: req.headers });
|
|
310
348
|
switch (event.type) {
|
|
311
|
-
case "
|
|
349
|
+
case "change_request.applied":
|
|
312
350
|
console.log(event.data);
|
|
313
351
|
break;
|
|
314
352
|
default:
|
|
@@ -351,7 +389,7 @@ Testing a handler: `webhooks.sign()` signs an event the way ProductCraft does, s
|
|
|
351
389
|
```ts
|
|
352
390
|
import { Flags } from "@productcraft/flags";
|
|
353
391
|
const flags = new Flags({ webhookSecret: "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" });
|
|
354
|
-
const { payload, headers } = await flags.webhooks.sign({ payload: { id: "evt_test_1", type: "
|
|
392
|
+
const { payload, headers } = await flags.webhooks.sign({ payload: { id: "evt_test_1", type: "change_request.applied", created_at: new Date().toISOString(), data: {} } });
|
|
355
393
|
const event = await flags.webhooks.unwrap({ payload, headers });
|
|
356
394
|
console.log(event.type);
|
|
357
395
|
```
|
|
@@ -364,9 +402,9 @@ Every returned object has a non-enumerable `lastResponse` (`requestId`, `status`
|
|
|
364
402
|
import { Flags } from "@productcraft/flags";
|
|
365
403
|
const flags = new Flags({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
|
|
366
404
|
const id = "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b";
|
|
367
|
-
const obj = await flags.
|
|
405
|
+
const obj = await flags.changeRequests.retrieve(id);
|
|
368
406
|
console.log(obj.lastResponse.requestId);
|
|
369
|
-
const { data, response, requestId, rateLimit } = await flags.
|
|
407
|
+
const { data, response, requestId, rateLimit } = await flags.changeRequests.retrieve(id).withResponse();
|
|
370
408
|
console.log(data, response.status, requestId, rateLimit?.remaining);
|
|
371
409
|
```
|
|
372
410
|
|
|
@@ -379,7 +417,7 @@ import { Flags } from "@productcraft/flags";
|
|
|
379
417
|
import { createMockFetch } from "@productcraft/flags/testing";
|
|
380
418
|
const fetch = createMockFetch();
|
|
381
419
|
const flags = new Flags({ apiKey: "test", workspaceId: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b", fetch });
|
|
382
|
-
await flags.
|
|
420
|
+
await flags.changeRequests.list();
|
|
383
421
|
console.log(fetch.calls.length);
|
|
384
422
|
```
|
|
385
423
|
|
|
@@ -390,7 +428,7 @@ console.log(fetch.calls.length);
|
|
|
390
428
|
```ts
|
|
391
429
|
import { Flags } from "@productcraft/flags";
|
|
392
430
|
const flags = new Flags({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
|
|
393
|
-
const { data, error } = await flags.client.GET("/v1/workspaces/{workspace_id}/
|
|
431
|
+
const { data, error } = await flags.client.GET("/v1/workspaces/{workspace_id}/change-requests", { params: { path: { workspace_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b" } } });
|
|
394
432
|
console.log(data, error);
|
|
395
433
|
```
|
|
396
434
|
|