@aboutcircles/sdk 0.1.24 → 0.1.25

package/dist/Sdk.d.ts

@@ -36,6 +36,7 @@ export declare class Sdk {
     readonly core: Core;
     readonly rpc: CirclesRpc;
     private readonly profilesClient;
+    private readonly referralsClient?;
     readonly data: CirclesData;
     /**
      * Create a new Sdk instance
@@ -149,6 +150,46 @@ export declare class Sdk {
          */
         get: (cid: string) => Promise<Profile | undefined>;
     };
+    /**
+     * Referral/invitation management methods
+     *
+     * The referrals backend enables users to invite others via referral links.
+     * Requires referralsServiceUrl to be configured in CirclesConfig.
+     */
+    readonly referrals: {
+        /**
+         * Store a referral private key
+         *
+         * The private key is validated on-chain via ReferralsModule.accounts() to ensure
+         * the account exists and has not been claimed. The inviter address is self-declared
+         * for dashboard visibility only.
+         *
+         * @param privateKey - The referral private key (0x-prefixed, 64 hex chars)
+         * @param inviter - Self-declared inviter address for dashboard visibility
+         * @throws Error if referrals service not configured or validation fails
+         */
+        store: (privateKey: string, inviter: Address) => Promise<void>;
+        /**
+         * 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 Error if referrals service not configured or referral not found
+         */
+        retrieve: (privateKey: string) => Promise<import("@aboutcircles/sdk-invitations").ReferralInfo>;
+        /**
+         * List all referrals created by the authenticated user
+         *
+         * Requires authentication - must configure a token provider.
+         *
+         * @returns List of referrals with their status and metadata
+         * @throws Error if referrals service not configured or not authenticated
+         */
+        listMine: () => Promise<import("@aboutcircles/sdk-invitations").ReferralList>;
+    };
     /**
      * Token utilities
      */

package/dist/Sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sdk.d.ts","sourceRoot":"","sources":["../src/Sdk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,cAAc,EACd,OAAO,EAEP,YAAY,EACZ,SAAS,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAiB,IAAI,EAAkC,MAAM,wBAAwB,CAAC;AAE7F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAI7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,qBAAa,GAAG;IACd,SAAgB,aAAa,EAAE,aAAa,CAAC;IAC7C,SAAgB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChD,SAAgB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxC,SAAgB,IAAI,EAAE,IAAI,CAAC;IAC3B,SAAgB,GAAG,EAAE,UAAU,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAW;IAE1C,SAAgB,IAAI,EAAE,WAAW,CAU/B;IAEF;;;;;;OAMG;gBACS,MAAM,GAAE,aAAkC,EAAE,cAAc,CAAC,EAAE,cAAc;IAsBvF;;;;;;;;OAQG;IACG,SAAS,CAAC,aAAa,EAAE,OAAO,EAAE,mBAAmB,GAAE,OAAe,GAAG,OAAO,CAAC,WAAW,GAAG,kBAAkB,GAAG,eAAe,CAAC;IA+B1I;;OAEG;IACH,SAAgB,QAAQ;QACtB;;;;;;;;;;;;;;;;;;;;;;;WAuBG;2BAEQ,OAAO,WACP,OAAO,GAAG,MAAM,KACxB,OAAO,CAAC,WAAW,CAAC;QAsCvB;;;;;;;;;;;;;;;WAeG;kCAC6B,OAAO,GAAG,MAAM,KAAG,OAAO,CAAC,kBAAkB,CAAC;QAqD9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA4BG;yBAEM,OAAO,WACL,OAAO,iBACD,OAAO,qBACH,OAAO,EAAE,QACtB,MAAM,UACJ,MAAM,WACL,OAAO,GAAG,MAAM,KACxB,OAAO,CAAC,eAAe,CAAC;MAsF3B;IAEF;;OAEG;IACH,SAAgB,QAAQ;QACtB;;;;WAIG;0BACqB,OAAO,KAAG,OAAO,CAAC,MAAM,CAAC;QAIjD;;;;WAIG;mBACc,MAAM,KAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;MAGtD;IAEF;;OAEG;IACH,SAAgB,MAAM;QACpB;;;;WAIG;0CACqC,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;QAIlE;;;;WAIG;wCACmC,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;QAIhE;;;;;;;;;;;;;;;;;;;WAmBG;mCAEa,OAAO,UACd,MAAM,cACF,SAAS;MAItB;IAEF;;OAEG;IACH,SAAgB,MAAM;QACpB;;;;WAIG;0BACqB,OAAO,KAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;QAIhE;;;;;;;;;;;;;;;;;;;;;;;;;;;WA2BG;mCAEa,OAAO,UACd,MAAM,cACF,KAAK,GAAG,MAAM;QAK3B;;;;;;;;;;;;;;;;;;;WAmBG;sCACiC,OAAO,KAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QAcrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA6BG;mCACwB,OAAO,UAAS,MAAM,KAAS,UAAU,CAAC,mBAAmB,CAAC;MAGzF;CACH"}
+{"version":3,"file":"Sdk.d.ts","sourceRoot":"","sources":["../src/Sdk.ts"],"names":[],"mappings":"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"}

package/dist/Sdk.js

@@ -1,5 +1,6 @@
 import { circlesConfig, Core, CirclesType, BaseGroupContract } from '@aboutcircles/sdk-core';
 import { Profiles } from '@aboutcircles/sdk-profiles';
+import { Referrals } from '@aboutcircles/sdk-invitations';
 import { CirclesRpc, PagedQuery } from '@aboutcircles/sdk-rpc';
 import { cidV0ToHex } from '@aboutcircles/sdk-utils';
 import { HumanAvatar, OrganisationAvatar, BaseGroupAvatar } from './avatars';
@@ -39,6 +40,7 @@ export class Sdk {
     core;
     rpc;
     profilesClient;
+    referralsClient;
     data = {
         getAvatar: async (address) => {
             return await this.rpc.avatar.getAvatarInfo(address);
@@ -63,6 +65,10 @@ export class Sdk {
         this.core = new Core(config);
         this.rpc = new CirclesRpc(config.circlesRpcUrl);
         this.profilesClient = new Profiles(config.profileServiceUrl);
+        // Initialize referrals client if service URL is configured
+        if (config.referralsServiceUrl) {
+            this.referralsClient = new Referrals(config.referralsServiceUrl);
+        }
         // Validate and extract sender address from contract runner
         if (contractRunner) {
             if (!contractRunner.sendTransaction) {
@@ -335,6 +341,61 @@ export class Sdk {
             return await this.profilesClient.get(cid);
         },
     };
+    /**
+     * Referral/invitation management methods
+     *
+     * The referrals backend enables users to invite others via referral links.
+     * Requires referralsServiceUrl to be configured in CirclesConfig.
+     */
+    referrals = {
+        /**
+         * Store a referral private key
+         *
+         * The private key is validated on-chain via ReferralsModule.accounts() to ensure
+         * the account exists and has not been claimed. The inviter address is self-declared
+         * for dashboard visibility only.
+         *
+         * @param privateKey - The referral private key (0x-prefixed, 64 hex chars)
+         * @param inviter - Self-declared inviter address for dashboard visibility
+         * @throws Error if referrals service not configured or validation fails
+         */
+        store: async (privateKey, inviter) => {
+            if (!this.referralsClient) {
+                throw SdkError.configError('Referrals service not configured. Set referralsServiceUrl in CirclesConfig.');
+            }
+            return await this.referralsClient.store(privateKey, inviter);
+        },
+        /**
+         * 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 Error if referrals service not configured or referral not found
+         */
+        retrieve: async (privateKey) => {
+            if (!this.referralsClient) {
+                throw SdkError.configError('Referrals service not configured. Set referralsServiceUrl in CirclesConfig.');
+            }
+            return await this.referralsClient.retrieve(privateKey);
+        },
+        /**
+         * List all referrals created by the authenticated user
+         *
+         * Requires authentication - must configure a token provider.
+         *
+         * @returns List of referrals with their status and metadata
+         * @throws Error if referrals service not configured or not authenticated
+         */
+        listMine: async () => {
+            if (!this.referralsClient) {
+                throw SdkError.configError('Referrals service not configured. Set referralsServiceUrl in CirclesConfig.');
+            }
+            return await this.referralsClient.listMine();
+        },
+    };
     /**
      * Token utilities
      */