@procedures/peer 0.0.0-stage → 0.1.0

package/src/types.ts

@@ -0,0 +1,257 @@
+/**
+ * Type definitions for client-server procedures
+ */
+
+// =============================================================================
+// Transport Configuration
+// =============================================================================
+
+export type TransportType = "http" | "websocket" | "local";
+
+export interface HttpTransportConfig {
+  type: "http";
+  port?: number | undefined;
+  host?: string | undefined;
+  basePath?: string | undefined;
+  /** Send CORS headers. The default is false: only `corsOrigins` (or loopback pages) are served to browsers. */
+  cors?: boolean | undefined;
+  /** Browser origins that may call the peer, besides loopback origins */
+  corsOrigins?: string[] | undefined;
+  /** URL strategy: "rest" (default) or "rpc" for /rpc/service/operation format */
+  urlStrategy?: "rest" | "rpc" | undefined;
+  /** A secret that every request must send as `Authorization: Bearer <token>` */
+  token?: string | undefined;
+}
+
+export interface WebSocketTransportConfig {
+  type: "websocket";
+  port?: number | undefined;
+  host?: string | undefined;
+  path?: string | undefined;
+  /** Browser origins that may connect, besides loopback origins */
+  origins?: string[] | undefined;
+  /** A secret that every connection must send as `?token=<token>` (or a bearer header) */
+  token?: string | undefined;
+}
+
+export interface LocalTransportConfig {
+  type: "local";
+}
+
+export type TransportConfig = HttpTransportConfig | WebSocketTransportConfig | LocalTransportConfig;
+
+// =============================================================================
+// server.create Types
+// =============================================================================
+
+export interface ServerCreateInput {
+  /** Transports to enable */
+  transports?: TransportConfig[] | undefined;
+  /** Auto-register all procedures from registry */
+  autoRegister?: boolean | undefined;
+  /** A secret that every request must carry (each transport that has no token of its own gets this one) */
+  token?: string | undefined;
+  /** The procedures to serve: exact keys (`git.status`) or prefixes (`git.*`). Default: every procedure */
+  expose?: string[] | undefined;
+}
+
+export interface ServerCreateOutput {
+  /** Server ID for reference */
+  serverId: string;
+  /** Active transport endpoints */
+  endpoints: Array<{
+    type: TransportType;
+    address: string;
+  }>;
+  /** Number of registered procedures */
+  procedureCount: number;
+}
+
+// =============================================================================
+// server.connect Types
+// =============================================================================
+
+export interface ServerConnectInput {
+  /** Remote server address */
+  address: string;
+  /** Transport type to use */
+  transport?: TransportType | undefined;
+  /** Connection timeout in ms */
+  timeout?: number | undefined;
+}
+
+export interface ProcedureInfo {
+  /** Procedure path */
+  path: string[];
+  /** Description from metadata */
+  description?: string | undefined;
+  /** Input schema as JSON schema */
+  inputSchema?: Record<string, unknown> | undefined;
+  /** Output schema as JSON schema */
+  outputSchema?: Record<string, unknown> | undefined;
+}
+
+export interface ServerConnectOutput {
+  /** Connection ID */
+  connectionId: string;
+  /** Remote peer ID */
+  remotePeerId: string;
+  /** Procedures available on remote */
+  remoteProcedures: ProcedureInfo[];
+}
+
+// =============================================================================
+// server.disconnect Types
+// =============================================================================
+
+export interface ServerDisconnectInput {
+  /** Connection ID to disconnect */
+  connectionId: string;
+}
+
+export interface ServerDisconnectOutput {
+  /** Whether disconnect succeeded */
+  success: boolean;
+}
+
+// =============================================================================
+// manifest.generate Types
+// =============================================================================
+
+export type ManifestFormat = "json" | "typescript";
+
+export interface ManifestGenerateInput {
+  /** Output formats to generate */
+  formats?: ManifestFormat[] | undefined;
+  /** Namespace filter (only include procedures under this path) */
+  namespace?: string[] | undefined;
+  /** Output directory for files */
+  outputDir?: string | undefined;
+}
+
+export interface ManifestGenerateOutput {
+  /** Generated JSON manifest */
+  json?:
+    | {
+        procedures: ProcedureInfo[];
+        generatedAt: string;
+        version: string;
+      }
+    | undefined;
+  /** Generated TypeScript declaration */
+  typescript?: string | undefined;
+  /** Files written if outputDir provided */
+  filesWritten?: string[] | undefined;
+}
+
+// =============================================================================
+// Peer Connection Types
+// =============================================================================
+
+export interface PeerConnection {
+  /** Unique connection ID */
+  id: string;
+  /** Remote peer ID */
+  remotePeerId: string;
+  /** Transport type used */
+  transport: TransportType;
+  /** Connection state */
+  state: "connecting" | "connected" | "disconnected" | "error";
+  /** Remote procedures */
+  remoteProcedures: ProcedureInfo[];
+  /** When connection was established */
+  connectedAt?: Date;
+}
+
+// =============================================================================
+// Procedure Discovery Protocol Messages
+// =============================================================================
+
+export interface ProcedureAnnounceMessage {
+  type: "procedure-announce";
+  peerId: string;
+  procedures: ProcedureInfo[];
+}
+
+export interface ProcedureUpdateMessage {
+  type: "procedure-update";
+  peerId: string;
+  added?: ProcedureInfo[];
+  removed?: string[]; // Procedure paths as strings
+}
+
+// =============================================================================
+// server.start Types
+// =============================================================================
+
+export interface ServerStartInput {
+  /** Port to listen on */
+  port?: number | undefined;
+  /** Host to bind to */
+  host?: string | undefined;
+  /** Transport type */
+  transport?: "http" | "websocket" | "both" | undefined;
+}
+
+export interface ServerStartOutput {
+  /** Whether start succeeded */
+  success: boolean;
+  /** Process ID of server */
+  pid?: number | undefined;
+  /** Port server is running on */
+  port?: number | undefined;
+  /** Endpoint URL */
+  endpoint?: string | undefined;
+  /** Log file path */
+  logFile?: string | undefined;
+  /** Status message */
+  message: string;
+}
+
+// =============================================================================
+// server.stop Types
+// =============================================================================
+
+export interface ServerStopInput {
+  /** Port of server to stop (stops all if omitted) */
+  port?: number | undefined;
+  /** Force kill with SIGKILL instead of SIGTERM */
+  force?: boolean | undefined;
+}
+
+export interface ServerStopOutput {
+  /** Whether stop succeeded */
+  success: boolean;
+  /** Status message */
+  message: string;
+}
+
+// =============================================================================
+// server.status Types
+// =============================================================================
+
+export interface ServerStatusInput {
+  /** Port to check (shows all if omitted) */
+  port?: number | undefined;
+}
+
+export interface ServerStatusOutput {
+  /** Whether server is running */
+  running: boolean;
+  /** Process ID */
+  pid?: number | undefined;
+  /** Port */
+  port?: number | undefined;
+  /** Endpoint URL */
+  endpoint?: string | undefined;
+  /** Transport type */
+  transport?: string | undefined;
+  /** When server started (ISO string) */
+  startedAt?: string | undefined;
+  /** Human-readable uptime */
+  uptime?: string | undefined;
+  /** Log file path */
+  logFile?: string | undefined;
+  /** Status message */
+  message: string;
+}