klipy-js

Typed JavaScript/TypeScript SDK for the KLIPY API.

import { KlipyClient } from 'klipy-js'

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

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

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:

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 media by query string.

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

params — MediaSearchParams:

Get trending media.

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

params — MediaTrendingParams (same as MediaSearchParams without q).

Get available categories.

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

params — MediaCategoriesParams:

Get recently used media for a customer.

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

params — MediaRecentParams:

Get specific items by slug(s).

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

params — MediaItemsParams:

Remove an item from a customer's recent list.

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

params — MediaHideFromRecentsParams:

Register a share event for analytics.

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

params — MediaShareTriggerParams:

Report an item.

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

params — MediaReportParams:

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

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

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

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

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

params — SuggestionParams:

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

interface Pagination {
  current_page: number
  per_page: number
  has_next: boolean
}

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

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

The package exports the following types for consumers:

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

Clip types ClipItem, ClipPage, ClipPaginatedPage

Client types GifClient, StickerClient, MemeClient, EmojiClient, ClipClient

Param types MediaSearchParams, MediaTrendingParams, MediaRecentParams, MediaCategoriesParams, MediaItemsParams, MediaHideFromRecentsParams, MediaShareTriggerParams, MediaReportParams, MediaPaginationParams, SuggestionParams

Filter types ContentFilter ('off' | 'low' | 'medium' | 'high'), FormatFilter ('gif' | 'webp' | 'jpg' | 'mp4' | 'webm'), MediaReportReasons

When the API returns a non-2xx status, the client throws a KlipyApiError:

import { KlipyApiError } from 'klipy-js'

try {
  await client.gifs.search({ q: 'hello' })
}
catch (error) {
  if (error instanceof KlipyApiError) {
    console.log(error.status) // number
    console.log(error.body) // unknown
  }
}