@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.
Files changed (58) hide show
  1. package/README.md +51 -13
  2. package/api.md +577 -20
  3. package/dist/{chunk-7237IZU3.js → browser/chunk-OUAC4WID.js} +589 -24
  4. package/dist/browser/chunk-OUAC4WID.js.map +1 -0
  5. package/dist/browser/{chunk-CXYODDHM.cjs → chunk-UYL3NMDA.cjs} +589 -24
  6. package/dist/browser/chunk-UYL3NMDA.cjs.map +1 -0
  7. package/dist/browser/{chunk-72WU42RU.js → chunk-WUZAG2E3.js} +11 -4
  8. package/dist/browser/chunk-WUZAG2E3.js.map +1 -0
  9. package/dist/browser/{chunk-4XCQBTYE.cjs → chunk-YM5K4NHA.cjs} +11 -4
  10. package/dist/browser/chunk-YM5K4NHA.cjs.map +1 -0
  11. package/dist/browser/index.cjs +9 -9
  12. package/dist/browser/index.cjs.map +1 -1
  13. package/dist/browser/index.js +3 -3
  14. package/dist/browser/index.js.map +1 -1
  15. package/dist/browser/management.cjs +2 -2
  16. package/dist/browser/management.js +1 -1
  17. package/dist/browser/testing.cjs +848 -3
  18. package/dist/browser/testing.cjs.map +1 -1
  19. package/dist/browser/testing.js +846 -1
  20. package/dist/browser/testing.js.map +1 -1
  21. package/dist/{chunk-NSAKFGTJ.cjs → chunk-5SDZWOUP.cjs} +589 -24
  22. package/dist/chunk-5SDZWOUP.cjs.map +1 -0
  23. package/dist/{chunk-NB7OGN6R.js → chunk-7BOM23MI.js} +12 -5
  24. package/dist/chunk-7BOM23MI.js.map +1 -0
  25. package/dist/{browser/chunk-TCVKCN3S.js → chunk-JGSMXA3G.js} +589 -24
  26. package/dist/chunk-JGSMXA3G.js.map +1 -0
  27. package/dist/{chunk-Q3P66XRI.cjs → chunk-SHMDNO4G.cjs} +12 -5
  28. package/dist/chunk-SHMDNO4G.cjs.map +1 -0
  29. package/dist/{client-K2zALPGD.d.cts → client-BBiIKiGW.d.cts} +18 -14
  30. package/dist/{client-K2zALPGD.d.ts → client-BBiIKiGW.d.ts} +18 -14
  31. package/dist/{client-BwoMpm8_.d.cts → client-DVKdRqhR.d.cts} +7628 -3034
  32. package/dist/{client-BwoMpm8_.d.ts → client-DVKdRqhR.d.ts} +7628 -3034
  33. package/dist/index.cjs +9 -9
  34. package/dist/index.cjs.map +1 -1
  35. package/dist/index.d.cts +3 -3
  36. package/dist/index.d.ts +3 -3
  37. package/dist/index.js +3 -3
  38. package/dist/index.js.map +1 -1
  39. package/dist/management.cjs +2 -2
  40. package/dist/management.d.cts +1 -1
  41. package/dist/management.d.ts +1 -1
  42. package/dist/management.js +1 -1
  43. package/dist/testing.cjs +848 -3
  44. package/dist/testing.cjs.map +1 -1
  45. package/dist/testing.d.cts +5 -5
  46. package/dist/testing.d.ts +5 -5
  47. package/dist/testing.js +846 -1
  48. package/dist/testing.js.map +1 -1
  49. package/manifest.json +317 -2
  50. package/package.json +2 -2
  51. package/dist/browser/chunk-4XCQBTYE.cjs.map +0 -1
  52. package/dist/browser/chunk-72WU42RU.js.map +0 -1
  53. package/dist/browser/chunk-CXYODDHM.cjs.map +0 -1
  54. package/dist/browser/chunk-TCVKCN3S.js.map +0 -1
  55. package/dist/chunk-7237IZU3.js.map +0 -1
  56. package/dist/chunk-NB7OGN6R.js.map +0 -1
  57. package/dist/chunk-NSAKFGTJ.cjs.map +0 -1
  58. 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.projects.list({ limit: 50 })) console.log(item);
257
- const page = await flags.projects.list();
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.projects.list().toArray({ maxItems: 500 });
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.changes.retrieve("00000000-0000-0000-0000-000000000000");
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.projects.list({}, { maxRetries: 0, signal: AbortSignal.timeout(5_000) });
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 "config.published":
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: "config.published", created_at: new Date().toISOString(), data: {} } });
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.changes.retrieve(id);
405
+ const obj = await flags.changeRequests.retrieve(id);
368
406
  console.log(obj.lastResponse.requestId);
369
- const { data, response, requestId, rateLimit } = await flags.changes.retrieve(id).withResponse();
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.projects.list();
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}/limits", { params: { path: { workspace_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b" } } });
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