@xerg/schemas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xerg
+
+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

@@ -0,0 +1,72 @@
+# @xerg/schemas
+
+Versioned TypeScript wire types for Xerg audit payloads, findings, comparisons, and recommendations.
+
+## What it is
+
+`@xerg/schemas` defines the JSON contract shared between the Xerg CLI, the local audit engine, and any service that consumes pushed audit summaries.
+
+It is intentionally small and stable:
+
+- TypeScript-first types for Xerg wire payloads
+- A runtime `AUDIT_PUSH_PAYLOAD_VERSION` constant for compatibility checks
+- A dependency-light package surface for backends, ingestion services, and internal tooling
+
+## What it is not
+
+This package does not perform runtime validation by itself. It provides compile-time guarantees for TypeScript consumers. If you accept untrusted JSON, add runtime validation in the consuming service and keep it aligned with these exported types.
+
+## Install
+
+```bash
+npm install @xerg/schemas
+```
+
+## Example
+
+```ts
+import {
+  AUDIT_PUSH_PAYLOAD_VERSION,
+  type AuditPushPayload,
+} from '@xerg/schemas';
+
+export function acceptAuditPayload(payload: AuditPushPayload) {
+  if (payload.version !== AUDIT_PUSH_PAYLOAD_VERSION) {
+    throw new Error(`Unsupported payload version: ${payload.version}`);
+  }
+
+  return payload.summary.auditId;
+}
+```
+
+## Compatibility contract
+
+`AuditPushPayload.version` is the top-level wire version.
+
+- Additive fields that older consumers can safely ignore should usually keep the same version.
+- Breaking changes to existing field names, meanings, or required structure should ship behind a new payload version.
+- Producers and consumers should reject payloads with a newer unsupported version instead of guessing.
+
+Current version:
+
+```ts
+import { AUDIT_PUSH_PAYLOAD_VERSION } from '@xerg/schemas';
+
+AUDIT_PUSH_PAYLOAD_VERSION; // 1
+```
+
+## Exports
+
+Primary exports include:
+
+- `AuditPushPayload`
+- `WireFinding`
+- `WireComparison`
+- `XergRecommendation`
+- `AUDIT_PUSH_PAYLOAD_VERSION`
+
+## Use cases
+
+- Share a single payload contract between the Xerg CLI and backend services
+- Type audit ingestion pipelines without copying interface definitions
+- Gate processing logic on an explicit payload version

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+interface WireComparison {
+    baselineAuditId: string;
+    baselineGeneratedAt: string;
+    baselineTotalSpendUsd: number;
+    baselineWasteSpendUsd: number;
+    baselineStructuralWasteRate: number;
+    deltaTotalSpendUsd: number;
+    deltaWasteSpendUsd: number;
+    deltaStructuralWasteRate: number;
+    deltaRunCount: number;
+    deltaCallCount: number;
+}
+
+type WireFindingScope = 'global' | 'workflow' | 'run';
+interface WireFinding {
+    id: string;
+    classification: 'waste' | 'opportunity';
+    confidence: 'high' | 'medium' | 'low';
+    kind: string;
+    title: string;
+    summary: string;
+    scope: WireFindingScope;
+    scopeId: string;
+    costImpactUsd: number;
+}
+
+declare const AUDIT_PUSH_PAYLOAD_VERSION: 1;
+type AuditPushPayloadVersion = typeof AUDIT_PUSH_PAYLOAD_VERSION;
+type PushEnvironment = 'local' | 'remote' | 'railway';
+interface FindingTaxonomyBucket {
+    kind: string;
+    label: string;
+    classification: 'waste' | 'opportunity';
+    spendUsd: number;
+    findingCount: number;
+}
+interface SpendBreakdown {
+    key: string;
+    spendUsd: number;
+    callCount: number;
+    observedShare: number;
+}
+interface AuditPushPayload {
+    version: AuditPushPayloadVersion;
+    summary: {
+        auditId: string;
+        generatedAt: string;
+        comparisonKey: string;
+        runCount: number;
+        callCount: number;
+        totalSpendUsd: number;
+        observedSpendUsd: number;
+        estimatedSpendUsd: number;
+        wasteSpendUsd: number;
+        opportunitySpendUsd: number;
+        structuralWasteRate: number;
+        wasteByKind: FindingTaxonomyBucket[];
+        opportunityByKind: FindingTaxonomyBucket[];
+        spendByWorkflow: SpendBreakdown[];
+        spendByModel: SpendBreakdown[];
+        findings: WireFinding[];
+        notes: string[];
+        comparison?: WireComparison | null;
+    };
+    meta: {
+        cliVersion: string;
+        sourceId: string;
+        sourceHost: string;
+        environment: PushEnvironment;
+        pushedAt: string;
+    };
+}
+
+interface XergRecommendation {
+    id: string;
+    findingId: string;
+    kind: string;
+    title: string;
+    description: string;
+    estimatedSavingsUsd: number;
+    confidence: 'high' | 'medium' | 'low';
+    actionType: 'model-switch' | 'cache-config' | 'prompt-trim' | 'dedup' | 'other';
+    suggestedChange?: Record<string, unknown>;
+}
+
+export { AUDIT_PUSH_PAYLOAD_VERSION, type AuditPushPayload, type AuditPushPayloadVersion, type FindingTaxonomyBucket, type PushEnvironment, type SpendBreakdown, type WireComparison, type WireFinding, type WireFindingScope, type XergRecommendation };

package/dist/index.js

@@ -0,0 +1,5 @@
+// src/audit-push-payload.ts
+var AUDIT_PUSH_PAYLOAD_VERSION = 1;
+export {
+  AUDIT_PUSH_PAYLOAD_VERSION
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@xerg/schemas",
+  "version": "0.1.0",
+  "description": "Versioned TypeScript wire types for Xerg audit payloads, findings, comparisons, and recommendations.",
+  "keywords": [
+    "xerg",
+    "schemas",
+    "typescript",
+    "types",
+    "wire-types",
+    "api",
+    "contracts",
+    "audit",
+    "openclaw",
+    "finops",
+    "llm"
+  ],
+  "homepage": "https://xerg.ai",
+  "bugs": {
+    "email": "query@xerg.ai",
+    "url": "https://xerg.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xergai/xerg.git",
+    "directory": "packages/schemas"
+  },
+  "author": "Xerg <query@xerg.ai>",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {}
+}