`upload()` silently accepts a legacy `account` param after the `signer` rename — fails deep with `TypeError: Cannot read properties of undefined (reading 'accountAddress')`

[salch-cred]

Summary

ShelbyNodeClient.upload() does not validate its params object. Between v0.3.1 and v0.8.0 the
signer param was renamed from account to signer, but code written against the v0.3.1 API (or
copied from v0.3.1-era JSDoc, whose examples literally show account: signer) passes account.
The key is silently ignored, params.signer is undefined, and the call fails deep inside
registerBlob with a cryptic TypeError instead of a clear "missing required param" error.

This is easy to hit in practice: ^0.3.1 in package.json resolves to 0.8.0 on a fresh
npm install, so existing consumers get the rename without any signal.

Environment

• @shelby-protocol/sdk: 0.3.1 (works) / 0.8.0 (fails) — verified against both tarballs from npm
• @aptos-labs/ts-sdk: 6.x
• Environment: Node.js 24, ShelbyNodeClient from @shelby-protocol/sdk/node
• Network: Shelbynet

Reproduction

import { ShelbyNodeClient } from "@shelby-protocol/sdk/node";
import { Network, Ed25519Account, Ed25519PrivateKey } from "@aptos-labs/ts-sdk";

const account = new Ed25519Account({ privateKey: new Ed25519PrivateKey(PRIV_KEY) });
const client = new ShelbyNodeClient({ network: Network.SHELBYNET, apiKey: API_KEY });

// v0.3.1-style call (matches v0.3.1 JSDoc examples: `account: signer`)
await client.upload({
  account,                      // ← legacy key, silently ignored in 0.8.0
  blobData: new Uint8Array(1024),
  blobName: "demo.bin",
  expirationMicros: (Date.now() + 90 * 864e5) * 1000,
});

Actual result

TypeError: Cannot read properties of undefined (reading 'accountAddress')
    at ShelbyNodeClient.registerBlob (dist/node/clients/ShelbyNodeClient.mjs:1252:34)

Nothing indicates the caller used the wrong key name.

Expected result

A validation error at the API boundary, e.g.:

Error: upload(): missing required param 'signer'. Note: 'account' was renamed to 'signer' in v0.4.0.

Evidence (from the published npm tarballs)

• v0.3.1 — dist/node/index.mjs (~line 1251): the coordination layer reads
  signer: params.account, and the JSDoc examples show account: signer.
• v0.8.0 — dist/node/clients/ShelbyNodeClient.mjs:
  • upload() (~line 3040) maps account: params.signer
  • registerBlob() (~line 1252) dereferences params.account.accountAddress with no
    undefined-check → the TypeError above when signer was never provided.

Suggested fix

1. Validate required params at the entry point of public methods (upload, download, …) and
   throw a named, actionable error.
2. Detect the legacy account key specifically and emit a targeted migration message
   ('account' was renamed to 'signer' in v0.4.0).
3. Optionally accept account as a deprecated alias for one minor cycle with a console.warn,
   since ^0.3.x ranges auto-upgrade consumers into the rename.
4. Add a repository field (and CHANGELOG entry for the rename) to the npm package so
   npm repo/npm docs resolve and breaking param changes are discoverable.

Context

We hit this integrating Shelby into Provenode, a
verifiable AI model lifecycle platform running real workloads on Shelbynet (blob storage +
ShelbyUSD micropayments + Move anchoring). Happy to test a patched build against our pipeline.

[salch-cred]

Correction to the version story above

I re-verified against the installed tarballs and the rename claim in my original report is wrong:

• v0.3.1 upload() reads params.signer (dist/node/clients/ShelbyNodeClient.mjs ~line 2698: account: params.signer.accountAddress, ~2708: account: params.signer)
• v0.8.0 upload() also reads params.signer (~line 3040)

So there was no account → signer rename at the upload() level — both versions expect signer. Apologies for the misdiagnosis.

What still stands (and is, IMO, the actual bug)

Passing the legacy/coordination-style account key to upload() is silently accepted in both versions and fails deep with the same cryptic error:

TypeError: Cannot read properties of undefined (reading 'accountAddress')
    at ShelbyNodeClient.registerBlob (dist/node/clients/ShelbyNodeClient.mjs:1252)

The trap is real because the SDK's own JSDoc examples for the coordination layer (getBlobMetadata, registerBlob) use account: naming — e.g. v0.3.1 dist/node/index.mjs ~line 1216 shows * account: signer, — so copying from the in-repo examples leads you straight into the wrong key, with zero validation at the public API boundary.

One more DX finding

@shelby-protocol/sdk does not export its ./package.json subpath, so consumers can't even check the installed version programmatically:

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './package.json' is not defined by "exports"

Revised suggested fix (unchanged in spirit)

1. Validate required params at the entry point of public methods (upload, download, …) and throw a named, actionable error (e.g. upload(): missing required param 'signer').
2. Detect the account key specifically and emit a targeted hint (did you mean 'signer'? see JSDoc vs coordination-layer examples).
3. Add the repository field + export ./package.json so version checks and bug reports like this one are easier.

Happy to test a patched build against our production pipeline (Provenode, real Shelbynet workloads).