@aboutcircles/sdk-invitations 0.1.10 → 0.1.11

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,4 +1,5 @@
 export * from './Invitations';
+export * from './InviteFarm';
 export * from './Referrals';
 export * from './errors';
 export * from './types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,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"}