@v3finance/core-sdk 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this package are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com), and this project adheres to [Semantic Versioning](https://semver.org).
+
+## 0.1.0 — 2026-11-10
+
+First release. The whole API is covered — 171 operations grouped into resources, with the
+administrative surface marked — and a test asserts that every endpoint is reachable, so one added
+to the API shows up as a failure rather than as a gap nobody noticed.
+
+### Added
+
+- `CoreClient` with vault scoping: `core.vault(code).addresses.list()`. A scope is an expression,
+  not state, so two vaults can be used side by side and switching the active one cannot leave a
+  stale scope pointing at the wrong place.
+- Injected authentication: `getAuthHeaders`, `onTokenRotated`, `onUnauthorized`. Works with a
+  browser cookie, a native cookie jar or a bearer token; the package stores no credentials.
+- `CoreError` with a `code` that is always present and a `kind` separating HTTP, network, timeout,
+  aborted and parse failures. Three real response shapes are parsed, including the validation
+  failure that arrives as a plain string.
+- Money as smallest-unit strings with BigInt arithmetic (`amount`, `parseDecimal`, `format`, `add`,
+  `sub`, `compare`). There is no `toNumber`, on purpose: it would be a convenient door into the
+  precision loss the module exists to prevent.
+- `Gated` results for the fifteen operations that can finish in more than one way, telling applied,
+  pending and replayed apart by HTTP status — the response bodies are identical, so a client
+  reading only the body reports "done" where the truth is "awaiting signatures".
+- Keyset pagination helpers `paginate` and `collectAll`.
+- Resources: addresses, transfers, history, balances, approvals, counterparties and their groups,
+  shared access, folders, members, operation labelling, operation metadata and relations, reports
+  with templates, snapshots and exports, registries, policy preflight, AML, sign-in, and the
+  administrative surface.
+- Per-report-type parameters, so the compiler requires `from`/`to` and the target each report needs
+  rather than letting the call fail at runtime.
+- `OPERATIONS`, a generated catalogue of all 171 API operations with the access level each requires.
+- Cache keys for TanStack Query at `@v3finance/core-sdk/query-keys`.
+
+### Known limitations
+
+- The `assets` filter on reports is accepted by the API and silently ignored by it, so it is marked
+  deprecated here. Use `tokenIds`.
+- `runTemplate` cannot override a template's stored filters: the endpoint accepts no body.
+- `/welcome` and `/webhooks/wallet` are not exposed — a browser landing page and the wallet
+  service's inbound channel respectively.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 V3 Finance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# V3 Finance Core SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@v3finance/core-sdk.svg)](https://www.npmjs.com/package/@v3finance/core-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@v3finance/core-sdk.svg)](https://www.npmjs.com/package/@v3finance/core-sdk)
+[![types](https://img.shields.io/npm/types/@v3finance/core-sdk.svg)](https://www.npmjs.com/package/@v3finance/core-sdk)
+[![license](https://img.shields.io/npm/l/@v3finance/core-sdk.svg)](./LICENSE)
+
+The official TypeScript SDK for the V3 Finance Core API.
+Custodial addresses, transfers under policy control, approvals and shared access.
+
+- **Vault scoping** that carries no state: `core.vault(code)` is an expression, so two vaults work side by side.
+- **Policy-aware results**: a transfer either executes, waits for signatures or replays — told apart by status, not guesswork.
+- **Money that cannot silently lose precision**: smallest-unit strings and BigInt arithmetic, with no `toNumber`.
+- **Pluggable authentication**: browser cookie, native cookie jar or bearer token — you supply headers, the SDK hands events back.
+- **Complete**: every endpoint of the API, grouped into resources, with the administrative surface marked.
+- **Fully typed**, zero dependencies, ESM and CommonJS. Runs on Node.js, Bun, Deno, Cloudflare Workers and React Native.
+
+The whole API is covered: addresses and transfers, approvals, counterparties, shared access and
+folders, operation labelling, reports, and the administrative surface. A test asserts that every
+endpoint is reachable through some resource, so an endpoint added to the API shows up as a failure
+rather than as a gap nobody noticed.
+
+Two endpoints are deliberately absent: `/welcome` is a browser landing page the API redirects to,
+and `/webhooks/wallet` is the inbound channel for the wallet service.
+
+## Install
+
+```bash
+npm install @v3finance/core-sdk
+```
+
+## Quick start
+
+```ts
+import { CoreClient } from '@v3finance/core-sdk'
+
+const core = new CoreClient({
+  getAuthHeaders: () => ({ Authorization: `Bearer ${sessionToken}` }),
+  onTokenRotated: (token) => storage.save(token),
+  onUnauthorized: () => router.push('/login'),
+})
+
+const page = await core.vault('my-vault').addresses.list({ limit: 20 })
+```
+
+## Three things to know before the first call
+
+### 1. `vault(code)` is an expression, not state
+
+```ts
+core.vault('alpha').addresses.list()
+core.vault('beta').addresses.list()
+```
+
+There is deliberately no "current vault". The code is visible on every call site, an administrator can
+work with several vaults at once, and switching the active vault at runtime cannot leave a stale scope
+pointing at the wrong one. Build a scope where you use it; do not store it.
+
+### 2. An operation may not execute — it may go for approval
+
+Transfers and address creation run through the policy engine. The result is `Gated`, and the three
+branches **must** be distinguished: the response body is identical, only the status differs.
+
+```ts
+const result = await core.vault(code).transfers.send({
+  fromAddressId,
+  toAddress,
+  amount: '1.5',
+  asset: 'usdt',
+  idempotencyKey: crypto.randomUUID(),
+})
+
+switch (result.outcome) {
+  case 'applied':
+    return toast('Transfer sent')
+  case 'pending':
+    return toast('Awaiting signatures — the funds are reserved')
+  case 'replayed':
+    return toast('This transfer was already sent')
+}
+```
+
+Reporting "sent" on `pending` tells a person their money has gone when it is frozen.
+
+**Always pass `idempotencyKey`** and keep it until you have an answer: after a timeout it is the only
+way to retry without sending money twice.
+
+### 3. Amounts are strings, never numbers
+
+Balances arrive in smallest units. `float64` loses precision above 2⁵³, and production balances go higher.
+
+```ts
+import { amount, parseDecimal, format, add } from '@v3finance/core-sdk'
+
+const balance = amount(address.balance ?? '0', 6, 'usdt')
+format(balance, { withAsset: true }) // "1,500.00 USDT"
+add(balance, parseDecimal('2.5', 6))
+```
+
+There is no `toNumber`, on purpose — it would be a convenient door into the bug this layer prevents.
+
+**`balance: null` is not zero.** It means the address has no ledger account yet: nothing has ever
+arrived. "No account" and "empty account" deserve different wording in an interface.
+
+## Errors
+
+Every failure is a `CoreError` and always carries a `code` — sent by the server or derived from the
+HTTP status. Branch on `code`, display `message`.
+
+```ts
+import { hasCode, isCoreError } from '@v3finance/core-sdk'
+
+try {
+  await core.vault(code).transfers.send(input)
+} catch (error) {
+  if (hasCode(error, 'INSUFFICIENT_BALANCE')) return showTopUp()
+  if (hasCode(error, 'APPROVAL_UNSATISFIABLE')) return showNoApprovers()
+  if (isCoreError(error) && error.kind === 'timeout') return retryWithSameKey()
+  throw error
+}
+```
+
+`kind` separates `http` (the server answered), `network` (the request never left), `timeout`,
+`aborted` and `parse`.
+
+## Authentication
+
+The SDK does not store credentials: you provide headers, it reports two events back.
+
+| Runtime | How |
+| --- | --- |
+| Browser | `credentials: 'include'`, the cookie is set by the server |
+| React Native | your own cookie jar, returned from `getAuthHeaders` |
+| Anywhere | `Authorization: Bearer <session-token>` |
+
+In bearer mode **`onTokenRotated` is required**: the server extends a session through the
+`set-auth-token` header, and a client that does not store the new token is signed out at the next
+rotation.
+
+Sign-in is a magic link sent by email. Signing up is possible only on an administrator's invitation.
+
+## Pagination
+
+Lists return `{ items, nextCursor }`. The cursor is opaque — do not parse it.
+
+```ts
+import { paginate } from '@v3finance/core-sdk'
+
+for await (const address of paginate((p) => core.vault(code).addresses.list(p))) {
+  console.log(address.address)
+}
+```
+
+## Admin operations
+
+The package covers the whole API, administrative endpoints included. Access level is available
+programmatically:
+
+```ts
+import { OPERATIONS, isAdminOperation } from '@v3finance/core-sdk'
+
+isAdminOperation('POST /api/v1/policies') // true
+```
+
+A method existing in the package grants nothing: the server decides, based on your session.
+
+## Staying in sync with the API
+
+The repository holds a snapshot of the OpenAPI document (`openapi/spec.json`). Every model is
+generated from it into `src/generated/types.ts` — one exported type per schema, descriptions
+included — by a small purpose-built generator rather than `openapi-typescript`, which is built on
+the TypeScript 5 compiler API that TypeScript 7 no longer ships.
+
+```bash
+npm run spec:update   # refresh the snapshot from the live API
+npm run generate      # regenerate types and the operation catalogue
+```
+
+CI fails when the generated files drift from the snapshot, and when the API gains an operation that
+has not been classified by access level.
+
+A test keeps the generated files in step with the snapshot, so a drift shows up in a pull request
+rather than in a consumer at runtime.
+
+Development requires Node.js 24 (the build scripts are TypeScript run directly). The published
+package supports Node.js 20 and above.
+
+## License
+
+[MIT](./LICENSE)

package/dist/cjs/client.d.ts

@@ -0,0 +1,117 @@
+import { HttpClient, type ClientOptions } from './core/http.js';
+import type { CreateVaultBody, Health, VaultDetail } from './generated/types.js';
+import { AddressesResource } from './resources/addresses.js';
+import { ApprovalsResource } from './resources/approvals.js';
+import { BalancesResource } from './resources/balances.js';
+import { CounterpartiesResource, CounterpartyGroupsResource } from './resources/counterparties.js';
+import { AdminResource } from './resources/admin.js';
+import { AuthResource } from './resources/auth.js';
+import { CategoriesResource } from './resources/categories.js';
+import { FoldersResource } from './resources/folders.js';
+import { HistoryResource } from './resources/history.js';
+import { MembersResource } from './resources/members.js';
+import { OperationsResource } from './resources/operations.js';
+import { RegistriesResource } from './resources/registries.js';
+import { ReportsResource } from './resources/reports.js';
+import { SharingResource } from './resources/sharing.js';
+import { MeResource } from './resources/me.js';
+import { TransfersResource } from './resources/transfers.js';
+/**
+ * Client for the V3 Finance Core API.
+ *
+ * CALL SHAPE: `core.vault(code).addresses.list()`.
+ *
+ * `vault(code)` is an EXPRESSION, not state. There is deliberately no
+ * "current vault" that you set once and forget:
+ *
+ *   • the vault code is visible on every call site, so reading the code does
+ *     not require scrolling up to find which vault is in effect;
+ *   • an administrator works with several vaults at once, and two scopes side
+ *     by side cannot interfere — there is no shared mutable field;
+ *   • in the mobile app and on the web the active vault changes at runtime,
+ *     and a remembered scope would mean requests to the wrong vault after a
+ *     switch.
+ *
+ * A scope is cheap: it is a pair of small objects over the shared HTTP
+ * client, so creating one per call is fine.
+ *
+ * Cross-vault and registry endpoints live at the root: `core.vaults`, `core.me`.
+ *
+ * @example
+ * ```ts
+ * import { CoreClient } from '@v3finance/core-sdk'
+ *
+ * const core = new CoreClient({
+ *   getAuthHeaders: () => ({ Authorization: `Bearer ${sessionToken}` }),
+ *   onTokenRotated: (token) => save(token),
+ *   onUnauthorized: () => signOut(),
+ * })
+ *
+ * const page = await core.vault('my-vault').addresses.list({ limit: 20 })
+ * ```
+ */
+export interface VaultScope {
+    readonly code: string;
+    readonly addresses: AddressesResource;
+    readonly transfers: TransfersResource;
+    readonly history: HistoryResource;
+    readonly balances: BalancesResource;
+    readonly approvals: ApprovalsResource;
+    readonly counterparties: CounterpartiesResource;
+    readonly counterpartyGroups: CounterpartyGroupsResource;
+    readonly sharing: SharingResource;
+    readonly folders: FoldersResource;
+    readonly members: MembersResource;
+    readonly categories: CategoriesResource;
+    readonly reports: ReportsResource;
+    readonly operations: OperationsResource;
+}
+export interface VaultSummary {
+    id: string;
+    code: string;
+    name: string;
+    [extra: string]: unknown;
+}
+export interface Profile {
+    id: string;
+    name: string | null;
+    username: string | null;
+    email: string | null;
+    /** The account came from an invitation link and has no real email yet. */
+    needsEmail: boolean;
+    [extra: string]: unknown;
+}
+export declare class CoreClient {
+    /** Low-level access for endpoints the resources do not cover yet. */
+    readonly http: HttpClient;
+    constructor(options?: ClientOptions);
+    /** Scope of one vault. Build it at the call site; do not store it. */
+    vault(code: string): VaultScope;
+    readonly vaults: {
+        /** Administrators only: a plain member sees their own vault through `me.vault()`. */
+        list: () => Promise<VaultSummary[]>;
+        get: (code: string) => Promise<VaultSummary>;
+        /** Administrators only. */
+        create: (input: CreateVaultBody) => Promise<VaultDetail>;
+        /**
+         * Assembles a derivation path from segment values, and takes one apart.
+         *
+         * Use these rather than building the string yourself: the path is written
+         * WITHOUT apostrophes (`m/44/195/…`, not `m/44'/…`), and the segment
+         * order comes from the vault's own configuration, not from a convention.
+         */
+        buildDerivationPath: (code: string, body: unknown) => Promise<unknown>;
+        parseDerivationPath: (code: string, body: unknown) => Promise<unknown>;
+    };
+    /** Liveness probe. Needs no authentication. */
+    health(): Promise<Health>;
+    /** The caller's own profile, devices and permissions. */
+    readonly me: MeResource;
+    /** Networks, tokens, rates, policy preflight and AML. Not vault-scoped. */
+    readonly registries: RegistriesResource;
+    /** Administrative endpoints. Having one here grants nothing — the server decides. */
+    readonly admin: AdminResource;
+    /** Signing in. One way only: a magic link, and only by invitation. */
+    readonly auth: AuthResource;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/client.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoreClient = void 0;
+const http_js_1 = require("./core/http.js");
+const addresses_js_1 = require("./resources/addresses.js");
+const approvals_js_1 = require("./resources/approvals.js");
+const balances_js_1 = require("./resources/balances.js");
+const counterparties_js_1 = require("./resources/counterparties.js");
+const admin_js_1 = require("./resources/admin.js");
+const auth_js_1 = require("./resources/auth.js");
+const categories_js_1 = require("./resources/categories.js");
+const folders_js_1 = require("./resources/folders.js");
+const history_js_1 = require("./resources/history.js");
+const members_js_1 = require("./resources/members.js");
+const operations_js_1 = require("./resources/operations.js");
+const registries_js_1 = require("./resources/registries.js");
+const reports_js_1 = require("./resources/reports.js");
+const sharing_js_1 = require("./resources/sharing.js");
+const me_js_1 = require("./resources/me.js");
+const transfers_js_1 = require("./resources/transfers.js");
+const version_js_1 = require("./version.js");
+class CoreClient {
+    /** Low-level access for endpoints the resources do not cover yet. */
+    http;
+    constructor(options = {}) {
+        this.http = new http_js_1.HttpClient({ ...options, baseUrl: options.baseUrl ?? version_js_1.DEFAULT_BASE_URL });
+        this.me = new me_js_1.MeResource(this.http);
+        this.registries = new registries_js_1.RegistriesResource(this.http);
+        this.admin = new admin_js_1.AdminResource(this.http);
+        this.auth = new auth_js_1.AuthResource(this.http);
+    }
+    /** Scope of one vault. Build it at the call site; do not store it. */
+    vault(code) {
+        if (!code)
+            throw new Error('@v3finance/core-sdk: a vault code is required.');
+        return {
+            code,
+            addresses: new addresses_js_1.AddressesResource(this.http, code),
+            transfers: new transfers_js_1.TransfersResource(this.http, code),
+            history: new history_js_1.HistoryResource(this.http, code),
+            balances: new balances_js_1.BalancesResource(this.http, code),
+            approvals: new approvals_js_1.ApprovalsResource(this.http, code),
+            counterparties: new counterparties_js_1.CounterpartiesResource(this.http, code),
+            counterpartyGroups: new counterparties_js_1.CounterpartyGroupsResource(this.http, code),
+            sharing: new sharing_js_1.SharingResource(this.http, code),
+            folders: new folders_js_1.FoldersResource(this.http, code),
+            members: new members_js_1.MembersResource(this.http, code),
+            categories: new categories_js_1.CategoriesResource(this.http, code),
+            reports: new reports_js_1.ReportsResource(this.http, code),
+            operations: new operations_js_1.OperationsResource(this.http, code),
+        };
+    }
+    vaults = {
+        /** Administrators only: a plain member sees their own vault through `me.vault()`. */
+        list: () => this.http.request('GET', '/api/v1/vaults'),
+        get: (code) => this.http.request('GET', `/api/v1/vaults/${(0, http_js_1.seg)(code)}`),
+        /** Administrators only. */
+        create: (input) => this.http.request('POST', '/api/v1/vaults', { body: input }),
+        /**
+         * Assembles a derivation path from segment values, and takes one apart.
+         *
+         * Use these rather than building the string yourself: the path is written
+         * WITHOUT apostrophes (`m/44/195/…`, not `m/44'/…`), and the segment
+         * order comes from the vault's own configuration, not from a convention.
+         */
+        buildDerivationPath: (code, body) => this.http.request('POST', `/api/v1/vaults/${(0, http_js_1.seg)(code)}/derivation-path/build`, { body }),
+        parseDerivationPath: (code, body) => this.http.request('POST', `/api/v1/vaults/${(0, http_js_1.seg)(code)}/derivation-path/parse`, { body }),
+    };
+    /** Liveness probe. Needs no authentication. */
+    health() {
+        return this.http.request('GET', '/');
+    }
+    /** The caller's own profile, devices and permissions. */
+    me;
+    /** Networks, tokens, rates, policy preflight and AML. Not vault-scoped. */
+    registries;
+    /** Administrative endpoints. Having one here grants nothing — the server decides. */
+    admin;
+    /** Signing in. One way only: a magic link, and only by invitation. */
+    auth;
+}
+exports.CoreClient = CoreClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":";;;AAAA,4CAAoE;AAEpE,2DAA4D;AAC5D,2DAA4D;AAC5D,yDAA0D;AAC1D,qEAGsC;AACtC,mDAAoD;AACpD,iDAAkD;AAClD,6DAA8D;AAC9D,uDAAwD;AACxD,uDAAwD;AACxD,uDAAwD;AACxD,6DAA8D;AAC9D,6DAA8D;AAC9D,uDAAwD;AACxD,uDAAwD;AACxD,6CAA8C;AAC9C,2DAA4D;AAC5D,6CAA+C;AAuE/C;IACE,qEAAqE;IAC5D,IAAI,CAAY;IAEzB,YAAY,OAAO,GAAkB,EAAE;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,oBAAU,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,6BAAgB,EAAE,CAAC,CAAA;QACxF,IAAI,CAAC,EAAE,GAAG,IAAI,kBAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,CAAC,UAAU,GAAG,IAAI,kCAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACnD,IAAI,CAAC,KAAK,GAAG,IAAI,wBAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACzC,IAAI,CAAC,IAAI,GAAG,IAAI,sBAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzC,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,IAAY;QAChB,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;QAC5E,OAAO;YACL,IAAI;YACJ,SAAS,EAAE,IAAI,gCAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YACjD,SAAS,EAAE,IAAI,gCAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YACjD,OAAO,EAAE,IAAI,4BAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YAC7C,QAAQ,EAAE,IAAI,8BAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YAC/C,SAAS,EAAE,IAAI,gCAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YACjD,cAAc,EAAE,IAAI,0CAAsB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YAC3D,kBAAkB,EAAE,IAAI,8CAA0B,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YACnE,OAAO,EAAE,IAAI,4BAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YAC7C,OAAO,EAAE,IAAI,4BAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YAC7C,OAAO,EAAE,IAAI,4BAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YAC7C,UAAU,EAAE,IAAI,kCAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YACnD,OAAO,EAAE,IAAI,4BAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;YAC7C,UAAU,EAAE,IAAI,kCAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;SACpD,CAAA;IACH,CAAC;IAEQ,MAAM,GAAG;QAChB,qFAAqF;QACrF,IAAI,EAAE,GAA4B,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAiB,KAAK,EAAE,gBAAgB,CAAC;QAE/F,GAAG,EAAE,CAAC,IAAY,EAAyB,EAAE,CAC3C,IAAI,CAAC,IAAI,CAAC,OAAO,CAAe,KAAK,EAAE,kBAAkB,IAAA,aAAG,EAAC,IAAI,CAAC,EAAE,CAAC;QAEvE,2BAA2B;QAC3B,MAAM,EAAE,CAAC,KAAsB,EAAwB,EAAE,CACvD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAc,MAAM,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAE3E;;;;;;WAMG;QACH,mBAAmB,EAAE,CAAC,IAAY,EAAE,IAAa,EAAoB,EAAE,CACrE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,kBAAkB,IAAA,aAAG,EAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,IAAI,EAAE,CAAC;QAE1F,mBAAmB,EAAE,CAAC,IAAY,EAAE,IAAa,EAAoB,EAAE,CACrE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,kBAAkB,IAAA,aAAG,EAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,IAAI,EAAE,CAAC;KAC3F,CAAA;IAED,+CAA+C;IAC/C,MAAM;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAS,KAAK,EAAE,GAAG,CAAC,CAAA;IAC9C,CAAC;IAED,yDAAyD;IAChD,EAAE,CAAY;IAEvB,2EAA2E;IAClE,UAAU,CAAoB;IAEvC,qFAAqF;IAC5E,KAAK,CAAe;IAE7B,sEAAsE;IAC7D,IAAI,CAAc;CAC5B"}

package/dist/cjs/core/errors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Every failure from the SDK is a `CoreError`.
+ *
+ * The API wraps errors into `{error:{code,message,details?}}`, but that
+ * wrapper has three gaps the client has to close itself — otherwise a precise
+ * error turns into "something went wrong":
+ *
+ *   1. Bodies without an `error` key pass through untouched. Batch sharing
+ *      endpoints answer 400 with `{results:[…]}`, which is not a failure of
+ *      the whole call but "some subjects were rejected", and has to be read
+ *      item by item.
+ *   2. Validation failures arrive as a plain string — `{error: "path: msg"}`
+ *      — with no code and no details.
+ *   3. Inside a batch result `message` equals the code (`{code:"X",
+ *      message:"X"}`), so it must never be shown to a person as-is.
+ *
+ * Because of that `code` is always present here: either the server sent one,
+ * or it is derived from the HTTP status. Branch on `code`, display `message`.
+ */
+/** Where the failure came from. Each kind calls for a different reaction. */
+export type CoreErrorKind = 
+/** The server answered with a status >= 400. `status` and `code` are meaningful. */
+'http'
+/** The request never left: no connection, DNS, socket closed. Retrying makes sense. */
+ | 'network'
+/** The request timed out. On money paths retry only with the same idempotency key. */
+ | 'timeout'
+/** The caller aborted it. Not a failure — do not surface it. */
+ | 'aborted'
+/** A response arrived but could not be read as the contract promises. */
+ | 'parse';
+export interface CoreErrorInit {
+    kind: CoreErrorKind;
+    message: string;
+    code: string;
+    status?: number | null;
+    details?: unknown;
+    /** `METHOD /path`, for logs. Never part of the user-facing message. */
+    endpoint?: string;
+    cause?: unknown;
+}
+export declare class CoreError extends Error {
+    readonly kind: CoreErrorKind;
+    /** Machine-readable code. Never empty: sent by the server or derived from the status. */
+    readonly code: string;
+    /** HTTP status, or `null` for network, timeout and aborted failures. */
+    readonly status: number | null;
+    /** Structured details when the handler provided them. The shape depends on `code`. */
+    readonly details: unknown;
+    readonly endpoint: string | undefined;
+    constructor(init: CoreErrorInit);
+}
+export declare function isCoreError(e: unknown): e is CoreError;
+/** Convenience for `catch`: `if (hasCode(e, 'INSUFFICIENT_BALANCE'))`. */
+export declare function hasCode(e: unknown, ...codes: readonly string[]): boolean;
+/**
+ * Status to code, mirroring the mapping the API uses, so that both sides call
+ * the same thing by the same name.
+ */
+export declare function codeFromStatus(status: number): string;
+/**
+ * Turns an error response body into a `CoreError`.
+ *
+ * Reads both places a code can live: the nested `error.code` and a flat `code`
+ * next to `error`. The API populates either one depending on the path.
+ */
+export declare function parseErrorBody(status: number, body: unknown, endpoint?: string): CoreError;
+export declare const networkError: (cause: unknown, endpoint?: string) => CoreError;
+export declare const timeoutError: (ms: number, endpoint?: string) => CoreError;
+export declare const abortedError: (endpoint?: string) => CoreError;
+export declare const parseError: (cause: unknown, endpoint?: string) => CoreError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,aAAa;AACvB,oFAAoF;AAClF,MAAM;AACR,uFAAuF;GACrF,SAAS;AACX,sFAAsF;GACpF,SAAS;AACX,gEAAgE;GAC9D,SAAS;AACX,yEAAyE;GACvE,OAAO,CAAA;AAEX,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,aAAa,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAErC,YAAY,IAAI,EAAE,aAAa,EAQ9B;CACF;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,SAAS,CAEtD;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAExE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAyBrD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAiD1F;AAsBD,eAAO,MAAM,YAAY,UAAW,OAAO,aAAa,MAAM,KAAG,SAQ7D,CAAA;AAEJ,eAAO,MAAM,YAAY,OAAQ,MAAM,aAAa,MAAM,KAAG,SAOzD,CAAA;AAEJ,eAAO,MAAM,YAAY,cAAe,MAAM,KAAG,SAO7C,CAAA;AAEJ,eAAO,MAAM,UAAU,UAAW,OAAO,aAAa,MAAM,KAAG,SAQ3D,CAAA"}