@aboutcircles/sdk-invitations 0.1.9 → 0.1.11

package/dist/InviteFarm.d.ts

@@ -0,0 +1,59 @@
+import type { Address, CirclesConfig, TransactionRequest, Hex } from '@aboutcircles/sdk-types';
+import type { ReferralPreviewList } from './types';
+export interface GeneratedInvite {
+    secret: Hex;
+    signer: Address;
+}
+export interface GenerateInvitesResult {
+    invites: GeneratedInvite[];
+    transactions: TransactionRequest[];
+}
+/**
+ * InviteFarm handles batch invitation generation via the InvitationFarm contract
+ *
+ * This class provides methods to generate multiple invitations at once using
+ * the InvitationFarm contract, which manages a farm of InvitationBot instances.
+ */
+export declare class InviteFarm {
+    private config;
+    private invitations;
+    private invitationFarm;
+    private referralsModule;
+    private hubV2;
+    constructor(config: CirclesConfig);
+    /**
+     * Get the remaining invite quota for a specific inviter
+     */
+    getQuota(inviter: Address): Promise<bigint>;
+    /**
+     * Get the invitation fee (96 CRC)
+     */
+    getInvitationFee(): Promise<bigint>;
+    /**
+     * Get the invitation module address from the farm
+     */
+    getInvitationModule(): Promise<Address>;
+    /**
+     * Generate batch invitations using the InvitationFarm
+     *
+     * This method:
+     * 1. Simulates claimInvites to get token IDs that will be claimed
+     * 2. Generates random secrets and derives signer addresses
+     * 3. Builds transaction batch: claimInvites + safeBatchTransferFrom
+     *
+     * @param inviter - Address of the inviter (must have quota)
+     * @param count - Number of invitations to generate
+     * @returns Generated invites with secrets/signers and transactions to execute
+     */
+    generateInvites(inviter: Address, count: number): Promise<GenerateInvitesResult>;
+    /**
+     * List referrals for a given inviter with key previews
+     *
+     * @param inviter - Address of the inviter
+     * @param limit - Maximum number of referrals to return (default 10)
+     * @param offset - Number of referrals to skip for pagination (default 0)
+     * @returns Paginated list of referral previews with masked keys
+     */
+    listReferrals(inviter: Address, limit?: number, offset?: number): Promise<ReferralPreviewList>;
+}
+//# sourceMappingURL=InviteFarm.d.ts.map

package/dist/InviteFarm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InviteFarm.d.ts","sourceRoot":"","sources":["../src/InviteFarm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAO/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AASnD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,KAAK,CAAuB;gBAExB,MAAM,EAAE,aAAa;IAiBjC;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjD;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAIzC;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7C;;;;;;;;;;;OAWG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA0EtF;;;;;;;OAOG;IACG,aAAa,CACjB,OAAO,EAAE,OAAO,EAChB,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,GACjB,OAAO,CAAC,mBAAmB,CAAC;CAGhC"}

package/dist/InviteFarm.js

@@ -0,0 +1,123 @@
+import { InvitationFarmContractMinimal, ReferralsModuleContractMinimal, HubV2ContractMinimal } from '@aboutcircles/sdk-core/minimal';
+import { InvitationError } from './errors';
+import { Invitations } from './Invitations';
+import { generatePrivateKey, privateKeyToAddress, encodeAbiParameters, INVITATION_FEE } from '@aboutcircles/sdk-utils';
+/**
+ * InviteFarm handles batch invitation generation via the InvitationFarm contract
+ *
+ * This class provides methods to generate multiple invitations at once using
+ * the InvitationFarm contract, which manages a farm of InvitationBot instances.
+ */
+export class InviteFarm {
+    config;
+    invitations;
+    invitationFarm;
+    referralsModule;
+    hubV2;
+    constructor(config) {
+        this.config = config;
+        this.invitations = new Invitations(config);
+        this.invitationFarm = new InvitationFarmContractMinimal({
+            address: config.invitationFarmAddress,
+            rpcUrl: config.circlesRpcUrl,
+        });
+        this.referralsModule = new ReferralsModuleContractMinimal({
+            address: config.referralsModuleAddress,
+            rpcUrl: config.circlesRpcUrl,
+        });
+        this.hubV2 = new HubV2ContractMinimal({
+            address: config.v2HubAddress,
+            rpcUrl: config.circlesRpcUrl,
+        });
+    }
+    /**
+     * Get the remaining invite quota for a specific inviter
+     */
+    async getQuota(inviter) {
+        return this.invitationFarm.inviterQuota(inviter);
+    }
+    /**
+     * Get the invitation fee (96 CRC)
+     */
+    async getInvitationFee() {
+        return this.invitationFarm.invitationFee();
+    }
+    /**
+     * Get the invitation module address from the farm
+     */
+    async getInvitationModule() {
+        return this.invitationFarm.invitationModule();
+    }
+    /**
+     * Generate batch invitations using the InvitationFarm
+     *
+     * This method:
+     * 1. Simulates claimInvites to get token IDs that will be claimed
+     * 2. Generates random secrets and derives signer addresses
+     * 3. Builds transaction batch: claimInvites + safeBatchTransferFrom
+     *
+     * @param inviter - Address of the inviter (must have quota)
+     * @param count - Number of invitations to generate
+     * @returns Generated invites with secrets/signers and transactions to execute
+     */
+    async generateInvites(inviter, count) {
+        if (count <= 0) {
+            throw new InvitationError('Count must be greater than 0', {
+                code: 'INVITATION_INVALID_COUNT',
+                source: 'VALIDATION',
+                context: { count },
+            });
+        }
+        const inviterLower = inviter.toLowerCase();
+        const numberOfInvites = BigInt(count);
+        // Step 1: Simulate claimInvites to get token IDs
+        const ids = await this.invitationFarm.read('claimInvites', [numberOfInvites], {
+            from: inviterLower
+        });
+        if (!ids || ids.length === 0) {
+            throw new InvitationError('No invitation IDs returned from claimInvites', {
+                code: 'INVITATION_NO_IDS',
+                source: 'INVITATIONS',
+                context: { inviter: inviterLower, count },
+            });
+        }
+        // Step 2: Generate secrets and signers
+        const invites = [];
+        const signers = [];
+        for (let i = 0; i < count; i++) {
+            const secret = generatePrivateKey();
+            const signer = privateKeyToAddress(secret).toLowerCase();
+            invites.push({ secret, signer });
+            signers.push(signer);
+        }
+        // Step 3: Get addresses
+        const invitationModuleAddress = await this.invitationFarm.invitationModule();
+        // Step 4: Build transactions
+        const claimTx = this.invitationFarm.claimInvites(numberOfInvites);
+        // Encode createAccounts call
+        const createAccountsTx = this.referralsModule.createAccounts(signers);
+        const createAccountsData = createAccountsTx.data;
+        // Encode data for safeBatchTransferFrom
+        const encodedData = encodeAbiParameters(['address', 'bytes'], [this.config.referralsModuleAddress, createAccountsData]);
+        // Build amounts array (96 CRC per invite)
+        const amounts = ids.map(() => INVITATION_FEE);
+        const batchTransferTx = this.hubV2.safeBatchTransferFrom(inviterLower, invitationModuleAddress, ids, amounts, encodedData);
+        // Save all referrals to database
+        await Promise.all(invites.map((inv) => this.invitations.saveReferralData(inviterLower, inv.secret)));
+        return {
+            invites,
+            transactions: [claimTx, batchTransferTx],
+        };
+    }
+    /**
+     * List referrals for a given inviter with key previews
+     *
+     * @param inviter - Address of the inviter
+     * @param limit - Maximum number of referrals to return (default 10)
+     * @param offset - Number of referrals to skip for pagination (default 0)
+     * @returns Paginated list of referral previews with masked keys
+     */
+    async listReferrals(inviter, limit = 10, offset = 0) {
+        return this.invitations.listReferrals(inviter, limit, offset);
+    }
+}

package/dist/Referrals.d.ts

@@ -0,0 +1,44 @@
+import type { ReferralInfo, ReferralList } from "./types";
+/**
+ * Referrals service client for retrieving referral information
+ *
+ * The referrals backend enables Circles SDK users to query referral data:
+ * - Retrieve: Get referral info by private key (public)
+ * - List: Get all referrals created by authenticated user
+ *
+ * Note: Storing referrals is handled by Invitations.generateReferral()
+ */
+export declare class Referrals {
+    private readonly baseUrl;
+    private readonly getToken?;
+    /**
+     * Create a new Referrals client
+     *
+     * @param baseUrl - The referrals service base URL (e.g., "https://referrals.circles.example")
+     * @param getToken - Optional function to get auth token for authenticated endpoints
+     */
+    constructor(baseUrl: string, getToken?: (() => Promise<string>) | undefined);
+    private getBaseUrl;
+    private getAuthHeaders;
+    /**
+     * Retrieve referral info by private key
+     *
+     * This is a public endpoint - no authentication required.
+     * Used by invitees to look up who invited them.
+     *
+     * @param privateKey - The referral private key
+     * @returns Referral info including inviter and status
+     * @throws InvitationError if referral not found or expired
+     */
+    retrieve(privateKey: string): Promise<ReferralInfo>;
+    /**
+     * List all referrals created by the authenticated user
+     *
+     * Requires authentication - the user's address is extracted from the JWT token.
+     *
+     * @returns List of referrals with their status and metadata
+     * @throws InvitationError if not authenticated or request fails
+     */
+    listMine(): Promise<ReferralList>;
+}
+//# sourceMappingURL=Referrals.d.ts.map

package/dist/Referrals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Referrals.d.ts","sourceRoot":"","sources":["../src/Referrals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAY,MAAM,SAAS,CAAC;AAGpE;;;;;;;;GAQG;AACH,qBAAa,SAAS;IAQlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAR5B;;;;;OAKG;gBAEgB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,GAAE,MAAM,OAAO,CAAC,MAAM,CAAC,aAAA;IAGnD,OAAO,CAAC,UAAU;YAMJ,cAAc;IAY5B;;;;;;;;;OASG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAmCzD;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC;CAyCxC"}

package/dist/Referrals.js

@@ -0,0 +1,129 @@
+import { InvitationError } from "./errors";
+/**
+ * Referrals service client for retrieving referral information
+ *
+ * The referrals backend enables Circles SDK users to query referral data:
+ * - Retrieve: Get referral info by private key (public)
+ * - List: Get all referrals created by authenticated user
+ *
+ * Note: Storing referrals is handled by Invitations.generateReferral()
+ */
+export class Referrals {
+    baseUrl;
+    getToken;
+    /**
+     * Create a new Referrals client
+     *
+     * @param baseUrl - The referrals service base URL (e.g., "https://referrals.circles.example")
+     * @param getToken - Optional function to get auth token for authenticated endpoints
+     */
+    constructor(baseUrl, getToken) {
+        this.baseUrl = baseUrl;
+        this.getToken = getToken;
+    }
+    getBaseUrl() {
+        return this.baseUrl.endsWith("/")
+            ? this.baseUrl.slice(0, -1)
+            : this.baseUrl;
+    }
+    async getAuthHeaders() {
+        if (!this.getToken) {
+            return { "Content-Type": "application/json" };
+        }
+        const token = await this.getToken();
+        return {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+        };
+    }
+    /**
+     * Retrieve referral info by private key
+     *
+     * This is a public endpoint - no authentication required.
+     * Used by invitees to look up who invited them.
+     *
+     * @param privateKey - The referral private key
+     * @returns Referral info including inviter and status
+     * @throws InvitationError if referral not found or expired
+     */
+    async retrieve(privateKey) {
+        try {
+            const url = `${this.getBaseUrl()}/referral/retrieve?key=${encodeURIComponent(privateKey)}`;
+            const response = await fetch(url);
+            if (!response.ok) {
+                let errorMessage = `HTTP error! status: ${response.status}`;
+                try {
+                    const error = (await response.json());
+                    errorMessage = error.error || errorMessage;
+                }
+                catch {
+                    errorMessage = response.statusText || errorMessage;
+                }
+                throw new InvitationError(errorMessage, {
+                    code: 'INVITATION_RETRIEVE_FAILED',
+                    source: 'INVITATIONS',
+                    context: { status: response.status, url, privateKey }
+                });
+            }
+            return response.json();
+        }
+        catch (error) {
+            if (error instanceof InvitationError) {
+                throw error;
+            }
+            throw new InvitationError(`Failed to retrieve referral: ${error instanceof Error ? error.message : 'Unknown error'}`, {
+                code: 'INVITATION_RETRIEVE_ERROR',
+                source: 'INVITATIONS',
+                cause: error,
+                context: { privateKey }
+            });
+        }
+    }
+    /**
+     * List all referrals created by the authenticated user
+     *
+     * Requires authentication - the user's address is extracted from the JWT token.
+     *
+     * @returns List of referrals with their status and metadata
+     * @throws InvitationError if not authenticated or request fails
+     */
+    async listMine() {
+        if (!this.getToken) {
+            throw new InvitationError("Authentication required to list referrals", {
+                code: 'INVITATION_AUTH_REQUIRED',
+                source: 'INVITATIONS'
+            });
+        }
+        try {
+            const url = `${this.getBaseUrl()}/referral/my-referrals`;
+            const headers = await this.getAuthHeaders();
+            const response = await fetch(url, { headers });
+            if (!response.ok) {
+                let errorMessage = `HTTP error! status: ${response.status}`;
+                try {
+                    const error = (await response.json());
+                    errorMessage = error.error || errorMessage;
+                }
+                catch {
+                    errorMessage = response.statusText || errorMessage;
+                }
+                throw new InvitationError(errorMessage, {
+                    code: 'INVITATION_LIST_FAILED',
+                    source: 'INVITATIONS',
+                    context: { status: response.status, url }
+                });
+            }
+            return response.json();
+        }
+        catch (error) {
+            if (error instanceof InvitationError) {
+                throw error;
+            }
+            throw new InvitationError(`Failed to list referrals: ${error instanceof Error ? error.message : 'Unknown error'}`, {
+                code: 'INVITATION_LIST_ERROR',
+                source: 'INVITATIONS',
+                cause: error
+            });
+        }
+    }
+}

package/dist/errors.js

@@ -0,0 +1,69 @@
+import { CirclesError } from '@aboutcircles/sdk-utils';
+/**
+ * Base error for invitations package
+ */
+export class InvitationError extends CirclesError {
+    constructor(message, options) {
+        super('InvitationError', message, { ...options, source: options?.source || 'INVITATIONS' });
+    }
+    /**
+     * Error when no valid invitation path is found
+     */
+    static noPathFound(from, to, reason) {
+        return new InvitationError(`No valid invitation path found from ${from} to ${to}. ${reason || 'The inviter may not have enough balance of the proxy inviter\'s token or there\'s no trust connection.'}`, {
+            code: 'INVITATION_NO_PATH',
+            source: 'PATHFINDING',
+            context: { from, to, reason },
+        });
+    }
+    /**
+     * Error when no proxy inviters are available
+     */
+    static noProxyInviters(inviter) {
+        return new InvitationError(`No proxy inviters found for ${inviter}. The inviter must have mutual trust connections with users who are also trusted by the invitation module, and these users must have sufficient balance.`, {
+            code: 'INVITATION_NO_PROXY_INVITERS',
+            source: 'VALIDATION',
+            context: { inviter },
+        });
+    }
+    /**
+     * Error when balance is insufficient for the requested invitations
+     */
+    static insufficientBalance(requestedInvites, availableInvites, requested, available, from, to) {
+        const requestedCrc = Number(requested) / 1e18;
+        const availableCrc = Number(available) / 1e18;
+        return new InvitationError(`Insufficient balance for ${requestedInvites} invitation(s). Can only afford ${availableInvites} invitation(s). Requested: ${requestedCrc.toFixed(6)} CRC, Available: ${availableCrc.toFixed(6)} CRC.`, {
+            code: 'INVITATION_INSUFFICIENT_BALANCE',
+            source: 'VALIDATION',
+            context: {
+                from,
+                to,
+                requestedInvites,
+                availableInvites,
+                requested: requested.toString(),
+                available: available.toString(),
+                requestedCrc,
+                availableCrc,
+            },
+        });
+    }
+    /**
+     * Error when invitee is already registered in Circles Hub
+     */
+    static inviteeAlreadyRegistered(inviter, invitee) {
+        return new InvitationError(`Invitee ${invitee} is already registered as a human in Circles Hub. Cannot invite an already registered user.`, {
+            code: 'INVITATION_INVITEE_ALREADY_REGISTERED',
+            source: 'VALIDATION',
+            context: { inviter, invitee },
+        });
+    }
+    /**
+     * Error when no addresses are provided for invitation
+     */
+    static noAddressesProvided() {
+        return new InvitationError('At least one address must be provided for invitation.', {
+            code: 'INVITATION_NO_ADDRESSES_PROVIDED',
+            source: 'VALIDATION',
+        });
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
-export * from './InvitationBuilder';
+export * from './Invitations';
+export * from './InviteFarm';
+export * from './Referrals';
 export * from './errors';
+export * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}