klipy-js - npm

npm

Search<br>Sign UpSign In

klipy-js

1.1.0 • Public • Published 5 days ago<br>Readme<br>Code Beta<br>0 Dependencies<br>0 Dependents<br>4 Versions<br>klipy-js

Typed JavaScript/TypeScript SDK for the KLIPY API.

Installation

npm install klipy-js

pnpm add klipy-js

Quick Start

import { KlipyClient } from 'klipy-js'

const client = new KlipyClient({ apiKey: 'your-api-key' })

const results = await client.gifs.search({ q: 'hello' })<br>console.log(results.data)

Initialization

const client = new KlipyClient({ apiKey: '...' })

apiKey is required. The client throws if it is missing or empty.

The client exposes five readonly properties and two utility methods:

Property<br>Type

client.gifs<br>GifClient

client.stickers<br>StickerClient

client.memes<br>MemeClient

client.emojis<br>EmojiClient

client.clips<br>ClipClient

API

Media clients — gifs, stickers, memes, emojis

The four media clients (gifs, stickers, memes, emojis) share the same method signatures but return different types depending on the content type.

Each method returns a promise.

search(params)

Search media by query string.

const results = await client.gifs.search({ q: 'hello' })<br>// typeof results — MediaPaginatedPage

params — MediaSearchParams:

Field<br>Type<br>Required

string<br>yes

customerId<br>string<br>no

page<br>number<br>no

perPage<br>number<br>no

locale<br>string<br>no

contentFilter<br>ContentFilter<br>no

formatFilter<br>FormatFilter<br>no

trending(params)

Get trending media.

const results = await client.stickers.trending({})

params — MediaTrendingParams (same as MediaSearchParams without q).

categories(params)

Get available categories.

const cats = await client.memes.categories({ locale: 'en' })<br>// typeof cats — CategoriesData

params — MediaCategoriesParams:

Field<br>Type<br>Required

locale<br>string<br>no

recent(params)

Get recently used media for a customer.

const recent = await client.emojis.recent({ customerId: 'cust-1' })

params — MediaRecentParams:

Field<br>Type<br>Required

customerId<br>string<br>yes

page<br>number<br>no

perPage<br>number<br>no

items(params)

Get specific items by slug(s).

const items = await client.gifs.items({ slugs: 'hello-wave,party' })

params — MediaItemsParams:

Field<br>Type<br>Required

slugs<br>string<br>yes

hideFromRecents(params)

Remove an item from a customer's recent list.

await client.gifs.hideFromRecents({ slug: 'hello', customerId: 'cust-1' })

params — MediaHideFromRecentsParams:

Field<br>Type<br>Required

slug<br>string<br>yes

customerId<br>string<br>yes

shareTrigger(params)

Register a share event for analytics.

await client.gifs.shareTrigger({ slug: 'hello', customerId: 'cust-1' })

params — MediaShareTriggerParams:

Field<br>Type<br>Required

slug<br>string<br>yes

string<br>no

customerId<br>string<br>no

report(params)

Report an item.

await client.gifs.report({ slug: 'hello', reason: 'spam' })

params — MediaReportParams:

Field<br>Type<br>Required

slug<br>string<br>yes

reason<br>MediaReportReasons<br>yes

customerId<br>string<br>no

MediaReportReasons values: 'nudity' | 'violence' | 'hate_speech' | 'harassment' | 'spam' | 'misinformation' | 'copyright' | 'offensive' | 'illegal' | 'broken' | 'low_quality' | 'not_relevant'

Clip client

client.clips has the same methods as the media clients but returns clip-specific types.

const results = await client.clips.search({ q: 'hello' })<br>// typeof results — ClipPaginatedPage<br>const cats = await client.clips.categories({ locale: 'en' })<br>const recent = await client.clips.recent({ customerId: 'cust-1' })<br>const items = await client.clips.items({ slugs: 'hello-wave' })<br>await client.clips.hideFromRecents({ slug: 'hello', customerId: 'cust-1' })<br>await client.clips.shareTrigger({ slug: 'hello' })<br>await client.clips.report({ slug: 'hello', reason: 'spam' })

The search, trending, and recent methods return ClipPaginatedPage. The items method returns ClipPage. All other methods return void.

Search suggestions

client.searchSuggestions(params) and client.autocomplete(params) return search term suggestions directly on the client.

const suggestions = await client.searchSuggestions({ q: 'hel', limit: 5 })<br>// typeof suggestions — string[]<br>const auto = await client.autocomplete({ q: 'hel', limit: 5 })<br>// typeof auto — string[]

params — SuggestionParams:

Field<br>Type<br>Required

string<br>yes

limit<br>number<br>no

Pagination

Methods that return paginated results accept page and perPage in their params. The response includes pagination fields directly on the result object:

interface Pagination {<br>current_page: number<br>per_page: number<br>has_next: boolean

ClipPaginatedPage extends ClipPage + Pagination.<br>MediaPaginatedPage extends MediaPage + Pagination.

const page1 = await client.gifs.search({ q: 'hello', page: 1, perPage: 20 })<br>console.log(page1.current_page) // 1<br>console.log(page1.has_next) // true

Types

The package exports the following types for consumers:

Media types<br>MediaContentType, MediaItem, MediaPage, MediaPaginatedPage, Meta, Pagination, Rendition, CategoriesData, Category

Clip types<br>ClipItem, ClipPage, ClipPaginatedPage

Client types<br>GifClient, StickerClient, MemeClient, EmojiClient,...