Skip to content

Commit c98fafe

Browse files
author
naman-contentstack
committed
feat: add asset management package for AM2.0 support
1 parent 00534b9 commit c98fafe

39 files changed

Lines changed: 2464 additions & 70 deletions

.talismanrc

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,19 @@
11
fileignoreconfig:
2-
- filename: package-lock.json
3-
checksum: 45100667793fc7dfaae3e24787871257e7f29e06df69ba10ec05b358d59ff15d
4-
- filename: pnpm-lock.yaml
5-
checksum: 87d001c32b1d7f9df30a289c277e0ea13cfd8a0e2e5fa5118956ff4183683e5c
6-
- filename: .husky/pre-commit
7-
checksum: 7a12030ddfea18d6f85edc25f1721fb2009df00fdd42bab66b05de25ab3e32b2
2+
- filename: packages/contentstack-asset-management/.eslintrc
3+
checksum: 136f03481c8c59575d2eafd4c78d105119f85fb10fe88e02af8cffaf3eb7c090
4+
- filename: packages/contentstack-asset-management/src/export/base.ts
5+
checksum: fcae2679bdeb93a6786cb290b60ba98f222a9c682552c6474370d17bf59ae1b4
6+
- filename: packages/contentstack-export/src/export/modules/stack.ts
7+
checksum: 82f7df78993942debb79e690c8c27d0998157428ef506d0b07ea31d5a1f71aba
8+
- filename: packages/contentstack-asset-management/src/types/export-types.ts
9+
checksum: d00ca608006d864f516e21b76d552c0ecf52ff89b3dcb361ed11ac600abed989
10+
- filename: packages/contentstack-asset-management/src/utils/export-helpers.ts
11+
checksum: 1a533a4e4d56a952f61ced63aa6f1bc8fbb3855fd7acecdd9fd40dd71e5fab6d
12+
- filename: packages/contentstack-asset-management/test/unit/utils/export-helpers.test.ts
13+
checksum: 0e8751163491fc45e7ae3999282d336ae1ab8a9f88e601cbb85b4f44e8db96b8
14+
- filename: packages/contentstack-asset-management/test/unit/utils/asset-management-api-adapter.test.ts
15+
checksum: ff688f37f40de3f7cbef378ec682ca1167720d902d8d84370464af7feb36c124
16+
- filename: packages/contentstack-asset-management/src/utils/asset-management-api-adapter.ts
17+
checksum: 6f5e11d3685b6093d6c4def7fc4199f673d9a56e5fbc2858ed72f69d764f1260
18+
version: "1.0"
819
version: '1.0'
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
{
2+
"env": {
3+
"node": true
4+
},
5+
"parser": "@typescript-eslint/parser",
6+
"parserOptions": {
7+
"project": "tsconfig.json",
8+
"sourceType": "module"
9+
},
10+
"extends": [
11+
"oclif-typescript",
12+
"plugin:@typescript-eslint/recommended"
13+
],
14+
"rules": {
15+
"@typescript-eslint/no-unused-vars": [
16+
"error",
17+
{
18+
"args": "none"
19+
}
20+
],
21+
"@typescript-eslint/prefer-namespace-keyword": "error",
22+
"@typescript-eslint/quotes": [
23+
"error",
24+
"single",
25+
{
26+
"avoidEscape": true,
27+
"allowTemplateLiterals": true
28+
}
29+
],
30+
"semi": "off",
31+
"@typescript-eslint/type-annotation-spacing": "error",
32+
"@typescript-eslint/no-redeclare": "off",
33+
"eqeqeq": [
34+
"error",
35+
"smart"
36+
],
37+
"id-match": "error",
38+
"no-eval": "error",
39+
"no-var": "error",
40+
"quotes": "off",
41+
"indent": "off",
42+
"camelcase": "off",
43+
"comma-dangle": "off",
44+
"arrow-parens": "off",
45+
"operator-linebreak": "off",
46+
"object-curly-spacing": "off",
47+
"node/no-missing-import": "off",
48+
"padding-line-between-statements": "off",
49+
"@typescript-eslint/ban-ts-ignore": "off",
50+
"unicorn/no-abusive-eslint-disable": "off",
51+
"unicorn/consistent-function-scoping": "off",
52+
"@typescript-eslint/no-use-before-define": "off"
53+
}
54+
}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
lib/
2+
node_modules/
3+
*.tsbuildinfo
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# @contentstack/cli-asset-management
2+
3+
Asset Management 2.0 API adapter for Contentstack CLI export and import. Used by the export and import plugins when Asset Management (AM 2.0) is enabled. To learn how to export and import content in Contentstack, refer to the [Migration guide](https://www.contentstack.com/docs/developers/cli/migration/).
4+
5+
[![License](https://img.shields.io/npm/l/@contentstack/cli)](https://github.com/contentstack/cli/blob/main/LICENSE)
6+
7+
<!-- toc -->
8+
* [@contentstack/cli-asset-management](#contentstackcli-asset-management)
9+
* [Overview](#overview)
10+
* [Usage](#usage)
11+
* [Exports](#exports)
12+
<!-- tocstop -->
13+
14+
# Overview
15+
16+
This package provides:
17+
18+
- **AssetManagementAdapter** – HTTP client for the Asset Management API (spaces, assets, folders, fields, asset types).
19+
- **exportSpaceStructure** – Exports space metadata and full workspace structure (metadata, folders, assets, fields, asset types) for linked workspaces.
20+
- **Types**`AssetManagementExportOptions`, `LinkedWorkspace`, `IAssetManagementAdapter`, and related types for export/import integration.
21+
22+
# Usage
23+
24+
This package is consumed by the export and import plugins. When using the export CLI with the `--asset-management` flag (or when the host app enables AM 2.0), the export plugin calls `exportSpaceStructure` with linked workspaces and options:
25+
26+
```ts
27+
import { exportSpaceStructure } from '@contentstack/cli-asset-management';
28+
29+
await exportSpaceStructure({
30+
linkedWorkspaces,
31+
exportDir,
32+
branchName: 'main',
33+
assetManagementUrl,
34+
org_uid,
35+
context,
36+
progressManager,
37+
progressProcessName,
38+
updateStatus,
39+
downloadAsset, // optional
40+
});
41+
```
42+
43+
# Exports
44+
45+
| Export | Description |
46+
|--------|-------------|
47+
| `exportSpaceStructure` | Async function to export space structure for given linked workspaces. |
48+
| `AssetManagementAdapter` | Class to call the Asset Management API (getSpace, getWorkspaceFields, getWorkspaceAssets, etc.). |
49+
| Types from `./types` | `AssetManagementExportOptions`, `ExportSpaceOptions`, `ChunkedJsonWriteOptions`, `LinkedWorkspace`, `SpaceResponse`, `FieldsResponse`, `AssetTypesResponse`, and related API types. |
Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
{
2+
"name": "@contentstack/cli-asset-management",
3+
"version": "1.0.0",
4+
"description": "Asset Management 2.0 API adapter for export and import",
5+
"main": "lib/index.js",
6+
"types": "lib/index.d.ts",
7+
"files": [
8+
"lib",
9+
"oclif.manifest.json"
10+
],
11+
"scripts": {
12+
"build": "pnpm compile",
13+
"clean": "rm -rf ./lib ./node_modules tsconfig.build.tsbuildinfo",
14+
"compile": "tsc -b tsconfig.json",
15+
"postpack": "rm -f oclif.manifest.json",
16+
"prepack": "pnpm compile && oclif manifest && oclif readme",
17+
"version": "oclif readme && git add README.md",
18+
"lint": "eslint src/**/*.ts",
19+
"format": "eslint src/**/*.ts --fix",
20+
"test": "nyc --extension .ts mocha --require ts-node/register --forbid-only \"test/**/*.test.ts\"",
21+
"posttest": "npm run lint",
22+
"test:unit": "mocha --require ts-node/register --forbid-only \"test/unit/**/*.test.ts\"",
23+
"test:unit:report": "nyc --extension .ts mocha --require ts-node/register --forbid-only \"test/unit/**/*.test.ts\""
24+
},
25+
"keywords": [
26+
"contentstack",
27+
"asset-management",
28+
"cli"
29+
],
30+
"license": "MIT",
31+
"dependencies": {
32+
"@contentstack/cli-utilities": "~2.0.0-beta"
33+
},
34+
"oclif": {
35+
"commands": "./lib/commands",
36+
"bin": "csdx",
37+
"devPlugins": [
38+
"@oclif/plugin-help"
39+
],
40+
"repositoryPrefix": "<%- repo %>/blob/main/packages/contentstack-asset-management/<%- commandPath %>"
41+
},
42+
"devDependencies": {
43+
"@types/chai": "^4.3.11",
44+
"@types/mocha": "^10.0.6",
45+
"@types/node": "^20.17.50",
46+
"@types/sinon": "^17.0.2",
47+
"chai": "^4.4.1",
48+
"eslint": "^8.57.1",
49+
"eslint-config-oclif": "^6.0.68",
50+
"mocha": "^10.8.2",
51+
"nyc": "^15.1.0",
52+
"oclif": "^4.17.46",
53+
"sinon": "^17.0.1",
54+
"source-map-support": "^0.5.21",
55+
"ts-node": "^10.9.2",
56+
"typescript": "^5.8.3"
57+
}
58+
}
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
/**
2+
* Main process name for Asset Management 2.0 export (single progress bar).
3+
* Use this when adding/starting the process and for all ticks.
4+
*/
5+
export const AM_MAIN_PROCESS_NAME = 'Asset Management 2.0';
6+
7+
/**
8+
* Process names for Asset Management 2.0 export progress (for tick labels).
9+
*/
10+
export const PROCESS_NAMES = {
11+
AM_SPACE_METADATA: 'Space metadata',
12+
AM_FOLDERS: 'Folders',
13+
AM_ASSETS: 'Assets',
14+
AM_FIELDS: 'Fields',
15+
AM_ASSET_TYPES: 'Asset types',
16+
AM_DOWNLOADS: 'Asset downloads',
17+
} as const;
18+
19+
/**
20+
* Status messages for each process (exporting, fetching, failed).
21+
*/
22+
export const PROCESS_STATUS = {
23+
[PROCESS_NAMES.AM_SPACE_METADATA]: {
24+
EXPORTING: 'Exporting space metadata...',
25+
FAILED: 'Failed to export space metadata.',
26+
},
27+
[PROCESS_NAMES.AM_FOLDERS]: {
28+
FETCHING: 'Fetching folders...',
29+
FAILED: 'Failed to fetch folders.',
30+
},
31+
[PROCESS_NAMES.AM_ASSETS]: {
32+
FETCHING: 'Fetching assets...',
33+
FAILED: 'Failed to fetch assets.',
34+
},
35+
[PROCESS_NAMES.AM_FIELDS]: {
36+
FETCHING: 'Fetching fields...',
37+
FAILED: 'Failed to fetch fields.',
38+
},
39+
[PROCESS_NAMES.AM_ASSET_TYPES]: {
40+
FETCHING: 'Fetching asset types...',
41+
FAILED: 'Failed to fetch asset types.',
42+
},
43+
[PROCESS_NAMES.AM_DOWNLOADS]: {
44+
DOWNLOADING: 'Downloading asset files...',
45+
FAILED: 'Failed to download assets.',
46+
},
47+
} as const;
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import { log } from '@contentstack/cli-utilities';
2+
3+
import type { AssetManagementAPIConfig } from '../types/asset-management-api';
4+
import type { ExportContext } from '../types/export-types';
5+
import { AssetManagementExportAdapter } from './base';
6+
import { getArrayFromResponse } from '../utils/export-helpers';
7+
import { PROCESS_NAMES } from '../constants/index';
8+
9+
export default class ExportAssetTypes extends AssetManagementExportAdapter {
10+
constructor(apiConfig: AssetManagementAPIConfig, exportContext: ExportContext) {
11+
super(apiConfig, exportContext);
12+
}
13+
14+
async start(spaceUid: string): Promise<void> {
15+
await this.init();
16+
const assetTypesData = await this.getWorkspaceAssetTypes(spaceUid);
17+
const items = getArrayFromResponse(assetTypesData, 'asset_types');
18+
const dir = this.getAssetTypesDir();
19+
log.debug(
20+
items.length === 0
21+
? 'No asset types, wrote empty asset-types'
22+
: `Writing ${items.length} shared asset types`,
23+
this.exportContext.context,
24+
);
25+
await this.writeItemsToChunkedJson(dir, 'asset-types.json', 'asset_types', ['uid', 'title', 'category', 'file_extension'], items);
26+
this.tick(true, PROCESS_NAMES.AM_ASSET_TYPES, null);
27+
}
28+
}
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
import { resolve as pResolve } from 'node:path';
2+
import { Readable } from 'node:stream';
3+
import { mkdir, writeFile } from 'node:fs/promises';
4+
import { configHandler, log } from '@contentstack/cli-utilities';
5+
6+
import type { AssetManagementAPIConfig, LinkedWorkspace } from '../types/asset-management-api';
7+
import type { ExportContext } from '../types/export-types';
8+
import { AssetManagementExportAdapter } from './base';
9+
import { getAssetItems, writeStreamToFile } from '../utils/export-helpers';
10+
import { PROCESS_NAMES, PROCESS_STATUS } from '../constants/index';
11+
12+
export default class ExportAssets extends AssetManagementExportAdapter {
13+
constructor(apiConfig: AssetManagementAPIConfig, exportContext: ExportContext) {
14+
super(apiConfig, exportContext);
15+
}
16+
17+
async start(workspace: LinkedWorkspace, spaceDir: string): Promise<void> {
18+
await this.init();
19+
const assetsDir = pResolve(spaceDir, 'assets');
20+
await mkdir(assetsDir, { recursive: true });
21+
log.debug(`Fetching folders and assets for space ${workspace.space_uid}`, this.exportContext.context);
22+
23+
const [folders, assetsData] = await Promise.all([
24+
this.getWorkspaceFolders(workspace.space_uid),
25+
this.getWorkspaceAssets(workspace.space_uid),
26+
]);
27+
28+
await writeFile(pResolve(assetsDir, 'folders.json'), JSON.stringify(folders, null, 2));
29+
this.tick(true, `folders: ${workspace.space_uid}`, null);
30+
log.debug(`Wrote folders.json for space ${workspace.space_uid}`, this.exportContext.context);
31+
32+
const assetItems = getAssetItems(assetsData);
33+
log.debug(
34+
assetItems.length === 0
35+
? `No assets for space ${workspace.space_uid}, wrote empty assets.json`
36+
: `Writing ${assetItems.length} assets metadata for space ${workspace.space_uid}`,
37+
this.exportContext.context,
38+
);
39+
await this.writeItemsToChunkedJson(
40+
assetsDir,
41+
'assets.json',
42+
'assets',
43+
['uid', 'url', 'filename', 'file_name', 'parent_uid'],
44+
assetItems,
45+
);
46+
this.tick(true, `assets: ${workspace.space_uid} (${assetItems.length})`, null);
47+
48+
await this.downloadWorkspaceAssets(assetsData, assetsDir, workspace.space_uid);
49+
}
50+
51+
private async downloadWorkspaceAssets(
52+
assetsData: unknown,
53+
assetsDir: string,
54+
spaceUid: string,
55+
): Promise<void> {
56+
const items = getAssetItems(assetsData);
57+
if (items.length === 0) {
58+
log.debug('No assets to download', this.exportContext.context);
59+
return;
60+
}
61+
62+
this.updateStatus(PROCESS_STATUS[PROCESS_NAMES.AM_DOWNLOADS].DOWNLOADING);
63+
log.debug(`Downloading ${items.length} asset file(s) for space ${spaceUid}...`, this.exportContext.context);
64+
const filesDir = pResolve(assetsDir, 'files');
65+
await mkdir(filesDir, { recursive: true });
66+
67+
const securedAssets = this.exportContext.securedAssets ?? false;
68+
const authtoken = securedAssets ? configHandler.get('authtoken') : null;
69+
let lastError: string | null = null;
70+
let allSuccess = true;
71+
72+
for (const asset of items) {
73+
const uid = asset.uid ?? asset._uid;
74+
const url = asset.url;
75+
const filename = asset.filename ?? asset.file_name ?? 'asset';
76+
if (!url || !uid) continue;
77+
try {
78+
const separator = url.includes('?') ? '&' : '?';
79+
const downloadUrl = securedAssets && authtoken ? `${url}${separator}authtoken=${authtoken}` : url;
80+
const response = await fetch(downloadUrl);
81+
if (!response.ok) throw new Error(`HTTP ${response.status}`);
82+
const body = response.body;
83+
if (!body) throw new Error('No response body');
84+
const nodeStream = Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]);
85+
const assetFolderPath = pResolve(filesDir, uid);
86+
await mkdir(assetFolderPath, { recursive: true });
87+
const filePath = pResolve(assetFolderPath, filename);
88+
await writeStreamToFile(nodeStream, filePath);
89+
log.debug(`Downloaded asset ${uid}`, this.exportContext.context);
90+
} catch (e) {
91+
allSuccess = false;
92+
lastError = (e as Error)?.message ?? PROCESS_STATUS[PROCESS_NAMES.AM_DOWNLOADS].FAILED;
93+
log.debug(`Failed to download asset ${uid}: ${e}`, this.exportContext.context);
94+
}
95+
}
96+
97+
this.tick(allSuccess, `downloads: ${spaceUid}`, lastError);
98+
log.debug('Asset downloads completed', this.exportContext.context);
99+
}
100+
}

0 commit comments

Comments
 (0)