mailschema 0.1.0 → 0.1.2

package/README.md

@@ -1,31 +1,65 @@
-# MailSchema
+# MailSchema for JavaScript
 
-JSON Schemas, TypeScript definitions and validation tools for the MailSchema Registry.
+[![npm](https://img.shields.io/npm/v/mailschema)](https://www.npmjs.com/package/mailschema)
+[![CI](https://github.com/mailschema/javascript/actions/workflows/test.yml/badge.svg)](https://github.com/mailschema/javascript/actions/workflows/test.yml)
 
-Prepare a new interaction type, amend an existing definition, or declare an implementation's supported operations. This package checks the Registry contribution format. It does not implement email delivery, authorization or the draft Mail Action Protocol wire format.
+Validate Mail Action Protocol documents and MailSchema Registry contributions without making a network request.
+
+[Specification](https://mailschema.org/specification/) · [Registry](https://mailschema.org/registry/) · [Tools](https://mailschema.org/tools/) · [Source](https://github.com/mailschema/javascript)
+
+## Install
 
 ```sh
 npm install mailschema
-npx mailschema check contribution.json
-npx mailschema schema > contribution.schema.json
 ```
 
-Node.js 22 or newer. The JavaScript API is ESM; the CLI reads a local JSON file of at most 256 KiB and does not upload or modify it.
+Node.js 22 or newer is required. The package is ESM and includes TypeScript declarations.
+
+## Validate MAP documents
+
+```js
+import { assertMapDocument, assertContentReviewRequest, getMapSchema } from 'mailschema';
+
+assertMapDocument(description);
+assertContentReviewRequest(request);
+const mapSchema = getMapSchema();
+```
+
+The CLI performs the same checks against local JSON files:
+
+```sh
+npx mailschema check description.json --map
+npx mailschema check request.json --content-review
+```
+
+## Work with Registry data
 
 ```js
-import { assertContribution, contributionErrors, getContributionSchema } from 'mailschema';
+import {
+  assertContribution,
+  contributionErrors,
+  getContributionSchema,
+  referenceErrors,
+} from 'mailschema';
 
 const errors = contributionErrors(candidate);
 if (errors.length) console.error(errors);
 else assertContribution(candidate);
 
-const schema = getContributionSchema(); // Independent copy, JSON Schema Draft 2020-12.
+const schema = getContributionSchema();
+const referenceProblems = referenceErrors(candidate, catalog);
 ```
 
-Use `assertTypeRecord(value)` or `mailschema check record.json --record` for expanded Registry records. `getRecordSchema()` returns the equivalent schema. The raw contribution schema is also exported as `mailschema/contribution.schema.json`.
+`assertTypeRecord`, `getRecordSchema` and `mailschema check record.json --record` handle expanded Registry records. Reference checks use a catalogue supplied by the caller; the package never fetches one automatically.
+
+Raw Draft 2020-12 schemas are exported as:
+
+- `mailschema/map-0.1.schema.json`
+- `mailschema/content-review-0.1.schema.json`
+- `mailschema/contribution.schema.json`
 
-For a structurally valid contribution, `referenceErrors(contribution, catalog)` checks references against a supplied catalogue: current amendment bases, existing type names, exact implementation records, versions, profiles and operations. The catalogue contains `types` and `snapshots` arrays of `{ record, digest }` entries. It is never fetched automatically.
+## Trust boundary
 
-`Contribution`, `TypeRecord`, `TypeDefinition`, `Implementation`, `Party` and `CatalogView` are exported TypeScript types. Successful validation does not verify a contributor's identity, establish product compatibility or accept a submission. Full repository review also checks competing amendments and contribution identifiers.
+A valid document is structured input. Validation does not authenticate a service, grant authority, approve an action or establish product conformance. Implementations must apply their own endpoint trust, credentials, permissions and policy before executing a request.
 
-Package version `0.1.0` is independent of any specification version. MIT licensed.
+The CLI reads one local file of at most 256 KiB and does not upload or modify it. Package versions and MAP profile versions advance independently. MIT licensed.

package/{cli.mjs → bin/mailschema.js}

@@ -3,15 +3,19 @@ import { open } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import {
   assertContribution,
+  assertContentReviewRequest,
+  assertMapDocument,
   assertTypeRecord,
+  getContentReviewSchema,
   getContributionSchema,
+  getMapSchema,
   getRecordSchema,
-} from './dist/index.js';
+} from '../dist/index.js';
 
 const help = `MailSchema contribution tools
 
-  mailschema check <file.json> [--record]
-  mailschema schema [--record]
+  mailschema check <file.json> [--record | --map | --content-review]
+  mailschema schema [--record | --map | --content-review]
 
 Checks JSON structure and required fields locally. Registry references and
 editorial acceptance are separate checks. No files are uploaded or changed.`;
@@ -19,13 +23,37 @@ editorial acceptance are separate checks. No files are uploaded or changed.`;
 try {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
-    options: { record: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+    options: {
+      record: { type: 'boolean' },
+      map: { type: 'boolean' },
+      'content-review': { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+    },
   });
   const [command, path, ...extra] = positionals;
+  const formats = [values.record, values.map, values['content-review']].filter(Boolean);
+  if (formats.length > 1) throw new Error('Choose only one document format.');
+  const selected = values['content-review']
+    ? 'Content Review request'
+    : values.map
+      ? 'MAP document'
+      : values.record
+        ? 'type record'
+        : 'contribution';
   if (values.help || !command) console.log(help);
   else if (command === 'schema' && !path && !extra.length)
     console.log(
-      JSON.stringify(values.record ? getRecordSchema() : getContributionSchema(), null, 2),
+      JSON.stringify(
+        values['content-review']
+          ? getContentReviewSchema()
+          : values.map
+            ? getMapSchema()
+            : values.record
+              ? getRecordSchema()
+              : getContributionSchema(),
+        null,
+        2,
+      ),
     );
   else if (command === 'check' && path && !extra.length) {
     const file = await open(path, 'r');
@@ -41,11 +69,11 @@ try {
     } finally {
       await file.close();
     }
-    if (values.record) assertTypeRecord(value);
+    if (values['content-review']) assertContentReviewRequest(value);
+    else if (values.map) assertMapDocument(value);
+    else if (values.record) assertTypeRecord(value);
     else assertContribution(value);
-    console.log(
-      'Valid MailSchema ' + (values.record ? 'type record' : 'contribution') + ' structure.',
-    );
+    console.log(`Valid MailSchema ${selected}.`);
   } else throw new Error(help);
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));

package/dist/content-review-0.1.schema.json

@@ -0,0 +1,52 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mailschema.org/schemas/content-review-0.1.schema.json",
+    "title": "Content Review 0.1 MAP request",
+    "allOf": [
+        { "$ref": "https://mailschema.org/schemas/map-0.1.schema.json#/$defs/request" },
+        {
+            "type": "object",
+            "properties": {
+                "type": {
+                    "type": "object",
+                    "properties": {
+                        "id": { "const": "https://mailschema.org/types/content-review" },
+                        "version": { "const": "0.1" },
+                        "recordDigest": {
+                            "const": "sha-256:0e6365df1bf904f2475f972ec66a5561edc0bfaae69fd7a1b41f53b40bf8ac1c"
+                        }
+                    }
+                }
+            }
+        },
+        {
+            "oneOf": [
+                {
+                    "type": "object",
+                    "properties": {
+                        "operation": { "const": "request-changes" },
+                        "input": {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "properties": {
+                                "feedback": { "type": "string", "minLength": 1, "maxLength": 12000 }
+                            },
+                            "required": ["feedback"]
+                        }
+                    }
+                },
+                {
+                    "type": "object",
+                    "properties": {
+                        "operation": { "const": "approve" },
+                        "input": {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "maxProperties": 0
+                        }
+                    }
+                }
+            ]
+        }
+    ]
+}