# @xylabs/sdk-meta

[![npm][npm-badge]][npm-link]
[![license][license-badge]][license-link]

> Base functionality used throughout XYO TypeScript/JavaScript libraries

## Install

Using npm:

```sh
npm install {{name}}
```

Using yarn:

```sh
yarn add {{name}}
```

Using pnpm:

```sh
pnpm add {{name}}
```

Using bun:

```sh
bun add {{name}}
```


## License

See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).

## Reference

### packages

  ### meta

    ### .temp-typedoc

      ### functions

        ### <a id="addMetaToHead"></a>addMetaToHead

[**@xylabs/sdk-meta**](#../README)

***

```ts
function addMetaToHead(
   $, 
   name, 
   value): void;
```

Adds or replaces a meta tag in the document head.

## Parameters

### $

`CheerioAPI`

The Cheerio API instance for the document.

### name

`string`

The meta property name.

### value

`string` \| `object`

The meta content value (string, array, or nested object).

## Returns

`void`

        ### <a id="getMetaAsDict"></a>getMetaAsDict

[**@xylabs/sdk-meta**](#../README)

***

```ts
function getMetaAsDict(obj, parentKey?): Record<string, string>;
```

Recursively flattens a nested meta object into a flat dictionary with colon-delimited keys.

## Parameters

### obj

[`StringIndexable`](#../type-aliases/StringIndexable)

The nested object to flatten.

### parentKey?

`string`

The accumulated key prefix from parent levels.

## Returns

`Record`\<`string`, `string`\>

A flat record mapping colon-delimited property names to string values.

        ### <a id="mergeDocumentHead"></a>mergeDocumentHead

[**@xylabs/sdk-meta**](#../README)

***

```ts
function mergeDocumentHead(destination, source): string;
```

Merges meta tags from the source HTML head into the destination HTML head.
Existing meta tags with matching property attributes are replaced; others are appended.

## Parameters

### destination

`string`

The base HTML string to merge into.

### source

`string`

The HTML string whose head meta tags will be merged.

## Returns

`string`

The merged HTML string.

        ### <a id="metaBuilder"></a>metaBuilder

[**@xylabs/sdk-meta**](#../README)

***

```ts
function metaBuilder(
   html, 
   meta, 
   handler?): string;
```

Injects meta properties, title, and description into an HTML string.

## Parameters

### html

`string`

The base HTML string to modify.

### meta

[`Meta`](#../interfaces/Meta)

The metadata to inject.

### handler?

`string`

Optional meta-handler property value to include.

## Returns

`string`

The modified HTML string with injected metadata.

      ### interfaces

        ### <a id="Meta"></a>Meta

[**@xylabs/sdk-meta**](#../README)

***

Represents page metadata including Open Graph and Twitter card properties.

## Properties

### description?

```ts
optional description?: string;
```

***

### og?

```ts
optional og?: OpenGraphMeta;
```

***

### title?

```ts
optional title?: string;
```

***

### twitter?

```ts
optional twitter?: TwitterMeta;
```

        ### <a id="OpenGraphMeta"></a>OpenGraphMeta

[**@xylabs/sdk-meta**](#../README)

***

Open Graph protocol metadata for rich link previews.

## Properties

### audio?

```ts
optional audio?: OpenGraphStructuredProperty;
```

***

### description?

```ts
optional description?: string;
```

***

### determiner?

```ts
optional determiner?: string;
```

***

### image?

```ts
optional image?: OpenGraphStructuredProperty;
```

***

### locale?

```ts
optional locale?: string | string[];
```

***

### site\_name?

```ts
optional site_name?: string;
```

***

### title?

```ts
optional title?: string;
```

***

### type?

```ts
optional type?: string;
```

***

### url?

```ts
optional url?: string;
```

***

### video?

```ts
optional video?: OpenGraphStructuredProperty;
```

        ### <a id="OpenGraphStructured"></a>OpenGraphStructured

[**@xylabs/sdk-meta**](#../README)

***

Structured properties for an Open Graph media object (image, video, or audio).

## Properties

### ?

```ts
optional ?: string;
```

***

### alt?

```ts
optional alt?: string;
```

***

### height?

```ts
optional height?: number;
```

***

### secure\_url?

```ts
optional secure_url?: string;
```

***

### type?

```ts
optional type?: string;
```

***

### url?

```ts
optional url?: string;
```

***

### width?

```ts
optional width?: number;
```

        ### <a id="TwitterApp"></a>TwitterApp

[**@xylabs/sdk-meta**](#../README)

***

Twitter App Card metadata containing app store identifiers, names, and URLs per platform.

## Properties

### id?

```ts
optional id?: object;
```

### googleplay?

```ts
optional googleplay?: string;
```

### ipad?

```ts
optional ipad?: string;
```

### iphone?

```ts
optional iphone?: string;
```

***

### name?

```ts
optional name?: object;
```

### googleplay?

```ts
optional googleplay?: string;
```

### ipad?

```ts
optional ipad?: string;
```

### iphone?

```ts
optional iphone?: string;
```

***

### url?

```ts
optional url?: object;
```

### googleplay?

```ts
optional googleplay?: string;
```

### ipad?

```ts
optional ipad?: string;
```

### iphone?

```ts
optional iphone?: string;
```

        ### <a id="TwitterMeta"></a>TwitterMeta

[**@xylabs/sdk-meta**](#../README)

***

https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup

## Properties

### app?

```ts
optional app?: TwitterApp;
```

***

### card?

```ts
optional card?: "summary" | "summary_large_image" | "app" | "player";
```

The card type. Used with all cards. Fallback: og:type.
If an og:type, og:title and og:description exist in the markup but
twitter:card is absent, then a summary card may be rendered.

***

### creator?

```ts
optional creator?: object;
```

### ?

```ts
optional ?: string;
```

The

#### Username

of content creator. Used with summary_large_image cards

### id?

```ts
optional id?: string;
```

Twitter user ID of content creator. Used with summary,
summary_large_image cards

***

### description?

```ts
optional description?: string;
```

Description of content (maximum 200 characters). Used with summary,
summary_large_image, player cards. Fallback: og:description.

***

### image?

```ts
optional image?: object;
```

### ?

```ts
optional ?: string;
```

URL of image to use in the card. Images must be less than 5MB in size.
JPG, PNG, WEBP and GIF formats are supported. Only the first frame of
an animated GIF will be used. SVG is not supported. Used with summary,
summary_large_image, player cards. Fallback: og:image

### alt?

```ts
optional alt?: string;
```

A text description of the image conveying the essential nature of
an image to users who are visually impaired. Maximum 420
characters. Used with summary, summary_large_image, player cards

***

### player?

```ts
optional player?: TwitterPlayer;
```

***

### site?

```ts
optional site?: object;
```

The

### ?

```ts
optional ?: string;
```

### id?

```ts
optional id?: string;
```

Same as twitter:site, but the user’s Twitter ID. Either
twitter:site or twitter:site:id is required. Used with
summary, summary_large_image, player cards

### Username

of website. Either twitter:site or twitter:site:id is
required. Used with summary, summary_large_image, app, player
cards

***

### title?

```ts
optional title?: string;
```

Title of content (max 70 characters). Used with summary,
summary_large_image, player cards. Fallback: og:title.

        ### <a id="TwitterPlayer"></a>TwitterPlayer

[**@xylabs/sdk-meta**](#../README)

***

https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/player-card

## Properties

### 

```ts
: string;
```

HTTPS URL to iFrame player. This must be a HTTPS URL which does not
generate active mixed content warnings in a web browser. The audio or
video player must not require plugins such as Adobe Flash.

***

### height?

```ts
optional height?: number;
```

Height of iframe in pixels. Used with player card

***

### stream?

```ts
optional stream?: string;
```

URL to raw video or audio stream. Used with player card

***

### width?

```ts
optional width?: number;
```

Width of iframe in pixels. Used with player card

      ### type-aliases

        ### <a id="OpenGraphStructuredProperty"></a>OpenGraphStructuredProperty

[**@xylabs/sdk-meta**](#../README)

***

```ts
type OpenGraphStructuredProperty = 
  | string
  | OpenGraphStructured
  | (string | OpenGraphStructured)[];
```

A structured Open Graph property value: a URL string, a structured object, or an array of either.

        ### <a id="StringIndexable"></a>StringIndexable

[**@xylabs/sdk-meta**](#../README)

***

```ts
type StringIndexable = Record<string, any>;
```

An object with string keys and arbitrary values, used for recursive meta flattening.


[npm-badge]: https://img.shields.io/npm/v/@xylabs/sdk-meta.svg
[npm-link]: https://www.npmjs.com/package/@xylabs/sdk-meta
[license-badge]: https://img.shields.io/npm/l/@xylabs/sdk-meta.svg
[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE