meca 1.0.4 → 1.0.5

package/README.md

@@ -1,8 +1,8 @@
 # meca
 
 [![meca on npm](https://img.shields.io/npm/v/meca.svg)](https://www.npmjs.com/package/meca)
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/curvenote/meca/blob/main/LICENSE)
-[![CI](https://github.com/curvenote/meca/workflows/CI/badge.svg)](https://github.com/curvenote/meca/actions)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/curvenote/jats/blob/main/LICENSE)
+[![CI](https://github.com/curvenote/jats/workflows/CI/badge.svg)](https://github.com/curvenote/jats/actions)
 
 Types and utilities for working with MECA bundles documents in Node and Typescript.
 
@@ -17,11 +17,130 @@ meca -v
 
 ## What is MECA?
 
-## Packages
+Manuscript Exchange Common Approach (MECA) is a [NISO standard](https://www.niso.org/standards-committees/meca) for transferring scientific manuscripts between vendors. It is a ZIP file with a `manifest.xml`, which contains a JATS file as the `article-metadata` and other source materials.
 
-See packages folder:
+## From the command line
 
-- meca
+Commands available:
+
+`validate`: validate the MECA zip file, including the JATS
+
+```bash
+meca validate my-meca-file.zip
+```
+
+## From Typescript
+
+The `manifest.xml` can be read and written as follows.
+
+```typescript
+import fs from 'fs';
+import { ManifestXml, createManifestXml } from 'meca';
+
+const data = fs.readFileSync('manifest.xml').toString();
+const manifest = new ManifestXml(data);
+console.log(manifest.items);
+
+// Write a manifest file
+const roundTrip = createManifestXml(manifest.items);
+fs.writeFileSync('manifest.xml', roundTrip);
+```
+
+The `ManifestItem` has the following shape:
+
+```typescript
+type ManifestItem = {
+  id?: string;
+  itemType?: string;
+  version?: string;
+  title?: string;
+  description?: string;
+  href: string;
+  mediaType?: string;
+  fileOrder?: string;
+  metadata?: Record<string, string>;
+};
+```
+
+which translates to the following XML, for example, from the NISO spec:
+
+```xml
+<item id="b-456" item-type="figure" item-version="0">
+  <item-description>Figure</item-description>
+  <file-order>3</file-order>
+  <item-metadata>
+    <metadata metadata-name="Figure Number">1</metadata>
+    <metadata metadata-name="Caption"
+    >This is the caption for Figure 1</metadata>
+  </item-metadata>
+  <instance media-type="image/jpeg" xlink:href="wrist_scaphoidvx_diagnosis.jpg" />
+</item>
+```
+
+We assume that there is only one instance for each `item` and will warn if that is not the case.
+
+### transfer.xml
+
+```typescript
+import fs from 'fs';
+import { TransferXml, createTransferXml } from 'meca';
+
+const data = fs.readFileSync('manifest.xml').toString();
+const transfer = new TransferXml(data);
+console.log(transfer.source);
+
+// Write a transfer file
+const roundTrip = createTransferXml({ source, destination, instructions });
+fs.writeFileSync('transfer.xml', roundTrip);
+```
+
+The `source` has the following structure:
+
+```typescript
+const source = {
+  provider: {
+    name: 'Aries Systems',
+    contact: {
+      name: { given: 'Mary', surname: 'Smith' },
+      email: 'MarySmith@sample.email',
+      phone: '444-555-0101',
+    },
+  },
+  publication: {
+    type: 'journal',
+    title: 'The Journal of the American Medical Association',
+    acronym: 'JAMA',
+    contact: {
+      email: 'MyJournal@ariessys.com',
+    },
+  },
+};
+```
+
+Which creates the following XML:
+
+```xml
+<transfer-source>
+  <service-provider>
+    <provider-name>Aries Systems</provider-name>
+    <contact>
+      <contact-name>
+        <surname>Smith</surname>
+        <given-names>Mary</given-names>
+      </contact-name>
+      <email>MarySmith@sample.email</email>
+      <phone>444-555-0101</phone>
+    </contact>
+  </service-provider>
+  <publication type="journal">
+    <publication-title>The Journal of the American Medical Association</publication-title>
+    <acronym>JAMA</acronym>
+    <contact>
+      <email>MyJournal@ariessys.com</email>
+    </contact>
+  </publication>
+</transfer-source>
+```
 
 ---
 

package/dist/cli/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
 export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -4,6 +4,6 @@ import version from '../version.js';
 import { addValidateCLI } from './validate.js';
 const program = new Command();
 addValidateCLI(program);
-program.version(`v${version}`, '-v, --version', 'Print the current version of jats-xml');
+program.version(`v${version}`, '-v, --version', 'Print the current version of meca');
 program.option('-d, --debug', 'Log out any errors to the console.');
 program.parse(process.argv);

package/dist/cli/validate.d.ts

@@ -1,2 +1,3 @@
 import { Command } from 'commander';
 export declare function addValidateCLI(program: Command): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/cli/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/cli/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AA8C5C,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,QAE9C"}

package/dist/cli/validate.js

@@ -1,7 +1,7 @@
 import { Command, Option } from 'commander';
 import { clirun } from 'myst-cli-utils';
 import { getSession } from 'jats-xml';
-import { validateMecaWrapper } from '../validate/index.js';
+import { validateMecaWrapper } from '../validate.js';
 function makeValidateCLI(program) {
     const command = new Command('validate')
         .description(`

package/dist/index.d.ts

@@ -1,2 +1,5 @@
 export { default as version } from './version.js';
-export * from './validate/index.js';
+export * from './manifest.js';
+export * from './validate.js';
+export * from './transfer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAClD,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -1,2 +1,4 @@
 export { default as version } from './version.js';
-export * from './validate/index.js';
+export * from './manifest.js';
+export * from './validate.js';
+export * from './transfer.js';

package/dist/{MECA_manifest.dtd → manifest-1.0.dtd}

@@ -1,6 +1,4 @@
-<!-- DOCTYPE manifest PUBLIC “-//MECA//DTD Manifest v1.0//en"
- "https://www.manuscriptexchange.org/schema/manifest-1.0.dtd"
--->
+<!-- DOCTYPE manifest PUBLIC “-//MECA//DTD Manifest v1.0//en" "https://meca.zip/manifest-1.0.dtd" -->
 <!-- ============================================================= -->
 <!-- SPECIAL CHARACTER MODULES -->
 <!-- ============================================================= -->
@@ -40,4 +38,4 @@
 <!ATTLIST instance media-type CDATA #IMPLIED>
 <!ATTLIST instance origin CDATA #IMPLIED>
 <!ATTLIST instance conversion CDATA #IMPLIED>
-<!ATTLIST instance composition CDATA #IMPLIED>
+<!ATTLIST instance composition CDATA #IMPLIED>

package/dist/manifest.d.ts

@@ -0,0 +1,55 @@
+import type { GenericParent } from 'myst-common';
+import type { Element, DeclarationAttributes } from 'xml-js';
+import type { Logger } from 'myst-cli-utils';
+export declare const MANIFEST = "manifest.xml";
+export declare const MANIFEST_DTD = "manifest-1.0.dtd";
+type Options = {
+    log?: Logger;
+    source?: string;
+};
+export declare enum ItemTypes {
+    articleMetadata = "article-metadata",
+    articleSupportingFile = "article-supporting-file",
+    manuscript = "manuscript",
+    manuscriptSupportingFile = "manuscript-supporting-file",
+    articleSource = "article-source",
+    articleSourceEnvironment = "article-source-environment",
+    articleSourceDirectory = "article-source-directory",
+    transferMetadata = "transfer-metadata"
+}
+export type ManifestItem = {
+    id?: string;
+    itemType?: string;
+    version?: string;
+    title?: string;
+    description?: string;
+    href: string;
+    mediaType?: string;
+    fileOrder?: string;
+    metadata?: Record<string, string>;
+};
+export declare class ManifestXml {
+    declaration?: DeclarationAttributes;
+    doctype?: string;
+    rawXML: string;
+    raw: Element;
+    log: Logger;
+    tree: GenericParent;
+    source?: string;
+    constructor(data: string, opts?: Options);
+    get localDtd(): string;
+    validateXml(remoteDtd?: string): Promise<boolean | undefined>;
+    get version(): string;
+    get items(): ManifestItem[];
+    get itemTypes(): string[];
+    get articleMetadata(): ManifestItem | undefined;
+    get transferMetadata(): ManifestItem[];
+}
+type WriteOptions = {
+    /** Some publishers prefer `href` instead of `xlink:href`, which is in the spec */
+    noXLink?: boolean;
+    dtdUrl?: string;
+};
+export declare function createManifestXml(manifestItems: ManifestItem[], opts?: WriteOptions): string;
+export {};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAE7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAI7C,eAAO,MAAM,QAAQ,iBAAiB,CAAC;AACvC,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAE/C,KAAK,OAAO,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,oBAAY,SAAS;IACnB,eAAe,qBAAqB;IACpC,qBAAqB,4BAA4B;IACjD,UAAU,eAAe;IACzB,wBAAwB,+BAA+B;IACvD,aAAa,mBAAmB;IAChC,wBAAwB,+BAA+B;IACvD,sBAAsB,6BAA6B;IACnD,gBAAgB,sBAAsB;CACvC;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF,qBAAa,WAAW;IACtB,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEJ,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAuBxC,IAAI,QAAQ,IAAI,MAAM,CAOrB;IAEK,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM;IAqBpC,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,KAAK,IAAI,YAAY,EAAE,CAmC1B;IAED,IAAI,SAAS,IAAI,MAAM,EAAE,CAMxB;IAED,IAAI,eAAe,IAAI,YAAY,GAAG,SAAS,CAI9C;IAED,IAAI,gBAAgB,IAAI,YAAY,EAAE,CAErC;CACF;AAED,KAAK,YAAY,GAAG;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAuCF,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,YAAY,EAAE,EAAE,IAAI,CAAC,EAAE,YAAY,UA4BnF"}

package/dist/manifest.js

@@ -0,0 +1,194 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import fs from 'node:fs';
+import path from 'node:path';
+import { js2xml, xml2js } from 'xml-js';
+import { convertToUnist, xmllintValidate } from 'jats-xml';
+import { tic } from 'myst-cli-utils';
+import { createTempFolder, elementWithText, removeTempFolder, select, selectAll } from './utils.js';
+export const MANIFEST = 'manifest.xml';
+export const MANIFEST_DTD = 'manifest-1.0.dtd';
+export var ItemTypes;
+(function (ItemTypes) {
+    ItemTypes["articleMetadata"] = "article-metadata";
+    ItemTypes["articleSupportingFile"] = "article-supporting-file";
+    ItemTypes["manuscript"] = "manuscript";
+    ItemTypes["manuscriptSupportingFile"] = "manuscript-supporting-file";
+    ItemTypes["articleSource"] = "article-source";
+    ItemTypes["articleSourceEnvironment"] = "article-source-environment";
+    ItemTypes["articleSourceDirectory"] = "article-source-directory";
+    ItemTypes["transferMetadata"] = "transfer-metadata";
+})(ItemTypes || (ItemTypes = {}));
+export class ManifestXml {
+    constructor(data, opts) {
+        var _a, _b;
+        const toc = tic();
+        this.log = (_a = opts === null || opts === void 0 ? void 0 : opts.log) !== null && _a !== void 0 ? _a : console;
+        this.rawXML = data;
+        if (opts === null || opts === void 0 ? void 0 : opts.source)
+            this.source = opts.source;
+        try {
+            this.raw = xml2js(data, { compact: false });
+        }
+        catch (error) {
+            throw new Error('Problem parsing the TransferXML document, please ensure it is XML');
+        }
+        const { declaration, elements } = this.raw;
+        this.declaration = declaration === null || declaration === void 0 ? void 0 : declaration.attributes;
+        if (!((elements === null || elements === void 0 ? void 0 : elements.length) === 2 && elements[0].type === 'doctype' && elements[1].name === 'manifest')) {
+            throw new Error('Element <manifest> is not the only element of the manifest.xml');
+        }
+        this.doctype = elements[0].doctype;
+        const converted = convertToUnist(elements[1]);
+        this.tree = select('manifest', converted);
+        (_b = this.log) === null || _b === void 0 ? void 0 : _b.debug(toc('Parsed and converted manifest.xml to unist tree in %s'));
+    }
+    get localDtd() {
+        // This works both compiled and in tests
+        const dtd = fs.existsSync(path.join(__dirname, MANIFEST_DTD))
+            ? path.join(__dirname, MANIFEST_DTD)
+            : path.join(__dirname, '..', 'static', MANIFEST_DTD);
+        if (fs.existsSync(dtd))
+            return dtd;
+        throw new Error(`Unable to locate manifest DTD file ${MANIFEST_DTD} in meca lib distribution`);
+    }
+    validateXml(remoteDtd) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tempFolder = createTempFolder();
+            fs.writeFileSync(path.join(tempFolder, MANIFEST), this.rawXML);
+            let dtdFile = this.localDtd;
+            if (remoteDtd) {
+                const data = yield (yield fetch(remoteDtd)).text();
+                dtdFile = path.join(tempFolder, MANIFEST_DTD);
+                fs.writeFileSync(dtdFile, data);
+            }
+            const manifestIsValid = yield xmllintValidate(this, path.join(tempFolder, MANIFEST), dtdFile).catch(() => {
+                this.log.error(`${MANIFEST} DTD validation failed`);
+                return false;
+            });
+            removeTempFolder(tempFolder);
+            return manifestIsValid;
+        });
+    }
+    get version() {
+        return this.tree['manifest-version'] || this.tree.version;
+    }
+    get items() {
+        const items = selectAll(`item`, this.tree)
+            .map((item) => {
+            var _a, _b, _c, _d, _e, _f, _g, _h;
+            const instances = selectAll(`instance`, item);
+            if (instances.length === 0) {
+                this.log.warn('Item without an instance');
+                return undefined;
+            }
+            if (instances.length > 1) {
+                this.log.warn('Item has multiple instances, only the first is used.');
+            }
+            const instance = instances[0];
+            const title = (_b = (_a = select(`item-title`, item)) === null || _a === void 0 ? void 0 : _a.children) === null || _b === void 0 ? void 0 : _b[0].value;
+            const description = (_d = (_c = select(`item-description`, item)) === null || _c === void 0 ? void 0 : _c.children) === null || _d === void 0 ? void 0 : _d[0].value;
+            const fileOrder = (_f = (_e = select(`file-order`, item)) === null || _e === void 0 ? void 0 : _e.children) === null || _f === void 0 ? void 0 : _f[0].value;
+            const metadata = Object.fromEntries((_h = (_g = selectAll('metadata', item)) === null || _g === void 0 ? void 0 : _g.map((n) => {
+                var _a;
+                return [
+                    n['metadata-name'] || n.name,
+                    (_a = n === null || n === void 0 ? void 0 : n.children) === null || _a === void 0 ? void 0 : _a[0].value,
+                ];
+            })) !== null && _h !== void 0 ? _h : []);
+            return {
+                id: item.id,
+                itemType: item['item-type'],
+                version: item['item-version'] || item['version'],
+                title,
+                description,
+                href: instance['xlink:href'] || instance.href,
+                mediaType: instance['media-type'],
+                fileOrder,
+                metadata,
+            };
+        })
+            .filter((item) => !!item);
+        return items;
+    }
+    get itemTypes() {
+        const itemTypes = new Set();
+        this.items.forEach((item) => {
+            if (item.itemType)
+                itemTypes.add(item.itemType);
+        });
+        return [...itemTypes];
+    }
+    get articleMetadata() {
+        const items = this.items.filter((item) => item.itemType === ItemTypes.articleMetadata);
+        if (items.length > 1)
+            this.log.warn('More than 1 article metadata found');
+        return items[0];
+    }
+    get transferMetadata() {
+        return this.items.filter((item) => item.itemType === ItemTypes.transferMetadata);
+    }
+}
+function writeManifestItem(item, opts) {
+    const { id, version, href, itemType, mediaType, title, description, fileOrder, metadata } = item;
+    return {
+        type: 'element',
+        name: 'item',
+        attributes: {
+            id,
+            'item-type': itemType,
+            'item-version': version,
+        },
+        elements: [
+            title ? elementWithText('item-title', title) : undefined,
+            description ? elementWithText('item-description', description) : undefined,
+            fileOrder ? elementWithText('file-order', fileOrder) : undefined,
+            metadata && Object.keys(metadata !== null && metadata !== void 0 ? metadata : {}).length > 0
+                ? {
+                    type: 'element',
+                    name: 'item-metadata',
+                    elements: Object.entries(metadata).map(([k, v]) => elementWithText('metadata', v, { 'metadata-name': k })),
+                }
+                : undefined,
+            {
+                type: 'element',
+                name: 'instance',
+                attributes: {
+                    [(opts === null || opts === void 0 ? void 0 : opts.noXLink) ? 'href' : 'xlink:href']: href,
+                    'media-type': mediaType,
+                },
+            },
+        ].filter((e) => !!e),
+    };
+}
+export function createManifestXml(manifestItems, opts) {
+    var _a;
+    const element = {
+        type: 'element',
+        elements: [
+            {
+                type: 'doctype',
+                doctype: `manifest PUBLIC "-//MECA//DTD Manifest v1.0//en" "${(_a = opts === null || opts === void 0 ? void 0 : opts.dtdUrl) !== null && _a !== void 0 ? _a : 'https://meca.zip/manifest-1.0.dtd'}"`,
+            },
+            {
+                type: 'element',
+                name: 'manifest',
+                attributes: Object.assign({ 'manifest-version': '1', xmlns: 'https://manuscriptexchange.org/schema/manifest' }, ((opts === null || opts === void 0 ? void 0 : opts.noXLink) ? {} : { 'xmlns:xlink': 'http://www.w3.org/1999/xlink' })),
+                elements: manifestItems.map((item) => writeManifestItem(item, opts)),
+            },
+        ],
+        declaration: { attributes: { version: '1.0', encoding: 'UTF-8' } },
+    };
+    const manifest = js2xml(element, {
+        compact: false,
+        spaces: 2,
+    });
+    return manifest;
+}