{"_id":"@adtonos/iab-cat-tax-map","_rev":"2-58486f8b219027bb80043381dbfeb338","name":"@adtonos/iab-cat-tax-map","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"@adtonos/iab-cat-tax-map","version":"1.0.0","author":{"name":"AdTonos"},"license":"MIT","_id":"@adtonos/iab-cat-tax-map@1.0.0","maintainers":[{"name":"adtonos","email":"support@adtonos.com"}],"dist":{"shasum":"ba6f09d016b6d08686d37de4172172423c181bfc","tarball":"https://registry.npmjs.org/@adtonos/iab-cat-tax-map/-/iab-cat-tax-map-1.0.0.tgz","fileCount":63,"integrity":"sha512-2zqetShM99YA+0uTFYGPs3hRQjPwjaKMUREcoqEETY84DxNPU+abz0yiik6foyapkxchCUcCzBoYeJ30O2elhg==","signatures":[{"sig":"MEUCIQDrMB5DqWSl9sz+kbHWErn/U+wTT8AsU1i5UlX8Sbpv0AIgKnyi/yMwIPU1GrRaWkwpG2zVslLVu2Scwd/baevWRMQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":255261},"main":"dist/index.js","types":"dist/index.d.ts","volta":{"node":"24.6.0"},"$schema":"https://json.schemastore.org/package","gitHead":"9ffb2d0d71f34b32aca6488c3b413fa6f8714fe0","scripts":{"test":"tsx --test","build":"tsc -p tsconfig.build.json","prepare":"husky","typecheck":"tsc --noEmit","prepublish":"npm run test && npm run build"},"_npmUser":{"name":"adtonos","email":"support@adtonos.com"},"_npmVersion":"11.5.1","description":"A comprehensive TypeScript library for working with Interactive Advertising Bureau (IAB) category taxonomies. This library provides robust functionality to detect, validate, and map categories across different versions of IAB taxonomies, including Content","directories":{},"lint-staged":{"*.{js,ts,json,md}":"prettier --write","**/*.{js,ts,json,md}":"prettier --write"},"_nodeVersion":"24.6.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","husky":"^9.1.7","prettier":"^3.6.2","typescript":"^5.9.2","@types/node":"^24.3.0","lint-staged":"^16.1.5"},"_npmOperationalInternal":{"tmp":"tmp/iab-cat-tax-map_1.0.0_1757672165577_0.9322822809475257","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"$schema":"https://json.schemastore.org/package","name":"@adtonos/iab-cat-tax-map","version":"2.0.0","main":"dist/index.js","types":"dist/index.d.ts","keywords":["iab","taxonomy","category","content","categories","taxonomies","map","mapping","mapper"],"scripts":{"test":"tsx --test","build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","prepare":"husky","prepublish":"npm run test && npm run build"},"author":{"name":"AdTonos"},"license":"MIT","description":"A comprehensive TypeScript library for working with Interactive Advertising Bureau (IAB) category taxonomies. This library provides robust functionality to detect, validate, and map categories across different versions of IAB taxonomies, including Content","devDependencies":{"@types/node":"^24.3.0","husky":"^9.1.7","lint-staged":"^16.1.5","prettier":"^3.6.2","tsx":"^4.20.5","typescript":"^5.9.2"},"lint-staged":{"*.{js,ts,json,md}":"prettier --write","**/*.{js,ts,json,md}":"prettier --write"},"volta":{"node":"24.6.0"},"publishConfig":{"access":"public"},"_id":"@adtonos/iab-cat-tax-map@2.0.0","gitHead":"6422fb2445d35ba2cd2b18baccc8d10e7a39a9af","_nodeVersion":"24.6.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-/H2KRYjrDlbTsnc7EyuS5zbdunggntr/IxwJeoT8WZh6kdxNtctPWwSsKgqDRrYs8YKtWtVFmtiXHc5JqHeZzQ==","shasum":"21cfa73300def67409aa6e60a0630ddd2dbe40f8","tarball":"https://registry.npmjs.org/@adtonos/iab-cat-tax-map/-/iab-cat-tax-map-2.0.0.tgz","fileCount":66,"unpackedSize":266348,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCMaYo98oy+suut9Qnk40JkMrn7g3NJE6jA0TOxZ/s6UgIhALtgDkW52cZenF8WWYaIQWAVjY0B6hjTSkT930sOc1cZ"}]},"_npmUser":{"name":"adtonos","email":"support@adtonos.com"},"directories":{},"maintainers":[{"name":"adtonos","email":"support@adtonos.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/iab-cat-tax-map_2.0.0_1757683212809_0.6940050758201868"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-12T10:16:05.481Z","modified":"2025-09-12T13:20:13.182Z","1.0.0":"2025-09-12T10:16:05.755Z","2.0.0":"2025-09-12T13:20:12.988Z"},"author":{"name":"AdTonos"},"license":"MIT","description":"A comprehensive TypeScript library for working with Interactive Advertising Bureau (IAB) category taxonomies. This library provides robust functionality to detect, validate, and map categories across different versions of IAB taxonomies, including Content","maintainers":[{"name":"adtonos","email":"support@adtonos.com"}],"readme":"# IAB Category Taxonomy Mapper\n\nA comprehensive TypeScript library for working with Interactive Advertising Bureau (IAB) category taxonomies. This library provides robust functionality to detect, validate, and map categories across different versions of IAB taxonomies, including Content Categories, Ad Product Categories, and Audience Categories.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Supported Taxonomies](#supported-taxonomies)\n- [API Reference](#api-reference)\n  - [detectTaxonomy](#detecttaxonomy)\n  - [isValidTaxonomy](#isvalidtaxonomy)\n  - [mapCategory](#mapcategories)\n- [Architecture](#architecture)\n- [Mapping Strategy](#mapping-strategy)\n- [Usage Examples](#usage-examples)\n- [Error Handling](#error-handling)\n- [Limitations](#limitations)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nThe Interactive Advertising Bureau (IAB) maintains several category taxonomies used for content and advertisement classification in digital advertising. Over time, these taxonomies have evolved through multiple versions, creating compatibility challenges when working with different systems that may use different taxonomy versions.\n\nThis library solves these challenges by providing:\n\n- **Taxonomy Detection**: Automatically identify which taxonomy version(s) a category belongs to\n- **Category Validation**: Verify if a category ID is valid within a specific taxonomy\n- **Cross-Taxonomy Mapping**: Convert categories between different taxonomy versions\n- **Comprehensive Coverage**: Support for all major IAB taxonomy versions\n\n## Installation\n\n```bash\nnpm install @adtonos/iab-cat-tax-map\n```\n\n```bash\nyarn add @adtonos/iab-cat-tax-map\n```\n\n```bash\npnpm add @adtonos/iab-cat-tax-map\n```\n\n## Quick Start\n\n```typescript\nimport { detectTaxonomy, isValidTaxonomy, mapCategory, CategoryTaxonomies } from '@adtonos/iab-cat-tax-map';\n\n// Detect which taxonomies a category belongs to\nconst taxonomies = detectTaxonomy('IAB1');\nconsole.log(taxonomies); // [1] - Content v1.0\n\n// Validate a category against a specific taxonomy\nconst isValid = isValidTaxonomy('IAB1-1', CategoryTaxonomies.CONTENT_V2);\nconsole.log(isValid); // false\n\n// Map a category from one taxonomy to another\nconst mapped = mapCategory('IAB1-1', CategoryTaxonomies.CONTENT_V1, CategoryTaxonomies.CONTENT_V2);\nconsole.log(mapped); // '42'\n```\n\n## Supported Taxonomies\n\nThis library supports the following IAB category taxonomies, their assigned enum values directly correspond to [IAB OpenRTB spec](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list_categorytaxonomies):\n\n### Content Categories\n- **Content v1.0** (`CONTENT_V1` = 1): Original IAB Content Category taxonomy\n- **Content v2.0** (`CONTENT_V2` = 2): Updated content categories with expanded classifications\n- **Content v2.1** (`CONTENT_V2_1` = 5): Minor revision of v2.0\n- **Content v2.2** (`CONTENT_V2_2` = 6): Further refinements to content categories\n- **Content v3.0** (`CONTENT_V3` = 7): Major revision with category changes\n- **Content v3.1** (`CONTENT_V3_1` = 9): Latest content category taxonomy\n\n### Ad Product Categories\n- **Ad Product v1.0** (`AD_PRODUCT_V1` = 3): Original product/service categories for advertising\n- **Ad Product v2.0** (`AD_PRODUCT_V2` = 8): Updated product taxonomy\n\n### Audience Categories\n- **Audience v1.1** (`AUDIENCE_V1_1` = 4): Demographic and interest-based audience categories\n\n## API Reference\n\n### detectTaxonomy\n\nIdentifies which taxonomy versions a given category belongs to.\n\n```typescript\nfunction detectTaxonomy(category: string): CategoryTaxonomy[]\n```\n\n**Parameters:**\n- `category` (string): The category ID to analyze\n\n**Returns:**\n- Array of `CategoryTaxonomy` values representing all taxonomies that contain this category\n\n**Example:**\n```typescript\nconst taxonomies = detectTaxonomy('IAB1-1');\n// Returns: [1, 2, 5, 6, 7, 9] - found in multiple content taxonomies\n```\n\n### isValidTaxonomy\n\nValidates whether a category exists in a specific taxonomy.\n\n```typescript\nfunction isValidTaxonomy(category: string, taxonomy: CategoryTaxonomy): boolean\n```\n\n**Parameters:**\n- `category` (string): The category ID to validate\n- `taxonomy` (CategoryTaxonomy): The taxonomy to check against\n\n**Returns:**\n- `true` if the category exists in the specified taxonomy, `false` otherwise\n\n**Example:**\n```typescript\nconst isValid = isValidTaxonomy('IAB1-1', CategoryTaxonomies.CONTENT_V3);\n// Returns: false because 'IAB1-1' does not exist in Content v3.0 taxonomy\n```\n\n### mapCategory\n\nMaps a category from one taxonomy to another.\n\n```typescript\nfunction mapCategory(\n  input: string,\n  inputTax: CategoryTaxonomy,\n  outputTax: CategoryTaxonomy\n): string | null\n```\n\n**Parameters:**\n- `input` (string): The category ID to map\n- `inputTax` (CategoryTaxonomy): Source taxonomy\n- `outputTax` (CategoryTaxonomy): Target taxonomy\n\n**Returns:**\n- Mapped category ID as a string, or `null` if no mapping exists\n\n**Example:**\n```typescript\nconst mapped = mapCategory('IAB1', CategoryTaxonomies.CONTENT_V1, CategoryTaxonomies.CONTENT_V2);\n// Returns: '42'\nconst unappable = mapCategory('trash', CategoryTaxonomies.CONTENT_V1, CategoryTaxonomies.CONTENT_V2);\n// Returns: null\n```\n\n## Architecture\n\nThe library is built around a flexible mapping system that supports bidirectional conversions between taxonomies:\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Content v1.0  │◄──►│   Content v2.0   │◄──►│   Content v2.1  │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n         ▲                        ▲                        ▲\n         │                        │                        │\n         ▼                        ▼                        ▼\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Ad Product    │    │   Content v3.0   │    │   Content v2.2  │\n│      v2.0       │    │                  │    │                 │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n### Core Components\n\n1. **Category Sets**: Pre-defined sets containing all valid categories for each taxonomy version\n2. **Mapping Functions**: Specialized functions that handle conversion logic between specific taxonomy pairs\n3. **Dynamic Mapper Generator**: Automatically creates mapping chains for indirect conversions\n4. **Validation Layer**: Ensures category validity before attempting mappings\n\n## Mapping Strategy\n\nThe library uses a sophisticated mapping strategy that handles both direct and indirect conversions:\n\n### Direct Mappings\nFor taxonomy pairs with explicit mapping definitions:\n- Content v1.0 ↔ Content v2.0\n- Content v1.0 ↔ Ad Product v2.0\n\n### Identity Mappings\nFor taxonomies that share identical category structures:\n- Content v2.0 ↔ Content v2.1 ↔ Content v2.2\n\n### Chain Mappings\nFor indirect conversions through intermediate taxonomies:\n- Content v1.0 → Content v2.0 → Content v3.0\n\n### Validation-Based Mappings\nFor taxonomies with overlapping but not identical category sets:\n- Content v2.0 ↔ Content v3.0 (validates existence before mapping)\n- Content v3.0 ↔ Content v3.1 (handles specific exclusions like \"thriller\" genre)\n\n## Usage Examples\n\n### Basic Category Detection and Validation\n\n```typescript\nimport { detectTaxonomy, isValidTaxonomy, CategoryTaxonomies } from '@adtonos/iab-cat-tax-map';\n\n// Check if a category exists across multiple taxonomies\nconst category = 'IAB12-3';\nconst possibleTaxonomies = detectTaxonomy(category);\n\nfor (const taxonomy of possibleTaxonomies) {\n  console.log(`Category ${category} exists in taxonomy ${taxonomy}`);\n\n  const isValid = isValidTaxonomy(category, taxonomy);\n  console.log(`Validation result: ${isValid}`);\n}\n```\n\n### Cross-Taxonomy Category Mapping\n\n```typescript\nimport { mapCategory, CategoryTaxonomies } from '@adtonos/iab-cat-tax-map';\n\n// Map from Content v1.0 to Content v2.0\nconst sourceCategory = 'IAB1-1';\nconst mappedCategory = mapCategory(\n  sourceCategory,\n  CategoryTaxonomies.CONTENT_V1,\n  CategoryTaxonomies.CONTENT_V2\n);\n\nif (mappedCategory) {\n  console.log(`${sourceCategory} maps to ${mappedCategory}`);\n} else {\n  console.log(`No mapping available for ${sourceCategory}`);\n}\n```\n\n### Batch Category Processing\n\n```typescript\nimport { detectTaxonomy, mapCategory, CategoryTaxonomies } from '@adtonos/iab-cat-tax-map';\n\nconst categories = ['IAB1', 'IAB2-1', 'IAB12-3', 'IAB20'];\n\nconst processCategoryBatch = (categories: string[]) => {\n  return categories.map(category => {\n    const taxonomies = detectTaxonomy(category);\n\n    // Try to map to Content v3.0 if possible\n    if (taxonomies.includes(CategoryTaxonomies.CONTENT_V1)) {\n      const mapped = mapCategory(\n        category,\n        CategoryTaxonomies.CONTENT_V1,\n        CategoryTaxonomies.CONTENT_V3\n      );\n\n      return {\n        original: category,\n        taxonomies,\n        mappedToV3: mapped\n      };\n    }\n\n    return {\n      original: category,\n      taxonomies,\n      mappedToV3: null\n    };\n  });\n};\n\nconst results = processCategoryBatch(categories);\nconsole.log(results);\n```\n\n### Working with Ad Product Categories\n\n```typescript\nimport { mapCategory, isValidTaxonomy, CategoryTaxonomies } from '@adtonos/iab-cat-tax-map';\n\nconst productCategory = 'IAB13-1';\n\n// Verify category exists in Ad Product v2.0\nif (isValidTaxonomy(productCategory, CategoryTaxonomies.AD_PRODUCT_V2)) {\n  // Map to Content v1.0 for content targeting\n  const contentCategory = mapCategory(\n    productCategory,\n    CategoryTaxonomies.AD_PRODUCT_V2,\n    CategoryTaxonomies.CONTENT_V1\n  );\n\n  if (contentCategory) {\n    console.log(`Product category ${productCategory} maps to content category ${contentCategory}`);\n  }\n}\n```\n\n## Error Handling\n\nIf only known and valid taxonomy is passed the functions should never throw it is so that they can be used in possibly high throughput situations.\nThat is why, one should handle non-happy paths of the functions:\n\n```typescript\nconst taxonomies = detectTaxonomy('foo');\nconsole.log(taxonomies); // [] - no known taxonomy contains \"foo\" as valid category\n\nconst mappedCategory = mapCategory('IAB24', CategoryTaxonomies.CONTENT_V1, CategoryTaxonomies.CONTENT_V2);\nconsole.log(mappedCategory); // null - IAB24 is unmappable to Content Category v2.0\n```\n\n## Limitations\n\n### Current Known Limitations\n\n1. **Ad Product v1.0 Mappings**: Currently unmappable due to low-quality source data\n   ```typescript\n   // These mappings will always return null\n   const result = mapCategory('category', CategoryTaxonomies.AD_PRODUCT_V1, CategoryTaxonomies.CONTENT_V1);\n   // Returns: null\n   ```\n\n2. **Audience Category Isolation**: Audience categories cannot be mapped to/from other taxonomy types\n   ```typescript\n   // Audience categories are isolated\n   const result = mapCategory('audienceCategory', CategoryTaxonomies.AUDIENCE_V1_1, CategoryTaxonomies.CONTENT_V1);\n   // Returns: null\n   ```\n\n3. **Lossy Mappings**: Some mappings may be lossy due to taxonomy structural differences\n   - Content v3.1 excludes the \"thriller\" genre (ID: 700) present in v3.0\n   - Some categories present in newer taxonomies may not have equivalents in older versions\n\n### Possible Improvements\n\nHere are possible improvements in the future (in the order of the most likely to least likely):\n- Fix Ad Product v1.0 mappings with higher quality source data\n- Extend testing\n- Add special functionalities to define custom taxonomies and mappings between other\n- Implement fuzzy matching for similar categories across taxonomies\n\n## Development\n\n### Prerequisites\n\n- Node.js 24.6.0+ (managed via Volta)\n- TypeScript 5.9.2+\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone git@github.com:adtonos/iab-cat-tax-map.git\ncd @adtonos/iab-cat-tax-map\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build the library\nnpm run build\n```\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # Main exports\n├── types.ts              # TypeScript definitions\n├── detect-taxonomy.ts    # Taxonomy detection logic\n├── is-valid-taxonomy.ts  # Category validation\n├── map-categories.ts     # Core mapping functionality\n├── maps/                 # Specific taxonomy mapping functions\n│   ├── content10ToContent20.ts\n│   ├── content10ToProduct20.ts\n│   ├── content20ToContent10.ts\n│   └── product20ToContent10.ts\n└── sets/                 # Category sets for each taxonomy\n    ├── content-10.ts\n    ├── content-20.ts\n    ├── content-21.ts\n    ├── content-22.ts\n    ├── content-30.ts\n    ├── content-31.ts\n    ├── ad-10.ts\n    ├── ad-20.ts\n    └── audience-11.ts\n```\n\n### Code Quality\n\nThe project uses several tools to maintain code quality:\n\n- **TypeScript**: Static type checking\n- **Prettier**: Code formatting\n- **Husky**: Git hooks\n- **lint-staged**: Pre-commit linting\n\n### Testing\n\n```bash\n# Run all tests using native Node.js test runner\nnpm test\n```\n\n## Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n1. **Fork the repository** and create a feature branch\n2. **Write tests** for any new functionality\n3. **Ensure code quality** by running the linter and formatter\n4. **Update documentation** for any API changes\n5. **Submit a pull request** with a clear description of changes\n\n### Adding New Taxonomy Support\n\nTo add support for a new taxonomy version:\n\n1. Create a new category set in `src/sets/`\n2. Add the taxonomy constant to `types.ts`\n3. Update `detect-taxonomy.ts` and `is-valid-taxonomy.ts`\n4. Create mapping functions in `src/maps/` if needed\n5. Update `map-categories.ts` to include the new mappings\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n---\n\n**Maintained by AdTonos**\n\nFor questions, issues, or contributions, please visit our [GitHub repository](https://github.com/adtonos/iab-cat-tax-map).\n","readmeFilename":"README.md","keywords":["iab","taxonomy","category","content","categories","taxonomies","map","mapping","mapper"]}