@aboutcircles/sdk-invitations 0.1.24 → 0.1.25

package/dist/types.d.ts

@@ -16,56 +16,50 @@ export interface ReferralInfo {
 /**
  * Full referral record returned from my-referrals endpoint
  */
+export interface ReferralSession {
+    id: string;
+    slug: string;
+    label: string | null;
+}
 export interface Referral {
-    /** Unique identifier */
     id: string;
-    /** The referral private key */
     privateKey: string;
-    /** Current status */
     status: ReferralStatus;
-    /** The Safe account address */
     accountAddress?: string;
-    /** When the referral was created */
     createdAt: string;
-    /** When the account was confirmed on-chain */
+    pendingAt: string;
+    staleAt: string | null;
     confirmedAt: string | null;
-    /** When the account was claimed */
     claimedAt: string | null;
+    /** Distribution sessions this key belongs to. Empty array if not assigned. */
+    sessions: ReferralSession[];
 }
-/**
- * Response from my-referrals endpoint
- */
 export interface ReferralList {
-    /** List of referrals */
     referrals: Referral[];
-    /** Total count */
     count: number;
+    total: number;
+    limit: number;
+    offset: number;
 }
 /**
- * Referral preview returned from the list endpoint (key is masked)
+ * Referral preview returned from the public list/{address} endpoint (key is masked)
  */
 export interface ReferralPreview {
-    /** Unique identifier */
     id: string;
-    /** Masked private key preview (e.g. "0x123456...cdef") */
+    /** Masked private key preview (e.g. "0x1234...7890") */
     keyPreview: string;
-    /** Current status */
     status: ReferralStatus;
-    /** The Safe account address */
     accountAddress: string | null;
-    /** When the referral was created */
     createdAt: string;
-    /** When the referral entered pending state */
     pendingAt: string | null;
-    /** When the referral became stale */
     staleAt: string | null;
-    /** When the account was confirmed on-chain */
     confirmedAt: string | null;
-    /** When the account was claimed */
     claimedAt: string | null;
+    /** Whether this key is also present in at least one distribution session */
+    inSession: boolean;
 }
 /**
- * Paginated response from referrals/list endpoint
+ * Paginated response from the public list/{address} endpoint
  */
 export interface ReferralPreviewList {
     referrals: ReferralPreview[];
@@ -73,6 +67,8 @@ export interface ReferralPreviewList {
     total: number;
     limit: number;
     offset: number;
+    /** 'synced' = fresh RPC check, 'cached' = DB-cached status (30s TTL) */
+    syncStatus: "synced" | "cached";
 }
 /**
  * Error response from API
@@ -80,4 +76,141 @@ export interface ReferralPreviewList {
 export interface ApiError {
     error: string;
 }
+/**
+ * Result from store-batch endpoint
+ */
+export interface StoreBatchResult {
+    success: boolean;
+    stored: number;
+    failed: number;
+    errors?: Array<{
+        index: number;
+        keyPreview: string;
+        reason: string;
+    }>;
+}
+/**
+ * A distribution session gates access to an inviter's key pool
+ * via quota, expiry, and pause controls.
+ */
+export interface DistributionSession {
+    id: string;
+    slug: string;
+    inviterAddress: string;
+    label: string | null;
+    quota: number;
+    dispensedCount: number;
+    expiresAt: string | null;
+    paused: boolean;
+    createdAt: string;
+    updatedAt: string;
+    /** Full URL for QR codes (only when DISTRIBUTION_BASE_URL is configured) */
+    distributionUrl: string | null;
+}
+/**
+ * Paginated list of distribution sessions
+ */
+export interface DistributionSessionList {
+    sessions: DistributionSession[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Parameters for creating a distribution session
+ */
+export interface CreateSessionParams {
+    /** Inviter's Ethereum address whose key pool this session draws from */
+    inviterAddress: string;
+    /** Maximum number of keys this session can dispense */
+    quota: number;
+    /** Human-readable label (e.g. "ETHDenver 2026 booth") */
+    label?: string;
+    /** ISO 8601 expiry timestamp */
+    expiresAt?: string;
+}
+/**
+ * Parameters for updating a distribution session
+ */
+export interface UpdateSessionParams {
+    label?: string;
+    quota?: number;
+    /** New expiry (ISO 8601), or null to remove expiry */
+    expiresAt?: string | null;
+    paused?: boolean;
+}
+/**
+ * A single key entry within a distribution session
+ */
+export interface SessionKey {
+    id: string;
+    privateKey: string;
+    signerAddress: string | null;
+    accountAddress: string | null;
+    status: "queued" | "dispatched" | "claimed";
+    dispatchedAt: string | null;
+    claimedAt: string | null;
+    addedAt: string;
+}
+/**
+ * Paginated list of keys in a distribution session
+ */
+export interface SessionKeyList {
+    keys: SessionKey[];
+    total: number;
+    queuedCount: number;
+    dispatchedCount: number;
+    claimedCount: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Result from adding keys to a distribution session
+ */
+export interface AddKeysResult {
+    added: number;
+    skipped: number;
+    claimed: number;
+    errors: Array<{
+        key: string;
+        error: string;
+    }>;
+}
+/**
+ * Result from dispensing a key via a distribution session slug.
+ */
+export interface DispenseResult {
+    /** Full private key for the invitation link */
+    privateKey: string;
+    /** Inviter address that owns the key pool */
+    inviter: string;
+    /** Pre-built claim URL (only when DISTRIBUTION_BASE_URL configured) */
+    claimUrl?: string;
+    /** The session slug this key was dispensed through */
+    sessionSlug: string;
+}
+/**
+ * Error codes returned when dispense fails.
+ */
+export type DispenseErrorCode = "SESSION_NOT_FOUND" | "POOL_EMPTY" | "SESSION_EXPIRED" | "QUOTA_EXHAUSTED" | "SESSION_PAUSED" | "RATE_LIMITED" | "UNKNOWN";
+/**
+ * Typed error thrown by dispense() with a code for programmatic handling.
+ */
+export declare class DispenseError extends Error {
+    readonly code: DispenseErrorCode;
+    readonly httpStatus: number;
+    constructor(message: string, code: DispenseErrorCode, httpStatus: number);
+}
+/**
+ * Error codes for distribution session CRUD operations.
+ */
+export type SessionErrorCode = "VALIDATION_ERROR" | "NOT_FOUND" | "CONFLICT" | "SERVER_ERROR";
+/**
+ * Typed error thrown by session CRUD methods.
+ */
+export declare class SessionError extends Error {
+    readonly code: SessionErrorCode;
+    readonly httpStatus: number;
+    constructor(message: string, code: SessionErrorCode, httpStatus: number);
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,MAAM,EAAE,cAAc,CAAC;IACvB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mCAAmC;IACnC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,+BAA+B;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qCAAqC;IACrC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mCAAmC;IACnC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1 +1,26 @@
-export {};
+/**
+ * Typed error thrown by dispense() with a code for programmatic handling.
+ */
+export class DispenseError extends Error {
+    code;
+    httpStatus;
+    constructor(message, code, httpStatus) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.name = "DispenseError";
+    }
+}
+/**
+ * Typed error thrown by session CRUD methods.
+ */
+export class SessionError extends Error {
+    code;
+    httpStatus;
+    constructor(message, code, httpStatus) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.name = "SessionError";
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aboutcircles/sdk-invitations",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Circles Invitations Module SDK",
   "type": "module",
   "main": "./dist/index.js",