@beeperbot/sdk 0.1.1 → 0.2.1

package/dist/index.js

@@ -1,5 +1,5 @@
-import { z } from 'zod';
 import { randomUUID } from 'crypto';
+import { z } from 'zod';
 
 // src/client/http.ts
 
@@ -46,6 +46,7 @@ var ErrorCodes = {
   DRAFT_NOT_FOUND: "DRAFT_NOT_FOUND",
   DRAFT_INVALID: "DRAFT_INVALID",
   // Generic
+  NOT_FOUND: "NOT_FOUND",
   UNKNOWN_ERROR: "UNKNOWN_ERROR"
 };
 var RETRYABLE_ERROR_CODES = [
@@ -63,8 +64,7 @@ var HTTP_STATUS_TO_ERROR_CODE = {
   400: ErrorCodes.VALIDATION_ERROR,
   401: ErrorCodes.UNAUTHORIZED,
   403: ErrorCodes.FORBIDDEN,
-  404: ErrorCodes.UNKNOWN_ERROR,
-  // Specific 404s are mapped differently
+  404: ErrorCodes.NOT_FOUND,
   408: ErrorCodes.TIMEOUT,
   429: ErrorCodes.RATE_LIMITED,
   500: ErrorCodes.INTERNAL_ERROR,
@@ -197,16 +197,35 @@ var BeeperError = class _BeeperError extends Error {
    * Create from an HTTP response
    */
   static fromHttpResponse(statusCode, body, requestId) {
-    const rawBody = body;
-    const errorData = rawBody?.error ?? rawBody;
-    const code = errorData?.code ?? ErrorCodes.UNKNOWN_ERROR;
-    const message = errorData?.message ?? `HTTP ${statusCode} error`;
+    let code = ErrorCodes.UNKNOWN_ERROR;
+    let message = `HTTP ${statusCode} error`;
+    let details;
+    if (body && typeof body === "object") {
+      const errorBody = body.error;
+      const parsed = errorBody && typeof errorBody === "object" ? errorBody : body;
+      if (parsed.code && typeof parsed.code === "string") {
+        const knownCodes = Object.values(ErrorCodes);
+        code = knownCodes.includes(parsed.code) ? parsed.code : ErrorCodes.UNKNOWN_ERROR;
+      }
+      if (parsed.message && typeof parsed.message === "string") {
+        message = parsed.message;
+      }
+      if (parsed.details && typeof parsed.details === "object") {
+        details = parsed.details;
+      }
+    }
+    if (code === ErrorCodes.UNKNOWN_ERROR) {
+      const statusFallback = HTTP_STATUS_TO_ERROR_CODE[statusCode];
+      if (statusFallback) {
+        code = statusFallback;
+      }
+    }
     const context = { statusCode };
     if (requestId !== void 0) {
       context.requestId = requestId;
     }
-    if (errorData?.details !== void 0) {
-      context.details = errorData.details;
+    if (details !== void 0) {
+      context.details = details;
     }
     return new _BeeperError({
       code,
@@ -224,22 +243,10 @@ var API_BASE_URLS = {
 };
 var TIMEOUTS = {
   /** Default request timeout */
-  DEFAULT: 3e4,
-  /** Timeout for quote requests */
-  QUOTE: 1e4,
-  /** Timeout for execute requests (longer due to blockchain) */
-  EXECUTE: 6e4,
-  /** Timeout for health checks */
-  HEALTH: 5e3
-};
-var ENDPOINTS = {
-  HEALTH: "/send/health",
-  QUOTES: "/send/quotes",
-  KEYS: "/keys"
+  DEFAULT: 3e4
 };
 var HEADERS = {
   IDEMPOTENCY_KEY: "Idempotency-Key",
-  AUTHORIZATION: "Authorization",
   REQUEST_ID: "X-Request-Id",
   CONTENT_TYPE: "Content-Type"
 };
@@ -532,7 +539,7 @@ var HttpClient = class {
   buildHeaders(options) {
     const headers = {
       [HEADERS.CONTENT_TYPE]: "application/json",
-      [HEADERS.AUTHORIZATION]: `Bearer ${this.config.apiKey}`,
+      "Authorization": `Bearer ${this.config.apiKey}`,
       "User-Agent": `beeper-sdk/${SDK_VERSION}`,
       ...options.headers
     };
@@ -582,8 +589,8 @@ var HttpClient = class {
   mergeSignals(signal1, signal2) {
     const controller = new AbortController();
     const abort = () => controller.abort();
-    signal1.addEventListener("abort", abort);
-    signal2.addEventListener("abort", abort);
+    signal1.addEventListener("abort", abort, { once: true });
+    signal2.addEventListener("abort", abort, { once: true });
     if (signal1.aborted || signal2.aborted) {
       controller.abort();
     }
@@ -591,9 +598,7 @@ var HttpClient = class {
   }
 };
 function generateIdempotencyKey() {
-  const timestamp = Date.now().toString(36);
-  const random = Math.random().toString(36).substring(2, 15);
-  return `${timestamp}-${random}`;
+  return `idk_${randomUUID()}`;
 }
 
 // src/client/filters.schema.ts
@@ -891,7 +896,7 @@ function generateFilterDocumentation() {
 }
 
 // src/client/AgentClient.ts
-var ENDPOINTS2 = {
+var ENDPOINTS = {
   LOOKUP: "/agent/lookup",
   INTENT: "/agent/intent",
   PRICE: "/agent/price",
@@ -901,8 +906,6 @@ var ENDPOINTS2 = {
 };
 var AgentClient = class {
   http;
-  // @ts-expect-error Reserved for future use
-  _debug;
   constructor(config) {
     if (!config.apiKey) {
       throw BeeperError.validation("API key is required");
@@ -916,7 +919,6 @@ var AgentClient = class {
       ...config.debug && { debug: config.debug }
     });
     this.http = new HttpClient(httpConfig);
-    this._debug = config.debug ?? false;
   }
   /**
    * Look up a user by username, FID, or wallet address
@@ -934,7 +936,7 @@ var AgentClient = class {
   async lookup(identifier) {
     const params = typeof identifier === "number" ? { fid: identifier } : { q: identifier };
     const response = await this.http.get(
-      ENDPOINTS2.LOOKUP,
+      ENDPOINTS.LOOKUP,
       { params }
     );
     return response.data.data;
@@ -954,7 +956,7 @@ var AgentClient = class {
   async getPrice(identifier) {
     const params = typeof identifier === "number" ? { fid: identifier } : { q: identifier };
     const response = await this.http.get(
-      ENDPOINTS2.PRICE,
+      ENDPOINTS.PRICE,
       { params }
     );
     return response.data.data;
@@ -988,7 +990,7 @@ var AgentClient = class {
       throw BeeperError.validation("Amount must be a positive number");
     }
     const response = await this.http.post(
-      ENDPOINTS2.INTENT,
+      ENDPOINTS.INTENT,
       {
         to: input.to,
         amountUsd: amountStr,
@@ -1046,7 +1048,7 @@ var AgentClient = class {
       throw BeeperError.validation("Budget must be a positive number");
     }
     const response = await this.http.post(
-      ENDPOINTS2.ESTIMATE,
+      ENDPOINTS.ESTIMATE,
       {
         filters: input.filters,
         budgetUsd: budgetStr,
@@ -1076,7 +1078,7 @@ var AgentClient = class {
   async preview(input) {
     const limit = Math.min(input.limit ?? 10, 20);
     const response = await this.http.post(
-      ENDPOINTS2.PREVIEW,
+      ENDPOINTS.PREVIEW,
       {
         filters: input.filters,
         limit
@@ -1108,7 +1110,7 @@ var AgentClient = class {
       throw BeeperError.validation("Budget must be a positive number");
     }
     const response = await this.http.post(
-      ENDPOINTS2.BULK_INTENT,
+      ENDPOINTS.BULK_INTENT,
       {
         filters: input.filters,
         budgetUsd: budgetStr,
@@ -1182,9 +1184,6 @@ function getApiKeyEnvironment(apiKey) {
   }
   return null;
 }
-function createAuthorizationHeader(apiKey) {
-  return `Bearer ${apiKey}`;
-}
 function maskApiKey(apiKey) {
   if (!apiKey || apiKey.length < 12) {
     return "***";
@@ -1213,15 +1212,7 @@ var QuoteSchema = z.object({
   depositChainId: z.number(),
   depositTokenAddress: z.string(),
   expiresAt: z.string(),
-  input: z.object({
-    filter: z.record(z.unknown()),
-    tokenAddress: z.string(),
-    chainId: z.number(),
-    amountPerRecipient: z.string(),
-    budgetCap: z.string(),
-    memo: z.string().optional(),
-    metadata: z.record(z.unknown()).optional()
-  }),
+  input: z.record(z.unknown()),
   createdAt: z.string(),
   updatedAt: z.string()
 });
@@ -1246,18 +1237,24 @@ var ConfirmResultSchema = z.object({
   status: z.enum(["confirmed", "pending_verification"]),
   detectedAmount: z.string(),
   sufficient: z.boolean(),
-  blockNumber: z.number(),
-  confirmedAt: z.string()
+  blockNumber: z.number().int().optional(),
+  confirmedAt: z.string().datetime().optional()
 });
 var ExecuteResultSchema = z.object({
   quoteId: z.string(),
-  status: z.enum(["executing", "queued"]),
-  estimatedCompletionAt: z.string(),
-  batchId: z.string()
+  status: z.enum(["executing", "queued", "pending_deployment"]),
+  estimatedCompletionAt: z.string().datetime().optional(),
+  batchId: z.string().optional(),
+  deployment: z.object({
+    to: z.string(),
+    data: z.string(),
+    value: z.string(),
+    chainId: z.number()
+  }).optional()
 });
 var ReceiptSchema = z.object({
   quoteId: z.string(),
-  status: z.enum(["completed", "partial", "failed"]),
+  status: z.enum(["completed", "partial", "failed", "executing"]),
   successCount: z.number(),
   failureCount: z.number(),
   totalSent: z.string(),
@@ -1272,7 +1269,12 @@ var ReceiptSchema = z.object({
       error: z.string().optional()
     })
   ),
-  completedAt: z.string()
+  completedAt: z.string().datetime().optional()
+});
+var ConfirmDeploymentResultSchema = z.object({
+  quoteId: z.string(),
+  status: z.string(),
+  escrowId: z.string().optional()
 });
 var HealthSchema = z.object({
   status: z.enum(["healthy", "degraded", "unhealthy"]),
@@ -1284,7 +1286,7 @@ var HealthSchema = z.object({
     oracle: z.enum(["up", "down"])
   })
 });
-var ENDPOINTS3 = {
+var ENDPOINTS2 = {
   QUOTES: "/api/v1/sdk/send/quotes",
   HEALTH: "/api/v1/sdk/send/health"
 };
@@ -1365,7 +1367,7 @@ var BeeperClient = class {
       ttlSeconds: opts?.ttlSeconds ?? 300
     };
     const response = await this.http.post(
-      ENDPOINTS3.QUOTES,
+      ENDPOINTS2.QUOTES,
       body,
       {},
       QuoteSchema
@@ -1421,7 +1423,7 @@ var BeeperClient = class {
       ttlSeconds: opts?.ttlSeconds ?? 300
     };
     const response = await this.http.post(
-      ENDPOINTS3.QUOTES,
+      ENDPOINTS2.QUOTES,
       body,
       {},
       AttentionQuoteSchema
@@ -1435,7 +1437,7 @@ var BeeperClient = class {
    */
   async getQuote(quoteId) {
     const response = await this.http.get(
-      `${ENDPOINTS3.QUOTES}/${quoteId}`,
+      `${ENDPOINTS2.QUOTES}/${quoteId}`,
       {},
       QuoteSchema
     );
@@ -1455,7 +1457,7 @@ var BeeperClient = class {
       throw BeeperError.validation("Invalid transaction hash format");
     }
     const response = await this.http.post(
-      `${ENDPOINTS3.QUOTES}/${quoteId}/confirm`,
+      `${ENDPOINTS2.QUOTES}/${quoteId}/confirm`,
       { txHash: params.txHash },
       { idempotencyKey: params.idempotencyKey },
       ConfirmResultSchema
@@ -1465,21 +1467,46 @@ var BeeperClient = class {
   /**
    * Triggers execution of the send
    * @param quoteId - The quote ID
-   * @param params - Execution parameters including idempotencyKey
+   * @param params - Execution parameters including idempotencyKey and optional deploymentMode
    * @returns Execution result
    */
   async executeSend(quoteId, params) {
     if (!params.idempotencyKey) {
       throw BeeperError.validation("Idempotency key is required for executeSend");
     }
+    const body = {};
+    if (params.deploymentMode) {
+      body.deploymentMode = params.deploymentMode;
+    }
     const response = await this.http.post(
-      `${ENDPOINTS3.QUOTES}/${quoteId}/execute`,
-      {},
+      `${ENDPOINTS2.QUOTES}/${quoteId}/execute`,
+      body,
       { idempotencyKey: params.idempotencyKey },
       ExecuteResultSchema
     );
     return response.data;
   }
+  /**
+   * Confirms a client-side deployment transaction
+   * @param quoteId - The quote ID
+   * @param input - Deployment confirmation parameters including txHash
+   * @returns Deployment confirmation result
+   */
+  async confirmDeployment(quoteId, input) {
+    if (!quoteId) {
+      throw BeeperError.validation("quoteId is required");
+    }
+    if (!input.txHash) {
+      throw BeeperError.validation("txHash is required");
+    }
+    const response = await this.http.post(
+      `${ENDPOINTS2.QUOTES}/${quoteId}/confirm-deployment`,
+      { txHash: input.txHash },
+      { idempotencyKey: `cdep_${quoteId}_${input.txHash.slice(0, 10)}` },
+      ConfirmDeploymentResultSchema
+    );
+    return response.data;
+  }
   /**
    * Gets the receipt for a completed (or failed) execution
    * @param quoteId - The quote ID
@@ -1487,7 +1514,7 @@ var BeeperClient = class {
    */
   async getReceiptByQuoteId(quoteId) {
     const response = await this.http.get(
-      `${ENDPOINTS3.QUOTES}/${quoteId}/receipt`,
+      `${ENDPOINTS2.QUOTES}/${quoteId}/receipt`,
       {},
       ReceiptSchema
     );
@@ -1533,7 +1560,7 @@ var BeeperClient = class {
    */
   async health() {
     const response = await this.http.get(
-      ENDPOINTS3.HEALTH,
+      ENDPOINTS2.HEALTH,
       {},
       HealthSchema
     );
@@ -2155,6 +2182,18 @@ function updateDraft(draft, updates) {
 function isReadyForQuote(draft) {
   return draft.status === "draft" && draft.name.length > 0 && parseFloat(draft.amount) > 0;
 }
+
+// src/send/validation.ts
+function validateQuoteId(quoteId) {
+  if (!quoteId || typeof quoteId !== "string") {
+    throw BeeperError.validation("quoteId is required");
+  }
+  if (!/^qt_[a-zA-Z0-9]+$/.test(quoteId)) {
+    throw BeeperError.validation(`Invalid quoteId format: ${quoteId}. Expected format: qt_<id>`);
+  }
+}
+
+// src/send/quotes.ts
 var ApiQuoteResponseSchema = z.object({
   id: z.string().regex(/^qt_[a-zA-Z0-9]+$/),
   status: z.enum([
@@ -2197,13 +2236,7 @@ async function createQuote(httpClient, draft, opts) {
   return response.data;
 }
 async function getQuote(httpClient, quoteId) {
-  if (!quoteId.match(/^qt_[a-zA-Z0-9]+$/)) {
-    throw new BeeperError({
-      code: ErrorCodes.VALIDATION_ERROR,
-      message: "Invalid quote ID format. Expected format: qt_xxxxx",
-      retryable: false
-    });
-  }
+  validateQuoteId(quoteId);
   const response = await httpClient.get(
     `/api/v1/sdk/send/quotes/${quoteId}`,
     {},
@@ -2225,7 +2258,11 @@ function getChainId(network) {
     polygon: 137,
     optimism: 10
   };
-  return chainIds[network] ?? 1;
+  const id = chainIds[network];
+  if (id === void 0) {
+    throw BeeperError.validation(`Unsupported network: ${network}`);
+  }
+  return id;
 }
 function getTokenAddress(token, network) {
   const addresses = {
@@ -2244,15 +2281,19 @@ function getTokenAddress(token, network) {
       optimism: "0x94b008aA00579c1307B0EF2c499aD98a8ce58e58"
     }
   };
-  return addresses[token]?.[network] ?? "0x0000000000000000000000000000000000000000";
+  const addr = addresses[token]?.[network];
+  if (!addr) {
+    throw BeeperError.validation(`Unsupported token ${token} on network ${network}`);
+  }
+  return addr;
 }
 var ConfirmDepositResponseSchema = z.object({
   quoteId: z.string(),
   status: z.enum(["confirmed", "pending_verification"]),
   detectedAmount: z.string(),
   sufficient: z.boolean(),
-  blockNumber: z.number().int(),
-  confirmedAt: z.string().datetime()
+  blockNumber: z.number().int().optional(),
+  confirmedAt: z.string().datetime().optional()
 });
 async function confirmDeposit(httpClient, quoteId, params) {
   validateQuoteId(quoteId);
@@ -2291,26 +2332,23 @@ function validateTxHash(txHash) {
     });
   }
 }
-function validateQuoteId(quoteId) {
-  if (!quoteId.match(/^qt_[a-zA-Z0-9]+$/)) {
-    throw new BeeperError({
-      code: ErrorCodes.VALIDATION_ERROR,
-      message: "Invalid quote ID format. Expected format: qt_xxxxx",
-      retryable: false
-    });
-  }
-}
 function generateDepositIdempotencyKey(quoteId) {
   return `confirm-${quoteId}`;
 }
 var ExecuteSendResponseSchema = z.object({
   quoteId: z.string(),
-  status: z.enum(["executing", "queued"]),
-  estimatedCompletionAt: z.string().datetime(),
-  batchId: z.string()
-});
-async function executeSend(httpClient, quoteId, params) {
-  validateQuoteId2(quoteId);
+  status: z.enum(["executing", "queued", "pending_deployment"]),
+  estimatedCompletionAt: z.string().datetime().optional(),
+  batchId: z.string().optional(),
+  deployment: z.object({
+    to: z.string(),
+    data: z.string(),
+    value: z.string(),
+    chainId: z.number()
+  }).optional()
+});
+async function executeSend(httpClient, quoteId, params, options) {
+  validateQuoteId(quoteId);
   if (!params.idempotencyKey || params.idempotencyKey.length === 0) {
     throw new BeeperError({
       code: ErrorCodes.VALIDATION_ERROR,
@@ -2318,10 +2356,13 @@ async function executeSend(httpClient, quoteId, params) {
       retryable: false
     });
   }
+  const body = {};
+  if (options?.deploymentMode) {
+    body.deploymentMode = options.deploymentMode;
+  }
   const response = await httpClient.post(
     `/api/v1/sdk/send/quotes/${quoteId}/execute`,
-    {},
-    // Empty body as per HTTP contract
+    body,
     { idempotencyKey: params.idempotencyKey },
     ExecuteSendResponseSchema
   );
@@ -2331,19 +2372,13 @@ function isExecuting(result) {
   return result.status === "executing" || result.status === "queued";
 }
 function getEstimatedTimeRemaining(result) {
+  if (!result.estimatedCompletionAt) {
+    return 0;
+  }
   const estimatedCompletion = new Date(result.estimatedCompletionAt);
   const now = /* @__PURE__ */ new Date();
   return Math.max(0, estimatedCompletion.getTime() - now.getTime());
 }
-function validateQuoteId2(quoteId) {
-  if (!quoteId.match(/^qt_[a-zA-Z0-9]+$/)) {
-    throw new BeeperError({
-      code: ErrorCodes.VALIDATION_ERROR,
-      message: "Invalid quote ID format. Expected format: qt_xxxxx",
-      retryable: false
-    });
-  }
-}
 function generateExecuteIdempotencyKey(quoteId) {
   return `execute-${quoteId}`;
 }
@@ -2356,25 +2391,19 @@ var ReceiptTransactionSchema = z.object({
 });
 var ApiReceiptResponseSchema = z.object({
   quoteId: z.string(),
-  status: z.enum(["completed", "partial", "failed"]),
+  status: z.enum(["completed", "partial", "failed", "executing"]),
   successCount: z.number().int().min(0),
   failureCount: z.number().int().min(0),
   totalSent: z.string(),
   refundAmount: z.string(),
   refundTxHash: z.string().nullable().optional(),
   transactions: z.array(ReceiptTransactionSchema),
-  completedAt: z.string().datetime()
+  completedAt: z.string().datetime().optional()
 });
 var DEFAULT_MAX_ATTEMPTS = 60;
 var DEFAULT_INTERVAL_MS = 5e3;
 async function getReceipt(httpClient, quoteId) {
-  if (!quoteId.match(/^qt_[a-zA-Z0-9]+$/)) {
-    throw new BeeperError({
-      code: ErrorCodes.VALIDATION_ERROR,
-      message: "Invalid quote ID format. Expected format: qt_xxxxx",
-      retryable: false
-    });
-  }
+  validateQuoteId(quoteId);
   const response = await httpClient.get(
     `/api/v1/sdk/send/quotes/${quoteId}/receipt`,
     {},
@@ -2406,7 +2435,7 @@ async function pollUntilComplete(httpClient, quoteId, opts) {
     }
   }
   throw new BeeperError({
-    code: ErrorCodes.QUOTE_EXPIRED,
+    code: ErrorCodes.TIMEOUT,
     message: `Polling timed out after ${maxAttempts} attempts`,
     context: { details: { quoteId, maxAttempts } },
     retryable: false
@@ -2427,11 +2456,27 @@ function getFailedTransactions(receipt) {
 }
 function sleep(ms, signal) {
   return new Promise((resolve, reject) => {
-    const timeoutId = setTimeout(resolve, ms);
-    signal?.addEventListener("abort", () => {
-      clearTimeout(timeoutId);
-      reject(new Error("Aborted"));
-    });
+    if (signal?.aborted) {
+      reject(new BeeperError({
+        code: ErrorCodes.TIMEOUT,
+        message: "Poll aborted by signal",
+        retryable: false
+      }));
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (signal) signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new BeeperError({
+        code: ErrorCodes.TIMEOUT,
+        message: "Poll aborted by signal",
+        retryable: false
+      }));
+    }
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
   });
 }
 
@@ -2466,7 +2511,7 @@ var FilterExpression = class {
     return FilterBuilder.not(this);
   }
 };
-var FilterBuilder = class {
+var FilterBuilder = class _FilterBuilder {
   // ===========================================================================
   // Logical Combinators
   // ===========================================================================
@@ -2476,7 +2521,7 @@ var FilterBuilder = class {
    */
   static and(filters) {
     if (filters.length === 0) {
-      throw new Error("and() requires at least one filter");
+      throw BeeperError.validation("and() requires at least one filter");
     }
     if (filters.length === 1) {
       return filters[0];
@@ -2491,7 +2536,7 @@ var FilterBuilder = class {
    */
   static or(filters) {
     if (filters.length === 0) {
-      throw new Error("or() requires at least one filter");
+      throw BeeperError.validation("or() requires at least one filter");
     }
     if (filters.length === 1) {
       return filters[0];
@@ -2528,7 +2573,7 @@ var FilterBuilder = class {
    */
   static activeInLastDays(days) {
     if (days < 1 || days > 365) {
-      throw new Error("activeInLastDays must be between 1 and 365");
+      throw BeeperError.validation("activeInLastDays must be between 1 and 365");
     }
     return new FilterExpression({ activeInLastDays: days });
   }
@@ -2541,7 +2586,7 @@ var FilterBuilder = class {
    */
   static neynarScoreMin(score) {
     if (score < 0 || score > 1) {
-      throw new Error("neynarScoreMin must be between 0 and 1");
+      throw BeeperError.validation("neynarScoreMin must be between 0 and 1");
     }
     return new FilterExpression({ neynarScoreMin: score });
   }
@@ -2551,7 +2596,7 @@ var FilterBuilder = class {
    */
   static neynarScoreMax(score) {
     if (score < 0 || score > 1) {
-      throw new Error("neynarScoreMax must be between 0 and 1");
+      throw BeeperError.validation("neynarScoreMax must be between 0 and 1");
     }
     return new FilterExpression({ neynarScoreMax: score });
   }
@@ -2562,10 +2607,10 @@ var FilterBuilder = class {
    */
   static neynarScoreRange(min, max) {
     if (min !== void 0 && (min < 0 || min > 1)) {
-      throw new Error("neynarScoreRange min must be between 0 and 1");
+      throw BeeperError.validation("neynarScoreRange min must be between 0 and 1");
     }
     if (max !== void 0 && (max < 0 || max > 1)) {
-      throw new Error("neynarScoreRange max must be between 0 and 1");
+      throw BeeperError.validation("neynarScoreRange max must be between 0 and 1");
     }
     const range = {};
     if (min !== void 0) range.min = min;
@@ -2580,11 +2625,10 @@ var FilterBuilder = class {
     return new FilterExpression({ spamLabel: label });
   }
   /**
-   * Filter to exclude spam users (convenience method)
-   * @deprecated Use spamLabel('not_spam_only') instead
+   * Convenience method: exclude spam users (shorthand for spamLabel('not_spam_only'))
    */
   static excludeSpam() {
-    return new FilterExpression({ spamLabel: "not_spam_only" });
+    return _FilterBuilder.spamLabel("not_spam_only");
   }
   // ===========================================================================
   // Social Graph Filters (Followers)
@@ -2595,7 +2639,7 @@ var FilterBuilder = class {
    */
   static minFollowers(count) {
     if (count < 0) {
-      throw new Error("minFollowers must be >= 0");
+      throw BeeperError.validation("minFollowers must be >= 0");
     }
     return new FilterExpression({ minFollowers: count });
   }
@@ -2605,7 +2649,7 @@ var FilterBuilder = class {
    */
   static maxFollowers(count) {
     if (count < 0) {
-      throw new Error("maxFollowers must be >= 0");
+      throw BeeperError.validation("maxFollowers must be >= 0");
     }
     return new FilterExpression({ maxFollowers: count });
   }
@@ -2616,10 +2660,10 @@ var FilterBuilder = class {
    */
   static followerRange(min, max) {
     if (min !== void 0 && min < 0) {
-      throw new Error("followerRange min must be >= 0");
+      throw BeeperError.validation("followerRange min must be >= 0");
     }
     if (max !== void 0 && max < 0) {
-      throw new Error("followerRange max must be >= 0");
+      throw BeeperError.validation("followerRange max must be >= 0");
     }
     const range = {};
     if (min !== void 0) range.min = min;
@@ -2632,7 +2676,7 @@ var FilterBuilder = class {
    */
   static followersOf(fid) {
     if (fid < 1) {
-      throw new Error("followersOf FID must be >= 1");
+      throw BeeperError.validation("followersOf FID must be >= 1");
     }
     return new FilterExpression({ followersOf: fid });
   }
@@ -2642,7 +2686,7 @@ var FilterBuilder = class {
    */
   static mutualsWith(fid) {
     if (fid < 1) {
-      throw new Error("mutualsWith FID must be >= 1");
+      throw BeeperError.validation("mutualsWith FID must be >= 1");
     }
     return new FilterExpression({ mutualsWith: fid });
   }
@@ -2655,7 +2699,7 @@ var FilterBuilder = class {
    */
   static maxAttentionPriceUsd(usd) {
     if (usd < 0) {
-      throw new Error("maxAttentionPriceUsd must be >= 0");
+      throw BeeperError.validation("maxAttentionPriceUsd must be >= 0");
     }
     return new FilterExpression({ maxAttentionPriceUsd: usd });
   }
@@ -2668,11 +2712,11 @@ var FilterBuilder = class {
    */
   static tokenHolder(opts) {
     if (!/^0x[a-fA-F0-9]{40}$/.test(opts.tokenAddress)) {
-      throw new Error("tokenAddress must be a valid Ethereum address");
+      throw BeeperError.validation("tokenAddress must be a valid Ethereum address");
     }
     if (opts.minBalance !== void 0) {
       if (!/^[0-9]+$/.test(opts.minBalance)) {
-        throw new Error("minBalance must be a numeric string (wei)");
+        throw BeeperError.validation("minBalance must be a numeric string (wei)");
       }
       return new FilterExpression({
         walletMinBalance: {
@@ -2695,24 +2739,26 @@ var FilterBuilder = class {
    */
   static tokenHolders(opts) {
     if (opts.length === 0) {
-      throw new Error("tokenHolders requires at least one token option");
+      throw BeeperError.validation("tokenHolders requires at least one token option");
     }
     if (opts.length > 10) {
       throw new Error("tokenHolders cannot exceed 10 tokens");
     }
     for (const opt of opts) {
       if (!/^0x[a-fA-F0-9]{40}$/.test(opt.tokenAddress)) {
-        throw new Error("tokenAddress must be a valid Ethereum address");
+        throw BeeperError.validation("tokenAddress must be a valid Ethereum address");
       }
       if (opt.minBalance !== void 0 && !/^[0-9]+$/.test(opt.minBalance)) {
-        throw new Error("minBalance must be a numeric string (wei)");
+        throw BeeperError.validation("minBalance must be a numeric string (wei)");
       }
     }
     return new FilterExpression({
       tokenHolders: opts.map((o) => ({
-        tokenAddress: o.tokenAddress,
-        chainId: o.chainId,
-        ...o.minBalance !== void 0 ? { minBalance: o.minBalance } : {}
+        contractAddress: o.tokenAddress,
+        chain: o.chainId === 8453 ? "base" : "ethereum",
+        tokenStandard: o.tokenStandard ?? "ERC20",
+        ...o.minBalance !== void 0 ? { minBalance: o.minBalance } : {},
+        ...o.tokenId !== void 0 ? { tokenId: o.tokenId } : {}
       }))
     });
   }
@@ -2735,11 +2781,14 @@ var FilterBuilder = class {
         throw new Error("minBalance must be a numeric string (wei)");
       }
     }
+    const chainNames = { 1: "ethereum", 8453: "base", 42161: "arbitrum", 10: "optimism", 137: "polygon" };
     return new FilterExpression({
       cachedTokenHolders: opts.map((o) => ({
-        tokenAddress: o.tokenAddress,
-        chainId: o.chainId,
-        ...o.minBalance !== void 0 ? { minBalance: o.minBalance } : {}
+        contractAddress: o.tokenAddress,
+        chain: chainNames[o.chainId] ?? String(o.chainId),
+        tokenStandard: o.tokenStandard ?? "ERC20",
+        ...o.minBalance !== void 0 ? { minBalance: o.minBalance } : {},
+        ...o.tokenId !== void 0 ? { tokenId: o.tokenId } : {}
       }))
     });
   }
@@ -2801,7 +2850,7 @@ var FilterBuilder = class {
    */
   static minTenureDays(days) {
     if (days < 0) {
-      throw new Error("minTenureDays must be >= 0");
+      throw BeeperError.validation("minTenureDays must be >= 0");
     }
     return new FilterExpression({ minTenureDays: days });
   }
@@ -2821,10 +2870,10 @@ var FilterBuilder = class {
    */
   static userIds(ids) {
     if (ids.length === 0) {
-      throw new Error("userIds requires at least one ID");
+      throw BeeperError.validation("userIds requires at least one ID");
     }
     if (ids.length > 1e3) {
-      throw new Error("userIds cannot exceed 1000 IDs");
+      throw BeeperError.validation("userIds cannot exceed 1000 IDs");
     }
     return new FilterExpression({ userIds: ids });
   }
@@ -2841,10 +2890,10 @@ var FilterBuilder = class {
    */
   static fids(fids) {
     if (fids.length === 0) {
-      throw new Error("fids requires at least one FID");
+      throw BeeperError.validation("fids requires at least one FID");
     }
     if (fids.length > 1e3) {
-      throw new Error("fids cannot exceed 1000 FIDs");
+      throw BeeperError.validation("fids cannot exceed 1000 FIDs");
     }
     return new FilterExpression({ fids });
   }
@@ -2857,7 +2906,7 @@ var FilterBuilder = class {
    */
   static hasTag(tag) {
     if (tag.length > 64) {
-      throw new Error("Tag must be 64 characters or less");
+      throw BeeperError.validation("Tag must be 64 characters or less");
     }
     return new FilterExpression({ hasTag: tag });
   }
@@ -2867,7 +2916,7 @@ var FilterBuilder = class {
    */
   static hasAnyTag(tags) {
     if (tags.length === 0 || tags.length > 20) {
-      throw new Error("hasAnyTag requires 1-20 tags");
+      throw BeeperError.validation("hasAnyTag requires 1-20 tags");
     }
     return new FilterExpression({ hasAnyTag: tags });
   }
@@ -2877,7 +2926,7 @@ var FilterBuilder = class {
    */
   static hasAllTags(tags) {
     if (tags.length === 0 || tags.length > 20) {
-      throw new Error("hasAllTags requires 1-20 tags");
+      throw BeeperError.validation("hasAllTags requires 1-20 tags");
     }
     return new FilterExpression({ hasAllTags: tags });
   }
@@ -2948,17 +2997,17 @@ var FilterBuilder = class {
    */
   static timezones(zones) {
     if (zones.length === 0) {
-      throw new Error("timezones requires at least one timezone");
+      throw BeeperError.validation("timezones requires at least one timezone");
     }
     if (zones.length > 24) {
       throw new Error("timezones cannot exceed 24 entries");
     }
     for (const zone of zones) {
       if (zone.offset < -12 || zone.offset > 14) {
-        throw new Error("timezone offset must be between -12 and 14");
+        throw BeeperError.validation("timezone offset must be between -12 and 14");
       }
       if (zone.range !== void 0 && (zone.range < 0 || zone.range > 12)) {
-        throw new Error("timezone range must be between 0 and 12");
+        throw BeeperError.validation("timezone range must be between 0 and 12");
       }
     }
     return new FilterExpression({ timezones: zones });
@@ -2969,28 +3018,28 @@ var FilterBuilder = class {
    */
   static countries(codes) {
     if (codes.length === 0) {
-      throw new Error("countries requires at least one country code");
+      throw BeeperError.validation("countries requires at least one country code");
     }
     if (codes.length > 50) {
       throw new Error("countries cannot exceed 50 country codes");
     }
     for (const code of codes) {
       if (!/^[A-Z]{2}$/.test(code)) {
-        throw new Error("Country codes must be ISO 3166-1 alpha-2 format (e.g., US, CA, GB)");
+        throw BeeperError.validation("Country codes must be ISO 3166-1 alpha-2 format (e.g., US, CA, GB)");
       }
     }
-    return new FilterExpression({ countries: codes.map((code) => ({ code })) });
+    return new FilterExpression({ countries: codes.map((c) => ({ code: c })) });
   }
   // ===========================================================================
   // Engagement & Quality Filters
   // ===========================================================================
   /**
    * Filter users with quotient score >= minimum
-   * @param score - Minimum quotient score (0-1, where 0.5=Casual, 0.75=Influential, 0.9=Exceptional)
+   * @param score - Minimum quotient score (0-1)
    */
   static quotientScoreMin(score) {
     if (score < 0 || score > 1) {
-      throw new Error("quotientScoreMin must be between 0 and 1");
+      throw BeeperError.validation("quotientScoreMin must be between 0 and 1");
     }
     return new FilterExpression({ quotientScoreMin: score });
   }
@@ -3000,7 +3049,7 @@ var FilterBuilder = class {
    */
   static quotientScoreMax(score) {
     if (score < 0 || score > 1) {
-      throw new Error("quotientScoreMax must be between 0 and 1");
+      throw BeeperError.validation("quotientScoreMax must be between 0 and 1");
     }
     return new FilterExpression({ quotientScoreMax: score });
   }
@@ -3027,7 +3076,7 @@ var FilterBuilder = class {
    */
   static minBatteryPercentage(pct) {
     if (pct < 0 || pct > 100) {
-      throw new Error("minBatteryPercentage must be between 0 and 100");
+      throw BeeperError.validation("minBatteryPercentage must be between 0 and 100");
     }
     return new FilterExpression({ minBatteryPercentage: pct });
   }
@@ -3037,7 +3086,7 @@ var FilterBuilder = class {
    */
   static hasRechargedInLastDays(days) {
     if (days < 1) {
-      throw new Error("hasRechargedInLastDays must be >= 1");
+      throw BeeperError.validation("hasRechargedInLastDays must be >= 1");
     }
     return new FilterExpression({ hasRechargedInLastDays: days });
   }
@@ -3071,7 +3120,7 @@ var FilterBuilder = class {
    */
   static minCastCount(count) {
     if (count < 0) {
-      throw new Error("minCastCount must be >= 0");
+      throw BeeperError.validation("minCastCount must be >= 0");
     }
     return new FilterExpression({ minCastCount: count });
   }
@@ -3085,18 +3134,6 @@ var FilterBuilder = class {
   static orderBy(order) {
     return new FilterExpression({ orderBy: order });
   }
-  /**
-   * Limit the number of results
-   * @param n - Maximum number of results
-   * @deprecated Limit is controlled by budgetCap, not this filter. This method will be removed.
-   */
-  static limit(n) {
-    console.warn("FilterBuilder.limit() is deprecated. Use budgetCap to control result count.");
-    if (n < 1 || n > 1e4) {
-      throw new Error("limit must be between 1 and 10000");
-    }
-    return new FilterExpression({ limit: n });
-  }
 };
 var GasTierSchema = z.enum(["slow", "standard", "fast"]);
 var QuoteOptionsSchema = z.object({
@@ -3197,6 +3234,6 @@ function parseReceipt(receipt) {
   return ReceiptSchema2.parse(receipt);
 }
 
-export { API_BASE_URLS, API_KEY_PREFIXES, ActiveInLastDaysFilterSchema, AgentClient, ApiQuoteResponseSchema, ApiReceiptResponseSchema, BeeperClient, BeeperEconomicsFilterSchema, BeeperError, CachedTokenHolderFilterSchema, CachedTokenHolderSchema, ConfirmDepositResponseSchema, ConfirmResultSchema2 as ConfirmResultSchema, CountryFilterSchema, DistributionStrategySchema, DraftInputSchema, DraftSchema, DraftStatusSchema, DraftUpdateSchema, ENDPOINTS, ErrorCodes, ExcludePingedTodayFilterSchema, ExcludeUsersFilterSchema, ExecuteResultSchema2 as ExecuteResultSchema, ExecuteSendResponseSchema, ExecuteStatusSchema, FILTER_SCHEMA, FieldComparisonSchema, FilterBuilder, FilterExpression, FilterExpressionSchema, FilterOperatorSchema, FilterValueSchema, FollowersOfFilterSchema, FollowingOfFilterSchema, GasTierSchema, HEADERS, HTTP_STATUS_TO_ERROR_CODE, HasBaseWalletFilterSchema, HasRechargedInLastDaysFilterSchema, HasTierFilterSchema, HasVerifiedWalletFilterSchema, HttpClient, IsWaitlistedFilterSchema, LegacyFieldComparisonSchema, LegacyFilterOperatorSchema, LegacyFilterValueSchema, LegacyRecipientFilterDSLSchema, MaxAttentionPriceFilterSchema, MaxFidFilterSchema, MaxFollowersFilterSchema, MaxFollowingFilterSchema, MinAttentionPriceFilterSchema, MinBatteryPercentageFilterSchema, MinCastCountFilterSchema, MinClickThroughRateFilterSchema, MinFidFilterSchema, MinFollowersFilterSchema, MinFollowingFilterSchema, MinProTenureDaysFilterSchema, MinTenureDaysFilterSchema, MutualsWithFilterSchema, NetworkSchema, NeynarScoreMaxFilterSchema, NeynarScoreMinFilterSchema, OnchainFilterSchema, OrderBySchema, PlatformFilterSchema, ProSubscriptionFilterSchema, QUOTE_EXPIRATION_SECONDS, QuoteOptionsSchema, QuoteRecipientSchema, QuoteSchema2 as QuoteSchema, QuotientScoreMaxFilterSchema, QuotientScoreMinFilterSchema, RETRYABLE_ERROR_CODES, RETRY_CONFIG, ReceiptSchema2 as ReceiptSchema, ReceiptTransactionSchema, ReceiptTransferSchema, RecipientFilterDSLSchema, RecipientFilterSchema, ReputationFilterSchema, RequireLotteryOptInFilterSchema, RequireQuizOptInFilterSchema, RolesFilterSchema, SDK_VERSION, SignalTokenFilterSchema, SocialFilterSchema, SpamLabelFilterSchema, SpecificUsersFilterSchema, TIMEOUTS, TimezoneFilterSchema, TokenHolderDiscoverySchema, TokenHolderFilterSchema, TokenTypeSchema, TransferStatusSchema, VerifiedOnlyFilterSchema, createAuthorizationHeader, createHttpConfig, BeeperClient_default as default, describeFilters, generateDepositIdempotencyKey, generateExecuteIdempotencyKey, generateFilterDocumentation, generateIdempotencyKey, getAllFilterNames, getApiKeyEnvironment, getFilterSchema, isRetryableCode, isValidApiKeyFormat, maskApiKey, parseDraft, parseDraftInput, parseExecuteResult, parseFilter, parseQuote, parseQuoteOptions, parseReceipt, parseRecipientFilter, safeParseFilter, safeParseRecipientFilter, confirmDeposit as sendConfirmDeposit, createDraft as sendCreateDraft, createQuote as sendCreateQuote, executeSend as sendExecuteSend, getEstimatedTimeRemaining as sendGetEstimatedTimeRemaining, getFailedTransactions as sendGetFailedTransactions, getQuote as sendGetQuote, getReceipt as sendGetReceipt, getSuccessRate as sendGetSuccessRate, isComplete as sendIsComplete, isDepositSufficient as sendIsDepositSufficient, isExecuting as sendIsExecuting, isQuoteExpired as sendIsQuoteExpired, isReadyForDeposit as sendIsReadyForDeposit, isReadyForQuote as sendIsReadyForQuote, isSuccess as sendIsSuccess, pollUntilComplete as sendPollUntilComplete, updateDraft as sendUpdateDraft, validateDraftInput2 as sendValidateDraftInput, validateDraft, validateDraftInput, validateExecuteResult, validateFilter, validateFilterHasTargeting, validateQuote, validateQuoteOptions, validateReceipt, validateRecipientFilter };
+export { API_BASE_URLS, API_KEY_PREFIXES, ActiveInLastDaysFilterSchema, AgentClient, ApiQuoteResponseSchema, ApiReceiptResponseSchema, BeeperClient, BeeperEconomicsFilterSchema, BeeperError, CachedTokenHolderFilterSchema, CachedTokenHolderSchema, ConfirmDepositResponseSchema, ConfirmResultSchema2 as ConfirmResultSchema, CountryFilterSchema, DistributionStrategySchema, DraftInputSchema, DraftSchema, DraftStatusSchema, DraftUpdateSchema, ErrorCodes, ExcludePingedTodayFilterSchema, ExcludeUsersFilterSchema, ExecuteResultSchema2 as ExecuteResultSchema, ExecuteSendResponseSchema, ExecuteStatusSchema, FILTER_SCHEMA, FieldComparisonSchema, FilterBuilder, FilterExpression, FilterExpressionSchema, FilterOperatorSchema, FilterValueSchema, FollowersOfFilterSchema, FollowingOfFilterSchema, GasTierSchema, HEADERS, HTTP_STATUS_TO_ERROR_CODE, HasBaseWalletFilterSchema, HasRechargedInLastDaysFilterSchema, HasTierFilterSchema, HasVerifiedWalletFilterSchema, HttpClient, IsWaitlistedFilterSchema, LegacyFieldComparisonSchema, LegacyFilterOperatorSchema, LegacyFilterValueSchema, LegacyRecipientFilterDSLSchema, MaxAttentionPriceFilterSchema, MaxFidFilterSchema, MaxFollowersFilterSchema, MaxFollowingFilterSchema, MinAttentionPriceFilterSchema, MinBatteryPercentageFilterSchema, MinCastCountFilterSchema, MinClickThroughRateFilterSchema, MinFidFilterSchema, MinFollowersFilterSchema, MinFollowingFilterSchema, MinProTenureDaysFilterSchema, MinTenureDaysFilterSchema, MutualsWithFilterSchema, NetworkSchema, NeynarScoreMaxFilterSchema, NeynarScoreMinFilterSchema, OnchainFilterSchema, OrderBySchema, PlatformFilterSchema, ProSubscriptionFilterSchema, QUOTE_EXPIRATION_SECONDS, QuoteOptionsSchema, QuoteRecipientSchema, QuoteSchema2 as QuoteSchema, QuotientScoreMaxFilterSchema, QuotientScoreMinFilterSchema, RETRYABLE_ERROR_CODES, RETRY_CONFIG, ReceiptSchema2 as ReceiptSchema, ReceiptTransactionSchema, ReceiptTransferSchema, RecipientFilterDSLSchema, RecipientFilterSchema, ReputationFilterSchema, RequireLotteryOptInFilterSchema, RequireQuizOptInFilterSchema, RolesFilterSchema, SDK_VERSION, SignalTokenFilterSchema, SocialFilterSchema, SpamLabelFilterSchema, SpecificUsersFilterSchema, TIMEOUTS, TimezoneFilterSchema, TokenHolderDiscoverySchema, TokenHolderFilterSchema, TokenTypeSchema, TransferStatusSchema, VerifiedOnlyFilterSchema, createHttpConfig, BeeperClient_default as default, describeFilters, generateDepositIdempotencyKey, generateExecuteIdempotencyKey, generateFilterDocumentation, generateIdempotencyKey, getAllFilterNames, getApiKeyEnvironment, getFilterSchema, isRetryableCode, isValidApiKeyFormat, maskApiKey, parseDraft, parseDraftInput, parseExecuteResult, parseFilter, parseQuote, parseQuoteOptions, parseReceipt, parseRecipientFilter, safeParseFilter, safeParseRecipientFilter, confirmDeposit as sendConfirmDeposit, createDraft as sendCreateDraft, createQuote as sendCreateQuote, executeSend as sendExecuteSend, getEstimatedTimeRemaining as sendGetEstimatedTimeRemaining, getFailedTransactions as sendGetFailedTransactions, getQuote as sendGetQuote, getReceipt as sendGetReceipt, getSuccessRate as sendGetSuccessRate, isComplete as sendIsComplete, isDepositSufficient as sendIsDepositSufficient, isExecuting as sendIsExecuting, isQuoteExpired as sendIsQuoteExpired, isReadyForDeposit as sendIsReadyForDeposit, isReadyForQuote as sendIsReadyForQuote, isSuccess as sendIsSuccess, pollUntilComplete as sendPollUntilComplete, updateDraft as sendUpdateDraft, validateDraftInput2 as sendValidateDraftInput, validateDraft, validateDraftInput, validateExecuteResult, validateFilter, validateFilterHasTargeting, validateQuote, validateQuoteOptions, validateReceipt, validateRecipientFilter };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map