@internetarchive/metadata-service 1.1.0 → 1.2.0-beta.0

package/dist/test/metadata-patch.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-patch.test.js","sourceRoot":"","sources":["../../test/metadata-patch.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { expect } from '@open-wc/testing';\nimport { buildMetadataFieldPatch } from '../src/metadata-patch';\n\ndescribe('buildMetadataFieldPatch', () => {\n  it('replaces an existing field', () => {\n    expect(buildMetadataFieldPatch('title', 'New', 'Old')).to.deep.equal([\n      { op: 'replace', path: '/title', value: 'New' },\n    ]);\n  });\n\n  it('adds a field that is absent', () => {\n    expect(buildMetadataFieldPatch('volume', ['2'], undefined)).to.deep.equal([\n      { op: 'add', path: '/volume', value: '2' },\n    ]);\n  });\n\n  it('writes a single-entry list as a bare string', () => {\n    expect(\n      buildMetadataFieldPatch('subject', ['one'], ['one', 'two']),\n    ).to.deep.equal([{ op: 'replace', path: '/subject', value: 'one' }]);\n  });\n\n  it('keeps multiple values as a list', () => {\n    expect(buildMetadataFieldPatch('subject', ['a', 'b'], 'a')).to.deep.equal([\n      { op: 'replace', path: '/subject', value: ['a', 'b'] },\n    ]);\n  });\n\n  it('removes a field set to nothing', () => {\n    expect(buildMetadataFieldPatch('notes', [], 'old')).to.deep.equal([\n      { op: 'remove', path: '/notes' },\n    ]);\n    expect(buildMetadataFieldPatch('notes', '', ['a', 'b'])).to.deep.equal([\n      { op: 'remove', path: '/notes' },\n    ]);\n  });\n\n  it('returns an empty patch when nothing changes', () => {\n    expect(buildMetadataFieldPatch('title', ['Same'], 'Same')).to.deep.equal(\n      [],\n    );\n    expect(buildMetadataFieldPatch('title', 'Same', ['Same'])).to.deep.equal(\n      [],\n    );\n    expect(buildMetadataFieldPatch('notes', [], undefined)).to.deep.equal([]);\n  });\n\n  it('escapes the key as a JSON Pointer', () => {\n    expect(buildMetadataFieldPatch('a/b~c', 'x', undefined)).to.deep.equal([\n      { op: 'add', path: '/a~1b~0c', value: 'x' },\n    ]);\n  });\n});\n"]}

package/dist/test/metadata-service-write.test.js

@@ -0,0 +1,96 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { expect } from '@open-wc/testing';
+import { MetadataService } from '../src/metadata-service';
+import { MetadataServiceError, MetadataServiceErrorType, } from '../src/metadata-service-error';
+class WritableMockBackend {
+    constructor() {
+        this.current = {};
+        this.writes = [];
+    }
+    async fetchMetadata(_identifier, keypath) {
+        if (this.readError)
+            return { error: this.readError };
+        if (keypath !== 'metadata')
+            return { success: {} };
+        return { success: { result: this.current } };
+    }
+    async writeMetadata(identifier, target, patch) {
+        if (this.writeError)
+            return { error: this.writeError };
+        this.writes.push({ identifier, target, patch });
+        return { success: { success: true, task_id: 42 } };
+    }
+}
+describe('MetadataService writes', () => {
+    describe('patchMetadata', () => {
+        it('sends the patch to the metadata target by default', async () => {
+            const backend = new WritableMockBackend();
+            const service = new MetadataService(backend);
+            const patch = [{ op: 'remove', path: '/notes' }];
+            const result = await service.patchMetadata('foo', patch);
+            expect(result.success).to.deep.equal({ changed: true, taskId: 42 });
+            expect(backend.writes).to.deep.equal([
+                { identifier: 'foo', target: 'metadata', patch },
+            ]);
+        });
+        it('passes a backend error through', async () => {
+            var _a;
+            const backend = new WritableMockBackend();
+            backend.writeError = new MetadataServiceError(MetadataServiceErrorType.writeError, 'nope');
+            const service = new MetadataService(backend);
+            const result = await service.patchMetadata('foo', []);
+            expect((_a = result.error) === null || _a === void 0 ? void 0 : _a.message).to.equal('nope');
+        });
+        it('reports writeNotSupported for a backend without writes', async () => {
+            var _a;
+            const readOnlyBackend = {
+                fetchMetadata: async () => ({ success: {} }),
+            };
+            const service = new MetadataService(readOnlyBackend);
+            const result = await service.patchMetadata('foo', []);
+            expect((_a = result.error) === null || _a === void 0 ? void 0 : _a.type).to.equal(MetadataServiceErrorType.writeNotSupported);
+        });
+    });
+    describe('updateMetadataField', () => {
+        it('replaces a field MDAPI has', async () => {
+            const backend = new WritableMockBackend();
+            backend.current = { title: 'Old' };
+            const service = new MetadataService(backend);
+            const result = await service.updateMetadataField('foo', 'title', 'New');
+            expect(result.success).to.deep.equal({ changed: true, taskId: 42 });
+            expect(backend.writes[0].patch).to.deep.equal([
+                { op: 'replace', path: '/title', value: 'New' },
+            ]);
+        });
+        it('adds a field MDAPI does not have', async () => {
+            const backend = new WritableMockBackend();
+            backend.current = { title: 'T' };
+            const service = new MetadataService(backend);
+            await service.updateMetadataField('foo', 'volume', ['2']);
+            expect(backend.writes[0].patch).to.deep.equal([
+                { op: 'add', path: '/volume', value: '2' },
+            ]);
+        });
+        it('skips the write when MDAPI already has the value', async () => {
+            const backend = new WritableMockBackend();
+            backend.current = { subject: ['a', 'b'] };
+            const service = new MetadataService(backend);
+            const result = await service.updateMetadataField('foo', 'subject', [
+                'a',
+                'b',
+            ]);
+            expect(result.success).to.deep.equal({ changed: false });
+            expect(backend.writes).to.be.empty;
+        });
+        it('returns the read error without writing', async () => {
+            var _a;
+            const backend = new WritableMockBackend();
+            backend.readError = new MetadataServiceError(MetadataServiceErrorType.searchEngineError, "Couldn't locate item 'foo'");
+            const service = new MetadataService(backend);
+            const result = await service.updateMetadataField('foo', 'title', 'New');
+            expect((_a = result.error) === null || _a === void 0 ? void 0 : _a.message).to.equal("Couldn't locate item 'foo'");
+            expect(backend.writes).to.be.empty;
+        });
+    });
+});
+//# sourceMappingURL=metadata-service-write.test.js.map

package/dist/test/metadata-service-write.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-service-write.test.js","sourceRoot":"","sources":["../../test/metadata-service-write.test.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { expect } from '@open-wc/testing';\n\nimport { Result } from '@internetarchive/result-type';\nimport { MetadataBackendInterface } from '../src/backend/metadata-backend-interface';\nimport { MetadataService } from '../src/metadata-service';\nimport {\n  MetadataServiceError,\n  MetadataServiceErrorType,\n} from '../src/metadata-service-error';\nimport type { MetadataPatchOperation } from '../src/metadata-patch';\n\nclass WritableMockBackend implements MetadataBackendInterface {\n  current: Record<string, unknown> = {};\n\n  readError?: MetadataServiceError;\n\n  writeError?: MetadataServiceError;\n\n  writes: { identifier: string; target: string; patch: any[] }[] = [];\n\n  async fetchMetadata(\n    _identifier: string,\n    keypath?: string,\n  ): Promise<Result<any, MetadataServiceError>> {\n    if (this.readError) return { error: this.readError };\n    if (keypath !== 'metadata') return { success: {} };\n    return { success: { result: this.current } };\n  }\n\n  async writeMetadata(\n    identifier: string,\n    target: string,\n    patch: MetadataPatchOperation[],\n  ): Promise<Result<any, MetadataServiceError>> {\n    if (this.writeError) return { error: this.writeError };\n    this.writes.push({ identifier, target, patch });\n    return { success: { success: true, task_id: 42 } };\n  }\n}\n\ndescribe('MetadataService writes', () => {\n  describe('patchMetadata', () => {\n    it('sends the patch to the metadata target by default', async () => {\n      const backend = new WritableMockBackend();\n      const service = new MetadataService(backend);\n      const patch = [{ op: 'remove' as const, path: '/notes' }];\n\n      const result = await service.patchMetadata('foo', patch);\n\n      expect(result.success).to.deep.equal({ changed: true, taskId: 42 });\n      expect(backend.writes).to.deep.equal([\n        { identifier: 'foo', target: 'metadata', patch },\n      ]);\n    });\n\n    it('passes a backend error through', async () => {\n      const backend = new WritableMockBackend();\n      backend.writeError = new MetadataServiceError(\n        MetadataServiceErrorType.writeError,\n        'nope',\n      );\n      const service = new MetadataService(backend);\n\n      const result = await service.patchMetadata('foo', []);\n\n      expect(result.error?.message).to.equal('nope');\n    });\n\n    it('reports writeNotSupported for a backend without writes', async () => {\n      const readOnlyBackend: MetadataBackendInterface = {\n        fetchMetadata: async () => ({ success: {} }),\n      };\n      const service = new MetadataService(readOnlyBackend);\n\n      const result = await service.patchMetadata('foo', []);\n\n      expect(result.error?.type).to.equal(\n        MetadataServiceErrorType.writeNotSupported,\n      );\n    });\n  });\n\n  describe('updateMetadataField', () => {\n    it('replaces a field MDAPI has', async () => {\n      const backend = new WritableMockBackend();\n      backend.current = { title: 'Old' };\n      const service = new MetadataService(backend);\n\n      const result = await service.updateMetadataField('foo', 'title', 'New');\n\n      expect(result.success).to.deep.equal({ changed: true, taskId: 42 });\n      expect(backend.writes[0].patch).to.deep.equal([\n        { op: 'replace', path: '/title', value: 'New' },\n      ]);\n    });\n\n    it('adds a field MDAPI does not have', async () => {\n      const backend = new WritableMockBackend();\n      backend.current = { title: 'T' };\n      const service = new MetadataService(backend);\n\n      await service.updateMetadataField('foo', 'volume', ['2']);\n\n      expect(backend.writes[0].patch).to.deep.equal([\n        { op: 'add', path: '/volume', value: '2' },\n      ]);\n    });\n\n    it('skips the write when MDAPI already has the value', async () => {\n      const backend = new WritableMockBackend();\n      backend.current = { subject: ['a', 'b'] };\n      const service = new MetadataService(backend);\n\n      const result = await service.updateMetadataField('foo', 'subject', [\n        'a',\n        'b',\n      ]);\n\n      expect(result.success).to.deep.equal({ changed: false });\n      expect(backend.writes).to.be.empty;\n    });\n\n    it('returns the read error without writing', async () => {\n      const backend = new WritableMockBackend();\n      backend.readError = new MetadataServiceError(\n        MetadataServiceErrorType.searchEngineError,\n        \"Couldn't locate item 'foo'\",\n      );\n      const service = new MetadataService(backend);\n\n      const result = await service.updateMetadataField('foo', 'title', 'New');\n\n      expect(result.error?.message).to.equal(\"Couldn't locate item 'foo'\");\n      expect(backend.writes).to.be.empty;\n    });\n  });\n});\n"]}

package/index.ts

@@ -13,4 +13,12 @@ export {
 export { DefaultMetadataBackend } from './src/backend/default-metadata-backend';
 export { MetadataService } from './src/metadata-service';
 export { MetadataServiceError } from './src/metadata-service-error';
-export { MetadataServiceInterface } from './src/metadata-service-interface';
+export {
+  MetadataServiceInterface,
+  MetadataWriteResult,
+} from './src/metadata-service-interface';
+export { buildMetadataFieldPatch } from './src/metadata-patch';
+export type {
+  MetadataFieldValue,
+  MetadataPatchOperation,
+} from './src/metadata-patch';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@internetarchive/metadata-service",
-  "version": "1.1.0",
+  "version": "1.2.0-beta.0",
   "description": "A service for fetching metadata about items in the Internet Archive",
   "license": "AGPL-3.0-only",
   "main": "dist/index.js",

package/src/backend/default-metadata-backend.ts

@@ -5,6 +5,7 @@ import {
   MetadataServiceErrorType,
 } from '../metadata-service-error';
 import { MetadataBackendInterface } from './metadata-backend-interface';
+import type { MetadataPatchOperation } from '../metadata-patch';
 
 /**
  * The DefaultSearchBackend performs a `window.fetch` request to archive.org
@@ -56,6 +57,52 @@ export class DefaultMetadataBackend implements MetadataBackendInterface {
     return this.fetchUrl(url);
   }
 
+  /**
+   * @inheritdoc
+   *
+   * Makes a single attempt: a write that timed out may still have queued its
+   * task, and retrying would queue another.
+   */
+  async writeMetadata(
+    identifier: string,
+    target: string,
+    patch: MetadataPatchOperation[],
+  ): Promise<Result<any, MetadataServiceError>> {
+    const url = `https://${this.baseUrl}/metadata/${identifier}`;
+    const body = new URLSearchParams({
+      '-target': target,
+      '-patch': JSON.stringify(patch),
+    });
+
+    const result = await this.fetchUrl(url, {
+      requestOptions: {
+        method: 'POST',
+        credentials: this.includeCredentials ? 'include' : 'same-origin',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+        },
+        body,
+      },
+    });
+
+    // MDAPI reports a rejected write as `{ success: false, error }`
+    if (result.error?.type === MetadataServiceErrorType.searchEngineError) {
+      return this.getErrorResult(
+        MetadataServiceErrorType.writeError,
+        result.error.message,
+        result.error.details,
+      );
+    }
+    if (result.success && result.success.success !== true) {
+      return this.getErrorResult(
+        MetadataServiceErrorType.writeError,
+        'Metadata write was not accepted',
+        result.success,
+      );
+    }
+    return result;
+  }
+
   /**
    * Fires a request to the URL (with this backend's options applied) and
    * asynchronously returns a Result object containing either the raw response

package/src/backend/metadata-backend-interface.ts

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import type { Result } from '@internetarchive/result-type';
 import { MetadataServiceError } from '../metadata-service-error';
+import type { MetadataPatchOperation } from '../metadata-patch';
 
 /**
  * An interface to provide the network layer to the `MetadataService`.
@@ -22,4 +23,22 @@ export interface MetadataBackendInterface {
     identifier: string,
     keypath?: string,
   ): Promise<Result<any, MetadataServiceError>>;
+
+  /**
+   * Apply a JSON Patch to one of an item's targets (e.g. `metadata`) through
+   * the MDAPI write endpoint, as the logged-in user. Resolves with MDAPI's raw
+   * response (`{ success, task_id, log }`) on success.
+   *
+   * Optional so backends written before writes existed keep compiling; the
+   * service reports `writeNotSupported` for a backend without it.
+   *
+   * @param identifier
+   * @param target
+   * @param patch
+   */
+  writeMetadata?(
+    identifier: string,
+    target: string,
+    patch: MetadataPatchOperation[],
+  ): Promise<Result<any, MetadataServiceError>>;
 }

package/src/metadata-patch.ts

@@ -0,0 +1,53 @@
+/** A metadata field value as MDAPI stores it: one string, or a list of them */
+export type MetadataFieldValue = string | string[];
+
+/** One JSON Patch (RFC 6902) operation, as MDAPI's write endpoint accepts */
+export type MetadataPatchOperation =
+  | { op: 'add' | 'replace'; path: string; value: unknown }
+  | { op: 'remove'; path: string };
+
+/** Escapes a metadata key for use as a JSON Pointer segment (RFC 6901) */
+function pointerFor(field: string): string {
+  return `/${field.replace(/~/g, '~0').replace(/\//g, '~1')}`;
+}
+
+/** MDAPI's storage shape: a one-entry list collapses to a bare string */
+function normalize(
+  value: MetadataFieldValue | undefined,
+): MetadataFieldValue | undefined {
+  return Array.isArray(value) && value.length === 1 ? value[0] : value;
+}
+
+function isEmpty(value: MetadataFieldValue | undefined): boolean {
+  if (value == null) return true;
+  if (Array.isArray(value)) return value.length === 0;
+  return value === '';
+}
+
+/**
+ * Builds the JSON Patch that sets one metadata field to `value`, given the
+ * field's current value.
+ *
+ * A single-entry list is written as a bare string, which is how MDAPI stores
+ * a one-value field, and an empty string or list removes the field. Returns
+ * an empty patch when nothing changes, since MDAPI rejects a write that
+ * doesn't modify the item.
+ */
+export function buildMetadataFieldPatch(
+  field: string,
+  value: MetadataFieldValue,
+  current: MetadataFieldValue | undefined,
+): MetadataPatchOperation[] {
+  const path = pointerFor(field);
+  const next = normalize(value);
+  const existing = normalize(current);
+
+  if (next == null || isEmpty(next)) {
+    return isEmpty(existing) ? [] : [{ op: 'remove', path }];
+  }
+
+  if (JSON.stringify(next) === JSON.stringify(existing)) return [];
+
+  const op = isEmpty(existing) ? 'add' : 'replace';
+  return [{ op, path, value: next }];
+}

package/src/metadata-service-error.ts

@@ -3,6 +3,8 @@ export enum MetadataServiceErrorType {
   itemNotFound = 'MetadataService.ItemNotFound',
   decodingError = 'MetadataService.DecodingError',
   searchEngineError = 'MetadataService.SearchEngineError',
+  writeError = 'MetadataService.WriteError',
+  writeNotSupported = 'MetadataService.WriteNotSupported',
 }
 
 export class MetadataServiceError extends Error {

package/src/metadata-service-interface.ts

@@ -1,6 +1,17 @@
 import type { Result } from '@internetarchive/result-type';
 import type { MetadataServiceError } from './metadata-service-error';
 import type { MetadataResponse } from './responses/metadata-response';
+import type {
+  MetadataFieldValue,
+  MetadataPatchOperation,
+} from './metadata-patch';
+
+export type MetadataWriteResult = {
+  /** Whether a write was sent. False when the field already had the value. */
+  changed: boolean;
+  /** The catalog task that will apply the change to the item */
+  taskId?: number;
+};
 
 export interface MetadataServiceInterface {
   /**
@@ -48,4 +59,49 @@ export interface MetadataServiceInterface {
     identifier: string,
     keypath: string,
   ): Promise<Result<T, MetadataServiceError>>;
+
+  /**
+   * Apply a JSON Patch to an item's metadata as the logged-in user.
+   *
+   * MDAPI applies the change through a queued catalog task. MDAPI reads
+   * replay pending tasks' patches ("lookahead"), so they show the change right
+   * away, but caches built on MDAPI (search, page services) can lag it. MDAPI
+   * rejects a patch that doesn't change the item.
+   *
+   * ```ts
+   * await metadataService.patchMetadata('goody', [
+   *   { op: 'replace', path: '/title', value: 'Goody Two-Shoes' },
+   * ]);
+   * ```
+   *
+   * @param identifier
+   * @param patch JSON Patch operations against the item's metadata
+   * @param target MDAPI write target, `metadata` by default
+   */
+  patchMetadata(
+    identifier: string,
+    patch: MetadataPatchOperation[],
+    target?: string,
+  ): Promise<Result<MetadataWriteResult, MetadataServiceError>>;
+
+  /**
+   * Set one metadata field on an item as the logged-in user. An empty string
+   * or list removes the field.
+   *
+   * Reads the item's current metadata from MDAPI first and patches against
+   * that, so the right add / replace / remove goes out even when the caller's
+   * copy is stale. That read includes this user's still-queued writes through
+   * MDAPI's lookahead, except for tasks lookahead skips (e.g. ones held for an
+   * admin). Resolves with `changed: false`, without writing, when the field
+   * already has the value.
+   *
+   * @param identifier
+   * @param field The metadata key, e.g. `title`
+   * @param value
+   */
+  updateMetadataField(
+    identifier: string,
+    field: string,
+    value: MetadataFieldValue,
+  ): Promise<Result<MetadataWriteResult, MetadataServiceError>>;
 }

package/src/metadata-service.ts

@@ -5,7 +5,15 @@ import {
   MetadataServiceError,
   MetadataServiceErrorType,
 } from './metadata-service-error';
-import type { MetadataServiceInterface } from './metadata-service-interface';
+import type {
+  MetadataServiceInterface,
+  MetadataWriteResult,
+} from './metadata-service-interface';
+import {
+  buildMetadataFieldPatch,
+  type MetadataFieldValue,
+  type MetadataPatchOperation,
+} from './metadata-patch';
 import { MetadataResponse } from './responses/metadata-response';
 
 /**
@@ -60,4 +68,52 @@ export class MetadataService implements MetadataServiceInterface {
 
     return { success: result.success.result };
   }
+
+  /** @inheritdoc */
+  async patchMetadata(
+    identifier: string,
+    patch: MetadataPatchOperation[],
+    target = 'metadata',
+  ): Promise<Result<MetadataWriteResult, MetadataServiceError>> {
+    if (!this.backend.writeMetadata) {
+      return {
+        error: new MetadataServiceError(
+          MetadataServiceErrorType.writeNotSupported,
+          'This metadata backend does not support writes',
+        ),
+      };
+    }
+
+    const result = await this.backend.writeMetadata(identifier, target, patch);
+    if (result.error) {
+      return result;
+    }
+
+    return { success: { changed: true, taskId: result.success?.task_id } };
+  }
+
+  /** @inheritdoc */
+  async updateMetadataField(
+    identifier: string,
+    field: string,
+    value: MetadataFieldValue,
+  ): Promise<Result<MetadataWriteResult, MetadataServiceError>> {
+    const current = await this.fetchMetadataValue<
+      Record<string, MetadataFieldValue>
+    >(identifier, 'metadata');
+    if (current.error) {
+      return { error: current.error };
+    }
+
+    const patch = buildMetadataFieldPatch(
+      field,
+      value,
+      current.success?.[field],
+    );
+    if (patch.length === 0) {
+      return { success: { changed: false } };
+    }
+
+    return this.patchMetadata(identifier, patch);
+  }
 }

package/test/default-metadata-backend.test.ts

@@ -102,3 +102,69 @@ describe('DefaultMetadataBackend', () => {
     window.fetch = fetchBackup;
   });
 });
+
+describe('DefaultMetadataBackend writeMetadata', () => {
+  const fetchBackup = window.fetch;
+
+  afterEach(() => {
+    window.fetch = fetchBackup;
+  });
+
+  it('posts the patch as a form to the item endpoint', async () => {
+    let requestUrl = '';
+    let requestInit: RequestInit | undefined;
+    window.fetch = async (
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ): Promise<Response> => {
+      requestUrl = String(input);
+      requestInit = init;
+      return new Response('{ "success": true, "task_id": 7, "log": "x" }');
+    };
+
+    const backend = new DefaultMetadataBackend({ includeCredentials: true });
+    const patch = [{ op: 'replace' as const, path: '/title', value: 'New' }];
+    const result = await backend.writeMetadata('foo', 'metadata', patch);
+
+    expect(result.success?.task_id).to.equal(7);
+    expect(requestUrl).to.equal('https://archive.org/metadata/foo');
+    expect(requestInit?.method).to.equal('POST');
+    expect(requestInit?.credentials).to.equal('include');
+    const body = requestInit?.body as URLSearchParams;
+    expect(body.get('-target')).to.equal('metadata');
+    expect(JSON.parse(body.get('-patch') ?? '')).to.deep.equal(patch);
+  });
+
+  it('returns a writeError with MDAPI’s message when the write is rejected', async () => {
+    window.fetch = async (): Promise<Response> =>
+      new Response('{ "success": false, "error": "Authorization failed" }', {
+        status: 401,
+      });
+
+    const backend = new DefaultMetadataBackend();
+    const result = await backend.writeMetadata('foo', 'metadata', []);
+
+    expect(result.error?.type).to.equal(MetadataServiceErrorType.writeError);
+    expect(result.error?.message).to.equal('Authorization failed');
+  });
+
+  it('returns a writeError when MDAPI does not report success', async () => {
+    window.fetch = async (): Promise<Response> => new Response('{}');
+
+    const backend = new DefaultMetadataBackend();
+    const result = await backend.writeMetadata('foo', 'metadata', []);
+
+    expect(result.error?.type).to.equal(MetadataServiceErrorType.writeError);
+  });
+
+  it('returns a networkError when the request fails', async () => {
+    window.fetch = async (): Promise<Response> => {
+      throw new Error('offline');
+    };
+
+    const backend = new DefaultMetadataBackend();
+    const result = await backend.writeMetadata('foo', 'metadata', []);
+
+    expect(result.error?.type).to.equal(MetadataServiceErrorType.networkError);
+  });
+});

package/test/metadata-patch.test.ts

@@ -0,0 +1,53 @@
+import { expect } from '@open-wc/testing';
+import { buildMetadataFieldPatch } from '../src/metadata-patch';
+
+describe('buildMetadataFieldPatch', () => {
+  it('replaces an existing field', () => {
+    expect(buildMetadataFieldPatch('title', 'New', 'Old')).to.deep.equal([
+      { op: 'replace', path: '/title', value: 'New' },
+    ]);
+  });
+
+  it('adds a field that is absent', () => {
+    expect(buildMetadataFieldPatch('volume', ['2'], undefined)).to.deep.equal([
+      { op: 'add', path: '/volume', value: '2' },
+    ]);
+  });
+
+  it('writes a single-entry list as a bare string', () => {
+    expect(
+      buildMetadataFieldPatch('subject', ['one'], ['one', 'two']),
+    ).to.deep.equal([{ op: 'replace', path: '/subject', value: 'one' }]);
+  });
+
+  it('keeps multiple values as a list', () => {
+    expect(buildMetadataFieldPatch('subject', ['a', 'b'], 'a')).to.deep.equal([
+      { op: 'replace', path: '/subject', value: ['a', 'b'] },
+    ]);
+  });
+
+  it('removes a field set to nothing', () => {
+    expect(buildMetadataFieldPatch('notes', [], 'old')).to.deep.equal([
+      { op: 'remove', path: '/notes' },
+    ]);
+    expect(buildMetadataFieldPatch('notes', '', ['a', 'b'])).to.deep.equal([
+      { op: 'remove', path: '/notes' },
+    ]);
+  });
+
+  it('returns an empty patch when nothing changes', () => {
+    expect(buildMetadataFieldPatch('title', ['Same'], 'Same')).to.deep.equal(
+      [],
+    );
+    expect(buildMetadataFieldPatch('title', 'Same', ['Same'])).to.deep.equal(
+      [],
+    );
+    expect(buildMetadataFieldPatch('notes', [], undefined)).to.deep.equal([]);
+  });
+
+  it('escapes the key as a JSON Pointer', () => {
+    expect(buildMetadataFieldPatch('a/b~c', 'x', undefined)).to.deep.equal([
+      { op: 'add', path: '/a~1b~0c', value: 'x' },
+    ]);
+  });
+});