Bug Report — Two API Failures with SDK `v0.1.1`

[shwetank-dev]

Bug Report — Two API Failures with SDK v0.1.1

Date: 2026-02-18
SDK: @nimblebrain/mpak-sdk@0.1.1

---

Environment

Field	Value
OS	macOS Darwin 24.5.0 (ARM64 / Apple Silicon)
Machine	Shwetanks-Mac-mini.local
Node.js	v22.12.0
npm	10.9.0
SDK version	@nimblebrain/mpak-sdk@0.1.1
Default registry	https://api.mpak.dev

---

Bug 1 — searchBundles returns MpakNetworkError for HTTP 404 (wrong error class)

What the docs say should happen (README.md lines 28–33):

const results = await client.searchBundles({ q: 'mcp', limit: 10 });
// → returns an object with a `bundles` array
for (const bundle of results.bundles) {
  console.log(`${bundle.name}@${bundle.latest_version}`);
}

What actually happens:

MpakNetworkError: Failed to search bundles: HTTP 404
  code: 'NETWORK_ERROR'
  statusCode: undefined

Root cause (SDK source dist/index.js):

The searchBundles method hits GET /v1/bundles/search — the server returned HTTP 404, and the SDK catches any non-ok response and always throws MpakNetworkError:

if (!response.ok) {
  throw new MpakNetworkError(`Failed to search bundles: HTTP ${response.status}`);
}

Two problems here:

1. Wrong error class. Per the README, MpakNetworkError is for "Network failures, timeouts". A 404 is a server-side logical error, not a network failure. The SDK uses MpakNotFoundError correctly in getBundle, but not in searchBundles.
2. statusCode is always undefined on MpakNetworkError. The MpakNetworkError constructor signature is constructor(message) — it never sets statusCode, so callers can't programmatically inspect the HTTP status from the error object. The status is only embedded in the message string.

---

Bug 2 — getBundle('@nimblebraininc/echo') returns 404 / bundle not found

What the docs say should happen (README.md lines 38–42):

const bundle = await client.getBundle('@nimblebraininc/echo');
console.log(bundle.description);
console.log(`Versions: ${bundle.versions.map(v => v.version).join(', ')}`);

What actually happens:

MpakNotFoundError: Resource not found: @nimblebraininc/echo
  code: 'NOT_FOUND'
  statusCode: 404

The SDK itself documents @nimblebraininc/echo as the canonical example bundle in the README. The bundle either does not exist at GET /v1/bundles/@nimblebraininc/echo, or the scope/name has changed in the registry. This is a docs/registry inconsistency — the example bundle referenced in the SDK's own README cannot be fetched.

---

Summary Table

#	Method	Expected	Actual	Error Type
1	searchBundles({ q: 'mcp', limit: 10 })	{ bundles: [...] }	Throws on HTTP 404 from /v1/bundles/search	MpakNetworkError (should be MpakNotFoundError or empty result)
2	getBundle('@nimblebraininc/echo')	Bundle object with description, versions[]	Bundle does not exist in registry	MpakNotFoundError — README example is stale

---

Steps to Reproduce

1. Create a new directory and initialise a project

mkdir mpak-bug-repro
cd mpak-bug-repro
npm init -y

2. Install the SDK

npm install @nimblebrain/mpak-sdk

3. Create the test file

Create a file named test.mjs with the following content:

import { MpakClient } from '@nimblebrain/mpak-sdk';

const client = new MpakClient();

async function main() {
  // Searching for bundles
  try {
    const results = await client.searchBundles({ q: 'mcp', limit: 10 });

    for (const bundle of results.bundles) {
      console.log(`${bundle.name}@${bundle.latest_version}`);
    }
  } catch (err) {
    console.log('Error while fetching bundles', err);
  }

  // Fetching echo bundle
  try {
    const bundle = await client.getBundle('@nimblebraininc/echo');
    console.log(bundle.description);
    console.log(
      `Versions: ${bundle.versions.map((v) => v.version).join(', ')}`,
    );
  } catch (err) {
    console.log('Error while fetching echo bundle', err);
  }
}

main();

4. Run the file

node test.mjs

5. Observe the output

Error while fetching bundles MpakNetworkError: Failed to search bundles: HTTP 404
    at MpakClient.searchBundles (.../node_modules/@nimblebrain/mpak-sdk/dist/index.js:68:13)
    ...
    code: 'NETWORK_ERROR',
    statusCode: undefined

Error while fetching echo bundle MpakNotFoundError: Resource not found: @nimblebraininc/echo
    at MpakClient.getBundle (.../node_modules/@nimblebrain/mpak-sdk/dist/index.js:80:13)
    ...
    code: 'NOT_FOUND',
    statusCode: 404

---

Bug report generated with the help of Claude Code (claude-sonnet-4-6).

[JoeCardoso13]

Note on PR #7 test coverage gap

PR #7 added an e2e integration test that exercises the full download pipeline (resolve → download → SHA256 verify → extract → validate manifest). Both bugs reported here remain uncaught by that test. Here's why:

Bug 1 (searchBundles throws MpakNetworkError for 404): The e2e test doesn't call searchBundles at all — it only tests getBundleDownload. The searchBundles method has its own error handling code path, and it was simply not covered.

Bug 2 (getBundle('@nimblebraininc/echo') returns 404): The e2e test does use @nimblebraininc/echo as the known bundle, but it calls getBundleDownload, not getBundle. These hit different API endpoints:

• getBundleDownload → GET /v1/bundles/@nimblebraininc/echo/versions/latest/download — works
• getBundle → GET /v1/bundles/@nimblebraininc/echo — returns 404

The bundle exists for download resolution but the detail endpoint returns 404. The e2e test passes because it only exercises the download path.

In short: The e2e test covers one happy path but misses both broken code paths — the search endpoint's error classification, and the bundle detail endpoint for the SDK's own canonical example package. A fix for these two bugs should include test coverage for searchBundles error handling and getBundle on the example bundle.

[mgoldsborough]

Both bugs traced to the same root cause plus one real code issue:

Bug 2 (echo bundle 404): Published v0.1.1 on npm had a wrong default registry URL (https://api.mpak.dev instead of https://registry.mpak.dev). The api.mpak.dev host returns 404 for all /v1/ routes. This was already fixed in source — will be resolved once we publish the next version.

Bug 1 (wrong error class): Two sub-issues:

1. Same wrong default URL caused the 404 in the first place.
2. Real code bug: searchBundles and searchSkills threw MpakNetworkError for all non-ok HTTP responses (including 404), while every other method (getBundle, getBundleVersions, etc.) checks for 404 first and throws MpakNotFoundError. This inconsistency is now fixed — both search methods now handle 404 distinctly.

Fix is in PR #7 (commit f83904f). Will be included in the next npm release.