@bunizao/contracts 0.22.0 → 0.24.0

package/dist/analytics.d.ts

@@ -359,3 +359,106 @@ export interface SiteAnalyticsReportResult {
     }> | null;
     notices: string[];
 }
+export declare const SITE_EXPLORE_ENDPOINT: '/api/analytics/explore';
+export declare const SITE_EXPLORE_VIEWS: readonly ['traffic', 'decoy'];
+export type SiteExploreView = typeof SITE_EXPLORE_VIEWS[number];
+export declare const SITE_EXPLORE_RANGES: readonly ['24h', '7d', '30d', '90d'];
+export type SiteExploreRange = typeof SITE_EXPLORE_RANGES[number];
+export declare const SITE_EXPLORE_CLASSES: readonly ['human', 'bot', 'owner', 'all'];
+export type SiteExploreClass = typeof SITE_EXPLORE_CLASSES[number];
+export declare const SITE_EXPLORE_PARTS: readonly ['summary', 'panel', 'clicks', 'log'];
+export type SiteExplorePart = typeof SITE_EXPLORE_PARTS[number];
+export declare const SITE_EXPLORE_DIMS: {
+    readonly traffic: readonly ['page', 'section', 'referrer', 'channel', 'utm', 'country', 'city', 'device', 'browser', 'os', 'visitor'];
+    readonly decoy: readonly ['client', 'kind', 'reason', 'ua', 'path', 'network', 'country'];
+};
+export type SiteExploreDim<V extends SiteExploreView = SiteExploreView> = typeof SITE_EXPLORE_DIMS[V][number];
+export declare const SITE_EXPLORE_METRICS: {
+    readonly traffic: readonly ['visitors', 'views', 'engagement', 'dwell'];
+    readonly decoy: readonly ['hits', 'clients', 'networks', 'named'];
+};
+export type SiteExploreMetric<V extends SiteExploreView = SiteExploreView> = typeof SITE_EXPLORE_METRICS[V][number];
+export declare const SITE_EXPLORE_PANEL_LIMIT = 100;
+export declare const SITE_EXPLORE_EMPTY = "(none)";
+export interface SiteExploreSeries {
+    totals: Record<string, number>;
+    points: Record<string, number[]>;
+}
+export interface SiteExploreSummary {
+    view: SiteExploreView;
+    range: SiteExploreRange;
+    timezone: 'Australia/Melbourne';
+    bucket: 'hour' | 'day';
+    buckets: string[];
+    from: string;
+    to: string;
+    previousFrom: string | null;
+    current: SiteExploreSeries;
+    previous: SiteExploreSeries | null;
+    notices: Array<'compare_beyond_retention'>;
+}
+export interface SiteExploreRow {
+    key: string;
+    label: string;
+    count: number;
+    visitors: number;
+}
+export interface SiteExplorePanel {
+    dim: SiteExploreDim;
+    rows: SiteExploreRow[];
+    more: boolean;
+}
+export interface SiteExploreClickRow {
+    name: string;
+    label: string;
+    href: string;
+    clicks: number;
+    visitors: number;
+}
+export interface SiteExploreClicks {
+    rows: SiteExploreClickRow[];
+    more: boolean;
+    ignored: SiteExploreDim<'traffic'>[];
+}
+export interface SiteExploreVisit {
+    at: string;
+    until: string;
+    visitor: string;
+    session: string;
+    class: SiteAnalyticsTrafficClass;
+    country: string;
+    city: string;
+    network: string;
+    org: string;
+    device: string;
+    browser: string;
+    os: string;
+    entry: string;
+    referrer: string;
+    channel: string;
+    pages: number;
+    dwellMs: number;
+    interactions: number;
+}
+export interface SiteExploreDecoyHit {
+    at: string;
+    reason: string;
+    kind: string;
+    client: string;
+    ua: string;
+    path: string;
+    network: string;
+    org: string;
+    country: string;
+    method: string;
+}
+export type SiteExploreLog = {
+    view: 'traffic';
+    rows: SiteExploreVisit[];
+    more: boolean;
+    next: string | null;
+} | {
+    view: 'decoy';
+    rows: SiteExploreDecoyHit[];
+    more: boolean;
+};

package/dist/analytics.js

@@ -36,6 +36,21 @@ var SITE_ANALYTICS_SURFACES = [
   "other"
 ];
 var SITE_ANALYTICS_REPORTS = ["overview", "pages", "clicks", "sources", "audience", "quality", "log", "visitor"];
+var SITE_EXPLORE_ENDPOINT = "/api/analytics/explore";
+var SITE_EXPLORE_VIEWS = ["traffic", "decoy"];
+var SITE_EXPLORE_RANGES = ["24h", "7d", "30d", "90d"];
+var SITE_EXPLORE_CLASSES = ["human", "bot", "owner", "all"];
+var SITE_EXPLORE_PARTS = ["summary", "panel", "clicks", "log"];
+var SITE_EXPLORE_DIMS = {
+  traffic: ["page", "section", "referrer", "channel", "utm", "country", "city", "device", "browser", "os", "visitor"],
+  decoy: ["client", "kind", "reason", "ua", "path", "network", "country"]
+};
+var SITE_EXPLORE_METRICS = {
+  traffic: ["visitors", "views", "engagement", "dwell"],
+  decoy: ["hits", "clients", "networks", "named"]
+};
+var SITE_EXPLORE_PANEL_LIMIT = 100;
+var SITE_EXPLORE_EMPTY = "(none)";
 export {
   BLOG_ANALYTICS_ARTICLE_ENDPOINT,
   BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH,
@@ -53,5 +68,14 @@ export {
   SITE_ANALYTICS_REPORTS,
   SITE_ANALYTICS_REPORT_ENDPOINT,
   SITE_ANALYTICS_SESSION_IDLE_MS,
-  SITE_ANALYTICS_SURFACES
+  SITE_ANALYTICS_SURFACES,
+  SITE_EXPLORE_CLASSES,
+  SITE_EXPLORE_DIMS,
+  SITE_EXPLORE_EMPTY,
+  SITE_EXPLORE_ENDPOINT,
+  SITE_EXPLORE_METRICS,
+  SITE_EXPLORE_PANEL_LIMIT,
+  SITE_EXPLORE_PARTS,
+  SITE_EXPLORE_RANGES,
+  SITE_EXPLORE_VIEWS
 };

package/dist/desk.d.ts

@@ -0,0 +1,78 @@
+/** Mac power state as the reporter sees it. */
+export declare const DESK_MAC_STATES: readonly ['on', 'locked', 'sleeping', 'paused'];
+export type DeskMacState = (typeof DESK_MAC_STATES)[number];
+/**
+ * An app on the desk. `label` is at most 24 letters, digits, spaces and dots;
+ * site-api turns anything else into "something else". `icon` is the
+ * lowercase hex sha256 of a PNG (at most 128 px a side) already uploaded to
+ * deskIconPath(icon), or null.
+ */
+export interface DeskApp {
+    label: string;
+    icon: string | null;
+}
+/** Report body version the reporter sends; site-api rejects any other. */
+export declare const DESK_REPORT_VERSION = 1;
+/**
+ * Body of the owner-only, HMAC-signed POST to DESK_REPORT_PATH. The server
+ * ignores a report whose sentAt is not newer than the stored one, and
+ * computes expiry from its own clock plus ttl.
+ */
+export interface DeskReport {
+    v: typeof DESK_REPORT_VERSION;
+    /** Reporter clock, epoch milliseconds. Only used for ordering. */
+    sentAt: number;
+    mac: DeskMacState;
+    /** Seconds since the last keyboard or pointer input. */
+    idleSeconds: number;
+    /** True while an app holds a display-sleep assertion (video, a call). */
+    screenHeld: boolean;
+    /** Apps in use, most active first; `other` for an unlisted one. Never window titles or bundle ids. */
+    apps: DeskApp[];
+    /** IANA zone of the Mac, e.g. Australia/Melbourne. */
+    timeZone: string;
+    /** Seconds this report stays valid without a successor. */
+    ttl: number;
+}
+export declare const DESK_PRESENCE_STATES: readonly ['awake', 'idle', 'asleep', 'offline'];
+export type DeskPresenceState = (typeof DESK_PRESENCE_STATES)[number];
+export declare const DESK_SKIES: readonly ['clear', 'cloudy', 'fog', 'drizzle', 'rain', 'snow', 'storm'];
+export type Sky = (typeof DESK_SKIES)[number];
+export interface DeskPresence {
+    state: DeskPresenceState;
+    /** Empty unless awake or idle; an unlisted app reads "something else" with no icon. */
+    apps: DeskApp[];
+    /** Seconds of lease left when computed; null when offline or asleep. */
+    validFor: number | null;
+}
+export interface DeskPlace {
+    /** IANA zone the clock shows; the last pushed zone, or the default. */
+    timeZone: string;
+    /** City named by the zone; null when the zone names none (e.g. UTC). */
+    city: string | null;
+}
+export interface DeskWeather {
+    /** Degrees Celsius, rounded. */
+    temperature: number;
+    sky: Sky;
+    /** Daylight at the place right now. */
+    day: boolean;
+}
+/** Response of GET DESK_PATH. Fields are only ever added. */
+export interface DeskNow {
+    presence: DeskPresence;
+    place: DeskPlace;
+    /** Null when the weather source is unavailable. */
+    weather: DeskWeather | null;
+}
+/** Close code the live socket uses when it is full; poll instead. */
+export declare const DESK_LIVE_FULL_CLOSE_CODE = 1013;
+/**
+ * Message the live socket at DESK_LIVE_PATH sends on connect and whenever
+ * presence or place changes. Weather is not pushed; read it from DESK_PATH.
+ * The socket answers the text `ping` with `pong`. Fields are only ever added.
+ */
+export interface DeskLive {
+    presence: DeskPresence;
+    place: DeskPlace;
+}

package/dist/desk.js

@@ -0,0 +1,13 @@
+// src/desk.ts
+var DESK_MAC_STATES = ["on", "locked", "sleeping", "paused"];
+var DESK_REPORT_VERSION = 1;
+var DESK_PRESENCE_STATES = ["awake", "idle", "asleep", "offline"];
+var DESK_SKIES = ["clear", "cloudy", "fog", "drizzle", "rain", "snow", "storm"];
+var DESK_LIVE_FULL_CLOSE_CODE = 1013;
+export {
+  DESK_LIVE_FULL_CLOSE_CODE,
+  DESK_MAC_STATES,
+  DESK_PRESENCE_STATES,
+  DESK_REPORT_VERSION,
+  DESK_SKIES
+};

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './analytics';
 export * from './admin';
 export * from './comments';
 export * from './content';
+export * from './desk';
 export * from './instagram';
 export * from './listening';
 export * from './messages';

package/dist/index.js

@@ -36,6 +36,21 @@ var SITE_ANALYTICS_SURFACES = [
   "other"
 ];
 var SITE_ANALYTICS_REPORTS = ["overview", "pages", "clicks", "sources", "audience", "quality", "log", "visitor"];
+var SITE_EXPLORE_ENDPOINT = "/api/analytics/explore";
+var SITE_EXPLORE_VIEWS = ["traffic", "decoy"];
+var SITE_EXPLORE_RANGES = ["24h", "7d", "30d", "90d"];
+var SITE_EXPLORE_CLASSES = ["human", "bot", "owner", "all"];
+var SITE_EXPLORE_PARTS = ["summary", "panel", "clicks", "log"];
+var SITE_EXPLORE_DIMS = {
+  traffic: ["page", "section", "referrer", "channel", "utm", "country", "city", "device", "browser", "os", "visitor"],
+  decoy: ["client", "kind", "reason", "ua", "path", "network", "country"]
+};
+var SITE_EXPLORE_METRICS = {
+  traffic: ["visitors", "views", "engagement", "dwell"],
+  decoy: ["hits", "clients", "networks", "named"]
+};
+var SITE_EXPLORE_PANEL_LIMIT = 100;
+var SITE_EXPLORE_EMPTY = "(none)";
 // src/admin.ts
 var ADMIN_COMMENT_REJECT_REASONS = ["spam", "promotional", "abuse", "off_topic", "personal_info"];
 var ADMIN_ACTIVITY_EVENTS = [
@@ -145,6 +160,12 @@ function parsePostLocaleTag(tagName) {
   }
   return canonicalSlug ? { locale, canonicalSlug } : { locale };
 }
+// src/desk.ts
+var DESK_MAC_STATES = ["on", "locked", "sleeping", "paused"];
+var DESK_REPORT_VERSION = 1;
+var DESK_PRESENCE_STATES = ["awake", "idle", "asleep", "offline"];
+var DESK_SKIES = ["clear", "cloudy", "fog", "drizzle", "rain", "snow", "storm"];
+var DESK_LIVE_FULL_CLOSE_CODE = 1013;
 // src/messages.ts
 var MESSAGE_LOCALES = ["zh", "en"];
 var MESSAGE_MIN_BODY_LENGTH = 2;
@@ -205,6 +226,13 @@ var MOOD_SEARCH_PATH = "/v2/mood/search";
 var MOOD_IMAGE_PROXY_BASE_PATH = "/v2/images";
 var MOOD_MEDIA_PROXY_BASE_PATH = "/v2/media";
 var LISTENING_PATH = "/v2/listening";
+var DESK_PATH = "/v2/desk";
+var DESK_LIVE_PATH = "/v2/desk/live";
+var DESK_REPORT_PATH = "/v2/desk/report";
+var DESK_ICONS_PATH = "/v2/desk/icons";
+function deskIconPath(hash) {
+  return `${DESK_ICONS_PATH}/${hash}`;
+}
 var INSTAGRAM_PROFILE_PATH = "/v2/instagram";
 var INSTAGRAM_AVATAR_PATH = "/v2/instagram/avatar";
 var COMMENTS_PATH = "/v2/comments";
@@ -317,6 +345,15 @@ export {
   CONTENT_DOCUMENT_SOURCES,
   DEFAULT_COMMENT_POLICY,
   DEFAULT_REACTION_EMOJI,
+  DESK_ICONS_PATH,
+  DESK_LIVE_FULL_CLOSE_CODE,
+  DESK_LIVE_PATH,
+  DESK_MAC_STATES,
+  DESK_PATH,
+  DESK_PRESENCE_STATES,
+  DESK_REPORT_PATH,
+  DESK_REPORT_VERSION,
+  DESK_SKIES,
   EVENT_STATUSES,
   GHOST_WEBHOOK_PATH,
   HEALTH_PATH,
@@ -386,6 +423,15 @@ export {
   SITE_ANALYTICS_REPORT_ENDPOINT,
   SITE_ANALYTICS_SESSION_IDLE_MS,
   SITE_ANALYTICS_SURFACES,
+  SITE_EXPLORE_CLASSES,
+  SITE_EXPLORE_DIMS,
+  SITE_EXPLORE_EMPTY,
+  SITE_EXPLORE_ENDPOINT,
+  SITE_EXPLORE_METRICS,
+  SITE_EXPLORE_PANEL_LIMIT,
+  SITE_EXPLORE_PARTS,
+  SITE_EXPLORE_RANGES,
+  SITE_EXPLORE_VIEWS,
   SUBSCRIPTION_SOURCES,
   TELEGRAM_OPS_BASE_PATH,
   TELEGRAM_OPS_BROADCASTS_PATH,
@@ -407,6 +453,7 @@ export {
   avatarClass,
   commentAnchorToken,
   commentPolicyFromTags,
+  deskIconPath,
   isAvatarSeed,
   parsePostLocaleTag,
   seedInClass,

package/dist/routes.d.ts

@@ -12,6 +12,13 @@ export declare const MOOD_SEARCH_PATH: '/v2/mood/search';
 export declare const MOOD_IMAGE_PROXY_BASE_PATH: '/v2/images';
 export declare const MOOD_MEDIA_PROXY_BASE_PATH: '/v2/media';
 export declare const LISTENING_PATH: '/v2/listening';
+export declare const DESK_PATH: '/v2/desk';
+/** WebSocket upgrade; the server pushes DeskLive messages. */
+export declare const DESK_LIVE_PATH: '/v2/desk/live';
+export declare const DESK_REPORT_PATH: '/v2/desk/report';
+/** PUT (owner-signed) and GET an app icon PNG by its sha256: `${DESK_ICONS_PATH}/<hash>`. */
+export declare const DESK_ICONS_PATH: '/v2/desk/icons';
+export declare function deskIconPath(hash: string): string;
 export declare const INSTAGRAM_PROFILE_PATH: '/v2/instagram';
 export declare const INSTAGRAM_AVATAR_PATH: '/v2/instagram/avatar';
 export declare const COMMENTS_PATH: '/v2/comments';

package/dist/routes.js

@@ -13,6 +13,13 @@ var MOOD_SEARCH_PATH = "/v2/mood/search";
 var MOOD_IMAGE_PROXY_BASE_PATH = "/v2/images";
 var MOOD_MEDIA_PROXY_BASE_PATH = "/v2/media";
 var LISTENING_PATH = "/v2/listening";
+var DESK_PATH = "/v2/desk";
+var DESK_LIVE_PATH = "/v2/desk/live";
+var DESK_REPORT_PATH = "/v2/desk/report";
+var DESK_ICONS_PATH = "/v2/desk/icons";
+function deskIconPath(hash) {
+  return `${DESK_ICONS_PATH}/${hash}`;
+}
 var INSTAGRAM_PROFILE_PATH = "/v2/instagram";
 var INSTAGRAM_AVATAR_PATH = "/v2/instagram/avatar";
 var COMMENTS_PATH = "/v2/comments";
@@ -45,6 +52,10 @@ export {
   API_PREFIX,
   COMMENTS_PATH,
   COMMENT_PATH_PREFIX,
+  DESK_ICONS_PATH,
+  DESK_LIVE_PATH,
+  DESK_PATH,
+  DESK_REPORT_PATH,
   GHOST_WEBHOOK_PATH,
   HEALTH_PATH,
   INSTAGRAM_AVATAR_PATH,
@@ -81,5 +92,6 @@ export {
   READER_PREFERENCES_PATH,
   READER_RESEND_PATH,
   READER_VERIFY_PATH,
-  TELEGRAM_WEBHOOK_PATH
+  TELEGRAM_WEBHOOK_PATH,
+  deskIconPath
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/contracts",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,
@@ -48,6 +48,11 @@
       "import": "./dist/content.js",
       "default": "./dist/content.js"
     },
+    "./desk": {
+      "types": "./dist/desk.d.ts",
+      "import": "./dist/desk.js",
+      "default": "./dist/desk.js"
+    },
     "./instagram": {
       "types": "./dist/instagram.d.ts",
       "import": "./dist/instagram.js",