@nocville/node 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @nocville/node
 
-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.
+Node.js SDK for pushing status updates to Nocville.
+
+## Installation
+
+```bash
+npm install @nocville/node
+```
+
+## Usage
+
+```typescript
+import { NocvilleClient } from '@nocville/node';
+
+const client = new NocvilleClient({
+  apiKey: 'your-api-key',
+  serviceId: 'my-service',
+  // apiUrl defaults to https://nocville.com
+});
+
+// Push a status update
+const response = await client.pushStatus({
+  status: 'healthy',
+  mood: 'happy',
+  message: 'All systems operational',
+  metrics: {
+    cpu: 45,
+    memory: 60,
+    requests: 1250,
+  },
+});
+
+// Quick helpers
+await client.healthy('Everything is fine');
+await client.warning('High memory usage');
+await client.critical('Service down!');
+```
+
+## Configuration
+
+| Option       | Type    | Default                | Description                                 |
+| ------------ | ------- | ---------------------- | ------------------------------------------- |
+| `apiKey`     | string  | required               | Team API key for authentication             |
+| `apiUrl`     | string  | `https://nocville.com` | Nocville API URL (override for development) |
+| `serviceId`  | string  | required               | The service ID this client represents       |
+| `timeout`    | number  | 5000                   | Request timeout in milliseconds             |
+| `retries`    | number  | 3                      | Number of retry attempts on failure         |
+| `retryDelay` | number  | 1000                   | Base delay between retries in milliseconds  |
+| `debug`      | boolean | false                  | Enable debug logging                        |
+
+## Status Values
+
+- `healthy` - Service is operating normally
+- `warning` - Service has non-critical issues
+- `critical` - Service has critical issues
+- `unknown` - Service status cannot be determined
+
+## Mood Values
+
+- `happy` - NPC appears happy (typically for healthy status)
+- `concerned` - NPC appears concerned (typically for warning status)
+- `stressed` - NPC appears stressed (typically for critical status)
+- `idle` - NPC appears neutral (typically for unknown status)
+
+## License
+
+MIT

package/dist/cjs/index.js

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * Nocville Status Pusher SDK for Node.js
+ *
+ * @example
+ * ```typescript
+ * import { NocvilleClient } from '@nocville/node';
+ *
+ * const client = new NocvilleClient({
+ *   apiKey: 'your-api-key',
+ *   serviceId: 'my-service',
+ * });
+ *
+ * // Push a status update
+ * await client.pushStatus({
+ *   status: 'healthy',
+ *   mood: 'happy',
+ *   message: 'All systems operational',
+ *   metrics: {
+ *     cpu: 45,
+ *     memory: 60,
+ *     requests: 1250,
+ *   },
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NocvilleClient = void 0;
+class StatusPushError extends Error {
+    constructor(statusCode, body) {
+        super(`HTTP ${statusCode}: ${body}`);
+        this.statusCode = statusCode;
+    }
+}
+class NocvilleClient {
+    constructor(config) {
+        this.lastStatus = 'unknown';
+        this.lastMood = 'idle';
+        this.lastUpdate = 0;
+        this._links = [];
+        this._actions = [];
+        this._logBuffer = [];
+        this._heartbeatInterval = null;
+        this.config = {
+            apiUrl: 'https://nocville.com',
+            timeout: 5000,
+            retries: 3,
+            retryDelay: 1000,
+            debug: false,
+            ...config,
+        };
+        this.config.apiUrl = this.config.apiUrl.replace(/\/+$/, '');
+        if (!this.config.apiKey) {
+            throw new Error('apiKey is required');
+        }
+        if (!this.config.serviceId) {
+            throw new Error('serviceId is required');
+        }
+    }
+    /**
+     * Push a status update to the Nocville server
+     */
+    async pushStatus(update) {
+        const payload = {
+            serviceId: this.config.serviceId,
+            status: update.status,
+            mood: update.mood || this.moodFromStatus(update.status),
+            message: update.message,
+            metrics: update.metrics,
+        };
+        if (update.agentStats !== undefined)
+            payload.agentStats = update.agentStats;
+        if (update.appearance !== undefined)
+            payload.appearance = update.appearance;
+        if (update.name !== undefined)
+            payload.name = update.name;
+        if (update.archetype !== undefined)
+            payload.archetype = update.archetype;
+        if (update.subStatus !== undefined)
+            payload.subStatus = update.subStatus;
+        if (update.screenData !== undefined)
+            payload.screenData = update.screenData;
+        if (update.alertConfig !== undefined)
+            payload.alertConfig = update.alertConfig;
+        if (update.behavior !== undefined)
+            payload.behavior = update.behavior;
+        if (update.companion !== undefined)
+            payload.companion = update.companion;
+        if (update.offline !== undefined)
+            payload.offline = update.offline;
+        if (update.map !== undefined)
+            payload.map = update.map;
+        // Merge stored links/actions with per-call overrides
+        const links = update.links || (this._links.length > 0 ? this._links : undefined);
+        const actions = update.actions || (this._actions.length > 0 ? this._actions : undefined);
+        if (links)
+            payload.links = links;
+        if (actions)
+            payload.actions = actions;
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+            try {
+                if (attempt > 0) {
+                    const delay = this.config.retryDelay * Math.pow(2, attempt - 1);
+                    this.log(`Retry attempt ${attempt} after ${delay}ms`);
+                    await this.sleep(delay);
+                }
+                const response = await this.makeRequest(payload);
+                this.lastStatus = update.status;
+                this.lastMood = update.mood || this.moodFromStatus(update.status);
+                this.lastUpdate = Date.now();
+                return {
+                    success: true,
+                    timestamp: this.lastUpdate,
+                };
+            }
+            catch (error) {
+                lastError = error;
+                this.log(`Request failed: ${lastError.message}`);
+                if (lastError instanceof StatusPushError &&
+                    [400, 401, 403, 404].includes(lastError.statusCode))
+                    break;
+            }
+        }
+        return {
+            success: false,
+            timestamp: Date.now(),
+            error: lastError?.message || 'Unknown error',
+            statusCode: lastError instanceof StatusPushError ? lastError.statusCode : undefined,
+        };
+    }
+    /**
+     * Quick status helpers
+     */
+    async healthy(message, metrics) {
+        return this.pushStatus({ status: 'healthy', mood: 'happy', message, metrics });
+    }
+    async warning(message, metrics) {
+        return this.pushStatus({ status: 'warning', mood: 'concerned', message, metrics });
+    }
+    async critical(message, metrics) {
+        return this.pushStatus({ status: 'critical', mood: 'stressed', message, metrics });
+    }
+    /**
+     * Get the last known status
+     */
+    getLastStatus() {
+        return {
+            status: this.lastStatus,
+            timestamp: this.lastUpdate,
+        };
+    }
+    /**
+     * Push screen data for NPC display
+     */
+    async pushScreen(data) {
+        return this.pushStatus({
+            status: this.lastStatus,
+            mood: this.lastMood,
+            screenData: data,
+        });
+    }
+    /**
+     * Push metrics as a multi-metric gauge layout
+     */
+    async pushGauges(metrics) {
+        const screenData = {
+            layout: 'multi-metric',
+            values: Object.entries(metrics).map(([label, value]) => ({
+                label,
+                value: String(value),
+            })),
+        };
+        return this.pushScreen(screenData);
+    }
+    /**
+     * Push a ticker-style screen display
+     */
+    async pushTicker(values) {
+        const screenData = {
+            layout: 'ticker',
+            values: values.map((v) => ({
+                label: v.label,
+                value: v.value,
+                trend: v.trend,
+            })),
+        };
+        return this.pushScreen(screenData);
+    }
+    /**
+     * Push a log line to a rolling terminal display (keeps last 20 lines)
+     */
+    async pushLogLine(line) {
+        this._logBuffer.push(line);
+        if (this._logBuffer.length > 20) {
+            this._logBuffer = this._logBuffer.slice(-20);
+        }
+        const screenData = {
+            layout: 'log-terminal',
+            values: [{ label: 'log', value: this._logBuffer.join('\n') }],
+        };
+        return this.pushScreen(screenData);
+    }
+    /**
+     * Start a heartbeat that periodically pushes the current status
+     */
+    startHeartbeat(intervalMs = 30000) {
+        this.stopHeartbeat();
+        this._heartbeatInterval = setInterval(() => {
+            this.pushStatus({
+                status: this.lastStatus,
+                mood: this.lastMood,
+            }).catch((err) => this.log(`Heartbeat push failed: ${err}`));
+        }, intervalMs);
+    }
+    /**
+     * Stop the heartbeat interval
+     */
+    stopHeartbeat() {
+        if (this._heartbeatInterval !== null) {
+            clearInterval(this._heartbeatInterval);
+            this._heartbeatInterval = null;
+        }
+    }
+    /**
+     * Set links to be included in every subsequent push
+     */
+    setLinks(links) {
+        this._links = links;
+    }
+    /**
+     * Set actions to be included in every subsequent push
+     */
+    setActions(actions) {
+        this._actions = actions;
+    }
+    /**
+     * Open an incident for this service
+     */
+    async openIncident(title, severity = 'critical') {
+        const url = `${this.config.apiUrl}/api/v1/teams/_/incidents/sdk`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({
+                    serviceId: this.config.serviceId,
+                    title,
+                    severity,
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            const result = (await response.json());
+            this.log(`Incident opened: ${result.data.id}`);
+            return { id: result.data.id };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Resolve an incident by ID
+     */
+    async resolveIncident(incidentId) {
+        const url = `${this.config.apiUrl}/api/v1/teams/_/incidents/${incidentId}/sdk`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'PATCH',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({ status: 'resolved' }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            this.log(`Incident resolved: ${incidentId}`);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Add a note to an incident timeline
+     */
+    async addIncidentNote(incidentId, note) {
+        const url = `${this.config.apiUrl}/api/v1/teams/_/incidents/${incidentId}/events/sdk`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({
+                    type: 'note',
+                    data: { note },
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            this.log(`Note added to incident: ${incidentId}`);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    moodFromStatus(status) {
+        switch (status) {
+            case 'healthy':
+                return 'happy';
+            case 'warning':
+                return 'concerned';
+            case 'critical':
+                return 'stressed';
+            default:
+                return 'idle';
+        }
+    }
+    async makeRequest(payload) {
+        const url = `${this.config.apiUrl}/api/v1/status`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new StatusPushError(response.status, errorText);
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    log(message) {
+        if (this.config.debug) {
+            console.log(`[nocville] ${message}`);
+        }
+    }
+}
+exports.NocvilleClient = NocvilleClient;
+// Default export for convenience
+exports.default = NocvilleClient;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Nocville Status Pusher SDK for Node.js
+ *
+ * @example
+ * ```typescript
+ * import { NocvilleClient } from '@nocville/node';
+ *
+ * const client = new NocvilleClient({
+ *   apiKey: 'your-api-key',
+ *   serviceId: 'my-service',
+ * });
+ *
+ * // Push a status update
+ * await client.pushStatus({
+ *   status: 'healthy',
+ *   mood: 'happy',
+ *   message: 'All systems operational',
+ *   metrics: {
+ *     cpu: 45,
+ *     memory: 60,
+ *     requests: 1250,
+ *   },
+ * });
+ * ```
+ */
+export type Status = 'healthy' | 'warning' | 'critical' | 'unknown';
+export type Mood = 'happy' | 'concerned' | 'stressed' | 'idle';
+export interface ScreenValue {
+    label: string;
+    value: string;
+    color?: string;
+    trend?: 'up' | 'down' | 'flat';
+    sparkline?: number[];
+}
+export interface ScreenData {
+    layout: string;
+    values: ScreenValue[];
+}
+export interface NPCLink {
+    label: string;
+    url: string;
+    icon?: string;
+}
+export interface NPCAction {
+    id: string;
+    label: string;
+    type: 'confirm' | 'webhook' | 'link';
+    url?: string;
+    requiresAdmin?: boolean;
+}
+export interface AlertConfig {
+    notifyOnCritical?: boolean;
+    soundEnabled?: boolean;
+    autoAcknowledgeAfter?: number;
+    heartbeatInterval?: number;
+}
+/** Companion pixel-screen types the server knows how to render. */
+export type CompanionScreenType = 'log-terminal' | 'ticker-tape' | 'crt-monitor' | 'dashboard-wall' | 'status-light' | 'gauge-panel' | 'web-view' | 'desk-sign' | 'commit-board' | 'welcome-sign';
+export type BehaviorActivity = 'busy' | 'idle' | 'waiting' | 'critical';
+export type BehaviorIdle = 'seek-lounge' | 'seek-desk' | 'wander' | 'stay';
+export type BehaviorPose = 'sit' | 'sleep' | 'stand';
+export type CompanionPlacement = 'adjacent-wall' | 'on-desk' | 'freestanding';
+export interface BehaviorPatrol {
+    /** [minMinutes, maxMinutes] between patrols */
+    everyMinutes: [number, number];
+    /** Number of stops per patrol */
+    stops?: number;
+}
+export type BehaviorHome = {
+    near: 'entrance' | 'center';
+} | {
+    x: number;
+    y: number;
+};
+/**
+ * Behavior hints that steer how the NPC moves and idles in the world.
+ * All fields optional; the server merges hints → archetype defaults → global defaults.
+ */
+export interface BehaviorHints {
+    /** Schema version */
+    v?: number;
+    /** Explicit activity override; else derived server-side */
+    activity?: BehaviorActivity;
+    /** Where to go when idle */
+    idle?: BehaviorIdle;
+    /** Where to go when busy: 'seek-desk' | 'wander' | 'stay' | 'seek-object:<category|catalogId>' */
+    busy?: string;
+    /** Pose to strike when idle */
+    idlePose?: BehaviorPose;
+    /** Emote to show while waiting (e.g. 'raised-hand') */
+    waitingEmote?: string;
+    /** Greet players on first appearance */
+    greetPlayers?: boolean;
+    /** Patrol schedule */
+    patrol?: BehaviorPatrol;
+    /** Home base to return to */
+    home?: BehaviorHome;
+}
+export interface CompanionSize {
+    /** Width in tiles (1-6) */
+    w: number;
+    /** Height in tiles (1-6) */
+    h: number;
+}
+/** A companion pixel-art object that spawns alongside the NPC. */
+export interface CompanionSpec {
+    screenType: CompanionScreenType;
+    size?: CompanionSize;
+    placement: CompanionPlacement;
+    label?: string;
+}
+export interface NocvilleConfig {
+    /** Nocville API URL (default: https://nocville.com) */
+    apiUrl?: string;
+    /** Team API key for authentication */
+    apiKey: string;
+    /** The service ID this client represents */
+    serviceId: string;
+    /** Request timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Number of retry attempts on failure (default: 3) */
+    retries?: number;
+    /** Base delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+export interface AgentStats {
+    filesChanged: number;
+    insertions: number;
+    deletions: number;
+    lastFiles: string[];
+    /** Reserved for future usage reporting; the hook collector does not compute these. */
+    tokensIn?: number;
+    tokensOut?: number;
+    costUsd?: number;
+}
+export interface StatusUpdate {
+    agentStats?: AgentStats;
+    /** The current status of the service */
+    status: Status;
+    /** The mood/emotional state for NPC visualization */
+    mood?: Mood;
+    /** Optional message to display */
+    message?: string;
+    /** Friendly display name shown on the NPC banner (falls back to serviceId). */
+    name?: string;
+    /** Optional metrics to track */
+    metrics?: Record<string, number | string>;
+    /** NPC archetype identifier */
+    archetype?: string;
+    /** Sub-status for more granular state */
+    subStatus?: string;
+    /** Screen data for NPC display */
+    screenData?: ScreenData;
+    /** Links associated with this NPC */
+    links?: NPCLink[];
+    /** Actions available on this NPC */
+    actions?: NPCAction[];
+    /** Alert configuration */
+    alertConfig?: AlertConfig;
+    /** Behavior hints steering NPC movement/idle/busy */
+    behavior?: BehaviorHints;
+    /** Companion pixel-art object spec */
+    companion?: CompanionSpec;
+    /**
+     * Appearance hint. `family` dresses an ai-agent NPC in its branded look
+     * ('claude' = terracotta Claude tee, 'codex' = black OpenAI tee).
+     */
+    appearance?: {
+        family?: 'claude' | 'codex' | 'gemini' | 'cursor';
+    };
+    /** Clean-shutdown sentinel — prompts the server to despawn the NPC promptly */
+    offline?: boolean;
+    /**
+     * Target map for this push — a map id (e.g. `map_abc123`) or a map name
+     * (case-insensitive). Omit to target the team's default map.
+     */
+    map?: string;
+}
+export interface PushResponse {
+    /** HTTP status on failure, absent for network errors. */
+    statusCode?: number;
+    success: boolean;
+    timestamp: number;
+    error?: string;
+}
+export declare class NocvilleClient {
+    private config;
+    private lastStatus;
+    private lastMood;
+    private lastUpdate;
+    private _links;
+    private _actions;
+    private _logBuffer;
+    private _heartbeatInterval;
+    constructor(config: NocvilleConfig);
+    /**
+     * Push a status update to the Nocville server
+     */
+    pushStatus(update: StatusUpdate): Promise<PushResponse>;
+    /**
+     * Quick status helpers
+     */
+    healthy(message?: string, metrics?: Record<string, number | string>): Promise<PushResponse>;
+    warning(message?: string, metrics?: Record<string, number | string>): Promise<PushResponse>;
+    critical(message?: string, metrics?: Record<string, number | string>): Promise<PushResponse>;
+    /**
+     * Get the last known status
+     */
+    getLastStatus(): {
+        status: Status;
+        timestamp: number;
+    };
+    /**
+     * Push screen data for NPC display
+     */
+    pushScreen(data: ScreenData): Promise<PushResponse>;
+    /**
+     * Push metrics as a multi-metric gauge layout
+     */
+    pushGauges(metrics: Record<string, number>): Promise<PushResponse>;
+    /**
+     * Push a ticker-style screen display
+     */
+    pushTicker(values: Array<{
+        label: string;
+        value: string;
+        trend?: 'up' | 'down' | 'flat';
+    }>): Promise<PushResponse>;
+    /**
+     * Push a log line to a rolling terminal display (keeps last 20 lines)
+     */
+    pushLogLine(line: string): Promise<PushResponse>;
+    /**
+     * Start a heartbeat that periodically pushes the current status
+     */
+    startHeartbeat(intervalMs?: number): void;
+    /**
+     * Stop the heartbeat interval
+     */
+    stopHeartbeat(): void;
+    /**
+     * Set links to be included in every subsequent push
+     */
+    setLinks(links: NPCLink[]): void;
+    /**
+     * Set actions to be included in every subsequent push
+     */
+    setActions(actions: NPCAction[]): void;
+    /**
+     * Open an incident for this service
+     */
+    openIncident(title: string, severity?: 'minor' | 'major' | 'critical'): Promise<{
+        id: string;
+    }>;
+    /**
+     * Resolve an incident by ID
+     */
+    resolveIncident(incidentId: string): Promise<void>;
+    /**
+     * Add a note to an incident timeline
+     */
+    addIncidentNote(incidentId: string, note: string): Promise<void>;
+    private moodFromStatus;
+    private makeRequest;
+    private sleep;
+    private log;
+}
+export default NocvilleClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,369 @@
+/**
+ * Nocville Status Pusher SDK for Node.js
+ *
+ * @example
+ * ```typescript
+ * import { NocvilleClient } from '@nocville/node';
+ *
+ * const client = new NocvilleClient({
+ *   apiKey: 'your-api-key',
+ *   serviceId: 'my-service',
+ * });
+ *
+ * // Push a status update
+ * await client.pushStatus({
+ *   status: 'healthy',
+ *   mood: 'happy',
+ *   message: 'All systems operational',
+ *   metrics: {
+ *     cpu: 45,
+ *     memory: 60,
+ *     requests: 1250,
+ *   },
+ * });
+ * ```
+ */
+class StatusPushError extends Error {
+    constructor(statusCode, body) {
+        super(`HTTP ${statusCode}: ${body}`);
+        this.statusCode = statusCode;
+    }
+}
+export class NocvilleClient {
+    constructor(config) {
+        this.lastStatus = 'unknown';
+        this.lastMood = 'idle';
+        this.lastUpdate = 0;
+        this._links = [];
+        this._actions = [];
+        this._logBuffer = [];
+        this._heartbeatInterval = null;
+        this.config = {
+            apiUrl: 'https://nocville.com',
+            timeout: 5000,
+            retries: 3,
+            retryDelay: 1000,
+            debug: false,
+            ...config,
+        };
+        this.config.apiUrl = this.config.apiUrl.replace(/\/+$/, '');
+        if (!this.config.apiKey) {
+            throw new Error('apiKey is required');
+        }
+        if (!this.config.serviceId) {
+            throw new Error('serviceId is required');
+        }
+    }
+    /**
+     * Push a status update to the Nocville server
+     */
+    async pushStatus(update) {
+        const payload = {
+            serviceId: this.config.serviceId,
+            status: update.status,
+            mood: update.mood || this.moodFromStatus(update.status),
+            message: update.message,
+            metrics: update.metrics,
+        };
+        if (update.agentStats !== undefined)
+            payload.agentStats = update.agentStats;
+        if (update.appearance !== undefined)
+            payload.appearance = update.appearance;
+        if (update.name !== undefined)
+            payload.name = update.name;
+        if (update.archetype !== undefined)
+            payload.archetype = update.archetype;
+        if (update.subStatus !== undefined)
+            payload.subStatus = update.subStatus;
+        if (update.screenData !== undefined)
+            payload.screenData = update.screenData;
+        if (update.alertConfig !== undefined)
+            payload.alertConfig = update.alertConfig;
+        if (update.behavior !== undefined)
+            payload.behavior = update.behavior;
+        if (update.companion !== undefined)
+            payload.companion = update.companion;
+        if (update.offline !== undefined)
+            payload.offline = update.offline;
+        if (update.map !== undefined)
+            payload.map = update.map;
+        // Merge stored links/actions with per-call overrides
+        const links = update.links || (this._links.length > 0 ? this._links : undefined);
+        const actions = update.actions || (this._actions.length > 0 ? this._actions : undefined);
+        if (links)
+            payload.links = links;
+        if (actions)
+            payload.actions = actions;
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+            try {
+                if (attempt > 0) {
+                    const delay = this.config.retryDelay * Math.pow(2, attempt - 1);
+                    this.log(`Retry attempt ${attempt} after ${delay}ms`);
+                    await this.sleep(delay);
+                }
+                const response = await this.makeRequest(payload);
+                this.lastStatus = update.status;
+                this.lastMood = update.mood || this.moodFromStatus(update.status);
+                this.lastUpdate = Date.now();
+                return {
+                    success: true,
+                    timestamp: this.lastUpdate,
+                };
+            }
+            catch (error) {
+                lastError = error;
+                this.log(`Request failed: ${lastError.message}`);
+                if (lastError instanceof StatusPushError &&
+                    [400, 401, 403, 404].includes(lastError.statusCode))
+                    break;
+            }
+        }
+        return {
+            success: false,
+            timestamp: Date.now(),
+            error: lastError?.message || 'Unknown error',
+            statusCode: lastError instanceof StatusPushError ? lastError.statusCode : undefined,
+        };
+    }
+    /**
+     * Quick status helpers
+     */
+    async healthy(message, metrics) {
+        return this.pushStatus({ status: 'healthy', mood: 'happy', message, metrics });
+    }
+    async warning(message, metrics) {
+        return this.pushStatus({ status: 'warning', mood: 'concerned', message, metrics });
+    }
+    async critical(message, metrics) {
+        return this.pushStatus({ status: 'critical', mood: 'stressed', message, metrics });
+    }
+    /**
+     * Get the last known status
+     */
+    getLastStatus() {
+        return {
+            status: this.lastStatus,
+            timestamp: this.lastUpdate,
+        };
+    }
+    /**
+     * Push screen data for NPC display
+     */
+    async pushScreen(data) {
+        return this.pushStatus({
+            status: this.lastStatus,
+            mood: this.lastMood,
+            screenData: data,
+        });
+    }
+    /**
+     * Push metrics as a multi-metric gauge layout
+     */
+    async pushGauges(metrics) {
+        const screenData = {
+            layout: 'multi-metric',
+            values: Object.entries(metrics).map(([label, value]) => ({
+                label,
+                value: String(value),
+            })),
+        };
+        return this.pushScreen(screenData);
+    }
+    /**
+     * Push a ticker-style screen display
+     */
+    async pushTicker(values) {
+        const screenData = {
+            layout: 'ticker',
+            values: values.map((v) => ({
+                label: v.label,
+                value: v.value,
+                trend: v.trend,
+            })),
+        };
+        return this.pushScreen(screenData);
+    }
+    /**
+     * Push a log line to a rolling terminal display (keeps last 20 lines)
+     */
+    async pushLogLine(line) {
+        this._logBuffer.push(line);
+        if (this._logBuffer.length > 20) {
+            this._logBuffer = this._logBuffer.slice(-20);
+        }
+        const screenData = {
+            layout: 'log-terminal',
+            values: [{ label: 'log', value: this._logBuffer.join('\n') }],
+        };
+        return this.pushScreen(screenData);
+    }
+    /**
+     * Start a heartbeat that periodically pushes the current status
+     */
+    startHeartbeat(intervalMs = 30000) {
+        this.stopHeartbeat();
+        this._heartbeatInterval = setInterval(() => {
+            this.pushStatus({
+                status: this.lastStatus,
+                mood: this.lastMood,
+            }).catch((err) => this.log(`Heartbeat push failed: ${err}`));
+        }, intervalMs);
+    }
+    /**
+     * Stop the heartbeat interval
+     */
+    stopHeartbeat() {
+        if (this._heartbeatInterval !== null) {
+            clearInterval(this._heartbeatInterval);
+            this._heartbeatInterval = null;
+        }
+    }
+    /**
+     * Set links to be included in every subsequent push
+     */
+    setLinks(links) {
+        this._links = links;
+    }
+    /**
+     * Set actions to be included in every subsequent push
+     */
+    setActions(actions) {
+        this._actions = actions;
+    }
+    /**
+     * Open an incident for this service
+     */
+    async openIncident(title, severity = 'critical') {
+        const url = `${this.config.apiUrl}/api/v1/teams/_/incidents/sdk`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({
+                    serviceId: this.config.serviceId,
+                    title,
+                    severity,
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            const result = (await response.json());
+            this.log(`Incident opened: ${result.data.id}`);
+            return { id: result.data.id };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Resolve an incident by ID
+     */
+    async resolveIncident(incidentId) {
+        const url = `${this.config.apiUrl}/api/v1/teams/_/incidents/${incidentId}/sdk`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'PATCH',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({ status: 'resolved' }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            this.log(`Incident resolved: ${incidentId}`);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Add a note to an incident timeline
+     */
+    async addIncidentNote(incidentId, note) {
+        const url = `${this.config.apiUrl}/api/v1/teams/_/incidents/${incidentId}/events/sdk`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({
+                    type: 'note',
+                    data: { note },
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            this.log(`Note added to incident: ${incidentId}`);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    moodFromStatus(status) {
+        switch (status) {
+            case 'healthy':
+                return 'happy';
+            case 'warning':
+                return 'concerned';
+            case 'critical':
+                return 'stressed';
+            default:
+                return 'idle';
+        }
+    }
+    async makeRequest(payload) {
+        const url = `${this.config.apiUrl}/api/v1/status`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new StatusPushError(response.status, errorText);
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    log(message) {
+        if (this.config.debug) {
+            console.log(`[nocville] ${message}`);
+        }
+    }
+}
+// Default export for convenience
+export default NocvilleClient;

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@nocville/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "Nocville Status Pusher SDK for Node.js",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.3.2",
+    "vitest": "^3.2.6"
+  },
+  "keywords": [
+    "nocville",
+    "monitoring",
+    "noc",
+    "status"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marshmansf/nocville.git",
+    "directory": "libs/nocville-node"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }))\"",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }