@m1kad0/hannah-proto 4.5.0 → 4.6.0

package/README.md

@@ -16,6 +16,27 @@ Three independent, tag-triggered publish targets — pick whichever matches your
 
 Go has no separate package registry, so that tagged GitHub repo *is* the package — `go get` resolves it directly.
 
+## API generations: hannah.v1
+
+The schema exists in two packages side by side:
+
+| Package | Files | Status |
+|---|---|---|
+| `hannah.v1` | `hannah/v1/*.proto` | **current generation** — all changes go here |
+| `hannah` (unversioned) | `hannah/*.proto` | frozen (N−1), kept so older components keep working |
+
+Both carry the same services and messages, but under different gRPC method paths (`/hannah.v1.HannahService/...` vs `/hannah.HannahService/...`), so a server can serve both at once and gRPC routes each call to the right one. Hannah Core serves the current generation and the one before it (N and N−1, never more). Clients use the current generation and fall back to the previous one if Core answers `UNIMPLEMENTED` (Core too old).
+
+A breaking change never happens inside a generation — it starts the next one (`hannah.v2`), and the oldest one is removed. `hannah/options.proto` (the `compat_version` extension) is shared by both packages, not copied. The API generation is independent of the package version: `hannah.v1` ships in 4.x.
+
+| Language | Current generation | Previous generation |
+|---|---|---|
+| Python | `from hannah_proto.v1 import hannah_pb2` | `from hannah_proto import hannah_pb2` |
+| TypeScript | `import { v1 } from '@m1kad0/hannah-proto'` → `v1.agent.AgentMessage` | `import { agent } from '@m1kad0/hannah-proto'` |
+| Go | `github.com/NurPech/hannah-proto-go/v4/hannahv1` | `github.com/NurPech/hannah-proto-go/v4` |
+
+CI rejects any change under `hannah/` outside `hannah/v1/`.
+
 ## Versioning: PROTO_VERSION
 
 Alongside the semver package/tag version, every release carries a single-integer `PROTO_VERSION` (see the `PROTO_VERSION` file). Hannah Core and its clients exchange this value on every call and reject a mismatch at runtime — that's the actual compatibility gate, not the semver tag. A breaking schema change requires bumping `PROTO_VERSION`; CI enforces this on every merge request via `buf breaking`.

package/dist/compat_interceptor.js

@@ -5,10 +5,11 @@ const grpc_js_1 = require("@grpc/grpc-js");
 const compat_versions_1 = require("./compat_versions");
 Object.defineProperty(exports, "DEFAULT_COMPAT_VERSION", { enumerable: true, get: function () { return compat_versions_1.DEFAULT_COMPAT_VERSION; } });
 exports.COMPAT_VERSION_METADATA_KEY = "x-compat-version";
-/** `methodName` is the bare RPC name (e.g. "SubmitText"), matching the keys
- * gen-compat-versions.js writes into REQUIRED_COMPAT_VERSIONS. */
-function getRequiredCompatVersion(methodName) {
-    return compat_versions_1.REQUIRED_COMPAT_VERSIONS[methodName] ?? compat_versions_1.DEFAULT_COMPAT_VERSION;
+/** `methodPath` is the full gRPC path (e.g. "/hannah.v1.HannahService/SubmitText"),
+ * matching the keys gen-compat-versions.js writes into REQUIRED_COMPAT_VERSIONS —
+ * the bare name would be ambiguous between hannah and hannah.v1. */
+function getRequiredCompatVersion(methodPath) {
+    return compat_versions_1.REQUIRED_COMPAT_VERSIONS[methodPath] ?? compat_versions_1.DEFAULT_COMPAT_VERSION;
 }
 /**
  * grpc-js client interceptor: attaches x-compat-version metadata to every
@@ -18,8 +19,7 @@ function getRequiredCompatVersion(methodName) {
  * hannah-proto#9, the SetGroupRooms incident).
  */
 const compatVersionInterceptor = (options, nextCall) => {
-    const methodName = options.method_definition.path.split("/").pop() ?? "";
-    const required = getRequiredCompatVersion(methodName);
+    const required = getRequiredCompatVersion(options.method_definition.path);
     return new grpc_js_1.InterceptingCall(nextCall(options), {
         start(metadata, listener, next) {
             metadata.set(exports.COMPAT_VERSION_METADATA_KEY, String(required));

package/dist/compat_versions.js

@@ -4,92 +4,180 @@ exports.REQUIRED_COMPAT_VERSIONS = exports.DEFAULT_COMPAT_VERSION = void 0;
 // Generated by scripts/gen-compat-versions.js — do not edit by hand.
 exports.DEFAULT_COMPAT_VERSION = 1;
 exports.REQUIRED_COMPAT_VERSIONS = {
-    "GetUsers": 1,
-    "GetUser": 1,
-    "LinkAccount": 1,
-    "UnlinkAccount": 1,
-    "CreateLinkToken": 1,
-    "SetTrustLevel": 1,
-    "SetSystemMessages": 1,
-    "SetAutomation": 1,
-    "Login": 1,
-    "CreateUser": 1,
-    "UpdateUser": 1,
-    "DeleteUser": 1,
-    "GetResidents": 1,
-    "GetDevices": 1,
-    "ControlDevice": 1,
-    "SubmitText": 1,
-    "SubmitVoice": 1,
-    "Announce": 1,
-    "Notify": 1,
-    "GetSatellites": 1,
-    "SetSatelliteRoom": 1,
-    "SetSatelliteDisplayName": 1,
-    "SetSatelliteOwner": 1,
-    "SetSatelliteSmalltalkFollowup": 1,
-    "DeleteSatellite": 1,
-    "GetRooms": 1,
-    "GetGroups": 1,
-    "CreateGroup": 1,
-    "UpdateGroup": 1,
-    "DeleteGroup": 1,
-    "SetGroupSatellites": 1,
-    "GetTriggers": 1,
-    "CreateTrigger": 2,
-    "UpdateTrigger": 2,
-    "DeleteTrigger": 1,
-    "GetAlarms": 1,
-    "CreateAlarm": 1,
-    "UpdateAlarm": 1,
-    "DeleteAlarm": 1,
-    "GetSettings": 1,
-    "UpdateConfig": 1,
-    "GetBleTags": 1,
-    "CreateBleTag": 1,
-    "UpdateBleTag": 1,
-    "DeleteBleTag": 1,
-    "GetPresenceSources": 1,
-    "CreatePresenceSource": 1,
-    "UpdatePresenceSource": 1,
-    "DeletePresenceSource": 1,
-    "GetCars": 1,
-    "CreateCar": 1,
-    "UpdateCar": 1,
-    "DeleteCar": 1,
-    "GetCarState": 1,
-    "GetAllCarStates": 1,
-    "SubscribeEvents": 1,
-    "TriggerFirmwareUpdate": 1,
-    "TriggerSatelliteRestart": 1,
-    "RequestSatelliteCapture": 1,
-    "ReleaseSatelliteCapture": 1,
-    "StreamSatelliteAudio": 1,
-    "TriggerPlink": 1,
-    "CollectorConnect": 2,
-    "TriggerCollectorCapture": 2,
-    "RegisterProxy": 1,
-    "SubmitSatelliteAudio": 3,
-    "NotifySatelliteRegistered": 1,
-    "NotifySatelliteGone": 1,
-    "ProvisionSatellite": 1,
-    "StartVoiceEnrollment": 1,
-    "EnrollVoiceprint": 1,
-    "TimerConnect": 1,
-    "GetTimers": 1,
-    "DeleteTimer": 1,
-    "AgentConnect": 1,
-    "AutomationConnect": 1,
-    "ChannelConnect": 1,
-    "GetChannels": 1,
-    "SubscribeInfrastructure": 1,
-    "LogCollectorConnect": 1,
-    "ListActivityLog": 1,
-    "StreamActivityAudio": 1,
-    "CreateMessage": 1,
-    "ListMessages": 1,
-    "DeleteMessage": 1,
-    "Ship": 1,
-    "GetSources": 1,
-    "Export": 1
+    "/hannah.HannahService/GetUsers": 1,
+    "/hannah.HannahService/GetUser": 1,
+    "/hannah.HannahService/LinkAccount": 1,
+    "/hannah.HannahService/UnlinkAccount": 1,
+    "/hannah.HannahService/CreateLinkToken": 1,
+    "/hannah.HannahService/SetTrustLevel": 1,
+    "/hannah.HannahService/SetSystemMessages": 1,
+    "/hannah.HannahService/SetAutomation": 1,
+    "/hannah.HannahService/Login": 1,
+    "/hannah.HannahService/CreateUser": 1,
+    "/hannah.HannahService/UpdateUser": 1,
+    "/hannah.HannahService/DeleteUser": 1,
+    "/hannah.HannahService/GetResidents": 1,
+    "/hannah.HannahService/GetDevices": 1,
+    "/hannah.HannahService/ControlDevice": 1,
+    "/hannah.HannahService/SubmitText": 1,
+    "/hannah.HannahService/SubmitVoice": 1,
+    "/hannah.HannahService/Announce": 1,
+    "/hannah.HannahService/Notify": 1,
+    "/hannah.HannahService/GetSatellites": 1,
+    "/hannah.HannahService/SetSatelliteRoom": 1,
+    "/hannah.HannahService/SetSatelliteDisplayName": 1,
+    "/hannah.HannahService/SetSatelliteOwner": 1,
+    "/hannah.HannahService/SetSatelliteSmalltalkFollowup": 1,
+    "/hannah.HannahService/DeleteSatellite": 1,
+    "/hannah.HannahService/GetRooms": 1,
+    "/hannah.HannahService/GetGroups": 1,
+    "/hannah.HannahService/CreateGroup": 1,
+    "/hannah.HannahService/UpdateGroup": 1,
+    "/hannah.HannahService/DeleteGroup": 1,
+    "/hannah.HannahService/SetGroupSatellites": 1,
+    "/hannah.HannahService/GetTriggers": 1,
+    "/hannah.HannahService/CreateTrigger": 2,
+    "/hannah.HannahService/UpdateTrigger": 2,
+    "/hannah.HannahService/DeleteTrigger": 1,
+    "/hannah.HannahService/GetAlarms": 1,
+    "/hannah.HannahService/CreateAlarm": 1,
+    "/hannah.HannahService/UpdateAlarm": 1,
+    "/hannah.HannahService/DeleteAlarm": 1,
+    "/hannah.HannahService/GetSettings": 1,
+    "/hannah.HannahService/UpdateConfig": 1,
+    "/hannah.HannahService/GetBleTags": 1,
+    "/hannah.HannahService/CreateBleTag": 1,
+    "/hannah.HannahService/UpdateBleTag": 1,
+    "/hannah.HannahService/DeleteBleTag": 1,
+    "/hannah.HannahService/GetPresenceSources": 1,
+    "/hannah.HannahService/CreatePresenceSource": 1,
+    "/hannah.HannahService/UpdatePresenceSource": 1,
+    "/hannah.HannahService/DeletePresenceSource": 1,
+    "/hannah.HannahService/GetCars": 1,
+    "/hannah.HannahService/CreateCar": 1,
+    "/hannah.HannahService/UpdateCar": 1,
+    "/hannah.HannahService/DeleteCar": 1,
+    "/hannah.HannahService/GetCarState": 1,
+    "/hannah.HannahService/GetAllCarStates": 1,
+    "/hannah.HannahService/SubscribeEvents": 1,
+    "/hannah.HannahService/TriggerFirmwareUpdate": 1,
+    "/hannah.HannahService/TriggerSatelliteRestart": 1,
+    "/hannah.HannahService/RequestSatelliteCapture": 1,
+    "/hannah.HannahService/ReleaseSatelliteCapture": 1,
+    "/hannah.HannahService/StreamSatelliteAudio": 1,
+    "/hannah.HannahService/TriggerPlink": 1,
+    "/hannah.HannahService/CollectorConnect": 2,
+    "/hannah.HannahService/TriggerCollectorCapture": 2,
+    "/hannah.HannahService/RegisterProxy": 1,
+    "/hannah.HannahService/SubmitSatelliteAudio": 3,
+    "/hannah.HannahService/NotifySatelliteRegistered": 1,
+    "/hannah.HannahService/NotifySatelliteGone": 1,
+    "/hannah.HannahService/ProvisionSatellite": 1,
+    "/hannah.HannahService/StartVoiceEnrollment": 1,
+    "/hannah.HannahService/EnrollVoiceprint": 1,
+    "/hannah.HannahService/TimerConnect": 1,
+    "/hannah.HannahService/GetTimers": 1,
+    "/hannah.HannahService/DeleteTimer": 1,
+    "/hannah.HannahService/AgentConnect": 1,
+    "/hannah.HannahService/AutomationConnect": 1,
+    "/hannah.HannahService/ChannelConnect": 1,
+    "/hannah.HannahService/GetChannels": 1,
+    "/hannah.HannahService/SubscribeInfrastructure": 1,
+    "/hannah.HannahService/LogCollectorConnect": 1,
+    "/hannah.HannahService/ListActivityLog": 1,
+    "/hannah.HannahService/StreamActivityAudio": 1,
+    "/hannah.HannahService/CreateMessage": 1,
+    "/hannah.HannahService/ListMessages": 1,
+    "/hannah.HannahService/DeleteMessage": 1,
+    "/hannah.LogService/Ship": 1,
+    "/hannah.LogService/GetSources": 1,
+    "/hannah.LogService/Export": 1,
+    "/hannah.v1.HannahService/GetUsers": 1,
+    "/hannah.v1.HannahService/GetUser": 1,
+    "/hannah.v1.HannahService/LinkAccount": 1,
+    "/hannah.v1.HannahService/UnlinkAccount": 1,
+    "/hannah.v1.HannahService/CreateLinkToken": 1,
+    "/hannah.v1.HannahService/SetTrustLevel": 1,
+    "/hannah.v1.HannahService/SetSystemMessages": 1,
+    "/hannah.v1.HannahService/SetAutomation": 1,
+    "/hannah.v1.HannahService/Login": 1,
+    "/hannah.v1.HannahService/CreateUser": 1,
+    "/hannah.v1.HannahService/UpdateUser": 1,
+    "/hannah.v1.HannahService/DeleteUser": 1,
+    "/hannah.v1.HannahService/GetResidents": 1,
+    "/hannah.v1.HannahService/GetDevices": 1,
+    "/hannah.v1.HannahService/ControlDevice": 1,
+    "/hannah.v1.HannahService/SubmitText": 1,
+    "/hannah.v1.HannahService/SubmitVoice": 1,
+    "/hannah.v1.HannahService/Announce": 1,
+    "/hannah.v1.HannahService/Notify": 1,
+    "/hannah.v1.HannahService/GetSatellites": 1,
+    "/hannah.v1.HannahService/SetSatelliteRoom": 1,
+    "/hannah.v1.HannahService/SetSatelliteDisplayName": 1,
+    "/hannah.v1.HannahService/SetSatelliteOwner": 1,
+    "/hannah.v1.HannahService/SetSatelliteSmalltalkFollowup": 1,
+    "/hannah.v1.HannahService/DeleteSatellite": 1,
+    "/hannah.v1.HannahService/GetRooms": 1,
+    "/hannah.v1.HannahService/GetGroups": 1,
+    "/hannah.v1.HannahService/CreateGroup": 1,
+    "/hannah.v1.HannahService/UpdateGroup": 1,
+    "/hannah.v1.HannahService/DeleteGroup": 1,
+    "/hannah.v1.HannahService/SetGroupSatellites": 1,
+    "/hannah.v1.HannahService/GetTriggers": 1,
+    "/hannah.v1.HannahService/CreateTrigger": 2,
+    "/hannah.v1.HannahService/UpdateTrigger": 2,
+    "/hannah.v1.HannahService/DeleteTrigger": 1,
+    "/hannah.v1.HannahService/GetAlarms": 1,
+    "/hannah.v1.HannahService/CreateAlarm": 1,
+    "/hannah.v1.HannahService/UpdateAlarm": 1,
+    "/hannah.v1.HannahService/DeleteAlarm": 1,
+    "/hannah.v1.HannahService/GetSettings": 1,
+    "/hannah.v1.HannahService/UpdateConfig": 1,
+    "/hannah.v1.HannahService/GetBleTags": 1,
+    "/hannah.v1.HannahService/CreateBleTag": 1,
+    "/hannah.v1.HannahService/UpdateBleTag": 1,
+    "/hannah.v1.HannahService/DeleteBleTag": 1,
+    "/hannah.v1.HannahService/GetPresenceSources": 1,
+    "/hannah.v1.HannahService/CreatePresenceSource": 1,
+    "/hannah.v1.HannahService/UpdatePresenceSource": 1,
+    "/hannah.v1.HannahService/DeletePresenceSource": 1,
+    "/hannah.v1.HannahService/GetCars": 1,
+    "/hannah.v1.HannahService/CreateCar": 1,
+    "/hannah.v1.HannahService/UpdateCar": 1,
+    "/hannah.v1.HannahService/DeleteCar": 1,
+    "/hannah.v1.HannahService/GetCarState": 1,
+    "/hannah.v1.HannahService/GetAllCarStates": 1,
+    "/hannah.v1.HannahService/SubscribeEvents": 1,
+    "/hannah.v1.HannahService/TriggerFirmwareUpdate": 1,
+    "/hannah.v1.HannahService/TriggerSatelliteRestart": 1,
+    "/hannah.v1.HannahService/RequestSatelliteCapture": 1,
+    "/hannah.v1.HannahService/ReleaseSatelliteCapture": 1,
+    "/hannah.v1.HannahService/StreamSatelliteAudio": 1,
+    "/hannah.v1.HannahService/TriggerPlink": 1,
+    "/hannah.v1.HannahService/CollectorConnect": 2,
+    "/hannah.v1.HannahService/TriggerCollectorCapture": 2,
+    "/hannah.v1.HannahService/RegisterProxy": 1,
+    "/hannah.v1.HannahService/SubmitSatelliteAudio": 3,
+    "/hannah.v1.HannahService/NotifySatelliteRegistered": 1,
+    "/hannah.v1.HannahService/NotifySatelliteGone": 1,
+    "/hannah.v1.HannahService/ProvisionSatellite": 1,
+    "/hannah.v1.HannahService/StartVoiceEnrollment": 1,
+    "/hannah.v1.HannahService/EnrollVoiceprint": 1,
+    "/hannah.v1.HannahService/TimerConnect": 1,
+    "/hannah.v1.HannahService/GetTimers": 1,
+    "/hannah.v1.HannahService/DeleteTimer": 1,
+    "/hannah.v1.HannahService/AgentConnect": 1,
+    "/hannah.v1.HannahService/AutomationConnect": 1,
+    "/hannah.v1.HannahService/ChannelConnect": 1,
+    "/hannah.v1.HannahService/GetChannels": 1,
+    "/hannah.v1.HannahService/SubscribeInfrastructure": 1,
+    "/hannah.v1.HannahService/LogCollectorConnect": 1,
+    "/hannah.v1.HannahService/ListActivityLog": 1,
+    "/hannah.v1.HannahService/StreamActivityAudio": 1,
+    "/hannah.v1.HannahService/CreateMessage": 1,
+    "/hannah.v1.HannahService/ListMessages": 1,
+    "/hannah.v1.HannahService/DeleteMessage": 1,
+    "/hannah.v1.LogService/Ship": 1,
+    "/hannah.v1.LogService/GetSources": 1,
+    "/hannah.v1.LogService/Export": 1
 };

package/dist/index.d.ts

@@ -24,3 +24,4 @@ export * as timer_service from './timer_service';
 export * as user_registry from './user_registry';
 export * as wakeword_capture from './wakeword_capture';
 export * as weather from './weather';
+export * as v1 from './v1';

package/dist/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.weather = exports.wakeword_capture = exports.user_registry = exports.timer_service = exports.timer_admin = exports.speaker_enrollment = exports.shared = exports.satellite_proxy = exports.satellite_provisioning = exports.satellite = exports.options = exports.messages = exports.logging = exports.infrastructure = exports.hannah = exports.event_stream = exports.device_control_menu = exports.control = exports.compat_versions = exports.compat_interceptor = exports.channel = exports.car_state = exports.automation = exports.agent = exports.activity_log = void 0;
+exports.v1 = exports.weather = exports.wakeword_capture = exports.user_registry = exports.timer_service = exports.timer_admin = exports.speaker_enrollment = exports.shared = exports.satellite_proxy = exports.satellite_provisioning = exports.satellite = exports.options = exports.messages = exports.logging = exports.infrastructure = exports.hannah = exports.event_stream = exports.device_control_menu = exports.control = exports.compat_versions = exports.compat_interceptor = exports.channel = exports.car_state = exports.automation = exports.agent = exports.activity_log = void 0;
 __exportStar(require("./version"), exports);
 exports.activity_log = __importStar(require("./activity_log"));
 exports.agent = __importStar(require("./agent"));
@@ -63,3 +63,4 @@ exports.timer_service = __importStar(require("./timer_service"));
 exports.user_registry = __importStar(require("./user_registry"));
 exports.wakeword_capture = __importStar(require("./wakeword_capture"));
 exports.weather = __importStar(require("./weather"));
+exports.v1 = __importStar(require("./v1"));

package/dist/v1/activity_log.d.ts

@@ -0,0 +1,60 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+export declare const protobufPackage = "hannah.v1";
+export interface ActivityLogEntry {
+    id: bigint;
+    ts: string;
+    channelType: string;
+    channelId: string;
+    /** 0 = unresolved/unset */
+    userId: number;
+    rawText: string;
+    intentName: string;
+    /** JSON-encoded, "" = none */
+    intentMetaJson: string;
+    answerText: string;
+    /** audio_path was set — tells the caller whether to offer playback */
+    hasAudio: boolean;
+}
+export interface ListActivityLogRequest {
+    requestorId: number;
+    /** only honored when requestor's trust_level >= 10; 0 = no target filter */
+    filterUserId: number;
+    pageSize: number;
+    /** cursor, 0 = start from newest */
+    beforeId: bigint;
+}
+export interface ListActivityLogResponse {
+    entries: ActivityLogEntry[];
+    hasMore: boolean;
+}
+export interface StreamActivityAudioRequest {
+    requestorId: number;
+    activityLogId: bigint;
+}
+/** A chunk of raw PCM audio (16-bit signed, mono) streamed from a single Activity Log entry. */
+export interface ActivityAudioChunk {
+    pcm: Uint8Array;
+    sampleRate: number;
+}
+export declare const ActivityLogEntry: MessageFns<ActivityLogEntry>;
+export declare const ListActivityLogRequest: MessageFns<ListActivityLogRequest>;
+export declare const ListActivityLogResponse: MessageFns<ListActivityLogResponse>;
+export declare const StreamActivityAudioRequest: MessageFns<StreamActivityAudioRequest>;
+export declare const ActivityAudioChunk: MessageFns<ActivityAudioChunk>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | bigint | undefined;
+export type DeepPartial<T> = T extends bigint ? string | number | bigint : T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+export type Exact<P, I extends P> = P extends Builtin ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & {
+    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
+};
+export interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
+    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
+}
+export {};