@glyphteck/veyl 0.2.0 → 0.3.0

package/docs/api.md

@@ -0,0 +1,647 @@
+# Veyl Headless API
+
+This is the JavaScript API reference for `@glyphteck/veyl`. The CLI and MCP server are thin adapters over this API.
+
+## Model
+
+Headless is a client. It uses the same client-owned cryptographic model as web and iOS:
+
+- machine or passkey authentication signs into Firebase;
+- vault secrets stay local;
+- wallet and chat seeds are derived locally;
+- Spark wallet boot and signing happen locally;
+- messages are encrypted locally;
+- Veyl backend services store public profile metadata, opaque encrypted chat records, and encrypted vault data.
+
+Machine-created accounts are publicly marked as `bot`. Passkey-created CLI accounts are not marked as bots.
+
+## Install
+
+```bash
+bunx @glyphteck/veyl help
+bun add @glyphteck/veyl
+```
+
+## Exports
+
+```js
+import {
+  API_VERSION,
+  COMMANDS,
+  ClientNotReadyError,
+  VeylHeadlessClient,
+  createClient,
+  open,
+} from '@glyphteck/veyl';
+```
+
+- `open(options)`: returns a `VeylHeadlessClient`.
+- `createClient(options)`: synchronous constructor helper.
+- `COMMANDS`: command inventory generated from the canonical adapter descriptors in `src/commands.js`.
+- `API_VERSION`: numeric API version.
+
+## Client Options
+
+```js
+const veyl = await open({
+  profile: 'runner',
+  homeDir: '/secure/veyl-home',
+  network: 'REGTEST',
+  webUrl: 'https://veyl.glyphteck.com',
+  functionBaseUrl: 'https://us-central1-glyphteck.cloudfunctions.net/headless',
+  firebaseConfig,
+  region: 'us-central1',
+  appName: 'my-agent',
+});
+```
+
+- `profile`: local profile name. Defaults to `VEYL_PROFILE` or the active profile.
+- `homeDir`: local profile directory. Defaults to `VEYL_HOME` or `~/.veyl`.
+- `network`: `REGTEST` or `MAINNET`. Defaults to `VEYL_NETWORK`, `NETWORK`, or `REGTEST`.
+- `webUrl`: passkey web origin. Defaults to `VEYL_WEB_URL` or production Veyl.
+- `functionBaseUrl`: override for the headless account HTTP function.
+- `firebaseConfig`, `region`, `appName`: Firebase app configuration overrides.
+- `store`, `profileData`, `session`, `cloudContext`: advanced injection points for tests or custom runtimes.
+
+## Account API
+
+### `veyl.account.create(options)`
+
+Creates a machine-operated account.
+
+```js
+const account = await veyl.account.create({
+  username: 'runner',
+  network: 'REGTEST',
+  saveCredential: true,
+});
+```
+
+Returns an account summary plus `publicKeyPem` and `privateKeyPem`. If `saveCredential` is not `false`, the private key is stored in the local profile.
+
+### `veyl.account.login(options)`
+
+Logs in with the saved or provided machine credential.
+
+```js
+await veyl.account.login();
+await veyl.account.login({ username: 'runner' });
+await veyl.account.login({ credentialId, privateKeyPem });
+```
+
+### `veyl.account.createPasskey(options)`
+
+Creates a real passkey account from the terminal.
+
+```js
+await veyl.account.createPasskey({
+  username: 'zak',
+  webUrl: 'https://veyl.glyphteck.com',
+  saveCredential: true,
+});
+```
+
+The browser completes WebAuthn. The CLI receives a Firebase token through a localhost callback and adds a local machine credential so future CLI sessions can run without another browser prompt.
+
+### `veyl.account.loginPasskey(options)`
+
+Logs into an existing passkey account through the browser-assisted flow.
+
+```js
+await veyl.account.loginPasskey({
+  username: 'zak',
+  webUrl: 'https://veyl.glyphteck.com',
+});
+```
+
+### `veyl.account.me()`
+
+Reads the current local profile without logging in.
+
+```js
+const account = await veyl.account.me();
+```
+
+### Account Summary
+
+```js
+{
+  uid,
+  username,
+  profile,
+  credentialId,
+  network,
+  hasVault,
+  hasVaultSecret,
+  walletPK,
+  chatPK,
+  auth,      // "machine" or "passkey"
+  bot,       // "bot" for machine-created accounts, otherwise null
+  signedIn,
+  unlocked,
+}
+```
+
+## Vault API
+
+### `veyl.vault.create(options)`
+
+Creates wallet/chat key material locally, encrypts it with a vault secret, uploads the encrypted vault, and stores public wallet/chat keys on the profile.
+
+```js
+const vault = await veyl.vault.create({
+  secret: process.env.VEYL_VAULT_SECRET,
+  saveSecret: true,
+});
+```
+
+If `secret` is omitted, the package uses `VEYL_VAULT_SECRET` or generates a random secret. If `saveSecret` is not `false`, the secret is saved in the local profile.
+
+### `veyl.vault.unlock(options)`
+
+Decrypts the vault locally and boots the Spark wallet and chat session.
+
+```js
+await veyl.vault.unlock();
+await veyl.vault.unlock({ secret: process.env.VEYL_VAULT_SECRET });
+```
+
+Most chat and money methods auto-unlock through the saved vault secret when possible.
+
+### `veyl.vault.lock()`
+
+Clears the in-process session and closes wallet connections.
+
+```js
+await veyl.vault.lock();
+```
+
+## Chat API
+
+Peers can be usernames such as `@alice`, chat public keys, wallet public keys, or compatible stream event targets.
+
+### `veyl.chat.list(options)`
+
+Lists recent chats.
+
+```js
+const chats = await veyl.chat.list({ count: 20 });
+```
+
+Chat summaries contain `id`, `linkId`, `peerChatPK`, `peerUid`, `username`, `unseen`, `ts`, and `preview`.
+
+### `veyl.chat.read(peer, options)`
+
+Reads display messages from a chat.
+
+```js
+const page = await veyl.chat.read('@alice', {
+  count: 30,
+  markRead: true,
+  raw: false,
+});
+```
+
+Returns:
+
+```js
+{
+  chat,
+  messages,
+  hasMore,
+  nextOlderThan,
+}
+```
+
+Text messages:
+
+```js
+{
+  id,
+  cid,
+  chatId,
+  from,       // "peer" or "self"
+  peerChatPK,
+  type: 'txt',
+  text,
+  replyId,
+  ts,
+}
+```
+
+Payment requests:
+
+```js
+{
+  type: 'req',
+  amountSats,
+  paid,
+  txId,
+  requestId,
+  replyId,
+}
+```
+
+Other message types return `{ type, payload }`. Use `raw: true` when a caller needs source payload detail.
+
+### `veyl.chat.send(peer, message, options)`
+
+Sends a text message.
+
+```js
+await veyl.chat.send('@alice', 'hello');
+```
+
+### `veyl.chat.reply(target, message, options)`
+
+Replies to a message. The target can be `{ peer, messageId }` or a `message` event from `listen`.
+
+```js
+await veyl.chat.reply({ peer: '@alice', messageId: 'abc123' }, 'got it');
+await veyl.chat.reply(event, 'thanks');
+```
+
+If no message id is present, this falls back to a normal text send to the resolved peer.
+
+### `veyl.chat.react(peer, messageId, emoji, options)`
+
+Adds or changes your reaction to a displayed message.
+
+```js
+await veyl.chat.react('@alice', 'abc123', '+1');
+```
+
+### `veyl.chat.reactTo(target, emoji, options)`
+
+Reacts to `{ peer, messageId }` or a stream event.
+
+```js
+await veyl.chat.reactTo(event, '+1');
+```
+
+### `veyl.chat.unreact(peer, messageId, options)`
+
+Removes your reaction from a message.
+
+```js
+await veyl.chat.unreact('@alice', 'abc123');
+```
+
+### `veyl.chat.save(peer, messageId, options)`
+
+Keeps a displayed message permanently.
+
+```js
+await veyl.chat.save('@alice', 'abc123');
+```
+
+### `veyl.chat.unsave(peer, messageId, options)`
+
+Returns a saved message to normal temporary retention.
+
+```js
+await veyl.chat.unsave('@alice', 'abc123');
+```
+
+### `veyl.chat.delete(peer, messageId, options)`
+
+Deletes one displayed message.
+
+```js
+await veyl.chat.delete('@alice', 'abc123');
+```
+
+### `veyl.chat.deleteChat(peer, options)`
+
+Deletes one chat locally and optionally requests cleanup.
+
+```js
+await veyl.chat.deleteChat('@alice', { cleanup: true });
+```
+
+### `veyl.chat.retention(peer, value, options)`
+
+Sets chat retention. Valid values are `seen` and `24h`.
+
+```js
+await veyl.chat.retention('@alice', '24h');
+```
+
+## Money API
+
+Money methods require an unlocked vault. Amounts are satoshis.
+
+### `veyl.money.balance(options)`
+
+Reads the wallet balance.
+
+```js
+const balance = await veyl.money.balance();
+```
+
+Returns `{ availableSats }` plus `raw` when `raw: true`.
+
+### `veyl.money.receive(options)` / `veyl.money.address(options)`
+
+Returns the static funding address for the active network.
+
+```js
+const { address, network } = await veyl.money.receive();
+```
+
+### `veyl.money.claim(options)`
+
+Claims static deposits and pending incoming transfers.
+
+```js
+await veyl.money.claim({ count: 100 });
+```
+
+### `veyl.money.send(peer, sats, options)`
+
+Sends sats to a Veyl peer.
+
+```js
+await veyl.money.send('@alice', 1000);
+```
+
+### `veyl.money.request(peer, sats, options)`
+
+Sends a chat payment request.
+
+```js
+const request = await veyl.money.request('@alice', 1000);
+```
+
+The request message contains `requestId`, which the payer can use with `money.pay`.
+
+### `veyl.money.pay(requestId, options)`
+
+Pays a chat payment request.
+
+```js
+await veyl.money.pay(request.message.requestId);
+```
+
+### `veyl.money.transactions(options)`
+
+Lists visible wallet transfers.
+
+```js
+const txs = await veyl.money.transactions({ count: 50, offset: 0 });
+```
+
+Returns `{ transfers }`; each transfer contains `id`, `type`, `status`, `direction`, `amountSats`, `createdAt`, `updatedAt`, sender and receiver keys.
+
+### `veyl.money.invoice(sats, options)`
+
+Creates a Lightning invoice.
+
+```js
+const invoice = await veyl.money.invoice(1000, {
+  memo: 'coffee',
+  expirySeconds: 3600,
+  includeSparkAddress: false,
+  includeSparkInvoice: false,
+});
+```
+
+### `veyl.money.payInvoice(invoice, options)`
+
+Pays a Lightning or Spark invoice. QR payloads are accepted.
+
+```js
+await veyl.money.payInvoice(encodedInvoice, {
+  type: 'lightning',
+  amountSats: 1000,
+  maxFeeSats: 20,
+  preferSpark: true,
+});
+```
+
+### `veyl.money.lightningQuote(invoice, options)`
+
+Quotes Lightning send fees.
+
+```js
+await veyl.money.lightningQuote(invoice, { amountSats: 1000 });
+```
+
+### `veyl.money.lightningPay(invoice, options)`
+
+Pays a Lightning invoice directly.
+
+```js
+await veyl.money.lightningPay(invoice, {
+  amountSats: 1000,
+  maxFeeSats: 20,
+  preferSpark: true,
+});
+```
+
+### `veyl.money.lightningReceive(id, options)`
+
+Reads a Lightning receive request.
+
+```js
+await veyl.money.lightningReceive(id);
+```
+
+### `veyl.money.lightningSend(id, options)`
+
+Reads a Lightning send request.
+
+```js
+await veyl.money.lightningSend(id);
+```
+
+### `veyl.money.withdrawQuote(address, sats, options)`
+
+Quotes an on-chain withdrawal.
+
+```js
+await veyl.money.withdrawQuote(bitcoinAddress, 10000);
+```
+
+### `veyl.money.withdrawPrepare(address, sats, options)`
+
+Prepares an on-chain withdrawal review.
+
+```js
+await veyl.money.withdrawPrepare(bitcoinAddress, 10000, {
+  speed: 'MEDIUM',
+  deductFeeFromWithdrawalAmount: true,
+});
+```
+
+### `veyl.money.withdraw(address, sats, options)`
+
+Sends an on-chain withdrawal.
+
+```js
+await veyl.money.withdraw(bitcoinAddress, 10000, {
+  speed: 'MEDIUM',
+  deductFeeFromWithdrawalAmount: true,
+});
+```
+
+## Listen API
+
+`veyl.listen(options)` keeps one auth and vault session alive, polls chats and transfers, and emits events through `onEvent`.
+
+```js
+const controller = new AbortController();
+
+await veyl.listen({
+  agent: true,
+  interval: 3000,
+  chatCount: 20,
+  messageCount: 10,
+  txCount: 50,
+  replay: false,
+  chats: true,
+  transactions: true,
+  signal: controller.signal,
+  onEvent: async (event) => {
+    if (event.type !== 'message') return;
+    await veyl.chat.reactTo(event, '+1');
+    await veyl.chat.reply(event, 'thanks');
+  },
+});
+```
+
+Options:
+
+- `agent: true`: shorthand for `compact: true` and incoming-only messages.
+- `compact: true`: emits smaller account/chat/message payloads.
+- `incomingOnly: true`: emits only peer-authored messages.
+- `incomingOnly: false`: emits self-authored and peer-authored messages.
+- `interval` / `intervalMs`: poll interval, minimum 1000 ms, default 3000 ms.
+- `chatCount`: number of chats to scan, default 20, max 100.
+- `messageCount`: messages per chat to scan, default 10, max 100.
+- `txCount`: transfers to scan, default 50, max 100.
+- `replay: true`: emits current matching messages/transfers on startup.
+- `chats: false`: disables message events.
+- `transactions: false`: disables transfer events.
+- `signal`: `AbortSignal` to stop listening.
+- `onEvent`: event callback.
+
+When `replay` is false, `ready` means the initial baseline scan has completed. Messages that arrive after `ready` should emit as new events.
+
+Compact `ready` event:
+
+```js
+{
+  type: 'ready',
+  ts,
+  account: { uid, username, network, auth, bot, unlocked },
+}
+```
+
+Compact `message` event:
+
+```js
+{
+  type: 'message',
+  ts,
+  peer: '@alice',
+  replyTo: { peer: '@alice', messageId: 'abc123' },
+  reactTo: { peer: '@alice', messageId: 'abc123' },
+  chat: {
+    id,
+    peer,
+    username,
+    peerChatPK,
+    peerUid,
+    unseen,
+    ts,
+  },
+  message: {
+    id,
+    cid,
+    chatId,
+    from,
+    type,
+    ts,
+    peerChatPK,
+    text,
+    amountSats,
+    paid,
+    requestId,
+    replyId,
+  },
+}
+```
+
+Transaction event:
+
+```js
+{
+  type: 'transaction',
+  ts,
+  transaction,
+}
+```
+
+Error event:
+
+```js
+{
+  type: 'error',
+  ts,
+  peer,
+  message,
+}
+```
+
+Per-chat read errors are isolated, so one unreadable stale chat does not stop valid incoming messages from other chats.
+
+## Local Profiles and Secrets
+
+Profiles live under `~/.veyl` by default:
+
+```text
+~/.veyl/
+  active.json
+  profiles/<profile>.json
+```
+
+Profile files are written with `0600` permissions and directories with `0700`.
+
+Stored profile fields can include Firebase uid, username, network, machine credential id, public/private machine keys, vault metadata, wallet/chat public keys, and optionally the vault secret. If the caller has a dedicated secret manager, use `--no-save-secret`, `--no-save-credential`, `saveSecret: false`, or `saveCredential: false`, then store returned secrets yourself.
+
+Glyphteck-owned Google Secret Manager bot seeds are not used by this public path.
+
+## Environment
+
+```bash
+VEYL_HOME=/secure/veyl-home
+VEYL_PROFILE=runner
+VEYL_NETWORK=REGTEST
+VEYL_VAULT_SECRET=...
+VEYL_WEB_URL=https://veyl.glyphteck.com
+```
+
+`VEYL_WEB_URL` must be `https://...` or `localhost` for passkey flows.
+
+## Backend Contract
+
+The package calls the deployed headless HTTP function:
+
+```text
+POST /headless/account/create/start
+POST /headless/account/create/finish
+POST /headless/account/login/start
+POST /headless/account/login/finish
+POST /headless/account/credential/add/start
+POST /headless/account/credential/add/finish
+```
+
+The backend verifies signatures over short-lived challenges and returns Firebase custom tokens. It does not receive the vault secret, wallet seed, chat seed, or Spark wallet entropy.
+
+## Current Limits
+
+- `listen` is polling-based. There is no backend wake-ping contract yet.
+- Headless chat currently sends and replies with text. Media read summaries are exposed, but media upload helpers are not part of this public client API yet.
+- Machine-created headless accounts are intentionally separate from passkey-created human accounts.
+- Passkey account creation and login require a browser-capable environment.