The best way to control Claude Code, Codex and more from any computer or phone

main
ts 300 lines 10.8 KB
Raw
1 import * as frauddetector from "@distilled.cloud/aws/frauddetector";
2 import { deepEqual, isResolved } from "alchemy/Diff";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import { createInternalTags } from "alchemy/Tags";
6 import * as Effect from "effect/Effect";
7 import type { Providers } from "../Providers.ts";
8 import { syncFraudDetectorTags } from "./internal.ts";
9
10 /**
11 * An inline rule definition owned by a detector version. Fraud Detector rules
12 * are versioned resources scoped to a detector; a detector version references
13 * a specific rule version. Declaring rules inline here lets the detector
14 * version own their whole lifecycle.
15 */
16 export interface RuleDefinition {
17 /**
18 * Identifier of the rule, unique within the detector (e.g. `high_risk`).
19 */
20 ruleId: string;
21 /**
22 * The rule expression, written in the rule language (see `language`). It
23 * references variables and evaluates to a boolean, e.g.
24 * `$order_price > 1000 and $email == "unknown"`.
25 */
26 expression: string;
27 /**
28 * Names of the outcomes returned when the rule matches. Must reference
29 * existing Fraud Detector outcomes.
30 */
31 outcomes: string[];
32 /**
33 * The rule language. Only `DETECTORPL` is supported.
34 * @default "DETECTORPL"
35 */
36 language?: string;
37 /**
38 * Human-readable description of the rule.
39 */
40 description?: string;
41 }
42
43 export interface DetectorVersionProps {
44 /**
45 * The identifier of the detector this version belongs to. Immutable —
46 * changing it replaces the detector version.
47 */
48 detectorId: string;
49 /**
50 * Human-readable description of the version. Changing it replaces the
51 * version (published versions are immutable).
52 */
53 description?: string;
54 /**
55 * The rules evaluated by this version, in priority order. Changing the set
56 * of rules replaces the version.
57 */
58 rules: RuleDefinition[];
59 /**
60 * How rules are evaluated: `FIRST_MATCHED` stops at the first matching rule,
61 * `ALL_MATCHED` evaluates every rule. Changing it replaces the version.
62 * @default "FIRST_MATCHED"
63 */
64 ruleExecutionMode?: string;
65 /**
66 * The desired status of the version: `DRAFT`, `ACTIVE`, or `INACTIVE`. Only
67 * an `ACTIVE` version serves predictions. This is an in-place update.
68 * @default "ACTIVE"
69 */
70 status?: string;
71 /**
72 * User-defined tags for the detector version.
73 */
74 tags?: Record<string, string>;
75 }
76
77 export interface DetectorVersion extends Resource<
78 "AWS.FraudDetector.DetectorVersion",
79 DetectorVersionProps,
80 {
81 /** The identifier of the parent detector. */
82 detectorId: string;
83 /** The generated version identifier, e.g. `"1"`. */
84 detectorVersionId: string;
85 /** The ARN of the detector version. */
86 arn: string;
87 /** The version status: `DRAFT`, `ACTIVE`, or `INACTIVE`. */
88 status: string;
89 },
90 never,
91 Providers
92 > {}
93
94 /**
95 * An Amazon Fraud Detector detector version — the deployable revision of a
96 * detector. It bundles a set of rules (owned inline here) over the detector's
97 * event type and, when `ACTIVE`, serves real-time predictions via
98 * `getEventPrediction`. Rules and the version are cheap, rule-based
99 * configuration objects — no model training is involved.
100 *
101 * ### Creating a Detector Version
102 * **Example:** Active Version with One Rule
103 * ```typescript
104 * const version = yield* FraudDetector.DetectorVersion("v1", {
105 * detectorId: detector.detectorId,
106 * status: "ACTIVE",
107 * ruleExecutionMode: "FIRST_MATCHED",
108 * rules: [
109 * {
110 * ruleId: "high_risk",
111 * expression: '$email == "fraud@example.com"',
112 * outcomes: ["review"],
113 * },
114 * ],
115 * });
116 * ```
117 *
118 * @resource
119 */
120 export const DetectorVersion = Resource<DetectorVersion>("AWS.FraudDetector.DetectorVersion");
121
122 export const DetectorVersionProvider = () =>
123 Provider.effect(
124 DetectorVersion,
125 Effect.gen(function* () {
126 /** Read a detector version by id; typed not-found → undefined. */
127 const getVersion = Effect.fn(function* (detectorId: string, detectorVersionId: string) {
128 return yield* frauddetector
129 .getDetectorVersion({ detectorId, detectorVersionId })
130 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
131 });
132
133 /**
134 * Ensure every declared rule exists as a rule version and return the
135 * references (create-once by `ruleId`; existing rules reuse their latest
136 * version — rule-expression edits are expressed by changing `ruleId`).
137 */
138 const ensureRules = Effect.fn(function* (detectorId: string, rules: RuleDefinition[]) {
139 const refs: frauddetector.Rule[] = [];
140 for (const rule of rules) {
141 const existing = yield* frauddetector
142 .getRules({ detectorId, ruleId: rule.ruleId })
143 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
144 const details = existing?.ruleDetails ?? [];
145 if (details.length === 0) {
146 const created = yield* frauddetector.createRule({
147 ruleId: rule.ruleId,
148 detectorId,
149 expression: rule.expression,
150 language: rule.language ?? "DETECTORPL",
151 outcomes: rule.outcomes,
152 description: rule.description,
153 });
154 refs.push(created.rule!);
155 } else {
156 // Reuse the latest existing version of the rule.
157 const latest = details.reduce((a, b) =>
158 Number(b.ruleVersion ?? "0") > Number(a.ruleVersion ?? "0") ? b : a,
159 );
160 refs.push({
161 detectorId,
162 ruleId: latest.ruleId!,
163 ruleVersion: latest.ruleVersion!,
164 });
165 }
166 }
167 return refs;
168 });
169
170 return {
171 stables: ["detectorId", "detectorVersionId", "arn"],
172
173 diff: Effect.fn(function* ({ olds = {}, news }) {
174 if (!isResolved(news)) return undefined;
175 // Everything but status is baked into the published version — a
176 // change to the detector, rules, execution mode, or description
177 // replaces the version. Status transitions happen in place.
178 if (
179 (olds.detectorId ?? undefined) !== (news.detectorId ?? undefined) ||
180 (olds.ruleExecutionMode ?? undefined) !== (news.ruleExecutionMode ?? undefined) ||
181 (olds.description ?? undefined) !== (news.description ?? undefined) ||
182 !deepEqual(olds.rules, news.rules)
183 ) {
184 return { action: "replace" } as const;
185 }
186 }),
187
188 read: Effect.fn(function* ({ output }) {
189 if (output?.detectorVersionId === undefined) return undefined;
190 const version = yield* getVersion(output.detectorId, output.detectorVersionId);
191 if (version === undefined) return undefined;
192 return {
193 detectorId: version.detectorId!,
194 detectorVersionId: version.detectorVersionId!,
195 arn: version.arn!,
196 status: version.status!,
197 };
198 }),
199
200 reconcile: Effect.fn(function* ({ id, news, output, session }) {
201 const detectorId = news.detectorId;
202 const desiredStatus = news.status ?? "ACTIVE";
203 const internalTags = yield* createInternalTags(id);
204 const desiredTags = { ...internalTags, ...news.tags };
205
206 // 1. ENSURE the rules exist and collect their version references.
207 const ruleRefs = yield* ensureRules(detectorId, news.rules);
208
209 // 2. OBSERVE the version; create it if missing. Published versions
210 // are immutable, so any content change triggers replacement (see
211 // diff) — here we only ever create or converge status/tags.
212 let detectorVersionId = output?.detectorVersionId;
213 let version =
214 detectorVersionId !== undefined
215 ? yield* getVersion(detectorId, detectorVersionId)
216 : undefined;
217
218 if (version === undefined) {
219 const created = yield* frauddetector.createDetectorVersion({
220 detectorId,
221 description: news.description,
222 rules: ruleRefs,
223 ruleExecutionMode: news.ruleExecutionMode,
224 tags: Object.entries(desiredTags).map(([key, value]) => ({
225 key,
226 value,
227 })),
228 });
229 detectorVersionId = created.detectorVersionId!;
230 version = yield* getVersion(detectorId, detectorVersionId);
231 }
232
233 // 3. SYNC status — a new version is created in DRAFT; move it to the
234 // desired status if it drifts.
235 if ((version!.status ?? undefined) !== desiredStatus) {
236 yield* frauddetector.updateDetectorVersionStatus({
237 detectorId,
238 detectorVersionId: detectorVersionId!,
239 status: desiredStatus,
240 });
241 }
242
243 // 4. SYNC tags — diff against OBSERVED cloud tags.
244 yield* syncFraudDetectorTags(version!.arn!, desiredTags);
245
246 yield* session.note(detectorVersionId!);
247 return {
248 detectorId,
249 detectorVersionId: detectorVersionId!,
250 arn: version!.arn!,
251 status: desiredStatus,
252 };
253 }),
254
255 delete: Effect.fn(function* ({ output }) {
256 const { detectorId, detectorVersionId } = output;
257 // Read the rules the version owns before removing it so we can clean
258 // them up afterwards (rules block detector deletion otherwise).
259 const version = yield* getVersion(detectorId, detectorVersionId);
260 const rules = version?.rules ?? [];
261
262 // A version must be INACTIVE before it can be deleted.
263 yield* frauddetector
264 .updateDetectorVersionStatus({
265 detectorId,
266 detectorVersionId,
267 status: "INACTIVE",
268 })
269 .pipe(
270 Effect.catchTag(
271 ["ValidationException", "ConflictException", "ResourceNotFoundException"],
272 () => Effect.void,
273 ),
274 );
275
276 yield* frauddetector
277 .deleteDetectorVersion({ detectorId, detectorVersionId })
278 .pipe(
279 Effect.catchTag(
280 ["ValidationException", "ConflictException", "ResourceNotFoundException"],
281 () => Effect.void,
282 ),
283 );
284
285 // Best-effort cleanup of the owned rule versions.
286 for (const rule of rules) {
287 yield* frauddetector
288 .deleteRule({ rule })
289 .pipe(
290 Effect.catchTag(["ValidationException", "ConflictException"], () => Effect.void),
291 );
292 }
293 }),
294
295 // Detector versions are sub-resources keyed by their parent detector;
296 // there is no account-wide enumeration op, so list is a no-op.
297 list: () => Effect.succeed([]),
298 };
299 }),
300 );