@opentermsarchive/engine 11.0.2 → 12.0.0

package/.eslintrc.yaml

@@ -37,6 +37,9 @@ rules:
     - error
     - always-multiline
   consistent-return: 0
+  curly:
+    - error
+    - all 
   function-paren-newline:
     - error
     - multiline

package/config/default.json

@@ -47,6 +47,11 @@
     },
     "dataset": {
       "publishingSchedule": "30 8 * * MON"
+    },
+    "collection-api": {
+      "feed": {
+        "limit": 100
+      }
     }
   }
 }

package/config/test.json

@@ -47,7 +47,10 @@
     },
     "collection-api": {
       "port": 3000,
-      "basePath": "/collection-api"
+      "basePath": "/collection-api",
+      "feed": {
+        "limit": 3
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentermsarchive/engine",
-  "version": "11.0.2",
+  "version": "12.0.0",
   "description": "Tracks and makes visible changes to the terms of online services",
   "homepage": "https://opentermsarchive.org",
   "bugs": {
@@ -100,7 +100,8 @@
     "swagger-ui-express": "^5.0.1",
     "turndown": "^7.2.1",
     "winston": "^3.17.0",
-    "winston-mail": "^2.0.0"
+    "winston-mail": "^2.0.0",
+    "xml-js": "^1.6.11"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.8.1",

package/scripts/reporter/duplicate/index.js

@@ -39,7 +39,7 @@ async function removeDuplicateIssues() {
   }
 
   for (const [ title, duplicateIssues ] of issuesByTitle) {
-    if (duplicateIssues.length === 1) continue;
+    if (duplicateIssues.length === 1) { continue; }
 
     const originalIssue = duplicateIssues.reduce((oldest, current) => (new Date(current.created_at) < new Date(oldest.created_at) ? current : oldest));
 

package/src/archivist/collection/index.test.js

@@ -18,7 +18,7 @@ describe('Collection', () => {
     try {
       metadataBackup = await fs.readFile(metadataPath, 'utf8');
     } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
+      if (error.code !== 'ENOENT') { throw error; }
     }
   });
 

package/src/archivist/recorder/record.js

@@ -3,6 +3,13 @@
  * @class Record
  * @private
  */
+
+export const TITLE_PREFIXES = Object.freeze({
+  firstRecord: 'First record of',
+  technicalUpgrade: 'Apply technical or declaration upgrade on',
+  update: 'Record new changes of',
+});
+
 export default class Record {
   #content;
 
@@ -32,6 +39,20 @@ export default class Record {
     this.#content = content;
   }
 
+  get displayTitle() {
+    let prefix;
+
+    if (this.isFirstRecord) {
+      prefix = TITLE_PREFIXES.firstRecord;
+    } else if (this.isTechnicalUpgrade) {
+      prefix = TITLE_PREFIXES.technicalUpgrade;
+    } else {
+      prefix = TITLE_PREFIXES.update;
+    }
+
+    return `${prefix} ${this.serviceId} ${this.termsType}`;
+  }
+
   validate() {
     for (const requiredParam of this.constructor.REQUIRED_PARAMS) {
       if (requiredParam == 'content') {

package/src/archivist/recorder/repositories/git/dataMapper.js

@@ -2,18 +2,27 @@ import path from 'path';
 
 import mime from 'mime';
 
+import { TITLE_PREFIXES } from '../../record.js';
 import Snapshot from '../../snapshot.js';
 import Version from '../../version.js';
 
-export const COMMIT_MESSAGE_PREFIXES = {
-  startTracking: 'First record of',
-  technicalUpgrade: 'Apply technical or declaration upgrade on',
-  update: 'Record new changes of',
+// Prefixes for commits that represent an actual content change detected at the service source
+const CHANGE_PREFIXES = {
+  startTracking: TITLE_PREFIXES.firstRecord,
+  update: TITLE_PREFIXES.update,
   deprecated_startTracking: 'Start tracking',
-  deprecated_refilter: 'Refilter',
   deprecated_update: 'Update',
 };
 
+// Prefixes for commits that re-render an existing snapshot (e.g. with updated extraction rules) without any change at the service source
+const TECHNICAL_UPGRADE_PREFIXES = {
+  technicalUpgrade: TITLE_PREFIXES.technicalUpgrade,
+  deprecated_refilter: 'Refilter',
+};
+
+export const CHANGE_COMMIT_MESSAGE_PREFIXES = CHANGE_PREFIXES;
+export const COMMIT_MESSAGE_PREFIXES = { ...CHANGE_PREFIXES, ...TECHNICAL_UPGRADE_PREFIXES };
+
 export const TERMS_TYPE_AND_DOCUMENT_ID_SEPARATOR = ' #';
 export const SNAPSHOT_ID_MARKER = '%SNAPSHOT_ID';
 const SINGLE_SOURCE_DOCUMENT_PREFIX = 'This version was recorded after extracting from snapshot';
@@ -22,13 +31,9 @@ const MULTIPLE_SOURCE_DOCUMENTS_PREFIX = 'This version was recorded after extrac
 export const COMMIT_MESSAGE_PREFIXES_REGEXP = new RegExp(`^(${Object.values(COMMIT_MESSAGE_PREFIXES).join('|')})`);
 
 export function toPersistence(record, snapshotIdentiferTemplate) {
-  const { serviceId, termsType, documentId, isTechnicalUpgrade, snapshotIds = [], mimeType, isFirstRecord, metadata } = record;
+  const { serviceId, termsType, documentId, snapshotIds = [], mimeType, metadata } = record;
 
-  let prefix = isTechnicalUpgrade ? COMMIT_MESSAGE_PREFIXES.technicalUpgrade : COMMIT_MESSAGE_PREFIXES.update;
-
-  prefix = isFirstRecord ? COMMIT_MESSAGE_PREFIXES.startTracking : prefix;
-
-  const subject = `${prefix} ${serviceId} ${termsType}`;
+  const subject = record.displayTitle;
   const documentIdMessage = `${documentId ? `Document ID ${documentId}\n\n` : ''}`;
   let snapshotIdsMessage;
 
@@ -91,6 +96,10 @@ function generateFileName(termsType, documentId, extension) {
 }
 
 export function generateFilePath(serviceId, termsType, documentId, mimeType) {
+  if (termsType === undefined) {
+    return `${serviceId}/*`; // If only serviceId is provided, return a pattern to match all files for that service
+  }
+
   const extension = mime.getExtension(mimeType) || '*'; // If mime type is undefined, an asterisk is set as an extension. Used to match all files for the given service ID, terms type and document ID when mime type is unknown
 
   return `${serviceId}/${generateFileName(termsType, documentId, extension)}`; // Do not use `path.join` as even for Windows, the path should be with `/` and not `\`

package/src/archivist/recorder/repositories/git/git.js

@@ -68,8 +68,20 @@ export default class Git {
     return this.git.push();
   }
 
-  listCommits(options = []) {
-    return this.log([ '--reverse', '--no-merges', '--name-only', ...options ]); // Returns all commits in chronological order (`--reverse`), excluding merge commits (`--no-merges`), with modified files names (`--name-only`)
+  listCommits(options = [], { reverse = true, skip, maxCount } = {}) {
+    const reverseOption = reverse ? ['--reverse'] : [];
+    const skipOption = skip !== undefined ? [`--skip=${skip}`] : [];
+    const maxCountOption = maxCount !== undefined ? [`--max-count=${maxCount}`] : [];
+
+    return this.log([
+      ...reverseOption, // When `reverse` is true, lists commits oldest-first; otherwise the default newest-first applies
+      '--author-date-order', // Best-effort author-date ordering: with --max-count, git applies the cap topologically, so the page can miss strictly-newer commits that #getCommits' JS resort cannot recover
+      '--no-merges', // Exclude merge commits — records are stored as regular commits, never as merges
+      '--name-only', // Append the modified file names below each commit, used by `toDomain` to extract the record's file path
+      ...skipOption, // Optional `--skip=N`: drop the first N matching commits (pagination offset)
+      ...maxCountOption, // Optional `--max-count=N`: cap the result to N commits (pagination limit)
+      ...options, // Caller-supplied options: typically grep filters on commit messages and a path filter (`-- pathspec`)
+    ]);
   }
 
   async getCommit(options) {

package/src/archivist/recorder/repositories/git/index.js

@@ -88,16 +88,43 @@ export default class GitRepository extends RepositoryInterface {
     return this.#toDomain(commit);
   }
 
-  async findAll() {
-    return Promise.all((await this.#getCommits()).map(commit => this.#toDomain(commit, { deferContentLoading: true })));
+  async findAll({ limit, offset, includeTechnicalUpgrades = true } = {}) {
+    return Promise.all((await this.#getCommits({ limit, offset, includeTechnicalUpgrades })).map(commit => this.#toDomain(commit, { deferContentLoading: true })));
   }
 
-  async count() {
-    return (await this.git.log(Object.values(DataMapper.COMMIT_MESSAGE_PREFIXES).map(prefix => `--grep=${prefix}`))).length;
+  async findByService(serviceId, { limit, offset, includeTechnicalUpgrades = true } = {}) {
+    const pathPattern = DataMapper.generateFilePath(serviceId);
+
+    return Promise.all((await this.#getCommits({ pathFilter: pathPattern, limit, offset, includeTechnicalUpgrades })).map(commit => this.#toDomain(commit, { deferContentLoading: true })));
+  }
+
+  async findByServiceAndTermsType(serviceId, termsType, { limit, offset, includeTechnicalUpgrades = true } = {}) {
+    const pathPattern = DataMapper.generateFilePath(serviceId, termsType);
+
+    return Promise.all((await this.#getCommits({ pathFilter: pathPattern, limit, offset, includeTechnicalUpgrades })).map(commit => this.#toDomain(commit, { deferContentLoading: true })));
+  }
+
+  async count(serviceId, termsType) {
+    const grepOptions = Object.values(DataMapper.COMMIT_MESSAGE_PREFIXES).map(prefix => `--grep=${prefix}`);
+    const pathOptions = [];
+
+    if (serviceId && termsType) {
+      const pathPattern = DataMapper.generateFilePath(serviceId, termsType);
+
+      pathOptions.push('--', pathPattern);
+    } else if (serviceId) {
+      const pathPattern = DataMapper.generateFilePath(serviceId);
+
+      pathOptions.push('--', pathPattern);
+    } else {
+      pathOptions.push('--', '*/*'); // Count all records (exclude root directory files)
+    }
+
+    return (await this.git.log([ ...grepOptions, ...pathOptions ])).length;
   }
 
   async* iterate() {
-    const commits = await this.#getCommits();
+    const commits = await this.#getCommits({ reverse: true });
 
     for (const commit of commits) {
       yield this.#toDomain(commit);
@@ -131,12 +158,41 @@ export default class GitRepository extends RepositoryInterface {
     record.content = pdfBuffer;
   }
 
-  async #getCommits() {
-    return (await this.git.listCommits())
-      .filter(commit => // Skip non-record commits (e.g., README or LICENSE updates)
-        DataMapper.COMMIT_MESSAGE_PREFIXES_REGEXP.test(commit.message) // Commits generated by the engine have messages that match predefined prefixes
-        && path.dirname(commit.diff.files[0].file) !== '.') // Assumes one record per commit; records must be in a serviceId folder, not root
-      .sort((commitA, commitB) => new Date(commitA.date) - new Date(commitB.date)); // Make sure that the commits are sorted in ascending chronological order
+  async #getCommits({ pathFilter, reverse = false, limit, offset, includeTechnicalUpgrades = true } = {}) {
+    const prefixes = includeTechnicalUpgrades
+      ? DataMapper.COMMIT_MESSAGE_PREFIXES
+      : DataMapper.CHANGE_COMMIT_MESSAGE_PREFIXES;
+    const grepOptions = Object.values(prefixes).flatMap(prefix => [ '--grep', prefix ]);
+    const pathOptions = pathFilter
+      ? [ '--', pathFilter ]
+      : [ '--', '*/*' ]; // Exclude root directory files by only matching files in subdirectories
+
+    const options = [ ...grepOptions, ...pathOptions ];
+
+    // Use git-level pagination for performance: `--skip` and `--max-count` count in topological order, not strictly chronological.
+    // In records history, the only commits whose author date is out of step with their topological position are technical upgrades.
+    // The only caller currently relying on pagination is the feed endpoint, which already filters technical upgrades out via `includeTechnicalUpgrades: false`, so the paginated set has no chronological/topological divergence in practice.
+    // If a future caller needs paginated access that includes technical upgrades, switch to the approach proposed in https://github.com/OpenTermsArchive/engine/issues/1243.
+    const paginationOptions = {};
+
+    if (offset !== undefined) {
+      paginationOptions.skip = offset;
+    }
+
+    if (limit !== undefined) {
+      paginationOptions.maxCount = limit;
+    }
+
+    const commits = await this.git.listCommits(options, { reverse: false, ...paginationOptions }); // Get commits without git's --reverse for better performance, filtered at git level
+
+    commits.sort((commitA, commitB) => {
+      const dateA = new Date(commitA.date);
+      const dateB = new Date(commitB.date);
+
+      return reverse ? dateA - dateB : dateB - dateA;
+    });
+
+    return commits;
   }
 
   static async writeFile({ filePath, content }) {

package/src/archivist/recorder/repositories/git/index.test.js

@@ -540,8 +540,253 @@ describe('GitRepository', () => {
         }
       });
 
-      it('returns records in ascending order', () => {
-        expect(records.map(record => record.fetchDate)).to.deep.equal([ FETCH_DATE_EARLIER, FETCH_DATE, FETCH_DATE_LATER ]);
+      it('returns records in descending order', () => {
+        expect(records.map(record => record.fetchDate)).to.deep.equal([ FETCH_DATE_LATER, FETCH_DATE, FETCH_DATE_EARLIER ]);
+      });
+
+      context('with includeTechnicalUpgrades: false', () => {
+        let filteredRecords;
+
+        before(async () => {
+          filteredRecords = await subject.findAll({ includeTechnicalUpgrades: false });
+        });
+
+        it('excludes technical upgrade records', () => {
+          expect(filteredRecords.length).to.equal(2);
+        });
+
+        it('only returns records that represent actual content changes', () => {
+          for (const record of filteredRecords) {
+            expect(record.isTechnicalUpgrade).to.not.be.true;
+          }
+        });
+
+        it('returns the expected records in descending order', () => {
+          expect(filteredRecords.map(record => record.fetchDate)).to.deep.equal([ FETCH_DATE_LATER, FETCH_DATE ]);
+        });
+      });
+    });
+
+    describe('#findByServiceAndTermsType', () => {
+      const expectedIds = [];
+      let records;
+
+      before(async function () {
+        this.timeout(5000);
+
+        const { id: id1 } = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: CONTENT,
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        expectedIds.push(id1);
+
+        const { id: id2 } = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: `${CONTENT} - updated`,
+          fetchDate: FETCH_DATE_LATER,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        expectedIds.push(id2);
+
+        await subject.save(new Version({
+          serviceId: 'other_service',
+          termsType: 'Privacy Policy',
+          content: `${CONTENT} - other`,
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        (records = await subject.findByServiceAndTermsType(SERVICE_PROVIDER_ID, TERMS_TYPE));
+      });
+
+      after(() => subject.removeAll());
+
+      it('returns only matching records', () => {
+        expect(records.length).to.equal(2);
+      });
+
+      it('returns Version objects', () => {
+        for (const record of records) {
+          expect(record).to.be.an.instanceof(Version);
+        }
+      });
+
+      it('returns records with matching service ID', () => {
+        for (const record of records) {
+          expect(record.serviceId).to.equal(SERVICE_PROVIDER_ID);
+        }
+      });
+
+      it('returns records with matching terms type', () => {
+        for (const record of records) {
+          expect(record.termsType).to.equal(TERMS_TYPE);
+        }
+      });
+
+      it('returns records in descending order', () => {
+        expect(records.map(record => record.fetchDate)).to.deep.equal([ FETCH_DATE_LATER, FETCH_DATE ]);
+      });
+
+      it('returns records with correct IDs', () => {
+        expect(records.map(record => record.id)).to.have.members(expectedIds);
+      });
+
+      context('when no matching records exist', () => {
+        it('returns an empty array', async () => {
+          const result = await subject.findByServiceAndTermsType('non_existent_service', 'Non Existent Terms');
+
+          expect(result).to.be.an('array').that.is.empty;
+        });
+      });
+
+      context('with includeTechnicalUpgrades: false', () => {
+        let filteredRecords;
+        let technicalUpgradeId;
+
+        before(async () => {
+          ({ id: technicalUpgradeId } = await subject.save(new Version({
+            serviceId: SERVICE_PROVIDER_ID,
+            termsType: TERMS_TYPE,
+            content: `${CONTENT} - technical upgrade`,
+            fetchDate: FETCH_DATE_EARLIER,
+            snapshotIds: [SNAPSHOT_ID],
+            isTechnicalUpgrade: true,
+          })));
+
+          filteredRecords = await subject.findByServiceAndTermsType(SERVICE_PROVIDER_ID, TERMS_TYPE, { includeTechnicalUpgrades: false });
+        });
+
+        it('excludes technical upgrade records', () => {
+          expect(filteredRecords.map(record => record.id)).to.not.include(technicalUpgradeId);
+        });
+
+        it('only returns records that represent actual content changes', () => {
+          for (const record of filteredRecords) {
+            expect(record.isTechnicalUpgrade).to.not.be.true;
+          }
+        });
+      });
+    });
+
+    describe('#findByService', () => {
+      const OTHER_TERMS_TYPE = 'Privacy Policy';
+      const expectedIds = [];
+      let records;
+
+      before(async function () {
+        this.timeout(5000);
+
+        const { id: id1 } = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: CONTENT,
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        expectedIds.push(id1);
+
+        const { id: id2 } = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: `${CONTENT} - updated`,
+          fetchDate: FETCH_DATE_LATER,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        expectedIds.push(id2);
+
+        const { id: id3 } = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: OTHER_TERMS_TYPE,
+          content: `${CONTENT} - other terms type`,
+          fetchDate: FETCH_DATE_EARLIER,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        expectedIds.push(id3);
+
+        await subject.save(new Version({
+          serviceId: 'other_service',
+          termsType: TERMS_TYPE,
+          content: `${CONTENT} - other service`,
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        (records = await subject.findByService(SERVICE_PROVIDER_ID));
+      });
+
+      after(() => subject.removeAll());
+
+      it('returns only matching records', () => {
+        expect(records.length).to.equal(3);
+      });
+
+      it('returns Version objects', () => {
+        for (const record of records) {
+          expect(record).to.be.an.instanceof(Version);
+        }
+      });
+
+      it('returns records with matching service ID', () => {
+        for (const record of records) {
+          expect(record.serviceId).to.equal(SERVICE_PROVIDER_ID);
+        }
+      });
+
+      it('returns records across all terms types of the service', () => {
+        expect(new Set(records.map(record => record.termsType))).to.deep.equal(new Set([ TERMS_TYPE, OTHER_TERMS_TYPE ]));
+      });
+
+      it('returns records in descending order', () => {
+        expect(records.map(record => record.fetchDate)).to.deep.equal([ FETCH_DATE_LATER, FETCH_DATE, FETCH_DATE_EARLIER ]);
+      });
+
+      it('returns records with correct IDs', () => {
+        expect(records.map(record => record.id)).to.have.members(expectedIds);
+      });
+
+      context('when no matching records exist', () => {
+        it('returns an empty array', async () => {
+          const result = await subject.findByService('non_existent_service');
+
+          expect(result).to.be.an('array').that.is.empty;
+        });
+      });
+
+      context('with includeTechnicalUpgrades: false', () => {
+        let filteredRecords;
+        let technicalUpgradeId;
+
+        before(async () => {
+          ({ id: technicalUpgradeId } = await subject.save(new Version({
+            serviceId: SERVICE_PROVIDER_ID,
+            termsType: TERMS_TYPE,
+            content: `${CONTENT} - technical upgrade`,
+            fetchDate: new Date('2000-01-03T12:00:00.000Z'),
+            snapshotIds: [SNAPSHOT_ID],
+            isTechnicalUpgrade: true,
+          })));
+
+          filteredRecords = await subject.findByService(SERVICE_PROVIDER_ID, { includeTechnicalUpgrades: false });
+        });
+
+        it('excludes technical upgrade records', () => {
+          expect(filteredRecords.map(record => record.id)).to.not.include(technicalUpgradeId);
+        });
+
+        it('only returns records that represent actual content changes', () => {
+          for (const record of filteredRecords) {
+            expect(record.isTechnicalUpgrade).to.not.be.true;
+          }
+        });
       });
     });
 
@@ -582,6 +827,37 @@ describe('GitRepository', () => {
       it('returns the proper count', () => {
         expect(count).to.equal(3);
       });
+
+      context('with serviceId and termsType filters', () => {
+        it('returns count for specific service and terms type', async () => {
+          const filteredCount = await subject.count(SERVICE_PROVIDER_ID, TERMS_TYPE);
+
+          expect(filteredCount).to.equal(3);
+        });
+
+        it('returns zero for non-existent service', async () => {
+          const filteredCount = await subject.count('non-existent-service', TERMS_TYPE);
+
+          expect(filteredCount).to.equal(0);
+        });
+      });
+
+      context('with only serviceId filter', () => {
+        it('returns count for all terms types of a service', async () => {
+          // Add a version with different terms type
+          await subject.save(new Version({
+            serviceId: SERVICE_PROVIDER_ID,
+            termsType: 'Different Terms',
+            content: CONTENT,
+            fetchDate: FETCH_DATE,
+            snapshotIds: [SNAPSHOT_ID],
+          }));
+
+          const filteredCount = await subject.count(SERVICE_PROVIDER_ID);
+
+          expect(filteredCount).to.equal(4); // 3 from TERMS_TYPE + 1 from 'Different Terms'
+        });
+      });
     });
 
     describe('#findLatest', () => {
@@ -1101,8 +1377,8 @@ describe('GitRepository', () => {
         }
       });
 
-      it('returns records in ascending order', () => {
-        expect(records.map(record => record.fetchDate)).to.deep.equal([ FETCH_DATE_EARLIER, FETCH_DATE, FETCH_DATE_LATER ]);
+      it('returns records in descending order', () => {
+        expect(records.map(record => record.fetchDate)).to.deep.equal([ FETCH_DATE_LATER, FETCH_DATE, FETCH_DATE_EARLIER ]);
       });
     });
 
@@ -1462,8 +1738,8 @@ describe('GitRepository', () => {
         }
       });
 
-      it('returns records in ascending order', () => {
-        expect(records.map(record => record.fetchDate)).to.deep.equal(expectedDates);
+      it('returns records in descending order', () => {
+        expect(records.map(record => record.fetchDate)).to.deep.equal([...expectedDates].reverse());
       });
     });
 

package/src/archivist/recorder/repositories/interface.js

@@ -70,21 +70,59 @@ class RepositoryInterface {
   }
 
   /**
-   * Find all records
+   * Find all records, in descending chronological order (newest first; opposite of #iterate)
    * For performance reasons, the content of the records will not be loaded by default. Use #loadRecordContent to load the content of individual records
-   * @see RepositoryInterface#loadRecordContent
-   * @returns {Promise<Array<Record>>} Promise that will be resolved with an array of all records
+   * @see     RepositoryInterface#loadRecordContent
+   * @see     RepositoryInterface#iterate
+   * @param   {object}                 [options]                          - Query options
+   * @param   {number}                 [options.limit]                    - Maximum number of records to return
+   * @param   {number}                 [options.offset]                   - Number of records to skip
+   * @param   {boolean}                [options.includeTechnicalUpgrades] - When false, exclude technical upgrade records (re-renders of existing snapshots) and only return records that represent actual content changes. Default: true
+   * @returns {Promise<Array<Record>>}                                    Promise that will be resolved with an array of records in descending chronological order
    */
-  async findAll() {
+  async findAll(options = {}) {
     throw new Error(`#findAll method is not implemented in ${this.constructor.name}`);
   }
 
+  /**
+   * Find all records for a specific service, in descending chronological order
+   * For performance reasons, the content of the records will not be loaded by default. Use #loadRecordContent to load the content of individual records
+   * @see     RepositoryInterface#loadRecordContent
+   * @param   {string}                 serviceId                          - Service ID of records to find
+   * @param   {object}                 [options]                          - Query options
+   * @param   {number}                 [options.limit]                    - Maximum number of records to return
+   * @param   {number}                 [options.offset]                   - Number of records to skip
+   * @param   {boolean}                [options.includeTechnicalUpgrades] - When false, exclude technical upgrade records (re-renders of existing snapshots) and only return records that represent actual content changes. Default: true
+   * @returns {Promise<Array<Record>>}                                    Promise that will be resolved with an array of matching records in descending chronological order
+   */
+  async findByService(serviceId, options = {}) {
+    throw new Error(`#findByService method is not implemented in ${this.constructor.name}`);
+  }
+
+  /**
+   * Find all records for a specific service and terms type, in descending chronological order
+   * For performance reasons, the content of the records will not be loaded by default. Use #loadRecordContent to load the content of individual records
+   * @see     RepositoryInterface#loadRecordContent
+   * @param   {string}                 serviceId                          - Service ID of records to find
+   * @param   {string}                 termsType                          - Terms type of records to find
+   * @param   {object}                 [options]                          - Query options
+   * @param   {number}                 [options.limit]                    - Maximum number of records to return
+   * @param   {number}                 [options.offset]                   - Number of records to skip
+   * @param   {boolean}                [options.includeTechnicalUpgrades] - When false, exclude technical upgrade records (re-renders of existing snapshots) and only return records that represent actual content changes. Default: true
+   * @returns {Promise<Array<Record>>}                                    Promise that will be resolved with an array of matching records in descending chronological order
+   */
+  async findByServiceAndTermsType(serviceId, termsType, options = {}) {
+    throw new Error(`#findByServiceAndTermsType method is not implemented in ${this.constructor.name}`);
+  }
+
   /**
    * Count the total number of records in the repository
    * For performance reasons, use this method rather than counting the number of entries returned by #findAll if you only need the size of a repository
-   * @returns {Promise<number>} Promise that will be resolved with the total number of records
+   * @param   {string}          [serviceId] - Optional service ID to filter records
+   * @param   {string}          [termsType] - Optional terms type to filter records (requires serviceId)
+   * @returns {Promise<number>}             Promise that will be resolved with the total number of records
    */
-  async count() {
+  async count(serviceId, termsType) {
     throw new Error(`#count method is not implemented in ${this.constructor.name}`);
   }