Tags and Taxonomy

/**
 * Fetches a tag by ID
 * @param id - The tag's unique identifier
 * @returns Promise for a tag object
 */
getTag(id: string): Promise<Tag>;

interface Tag {
  /** The tag's display name */
  name: string;
  /** System metadata for the tag */
  sys: TagSys;
}

interface TagSys {
  id: string;
  type: 'Tag';
  version: number;
  visibility: string;
  createdAt: string;
  updatedAt: string;
  createdBy: { sys: UserLink };
  updatedBy: { sys: UserLink };
}

interface UserLink {
  type: 'Link';
  linkType: 'User';
  id: string;
}

import { createClient } from "contentful";

const client = createClient({
  space: 'your-space-id',
  accessToken: 'your-access-token'
});

const tag = await client.getTag('tag-id');
console.log(tag.name); // "Important"
console.log(tag.sys.visibility); // "public"

/**
 * Gets a collection of tags
 * @param query - Optional query parameters for filtering tags
 * @returns Promise for a collection of tags
 */
getTags(query?: TagQueries): Promise<TagCollection>;

interface TagQueries {
  /** Filter by tag name */
  name?: string;
  /** Filter by visibility */
  'sys.visibility'?: 'public' | 'private';
  /** Limit the number of results */
  limit?: number;
  /** Skip the first N results */
  skip?: number;
  /** Order results by field */
  order?: string;
}

interface TagCollection {
  sys: {
    type: 'Array';
  };
  items: Tag[];
  limit: number;
  skip: number;
  total: number;
}

// Get all tags
const allTags = await client.getTags();
console.log(allTags.items);

// Get tags with filtering
const publicTags = await client.getTags({
  'sys.visibility': 'public',
  limit: 10,
  order: 'name'
});

/**
 * Fetches a concept by ID
 * @param id - The concept's unique identifier
 * @returns Promise for a concept object
 */
getConcept(id: string): Promise<Concept<'en-US'>>;

interface Concept<Locales extends LocaleCode> {
  sys: ConceptSys;
  /** Optional URI for the concept */
  uri?: string;
  /** Primary label for the concept in each locale */
  prefLabel: { [locale in Locales]: string };
  /** Alternative labels in each locale */
  altLabels?: { [locale in Locales]: string[] };
  /** Hidden labels for search purposes */
  hiddenLabels?: { [locale in Locales]: string[] };
  /** General note about the concept */
  note?: { [locale in Locales]: string } | null;
  /** Definition of the concept */
  definition?: { [locale in Locales]: string } | null;
  /** Editorial notes for content creators */
  editorialNote?: { [locale in Locales]: string } | null;
  /** Usage examples */
  example?: { [locale in Locales]: string } | null;
  /** History and change notes */
  historyNote?: { [locale in Locales]: string } | null;
  /** Scope and application notes */
  scopeNote?: { [locale in Locales]: string } | null;
  /** Notation codes for the concept */
  notations?: string[];
  /** Links to broader concepts */
  broader?: UnresolvedLink<'TaxonomyConcept'>[];
  /** Links to related concepts */
  related?: UnresolvedLink<'TaxonomyConcept'>[];
  /** Links to concept schemes this concept belongs to */
  conceptSchemes?: UnresolvedLink<'TaxonomyConceptScheme'>[];
}

interface ConceptSys {
  id: string;
  type: 'TaxonomyConcept';
  createdAt: string;
  updatedAt: string;
  version: number;
}

const concept = await client.getConcept('concept-id');
console.log(concept.prefLabel['en-US']); // "Machine Learning"
console.log(concept.definition?.['en-US']); // "A method of data analysis..."

/**
 * Fetches a collection of concepts
 * @param query - Optional query parameters for filtering concepts
 * @returns Promise for a collection of concepts
 */
getConcepts(query?: ConceptsQueries): Promise<ConceptCollection<'en-US'>>;

interface ConceptsQueries {
  /** Filter by concept scheme */
  'sys.conceptScheme.sys.id'?: string;
  /** Search in preferred labels */
  'prefLabel[match]'?: string;
  /** Limit the number of results */
  limit?: number;
  /** Skip the first N results */
  skip?: number;
  /** Order results by field */
  order?: string;
}

interface ConceptCollection<Locale extends LocaleCode> {
  sys: {
    type: 'Array';
  };
  items: Concept<Locale>[];
  limit: number;
  pages?: {
    prev?: string;
    next?: string;
  };
}

// Get all concepts
const concepts = await client.getConcepts();

// Search concepts by label
const mlConcepts = await client.getConcepts({
  'prefLabel[match]': 'machine learning'
});

/**
 * Fetches a concept scheme by ID
 * @param id - The concept scheme's unique identifier
 * @returns Promise for a concept scheme object
 */
getConceptScheme(id: string): Promise<ConceptScheme<'en-US'>>;

interface ConceptScheme<Locales extends LocaleCode> {
  sys: ConceptSchemeSys;
  /** Optional URI for the concept scheme */
  uri?: string;
  /** Primary label for the scheme in each locale */
  prefLabel: { [locale in Locales]: string };
  /** Definition of the concept scheme */
  definition?: { [locale in Locales]: string } | null;
  /** Links to top-level concepts in the scheme */
  topConcepts: UnresolvedLink<'TaxonomyConcept'>[];
  /** Links to all concepts in the scheme */
  concepts: UnresolvedLink<'TaxonomyConcept'>[];
  /** Total number of concepts in the scheme */
  totalConcepts: number;
}

interface ConceptSchemeSys {
  id: string;
  type: 'TaxonomyConceptScheme';
  createdAt: string;
  updatedAt: string;
  version: number;
}

const scheme = await client.getConceptScheme('scheme-id');
console.log(scheme.prefLabel['en-US']); // "Technology Categories"
console.log(scheme.totalConcepts); // 150

/**
 * Fetches a collection of concept schemes
 * @param query - Optional query parameters for filtering concept schemes
 * @returns Promise for a collection of concept schemes
 */
getConceptSchemes(query?: ConceptSchemesQueries): Promise<ConceptSchemeCollection<'en-US'>>;

interface ConceptSchemesQueries {
  /** Search in preferred labels */
  'prefLabel[match]'?: string;
  /** Limit the number of results */
  limit?: number;
  /** Skip the first N results */
  skip?: number;
  /** Order results by field */
  order?: string;
}

interface ConceptSchemeCollection<Locale extends LocaleCode> {
  sys: {
    type: 'Array';
  };
  items: ConceptScheme<Locale>[];
  limit: number;
  pages?: {
    prev?: string;
    next?: string;
  };
}

// Get all concept schemes
const schemes = await client.getConceptSchemes();

// Search schemes by name
const techSchemes = await client.getConceptSchemes({
  'prefLabel[match]': 'technology'
});

interface UnresolvedLink<LinkType extends string> {
  sys: {
    type: 'Link';
    linkType: LinkType;
    id: string;
  };
}

type LocaleCode = string;