11 - IPC Reference

This document lists the preload-exposed desktop API surface used by the renderer.

Bridge Entry Point

Preload exposes a single object on window:

• desktopApi

All methods return promises.

Method Catalog

Method	Payload	Returns	Purpose
sendRequest	RequestPayload	SendRequestResult	Execute HTTP request in main process
getLibrarySnapshot	none	OperationResult<LibrarySnapshot>	Read configured library tree
chooseLibraryRoot	none	OperationResult<LibrarySnapshot>	Open folder picker and set root
loadRequest	relativePath: string	OperationResult<LoadedRequestRecord>	Load request YAML + body text
saveRequest	SaveRequestInput	OperationResult<SaveRequestResult>	Save or duplicate request
createFolder	parentFolderPath: string, name: string	OperationResult<LibraryMutationResult>	Create new folder
renameEntry	relativePath: string, newName: string	OperationResult<LibraryMutationResult>	Rename folder or request
deleteEntry	relativePath: string	OperationResult<LibraryMutationResult>	Delete folder or request
pickOpenApiFile	none	string | null	Open file picker for import source
previewOpenApiImport	OpenApiImportInput	OperationResult<OpenApiImportPreview>	Build import preview only
importOpenApi	OpenApiImportInput + mode	OperationResult<OpenApiImportResult>	Apply import mutation

Shared Result Wrappers

Most methods use:

• OperationResult<T>
  • ok: true with data
  • ok: false with error

Request send uses dedicated result:

• SendRequestResult
  • success: response payload
  • failure: error + duration

Error Shape

ResponseError contains:

• message (always)
• details (optional)

Request Execution Payload

RequestPayload fields:

• method
• url
• contextFolderPath
• headers
• body
• optional script fields

Response Execution Payload

ResponsePayload fields:

• status, statusText
• headers
• body
• durationMs
• url
• optional script test fields

Notes for Contributors

1. Keep all cross-process contracts in src/lib/contracts.ts.
2. Add handler in main process and preload bridge method together.
3. Prefer OperationResult<T> for non-request commands.
4. Return actionable error messages for UI feedback.