@leavepulse/control-sdk 0.3.31

package/runtime/realtime_pb/leavepulse/realtime/v1/ws_pb.ts

@@ -0,0 +1,464 @@
+// @generated by protoc-gen-es v2.2.3 with parameter "target=ts,import_extension=js"
+// @generated from file leavepulse/realtime/v1/ws.proto (package leavepulse.realtime.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file leavepulse/realtime/v1/ws.proto.
+ */
+export const file_leavepulse_realtime_v1_ws: GenFile =
+	/*@__PURE__*/
+	fileDesc(
+		"Ch9sZWF2ZXB1bHNlL3JlYWx0aW1lL3YxL3dzLnByb3RvEhZsZWF2ZXB1bHNlLnJlYWx0aW1lLnYxIskCCgtDbGllbnRGcmFtZRIsCgRhdXRoGAEgASgLMhwubGVhdmVwdWxzZS5yZWFsdGltZS52MS5BdXRoSAASNgoJc3Vic2NyaWJlGAIgASgLMiEubGVhdmVwdWxzZS5yZWFsdGltZS52MS5TdWJzY3JpYmVIABI6Cgt1bnN1YnNjcmliZRgDIAEoCzIjLmxlYXZlcHVsc2UucmVhbHRpbWUudjEuVW5zdWJzY3JpYmVIABIuCgVpbnB1dBgEIAEoCzIdLmxlYXZlcHVsc2UucmVhbHRpbWUudjEuSW5wdXRIABIyCgdyZXF1ZXN0GAUgASgLMh8ubGVhdmVwdWxzZS5yZWFsdGltZS52MS5SZXF1ZXN0SAASLAoEcGluZxgGIAEoCzIcLmxlYXZlcHVsc2UucmVhbHRpbWUudjEuUGluZ0gAQgYKBGJvZHkiFQoEQXV0aBINCgV0b2tlbhgBIAEoCSIaCglTdWJzY3JpYmUSDQoFdG9waWMYASABKAkiHAoLVW5zdWJzY3JpYmUSDQoFdG9waWMYASABKAkiKQoFSW5wdXQSEgoKc2Vzc2lvbl9pZBgBIAEoCRIMCgRkYXRhGAIgASgMIjYKB1JlcXVlc3QSCgoCaWQYASABKAkSDgoGbWV0aG9kGAIgASgJEg8KB3BheWxvYWQYAyABKAwiBgoEUGluZyL/AgoLU2VydmVyRnJhbWUSMgoHd2VsY29tZRgBIAEoCzIfLmxlYXZlcHVsc2UucmVhbHRpbWUudjEuV2VsY29tZUgAEjgKCnN1YnNjcmliZWQYAiABKAsyIi5sZWF2ZXB1bHNlLnJlYWx0aW1lLnYxLlN1YnNjcmliZWRIABI8Cgx1bnN1YnNjcmliZWQYAyABKAsyJC5sZWF2ZXB1bHNlLnJlYWx0aW1lLnYxLlVuc3Vic2NyaWJlZEgAEi4KBWV2ZW50GAQgASgLMh0ubGVhdmVwdWxzZS5yZWFsdGltZS52MS5FdmVudEgAEi4KBXJlcGx5GAUgASgLMh0ubGVhdmVwdWxzZS5yZWFsdGltZS52MS5SZXBseUgAEi4KBWVycm9yGAYgASgLMh0ubGVhdmVwdWxzZS5yZWFsdGltZS52MS5FcnJvckgAEiwKBHBpbmcYByABKAsyHC5sZWF2ZXB1bHNlLnJlYWx0aW1lLnYxLlBpbmdIAEIGCgRib2R5IjAKB1dlbGNvbWUSFQoNYXV0aGVudGljYXRlZBgBIAEoCBIOCgZ0b3BpY3MYAiADKAkiGwoKU3Vic2NyaWJlZBINCgV0b3BpYxgBIAEoCSIdCgxVbnN1YnNjcmliZWQSDQoFdG9waWMYASABKAkiOAoFRXZlbnQSDQoFdG9waWMYASABKAkSEgoKc2Vzc2lvbl9pZBgCIAEoCRIMCgRkYXRhGAMgASgMIlIKBVJlcGx5EgoKAmlkGAEgASgJEg8KB3BheWxvYWQYAiABKAwSLAoFZXJyb3IYAyABKAsyHS5sZWF2ZXB1bHNlLnJlYWx0aW1lLnYxLkVycm9yIkEKBUVycm9yEgwKBGNvZGUYASABKAkSDwoHbWVzc2FnZRgCIAEoCRINCgV0b3BpYxgDIAEoCRIKCgJpZBgEIAEoCUICUAFiBnByb3RvMw",
+	);
+
+/**
+ * @generated from message leavepulse.realtime.v1.ClientFrame
+ */
+export type ClientFrame = Message<"leavepulse.realtime.v1.ClientFrame"> & {
+	/**
+	 * @generated from oneof leavepulse.realtime.v1.ClientFrame.body
+	 */
+	body:
+		| {
+				/**
+				 * @generated from field: leavepulse.realtime.v1.Auth auth = 1;
+				 */
+				value: Auth;
+				case: "auth";
+		  }
+		| {
+				/**
+				 * @generated from field: leavepulse.realtime.v1.Subscribe subscribe = 2;
+				 */
+				value: Subscribe;
+				case: "subscribe";
+		  }
+		| {
+				/**
+				 * @generated from field: leavepulse.realtime.v1.Unsubscribe unsubscribe = 3;
+				 */
+				value: Unsubscribe;
+				case: "unsubscribe";
+		  }
+		| {
+				/**
+				 * Bidirectional session: a chunk of client->server stream data (e.g. console
+				 * stdin). session_id scopes it to one owned session.
+				 *
+				 * @generated from field: leavepulse.realtime.v1.Input input = 4;
+				 */
+				value: Input;
+				case: "input";
+		  }
+		| {
+				/**
+				 * One-shot request/reply (e.g. "restart this container"). Correlated by id.
+				 *
+				 * @generated from field: leavepulse.realtime.v1.Request request = 5;
+				 */
+				value: Request;
+				case: "request";
+		  }
+		| {
+				/**
+				 * @generated from field: leavepulse.realtime.v1.Ping ping = 6;
+				 */
+				value: Ping;
+				case: "ping";
+		  }
+		| { case: undefined; value?: undefined };
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.ClientFrame.
+ * Use `create(ClientFrameSchema)` to create a new message.
+ */
+export const ClientFrameSchema: GenMessage<ClientFrame> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 0);
+
+/**
+ * Present a JWT to upgrade the socket from anonymous to authenticated. Required
+ * before subscribing to a private topic or opening a session. Mirrors the
+ * existing JSON {op:"auth", token} frame.
+ *
+ * @generated from message leavepulse.realtime.v1.Auth
+ */
+export type Auth = Message<"leavepulse.realtime.v1.Auth"> & {
+	/**
+	 * @generated from field: string token = 1;
+	 */
+	token: string;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Auth.
+ * Use `create(AuthSchema)` to create a new message.
+ */
+export const AuthSchema: GenMessage<Auth> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 1);
+
+/**
+ * @generated from message leavepulse.realtime.v1.Subscribe
+ */
+export type Subscribe = Message<"leavepulse.realtime.v1.Subscribe"> & {
+	/**
+	 * @generated from field: string topic = 1;
+	 */
+	topic: string;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Subscribe.
+ * Use `create(SubscribeSchema)` to create a new message.
+ */
+export const SubscribeSchema: GenMessage<Subscribe> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 2);
+
+/**
+ * @generated from message leavepulse.realtime.v1.Unsubscribe
+ */
+export type Unsubscribe = Message<"leavepulse.realtime.v1.Unsubscribe"> & {
+	/**
+	 * @generated from field: string topic = 1;
+	 */
+	topic: string;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Unsubscribe.
+ * Use `create(UnsubscribeSchema)` to create a new message.
+ */
+export const UnsubscribeSchema: GenMessage<Unsubscribe> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 3);
+
+/**
+ * A chunk of upstream session data. data is opaque bytes (the session's own
+ * payload type, e.g. raw stdin); the gateway forwards it to the owning service
+ * without interpreting it.
+ *
+ * @generated from message leavepulse.realtime.v1.Input
+ */
+export type Input = Message<"leavepulse.realtime.v1.Input"> & {
+	/**
+	 * @generated from field: string session_id = 1;
+	 */
+	sessionId: string;
+
+	/**
+	 * @generated from field: bytes data = 2;
+	 */
+	data: Uint8Array;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Input.
+ * Use `create(InputSchema)` to create a new message.
+ */
+export const InputSchema: GenMessage<Input> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 4);
+
+/**
+ * A correlated request the owning service answers with exactly one Reply. method
+ * names the operation; payload is the request's own protobuf message, opaque to
+ * the gateway (it routes by method to the registered handler).
+ *
+ * @generated from message leavepulse.realtime.v1.Request
+ */
+export type Request = Message<"leavepulse.realtime.v1.Request"> & {
+	/**
+	 * client-chosen correlation id, echoed in Reply
+	 *
+	 * @generated from field: string id = 1;
+	 */
+	id: string;
+
+	/**
+	 * registered request method, e.g. "container.restart"
+	 *
+	 * @generated from field: string method = 2;
+	 */
+	method: string;
+
+	/**
+	 * @generated from field: bytes payload = 3;
+	 */
+	payload: Uint8Array;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Request.
+ * Use `create(RequestSchema)` to create a new message.
+ */
+export const RequestSchema: GenMessage<Request> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 5);
+
+/**
+ * @generated from message leavepulse.realtime.v1.Ping
+ */
+export type Ping = Message<"leavepulse.realtime.v1.Ping"> & {};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Ping.
+ * Use `create(PingSchema)` to create a new message.
+ */
+export const PingSchema: GenMessage<Ping> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 6);
+
+/**
+ * @generated from message leavepulse.realtime.v1.ServerFrame
+ */
+export type ServerFrame = Message<"leavepulse.realtime.v1.ServerFrame"> & {
+	/**
+	 * @generated from oneof leavepulse.realtime.v1.ServerFrame.body
+	 */
+	body:
+		| {
+				/**
+				 * @generated from field: leavepulse.realtime.v1.Welcome welcome = 1;
+				 */
+				value: Welcome;
+				case: "welcome";
+		  }
+		| {
+				/**
+				 * @generated from field: leavepulse.realtime.v1.Subscribed subscribed = 2;
+				 */
+				value: Subscribed;
+				case: "subscribed";
+		  }
+		| {
+				/**
+				 * @generated from field: leavepulse.realtime.v1.Unsubscribed unsubscribed = 3;
+				 */
+				value: Unsubscribed;
+				case: "unsubscribed";
+		  }
+		| {
+				/**
+				 * A topic event (fanout) OR a downstream session event. data is the topic's
+				 * own protobuf payload (e.g. LogChunk for control.logs), opaque here.
+				 *
+				 * @generated from field: leavepulse.realtime.v1.Event event = 4;
+				 */
+				value: Event;
+				case: "event";
+		  }
+		| {
+				/**
+				 * The answer to a ClientFrame.Request, correlated by id.
+				 *
+				 * @generated from field: leavepulse.realtime.v1.Reply reply = 5;
+				 */
+				value: Reply;
+				case: "reply";
+		  }
+		| {
+				/**
+				 * @generated from field: leavepulse.realtime.v1.Error error = 6;
+				 */
+				value: Error;
+				case: "error";
+		  }
+		| {
+				/**
+				 * @generated from field: leavepulse.realtime.v1.Ping ping = 7;
+				 */
+				value: Ping;
+				case: "ping";
+		  }
+		| { case: undefined; value?: undefined };
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.ServerFrame.
+ * Use `create(ServerFrameSchema)` to create a new message.
+ */
+export const ServerFrameSchema: GenMessage<ServerFrame> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 7);
+
+/**
+ * Sent once on connect. authenticated reflects whether a valid token was
+ * presented at upgrade (via query/header) before any Auth frame.
+ *
+ * @generated from message leavepulse.realtime.v1.Welcome
+ */
+export type Welcome = Message<"leavepulse.realtime.v1.Welcome"> & {
+	/**
+	 * @generated from field: bool authenticated = 1;
+	 */
+	authenticated: boolean;
+
+	/**
+	 * Static topics the client may subscribe to without parameters (advisory; the
+	 * authoritative manifest is served over HTTP at /realtime/topics).
+	 *
+	 * @generated from field: repeated string topics = 2;
+	 */
+	topics: string[];
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Welcome.
+ * Use `create(WelcomeSchema)` to create a new message.
+ */
+export const WelcomeSchema: GenMessage<Welcome> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 8);
+
+/**
+ * @generated from message leavepulse.realtime.v1.Subscribed
+ */
+export type Subscribed = Message<"leavepulse.realtime.v1.Subscribed"> & {
+	/**
+	 * @generated from field: string topic = 1;
+	 */
+	topic: string;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Subscribed.
+ * Use `create(SubscribedSchema)` to create a new message.
+ */
+export const SubscribedSchema: GenMessage<Subscribed> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 9);
+
+/**
+ * @generated from message leavepulse.realtime.v1.Unsubscribed
+ */
+export type Unsubscribed = Message<"leavepulse.realtime.v1.Unsubscribed"> & {
+	/**
+	 * @generated from field: string topic = 1;
+	 */
+	topic: string;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Unsubscribed.
+ * Use `create(UnsubscribedSchema)` to create a new message.
+ */
+export const UnsubscribedSchema: GenMessage<Unsubscribed> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 10);
+
+/**
+ * A payload pushed to the client. For fanout topics topic is set; for session
+ * downstream session_id is set instead. data is the channel's own protobuf
+ * message (the client decodes it by the channel's declared payload type).
+ *
+ * @generated from message leavepulse.realtime.v1.Event
+ */
+export type Event = Message<"leavepulse.realtime.v1.Event"> & {
+	/**
+	 * set for fanout topics ("" for session events)
+	 *
+	 * @generated from field: string topic = 1;
+	 */
+	topic: string;
+
+	/**
+	 * set for session events ("" for fanout)
+	 *
+	 * @generated from field: string session_id = 2;
+	 */
+	sessionId: string;
+
+	/**
+	 * @generated from field: bytes data = 3;
+	 */
+	data: Uint8Array;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Event.
+ * Use `create(EventSchema)` to create a new message.
+ */
+export const EventSchema: GenMessage<Event> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 11);
+
+/**
+ * The single answer to a Request. Exactly one of payload / error is meaningful.
+ *
+ * @generated from message leavepulse.realtime.v1.Reply
+ */
+export type Reply = Message<"leavepulse.realtime.v1.Reply"> & {
+	/**
+	 * echoes Request.id
+	 *
+	 * @generated from field: string id = 1;
+	 */
+	id: string;
+
+	/**
+	 * @generated from field: bytes payload = 2;
+	 */
+	payload: Uint8Array;
+
+	/**
+	 * @generated from field: leavepulse.realtime.v1.Error error = 3;
+	 */
+	error?: Error;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Reply.
+ * Use `create(ReplySchema)` to create a new message.
+ */
+export const ReplySchema: GenMessage<Reply> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 12);
+
+/**
+ * A transport-level error (bad token, permission denied, unknown topic, ...).
+ * topic/id are set when the error pertains to a specific subscribe/request.
+ *
+ * @generated from message leavepulse.realtime.v1.Error
+ */
+export type Error = Message<"leavepulse.realtime.v1.Error"> & {
+	/**
+	 * stable machine code, e.g. "permission_denied"
+	 *
+	 * @generated from field: string code = 1;
+	 */
+	code: string;
+
+	/**
+	 * human-readable detail
+	 *
+	 * @generated from field: string message = 2;
+	 */
+	message: string;
+
+	/**
+	 * @generated from field: string topic = 3;
+	 */
+	topic: string;
+
+	/**
+	 * request id, when the error answers a Request
+	 *
+	 * @generated from field: string id = 4;
+	 */
+	id: string;
+};
+
+/**
+ * Describes the message leavepulse.realtime.v1.Error.
+ * Use `create(ErrorSchema)` to create a new message.
+ */
+export const ErrorSchema: GenMessage<Error> =
+	/*@__PURE__*/
+	messageDesc(file_leavepulse_realtime_v1_ws, 13);

package/runtime/resource.ts

@@ -0,0 +1,84 @@
+// LeavePulse SDK — base resource.
+//
+// Generated resource classes extend this. It holds the backing data, supports
+// in-place hydration for the identity map, and computes runtime capabilities
+// (RFC 0001 §4): a static capability is "usable" only if the user's
+// permissions carry it. Getters here never touch the network.
+//
+// Wrapped responses (RFC §3.1 x-sdk-data-root, e.g.
+// `{ project: {id, ...}, servers: [...] }`) are normalized by the client
+// BEFORE a resource is constructed: the core object is unwrapped and sibling
+// fields (links) are merged onto it. So a resource always sees a flat object
+// with `id` at the top level — the data root never leaks into runtime.
+
+import type { Identified } from "./cache";
+
+/** Extract an instance id from a payload. Resources key on different fields:
+ * most use `id`, some use a domain id (`user_id`). When `idPath` is given the
+ * id lives at a nested path (`["summary", "id"]` for an envelope), so we walk it
+ * directly. Otherwise: top-level `id`, then the first `*_id` field, so identity
+ * mapping works regardless of the schema's id name. */
+export function extractId(
+	data: Record<string, unknown>,
+	idPath?: readonly string[],
+): string | number {
+	if (idPath && idPath.length > 0) {
+		let cursor: unknown = data;
+		for (const segment of idPath) {
+			if (cursor == null || typeof cursor !== "object") return "";
+			cursor = (cursor as Record<string, unknown>)[segment];
+		}
+		return typeof cursor === "string" || typeof cursor === "number"
+			? cursor
+			: "";
+	}
+	const direct = data.id;
+	if (typeof direct === "string" || typeof direct === "number") return direct;
+	for (const [key, value] of Object.entries(data)) {
+		if (
+			key.endsWith("_id") &&
+			(typeof value === "string" || typeof value === "number")
+		) {
+			return value;
+		}
+	}
+	return "";
+}
+
+export abstract class Resource<TData extends Record<string, unknown>>
+	implements Identified
+{
+	protected data: TData;
+
+	constructor(data: TData) {
+		this.data = data;
+	}
+
+	get id(): string | number {
+		return extractId(this.data);
+	}
+
+	/** Replace backing data in place (identity map refresh). */
+	_hydrate(data: unknown): void {
+		this.data = data as TData;
+	}
+
+	/** Snapshot of the backing data (always from memory). */
+	toJSON(): TData {
+		return this.data;
+	}
+
+	/**
+	 * Whether the current principal may perform `capability` on this instance:
+	 * the static capability must exist AND the permission must be granted in the
+	 * resource's payload. Emitters expose this as `can_<capability>` getters.
+	 */
+	protected hasCapability(
+		_capability: string,
+		permissionCode: string,
+	): boolean {
+		const perms = (this.data as { user_permissions?: unknown })
+			.user_permissions;
+		return Array.isArray(perms) && perms.includes(permissionCode);
+	}
+}

package/runtime/snowflake.ts

@@ -0,0 +1,7 @@
+// A 64-bit Snowflake id, carried as a string in TypeScript: the value exceeds
+// JS's safe-integer range (2^53), so a `number` would silently lose its low
+// digits. Backends keep it an int64; only the JS representation is a string.
+//
+// Kept as a plain alias (not a branded type) so ids interoperate with ordinary
+// string handling — template URLs, equality, Map keys — without ceremony.
+export type Snowflake = string;