refactor: centralize API error handling in ky client

[Paveltarno]

Description

This PR refactors API error handling by introducing a centralized ApiError.fromHttpError() method that converts HTTP client errors into structured ApiError instances. Previously, API methods used inconsistent patterns for error handling. Now, all API calls use a standardized try-catch pattern with ApiError.fromHttpError(), which automatically extracts status codes, formats error messages from response bodies, and adds contextual information about which operation failed.

Related Issue

Addresses refactoring discussed in #112: #112 (comment)

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• Added ApiError.fromHttpError() static method in src/core/errors.ts to convert HTTP errors to ApiError with context
• Moved formatApiError() function from src/core/clients/base44-client.ts to src/core/errors.ts (now internal)
• Added HttpErrorLike interface and isHttpError() type guard for safe error parsing
• Removed formatApiError and API error types from src/core/clients/index.ts exports
• Updated all API methods in agent/api.ts, entity/api.ts, function/api.ts, project/api.ts, and site/api.ts to use try-catch with ApiError.fromHttpError()
• Preserved special 428 status code handling in entity/api.ts using ky's HTTPError type
• Updated ApiErrorResponseSchema naming in schemas.ts for clarity
• Updated test expectations to match new error message format
• Added comprehensive JSDoc comments explaining the new error handling approach
• Added detailed error handling pattern documentation to AGENTS.md

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated AGENTS.md if I made architectural changes

Additional Notes

This refactoring improves error handling consistency across all API operations while maintaining identical functionality from the consumer's perspective. The new ApiError.fromHttpError() method provides better error context by including the operation name in error messages (e.g., "Error syncing agents" instead of generic error messages). The change reduces code duplication and makes it easier to maintain consistent error handling patterns as new API methods are added.

---

_{🤖 Generated by Claude | 2026-02-01 00:00 UTC}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.0.25-pr.135.55d3e79

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.0.25-pr.135.55d3e79"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.0.25-pr.135.55d3e79"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.0.25-pr.135.55d3e79
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.