@7k-inari/api-client 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,60 @@
1
+ # inari-api
2
+
3
+ The compatibility contract for Inari: protobuf definitions (agent EventStream protocol, plugin contract) + OpenAPI specs, with generated Go/TS clients (plan §6 #5).
4
+
5
+ Stack: Buf, protoc (connect/gRPC), oapi-codegen; generated Go + TypeScript clients
6
+
7
+ Part of the **Inari** multi-tenant Internal Developer Platform (GitHub org `7K-Inari`).
8
+ Canonical architecture & development plan: [inari-docs/docs/architecture/inari-platform-plan.md](https://github.com/7K-Inari/inari-docs/blob/main/docs/architecture/inari-platform-plan.md)
9
+
10
+ ## Layout
11
+
12
+ - `proto/inari/agent/v1/` — agent EventStream protocol (bidirectional gRPC stream, CloudEvents-style envelope)
13
+ - `proto/inari/plugin/v1/` — versioned plugin contract (hashicorp go-plugin model)
14
+ - `openapi/openapi.yaml` — REST surface for console/CLI (OpenAPI 3.0)
15
+ - `gen/go/`, `gen/ts/` — generated Go and TypeScript clients, **committed to the repo** (see below)
16
+
17
+ ## Development
18
+
19
+ Prerequisites: `buf`, Go, Node.js, `oapi-codegen`, `yq` (v4, for `import-openapi`).
20
+
21
+ - `make generate` — regenerate everything (`buf generate`, oapi-codegen, Orval)
22
+ - `make import-openapi` — pull the full REST surface from inari-server's offline export (`make export-openapi`) and merge it with `openapi/meta.fragment.yaml` (health endpoints, info, servers) into `openapi/openapi.yaml`; pass `EXPORTED=/path/to/openapi.yaml` to reuse an existing export, or `INARI_SERVER_REF=<ref>` to pin a ref. Run this whenever the inari-server REST surface changes, then `make generate`.
23
+ - `make lint` — `buf lint` + `redocly lint`
24
+ - `make breaking` — `buf breaking` against `main`
25
+ - `make build` / `make test` — compile and smoke-test both clients
26
+ - `make ci` — the full local gate
27
+
28
+ Note: `npm ci` must run with dev dependencies (`npm ci --include=dev`, or unset `NODE_ENV=production`); Orval and TypeScript are devDependencies.
29
+
30
+ ## Generated code policy
31
+
32
+ Generated output under `gen/` is **committed**, not built only in CI. Consumers pin
33
+ `go get github.com/7K-Inari/inari-api@<tag>` and the npm package directly at a git tag,
34
+ so the exact contract surface must be reviewable in PRs and resolvable without codegen in
35
+ consumer CI. A CI drift check (`make generate && git diff --exit-code`) guarantees
36
+ committed code always matches the sources.
37
+
38
+ ## Versioning policy
39
+
40
+ - Releases are SemVer git tags `vX.Y.Z`; commit messages follow Conventional Commits.
41
+ - **Protobuf: additive changes only within a package version.** New fields, messages, or
42
+ RPCs may be added to `inari.*.v1`. Any breaking change (removing/renumbering a field,
43
+ changing a type, renaming a package or service, changing request/response types) requires
44
+ a **new package version** (`v1` → `v2`) — never edit a released version in place.
45
+ `buf breaking` runs in CI against `main` to enforce this.
46
+ - **OpenAPI: additive changes only** (new endpoints, new optional fields). Breaking changes
47
+ require a new base path (`/api/v2`) and spec version.
48
+ - Go modules at v2+ use the `/v2` import-path suffix per Go module semantics; the release
49
+ workflow verifies tag/module-path consistency.
50
+
51
+ ## Consuming
52
+
53
+ ```sh
54
+ go get github.com/7K-Inari/inari-api@v0.1.0
55
+ npm install @7k-inari/api-client@0.1.0
56
+ ```
57
+
58
+ Tagging `vX.Y.Z` runs the release workflow: it re-verifies the full CI gate and publishes
59
+ the npm package (requires the `NPM_TOKEN` secret). The Go module is consumable from the
60
+ tag itself.
@@ -0,0 +1,30 @@
1
+ // @generated by protoc-gen-connect-es v1.6.1 with parameter "target=ts"
2
+ // @generated from file inari/agent/v1/agent.proto (package inari.agent.v1, syntax proto3)
3
+ /* eslint-disable */
4
+ // @ts-nocheck
5
+
6
+ import { ConnectRequest, ConnectResponse } from "./agent_pb.js";
7
+ import { MethodKind } from "@bufbuild/protobuf";
8
+
9
+ /**
10
+ * EventStreamService is the bidirectional gRPC stream between an in-cluster
11
+ * agent and the Agent Gateway (plan §5.2). Delivery is at-least-once;
12
+ * command handlers must be idempotent (command_id is the idempotency key).
13
+ *
14
+ * @generated from service inari.agent.v1.EventStreamService
15
+ */
16
+ export const EventStreamService = {
17
+ typeName: "inari.agent.v1.EventStreamService",
18
+ methods: {
19
+ /**
20
+ * @generated from rpc inari.agent.v1.EventStreamService.Connect
21
+ */
22
+ connect: {
23
+ name: "Connect",
24
+ I: ConnectRequest,
25
+ O: ConnectResponse,
26
+ kind: MethodKind.BiDiStreaming,
27
+ },
28
+ }
29
+ } as const;
30
+
@@ -0,0 +1,396 @@
1
+ // @generated by protoc-gen-es v1.10.0 with parameter "target=ts"
2
+ // @generated from file inari/agent/v1/agent.proto (package inari.agent.v1, syntax proto3)
3
+ /* eslint-disable */
4
+ // @ts-nocheck
5
+
6
+ import type { BinaryReadOptions, FieldList, JsonReadOptions, JsonValue, PartialMessage, PlainMessage } from "@bufbuild/protobuf";
7
+ import { Any, Message, proto3, protoInt64, Timestamp } from "@bufbuild/protobuf";
8
+
9
+ /**
10
+ * EventType enumerates every well-known event/command type carried on the
11
+ * EventStream. Event.type holds the reverse-DNS string form (e.g.
12
+ * "inari.agent.apply-bundle.v1"); this enum is its typed mirror for
13
+ * exhaustive consumer-side handling.
14
+ *
15
+ * @generated from enum inari.agent.v1.EventType
16
+ */
17
+ export enum EventType {
18
+ /**
19
+ * @generated from enum value: EVENT_TYPE_UNSPECIFIED = 0;
20
+ */
21
+ UNSPECIFIED = 0,
22
+
23
+ /**
24
+ * agent→server: discovered capability changes (plan §5.3).
25
+ *
26
+ * @generated from enum value: EVENT_TYPE_CAPABILITY_UPDATE = 1;
27
+ */
28
+ CAPABILITY_UPDATE = 1,
29
+
30
+ /**
31
+ * agent→server: resource health/sync reporting (plan §5.3).
32
+ *
33
+ * @generated from enum value: EVENT_TYPE_STATUS_UPDATE = 2;
34
+ */
35
+ STATUS_UPDATE = 2,
36
+
37
+ /**
38
+ * server→agent: stream keepalive.
39
+ *
40
+ * @generated from enum value: EVENT_TYPE_PING = 3;
41
+ */
42
+ PING = 3,
43
+
44
+ /**
45
+ * agent→server: keepalive reply.
46
+ *
47
+ * @generated from enum value: EVENT_TYPE_PONG = 4;
48
+ */
49
+ PONG = 4,
50
+
51
+ /**
52
+ * server→agent: checksum mismatch, re-send full state (plan §5.2).
53
+ *
54
+ * @generated from enum value: EVENT_TYPE_RESYNC_REQUEST = 5;
55
+ */
56
+ RESYNC_REQUEST = 5,
57
+
58
+ /**
59
+ * agent→server: resync complete marker.
60
+ *
61
+ * @generated from enum value: EVENT_TYPE_RESYNC_RESPONSE = 6;
62
+ */
63
+ RESYNC_RESPONSE = 6,
64
+
65
+ /**
66
+ * server→agent: apply a rendered bundle to tenant Git (plan §5.3).
67
+ *
68
+ * @generated from enum value: EVENT_TYPE_APPLY_BUNDLE = 7;
69
+ */
70
+ APPLY_BUNDLE = 7,
71
+
72
+ /**
73
+ * server→agent: register a tenant-local ArgoCD Application.
74
+ *
75
+ * @generated from enum value: EVENT_TYPE_REGISTER_ARGOCD_APP = 8;
76
+ */
77
+ REGISTER_ARGOCD_APP = 8,
78
+
79
+ /**
80
+ * server→agent: imperative out-of-band action (ArgoCD actions etc.).
81
+ *
82
+ * @generated from enum value: EVENT_TYPE_INVOKE_ACTION = 9;
83
+ */
84
+ INVOKE_ACTION = 9,
85
+
86
+ /**
87
+ * server→agent: render a KRO ResourceGraphDefinition instance.
88
+ *
89
+ * @generated from enum value: EVENT_TYPE_RENDER_RGD_INSTANCE = 10;
90
+ */
91
+ RENDER_RGD_INSTANCE = 10,
92
+
93
+ /**
94
+ * agent→server: command outcome (success).
95
+ *
96
+ * @generated from enum value: EVENT_TYPE_COMMAND_ACK = 11;
97
+ */
98
+ COMMAND_ACK = 11,
99
+
100
+ /**
101
+ * agent→server: command outcome (failure).
102
+ *
103
+ * @generated from enum value: EVENT_TYPE_COMMAND_NACK = 12;
104
+ */
105
+ COMMAND_NACK = 12,
106
+ }
107
+ // Retrieve enum metadata with: proto3.getEnumType(EventType)
108
+ proto3.util.setEnumType(EventType, "inari.agent.v1.EventType", [
109
+ { no: 0, name: "EVENT_TYPE_UNSPECIFIED" },
110
+ { no: 1, name: "EVENT_TYPE_CAPABILITY_UPDATE" },
111
+ { no: 2, name: "EVENT_TYPE_STATUS_UPDATE" },
112
+ { no: 3, name: "EVENT_TYPE_PING" },
113
+ { no: 4, name: "EVENT_TYPE_PONG" },
114
+ { no: 5, name: "EVENT_TYPE_RESYNC_REQUEST" },
115
+ { no: 6, name: "EVENT_TYPE_RESYNC_RESPONSE" },
116
+ { no: 7, name: "EVENT_TYPE_APPLY_BUNDLE" },
117
+ { no: 8, name: "EVENT_TYPE_REGISTER_ARGOCD_APP" },
118
+ { no: 9, name: "EVENT_TYPE_INVOKE_ACTION" },
119
+ { no: 10, name: "EVENT_TYPE_RENDER_RGD_INSTANCE" },
120
+ { no: 11, name: "EVENT_TYPE_COMMAND_ACK" },
121
+ { no: 12, name: "EVENT_TYPE_COMMAND_NACK" },
122
+ ]);
123
+
124
+ /**
125
+ * Event is the CloudEvents-style envelope exchanged on the agent EventStream
126
+ * (plan §4.3). Concrete payloads are typed messages packed into `payload`
127
+ * (google.protobuf.Any); see events.proto and commands.proto.
128
+ *
129
+ * @generated from message inari.agent.v1.Event
130
+ */
131
+ export class Event extends Message<Event> {
132
+ /**
133
+ * @generated from field: string event_id = 1;
134
+ */
135
+ eventId = "";
136
+
137
+ /**
138
+ * @generated from field: string resource_id = 2;
139
+ */
140
+ resourceId = "";
141
+
142
+ /**
143
+ * Reverse-DNS event type, e.g. inari.agent.ping.v1.
144
+ *
145
+ * @generated from field: string type = 3;
146
+ */
147
+ type = "";
148
+
149
+ /**
150
+ * @generated from field: google.protobuf.Any payload = 4;
151
+ */
152
+ payload?: Any;
153
+
154
+ /**
155
+ * @generated from field: google.protobuf.Timestamp time = 5;
156
+ */
157
+ time?: Timestamp;
158
+
159
+ /**
160
+ * Per-agent monotonic sequence number; the gateway uses gaps to trigger
161
+ * checksum-based resync after reconnects (plan §5.2).
162
+ *
163
+ * @generated from field: int64 sequence = 6;
164
+ */
165
+ sequence = protoInt64.zero;
166
+
167
+ constructor(data?: PartialMessage<Event>) {
168
+ super();
169
+ proto3.util.initPartial(data, this);
170
+ }
171
+
172
+ static readonly runtime: typeof proto3 = proto3;
173
+ static readonly typeName = "inari.agent.v1.Event";
174
+ static readonly fields: FieldList = proto3.util.newFieldList(() => [
175
+ { no: 1, name: "event_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
176
+ { no: 2, name: "resource_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
177
+ { no: 3, name: "type", kind: "scalar", T: 9 /* ScalarType.STRING */ },
178
+ { no: 4, name: "payload", kind: "message", T: Any },
179
+ { no: 5, name: "time", kind: "message", T: Timestamp },
180
+ { no: 6, name: "sequence", kind: "scalar", T: 3 /* ScalarType.INT64 */ },
181
+ ]);
182
+
183
+ static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): Event {
184
+ return new Event().fromBinary(bytes, options);
185
+ }
186
+
187
+ static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): Event {
188
+ return new Event().fromJson(jsonValue, options);
189
+ }
190
+
191
+ static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): Event {
192
+ return new Event().fromJsonString(jsonString, options);
193
+ }
194
+
195
+ static equals(a: Event | PlainMessage<Event> | undefined, b: Event | PlainMessage<Event> | undefined): boolean {
196
+ return proto3.util.equals(Event, a, b);
197
+ }
198
+ }
199
+
200
+ /**
201
+ * HandshakeRequest opens a session; the agent always dials out to the control
202
+ * plane (pull, never push). Authentication is the per-cluster OIDC JWT with a
203
+ * hardcoded cluster_id claim (plan §5.3) — the handshake only negotiates
204
+ * contract versions and resync state.
205
+ *
206
+ * @generated from message inari.agent.v1.HandshakeRequest
207
+ */
208
+ export class HandshakeRequest extends Message<HandshakeRequest> {
209
+ /**
210
+ * @generated from field: string agent_version = 1;
211
+ */
212
+ agentVersion = "";
213
+
214
+ /**
215
+ * @generated from field: string tenant_id = 2;
216
+ */
217
+ tenantId = "";
218
+
219
+ /**
220
+ * Contract package this agent implements, e.g. "inari.agent.v1".
221
+ *
222
+ * @generated from field: string contract_version = 3;
223
+ */
224
+ contractVersion = "";
225
+
226
+ /**
227
+ * Checksum of the agent state the gateway last acknowledged; a mismatch on
228
+ * the server side triggers a resync (plan §5.2).
229
+ *
230
+ * @generated from field: string last_seen_state_checksum = 4;
231
+ */
232
+ lastSeenStateChecksum = "";
233
+
234
+ constructor(data?: PartialMessage<HandshakeRequest>) {
235
+ super();
236
+ proto3.util.initPartial(data, this);
237
+ }
238
+
239
+ static readonly runtime: typeof proto3 = proto3;
240
+ static readonly typeName = "inari.agent.v1.HandshakeRequest";
241
+ static readonly fields: FieldList = proto3.util.newFieldList(() => [
242
+ { no: 1, name: "agent_version", kind: "scalar", T: 9 /* ScalarType.STRING */ },
243
+ { no: 2, name: "tenant_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
244
+ { no: 3, name: "contract_version", kind: "scalar", T: 9 /* ScalarType.STRING */ },
245
+ { no: 4, name: "last_seen_state_checksum", kind: "scalar", T: 9 /* ScalarType.STRING */ },
246
+ ]);
247
+
248
+ static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): HandshakeRequest {
249
+ return new HandshakeRequest().fromBinary(bytes, options);
250
+ }
251
+
252
+ static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): HandshakeRequest {
253
+ return new HandshakeRequest().fromJson(jsonValue, options);
254
+ }
255
+
256
+ static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): HandshakeRequest {
257
+ return new HandshakeRequest().fromJsonString(jsonString, options);
258
+ }
259
+
260
+ static equals(a: HandshakeRequest | PlainMessage<HandshakeRequest> | undefined, b: HandshakeRequest | PlainMessage<HandshakeRequest> | undefined): boolean {
261
+ return proto3.util.equals(HandshakeRequest, a, b);
262
+ }
263
+ }
264
+
265
+ /**
266
+ * @generated from message inari.agent.v1.HandshakeResponse
267
+ */
268
+ export class HandshakeResponse extends Message<HandshakeResponse> {
269
+ /**
270
+ * @generated from field: string session_id = 1;
271
+ */
272
+ sessionId = "";
273
+
274
+ /**
275
+ * Contract versions the gateway supports (N/N−1, plan §5.11),
276
+ * comma-separated, e.g. "inari.agent.v1".
277
+ *
278
+ * @generated from field: string server_contract_versions = 2;
279
+ */
280
+ serverContractVersions = "";
281
+
282
+ /**
283
+ * True when the agent must re-send full state (checksum mismatch or gap).
284
+ *
285
+ * @generated from field: bool resync_required = 3;
286
+ */
287
+ resyncRequired = false;
288
+
289
+ constructor(data?: PartialMessage<HandshakeResponse>) {
290
+ super();
291
+ proto3.util.initPartial(data, this);
292
+ }
293
+
294
+ static readonly runtime: typeof proto3 = proto3;
295
+ static readonly typeName = "inari.agent.v1.HandshakeResponse";
296
+ static readonly fields: FieldList = proto3.util.newFieldList(() => [
297
+ { no: 1, name: "session_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
298
+ { no: 2, name: "server_contract_versions", kind: "scalar", T: 9 /* ScalarType.STRING */ },
299
+ { no: 3, name: "resync_required", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
300
+ ]);
301
+
302
+ static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): HandshakeResponse {
303
+ return new HandshakeResponse().fromBinary(bytes, options);
304
+ }
305
+
306
+ static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): HandshakeResponse {
307
+ return new HandshakeResponse().fromJson(jsonValue, options);
308
+ }
309
+
310
+ static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): HandshakeResponse {
311
+ return new HandshakeResponse().fromJsonString(jsonString, options);
312
+ }
313
+
314
+ static equals(a: HandshakeResponse | PlainMessage<HandshakeResponse> | undefined, b: HandshakeResponse | PlainMessage<HandshakeResponse> | undefined): boolean {
315
+ return proto3.util.equals(HandshakeResponse, a, b);
316
+ }
317
+ }
318
+
319
+ /**
320
+ * ConnectRequest carries one Event from agent to gateway on the stream.
321
+ *
322
+ * @generated from message inari.agent.v1.ConnectRequest
323
+ */
324
+ export class ConnectRequest extends Message<ConnectRequest> {
325
+ /**
326
+ * @generated from field: inari.agent.v1.Event event = 1;
327
+ */
328
+ event?: Event;
329
+
330
+ constructor(data?: PartialMessage<ConnectRequest>) {
331
+ super();
332
+ proto3.util.initPartial(data, this);
333
+ }
334
+
335
+ static readonly runtime: typeof proto3 = proto3;
336
+ static readonly typeName = "inari.agent.v1.ConnectRequest";
337
+ static readonly fields: FieldList = proto3.util.newFieldList(() => [
338
+ { no: 1, name: "event", kind: "message", T: Event },
339
+ ]);
340
+
341
+ static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): ConnectRequest {
342
+ return new ConnectRequest().fromBinary(bytes, options);
343
+ }
344
+
345
+ static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): ConnectRequest {
346
+ return new ConnectRequest().fromJson(jsonValue, options);
347
+ }
348
+
349
+ static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): ConnectRequest {
350
+ return new ConnectRequest().fromJsonString(jsonString, options);
351
+ }
352
+
353
+ static equals(a: ConnectRequest | PlainMessage<ConnectRequest> | undefined, b: ConnectRequest | PlainMessage<ConnectRequest> | undefined): boolean {
354
+ return proto3.util.equals(ConnectRequest, a, b);
355
+ }
356
+ }
357
+
358
+ /**
359
+ * ConnectResponse carries one Event from gateway to agent on the stream.
360
+ *
361
+ * @generated from message inari.agent.v1.ConnectResponse
362
+ */
363
+ export class ConnectResponse extends Message<ConnectResponse> {
364
+ /**
365
+ * @generated from field: inari.agent.v1.Event event = 1;
366
+ */
367
+ event?: Event;
368
+
369
+ constructor(data?: PartialMessage<ConnectResponse>) {
370
+ super();
371
+ proto3.util.initPartial(data, this);
372
+ }
373
+
374
+ static readonly runtime: typeof proto3 = proto3;
375
+ static readonly typeName = "inari.agent.v1.ConnectResponse";
376
+ static readonly fields: FieldList = proto3.util.newFieldList(() => [
377
+ { no: 1, name: "event", kind: "message", T: Event },
378
+ ]);
379
+
380
+ static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): ConnectResponse {
381
+ return new ConnectResponse().fromBinary(bytes, options);
382
+ }
383
+
384
+ static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): ConnectResponse {
385
+ return new ConnectResponse().fromJson(jsonValue, options);
386
+ }
387
+
388
+ static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): ConnectResponse {
389
+ return new ConnectResponse().fromJsonString(jsonString, options);
390
+ }
391
+
392
+ static equals(a: ConnectResponse | PlainMessage<ConnectResponse> | undefined, b: ConnectResponse | PlainMessage<ConnectResponse> | undefined): boolean {
393
+ return proto3.util.equals(ConnectResponse, a, b);
394
+ }
395
+ }
396
+