@netgreener/runtime 0.1.0

package/dist/runtimeHealth.js

@@ -0,0 +1,121 @@
+/**
+ * Runtime / export health (N6 / CAP-R5 honesty).
+ *
+ * Additive ``runtime_health_v0`` twin of Python ``netgreener.runtime_health``.
+ * Does not change upload defaults or invent collector spool metrics.
+ */
+const state = {
+    hooksActive: false,
+    processKind: 'process',
+    bootstrap: 'node_runtime_v0',
+    codes: [],
+    exportMode: 'direct',
+    exportAttempts: 0,
+    exportOk: 0,
+    exportFail: 0,
+    exportSkippedInFlight: 0,
+    lastError: null,
+};
+export function _resetRuntimeHealthForTests() {
+    state.hooksActive = false;
+    state.processKind = 'process';
+    state.bootstrap = 'node_runtime_v0';
+    state.codes = [];
+    state.exportMode = 'direct';
+    state.exportAttempts = 0;
+    state.exportOk = 0;
+    state.exportFail = 0;
+    state.exportSkippedInFlight = 0;
+    state.lastError = null;
+}
+export function markHooksActive(opts) {
+    state.hooksActive = true;
+    if (opts?.processKind)
+        state.processKind = opts.processKind;
+    if (opts?.exportMode)
+        state.exportMode = opts.exportMode;
+}
+export function noteExportMode(mode) {
+    state.exportMode = mode;
+}
+export function noteFlushSkippedInFlight() {
+    state.exportSkippedInFlight += 1;
+}
+export function noteExportAttempt(mode) {
+    state.exportMode = mode;
+    state.exportAttempts += 1;
+}
+export function noteExportResult(ok, error) {
+    if (ok) {
+        state.exportOk += 1;
+        state.lastError = null;
+        state.codes = state.codes.filter((c) => c !== 'export_fail');
+    }
+    else {
+        state.exportFail += 1;
+        state.lastError = error || 'export_failed';
+        if (!state.codes.includes('export_fail'))
+            state.codes.push('export_fail');
+    }
+}
+function collectorModeFromEnv() {
+    const raw = String(process.env.NETGREENER_COLLECTOR_MODE || '')
+        .trim()
+        .toLowerCase();
+    return raw || null;
+}
+export function buildRuntimeHealthV0() {
+    const failRate = state.exportAttempts > 0 ? state.exportFail / state.exportAttempts : 0;
+    let status = 'unknown';
+    const codes = [...state.codes];
+    const remediation = [];
+    if (!state.hooksActive) {
+        status = 'unknown';
+    }
+    else if (state.exportFail > 0 && failRate >= 0.5) {
+        status = 'conflict';
+        remediation.push('Check NETGREENER_API_URL / NETGREENER_TOKEN (direct) or NETGREENER_COLLECTOR_ENDPOINT (collector).');
+    }
+    else if (state.exportFail > 0 || state.exportSkippedInFlight > 0) {
+        status = 'degraded';
+        if (state.exportSkippedInFlight > 0) {
+            codes.push('export_skipped_in_flight');
+            remediation.push('A flush was skipped while another was in flight — window data is retried on failure merge; reduce flush contention if drops grow.');
+        }
+        if (state.exportFail > 0) {
+            remediation.push('Inspect prior export errors; failed windows are restored into the aggregator for retry.');
+        }
+    }
+    else if (state.exportOk > 0 || state.hooksActive) {
+        status = 'ok';
+    }
+    let detail = 'Node Runtime hooks active.';
+    if (state.lastError) {
+        detail = `Last export error: ${state.lastError}`;
+    }
+    else if (state.exportSkippedInFlight > 0) {
+        detail = `Hooks active; ${state.exportSkippedInFlight} in-flight flush skip(s).`;
+    }
+    else if (status === 'ok') {
+        detail = 'Node Runtime hooks active; exports healthy.';
+    }
+    return {
+        schema_version: 1,
+        status,
+        codes: [...new Set(codes)],
+        detail,
+        remediation,
+        bootstrap: state.bootstrap,
+        hooks_active: state.hooksActive,
+        process_kind: state.processKind,
+        collector_mode: collectorModeFromEnv(),
+        export_mode: state.exportMode,
+        export_attempts: state.exportAttempts,
+        export_ok: state.exportOk,
+        export_fail: state.exportFail,
+        export_skipped_in_flight: state.exportSkippedInFlight,
+    };
+}
+export function mergeHealthIntoMetadata(meta, health = buildRuntimeHealthV0()) {
+    meta.runtime_health_v0 = health;
+}

package/dist/serverlessHints.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Serverless / thin-flush platform hints (N3 mode docs).
+ *
+ * Detection only — does **not** flip ``NETGREENER_EXPORT_MODE`` by itself.
+ * Long-running Node stays on default ``direct`` (or opt-in ``collector``).
+ * Callers set ``NETGREENER_EXPORT_MODE=thin`` or ``NETGREENER_FLUSH_MODE=thin``
+ * explicitly when a durable sibling collector is impossible.
+ */
+export type ServerlessPlatformSignal = 'aws_lambda' | 'azure_functions' | 'google_cloud_functions' | 'vercel' | 'netlify';
+export type ServerlessPlatformHint = {
+    /** True when any known serverless host signal is present. */
+    detected: boolean;
+    signals: ServerlessPlatformSignal[];
+    /**
+     * Suggested export mode when a sibling collector cannot run.
+     * Never applied automatically by this helper.
+     */
+    suggestedExportMode: 'thin' | null;
+    notes: string[];
+};
+/**
+ * Read well-known platform env vars. Additive / informational only.
+ */
+export declare function detectServerlessPlatformSignals(env?: NodeJS.ProcessEnv): ServerlessPlatformHint;
+/** True when ``NETGREENER_FLUSH_MODE`` requests thin (alias of export mode thin). */
+export declare function flushModeRequestsThin(env?: NodeJS.ProcessEnv): boolean;

package/dist/serverlessHints.js

@@ -0,0 +1,52 @@
+/**
+ * Serverless / thin-flush platform hints (N3 mode docs).
+ *
+ * Detection only — does **not** flip ``NETGREENER_EXPORT_MODE`` by itself.
+ * Long-running Node stays on default ``direct`` (or opt-in ``collector``).
+ * Callers set ``NETGREENER_EXPORT_MODE=thin`` or ``NETGREENER_FLUSH_MODE=thin``
+ * explicitly when a durable sibling collector is impossible.
+ */
+function present(env, key) {
+    return Boolean(String(env[key] || '').trim());
+}
+/**
+ * Read well-known platform env vars. Additive / informational only.
+ */
+export function detectServerlessPlatformSignals(env = process.env) {
+    const signals = [];
+    const notes = [];
+    if (present(env, 'AWS_LAMBDA_FUNCTION_NAME')) {
+        signals.push('aws_lambda');
+    }
+    if (present(env, 'FUNCTIONS_WORKER_RUNTIME') || present(env, 'AZURE_FUNCTIONS_ENVIRONMENT')) {
+        signals.push('azure_functions');
+    }
+    if (present(env, 'FUNCTION_TARGET') || present(env, 'FUNCTION_SIGNATURE_TYPE')) {
+        signals.push('google_cloud_functions');
+    }
+    if (env.VERCEL === '1' || present(env, 'VERCEL_ENV')) {
+        signals.push('vercel');
+    }
+    if (present(env, 'NETLIFY') || present(env, 'NETLIFY_DEV')) {
+        signals.push('netlify');
+    }
+    const unique = [...new Set(signals)];
+    const detected = unique.length > 0;
+    if (detected) {
+        notes.push('serverless host signal present; set NETGREENER_EXPORT_MODE=thin or NETGREENER_FLUSH_MODE=thin explicitly — auto-cutover is not applied');
+        notes.push('flush best-effort at invoke end (runtime.flush / shutdown); no durable sibling spool in thin mode');
+    }
+    return {
+        detected,
+        signals: unique,
+        suggestedExportMode: detected ? 'thin' : null,
+        notes,
+    };
+}
+/** True when ``NETGREENER_FLUSH_MODE`` requests thin (alias of export mode thin). */
+export function flushModeRequestsThin(env = process.env) {
+    const raw = String(env.NETGREENER_FLUSH_MODE || '')
+        .trim()
+        .toLowerCase();
+    return raw === 'thin';
+}

package/dist/tenantContext.d.ts

@@ -0,0 +1,78 @@
+/** Downstream B2B customer company id (not NetGreener org, not end-user). */
+export type TenantId = string;
+export type TenantContext = {
+    tenantId: TenantId;
+    tenantSource: string;
+    tenantLabel?: string;
+};
+/**
+ * Mutable ALS cell so ``setTenantContext`` (manual auth) updates the same
+ * object Express holds for finish/close after the request ALS exits.
+ */
+export type TenantStore = {
+    current: TenantContext | null;
+};
+export declare function normalizeTenantId(value: unknown): TenantId | null;
+export type TenantConfig = {
+    enabled: boolean;
+    source: string;
+    claim: string;
+    header: string;
+    pathRegex: string | null;
+    taskKwarg: string;
+    labelClaim: string | null;
+};
+export declare function loadTenantConfig(env?: NodeJS.ProcessEnv): TenantConfig;
+/**
+ * Build tenant config from effective RuntimeConfig (programmatic opts.config).
+ * Prefer this over ambient ``loadTenantConfig()`` when a runtime is already loaded.
+ */
+export declare function tenantConfigFromRuntime(config: {
+    tenantSource: string;
+    tenantClaim: string;
+    tenantHeader: string;
+    tenantPathRegex: string | null;
+    tenantTaskKwarg: string;
+    tenantLabelClaim: string | null;
+}): TenantConfig;
+export declare function resolveTenantFromHttpRequest(req: {
+    headers?: Record<string, unknown>;
+    path?: string;
+    url?: string;
+}, config: TenantConfig): TenantContext | null;
+/**
+ * Resolve tenant from queue job payload (Celery kwargs / BullMQ job.data).
+ * Requires ``NETGREENER_TENANT_SOURCE=task_kwarg``.
+ */
+export declare function resolveTenantFromTaskData(data: Record<string, unknown> | null | undefined, config: TenantConfig): TenantContext | null;
+export declare function runWithTenantContext<T>(ctx: TenantContext | null, fn: () => T): T;
+/**
+ * Enter a mutable tenant cell for the remainder of this async chain (Fastify
+ * ``onRequest`` → route). Prefer ``runWithTenantContext`` when the whole
+ * handler runs inside one callback (Express ``next``).
+ */
+export declare function enterTenantStore(ctx: TenantContext | null): TenantStore;
+/** Active mutable tenant cell for this async context (if any). */
+export declare function getTenantStore(): TenantStore | undefined;
+export declare function getTenantContext(): TenantContext | null;
+/**
+ * Bind tenant for the current request (e.g. after auth).
+ * Mutates the active store in place so finish/close still see the binding
+ * after the middleware ALS callback returns.
+ */
+export declare function setTenantContext(ctx: TenantContext): void;
+export declare function collectWindowTenantIds(runtimeV0?: {
+    by_tenant?: Record<string, unknown>;
+} | null, externalV0?: {
+    by_tenant?: Record<string, unknown>;
+} | null): Set<TenantId>;
+export declare function attachWindowTenantToRunContext(runContext: Record<string, unknown>, opts: {
+    runtimeV0?: {
+        by_tenant?: Record<string, unknown>;
+    } | null;
+    externalV0?: {
+        by_tenant?: Record<string, unknown>;
+    } | null;
+    tenantConfig: TenantConfig;
+    activeContext?: TenantContext | null;
+}): Record<string, unknown>;

package/dist/tenantContext.js

@@ -0,0 +1,226 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const TENANT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const storage = new AsyncLocalStorage();
+export function normalizeTenantId(value) {
+    if (value === null || value === undefined)
+        return null;
+    const cleaned = String(value).trim();
+    if (!cleaned || cleaned.includes('@'))
+        return null;
+    const clipped = cleaned.length > 128 ? cleaned.slice(0, 128) : cleaned;
+    return TENANT_ID_RE.test(clipped) ? clipped : null;
+}
+function tenantConfigFromSource(fields) {
+    const source = (fields.source || 'none').trim().toLowerCase();
+    const enabled = !['', 'none', 'off', '0', 'false'].includes(source);
+    return {
+        enabled,
+        source,
+        claim: (fields.claim || 'organization_id').trim(),
+        header: (fields.header || 'X-Organization-Id').trim(),
+        pathRegex: (fields.pathRegex || '').trim() || null,
+        taskKwarg: (fields.taskKwarg || 'organization_id').trim(),
+        labelClaim: (fields.labelClaim || '').trim() || null,
+    };
+}
+export function loadTenantConfig(env = process.env) {
+    return tenantConfigFromSource({
+        source: env.NETGREENER_TENANT_SOURCE || 'none',
+        claim: env.NETGREENER_TENANT_CLAIM || 'organization_id',
+        header: env.NETGREENER_TENANT_HEADER || 'X-Organization-Id',
+        pathRegex: (env.NETGREENER_TENANT_PATH_REGEX || '').trim() || null,
+        taskKwarg: env.NETGREENER_TENANT_TASK_KWARG || 'organization_id',
+        labelClaim: (env.NETGREENER_TENANT_LABEL_CLAIM || '').trim() || null,
+    });
+}
+/**
+ * Build tenant config from effective RuntimeConfig (programmatic opts.config).
+ * Prefer this over ambient ``loadTenantConfig()`` when a runtime is already loaded.
+ */
+export function tenantConfigFromRuntime(config) {
+    return tenantConfigFromSource({
+        source: config.tenantSource,
+        claim: config.tenantClaim,
+        header: config.tenantHeader,
+        pathRegex: config.tenantPathRegex,
+        taskKwarg: config.tenantTaskKwarg,
+        labelClaim: config.tenantLabelClaim,
+    });
+}
+function configuredTenantSourceLabel(config) {
+    if (!config.enabled)
+        return null;
+    if (config.source === 'jwt_claim')
+        return `jwt_claim:${config.claim}`;
+    if (config.source === 'header')
+        return `header:${config.header}`;
+    if (config.source === 'path_regex' && config.pathRegex)
+        return `path_regex:${config.pathRegex}`;
+    if (config.source === 'task_kwarg')
+        return `task_kwarg:${config.taskKwarg}`;
+    if (config.source === 'manual')
+        return 'manual';
+    return config.source;
+}
+function headerValue(req, name) {
+    const headers = req.headers || {};
+    const target = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== target)
+            continue;
+        if (Array.isArray(value))
+            return String(value[0] ?? '').trim() || null;
+        return String(value ?? '').trim() || null;
+    }
+    return null;
+}
+function jwtPayloadUnverified(authorization) {
+    if (!authorization)
+        return null;
+    const auth = authorization.trim();
+    if (!auth.toLowerCase().startsWith('bearer '))
+        return null;
+    const token = auth.slice(7).trim();
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return null;
+    try {
+        const segment = parts[1];
+        const pad = '='.repeat((4 - (segment.length % 4)) % 4);
+        const raw = Buffer.from(segment + pad, 'base64url').toString('utf8');
+        const payload = JSON.parse(raw);
+        return payload && typeof payload === 'object' ? payload : null;
+    }
+    catch {
+        return null;
+    }
+}
+function claimValue(payload, claim) {
+    if (claim in payload)
+        return payload[claim];
+    if (claim.includes('.')) {
+        let cur = payload;
+        for (const part of claim.split('.')) {
+            if (!cur || typeof cur !== 'object' || !(part in cur)) {
+                return null;
+            }
+            cur = cur[part];
+        }
+        return cur;
+    }
+    return null;
+}
+export function resolveTenantFromHttpRequest(req, config) {
+    if (!config.enabled || config.source === 'manual')
+        return null;
+    if (config.source === 'jwt_claim') {
+        const payload = jwtPayloadUnverified(headerValue(req, 'authorization'));
+        if (!payload)
+            return null;
+        const tenantId = normalizeTenantId(claimValue(payload, config.claim));
+        if (!tenantId)
+            return null;
+        const labelRaw = config.labelClaim ? claimValue(payload, config.labelClaim) : null;
+        return {
+            tenantId,
+            tenantSource: `jwt_claim:${config.claim}`,
+            ...(labelRaw != null ? { tenantLabel: String(labelRaw).slice(0, 128) } : {}),
+        };
+    }
+    if (config.source === 'header') {
+        const tenantId = normalizeTenantId(headerValue(req, config.header));
+        if (!tenantId)
+            return null;
+        return { tenantId, tenantSource: `header:${config.header}` };
+    }
+    if (config.source === 'path_regex' && config.pathRegex) {
+        const path = (req.path || req.url || '').split('?')[0] || '';
+        try {
+            const re = new RegExp(config.pathRegex);
+            const match = re.exec(path);
+            if (!match)
+                return null;
+            const captured = match[1] ?? match[0];
+            const tenantId = normalizeTenantId(captured);
+            if (!tenantId)
+                return null;
+            return { tenantId, tenantSource: `path_regex:${config.pathRegex}` };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve tenant from queue job payload (Celery kwargs / BullMQ job.data).
+ * Requires ``NETGREENER_TENANT_SOURCE=task_kwarg``.
+ */
+export function resolveTenantFromTaskData(data, config) {
+    if (!config.enabled || config.source !== 'task_kwarg')
+        return null;
+    const key = config.taskKwarg || 'organization_id';
+    const tenantId = normalizeTenantId((data || {})[key]);
+    if (!tenantId)
+        return null;
+    return { tenantId, tenantSource: `task_kwarg:${key}` };
+}
+export function runWithTenantContext(ctx, fn) {
+    return storage.run({ current: ctx }, fn);
+}
+/**
+ * Enter a mutable tenant cell for the remainder of this async chain (Fastify
+ * ``onRequest`` → route). Prefer ``runWithTenantContext`` when the whole
+ * handler runs inside one callback (Express ``next``).
+ */
+export function enterTenantStore(ctx) {
+    const store = { current: ctx };
+    storage.enterWith(store);
+    return store;
+}
+/** Active mutable tenant cell for this async context (if any). */
+export function getTenantStore() {
+    return storage.getStore();
+}
+export function getTenantContext() {
+    return storage.getStore()?.current ?? null;
+}
+/**
+ * Bind tenant for the current request (e.g. after auth).
+ * Mutates the active store in place so finish/close still see the binding
+ * after the middleware ALS callback returns.
+ */
+export function setTenantContext(ctx) {
+    const store = storage.getStore();
+    if (store) {
+        store.current = ctx;
+        return;
+    }
+    storage.enterWith({ current: ctx });
+}
+export function collectWindowTenantIds(runtimeV0, externalV0) {
+    const ids = new Set();
+    for (const block of [runtimeV0, externalV0]) {
+        if (!block?.by_tenant)
+            continue;
+        for (const key of Object.keys(block.by_tenant)) {
+            if (key)
+                ids.add(key);
+        }
+    }
+    return ids;
+}
+export function attachWindowTenantToRunContext(runContext, opts) {
+    const tenantIds = collectWindowTenantIds(opts.runtimeV0, opts.externalV0);
+    if (tenantIds.size !== 1)
+        return runContext;
+    const tenantId = [...tenantIds][0];
+    runContext.tenant_id = tenantId;
+    const source = configuredTenantSourceLabel(opts.tenantConfig) || opts.activeContext?.tenantSource;
+    if (source)
+        runContext.tenant_source = source;
+    const label = opts.activeContext?.tenantLabel;
+    if (label)
+        runContext.tenant_label = label;
+    return runContext;
+}

package/dist/tenantDefaults.d.ts

@@ -0,0 +1,9 @@
+/** Default tenant attribution fields for tests and partial RuntimeConfig mocks. */
+export declare const DEFAULT_TENANT_RUNTIME_FIELDS: {
+    readonly tenantSource: "none";
+    readonly tenantClaim: "organization_id";
+    readonly tenantHeader: "X-Organization-Id";
+    readonly tenantPathRegex: null;
+    readonly tenantTaskKwarg: "organization_id";
+    readonly tenantLabelClaim: null;
+};

package/dist/tenantDefaults.js

@@ -0,0 +1,9 @@
+/** Default tenant attribution fields for tests and partial RuntimeConfig mocks. */
+export const DEFAULT_TENANT_RUNTIME_FIELDS = {
+    tenantSource: 'none',
+    tenantClaim: 'organization_id',
+    tenantHeader: 'X-Organization-Id',
+    tenantPathRegex: null,
+    tenantTaskKwarg: 'organization_id',
+    tenantLabelClaim: null,
+};

package/dist/types.d.ts

@@ -0,0 +1,131 @@
+/** Shared shapes for NetGreener runtime session_metadata (Node emitter). */
+export type DurationMs = {
+    avg: number;
+    max: number;
+};
+export type ServiceRuntimeUnit = {
+    service_unit: string;
+    unit_type: string;
+    calls: number;
+    errors: number;
+    cpu_seconds_total: number;
+    energy_kwh: number;
+    carbon_g: number;
+    duration_ms: DurationMs;
+    peak_rss_kb_max?: number;
+    cpu_percent_hours?: number;
+    ram_gb_hours?: number;
+    process_gpu_hours?: number;
+};
+export type AllocationReconciliationV0 = {
+    schema_version: number;
+    window_energy_kwh: number;
+    allocated_energy_kwh: number;
+    residual_energy_kwh: number;
+    tolerance_kwh: number;
+    passed: boolean;
+    scope: string;
+    endpoint_capture_coverage: number | null;
+    capture_completeness: string;
+};
+/** Downstream B2B customer company id (not NetGreener org, not end-user). */
+export type TenantId = string;
+export type ServiceRuntimeTenantBucket = {
+    tenant_id: TenantId;
+    calls: number;
+    errors: number;
+    units: ServiceRuntimeUnit[];
+};
+export type ServiceRuntimeV0 = {
+    framework?: string | null;
+    collector: string;
+    window_seconds: number;
+    attribution: string;
+    accuracy: string;
+    units: ServiceRuntimeUnit[];
+    by_tenant?: Record<TenantId, ServiceRuntimeTenantBucket>;
+    allocation_reconciliation_v0?: AllocationReconciliationV0;
+};
+export type ExternalApiModelBucket = {
+    model: string;
+    calls: number;
+    errors: number;
+    calls_with_usage?: number;
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+};
+export type ExternalApiProvider = {
+    provider_key: string;
+    calls: number;
+    errors: number;
+    calls_with_usage?: number;
+    duration_ms_avg?: number;
+    hosts?: string[];
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    models?: string[];
+    by_model?: ExternalApiModelBucket[];
+};
+export type ExternalApiTenantBucket = {
+    tenant_id: TenantId;
+    calls: number;
+    errors: number;
+    providers: ExternalApiProvider[];
+};
+export type ExternalApiV0 = {
+    collector: string;
+    providers: ExternalApiProvider[];
+    by_service_unit?: Record<string, unknown>;
+    by_tenant?: Record<TenantId, ExternalApiTenantBucket>;
+};
+export type EvidenceMetric = {
+    metric: string;
+    grade: string;
+    reasons: string[];
+};
+export type EvidenceGrades = {
+    schema_version: number;
+    policy_version: string;
+    metrics: {
+        local_energy: EvidenceMetric;
+        local_carbon: EvidenceMetric;
+    };
+    combined_floor_grade: string;
+    notes?: string[];
+};
+export type MeasurementProvenance = {
+    cpu_source?: string;
+    memory_source?: string;
+    energy_model?: string;
+    gpu_scope?: string;
+    gpu_source?: string;
+    carbon_factor?: {
+        value: number | null;
+        unit?: string;
+        source?: string;
+    };
+    evidence_grades?: EvidenceGrades;
+    [key: string]: unknown;
+};
+export type RunContext = {
+    deploy_environment?: string;
+    client?: string;
+    release_tag?: string;
+    /** Downstream customer company org id when tenant attribution is enabled. */
+    tenant_id?: TenantId;
+    /** e.g. jwt_claim:organization_id */
+    tenant_source?: string;
+    /** Optional display label; not a billing key. */
+    tenant_label?: string;
+    [key: string]: unknown;
+};
+/** session_metadata fragment Node must be able to upload. */
+export type RuntimeSessionMetadata = {
+    run_context?: RunContext;
+    service_runtime_v0?: ServiceRuntimeV0;
+    external_api_v0?: ExternalApiV0;
+    measurement_provenance?: MeasurementProvenance;
+    [key: string]: unknown;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Shared shapes for NetGreener runtime session_metadata (Node emitter). */
+export {};

package/dist/uploader.d.ts

@@ -0,0 +1,23 @@
+import type { RuntimeConfig } from './config.js';
+import type { RuntimeSessionMetadata } from './types.js';
+export type RunSessionCreatePayload = {
+    project_id: number;
+    start_time: string;
+    end_time: string;
+    server_name?: string | null;
+    energy_kwh?: number;
+    runtime_window_id: string;
+    session_metadata: RuntimeSessionMetadata;
+};
+export type UploadResult = {
+    ok: true;
+    status: number;
+    body: unknown;
+    dryRun?: boolean;
+} | {
+    ok: false;
+    status?: number;
+    error: string;
+    body?: unknown;
+};
+export declare function uploadRunSession(config: RuntimeConfig, payload: RunSessionCreatePayload, fetchImpl?: typeof fetch): Promise<UploadResult>;