@aboutcircles/sdk-rpc 0.1.27 → 0.1.29

package/dist/methods/group.js

@@ -11,8 +11,8 @@ export class GroupMethods {
     /**
      * Find groups with optional filters
      *
-     * This is a convenience method that fetches all pages using cursor-based pagination
-     * and returns the combined results up to the specified limit.
+     * Uses the native RPC method for efficient server-side filtering and pagination.
+     * Fetches all results using cursor-based pagination up to the specified limit.
      *
      * @param limit - Maximum number of groups to return (default: 50)
      * @param params - Optional query parameters to filter groups
@@ -39,187 +39,78 @@ export class GroupMethods {
      * });
      * ```
      */
-    async findGroups(limit = 50, params) {
-        // Create the paged query
-        const query = this.getGroups(limit, params, 'DESC');
-        const results = [];
-        // Fetch all pages up to the limit
-        while (await query.queryNextPage()) {
-            results.push(...query.currentPage.results);
-            // If we have enough results, break
-            if (results.length >= limit) {
-                break;
+    async findGroups(limit = 50, params, cursor) {
+        const normalizedParams = params
+            ? {
+                nameStartsWith: params.nameStartsWith,
+                symbolStartsWith: params.symbolStartsWith,
+                ownerIn: params.ownerIn?.map((owner) => normalizeAddress(owner)),
             }
-            // If no more pages, break
-            if (!query.currentPage.hasMore) {
-                break;
+            : undefined;
+        const response = await this.client.call('circles_findGroups', [limit, normalizedParams ?? null, cursor ?? null]);
+        const rows = checksumAddresses(response.results).map((row) => {
+            const enriched = row;
+            if (!enriched.owner && enriched.mint) {
+                return { ...enriched, owner: enriched.mint };
             }
-        }
-        // Apply limit
-        return results.slice(0, limit);
+            return enriched;
+        });
+        return {
+            hasMore: response.hasMore,
+            nextCursor: response.nextCursor,
+            results: rows,
+        };
     }
     /**
-     * Get group memberships for an avatar using cursor-based pagination
+     * Get group memberships for an avatar
+     *
+     * Uses the native RPC method for efficient server-side queries.
+     * Fetches all results using cursor-based pagination up to the specified limit.
      *
      * @param avatar - Avatar address to query group memberships for
-     * @param limit - Number of memberships per page (default: 50)
-     * @param sortOrder - Sort order for results (default: 'DESC')
-     * @returns PagedQuery instance for iterating through memberships
+     * @param limit - Maximum number of memberships to return (default: 50)
+     * @returns Array of group membership rows
      *
      * @example
      * ```typescript
-     * const query = rpc.group.getGroupMemberships(
+     * const memberships = await rpc.group.getGroupMemberships(
      *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
      *   50
      * );
-     * await query.queryNextPage();
-     * console.log(query.currentPage.results);
+     * console.log(memberships);
      * ```
      */
-    getGroupMemberships(avatar, limit = 50, sortOrder = 'DESC') {
-        const normalized = normalizeAddress(avatar);
-        return new PagedQuery(this.client, {
-            namespace: 'V_CrcV2',
-            table: 'GroupMemberships',
-            sortOrder,
-            columns: [
-                'blockNumber',
-                'timestamp',
-                'transactionIndex',
-                'logIndex',
-                'transactionHash',
-                'group',
-                'member',
-                'expiryTime',
-            ],
-            filter: [
-                {
-                    Type: 'FilterPredicate',
-                    FilterType: 'Equals',
-                    Column: 'member',
-                    Value: normalized,
-                },
-            ],
-            limit,
-        }, (row) => checksumAddresses(row));
+    async getGroupMemberships(avatar, limit = 50, cursor) {
+        const response = await this.client.call('circles_getGroupMemberships', [normalizeAddress(avatar), limit, cursor ?? null]);
+        return {
+            hasMore: response.hasMore,
+            nextCursor: response.nextCursor,
+            results: checksumAddresses(response.results),
+        };
     }
     /**
-     * Get holders of a group token using cursor-based pagination
+     * Get members of a group
      *
-     * Returns a PagedQuery instance that can be used to fetch holders page by page.
-     * Results are ordered by totalBalance DESC (highest first), with holder address as tie-breaker.
+     * Uses the native RPC method for efficient server-side queries.
+     * Fetches all results using cursor-based pagination up to the specified limit.
      *
-     * Note: Pagination uses holder address as cursor because totalBalance (BigInt) values
-     * cannot be reliably passed through JSON-RPC filters. This means pagination boundaries
-     * are based on holder addresses, not balances.
-     *
-     * @param groupAddress - The address of the group token
-     * @param limit - Number of holders per page (default: 100)
-     * @returns PagedQuery instance for iterating through group token holders
+     * @param groupAddress - Group address to query members for
+     * @param limit - Maximum number of members to return (default: 100)
+     * @returns Array of group membership rows (members of the group)
      *
      * @example
      * ```typescript
-     * const query = rpc.group.getGroupHolders('0xGroupAddress...', 50);
-     *
-     * // Get first page (ordered by totalBalance DESC)
-     * await query.queryNextPage();
-     * console.log(query.currentPage.results[0]); // Holder with highest balance
-     *
-     * // Get next page if available
-     * if (query.currentPage.hasMore) {
-     *   await query.queryNextPage();
-     * }
+     * const members = await rpc.group.getGroupMembers('0xGroupAddress...', 100);
+     * console.log(`Group has ${members.length} members`);
      * ```
      */
-    getGroupHolders(groupAddress, limit = 100) {
-        const normalized = normalizeAddress(groupAddress);
-        return new PagedQuery(this.client, {
-            namespace: 'V_CrcV2',
-            table: 'GroupTokenHoldersBalance',
-            sortOrder: 'DESC',
-            columns: ['group', 'holder', 'totalBalance', 'demurragedTotalBalance', 'fractionOwnership'],
-            cursorColumns: [
-                {
-                    name: 'holder',
-                    sortOrder: 'ASC', // Use holder for cursor-based pagination
-                },
-            ],
-            orderColumns: [
-                { Column: 'totalBalance', SortOrder: 'DESC' },
-                { Column: 'holder', SortOrder: 'ASC' },
-            ],
-            filter: [
-                {
-                    Type: 'FilterPredicate',
-                    FilterType: 'Equals',
-                    Column: 'group',
-                    Value: normalized,
-                },
-            ],
-            limit,
-            rowTransformer: (row) => {
-                // Convert string values to bigint for specific fields
-                const transformed = {
-                    ...row,
-                    totalBalance: BigInt(row.totalBalance),
-                    demurragedTotalBalance: BigInt(row.demurragedTotalBalance),
-                };
-                return checksumAddresses(transformed);
-            },
-        });
-    }
-    /**
-     * Get members of a group using cursor-based pagination
-     *
-     * Returns a PagedQuery instance that can be used to fetch members page by page
-     * using cursor-based pagination.
-     *
-     * @param groupAddress - The address of the group to query members for
-     * @param limit - Number of members per page (default: 100)
-     * @param sortOrder - Sort order for results (default: 'DESC')
-     * @returns PagedQuery instance for iterating through group members
-     *
-     * @example
-     * ```typescript
-     * const query = rpc.group.getGroupMembers('0xGroupAddress...', 100);
-     *
-     * // Get first page
-     * await query.queryNextPage();
-     * console.log(query.currentPage.results);
-     *
-     * // Get next page if available
-     * if (query.currentPage.hasMore) {
-     *   await query.queryNextPage();
-     *   console.log(query.currentPage.results);
-     * }
-     * ```
-     */
-    getGroupMembers(groupAddress, limit = 100, sortOrder = 'DESC') {
-        const normalized = normalizeAddress(groupAddress);
-        return new PagedQuery(this.client, {
-            namespace: 'V_CrcV2',
-            table: 'GroupMemberships',
-            sortOrder,
-            columns: [
-                'blockNumber',
-                'timestamp',
-                'transactionIndex',
-                'logIndex',
-                'transactionHash',
-                'group',
-                'member',
-                'expiryTime',
-            ],
-            filter: [
-                {
-                    Type: 'FilterPredicate',
-                    FilterType: 'Equals',
-                    Column: 'group',
-                    Value: normalized,
-                },
-            ],
-            limit,
-        }, (row) => checksumAddresses(row));
+    async getGroupMembers(groupAddress, limit = 100, cursor) {
+        const response = await this.client.call('circles_getGroupMembers', [normalizeAddress(groupAddress), limit, cursor ?? null]);
+        return {
+            hasMore: response.hasMore,
+            nextCursor: response.nextCursor,
+            results: checksumAddresses(response.results),
+        };
     }
     /**
      * Get groups using cursor-based pagination
@@ -377,4 +268,39 @@ export class GroupMethods {
             limit,
         }, (row) => checksumAddresses(row));
     }
+    /**
+     * Get holders of a group token
+     *
+     * @param groupAddress - Group address (which is also the token address)
+     * @param limit - Maximum number of holders to return (default: 100)
+     * @returns PagedQuery instance for iterating through holders
+     */
+    getGroupHolders(groupAddress, limit = 100) {
+        const normalized = normalizeAddress(groupAddress);
+        return new PagedQuery(this.client, {
+            namespace: 'V_Crc',
+            table: 'TokenBalances',
+            sortOrder: 'DESC',
+            columns: [
+                'blockNumber',
+                'timestamp',
+                'transactionIndex',
+                'logIndex',
+                'transactionHash',
+                'token',
+                'account',
+                'balance',
+                'lastChangedAt'
+            ],
+            filter: [
+                {
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'token',
+                    Value: normalized,
+                }
+            ],
+            limit,
+        }, (row) => checksumAddresses(row));
+    }
 }

package/dist/methods/index.d.ts

@@ -8,4 +8,5 @@ export { TokenMethods } from './token.js';
 export { InvitationMethods } from './invitation.js';
 export { TransactionMethods } from './transaction.js';
 export { GroupMethods } from './group.js';
+export { SdkMethods } from './sdk.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/methods/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/methods/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/methods/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/methods/index.js

@@ -8,3 +8,4 @@ export { TokenMethods } from './token.js';
 export { InvitationMethods } from './invitation.js';
 export { TransactionMethods } from './transaction.js';
 export { GroupMethods } from './group.js';
+export { SdkMethods } from './sdk.js';

package/dist/methods/invitation.d.ts

@@ -1,15 +1,33 @@
 import type { RpcClient } from '../client.js';
-import type { Address, AvatarInfo } from '@aboutcircles/sdk-types';
+import type { Address, AvatarInfo, ValidInvitersResponse, TrustInvitation, EscrowInvitation, AtScaleInvitation, InvitationOriginResponse, InvitationsFromResponse, AllInvitationsResponse } from '@aboutcircles/sdk-types';
 /**
  * Invitation RPC methods
+ *
+ * All methods delegate to dedicated RPC endpoints for server-side SQL optimization.
  */
 export declare class InvitationMethods {
     private client;
     constructor(client: RpcClient);
-    private transformQueryResponse;
+    /**
+     * Get the invitation origin for an address — how they were invited to Circles
+     *
+     * @param address - The address of the invited avatar
+     * @returns Full invitation origin details or null if not registered
+     *
+     * @example
+     * ```typescript
+     * const origin = await rpc.invitation.getInvitationOrigin('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(origin?.invitationType); // 'v2_standard', 'v2_escrow', 'v2_at_scale', 'v1_signup'
+     * console.log(origin?.inviter); // '0x...' or null
+     * ```
+     */
+    getInvitationOrigin(address: Address): Promise<InvitationOriginResponse | null>;
     /**
      * Get the avatar that invited a specific avatar
      *
+     * Uses `circles_getInvitationOrigin` for a single optimized query that checks
+     * all invitation mechanisms (at-scale, escrow, v2 standard, v1 signup).
+     *
      * @param address - The address of the invited avatar
      * @returns The address of the inviting avatar or undefined if not found
      *
@@ -20,10 +38,22 @@ export declare class InvitationMethods {
      * ```
      */
     getInvitedBy(address: Address): Promise<Address | undefined>;
+    /**
+     * Get trust-based invitations (addresses that trust you with sufficient balance)
+     *
+     * Uses dedicated `circles_getTrustInvitations` endpoint.
+     *
+     * @param address - The address to check for trust invitations
+     * @param minimumBalance - Optional minimum balance threshold (as CRC string)
+     * @returns Array of trust invitations
+     */
+    getTrustInvitations(address: Address, minimumBalance?: string): Promise<TrustInvitation[]>;
     /**
      * Get the list of avatars who have invited this avatar
      * Checks v2 trust relations and validates that inviters have enough balance
      *
+     * Uses the native RPC method for efficient server-side filtering and validation.
+     *
      * @param address - The address to check for invitations
      * @returns Array of avatar info for valid inviters
      *
@@ -33,13 +63,23 @@ export declare class InvitationMethods {
      * console.log(invitations); // Array of AvatarInfo
      * ```
      */
-    getInvitations(address: Address): Promise<AvatarInfo[]>;
+    getInvitations(address: Address, minimumBalance?: string): Promise<AvatarInfo[]>;
+    /**
+     * Fetch valid inviters along with balances and avatar info
+     *
+     * @param address - Address to find inviters for
+     * @param minimumBalance - Optional minimum balance to filter inviters
+     * @returns Valid inviters response as provided by the RPC host
+     */
+    getValidInviters(address: Address, minimumBalance?: string): Promise<ValidInvitersResponse>;
     /**
      * Get the list of accounts that were invited by a specific avatar
      *
+     * Uses dedicated `circles_getInvitationsFrom` endpoint with server-side SQL.
+     *
      * @param address - The address of the inviter
      * @param accepted - If true, returns accepted invitations; if false, returns pending invitations
-     * @returns Array of invited addresses
+     * @returns Enriched response with invited account info and avatar data
      *
      * @example
      * ```typescript
@@ -48,14 +88,68 @@ export declare class InvitationMethods {
      *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
      *   true
      * );
+     * console.log(accepted.results); // [{address, status: 'accepted', avatarInfo, ...}]
      *
      * // Get pending invitations
      * const pending = await rpc.invitation.getInvitationsFrom(
      *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
      *   false
      * );
+     * console.log(pending.results); // [{address, status: 'pending'}]
+     * ```
+     */
+    getInvitationsFrom(address: Address, accepted?: boolean): Promise<InvitationsFromResponse>;
+    /**
+     * Get escrow-based invitations for an address
+     *
+     * Uses dedicated `circles_getEscrowInvitations` endpoint which handles all filtering
+     * server-side (redeemed, revoked, refunded) in a single optimized SQL query.
+     *
+     * @param address - The address to check for escrow invitations
+     * @returns Array of active escrow invitations
+     *
+     * @example
+     * ```typescript
+     * const escrowInvites = await rpc.invitation.getEscrowInvitations('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(escrowInvites); // Array of EscrowInvitation
+     * ```
+     */
+    getEscrowInvitations(address: Address): Promise<EscrowInvitation[]>;
+    /**
+     * Get at-scale invitations for an address
+     *
+     * Uses dedicated `circles_getAtScaleInvitations` endpoint which checks for
+     * unclaimed pre-created accounts in a single optimized SQL query.
+     *
+     * @param address - The address to check for at-scale invitations
+     * @returns Array of at-scale invitations (unclaimed pre-created accounts)
+     *
+     * @example
+     * ```typescript
+     * const atScaleInvites = await rpc.invitation.getAtScaleInvitations('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(atScaleInvites); // Array of AtScaleInvitation
+     * ```
+     */
+    getAtScaleInvitations(address: Address): Promise<AtScaleInvitation[]>;
+    /**
+     * Get all invitations from all sources (trust, escrow, at-scale)
+     * This is the recommended method to use for getting a complete view of available invitations
+     *
+     * Uses the optimized `circles_getAllInvitations` RPC method which fetches all invitation
+     * types in a single round-trip with server-side SQL JOINs for efficiency.
+     *
+     * @param address - The address to check for invitations
+     * @param minimumBalance - Optional minimum balance for trust-based invitations
+     * @returns All invitations from all sources
+     *
+     * @example
+     * ```typescript
+     * const allInvites = await rpc.invitation.getAllInvitations('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(`Trust invites: ${allInvites.trustInvitations.length}`);
+     * console.log(`Escrow invites: ${allInvites.escrowInvitations.length}`);
+     * console.log(`At-scale invites: ${allInvites.atScaleInvitations.length}`);
      * ```
      */
-    getInvitationsFrom(address: Address, accepted?: boolean): Promise<Address[]>;
+    getAllInvitations(address: Address, minimumBalance?: string): Promise<AllInvitationsResponse>;
 }
 //# sourceMappingURL=invitation.d.ts.map

package/dist/methods/invitation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invitation.d.ts","sourceRoot":"","sources":["../../src/methods/invitation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAsC,MAAM,yBAAyB,CAAC;AAOvG;;GAEG;AACH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC,OAAO,CAAC,sBAAsB;IAW9B;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAgClE;;;;;;;;;;;;OAYG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqF7D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAoF1F"}
+{"version":3,"file":"invitation.d.ts","sourceRoot":"","sources":["../../src/methods/invitation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAGjC;;;;GAIG;AACH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;;OAYG;IACG,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC;IASrF;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAQlE;;;;;;;;OAQG;IACG,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAShG;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAUtF;;;;;;OAMG;IACG,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAUjG;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC,uBAAuB,CAAC;IASvG;;;;;;;;;;;;;;OAcG;IACG,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IASzE;;;;;;;;;;;;;;OAcG;IACG,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAS3E;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;CAWpG"}