@unicitylabs/sphere-sdk 0.18.0-dev.2 → 0.18.0-dev.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unicitylabs/sphere-sdk",
-  "version": "0.18.0-dev.2",
+  "version": "0.18.0-dev.3",
   "description": "Modular TypeScript SDK for Unicity wallet operations",
   "type": "module",
   "main": "./dist/index.cjs",

package/dist/connect/chunks/chunk-3CYK5SIU.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../core/errors.ts"],"sourcesContent":["/**\n * SDK Error Types\n *\n * Structured error codes for programmatic error handling in UI.\n * UI can switch on error.code to show appropriate user-facing messages.\n *\n * Errors thrown by provider code (the `./impl/*` bundles) are a different `SphereError` class\n * copy, so `instanceof SphereError` / `isSphereError()` is false for them: read `code` structurally.\n *\n * @example\n * ```ts\n * import { PartialSendConflictError, isPossiblyCommittedSendOutcome } from '@unicitylabs/sphere-sdk';\n *\n * try {\n *   await sphere.payments.send({ recipient: '@alice', amount: '1000000', coinId });\n * } catch (err) {\n *   if (err instanceof PartialSendConflictError) {\n *     // Part of the amount already left the wallet and is final. Only err.remainingAmount is still owed:\n *     // if you pay it, do it as a NEW send of exactly that amount, never the original amount.\n *     showToast(`Partly sent: ${err.remainingAmount} base units were not sent`);\n *   } else if (isPossiblyCommittedSendOutcome(err)) {\n *     // The money may already have left the wallet: never call send() again for this payment.\n *     showToast('Sent, waiting for confirmation');\n *   } else {\n *     switch ((err as { code?: unknown } | null)?.code) {\n *       case 'SEND_INSUFFICIENT_BALANCE': showToast('Not enough funds'); break;\n *       case 'INVALID_RECIPIENT': showToast('Recipient not found'); break;\n *       case 'TRANSPORT_ERROR': showToast('Network connection issue'); break;\n *       default: showToast(err instanceof Error ? err.message : String(err));\n *     }\n *   }\n * }\n * ```\n */\n\nexport type SphereErrorCode =\n  | 'NOT_INITIALIZED'\n  | 'ALREADY_INITIALIZED'\n  | 'INVALID_CONFIG'\n  | 'INVALID_IDENTITY'\n  // Not thrown by the SDK: a send short of funds throws SEND_INSUFFICIENT_BALANCE.\n  | 'INSUFFICIENT_BALANCE'\n  | 'INVALID_RECIPIENT'\n  | 'TRANSFER_FAILED'\n  // The source state was consumed by a DIFFERENT transaction (lost race, not a\n  // resume) — raised as TransferConflictError (token-engine/errors.ts, Part E.2).\n  | 'TRANSFER_CONFLICT'\n  // The op's certification is INDETERMINATE (submit accepted / proof fetch\n  // inconclusive) — raised as ProofUnconfirmedError; keep the intent OPEN (#631).\n  | 'CERTIFICATION_UNCONFIRMED'\n  // Split burn checkpoint (sdk-changes E.4, sphere-sdk#501) — all keep-open (token-engine/errors.ts):\n  // burn certified but the checkpoint could not be persisted (no mint submitted);\n  | 'CHECKPOINT_PERSIST_FAILED'\n  // a certified mint leaf has no reproducing stored bytes, or a stored checkpoint fails byte-binding;\n  | 'SPLIT_CHECKPOINT_LOST'\n  // a byte-bound checkpoint proof no longer verifies against the current trust base (validator rotation).\n  | 'CHECKPOINT_TRUSTBASE_MISMATCH'\n  | 'STORAGE_ERROR'\n  // #665: the on-chain spend committed but the post-commit wallet-api mirror\n  // sync (inventory apply / blob upload / save) failed. NOT a lost payment —\n  // the intent is kept open and resume converges the mirror (idempotent apply,\n  // #664). Surfaced distinctly so a UI can reassure (\"sent — wallet catching\n  // up\") instead of showing a hard send failure.\n  | 'SEND_SYNC_PENDING'\n  // #677: a multi-leg send lost a source to a concurrent transfer AFTER ≥1\n  // earlier leg had already certified on-chain AND been journaled/delivered.\n  // The delivered value has irreversibly left the wallet, so this is NOT a\n  // plain, re-sendable failure: surfacing a bare TransferConflictError makes\n  // the caller re-send the FULL amount and pay the delivered leg twice. Raised\n  // as PartialSendConflictError; the caller MUST re-plan ONLY the remainder\n  // under a NEW transferId, never the whole amount.\n  | 'SEND_PARTIALLY_COMPLETED'\n  | 'TRANSPORT_ERROR'\n  | 'AGGREGATOR_ERROR'\n  | 'VALIDATION_ERROR'\n  | 'INVALID_AMOUNT'\n  | 'NETWORK_ERROR'\n  | 'TIMEOUT'\n  | 'DECRYPTION_ERROR'\n  | 'MODULE_NOT_AVAILABLE'\n  // #793: this Sphere was initialised with `walletApi: 'none'` — the explicit\n  // messaging-only composition. Distinct from NOT_INITIALIZED, which is transient\n  // (init in flight, mid address-switch, destroyed): this one never resolves.\n  | 'PAYMENTS_NOT_COMPOSED'\n  | 'SIGNING_ERROR'\n  // Token Spend Queue error codes\n  | 'SEND_QUEUE_TIMEOUT'\n  | 'SEND_INSUFFICIENT_BALANCE'\n  | 'SEND_RESERVATION_CANCELLED'\n  | 'SEND_QUEUE_FULL'\n  | 'MODULE_DESTROYED'\n  | 'REENTRANT_GATE'\n  // Invoice / Accounting error codes\n  | 'INVOICE_NO_TARGETS'\n  | 'INVOICE_INVALID_ADDRESS'\n  | 'INVOICE_NO_ASSETS'\n  | 'INVOICE_INVALID_ASSET'\n  | 'INVOICE_INVALID_AMOUNT'\n  | 'INVOICE_INVALID_COIN'\n  | 'INVOICE_INVALID_NFT'\n  | 'INVOICE_PAST_DUE_DATE'\n  | 'INVOICE_DUPLICATE_ADDRESS'\n  | 'INVOICE_DUPLICATE_COIN'\n  | 'INVOICE_DUPLICATE_NFT'\n  | 'INVOICE_MINT_FAILED'\n  | 'INVOICE_INVALID_PROOF'\n  | 'INVOICE_WRONG_TOKEN_TYPE'\n  | 'INVOICE_INVALID_DATA'\n  | 'INVOICE_ALREADY_EXISTS'\n  | 'INVOICE_NOT_FOUND'\n  | 'INVOICE_NOT_TARGET'\n  | 'INVOICE_ALREADY_CLOSED'\n  | 'INVOICE_ALREADY_CANCELLED'\n  | 'INVOICE_ORACLE_REQUIRED'\n  | 'INVOICE_TERMINATED'\n  | 'INVOICE_INVALID_TARGET'\n  | 'INVOICE_INVALID_ASSET_INDEX'\n  | 'INVOICE_RETURN_EXCEEDS_BALANCE'\n  | 'INVOICE_INVALID_DELIVERY_METHOD'\n  | 'INVOICE_INVALID_REFUND_ADDRESS'\n  | 'INVOICE_INVALID_CONTACT'\n  | 'INVOICE_INVALID_ID'\n  | 'INVOICE_TOO_MANY_TARGETS'\n  | 'INVOICE_TOO_MANY_ASSETS'\n  | 'INVOICE_MEMO_TOO_LONG'\n  | 'INVOICE_TERMS_TOO_LARGE'\n  | 'INVOICE_NOT_TERMINATED'\n  | 'INVOICE_NOT_CANCELLED'\n  | 'INVOICE_STORAGE_FAILED'\n  | 'RATE_LIMITED'\n  | 'COMMUNICATIONS_UNAVAILABLE'\n  // Swap error codes\n  | 'SWAP_INVALID_DEAL'\n  | 'SWAP_INVALID_MANIFEST'\n  | 'SWAP_NOT_FOUND'\n  | 'SWAP_WRONG_STATE'\n  | 'SWAP_RESOLVE_FAILED'\n  | 'SWAP_DM_SEND_FAILED'\n  | 'SWAP_ESCROW_REJECTED'\n  | 'SWAP_DEPOSIT_FAILED'\n  | 'SWAP_PAYOUT_VERIFICATION_FAILED'\n  | 'SWAP_ALREADY_EXISTS'\n  | 'SWAP_ALREADY_COMPLETED'\n  | 'SWAP_ALREADY_CANCELLED'\n  | 'SWAP_TIMEOUT'\n  | 'SWAP_LIMIT_EXCEEDED'\n  | 'SWAP_ALREADY_INITIALIZED'\n  | 'SWAP_MODULE_DESTROYED'\n  | 'SWAP_NOT_INITIALIZED';\n\nexport class SphereError extends Error {\n  readonly code: SphereErrorCode;\n  readonly cause?: unknown;\n  /**\n   * #441 deferred-paid linkage: the transferId of the possibly-committed send,\n   * stamped by `sendOnce` before the error leaves so a payment-request consumer\n   * can durably journal request→transfer and resolve 'paid' only when that\n   * transfer actually completes (never optimistically). Present ONLY on\n   * possibly-committed outcomes ({@link isPossiblyCommittedSendOutcome}).\n   */\n  transferId?: string;\n\n  constructor(message: string, code: SphereErrorCode, cause?: unknown) {\n    super(message);\n    this.name = 'SphereError';\n    this.code = code;\n    this.cause = cause;\n  }\n}\n\n/**\n * #677: a send that PARTIALLY completed before losing a source to a concurrent\n * transfer. At least one earlier leg certified on-chain and was journaled for\n * delivery (its {@link committedTokenIds}) — that value has irreversibly left\n * the wallet — but a LATER leg raised `TransferConflictError` (a lost race), and\n * `send()` could NOT COMPLETE the {@link remainingAmount} from the remaining live\n * sources. This is the fallback after the internal remainder re-plan gave up —\n * either insufficient funds OR a transient/transport error during the re-plan\n * (the underlying reason is on `cause`), not necessarily an \"out of funds\" state.\n *\n * Distinct from `TransferConflictError` on purpose: a bare conflict makes the\n * caller re-send the FULL amount, paying the already-delivered leg a second\n * time. Catching THIS type (or `code === 'SEND_PARTIALLY_COMPLETED'`) tells the\n * caller/UI: the delivered legs are final, the conflicted intent stays OPEN\n * (resume converges its certified legs), and only the REMAINDER\n * ({@link remainingAmount}) may be re-planned — under a NEW transferId, never\n * re-sending the whole amount.\n *\n * NOT a subclass of `TransferConflictError` by design: existing conflict\n * handlers that re-send in full must NOT treat this as an ordinary conflict.\n */\nexport class PartialSendConflictError extends SphereError {\n  /**\n   * The FIRST partial attempt's transferId — its intent stays open for resume,\n   * and it is the §6 handoff anchor. NOTE: `send()` may re-plan the remainder across\n   * SEVERAL internal attempts before giving up, so {@link committedTokenIds} can\n   * span MULTIPLE transferIds — they do NOT all map to this single id.\n   */\n  readonly transferId: string;\n  /**\n   * Source token ids whose spend already certified on-chain (and whose finished\n   * output blob is journaled for delivery). Their value has already been\n   * delivered; NEVER re-send these. May accumulate across several internal\n   * remainder-re-plan attempts (so not all are journaled under {@link transferId}).\n   */\n  readonly committedTokenIds: readonly string[];\n  /**\n   * The still-undelivered portion (base units, decimal string) — `send()` could\n   * not COMPLETE it from the remaining live sources (insufficient funds or a\n   * transient error; see `cause`). Re-plan ONLY this amount, under a new\n   * transferId; the delivered legs converge via the recipient's §6 claim.\n   */\n  readonly remainingAmount: string;\n\n  constructor(\n    message: string,\n    transferId: string,\n    committedTokenIds: readonly string[],\n    remainingAmount: string,\n    cause?: unknown,\n  ) {\n    super(message, 'SEND_PARTIALLY_COMPLETED', cause);\n    this.name = 'PartialSendConflictError';\n    this.transferId = transferId;\n    this.committedTokenIds = [...committedTokenIds];\n    this.remainingAmount = remainingAmount;\n  }\n}\n\n/**\n * Error codes for a send outcome where money has (or may have) already left the\n * wallet on-chain, so the send is NOT a clean, re-sendable failure. A consumer\n * that persists a \"paid\" flag (e.g. a payment request) must keep the request\n * NON-payable on any of these — reverting to a re-payable state would double-pay\n * (#441). Covers the post-commit mirror-sync-pending / keep-open certification\n * states AND the partial-conflict outcome.\n */\nconst POSSIBLY_COMMITTED_SEND_CODES: ReadonlySet<SphereErrorCode> = new Set([\n  'SEND_SYNC_PENDING',\n  'CERTIFICATION_UNCONFIRMED',\n  'CHECKPOINT_PERSIST_FAILED',\n  'SPLIT_CHECKPOINT_LOST',\n  'CHECKPOINT_TRUSTBASE_MISMATCH',\n  'SEND_PARTIALLY_COMPLETED',\n]);\n\n/**\n * #441: true when a send failed with an outcome where the payment has (or may\n * have) irreversibly left the wallet — a post-commit sync-pending / keep-open\n * certification state, or a `PartialSendConflictError`. Such a send completes (or\n * has already partially completed) via resume/claim and MUST NOT be re-sent, so\n * a persisted \"paid\" state must stay non-payable. A `false` result is a clean\n * pre-commit failure — nothing left the wallet, safe to re-pay.\n */\nexport function isPossiblyCommittedSendOutcome(err: unknown): boolean {\n  return isSphereError(err) && POSSIBLY_COMMITTED_SEND_CODES.has(err.code);\n}\n\n/**\n * Type guard to check if an error is a SphereError\n */\nexport function isSphereError(err: unknown): err is SphereError {\n  return err instanceof SphereError;\n}\n"],"mappings":";AAsJO,IAAM,cAAN,cAA0B,MAAM;AAAA,EAC5B;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQT;AAAA,EAEA,YAAY,SAAiB,MAAuB,OAAiB;AACnE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,QAAQ;AAAA,EACf;AACF;","names":[]}