@arkebcacy/beacon-cli-temp 0.1.1

package/src/cs/api/fileUploadInit.ts

@@ -0,0 +1,19 @@
+const fileUploadInit = {
+	bodySerializer(body: Record<string, string>) {
+		const fd = new FormData();
+
+		for (const [name, value] of Object.entries(body)) {
+			fd.append(
+				name,
+				new Blob([value], {
+					endings: 'transparent',
+					type: 'application/json',
+				}),
+			);
+		}
+
+		return fd;
+	},
+};
+
+export default fileUploadInit;

package/src/cs/api/paginate/ApiResponse.ts

@@ -0,0 +1,4 @@
+export default interface ApiResponse {
+	readonly data?: unknown;
+	readonly error?: unknown;
+}

package/src/cs/api/paginate/Batch.ts

@@ -0,0 +1,18 @@
+import type { Item } from '#cli/cs/Types.js';
+
+// Items is a _filtered_ list. We occasionally see:
+//
+//   - Entries with no data, in which all fields (including the title)
+//     are empty.
+//
+//   - Duplicate entries, in which all fields including the uid are identical.
+//
+// The `mapFn` parameter is responsible for filtering out these items and
+// returning this `Batch` object. The `items` property has invalid items
+// removed, but the `processedItemCount` property must include a count of
+// _all_ items so that we can paginate propertly.
+export default interface Batch<TItem extends Item> {
+	readonly count?: number;
+	readonly items: readonly TItem[];
+	readonly processedItemCount?: number;
+}

package/src/cs/api/paginate/createAccumulator.ts

@@ -0,0 +1,26 @@
+import type { Item } from '#cli/cs/Types.js';
+import duplicateItemHandler from './duplicateItemHandler.js';
+
+export default function createAccumulator<TItem extends Item>(
+	pluralNoun: string,
+	keyFn: (item: TItem) => string,
+	equality: (a: TItem, b: TItem) => boolean,
+) {
+	const acc = new Map<string, TItem>();
+
+	const handleDuplicateItems = (key: string, item: TItem) =>
+		duplicateItemHandler(pluralNoun, acc, equality, key, item);
+
+	return {
+		add(items: readonly TItem[]) {
+			for (const item of items) {
+				const key = keyFn(item);
+				handleDuplicateItems(key, item);
+				acc.set(key, item);
+			}
+		},
+		get result(): ReadonlyMap<string, TItem> {
+			return acc;
+		},
+	};
+}

package/src/cs/api/paginate/duplicateItemHandler.ts

@@ -0,0 +1,49 @@
+import type { Item } from '#cli/cs/Types.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import HandledError from '#cli/ui/HandledError.js';
+import { inspect, styleText } from 'node:util';
+
+export default function duplicateItemHandler<TItem extends Item>(
+	pluralNoun: string,
+	acc: ReadonlyMap<string, TItem>,
+	equality: (a: TItem, b: TItem) => boolean,
+	key: string,
+	item: TItem,
+) {
+	const existing = acc.get(key);
+
+	if (existing === undefined) {
+		return;
+	}
+
+	const msgs = ['Encountered a duplicate item while indexing '];
+	msgs.push(styleText('yellowBright', pluralNoun));
+	msgs.push(' by key: ');
+
+	if (key === '') {
+		msgs.push(styleText('dim', '[empty string]'));
+	} else {
+		msgs.push(styleText('yellow', key));
+	}
+
+	msgs.push('.');
+
+	if (equality(existing, item)) {
+		getUi().warn(msgs.join(''));
+		return;
+	}
+
+	msgs.push('\nThis is fatal because the items are not equal!\n');
+	msgs.push(styleText('bold', 'First'));
+	msgs.push(': ');
+	msgs.push(inspect(existing, { colors: true, depth: Infinity }));
+
+	msgs.push('\n');
+	msgs.push(styleText('bold', 'Second'));
+	msgs.push(': ');
+	msgs.push(inspect(item, { colors: true, depth: Infinity }));
+
+	const msg = msgs.join('');
+
+	throw new HandledError(msg);
+}

package/src/cs/api/paginate/readBatch.ts

@@ -0,0 +1,21 @@
+import type { Item } from '#cli/cs/Types.js';
+import isRecord from '#cli/util/isRecord.js';
+import ContentstackError from '../ContentstackError.js';
+import type ApiResponse from './ApiResponse.js';
+import type Batch from './Batch.js';
+
+export default async function readBatch<TItem extends Item>(
+	pluralNoun: string,
+	fetchFn: (skip: number) => Promise<ApiResponse>,
+	mapFn: (data: Record<string, unknown>) => Batch<TItem>,
+	skip = 0,
+): Promise<Batch<TItem>> {
+	const { data, error } = await fetchFn(skip);
+	ContentstackError.throwIfError(error, `Failed to get ${pluralNoun}`);
+
+	if (!isRecord(data)) {
+		throw new Error('Invalid response from Contentstack');
+	}
+
+	return mapFn(data);
+}

package/src/cs/api/paginate/readPaginatedItems.ts

@@ -0,0 +1,64 @@
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import ProgressReporter from '#cli/ui/progress/ProgressReporter.js';
+import { isDeepStrictEqual } from 'node:util';
+import type { Item } from '../../Types.js';
+import type ApiResponse from './ApiResponse.js';
+import type Batch from './Batch.js';
+import createAccumulator from './createAccumulator.js';
+import readBatch from './readBatch.js';
+
+export default async function readPaginatedItems<TItem extends Item>(
+	pluralNoun: string,
+	keyFn: (item: TItem) => string,
+	fetchFn: (skip: number) => Promise<ApiResponse>,
+	mapFn: (data: Record<string, unknown>) => Batch<TItem>,
+	equality: (a: TItem, b: TItem) => boolean = isDeepStrictEqual,
+): Promise<ReadonlyMap<string, TItem>> {
+	const batchFn = async (skip = 0) =>
+		readBatch(pluralNoun, fetchFn, mapFn, skip);
+
+	let batch = await batchFn();
+	const total = batch.count ?? 0;
+
+	const acc = createAccumulator<TItem>(pluralNoun, keyFn, equality);
+	acc.add(batch.items);
+	let processedThisBatch = calculateProcessedItemCount(batch);
+	let processedInTotal = processedThisBatch;
+
+	// Early exit that avoids the progress bar.
+	if (processedInTotal >= total) {
+		return acc.result;
+	}
+
+	const ui = getUi();
+	using bar = ui.createProgressBar(capitalize(pluralNoun), total);
+	using reporter = new ProgressReporter(bar, 'Loading', pluralNoun);
+	bar.increment(processedThisBatch);
+
+	while (processedInTotal < total) {
+		batch = await batchFn(processedInTotal);
+		processedThisBatch = calculateProcessedItemCount(batch);
+
+		if (processedThisBatch === 0) {
+			ui.warn('Received an empty batch while loading ' + pluralNoun);
+			break;
+		}
+
+		processedInTotal += processedThisBatch;
+		bar.increment(processedThisBatch);
+		acc.add(batch.items);
+	}
+
+	reporter.finish('Loaded');
+	return acc.result;
+}
+
+function capitalize(s: string) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function calculateProcessedItemCount<TItem extends Item>(
+	batch: Batch<TItem>,
+): number {
+	return Math.max(0, batch.processedItemCount ?? batch.items.length);
+}

package/src/cs/api/stall/ApiTimeoutError.ts

@@ -0,0 +1,5 @@
+export default class ApiTimeoutError extends Error {
+	public constructor() {
+		super('API timeout');
+	}
+}

package/src/cs/api/stall/RequestWithTimeout.ts

@@ -0,0 +1,22 @@
+import ApiTimeoutError from './ApiTimeoutError.js';
+
+export default class RequestWithTimeout extends Request implements Disposable {
+	readonly #timer: NodeJS.Timeout;
+
+	public constructor(request: Request, timeout: number) {
+		const controller = new AbortController();
+
+		super(request, {
+			signal: AbortSignal.any([request.signal, controller.signal]),
+		});
+
+		this.#timer = setTimeout(
+			() => controller.abort(new ApiTimeoutError()),
+			timeout,
+		);
+	}
+
+	[Symbol.dispose](): void {
+		clearTimeout(this.#timer);
+	}
+}

package/src/cs/api/stall/TimeoutAndRetryBehavior.ts

@@ -0,0 +1,44 @@
+import EventEmitter from 'node:events';
+import ApiTimeoutError from './ApiTimeoutError.js';
+import RequestWithTimeout from './RequestWithTimeout.js';
+
+const maxAttempts = 5; // arbitrary.
+
+interface EventMap {
+	readonly 'stall-encountered': [Request, number, number];
+	readonly 'stall-failed': [Request];
+}
+
+export default class TimeoutAndRetryBehavior extends EventEmitter<EventMap> {
+	public constructor(private readonly _timeout: number) {
+		super();
+	}
+
+	public async fetch(...args: Parameters<typeof fetch>) {
+		const [original] = args;
+
+		if (!(original instanceof Request)) {
+			throw new TypeError('Expected input to be a Request');
+		}
+
+		let attempts = 0;
+
+		do {
+			using antiStallRequest = new RequestWithTimeout(original, this._timeout);
+
+			try {
+				return await fetch(antiStallRequest);
+			} catch (ex: unknown) {
+				if (!(ex instanceof ApiTimeoutError)) {
+					throw ex;
+				}
+
+				attempts += 1;
+				this.emit('stall-encountered', original, attempts, maxAttempts);
+			}
+		} while (attempts < maxAttempts);
+
+		this.emit('stall-failed', original);
+		throw new ApiTimeoutError();
+	}
+}

package/src/cs/assets/Assets.ts

@@ -0,0 +1,152 @@
+import type Client from '../api/Client.js';
+import createAsset from './create.js';
+import createFolder from './createFolder.js';
+import deleteAsset from './delete.js';
+import deleteFolder from './deleteFolder.js';
+import indexByParent from './lib/indexByParent.js';
+import resolveRawAssetItem from './lib/resolveRawAssetItem.js';
+import type { RawAsset, RawAssetItem, RawFolder } from './Types.js';
+import { isRawAsset } from './Types.js';
+
+export interface ReadonlyAssets {
+	readonly byUid: ReadonlyMap<RawAssetItem['uid'], RawAssetItem>;
+
+	readonly byParentUid: ReadonlyMap<
+		RawAssetItem['parent_uid'],
+		ReadonlySet<RawAssetItem>
+	>;
+
+	descendant(uid: RawAssetItem['parent_uid']): Generator<RawAssetItem>;
+	descendantOrSelf(uid: RawAssetItem['parent_uid']): Generator<RawAssetItem>;
+}
+
+export default class Assets implements ReadonlyAssets {
+	readonly #byUid: Map<RawAssetItem['uid'], RawAssetItem>;
+
+	readonly #byParentUid: Map<RawAssetItem['parent_uid'], Set<RawAssetItem>>;
+
+	public constructor(
+		private readonly client: Client,
+		initialByUid: ReadonlyMap<RawAssetItem['uid'], RawAssetItem>,
+	) {
+		this.#byUid = new Map(initialByUid);
+		const byParent = indexByParent(initialByUid);
+		this.#byParentUid = new Map([...byParent].map(([k, v]) => [k, new Set(v)]));
+	}
+
+	public get byUid(): ReadonlyMap<RawAssetItem['uid'], RawAssetItem> {
+		return this.#byUid;
+	}
+
+	public get byParentUid(): ReadonlyMap<
+		RawAssetItem['parent_uid'],
+		ReadonlySet<RawAssetItem>
+	> {
+		return this.#byParentUid;
+	}
+
+	async createAsset(
+		newAsset: Parameters<typeof createAsset>[1],
+	): Promise<RawAsset> {
+		const created = await createAsset(this.client, newAsset);
+		this.#byUid.set(created.uid, created);
+
+		const { parent_uid: parentUid } = created;
+		if (parentUid) {
+			const parent = this.#byParentUid.get(parentUid);
+			if (!parent) {
+				throw new Error('Parent folder not found');
+			}
+
+			parent.add(created);
+		} else {
+			const parent = this.#byParentUid.get(null);
+
+			if (parent) {
+				parent.add(created);
+			} else {
+				this.#byParentUid.set(null, new Set([created]));
+			}
+		}
+
+		return created;
+	}
+
+	async createFolder(
+		name: RawFolder['name'],
+		parentUid: RawFolder['parent_uid'],
+	): Promise<RawAssetItem> {
+		const created = await createFolder(this.client, name, parentUid);
+
+		const parent = this.#byParentUid.get(parentUid);
+		if (parentUid) {
+			if (!parent) {
+				throw new Error('Parent folder not found');
+			}
+
+			parent.add(created);
+		} else if (parent) {
+			parent.add(created);
+		} else {
+			this.#byParentUid.set(null, new Set([created]));
+		}
+
+		this.#byUid.set(created.uid, created);
+		this.#byParentUid.set(created.uid, new Set());
+		return created;
+	}
+
+	async deleteAsset(itemPath: string) {
+		const item = resolveRawAssetItem(this.#byParentUid, itemPath);
+
+		if (!item || !isRawAsset(item)) {
+			throw new Error(`Item not found: ${itemPath}`);
+		}
+
+		const { parent_uid: parentUid, uid } = item;
+
+		await deleteAsset(this.client, uid);
+		this.#byUid.delete(uid);
+
+		const siblings = this.#byParentUid.get(parentUid);
+		if (!siblings) {
+			throw new Error('Parent folder not found');
+		}
+
+		siblings.delete(item);
+
+		if (siblings.size === 0 && parentUid) {
+			await this.deleteFolder(parentUid);
+		}
+	}
+
+	async deleteFolder(uid: RawFolder['uid']) {
+		await deleteFolder(this.client, uid);
+
+		[...this.descendantOrSelf(uid)].forEach((item) => {
+			this.#byUid.delete(item.uid);
+			this.#byParentUid.delete(uid);
+		});
+	}
+
+	*descendantOrSelf(uid: RawAssetItem['parent_uid']): Generator<RawAssetItem> {
+		yield* this.descendant(uid);
+
+		const self = uid ? this.#byUid.get(uid) : undefined;
+		if (self) {
+			yield self;
+		}
+	}
+
+	*descendant(uid: RawAssetItem['parent_uid']): Generator<RawAssetItem> {
+		const children = this.#byParentUid.get(uid);
+
+		for (const child of children ?? []) {
+			if (isRawAsset(child)) {
+				yield child;
+			} else {
+				yield* this.descendantOrSelf(child.uid);
+			}
+		}
+	}
+}

package/src/cs/assets/Types.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { isRawAsset } from './Types.js';
+
+describe('isRawAsset', () => {
+	it('can validate a RawAsset', () => {
+		// Arrange
+		const fixture = {
+			ACL: {},
+			_version: 1,
+			content_type: 'image/webp',
+			created_at: '2024-10-07T14:48:31.160Z',
+			created_by: 'blte1f9f862a5105eca',
+			file_size: '71498',
+			filename: 'Mariel.webp',
+			is_dir: false,
+			parent_uid: null,
+			tags: [],
+			title: 'Mariel.webp',
+			uid: 'blte7604d9ccee2b73b',
+			updated_at: '2024-10-07T14:48:31.160Z',
+			updated_by: 'blte1f9f862a5105eca',
+			url: 'https://images.contentstack.io/etc/etc/etc/Mariel.webp',
+		};
+
+		// Act
+		const result = isRawAsset(fixture);
+
+		// Assert
+		expect(result).toBe(true);
+	});
+});

package/src/cs/assets/Types.ts

@@ -0,0 +1,69 @@
+import type { Item } from '../Types.js';
+import { isItem } from '../Types.js';
+
+export interface RawBase extends Item {
+	readonly _version: number;
+	readonly ACL: unknown;
+	readonly content_type: string;
+	readonly created_at: string;
+	readonly created_by: string;
+	readonly parent_uid: string | null;
+	readonly tags: readonly string[];
+	readonly updated_at: string;
+	readonly updated_by: string;
+}
+
+function isRawBase(o: unknown): o is RawBase {
+	if (!isItem(o)) {
+		return false;
+	}
+
+	return (
+		typeof o._version === 'number' &&
+		'ACL' in o &&
+		typeof o.content_type === 'string' &&
+		typeof o.created_at === 'string' &&
+		typeof o.created_by === 'string' &&
+		(o.parent_uid === null || typeof o.parent_uid === 'string') &&
+		Array.isArray(o.tags) &&
+		o.tags.every((t) => typeof t === 'string') &&
+		typeof o.updated_at === 'string' &&
+		typeof o.updated_by === 'string'
+	);
+}
+
+export interface RawFolder extends RawBase {
+	readonly is_dir: true;
+	readonly name: string;
+}
+
+export function isRawFolder(o: unknown): o is RawFolder {
+	return isRawBase(o) && Boolean(o.is_dir) && typeof o.name === 'string';
+}
+
+export interface RawAsset extends RawBase {
+	readonly description?: string | undefined;
+	readonly file_size: string;
+	readonly filename: string;
+	readonly is_dir: false;
+	readonly title: string;
+	readonly url: string;
+}
+
+export function isRawAsset(o: unknown): o is RawAsset {
+	return (
+		isRawBase(o) &&
+		(o.description === undefined || typeof o.description === 'string') &&
+		typeof o.file_size === 'string' &&
+		typeof o.filename === 'string' &&
+		!o.is_dir &&
+		typeof o.title === 'string' &&
+		typeof o.url === 'string'
+	);
+}
+
+export type RawAssetItem = RawAsset | RawFolder;
+
+export function isRawAssetItem(o: unknown): o is RawAssetItem {
+	return isRawAsset(o) || isRawFolder(o);
+}

package/src/cs/assets/create.ts

@@ -0,0 +1,46 @@
+import isRecord from '#cli/util/isRecord.js';
+import type Client from '../api/Client.js';
+import type { operations } from '../api/cma-openapi-3.js';
+import ContentstackError from '../api/ContentstackError.js';
+import assetBody from './lib/assetBody.js';
+import type { RawAsset } from './Types.js';
+import { isRawAsset } from './Types.js';
+
+type SettableFields = 'description' | 'parent_uid' | 'tags' | 'title';
+type Operation = operations['uploadasset'];
+type Body = Operation['requestBody']['content']['multipart/form-data'];
+
+type NewAsset = Partial<Pick<RawAsset, SettableFields>> & {
+	readonly filePath: string;
+};
+
+export default async function create(client: Client, newAsset: NewAsset) {
+	const body = await assetBody(newAsset);
+
+	const { data, error, response } = await client.POST('/v3/assets', {
+		// as unknown as Body because the typing in the OpenAPI spec gets
+		// tricky with FormData
+		body: body as unknown as Body,
+	});
+
+	const msg = `Failed to create asset: ${newAsset.filePath}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+
+	const result = data as unknown;
+
+	if (!isRecord(result)) {
+		throw new Error(msg);
+	}
+
+	const { asset } = result;
+
+	if (!isRawAsset(asset)) {
+		throw new Error(msg);
+	}
+
+	return asset;
+}

package/src/cs/assets/createFolder.ts

@@ -0,0 +1,39 @@
+import isRecord from '#cli/util/isRecord.js';
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import type { RawFolder } from './Types.js';
+import { isRawFolder } from './Types.js';
+
+export default async function createFolder(
+	client: Client,
+	name: string,
+	parentUid?: string | null,
+): Promise<RawFolder> {
+	const response = await client.POST('/v3/assets/folders', {
+		body: {
+			asset: {
+				...(typeof parentUid === 'string' ? { parent_uid: parentUid } : {}),
+				name,
+			},
+		},
+	});
+
+	ContentstackError.throwIfError(
+		response.error,
+		'Failed to create asset folder: ' + name,
+	);
+
+	const result = response.data as unknown;
+
+	if (!isRecord(result) || !result.asset) {
+		throw new Error('Invalid response from Contentstack');
+	}
+
+	const { asset: folder } = result;
+
+	if (!isRawFolder(folder)) {
+		throw new Error('Invalid response from Contentstack');
+	}
+
+	return folder;
+}

package/src/cs/assets/delete.ts

@@ -0,0 +1,15 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+
+export default async function deleteAsset(client: Client, uid: string) {
+	const { error, response } = await client.DELETE('/v3/assets/{asset_uid}', {
+		params: { path: { asset_uid: uid } },
+	});
+
+	const msg = `Failed to delete asset: ${uid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/assets/deleteFolder.ts

@@ -0,0 +1,19 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+
+export default async function deleteFolder(
+	client: Client,
+	folderUid: string,
+): Promise<void> {
+	const { error, response } = await client.DELETE(
+		'/v3/assets/folders/{folder_uid}',
+		{ params: { path: { folder_uid: folderUid } } },
+	);
+
+	const msg = `Failed to delete asset folder: ${folderUid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}