4.4.69: Query parameter correctness, improved async upload error handling, and published integration guides

Highlights

• Fixes query parameter generation so 0 is no longer dropped, preventing subtle bugs in pagination/limit/offset and other numeric params.
• Improves uploadAsyncMethod error semantics by converting structured Fjell error responses into FjellHttpError (with status and request context), aligning behavior with the rest of the HTTP API surface.
• Adds and ships “agentic” usage/integration guides in the npm package, making integration patterns easier to follow without reading internal source.

Bug fixes

Query parameters: preserve numeric zero (and handle empty strings more predictably)

• generateQueryParameters now:
  • Includes numeric 0 values in the query string (e.g. ?limit=0&offset=0).
  • Filters out undefined values (as before).
  • Filters out empty-string values (e.g. { city: "" } will not be emitted).
  • Ensures boolean false is encoded as the literal string false.

Impact

• This affects every call site that builds URLs via generateQueryParameters, including core HTTP methods and file upload paths (e.g. src/api/http.ts, src/api/httpFile.ts, and async upload).

Async upload: structured Fjell errors now throw FjellHttpError

• uploadAsyncMethod now detects structured Fjell error payloads on HTTP status >= 400 and throws a FjellHttpError when the server returns either:
  • Wrapped shape: { success: false, error: ErrorInfo }
  • Direct shape: ErrorInfo
• When the body is not JSON / not structured, it falls back to a generic Error("Upload failed with status X").

Impact

• Consumers can now reliably catch FjellHttpError for structured server errors and access status + error details, similar to other methods in this package.

Documentation (included in published package)

• Added new guides under guide/:
  • guide/index.md
  • guide/usage.md
  • guide/integration.md
• Updated .npmignore so that guide/** is included in the npm tarball, even though *.md is generally ignored.

Dependencies

• Updated dependencies and refreshed package-lock.json.
• Notably:
  • @fjell/core is now ^4.4.79
  • @fjell/logging is now ^4.4.72

Tests

• Added coverage to verify:
  • Query params preserve 0 values.
  • uploadAsyncMethod throws FjellHttpError for structured Fjell error bodies and uses a generic error message for unstructured failures.

Breaking changes / upgrade notes

• No public API signature changes were detected.
• Behavior change to be aware of: if you previously relied on uploadAsyncMethod throwing only generic Error instances on HTTP >= 400, you may now receive FjellHttpError when the server returns a structured Fjell error body. Adjust error handling to check instanceof FjellHttpError (or your existing Fjell error utilities) if needed.