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

package/README.md

@@ -19,6 +19,24 @@ metadataResponse.metadata.collection.value // => 'some-collection'
 metadataResponse.metadata.collection.values // => ['some-collection', 'another-collection', 'more-collections']
 ```
 
+### Write Metadata
+
+Writes go through MDAPI as the logged-in user, so they need the viewer's archive.org cookies (`includeCredentials`). MDAPI applies a write through a queued catalog task. MDAPI reads replay pending tasks, so they show the change right away, but search and other caches built on MDAPI can lag it.
+
+```ts
+// Set one field. Reads the item's current metadata first and sends the
+// right add / replace / remove. An empty string or list removes the field.
+const result = await metadataService.updateMetadataField('some-identifier', 'subject', ['cats', 'dogs']);
+result.success // => { changed: true, taskId: 12345 }, or { changed: false } if it already had that value
+
+// Or send a JSON Patch yourself
+await metadataService.patchMetadata('some-identifier', [
+  { op: 'replace', path: '/title', value: 'A new title' },
+]);
+```
+
+Failed writes come back as a `MetadataServiceError` with type `writeError` and MDAPI's message.
+
 ## Metadata Values
 
 Internet Archive Metadata is expansive and nearly all metadata fields can be returned as either an array, string, or number.

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { MetadataResponse } from './src/responses/metadata-response';
+export type { AlternateLocation, AlternateLocations, } from './src/responses/metadata-response';
 export { File, Review, SpeechMusicASREntry, } from '@internetarchive/iaux-item-metadata';
 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/dist/index.js

@@ -3,4 +3,5 @@ export { File, Review, } from '@internetarchive/iaux-item-metadata';
 export { DefaultMetadataBackend } from './src/backend/default-metadata-backend';
 export { MetadataService } from './src/metadata-service';
 export { MetadataServiceError } from './src/metadata-service-error';
+export { buildMetadataFieldPatch } from './src/metadata-patch';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,OAAO,EACL,IAAI,EACJ,MAAM,GAEP,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC","sourcesContent":["export { MetadataResponse } from './src/responses/metadata-response';\n\nexport {\n  File,\n  Review,\n  SpeechMusicASREntry,\n} from '@internetarchive/iaux-item-metadata';\n\nexport { DefaultMetadataBackend } from './src/backend/default-metadata-backend';\nexport { MetadataService } from './src/metadata-service';\nexport { MetadataServiceError } from './src/metadata-service-error';\nexport { MetadataServiceInterface } from './src/metadata-service-interface';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAMrE,OAAO,EACL,IAAI,EACJ,MAAM,GAEP,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAKpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC","sourcesContent":["export { MetadataResponse } from './src/responses/metadata-response';\nexport type {\n  AlternateLocation,\n  AlternateLocations,\n} from './src/responses/metadata-response';\n\nexport {\n  File,\n  Review,\n  SpeechMusicASREntry,\n} from '@internetarchive/iaux-item-metadata';\n\nexport { DefaultMetadataBackend } from './src/backend/default-metadata-backend';\nexport { MetadataService } from './src/metadata-service';\nexport { MetadataServiceError } from './src/metadata-service-error';\nexport {\n  MetadataServiceInterface,\n  MetadataWriteResult,\n} from './src/metadata-service-interface';\nexport { buildMetadataFieldPatch } from './src/metadata-patch';\nexport type {\n  MetadataFieldValue,\n  MetadataPatchOperation,\n} from './src/metadata-patch';\n"]}

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

@@ -1,6 +1,7 @@
 import type { Result } from '@internetarchive/result-type';
 import { MetadataServiceError } 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
  */
@@ -15,6 +16,13 @@ export declare class DefaultMetadataBackend implements MetadataBackendInterface
     });
     /** @inheritdoc */
     fetchMetadata(identifier: string, keypath?: string): Promise<Result<any, MetadataServiceError>>;
+    /**
+     * @inheritdoc
+     *
+     * Makes a single attempt: a write that timed out may still have queued its
+     * task, and retrying would queue another.
+     */
+    writeMetadata(identifier: string, target: string, patch: MetadataPatchOperation[]): Promise<Result<any, MetadataServiceError>>;
     /**
      * Fires a request to the URL (with this backend's options applied) and
      * asynchronously returns a Result object containing either the raw response

package/dist/src/backend/default-metadata-backend.js

@@ -35,6 +35,38 @@ export class DefaultMetadataBackend {
         const url = `https://${this.baseUrl}/metadata/${identifier}${path}`;
         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, target, patch) {
+        var _a;
+        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 (((_a = result.error) === null || _a === void 0 ? void 0 : _a.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/dist/src/backend/default-metadata-backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"default-metadata-backend.js","sourceRoot":"","sources":["../../../src/backend/default-metadata-backend.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport type { Result } from '@internetarchive/result-type';\nimport {\n  MetadataServiceError,\n  MetadataServiceErrorType,\n} from '../metadata-service-error';\nimport { MetadataBackendInterface } from './metadata-backend-interface';\n\n/**\n * The DefaultSearchBackend performs a `window.fetch` request to archive.org\n */\nexport class DefaultMetadataBackend implements MetadataBackendInterface {\n  private baseUrl: string;\n\n  private includeCredentials: boolean;\n\n  private requestScope?: string;\n\n  constructor(options?: {\n    baseUrl?: string;\n    includeCredentials?: boolean;\n    scope?: string;\n  }) {\n    this.baseUrl = options?.baseUrl ?? 'archive.org';\n\n    if (options?.includeCredentials !== undefined) {\n      this.includeCredentials = options.includeCredentials;\n    } else {\n      // include credentials if the request is coming from an archive.org domain\n      // since credentialed requests are only allowed from archive.org domains\n      // due to CORS restrictions, see\n      // https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials\n      this.includeCredentials =\n        window.location.href.match(/^https?:\\/\\/.*archive\\.org(:[0-9]+)?/) !==\n        null;\n    }\n\n    if (options?.scope !== undefined) {\n      this.requestScope = options.scope;\n    } else {\n      const currentUrl = new URL(window.location.href);\n      const scope = currentUrl.searchParams.get('scope');\n      if (scope) {\n        this.requestScope = scope;\n      }\n    }\n  }\n\n  /** @inheritdoc */\n  async fetchMetadata(\n    identifier: string,\n    keypath?: string,\n  ): Promise<Result<any, MetadataServiceError>> {\n    const path = keypath ? `/${keypath}` : '';\n    const url = `https://${this.baseUrl}/metadata/${identifier}${path}`;\n    return this.fetchUrl(url);\n  }\n\n  /**\n   * Fires a request to the URL (with this backend's options applied) and\n   * asynchronously returns a Result object containing either the raw response\n   * JSON or a MetadataServiceError.\n   */\n  protected async fetchUrl(\n    url: string,\n    options?: {\n      requestOptions?: RequestInit;\n    },\n  ): Promise<Result<any, MetadataServiceError>> {\n    const finalUrl = new URL(url);\n    if (this.requestScope) {\n      finalUrl.searchParams.set('scope', this.requestScope);\n    }\n\n    let response: Response;\n    // first try the fetch and return a networkError if it fails\n    try {\n      const fetchOptions = options?.requestOptions ?? {\n        credentials: this.includeCredentials ? 'include' : 'same-origin',\n      };\n      response = await fetch(finalUrl.href, fetchOptions);\n    } catch (err) {\n      const message =\n        err instanceof Error\n          ? err.message\n          : typeof err === 'string'\n            ? err\n            : 'Unknown error';\n      return this.getErrorResult(\n        MetadataServiceErrorType.networkError,\n        message,\n      );\n    }\n\n    // then try json decoding and return a decodingError if it fails\n    try {\n      const json = await response.json();\n      // the advanced search endpoint doesn't return an HTTP Error 400\n      // and instead returns an HTTP 200 with an `error` key in the payload\n      const error = json['error'];\n      if (error) {\n        const forensics = json['forensics'];\n        return this.getErrorResult(\n          MetadataServiceErrorType.searchEngineError,\n          error,\n          forensics,\n        );\n      } else {\n        // success\n        return { success: json };\n      }\n    } catch (err) {\n      const message =\n        err instanceof Error\n          ? err.message\n          : typeof err === 'string'\n            ? err\n            : 'Unknown error';\n      return this.getErrorResult(\n        MetadataServiceErrorType.decodingError,\n        message,\n      );\n    }\n  }\n\n  private getErrorResult(\n    errorType: MetadataServiceErrorType,\n    message?: string,\n    details?: any,\n  ): Result<any, MetadataServiceError> {\n    const error = new MetadataServiceError(errorType, message, details);\n    const result = { error };\n    return result;\n  }\n}\n"]}
+{"version":3,"file":"default-metadata-backend.js","sourceRoot":"","sources":["../../../src/backend/default-metadata-backend.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport type { Result } from '@internetarchive/result-type';\nimport {\n  MetadataServiceError,\n  MetadataServiceErrorType,\n} from '../metadata-service-error';\nimport { MetadataBackendInterface } from './metadata-backend-interface';\nimport type { MetadataPatchOperation } from '../metadata-patch';\n\n/**\n * The DefaultSearchBackend performs a `window.fetch` request to archive.org\n */\nexport class DefaultMetadataBackend implements MetadataBackendInterface {\n  private baseUrl: string;\n\n  private includeCredentials: boolean;\n\n  private requestScope?: string;\n\n  constructor(options?: {\n    baseUrl?: string;\n    includeCredentials?: boolean;\n    scope?: string;\n  }) {\n    this.baseUrl = options?.baseUrl ?? 'archive.org';\n\n    if (options?.includeCredentials !== undefined) {\n      this.includeCredentials = options.includeCredentials;\n    } else {\n      // include credentials if the request is coming from an archive.org domain\n      // since credentialed requests are only allowed from archive.org domains\n      // due to CORS restrictions, see\n      // https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials\n      this.includeCredentials =\n        window.location.href.match(/^https?:\\/\\/.*archive\\.org(:[0-9]+)?/) !==\n        null;\n    }\n\n    if (options?.scope !== undefined) {\n      this.requestScope = options.scope;\n    } else {\n      const currentUrl = new URL(window.location.href);\n      const scope = currentUrl.searchParams.get('scope');\n      if (scope) {\n        this.requestScope = scope;\n      }\n    }\n  }\n\n  /** @inheritdoc */\n  async fetchMetadata(\n    identifier: string,\n    keypath?: string,\n  ): Promise<Result<any, MetadataServiceError>> {\n    const path = keypath ? `/${keypath}` : '';\n    const url = `https://${this.baseUrl}/metadata/${identifier}${path}`;\n    return this.fetchUrl(url);\n  }\n\n  /**\n   * @inheritdoc\n   *\n   * Makes a single attempt: a write that timed out may still have queued its\n   * task, and retrying would queue another.\n   */\n  async writeMetadata(\n    identifier: string,\n    target: string,\n    patch: MetadataPatchOperation[],\n  ): Promise<Result<any, MetadataServiceError>> {\n    const url = `https://${this.baseUrl}/metadata/${identifier}`;\n    const body = new URLSearchParams({\n      '-target': target,\n      '-patch': JSON.stringify(patch),\n    });\n\n    const result = await this.fetchUrl(url, {\n      requestOptions: {\n        method: 'POST',\n        credentials: this.includeCredentials ? 'include' : 'same-origin',\n        headers: {\n          'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',\n        },\n        body,\n      },\n    });\n\n    // MDAPI reports a rejected write as `{ success: false, error }`\n    if (result.error?.type === MetadataServiceErrorType.searchEngineError) {\n      return this.getErrorResult(\n        MetadataServiceErrorType.writeError,\n        result.error.message,\n        result.error.details,\n      );\n    }\n    if (result.success && result.success.success !== true) {\n      return this.getErrorResult(\n        MetadataServiceErrorType.writeError,\n        'Metadata write was not accepted',\n        result.success,\n      );\n    }\n    return result;\n  }\n\n  /**\n   * Fires a request to the URL (with this backend's options applied) and\n   * asynchronously returns a Result object containing either the raw response\n   * JSON or a MetadataServiceError.\n   */\n  protected async fetchUrl(\n    url: string,\n    options?: {\n      requestOptions?: RequestInit;\n    },\n  ): Promise<Result<any, MetadataServiceError>> {\n    const finalUrl = new URL(url);\n    if (this.requestScope) {\n      finalUrl.searchParams.set('scope', this.requestScope);\n    }\n\n    let response: Response;\n    // first try the fetch and return a networkError if it fails\n    try {\n      const fetchOptions = options?.requestOptions ?? {\n        credentials: this.includeCredentials ? 'include' : 'same-origin',\n      };\n      response = await fetch(finalUrl.href, fetchOptions);\n    } catch (err) {\n      const message =\n        err instanceof Error\n          ? err.message\n          : typeof err === 'string'\n            ? err\n            : 'Unknown error';\n      return this.getErrorResult(\n        MetadataServiceErrorType.networkError,\n        message,\n      );\n    }\n\n    // then try json decoding and return a decodingError if it fails\n    try {\n      const json = await response.json();\n      // the advanced search endpoint doesn't return an HTTP Error 400\n      // and instead returns an HTTP 200 with an `error` key in the payload\n      const error = json['error'];\n      if (error) {\n        const forensics = json['forensics'];\n        return this.getErrorResult(\n          MetadataServiceErrorType.searchEngineError,\n          error,\n          forensics,\n        );\n      } else {\n        // success\n        return { success: json };\n      }\n    } catch (err) {\n      const message =\n        err instanceof Error\n          ? err.message\n          : typeof err === 'string'\n            ? err\n            : 'Unknown error';\n      return this.getErrorResult(\n        MetadataServiceErrorType.decodingError,\n        message,\n      );\n    }\n  }\n\n  private getErrorResult(\n    errorType: MetadataServiceErrorType,\n    message?: string,\n    details?: any,\n  ): Result<any, MetadataServiceError> {\n    const error = new MetadataServiceError(errorType, message, details);\n    const result = { error };\n    return result;\n  }\n}\n"]}

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

@@ -1,5 +1,6 @@
 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`.
  *
@@ -17,4 +18,17 @@ export interface MetadataBackendInterface {
      * @param keypath
      */
     fetchMetadata(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/dist/src/backend/metadata-backend-interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-backend-interface.js","sourceRoot":"","sources":["../../../src/backend/metadata-backend-interface.ts"],"names":[],"mappings":"","sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport type { Result } from '@internetarchive/result-type';\nimport { MetadataServiceError } from '../metadata-service-error';\n\n/**\n * An interface to provide the network layer to the `MetadataService`.\n *\n * Objects implementing this interface are responsible for making calls to the Internet Archive\n * `metadata` endpoint or otherwise providing a similar reponse in JSON format.\n *\n * @export\n * @interface MetadataBackendInterface\n */\nexport interface MetadataBackendInterface {\n  /**\n   * Fetch metadata for a single item with an optional keypath\n   *\n   * @param identifier\n   * @param keypath\n   */\n  fetchMetadata(\n    identifier: string,\n    keypath?: string,\n  ): Promise<Result<any, MetadataServiceError>>;\n}\n"]}
+{"version":3,"file":"metadata-backend-interface.js","sourceRoot":"","sources":["../../../src/backend/metadata-backend-interface.ts"],"names":[],"mappings":"","sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport type { Result } from '@internetarchive/result-type';\nimport { MetadataServiceError } from '../metadata-service-error';\nimport type { MetadataPatchOperation } from '../metadata-patch';\n\n/**\n * An interface to provide the network layer to the `MetadataService`.\n *\n * Objects implementing this interface are responsible for making calls to the Internet Archive\n * `metadata` endpoint or otherwise providing a similar reponse in JSON format.\n *\n * @export\n * @interface MetadataBackendInterface\n */\nexport interface MetadataBackendInterface {\n  /**\n   * Fetch metadata for a single item with an optional keypath\n   *\n   * @param identifier\n   * @param keypath\n   */\n  fetchMetadata(\n    identifier: string,\n    keypath?: string,\n  ): Promise<Result<any, MetadataServiceError>>;\n\n  /**\n   * Apply a JSON Patch to one of an item's targets (e.g. `metadata`) through\n   * the MDAPI write endpoint, as the logged-in user. Resolves with MDAPI's raw\n   * response (`{ success, task_id, log }`) on success.\n   *\n   * Optional so backends written before writes existed keep compiling; the\n   * service reports `writeNotSupported` for a backend without it.\n   *\n   * @param identifier\n   * @param target\n   * @param patch\n   */\n  writeMetadata?(\n    identifier: string,\n    target: string,\n    patch: MetadataPatchOperation[],\n  ): Promise<Result<any, MetadataServiceError>>;\n}\n"]}

package/dist/src/metadata-patch.d.ts

@@ -0,0 +1,21 @@
+/** 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;
+};
+/**
+ * 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 declare function buildMetadataFieldPatch(field: string, value: MetadataFieldValue, current: MetadataFieldValue | undefined): MetadataPatchOperation[];

package/dist/src/metadata-patch.js

@@ -0,0 +1,37 @@
+/** Escapes a metadata key for use as a JSON Pointer segment (RFC 6901) */
+function pointerFor(field) {
+    return `/${field.replace(/~/g, '~0').replace(/\//g, '~1')}`;
+}
+/** MDAPI's storage shape: a one-entry list collapses to a bare string */
+function normalize(value) {
+    return Array.isArray(value) && value.length === 1 ? value[0] : value;
+}
+function isEmpty(value) {
+    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, value, current) {
+    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 }];
+}
+//# sourceMappingURL=metadata-patch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-patch.js","sourceRoot":"","sources":["../../src/metadata-patch.ts"],"names":[],"mappings":"AAQA,0EAA0E;AAC1E,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED,yEAAyE;AACzE,SAAS,SAAS,CAChB,KAAqC;IAErC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACvE,CAAC;AAED,SAAS,OAAO,CAAC,KAAqC;IACpD,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;IACpD,OAAO,KAAK,KAAK,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAa,EACb,KAAyB,EACzB,OAAuC;IAEvC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9B,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAEpC,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACjD,OAAO,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACrC,CAAC","sourcesContent":["/** A metadata field value as MDAPI stores it: one string, or a list of them */\nexport type MetadataFieldValue = string | string[];\n\n/** One JSON Patch (RFC 6902) operation, as MDAPI's write endpoint accepts */\nexport type MetadataPatchOperation =\n  | { op: 'add' | 'replace'; path: string; value: unknown }\n  | { op: 'remove'; path: string };\n\n/** Escapes a metadata key for use as a JSON Pointer segment (RFC 6901) */\nfunction pointerFor(field: string): string {\n  return `/${field.replace(/~/g, '~0').replace(/\\//g, '~1')}`;\n}\n\n/** MDAPI's storage shape: a one-entry list collapses to a bare string */\nfunction normalize(\n  value: MetadataFieldValue | undefined,\n): MetadataFieldValue | undefined {\n  return Array.isArray(value) && value.length === 1 ? value[0] : value;\n}\n\nfunction isEmpty(value: MetadataFieldValue | undefined): boolean {\n  if (value == null) return true;\n  if (Array.isArray(value)) return value.length === 0;\n  return value === '';\n}\n\n/**\n * Builds the JSON Patch that sets one metadata field to `value`, given the\n * field's current value.\n *\n * A single-entry list is written as a bare string, which is how MDAPI stores\n * a one-value field, and an empty string or list removes the field. Returns\n * an empty patch when nothing changes, since MDAPI rejects a write that\n * doesn't modify the item.\n */\nexport function buildMetadataFieldPatch(\n  field: string,\n  value: MetadataFieldValue,\n  current: MetadataFieldValue | undefined,\n): MetadataPatchOperation[] {\n  const path = pointerFor(field);\n  const next = normalize(value);\n  const existing = normalize(current);\n\n  if (next == null || isEmpty(next)) {\n    return isEmpty(existing) ? [] : [{ op: 'remove', path }];\n  }\n\n  if (JSON.stringify(next) === JSON.stringify(existing)) return [];\n\n  const op = isEmpty(existing) ? 'add' : 'replace';\n  return [{ op, path, value: next }];\n}\n"]}

package/dist/src/metadata-service-error.d.ts

@@ -2,7 +2,9 @@ export declare enum MetadataServiceErrorType {
     networkError = "MetadataService.NetworkError",
     itemNotFound = "MetadataService.ItemNotFound",
     decodingError = "MetadataService.DecodingError",
-    searchEngineError = "MetadataService.SearchEngineError"
+    searchEngineError = "MetadataService.SearchEngineError",
+    writeError = "MetadataService.WriteError",
+    writeNotSupported = "MetadataService.WriteNotSupported"
 }
 export declare class MetadataServiceError extends Error {
     type: MetadataServiceErrorType;

package/dist/src/metadata-service-error.js

@@ -4,6 +4,8 @@ export var MetadataServiceErrorType;
     MetadataServiceErrorType["itemNotFound"] = "MetadataService.ItemNotFound";
     MetadataServiceErrorType["decodingError"] = "MetadataService.DecodingError";
     MetadataServiceErrorType["searchEngineError"] = "MetadataService.SearchEngineError";
+    MetadataServiceErrorType["writeError"] = "MetadataService.WriteError";
+    MetadataServiceErrorType["writeNotSupported"] = "MetadataService.WriteNotSupported";
 })(MetadataServiceErrorType || (MetadataServiceErrorType = {}));
 export class MetadataServiceError extends Error {
     /* eslint-disable-next-line @typescript-eslint/no-explicit-any */

package/dist/src/metadata-service-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-service-error.js","sourceRoot":"","sources":["../../src/metadata-service-error.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,wBAKX;AALD,WAAY,wBAAwB;IAClC,yEAA6C,CAAA;IAC7C,yEAA6C,CAAA;IAC7C,2EAA+C,CAAA;IAC/C,mFAAuD,CAAA;AACzD,CAAC,EALW,wBAAwB,KAAxB,wBAAwB,QAKnC;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAM7C,iEAAiE;IACjE,YAAY,IAA8B,EAAE,OAAgB,EAAE,OAAa;QACzE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF","sourcesContent":["export enum MetadataServiceErrorType {\n  networkError = 'MetadataService.NetworkError',\n  itemNotFound = 'MetadataService.ItemNotFound',\n  decodingError = 'MetadataService.DecodingError',\n  searchEngineError = 'MetadataService.SearchEngineError',\n}\n\nexport class MetadataServiceError extends Error {\n  type: MetadataServiceErrorType;\n\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  details?: any;\n\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  constructor(type: MetadataServiceErrorType, message?: string, details?: any) {\n    super(message);\n    this.name = type;\n    this.type = type;\n    this.details = details;\n  }\n}\n"]}
+{"version":3,"file":"metadata-service-error.js","sourceRoot":"","sources":["../../src/metadata-service-error.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,wBAOX;AAPD,WAAY,wBAAwB;IAClC,yEAA6C,CAAA;IAC7C,yEAA6C,CAAA;IAC7C,2EAA+C,CAAA;IAC/C,mFAAuD,CAAA;IACvD,qEAAyC,CAAA;IACzC,mFAAuD,CAAA;AACzD,CAAC,EAPW,wBAAwB,KAAxB,wBAAwB,QAOnC;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAM7C,iEAAiE;IACjE,YAAY,IAA8B,EAAE,OAAgB,EAAE,OAAa;QACzE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF","sourcesContent":["export enum MetadataServiceErrorType {\n  networkError = 'MetadataService.NetworkError',\n  itemNotFound = 'MetadataService.ItemNotFound',\n  decodingError = 'MetadataService.DecodingError',\n  searchEngineError = 'MetadataService.SearchEngineError',\n  writeError = 'MetadataService.WriteError',\n  writeNotSupported = 'MetadataService.WriteNotSupported',\n}\n\nexport class MetadataServiceError extends Error {\n  type: MetadataServiceErrorType;\n\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  details?: any;\n\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  constructor(type: MetadataServiceErrorType, message?: string, details?: any) {\n    super(message);\n    this.name = type;\n    this.type = type;\n    this.details = details;\n  }\n}\n"]}

package/dist/src/metadata-service-interface.d.ts

@@ -1,6 +1,13 @@
 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 {
     /**
      * Fetch metadata for a given identifier
@@ -41,4 +48,39 @@ export interface MetadataServiceInterface {
      * @param keypath
      */
     fetchMetadataValue<T>(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/dist/src/metadata-service-interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-service-interface.js","sourceRoot":"","sources":["../../src/metadata-service-interface.ts"],"names":[],"mappings":"","sourcesContent":["import type { Result } from '@internetarchive/result-type';\nimport type { MetadataServiceError } from './metadata-service-error';\nimport type { MetadataResponse } from './responses/metadata-response';\n\nexport interface MetadataServiceInterface {\n  /**\n   * Fetch metadata for a given identifier\n   *\n   * @param {string} identifier\n   * @returns {Promise<Result<MetadataResponse, MetadataServiceError>>}\n   */\n  fetchMetadata(\n    identifier: string,\n  ): Promise<Result<MetadataResponse, MetadataServiceError>>;\n\n  /**\n   * Fetch the metadata value for a given identifier and keypath\n   *\n   * The response from this request can take any form, object, array, string, etc.\n   * depending on the query. You can provide return typing in the response by\n   * specifying the type. Note, there is no automatic type conversion since it can be anything.\n   *\n   * For example:\n   *\n   * ```ts\n   * const collection = await searchService.fetchMetadataValue<string>('goody', 'metadata/collection/0');\n   * console.debug('collection:', collection); => 'Goody Collection'\n   *\n   * const files_count = await searchService.fetchMetadataValue<number>('goody', 'files_count');\n   * console.debug('files_count:', files_count); => 12\n   * ```\n   *\n   * Keypath examples:\n   *\n   * /metadata/:identifier/metadata // returns the entire metadata object\n   * /metadata/:identifier/server // returns the server for the given identifier\n   * /metadata/:identifier/files_count\n   * /metadata/:identifier/files?start=1&count=2 // query for files\n   * /metadata/:identifier/metadata/collection // all collections\n   * /metadata/:identifier/metadata/collection/0 // first collection\n   * /metadata/:identifier/metadata/title\n   * /metadata/:identifier/files/0/name // first file name\n   *\n   * @param identifier\n   * @param keypath\n   */\n  fetchMetadataValue<T>(\n    identifier: string,\n    keypath: string,\n  ): Promise<Result<T, MetadataServiceError>>;\n}\n"]}
+{"version":3,"file":"metadata-service-interface.js","sourceRoot":"","sources":["../../src/metadata-service-interface.ts"],"names":[],"mappings":"","sourcesContent":["import type { Result } from '@internetarchive/result-type';\nimport type { MetadataServiceError } from './metadata-service-error';\nimport type { MetadataResponse } from './responses/metadata-response';\nimport type {\n  MetadataFieldValue,\n  MetadataPatchOperation,\n} from './metadata-patch';\n\nexport type MetadataWriteResult = {\n  /** Whether a write was sent. False when the field already had the value. */\n  changed: boolean;\n  /** The catalog task that will apply the change to the item */\n  taskId?: number;\n};\n\nexport interface MetadataServiceInterface {\n  /**\n   * Fetch metadata for a given identifier\n   *\n   * @param {string} identifier\n   * @returns {Promise<Result<MetadataResponse, MetadataServiceError>>}\n   */\n  fetchMetadata(\n    identifier: string,\n  ): Promise<Result<MetadataResponse, MetadataServiceError>>;\n\n  /**\n   * Fetch the metadata value for a given identifier and keypath\n   *\n   * The response from this request can take any form, object, array, string, etc.\n   * depending on the query. You can provide return typing in the response by\n   * specifying the type. Note, there is no automatic type conversion since it can be anything.\n   *\n   * For example:\n   *\n   * ```ts\n   * const collection = await searchService.fetchMetadataValue<string>('goody', 'metadata/collection/0');\n   * console.debug('collection:', collection); => 'Goody Collection'\n   *\n   * const files_count = await searchService.fetchMetadataValue<number>('goody', 'files_count');\n   * console.debug('files_count:', files_count); => 12\n   * ```\n   *\n   * Keypath examples:\n   *\n   * /metadata/:identifier/metadata // returns the entire metadata object\n   * /metadata/:identifier/server // returns the server for the given identifier\n   * /metadata/:identifier/files_count\n   * /metadata/:identifier/files?start=1&count=2 // query for files\n   * /metadata/:identifier/metadata/collection // all collections\n   * /metadata/:identifier/metadata/collection/0 // first collection\n   * /metadata/:identifier/metadata/title\n   * /metadata/:identifier/files/0/name // first file name\n   *\n   * @param identifier\n   * @param keypath\n   */\n  fetchMetadataValue<T>(\n    identifier: string,\n    keypath: string,\n  ): Promise<Result<T, MetadataServiceError>>;\n\n  /**\n   * Apply a JSON Patch to an item's metadata as the logged-in user.\n   *\n   * MDAPI applies the change through a queued catalog task. MDAPI reads\n   * replay pending tasks' patches (\"lookahead\"), so they show the change right\n   * away, but caches built on MDAPI (search, page services) can lag it. MDAPI\n   * rejects a patch that doesn't change the item.\n   *\n   * ```ts\n   * await metadataService.patchMetadata('goody', [\n   *   { op: 'replace', path: '/title', value: 'Goody Two-Shoes' },\n   * ]);\n   * ```\n   *\n   * @param identifier\n   * @param patch JSON Patch operations against the item's metadata\n   * @param target MDAPI write target, `metadata` by default\n   */\n  patchMetadata(\n    identifier: string,\n    patch: MetadataPatchOperation[],\n    target?: string,\n  ): Promise<Result<MetadataWriteResult, MetadataServiceError>>;\n\n  /**\n   * Set one metadata field on an item as the logged-in user. An empty string\n   * or list removes the field.\n   *\n   * Reads the item's current metadata from MDAPI first and patches against\n   * that, so the right add / replace / remove goes out even when the caller's\n   * copy is stale. That read includes this user's still-queued writes through\n   * MDAPI's lookahead, except for tasks lookahead skips (e.g. ones held for an\n   * admin). Resolves with `changed: false`, without writing, when the field\n   * already has the value.\n   *\n   * @param identifier\n   * @param field The metadata key, e.g. `title`\n   * @param value\n   */\n  updateMetadataField(\n    identifier: string,\n    field: string,\n    value: MetadataFieldValue,\n  ): Promise<Result<MetadataWriteResult, MetadataServiceError>>;\n}\n"]}

package/dist/src/metadata-service.d.ts

@@ -1,7 +1,8 @@
 import type { Result } from '@internetarchive/result-type';
 import { MetadataBackendInterface } from './backend/metadata-backend-interface';
 import { MetadataServiceError } from './metadata-service-error';
-import type { MetadataServiceInterface } from './metadata-service-interface';
+import type { MetadataServiceInterface, MetadataWriteResult } from './metadata-service-interface';
+import { type MetadataFieldValue, type MetadataPatchOperation } from './metadata-patch';
 import { MetadataResponse } from './responses/metadata-response';
 /**
  * The Metadata Service is responsible for taking the raw response provided by
@@ -15,4 +16,8 @@ export declare class MetadataService implements MetadataServiceInterface {
     fetchMetadata(identifier: string): Promise<Result<MetadataResponse, MetadataServiceError>>;
     /** @inheritdoc */
     fetchMetadataValue<T>(identifier: string, keypath: string): Promise<Result<T, MetadataServiceError>>;
+    /** @inheritdoc */
+    patchMetadata(identifier: string, patch: MetadataPatchOperation[], target?: string): Promise<Result<MetadataWriteResult, MetadataServiceError>>;
+    /** @inheritdoc */
+    updateMetadataField(identifier: string, field: string, value: MetadataFieldValue): Promise<Result<MetadataWriteResult, MetadataServiceError>>;
 }

package/dist/src/metadata-service.js

@@ -1,5 +1,6 @@
 import { DefaultMetadataBackend } from './backend/default-metadata-backend';
 import { MetadataServiceError, MetadataServiceErrorType, } from './metadata-service-error';
+import { buildMetadataFieldPatch, } from './metadata-patch';
 import { MetadataResponse } from './responses/metadata-response';
 /**
  * The Metadata Service is responsible for taking the raw response provided by
@@ -38,6 +39,33 @@ export class MetadataService {
         }
         return { success: result.success.result };
     }
+    /** @inheritdoc */
+    async patchMetadata(identifier, patch, target = 'metadata') {
+        var _a;
+        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: (_a = result.success) === null || _a === void 0 ? void 0 : _a.task_id } };
+    }
+    /** @inheritdoc */
+    async updateMetadataField(identifier, field, value) {
+        var _a;
+        const current = await this.fetchMetadataValue(identifier, 'metadata');
+        if (current.error) {
+            return { error: current.error };
+        }
+        const patch = buildMetadataFieldPatch(field, value, (_a = current.success) === null || _a === void 0 ? void 0 : _a[field]);
+        if (patch.length === 0) {
+            return { success: { changed: false } };
+        }
+        return this.patchMetadata(identifier, patch);
+    }
 }
 MetadataService.default = new MetadataService(new DefaultMetadataBackend());
 //# sourceMappingURL=metadata-service.js.map

package/dist/src/metadata-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-service.js","sourceRoot":"","sources":["../../src/metadata-service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAE5E,OAAO,EACL,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE;;;GAGG;AACH,MAAM,OAAO,eAAe;IAO1B,YAAY,OAAiC;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,kBAAkB;IAClB,KAAK,CAAC,aAAa,CACjB,UAAkB;;QAElB,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACjE,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;YACtB,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,IAAI,CAAA,MAAA,WAAW,CAAC,OAAO,0CAAE,QAAQ,MAAK,SAAS,EAAE,CAAC;YAChD,OAAO;gBACL,KAAK,EAAE,IAAI,oBAAoB,CAAC,wBAAwB,CAAC,YAAY,CAAC;aACvE,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,IAAI,gBAAgB,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAClE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;IACtC,CAAC;IAED,kBAAkB;IAClB,KAAK,CAAC,kBAAkB,CACtB,UAAkB,EAClB,OAAe;;QAEf,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACrE,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,IAAI,CAAA,MAAA,MAAM,CAAC,OAAO,0CAAE,MAAM,MAAK,SAAS,EAAE,CAAC;YACzC,OAAO;gBACL,KAAK,EAAE,IAAI,oBAAoB,CAAC,wBAAwB,CAAC,YAAY,CAAC;aACvE,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;IAC5C,CAAC;;AA9Ca,uBAAO,GAA6B,IAAI,eAAe,CACnE,IAAI,sBAAsB,EAAE,CAC7B,CAAC","sourcesContent":["import type { Result } from '@internetarchive/result-type';\nimport { DefaultMetadataBackend } from './backend/default-metadata-backend';\nimport { MetadataBackendInterface } from './backend/metadata-backend-interface';\nimport {\n  MetadataServiceError,\n  MetadataServiceErrorType,\n} from './metadata-service-error';\nimport type { MetadataServiceInterface } from './metadata-service-interface';\nimport { MetadataResponse } from './responses/metadata-response';\n\n/**\n * The Metadata Service is responsible for taking the raw response provided by\n * the backend and modeling it as a `MetadataResponse` object.\n */\nexport class MetadataService implements MetadataServiceInterface {\n  public static default: MetadataServiceInterface = new MetadataService(\n    new DefaultMetadataBackend(),\n  );\n\n  private backend: MetadataBackendInterface;\n\n  constructor(backend: MetadataBackendInterface) {\n    this.backend = backend;\n  }\n\n  /** @inheritdoc */\n  async fetchMetadata(\n    identifier: string,\n  ): Promise<Result<MetadataResponse, MetadataServiceError>> {\n    const rawResponse = await this.backend.fetchMetadata(identifier);\n    if (rawResponse.error) {\n      return rawResponse;\n    }\n\n    if (rawResponse.success?.metadata === undefined) {\n      return {\n        error: new MetadataServiceError(MetadataServiceErrorType.itemNotFound),\n      };\n    }\n\n    const modeledResponse = new MetadataResponse(rawResponse.success);\n    return { success: modeledResponse };\n  }\n\n  /** @inheritdoc */\n  async fetchMetadataValue<T>(\n    identifier: string,\n    keypath: string,\n  ): Promise<Result<T, MetadataServiceError>> {\n    const result = await this.backend.fetchMetadata(identifier, keypath);\n    if (result.error) {\n      return result;\n    }\n\n    if (result.success?.result === undefined) {\n      return {\n        error: new MetadataServiceError(MetadataServiceErrorType.itemNotFound),\n      };\n    }\n\n    return { success: result.success.result };\n  }\n}\n"]}
+{"version":3,"file":"metadata-service.js","sourceRoot":"","sources":["../../src/metadata-service.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Result } from '@internetarchive/result-type';\nimport { DefaultMetadataBackend } from './backend/default-metadata-backend';\nimport { MetadataBackendInterface } from './backend/metadata-backend-interface';\nimport {\n  MetadataServiceError,\n  MetadataServiceErrorType,\n} from './metadata-service-error';\nimport type {\n  MetadataServiceInterface,\n  MetadataWriteResult,\n} from './metadata-service-interface';\nimport {\n  buildMetadataFieldPatch,\n  type MetadataFieldValue,\n  type MetadataPatchOperation,\n} from './metadata-patch';\nimport { MetadataResponse } from './responses/metadata-response';\n\n/**\n * The Metadata Service is responsible for taking the raw response provided by\n * the backend and modeling it as a `MetadataResponse` object.\n */\nexport class MetadataService implements MetadataServiceInterface {\n  public static default: MetadataServiceInterface = new MetadataService(\n    new DefaultMetadataBackend(),\n  );\n\n  private backend: MetadataBackendInterface;\n\n  constructor(backend: MetadataBackendInterface) {\n    this.backend = backend;\n  }\n\n  /** @inheritdoc */\n  async fetchMetadata(\n    identifier: string,\n  ): Promise<Result<MetadataResponse, MetadataServiceError>> {\n    const rawResponse = await this.backend.fetchMetadata(identifier);\n    if (rawResponse.error) {\n      return rawResponse;\n    }\n\n    if (rawResponse.success?.metadata === undefined) {\n      return {\n        error: new MetadataServiceError(MetadataServiceErrorType.itemNotFound),\n      };\n    }\n\n    const modeledResponse = new MetadataResponse(rawResponse.success);\n    return { success: modeledResponse };\n  }\n\n  /** @inheritdoc */\n  async fetchMetadataValue<T>(\n    identifier: string,\n    keypath: string,\n  ): Promise<Result<T, MetadataServiceError>> {\n    const result = await this.backend.fetchMetadata(identifier, keypath);\n    if (result.error) {\n      return result;\n    }\n\n    if (result.success?.result === undefined) {\n      return {\n        error: new MetadataServiceError(MetadataServiceErrorType.itemNotFound),\n      };\n    }\n\n    return { success: result.success.result };\n  }\n\n  /** @inheritdoc */\n  async patchMetadata(\n    identifier: string,\n    patch: MetadataPatchOperation[],\n    target = 'metadata',\n  ): Promise<Result<MetadataWriteResult, MetadataServiceError>> {\n    if (!this.backend.writeMetadata) {\n      return {\n        error: new MetadataServiceError(\n          MetadataServiceErrorType.writeNotSupported,\n          'This metadata backend does not support writes',\n        ),\n      };\n    }\n\n    const result = await this.backend.writeMetadata(identifier, target, patch);\n    if (result.error) {\n      return result;\n    }\n\n    return { success: { changed: true, taskId: result.success?.task_id } };\n  }\n\n  /** @inheritdoc */\n  async updateMetadataField(\n    identifier: string,\n    field: string,\n    value: MetadataFieldValue,\n  ): Promise<Result<MetadataWriteResult, MetadataServiceError>> {\n    const current = await this.fetchMetadataValue<\n      Record<string, MetadataFieldValue>\n    >(identifier, 'metadata');\n    if (current.error) {\n      return { error: current.error };\n    }\n\n    const patch = buildMetadataFieldPatch(\n      field,\n      value,\n      current.success?.[field],\n    );\n    if (patch.length === 0) {\n      return { success: { changed: false } };\n    }\n\n    return this.patchMetadata(identifier, patch);\n  }\n}\n"]}

package/dist/src/responses/metadata-response.d.ts

@@ -1,4 +1,21 @@
 import { File, Metadata, Review, SpeechMusicASREntry } from '@internetarchive/iaux-item-metadata';
+/**
+ * A single alternate download location: a server and the directory on it that
+ * holds the item's files.
+ */
+export type AlternateLocation = {
+    server: string;
+    dir: string;
+};
+/**
+ * Alternate download locations for an item, beyond the primary `server`/`dir`.
+ * `servers` lists all known mirrors; `workable` is the subset currently
+ * reachable for downloads.
+ */
+export type AlternateLocations = {
+    servers: AlternateLocation[];
+    workable: AlternateLocation[];
+};
 /**
  * The main top-level reponse when fetching Metadata
  *
@@ -21,5 +38,10 @@ export declare class MetadataResponse {
     readonly workable_servers: string[];
     readonly speech_vs_music_asr?: SpeechMusicASREntry[];
     readonly reviews?: Review[];
+    readonly alternate_locations?: AlternateLocations;
+    readonly clips?: Record<string, unknown>;
+    readonly plays?: Record<string, unknown>;
+    readonly simplelists?: Record<string, unknown>;
+    readonly solo?: boolean;
     constructor(json: Record<string, any>);
 }

package/dist/src/responses/metadata-response.js

@@ -27,6 +27,11 @@ export class MetadataResponse {
         this.reviews = (_b = json.reviews) === null || _b === void 0 ? void 0 : _b.map(
         /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
         (entry) => new Review(entry));
+        this.alternate_locations = json.alternate_locations;
+        this.clips = json.clips;
+        this.plays = json.plays;
+        this.simplelists = json.simplelists;
+        this.solo = json.solo;
     }
 }
 //# sourceMappingURL=metadata-response.js.map

package/dist/src/responses/metadata-response.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-response.js","sourceRoot":"","sources":["../../../src/responses/metadata-response.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,MAAM,GAEP,MAAM,qCAAqC,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAgC3B,iEAAiE;IACjE,YAAY,IAAyB;;QACnC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QAClB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QAClB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,iEAAiE;QACjE,IAAI,CAAC,KAAK,GAAG,MAAA,IAAI,CAAC,KAAK,0CAAE,GAAG,CAAC,CAAC,IAAyB,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5E,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAChD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC;QAC9C,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACpD,IAAI,CAAC,OAAO,GAAG,MAAA,IAAI,CAAC,OAAO,0CAAE,GAAG;QAC9B,iEAAiE;QACjE,CAAC,KAA0B,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAClD,CAAC;IACJ,CAAC;CACF","sourcesContent":["import {\n  File,\n  Metadata,\n  Review,\n  SpeechMusicASREntry,\n} from '@internetarchive/iaux-item-metadata';\n\n/**\n * The main top-level reponse when fetching Metadata\n *\n * @export\n * @class MetadataResponse\n */\nexport class MetadataResponse {\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  readonly rawResponse: Readonly<Record<string, any>>;\n\n  readonly created: number;\n\n  readonly d1: string;\n\n  readonly d2: string;\n\n  readonly dir: string;\n\n  readonly files: File[];\n\n  readonly files_count: number;\n\n  readonly item_last_updated: number;\n\n  readonly item_size: number;\n\n  readonly metadata: Metadata;\n\n  readonly server: string;\n\n  readonly uniq: number;\n\n  readonly workable_servers: string[];\n\n  readonly speech_vs_music_asr?: SpeechMusicASREntry[];\n\n  readonly reviews?: Review[];\n\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  constructor(json: Record<string, any>) {\n    this.rawResponse = json;\n    this.created = json.created;\n    this.d1 = json.d1;\n    this.d2 = json.d2;\n    this.dir = json.dir;\n    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n    this.files = json.files?.map((file: Record<string, any>) => new File(file));\n    this.files_count = json.files_count;\n    this.item_last_updated = json.item_last_updated;\n    this.item_size = json.item_size;\n    this.metadata = new Metadata(json.metadata);\n    this.server = json.server;\n    this.uniq = json.uniq;\n    this.workable_servers = json.workable_servers;\n    this.speech_vs_music_asr = json.speech_vs_music_asr;\n    this.reviews = json.reviews?.map(\n      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n      (entry: Record<string, any>) => new Review(entry),\n    );\n  }\n}\n"]}
+{"version":3,"file":"metadata-response.js","sourceRoot":"","sources":["../../../src/responses/metadata-response.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,MAAM,GAEP,MAAM,qCAAqC,CAAC;AAqB7C;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IA0C3B,iEAAiE;IACjE,YAAY,IAAyB;;QACnC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QAClB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QAClB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,iEAAiE;QACjE,IAAI,CAAC,KAAK,GAAG,MAAA,IAAI,CAAC,KAAK,0CAAE,GAAG,CAAC,CAAC,IAAyB,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5E,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAChD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC;QAC9C,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACpD,IAAI,CAAC,OAAO,GAAG,MAAA,IAAI,CAAC,OAAO,0CAAE,GAAG;QAC9B,iEAAiE;QACjE,CAAC,KAA0B,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAClD,CAAC;QACF,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACpD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;CACF","sourcesContent":["import {\n  File,\n  Metadata,\n  Review,\n  SpeechMusicASREntry,\n} from '@internetarchive/iaux-item-metadata';\n\n/**\n * A single alternate download location: a server and the directory on it that\n * holds the item's files.\n */\nexport type AlternateLocation = {\n  server: string;\n  dir: string;\n};\n\n/**\n * Alternate download locations for an item, beyond the primary `server`/`dir`.\n * `servers` lists all known mirrors; `workable` is the subset currently\n * reachable for downloads.\n */\nexport type AlternateLocations = {\n  servers: AlternateLocation[];\n  workable: AlternateLocation[];\n};\n\n/**\n * The main top-level reponse when fetching Metadata\n *\n * @export\n * @class MetadataResponse\n */\nexport class MetadataResponse {\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  readonly rawResponse: Readonly<Record<string, any>>;\n\n  readonly created: number;\n\n  readonly d1: string;\n\n  readonly d2: string;\n\n  readonly dir: string;\n\n  readonly files: File[];\n\n  readonly files_count: number;\n\n  readonly item_last_updated: number;\n\n  readonly item_size: number;\n\n  readonly metadata: Metadata;\n\n  readonly server: string;\n\n  readonly uniq: number;\n\n  readonly workable_servers: string[];\n\n  readonly speech_vs_music_asr?: SpeechMusicASREntry[];\n\n  readonly reviews?: Review[];\n\n  readonly alternate_locations?: AlternateLocations;\n\n  readonly clips?: Record<string, unknown>;\n\n  readonly plays?: Record<string, unknown>;\n\n  readonly simplelists?: Record<string, unknown>;\n\n  readonly solo?: boolean;\n\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  constructor(json: Record<string, any>) {\n    this.rawResponse = json;\n    this.created = json.created;\n    this.d1 = json.d1;\n    this.d2 = json.d2;\n    this.dir = json.dir;\n    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n    this.files = json.files?.map((file: Record<string, any>) => new File(file));\n    this.files_count = json.files_count;\n    this.item_last_updated = json.item_last_updated;\n    this.item_size = json.item_size;\n    this.metadata = new Metadata(json.metadata);\n    this.server = json.server;\n    this.uniq = json.uniq;\n    this.workable_servers = json.workable_servers;\n    this.speech_vs_music_asr = json.speech_vs_music_asr;\n    this.reviews = json.reviews?.map(\n      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n      (entry: Record<string, any>) => new Review(entry),\n    );\n    this.alternate_locations = json.alternate_locations;\n    this.clips = json.clips;\n    this.plays = json.plays;\n    this.simplelists = json.simplelists;\n    this.solo = json.solo;\n  }\n}\n"]}

package/dist/test/default-metadata-backend.test.js

@@ -87,4 +87,56 @@ 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 () => {
+        var _a, _b;
+        let requestUrl = '';
+        let requestInit;
+        window.fetch = async (input, init) => {
+            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', path: '/title', value: 'New' }];
+        const result = await backend.writeMetadata('foo', 'metadata', patch);
+        expect((_a = result.success) === null || _a === void 0 ? void 0 : _a.task_id).to.equal(7);
+        expect(requestUrl).to.equal('https://archive.org/metadata/foo');
+        expect(requestInit === null || requestInit === void 0 ? void 0 : requestInit.method).to.equal('POST');
+        expect(requestInit === null || requestInit === void 0 ? void 0 : requestInit.credentials).to.equal('include');
+        const body = requestInit === null || requestInit === void 0 ? void 0 : requestInit.body;
+        expect(body.get('-target')).to.equal('metadata');
+        expect(JSON.parse((_b = body.get('-patch')) !== null && _b !== void 0 ? _b : '')).to.deep.equal(patch);
+    });
+    it('returns a writeError with MDAPI’s message when the write is rejected', async () => {
+        var _a, _b;
+        window.fetch = async () => new Response('{ "success": false, "error": "Authorization failed" }', {
+            status: 401,
+        });
+        const backend = new DefaultMetadataBackend();
+        const result = await backend.writeMetadata('foo', 'metadata', []);
+        expect((_a = result.error) === null || _a === void 0 ? void 0 : _a.type).to.equal(MetadataServiceErrorType.writeError);
+        expect((_b = result.error) === null || _b === void 0 ? void 0 : _b.message).to.equal('Authorization failed');
+    });
+    it('returns a writeError when MDAPI does not report success', async () => {
+        var _a;
+        window.fetch = async () => new Response('{}');
+        const backend = new DefaultMetadataBackend();
+        const result = await backend.writeMetadata('foo', 'metadata', []);
+        expect((_a = result.error) === null || _a === void 0 ? void 0 : _a.type).to.equal(MetadataServiceErrorType.writeError);
+    });
+    it('returns a networkError when the request fails', async () => {
+        var _a;
+        window.fetch = async () => {
+            throw new Error('offline');
+        };
+        const backend = new DefaultMetadataBackend();
+        const result = await backend.writeMetadata('foo', 'metadata', []);
+        expect((_a = result.error) === null || _a === void 0 ? void 0 : _a.type).to.equal(MetadataServiceErrorType.networkError);
+    });
+});
 //# sourceMappingURL=default-metadata-backend.test.js.map