Nonprofit Pizza Maker

    @knocklabs/client
    TypeScript icon, indicating that this package has built-in type declarations

    0.8.4 • Public • Published

    Knock Javascript client library

    A client-side Javascript library to interact with user-facing Knock features, such as feeds.

    Note: this is a lower level library designed for building UI on top of

    Documentation

    See the documentation for usage examples.

    Installation

    Via NPM:

    npm install @knocklabs/client

    Via Yarn:

    yarn add @knocklabs/client

    Configuration

    To configure the client library you will need:

    1. A public API key (found in the Knock dashboard)
    2. A feed channel ID (found in the Knock dashboard)
    3. A user ID, and optionally an auth token for production environments
    import Knock from "@knocklabs/client";
    
    const knockClient = new Knock(process.env.KNOCK_API_KEY);
    
    knockClient.authenticate(
      // The id of the user you want to authenticate against
      currentUser.id,
      // You only need this in production environments
      currentUser.knockToken,
    );

    Usage

    You can find an example usage in a React application in the example/App.js file, which is a plain-old Create React App.

    Retrieving new items from the feed

    import Knock from "@knocklabs/client";
    
    const knockClient = new Knock(process.env.KNOCK_API_KEY);
    
    // Authenticate the user
    knockClient.authenticate(currentUser.id, currentUser.knockToken);
    
    // Initialize the feed
    const feedClient = knockClient.feeds.initialize(
      process.env.KNOCK_FEED_CHANNEL_ID,
      // Optionally you can provide a default scope here:
      // { tenant: "jurassic-park", source: "new-comment" },
    );
    
    // Connect to the real-time socket
    const teardown = feedClient.listenForUpdates();
    
    // Setup a callback for when a batch of items is received (including on first load and subsequent page load)
    feedClient.on("items.received.page", ({ items }) => {
      console.log(items);
    });
    
    // Setup a callback for when new items arrive in real-time
    feedClient.on("items.received.realtime", ({ items }) => {
      console.log(items);
    });
    
    // Listen to all received items
    feedClient.on("items.received.*", ({ items }) => {
      console.log(items);
    });
    
    // Fetch the feed items
    feedClient.fetch({
      // Fetch a particular status only (defaults to all)
      status: "all" | "unread" | "unseen",
      // Pagination options
      after: lastItem.__cursor,
      before: firstItem.__cursor,
      // Defaults to 50
      page_size: 10,
      // Filter by a specific source
      source: "notification-key",
      // Filter by a specific tenant
      tenant: "jurassic-park",
    });
    
    teardown();

    Reading the feed store state (programmatically)

    // Initialize the feed as in above examples
    const feedClient = knockClient.feeds.initialize(
      process.env.KNOCK_FEED_CHANNEL_ID,
    );
    
    // Gives you all of the items currently in the store
    const { items } = feedClient.store.getState();

    Reading the feed store state (in React)

    // The feed store uses zustand
    import create from "zustand";
    
    // Initialize the feed as in above examples
    const feedClient = knockClient.feeds.initialize(
      process.env.KNOCK_FEED_CHANNEL_ID,
    );
    
    const useFeedStore = create(feedClient.store);
    
    // Retrieves all of the items
    const items = useFeedStore((state) => state.items);
    
    // Retrieve the badge counts
    const meta = useFeedStore((state) => state.metadata);

    Marking items as read, seen, or archived

    // Initialize the feed as in above examples
    const feedClient = knockClient.feeds.initialize(
      process.env.KNOCK_FEED_CHANNEL_ID,
    );
    
    // Mark one or more items as read
    feedClient.markAsRead(feedItemOrItems);
    // Mark one or more items as seen
    feedClient.markAsSeen(feedItemOrItems);
    // Mark one or more items as archived
    feedClient.markAsArchived(feedItemOrItems);
    
    // Mark one or more items as unread
    feedClient.markAsUnread(feedItemOrItems);
    // Mark one or more items as unseen
    feedClient.markAsUnseen(feedItemOrItems);
    // Mark one or more items as unarchived
    feedClient.markAsUnarchived(feedItemOrItems);

    Managing user preferences

    // Set an entire preference set
    await knockClient.preferences.set({
      channel_types: { email: true, sms: false },
      workflows: {
        "dinosaurs-loose": {
          channel_types: { email: false, in_app_feed: true },
        },
      },
    });
    
    // Retrieve a whole preference set
    const preferences = await knockClient.preferences.get();
    
    // Granular preference setting for channel types
    await knockClient.preferences.setChannelType("email", false);
    
    // Granular preference setting for workflows
    await knockClient.preferences.setWorkflow("dinosaurs-loose", {
      channel_types: {
        email: true,
        in_app_feed: false,
      },
    });

    Keywords

    none

    Install

    npm i @knocklabs/client

    DownloadsWeekly Downloads

    15,606

    Version

    0.8.4

    License

    MIT

    Unpacked Size

    272 kB

    Total Files

    95

    Last publish

    Collaborators

    • cjbell
    • samseely