@productcraft/flags 0.3.0 → 0.5.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 (54) hide show
  1. package/README.md +35 -0
  2. package/api.md +110 -18
  3. package/dist/browser/{chunk-4LRAE3F3.js → chunk-OOX7EUCT.js} +114 -22
  4. package/dist/browser/chunk-OOX7EUCT.js.map +1 -0
  5. package/dist/browser/{chunk-72WU42RU.js → chunk-WUZAG2E3.js} +11 -4
  6. package/dist/browser/chunk-WUZAG2E3.js.map +1 -0
  7. package/dist/browser/{chunk-FXZVXQ75.cjs → chunk-XZK57G7L.cjs} +114 -22
  8. package/dist/browser/chunk-XZK57G7L.cjs.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 +8 -8
  12. package/dist/browser/index.js +2 -2
  13. package/dist/browser/management.cjs +2 -2
  14. package/dist/browser/management.js +1 -1
  15. package/dist/browser/testing.cjs +3 -3
  16. package/dist/browser/testing.cjs.map +1 -1
  17. package/dist/browser/testing.js +1 -1
  18. package/dist/browser/testing.js.map +1 -1
  19. package/dist/{chunk-TSRLPHJ5.js → chunk-CGVDMKEE.js} +12 -5
  20. package/dist/chunk-CGVDMKEE.js.map +1 -0
  21. package/dist/{chunk-QTDMUNLG.cjs → chunk-L3AOANTB.cjs} +12 -5
  22. package/dist/chunk-L3AOANTB.cjs.map +1 -0
  23. package/dist/{chunk-WI4EZXOV.cjs → chunk-RJIVAOBG.cjs} +114 -22
  24. package/dist/chunk-RJIVAOBG.cjs.map +1 -0
  25. package/dist/{chunk-2YRDLKNB.js → chunk-XNJ5OX4X.js} +114 -22
  26. package/dist/chunk-XNJ5OX4X.js.map +1 -0
  27. package/dist/{client-K2zALPGD.d.cts → client-BBiIKiGW.d.cts} +18 -14
  28. package/dist/{client-K2zALPGD.d.ts → client-BBiIKiGW.d.ts} +18 -14
  29. package/dist/{client-bVEJfS6_.d.cts → client-BWi7PASW.d.cts} +1091 -45
  30. package/dist/{client-bVEJfS6_.d.ts → client-BWi7PASW.d.ts} +1091 -45
  31. package/dist/index.cjs +8 -8
  32. package/dist/index.d.cts +3 -3
  33. package/dist/index.d.ts +3 -3
  34. package/dist/index.js +2 -2
  35. package/dist/management.cjs +2 -2
  36. package/dist/management.d.cts +1 -1
  37. package/dist/management.d.ts +1 -1
  38. package/dist/management.js +1 -1
  39. package/dist/testing.cjs +3 -3
  40. package/dist/testing.cjs.map +1 -1
  41. package/dist/testing.d.cts +3 -3
  42. package/dist/testing.d.ts +3 -3
  43. package/dist/testing.js +1 -1
  44. package/dist/testing.js.map +1 -1
  45. package/manifest.json +1 -1
  46. package/package.json +2 -2
  47. package/dist/browser/chunk-4LRAE3F3.js.map +0 -1
  48. package/dist/browser/chunk-4XCQBTYE.cjs.map +0 -1
  49. package/dist/browser/chunk-72WU42RU.js.map +0 -1
  50. package/dist/browser/chunk-FXZVXQ75.cjs.map +0 -1
  51. package/dist/chunk-2YRDLKNB.js.map +0 -1
  52. package/dist/chunk-QTDMUNLG.cjs.map +0 -1
  53. package/dist/chunk-TSRLPHJ5.js.map +0 -1
  54. package/dist/chunk-WI4EZXOV.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`.