@arkebcacy/beacon-cli-temp 0.1.1

package/src/cs/entryWalker/lib/node.ts

@@ -0,0 +1,70 @@
+import type { SchemaFields } from '#cli/cs/Types.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import createStylus from '#cli/ui/createStylus.js';
+import type EntryWalker from '../EntryWalker.js';
+
+export default function node(
+	this: EntryWalker,
+	schema: SchemaFields,
+	container: Record<string, unknown>,
+) {
+	const ctx: NodeContext = {
+		container,
+		properties: new Map<string, unknown>(),
+		schema,
+		seen: new Set<string>(),
+	};
+
+	handleContainerProperties.call(this, ctx);
+	handleSchemaProperties.call(this, ctx);
+
+	const { properties } = ctx;
+	return properties.size ? Object.fromEntries(properties) : undefined;
+}
+
+interface NodeContext {
+	readonly container: Record<string, unknown>;
+	readonly properties: Map<string, unknown>;
+	readonly schema: SchemaFields;
+	readonly seen: Set<string>;
+}
+
+function handleContainerProperties(this: EntryWalker, ctx: NodeContext) {
+	for (const [fieldUid, value] of Object.entries(ctx.container)) {
+		ctx.seen.add(fieldUid);
+
+		if (fieldUid === '_metadata') {
+			ctx.properties.set(fieldUid, value);
+			continue;
+		}
+
+		const field = ctx.schema.find((f) => f.uid === fieldUid);
+		if (!field) {
+			const y = createStylus('yellowBright');
+			const msg1 = y`Entry ${this.context} contains a field named`;
+			const msg2 = y`${fieldUid} which is not defined in the schema.`;
+			getUi().warn(msg1, msg2);
+			ctx.properties.set(fieldUid, value);
+			continue;
+		}
+
+		const processed = this.field(field, value);
+
+		if (processed !== undefined) {
+			ctx.properties.set(fieldUid, processed);
+		}
+	}
+}
+
+function handleSchemaProperties(this: EntryWalker, ctx: NodeContext) {
+	for (const field of ctx.schema) {
+		if (ctx.seen.has(field.uid)) {
+			continue;
+		}
+
+		const processed = this.field(field, undefined);
+		if (processed !== undefined) {
+			ctx.properties.set(field.uid, processed);
+		}
+	}
+}

package/src/cs/entryWalker/lib/referenceBlock.ts

@@ -0,0 +1,36 @@
+import type { Item } from '#cli/cs/Types.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import createStylus from '#cli/ui/createStylus.js';
+import type EntryWalker from '../EntryWalker.js';
+
+export default function referenceBlock(
+	this: EntryWalker,
+	blockType: Item,
+	block: Record<string, unknown>,
+) {
+	const { reference_to: globalFieldUid } = blockType;
+
+	if (!globalFieldUid) {
+		return;
+	}
+
+	if (typeof globalFieldUid !== 'string') {
+		const y = createStylus('yellowBright');
+		const msg1 = y`Entry ${this.context} references modular block type`;
+		const msg2 = y`${blockType.uid} with an invalid global field reference:`;
+		getUi().warn(msg1, msg2, globalFieldUid);
+		return block;
+	}
+
+	const globalField = this.globalFieldsByUid.get(globalFieldUid);
+
+	if (!globalField) {
+		const y = createStylus('yellowBright');
+		const msg1 = y`Entry ${this.context} references a global field named`;
+		const msg2 = y`${globalFieldUid}, which does not exist.`;
+		getUi().warn(msg1, msg2);
+		return block;
+	}
+
+	return this.node(globalField.schema, block);
+}

package/src/cs/entryWalker/lib/resolveBlockTypes.ts

@@ -0,0 +1,32 @@
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import createStylus from '#cli/ui/createStylus.js';
+import type { Item, SchemaField } from '../../Types.js';
+import { isItem } from '../../Types.js';
+import type EntryWalker from '../EntryWalker.js';
+
+export default function resolveBlockTypes(
+	this: EntryWalker,
+	field: SchemaField,
+): ReadonlyMap<string, Item> | undefined {
+	if (!('blocks' in field)) {
+		const y = createStylus('yellowBright');
+		const msg1 = 'Failed to locate a modular blocks definition';
+		const msg2 = y`in entry ${this.context}:`;
+		getUi().warn(msg1, msg2, field);
+		return;
+	}
+
+	const { blocks: blockTypesArray } = field;
+	if (!Array.isArray(blockTypesArray) || !blockTypesArray.every(isItem)) {
+		const y = createStylus('yellowBright');
+		const msg1 = y`Entry ${this.context} contains an invalid modular`;
+		const msg2 = 'blocks schema:';
+		getUi().warn(msg1, msg2, field);
+		return;
+	}
+
+	return blockTypesArray.reduce(
+		(map, item) => map.set(item.uid, item),
+		new Map<string, Item>(),
+	);
+}

package/src/cs/entryWalker/lib/schemaBlock.ts

@@ -0,0 +1,25 @@
+import { type Item, isSchemaFields } from '#cli/cs/Types.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import createStylus from '#cli/ui/createStylus.js';
+import type EntryWalker from '../EntryWalker.js';
+
+export default function schemaBlock(
+	this: EntryWalker,
+	blockType: Item,
+	block: Record<string, unknown>,
+) {
+	const { schema } = blockType;
+	if (!schema) {
+		return;
+	}
+
+	if (!isSchemaFields(schema)) {
+		const y = createStylus('yellowBright');
+		const msg1 = y`Entry ${this.context} references modular block type`;
+		const msg2 = y`${blockType.uid} with an invalid schema:`;
+		getUi().warn(msg1, msg2, schema);
+		return block;
+	}
+
+	return this.node(schema, block);
+}

package/src/cs/global-fields/delete.ts

@@ -0,0 +1,21 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+
+export default async function deleteGlobalField(client: Client, uid: string) {
+	const { error, response } = await client.DELETE(
+		'/v3/global_fields/{global_field_uid}',
+		{
+			params: {
+				path: { global_field_uid: uid },
+				query: { force: 'true' },
+			},
+		},
+	);
+
+	const msg = `Failed to delete global field: ${uid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/global-fields/export.ts

@@ -0,0 +1,21 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import { isSchema } from '../Types.js';
+
+export default async function exportGlobalField(client: Client, uid: string) {
+	const { data, error } = await client.GET(
+		'/v3/global_fields/{global_field_uid}/export',
+		{ params: { path: { global_field_uid: uid } } },
+	);
+
+	const msg = `Failed to export global field: ${uid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	const result = data as unknown;
+
+	if (!isSchema(result)) {
+		throw new Error(msg);
+	}
+
+	return result;
+}

package/src/cs/global-fields/import.ts

@@ -0,0 +1,29 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import fileUploadInit from '../api/fileUploadInit.js';
+import type { Schema } from '../Types.js';
+
+export default async function importGlobalField(
+	client: Client,
+	overwrite: boolean,
+	schema: Schema,
+) {
+	// "overwrite" is undocumented but works. If left out, updates report an
+	// error prompting for its use.
+	const query: Record<string, unknown> = {
+		...(overwrite ? { overwrite: 'true' } : {}),
+	};
+
+	const { error, response } = await client.POST('/v3/global_fields/import', {
+		...fileUploadInit,
+		body: { global_field: JSON.stringify(schema) },
+		params: { query },
+	});
+
+	const msg = `Failed to import global field: ${schema.uid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/global-fields/index.ts

@@ -0,0 +1,33 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import typecheckArray from '../typecheckArray.js';
+import type { Schema } from '../Types.js';
+import { isSchema } from '../Types.js';
+
+export default async function index(
+	client: Client,
+): Promise<ReadonlyMap<Schema['uid'], Schema>> {
+	const response = await client.GET('/v3/global_fields');
+	ContentstackError.throwIfError(response.error, 'Failed to get global fields');
+
+	const result = response.data as unknown;
+
+	if (
+		typeof result !== 'object' ||
+		result === null ||
+		!('global_fields' in result)
+	) {
+		throw new Error('Invalid response from Contentstack');
+	}
+
+	const { global_fields: schemas } = result;
+
+	if (!typecheckArray(isSchema, 'global fields', schemas)) {
+		throw new Error('Invalid response from Contentstack');
+	}
+
+	return schemas.reduce(
+		(acc, schema) => acc.set(schema.uid, schema),
+		new Map(),
+	);
+}

package/src/cs/taxonomies/Taxonomy.ts

@@ -0,0 +1,17 @@
+import type { Item } from '../Types.js';
+import { isItem } from '../Types.js';
+
+export default interface Taxonomy extends Item {
+	readonly name: string;
+	readonly description: string;
+}
+
+export function isTaxonomy(o: unknown): o is Taxonomy {
+	return (
+		isItem(o) && typeof o.name === 'string' && typeof o.description === 'string'
+	);
+}
+
+export function key(o: Taxonomy) {
+	return o.uid;
+}

package/src/cs/taxonomies/TaxonomyDetail.ts

@@ -0,0 +1,25 @@
+import isRecord from '#cli/util/isRecord.js';
+import type Term from '../terms/Term.js';
+import { isTerm } from '../terms/Term.js';
+import type Taxonomy from './Taxonomy.js';
+import { isTaxonomy } from './Taxonomy.js';
+
+export default interface TaxonomyDetail {
+	readonly taxonomy: Taxonomy;
+	readonly terms: readonly Term[];
+}
+
+export function isTaxonomyDetail(
+	o: unknown,
+): o is Record<string, unknown> & TaxonomyDetail {
+	return (
+		isRecord(o) &&
+		isTaxonomy(o.taxonomy) &&
+		Array.isArray(o.terms) &&
+		o.terms.every(isTerm)
+	);
+}
+
+export function key(o: TaxonomyDetail) {
+	return o.taxonomy.uid;
+}

package/src/cs/taxonomies/delete.ts

@@ -0,0 +1,21 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+
+export default async function deleteTaxonomy(client: Client, uid: string) {
+	const { error, response } = await client.DELETE(
+		'/v3/taxonomies/{taxonomy_uid}',
+		{
+			params: {
+				path: { taxonomy_uid: uid },
+				query: { force: 'true' },
+			},
+		},
+	);
+
+	const msg = `Failed to delete taxonomy: ${uid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/taxonomies/export.ts

@@ -0,0 +1,26 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import { isTaxonomyDetail } from './TaxonomyDetail.js';
+
+export default async function exportTaxonomy(client: Client, uid: string) {
+	const { data, error } = await client.GET(
+		'/v3/taxonomies/{taxonomy_uid}/export',
+		{
+			params: {
+				path: { taxonomy_uid: uid },
+				query: { format: 'json' },
+			},
+		},
+	);
+
+	const msg = `Failed to export taxonomy: ${uid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	const result = data as unknown;
+
+	if (!isTaxonomyDetail(result)) {
+		throw new Error(msg);
+	}
+
+	return result;
+}

package/src/cs/taxonomies/import.ts

@@ -0,0 +1,22 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import fileUploadInit from '../api/fileUploadInit.js';
+import type TaxonomyDetail from './TaxonomyDetail.js';
+
+export default async function importTaxonomy(
+	client: Client,
+	content: TaxonomyDetail,
+) {
+	const { error, response } = await client.POST('/v3/taxonomies/import', {
+		// Weird casting is here because the OpenAPI definition is wrong.
+		...(fileUploadInit as unknown as Record<string, string>),
+		body: { taxonomy: JSON.stringify(content) } as unknown as undefined,
+	});
+
+	const msg = `Failed to import taxonomy: ${content.taxonomy.uid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/taxonomies/index.ts

@@ -0,0 +1,40 @@
+import type Client from '../api/Client.js';
+import readPaginatedItems from '../api/paginate/readPaginatedItems.js';
+import typecheckArray from '../typecheckArray.js';
+import { isTaxonomy, key } from './Taxonomy.js';
+
+export default async function index(client: Client) {
+	return readPaginatedItems(
+		'taxonomies',
+		key,
+		fetchFn.bind(null, client),
+		mapFn,
+	);
+}
+
+async function fetchFn(client: Client, skip: number) {
+	return client.GET('/v3/taxonomies', {
+		params: {
+			query: {
+				include_count: 'true',
+				include_referenced_entries_count: 'false',
+				include_terms_count: 'false',
+				limit: '100',
+				...(skip > 0 ? { skip: skip.toString() } : {}),
+			},
+		},
+	});
+}
+
+function mapFn(o: Record<string, unknown>) {
+	const { count, taxonomies: items } = o;
+
+	if (!typecheckArray(isTaxonomy, 'taxonomies', items)) {
+		throw new Error('Invalid response from Contentstack');
+	}
+
+	return {
+		items,
+		...(typeof count === 'number' ? { count } : {}),
+	};
+}

package/src/cs/taxonomies/update.ts

@@ -0,0 +1,29 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import type Taxonomy from './Taxonomy.js';
+
+export default async function update(client: Client, content: Taxonomy) {
+	const { error, response } = await client.PUT(
+		'/v3/taxonomies/{taxonomy_uid}',
+		{
+			body: {
+				taxonomy: {
+					description: content.description,
+					name: content.name,
+				},
+			},
+			params: {
+				path: {
+					taxonomy_uid: content.uid,
+				},
+			},
+		},
+	);
+
+	const msg = `Failed to update taxonomy: ${content.uid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/terms/Term.ts

@@ -0,0 +1,16 @@
+import type OmitIndex from '../../util/OmitIndex.js';
+import type { Item } from '../Types.js';
+import { isItem } from '../Types.js';
+
+export default interface Term extends OmitIndex<Item> {
+	readonly name: string;
+	readonly parent_uid: string | null;
+}
+
+export function isTerm(o: unknown): o is Term {
+	return (
+		isItem(o) &&
+		typeof o.name === 'string' &&
+		(o.parent_uid === null || typeof o.parent_uid === 'string')
+	);
+}

package/src/cs/terms/create.ts

@@ -0,0 +1,37 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import type Taxonomy from '../taxonomies/Taxonomy.js';
+import type Term from './Term.js';
+
+export default async function create(
+	client: Client,
+	taxonomyUid: Taxonomy['uid'],
+	term: Term,
+	order: number,
+) {
+	const { error, response } = await client.POST(
+		'/v3/taxonomies/{taxonomy_uid}/terms',
+		{
+			body: {
+				term: {
+					name: term.name,
+					order: order,
+					parent_uid: term.parent_uid,
+					uid: term.uid,
+				},
+			},
+			params: {
+				path: {
+					taxonomy_uid: taxonomyUid,
+				},
+			},
+		},
+	);
+
+	const msg = `Failed to create term: ${term.uid} in ${taxonomyUid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/terms/move.ts

@@ -0,0 +1,44 @@
+import type Client from '../api/Client.js';
+import type { operations } from '../api/cma-openapi-3.js';
+import ContentstackError from '../api/ContentstackError.js';
+import type Taxonomy from '../taxonomies/Taxonomy.js';
+import type Term from './Term.js';
+
+export default async function update(
+	client: Client,
+	taxonomyUid: Taxonomy['uid'],
+	termUid: Term['uid'],
+	parentUid: Term['parent_uid'],
+	order: number,
+) {
+	const { error, response } = await client.PUT(
+		'/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/move',
+		{
+			body: {
+				term: {
+					order,
+					parent_uid: parentUid,
+				},
+			},
+			params: {
+				path: {
+					taxonomy_uid: taxonomyUid,
+					term_uid: termUid,
+				},
+				query: { force: 'true' },
+				// "as" needed here because the type definition includes a required
+				// "header" property with an invalid value; it demands a header named
+				// "Content-Type " with the extra space at the end. The actual
+				// content type header is added automatically, and the space is an
+				// error in the specs, so this can be ignored.
+			} as operations['move/reorderaterm']['parameters'],
+		},
+	);
+
+	const msg = `Failed to update term: ${termUid} in ${taxonomyUid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/terms/remove.ts

@@ -0,0 +1,30 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import type Taxonomy from '../taxonomies/Taxonomy.js';
+import type Term from './Term.js';
+
+export default async function remove(
+	client: Client,
+	taxonomyUid: Taxonomy['uid'],
+	termUid: Term['uid'],
+) {
+	const { error, response } = await client.DELETE(
+		'/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}',
+		{
+			params: {
+				path: {
+					taxonomy_uid: taxonomyUid,
+					term_uid: termUid,
+				},
+				query: { force: 'true' },
+			},
+		},
+	);
+
+	const msg = `Failed to remove term: ${termUid} in ${taxonomyUid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/terms/update.ts

@@ -0,0 +1,31 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import type Taxonomy from '../taxonomies/Taxonomy.js';
+import type Term from './Term.js';
+
+export default async function update(
+	client: Client,
+	taxonomyUid: Taxonomy['uid'],
+	termUid: Term['uid'],
+	name: string,
+) {
+	const { error, response } = await client.PUT(
+		'/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}',
+		{
+			body: { term: { name } },
+			params: {
+				path: {
+					taxonomy_uid: taxonomyUid,
+					term_uid: termUid,
+				},
+			},
+		},
+	);
+
+	const msg = `Failed to update term: ${termUid} in ${taxonomyUid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	if (!response.ok) {
+		throw new Error(msg);
+	}
+}

package/src/cs/typecheckArray.ts

@@ -0,0 +1,31 @@
+import createStylus from '#cli/ui/createStylus.js';
+import HandledError from '#cli/ui/HandledError.js';
+
+export default function typecheckArray<T>(
+	guardFn: (o: unknown) => o is T,
+	pluralNoun: string,
+	o: unknown,
+): o is readonly T[] {
+	const y = createStylus('yellowBright');
+
+	if (!Array.isArray(o)) {
+		const t = typeof o;
+		const letter = t[0]?.toLowerCase() ?? '';
+		const article = 'aeiou'.includes(letter) ? 'an' : 'a';
+		const msg1 = y`Queried Contentstack for a list of ${pluralNoun} and `;
+		const msg2 = y`expected an ${'array'} response. Received `;
+		const msg3 = article + y` ${t} instead.`;
+		throw new HandledError(`${msg1}${msg2}${msg3}`);
+	}
+
+	for (let idx = 0; idx < o.length; idx++) {
+		if (!guardFn(o[idx])) {
+			const msg1 = y`Queried Contentstack for a list of ${pluralNoun} and `;
+			const msg2 = y`received an unexpected ${typeof o[idx]} `;
+			const msg3 = y`at index ${idx.toLocaleString()}.`;
+			throw new HandledError(`${msg1}${msg2}${msg3}`);
+		}
+	}
+
+	return true;
+}