### Start Development Server

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Use this command to start the development server for the search service.

```bash
npm run start
```

--------------------------------

### Install Dependencies

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Run this command to install all necessary project dependencies.

```bash
npm install
```

--------------------------------

### Install @internetarchive/search-service

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Install the search service package using npm. This is the first step before using the service in your project.

```bash
npm install @internetarchive/search-service
```

--------------------------------

### Format Code

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Run this command to format the project's code according to the defined style guide.

```bash
npm run format
```

--------------------------------

### Configure Simple Aggregations

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Example of how to configure simple aggregations for a search query, specifying fields for which to retrieve aggregated data.

```js
{ simpleParams: ['subject', 'creator', /*...*/] }
```

--------------------------------

### Perform a Metadata Search

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Example of how to perform a metadata search using the SearchService. It demonstrates setting up search parameters, including query, sorting, and fields, and handling the search results.

```typescript
import {
  SearchService,
  SearchType,
  SortParam,
  SortDirection
} from '@internetarchive/search-service';

const searchService = SearchService.default;
const dateSort = { field: 'date', direction: 'desc' };
const params = {
  query: 'collection:books AND title:(goody)',
  sort: [dateSort],
  rows: 25,
  fields: ['identifier', 'collection', 'title', 'creator']
};

const result = await searchService.search(params, SearchType.METADATA);
if (result.success) {
  const searchResponse = result.success;
  searchResponse.response.totalResults // => number -- total number of search results available to fetch
  searchResponse.response.returnedCount // => number -- how many search results are included in this response
  searchResponse.response.results // => Result[] array
  searchResponse.response.results[0].identifier // => 'some-item-identifier'
  searchResponse.response.results[0].title?.value // => 'some-item-title', or possibly undefined if no title exists on the item
}
```

--------------------------------

### Configure Custom SearchService Instance

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Shows how to instantiate SearchService with custom options, such as specifying a different base URL, enabling credentials, setting a request scope, and enabling verbose or debugging logging. This example performs a full-text search.

```typescript
import { SearchService, SearchType } from '@internetarchive/search-service';

const stagingService = new SearchService({
  baseUrl: 'be-api.us.archive.org',
  includeCredentials: true,
  scope: 'all',
  verbose: true,           // logs truncated response to console
  debuggingEnabled: true,  // appends ?debugging=true to every request
});

const result = await stagingService.search(
  { query: 'subject:jazz', rows: 5 },
  SearchType.FULLTEXT
);

if (result.success) {
  const hits = result.success.response.results;
  hits.forEach(hit => {
    // TextHit fields for FULLTEXT search
    console.log(hit.identifier, hit.highlight?.value, hit.page_num?.value);
  });
}
```

--------------------------------

### Configure Advanced Aggregations

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Example of how to configure advanced aggregations with custom bucket sizes for specific fields. Note: Advanced aggregation parameters are not currently supported by the backend.

```js
{ advancedParams: [{ field: 'subject', size: 2 }, { field: 'creator', size: 4 }, /*...*/] }
```

--------------------------------

### Fetch Account Details with Specific Page Elements

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Use `pageElements` to request specific sections of a user profile, such as uploads, reviews, or collections. This example shows how to retrieve and process these elements.

```typescript
import { SearchService, SearchType } from '@internetarchive/search-service';

const result = await SearchService.default.search(
  {
    pageType: 'account_details',
    pageTarget: '@brewster',
    pageElements: ['uploads', 'reviews', 'collections'],
    rows: 10,
  },
  SearchType.DEFAULT
);

if (result.success) {
  const { response } = result.success;
  const elements = response.pageElements;

  // Uploaded items
  elements?.uploads?.hits?.hits.forEach((h: any) =>
    console.log('Upload:', h.fields?.identifier)
  );

  // Reviews authored by this account
  elements?.reviews?.hits?.hits.forEach((h: any) => {
    const review = h.review;
    console.log('Review:', review?.title, '|', review?.reviewer_account_status);
  });

  // Account-level extra info
  const acct = response.accountExtraInfo;
  if (acct) {
    console.log('Screen name:', acct.account_details.screenname);
    console.log('Is archivist:', acct.is_archivist);
    console.log('Member since:', acct.account_details.user_since);
    console.log('Privileges:', acct.policy_settings.privileges);
  }
}
```

--------------------------------

### Performing a Metadata Search with Filters

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Details how to use the `SearchService.search()` method specifically for metadata searches (`SearchType.METADATA`). This example shows how to construct complex filters using `FilterMapBuilder` to refine search results based on multiple criteria like subject, year range, and media type.

```APIDOC
## SearchService.search() — metadata search

The primary search method dispatches to the metadata backend (`service_backend=metadata`) when called with `SearchType.METADATA`. Results are `ItemHit` instances with typed accessors for all standard Archive item fields.

```typescript
import {
  SearchService,
  SearchType,
  FilterConstraint,
  FilterMapBuilder,
} from '@internetarchive/search-service';

// Build a filter: subject includes "baseball", year >= 1950 and <= 2000
const filterMap = new FilterMapBuilder()
  .addFilter('subject', 'baseball', FilterConstraint.INCLUDE)
  .addFilter('year', '1950', FilterConstraint.GREATER_OR_EQUAL)
  .addFilter('year', '2000', FilterConstraint.LESS_OR_EQUAL)
  .build();

const result = await SearchService.default.search(
  {
    query: 'mediatype:movies',
    filters: filterMap,
    rows: 20,
    fields: ['identifier', 'title', 'year', 'downloads', 'item_size'],
    aggregations: { omit: true }, // skip aggregations for speed
  },
  SearchType.METADATA
);

if (result.success) {
  result.success.response.results.forEach(hit => {
    console.log(
      hit.identifier,
      hit.title?.value,
      hit.year?.value,
      hit.downloads?.value,
      hit.item_size?.value  // bytes
    );
  });
}
```
```

--------------------------------

### Sort Aggregation Buckets by Count, Alphabetically, or Numerically

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Use `Aggregation.getSortedBuckets()` to sort facet data. Supported sort orders include count-descending (default), alphabetical, and numeric-descending. This example demonstrates sorting subjects, years, and creators.

```typescript
import {
  SearchService,
  SearchType,
  AggregationSortType,
} from '@internetarchive/search-service';

const result = await SearchService.default.search(
  {
    query: 'collection:nasa',
    aggregations: { simpleParams: ['subject', 'year', 'creator'] },
    aggregationsSize: 20,
    rows: 0, // Aggregations only — skip returning hits
  },
  SearchType.METADATA
);

if (result.success) {
  const aggs = result.success.response.aggregations;

  // Top subjects by document count (default/COUNT order)
  const subjectBuckets = aggs?.subject?.getSortedBuckets(AggregationSortType.COUNT);
  console.log('Top subjects:');
  (subjectBuckets as { key: string; doc_count: number }[])?.slice(0, 5).forEach(b =>
    console.log(` ${b.key}: ${b.doc_count}`)
  );

  // Years sorted numerically descending
  const yearBuckets = aggs?.year?.getSortedBuckets(AggregationSortType.NUMERIC);
  console.log('Recent years:', yearBuckets?.slice(0, 5));

  // Creators alphabetically
  const creatorBuckets = aggs?.creator?.getSortedBuckets(AggregationSortType.ALPHABETICAL);
  console.log('Creators A-Z:', (creatorBuckets as any[])?.slice(0, 5).map(b => b.key));
}
```

--------------------------------

### Using the Default SearchService Singleton

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Demonstrates how to use the pre-configured `SearchService.default` singleton for common search operations, including specifying query parameters, sorting, pagination, fields, and aggregations. It also shows how to handle successful responses and errors.

```APIDOC
## SearchService.default — singleton search entry point

The static `SearchService.default` property provides a ready-to-use singleton that talks to `archive.org`. Construct a custom instance via `new SearchService(options)` to override the base URL, credentials, scope, or caching behavior.

```typescript
import {
  SearchService,
  SearchType,
  SortParam,
  SortDirection,
} from '@internetarchive/search-service';

const service = SearchService.default;

const sort: SortParam = { field: 'date', direction: 'desc' as SortDirection };

const result = await service.search(
  {
    query: 'collection:prelinger AND mediatype:movies',
    sort: [sort],
    rows: 10,
    page: 1,
    fields: ['identifier', 'title', 'creator', 'date', 'mediatype'],
    aggregations: { simpleParams: ['subject', 'creator'] },
    aggregationsSize: 5,
  },
  SearchType.METADATA
);

if (result.success) {
  const { totalResults, returnedCount, results, aggregations } = result.success.response;

  console.log(`${returnedCount} of ${totalResults} results`);

  for (const hit of results) {
    // hit is an ItemHit when SearchType.METADATA is used
    console.log(hit.identifier, hit.title?.value, hit.date?.value);
  }

  // Facet data
  const subjectAgg = aggregations?.subject;
  if (subjectAgg) {
    for (const bucket of subjectAgg.buckets as { key: string; doc_count: number }[]) {
      console.log(bucket.key, bucket.doc_count);
    }
  }
} else {
  // result.error is a SearchServiceError
  console.error(result.error.type, result.error.message);
}
```
```

--------------------------------

### Run Tests

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Execute this command to run the project's test suite.

```bash
npm run test
```

--------------------------------

### Creating a Custom SearchService Instance

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Illustrates how to instantiate `SearchService` with custom options, such as specifying a different base URL for staging environments, enabling verbose logging, or setting a specific request scope. This allows for more control over the search service's behavior.

```APIDOC
## SearchService — custom backend options

Instantiate `SearchService` with `SearchBackendOptionsInterface` to point at a staging host, enable verbose logging, or hard-code a request scope.

```typescript
import { SearchService, SearchType } from '@internetarchive/search-service';

const stagingService = new SearchService({
  baseUrl: 'be-api.us.archive.org',
  includeCredentials: true,
  scope: 'all',
  verbose: true,           // logs truncated response to console
  debuggingEnabled: true,  // appends ?debugging=true to every request
});

const result = await stagingService.search(
  { query: 'subject:jazz', rows: 5 },
  SearchType.FULLTEXT
);

if (result.success) {
  const hits = result.success.response.results;
  hits.forEach(hit => {
    // TextHit fields for FULLTEXT search
    console.log(hit.identifier, hit.highlight?.value, hit.page_num?.value);
  });
}
```
```

--------------------------------

### Search Service Usage

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Demonstrates how to initialize the SearchService and perform a search query with various parameters.

```APIDOC
## Search Service

### Description
Provides methods to search the Internet Archive.

### Method Signature
`SearchService.default.search(params: SearchParams, searchType: SearchType): Promise<SearchResponse>
`

### Parameters
#### `params` (object) - Required
An object containing search criteria.

- `query` (string) - Required - The search query string, potentially using Lucene syntax.
- `rows` (number) - Optional - The maximum number of search results to retrieve per page. Defaults to 25.
- `page` (number) - Optional - The page number of results to retrieve, starting from 1. Defaults to 1.
- `fields` (array of strings) - Optional - An array of metadata field names to include in the results.
- `sort` (array of objects) - Optional - An array of sorting parameters. Each object should have `field` (string) and `direction` ('asc' | 'desc').
- `aggregations` (object) - Optional - Specifies which aggregations to retrieve. Can be `{ omit: true }` or `{ simpleParams: string[] }` or `{ advancedParams: Array<{ field: string, size?: number }> }`.
- `aggregationsSize` (number) - Optional - The number of buckets to return for all aggregation types. Defaults to 6.
- `pageType` (string) - Optional - The type of page the data is requested for. Defaults to 'search_results'. Supports 'search_results' and 'collection_details'.
- `pageTarget` (string) - Optional - Used with `pageType: 'collection_details'` to specify the collection identifier.

#### `searchType` (SearchType) - Required
The type of search to perform. Available options are `SearchType.METADATA` and `SearchType.FULLTEXT`.

### Response
#### Success Response
An object containing the search results, including `totalResults`, `returnedCount`, and an array of `results`.

#### Response Example
```json
{
  "success": {
    "response": {
      "totalResults": 1000,
      "returnedCount": 25,
      "results": [
        {
          "identifier": "some-item-identifier",
          "collection": {"value": "some-collection"},
          "title": {"value": "some-item-title"},
          "creator": {"value": "some-creator"}
        }
      ]
    }
  }
}
```

### Error Handling
If the search fails, the response will indicate an error.

```

--------------------------------

### Use Default SearchService Singleton

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Demonstrates how to use the default singleton SearchService instance for metadata searches. Includes setting up sort parameters, performing the search, and handling success or error responses, including iterating through results and aggregations.

```typescript
import {
  SearchService,
  SearchType,
  SortParam,
  SortDirection,
} from '@internetarchive/search-service';

const service = SearchService.default;

const sort: SortParam = { field: 'date', direction: 'desc' as SortDirection };

const result = await service.search(
  {
    query: 'collection:prelinger AND mediatype:movies',
    sort: [sort],
    rows: 10,
    page: 1,
    fields: ['identifier', 'title', 'creator', 'date', 'mediatype'],
    aggregations: { simpleParams: ['subject', 'creator'] },
    aggregationsSize: 5,
  },
  SearchType.METADATA
);

if (result.success) {
  const { totalResults, returnedCount, results, aggregations } = 
    result.success.response;

  console.log(`${returnedCount} of ${totalResults} results`);

  for (const hit of results) {
    // hit is an ItemHit when SearchType.METADATA is used
    console.log(hit.identifier, hit.title?.value, hit.date?.value);
  }

  // Facet data
  const subjectAgg = aggregations?.subject;
  if (subjectAgg) {
    for (const bucket of subjectAgg.buckets as { key: string; doc_count: number }[]) {
      console.log(bucket.key, bucket.doc_count);
    }
  }
} else {
  // result.error is a SearchServiceError
  console.error(result.error.type, result.error.message);
}
```

--------------------------------

### Metadata Search with Filters

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Demonstrates performing a metadata search using SearchService.default, including building complex filters for inclusion and range constraints on fields like 'subject' and 'year'. It also shows how to omit aggregations for performance.

```typescript
import {
  SearchService,
  SearchType,
  FilterConstraint,
  FilterMapBuilder,
} from '@internetarchive/search-service';

// Build a filter: subject includes "baseball", year >= 1950 and <= 2000
const filterMap = new FilterMapBuilder()
  .addFilter('subject', 'baseball', FilterConstraint.INCLUDE)
  .addFilter('year', '1950', FilterConstraint.GREATER_OR_EQUAL)
  .addFilter('year', '2000', FilterConstraint.LESS_OR_EQUAL)
  .build();

const result = await SearchService.default.search(
  {
    query: 'mediatype:movies',
    filters: filterMap,
    rows: 20,
    fields: ['identifier', 'title', 'year', 'downloads', 'item_size'],
    aggregations: { omit: true }, // skip aggregations for speed
  },
  SearchType.METADATA
);

if (result.success) {
  result.success.response.results.forEach(hit => {
    console.log(
      hit.identifier,
      hit.title?.value,
      hit.year?.value,
      hit.downloads?.value,
      hit.item_size?.value  // bytes
    );
  });
}
```

--------------------------------

### Define Sort Parameter for Search

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Illustrates the structure for defining a sort parameter, specifying the field and direction for sorting search results.

```js
{ field: string, direction: 'asc' | 'desc' }
```

--------------------------------

### SearchResponse Object Structure

Source: https://github.com/internetarchive/iaux-search-service/blob/main/README.md

Illustrates the structure of the SearchResponse object, detailing fields like rawResponse, request parameters, responseHeader, and the main response content including totalResults, returnedCount, results, aggregations, and schema.

```javascript
{
  rawResponse: {/*...*/},
  request: {
    clientParameters: {/*...*/},
    finalizedParameters: {/*...*/}
  },
  responseHeader: {/*...*/},
  response: {
    totalResults: 12345,
    returnedCount: 50,
    results: [/*...*/],
    aggregations: {/*...*/},
    schema: {/*...*/}
  }
}
```

--------------------------------

### Perform Full-Text Search

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Use SearchType.FULLTEXT to route queries to the FTS backend. This returns TextHit objects with highlight and page_num properties. Ensure the SearchService and SearchType are imported.

```typescript
import { SearchService, SearchType } from '@internetarchive/search-service';

const result = await SearchService.default.search(
  {
    query: 'constitution amendments',
    rows: 5,
    fields: ['identifier', 'title', 'creator', 'filename'],
  },
  SearchType.FULLTEXT
);

if (result.success) {
  result.success.response.results.forEach(hit => {
    // TextHit-specific properties
    console.log('Item:', hit.identifier);
    console.log('File:', hit.filename?.value);
    console.log('Page:', hit.page_num?.value);
    console.log('Snippet:', hit.highlight?.value);
  });
} else {
  console.error('FTS error:', result.error.type, result.error.message);
}
```

--------------------------------

### Handle SearchService Errors with Type Discrimination

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Demonstrates how to handle potential errors from SearchService using the SearchServiceErrorType discriminant. Imports for SearchService, SearchType, and SearchServiceErrorType are required.

```typescript
import {
  SearchService,
  SearchType,
  SearchServiceErrorType,
} from '@internetarchive/search-service';

const result = await SearchService.default.search(
  { query: 'some query' },
  SearchType.METADATA
);

if (result.error) {
  const { type, message, details } = result.error;

  switch (type) {
    case SearchServiceErrorType.networkError:
      console.error('Network failure — retry or check connectivity:', message);
      break;
    case SearchServiceErrorType.decodingError:
      console.error('Failed to parse PPS response:', message);
      break;
    case SearchServiceErrorType.searchEngineError:
      console.error('PPS search engine error:', message, details);
      break;
    case SearchServiceErrorType.itemNotFound:
      console.error('Item not found:', message);
      break;
    default:
      console.error('Unexpected error:', type, message);
  }
}
```

--------------------------------

### Build Filter Maps Fluently with FilterMapBuilder

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Construct `SearchParams` filters using a fluent API. `FilterMapBuilder` handles merging duplicate constraints and supports inclusion/exclusion logic for various fields like 'subject', 'creator', and 'year'.

```typescript
import {
  FilterMapBuilder,
  FilterConstraint,
} from '@internetarchive/search-service';

const builder = new FilterMapBuilder();

// Include multiple subjects (OR logic)
builder
  .addFilter('subject', 'jazz', FilterConstraint.INCLUDE)
  .addFilter('subject', 'blues', FilterConstraint.INCLUDE);

// Exclude a specific creator
builder.addFilter('creator', 'Unknown', FilterConstraint.EXCLUDE);

// Restrict year range (1940–1960)
builder
  .addFilter('year', '1940', FilterConstraint.GREATER_OR_EQUAL)
  .addFilter('year', '1960', FilterConstraint.LESS_OR_EQUAL);

// Remove a previously added filter
builder.removeSingleFilter('subject', 'blues', FilterConstraint.INCLUDE);

// Merge an additional pre-existing filter map
builder.mergeFilterMap({
  mediatype: { audio: FilterConstraint.INCLUDE },
});

const filterMap = builder.build();
// => {
//   subject: { jazz: 'inc' },
//   creator: { Unknown: 'exc' },
//   year: { '1940': 'gte', '1960': 'lte' },
//   mediatype: { audio: 'inc' }
// }

const result = await SearchService.default.search(
  { query: '*', filters: filterMap, rows: 10 },
  SearchType.METADATA
);
```

--------------------------------

### Fetch Item Detail Page Data

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Use SearchService.itemDetails() to retrieve 'item_details' page type data for a specific Archive identifier. The response includes extraInfo with rich metadata like view stats and file counts. Import SearchService.

```typescript
import { SearchService } from '@internetarchive/search-service';

const result = await SearchService.default.itemDetails('prelinger');

if (result.success) {
  const { response } = result.success;

  // Item-level hits (members of the collection, etc.)
  console.log('Results:', response.results.length);

  // ExtraInfo contains rich item-level metadata
  const info = response.extraInfo;
  if (info) {
    console.log('Item size (bytes):', info.item_size);
    console.log('Files count:', info.files_count);
    console.log('Monthly views:', info.month);
    console.log('Weekly views:', info.week);
    console.log('Total downloads:', info.downloads);
    console.log('Favorites:', info.num_favorites);
    console.log('Thumbnail URL:', info.thumbnail_url);
    console.log('Primary collection:', info.primary_collection);

    // Full MDAPI Metadata object
    const meta = info.public_metadata;
    console.log('Title:', meta?.title?.values);
    console.log('Description:', meta?.description?.values);
  }
}
```

--------------------------------

### SearchService.search() — full-text search

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Performs a full-text search using SearchType.FULLTEXT. This routes queries to the FTS backend and returns TextHit objects with highlighted excerpts and page numbers.

```APIDOC
## SearchService.search() — full-text search

### Description
Performs a full-text search using `SearchType.FULLTEXT`. This routes queries to the FTS backend and returns `TextHit` objects that include `highlight` (matched text excerpt) and `page_num` properties alongside the standard item fields.

### Method
`SearchService.default.search(params, SearchType.FULLTEXT)`

### Parameters
#### Request Body (params)
- **query** (string) - Required - The search query string.
- **rows** (number) - Optional - The number of results to return.
- **fields** (array of strings) - Optional - An array of fields to include in the results.

### Request Example
```typescript
SearchService.default.search(
  {
    query: 'constitution amendments',
    rows: 5,
    fields: ['identifier', 'title', 'creator', 'filename'],
  },
  SearchType.FULLTEXT
);
```

### Response
#### Success Response
- **success.response.results** (array of TextHit) - An array of search results, where each hit includes standard item fields plus `highlight` and `page_num`.

#### Response Example
```json
{
  "success": {
    "response": {
      "results": [
        {
          "identifier": "item1",
          "filename": {"value": "file1.pdf"},
          "page_num": {"value": 10},
          "highlight": {"value": "...matched text..."}
        }
      ]
    }
  }
}
```

#### Error Response
- **error.type** (string) - The type of error.
- **error.message** (string) - A description of the error.
```

--------------------------------

### Search within a Collection

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Combine 'pageType: "collection_details"' with 'pageTarget' to scope search results to a collection. This also retrieves 'collectionExtraInfo' with collection-level statistics. Import SearchService and SearchType.

```typescript
import { SearchService, SearchType } from '@internetarchive/search-service';

const result = await SearchService.default.search(
  {
    pageType: 'collection_details',
    pageTarget: 'GratefulDead',
    rows: 25,
    sort: [{ field: 'date', direction: 'asc' }],
    aggregations: { simpleParams: ['year', 'subject'] },
  },
  SearchType.METADATA
);

if (result.success) {
  const { response } = result.success;

  console.log('Total items:', response.totalResults);
  console.log('Returned:', response.returnedCount);

  const extra = response.collectionExtraInfo;
  if (extra) {
    console.log('Total files:', extra.collection_files_count);
    console.log('Collection size:', extra.collection_size);
    console.log('Item count:', extra.item_count);
    console.log('Forum posts:', extra.forum_count);
    extra.related_collection_details?.forEach(rel =>
      console.log(' Related:', rel.identifier, rel.title, rel.item_count)
    );
  }

  response.results.forEach(hit =>
    console.log(hit.identifier, hit.title?.value, hit.date?.value)
  );
}
```

--------------------------------

### Perform Federated Search

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Utilize SearchType.FEDERATED to query multiple backends (metadata, FTS, TV, radio) simultaneously. Results are grouped by service in the federatedResults map. Import SearchService and SearchType.

```typescript
import { SearchService, SearchType } from '@internetarchive/search-service';

const result = await SearchService.default.search(
  { query: 'moon landing', rows: 10 },
  SearchType.FEDERATED
);

if (result.success) {
  const { totalResults, returnedCount, federatedResults } = 
    result.success.response;

  console.log(`Federated: ${returnedCount} / ${totalResults} total`);

  if (federatedResults) {
    for (const [service, hits] of Object.entries(federatedResults)) {
      console.log(`
=== ${service} (${hits.length} hits) ===`);
      hits.forEach(hit => console.log(' -', hit.identifier, hit.title?.value));
    }
  }
}
```

--------------------------------

### Perform TV Captions Search

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Searches for TV captions using SearchType.TV, returning TvClipHit results and tvChannelAliases. Requires importing SearchService and SearchType.

```typescript
import { SearchService, SearchType } from '@internetarchive/search-service';

// TV captions search
const tvResult = await SearchService.default.search(
  {
    query: 'climate change',
    rows: 5,
    fields: ['identifier', 'title', 'creator', 'date'],
    sort: [{ field: 'date', direction: 'desc' }],
  },
  SearchType.TV
);

if (tvResult.success) {
  const { results, tvChannelAliases } = tvResult.success.response;

  results.forEach(hit => {
    const networkName = tvChannelAliases?.[hit.creator?.value as string];
    console.log(
      hit.identifier,
      hit.title?.value,
      networkName ?? hit.creator?.value
    );
  });
}
```

--------------------------------

### Perform Radio Transcripts Search

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Searches for radio transcripts using SearchType.RADIO, returning standard hits. Requires importing SearchService and SearchType.

```typescript
import { SearchService, SearchType } from '@internetarchive/search-service';

// Radio transcripts search
const radioResult = await SearchService.default.search(
  { query: 'jazz history', rows: 5 },
  SearchType.RADIO
);

if (radioResult.success) {
  radioResult.success.response.results.forEach(hit =>
    console.log(hit.identifier, hit.title?.value)
  );
}
```

--------------------------------

### SearchService.itemDetails() — item detail page data

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Fetches detailed information for a single Archive item using its identifier. The response includes rich metadata in the `extraInfo` field.

```APIDOC
## SearchService.itemDetails() — item detail page data

### Description
Fetches the `item_details` page type for a single Archive identifier. The response's `extraInfo` field contains rich metadata including view stats, file counts, public metadata, reviews, and uploader details.

### Method
`SearchService.default.itemDetails(identifier)`

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The unique identifier of the Archive item.

### Request Example
```typescript
SearchService.default.itemDetails('prelinger');
```

### Response
#### Success Response
- **success.response.extraInfo** (object) - Contains rich item-level metadata such as `item_size`, `files_count`, `month` (views), `week` (views), `downloads`, `num_favorites`, `thumbnail_url`, `primary_collection`, and `public_metadata`.
- **success.response.extraInfo.public_metadata** (object) - The full MDAPI Metadata object for the item.

#### Response Example
```json
{
  "success": {
    "response": {
      "extraInfo": {
        "item_size": 123456789,
        "files_count": 50,
        "month": 1000,
        "week": 200,
        "downloads": 5000,
        "num_favorites": 100,
        "thumbnail_url": "http://example.com/thumb.jpg",
        "primary_collection": "some_collection",
        "public_metadata": {
          "title": {"values": ["Example Title"]},
          "description": {"values": ["Example Description"]}
        }
      }
    }
  }
}
```

#### Error Response
- **error.type** (string) - The type of error.
- **error.message** (string) - A description of the error.
```

--------------------------------

### SearchService.search() — federated search

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Performs a federated search using SearchType.FEDERATED, querying multiple backends (metadata, FTS, TV, radio) simultaneously. Results are grouped by service name.

```APIDOC
## SearchService.search() — federated search

### Description
Performs a federated search using `SearchType.FEDERATED`. This fans the query out across metadata, FTS, TV, and radio backends simultaneously. The response's `federatedResults` map groups hits by service name (e.g. `fts`, `tvs`, `rcs`).

### Method
`SearchService.default.search(params, SearchType.FEDERATED)`

### Parameters
#### Request Body (params)
- **query** (string) - Required - The search query string.
- **rows** (number) - Optional - The number of results to return.

### Request Example
```typescript
SearchService.default.search({ query: 'moon landing', rows: 10 }, SearchType.FEDERATED);
```

### Response
#### Success Response
- **success.response.totalResults** (number) - The total number of results across all federated services.
- **success.response.returnedCount** (number) - The number of results returned in this request.
- **success.response.federatedResults** (object) - A map where keys are service names and values are arrays of hits from that service.

#### Response Example
```json
{
  "success": {
    "response": {
      "totalResults": 100,
      "returnedCount": 10,
      "federatedResults": {
        "fts": [
          {"identifier": "item1", "title": {"value": "Moon Landing"}}
        ],
        "tvs": [
          {"identifier": "tv_item1", "title": {"value": "Apollo 11"}}
        ]
      }
    }
  }
}
```
```

--------------------------------

### SearchService.search() — collection details page

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Retrieves items within a specific collection, along with collection-level statistics. Uses SearchType.METADATA and requires 'collection_details' pageType.

```APIDOC
## SearchParams — collection details page

### Description
The `pageType: 'collection_details'` + `pageTarget` combination retrieves results scoped to a collection, along with `collectionExtraInfo` (item counts, related collections, uploader details, etc.).

### Method
`SearchService.default.search(params, SearchType.METADATA)`

### Parameters
#### Request Body (params)
- **pageType** (string) - Required - Must be set to `'collection_details'`.
- **pageTarget** (string) - Required - The identifier of the collection.
- **rows** (number) - Optional - The number of results to return.
- **sort** (array of objects) - Optional - Defines sorting criteria. Each object should have `field` and `direction`.
- **aggregations** (object) - Optional - Specifies aggregations to perform. `simpleParams` can include fields like 'year', 'subject'.

### Request Example
```typescript
SearchService.default.search(
  {
    pageType: 'collection_details',
    pageTarget: 'GratefulDead',
    rows: 25,
    sort: [{ field: 'date', direction: 'asc' }],
    aggregations: { simpleParams: ['year', 'subject'] },
  },
  SearchType.METADATA
);
```

### Response
#### Success Response
- **success.response.totalResults** (number) - Total number of items in the collection.
- **success.response.returnedCount** (number) - Number of items returned in this request.
- **success.response.collectionExtraInfo** (object) - Contains collection-level statistics like `collection_files_count`, `collection_size`, `item_count`, `forum_count`, and `related_collection_details`.
- **success.response.results** (array of objects) - An array of item hits within the collection.

#### Response Example
```json
{
  "success": {
    "response": {
      "totalResults": 1000,
      "returnedCount": 25,
      "collectionExtraInfo": {
        "collection_files_count": 50000,
        "collection_size": 10000000000,
        "item_count": 1000,
        "forum_count": 50,
        "related_collection_details": [
          {"identifier": "related1", "title": "Related Collection 1", "item_count": 100}
        ]
      },
      "results": [
        {"identifier": "item1", "title": {"value": "Item Title 1"}, "date": {"value": "1970-01-01"}}
      ]
    }
  }
}
```

#### Error Response
- **error.type** (string) - The type of error.
- **error.message** (string) - A description of the error.
```

--------------------------------

### Generate URLSearchParams from SearchParams

Source: https://context7.com/internetarchive/iaux-search-service/llms.txt

Converts a SearchParams object into a URLSearchParams instance for custom fetch calls or debugging. Ensure the SearchParamURLGenerator is imported.

```typescript
import { SearchParamURLGenerator } from '@internetarchive/search-service';

const urlParams = SearchParamURLGenerator.generateURLSearchParams({
  query: 'mediatype:audio AND creator:(Coltrane)',
  sort: [{ field: 'date', direction: 'desc' }],
  rows: 20,
  page: 2,
  fields: ['identifier', 'title', 'creator', 'date'],
  filters: {
    year: { '1955': 'gte', '1970': 'lte' },
  },
  aggregations: { simpleParams: ['subject'] },
  aggregationsSize: 10,
  uid: 'request-abc-123',
});

console.log(urlParams.toString());

const fullUrl =
  `https://archive.org/services/search/beta/page_production/` +
  `?service_backend=metadata&${urlParams.toString()}`;
console.log(fullUrl);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.