@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.
Files changed (58) hide show
  1. package/README.md +263 -0
  2. package/dist/application/client.d.ts +92 -0
  3. package/dist/application/client.d.ts.map +1 -0
  4. package/dist/application/client.js +156 -0
  5. package/dist/application/client.js.map +1 -0
  6. package/dist/application/mode.d.ts +71 -0
  7. package/dist/application/mode.d.ts.map +1 -0
  8. package/dist/application/mode.js +72 -0
  9. package/dist/application/mode.js.map +1 -0
  10. package/dist/application/ports.d.ts +95 -0
  11. package/dist/application/ports.d.ts.map +1 -0
  12. package/dist/application/ports.js +2 -0
  13. package/dist/application/ports.js.map +1 -0
  14. package/dist/application/runtime.d.ts +102 -0
  15. package/dist/application/runtime.d.ts.map +1 -0
  16. package/dist/application/runtime.js +342 -0
  17. package/dist/application/runtime.js.map +1 -0
  18. package/dist/domain/context.d.ts +68 -0
  19. package/dist/domain/context.d.ts.map +1 -0
  20. package/dist/domain/context.js +85 -0
  21. package/dist/domain/context.js.map +1 -0
  22. package/dist/domain/errors.d.ts +43 -0
  23. package/dist/domain/errors.d.ts.map +1 -0
  24. package/dist/domain/errors.js +64 -0
  25. package/dist/domain/errors.js.map +1 -0
  26. package/dist/domain/target.d.ts +3 -0
  27. package/dist/domain/target.d.ts.map +1 -0
  28. package/dist/domain/target.js +2 -0
  29. package/dist/domain/target.js.map +1 -0
  30. package/dist/domain/types.d.ts +108 -0
  31. package/dist/domain/types.d.ts.map +1 -0
  32. package/dist/domain/types.js +2 -0
  33. package/dist/domain/types.js.map +1 -0
  34. package/dist/domain/validation.d.ts +125 -0
  35. package/dist/domain/validation.d.ts.map +1 -0
  36. package/dist/domain/validation.js +347 -0
  37. package/dist/domain/validation.js.map +1 -0
  38. package/dist/index.d.ts +35 -0
  39. package/dist/index.d.ts.map +1 -0
  40. package/dist/index.js +23 -0
  41. package/dist/index.js.map +1 -0
  42. package/dist/infrastructure/adapters/inmemory.d.ts +78 -0
  43. package/dist/infrastructure/adapters/inmemory.d.ts.map +1 -0
  44. package/dist/infrastructure/adapters/inmemory.js +148 -0
  45. package/dist/infrastructure/adapters/inmemory.js.map +1 -0
  46. package/dist/infrastructure/adapters/local.d.ts +109 -0
  47. package/dist/infrastructure/adapters/local.d.ts.map +1 -0
  48. package/dist/infrastructure/adapters/local.js +102 -0
  49. package/dist/infrastructure/adapters/local.js.map +1 -0
  50. package/dist/infrastructure/adapters/remote.d.ts +75 -0
  51. package/dist/infrastructure/adapters/remote.d.ts.map +1 -0
  52. package/dist/infrastructure/adapters/remote.js +361 -0
  53. package/dist/infrastructure/adapters/remote.js.map +1 -0
  54. package/dist/infrastructure/hosts.d.ts +19 -0
  55. package/dist/infrastructure/hosts.d.ts.map +1 -0
  56. package/dist/infrastructure/hosts.js +68 -0
  57. package/dist/infrastructure/hosts.js.map +1 -0
  58. package/package.json +56 -0
@@ -0,0 +1,148 @@
1
+ /**
2
+ * Deterministic in-memory adapter for tests and conformance fixtures.
3
+ * Resolution model mirrors contracts/ fixture flag definitions: flags, variants,
4
+ * payloads, targeting by targeting key / person attributes / groups.
5
+ * Deliberately NO bucketing / percentage logic.
6
+ */
7
+ import { FireweaveError } from '../../domain/errors.js';
8
+ function deepEqual(a, b) {
9
+ if (a === b)
10
+ return true;
11
+ if (a === undefined || b === undefined || a === null || b === null)
12
+ return false;
13
+ if (typeof a !== typeof b)
14
+ return false;
15
+ if (Array.isArray(a) && Array.isArray(b)) {
16
+ return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
17
+ }
18
+ if (typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
19
+ const ak = Object.keys(a);
20
+ const bk = Object.keys(b);
21
+ return ak.length === bk.length && ak.every((k) => deepEqual(a[k], b[k]));
22
+ }
23
+ return false;
24
+ }
25
+ export class InMemoryAdapter {
26
+ name = 'inmemory';
27
+ flags;
28
+ fault;
29
+ initError;
30
+ initGate;
31
+ exposures = [];
32
+ signals = [];
33
+ closed = false;
34
+ constructor(options = {}) {
35
+ this.flags = new Map(Object.entries(options.flags ?? {}));
36
+ this.fault = options.fault;
37
+ this.initError = options.initError;
38
+ this.initGate = options.initGate;
39
+ }
40
+ setFlags(flags) {
41
+ this.flags = new Map(Object.entries(flags));
42
+ }
43
+ setFault(fault) {
44
+ this.fault = fault;
45
+ }
46
+ async initialize(signal) {
47
+ if (this.initError !== undefined) {
48
+ throw new FireweaveError(this.initError);
49
+ }
50
+ if (this.initGate !== undefined) {
51
+ if (signal?.aborted)
52
+ throw new FireweaveError('Timeout');
53
+ await this.initGate.promise;
54
+ }
55
+ }
56
+ async resolve(flagKey, context, _options) {
57
+ if (this.fault !== undefined) {
58
+ const opts = this.fault.metadata !== undefined ? { metadata: this.fault.metadata } : {};
59
+ throw new FireweaveError(this.fault.kind, opts);
60
+ }
61
+ const def = this.flags.get(flagKey);
62
+ if (def === undefined) {
63
+ return { found: false };
64
+ }
65
+ if (!this.matches(def, context)) {
66
+ return { found: false };
67
+ }
68
+ const resolution = {
69
+ found: true,
70
+ enabled: def.enabled,
71
+ value: def.value,
72
+ flagType: def.type,
73
+ };
74
+ if (def.variant !== undefined)
75
+ resolution.variant = def.variant;
76
+ if (def.fireweaveReason !== undefined)
77
+ resolution.reason = def.fireweaveReason;
78
+ if (def.reason?.code !== undefined)
79
+ resolution.reasonCode = def.reason.code;
80
+ if (def.reason?.condition_index !== undefined)
81
+ resolution.conditionIndex = def.reason.condition_index;
82
+ if (def.metadata?.version !== undefined)
83
+ resolution.version = def.metadata.version;
84
+ if (def.metadata?.id !== undefined)
85
+ resolution.vendorFlagId = def.metadata.id;
86
+ if (def.payload !== undefined)
87
+ resolution.payload = def.payload;
88
+ if (def.fromCache === true)
89
+ resolution.fromCache = true;
90
+ return resolution;
91
+ }
92
+ matches(def, context) {
93
+ if (def.matchTargetingKey !== undefined && context.targetingKey !== def.matchTargetingKey) {
94
+ return false;
95
+ }
96
+ if (def.matchAttribute !== undefined) {
97
+ for (const [k, v] of Object.entries(def.matchAttribute)) {
98
+ if (!deepEqual(context.attributes[k], v))
99
+ return false;
100
+ }
101
+ }
102
+ if (def.matchPerson !== undefined) {
103
+ for (const [k, v] of Object.entries(def.matchPerson)) {
104
+ if (!deepEqual(context.attributes[k], v))
105
+ return false;
106
+ }
107
+ }
108
+ if (def.matchGroups !== undefined) {
109
+ for (const [k, v] of Object.entries(def.matchGroups)) {
110
+ if (context.groups?.[k] !== v)
111
+ return false;
112
+ }
113
+ }
114
+ return true;
115
+ }
116
+ recordExposure(exposure) {
117
+ this.exposures.push(exposure);
118
+ }
119
+ getExposures() {
120
+ return this.exposures;
121
+ }
122
+ recordSignal(signal) {
123
+ this.signals.push(signal);
124
+ }
125
+ getSignals() {
126
+ return this.signals;
127
+ }
128
+ async flush() {
129
+ // no-op: exposures stay queryable for tests
130
+ }
131
+ async shutdown() {
132
+ this.closed = true;
133
+ }
134
+ isClosed() {
135
+ return this.closed;
136
+ }
137
+ features() {
138
+ return {
139
+ remoteEvaluation: false,
140
+ localEvaluation: true,
141
+ localOnly: true,
142
+ exposureEmission: true,
143
+ sideEffectFreeReads: true,
144
+ groupAnalytics: true,
145
+ };
146
+ }
147
+ }
148
+ //# sourceMappingURL=inmemory.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"inmemory.js","sourceRoot":"","sources":["../../../src/infrastructure/adapters/inmemory.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Local development adapter — the DEV substrate for a scaffolded harness.
3
+ *
4
+ * It is the counterpart to {@link FireweaveRemoteAdapter}: prod evaluates
5
+ * control points against fw-server, dev evaluates them here, in-process, with
6
+ * no network and no credentials. Because it satisfies the same
7
+ * {@link BackendAdapter} port, the dev branch of a harness runs through the
8
+ * same {@link FireweaveRuntime} as prod — inheriting identical lifecycle
9
+ * gating and context canonicalization. That symmetry is the point: dev/prod
10
+ * skew in the harness is exactly what the harness exists to prevent.
11
+ *
12
+ * Resolution policy is deliberately minimal:
13
+ *
14
+ * - a key present in `devFlags` resolves to its mapped value with reason
15
+ * `STATIC` — the only supported way to turn a control point ON (or force it
16
+ * OFF) on a laptop;
17
+ * - every other key MISSES (`{ found: false, reason: 'DEFAULT' }`), which the
18
+ * runtime turns into the caller's own default with reason `DEFAULT` — not
19
+ * an error (spec/modes.md "Behaviour per mode": local's unknown-key row is
20
+ * deliberately `default`/`DEFAULT`, unlike remote's `default`/`ERROR`/
21
+ * `FlagNotFound`).
22
+ *
23
+ * Call-site defaults stay `false` under RAMP-1. Never write
24
+ * `fw.flag(key, true)` to dogfood locally — that same `true` is the production
25
+ * fallback when the control point is absent from the provider, so it silently
26
+ * ships the ON branch. Use `devFlags` instead.
27
+ *
28
+ * Runtime portability: pure computation, no I/O, no env, no Node globals — so
29
+ * it runs unchanged on Node, Bun, and Deno (ADR-0008), and is covered by
30
+ * `test/unit/runtime-portability.test.ts`.
31
+ */
32
+ import type { AdapterResolution, AdapterRuntimeFeatures, BackendAdapter, RegisterTargetOptions, RegisterTargetResult, ResolveOptions } from '../../application/ports.js';
33
+ import type { TargetKind } from '../../domain/target.js';
34
+ import type { CanonicalContext } from '../../domain/types.js';
35
+ export interface FireweaveLocalAdapterOptions {
36
+ /**
37
+ * Per-key boolean overrides. A present key resolves to its mapped value with
38
+ * reason `STATIC`; an absent key misses so the caller's default is used.
39
+ */
40
+ readonly devFlags?: Record<string, boolean>;
41
+ /**
42
+ * Sink for the local `registerTarget` trace. Defaults to `console.info`.
43
+ * Injectable so tests assert the call without capturing stdout, and so a
44
+ * host that owns its logging can route it.
45
+ */
46
+ readonly log?: (message: string) => void;
47
+ }
48
+ /** A target recorded by {@link FireweaveLocalAdapter.registerTarget}. */
49
+ export interface LocalRegisteredTarget {
50
+ readonly targetingKey: string;
51
+ readonly kind: TargetKind;
52
+ readonly properties: Record<string, unknown>;
53
+ readonly environment?: string;
54
+ }
55
+ export declare class FireweaveLocalAdapter implements BackendAdapter {
56
+ /**
57
+ * Not `inmemory` — that name belongs to {@link InMemoryAdapter}, the fixture
58
+ * adapter conformance runs against. This is a distinct dev substrate, and
59
+ * `capabilities.get()` should report it as such rather than impersonate one.
60
+ */
61
+ readonly name: "other";
62
+ private readonly devFlags;
63
+ private readonly log;
64
+ private readonly targets;
65
+ private closed;
66
+ constructor(options?: FireweaveLocalAdapterOptions);
67
+ initialize(_signal?: AbortSignal): Promise<void>;
68
+ /**
69
+ * A `devFlags` hit reports `enabled: true` alongside `reason: 'STATIC'`.
70
+ * Reporting `enabled: false` for an override of `false` would make the
71
+ * runtime label the decision `DISABLED` (runtime.ts, reason resolution),
72
+ * which means "the control point exists but is switched off upstream" — not
73
+ * what a local override expresses.
74
+ *
75
+ * `flagType: 'boolean'` is declared honestly. Reading an overridden key as a
76
+ * string or number therefore yields TYPE_MISMATCH rather than silently
77
+ * handing back the default: `devFlags` is `Record<string, boolean>`, so such
78
+ * a read is a genuine call-site mistake and is better surfaced than hidden.
79
+ *
80
+ * A miss carries `reason: 'DEFAULT'` on the `{ found: false }` resolution —
81
+ * the signal `FireweaveRuntime.evaluate` (runtime.ts) reads to return the
82
+ * caller's default with reason `DEFAULT` instead of falling through to its
83
+ * generic FlagNotFound/ERROR mapping (spec/modes.md).
84
+ */
85
+ resolve(flagKey: string, _context: CanonicalContext, _options?: ResolveOptions): Promise<AdapterResolution>;
86
+ /**
87
+ * Records the target in-process and traces it, rather than reporting
88
+ * `UnsupportedCapability`.
89
+ *
90
+ * The capability previously reported Unsupported so that a dev harness could
91
+ * not *silently* look registered — the failure being guarded against is a
92
+ * developer believing their targeting works because nothing objected. A
93
+ * recorded target plus an explicit `[fireweave:local]` line preserves that
94
+ * guarantee by a different route: nothing is silent, and local dev can now
95
+ * exercise targeting rules offline instead of only in production.
96
+ *
97
+ * The trace names the mode, so a line appearing in a production log is
98
+ * itself the signal that something booted in local mode by mistake.
99
+ *
100
+ * No network call is made and nothing reaches fw-server.
101
+ */
102
+ registerTarget(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
103
+ /** Targets recorded this process, for assertions and dev inspection. */
104
+ getRegisteredTargets(): readonly LocalRegisteredTarget[];
105
+ shutdown(): Promise<void>;
106
+ isClosed(): boolean;
107
+ features(): AdapterRuntimeFeatures;
108
+ }
109
+ //# sourceMappingURL=local.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/adapters/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACf,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,qBAAsB,YAAW,cAAc;IAC1D;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAEjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IACpE,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE,4BAAiC;IAKhD,UAAU,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CACX,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,iBAAiB,CAAC;IAa7B;;;;;;;;;;;;;;;OAeG;IACG,cAAc,CAClB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC;IAiBhC,wEAAwE;IACxE,oBAAoB,IAAI,SAAS,qBAAqB,EAAE;IAIlD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,QAAQ,IAAI,OAAO;IAInB,QAAQ,IAAI,sBAAsB;CAYnC"}
@@ -0,0 +1,102 @@
1
+ export class FireweaveLocalAdapter {
2
+ /**
3
+ * Not `inmemory` — that name belongs to {@link InMemoryAdapter}, the fixture
4
+ * adapter conformance runs against. This is a distinct dev substrate, and
5
+ * `capabilities.get()` should report it as such rather than impersonate one.
6
+ */
7
+ name = 'other';
8
+ devFlags;
9
+ log;
10
+ targets = new Map();
11
+ closed = false;
12
+ constructor(options = {}) {
13
+ this.devFlags = { ...(options.devFlags ?? {}) };
14
+ this.log = options.log ?? ((m) => console.info(m));
15
+ }
16
+ async initialize(_signal) {
17
+ // Nothing to connect to. Kept async to satisfy the port.
18
+ }
19
+ /**
20
+ * A `devFlags` hit reports `enabled: true` alongside `reason: 'STATIC'`.
21
+ * Reporting `enabled: false` for an override of `false` would make the
22
+ * runtime label the decision `DISABLED` (runtime.ts, reason resolution),
23
+ * which means "the control point exists but is switched off upstream" — not
24
+ * what a local override expresses.
25
+ *
26
+ * `flagType: 'boolean'` is declared honestly. Reading an overridden key as a
27
+ * string or number therefore yields TYPE_MISMATCH rather than silently
28
+ * handing back the default: `devFlags` is `Record<string, boolean>`, so such
29
+ * a read is a genuine call-site mistake and is better surfaced than hidden.
30
+ *
31
+ * A miss carries `reason: 'DEFAULT'` on the `{ found: false }` resolution —
32
+ * the signal `FireweaveRuntime.evaluate` (runtime.ts) reads to return the
33
+ * caller's default with reason `DEFAULT` instead of falling through to its
34
+ * generic FlagNotFound/ERROR mapping (spec/modes.md).
35
+ */
36
+ async resolve(flagKey, _context, _options) {
37
+ const override = this.devFlags[flagKey];
38
+ if (override === undefined)
39
+ return { found: false, reason: 'DEFAULT' };
40
+ return {
41
+ found: true,
42
+ enabled: true,
43
+ value: override,
44
+ variant: override ? 'on' : 'off',
45
+ reason: 'STATIC',
46
+ flagType: 'boolean',
47
+ };
48
+ }
49
+ /**
50
+ * Records the target in-process and traces it, rather than reporting
51
+ * `UnsupportedCapability`.
52
+ *
53
+ * The capability previously reported Unsupported so that a dev harness could
54
+ * not *silently* look registered — the failure being guarded against is a
55
+ * developer believing their targeting works because nothing objected. A
56
+ * recorded target plus an explicit `[fireweave:local]` line preserves that
57
+ * guarantee by a different route: nothing is silent, and local dev can now
58
+ * exercise targeting rules offline instead of only in production.
59
+ *
60
+ * The trace names the mode, so a line appearing in a production log is
61
+ * itself the signal that something booted in local mode by mistake.
62
+ *
63
+ * No network call is made and nothing reaches fw-server.
64
+ */
65
+ async registerTarget(targetingKey, options = {}) {
66
+ const kind = options.kind ?? 'user';
67
+ const properties = { ...(options.properties ?? {}) };
68
+ const target = {
69
+ targetingKey,
70
+ kind,
71
+ properties,
72
+ ...(options.environment === undefined ? {} : { environment: options.environment }),
73
+ };
74
+ this.targets.set(targetingKey, target);
75
+ this.log(`[fireweave:local] registerTarget ${kind} ${targetingKey} ` +
76
+ `${JSON.stringify(properties)} — recorded in-process, NOT sent to fw-server`);
77
+ return { ok: true };
78
+ }
79
+ /** Targets recorded this process, for assertions and dev inspection. */
80
+ getRegisteredTargets() {
81
+ return [...this.targets.values()];
82
+ }
83
+ async shutdown() {
84
+ this.closed = true;
85
+ }
86
+ isClosed() {
87
+ return this.closed;
88
+ }
89
+ features() {
90
+ return {
91
+ remoteEvaluation: false,
92
+ localEvaluation: true,
93
+ localOnly: true,
94
+ // No exposure sink exists locally; claiming otherwise would make
95
+ // capabilities.get() advertise emission that silently goes nowhere.
96
+ exposureEmission: false,
97
+ sideEffectFreeReads: true,
98
+ groupAnalytics: false,
99
+ };
100
+ }
101
+ }
102
+ //# sourceMappingURL=local.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"local.js","sourceRoot":"","sources":["../../../src/infrastructure/adapters/local.ts"],"names":[],"mappings":"AAgEA,MAAM,OAAO,qBAAqB;IAChC;;;;OAIG;IACM,IAAI,GAAG,OAAgB,CAAC;IAEhB,QAAQ,CAA0B;IAClC,GAAG,CAA4B;IAC/B,OAAO,GAAG,IAAI,GAAG,EAAiC,CAAC;IAC5D,MAAM,GAAG,KAAK,CAAC;IAEvB,YAAY,UAAwC,EAAE;QACpD,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;QAChD,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,OAAqB;QACpC,yDAAyD;IAC3D,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,OAAO,CACX,OAAe,EACf,QAA0B,EAC1B,QAAyB;QAEzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACvE,OAAO;YACL,KAAK,EAAE,IAAI;YACX,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK;YAChC,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,SAAS;SACpB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,cAAc,CAClB,YAAoB,EACpB,UAAiC,EAAE;QAEnC,MAAM,IAAI,GAAe,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;QAChD,MAAM,UAAU,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC;QACrD,MAAM,MAAM,GAA0B;YACpC,YAAY;YACZ,IAAI;YACJ,UAAU;YACV,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;SACnF,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,GAAG,CACN,oCAAoC,IAAI,IAAI,YAAY,GAAG;YACzD,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,+CAA+C,CAC/E,CAAC;QACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,wEAAwE;IACxE,oBAAoB;QAClB,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,QAAQ;QACN,OAAO;YACL,gBAAgB,EAAE,KAAK;YACvB,eAAe,EAAE,IAAI;YACrB,SAAS,EAAE,IAAI;YACf,iEAAiE;YACjE,oEAAoE;YACpE,gBAAgB,EAAE,KAAK;YACvB,mBAAmB,EAAE,IAAI;YACzB,cAAc,EAAE,KAAK;SACtB,CAAC;IACJ,CAAC;CACF"}
@@ -0,0 +1,75 @@
1
+ import type { AdapterResolution, AdapterRuntimeFeatures, BackendAdapter, RegisterTargetOptions, RegisterTargetResult, ResolveOptions } from '../../application/ports.js';
2
+ import type { CanonicalContext, Exposure, Signal } from '../../domain/types.js';
3
+ type FetchLike = (url: string, init?: {
4
+ method?: string;
5
+ headers?: Record<string, string>;
6
+ body?: string;
7
+ signal?: AbortSignal;
8
+ }) => Promise<{
9
+ status: number;
10
+ text(): Promise<string>;
11
+ json(): Promise<unknown>;
12
+ }>;
13
+ export interface FireweaveRemoteAdapterOptions {
14
+ /**
15
+ * fw-server base URL (e.g. https://fw.example.com or http://127.0.0.1:3901).
16
+ * Required — never read from the environment (spec/modes.md "The SDK reads
17
+ * no environment variables. Credentials arrive as explicit options.").
18
+ */
19
+ apiUrl?: string;
20
+ /**
21
+ * Fireweave project/runtime key (project-api-key_…).
22
+ * Required — never read from the environment (spec/modes.md "The SDK reads
23
+ * no environment variables. Credentials arrive as explicit options.").
24
+ */
25
+ apiKey?: string;
26
+ /**
27
+ * SSRF allowlist override. Default: hostname of `apiUrl` + loopback.
28
+ * Pass `['*']` to opt out of host pinning.
29
+ */
30
+ allowedHosts?: readonly string[];
31
+ /** Per-request timeout for evaluate/capture (default 3000 ms). */
32
+ requestTimeoutMs?: number;
33
+ /** Deadline for flush during shutdown (default 10 000 ms). */
34
+ shutdownTimeoutMs?: number;
35
+ /** Injected fetch (tests). */
36
+ fetch?: FetchLike;
37
+ }
38
+ export declare class FireweaveRemoteAdapter implements BackendAdapter {
39
+ readonly name: "fireweave";
40
+ private readonly options;
41
+ private apiUrl;
42
+ private apiKey;
43
+ private closed;
44
+ private ready;
45
+ private readonly pending;
46
+ private readonly fetchImpl;
47
+ constructor(options?: FireweaveRemoteAdapterOptions);
48
+ initialize(_signal?: AbortSignal): Promise<void>;
49
+ resolve(flagKey: string, context: CanonicalContext, options?: ResolveOptions): Promise<AdapterResolution>;
50
+ /**
51
+ * Register a user or device so flag rules can target its DURABLE properties.
52
+ *
53
+ * Call once per login / device provisioning, then send the same
54
+ * `targetingKey` on evaluate. Per-request `attributes` still override the
55
+ * stored properties for a single evaluation — the two identity paths compose
56
+ * (see spec/remote-protocol.md § Two identity paths).
57
+ *
58
+ * Never throws for transport failures: registration sits in login paths, and
59
+ * an analytics call must not break sign-in. Retried ONCE when the error
60
+ * taxonomy marks the failure retryable (network / timeout / backend); a
61
+ * rejected payload or bad key is not retried, since it would be rejected
62
+ * identically. The result object reports what happened for callers that
63
+ * want to log it.
64
+ */
65
+ registerTarget(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
66
+ recordExposure(exposure: Exposure): void;
67
+ recordSignal(signal: Signal): void;
68
+ flush(): Promise<void>;
69
+ shutdown(): Promise<void>;
70
+ features(): AdapterRuntimeFeatures;
71
+ private toResolution;
72
+ private requestJson;
73
+ }
74
+ export {};
75
+ //# sourceMappingURL=remote.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/adapters/remote.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACf,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAa,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAQ3F,KAAK,SAAS,GAAG,CACf,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IACL,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B,CAAC,CAAC;AAEH,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8BAA8B;IAC9B,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAiFD,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,OAAO,GAAE,6BAAkC;IAKjD,UAAU,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BhD,OAAO,CACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC;IAqC7B;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAClB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC;IA2BhC,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAexC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAuB5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAWtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAe/B,QAAQ,IAAI,sBAAsB;IAWlC,OAAO,CAAC,YAAY;YA+BN,WAAW;CA8C1B"}