scrapebadger 0.51.1 → 0.53.0

package/dist/{index-Dz6kHfFt.d.cts → index-DBk60c2e.d.cts}

@@ -2084,6 +2084,29 @@ declare class ScrapeBadgerError extends Error {
 declare class AuthenticationError extends ScrapeBadgerError {
     constructor(message?: string);
 }
+/**
+ * Raised when the API key is not permitted to call this API (HTTP 403,
+ * `error: "insufficient_scope"`). Keys can be restricted to specific APIs in
+ * the dashboard; a refused call is not charged.
+ *
+ * Extends `AuthenticationError`, which is what a 403 threw before 0.52.0.
+ */
+declare class PermissionDeniedError extends AuthenticationError {
+    /** The API the request needed, e.g. `"twitter"` */
+    readonly requiredScope: string | undefined;
+    /** The APIs this key may call */
+    readonly allowedScopes: string[];
+    constructor(message?: string, requiredScope?: string, allowedScopes?: string[]);
+}
+/**
+ * Raised when the API key is restricted to IP addresses and this request came
+ * from another one (HTTP 403, `error: "ip_not_allowed"`). Not charged.
+ */
+declare class IPNotAllowedError extends PermissionDeniedError {
+    /** The address ScrapeBadger saw (null when relayed, e.g. via the hosted MCP server) */
+    readonly clientIp: string | null;
+    constructor(message?: string, clientIp?: string | null);
+}
 /**
  * Raised when rate limit is exceeded.
  */
@@ -3152,4 +3175,4 @@ declare class TwitterClient {
     removeWebhookFromMonitor(webhookId: string, body?: unknown, params?: Record<string, string | number | boolean | undefined>): Promise<Record<string, unknown>>;
 }
 
-export { type Article as $, AuthenticationError as A, BaseClient as B, ConflictError as C, type UserIds as D, type List as E, type CommunityBanner as F, GeoClient as G, type Hashtag as H, InsufficientCreditsError as I, type CommunityRule as J, type Community as K, ListsClient as L, type Media as M, NotFoundError as N, type CommunityMember as O, type PaginatedResponse as P, type QueryType as Q, type ResolvedConfig as R, type ScrapeBadgerConfig as S, TwitterClient as T, UsersClient as U, ValidationError as V, WebSocketStreamError as W, type Trend as X, type Location as Y, type PlaceTrends as Z, type Place as _, ScrapeBadgerError as a, type CommunityNote as a0, type Space as a1, type Broadcast as a2, type ApiResponse as a3, type ListResponse as a4, type MonitorStatus as a5, type StreamMonitor as a6, type StreamMonitorList as a7, type CreateMonitorParams as a8, type UpdateMonitorParams as a9, type StreamTweet as aa, type ConnectedEvent as ab, type PingEvent as ac, type TweetEvent as ad, type ErrorEvent as ae, type StreamEvent as af, type StreamEventType as ag, type DeliveryLog as ah, type DeliveryLogList as ai, type BillingLog as aj, type BillingLogList as ak, type ConnectOptions as al, type FilterRuleStatus as am, type FilterRuleResponse as an, type FilterRuleCreate as ao, type FilterRuleUpdate as ap, type FilterRulePricingTier as aq, type FilterRuleListResponse as ar, type FilterRuleValidateResponse as as, type FilterRuleDeliveryLog as at, type FilterRuleDeliveryLogListResponse as au, type FilterRulePricingTiersResponse as av, RateLimitError as b, ServerError as c, TimeoutError as d, AccountRestrictedError as e, type PaginationOptions as f, type IteratorOptions as g, collectAll as h, TweetsClient as i, CommunitiesClient as j, TrendsClient as k, type GeoSearchOptions as l, StreamClient as m, type StreamEmitter as n, SpacesClient as o, type TrendCategory as p, type CommunityTweetType as q, type PollOption as r, type Poll as s, type Url as t, type UserMention as u, verifyWebhookSignature as v, type TweetPlace as w, type Tweet as x, type User as y, type UserAbout as z };
+export { type PlaceTrends as $, AuthenticationError as A, BaseClient as B, ConflictError as C, type User as D, type UserAbout as E, type UserIds as F, GeoClient as G, type Hashtag as H, InsufficientCreditsError as I, type List as J, type CommunityBanner as K, ListsClient as L, type Media as M, NotFoundError as N, type CommunityRule as O, PermissionDeniedError as P, type QueryType as Q, type ResolvedConfig as R, type ScrapeBadgerConfig as S, TwitterClient as T, UsersClient as U, ValidationError as V, WebSocketStreamError as W, type Community as X, type CommunityMember as Y, type Trend as Z, type Location as _, ScrapeBadgerError as a, type Place as a0, type Article as a1, type CommunityNote as a2, type Space as a3, type Broadcast as a4, type ApiResponse as a5, type ListResponse as a6, type MonitorStatus as a7, type StreamMonitor as a8, type StreamMonitorList as a9, type CreateMonitorParams as aa, type UpdateMonitorParams as ab, type StreamTweet as ac, type ConnectedEvent as ad, type PingEvent as ae, type TweetEvent as af, type ErrorEvent as ag, type StreamEvent as ah, type StreamEventType as ai, type DeliveryLog as aj, type DeliveryLogList as ak, type BillingLog as al, type BillingLogList as am, type ConnectOptions as an, type FilterRuleStatus as ao, type FilterRuleResponse as ap, type FilterRuleCreate as aq, type FilterRuleUpdate as ar, type FilterRulePricingTier as as, type FilterRuleListResponse as at, type FilterRuleValidateResponse as au, type FilterRuleDeliveryLog as av, type FilterRuleDeliveryLogListResponse as aw, type FilterRulePricingTiersResponse as ax, RateLimitError as b, ServerError as c, TimeoutError as d, AccountRestrictedError as e, IPNotAllowedError as f, type PaginatedResponse as g, type PaginationOptions as h, type IteratorOptions as i, collectAll as j, TweetsClient as k, CommunitiesClient as l, TrendsClient as m, type GeoSearchOptions as n, StreamClient as o, type StreamEmitter as p, SpacesClient as q, type TrendCategory as r, type CommunityTweetType as s, type PollOption as t, type Poll as u, verifyWebhookSignature as v, type Url as w, type UserMention as x, type TweetPlace as y, type Tweet as z };

package/dist/{index-Dz6kHfFt.d.ts → index-DBk60c2e.d.ts}

@@ -2084,6 +2084,29 @@ declare class ScrapeBadgerError extends Error {
 declare class AuthenticationError extends ScrapeBadgerError {
     constructor(message?: string);
 }
+/**
+ * Raised when the API key is not permitted to call this API (HTTP 403,
+ * `error: "insufficient_scope"`). Keys can be restricted to specific APIs in
+ * the dashboard; a refused call is not charged.
+ *
+ * Extends `AuthenticationError`, which is what a 403 threw before 0.52.0.
+ */
+declare class PermissionDeniedError extends AuthenticationError {
+    /** The API the request needed, e.g. `"twitter"` */
+    readonly requiredScope: string | undefined;
+    /** The APIs this key may call */
+    readonly allowedScopes: string[];
+    constructor(message?: string, requiredScope?: string, allowedScopes?: string[]);
+}
+/**
+ * Raised when the API key is restricted to IP addresses and this request came
+ * from another one (HTTP 403, `error: "ip_not_allowed"`). Not charged.
+ */
+declare class IPNotAllowedError extends PermissionDeniedError {
+    /** The address ScrapeBadger saw (null when relayed, e.g. via the hosted MCP server) */
+    readonly clientIp: string | null;
+    constructor(message?: string, clientIp?: string | null);
+}
 /**
  * Raised when rate limit is exceeded.
  */
@@ -3152,4 +3175,4 @@ declare class TwitterClient {
     removeWebhookFromMonitor(webhookId: string, body?: unknown, params?: Record<string, string | number | boolean | undefined>): Promise<Record<string, unknown>>;
 }
 
-export { type Article as $, AuthenticationError as A, BaseClient as B, ConflictError as C, type UserIds as D, type List as E, type CommunityBanner as F, GeoClient as G, type Hashtag as H, InsufficientCreditsError as I, type CommunityRule as J, type Community as K, ListsClient as L, type Media as M, NotFoundError as N, type CommunityMember as O, type PaginatedResponse as P, type QueryType as Q, type ResolvedConfig as R, type ScrapeBadgerConfig as S, TwitterClient as T, UsersClient as U, ValidationError as V, WebSocketStreamError as W, type Trend as X, type Location as Y, type PlaceTrends as Z, type Place as _, ScrapeBadgerError as a, type CommunityNote as a0, type Space as a1, type Broadcast as a2, type ApiResponse as a3, type ListResponse as a4, type MonitorStatus as a5, type StreamMonitor as a6, type StreamMonitorList as a7, type CreateMonitorParams as a8, type UpdateMonitorParams as a9, type StreamTweet as aa, type ConnectedEvent as ab, type PingEvent as ac, type TweetEvent as ad, type ErrorEvent as ae, type StreamEvent as af, type StreamEventType as ag, type DeliveryLog as ah, type DeliveryLogList as ai, type BillingLog as aj, type BillingLogList as ak, type ConnectOptions as al, type FilterRuleStatus as am, type FilterRuleResponse as an, type FilterRuleCreate as ao, type FilterRuleUpdate as ap, type FilterRulePricingTier as aq, type FilterRuleListResponse as ar, type FilterRuleValidateResponse as as, type FilterRuleDeliveryLog as at, type FilterRuleDeliveryLogListResponse as au, type FilterRulePricingTiersResponse as av, RateLimitError as b, ServerError as c, TimeoutError as d, AccountRestrictedError as e, type PaginationOptions as f, type IteratorOptions as g, collectAll as h, TweetsClient as i, CommunitiesClient as j, TrendsClient as k, type GeoSearchOptions as l, StreamClient as m, type StreamEmitter as n, SpacesClient as o, type TrendCategory as p, type CommunityTweetType as q, type PollOption as r, type Poll as s, type Url as t, type UserMention as u, verifyWebhookSignature as v, type TweetPlace as w, type Tweet as x, type User as y, type UserAbout as z };
+export { type PlaceTrends as $, AuthenticationError as A, BaseClient as B, ConflictError as C, type User as D, type UserAbout as E, type UserIds as F, GeoClient as G, type Hashtag as H, InsufficientCreditsError as I, type List as J, type CommunityBanner as K, ListsClient as L, type Media as M, NotFoundError as N, type CommunityRule as O, PermissionDeniedError as P, type QueryType as Q, type ResolvedConfig as R, type ScrapeBadgerConfig as S, TwitterClient as T, UsersClient as U, ValidationError as V, WebSocketStreamError as W, type Community as X, type CommunityMember as Y, type Trend as Z, type Location as _, ScrapeBadgerError as a, type Place as a0, type Article as a1, type CommunityNote as a2, type Space as a3, type Broadcast as a4, type ApiResponse as a5, type ListResponse as a6, type MonitorStatus as a7, type StreamMonitor as a8, type StreamMonitorList as a9, type CreateMonitorParams as aa, type UpdateMonitorParams as ab, type StreamTweet as ac, type ConnectedEvent as ad, type PingEvent as ae, type TweetEvent as af, type ErrorEvent as ag, type StreamEvent as ah, type StreamEventType as ai, type DeliveryLog as aj, type DeliveryLogList as ak, type BillingLog as al, type BillingLogList as am, type ConnectOptions as an, type FilterRuleStatus as ao, type FilterRuleResponse as ap, type FilterRuleCreate as aq, type FilterRuleUpdate as ar, type FilterRulePricingTier as as, type FilterRuleListResponse as at, type FilterRuleValidateResponse as au, type FilterRuleDeliveryLog as av, type FilterRuleDeliveryLogListResponse as aw, type FilterRulePricingTiersResponse as ax, RateLimitError as b, ServerError as c, TimeoutError as d, AccountRestrictedError as e, IPNotAllowedError as f, type PaginatedResponse as g, type PaginationOptions as h, type IteratorOptions as i, collectAll as j, TweetsClient as k, CommunitiesClient as l, TrendsClient as m, type GeoSearchOptions as n, StreamClient as o, type StreamEmitter as p, SpacesClient as q, type TrendCategory as r, type CommunityTweetType as s, type PollOption as t, type Poll as u, verifyWebhookSignature as v, type Url as w, type UserMention as x, type TweetPlace as y, type Tweet as z };

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BaseClient, T as TwitterClient, S as ScrapeBadgerConfig } from './index-Dz6kHfFt.cjs';
-export { e as AccountRestrictedError, a3 as ApiResponse, $ as Article, A as AuthenticationError, aj as BillingLog, ak as BillingLogList, a2 as Broadcast, j as CommunitiesClient, K as Community, F as CommunityBanner, O as CommunityMember, a0 as CommunityNote, J as CommunityRule, q as CommunityTweetType, C as ConflictError, al as ConnectOptions, ab as ConnectedEvent, a8 as CreateMonitorParams, ah as DeliveryLog, ai as DeliveryLogList, ae as ErrorEvent, ao as FilterRuleCreate, at as FilterRuleDeliveryLog, au as FilterRuleDeliveryLogListResponse, ar as FilterRuleListResponse, aq as FilterRulePricingTier, av as FilterRulePricingTiersResponse, an as FilterRuleResponse, am as FilterRuleStatus, ap as FilterRuleUpdate, as as FilterRuleValidateResponse, G as GeoClient, l as GeoSearchOptions, H as Hashtag, I as InsufficientCreditsError, g as IteratorOptions, E as List, a4 as ListResponse, L as ListsClient, Y as Location, M as Media, a5 as MonitorStatus, N as NotFoundError, P as PaginatedResponse, f as PaginationOptions, ac as PingEvent, _ as Place, Z as PlaceTrends, s as Poll, r as PollOption, Q as QueryType, b as RateLimitError, R as ResolvedConfig, a as ScrapeBadgerError, c as ServerError, a1 as Space, o as SpacesClient, m as StreamClient, n as StreamEmitter, af as StreamEvent, ag as StreamEventType, a6 as StreamMonitor, a7 as StreamMonitorList, aa as StreamTweet, d as TimeoutError, X as Trend, p as TrendCategory, k as TrendsClient, x as Tweet, ad as TweetEvent, w as TweetPlace, i as TweetsClient, a9 as UpdateMonitorParams, t as Url, y as User, z as UserAbout, D as UserIds, u as UserMention, U as UsersClient, V as ValidationError, W as WebSocketStreamError, h as collectAll, v as verifyWebhookSignature } from './index-Dz6kHfFt.cjs';
+import { B as BaseClient, T as TwitterClient, S as ScrapeBadgerConfig } from './index-DBk60c2e.cjs';
+export { e as AccountRestrictedError, a5 as ApiResponse, a1 as Article, A as AuthenticationError, al as BillingLog, am as BillingLogList, a4 as Broadcast, l as CommunitiesClient, X as Community, K as CommunityBanner, Y as CommunityMember, a2 as CommunityNote, O as CommunityRule, s as CommunityTweetType, C as ConflictError, an as ConnectOptions, ad as ConnectedEvent, aa as CreateMonitorParams, aj as DeliveryLog, ak as DeliveryLogList, ag as ErrorEvent, aq as FilterRuleCreate, av as FilterRuleDeliveryLog, aw as FilterRuleDeliveryLogListResponse, at as FilterRuleListResponse, as as FilterRulePricingTier, ax as FilterRulePricingTiersResponse, ap as FilterRuleResponse, ao as FilterRuleStatus, ar as FilterRuleUpdate, au as FilterRuleValidateResponse, G as GeoClient, n as GeoSearchOptions, H as Hashtag, f as IPNotAllowedError, I as InsufficientCreditsError, i as IteratorOptions, J as List, a6 as ListResponse, L as ListsClient, _ as Location, M as Media, a7 as MonitorStatus, N as NotFoundError, g as PaginatedResponse, h as PaginationOptions, P as PermissionDeniedError, ae as PingEvent, a0 as Place, $ as PlaceTrends, u as Poll, t as PollOption, Q as QueryType, b as RateLimitError, R as ResolvedConfig, a as ScrapeBadgerError, c as ServerError, a3 as Space, q as SpacesClient, o as StreamClient, p as StreamEmitter, ah as StreamEvent, ai as StreamEventType, a8 as StreamMonitor, a9 as StreamMonitorList, ac as StreamTweet, d as TimeoutError, Z as Trend, r as TrendCategory, m as TrendsClient, z as Tweet, af as TweetEvent, y as TweetPlace, k as TweetsClient, ab as UpdateMonitorParams, w as Url, D as User, E as UserAbout, F as UserIds, x as UserMention, U as UsersClient, V as ValidationError, W as WebSocketStreamError, j as collectAll, v as verifyWebhookSignature } from './index-DBk60c2e.cjs';
 import 'node:events';
 
 /**
@@ -1498,11 +1498,25 @@ interface LensSearchParams {
     language?: string;
     gl?: string;
     hl?: string;
-    /** Bias towards shoppable product matches. */
+    /**
+     * Return only the tiles Google marked as buyable — those carrying a price
+     * chip and stock status — drawn from the same grid with no extra request.
+     * When the image has no shoppable matches the full grid is returned and
+     * `warnings` says so.
+     */
     product?: boolean;
-    /** Include the visual-matches carousel (default: true). */
+    /**
+     * Visual matches are the only surface this endpoint serves, so they are
+     * always returned. `false` is echoed in `warnings`. (default: true)
+     */
     visual_matches?: boolean;
-    /** Restrict to exact-match results only. */
+    /**
+     * Return just the pages hosting this image, each flagged `exact_match`,
+     * instead of the broad visual grid — what a copyright or provenance
+     * check needs. Google exposes this set for most images but not all (8 of 10
+     * in our sampling); when it is unavailable the full grid is
+     * returned and `warnings` says the filter was not applied.
+     */
     exact_matches?: boolean;
 }
 /**
@@ -1792,12 +1806,20 @@ declare class JobsClient {
  * parsed from. `related_searches` chips come alongside. Legacy
  * `results` alias retained for backwards compat.
  *
+ * Also carries a `warnings` array naming any parameter that could not be
+ * applied. `exact_matches: true` returns just the pages hosting the image,
+ * flagged `exact_match`, for most images; when Google does not expose that
+ * set the grid comes back and `warnings` says so. `product: true` narrows the same grid to the tiles Google marked
+ * buyable.
+ *
  * @example
  * ```typescript
  * const out = await client.google.lens.search({
  *   url: "https://example.com/photo.jpg",
- *   product: true, // bias towards shoppable matches
+ *   query: "wallpaper", // text refinement — honoured
  * });
+ * // GoogleResponse is Record<string, unknown>, so narrow before use.
+ * console.warn(out.warnings as string[] | undefined);
  * for (const match of out.lens_results) {
  *   console.log(match.title, match.price?.value, match.price?.currency);
  * }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BaseClient, T as TwitterClient, S as ScrapeBadgerConfig } from './index-Dz6kHfFt.js';
-export { e as AccountRestrictedError, a3 as ApiResponse, $ as Article, A as AuthenticationError, aj as BillingLog, ak as BillingLogList, a2 as Broadcast, j as CommunitiesClient, K as Community, F as CommunityBanner, O as CommunityMember, a0 as CommunityNote, J as CommunityRule, q as CommunityTweetType, C as ConflictError, al as ConnectOptions, ab as ConnectedEvent, a8 as CreateMonitorParams, ah as DeliveryLog, ai as DeliveryLogList, ae as ErrorEvent, ao as FilterRuleCreate, at as FilterRuleDeliveryLog, au as FilterRuleDeliveryLogListResponse, ar as FilterRuleListResponse, aq as FilterRulePricingTier, av as FilterRulePricingTiersResponse, an as FilterRuleResponse, am as FilterRuleStatus, ap as FilterRuleUpdate, as as FilterRuleValidateResponse, G as GeoClient, l as GeoSearchOptions, H as Hashtag, I as InsufficientCreditsError, g as IteratorOptions, E as List, a4 as ListResponse, L as ListsClient, Y as Location, M as Media, a5 as MonitorStatus, N as NotFoundError, P as PaginatedResponse, f as PaginationOptions, ac as PingEvent, _ as Place, Z as PlaceTrends, s as Poll, r as PollOption, Q as QueryType, b as RateLimitError, R as ResolvedConfig, a as ScrapeBadgerError, c as ServerError, a1 as Space, o as SpacesClient, m as StreamClient, n as StreamEmitter, af as StreamEvent, ag as StreamEventType, a6 as StreamMonitor, a7 as StreamMonitorList, aa as StreamTweet, d as TimeoutError, X as Trend, p as TrendCategory, k as TrendsClient, x as Tweet, ad as TweetEvent, w as TweetPlace, i as TweetsClient, a9 as UpdateMonitorParams, t as Url, y as User, z as UserAbout, D as UserIds, u as UserMention, U as UsersClient, V as ValidationError, W as WebSocketStreamError, h as collectAll, v as verifyWebhookSignature } from './index-Dz6kHfFt.js';
+import { B as BaseClient, T as TwitterClient, S as ScrapeBadgerConfig } from './index-DBk60c2e.js';
+export { e as AccountRestrictedError, a5 as ApiResponse, a1 as Article, A as AuthenticationError, al as BillingLog, am as BillingLogList, a4 as Broadcast, l as CommunitiesClient, X as Community, K as CommunityBanner, Y as CommunityMember, a2 as CommunityNote, O as CommunityRule, s as CommunityTweetType, C as ConflictError, an as ConnectOptions, ad as ConnectedEvent, aa as CreateMonitorParams, aj as DeliveryLog, ak as DeliveryLogList, ag as ErrorEvent, aq as FilterRuleCreate, av as FilterRuleDeliveryLog, aw as FilterRuleDeliveryLogListResponse, at as FilterRuleListResponse, as as FilterRulePricingTier, ax as FilterRulePricingTiersResponse, ap as FilterRuleResponse, ao as FilterRuleStatus, ar as FilterRuleUpdate, au as FilterRuleValidateResponse, G as GeoClient, n as GeoSearchOptions, H as Hashtag, f as IPNotAllowedError, I as InsufficientCreditsError, i as IteratorOptions, J as List, a6 as ListResponse, L as ListsClient, _ as Location, M as Media, a7 as MonitorStatus, N as NotFoundError, g as PaginatedResponse, h as PaginationOptions, P as PermissionDeniedError, ae as PingEvent, a0 as Place, $ as PlaceTrends, u as Poll, t as PollOption, Q as QueryType, b as RateLimitError, R as ResolvedConfig, a as ScrapeBadgerError, c as ServerError, a3 as Space, q as SpacesClient, o as StreamClient, p as StreamEmitter, ah as StreamEvent, ai as StreamEventType, a8 as StreamMonitor, a9 as StreamMonitorList, ac as StreamTweet, d as TimeoutError, Z as Trend, r as TrendCategory, m as TrendsClient, z as Tweet, af as TweetEvent, y as TweetPlace, k as TweetsClient, ab as UpdateMonitorParams, w as Url, D as User, E as UserAbout, F as UserIds, x as UserMention, U as UsersClient, V as ValidationError, W as WebSocketStreamError, j as collectAll, v as verifyWebhookSignature } from './index-DBk60c2e.js';
 import 'node:events';
 
 /**
@@ -1498,11 +1498,25 @@ interface LensSearchParams {
     language?: string;
     gl?: string;
     hl?: string;
-    /** Bias towards shoppable product matches. */
+    /**
+     * Return only the tiles Google marked as buyable — those carrying a price
+     * chip and stock status — drawn from the same grid with no extra request.
+     * When the image has no shoppable matches the full grid is returned and
+     * `warnings` says so.
+     */
     product?: boolean;
-    /** Include the visual-matches carousel (default: true). */
+    /**
+     * Visual matches are the only surface this endpoint serves, so they are
+     * always returned. `false` is echoed in `warnings`. (default: true)
+     */
     visual_matches?: boolean;
-    /** Restrict to exact-match results only. */
+    /**
+     * Return just the pages hosting this image, each flagged `exact_match`,
+     * instead of the broad visual grid — what a copyright or provenance
+     * check needs. Google exposes this set for most images but not all (8 of 10
+     * in our sampling); when it is unavailable the full grid is
+     * returned and `warnings` says the filter was not applied.
+     */
     exact_matches?: boolean;
 }
 /**
@@ -1792,12 +1806,20 @@ declare class JobsClient {
  * parsed from. `related_searches` chips come alongside. Legacy
  * `results` alias retained for backwards compat.
  *
+ * Also carries a `warnings` array naming any parameter that could not be
+ * applied. `exact_matches: true` returns just the pages hosting the image,
+ * flagged `exact_match`, for most images; when Google does not expose that
+ * set the grid comes back and `warnings` says so. `product: true` narrows the same grid to the tiles Google marked
+ * buyable.
+ *
  * @example
  * ```typescript
  * const out = await client.google.lens.search({
  *   url: "https://example.com/photo.jpg",
- *   product: true, // bias towards shoppable matches
+ *   query: "wallpaper", // text refinement — honoured
  * });
+ * // GoogleResponse is Record<string, unknown>, so narrow before use.
+ * console.warn(out.warnings as string[] | undefined);
  * for (const match of out.lens_results) {
  *   console.log(match.title, match.price?.value, match.price?.currency);
  * }

package/dist/index.js

@@ -26,6 +26,29 @@ var AuthenticationError = class _AuthenticationError extends ScrapeBadgerError {
     Object.setPrototypeOf(this, _AuthenticationError.prototype);
   }
 };
+var PermissionDeniedError = class _PermissionDeniedError extends AuthenticationError {
+  /** The API the request needed, e.g. `"twitter"` */
+  requiredScope;
+  /** The APIs this key may call */
+  allowedScopes;
+  constructor(message = "This API key is not permitted to call this API.", requiredScope, allowedScopes = []) {
+    super(message);
+    this.name = "PermissionDeniedError";
+    this.requiredScope = requiredScope;
+    this.allowedScopes = allowedScopes;
+    Object.setPrototypeOf(this, _PermissionDeniedError.prototype);
+  }
+};
+var IPNotAllowedError = class _IPNotAllowedError extends PermissionDeniedError {
+  /** The address ScrapeBadger saw (null when relayed, e.g. via the hosted MCP server) */
+  clientIp;
+  constructor(message = "This API key may not be used from this IP address.", clientIp = null) {
+    super(message);
+    this.name = "IPNotAllowedError";
+    this.clientIp = clientIp;
+    Object.setPrototypeOf(this, _IPNotAllowedError.prototype);
+  }
+};
 var RateLimitError = class _RateLimitError extends ScrapeBadgerError {
   /** Unix timestamp when the rate limit resets */
   retryAfter;
@@ -341,6 +364,16 @@ var BaseClient = class _BaseClient {
       case 402:
         throw new InsufficientCreditsError(message, errorData.credits_balance);
       case 403:
+        if (errorData.error === "ip_not_allowed") {
+          throw new IPNotAllowedError(message, errorData.client_ip ?? null);
+        }
+        if (errorData.error === "insufficient_scope") {
+          throw new PermissionDeniedError(
+            message,
+            errorData.required_scope,
+            errorData.allowed_scopes ?? []
+          );
+        }
         if (message.toLowerCase().includes("restricted")) {
           throw new AccountRestrictedError(message, errorData.reason);
         }
@@ -9097,6 +9130,7 @@ exports.GoogleShoppingClient = ShoppingClient;
 exports.GoogleShortsClient = ShortsClient;
 exports.GoogleTrendsClient = TrendsClient2;
 exports.GoogleVideosClient = VideosClient;
+exports.IPNotAllowedError = IPNotAllowedError;
 exports.ImmobiliareClient = ImmobiliareClient;
 exports.InstagramAudioClient = AudioClient;
 exports.InstagramClient = InstagramClient;
@@ -9119,6 +9153,7 @@ exports.LoopNetListingsClient = ListingsClient2;
 exports.LoopNetReferenceClient = ReferenceClient15;
 exports.LoopNetSearchClient = SearchClient18;
 exports.NotFoundError = NotFoundError;
+exports.PermissionDeniedError = PermissionDeniedError;
 exports.RateLimitError = RateLimitError;
 exports.RealtorClient = RealtorClient;
 exports.RealtorPropertiesClient = PropertiesClient;