@aboutcircles/sdk-invitations 0.1.24 → 0.1.26

package/dist/Distributions.d.ts

@@ -0,0 +1,41 @@
+import { type DistributionSession, type DistributionSessionList, type CreateSessionParams, type UpdateSessionParams, type SessionKeyList, type AddKeysResult, type DispenseResult } from "./types.js";
+/**
+ * HTTP client for distribution session management.
+ *
+ * Distribution sessions gate access to an inviter's key pool via
+ * quota, expiry, and pause controls. Each session gets a unique slug
+ * for QR codes / links.
+ *
+ * Session management endpoints require authentication. Pass a `getToken`
+ * callback to supply the Bearer JWT. The `dispense` endpoint is public.
+ */
+export declare class Distributions {
+    private readonly baseUrl;
+    private readonly getToken?;
+    constructor(baseUrl: string, getToken?: (() => Promise<string>) | undefined);
+    private getBaseUrl;
+    private getAuthHeaders;
+    createSession(params: CreateSessionParams): Promise<DistributionSession>;
+    listSessions(inviter: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<DistributionSessionList>;
+    getSession(id: string): Promise<DistributionSession>;
+    updateSession(id: string, params: UpdateSessionParams): Promise<DistributionSession>;
+    deleteSession(id: string): Promise<void>;
+    addKeys(id: string, keys: string[]): Promise<AddKeysResult>;
+    listKeys(id: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<SessionKeyList>;
+    removeKey(id: string, keyId: string): Promise<void>;
+    /**
+     * Dispense a key via a distribution session slug (public, no auth required).
+     *
+     * @throws {DispenseError} with typed code:
+     *   - `SESSION_NOT_FOUND` (404), `POOL_EMPTY` (404), `SESSION_EXPIRED` (410),
+     *     `QUOTA_EXHAUSTED` (410), `SESSION_PAUSED` (423), `RATE_LIMITED` (429)
+     */
+    dispense(slug: string): Promise<DispenseResult>;
+}
+//# sourceMappingURL=Distributions.d.ts.map

package/dist/Distributions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Distributions.d.ts","sourceRoot":"","sources":["../src/Distributions.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,EAIpB,MAAM,YAAY,CAAC;AASpB;;;;;;;;;GASG;AACH,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBADT,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,GAAE,MAAM,OAAO,CAAC,MAAM,CAAC,aAAA;IAGnD,OAAO,CAAC,UAAU;YAMJ,cAAc;IAOtB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsBxE,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,uBAAuB,CAAC;IAsB7B,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAkBpD,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsBpF,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBxC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAsB3D,QAAQ,CACZ,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,cAAc,CAAC;IAuBpB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBzD;;;;;;OAMG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAuCtD"}

package/dist/Distributions.js

@@ -0,0 +1,170 @@
+import { DispenseError, SessionError, } from "./types.js";
+function sessionErrorCode(status) {
+    if (status === 400)
+        return "VALIDATION_ERROR";
+    if (status === 404)
+        return "NOT_FOUND";
+    if (status === 409)
+        return "CONFLICT";
+    return "SERVER_ERROR";
+}
+/**
+ * HTTP client for distribution session management.
+ *
+ * Distribution sessions gate access to an inviter's key pool via
+ * quota, expiry, and pause controls. Each session gets a unique slug
+ * for QR codes / links.
+ *
+ * Session management endpoints require authentication. Pass a `getToken`
+ * callback to supply the Bearer JWT. The `dispense` endpoint is public.
+ */
+export class Distributions {
+    baseUrl;
+    getToken;
+    constructor(baseUrl, getToken) {
+        this.baseUrl = baseUrl;
+        this.getToken = getToken;
+    }
+    getBaseUrl() {
+        return this.baseUrl.endsWith("/")
+            ? this.baseUrl.slice(0, -1)
+            : this.baseUrl;
+    }
+    async getAuthHeaders() {
+        const base = { "Content-Type": "application/json" };
+        if (!this.getToken)
+            return base;
+        const token = await this.getToken();
+        return { ...base, Authorization: `Bearer ${token}` };
+    }
+    async createSession(params) {
+        const response = await fetch(`${this.getBaseUrl()}/distributions/sessions`, {
+            method: "POST",
+            headers: await this.getAuthHeaders(),
+            body: JSON.stringify(params),
+        });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new SessionError(error.error || `Failed to create session: ${response.statusText}`, sessionErrorCode(response.status), response.status);
+        }
+        return response.json();
+    }
+    async listSessions(inviter, opts) {
+        const params = new URLSearchParams({ inviter });
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set("offset", String(opts.offset));
+        const response = await fetch(`${this.getBaseUrl()}/distributions/sessions?${params}`, { headers: await this.getAuthHeaders() });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new SessionError(error.error || `Failed to list sessions: ${response.statusText}`, sessionErrorCode(response.status), response.status);
+        }
+        return response.json();
+    }
+    async getSession(id) {
+        const response = await fetch(`${this.getBaseUrl()}/distributions/sessions/${encodeURIComponent(id)}`, { headers: await this.getAuthHeaders() });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new SessionError(error.error || `Failed to get session: ${response.statusText}`, sessionErrorCode(response.status), response.status);
+        }
+        return response.json();
+    }
+    async updateSession(id, params) {
+        const response = await fetch(`${this.getBaseUrl()}/distributions/sessions/${encodeURIComponent(id)}`, {
+            method: "PATCH",
+            headers: await this.getAuthHeaders(),
+            body: JSON.stringify(params),
+        });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new SessionError(error.error || `Failed to update session: ${response.statusText}`, sessionErrorCode(response.status), response.status);
+        }
+        return response.json();
+    }
+    async deleteSession(id) {
+        const response = await fetch(`${this.getBaseUrl()}/distributions/sessions/${encodeURIComponent(id)}`, {
+            method: "DELETE",
+            headers: await this.getAuthHeaders(),
+        });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new SessionError(error.error || `Failed to delete session: ${response.statusText}`, sessionErrorCode(response.status), response.status);
+        }
+    }
+    async addKeys(id, keys) {
+        const response = await fetch(`${this.getBaseUrl()}/distributions/sessions/${encodeURIComponent(id)}/keys`, {
+            method: "POST",
+            headers: await this.getAuthHeaders(),
+            body: JSON.stringify({ keys }),
+        });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new SessionError(error.error || `Failed to add keys: ${response.statusText}`, sessionErrorCode(response.status), response.status);
+        }
+        return response.json();
+    }
+    async listKeys(id, opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set("offset", String(opts.offset));
+        const query = params.toString() ? `?${params}` : "";
+        const response = await fetch(`${this.getBaseUrl()}/distributions/sessions/${encodeURIComponent(id)}/keys${query}`, { headers: await this.getAuthHeaders() });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new SessionError(error.error || `Failed to list keys: ${response.statusText}`, sessionErrorCode(response.status), response.status);
+        }
+        return response.json();
+    }
+    async removeKey(id, keyId) {
+        const response = await fetch(`${this.getBaseUrl()}/distributions/sessions/${encodeURIComponent(id)}/keys/${encodeURIComponent(keyId)}`, {
+            method: "DELETE",
+            headers: await this.getAuthHeaders(),
+        });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new SessionError(error.error || `Failed to remove key: ${response.statusText}`, sessionErrorCode(response.status), response.status);
+        }
+    }
+    /**
+     * Dispense a key via a distribution session slug (public, no auth required).
+     *
+     * @throws {DispenseError} with typed code:
+     *   - `SESSION_NOT_FOUND` (404), `POOL_EMPTY` (404), `SESSION_EXPIRED` (410),
+     *     `QUOTA_EXHAUSTED` (410), `SESSION_PAUSED` (423), `RATE_LIMITED` (429)
+     */
+    async dispense(slug) {
+        const response = await fetch(`${this.getBaseUrl()}/d/${encodeURIComponent(slug)}`, { headers: { Accept: "application/json" } });
+        if (!response.ok) {
+            let message;
+            let code;
+            try {
+                const error = (await response.json());
+                message = error.error;
+            }
+            catch {
+                message = response.statusText;
+            }
+            switch (response.status) {
+                case 404:
+                    code = message.includes("keys available") ? "POOL_EMPTY" : "SESSION_NOT_FOUND";
+                    break;
+                case 410:
+                    code = message.includes("quota") ? "QUOTA_EXHAUSTED" : "SESSION_EXPIRED";
+                    break;
+                case 423:
+                    code = "SESSION_PAUSED";
+                    break;
+                case 429:
+                    code = "RATE_LIMITED";
+                    break;
+                default:
+                    code = "UNKNOWN";
+            }
+            throw new DispenseError(message, code, response.status);
+        }
+        return response.json();
+    }
+}

package/dist/Invitations.d.ts

@@ -1,5 +1,5 @@
 import type { Address, TransactionRequest, CirclesConfig } from '@aboutcircles/sdk-types';
-import type { ReferralPreviewList } from './types';
+import type { ReferralPreviewList } from './types.js';
 export interface ProxyInviter {
     address: Address;
     possibleInvites: number;

package/dist/Invitations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Invitations.d.ts","sourceRoot":"","sources":["../src/Invitations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAO,MAAM,yBAAyB,CAAC;AAU/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAkBnD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB;AAOD;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,wBAAwB,CAAkC;gBAEtD,MAAM,EAAE,aAAa;IA+BjC;;;;;;OAMG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA2BzE;;;;;;;;OAQG;IACG,gBAAgB,CACpB,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,KAAK,MAAM,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC;IA+BhB;;;;;;;OAOG;IACG,aAAa,CACjB,OAAO,EAAE,OAAO,EAChB,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,GACjB,OAAO,CAAC,mBAAmB,CAAC;IAiC/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA2FvF;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,EAAE,OAAO;IAmDpE;;;;;;;;;OASG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO;IAkCzC;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAqGhE;;;;;;;;;;;;;;;;;OAiBG;IACG,gBAAgB,CACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;QAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;QAAC,UAAU,EAAE,KAAK,MAAM,EAAE,CAAA;KAAE,CAAC;IA0F7E;;;;;;;;;;;;;OAaG;IACG,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,eAAe,GAAE,OAAc,GAAG,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;IA8CvG;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;IA8BxC;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;CAOlF"}
+{"version":3,"file":"Invitations.d.ts","sourceRoot":"","sources":["../src/Invitations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAO,MAAM,yBAAyB,CAAC;AAU/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAkBtD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB;AAOD;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,wBAAwB,CAAkC;gBAEtD,MAAM,EAAE,aAAa;IA+BjC;;;;;;OAMG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA2BzE;;;;;;;;OAQG;IACG,gBAAgB,CACpB,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,KAAK,MAAM,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC;IA+BhB;;;;;;;OAOG;IACG,aAAa,CACjB,OAAO,EAAE,OAAO,EAChB,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,GACjB,OAAO,CAAC,mBAAmB,CAAC;IAiC/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA2FvF;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,EAAE,OAAO;IAmDpE;;;;;;;;;OASG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO;IAkCzC;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAqGhE;;;;;;;;;;;;;;;;;OAiBG;IACG,gBAAgB,CACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;QAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;QAAC,UAAU,EAAE,KAAK,MAAM,EAAE,CAAA;KAAE,CAAC;IA0F7E;;;;;;;;;;;;;OAaG;IACG,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,eAAe,GAAE,OAAc,GAAG,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;IA8CvG;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;IA8BxC;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;CAOlF"}

package/dist/Invitations.js

@@ -1,6 +1,6 @@
 import { RpcClient, PathfinderMethods, TrustMethods, TokenMethods } from '@aboutcircles/sdk-rpc';
 import { HubV2ContractMinimal, ReferralsModuleContractMinimal, InvitationFarmContractMinimal, SafeContractMinimal, InvitationModuleContractMinimal } from '@aboutcircles/sdk-core/minimal';
-import { InvitationError } from './errors';
+import { InvitationError } from './errors.js';
 import { TransferBuilder } from '@aboutcircles/sdk-transfers';
 import { hexToBytes, INVITATION_FEE, MAX_FLOW, generatePrivateKey, privateKeyToAddress, encodeAbiParameters, keccak256, SAFE_PROXY_FACTORY, ACCOUNT_INITIALIZER_HASH, ACCOUNT_CREATION_CODE_HASH, checksumAddress, GNOSIS_GROUP_ADDRESS, FARM_DESTINATION } from '@aboutcircles/sdk-utils';
 /**

package/dist/InviteFarm.d.ts

@@ -1,5 +1,5 @@
 import type { Address, CirclesConfig, TransactionRequest, Hex } from '@aboutcircles/sdk-types';
-import type { ReferralPreviewList } from './types';
+import type { ReferralPreviewList } from './types.js';
 export interface GeneratedReferral {
     secret: Hex;
     signer: Address;

package/dist/InviteFarm.d.ts.map

@@ -1 +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;AAInD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAU;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgC;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiC;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;gBAEjC,MAAM,EAAE,aAAa;IAiBjC,4DAA4D;IACtD,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjD,sCAAsC;IAChC,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAIzC,sDAAsD;IAChD,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7C;;;;;;OAMG;IACG,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAoC1F;;;;;;OAMG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAoC5F;;;;;OAKG;IACG,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI3F,2DAA2D;YAC7C,aAAa;IAQ3B,4FAA4F;IAC5F,OAAO,CAAC,qBAAqB;IAW7B,iGAAiG;IACjG,OAAO,CAAC,0BAA0B;IAYlC,yFAAyF;IACzF,OAAO,CAAC,mBAAmB;IAU3B,+FAA+F;IAC/F,OAAO,CAAC,wBAAwB;CAUjC"}
+{"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,YAAY,CAAC;AAItD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAU;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgC;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiC;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;gBAEjC,MAAM,EAAE,aAAa;IAiBjC,4DAA4D;IACtD,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjD,sCAAsC;IAChC,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAIzC,sDAAsD;IAChD,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7C;;;;;;OAMG;IACG,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAoC1F;;;;;;OAMG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAoC5F;;;;;OAKG;IACG,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI3F,2DAA2D;YAC7C,aAAa;IAQ3B,4FAA4F;IAC5F,OAAO,CAAC,qBAAqB;IAW7B,iGAAiG;IACjG,OAAO,CAAC,0BAA0B;IAYlC,yFAAyF;IACzF,OAAO,CAAC,mBAAmB;IAU3B,+FAA+F;IAC/F,OAAO,CAAC,wBAAwB;CAUjC"}

package/dist/InviteFarm.js

@@ -1,6 +1,6 @@
 import { InvitationFarmContractMinimal, ReferralsModuleContractMinimal, HubV2ContractMinimal } from '@aboutcircles/sdk-core/minimal';
-import { InvitationError } from './errors';
-import { Invitations } from './Invitations';
+import { InvitationError } from './errors.js';
+import { Invitations } from './Invitations.js';
 import { encodeAbiParameters, INVITATION_FEE } from '@aboutcircles/sdk-utils';
 /**
  * InviteFarm handles batch invitation generation via the InvitationFarm contract.

package/dist/Referrals.d.ts

@@ -1,44 +1,59 @@
-import type { ReferralInfo, ReferralList } from "./types";
+import type { ReferralInfo, ReferralList, ReferralPreviewList, StoreBatchResult } from "./types.js";
 /**
- * Referrals service client for retrieving referral information
+ * Referrals service client for storing and retrieving referral links
  *
- * The referrals backend enables Circles SDK users to query referral data:
+ * The referrals backend enables Circles SDK users to invite others via referral links.
+ * - Store: Save a referral private key with on-chain validation
  * - 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
+     * Store a referral private key
      *
-     * This is a public endpoint - no authentication required.
-     * Used by invitees to look up who invited them.
+     * 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 - the on-chain indexer captures the true inviter.
+     */
+    store(privateKey: string, inviter: string): Promise<void>;
+    /**
+     * Store multiple referral private keys in a single request (max 200)
      *
-     * @param privateKey - The referral private key
-     * @returns Referral info including inviter and status
-     * @throws InvitationError if referral not found or expired
+     * Processing is independent — one failure doesn't block others.
+     */
+    storeBatch(invitations: Array<{
+        privateKey: string;
+        inviter: string;
+    }>): Promise<StoreBatchResult>;
+    /**
+     * Retrieve referral info by private key (public endpoint, no auth required)
      */
     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.
+     */
+    listMine(opts?: {
+        limit?: number;
+        offset?: number;
+        inSession?: boolean;
+        status?: string;
+    }): Promise<ReferralList>;
+    /**
+     * List referrals for a given address (public, no auth required)
      *
-     * @returns List of referrals with their status and metadata
-     * @throws InvitationError if not authenticated or request fails
+     * Returns masked key previews — full keys are never exposed here.
      */
-    listMine(): Promise<ReferralList>;
+    listPublic(address: string, opts?: {
+        limit?: number;
+        offset?: number;
+        inSession?: boolean;
+    }): Promise<ReferralPreviewList>;
 }
 //# sourceMappingURL=Referrals.d.ts.map

package/dist/Referrals.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"Referrals.d.ts","sourceRoot":"","sources":["../src/Referrals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAY,MAAM,YAAY,CAAC;AAE9G;;;;;;;GAOG;AACH,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBADT,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,GAAE,MAAM,OAAO,CAAC,MAAM,CAAC,aAAA;IAGnD,OAAO,CAAC,UAAU;YAMJ,cAAc;IAO5B;;;;;;OAMG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/D;;;;OAIG;IACG,UAAU,CACd,WAAW,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAC1D,OAAO,CAAC,gBAAgB,CAAC;IAe5B;;OAEG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAazD;;;;OAIG;IACG,QAAQ,CAAC,IAAI,CAAC,EAAE;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,YAAY,CAAC;IAuBzB;;;;OAIG;IACG,UAAU,CACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9D,OAAO,CAAC,mBAAmB,CAAC;CAkBhC"}

package/dist/Referrals.js

@@ -1,22 +1,14 @@
-import { InvitationError } from "./errors";
 /**
- * Referrals service client for retrieving referral information
+ * Referrals service client for storing and retrieving referral links
  *
- * The referrals backend enables Circles SDK users to query referral data:
+ * The referrals backend enables Circles SDK users to invite others via referral links.
+ * - Store: Save a referral private key with on-chain validation
  * - 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;
@@ -27,103 +19,104 @@ export class Referrals {
             : this.baseUrl;
     }
     async getAuthHeaders() {
-        if (!this.getToken) {
-            return { "Content-Type": "application/json" };
-        }
+        const base = { "Content-Type": "application/json" };
+        if (!this.getToken)
+            return base;
         const token = await this.getToken();
-        return {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${token}`,
-        };
+        return { ...base, Authorization: `Bearer ${token}` };
     }
     /**
-     * Retrieve referral info by private key
+     * Store a referral private key
      *
-     * This is a public endpoint - no authentication required.
-     * Used by invitees to look up who invited them.
+     * 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 - the on-chain indexer captures the true inviter.
+     */
+    async store(privateKey, inviter) {
+        const response = await fetch(`${this.getBaseUrl()}/store`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ privateKey, inviter }),
+        });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new Error(error.error || `Failed to store referral: ${response.statusText}`);
+        }
+    }
+    /**
+     * Store multiple referral private keys in a single request (max 200)
      *
-     * @param privateKey - The referral private key
-     * @returns Referral info including inviter and status
-     * @throws InvitationError if referral not found or expired
+     * Processing is independent — one failure doesn't block others.
      */
-    async retrieve(privateKey) {
-        try {
-            const url = `${this.getBaseUrl()}/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();
+    async storeBatch(invitations) {
+        const response = await fetch(`${this.getBaseUrl()}/store-batch`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ invitations }),
+        });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new Error(error.error || `Failed to store batch: ${response.statusText}`);
         }
-        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 }
-            });
+        return response.json();
+    }
+    /**
+     * Retrieve referral info by private key (public endpoint, no auth required)
+     */
+    async retrieve(privateKey) {
+        const response = await fetch(`${this.getBaseUrl()}/retrieve?key=${encodeURIComponent(privateKey)}`);
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new Error(error.error || `Failed to retrieve referral: ${response.statusText}`);
         }
+        return response.json();
     }
     /**
      * 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() {
+    async listMine(opts) {
         if (!this.getToken) {
-            throw new InvitationError("Authentication required to list referrals", {
-                code: 'INVITATION_AUTH_REQUIRED',
-                source: 'INVITATIONS'
-            });
+            throw new Error("Authentication required to list referrals");
         }
-        try {
-            const url = `${this.getBaseUrl()}/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();
+        const params = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set("offset", String(opts.offset));
+        if (opts?.inSession !== undefined)
+            params.set("inSession", String(opts.inSession));
+        if (opts?.status !== undefined)
+            params.set("status", opts.status);
+        const query = params.toString() ? `?${params}` : "";
+        const headers = await this.getAuthHeaders();
+        const response = await fetch(`${this.getBaseUrl()}/my-referrals${query}`, { headers });
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new Error(error.error || `Failed to list referrals: ${response.statusText}`);
         }
-        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
-            });
+        return response.json();
+    }
+    /**
+     * List referrals for a given address (public, no auth required)
+     *
+     * Returns masked key previews — full keys are never exposed here.
+     */
+    async listPublic(address, opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set("offset", String(opts.offset));
+        if (opts?.inSession !== undefined)
+            params.set("inSession", String(opts.inSession));
+        const query = params.toString() ? `?${params}` : "";
+        const response = await fetch(`${this.getBaseUrl()}/list/${encodeURIComponent(address)}${query}`);
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new Error(error.error || `Failed to list referrals: ${response.statusText}`);
         }
+        return response.json();
     }
 }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export * from './Invitations';
-export * from './InviteFarm';
-export * from './Referrals';
-export * from './errors';
-export * from './types';
+export * from './Invitations.js';
+export * from './InviteFarm.js';
+export * from './Referrals.js';
+export * from './Distributions.js';
+export * from './errors.js';
+export * from './types.js';
 //# 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,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,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,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}