@productcraft/flags 0.4.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.
- package/README.md +35 -0
- package/api.md +5 -16
- package/dist/{chunk-7237IZU3.js → browser/chunk-OOX7EUCT.js} +8 -19
- package/dist/browser/chunk-OOX7EUCT.js.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-CXYODDHM.cjs → chunk-XZK57G7L.cjs} +8 -19
- package/dist/browser/chunk-XZK57G7L.cjs.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 +8 -8
- package/dist/browser/index.js +2 -2
- package/dist/browser/management.cjs +2 -2
- package/dist/browser/management.js +1 -1
- package/dist/browser/testing.cjs +3 -3
- package/dist/browser/testing.cjs.map +1 -1
- package/dist/browser/testing.js +1 -1
- package/dist/browser/testing.js.map +1 -1
- package/dist/{chunk-NB7OGN6R.js → chunk-CGVDMKEE.js} +12 -5
- package/dist/chunk-CGVDMKEE.js.map +1 -0
- package/dist/{chunk-Q3P66XRI.cjs → chunk-L3AOANTB.cjs} +12 -5
- package/dist/chunk-L3AOANTB.cjs.map +1 -0
- package/dist/{chunk-NSAKFGTJ.cjs → chunk-RJIVAOBG.cjs} +8 -19
- package/dist/{browser/chunk-CXYODDHM.cjs.map → chunk-RJIVAOBG.cjs.map} +1 -1
- package/dist/{browser/chunk-TCVKCN3S.js → chunk-XNJ5OX4X.js} +8 -19
- package/dist/{browser/chunk-TCVKCN3S.js.map → chunk-XNJ5OX4X.js.map} +1 -1
- 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-BWi7PASW.d.cts} +94 -33
- package/dist/{client-BwoMpm8_.d.ts → client-BWi7PASW.d.ts} +94 -33
- package/dist/index.cjs +8 -8
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2 -2
- 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 +3 -3
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +3 -3
- package/dist/testing.d.ts +3 -3
- package/dist/testing.js +1 -1
- package/dist/testing.js.map +1 -1
- package/manifest.json +1 -1
- 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/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`.
|
package/api.md
CHANGED
|
@@ -1027,13 +1027,13 @@ const confidentialReveal = await flags.segments.revealConfidential("3f0c3c1e-8a2
|
|
|
1027
1027
|
|
|
1028
1028
|
Update a segment.
|
|
1029
1029
|
|
|
1030
|
-
Key, name, description or conditions; only the fields you send change. Edit a confidential list with `list_id` plus `values_add` / `values_remove`. A segment used in a protected environment also needs `flags.protected.update` there.
|
|
1030
|
+
Key, name, description or conditions; only the fields you send change. To add or remove values in one list condition without re-sending the others, send `condition_edits` (with the `version` you read). Edit a confidential list with `list_id` plus `values_add` / `values_remove`, or with `condition_edits`. A segment used in a protected environment also needs `flags.protected.update` there.
|
|
1031
1031
|
|
|
1032
1032
|
- Params: `Flags.SegmentUpdateParams`
|
|
1033
1033
|
|
|
1034
1034
|
| Status | Error class | Codes | When |
|
|
1035
1035
|
|---|---|---|---|
|
|
1036
|
-
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
|
|
1036
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid, an edit has no values, or both `conditions` and `condition_edits` were sent. |
|
|
1037
1037
|
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
|
|
1038
1038
|
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). A segment used in a protected environment also needs `flags.protected.update` on it. |
|
|
1039
1039
|
| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | `SEGMENT_NOT_FOUND`: no such segment in this workspace. |
|
|
@@ -1043,18 +1043,7 @@ Key, name, description or conditions; only the fields you send change. Edit a co
|
|
|
1043
1043
|
| 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
|
|
1044
1044
|
|
|
1045
1045
|
```ts
|
|
1046
|
-
const segmentDetail = await flags.segments.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
1047
|
-
conditions: [
|
|
1048
|
-
{
|
|
1049
|
-
user: {
|
|
1050
|
-
attribute: "email",
|
|
1051
|
-
comparator: "ends_with_any_hashed",
|
|
1052
|
-
list_id: "3f0c6a3e-0f5e-4b8e-9d1a-2c7b9f1e8a10",
|
|
1053
|
-
values_add: ["@beta.test"],
|
|
1054
|
-
},
|
|
1055
|
-
},
|
|
1056
|
-
],
|
|
1057
|
-
});
|
|
1046
|
+
const segmentDetail = await flags.segments.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { condition_edits: [{ condition_index: 0, values_add: ["qa-bot@example.com"] }] });
|
|
1058
1047
|
```
|
|
1059
1048
|
|
|
1060
1049
|
[HTTP reference](https://productcraft.co/docs/flags/api-reference#patch-v1-workspaces-workspace-id-segments-segment-id)
|
|
@@ -1215,13 +1204,13 @@ const confidentialReveal = await flags.settings.values.revealConfidential("3f0c3
|
|
|
1215
1204
|
|
|
1216
1205
|
Update a value.
|
|
1217
1206
|
|
|
1218
|
-
The quick edits: `value` (the toggle), `percentage_attribute`, and `clear_rules: true` to drop every rule and split so `value` is served to everyone (the kill switch). Send the `version` you read.
|
|
1207
|
+
The quick edits: `value` (the toggle), `percentage_attribute`, `rule_edits` to add or remove values in a list condition of an existing rule (a tester, a QA account) without re-sending the other rules, and `clear_rules: true` to drop every rule and split so `value` is served to everyone (the kill switch). Send the `version` you read. A protected environment needs `flags.protected.update`; one change and one revision per request, none when nothing changed.
|
|
1219
1208
|
|
|
1220
1209
|
- Params: `Flags.SettingsValueUpdateParams`
|
|
1221
1210
|
|
|
1222
1211
|
| Status | Error class | Codes | When |
|
|
1223
1212
|
|---|---|---|---|
|
|
1224
|
-
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: nothing to change,
|
|
1213
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: nothing to change, `version` is missing, an edit has no values, or `rule_edits` sent with `clear_rules`. |
|
|
1225
1214
|
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
|
|
1226
1215
|
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). Value writes need `flags.value.update` on the environment and the setting, plus `flags.protected.update` in a protected environment. |
|
|
1227
1216
|
| 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
|
|
@@ -1038,12 +1038,12 @@ var SegmentsResource = class extends APIResource {
|
|
|
1038
1038
|
/**
|
|
1039
1039
|
* Update a segment
|
|
1040
1040
|
*
|
|
1041
|
-
* Key, name, description or conditions; only the fields you send change. Edit a confidential list with `list_id` plus `values_add` / `values_remove`. A segment used in a protected environment also needs `flags.protected.update` there.
|
|
1041
|
+
* Key, name, description or conditions; only the fields you send change. To add or remove values in one list condition without re-sending the others, send `condition_edits` (with the `version` you read). Edit a confidential list with `list_id` plus `values_add` / `values_remove`, or with `condition_edits`. A segment used in a protected environment also needs `flags.protected.update` there.
|
|
1042
1042
|
*
|
|
1043
1043
|
* @param segmentId - Id of the segment.
|
|
1044
1044
|
* @param params - `Flags.SegmentUpdateParams`.
|
|
1045
1045
|
* @param options - Per-request options.
|
|
1046
|
-
* @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: a field is invalid.
|
|
1046
|
+
* @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: a field is invalid, an edit has no values, or both `conditions` and `condition_edits` were sent.
|
|
1047
1047
|
* @throws {AuthenticationError} 401 UNAUTHORIZED: Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`.
|
|
1048
1048
|
* @throws {PermissionDeniedError} 403 FORBIDDEN, SERVICE_NOT_ENABLED: The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). A segment used in a protected environment also needs `flags.protected.update` on it.
|
|
1049
1049
|
* @throws {NotFoundError} 404 NOT_FOUND, SEGMENT_NOT_FOUND: `SEGMENT_NOT_FOUND`: no such segment in this workspace.
|
|
@@ -1055,18 +1055,7 @@ var SegmentsResource = class extends APIResource {
|
|
|
1055
1055
|
* @see https://productcraft.co/docs/flags/api-reference#patch-v1-workspaces-workspace-id-segments-segment-id
|
|
1056
1056
|
* @example
|
|
1057
1057
|
* ```ts
|
|
1058
|
-
* const segmentDetail = await flags.segments.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
1059
|
-
* conditions: [
|
|
1060
|
-
* {
|
|
1061
|
-
* user: {
|
|
1062
|
-
* attribute: "email",
|
|
1063
|
-
* comparator: "ends_with_any_hashed",
|
|
1064
|
-
* list_id: "3f0c6a3e-0f5e-4b8e-9d1a-2c7b9f1e8a10",
|
|
1065
|
-
* values_add: ["@beta.test"],
|
|
1066
|
-
* },
|
|
1067
|
-
* },
|
|
1068
|
-
* ],
|
|
1069
|
-
* });
|
|
1058
|
+
* const segmentDetail = await flags.segments.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { condition_edits: [{ condition_index: 0, values_add: ["qa-bot@example.com"] }] });
|
|
1070
1059
|
* ```
|
|
1071
1060
|
*/
|
|
1072
1061
|
update(segmentId, params, options) {
|
|
@@ -1151,13 +1140,13 @@ var SettingsValuesResource = class extends APIResource {
|
|
|
1151
1140
|
/**
|
|
1152
1141
|
* Update a value
|
|
1153
1142
|
*
|
|
1154
|
-
* The quick edits: `value` (the toggle), `percentage_attribute`, and `clear_rules: true` to drop every rule and split so `value` is served to everyone (the kill switch). Send the `version` you read.
|
|
1143
|
+
* The quick edits: `value` (the toggle), `percentage_attribute`, `rule_edits` to add or remove values in a list condition of an existing rule (a tester, a QA account) without re-sending the other rules, and `clear_rules: true` to drop every rule and split so `value` is served to everyone (the kill switch). Send the `version` you read. A protected environment needs `flags.protected.update`; one change and one revision per request, none when nothing changed.
|
|
1155
1144
|
*
|
|
1156
1145
|
* @param settingId - Id of the setting.
|
|
1157
1146
|
* @param environmentId - Id of an environment of the same project.
|
|
1158
1147
|
* @param params - `Flags.SettingsValueUpdateParams`.
|
|
1159
1148
|
* @param options - Per-request options.
|
|
1160
|
-
* @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: nothing to change,
|
|
1149
|
+
* @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: nothing to change, `version` is missing, an edit has no values, or `rule_edits` sent with `clear_rules`.
|
|
1161
1150
|
* @throws {AuthenticationError} 401 UNAUTHORIZED: Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`.
|
|
1162
1151
|
* @throws {PermissionDeniedError} 403 FORBIDDEN, SERVICE_NOT_ENABLED: The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). Value writes need `flags.value.update` on the environment and the setting, plus `flags.protected.update` in a protected environment.
|
|
1163
1152
|
* @throws {NotFoundError} 404 NOT_FOUND, SETTING_NOT_FOUND, ENVIRONMENT_NOT_FOUND: `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`.
|
|
@@ -1644,7 +1633,7 @@ var WebhookEventStatus = { values: ["pending", "delivered", "failed", "not_sent"
|
|
|
1644
1633
|
var WebhookEventType = { values: ["config.published", "sdk_key.rotated"] };
|
|
1645
1634
|
|
|
1646
1635
|
// src/_generated/client.ts
|
|
1647
|
-
var VERSION = "0.
|
|
1636
|
+
var VERSION = "0.5.0" ;
|
|
1648
1637
|
var Flags = class extends FlagsResources {
|
|
1649
1638
|
constructor(options = {}) {
|
|
1650
1639
|
super(new APIClient(options, PC_BASE_URL.flags, { name: "flags", version: VERSION }));
|
|
@@ -1683,5 +1672,5 @@ var Flags = class extends FlagsResources {
|
|
|
1683
1672
|
})(Flags || (Flags = {}));
|
|
1684
1673
|
|
|
1685
1674
|
export { Flags };
|
|
1686
|
-
//# sourceMappingURL=chunk-
|
|
1687
|
-
//# sourceMappingURL=chunk-
|
|
1675
|
+
//# sourceMappingURL=chunk-OOX7EUCT.js.map
|
|
1676
|
+
//# sourceMappingURL=chunk-OOX7EUCT.js.map
|