@liberfi.io/types 0.3.13 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +119 -57
- package/dist/api/index.d.mts +1829 -0
- package/dist/api/index.d.ts +1829 -0
- package/dist/api/index.js +37 -0
- package/dist/api/index.js.map +1 -0
- package/dist/api/index.mjs +10 -0
- package/dist/api/index.mjs.map +1 -0
- package/dist/index.d.mts +1 -1842
- package/dist/index.d.ts +1 -1842
- package/dist/index.js +3 -20
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2 -23
- package/dist/index.mjs.map +1 -1
- package/package.json +7 -2
package/README.md
CHANGED
|
@@ -1,13 +1,32 @@
|
|
|
1
1
|
# @liberfi.io/types
|
|
2
2
|
|
|
3
|
-
Pure TypeScript type-definition package with zero runtime dependencies
|
|
3
|
+
Pure TypeScript type-definition package with **zero runtime dependencies**;
|
|
4
|
+
the package itself ships only types plus a few derived enum constants
|
|
5
|
+
(`Chain`, `ChainNamespace`, `SolanaTokenProtocol`, `SwapMode`,
|
|
6
|
+
`SOLANA_TOKEN_PROTOCOLS`). Serves as the **single source of truth** for
|
|
7
|
+
domain types and API contract interfaces across the entire LiberFi React
|
|
8
|
+
SDK monorepo. Consumed by `@liberfi.io/client`, `@liberfi.io/react`, and
|
|
9
|
+
all UI packages.
|
|
4
10
|
|
|
5
11
|
## Design Philosophy
|
|
6
12
|
|
|
7
|
-
- **Zero runtime dependencies** —
|
|
8
|
-
|
|
9
|
-
- **
|
|
10
|
-
|
|
13
|
+
- **Zero runtime dependencies** — no third-party packages at runtime;
|
|
14
|
+
consumers pay only for the enums / constants they actually import.
|
|
15
|
+
- **Domain vs API contract layering** — domain models (`Token`,
|
|
16
|
+
`Activity`, `Chain`, `Portfolio`, etc.) are cleanly separated from API
|
|
17
|
+
contract interfaces (`IClient`, `ISubscribeClient`), with one-directional
|
|
18
|
+
imports from domain → API.
|
|
19
|
+
- **Open literal types** — patterns like
|
|
20
|
+
`TokenProtocol = SolanaTokenProtocol | (string & {})` and
|
|
21
|
+
`SwapDex = "jupiter" | "kyberswap" | (string & {})` give autocomplete
|
|
22
|
+
for known values while remaining extensible for future additions.
|
|
23
|
+
- **Interface-based abstraction** — `IClient` and `ISubscribeClient`
|
|
24
|
+
define the API surface abstractly, enabling different implementations
|
|
25
|
+
(production client, mocks, stubs) without coupling consumers to a
|
|
26
|
+
concrete class.
|
|
27
|
+
- **Single tag vocabulary** — wallet classification across token-holding,
|
|
28
|
+
activity, and portfolio contexts is unified into a single `WalletTag`
|
|
29
|
+
type rather than three structurally identical aliases.
|
|
11
30
|
|
|
12
31
|
## Installation
|
|
13
32
|
|
|
@@ -17,6 +36,31 @@ pnpm add @liberfi.io/types
|
|
|
17
36
|
|
|
18
37
|
No peer dependencies required.
|
|
19
38
|
|
|
39
|
+
## Sub-path Exports
|
|
40
|
+
|
|
41
|
+
The package exposes two entry points:
|
|
42
|
+
|
|
43
|
+
| Entry point | Purpose |
|
|
44
|
+
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
45
|
+
| `@liberfi.io/types` | Default — every type re-exported flat (domain + API contract). |
|
|
46
|
+
| `@liberfi.io/types/api` | API contract subset only (`IClient`, `ISubscribeClient`, swap / transaction / option types, subscription payloads, cursor pagination). |
|
|
47
|
+
|
|
48
|
+
Use the sub-path entry when you want to address API contract types as a
|
|
49
|
+
group (e.g. while mocking the client layer):
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
import * as API from "@liberfi.io/types/api";
|
|
53
|
+
|
|
54
|
+
const mockClient: API.IClient = {
|
|
55
|
+
/* ... */
|
|
56
|
+
};
|
|
57
|
+
const params: API.SwapParams = {
|
|
58
|
+
/* ... */
|
|
59
|
+
};
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
For everyday usage, prefer flat named imports from the package root.
|
|
63
|
+
|
|
20
64
|
## API Reference
|
|
21
65
|
|
|
22
66
|
### Enums
|
|
@@ -30,43 +74,46 @@ No peer dependencies required.
|
|
|
30
74
|
|
|
31
75
|
### Domain Interfaces — Token
|
|
32
76
|
|
|
33
|
-
| Type | Description
|
|
34
|
-
| ------------------------ |
|
|
35
|
-
| `Token` | Core token model with metadata, stats, market data, liquidity, security, and social links.
|
|
36
|
-
| `TokenCreator` | Token creator info: address, share percentage, verification status.
|
|
37
|
-
| `TokenLaunchedFrom` | Launch platform details: program address and protocol family.
|
|
38
|
-
| `TokenMigratedTo` | Migration target: program address, protocol family, pool address, timestamp.
|
|
39
|
-
| `TokenSocialMedias` | Social media URLs (twitter, telegram, website, discord, github, etc.).
|
|
40
|
-
| `TokenStats` | Per-resolution (`1m`–`24h`) trading statistics container.
|
|
41
|
-
| `TokenStatsByResolution` | Single-resolution stats: buys, sells, traders, volumes, OHLC prices, price change.
|
|
42
|
-
| `TokenMarketData` | Market data: supply, market cap, price, TVL, holder breakdowns by tag (bluechip, KOL, sniper, pro, insider
|
|
43
|
-
| `TokenLiquidity` | Liquidity pool info: pool/pair address, protocol, TVL.
|
|
44
|
-
| `TokenSecurity` | Security flags: transfer fee, freezable, closable, transferable.
|
|
45
|
-
| `TokenCandle` | OHLCV candlestick data point with resolution and timestamp.
|
|
46
|
-
| `TokenHolder` | Single holder: address, amount, USD value, holding ratio. Phase 3: `tags`, `lastActiveAt`, `startHoldingAt`.
|
|
47
|
-
| `HolderTag` | Classification tag for a holder (`kol` / `smart` / `sniper` / `dev` / `bundle` / `bluechip` / `(string & {})`). |
|
|
77
|
+
| Type | Description |
|
|
78
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
|
79
|
+
| `Token` | Core token model with metadata, stats, market data, liquidity, security, and social links. |
|
|
80
|
+
| `TokenCreator` | Token creator info: address, share percentage, verification status. |
|
|
81
|
+
| `TokenLaunchedFrom` | Launch platform details: program address and protocol family. |
|
|
82
|
+
| `TokenMigratedTo` | Migration target: program address, protocol family, pool address, timestamp. |
|
|
83
|
+
| `TokenSocialMedias` | Social media URLs (twitter, telegram, website, discord, github, etc.). |
|
|
84
|
+
| `TokenStats` | Per-resolution (`1m`–`24h`) trading statistics container. |
|
|
85
|
+
| `TokenStatsByResolution` | Single-resolution stats: buys, sells, traders, volumes, OHLC prices, price change. |
|
|
86
|
+
| `TokenMarketData` | Market data: supply, market cap, price, TVL, holder breakdowns by tag (bluechip, KOL, sniper, pro, insider). |
|
|
87
|
+
| `TokenLiquidity` | Liquidity pool info: pool/pair address, protocol, TVL. |
|
|
88
|
+
| `TokenSecurity` | Security flags: transfer fee, freezable, closable, transferable. |
|
|
89
|
+
| `TokenCandle` | OHLCV candlestick data point with resolution and timestamp. |
|
|
90
|
+
| `TokenHolder` | Single holder: address, amount, USD value, holding ratio. Phase 3: `tags`, `lastActiveAt`, `startHoldingAt`. |
|
|
48
91
|
|
|
49
92
|
### Domain Interfaces — Activity
|
|
50
93
|
|
|
51
94
|
| Type | Description |
|
|
52
|
-
| --------------- | ----------------------------------------------------------------------------------------- |
|
|
95
|
+
| --------------- | ----------------------------------------------------------------------------------------- |
|
|
53
96
|
| `Activity` | On-chain activity record (trade, liquidity, red packet). Phase 3: `gasFee`, `traderTags`. |
|
|
54
97
|
| `ActivityToken` | Token within an activity: address, symbol, amount, USD values. |
|
|
55
98
|
| `ActivityDex` | DEX where the activity occurred: name, image, protocol family, program address. |
|
|
56
|
-
| `
|
|
57
|
-
| `Trade` | Narrowed subset of `Activity` with `type: "buy" | "sell"`. |
|
|
99
|
+
| `Trade` | Narrowed subset of `Activity` with `type: "buy" \| "sell"`. |
|
|
58
100
|
|
|
59
101
|
### Domain Interfaces — Wallet & Portfolio
|
|
60
102
|
|
|
61
103
|
| Type | Description |
|
|
62
104
|
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
63
105
|
| `Portfolio` | Wallet's token holding: price, amount, decimals. Phase 3: `isActive`, `avgCostUsd`, `lastActiveAt`, `walletTokenTags`. |
|
|
64
|
-
| `WalletTokenTag` | Classification tag applied to a wallet-token relationship (e.g. `held`, `sold`, `bluechip`). |
|
|
65
106
|
| `PortfolioPnl` | Per-token PnL details: buy/sell volumes, avg prices, realized/unrealized profit. Phase 3: `isClosed`, `firstBuyAt`, `lastSellAt`. |
|
|
66
107
|
| `WalletPnl` | Wallet-level PnL summary: win rate, total trades, profit breakdown. |
|
|
67
108
|
| `WalletPortfolioPnls` | Paginated portfolio PnL list with wallet-level summary (extends `WalletPnl` + `CursorPagination`). |
|
|
68
109
|
| `WalletPortfolios` | Paginated wallet portfolios with total balance (extends `CursorPagination`). |
|
|
69
110
|
|
|
111
|
+
### Tag
|
|
112
|
+
|
|
113
|
+
| Type | Description |
|
|
114
|
+
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
115
|
+
| `WalletTag` | Single classification tag vocabulary used across token-holding (`Token.holders[i].tags`), activity (`Activity.traderTags`), and portfolio (`Portfolio.walletTokenTags`) contexts. Known values: `kol`, `smart`, `sniper`, `dev`, `bundle`, `bluechip`. Open union via `(string & {})`. |
|
|
116
|
+
|
|
70
117
|
### API Contract — Pagination
|
|
71
118
|
|
|
72
119
|
| Type | Description |
|
|
@@ -77,22 +124,24 @@ No peer dependencies required.
|
|
|
77
124
|
|
|
78
125
|
### API Contract — Query Options
|
|
79
126
|
|
|
80
|
-
| Type | Description
|
|
81
|
-
| ------------------------------- |
|
|
82
|
-
| `GetTokenCandlesOptions` | Candle query options: `after`, `before` (Date), `limit`.
|
|
83
|
-
| `GetTokenListOptions` | Token list options: `sortBy`, `sortDirection`, `filters`, `keywords`, `excludeKeywords`.
|
|
84
|
-
| `SearchTokensOptions` | Search options (extends `CursorListOptions`): `chains`, `keyword`, `filters`, `sortBy`, `sortDirection`.
|
|
85
|
-
| `SearchTokenCursorList` | Search result (extends `CursorList<Token>`): adds `total` count and `extra` metadata.
|
|
86
|
-
| `TokenFilterOption` | Filter descriptor: `field` (TokenFieldOption), `operator` (eq/gt/between/in
|
|
87
|
-
| `GetTradesOptions` | Trade query options (extends `CursorListOptions`): `before`, `after`, `beforeBlockHeight`, `afterBlockHeight`, `type`, `poolAddress`.
|
|
88
|
-
| `GetActivitiesOptions` | Activity query options (extends `CursorListOptions`): time/block filters plus `type`, and (Phase 3) `sortBy` (`timestamp` / `totalUsd`).
|
|
89
|
-
| `GetTokenHoldersOptions` | Token holder query options (extends `CursorListOptions`): Phase 3 `sortBy` (`amount` / `usd` / `ratio` / `lastActiveAt`).
|
|
90
|
-
| `GetWalletPortfolioPnlsOptions` | Wallet PnL detail query options (extends `CursorListOptions`): Phase 3 `resolution` (
|
|
127
|
+
| Type | Description |
|
|
128
|
+
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
129
|
+
| `GetTokenCandlesOptions` | Candle query options: `after`, `before` (Date), `limit`. |
|
|
130
|
+
| `GetTokenListOptions` | Token list options: `sortBy`, `sortDirection`, `filters`, `keywords`, `excludeKeywords`. |
|
|
131
|
+
| `SearchTokensOptions` | Search options (extends `CursorListOptions`): `chains`, `keyword`, `filters`, `sortBy`, `sortDirection`. |
|
|
132
|
+
| `SearchTokenCursorList` | Search result (extends `CursorList<Token>`): adds `total` count and `extra` metadata. |
|
|
133
|
+
| `TokenFilterOption` | Filter descriptor: `field` (`TokenFieldOption`), `operator` (`eq` / `gt` / `between` / `in` / …), `value`. |
|
|
134
|
+
| `GetTradesOptions` | Trade query options (extends `CursorListOptions`): `before`, `after`, `beforeBlockHeight`, `afterBlockHeight`, `type`, `poolAddress`. |
|
|
135
|
+
| `GetActivitiesOptions` | Activity query options (extends `CursorListOptions`): time/block filters plus `type`, and (Phase 3) `sortBy` (`timestamp` / `totalUsd`). |
|
|
136
|
+
| `GetTokenHoldersOptions` | Token holder query options (extends `CursorListOptions`): Phase 3 `sortBy` (`amount` / `usd` / `ratio` / `lastActiveAt`). |
|
|
137
|
+
| `GetWalletPortfolioPnlsOptions` | Wallet PnL detail query options (extends `CursorListOptions`): Phase 3 `resolution` (`WalletPnlResolution`, required), `positionState` (`open` / `closed` / `all`), `sortBy` (`pnl` / `totalUsd` / `winRate`). |
|
|
138
|
+
| `WalletPnlResolution` | Allowed resolution values for wallet PnL queries: `7d` / `30d` / `90d`. |
|
|
91
139
|
|
|
92
140
|
### API Contract — Swap & Transaction
|
|
93
141
|
|
|
94
142
|
| Type | Description |
|
|
95
143
|
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
144
|
+
| `SwapDex` | Aggregator id: `"jupiter" \| "kyberswap" \| (string & {})`. |
|
|
96
145
|
| `SwapParams` | Swap request: chain, addresses, mode, amount, slippage, fees, anti-MEV flag. |
|
|
97
146
|
| `SwapRoute` | Swap response: serialized unsigned transaction, route plans, and optional Solana blockhash expiry metadata. |
|
|
98
147
|
| `SwapRoutePlan` | Single route plan step: protocol name, input/output tokens and amounts, fees. |
|
|
@@ -127,7 +176,11 @@ interface IClient {
|
|
|
127
176
|
sendTx(params: SendTxParams): Promise<SendTxResult>;
|
|
128
177
|
checkTxSuccess(chain, txHash, timeout?): Promise<boolean>;
|
|
129
178
|
getWalletPortfolios(chain, address, options?): Promise<WalletPortfolios>;
|
|
130
|
-
getWalletPnl(
|
|
179
|
+
getWalletPnl(
|
|
180
|
+
chain,
|
|
181
|
+
address,
|
|
182
|
+
resolution?: WalletPnlResolution,
|
|
183
|
+
): Promise<WalletPnl>;
|
|
131
184
|
getWalletPortfolioPnls(
|
|
132
185
|
chain,
|
|
133
186
|
address,
|
|
@@ -187,32 +240,25 @@ interface ISubscription {
|
|
|
187
240
|
| Type | Description |
|
|
188
241
|
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
189
242
|
| `TokenSubscribed` | Incremental token update — `chain` + `address` required, all other `Token` fields optional (`undefined` = not included in this push). |
|
|
190
|
-
| `WalletPnlSubscribed` | `WalletPnl` extended with optional `resolution
|
|
243
|
+
| `WalletPnlSubscribed` | `WalletPnl` extended with optional `resolution: WalletPnlResolution`. |
|
|
191
244
|
| `PortfolioSubscribed` | Lightweight portfolio update: chain, wallet address, token address, price, amount. |
|
|
192
245
|
| `PortfolioPnlSubscribed` | Partial `PortfolioPnl` keyed by `walletAddress` + `tokenAddress`. |
|
|
193
246
|
|
|
194
247
|
### Type Aliases
|
|
195
248
|
|
|
196
|
-
| Type | Definition
|
|
197
|
-
| -------------------- |
|
|
198
|
-
| `TokenProtocol` | `SolanaTokenProtocol \| (string & {})`
|
|
199
|
-
| `ActivityType` | `"buy" \| "sell" \| "liquidity_initialize" \| "liquidity_add" \| ...`
|
|
200
|
-
| `TokenResolution` | `"1s" \| "15s" \| "30s" \| "1m" \| ... \| "24h"`
|
|
201
|
-
| `TrendingResolution` | `Extract<TokenResolution, "1m" \| "5m" \| "1h" \| "4h" \| "24h">`
|
|
202
|
-
| `TokenFieldOption` |
|
|
249
|
+
| Type | Definition | Description |
|
|
250
|
+
| -------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
251
|
+
| `TokenProtocol` | `SolanaTokenProtocol \| (string & {})` | Open union for token launch protocols. |
|
|
252
|
+
| `ActivityType` | `"buy" \| "sell" \| "liquidity_initialize" \| "liquidity_add" \| ...` | All known on-chain activity types. |
|
|
253
|
+
| `TokenResolution` | `"1s" \| "15s" \| "30s" \| "1m" \| ... \| "24h"` | Candlestick / stats time resolution. |
|
|
254
|
+
| `TrendingResolution` | `Extract<TokenResolution, "1m" \| "5m" \| "1h" \| "4h" \| "24h">` | Subset of resolutions supported by trending lists. |
|
|
255
|
+
| `TokenFieldOption` | Template literal: `${TimeBasedMetric}${Capitalize<Timeframe>}` ∪ standalone fields ∪ `(string & {})` | Sortable / filterable token field identifiers, generated programmatically. |
|
|
203
256
|
|
|
204
257
|
### Constants
|
|
205
258
|
|
|
206
259
|
| Name | Type | Description |
|
|
207
260
|
| ------------------------ | ----------------------- | ----------------------------------------------- |
|
|
208
261
|
| `SOLANA_TOKEN_PROTOCOLS` | `SolanaTokenProtocol[]` | Array of all `SolanaTokenProtocol` enum values. |
|
|
209
|
-
| `version` | `string` | Current package version. |
|
|
210
|
-
|
|
211
|
-
### Namespace
|
|
212
|
-
|
|
213
|
-
| Name | Description |
|
|
214
|
-
| ----- | ------------------------------------------------------------------------------------------------------------ |
|
|
215
|
-
| `API` | Re-exports all types from `./api` as a single namespace for backward-compatible access (e.g. `API.IClient`). |
|
|
216
262
|
|
|
217
263
|
## Usage Examples
|
|
218
264
|
|
|
@@ -286,11 +332,27 @@ function watchToken(client: ISubscribeClient, chain: Chain, address: string) {
|
|
|
286
332
|
}
|
|
287
333
|
```
|
|
288
334
|
|
|
335
|
+
### Group API contract types under a namespace alias
|
|
336
|
+
|
|
337
|
+
```typescript
|
|
338
|
+
import * as API from "@liberfi.io/types/api";
|
|
339
|
+
|
|
340
|
+
function makeMockClient(): API.IClient {
|
|
341
|
+
return {
|
|
342
|
+
/* ... */
|
|
343
|
+
} as API.IClient;
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
function buildSwap(params: API.SwapParams): Promise<API.SwapRoute> {
|
|
347
|
+
/* ... */
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
289
351
|
## Future Improvements
|
|
290
352
|
|
|
291
|
-
-
|
|
292
|
-
|
|
293
|
-
-
|
|
294
|
-
|
|
295
|
-
-
|
|
296
|
-
|
|
353
|
+
- Complete the `TokenSecurity` interface (additional security checks pending
|
|
354
|
+
upstream backend support).
|
|
355
|
+
- Consider auto-generating the `Chain` enum from a canonical chain registry
|
|
356
|
+
to keep the ~190 entries authoritative.
|
|
357
|
+
- Evaluate further splitting `Token` into `TokenCore` + `TokenStats` +
|
|
358
|
+
`TokenMarketData` if downstream consumers commonly need only a subset.
|