npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

lilbird

v0.2.19

Published

A Tinybird Event API helper library in the style of Analytics.js

Downloads

7

Readme

LilBird

Tinybird Event API helper library.

Adds routine Analytics.js style tracking to Tinybird with as little setup as possible.

Lilbird

Tinybird Signup & Setup

  1. Head to https://www.tinybird.co/
  2. Create a new account
  3. Put your data into the EU region when prompted
  4. Create a new Auth Token. This is your WRITE_KEY.
    1. You should only select: DATA SOURCES SCOPES
      1. Create new Data Sources or append data to existing ones (ENABLED)
    2. This will allow your key to be used to send events to Tinybird, create Data Sources (tables) on the fly, and not much else.

You should create a write-only key for your Tinybird instance. They'll give you a key with lots of permissions when you sign up. For security reasons, don't use this one.

Create a Tinybird Write Key

Setup

Inline (HTML)

<script>window.TINYBIRD_CONFIGURATION = { WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY' }</script>
<script src="https://cdn.jsdelivr.net/npm/lilbird@latest"></script>

You should create a write-only key for your Tinybird instance. See instructions above.

NPM

npm i -s lilbird

Then, in your project:

import * as Lilbird from 'lilbird';

Lilbird.init({ WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY' });

Usage

Like most event analytics platforms, Lilbird exposes a track() and an identify() method.

Identify is used to set properties on your current user, which describes the user. For example, you could identify whether the user is a paying customer, or on a free trial, with identify({ trial: false })

Track sends an event to Tinybird, which includes every property identified for this user. For example, you could track('new_project_created') to later visualize the number of new projects created over time.

If you wanted to track new projects created by type, you could send that like this; track('new_project_created', { type: 'IT' '}).

It is recommended that you enforce types and set a default value for every column (user or event property) you send to Tinybird. See "Enforce Types" and "Default Values" below.

Event properties that are added automatically, if not defined

  1. A timestamp is appended to each event under the namespace ts
    1. This is formatted as an ISOString (ISO 8601)
  2. A unique session identifier is stored in sessionStorage and appended to each event under the namespace session_id
  3. An anonymous device identifier is appended to each event under the namespace anonymous_device_id
    1. If your requirements are minimal, you can use this as your unique user identifier. Otherwise, send a uid or uuid to whatever namespace you like, and use this as your fallback identifier for anonymous users.

Disabling Automatic Event Properties

Each of these can be disabled by sending the appropriate configuration:

Lilbird.init({ 
   WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
   ADD_ANONYMOUS_DEVICE_ID: false,
   ADD_SESSION_ID: false,
   ADD_TS: false,
});

Identifying users (Optional)

You can identify users before sending a track() event. This appends data to the user, which will be sent alongside each track() event.

Example:

var uid = '123456';

Lilbird.identify(uid, {
   user: true,
   age: 32,
   admin: false,
   beta: false,
   name: 'John Doe',
});

UID is optional. You can omit it, or even include it in the body:

Lilbird.identify({
   user: true,
   age: 32,
   admin: false,
   beta: false,
   name: 'John Doe',
});

Tracking Events

Events are tracked using the track() method. This tracks an event by adding a row to a Data Source in Tinybird.

Event names can be letters, numbers, dashes, underscores, but no spaces or special characters.

Example:

var event_name = 'signed_up';

Lilbird.track(event_name, {
   username: 'bob'
});

The payload is optional, and describes the event you are tracking. Be aware, namespaces conflict with values sent via the Identify method, and should be unique. If you have previously sent a value, it must be of the same type each time it is sent.

You can also track an event without a payload.

Lilbird.track('login');

Default Values

Tinybird enforces strict checks on each ingested row, and quarantines any row with a missing column. Therefore, it's a good idea to provide default values for every column that isn't nullable.

Keep in mind, sometimes rejected data is what you really want. Instead of allowing Tinybird to ingest bad data (like in our example below, login events without a username), you may want to skip defaults, and allow the invalid rows to be rejected. Otherwise, you're going to be writing SQL later to filter out the invalid data.

Here's an example of how you can set defaults with the DEFAULTS configuration namespace:

Lilbird.init({
   WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
   DEFAULTS: {
      "*": {
         "created_at": 0
      },
      "login": {
         "username": "-"
      }
   }
});

In this example, if we sent a login event with no body, it would get a default value for both created_at and username, preventing any related insertion errors.

Enforce Types

Tinybird enforces strict type checks on each ingested row, and rows with any column that doesn't match your schema will be quarantined and permanently rejected.

So, you can enforce types for your incoming data, via configuration, to prevent this from occurring.

Available types are:

  • boolean
  • integer
  • string
  • float

Here's an example:

Lilbird.init({
   WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
   ENFORCE_TYPES: {
      "*": {
         "created_at": 'integer'
      },
      "login": {
         "username": "string",
         "company": "string",
         "age": "integer",
         "is_registered": "boolean",
         "pixel_ratio": "float"
      }
   }
});

Custom Body Transformation (Advanced)

Tinybird has strict type checking and enforcement, so you may need to do data transformation on events before they're sent, to prevent validation errors.

You can do that with a BODY_TRANSFORMATION function, which modifies the body before Tinybird ingestion.

Note: this is a synchronous function, which must return the body once it is modified.

Example:

Lilbird.init({
   WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
   BODY_TRANSFORMATION: function(body, event_name) {
       if (event_name === 'pageview') {
           // Do something
           if (typeof body.ts === 'string') body.ts = parseInt(body.ts);
       }
       
       return body;
   }
});

Transform all numbers to strings

The configuration option TRANSFORM_NUMBERS_TO_STRINGS transforms all properties which are numbers into strings.

Lilbird.init({
   WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
   TRANSFORM_NUMBERS_TO_STRINGS: true
});