@v3finance/core-sdk 0.1.0 → 0.2.0

package/dist/cjs/core/pagination.js

@@ -1,6 +1,33 @@
 "use strict";
 /**
- * Keyset pagination. Every list endpoint returns `{items, nextCursor}`.
+ * Keyset pagination — for the eleven endpoints that have it.
+ *
+ * "Every list returns `{items, nextCursor}`" is what this file used to claim,
+ * and it is not what the API does. Counted over the spec snapshot
+ * (`openapi/spec.json`), the reading endpoints fall into three shapes:
+ *
+ *   • 11 GETs take `cursor`/`limit` and answer a `nextCursor` — addresses,
+ *     history, approval requests, members, counterparties, counterparty
+ *     groups, operation categories, operation relations, ledger entries, a
+ *     vault's policies, balances. These are what `paginate` is for;
+ *   • 18 answer `{items}` with NO cursor parameter at all — folders and their
+ *     grants, address shares, shared-with-me / shared-by-me, visibility
+ *     grants, category assignments and their versions, report templates and
+ *     snapshots, user groups and their members, status history, the
+ *     admin-level `/policies` list and one policy's versions (18 paths, two
+ *     of them the older `/address-groups` prefix of the folder endpoints).
+ *     What you get is everything there is; `paginate` over one of them yields
+ *     that single page and stops, because an absent `nextCursor` is the
+ *     end-of-list signal;
+ *   • 8 answer a BARE ARRAY rather than an object: `/networks`, `/tokens`,
+ *     `/vaults`, a vault's `/policy-groups` and `/invitations`, one
+ *     operation's `/relations`, a policy group's `/policies`, a user's
+ *     `/policy-groups`. There is no `items` to walk, so `paginate` refuses
+ *     them by name instead of quietly yielding nothing.
+ *
+ * `/balances` is the one cursored endpoint `paginate` CANNOT walk: its page is
+ * `{vaultId, totals, accounts, nextCursor}` and the array is called
+ * `accounts`. Pass the cursor by hand there.
  *
  * The cursor is opaque: do not parse it, build it or compare it. A
  * `nextCursor` of `null` is the only end-of-list signal — an empty page is
@@ -28,6 +55,14 @@ async function* paginate(fetchPage, options = {}) {
             ...(options.limit === undefined ? {} : { limit: options.limit }),
             ...(cursor === undefined ? {} : { cursor }),
         });
+        // A bare-array endpoint (or `/balances`, whose array is `accounts`) has no
+        // `items`, and `for…of undefined` would report that as an unexplained
+        // TypeError from inside the SDK. Say what is wrong instead.
+        if (!Array.isArray(result.items)) {
+            throw new Error('@v3finance/core-sdk: this response has no `items` array, so it cannot be paged. ' +
+                'Endpoints answering a bare array, and /balances (its array is `accounts`), ' +
+                'are read with a single call — see the note at the top of core/pagination.ts.');
+        }
         for (const item of result.items)
             yield item;
         seen += result.items.length;

package/dist/cjs/core/pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/core/pagination.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;AAcH;;;;;;;;;GASG;AACI,KAAK,SAAS,CAAC,UACpB,SAAmD,EACnD,OAAO,GAA0C,EAAE;IAEnD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAA;IACzC,IAAI,MAA0B,CAAA;IAC9B,IAAI,IAAI,GAAG,CAAC,CAAA;IAEZ,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAY,MAAM,SAAS,CAAC;YACtC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAChE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;SAC5C,CAAC,CAAA;QACF,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK;YAAE,MAAM,IAAI,CAAA;QAC3C,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAA;QAE3B,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;YAAE,OAAM;QACzE,IAAI,MAAM,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CACb,wEAAwE,IAAI,SAAS,CACtF,CAAA;QACH,CAAC;QACD,MAAM,GAAG,MAAM,CAAC,UAAU,CAAA;IAC5B,CAAC;IAED,MAAM,IAAI,KAAK,CACb,kCAAkC,QAAQ,0DAA0D,CACrG,CAAA;AACH,CAAC;AAED,uEAAuE;AAChE,KAAK,qBACV,SAAmD,EACnD,OAAO,GAA0C,EAAE;IAEnD,MAAM,GAAG,GAAQ,EAAE,CAAA;IACnB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrE,OAAO,GAAG,CAAA;AACZ,CAAC"}
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/core/pagination.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;;;;AAcH;;;;;;;;;GASG;AACI,KAAK,SAAS,CAAC,UACpB,SAAmD,EACnD,OAAO,GAA0C,EAAE;IAEnD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAA;IACzC,IAAI,MAA0B,CAAA;IAC9B,IAAI,IAAI,GAAG,CAAC,CAAA;IAEZ,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAY,MAAM,SAAS,CAAC;YACtC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAChE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;SAC5C,CAAC,CAAA;QACF,2EAA2E;QAC3E,sEAAsE;QACtE,4DAA4D;QAC5D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CACb,kFAAkF;gBAChF,6EAA6E;gBAC7E,8EAA8E,CACjF,CAAA;QACH,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK;YAAE,MAAM,IAAI,CAAA;QAC3C,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAA;QAE3B,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;YAAE,OAAM;QACzE,IAAI,MAAM,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CACb,wEAAwE,IAAI,SAAS,CACtF,CAAA;QACH,CAAC;QACD,MAAM,GAAG,MAAM,CAAC,UAAU,CAAA;IAC5B,CAAC;IAED,MAAM,IAAI,KAAK,CACb,kCAAkC,QAAQ,0DAA0D,CACrG,CAAA;AACH,CAAC;AAED,uEAAuE;AAChE,KAAK,qBACV,SAAmD,EACnD,OAAO,GAA0C,EAAE;IAEnD,MAAM,GAAG,GAAQ,EAAE,CAAA;IACnB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrE,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/cjs/generated/operations.js

@@ -10,7 +10,7 @@
 // the API does not slip in unclassified.
 //
 // Operations: 171 · admin: 40 · both: 1 · member: 127 · service: 3
-// Spec sha256: 1b67f22c80335e08be9a9ecf1351324e01b6003a96dde1253ef0032b3ab6a6fc
+// Spec sha256: a03bd2e06186734bd8816c3d764dd90a48c1c31d7edda2743a3ae29550601cd1
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OPERATIONS = void 0;
 exports.isAdminOperation = isAdminOperation;