Much better responses from the various functions

[TwitchBronBron]

Sometimes roku-deploy just returns a string as the response from doing something. That's not overly helpful. We should do a much better job return a structured response/status object so the callers can make more informed decisions about this stuff.

Problems to solve:

• roku has info, warn, error stuff. we're not logging those. we should. So if we're gonna throw, we should log better reasons why.
• our tools like vscode are likely not taking advantage of this when it could. we're just looking at "it threw" and logging it. We should try passing along info, warn, error stuff to the console.

We might need to append rokuMessages to every error.

interface RokuDeployError {
    message: string;
    stack: any;
    rokuMessages: RokuMessages;
}

[Christian-Holbrook]

Unified Error & Response Handling for v4

Combines #186, #69, #122

Design

1. All errors extend RokuDeployError base class with a typed details property
2. details contains:
   - httpResponse - the raw response from the device
   - rokuMessages - parsed { errors[], infos[], successes[] } from device
   - Additional context specific to the error type
3. Functions return structured objects instead of primitives

Code Examples:

  // Base class for all errors - typed `details` replaces inconsistent 
  `results`                          
  class RokuDeployError<T> extends Error {
      constructor(message: string, public readonly details?: T) {}
  }

  // All device errors include httpResponse + rokuMessages
  interface DeviceErrorDetails {
      httpResponse?: { response: Response; body: any };
      rokuMessages?: { errors: string[]; infos: string[]; successes: string[] };
  }

  // Example error classes
  class CompileError extends RokuDeployError<DeviceErrorDetails> {}
  class UnauthorizedDeviceResponseError extends RokuDeployError<DeviceErrorDetails> {}

Example: Before/After

  // === CATCHING ERRORS ===

  // Before (v3)
  try {
      await rokuDeploy.sideload(options);
  } catch (e) {
      if (e.results?.response) {
          console.log(e.results.body);
      }
  }

  // After (v4)
  try {
      await rokuDeploy.sideload(options);
  } catch (e) {
      if (e instanceof CompileError) {
          console.log(e.details.rokuMessages.errors); // ['syntax error line 42']
          console.log(e.details.httpResponse.body);   // raw HTML
      }
  }

  // === FUNCTION RETURNS ===

  // Before (v3)
  const pkgPath = await rokuDeploy.createSignedPackage(options);
  // pkgPath = "/path/to/app.pkg"

  // After (v4)
  const result = await rokuDeploy.createSignedPackage(options);
  // result = { pkgPath: "/path/to/app.pkg", appName: "MyApp" }

[TwitchBronBron]

For network-related errors, let's include some basic info. Normalized for our needs, and NOT specific to our underlying networking library, we want to abstract that away:

• url
• method
• headers (maybe just Record<string, string>)
• status code
• body (as a buffer? string?)

[TwitchBronBron]

Should also pass along RokuMessages that were encountered during the request process. and ifgure out where those should live on the error object.