@arkebcacy/beacon-cli-temp 0.1.1

package/src/cs/entries/getEntryLocales.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from 'vitest';
+import type Client from '../api/Client.js';
+import getEntryLocales from './getEntryLocales.js';
+
+describe('getEntryLocales', () => {
+	it('should return locales from successful API response', async () => {
+		const mockLocales = [
+			{
+				code: 'en-us',
+				name: 'English - United States',
+				uid: 'blt1234567890abcdef',
+			},
+			{
+				code: 'fr',
+				name: 'French',
+				uid: 'blt0987654321fedcba',
+			},
+		];
+
+		const mockClient = {
+			GET: vi.fn().mockResolvedValue({
+				data: { locales: mockLocales },
+				error: undefined,
+			}),
+		} as unknown as Client;
+
+		const result = await getEntryLocales(
+			mockClient,
+			'test_content_type',
+			'bltentry123',
+		);
+
+		expect(result).toEqual(mockLocales);
+		expect(mockClient.GET).toHaveBeenCalledWith(
+			'/v3/content_types/{content_type_uid}/entries/{entry_uid}/locales',
+			{
+				params: {
+					path: {
+						content_type_uid: 'test_content_type',
+						entry_uid: 'bltentry123',
+					},
+				},
+			},
+		);
+	});
+
+	it('should throw error when API returns error', async () => {
+		const mockClient = {
+			GET: vi.fn().mockResolvedValue({
+				data: undefined,
+				error: { message: 'Entry not found' },
+			}),
+		} as unknown as Client;
+
+		await expect(
+			getEntryLocales(mockClient, 'test_content_type', 'bltentry123'),
+		).rejects.toThrow();
+	});
+
+	it('should throw error when response is not valid LocalesResponse', async () => {
+		const mockClient = {
+			GET: vi.fn().mockResolvedValue({
+				data: { invalid: 'structure' },
+				error: undefined,
+			}),
+		} as unknown as Client;
+
+		await expect(
+			getEntryLocales(mockClient, 'test_content_type', 'bltentry123'),
+		).rejects.toThrow(
+			'Failed to get locales for test_content_type entry: bltentry123',
+		);
+	});
+
+	it('should handle locales with optional fallback_locale', async () => {
+		const mockLocales = [
+			{
+				code: 'en-us',
+				name: 'English - United States',
+				uid: 'blt1234567890abcdef',
+			},
+			{
+				code: 'fr-ca',
+				fallback_locale: 'en-us',
+				name: 'French - Canada',
+				uid: 'bltabcdef1234567890',
+			},
+		];
+
+		const mockClient = {
+			GET: vi.fn().mockResolvedValue({
+				data: { locales: mockLocales },
+				error: undefined,
+			}),
+		} as unknown as Client;
+
+		const result = await getEntryLocales(
+			mockClient,
+			'test_content_type',
+			'bltentry123',
+		);
+
+		expect(result).toEqual(mockLocales);
+		expect(result[1]?.fallback_locale).toBe('en-us');
+	});
+});

package/src/cs/entries/getEntryLocales.ts

@@ -0,0 +1,81 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import isRecord from '#cli/util/isRecord.js';
+import type { ContentType } from '../content-types/Types.js';
+import type { Entry } from './Types.js';
+
+export interface LocaleInfo {
+	readonly code: string;
+	readonly fallback_locale?: string;
+	readonly name: string;
+	readonly uid: string;
+}
+
+interface LocalesResponse {
+	readonly locales: readonly LocaleInfo[];
+}
+
+function isLocaleInfo(o: unknown): o is LocaleInfo {
+	return (
+		isRecord(o) &&
+		typeof o.code === 'string' &&
+		typeof o.name === 'string' &&
+		typeof o.uid === 'string'
+	);
+}
+
+function isLocalesResponse(o: unknown): o is LocalesResponse {
+	return (
+		isRecord(o) && Array.isArray(o.locales) && o.locales.every(isLocaleInfo)
+	);
+}
+
+/**
+ * Retrieves all available locale versions of an entry from Contentstack.
+ *
+ * This function queries the Contentstack Management API to get a list of all locales
+ * in which the specified entry exists. This is used during pull operations to determine
+ * which locale versions need to be exported and saved to the filesystem.
+ *
+ * @param client - The Contentstack API client
+ * @param contentTypeUid - The UID of the content type (e.g., 'event', 'home_page')
+ * @param entryUid - The UID of the entry to get locales for
+ * @returns A readonly array of LocaleInfo objects, each containing the locale code, name, and UID
+ * @throws {ContentstackError} If the API returns an error
+ * @throws {Error} If the response cannot be parsed as a valid LocalesResponse
+ *
+ * @example
+ * const locales = await getEntryLocales(client, 'event', 'blt123456');
+ * // Returns: [
+ * //   { code: 'en-us', name: 'English - United States', uid: 'blt...' },
+ * //   { code: 'fr', name: 'French', uid: 'blt...' }
+ * // ]
+ */
+export default async function getEntryLocales(
+	client: Client,
+	contentTypeUid: ContentType['uid'],
+	entryUid: Entry['uid'],
+): Promise<readonly LocaleInfo[]> {
+	const { data, error } = await client.GET(
+		'/v3/content_types/{content_type_uid}/entries/{entry_uid}/locales',
+		{
+			params: {
+				path: {
+					content_type_uid: contentTypeUid,
+					entry_uid: entryUid,
+				},
+			},
+		},
+	);
+
+	const msg = `Failed to get locales for ${contentTypeUid} entry: ${entryUid}`;
+	ContentstackError.throwIfError(error, msg);
+
+	const result = data as unknown;
+
+	if (!isLocalesResponse(result)) {
+		throw new Error(msg);
+	}
+
+	return result.locales;
+}

package/src/cs/entries/import.ts

@@ -0,0 +1,16 @@
+import type Client from '../api/Client.js';
+import importCreate from './lib/importCreate.js';
+import importOverwrite from './lib/importOverwrite.js';
+import type { Entry } from './Types.js';
+
+export default async function importEntry(
+	client: Client,
+	contentTypeUid: string,
+	entry: Entry,
+	overwrite: boolean,
+	locale?: string,
+) {
+	return overwrite
+		? await importOverwrite(client, contentTypeUid, entry, locale)
+		: await importCreate(client, contentTypeUid, entry, locale);
+}

package/src/cs/entries/index.ts

@@ -0,0 +1,56 @@
+import equality from '#cli/schema/entries/equality.js';
+import type Client from '../api/Client.js';
+import readPaginatedItems from '../api/paginate/readPaginatedItems.js';
+import type { ContentType } from '../content-types/Types.js';
+import typecheckArray from '../typecheckArray.js';
+import type { Schema } from '../Types.js';
+import isEmptyEntry from './lib/isEmptyEntry.js';
+import { isEntry, key } from './Types.js';
+
+export default async function index(
+	client: Client,
+	globalFieldsByUid: ReadonlyMap<Schema['uid'], Schema>,
+	contentType: ContentType,
+) {
+	return readPaginatedItems(
+		`${contentType.title} entries`,
+		key,
+		fetchFn.bind(null, contentType.uid, client),
+		mapFn.bind(null, globalFieldsByUid, contentType),
+		equality,
+	);
+}
+
+async function fetchFn(contentTypeUid: string, client: Client, skip: number) {
+	return client.GET('/v3/content_types/{content_type_uid}/entries', {
+		params: {
+			path: { content_type_uid: contentTypeUid },
+			query: {
+				include_count: 'true',
+				include_publish_details: 'false',
+				limit: 100,
+				...(skip > 0 ? { skip } : {}),
+			},
+		},
+	});
+}
+
+function mapFn(
+	globalFieldsByUid: ReadonlyMap<Schema['uid'], Schema>,
+	contentType: ContentType,
+	o: Record<string, unknown>,
+) {
+	const { count, entries: rawItems } = o;
+
+	if (!typecheckArray(isEntry, `${contentType.title} entries`, rawItems)) {
+		throw new Error('Invalid response from Contentstack');
+	}
+
+	return {
+		items: rawItems.filter(
+			(x) => !isEmptyEntry(globalFieldsByUid, contentType, x),
+		),
+		processedItems: rawItems.length,
+		...(typeof count === 'number' ? { count } : {}),
+	};
+}

package/src/cs/entries/indexAllCsEntries.ts

@@ -0,0 +1,50 @@
+import indexContentTypes from '#cli/cs/content-types/index.js';
+import indexGlobalFields from '#cli/cs/global-fields/index.js';
+import ProgressReporter from '#cli/ui/progress/ProgressReporter.js';
+import getUi from '../../schema/lib/SchemaUi.js';
+import type Client from '../api/Client.js';
+import type { ContentType } from '../content-types/Types.js';
+import type { Schema } from '../Types.js';
+import index from './index.js';
+import type { Entry } from './Types.js';
+
+export default async function indexAllCsEntries(
+	client: Client,
+): Promise<
+	[
+		ReadonlyMap<Schema['uid'], Schema>,
+		ReadonlyMap<ContentType, ReadonlySet<Entry>>,
+	]
+> {
+	const allEntries = new Map<ContentType, ReadonlySet<Entry>>();
+
+	const [globalFields, rawContentTypes] = await Promise.all([
+		indexGlobalFields(client),
+		indexContentTypes(client),
+	]);
+
+	const sorted = [...rawContentTypes.values()].sort((a, b) =>
+		a.title.localeCompare(b.title),
+	);
+
+	if (sorted.length === 0) {
+		return [globalFields, allEntries];
+	}
+
+	const ui = getUi();
+
+	{
+		using bar = ui.createProgressBar('Indexing entries', sorted.length);
+
+		for (const contentType of sorted) {
+			using reporter = new ProgressReporter(bar, 'indexing', contentType.title);
+
+			const entries = await index(client, globalFields, contentType);
+			allEntries.set(contentType, new Set([...entries.values()]));
+			bar.increment();
+			reporter.finish('indexed');
+		}
+	}
+
+	return [globalFields, allEntries];
+}

package/src/cs/entries/lib/importCreate.ts

@@ -0,0 +1,34 @@
+import type Client from '#cli/cs/api/Client.js';
+import fileUploadInit from '#cli/cs/api/fileUploadInit.js';
+import type { ContentType } from '#cli/cs/content-types/Types.js';
+import createStylus from '#cli/ui/createStylus.js';
+import type { Entry } from '../Types.js';
+import parseImportResponse from './parseImportResponse.js';
+
+export default async function importCreate(
+	client: Client,
+	contentTypeUid: ContentType['uid'],
+	entry: Entry,
+	locale?: string,
+): Promise<Entry> {
+	const y = createStylus('yellowBright');
+	const msg = y`Failed to create ${contentTypeUid} entry: ${entry.title}.`;
+
+	const response = await client.POST(
+		'/v3/content_types/{content_type_uid}/entries/import',
+		{
+			...fileUploadInit,
+			body: { entry: JSON.stringify(entry) },
+
+			params: {
+				path: { content_type_uid: contentTypeUid },
+				query: {
+					...(locale ? { locale } : {}),
+					overwrite: 'false',
+				},
+			},
+		},
+	);
+
+	return parseImportResponse(response, msg);
+}

package/src/cs/entries/lib/importOverwrite.ts

@@ -0,0 +1,111 @@
+import type Client from '#cli/cs/api/Client.js';
+import ContentstackError from '#cli/cs/api/ContentstackError.js';
+import fileUploadInit from '#cli/cs/api/fileUploadInit.js';
+import type { ContentType } from '#cli/cs/content-types/Types.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import createStylus from '#cli/ui/createStylus.js';
+import { isDeepStrictEqual } from 'node:util';
+import type { Entry } from '../Types.js';
+import parseImportResponse from './parseImportResponse.js';
+
+export default async function importOverwrite(
+	client: Client,
+	contentTypeUid: ContentType['uid'],
+	entry: Entry,
+	locale?: string,
+): Promise<Entry> {
+	const errorContext = buildContext(contentTypeUid, entry);
+	const req = attempt.bind(
+		null,
+		client,
+		contentTypeUid,
+		entry,
+		locale,
+		errorContext,
+	);
+	return useRetryStrategy(req, errorContext);
+}
+
+function buildContext(contentTypeUid: ContentType['uid'], entry: Entry) {
+	const y = createStylus('yellowBright');
+	const msg1 = y`Failed to update ${contentTypeUid} entry:`;
+	const msg2 = y`[${entry.uid}] ${entry.title}.`;
+	return `${msg1} ${msg2}`;
+}
+
+async function attempt(
+	client: Client,
+	contentTypeUid: ContentType['uid'],
+	entry: Entry,
+	locale: string | undefined,
+	errorContext: string,
+) {
+	const response = await client.POST(
+		'/v3/content_types/{content_type_uid}/entries/{entry_uid}/import',
+		{
+			...fileUploadInit,
+			body: { entry: JSON.stringify(entry) },
+
+			params: {
+				path: {
+					content_type_uid: contentTypeUid,
+					entry_uid: entry.uid,
+				},
+				query: {
+					...(locale ? { locale } : {}),
+					overwrite: 'true',
+				},
+			},
+		},
+	);
+
+	return parseImportResponse(response, errorContext);
+}
+
+// Attempting to resolve a relatively rare issue where the entry
+// fails to update correctly the first time but succeeds on the
+// second try. Unclear why this happens.
+async function useRetryStrategy(
+	req: () => Promise<Entry>,
+	errorContext: string,
+) {
+	try {
+		return await req();
+	} catch (ex: unknown) {
+		if (!isNullReferenceError(ex)) {
+			throw ex;
+		}
+
+		const ui = getUi();
+
+		try {
+			const result = await req();
+			ui.warn(errorContext, 'Resolved on second attempt.');
+			return result;
+		} catch (ex2: unknown) {
+			ui.warn(errorContext, 'Failed after second attempt.', [ex, ex2]);
+			throw ex2;
+		}
+	}
+}
+
+function isNullReferenceError(ex: unknown) {
+	if (!(ex instanceof ContentstackError)) {
+		return false;
+	}
+
+	const invalidDataCode = 119;
+	if (ex.code !== invalidDataCode) {
+		return false;
+	}
+
+	const nullMsg = "Cannot read properties of null (reading 'data')";
+
+	for (const detail of Object.values(ex.details)) {
+		if (!isDeepStrictEqual(detail, [nullMsg])) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/cs/entries/lib/isEmptyEntry.test.ts

@@ -0,0 +1,133 @@
+import type { ContentType } from '#cli/cs/content-types/Types.js';
+import type { Schema } from '#cli/cs/Types.js';
+import { Store } from '#cli/schema/lib/SchemaUi.js';
+import TestLogContext from '#test/integration/lib/TestLogContext.js';
+import TestPushUiContext from '#test/integration/lib/TestPushUiContext.js';
+import { describe, expect, it } from 'vitest';
+import type { Entry } from '../Types.js';
+import isEmptyEntry from './isEmptyEntry.js';
+
+const logs = new TestLogContext();
+const ui = new TestPushUiContext('', logs);
+
+describe(isEmptyEntry.name, () => {
+	const globalFields: ReadonlyMap<Schema['uid'], Schema> = new Map();
+
+	interface Theory {
+		readonly description: string;
+		readonly entry: Entry;
+		readonly expected: boolean;
+	}
+
+	const theories: Theory[] = [
+		{
+			description: 'returns true for empty entries',
+			entry: {
+				...mockEntry(),
+				display_name: '',
+				link: { href: '', title: '' },
+				logo: {},
+				logo_url: '',
+			},
+			expected: true,
+		},
+		{
+			description: 'returns false for populated entries',
+			entry: {
+				...mockEntry(),
+				display_name: 'some-display-name',
+				link: { href: 'some-link-href', title: 'some-link-title' },
+				logo: {},
+				logo_url: 'some-logo-url',
+				tags: ['some-tag'],
+				title: 'some-title',
+			},
+			expected: false,
+		},
+		{
+			description: 'returns true for entries containing empty RTE fields',
+			entry: {
+				...mockEntry(),
+				description: {
+					_version: 1,
+					attrs: {},
+					children: [
+						{
+							attrs: {},
+							children: [{ text: '' }],
+							type: 'p',
+							uid: '87e76bf2af8d49d2b69a0b63cf83f96a',
+						},
+					],
+					type: 'doc',
+					uid: '07cc2e39fcc94427ae255b8e5f32fce2',
+				},
+			},
+			expected: true,
+		},
+		{
+			description: 'returns false for entries containing populated RTE fields',
+			entry: {
+				...mockEntry(),
+				description: {
+					_version: 1,
+					attrs: {},
+					children: [
+						{
+							attrs: {},
+							children: [{ text: 'some text goes here' }],
+							type: 'p',
+							uid: '87e76bf2af8d49d2b69a0b63cf83f96a',
+						},
+					],
+					type: 'doc',
+					uid: '07cc2e39fcc94427ae255b8e5f32fce2',
+				},
+			},
+			expected: false,
+		},
+	];
+
+	theories.forEach(({ description, entry, expected }) => {
+		it(description, () => {
+			// Arrange
+			const contentType: ContentType = {
+				schema: [
+					{
+						data_type: 'json',
+						field_metadata: { allow_json_rte: true },
+						uid: 'description',
+					},
+				],
+				title: 'some-title',
+				uid: 'contentTypeUid',
+			};
+
+			// Act
+			const result = Store.run(ui, () =>
+				isEmptyEntry(globalFields, contentType, entry),
+			);
+
+			// Assert
+			expect(result).toBe(expected);
+		});
+	});
+});
+
+function mockEntry() {
+	const now = new Date();
+
+	return {
+		ACL: {},
+		_in_progress: true,
+		_version: 1,
+		created_at: now.toISOString(),
+		created_by: 'another-uid-value',
+		locale: 'en-us',
+		tags: [],
+		title: '',
+		uid: 'some-uid-value',
+		updated_at: now.toISOString(),
+		updated_by: 'another-uid-value',
+	};
+}

package/src/cs/entries/lib/isEmptyEntry.ts

@@ -0,0 +1,82 @@
+import type { ContentType } from '#cli/cs/content-types/Types.js';
+import type { Schema } from '#cli/cs/Types.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import isRecord from '#cli/util/isRecord.js';
+import { styleText } from 'node:util';
+import type { Entry } from '../Types.js';
+import removeEmptyJsonRTEs from './removeEmptyJsonRTEs.js';
+
+// We are encountering some instances with partially-formed entries. These have
+// no data in any field, including the title field, which comes across as an
+// empty string. This causes issues when there are two or more of these because
+// the empty string is still a valid key value, but we can't deal with
+// duplicate keys.
+//
+// I do not know how these entries come into being and I have not been able to
+// replicate the issue. This code is an attempt to filter them out.
+export default function isEmptyEntry(
+	globalFieldsByUid: ReadonlyMap<Schema['uid'], Schema>,
+	contentType: ContentType,
+	x: Entry,
+): boolean {
+	if (x.title) {
+		return false;
+	}
+
+	const simplified = removeEmptyJsonRTEs(globalFieldsByUid, contentType, x);
+	const withoutMeta = ignoreTopLevelMetadata(simplified);
+
+	if (!hasRealData(withoutMeta)) {
+		getUi().warn(
+			'Empty',
+			styleText('yellowBright', contentType.title),
+			'entry detected and filtered out:',
+			`[${styleText('yellowBright', x.uid)}]`,
+			x.title
+				? `(${styleText('yellowBright', x.title)})`
+				: `(${styleText('dim', 'Untitled')})`,
+		);
+
+		return true;
+	}
+
+	return false;
+}
+
+function ignoreTopLevelMetadata(x: Entry) {
+	const props = new Map(Object.entries(x));
+	props.delete('_in_progress');
+	props.delete('_version');
+	props.delete('ACL');
+	props.delete('created_at');
+	props.delete('created_by');
+	props.delete('locale');
+	props.delete('uid');
+	props.delete('updated_at');
+	props.delete('updated_by');
+	return Object.fromEntries(props);
+}
+
+function hasRealData(obj: Readonly<Record<string, unknown>>) {
+	for (const value of Object.values(obj)) {
+		if (typeof value === 'string') {
+			if (value !== '') {
+				return true;
+			}
+		}
+
+		if (Array.isArray(value)) {
+			if (value.length > 0) {
+				return true;
+			}
+		}
+
+		if (isRecord(value)) {
+			if (hasRealData(value)) {
+				return true;
+			}
+		}
+	}
+
+	return false;
+}