@arkebcacy/beacon-cli-temp 0.1.5 → 0.1.7

package/package.json

@@ -50,5 +50,5 @@
     "prepack": "node ./build/prepack.js"
   },
   "type": "module",
-  "version": "0.1.5"
+  "version": "0.1.7"
 }

package/src/cs/labels/Label.ts

@@ -0,0 +1,12 @@
+import type OmitIndex from '../../util/OmitIndex.js';
+import type { Item } from '../Types.js';
+import { isItem } from '../Types.js';
+
+export default interface Label extends OmitIndex<Item> {
+	readonly name: string;
+	readonly parent: readonly string[];
+}
+
+export function isLabel(o: unknown): o is Label {
+	return isItem(o) && typeof o.name === 'string' && Array.isArray(o.parent);
+}

package/src/cs/labels/getAllLabels.ts

@@ -1,18 +1,43 @@
 import ContentstackError from '../api/ContentstackError.js';
 import type Client from '../api/Client.js';
 import isRecord from '#cli/util/isRecord.js';
+import type Label from './Label.js';
+import { isLabel } from './Label.js';
 
-export default async function getAllLabels(client: Client): Promise<unknown[]> {
+export default async function getAllLabels(client: Client): Promise<Label[]> {
 	const res = (await client.GET('/v3/labels')) as unknown;
 	const data = (res as { data?: unknown } | undefined)?.data;
 	const error = (res as { error?: unknown } | undefined)?.error;
 	const msg = `Failed to fetch labels`;
 	ContentstackError.throwIfError(error, msg);
+
+	let rawLabels: unknown[] = [];
 	if (isRecord(data) && Array.isArray(data.labels)) {
-		return data.labels as unknown[];
+		rawLabels = data.labels;
+	} else if (Array.isArray(data)) {
+		rawLabels = data;
 	}
-	if (Array.isArray(data)) {
-		return data as unknown[];
+
+	// Transform raw labels to ensure they have parent_uid (null if not present)
+	const labels: Label[] = [];
+	for (const raw of rawLabels) {
+		if (
+			isRecord(raw) &&
+			typeof raw.uid === 'string' &&
+			typeof raw.name === 'string'
+		) {
+			// Preserve all fields from the remote label
+			const label: Label = {
+				...raw,
+				name: raw.name,
+				parent: Array.isArray(raw.parent) ? raw.parent : [],
+				uid: raw.uid,
+			};
+			if (isLabel(label)) {
+				labels.push(label);
+			}
+		}
 	}
-	return [];
+
+	return labels;
 }

package/src/cs/locales/addLocale.ts

@@ -0,0 +1,59 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import isRecord from '#cli/util/isRecord.js';
+import type { Locale } from './getLocales.js';
+
+interface AddLocaleRequest {
+	readonly locale: {
+		readonly code: string;
+		readonly fallback_locale?: string;
+		readonly name?: string;
+	};
+}
+
+/**
+ * Adds a new locale to the stack.
+ * @param client - Contentstack API client
+ * @param code - Locale code (e.g., 'zh-cn', 'zh-chs')
+ * @param name - Display name for the locale (e.g., 'Chinese - China')
+ * @param fallbackLocale - Optional fallback locale code
+ */
+export async function addLocale(
+	client: Client,
+	code: string,
+	name?: string,
+	fallbackLocale?: string,
+): Promise<Locale> {
+	const requestBody: AddLocaleRequest = {
+		locale: {
+			code,
+			...(fallbackLocale !== undefined && { fallback_locale: fallbackLocale }),
+			...(name !== undefined && { name }),
+		},
+	};
+
+	const response = await client.POST('/v3/locales', {
+		body: requestBody as never,
+	});
+
+	const msg = `Failed to add locale '${code}'`;
+	ContentstackError.throwIfError(response.error, msg);
+
+	if (!response.response.ok) {
+		throw new Error(msg);
+	}
+
+	const { data } = response;
+
+	if (!isRecord(data)) {
+		throw new TypeError(msg);
+	}
+
+	const { locale } = data;
+
+	if (!isRecord(locale)) {
+		throw new TypeError(msg);
+	}
+
+	return locale as Locale;
+}

package/src/cs/locales/ensureLocaleExists.ts

@@ -0,0 +1,51 @@
+import type Client from '../api/Client.js';
+import { addLocale } from './addLocale.js';
+import { getLocales } from './getLocales.js';
+import type { Locale } from './getLocales.js';
+
+/**
+ * Ensures a locale exists in the target stack. If it doesn't exist, creates it.
+ * @param client - Contentstack API client
+ * @param localeCode - Locale code to ensure exists (e.g., 'zh-cn')
+ * @param fallbackLocale - Optional fallback locale code (defaults to 'en-us')
+ * @returns The locale object (either existing or newly created)
+ */
+export async function ensureLocaleExists(
+	client: Client,
+	localeCode: string,
+	fallbackLocale = 'en-us',
+): Promise<Locale> {
+	const existingLocales = await getLocales(client);
+	const existing = existingLocales.find((loc) => loc.code === localeCode);
+
+	if (existing !== undefined) {
+		return existing;
+	}
+
+	// Locale doesn't exist - create it
+
+	// Derive a reasonable display name from the locale code
+	const name = deriveLocaleName(localeCode);
+
+	const newLocale = await addLocale(client, localeCode, name, fallbackLocale);
+
+	return newLocale;
+}
+
+/**
+ * Derives a human-readable name from a locale code.
+ * This is a basic implementation that can be expanded as needed.
+ */
+function deriveLocaleName(code: string): string {
+	const nameMap: Record<string, string> = {
+		'en-us': 'English - United States',
+		'zh-chs': 'Chinese (simplified)',
+		'zh-cht': 'Chinese (traditional)',
+		'zh-cn': 'Chinese - China',
+		'zh-hans': 'Chinese (simplified)',
+		'zh-hant': 'Chinese (traditional)',
+		'zh-tw': 'Chinese - Taiwan',
+	};
+
+	return nameMap[code.toLowerCase()] ?? code.toUpperCase();
+}

package/src/cs/locales/getLocales.ts

@@ -0,0 +1,38 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import isRecord from '#cli/util/isRecord.js';
+
+export interface Locale {
+	readonly code: string;
+	readonly fallback_locale?: string;
+	readonly name: string;
+	readonly uid: string;
+}
+
+/**
+ * Fetches all locales configured for a stack.
+ */
+export async function getLocales(client: Client): Promise<readonly Locale[]> {
+	const response = await client.GET('/v3/locales', {});
+
+	const msg = 'Failed to fetch locales';
+	ContentstackError.throwIfError(response.error, msg);
+
+	if (!response.response.ok) {
+		throw new Error(msg);
+	}
+
+	const { data } = response;
+
+	if (!isRecord(data)) {
+		throw new TypeError(msg);
+	}
+
+	const { locales } = data;
+
+	if (!Array.isArray(locales)) {
+		throw new TypeError(msg);
+	}
+
+	return locales as Locale[];
+}

package/src/dto/labels/NormalizedLabels.ts

@@ -0,0 +1,47 @@
+import isRecord from '#cli/util/isRecord.js';
+import type Label from '#cli/cs/labels/Label.js';
+import { isItem } from '#cli/cs/Types.js';
+
+export default interface NormalizedLabels {
+	readonly labels: readonly LabelTreeNode[];
+}
+
+export interface LabelTreeNode {
+	// Allow any additional fields from the label
+	readonly [key: string]: unknown;
+	readonly uid: Label['uid'];
+	readonly name: Label['name'];
+	readonly children?: readonly LabelTreeNode[];
+}
+
+export function key() {
+	return 'labels';
+}
+
+export function isNormalizedLabels(
+	value: unknown,
+): value is NormalizedLabels & Record<string, unknown> {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	return Array.isArray(value.labels) && value.labels.every(isLabelTreeNode);
+}
+
+function isLabelTreeNode(value: unknown): value is LabelTreeNode {
+	if (!isItem(value)) {
+		return false;
+	}
+
+	if (typeof value.name !== 'string') {
+		return false;
+	}
+
+	if (!('children' in value)) {
+		return true;
+	}
+
+	const { children } = value;
+
+	return Array.isArray(children) && children.every(isLabelTreeNode);
+}

package/src/dto/labels/flatten.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import flatten from './flatten.js';
+import type { LabelTreeNode } from './NormalizedLabels.js';
+
+describe('flatten', () => {
+	it('flattens a simple hierarchy', () => {
+		const tree: LabelTreeNode[] = [
+			{
+				children: [
+					{ name: 'Child 1', uid: 'child1' },
+					{ name: 'Child 2', uid: 'child2' },
+				],
+				name: 'Parent',
+				uid: 'parent',
+			},
+		];
+
+		const result = flatten(tree);
+
+		expect(result).toEqual([
+			{ name: 'Parent', parent: [], uid: 'parent' },
+			{ name: 'Child 1', parent: ['parent'], uid: 'child1' },
+			{ name: 'Child 2', parent: ['parent'], uid: 'child2' },
+		]);
+	});
+
+	it('flattens nested hierarchy', () => {
+		const tree: LabelTreeNode[] = [
+			{
+				children: [
+					{ name: 'Calculator', uid: 'calculator' },
+					{ name: 'Data', uid: 'data' },
+					{ name: 'Page', uid: 'page' },
+				],
+				name: 'Component',
+				uid: 'component',
+			},
+		];
+
+		const result = flatten(tree);
+
+		expect(result).toEqual([
+			{ name: 'Component', parent: [], uid: 'component' },
+			{ name: 'Calculator', parent: ['component'], uid: 'calculator' },
+			{ name: 'Data', parent: ['component'], uid: 'data' },
+			{ name: 'Page', parent: ['component'], uid: 'page' },
+		]);
+	});
+
+	it('handles deeply nested hierarchy', () => {
+		const tree: LabelTreeNode[] = [
+			{
+				children: [
+					{
+						children: [
+							{
+								children: [{ name: 'Level 3', uid: 'level3' }],
+								name: 'Level 2',
+								uid: 'level2',
+							},
+						],
+						name: 'Level 1',
+						uid: 'level1',
+					},
+				],
+				name: 'Root',
+				uid: 'root',
+			},
+		];
+
+		const result = flatten(tree);
+
+		expect(result).toEqual([
+			{ name: 'Root', parent: [], uid: 'root' },
+			{ name: 'Level 1', parent: ['root'], uid: 'level1' },
+			{ name: 'Level 2', parent: ['level1'], uid: 'level2' },
+			{ name: 'Level 3', parent: ['level2'], uid: 'level3' },
+		]);
+	});
+
+	it('handles multiple top-level labels', () => {
+		const tree: LabelTreeNode[] = [
+			{ name: 'Label 1', uid: 'label1' },
+			{
+				children: [{ name: 'Child', uid: 'child' }],
+				name: 'Label 2',
+				uid: 'label2',
+			},
+		];
+
+		const result = flatten(tree);
+
+		expect(result).toEqual([
+			{ name: 'Label 1', parent: [], uid: 'label1' },
+			{ name: 'Label 2', parent: [], uid: 'label2' },
+			{ name: 'Child', parent: ['label2'], uid: 'child' },
+		]);
+	});
+
+	it('handles empty array', () => {
+		const result = flatten([]);
+		expect(result).toEqual([]);
+	});
+
+	it('handles labels without children', () => {
+		const tree: LabelTreeNode[] = [
+			{ name: 'Label 1', uid: 'label1' },
+			{ name: 'Label 2', uid: 'label2' },
+		];
+
+		const result = flatten(tree);
+
+		expect(result).toEqual([
+			{ name: 'Label 1', parent: [], uid: 'label1' },
+			{ name: 'Label 2', parent: [], uid: 'label2' },
+		]);
+	});
+});

package/src/dto/labels/flatten.ts

@@ -0,0 +1,27 @@
+import type Label from '#cli/cs/labels/Label.js';
+import type { LabelTreeNode } from './NormalizedLabels.js';
+
+export default function flatten(
+	labels: readonly LabelTreeNode[],
+): readonly Label[] {
+	const result: Label[] = [];
+
+	function traverse(nodes: readonly LabelTreeNode[], parentUid: string | null) {
+		for (const node of nodes) {
+			const { children, ...label } = node;
+
+			result.push({
+				...label,
+				parent: parentUid ? [parentUid] : [],
+			} as Label);
+
+			if (children) {
+				traverse(children, node.uid);
+			}
+		}
+	}
+
+	traverse(labels, null);
+
+	return result;
+}

package/src/dto/labels/organize.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+import organize from './organize.js';
+import type Label from '#cli/cs/labels/Label.js';
+
+describe('organize', () => {
+	it('organizes flat labels into hierarchy', () => {
+		const labels: Label[] = [
+			{ name: 'Parent', parent: [], uid: 'parent' },
+			{ name: 'Child 1', parent: ['parent'], uid: 'child1' },
+			{ name: 'Child 2', parent: ['parent'], uid: 'child2' },
+		];
+
+		const result = organize(labels);
+
+		expect(result).toEqual([
+			{
+				children: [
+					{ name: 'Child 1', uid: 'child1' },
+					{ name: 'Child 2', uid: 'child2' },
+				],
+				name: 'Parent',
+				uid: 'parent',
+			},
+		]);
+	});
+
+	it('organizes component label structure from screenshot', () => {
+		const labels: Label[] = [
+			{ name: 'Component', parent: [], uid: 'component' },
+			{ name: 'Calculator', parent: ['component'], uid: 'calculator' },
+			{ name: 'Data', parent: ['component'], uid: 'data' },
+			{ name: 'Page', parent: ['component'], uid: 'page' },
+		];
+
+		const result = organize(labels);
+
+		expect(result).toEqual([
+			{
+				children: [
+					{ name: 'Calculator', uid: 'calculator' },
+					{ name: 'Data', uid: 'data' },
+					{ name: 'Page', uid: 'page' },
+				],
+				name: 'Component',
+				uid: 'component',
+			},
+		]);
+	});
+
+	it('handles deeply nested labels', () => {
+		const labels: Label[] = [
+			{ name: 'Root', parent: [], uid: 'root' },
+			{ name: 'Level 1', parent: ['root'], uid: 'level1' },
+			{ name: 'Level 2', parent: ['level1'], uid: 'level2' },
+			{ name: 'Level 3', parent: ['level2'], uid: 'level3' },
+		];
+
+		const result = organize(labels);
+
+		expect(result).toEqual([
+			{
+				children: [
+					{
+						children: [
+							{
+								children: [{ name: 'Level 3', uid: 'level3' }],
+								name: 'Level 2',
+								uid: 'level2',
+							},
+						],
+						name: 'Level 1',
+						uid: 'level1',
+					},
+				],
+				name: 'Root',
+				uid: 'root',
+			},
+		]);
+	});
+
+	it('handles multiple top-level labels', () => {
+		const labels: Label[] = [
+			{ name: 'Label 1', parent: [], uid: 'label1' },
+			{ name: 'Label 2', parent: [], uid: 'label2' },
+			{ name: 'Child', parent: ['label2'], uid: 'child' },
+		];
+
+		const result = organize(labels);
+
+		expect(result).toEqual([
+			{ name: 'Label 1', uid: 'label1' },
+			{
+				children: [{ name: 'Child', uid: 'child' }],
+				name: 'Label 2',
+				uid: 'label2',
+			},
+		]);
+	});
+
+	it('handles empty array', () => {
+		const result = organize([]);
+		expect(result).toEqual([]);
+	});
+
+	it('throws error for orphaned label', () => {
+		const labels: Label[] = [
+			{ name: 'Child', parent: ['nonexistent'], uid: 'child' },
+		];
+
+		expect(() => organize(labels)).toThrow(
+			'Orphaned label child with parent nonexistent',
+		);
+	});
+
+	it('preserves order of siblings', () => {
+		const labels: Label[] = [
+			{ name: 'Parent', parent: [], uid: 'parent' },
+			{ name: 'Child 3', parent: ['parent'], uid: 'child3' },
+			{ name: 'Child 1', parent: ['parent'], uid: 'child1' },
+			{ name: 'Child 2', parent: ['parent'], uid: 'child2' },
+		];
+
+		const result = organize(labels);
+
+		expect(result[0]?.children).toEqual([
+			{ name: 'Child 3', uid: 'child3' },
+			{ name: 'Child 1', uid: 'child1' },
+			{ name: 'Child 2', uid: 'child2' },
+		]);
+	});
+});

package/src/dto/labels/organize.ts

@@ -0,0 +1,58 @@
+import type Label from '#cli/cs/labels/Label.js';
+import type { LabelTreeNode } from './NormalizedLabels.js';
+
+// Labels have a tree structure defined by uid/parent array.
+//
+// The API returns a flat array that includes uid/parent, where parent is an array
+// containing the parent UID (or empty array for top-level labels).
+//
+// We organize labels into a tree structure for serialization.
+//
+// The sort order amongst siblings is maintained equal to the order
+// as it appears in the array.
+export default function organize(
+	labels: readonly Label[],
+): readonly LabelTreeNode[] {
+	const byUid = new Map<string, MutableNode>();
+	const topLevel: MutableNode[] = [];
+
+	for (const label of labels) {
+		const { parent, ...labelWithoutParent } = label;
+		// Preserve all fields except parent (which is represented by the tree structure)
+		byUid.set(label.uid, {
+			...labelWithoutParent,
+			name: label.name,
+			uid: label.uid,
+		});
+	}
+
+	for (const label of labels) {
+		const node = byUid.get(label.uid);
+		if (!node) {
+			throw new Error(`Label ${label.uid} not found`);
+		}
+
+		const parentUid = label.parent.length > 0 ? label.parent[0] : null;
+		if (!parentUid) {
+			topLevel.push(node);
+			continue;
+		}
+
+		const parent = byUid.get(parentUid);
+		if (!parent) {
+			const msg = `Orphaned label ${label.uid} with parent ${parentUid}`;
+			throw new Error(msg);
+		}
+
+		(parent.children ??= []).push(node);
+	}
+
+	return topLevel;
+}
+
+interface MutableNode {
+	[key: string]: unknown;
+	readonly uid: string;
+	readonly name: string;
+	children?: MutableNode[];
+}