@v3finance/core-sdk 0.1.0 → 0.2.0

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.0";
 /** 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.0';
 /** 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,191 @@
+# 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; it already happened earlier |
+
+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('This transfer was already sent')
+}
+```
+
+`replayed` is kept apart from `applied` on purpose: a replay means the previous attempt reached the
+server and only the answer was lost, so the person should be told "already sent" rather than being
+told "sent" a second time.
+
+**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.