@cockpitify/js 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Cockpitify
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Cockpitify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,43 +1,43 @@
-# @cockpitify/js
-
-Usage analytics for web apps: page views, events and sessions, sent to the `ops` layer that
-[Cockpitify](https://cockpitify.app) installs in your own Supabase project. You see them in the Cockpitify app.
-
-```sh
-npm install @cockpitify/js
-```
-
-```ts
-import { Ops } from '@cockpitify/js';
-import { supabase } from './supabase';
-
-Ops.init(supabase); // page views are recorded from here on
-
-// When a feature is used:
-Ops.track('report_exported', { rows: 120 });
-```
-
-Page views come from the History API. Id-like path segments become `[id]`, so `/orders/8412` is
-counted as `/orders/[id]`.
-
-## Not on Supabase Auth
-
-Send batches to your own endpoint, which verifies the user and passes the batch on to `ops.ingest_batch`:
-
-```ts
-import { Ops, httpTransport } from '@cockpitify/js';
-
-Ops.init(httpTransport({ endpoint: 'https://api.example.com/ops', getToken: () => auth.currentUser?.getIdToken() }));
-```
-
-## API
-
-| | |
-|---|---|
-| `Ops.init(target, options?)` | `target`: a supabase-js client, an `httpTransport(...)`, or full options. Options: `appVersion`, `pageViews` (default `true`), `screenName(pathname)`, `debug`. Safe to call again. |
-| `Ops.track(name, props?)` | An event. Props are strings, numbers or booleans. |
-| `Ops.screen(name)` | A screen view, when you name screens yourself. |
-| `Ops.flush()` | Sends what is queued now. |
-| `Ops.optOut()` / `Ops.optIn()` | Stops or resumes recording on this device. |
-
-Recording never throws into your code. Events are queued, sent in batches and retried when offline. A new session starts after 30 minutes away.
+# @cockpitify/js
+
+Usage analytics for web apps: page views, events and sessions, sent to the `ops` layer that
+[Cockpitify](https://cockpitify.app) installs in your own Supabase project. You see them in the Cockpitify app.
+
+```sh
+npm install @cockpitify/js
+```
+
+```ts
+import { Ops } from '@cockpitify/js';
+import { supabase } from './supabase';
+
+Ops.init(supabase); // page views are recorded from here on
+
+// When a feature is used:
+Ops.track('report_exported', { rows: 120 });
+```
+
+Page views come from the History API. Id-like path segments become `[id]`, so `/orders/8412` is
+counted as `/orders/[id]`.
+
+## Not on Supabase Auth
+
+Send batches to your own endpoint, which verifies the user and passes the batch on to `ops.ingest_batch`:
+
+```ts
+import { Ops, httpTransport } from '@cockpitify/js';
+
+Ops.init(httpTransport({ endpoint: 'https://api.example.com/ops', getToken: () => auth.currentUser?.getIdToken() }));
+```
+
+## API
+
+| | |
+|---|---|
+| `Ops.init(target, options?)` | `target`: a supabase-js client, an `httpTransport(...)`, or full options. Options: `appVersion`, `pageViews` (default `true`), `screenName(pathname)`, `debug`. Safe to call again. |
+| `Ops.track(name, props?)` | An event. Props are strings, numbers or booleans. |
+| `Ops.screen(name)` | A screen view, when you name screens yourself. |
+| `Ops.flush()` | Sends what is queued now. |
+| `Ops.optOut()` / `Ops.optIn()` | Stops or resumes recording on this device. |
+
+Recording never throws into your code. Events are queued, sent in batches and retried when offline. A new session starts after 30 minutes away.

package/dist/core.d.ts

@@ -24,6 +24,11 @@ export declare class OpsClient {
     constructor(opts: OpsOptions);
     /** A feature was used. */
     track(name: string, props?: Record<string, unknown>): void;
+    /**
+     * Revenue (an ad impression's earnings, …): like `track`, but never sampled out, since a margin
+     * built from a sample would be wrong. The user's opt-out still holds.
+     */
+    trackRevenue(name: string, props?: Record<string, unknown>): void;
     /** The app moved to a screen (route pattern, e.g. "/quiz/[id]"). The previous one is closed and timed. */
     setScreen(name: string): void;
     /** Sends what is queued now (also called on background). Never throws. */
@@ -37,6 +42,7 @@ export declare class OpsClient {
     private boot;
     private startTimer;
     private applyConfig;
+    /** `essential`: revenue, kept whatever the sample rate. */
     private recording;
     /** Starts a session, or a new one after 30 minutes away (closing the old one at its last activity). */
     private ensureSession;

package/dist/core.js

@@ -98,6 +98,16 @@ export class OpsClient {
             this.push({ type: 'event', name: name.trim().slice(0, 100), t: this.clock.now(), ...(clean ? { props: clean } : {}) });
         });
     }
+    /**
+     * Revenue (an ad impression's earnings, …): like `track`, but never sampled out, since a margin
+     * built from a sample would be wrong. The user's opt-out still holds.
+     */
+    trackRevenue(name, props) {
+        void this.ready.then(() => {
+            const clean = cleanProps(props);
+            this.push({ type: 'event', name: name.trim().slice(0, 100), t: this.clock.now(), ...(clean ? { props: clean } : {}) }, undefined, true);
+        });
+    }
     /** The app moved to a screen (route pattern, e.g. "/quiz/[id]"). The previous one is closed and timed. */
     setScreen(name) {
         void this.ready.then(() => {
@@ -217,8 +227,9 @@ export class OpsClient {
         if (changedTimer)
             this.startTimer();
     }
-    recording() {
-        return !this.optedOut && this.config.enabled && deviceFraction(this.deviceId) < this.config.sampleRate;
+    /** `essential`: revenue, kept whatever the sample rate. */
+    recording(essential = false) {
+        return !this.optedOut && this.config.enabled && (essential || deviceFraction(this.deviceId) < this.config.sampleRate);
     }
     /** Starts a session, or a new one after 30 minutes away (closing the old one at its last activity). */
     ensureSession(now) {
@@ -261,8 +272,8 @@ export class OpsClient {
         if (this.screen)
             this.screen.enteredAt = now;
     }
-    push(e, sessionId) {
-        if (!this.recording() || !e.name)
+    push(e, sessionId, essential = false) {
+        if (!this.recording(essential) || !e.name)
             return;
         if (this.foreground && this.session && e.type !== 'session_end')
             this.session.lastActiveAt = Math.max(this.session.lastActiveAt, this.clock.now());

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { httpTransport, supabaseTransport, isSupabaseClient, type HttpTransportO
 export { createSingleton, resolveOptions, type InitTarget, type OpsApi } from './singleton.js';
 export { routePattern, watchHistory } from './web.js';
 export type * from './types.js';
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.1";
 export interface WebInitOptions {
     /** Your app's version, shown in the console's version breakdown. */
     appVersion?: string;
@@ -19,6 +19,7 @@ export declare const Ops: {
     /** A Supabase client, an `httpTransport(...)`, or full options. Safe to call again (re-initialises). */
     init(target: InitTarget, options?: WebInitOptions): OpsClient;
     track(name: string, props?: Record<string, unknown>): void;
+    trackRevenue(name: string, props?: Record<string, unknown>): void;
     screen(name: string): void;
     flush(): Promise<void>;
     optOut(): void;

package/dist/index.js

@@ -10,7 +10,7 @@ export { OpsClient, cleanProps, randomUuid, SESSION_GAP_MS } from "./core.js";
 export { httpTransport, supabaseTransport, isSupabaseClient } from "./adapters.js";
 export { createSingleton, resolveOptions } from "./singleton.js";
 export { routePattern, watchHistory } from "./web.js";
-export const VERSION = '0.1.0';
+export const VERSION = '0.1.1';
 const singleton = createSingleton();
 let stopHistory = null;
 export const Ops = {

package/dist/singleton.d.ts

@@ -6,6 +6,8 @@ export type InitTarget = SupabaseLike | Transport | OpsOptions;
 export declare function resolveOptions(target: InitTarget, defaults: Omit<OpsOptions, 'transport'>): OpsOptions;
 export interface OpsApi {
     track(name: string, props?: Record<string, unknown>): void;
+    /** Revenue events: never sampled out (see OpsClient.trackRevenue). */
+    trackRevenue(name: string, props?: Record<string, unknown>): void;
     screen(name: string): void;
     flush(): Promise<void>;
     optOut(): void;

package/dist/singleton.js

@@ -27,6 +27,7 @@ export function createSingleton() {
                 fn(client);
         },
         track: (name, props) => run((c) => c.track(name, props)),
+        trackRevenue: (name, props) => run((c) => c.trackRevenue(name, props)),
         screen: (name) => run((c) => c.setScreen(name)),
         flush: () => current?.flush() ?? Promise.resolve(),
         optOut: () => run((c) => c.optOut()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cockpitify/js",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Cockpitify usage analytics for web apps: screen views, events and sessions.",
   "license": "MIT",
   "author": "Cockpitify",