@fireweaveai/server-sdk 2.2.1-staging.1
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 +263 -0
- package/dist/application/client.d.ts +92 -0
- package/dist/application/client.d.ts.map +1 -0
- package/dist/application/client.js +156 -0
- package/dist/application/client.js.map +1 -0
- package/dist/application/mode.d.ts +71 -0
- package/dist/application/mode.d.ts.map +1 -0
- package/dist/application/mode.js +72 -0
- package/dist/application/mode.js.map +1 -0
- package/dist/application/ports.d.ts +95 -0
- package/dist/application/ports.d.ts.map +1 -0
- package/dist/application/ports.js +2 -0
- package/dist/application/ports.js.map +1 -0
- package/dist/application/runtime.d.ts +102 -0
- package/dist/application/runtime.d.ts.map +1 -0
- package/dist/application/runtime.js +342 -0
- package/dist/application/runtime.js.map +1 -0
- package/dist/domain/context.d.ts +68 -0
- package/dist/domain/context.d.ts.map +1 -0
- package/dist/domain/context.js +85 -0
- package/dist/domain/context.js.map +1 -0
- package/dist/domain/errors.d.ts +43 -0
- package/dist/domain/errors.d.ts.map +1 -0
- package/dist/domain/errors.js +64 -0
- package/dist/domain/errors.js.map +1 -0
- package/dist/domain/target.d.ts +3 -0
- package/dist/domain/target.d.ts.map +1 -0
- package/dist/domain/target.js +2 -0
- package/dist/domain/target.js.map +1 -0
- package/dist/domain/types.d.ts +108 -0
- package/dist/domain/types.d.ts.map +1 -0
- package/dist/domain/types.js +2 -0
- package/dist/domain/types.js.map +1 -0
- package/dist/domain/validation.d.ts +125 -0
- package/dist/domain/validation.d.ts.map +1 -0
- package/dist/domain/validation.js +347 -0
- package/dist/domain/validation.js.map +1 -0
- package/dist/index.d.ts +35 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +23 -0
- package/dist/index.js.map +1 -0
- package/dist/infrastructure/adapters/inmemory.d.ts +78 -0
- package/dist/infrastructure/adapters/inmemory.d.ts.map +1 -0
- package/dist/infrastructure/adapters/inmemory.js +148 -0
- package/dist/infrastructure/adapters/inmemory.js.map +1 -0
- package/dist/infrastructure/adapters/local.d.ts +109 -0
- package/dist/infrastructure/adapters/local.d.ts.map +1 -0
- package/dist/infrastructure/adapters/local.js +102 -0
- package/dist/infrastructure/adapters/local.js.map +1 -0
- package/dist/infrastructure/adapters/remote.d.ts +75 -0
- package/dist/infrastructure/adapters/remote.d.ts.map +1 -0
- package/dist/infrastructure/adapters/remote.js +361 -0
- package/dist/infrastructure/adapters/remote.js.map +1 -0
- package/dist/infrastructure/hosts.d.ts +19 -0
- package/dist/infrastructure/hosts.d.ts.map +1 -0
- package/dist/infrastructure/hosts.js +68 -0
- package/dist/infrastructure/hosts.js.map +1 -0
- package/package.json +56 -0
package/README.md
ADDED
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
# @fireweaveai/server-sdk (Node SDK)
|
|
2
|
+
|
|
3
|
+
Fireweave release-engineering SDK for server runtimes — **control points** and **target
|
|
4
|
+
registration**, the two v1 capabilities ([spec/control-points.md](../../spec/control-points.md)
|
|
5
|
+
"Scope of v1"; spec v0.1.0).
|
|
6
|
+
|
|
7
|
+
- **Zero runtime dependencies.**
|
|
8
|
+
- **Runs on Node ≥ 20.20, Bun ≥ 1.2, and Deno ≥ 2.0** — no Node built-ins, no Node globals ([ADR-0008](../../docs/adr/0008-multi-runtime-support.md)).
|
|
9
|
+
- **No vendor SDK, key, or hostname in your process.** Applications hold a Fireweave project key and talk to fw-server; which backend fw-server forwards to is fw-server's concern ([ADR-0005](../../docs/adr/0005-fireweave-proxy-backend.md), [ADR-0006](../../docs/adr/0006-node-drops-direct-posthog-adapter.md)).
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @fireweaveai/server-sdk # or: bun add …
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
// Deno needs no install step
|
|
19
|
+
import { initFireweave } from 'npm:@fireweaveai/server-sdk';
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Quick start (production path)
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { initFireweave } from '@fireweaveai/server-sdk';
|
|
26
|
+
|
|
27
|
+
// apiUrl/apiKey are required, explicit options — the SDK reads no
|
|
28
|
+
// environment variables (spec/modes.md).
|
|
29
|
+
const fireweave = await initFireweave({
|
|
30
|
+
mode: 'remote',
|
|
31
|
+
apiUrl: process.env.FW_API_URL!,
|
|
32
|
+
apiKey: process.env.FW_PROJECT_API_KEY!,
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
// Once per login: the durable facts your targeting rules match on.
|
|
36
|
+
await fireweave.registerTarget('user_42', {
|
|
37
|
+
kind: 'user',
|
|
38
|
+
properties: { plan: 'pro', region: 'eu-west' },
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
// Per request.
|
|
42
|
+
const enabled = await fireweave.controlPoints.getBooleanValue('new-checkout', false, {
|
|
43
|
+
targetingKey: 'user_42',
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
await fireweave.shutdown(); // flushes queued network I/O first
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Quick start (offline, local mode)
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
import { initFireweave } from '@fireweaveai/server-sdk';
|
|
53
|
+
|
|
54
|
+
const fireweave = await initFireweave({
|
|
55
|
+
mode: 'local',
|
|
56
|
+
local: { controlPoints: { 'new-checkout': true } },
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
// → true
|
|
60
|
+
await fireweave.controlPoints.getBooleanValue('new-checkout', false, { targetingKey: 'u1' });
|
|
61
|
+
|
|
62
|
+
await fireweave.shutdown();
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`initFireweave` is the single entry point (`spec/modes.md`): `mode` is required and never
|
|
66
|
+
inferred, so a missing or mistyped credential fails loudly at boot instead of silently falling
|
|
67
|
+
back to local evaluation. Reads on the returned client never throw — every failure resolves to
|
|
68
|
+
the caller's `default` with a `Decision` naming the reason (`spec/control-points.md` "Return
|
|
69
|
+
discipline").
|
|
70
|
+
|
|
71
|
+
## Lower-level construction
|
|
72
|
+
|
|
73
|
+
`initFireweave` is a thin composition root over exported pieces — construct them directly for a
|
|
74
|
+
custom adapter or advanced wiring:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import { FireweaveClient, FireweaveRemoteAdapter, FireweaveRuntime } from '@fireweaveai/server-sdk';
|
|
78
|
+
|
|
79
|
+
const runtime = new FireweaveRuntime(new FireweaveRemoteAdapter({ apiUrl, apiKey }));
|
|
80
|
+
const fireweave = new FireweaveClient(runtime);
|
|
81
|
+
await fireweave.initialize();
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The per-call parameter is `flagKey`, not `controlPointKey` — that name is fixed by
|
|
85
|
+
`spec/decision.schema.json` and the wire protocol shared with the Python, Go, and Java SDKs.
|
|
86
|
+
"Control point" is the product noun; `flagKey` is its key at those boundaries
|
|
87
|
+
([ADR-0007](../../docs/adr/0007-control-point-vocabulary.md)).
|
|
88
|
+
|
|
89
|
+
## Module layout
|
|
90
|
+
|
|
91
|
+
| Module | Responsibility |
|
|
92
|
+
| --- | --- |
|
|
93
|
+
| `application/runtime.ts` | Lifecycle state machine, config validation, context policy, decision construction. Evaluation never throws. |
|
|
94
|
+
| `application/client.ts` | `FireweaveClient` — `controlPoints`, `registerTarget`. |
|
|
95
|
+
| `application/mode.ts` | `initFireweave` — the single entry point; the only module allowed to import concrete adapters. |
|
|
96
|
+
| `infrastructure/adapters/remote.ts` | `FireweaveRemoteAdapter` — the production backend (`/v1/flags/evaluate`, `/v1/targets/register`). |
|
|
97
|
+
| `infrastructure/adapters/inmemory.ts` | Deterministic fixture-driven adapter for tests and conformance. |
|
|
98
|
+
| `infrastructure/adapters/local.ts` | `FireweaveLocalAdapter` — the DEV substrate `initFireweave({ mode: 'local' })` builds. |
|
|
99
|
+
| `application/ports.ts` | The `BackendAdapter` boundary. |
|
|
100
|
+
| `domain/context.ts` | Merge order (global → client → invocation), deep copy, bounds, reserved keys. |
|
|
101
|
+
| `domain/errors.ts` | The 15-kind error taxonomy and secret redaction. |
|
|
102
|
+
| `infrastructure/hosts.ts` | SSRF allowlist (on by default; https required off-loopback). |
|
|
103
|
+
|
|
104
|
+
## Configuration
|
|
105
|
+
|
|
106
|
+
The SDK reads no environment variables (spec/modes.md) — every option is an explicit argument to
|
|
107
|
+
`initFireweave` (or the adapter constructor, for lower-level use).
|
|
108
|
+
|
|
109
|
+
| Option | Mode | Description |
|
|
110
|
+
| --- | --- | --- |
|
|
111
|
+
| `apiUrl` | `remote` | fw-server base URL (required) |
|
|
112
|
+
| `apiKey` | `remote` | Fireweave project key (`project-api-key_…`) (required) |
|
|
113
|
+
| `allowedHosts` | `remote` | SSRF allowlist override; defaults to the `apiUrl` host plus loopback |
|
|
114
|
+
| `local.controlPoints` | `local` | seeded boolean overrides; a present key resolves `STATIC`, an absent key misses to the caller's default with reason `DEFAULT` |
|
|
115
|
+
|
|
116
|
+
## Upgrading from v2.0 to 2.1
|
|
117
|
+
|
|
118
|
+
**Only one change is mandatory.** If you imported the direct vendor adapter, swap it. Everything else from v2 still works, so most of this section exists to tell you what you *don't* have to do.
|
|
119
|
+
|
|
120
|
+
### Does this affect me?
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
# Mandatory to fix (any hit ⇒ migration required)
|
|
124
|
+
rg -n "@fireweaveai/server-sdk/posthog|PostHogAdapter"
|
|
125
|
+
rg -n '"posthog-node"' package.json
|
|
126
|
+
|
|
127
|
+
# Configuration that moves
|
|
128
|
+
rg -n "POSTHOG_HOST|POSTHOG_API_KEY|POSTHOG_PROJECT_API_KEY"
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
No hits? Bump the version; you are done.
|
|
132
|
+
|
|
133
|
+
### 1. Swap the adapter (required)
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
// before
|
|
137
|
+
import { PostHogAdapter } from '@fireweaveai/server-sdk/posthog';
|
|
138
|
+
const adapter = new PostHogAdapter({
|
|
139
|
+
projectApiKey: process.env.POSTHOG_API_KEY,
|
|
140
|
+
host: process.env.POSTHOG_HOST,
|
|
141
|
+
featureFlagsRequestTimeoutMs: 3000,
|
|
142
|
+
});
|
|
143
|
+
|
|
144
|
+
// after
|
|
145
|
+
import { initFireweave } from '@fireweaveai/server-sdk';
|
|
146
|
+
const fireweave = await initFireweave({
|
|
147
|
+
mode: 'remote',
|
|
148
|
+
apiUrl: process.env.FW_API_URL!,
|
|
149
|
+
apiKey: process.env.FW_PROJECT_API_KEY!,
|
|
150
|
+
});
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
| v2 option | 2.1 |
|
|
154
|
+
| --- | --- |
|
|
155
|
+
| `projectApiKey` (`phc_…`) | `apiKey` (`project-api-key_…`) |
|
|
156
|
+
| `host` | `apiUrl` |
|
|
157
|
+
| `featureFlagsRequestTimeoutMs` | `requestTimeoutMs` (adapter-level; `initFireweave` does not expose it directly — use *Lower-level construction* above if you need it) |
|
|
158
|
+
| `shutdownTimeoutMs`, `allowedHosts` | unchanged |
|
|
159
|
+
| `secretApiKey`, `onlyEvaluateLocally`, `featureFlagsPollingInterval`, `waitForLocalDefinitions`, `client` | **no equivalent** — see §4 |
|
|
160
|
+
|
|
161
|
+
Then:
|
|
162
|
+
|
|
163
|
+
- Remove `posthog-node` from `package.json` — **unless** you use it for your own analytics capture. Check with `rg "posthog-node"` first.
|
|
164
|
+
- Update deployment config, secret stores, and CI: `POSTHOG_HOST` → `FW_API_URL`, `POSTHOG_API_KEY` → `FW_PROJECT_API_KEY`. **The new key is a Fireweave project key, not a re-labelled vendor key** — it has to be issued from your Fireweave project.
|
|
165
|
+
|
|
166
|
+
### 2. What you do *not* have to change
|
|
167
|
+
|
|
168
|
+
| v2 | Status in 2.1 |
|
|
169
|
+
| --- | --- |
|
|
170
|
+
| `client.flags.evaluate` / `getBooleanValue` / … | works — the same object as `client.controlPoints` |
|
|
171
|
+
| `new InMemoryAdapter({ flags })` | unchanged |
|
|
172
|
+
| `Decision.flagKey`, `flagMetadata` | unchanged |
|
|
173
|
+
| `FlagValueType`, `InMemoryFlagDefinition`, `ExpectedFlagType` | unchanged |
|
|
174
|
+
| every other v2 export | unchanged |
|
|
175
|
+
|
|
176
|
+
`client.flags === client.controlPoints` — a getter returning the same instance, not a copy. It is
|
|
177
|
+
marked `@deprecated` in JSDoc and **is not scheduled for removal in the 2.x line**; retiring it
|
|
178
|
+
would need its own major and its own ADR. Renaming your call sites is cosmetic and can be
|
|
179
|
+
deferred indefinitely. Accessing `client.flags` is silent at runtime — no log line, no env gate —
|
|
180
|
+
because the SDK reads no environment variables regardless (spec/modes.md); the deprecation is
|
|
181
|
+
conveyed by JSDoc only.
|
|
182
|
+
|
|
183
|
+
### 3. Two type-level narrowings
|
|
184
|
+
|
|
185
|
+
`'posthog'` is no longer a member of `BackendAdapter['name']` or `Capabilities['runtime']['backend']`.
|
|
186
|
+
|
|
187
|
+
- A custom adapter declaring `name: 'posthog'` → use `'other'`.
|
|
188
|
+
- An exhaustive `switch` on `backend` with a `case 'posthog'` → that arm is unreachable; remove it.
|
|
189
|
+
|
|
190
|
+
Both are rare, and `tsc` points straight at them.
|
|
191
|
+
|
|
192
|
+
### 4. Local evaluation is gone
|
|
193
|
+
|
|
194
|
+
v2's vendor adapter could evaluate in-process from polled definitions with a secret key. 2.1 has no equivalent: caching is fw-server's concern, and both shipped adapters report `localEvaluation: false`.
|
|
195
|
+
|
|
196
|
+
If in-process evaluation is load-bearing for you — an air-gapped service, or a latency floor below one network hop — **stay on v2 for now and tell us**. The interface seam (`AdapterRuntimeFeatures.localEvaluation` / `localOnly`, `AdapterResolution.fromCache`, the `STALE` reason) is deliberately preserved for a future Fireweave-native cache ([ADR-0006](../../docs/adr/0006-node-drops-direct-posthog-adapter.md)).
|
|
197
|
+
|
|
198
|
+
### 5. Worth re-checking
|
|
199
|
+
|
|
200
|
+
1. **`DEFAULT_ALLOWED_HOSTS` changed contents** while keeping its name. It now lists Fireweave hosts, not vendor hosts. Code doing `allowedHosts: [...DEFAULT_ALLOWED_HOSTS, 'mine.example']` keeps compiling and silently stops permitting the old endpoints. That is intended — verify it matches your deployment.
|
|
201
|
+
2. **Move durable attributes to `registerTarget`.** Attributes you resend on every evaluation can be registered once per login. Per-request attributes still override stored properties, so the two compose — this is an optimization, not a cutover. Note that `registerTarget` returns `{ ok }` rather than throwing (it sits in sign-in paths); log `ok: false`, because a silently unregistered target is exactly how targeting rules end up matching nobody.
|
|
202
|
+
|
|
203
|
+
### 6. Verify
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
npm install @fireweaveai/server-sdk@latest
|
|
207
|
+
npx tsc --noEmit # catches §3
|
|
208
|
+
<your test command>
|
|
209
|
+
rg -n "@fireweaveai/server-sdk/posthog|PostHogAdapter" # expect no hits
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
At runtime, a boolean read against a known-on control point should resolve `true` with reason
|
|
213
|
+
`TARGETING_MATCH`/`SPLIT`/`STATIC` (never `ERROR`); if it resolves the default with reason
|
|
214
|
+
`ERROR`, the remote adapter was never wired in correctly — check `apiUrl`/`apiKey`.
|
|
215
|
+
|
|
216
|
+
### Rollback
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
npm install @fireweaveai/server-sdk@2 # re-add posthog-node if you removed it
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Revert the adapter swap and the env vars. No data migration is involved, so rollback is code and config only.
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Renaming `flags` → `controlPoints` safely
|
|
227
|
+
|
|
228
|
+
If you do decide to adopt the new name, scope the edit. `flags` is an ordinary word: your repo very likely contains feature-flag code, config keys, DB columns, and `flags` variables that have nothing to do with this SDK.
|
|
229
|
+
|
|
230
|
+
**Rename only `.flags` accesses whose receiver is provably a `FireweaveClient`** — traceable to a `new FireweaveClient(...)`/`initFireweave(...)` call, an imported binding assigned from one, or a parameter annotated `FireweaveClient`.
|
|
231
|
+
|
|
232
|
+
Never rename:
|
|
233
|
+
|
|
234
|
+
| Looks similar | Why it stays |
|
|
235
|
+
| --- | --- |
|
|
236
|
+
| `new InMemoryAdapter({ flags: … })` | SDK option key, unchanged |
|
|
237
|
+
| `flagKey`, `flagMetadata`, `FlagValueType`, `InMemoryFlagDefinition` | SDK API, unchanged |
|
|
238
|
+
| `features.flags` in the capability matrix | still `true`; removing it fails conformance |
|
|
239
|
+
| your own `flags` variables, `featureFlags`, CLI `--flags`, `flags` columns | not this SDK |
|
|
240
|
+
| another vendor's SDK (`ldClient.variation`, flagd, Unleash) | not this SDK |
|
|
241
|
+
|
|
242
|
+
**Do not run a repo-wide `flags` → `controlPoints` replacement** — not with `sed`, not with editor replace-all. Go call site by call site, and when a receiver is ambiguous, leave it. A missed cosmetic rename costs nothing; a wrong one breaks unrelated code.
|
|
243
|
+
|
|
244
|
+
## Development
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
npm install # from sdks/node
|
|
248
|
+
npm run build # emit dist/ (package exports resolve to it)
|
|
249
|
+
npm run verify # typecheck + unit + integration + conformance + smoke
|
|
250
|
+
npm run smoke # cross-runtime smoke (Node leg)
|
|
251
|
+
|
|
252
|
+
bun test test/unit test/integration
|
|
253
|
+
bun scripts/smoke-runtimes.mjs
|
|
254
|
+
deno run --allow-read scripts/smoke-runtimes.mjs
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
## Documentation
|
|
258
|
+
|
|
259
|
+
Full docs live in [`docs/`](../../docs/): [quickstart](../../docs/quickstart.md) · [remote adapter](../../docs/remote.md) · [runtimes](../../docs/runtimes.md) · [testing](../../docs/testing.md) · [migration](../../docs/migration.md) · [troubleshooting](../../docs/troubleshooting.md) · [ADRs](../../docs/adr/).
|
|
260
|
+
|
|
261
|
+
## License
|
|
262
|
+
|
|
263
|
+
[MIT](../../LICENSE).
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* FireweaveClient — control-point evaluation and target registration
|
|
3
|
+
* (spec/control-points.md): the only two v1 capabilities. Facade methods
|
|
4
|
+
* degrade instead of throwing.
|
|
5
|
+
*/
|
|
6
|
+
import { type FireweaveErrorKind } from '../domain/errors.js';
|
|
7
|
+
import type { EvaluateOptions, ExpectedFlagType, FireweaveRuntime } from './runtime.js';
|
|
8
|
+
import type { ContextInput } from '../domain/context.js';
|
|
9
|
+
import type { RegisterTargetOptions, RegisterTargetResult } from './ports.js';
|
|
10
|
+
import type { Decision, JsonValue } from '../domain/types.js';
|
|
11
|
+
export interface ExtensionResult {
|
|
12
|
+
ok: boolean;
|
|
13
|
+
errorKind?: FireweaveErrorKind;
|
|
14
|
+
errorCode?: string;
|
|
15
|
+
errorMessage?: string;
|
|
16
|
+
degraded?: boolean;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Control-point evaluation on the public client surface (ruling 16):
|
|
20
|
+
* Decision-returning evaluation without reaching into the runtime. Never throws
|
|
21
|
+
* — errors surface as ERROR decisions, exactly like the OpenFeature path.
|
|
22
|
+
*
|
|
23
|
+
* "Control point" is the Fireweave product noun (ADR-0007). The per-call
|
|
24
|
+
* parameter stays `flagKey`, because that is the name fixed by the OpenFeature
|
|
25
|
+
* spec, by `spec/decision.schema.json`, and by the `/v1/flags/evaluate` wire
|
|
26
|
+
* contract shared with the Python, Go, and Java SDKs.
|
|
27
|
+
*/
|
|
28
|
+
export declare class ControlPointsApi {
|
|
29
|
+
private readonly runtime;
|
|
30
|
+
constructor(runtime: FireweaveRuntime);
|
|
31
|
+
/** Evaluate a flag to a canonical Decision (detailed evaluation). */
|
|
32
|
+
evaluate(flagKey: string, expectedType: ExpectedFlagType, defaultValue: JsonValue, context?: ContextInput, options?: EvaluateOptions): Promise<Decision>;
|
|
33
|
+
getBooleanValue(flagKey: string, defaultValue: boolean, context?: ContextInput): Promise<boolean>;
|
|
34
|
+
getStringValue(flagKey: string, defaultValue: string, context?: ContextInput): Promise<string>;
|
|
35
|
+
getNumberValue(flagKey: string, defaultValue: number, context?: ContextInput): Promise<number>;
|
|
36
|
+
getObjectValue(flagKey: string, defaultValue: JsonValue, context?: ContextInput): Promise<JsonValue>;
|
|
37
|
+
/**
|
|
38
|
+
* Detailed reads — the whole {@link Decision} rather than just its value.
|
|
39
|
+
*
|
|
40
|
+
* Same arguments as the `*Value` pair above, so a caller upgrades from one to
|
|
41
|
+
* the other without restructuring the call. Required by
|
|
42
|
+
* `spec/control-points.md`; before ADR-0010 the only route to `reason`,
|
|
43
|
+
* `variant` or `error` was the OpenFeature provider's `resolve*Evaluation`,
|
|
44
|
+
* so detailed evaluation was unreachable without installing OpenFeature.
|
|
45
|
+
*/
|
|
46
|
+
getBooleanDetails(flagKey: string, defaultValue: boolean, context?: ContextInput): Promise<Decision>;
|
|
47
|
+
getStringDetails(flagKey: string, defaultValue: string, context?: ContextInput): Promise<Decision>;
|
|
48
|
+
getNumberDetails(flagKey: string, defaultValue: number, context?: ContextInput): Promise<Decision>;
|
|
49
|
+
getObjectDetails(flagKey: string, defaultValue: JsonValue, context?: ContextInput): Promise<Decision>;
|
|
50
|
+
}
|
|
51
|
+
export interface FireweaveClientOptions {
|
|
52
|
+
}
|
|
53
|
+
export declare class FireweaveClient {
|
|
54
|
+
readonly runtime: FireweaveRuntime;
|
|
55
|
+
readonly controlPoints: ControlPointsApi;
|
|
56
|
+
/**
|
|
57
|
+
* Control-point evaluation under its former name.
|
|
58
|
+
*
|
|
59
|
+
* @deprecated Renamed to {@link FireweaveClient.controlPoints} (ADR-0007).
|
|
60
|
+
* Identical and fully supported — `client.flags === client.controlPoints`, so
|
|
61
|
+
* no migration is required and none is planned. Silent at runtime: the alias
|
|
62
|
+
* is permanent, not scheduled for removal, so there is nothing to warn a
|
|
63
|
+
* caller toward — deprecation is conveyed by this doc comment only (no log,
|
|
64
|
+
* and no env gate to control one, since the SDK reads no environment
|
|
65
|
+
* variables regardless — spec/modes.md).
|
|
66
|
+
*/
|
|
67
|
+
get flags(): ControlPointsApi;
|
|
68
|
+
constructor(runtime: FireweaveRuntime, _options?: FireweaveClientOptions);
|
|
69
|
+
/**
|
|
70
|
+
* Register durable targeting facts for a target (spec/modes.md).
|
|
71
|
+
*
|
|
72
|
+
* Resolves `{ ok: false }` rather than throwing: this runs in sign-in paths,
|
|
73
|
+
* where a targeting concern must not break authentication. A careful caller
|
|
74
|
+
* logs a false — a silently unregistered target is how targeting rules end
|
|
75
|
+
* up matching nobody.
|
|
76
|
+
*
|
|
77
|
+
* In local mode this records in-process and traces the call; nothing reaches
|
|
78
|
+
* fw-server. See `FireweaveLocalAdapter.registerTarget`.
|
|
79
|
+
*/
|
|
80
|
+
registerTarget(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
|
|
81
|
+
/**
|
|
82
|
+
* Dynamic capability dispatch. Unknown capabilities — currently all of
|
|
83
|
+
* them, v1's SUPPORTED_CAPABILITIES is empty — degrade with
|
|
84
|
+
* UnsupportedCapability, never throw (fixture
|
|
85
|
+
* ext-unsupported-capability-degrade). Any future capability listed in
|
|
86
|
+
* SUPPORTED_CAPABILITIES is lifecycle-gated the same way (ruling 17).
|
|
87
|
+
*/
|
|
88
|
+
invokeCapability(capability: string, _args?: Record<string, JsonValue>): ExtensionResult;
|
|
89
|
+
initialize(signal?: AbortSignal): Promise<void>;
|
|
90
|
+
shutdown(): Promise<void>;
|
|
91
|
+
}
|
|
92
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/application/client.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* FireweaveClient — control-point evaluation and target registration
|
|
3
|
+
* (spec/control-points.md): the only two v1 capabilities. Facade methods
|
|
4
|
+
* degrade instead of throwing.
|
|
5
|
+
*/
|
|
6
|
+
import { FireweaveError } from '../domain/errors.js';
|
|
7
|
+
const failure = (err, degraded = false) => ({
|
|
8
|
+
ok: false,
|
|
9
|
+
errorKind: err.kind,
|
|
10
|
+
errorCode: err.openFeatureErrorCode,
|
|
11
|
+
errorMessage: err.message,
|
|
12
|
+
...(degraded ? { degraded: true } : {}),
|
|
13
|
+
});
|
|
14
|
+
/**
|
|
15
|
+
* Lifecycle gate for extension calls (ruling 17, Go/Java model; fixture
|
|
16
|
+
* ext-lifecycle-gating): READY/STALE proceed; post-shutdown degrades
|
|
17
|
+
* AlreadyClosed; pre-ready degrades UnsupportedCapability. Gated methods never
|
|
18
|
+
* throw — failures come back as structured, degraded results.
|
|
19
|
+
*/
|
|
20
|
+
const lifecycleGate = (runtime) => {
|
|
21
|
+
switch (runtime.getState()) {
|
|
22
|
+
case 'READY':
|
|
23
|
+
case 'STALE':
|
|
24
|
+
return undefined;
|
|
25
|
+
case 'SHUTDOWN':
|
|
26
|
+
return new FireweaveError('AlreadyClosed');
|
|
27
|
+
default:
|
|
28
|
+
return new FireweaveError('UnsupportedCapability');
|
|
29
|
+
}
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* Control-point evaluation on the public client surface (ruling 16):
|
|
33
|
+
* Decision-returning evaluation without reaching into the runtime. Never throws
|
|
34
|
+
* — errors surface as ERROR decisions, exactly like the OpenFeature path.
|
|
35
|
+
*
|
|
36
|
+
* "Control point" is the Fireweave product noun (ADR-0007). The per-call
|
|
37
|
+
* parameter stays `flagKey`, because that is the name fixed by the OpenFeature
|
|
38
|
+
* spec, by `spec/decision.schema.json`, and by the `/v1/flags/evaluate` wire
|
|
39
|
+
* contract shared with the Python, Go, and Java SDKs.
|
|
40
|
+
*/
|
|
41
|
+
export class ControlPointsApi {
|
|
42
|
+
runtime;
|
|
43
|
+
constructor(runtime) {
|
|
44
|
+
this.runtime = runtime;
|
|
45
|
+
}
|
|
46
|
+
/** Evaluate a flag to a canonical Decision (detailed evaluation). */
|
|
47
|
+
evaluate(flagKey, expectedType, defaultValue, context, options) {
|
|
48
|
+
return this.runtime.evaluate(flagKey, expectedType, defaultValue, context, options ?? {});
|
|
49
|
+
}
|
|
50
|
+
async getBooleanValue(flagKey, defaultValue, context) {
|
|
51
|
+
const decision = await this.evaluate(flagKey, 'boolean', defaultValue, context);
|
|
52
|
+
return decision.value;
|
|
53
|
+
}
|
|
54
|
+
async getStringValue(flagKey, defaultValue, context) {
|
|
55
|
+
const decision = await this.evaluate(flagKey, 'string', defaultValue, context);
|
|
56
|
+
return decision.value;
|
|
57
|
+
}
|
|
58
|
+
async getNumberValue(flagKey, defaultValue, context) {
|
|
59
|
+
const decision = await this.evaluate(flagKey, 'number', defaultValue, context);
|
|
60
|
+
return decision.value;
|
|
61
|
+
}
|
|
62
|
+
async getObjectValue(flagKey, defaultValue, context) {
|
|
63
|
+
const decision = await this.evaluate(flagKey, 'object', defaultValue, context);
|
|
64
|
+
return decision.value;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Detailed reads — the whole {@link Decision} rather than just its value.
|
|
68
|
+
*
|
|
69
|
+
* Same arguments as the `*Value` pair above, so a caller upgrades from one to
|
|
70
|
+
* the other without restructuring the call. Required by
|
|
71
|
+
* `spec/control-points.md`; before ADR-0010 the only route to `reason`,
|
|
72
|
+
* `variant` or `error` was the OpenFeature provider's `resolve*Evaluation`,
|
|
73
|
+
* so detailed evaluation was unreachable without installing OpenFeature.
|
|
74
|
+
*/
|
|
75
|
+
getBooleanDetails(flagKey, defaultValue, context) {
|
|
76
|
+
return this.evaluate(flagKey, 'boolean', defaultValue, context);
|
|
77
|
+
}
|
|
78
|
+
getStringDetails(flagKey, defaultValue, context) {
|
|
79
|
+
return this.evaluate(flagKey, 'string', defaultValue, context);
|
|
80
|
+
}
|
|
81
|
+
getNumberDetails(flagKey, defaultValue, context) {
|
|
82
|
+
return this.evaluate(flagKey, 'number', defaultValue, context);
|
|
83
|
+
}
|
|
84
|
+
getObjectDetails(flagKey, defaultValue, context) {
|
|
85
|
+
return this.evaluate(flagKey, 'object', defaultValue, context);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Names invokeCapability will dispatch instead of degrading with
|
|
90
|
+
* UnsupportedCapability. Empty in v1: releases, exposures, signals,
|
|
91
|
+
* capabilities discovery, and guardrails are all out of scope
|
|
92
|
+
* (spec/control-points.md) and MUST NOT be exposed, so a cut namespace's
|
|
93
|
+
* capability string resolves exactly like any other unknown string.
|
|
94
|
+
*/
|
|
95
|
+
const SUPPORTED_CAPABILITIES = Object.freeze([]);
|
|
96
|
+
export class FireweaveClient {
|
|
97
|
+
runtime;
|
|
98
|
+
controlPoints;
|
|
99
|
+
/**
|
|
100
|
+
* Control-point evaluation under its former name.
|
|
101
|
+
*
|
|
102
|
+
* @deprecated Renamed to {@link FireweaveClient.controlPoints} (ADR-0007).
|
|
103
|
+
* Identical and fully supported — `client.flags === client.controlPoints`, so
|
|
104
|
+
* no migration is required and none is planned. Silent at runtime: the alias
|
|
105
|
+
* is permanent, not scheduled for removal, so there is nothing to warn a
|
|
106
|
+
* caller toward — deprecation is conveyed by this doc comment only (no log,
|
|
107
|
+
* and no env gate to control one, since the SDK reads no environment
|
|
108
|
+
* variables regardless — spec/modes.md).
|
|
109
|
+
*/
|
|
110
|
+
get flags() {
|
|
111
|
+
return this.controlPoints;
|
|
112
|
+
}
|
|
113
|
+
constructor(runtime, _options = {}) {
|
|
114
|
+
this.runtime = runtime;
|
|
115
|
+
this.controlPoints = new ControlPointsApi(runtime);
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Register durable targeting facts for a target (spec/modes.md).
|
|
119
|
+
*
|
|
120
|
+
* Resolves `{ ok: false }` rather than throwing: this runs in sign-in paths,
|
|
121
|
+
* where a targeting concern must not break authentication. A careful caller
|
|
122
|
+
* logs a false — a silently unregistered target is how targeting rules end
|
|
123
|
+
* up matching nobody.
|
|
124
|
+
*
|
|
125
|
+
* In local mode this records in-process and traces the call; nothing reaches
|
|
126
|
+
* fw-server. See `FireweaveLocalAdapter.registerTarget`.
|
|
127
|
+
*/
|
|
128
|
+
registerTarget(targetingKey, options = {}) {
|
|
129
|
+
return this.runtime.registerTarget(targetingKey, options);
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* Dynamic capability dispatch. Unknown capabilities — currently all of
|
|
133
|
+
* them, v1's SUPPORTED_CAPABILITIES is empty — degrade with
|
|
134
|
+
* UnsupportedCapability, never throw (fixture
|
|
135
|
+
* ext-unsupported-capability-degrade). Any future capability listed in
|
|
136
|
+
* SUPPORTED_CAPABILITIES is lifecycle-gated the same way (ruling 17).
|
|
137
|
+
*/
|
|
138
|
+
invokeCapability(capability, _args) {
|
|
139
|
+
if (!SUPPORTED_CAPABILITIES.includes(capability)) {
|
|
140
|
+
return failure(new FireweaveError('UnsupportedCapability'), true);
|
|
141
|
+
}
|
|
142
|
+
if (capability !== 'capabilities.get') {
|
|
143
|
+
const gateError = lifecycleGate(this.runtime);
|
|
144
|
+
if (gateError !== undefined)
|
|
145
|
+
return failure(gateError, true);
|
|
146
|
+
}
|
|
147
|
+
return { ok: true };
|
|
148
|
+
}
|
|
149
|
+
async initialize(signal) {
|
|
150
|
+
await this.runtime.initialize(signal);
|
|
151
|
+
}
|
|
152
|
+
async shutdown() {
|
|
153
|
+
await this.runtime.shutdown();
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
//# sourceMappingURL=client.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/application/client.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* initFireweave — the single SDK entry point (spec/modes.md).
|
|
3
|
+
*
|
|
4
|
+
* `mode` is required and never inferred: a missing or mistyped credential
|
|
5
|
+
* must fail loudly at boot, not silently fall back to local evaluation —
|
|
6
|
+
* that failure mode looks like a green boot and a feature that never ramps.
|
|
7
|
+
* This function's only job is to validate the initialisation-time contract
|
|
8
|
+
* and select the matching adapter; nothing downstream branches on mode again
|
|
9
|
+
* (spec/modes.md "Behaviour per mode" — both adapters implement the same
|
|
10
|
+
* BackendAdapter port, so FireweaveClient / FireweaveRuntime stay mode-blind).
|
|
11
|
+
*
|
|
12
|
+
* Initialisation fails loudly (throws); reads on the returned client never do
|
|
13
|
+
* (spec/control-points.md "initialise is the exception"). The validation
|
|
14
|
+
* itself lives in `validateInitOptions` (validation.ts), which returns
|
|
15
|
+
* `Validated<T>` like every other validator — this function is what converts
|
|
16
|
+
* a failed `Validated` into the throw spec/modes.md requires.
|
|
17
|
+
*/
|
|
18
|
+
import { FireweaveClient } from './client.js';
|
|
19
|
+
import type { FireweaveRemoteAdapterOptions } from '../infrastructure/adapters/remote.js';
|
|
20
|
+
export interface InitFireweaveRemoteOptions {
|
|
21
|
+
/** Evaluate against fw-server over the network (spec/remote-protocol.md). */
|
|
22
|
+
readonly mode: 'remote';
|
|
23
|
+
/** Fireweave project/runtime key (project-api-key_…). Required — never read from env. */
|
|
24
|
+
readonly apiKey: string;
|
|
25
|
+
/** fw-server base URL. Required — never read from env. */
|
|
26
|
+
readonly apiUrl: string;
|
|
27
|
+
/**
|
|
28
|
+
* SSRF allowlist override (spec/modes.md "apiUrl fails the host allowlist").
|
|
29
|
+
* Default: the canonical Fireweave hosts + loopback (`DEFAULT_ALLOWED_HOSTS`).
|
|
30
|
+
* A self-hosted fw-server must list its own host explicitly; `['*']` opts out.
|
|
31
|
+
*/
|
|
32
|
+
readonly allowedHosts?: readonly string[];
|
|
33
|
+
/** Injected transport (tests). Production uses the runtime's global `fetch`. */
|
|
34
|
+
readonly fetch?: FireweaveRemoteAdapterOptions['fetch'];
|
|
35
|
+
}
|
|
36
|
+
export interface InitFireweaveLocalOptions {
|
|
37
|
+
/** Evaluate against an in-process seeded map; no network (spec/modes.md). */
|
|
38
|
+
readonly mode: 'local';
|
|
39
|
+
readonly local?: {
|
|
40
|
+
/**
|
|
41
|
+
* Per-key boolean overrides — the seeded local map. A present key
|
|
42
|
+
* resolves with reason `STATIC`; an absent key misses so the caller's own
|
|
43
|
+
* default is used. May be empty or omitted entirely.
|
|
44
|
+
*/
|
|
45
|
+
readonly controlPoints?: Record<string, boolean>;
|
|
46
|
+
/**
|
|
47
|
+
* Sink for the `[fireweave:local]` registerTarget trace line
|
|
48
|
+
* (spec/modes.md "registerTarget in local mode"). Defaults to
|
|
49
|
+
* `console.info`.
|
|
50
|
+
*/
|
|
51
|
+
readonly log?: (message: string) => void;
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
export type InitFireweaveOptions = InitFireweaveRemoteOptions | InitFireweaveLocalOptions;
|
|
55
|
+
/**
|
|
56
|
+
* Build the adapter matching `options.mode` and bring a {@link FireweaveClient}
|
|
57
|
+
* to READY.
|
|
58
|
+
*
|
|
59
|
+
* Throws {@link FireweaveError} (kind `Configuration`) for every row of the
|
|
60
|
+
* initialisation-validation table (spec/modes.md):
|
|
61
|
+
* - `mode` absent or unrecognised
|
|
62
|
+
* - `mode: 'remote'` with `apiKey` or `apiUrl` missing/blank
|
|
63
|
+
* - `apiUrl` fails the host allowlist
|
|
64
|
+
* - `mode: 'local'` with credentials supplied
|
|
65
|
+
*
|
|
66
|
+
* The first, second and fourth rows are `validateInitOptions`'s job; the
|
|
67
|
+
* third is validated downstream, when `runtime.initialize()` brings the
|
|
68
|
+
* adapter up (`FireweaveRuntime`'s own config validation, `hosts.ts`).
|
|
69
|
+
*/
|
|
70
|
+
export declare function initFireweave(options: InitFireweaveOptions): Promise<FireweaveClient>;
|
|
71
|
+
//# sourceMappingURL=mode.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../src/application/mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAI9C,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,sCAAsC,CAAC;AAG1F,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,6BAA6B,CAAC,OAAO,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,yBAAyB;IACxC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf;;;;WAIG;QACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjD;;;;WAIG;QACH,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;KAC1C,CAAC;CACH;AAED,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,GAAG,yBAAyB,CAAC;AAgC1F;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAK3F"}
|