@v3finance/core-sdk 0.1.0 → 0.2.1

package/dist/esm/units.js

@@ -23,8 +23,15 @@ export class AmountError extends Error {
 }
 const RAW_RE = /^-?\d+$/;
 const DECIMAL_RE = /^-?\d+(\.\d+)?$/;
+/**
+ * The API's own ceiling: `CreateTokenBody.decimals` is `int().min(0).max(38)`
+ * in the policy engine's `src/openapi/models.ts`. A lower bound here would
+ * contradict the rest of the package — `registries.createToken` would accept a
+ * token this module then refuses to do arithmetic on.
+ */
+const MAX_DECIMALS = 38;
 function assertDecimals(decimals) {
-    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > MAX_DECIMALS) {
         throw new AmountError(`Invalid decimals: ${decimals}`);
     }
 }
@@ -76,8 +83,17 @@ export function toDecimalString(a, options = {}) {
  */
 export function format(a, options = {}) {
     const decimal = toDecimalString(a, { trim: false });
+    // The padding is clamped to `decimals` because `decimals` is the maximum
+    // below, and Intl throws RangeError when a minimum exceeds its maximum. So
+    // the default of two digits made `format` unusable — not merely unpadded —
+    // for any token with 0 or 1 decimals, and such tokens are reachable: the API
+    // allows `decimals: 0` on a token, and a `currency` category field takes
+    // `scale: 0` today. Clamping rather than raising the maximum: digits past
+    // `decimals` do not exist in the asset, and printing them would claim a
+    // divisibility the token does not have.
+    const minFraction = Math.min(options.minFractionDigits ?? 2, a.decimals);
     const formatter = new Intl.NumberFormat(options.locale ?? 'en-US', {
-        minimumFractionDigits: options.minFractionDigits ?? 2,
+        minimumFractionDigits: minFraction,
         maximumFractionDigits: a.decimals,
     });
     // The runtime accepts a string and keeps precision; lib.es5 still types the

package/dist/esm/units.js.map

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

package/dist/esm/version.d.ts

@@ -1,5 +1,5 @@
 /** SDK version, sent in the `user-agent` header. */
-export declare const SDK_VERSION = "0.1.0";
+export declare const SDK_VERSION = "0.2.1";
 /** Default API base URL. */
 export declare const DEFAULT_BASE_URL = "https://policy-engine-rest.ezig.workers.dev";
 //# sourceMappingURL=version.d.ts.map

package/dist/esm/version.js

@@ -1,5 +1,5 @@
 /** SDK version, sent in the `user-agent` header. */
-export const SDK_VERSION = '0.1.0';
+export const SDK_VERSION = '0.2.1';
 /** Default API base URL. */
 export const DEFAULT_BASE_URL = 'https://policy-engine-rest.ezig.workers.dev';
 //# sourceMappingURL=version.js.map

package/docs/concepts.md

@@ -0,0 +1,193 @@
+# Concepts
+
+The API behind this SDK is a custody system: it holds addresses, moves money under rules, and
+records who decided what. Most of the surprises in it come from five ideas. Knowing them makes the
+rest of the package read as obvious; not knowing them is how an interface ends up telling someone
+their money has left when it has not.
+
+## 1. A vault is the unit of everything
+
+A vault owns addresses, counterparties, policies, categories and reports. Almost every path is
+`/vaults/{code}/…`, and nothing crosses a vault boundary.
+
+In the SDK that is `core.vault(code)`, created where it is used rather than stored:
+
+```ts
+core.vault('alpha').addresses.list()
+core.vault('beta').addresses.list()
+```
+
+There is no "current vault". An administrator works with several at once, the active one changes at
+runtime in both our clients, and a remembered scope would mean requests to the wrong vault after a
+switch — a failure mode with no symptom until the figures are wrong.
+
+## 2. Two tiers of authorisation, and they do not substitute for each other
+
+This is the distinction most often confused in this system.
+
+|  | **Policy** | **Grant** |
+| --- | --- | --- |
+| Answers | may this ACTION happen? | is there access to this OBJECT? |
+| Input | action plus request context — amount, recipient, path, history | a pair: subject and resource |
+| Nature | computed every time | a fact, stored as a row |
+| Outcomes | three: allow / block / require approval | binary: yes or no |
+
+They compose. Sending a transfer first needs the address right (a grant) and then clears the engine
+(a policy). Removing either does not simplify anything — they answer different questions.
+
+Practical consequences you will meet:
+
+- the counterparty directory does **not** restrict where money can go. A transfer accepts any
+  address; the directory only attaches a name afterwards. Restricting recipients is a policy of the
+  form `block + not(...)`;
+- policies are loaded only from the initiator's groups. An allow-list added to one group does not
+  apply to members of another, so a list meant for everyone has to exist in every transfer group;
+- visibility is a grant too, and the default is deny. A member sees only themselves until someone
+  grants otherwise, which is why an empty directory usually means "no visibility grants yet" rather
+  than "no members".
+
+## 3. An operation may not happen — it may go for approval
+
+Transfers, address creation, changes to the counterparty directory and gated labelling all pass
+through the policy engine, and the engine has three outcomes, not two.
+
+The API expresses this with the HTTP status, because **the response bodies are identical**:
+
+| Status | Meaning |
+| --- | --- |
+| 201 | applied — it happened |
+| 202 | pending — funds are RESERVED, nothing has moved, there is a request to sign |
+| 200 | replayed — the same idempotency key; the transfer already existed, in whatever state it is now |
+
+The SDK turns that into `Gated`:
+
+```ts
+switch (result.outcome) {
+  case 'applied':  return toast('Transfer sent')
+  case 'pending':  return toast('Awaiting signatures — funds are reserved')
+  case 'replayed': return toast(describeStatus(result.data.transaction.status))
+}
+```
+
+`replayed` is kept apart from `applied` on purpose: a replay means the previous attempt reached the
+server and only the answer was lost — not that it succeeded. The body is that transfer as it stands
+now, so `replayed` must not be shown as "sent": `data.transaction.status` says whether it went out
+(`confirmed`, or `submitted`), is waiting for signatures (`awaiting_approval`), is still executing
+(`pending`) or did not go out (`failed`, `rejected`, `cancelled`).
+
+**Only `transfers.send` can return it.** `idempotencyKey` exists on exactly one request body in the
+whole API — the transfer — so it is the only place where a 200 means "this already happened". On
+every other gated method a 200 is an ordinary success (updating a counterparty, for instance) and
+is labelled `applied`; writing a `case 'replayed'` there is harmless but dead. The branch is worth
+handling where it is reachable and worth knowing about where it is not, because "the key protects
+the retry" is true of transfers and of nothing else: a timed-out counterparty change has to be
+verified by reading the object back.
+
+Two further rules about approvals:
+
+- **who may vote is a snapshot.** It is taken when the request is created, from the policies as
+  they stood then. Editing a policy or a group afterwards does not change a request in flight —
+  deliberately, so that a change of rules cannot retroactively unlock money already reserved;
+- **requirements are collected from every applicable policy**, not resolved to the strictest one.
+  That is how "the CFO AND compliance" is expressed, and it means adding a permissive policy beside
+  an existing one does not remove its signatures.
+
+## 4. Money is a string, and zero is not nothing
+
+Every amount is raw smallest units in a string: `"96325670000"` is 96 325.67 USDT. `float64` loses
+precision above 2⁵³, and balances here exceed that.
+
+```ts
+import { amount, format, add, parseDecimal } from '@v3finance/core-sdk'
+
+const balance = amount(address.balance ?? '0', 6, 'usdt')
+format(balance, { withAsset: true })      // "96,325.67 USDT"
+add(balance, parseDecimal('2.5', 6))
+```
+
+There is no `toNumber`. It would be a convenient door into exactly the bug this layer exists to
+prevent.
+
+**Where it is decimal instead.** "Raw" above describes what the API ANSWERS with — addresses,
+transfers, deposits, balances, the ledger. Three places are decimal, and one of them is an INPUT
+where a mistake moves money:
+
+- **the `amount` you send to `transfers.send` is DECIMAL** — `'1.5'` means one and a half USDT, and
+  the API scales it by the token's decimals. Sending the raw figure `'1500000'` there asks for a
+  million and a half. The same holds for `context.amount.value` in `registries.evaluate`;
+- the figures inside a report are decimal strings in units of the asset — `"1.5"`, already scaled.
+  The one raw figure in a report is `balanceRaw`, in the opening and closing balances of
+  `address_activity`;
+- the totals of `balances.asOf()` are decimal, although the same-named fields of `balances.list()`
+  are raw.
+
+`amount()` would misread a decimal: it rejects `"1.5"` outright and takes `"15"` for fifteen
+smallest units. Read decimals with `parseDecimal`, and convert before sending — never pass a raw
+string where a decimal is expected, or the other way round.
+
+**`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, and merging them produces an
+interface that claims an address is empty when it has never been used.
+
+Underneath, balances are derived from a double-entry ledger, which is the single source of truth:
+no balance is stored on an address. A token with no ledger account simply does not appear in
+`balances[]`, for the same reason.
+
+The ledger is append-only. A correction is a reversing entry, never an edit.
+
+## 5. Shared access: roles out, flags in
+
+An address or a folder can be shared. Outwards the right is a **role**, inwards it is flags:
+
+- `viewer` — can see;
+- `contributor` — can see and transfer.
+
+There is no "manager" role, because that is the creator of the object: one person, not something a
+grant hands out.
+
+Granting is idempotent — repeating it for the same pair updates the rights and revives a revoked
+grant — and revoking is soft and immediate.
+
+A folder and an address group are **one entity** served under two prefixes; this package uses
+`/address-folders`. Two rules protect it from leaking somebody else's address:
+
+- only the creator changes a folder's contents, and only with their own addresses;
+- an owner can always pull their own address out of someone else's folder.
+
+## Labelling and reports, in one paragraph each
+
+**Operation categories** are a configurable schema: which categories exist and what fields they
+have is visible to every member, while the *values* on operations are restricted and managing the
+schema is administrator-only. A category key and a field's key and type are immutable once created,
+because values, reports and snapshots refer to them; a field with history is archived, not deleted.
+Whether editing values needs approval is a property of the category (`approvalScope`), not of the
+policy engine — looking for it there is wasted time.
+
+**Reports** come in ten types, and each answers with its own shape — a position report has no
+turnover summary, an approval report counts requests rather than money — so `reports.run(type, …)`
+is typed per report. They answer in their own error envelope with `REPORT_*` codes, which is
+intentional. Sensitive field values are redacted per operation by the loader according to what the
+caller may see: the value becomes `null` and its key appears in `redactedFields`. Access to an
+operation and access to its sensitive labelling are different rights — the first comes with
+`view`, the second only with `transfer`.
+
+## Authentication
+
+One way in: a magic link by email. Signing up is possible only on an administrator's invitation, so
+requesting a link for an uninvited address creates nothing.
+
+The session travels in one of three ways, and the SDK supports all three because it stores none of
+them — you supply headers, it hands two events back:
+
+| Runtime | How |
+| --- | --- |
+| Browser | `credentials: 'include'`, cookie 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.
+
+There is no API key and no machine-to-machine flow today. An integration that needs to run without
+a person signing in cannot authenticate yet.