@aboutcircles/sdk-rpc 0.1.24 → 0.1.25

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.
Files changed (4) hide show
  1. package/dist/methods/sdk.d.ts +150 -0
  2. package/dist/methods/sdk.d.ts.map +1 -0
  3. package/dist/methods/sdk.js +173 -0
  4. package/package.json +1 -1
package/dist/methods/sdk.d.ts ADDED
@@ -0,0 +1,150 @@
1
+ import type { Address, ProfileView, TrustNetworkSummary, AggregatedTrustRelationsResponse, ValidInvitersResponse, PagedResponse, EnrichedTransaction, ProfileSearchResponse } from '@aboutcircles/sdk-types';
2
+ import type { RpcClient } from '../client';
3
+ /**
4
+ * SDK Enablement RPC methods
5
+ * These methods reduce SDK round-trips by consolidating common multi-call patterns
6
+ */
7
+ export declare class SdkMethods {
8
+ private client;
9
+ constructor(client: RpcClient);
10
+ /**
11
+ * Get a complete profile view combining avatar info, profile data, trust stats, and balances
12
+ *
13
+ * Replaces 6-7 separate RPC calls:
14
+ * - circles_getAvatarInfo
15
+ * - circles_getProfileByAddress
16
+ * - circles_getTrustRelations
17
+ * - circles_getTotalBalance (v1)
18
+ * - circlesV2_getTotalBalance (v2)
19
+ *
20
+ * @param address - Avatar address to query
21
+ * @returns Consolidated profile view with all data
22
+ *
23
+ * @example
24
+ * ```typescript
25
+ * const profileView = await rpc.sdk.getProfileView('0xde374ece6fa50e781e81aac78e811b33d16912c7');
26
+ * console.log(`${profileView.profile?.name} has ${profileView.trustStats.trustsCount} trusts`);
27
+ * console.log(`V2 Balance: ${profileView.v2Balance}`);
28
+ * ```
29
+ */
30
+ getProfileView(address: Address): Promise<ProfileView>;
31
+ /**
32
+ * Get aggregated trust network summary including mutual trusts and network reach
33
+ *
34
+ * Server-side aggregation reduces client-side processing and provides ready-to-display statistics.
35
+ * Network reach = (trusts ∪ trustedBy).count = trustsCount + trustedByCount - mutualTrustsCount
36
+ *
37
+ * @param address - Avatar address to query
38
+ * @param maxDepth - Maximum network depth to analyze (default: 2)
39
+ * @returns Trust network summary with aggregated metrics
40
+ *
41
+ * @example
42
+ * ```typescript
43
+ * const summary = await rpc.sdk.getTrustNetworkSummary('0xde374ece6fa50e781e81aac78e811b33d16912c7');
44
+ * console.log(`Network reach: ${summary.networkReach}`);
45
+ * console.log(`Mutual trusts: ${summary.mutualTrustsCount}`);
46
+ * ```
47
+ */
48
+ getTrustNetworkSummary(address: Address, maxDepth?: number): Promise<TrustNetworkSummary>;
49
+ /**
50
+ * Get trust relations categorized by type (mutual, one-way trusts, one-way trusted-by)
51
+ *
52
+ * Replaces client-side categorization + multiple getAvatarInfo calls.
53
+ * Returns relationships organized for easy UI rendering (different icons/colors per type).
54
+ *
55
+ * @param address - Avatar address to query
56
+ * @returns Trust relations categorized with enriched avatar info
57
+ *
58
+ * @example
59
+ * ```typescript
60
+ * const relations = await rpc.sdk.getAggregatedTrustRelations('0xde374ece6fa50e781e81aac78e811b33d16912c7');
61
+ * console.log(`Mutual trusts: ${relations.mutual.length}`);
62
+ * console.log(`One-way trusts: ${relations.trusts.length}`);
63
+ * console.log(`Trusted by: ${relations.trustedBy.length}`);
64
+ * ```
65
+ */
66
+ getAggregatedTrustRelations(address: Address): Promise<AggregatedTrustRelationsResponse>;
67
+ /**
68
+ * Get list of addresses that trust you AND have sufficient balance to invite
69
+ *
70
+ * Useful for invitation flows and invitation escrow scenarios.
71
+ * Server-side filtering reduces data transfer and client-side processing.
72
+ *
73
+ * @param address - Avatar address to query
74
+ * @param minimumBalance - Optional minimum balance threshold (as TimeCircles string)
75
+ * @returns List of valid inviters with balances and avatar info
76
+ *
77
+ * @example
78
+ * ```typescript
79
+ * // Find all potential inviters
80
+ * const inviters = await rpc.sdk.getValidInviters('0xde374ece6fa50e781e81aac78e811b33d16912c7');
81
+ *
82
+ * // Find inviters with at least 50 CRC balance
83
+ * const richInviters = await rpc.sdk.getValidInviters(
84
+ * '0xde374ece6fa50e781e81aac78e811b33d16912c7',
85
+ * '50.0'
86
+ * );
87
+ * ```
88
+ */
89
+ getValidInviters(address: Address, minimumBalance?: string): Promise<ValidInvitersResponse>;
90
+ /**
91
+ * Get transaction history with enriched participant profiles and metadata
92
+ *
93
+ * Replaces circles_events + multiple getProfileByAddress calls + client-side event processing.
94
+ * Returns transaction history ready for UI display with participant names and avatars.
95
+ *
96
+ * @param address - Avatar address to query
97
+ * @param fromBlock - Starting block number
98
+ * @param toBlock - Optional ending block number (null for latest)
99
+ * @param limit - Maximum number of transactions (default: 50)
100
+ * @returns Enriched transaction history with participant profiles
101
+ *
102
+ * @example
103
+ * ```typescript
104
+ * const history = await rpc.sdk.getTransactionHistoryEnriched(
105
+ * '0xde374ece6fa50e781e81aac78e811b33d16912c7',
106
+ * 30282299,
107
+ * null,
108
+ * 20
109
+ * );
110
+ *
111
+ * for (const tx of history.transactions) {
112
+ * const from = tx.event.values.from;
113
+ * const fromProfile = tx.participants[from]?.profile;
114
+ * console.log(`From: ${fromProfile?.name || from}`);
115
+ * }
116
+ * ```
117
+ */
118
+ getTransactionHistoryEnriched(address: Address, fromBlock?: number, toBlock?: number | null, limit?: number, cursor?: string | null): Promise<PagedResponse<EnrichedTransaction>>;
119
+ /**
120
+ * Unified search across profiles by address prefix OR name/description text
121
+ *
122
+ * Combines address lookup and full-text search in a single endpoint.
123
+ * Automatically detects search type based on query format (0x prefix = address search).
124
+ *
125
+ * @param query - Search query (address prefix or name/description text)
126
+ * @param limit - Maximum number of results (default: 20)
127
+ * @param offset - Pagination offset (default: 0)
128
+ * @param types - Optional array of avatar types to filter by
129
+ * @returns Unified search results with profiles
130
+ *
131
+ * @example
132
+ * ```typescript
133
+ * // Search by name
134
+ * const byName = await rpc.sdk.searchProfileByAddressOrName('Alice');
135
+ *
136
+ * // Search by address prefix
137
+ * const byAddress = await rpc.sdk.searchProfileByAddressOrName('0xde374');
138
+ *
139
+ * // Search with filters
140
+ * const filtered = await rpc.sdk.searchProfileByAddressOrName(
141
+ * 'developer',
142
+ * 10,
143
+ * 0,
144
+ * ['CrcV2_RegisterHuman']
145
+ * );
146
+ * ```
147
+ */
148
+ searchProfileByAddressOrName(query: string, limit?: number, offset?: number, types?: string[]): Promise<ProfileSearchResponse>;
149
+ }
150
+ //# sourceMappingURL=sdk.d.ts.map
package/dist/methods/sdk.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/methods/sdk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,gCAAgC,EAChC,qBAAqB,EACrB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C;;;GAGG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAQ5D;;;;;;;;;;;;;;;;OAgBG;IACG,sBAAsB,CAC1B,OAAO,EAAE,OAAO,EAChB,QAAQ,GAAE,MAAU,GACnB,OAAO,CAAC,mBAAmB,CAAC;IAQ/B;;;;;;;;;;;;;;;;OAgBG;IACG,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,CAAC;IAQ9F;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,gBAAgB,CACpB,OAAO,EAAE,OAAO,EAChB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,qBAAqB,CAAC;IAUjC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,6BAA6B,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,GAAE,MAAU,EACrB,OAAO,GAAE,MAAM,GAAG,IAAW,EAC7B,KAAK,GAAE,MAAW,EAClB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAc9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,4BAA4B,CAChC,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,EAClB,KAAK,CAAC,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,qBAAqB,CAAC;CAMlC"}
package/dist/methods/sdk.js ADDED
@@ -0,0 +1,173 @@
1
+ import { normalizeAddress, checksumAddresses } from '../utils';
2
+ /**
3
+ * SDK Enablement RPC methods
4
+ * These methods reduce SDK round-trips by consolidating common multi-call patterns
5
+ */
6
+ export class SdkMethods {
7
+ client;
8
+ constructor(client) {
9
+ this.client = client;
10
+ }
11
+ /**
12
+ * Get a complete profile view combining avatar info, profile data, trust stats, and balances
13
+ *
14
+ * Replaces 6-7 separate RPC calls:
15
+ * - circles_getAvatarInfo
16
+ * - circles_getProfileByAddress
17
+ * - circles_getTrustRelations
18
+ * - circles_getTotalBalance (v1)
19
+ * - circlesV2_getTotalBalance (v2)
20
+ *
21
+ * @param address - Avatar address to query
22
+ * @returns Consolidated profile view with all data
23
+ *
24
+ * @example
25
+ * ```typescript
26
+ * const profileView = await rpc.sdk.getProfileView('0xde374ece6fa50e781e81aac78e811b33d16912c7');
27
+ * console.log(`${profileView.profile?.name} has ${profileView.trustStats.trustsCount} trusts`);
28
+ * console.log(`V2 Balance: ${profileView.v2Balance}`);
29
+ * ```
30
+ */
31
+ async getProfileView(address) {
32
+ const normalizedAddress = normalizeAddress(address);
33
+ return this.client.call('circles_getProfileView', [normalizedAddress]);
34
+ }
35
+ /**
36
+ * Get aggregated trust network summary including mutual trusts and network reach
37
+ *
38
+ * Server-side aggregation reduces client-side processing and provides ready-to-display statistics.
39
+ * Network reach = (trusts ∪ trustedBy).count = trustsCount + trustedByCount - mutualTrustsCount
40
+ *
41
+ * @param address - Avatar address to query
42
+ * @param maxDepth - Maximum network depth to analyze (default: 2)
43
+ * @returns Trust network summary with aggregated metrics
44
+ *
45
+ * @example
46
+ * ```typescript
47
+ * const summary = await rpc.sdk.getTrustNetworkSummary('0xde374ece6fa50e781e81aac78e811b33d16912c7');
48
+ * console.log(`Network reach: ${summary.networkReach}`);
49
+ * console.log(`Mutual trusts: ${summary.mutualTrustsCount}`);
50
+ * ```
51
+ */
52
+ async getTrustNetworkSummary(address, maxDepth = 2) {
53
+ const normalizedAddress = normalizeAddress(address);
54
+ return this.client.call('circles_getTrustNetworkSummary', [normalizedAddress, maxDepth]);
55
+ }
56
+ /**
57
+ * Get trust relations categorized by type (mutual, one-way trusts, one-way trusted-by)
58
+ *
59
+ * Replaces client-side categorization + multiple getAvatarInfo calls.
60
+ * Returns relationships organized for easy UI rendering (different icons/colors per type).
61
+ *
62
+ * @param address - Avatar address to query
63
+ * @returns Trust relations categorized with enriched avatar info
64
+ *
65
+ * @example
66
+ * ```typescript
67
+ * const relations = await rpc.sdk.getAggregatedTrustRelations('0xde374ece6fa50e781e81aac78e811b33d16912c7');
68
+ * console.log(`Mutual trusts: ${relations.mutual.length}`);
69
+ * console.log(`One-way trusts: ${relations.trusts.length}`);
70
+ * console.log(`Trusted by: ${relations.trustedBy.length}`);
71
+ * ```
72
+ */
73
+ async getAggregatedTrustRelations(address) {
74
+ const normalizedAddress = normalizeAddress(address);
75
+ return this.client.call('circles_getAggregatedTrustRelations', [normalizedAddress]);
76
+ }
77
+ /**
78
+ * Get list of addresses that trust you AND have sufficient balance to invite
79
+ *
80
+ * Useful for invitation flows and invitation escrow scenarios.
81
+ * Server-side filtering reduces data transfer and client-side processing.
82
+ *
83
+ * @param address - Avatar address to query
84
+ * @param minimumBalance - Optional minimum balance threshold (as TimeCircles string)
85
+ * @returns List of valid inviters with balances and avatar info
86
+ *
87
+ * @example
88
+ * ```typescript
89
+ * // Find all potential inviters
90
+ * const inviters = await rpc.sdk.getValidInviters('0xde374ece6fa50e781e81aac78e811b33d16912c7');
91
+ *
92
+ * // Find inviters with at least 50 CRC balance
93
+ * const richInviters = await rpc.sdk.getValidInviters(
94
+ * '0xde374ece6fa50e781e81aac78e811b33d16912c7',
95
+ * '50.0'
96
+ * );
97
+ * ```
98
+ */
99
+ async getValidInviters(address, minimumBalance) {
100
+ const normalizedAddress = normalizeAddress(address);
101
+ const response = await this.client.call('circles_getValidInviters', minimumBalance ? [normalizedAddress, minimumBalance] : [normalizedAddress]);
102
+ return checksumAddresses(response);
103
+ }
104
+ /**
105
+ * Get transaction history with enriched participant profiles and metadata
106
+ *
107
+ * Replaces circles_events + multiple getProfileByAddress calls + client-side event processing.
108
+ * Returns transaction history ready for UI display with participant names and avatars.
109
+ *
110
+ * @param address - Avatar address to query
111
+ * @param fromBlock - Starting block number
112
+ * @param toBlock - Optional ending block number (null for latest)
113
+ * @param limit - Maximum number of transactions (default: 50)
114
+ * @returns Enriched transaction history with participant profiles
115
+ *
116
+ * @example
117
+ * ```typescript
118
+ * const history = await rpc.sdk.getTransactionHistoryEnriched(
119
+ * '0xde374ece6fa50e781e81aac78e811b33d16912c7',
120
+ * 30282299,
121
+ * null,
122
+ * 20
123
+ * );
124
+ *
125
+ * for (const tx of history.transactions) {
126
+ * const from = tx.event.values.from;
127
+ * const fromProfile = tx.participants[from]?.profile;
128
+ * console.log(`From: ${fromProfile?.name || from}`);
129
+ * }
130
+ * ```
131
+ */
132
+ async getTransactionHistoryEnriched(address, fromBlock = 0, toBlock = null, limit = 50, cursor) {
133
+ const normalizedAddress = normalizeAddress(address);
134
+ const response = await this.client.call('circles_getTransactionHistoryEnriched', [normalizedAddress, fromBlock, toBlock, limit, cursor ?? null]);
135
+ return {
136
+ hasMore: response.hasMore,
137
+ nextCursor: response.nextCursor,
138
+ results: checksumAddresses(response.results),
139
+ };
140
+ }
141
+ /**
142
+ * Unified search across profiles by address prefix OR name/description text
143
+ *
144
+ * Combines address lookup and full-text search in a single endpoint.
145
+ * Automatically detects search type based on query format (0x prefix = address search).
146
+ *
147
+ * @param query - Search query (address prefix or name/description text)
148
+ * @param limit - Maximum number of results (default: 20)
149
+ * @param offset - Pagination offset (default: 0)
150
+ * @param types - Optional array of avatar types to filter by
151
+ * @returns Unified search results with profiles
152
+ *
153
+ * @example
154
+ * ```typescript
155
+ * // Search by name
156
+ * const byName = await rpc.sdk.searchProfileByAddressOrName('Alice');
157
+ *
158
+ * // Search by address prefix
159
+ * const byAddress = await rpc.sdk.searchProfileByAddressOrName('0xde374');
160
+ *
161
+ * // Search with filters
162
+ * const filtered = await rpc.sdk.searchProfileByAddressOrName(
163
+ * 'developer',
164
+ * 10,
165
+ * 0,
166
+ * ['CrcV2_RegisterHuman']
167
+ * );
168
+ * ```
169
+ */
170
+ async searchProfileByAddressOrName(query, limit = 20, offset = 0, types) {
171
+ return this.client.call('circles_searchProfileByAddressOrName', types ? [query, limit, offset, types] : [query, limit, offset]);
172
+ }
173
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aboutcircles/sdk-rpc",
3
- "version": "0.1.24",
3
+ "version": "0.1.25",
4
4
  "description": "Circles RPC wrapper",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",