API Reference (@knocklabs/client)

In this section, you'll find the documentation for the classes and methods available in the @knocklabs/client library.

Knock

The top level Knock class, used to interact with a client instance.

Params:

apiKeystring*The public API key for the Knock environment.
optionsKnockOptionsAdditional options to pass through.

Example:

userId

Returns the user ID of the authenticated user.

Returns: string

feeds

Returns a FeedClient instance that can be initialized to return a feed.

Optionally a feed can be initialized with a default set of FeedClientOptions which will be applied to all subsequent requests.

Returns: Feed instance

Example:

preferences

Returns a Preferences instance to interact with the preferences API for the current, authenticated user.

Returns: Preferences instance

Example:

client

Returns an instance of an authenticated ApiClient that can be used to make HTTP and Websocket requests to Knock.

Returns: ApiClient instance

authenticate

Authenticates the current user and creates a new Knock session.

Params:

userIdstring*The authenticated user to retrieve a feed for
userTokenstringJWT for the authenticated user. Not required in development environments.

Returns: void

Example:

teardown

Tearsdown a current session and disconnects any connected sockets.

Returns: void

ApiClient

The API client exposes direct functions for communicating with the Knock API over HTTP and websocket.

socket

Returns: a Socket

connectSocket

Connects the socket instance to Knock's realtime server.

Returns: void

disconnectSocket

Disconnects the socket from Knock's realtime server.

Returns: void

makeRequest

Feed

Represents the connection between a user and a feed, including methods for interacting with the items on that feed. Also includes a stateful store that can be used to build in-app notification experiences easily. See FeedStoreState for more on the shape of the store.

store

Returns: StoreApi<FeedStoreState>

listenForUpdates

Connects the feed instance to the realtime socket so that any new items published to the feed are received over the websocket.

Returns: a teardown function.

Example:

Returns: void

on

Binds an event handler to be invoked when the event is triggered.

Events:

items.received.realtimeeventInvoked whenever items are received in realtime from the socket.
items.received.pageeventInvoked whenever items are from performing a fetch. Will be invoked for the initial fetch as well.

Params:

eventNameenum of `messages.new` | `items.received.realtime` | `items.received.page` | `items.received.*`The type of event to bind to.
callbackfunctionA function to be invoked when the event is triggered.

Returns: void.

Example:

off

Unbinds an existing event handler previously bound with on. Use this method to cleanup bound event handlers.

Returns: void.

getState

Programatically access the current FeedStoreState.

Returns: FeedStoreState.

markAsSeen

Marks the given items as seen. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.

Params:

itemOrItemsFeedItemOrItemsA single `FeedItem` or a list of `FeedItem` to perform the update on.

Returns: Promise<ApiResponse>

markAsUnseen

Removes the seen status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.

Params:

itemOrItemsFeedItemOrItemsA single `FeedItem` or a list of `FeedItem` to perform the update on.

Returns: Promise<ApiResponse>

markAsRead

Sets the read status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.

Params:

itemOrItemsFeedItemOrItemsA single `FeedItem` or a list of `FeedItem` to perform the update on.

Returns: Promise<ApiResponse>

markAsUnread

Removes the read status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.

Params:

itemOrItemsFeedItemOrItemsA single `FeedItem` or a list of `FeedItem` to perform the update on.

Returns: Promise<ApiResponse>

markAsArchived

Sets the archived status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.

Params:

itemOrItemsFeedItemOrItemsA single `FeedItem` or a list of `FeedItem` to perform the update on.

Returns: Promise<ApiResponse>

markAsUnarchived

Removes the archived status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.

Params:

itemOrItemsFeedItemOrItemsA single `FeedItem` or a list of `FeedItem` to perform the update on.

Returns: Promise<ApiResponse>

fetch

Fetches

Emits items.received.page events on a successful fetch.

Params:

optionsFetchFeedOptionsOptions to pass through to the feed request

Returns: Promise<ApiResponse>

fetchNextPage

Fetches the next page of the feed items (if there are any more to fetch). Note: this will

FeedStoreState

A zustand state store that holds the current feed state, including item counts, for easy notification feed rendering within your application. The FeedStoreState is entirely managed by the Feed instance, and any calls to fetch(), markAsX, or fetchNextPage will update the state accordingly.

itemsFeedItem[]An ordered list of feed items to be rendered.
pageInfoPageInfoThe page info of the last successful fetch.
metadataFeedMetadataThe current feed metadata including unread, unseen, read, and total counts of items in the feed.
loadingbooleanWhether or not the feed is currently loading.
networkStatusNetworkStatusRepresents the various network states the feed can be in, including differentiating between 'fetching more' and 'fetching'.

Preferences

get

Retrieves a preference set for the authenticated user by calling the get preferences endpoint directly from the client.

Returns: Promise<ApiResponse>

Example:

set

Updates the authenticated users preferences by calling the set preferences endpoint directly from the client.

Params:

preferenceSetSetPreferencesPropertiesThe preferences to set for the current user.

Returns: Promise<ApiResponse>

Example: