@lapwy/js 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @lapwy/js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The lapwy tracker for any website or single-page app.
+
+```sh
+npm install @lapwy/js
+```
+
+```js
+import { init, track } from "@lapwy/js";
+
+init({ site: "lw_…" });           // once, in the browser
+track("signup", { plan: "pro" }); // anywhere, any time
+```
+
+Route changes are followed on their own. `init` is safe to call more than once and safe on a server, where it does nothing. Calls made before `init` are kept and sent after it.
+
+Also exported: `page`, `consent` and `notFound`.
+
+With React, Next.js or Vue, use [`@lapwy/react`](https://www.npmjs.com/package/@lapwy/react), [`@lapwy/next`](https://www.npmjs.com/package/@lapwy/next) or [`@lapwy/vue`](https://www.npmjs.com/package/@lapwy/vue) instead of calling `init` yourself.

package/dist/core.d.cts

@@ -0,0 +1,55 @@
+export type Props = Record<string, string | number | boolean>;
+export type Options = {
+    /** The site's public key, from its Install screen. */
+    site: string;
+    /** Where events go. Defaults to lapwy's own ingest. */
+    endpoint?: string;
+    /**
+     * "always": keep a first-party id. "consent": only after consent(true).
+     * Anything else: never. The site's setting in lapwy must ask for it too.
+     */
+    cookie?: "always" | "consent" | false | null;
+    /** Your build or version, to see what a release changed. */
+    release?: string;
+    /**
+     * Calls the page makes with fetch and XMLHttpRequest are counted per
+     * endpoint: how many, how many failed, how long they took. Calls to the
+     * page's own domain always count; list other API hosts here
+     * (["api.example.com"]). false switches it off.
+     */
+    api?: string[] | false;
+    /**
+     * Pages to count as one. By default every address is its own page. A
+     * pattern groups the ones that differ only by an id or a name:
+     * ["/blog/:slug", "/users/:id/orders/:order", "/docs/*"]. A part that
+     * starts with ":" stands for any one part of the path; "*" at the end
+     * stands for everything after it. A page that fits is sent as the pattern
+     * itself, so the id never leaves the browser, and the pages cannot be told
+     * apart afterwards. The first pattern that fits wins.
+     */
+    pages?: string[];
+    /**
+     * Full control over the path that is sent, for what patterns cannot say:
+     * path: (p) => p.replace(/^\/(en|nl|de)\//, "/"). Used instead of pages.
+     */
+    path?: (path: string) => string;
+    /** Names the sender in the data. Set by the entry points. */
+    sdk?: string;
+};
+export type Tracker = {
+    /** Something a visitor did: track("signup", { plan: "pro" }). */
+    track: (name: string, props?: Props) => void;
+    /** A page view. Called on its own for the first page and for every route change. */
+    page: (props?: Props) => void;
+    /** Tell the tracker what the visitor said about cookies. Only matters with cookie: "consent". */
+    consent: (granted: boolean) => void;
+    /**
+     * This page is a dead end: call it from the "not found" screen of a
+     * single-page app, which the browser cannot tell from a real page.
+     * A page the server answers with a 404 or a 500 is seen without it.
+     */
+    notFound: (status?: number) => void;
+};
+export declare const DEFAULT_ENDPOINT = "https://in.lapwy.com/e";
+/** Starts tracking this page. Call it once, in the browser. On a server it does nothing. */
+export declare function start(options: Options): Tracker;

package/dist/core.d.ts

@@ -0,0 +1,55 @@
+export type Props = Record<string, string | number | boolean>;
+export type Options = {
+    /** The site's public key, from its Install screen. */
+    site: string;
+    /** Where events go. Defaults to lapwy's own ingest. */
+    endpoint?: string;
+    /**
+     * "always": keep a first-party id. "consent": only after consent(true).
+     * Anything else: never. The site's setting in lapwy must ask for it too.
+     */
+    cookie?: "always" | "consent" | false | null;
+    /** Your build or version, to see what a release changed. */
+    release?: string;
+    /**
+     * Calls the page makes with fetch and XMLHttpRequest are counted per
+     * endpoint: how many, how many failed, how long they took. Calls to the
+     * page's own domain always count; list other API hosts here
+     * (["api.example.com"]). false switches it off.
+     */
+    api?: string[] | false;
+    /**
+     * Pages to count as one. By default every address is its own page. A
+     * pattern groups the ones that differ only by an id or a name:
+     * ["/blog/:slug", "/users/:id/orders/:order", "/docs/*"]. A part that
+     * starts with ":" stands for any one part of the path; "*" at the end
+     * stands for everything after it. A page that fits is sent as the pattern
+     * itself, so the id never leaves the browser, and the pages cannot be told
+     * apart afterwards. The first pattern that fits wins.
+     */
+    pages?: string[];
+    /**
+     * Full control over the path that is sent, for what patterns cannot say:
+     * path: (p) => p.replace(/^\/(en|nl|de)\//, "/"). Used instead of pages.
+     */
+    path?: (path: string) => string;
+    /** Names the sender in the data. Set by the entry points. */
+    sdk?: string;
+};
+export type Tracker = {
+    /** Something a visitor did: track("signup", { plan: "pro" }). */
+    track: (name: string, props?: Props) => void;
+    /** A page view. Called on its own for the first page and for every route change. */
+    page: (props?: Props) => void;
+    /** Tell the tracker what the visitor said about cookies. Only matters with cookie: "consent". */
+    consent: (granted: boolean) => void;
+    /**
+     * This page is a dead end: call it from the "not found" screen of a
+     * single-page app, which the browser cannot tell from a real page.
+     * A page the server answers with a 404 or a 500 is seen without it.
+     */
+    notFound: (status?: number) => void;
+};
+export declare const DEFAULT_ENDPOINT = "https://in.lapwy.com/e";
+/** Starts tracking this page. Call it once, in the browser. On a server it does nothing. */
+export declare function start(options: Options): Tracker;