forked from Lilly-Protocol/lily-sdk
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
335 lines (320 loc) · 51.6 KB
/
Copy pathindex.html
File metadata and controls
335 lines (320 loc) · 51.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
<!DOCTYPE html><html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@lily-protocol/sdk</title><meta name="description" content="Documentation for @lily-protocol/sdk"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script><script async src="assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar">
<div class="tsd-toolbar-contents container"><a href="index.html" class="title">@lily-protocol/sdk</a>
<div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/>
<ul role="listbox" id="tsd-search-results"></ul>
<div id="tsd-search-status" aria-live="polite" aria-atomic="true">
<div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></header>
<div class="container container-main">
<div class="col-content">
<div class="tsd-page-title">
<h1>@lily-protocol/sdk</h1></div>
<div class="tsd-panel tsd-typography"><h1 id="lily-sdk" class="tsd-anchor-link">Lily SDK<a href="#lily-sdk" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1>
<h2 id="security" class="tsd-anchor-link">Security<a href="#security" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>Please see <a href="media/SECURITY.md">SECURITY.md</a> for supported versions and private vulnerability reporting through GitHub Security Advisories. Do not file public issues for security-sensitive reports.</p>
<p><a href="https://github.com/lily-protocol/lily-sdk/actions/workflows/ci.yml"><img src="https://github.com/lily-protocol/lily-sdk/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/typed-TypeScript-3178C6.svg" alt="TypeScript"></a>
<a href="./SECURITY.md"><img src="https://img.shields.io/badge/security-policy-blue.svg" alt="Security Policy"></a></p>
<p>TypeScript-first SDK for integrating Lily Protocol's autonomous agent finance infrastructure into Node.js applications.</p>
<p>The SDK is designed for backend and service-to-service integrations that need typed access to AgentLily wallets, agent identity, autonomous payments, and Lily backend APIs on Stellar.</p>
<h2 id="status" class="tsd-anchor-link">Status<a href="#status" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>This repository is production-oriented foundation work. The public API, tooling, and contributor workflow are in place, while several domain methods still use intentionally conservative request models so the SDK can evolve alongside the backend without breaking contributors every week.</p>
<h2 id="features" class="tsd-anchor-link">Features<a href="#features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li>Typed SDK constructor with strict configuration validation</li>
<li>Modular clients for agents, wallets, payments, identity, and system health</li>
<li>Reusable HTTP transport abstraction with auth header handling, timeouts, and retry scaffolding</li>
<li>Node.js ESM and CommonJS builds, a browser-targeted ESM build, and emitted declaration files</li>
<li>Vitest test suite, ESLint, Prettier, and GitHub Actions CI</li>
<li>Contributor-ready project docs, issue templates, and example script</li>
</ul>
<h2 id="browser-support" class="tsd-anchor-link">Browser Support<a href="#browser-support" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>The SDK ships a browser-compatible ESM build at <code>dist/browser/</code>. Bundlers that support the <code>browser</code> export condition (webpack, Vite, Rollup, esbuild) will automatically resolve to this build.</p>
<pre><code class="js"><span class="hl-0">// Browser bundlers resolve to dist/browser/index.js via the exports map</span><br/><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">LilySdk</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'@lily-protocol/sdk'</span><span class="hl-2">;</span>
</code><button type="button">Copy</button></pre>
<p>The browser build targets ES2022 and uses the native <code>fetch</code> API. Node.js-specific APIs are not included.</p>
<h2 id="installation" class="tsd-anchor-link">Installation<a href="#installation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<pre><code class="bash"><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">install</span><span class="hl-2"> </span><span class="hl-4">@lily-protocol/sdk</span>
</code><button type="button">Copy</button></pre>
<h3 id="browser-support-1" class="tsd-anchor-link">Browser support<a href="#browser-support-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>The SDK supports modern browsers with native <code>fetch</code>, <code>URL</code>, and <code>AbortController</code> APIs. Browser-aware bundlers select the dedicated <code>browser</code> export automatically; it is compiled as ES2022 without Node.js globals or built-ins. Keep API keys and other server-side credentials out of browser applications—only use credentials that are explicitly safe to expose to end users.</p>
<p>For local development in this repository:</p>
<pre><code class="bash"><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">install</span>
</code><button type="button">Copy</button></pre>
<h2 id="requirements-compatibility" class="tsd-anchor-link">Requirements & Compatibility<a href="#requirements-compatibility" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li>
<p><strong>Node.js >= 20</strong>: The SDK requires Node.js 20 or later. It relies on the built-in global <code>fetch</code>, <code>AbortController</code>, and DOM <code>Headers</code> APIs available natively from Node 20+.</p>
</li>
<li>
<p><strong>Global Fetch</strong>: A standards-compliant <code>fetch</code> implementation must be available globally. If running in an environment without native fetch, provide a compatible polyfill via the <code>config.fetch</code> option when constructing the SDK.</p>
</li>
<li>
<p><strong>CI-Supported Versions</strong>: Automated tests run against Node.js 20 and Node.js 22.</p>
</li>
<li>
<p><strong>Browser Considerations</strong>: When using the SDK in browser environments, be aware of CORS restrictions and ensure that the <code>Headers</code> API is supported. The SDK does not include browser-specific polyfills; configure your bundler or runtime accordingly.</p>
</li>
<li>
<p><strong>Custom Fetch Fallback</strong>: For unsupported runtimes (e.g., older Node versions or specialized environments), pass a custom fetch implementation through the SDK configuration to override the global default.</p>
<pre><code class="ts"><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">LilySdk</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'@lily-protocol/sdk'</span><span class="hl-2">;</span><br/><span class="hl-1">import</span><span class="hl-2"> </span><span class="hl-3">fetch</span><span class="hl-2"> </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'node-fetch'</span><span class="hl-2">; </span><span class="hl-0">// or any compatible polyfill</span><br/><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">sdk</span><span class="hl-2"> = </span><span class="hl-6">new</span><span class="hl-2"> </span><span class="hl-5">LilySdk</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-3">baseUrl:</span><span class="hl-2"> </span><span class="hl-4">'https://api.lilyprotocol.com'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">fetch:</span><span class="hl-2"> </span><span class="hl-3">fetch</span><span class="hl-2"> </span><span class="hl-1">as</span><span class="hl-2"> </span><span class="hl-6">typeof</span><span class="hl-2"> </span><span class="hl-3">globalThis</span><span class="hl-2">.</span><span class="hl-3">fetch</span><span class="hl-2">,</span><br/><span class="hl-2">});</span>
</code><button type="button">Copy</button></pre>
<p>Browser applications are also subject to server-enforced CORS restrictions. Ensure the Lily backend allows requests from your origin, or use a proxy/backend-for-frontend pattern.</p>
</li>
</ul>
<h2 id="quick-start" class="tsd-anchor-link">Quick Start<a href="#quick-start" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<pre><code class="ts"><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">LilySdk</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'@lily-protocol/sdk'</span><span class="hl-2">;</span><br/><br/><span class="hl-0">// Uses https://api.lilyprotocol.com by default and reads LILY_API_URL,</span><br/><span class="hl-0">// LILY_API_KEY, and LILY_AUTH_TOKEN from the environment when present.</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">sdk</span><span class="hl-2"> = </span><span class="hl-3">LilySdk</span><span class="hl-2">.</span><span class="hl-5">create</span><span class="hl-2">();</span><br/><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">health</span><span class="hl-2"> = </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">system</span><span class="hl-2">.</span><span class="hl-5">health</span><span class="hl-2">();</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">wallet</span><span class="hl-2"> = </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">wallets</span><span class="hl-2">.</span><span class="hl-5">provision</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-3">agentId:</span><span class="hl-2"> </span><span class="hl-4">'agent_123'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">network:</span><span class="hl-2"> </span><span class="hl-4">'stellar-testnet'</span><span class="hl-2">,</span><br/><span class="hl-2">});</span><br/><br/><span class="hl-3">console</span><span class="hl-2">.</span><span class="hl-5">log</span><span class="hl-2">(</span><span class="hl-3">health</span><span class="hl-2">.</span><span class="hl-3">status</span><span class="hl-2">);</span><br/><span class="hl-3">console</span><span class="hl-2">.</span><span class="hl-5">log</span><span class="hl-2">(</span><span class="hl-3">wallet</span><span class="hl-2">.</span><span class="hl-3">wallet</span><span class="hl-2">.</span><span class="hl-3">address</span><span class="hl-2">);</span>
</code><button type="button">Copy</button></pre>
<h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>The SDK accepts a <code>LilySdkConfig</code> object. All fields except <code>baseUrl</code> are optional and have sensible defaults.</p>
<table>
<thead>
<tr>
<th style="text-align:left">Field</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Default</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>baseUrl</code></td>
<td style="text-align:left"><code>string</code></td>
<td style="text-align:left"><em>required</em></td>
<td style="text-align:left">Absolute URL for the Lily Protocol API (e.g. <code>https://api.lilyprotocol.com</code>).</td>
</tr>
<tr>
<td style="text-align:left"><code>apiKey</code></td>
<td style="text-align:left"><code>string</code></td>
<td style="text-align:left"><code>undefined</code></td>
<td style="text-align:left">API key sent as <code>x-api-key</code> header when provided.</td>
</tr>
<tr>
<td style="text-align:left"><code>authToken</code></td>
<td style="text-align:left"><code>string</code></td>
<td style="text-align:left"><code>undefined</code></td>
<td style="text-align:left">Bearer token sent as <code>Authorization</code> header when provided.</td>
</tr>
<tr>
<td style="text-align:left"><code>timeoutMs</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"><code>10000</code></td>
<td style="text-align:left">Request timeout in milliseconds. Must be positive. Can be overridden per-request via <code>HttpRequest.timeoutMs</code>.</td>
</tr>
<tr>
<td style="text-align:left"><code>retry</code></td>
<td style="text-align:left"><code>Partial<RetryPolicy></code></td>
<td style="text-align:left"><code>{ retries: 2, retryDelayMs: 250, retryableStatusCodes: [408,409,425,429,500,502,503,504] }</code></td>
<td style="text-align:left">Retry behaviour for failed requests. See below.</td>
</tr>
<tr>
<td style="text-align:left"><code>defaultHeaders</code></td>
<td style="text-align:left"><code>Record<string,string></code></td>
<td style="text-align:left"><code>{}</code></td>
<td style="text-align:left">Extra headers merged into every request.</td>
</tr>
<tr>
<td style="text-align:left"><code>userAgent</code></td>
<td style="text-align:left"><code>string</code></td>
<td style="text-align:left"><code>lily-sdk/0.1.0</code></td>
<td style="text-align:left">Value of the <code>User-Agent</code> header.</td>
</tr>
<tr>
<td style="text-align:left"><code>fetch</code></td>
<td style="text-align:left"><code>typeof fetch</code></td>
<td style="text-align:left"><code>globalThis.fetch</code></td>
<td style="text-align:left">Custom fetch implementation for unsupported runtimes.</td>
</tr>
</tbody>
</table>
<h3 id="retry-semantics" class="tsd-anchor-link">Retry semantics<a href="#retry-semantics" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
<ul>
<li>Retries only apply to <strong>safe/idempotent</strong> methods: <code>GET</code>, <code>PUT</code>, and <code>DELETE</code>. Requests using <code>POST</code> or <code>PATCH</code> fail immediately on error.</li>
<li>Eligible status codes default to <code>[408, 409, 425, 429, 500, 502, 503, 504]</code> and can be customised via <code>retry.retryableStatusCodes</code>.</li>
<li>Transport-level errors (network failures, DNS errors) are retried under the same method constraint.</li>
<li>The delay between attempts grows linearly: <code>retryDelayMs × attemptNumber</code> (e.g. 250 ms, then 500 ms).</li>
<li>Timeouts (<code>AbortError</code>) are wrapped as <code>LilyTransportError</code> with code <code>TIMEOUT</code> and are not retried beyond the transport policy.</li>
</ul>
<h3 id="example" class="tsd-anchor-link">Example<a href="#example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
<pre><code class="ts"><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">sdk</span><span class="hl-2"> = </span><span class="hl-6">new</span><span class="hl-2"> </span><span class="hl-5">LilySdk</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-3">baseUrl:</span><span class="hl-2"> </span><span class="hl-4">'https://api.lilyprotocol.com'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">authToken:</span><span class="hl-2"> </span><span class="hl-3">process</span><span class="hl-2">.</span><span class="hl-3">env</span><span class="hl-2">.</span><span class="hl-7">LILY_AUTH_TOKEN</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">timeoutMs:</span><span class="hl-2"> </span><span class="hl-8">15_000</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">retry:</span><span class="hl-2"> { </span><span class="hl-3">retries:</span><span class="hl-2"> </span><span class="hl-8">3</span><span class="hl-2">, </span><span class="hl-3">retryDelayMs:</span><span class="hl-2"> </span><span class="hl-8">500</span><span class="hl-2"> },</span><br/><span class="hl-2"> </span><span class="hl-3">defaultHeaders:</span><span class="hl-2"> { </span><span class="hl-4">'x-request-source'</span><span class="hl-3">:</span><span class="hl-2"> </span><span class="hl-4">'billing-service'</span><span class="hl-2"> },</span><br/><span class="hl-2">});</span>
</code><button type="button">Copy</button></pre>
<p>Per-request overrides use the low-level HTTP client instead:</p>
<pre><code class="ts"><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">http</span><span class="hl-2">.</span><span class="hl-5">request</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-3">method:</span><span class="hl-2"> </span><span class="hl-4">'POST'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">path:</span><span class="hl-2"> </span><span class="hl-4">'/v1/wallets/provision'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">body:</span><span class="hl-2"> { </span><span class="hl-3">agentId:</span><span class="hl-2"> </span><span class="hl-4">'agent_123'</span><span class="hl-2">, </span><span class="hl-3">network:</span><span class="hl-2"> </span><span class="hl-4">'stellar-testnet'</span><span class="hl-2"> },</span><br/><span class="hl-2"> </span><span class="hl-3">timeoutMs:</span><span class="hl-2"> </span><span class="hl-8">5_000</span><span class="hl-2">,</span><br/><span class="hl-2">});</span>
</code><button type="button">Copy</button></pre>
<h2 id="public-api-overview" class="tsd-anchor-link">Public API Overview<a href="#public-api-overview" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<pre><code class="ts"><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">LilySdk</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'@lily-protocol/sdk'</span><span class="hl-2">;</span><br/><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">sdk</span><span class="hl-2"> = </span><span class="hl-6">new</span><span class="hl-2"> </span><span class="hl-5">LilySdk</span><span class="hl-2">({ </span><span class="hl-3">baseUrl:</span><span class="hl-2"> </span><span class="hl-4">'https://api.lilyprotocol.com'</span><span class="hl-2"> });</span><br/><br/><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">agents</span><span class="hl-2">.</span><span class="hl-5">list</span><span class="hl-2">();</span><br/><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">wallets</span><span class="hl-2">.</span><span class="hl-5">provision</span><span class="hl-2">({ </span><span class="hl-3">agentId:</span><span class="hl-2"> </span><span class="hl-4">'agent_123'</span><span class="hl-2">, </span><span class="hl-3">network:</span><span class="hl-2"> </span><span class="hl-4">'stellar-testnet'</span><span class="hl-2"> });</span><br/><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">payments</span><span class="hl-2">.</span><span class="hl-5">quote</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-3">fromWalletId:</span><span class="hl-2"> </span><span class="hl-4">'wallet_123'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">toAddress:</span><span class="hl-2"> </span><span class="hl-4">'GB...'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> { </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'USDC'</span><span class="hl-2">, </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-4">'10.00'</span><span class="hl-2"> },</span><br/><span class="hl-2">});</span><br/><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">identity</span><span class="hl-2">.</span><span class="hl-5">resolve</span><span class="hl-2">({ </span><span class="hl-3">agentId:</span><span class="hl-2"> </span><span class="hl-4">'agent_123'</span><span class="hl-2"> });</span><br/><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">system</span><span class="hl-2">.</span><span class="hl-5">health</span><span class="hl-2">();</span><br/><br/><span class="hl-0">// Low-level escape hatch: the active HttpClient (injected or default)</span><br/><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">http</span><span class="hl-2">.</span><span class="hl-5">request</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-3">method:</span><span class="hl-2"> </span><span class="hl-4">'GET'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">path:</span><span class="hl-2"> </span><span class="hl-4">'/v1/system/health'</span><span class="hl-2">,</span><br/><span class="hl-2">});</span>
</code><button type="button">Copy</button></pre>
<p>The root entrypoint also exposes the transport layer for custom clients and tests:</p>
<pre><code class="ts"><span class="hl-1">import</span><span class="hl-2"> {</span><br/><span class="hl-2"> </span><span class="hl-3">BaseClient</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">createFetchHttpClient</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">HttpClient</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">HttpHeaders</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">HttpRequest</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">HttpResponse</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">RetryPolicy</span><span class="hl-2">,</span><br/><span class="hl-2">} </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'@lily-protocol/sdk'</span><span class="hl-2">;</span><br/><br/><span class="hl-6">class</span><span class="hl-2"> </span><span class="hl-9">MyClient</span><span class="hl-2"> </span><span class="hl-6">extends</span><span class="hl-2"> </span><span class="hl-9">BaseClient</span><span class="hl-2"> {</span><br/><span class="hl-2"> </span><span class="hl-6">async</span><span class="hl-2"> </span><span class="hl-5">health</span><span class="hl-2">() {</span><br/><span class="hl-2"> </span><span class="hl-1">return</span><span class="hl-2"> </span><span class="hl-6">this</span><span class="hl-2">.</span><span class="hl-5">request</span><span class="hl-2"><{ </span><span class="hl-3">status</span><span class="hl-2">: </span><span class="hl-9">string</span><span class="hl-2"> }>({</span><br/><span class="hl-2"> </span><span class="hl-3">method:</span><span class="hl-2"> </span><span class="hl-4">'GET'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">path:</span><span class="hl-2"> </span><span class="hl-4">'/v1/system/health'</span><span class="hl-2">,</span><br/><span class="hl-2"> });</span><br/><span class="hl-2"> }</span><br/><span class="hl-2">}</span><br/><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">httpClient</span><span class="hl-2"> = </span><span class="hl-5">createFetchHttpClient</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-3">baseUrl:</span><span class="hl-2"> </span><span class="hl-4">'https://api.lilyprotocol.com'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">authToken:</span><span class="hl-2"> </span><span class="hl-3">process</span><span class="hl-2">.</span><span class="hl-3">env</span><span class="hl-2">.</span><span class="hl-7">LILY_AUTH_TOKEN</span><span class="hl-2">,</span><br/><span class="hl-2">});</span><br/><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">client</span><span class="hl-2"> = </span><span class="hl-6">new</span><span class="hl-2"> </span><span class="hl-5">MyClient</span><span class="hl-2">(</span><span class="hl-3">httpClient</span><span class="hl-2">);</span>
</code><button type="button">Copy</button></pre>
<h2 id="domain-models" class="tsd-anchor-link">Domain Models<a href="#domain-models" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="and-stellar-asset-semantics" class="tsd-anchor-link"><code>MoneyAmount</code> and Stellar Asset Semantics<a href="#and-stellar-asset-semantics" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p><code>MoneyAmount</code> (defined in <code>src/models/common.ts</code>) is the core model representing currency amounts and asset specifications across the Lily SDK, including wallet balances (<code>Wallet.balances</code>), payment quoting (<code>PaymentQuoteRequest</code>, <code>PaymentQuote</code>), and payment execution (<code>ExecutePaymentRequest</code>, <code>Payment</code>).</p>
<pre><code class="ts"><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-6">interface</span><span class="hl-2"> </span><span class="hl-9">MoneyAmount</span><span class="hl-2"> {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode</span><span class="hl-2">: </span><span class="hl-9">string</span><span class="hl-2">;</span><br/><span class="hl-2"> </span><span class="hl-3">assetIssuer</span><span class="hl-2">?: </span><span class="hl-9">string</span><span class="hl-2">;</span><br/><span class="hl-2"> </span><span class="hl-3">amount</span><span class="hl-2">: </span><span class="hl-9">string</span><span class="hl-2">;</span><br/><span class="hl-2">}</span>
</code><button type="button">Copy</button></pre>
<h4 id="decimal-string-semantics-" class="tsd-anchor-link">Decimal-String Semantics (<code>amount</code>)<a href="#decimal-string-semantics-" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
<ul>
<li><strong>String, Never Float:</strong> The <code>amount</code> field is strictly typed as a base-10 decimal <code>string</code> (e.g. <code>'10.50'</code>), <strong>never</strong> a JavaScript <code>number</code>.</li>
<li><strong>Float Precision Rationale:</strong> Standard JavaScript numbers are IEEE 754 floating-point values, which cannot precisely represent fractional base-10 amounts (for instance, <code>0.1 + 0.2 === 0.30000000000000004</code>). In financial transactions and agent autonomous settlements, floating-point math can lead to subtle truncation bugs and balance mismatches. Using decimal strings ensures exact arithmetic and lossless serialization across API boundaries.</li>
<li><strong>Precision Expectations:</strong> On the Stellar network, amounts support up to 7 decimal places of precision, corresponding to the smallest Stellar unit: 1 stroop (<code>0.0000001 XLM</code> = <code>10^-7 XLM</code>). Amounts passed in <code>MoneyAmount</code> should reflect exact decimal values up to 7 fractional digits (or the designated precision of the custom asset).</li>
</ul>
<h4 id="native-vs-issued-assets-" class="tsd-anchor-link">Native vs. Issued Assets (<code>assetCode</code> & <code>assetIssuer</code>)<a href="#native-vs-issued-assets-" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
<p>Stellar distinguishes between native network lumens and custom issued assets:</p>
<ul>
<li><strong>Native Asset (<code>XLM</code>):</strong>
<ul>
<li><code>assetCode</code>: Set to <code>'XLM'</code>.</li>
<li><code>assetIssuer</code>: Must be omitted or <code>undefined</code>. The native asset is built into the ledger and has no issuing account.</li>
</ul>
</li>
<li><strong>Issued Credit Assets (e.g., <code>USDC</code>, <code>EURC</code>):</strong>
<ul>
<li><code>assetCode</code>: 1 to 12 character alphanumeric string (Alpha4 for 1–4 characters such as <code>'USDC'</code>, Alpha12 for 5–12 characters).</li>
<li><code>assetIssuer</code>: The 56-character base32-encoded Stellar public key (G-address, e.g. <code>'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN'</code>) of the issuing account or anchor.</li>
</ul>
</li>
<li><strong>Relationship to Stellar <code>Asset</code> and Home Domains:</strong>
<ul>
<li>In the Stellar protocol, an issued asset is uniquely identified by the pair <code>(assetCode, assetIssuer)</code>. Two assets with the identical code issued by different accounts represent separate, distinct assets.</li>
<li>Stellar issuing accounts publish a <code>home_domain</code> in their account records for SEP-1 TOML discovery, allowing clients to resolve issuer legitimacy and asset metadata.</li>
</ul>
</li>
</ul>
<h4 id="asset-code-and-amount-validation" class="tsd-anchor-link">Asset Code and Amount Validation<a href="#asset-code-and-amount-validation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
<ul>
<li><strong>Validation Rules:</strong> Asset codes and issuer addresses are validated by Lily backend APIs and verified on-chain by Stellar Horizon/RPC nodes during transaction submission.</li>
<li><strong>Asset Code Constraints:</strong> Alphanumeric characters only (<code>[a-zA-Z0-9]</code>), length between 1 and 12 characters.</li>
<li><strong>Issuer Key Constraints:</strong> Valid 56-character Ed25519 public key starting with <code>G</code> with a valid checksum.</li>
<li><strong>Amount Constraints:</strong> Positive base-10 decimal strings (e.g. <code>'10.50'</code>, <code>'0.0000001'</code>). Negative numbers, exponential/scientific notation (e.g. <code>'1e-5'</code>), and non-numeric characters are invalid.</li>
</ul>
<h4 id="examples-valid-and-invalid" class="tsd-anchor-link">Examples: Valid and Invalid <code>MoneyAmount</code><a href="#examples-valid-and-invalid" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
<pre><code class="ts"><span class="hl-1">import</span><span class="hl-2"> </span><span class="hl-1">type</span><span class="hl-2"> { </span><span class="hl-3">MoneyAmount</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'@lily-protocol/sdk'</span><span class="hl-2">;</span><br/><br/><span class="hl-0">// ✅ Valid: Native XLM (no issuer, 7 decimal places)</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">validNative</span><span class="hl-2">: </span><span class="hl-9">MoneyAmount</span><span class="hl-2"> = {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'XLM'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-4">'25.5000000'</span><span class="hl-2">,</span><br/><span class="hl-2">};</span><br/><br/><span class="hl-0">// ✅ Valid: Issued asset (USDC with 56-char G-address issuer)</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">validIssued</span><span class="hl-2">: </span><span class="hl-9">MoneyAmount</span><span class="hl-2"> = {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'USDC'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">assetIssuer:</span><span class="hl-2"> </span><span class="hl-4">'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-4">'100.00'</span><span class="hl-2">,</span><br/><span class="hl-2">};</span><br/><br/><span class="hl-0">// ✅ Valid: Minimum Stellar unit (1 stroop)</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">validStroop</span><span class="hl-2">: </span><span class="hl-9">MoneyAmount</span><span class="hl-2"> = {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'XLM'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-4">'0.0000001'</span><span class="hl-2">,</span><br/><span class="hl-2">};</span><br/><br/><span class="hl-0">// ✅ Valid: Whole integer amount as decimal string</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">validInteger</span><span class="hl-2">: </span><span class="hl-9">MoneyAmount</span><span class="hl-2"> = {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'XLM'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-4">'50'</span><span class="hl-2">,</span><br/><span class="hl-2">};</span><br/><br/><span class="hl-0">// ❌ Invalid: Using a number instead of a decimal string</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">invalidFloat</span><span class="hl-2"> = {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'XLM'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-8">10.5</span><span class="hl-2">, </span><span class="hl-0">// Type error: amount must be a string to avoid float precision bugs</span><br/><span class="hl-2">};</span><br/><br/><span class="hl-0">// ❌ Invalid: Scientific / exponential notation is not allowed</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">invalidExponential</span><span class="hl-2">: </span><span class="hl-9">MoneyAmount</span><span class="hl-2"> = {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'XLM'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-4">'1e-7'</span><span class="hl-2">, </span><span class="hl-0">// Invalid format: must be standard decimal string</span><br/><span class="hl-2">};</span><br/><br/><span class="hl-0">// ❌ Invalid: Incomplete decimal point notation</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">invalidDecimal</span><span class="hl-2">: </span><span class="hl-9">MoneyAmount</span><span class="hl-2"> = {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'XLM'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-4">'10.'</span><span class="hl-2">, </span><span class="hl-0">// Invalid format: missing fractional digits</span><br/><span class="hl-2">};</span><br/><br/><span class="hl-0">// ❌ Invalid: Native asset (XLM) with an issuer</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">invalidNativeIssuer</span><span class="hl-2">: </span><span class="hl-9">MoneyAmount</span><span class="hl-2"> = {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'XLM'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-3">assetIssuer:</span><span class="hl-2"> </span><span class="hl-4">'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN'</span><span class="hl-2">, </span><span class="hl-0">// XLM has no issuer</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-4">'10.00'</span><span class="hl-2">,</span><br/><span class="hl-2">};</span><br/><br/><span class="hl-0">// ❌ Invalid: Issued asset without the required assetIssuer</span><br/><span class="hl-6">const</span><span class="hl-2"> </span><span class="hl-7">invalidMissingIssuer</span><span class="hl-2">: </span><span class="hl-9">MoneyAmount</span><span class="hl-2"> = {</span><br/><span class="hl-2"> </span><span class="hl-3">assetCode:</span><span class="hl-2"> </span><span class="hl-4">'USDC'</span><span class="hl-2">, </span><span class="hl-0">// Issued assets require assetIssuer to identify the anchor</span><br/><span class="hl-2"> </span><span class="hl-3">amount:</span><span class="hl-2"> </span><span class="hl-4">'100.00'</span><span class="hl-2">,</span><br/><span class="hl-2">};</span>
</code><button type="button">Copy</button></pre>
<h2 id="repository-structure" class="tsd-anchor-link">Repository Structure<a href="#repository-structure" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<pre><code class="text">src/
clients/ domain-oriented SDK modules
config/ SDK configuration types and resolution
errors/ typed SDK error hierarchy
http/ transport abstraction and fetch implementation
models/ public request/response and domain model types
types/ client contracts and shared public contracts
tests/ unit tests and test helpers
examples/ runnable local examples
.github/ CI and contributor workflow templates
</code><button type="button">Copy</button></pre>
<h2 id="testing" class="tsd-anchor-link">Testing<a href="#testing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>npm test</code></td>
<td>Run tests with coverage (default)</td>
</tr>
<tr>
<td><code>npm run test:unit</code></td>
<td>Fast tests without coverage instrumentation</td>
</tr>
<tr>
<td><code>npm run test:coverage</code></td>
<td>Explicit coverage run (same as <code>npm test</code>)</td>
</tr>
<tr>
<td><code>npm run test:watch</code></td>
<td>Watch mode for development</td>
</tr>
</tbody>
</table>
<h2 id="development" class="tsd-anchor-link">Development<a href="#development" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<pre><code class="bash"><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">install</span><br/><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">run</span><span class="hl-2"> </span><span class="hl-4">lint</span><br/><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">run</span><span class="hl-2"> </span><span class="hl-4">typecheck</span><br/><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">run</span><span class="hl-2"> </span><span class="hl-4">test:unit</span><br/><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">run</span><span class="hl-2"> </span><span class="hl-4">test:coverage</span><br/><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">run</span><span class="hl-2"> </span><span class="hl-4">test</span><br/><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">run</span><span class="hl-2"> </span><span class="hl-4">build</span>
</code><button type="button">Copy</button></pre>
<p>Run the example:</p>
<pre><code class="bash"><span class="hl-5">npm</span><span class="hl-2"> </span><span class="hl-4">run</span><span class="hl-2"> </span><span class="hl-4">example</span>
</code><button type="button">Copy</button></pre>
<h2 id="error-handling" class="tsd-anchor-link">Error Handling<a href="#error-handling" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>All SDK errors extend <code>LilySdkError</code>. Use <code>isLilySdkError</code> to safely narrow an
unknown caught value and <code>LILY_ERROR_CODES</code> to compare transport error codes
without hardcoded strings:</p>
<pre><code class="ts"><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">isLilySdkError</span><span class="hl-2">, </span><span class="hl-3">LILY_ERROR_CODES</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'@lily-protocol/sdk'</span><span class="hl-2">;</span><br/><br/><span class="hl-1">try</span><span class="hl-2"> {</span><br/><span class="hl-2"> </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-3">sdk</span><span class="hl-2">.</span><span class="hl-3">system</span><span class="hl-2">.</span><span class="hl-5">health</span><span class="hl-2">();</span><br/><span class="hl-2">} </span><span class="hl-1">catch</span><span class="hl-2"> (</span><span class="hl-3">error</span><span class="hl-2">) {</span><br/><span class="hl-2"> </span><span class="hl-1">if</span><span class="hl-2"> (</span><span class="hl-5">isLilySdkError</span><span class="hl-2">(</span><span class="hl-3">error</span><span class="hl-2">) && </span><span class="hl-3">error</span><span class="hl-2">.</span><span class="hl-3">code</span><span class="hl-2"> === </span><span class="hl-7">LILY_ERROR_CODES</span><span class="hl-2">.</span><span class="hl-7">TIMEOUT</span><span class="hl-2">) {</span><br/><span class="hl-2"> </span><span class="hl-0">// Handle a request timeout.</span><br/><span class="hl-2"> }</span><br/><span class="hl-2">}</span>
</code><button type="button">Copy</button></pre>
<p>The transport uses <code>API_ERROR</code>, <code>AUTHENTICATION_ERROR</code>, <code>TIMEOUT</code>, and
<code>TRANSPORT_ERROR</code>. Their typed values are available from <code>LILY_ERROR_CODES</code>.</p>
<h2 id="design-notes" class="tsd-anchor-link">Design Notes<a href="#design-notes" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li><code>LilySdk</code> composes a shared transport with focused domain clients instead of exposing a single massive client surface. The resolved <code>HttpClient</code> is also available as <code>sdk.http</code> for one-off raw requests that must reuse the SDK's transport and config.</li>
<li>Models are exported from stable entrypoints so future internal refactors do not require a public breaking change.</li>
<li>The HTTP layer is intentionally small and swappable, which keeps backend integration work easy to test and contributor-friendly.</li>
<li>Timed-out GET, PUT, and DELETE requests use the configured retry budget; non-idempotent requests fail immediately on timeout.</li>
</ul>
<h2 id="changelog" class="tsd-anchor-link">Changelog<a href="#changelog" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>See <a href="media/CHANGELOG.md">CHANGELOG.md</a> for a full list of changes. The changelog follows <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> and is updated with every release.</p>
<h2 id="roadmap-themes" class="tsd-anchor-link">Roadmap Themes<a href="#roadmap-themes" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li>Real backend endpoint alignment and response model hardening</li>
<li>Pagination helpers and richer idempotency ergonomics</li>
<li>Webhook verification, observability hooks, and advanced auth flows</li>
<li>More complete Stellar asset and payment orchestration coverage</li>
</ul>
<h2 id="contributing" class="tsd-anchor-link">Contributing<a href="#contributing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>Please read <a href="media/CONTRIBUTING.md">CONTRIBUTING.md</a> before opening a pull request.</p>
</div></div>
<div class="col-sidebar">
<div class="page-menu">
<div class="tsd-navigation settings">
<details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>
<h3>Settings</h3></summary>
<div class="tsd-accordion-details">
<div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span>
<ul id="tsd-filter-options">
<li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li>
<li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li>
<li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div>
<div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div>
<details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>
<h3>On This Page</h3></summary>
<div class="tsd-accordion-details"><a href="#lily-sdk"><span>Lily <wbr/>SDK</span></a>
<ul>
<li><a href="#security"><span>Security</span></a></li>
<li><a href="#status"><span>Status</span></a></li>
<li><a href="#features"><span>Features</span></a></li>
<li><a href="#browser-support"><span>Browser <wbr/>Support</span></a></li>
<li><a href="#installation"><span>Installation</span></a></li>
<li>
<ul>
<li><a href="#browser-support-1"><span>Browser support</span></a></li></ul></li>
<li><a href="#requirements-compatibility"><span>Requirements & <wbr/>Compatibility</span></a></li>
<li><a href="#quick-start"><span>Quick <wbr/>Start</span></a></li>
<li><a href="#configuration"><span>Configuration</span></a></li>
<li>
<ul>
<li><a href="#retry-semantics"><span>Retry semantics</span></a></li>
<li><a href="#example"><span>Example</span></a></li></ul></li>
<li><a href="#public-api-overview"><span>Public <wbr/>API <wbr/>Overview</span></a></li>
<li><a href="#domain-models"><span>Domain <wbr/>Models</span></a></li>
<li>
<ul>
<li><a href="#and-stellar-asset-semantics"><span> and <wbr/>Stellar <wbr/>Asset <wbr/>Semantics</span></a></li>
<li>
<ul>
<li><a href="#decimal-string-semantics-"><span>Decimal-<wbr/>String <wbr/>Semantics ()</span></a></li>
<li><a href="#native-vs-issued-assets-"><span>Native vs. <wbr/>Issued <wbr/>Assets ( & )</span></a></li>
<li><a href="#asset-code-and-amount-validation"><span>Asset <wbr/>Code and <wbr/>Amount <wbr/>Validation</span></a></li>
<li><a href="#examples-valid-and-invalid"><span>Examples: <wbr/>Valid and <wbr/>Invalid </span></a></li></ul></li></ul></li>
<li><a href="#repository-structure"><span>Repository <wbr/>Structure</span></a></li>
<li><a href="#testing"><span>Testing</span></a></li>
<li><a href="#development"><span>Development</span></a></li>
<li><a href="#error-handling"><span>Error <wbr/>Handling</span></a></li>
<li><a href="#design-notes"><span>Design <wbr/>Notes</span></a></li>
<li><a href="#changelog"><span>Changelog</span></a></li>
<li><a href="#roadmap-themes"><span>Roadmap <wbr/>Themes</span></a></li>
<li><a href="#contributing"><span>Contributing</span></a></li></ul></div></details></div>
<div class="site-menu">
<nav class="tsd-navigation"><a href="modules.html">@lily-protocol/sdk</a>
<ul class="tsd-small-nested-navigation" id="tsd-nav-container">
<li>Loading...</li></ul></nav></div></div></div><footer>
<p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer>
<div class="overlay"></div></body></html>