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

main
ts 401 lines 14.2 KB
Raw
1 import * as bcm from "@distilled.cloud/aws/bcm-data-exports";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import * as Stream from "effect/Stream";
11 import type { Providers } from "../Providers.ts";
12
13 /**
14 * The SQL query and table configurations for a data export.
15 */
16 export interface ExportDataQuery {
17 /**
18 * The SQL statement selecting the columns to export, e.g.
19 * `SELECT identity_line_item_id, line_item_unblended_cost FROM COST_AND_USAGE_REPORT`.
20 * Data Exports supports a limited subset of SQL — see the AWS Data Exports
21 * table dictionary for available tables and columns.
22 */
23 queryStatement: string;
24 /**
25 * Per-table property overrides, e.g.
26 * `{ COST_AND_USAGE_REPORT: { TIME_GRANULARITY: "HOURLY" } }`.
27 * Every table property has a default it assumes when omitted.
28 */
29 tableConfigurations?: Record<string, Record<string, string>>;
30 }
31
32 /**
33 * Formatting options for the objects written to S3.
34 */
35 export interface ExportS3OutputConfigurations {
36 /**
37 * The output type of the export.
38 * @default "CUSTOM"
39 */
40 outputType?: "CUSTOM" | (string & {});
41 /**
42 * The file format of the exported objects.
43 * @default "TEXT_OR_CSV"
44 */
45 format?: "TEXT_OR_CSV" | "PARQUET" | (string & {});
46 /**
47 * The compression of the exported objects. Use `PARQUET` compression with
48 * the `PARQUET` format.
49 * @default "GZIP"
50 */
51 compression?: "GZIP" | "PARQUET" | (string & {});
52 /**
53 * Whether each delivery overwrites the previous report or writes a new one.
54 * @default "OVERWRITE_REPORT"
55 */
56 overwrite?: "CREATE_NEW_REPORT" | "OVERWRITE_REPORT" | (string & {});
57 }
58
59 /**
60 * The S3 bucket the export is delivered to. The bucket policy must allow the
61 * `bcm-data-exports.amazonaws.com` and `billingreports.amazonaws.com` service
62 * principals to `s3:PutObject` and `s3:GetBucketPolicy`.
63 */
64 export interface ExportS3Destination {
65 /**
66 * Name of the destination S3 bucket.
67 */
68 s3Bucket: string;
69 /**
70 * Key prefix the export is written under.
71 */
72 s3Prefix: string;
73 /**
74 * Region of the destination S3 bucket.
75 */
76 s3Region: string;
77 /**
78 * Account ID that owns the destination bucket, for cross-account delivery.
79 */
80 s3BucketOwner?: string;
81 /**
82 * Output formatting options.
83 * @default `{ outputType: "CUSTOM", format: "TEXT_OR_CSV", compression: "GZIP", overwrite: "OVERWRITE_REPORT" }`
84 */
85 s3OutputConfigurations?: ExportS3OutputConfigurations;
86 }
87
88 export interface ExportProps {
89 /**
90 * Name of the export. Must be unique within the account. If omitted, a
91 * unique name is generated from the app, stage, and logical ID.
92 *
93 * Changing the name replaces the export.
94 */
95 exportName?: string;
96 /**
97 * Description of the export.
98 */
99 description?: string;
100 /**
101 * The SQL data query — the statement plus optional table configurations.
102 */
103 dataQuery: ExportDataQuery;
104 /**
105 * The S3 destination the export is delivered to.
106 */
107 s3Destination: ExportS3Destination;
108 /**
109 * How often the export refreshes. `SYNCHRONOUS` refreshes whenever the
110 * source billing data updates.
111 * @default `{ frequency: "SYNCHRONOUS" }`
112 */
113 refreshCadence?: {
114 /**
115 * The refresh frequency.
116 * @default "SYNCHRONOUS"
117 */
118 frequency: "SYNCHRONOUS" | (string & {});
119 };
120 /**
121 * Tags applied to the export.
122 */
123 tags?: Record<string, string>;
124 }
125
126 export interface Export extends Resource<
127 "AWS.BCMDataExports.Export",
128 ExportProps,
129 {
130 /**
131 * Name of the export.
132 */
133 exportName: string;
134 /**
135 * The ARN of the export.
136 */
137 exportArn: string;
138 },
139 never,
140 Providers
141 > {}
142
143 /**
144 * An AWS Billing and Cost Management data export (Data Exports / CUR 2.0) —
145 * delivers billing and cost management data selected by an SQL query to an
146 * S3 bucket on a refresh cadence.
147 *
148 * Data Exports is a global service pinned to `us-east-1`; exports are free
149 * (standard S3 storage rates apply to the delivered objects).
150 *
151 * The destination bucket must grant the Data Exports service principals
152 * write access via its bucket policy (see the example below).
153 *
154 * ### Creating an Export
155 * **Example:** CUR 2.0 export to an S3 bucket
156 * ```typescript
157 * import * as AWS from "@alchemy.run/aws";
158 *
159 * const bucket = yield* AWS.S3.Bucket("BillingData", {
160 * forceDestroy: true,
161 * policy: [
162 * {
163 * Effect: "Allow",
164 * Principal: {
165 * Service: [
166 * "billingreports.amazonaws.com",
167 * "bcm-data-exports.amazonaws.com",
168 * ],
169 * },
170 * Action: ["s3:PutObject", "s3:GetBucketPolicy"],
171 * Resource: [bucket.bucketArn, AWS.interpolate`${bucket.bucketArn}/*`],
172 * },
173 * ],
174 * });
175 *
176 * const cur = yield* AWS.BCMDataExports.Export("Cur2", {
177 * dataQuery: {
178 * queryStatement:
179 * "SELECT identity_line_item_id, line_item_unblended_cost FROM COST_AND_USAGE_REPORT",
180 * tableConfigurations: {
181 * COST_AND_USAGE_REPORT: { TIME_GRANULARITY: "HOURLY" },
182 * },
183 * },
184 * s3Destination: {
185 * s3Bucket: bucket.bucketName,
186 * s3Prefix: "cur2",
187 * s3Region: "us-west-2",
188 * },
189 * });
190 * ```
191 *
192 * @resource
193 */
194 export const Export = Resource<Export>("AWS.BCMDataExports.Export");
195
196 const retryThrottling = <A, E extends { readonly _tag: string }, R>(
197 self: Effect.Effect<A, E, R>,
198 ): Effect.Effect<A, E, R> =>
199 Effect.retry(self, {
200 while: (e) => e._tag === "ThrottlingException",
201 schedule: Schedule.max([Schedule.exponential("1 second"), Schedule.recurs(5)]),
202 });
203
204 export const ExportProvider = () =>
205 Provider.effect(
206 Export,
207 Effect.gen(function* () {
208 const createName = Effect.fn(function* (
209 id: string,
210 props: { exportName?: string | undefined },
211 ) {
212 return props.exportName ?? (yield* createPhysicalName({ id, maxLength: 100 }));
213 });
214
215 const buildExport = (name: string, props: ExportProps): bcm.Export => ({
216 Name: name,
217 Description: props.description,
218 DataQuery: {
219 QueryStatement: props.dataQuery.queryStatement,
220 TableConfigurations: props.dataQuery.tableConfigurations,
221 },
222 DestinationConfigurations: {
223 S3Destination: {
224 S3Bucket: props.s3Destination.s3Bucket,
225 S3Prefix: props.s3Destination.s3Prefix,
226 S3Region: props.s3Destination.s3Region,
227 S3BucketOwner: props.s3Destination.s3BucketOwner,
228 S3OutputConfigurations: {
229 OutputType: props.s3Destination.s3OutputConfigurations?.outputType ?? "CUSTOM",
230 Format: props.s3Destination.s3OutputConfigurations?.format ?? "TEXT_OR_CSV",
231 Compression: props.s3Destination.s3OutputConfigurations?.compression ?? "GZIP",
232 Overwrite:
233 props.s3Destination.s3OutputConfigurations?.overwrite ?? "OVERWRITE_REPORT",
234 },
235 },
236 },
237 RefreshCadence: {
238 Frequency: props.refreshCadence?.frequency ?? "SYNCHRONOUS",
239 },
240 });
241
242 // Project both the observed and the desired definition through the
243 // same shape (fixed key order, defaults filled) so wire echoes — key
244 // ordering, an echoed S3BucketOwner — never register as drift.
245 const normalizeExport = (e: bcm.Export): string => {
246 const dest = e.DestinationConfigurations.S3Destination;
247 return JSON.stringify({
248 Name: e.Name,
249 Description: e.Description ?? "",
250 QueryStatement: e.DataQuery.QueryStatement,
251 TableConfigurations: Object.fromEntries(
252 Object.entries(e.DataQuery.TableConfigurations ?? {})
253 .sort(([l], [r]) => l.localeCompare(r))
254 .map(([table, props]) => [
255 table,
256 Object.fromEntries(
257 Object.entries(props ?? {}).sort(([l], [r]) => l.localeCompare(r)),
258 ),
259 ]),
260 ),
261 S3Bucket: dest.S3Bucket,
262 S3Prefix: dest.S3Prefix,
263 S3Region: dest.S3Region,
264 OutputType: dest.S3OutputConfigurations.OutputType,
265 Format: dest.S3OutputConfigurations.Format,
266 Compression: dest.S3OutputConfigurations.Compression,
267 Overwrite: dest.S3OutputConfigurations.Overwrite,
268 Frequency: e.RefreshCadence.Frequency,
269 });
270 };
271 // S3BucketOwner is compared only when the user sets it — AWS may echo
272 // the effective owner account on reads even when it was never supplied.
273 const sameExport = (live: bcm.Export, desired: bcm.Export): boolean =>
274 normalizeExport(live) === normalizeExport(desired) &&
275 (desired.DestinationConfigurations.S3Destination.S3BucketOwner === undefined ||
276 desired.DestinationConfigurations.S3Destination.S3BucketOwner ===
277 live.DestinationConfigurations.S3Destination.S3BucketOwner);
278
279 const findArnByName = Effect.fn(function* (name: string) {
280 const matches = yield* bcm.listExports.items({}).pipe(
281 Stream.filter((e) => e.ExportName === name),
282 Stream.take(1),
283 Stream.runCollect,
284 );
285 return Array.from(matches)[0]?.ExportArn;
286 });
287
288 // Observe the live export definition. `arnHint` (from cached output)
289 // is verified, not trusted — a stale ARN falls through to name lookup.
290 const observe = Effect.fn(function* (name: string, arnHint: string | undefined) {
291 const arns = arnHint !== undefined ? [arnHint] : [];
292 const byName = yield* findArnByName(name);
293 if (byName !== undefined && byName !== arnHint) arns.push(byName);
294 for (const arn of arns) {
295 const found = yield* bcm
296 .getExport({ ExportArn: arn })
297 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
298 if (found?.Export !== undefined) {
299 return { exportArn: arn, export: found.Export };
300 }
301 }
302 return undefined;
303 });
304
305 const fetchObservedTags = Effect.fn(function* (arn: string) {
306 return yield* bcm.listTagsForResource({ ResourceArn: arn }).pipe(
307 Effect.map((r) =>
308 Object.fromEntries((r.ResourceTags ?? []).map((t) => [t.Key, t.Value])),
309 ),
310 Effect.catchTag("ResourceNotFoundException", () =>
311 Effect.succeed({} as Record<string, string>),
312 ),
313 );
314 });
315
316 return Export.Provider.of({
317 stables: ["exportName", "exportArn"],
318 list: () =>
319 bcm.listExports.items({}).pipe(
320 Stream.runCollect,
321 Effect.map((chunk) =>
322 Array.from(chunk).map((e) => ({
323 exportName: e.ExportName,
324 exportArn: e.ExportArn,
325 })),
326 ),
327 ),
328 read: Effect.fn(function* ({ id, olds, output }) {
329 const name = output?.exportName ?? (yield* createName(id, olds ?? {}));
330 const live = yield* observe(name, output?.exportArn);
331 if (live === undefined) return undefined;
332 const attrs = { exportName: name, exportArn: live.exportArn };
333 const tags = yield* fetchObservedTags(live.exportArn);
334 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
335 }),
336 // Replacement detection only — the export name is immutable; every
337 // other property updates in place via updateExport.
338 diff: Effect.fn(function* ({ id, news, olds }) {
339 if (!isResolved(news)) return undefined;
340 const oldName = yield* createName(id, olds);
341 const newName = yield* createName(id, news);
342 if (oldName !== newName) return { action: "replace" } as const;
343 }),
344 reconcile: Effect.fn(function* ({ id, news, output, session }) {
345 const name = output?.exportName ?? (yield* createName(id, news));
346 const internalTags = yield* createInternalTags(id);
347 const desiredTags = { ...news.tags, ...internalTags };
348 const desired = buildExport(name, news);
349
350 // 1. OBSERVE — cloud state is authoritative; output only caches
351 // the ARN.
352 const live = yield* observe(name, output?.exportArn);
353
354 let exportArn: string;
355 if (live === undefined) {
356 // 2. ENSURE — create the export with all tags attached.
357 yield* session.note(`creating data export ${name}`);
358 const created = yield* retryThrottling(
359 bcm.createExport({
360 Export: desired,
361 ResourceTags: Object.entries(desiredTags).map(([Key, Value]) => ({ Key, Value })),
362 }),
363 );
364 exportArn = created.ExportArn ?? (yield* findArnByName(name)) ?? name;
365 } else {
366 exportArn = live.exportArn;
367 // 3. SYNC — updateExport overwrites the full definition; skip
368 // the call when the observed definition already matches.
369 if (!sameExport(live.export, desired)) {
370 yield* session.note(`updating data export ${name}`);
371 yield* retryThrottling(bcm.updateExport({ ExportArn: exportArn, Export: desired }));
372 }
373 }
374
375 // 3b. SYNC TAGS — diff against observed cloud tags.
376 const observedTags = yield* fetchObservedTags(exportArn);
377 const { upsert, removed } = diffTags(observedTags, desiredTags);
378 if (upsert.length > 0) {
379 yield* bcm.tagResource({
380 ResourceArn: exportArn,
381 ResourceTags: upsert,
382 });
383 }
384 if (removed.length > 0) {
385 yield* bcm.untagResource({
386 ResourceArn: exportArn,
387 ResourceTagKeys: removed,
388 });
389 }
390
391 yield* session.note(name);
392 return { exportName: name, exportArn };
393 }),
394 delete: Effect.fn(function* ({ output }) {
395 yield* bcm
396 .deleteExport({ ExportArn: output.exportArn })
397 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
398 }),
399 });
400 }),
401 );