@firebase/ai 2.3.0-20250917161512 → 2.3.0-canary.0ffcb26af

package/dist/esm/src/types/googleai.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Tool, GenerationConfig, Citation, FinishReason, GroundingMetadata, PromptFeedback, SafetyRating, UsageMetadata } from '../public-types';
+import { Tool, GenerationConfig, Citation, FinishReason, GroundingMetadata, PromptFeedback, SafetyRating, UsageMetadata, URLContextMetadata } from '../public-types';
 import { Content, Part } from './content';
 /**
  * @internal
@@ -47,6 +47,7 @@ export interface GoogleAIGenerateContentCandidate {
     safetyRatings?: SafetyRating[];
     citationMetadata?: GoogleAICitationMetadata;
     groundingMetadata?: GroundingMetadata;
+    urlContextMetadata?: URLContextMetadata;
 }
 /**
  * @internal

package/dist/esm/src/types/requests.d.ts

@@ -218,7 +218,7 @@ export interface RequestOptions {
  * Defines a tool that model can call to access external knowledge.
  * @public
  */
-export type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool;
+export type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
 /**
  * Structured representation of a function declaration as defined by the
  * {@link https://spec.openapis.org/oas/v3.0.3 | OpenAPI 3.0 specification}.
@@ -291,6 +291,26 @@ export interface CodeExecutionTool {
  */
 export interface GoogleSearch {
 }
+/**
+ * A tool that allows you to provide additional context to the models in the form of public web
+ * URLs. By including URLs in your request, the Gemini model will access the content from those
+ * pages to inform and enhance its response.
+ *
+ * @beta
+ */
+export interface URLContextTool {
+    /**
+     * Specifies the URL Context configuration.
+     */
+    urlContext: URLContext;
+}
+/**
+ * Specifies the URL Context configuration.
+ *
+ * @beta
+ */
+export interface URLContext {
+}
 /**
  * A `FunctionDeclarationsTool` is a piece of code that enables the system to
  * interact with external systems to perform an action, or set of actions,

package/dist/esm/src/types/responses.d.ts

@@ -102,8 +102,16 @@ export interface UsageMetadata {
      */
     thoughtsTokenCount?: number;
     totalTokenCount: number;
+    /**
+     * The number of tokens used by tools.
+     */
+    toolUsePromptTokenCount?: number;
     promptTokensDetails?: ModalityTokenCount[];
     candidatesTokensDetails?: ModalityTokenCount[];
+    /**
+     * A list of tokens used by tools, broken down by modality.
+     */
+    toolUsePromptTokensDetails?: ModalityTokenCount[];
 }
 /**
  * Represents token counting info for a single modality.
@@ -143,6 +151,7 @@ export interface GenerateContentCandidate {
     safetyRatings?: SafetyRating[];
     citationMetadata?: CitationMetadata;
     groundingMetadata?: GroundingMetadata;
+    urlContextMetadata?: URLContextMetadata;
 }
 /**
  * Citation metadata that may be found on a {@link GenerateContentCandidate}.
@@ -323,6 +332,89 @@ export interface Segment {
      */
     text: string;
 }
+/**
+ * Metadata related to {@link URLContextTool}.
+ *
+ * @beta
+ */
+export interface URLContextMetadata {
+    /**
+     * List of URL metadata used to provide context to the Gemini model.
+     */
+    urlMetadata: URLMetadata[];
+}
+/**
+ * Metadata for a single URL retrieved by the {@link URLContextTool} tool.
+ *
+ * @beta
+ */
+export interface URLMetadata {
+    /**
+     * The retrieved URL.
+     */
+    retrievedUrl?: string;
+    /**
+     * The status of the URL retrieval.
+     */
+    urlRetrievalStatus?: URLRetrievalStatus;
+}
+/**
+ * The status of a URL retrieval.
+ *
+ * @remarks
+ * <b>URL_RETRIEVAL_STATUS_UNSPECIFIED:</b> Unspecified retrieval status.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_SUCCESS:</b> The URL retrieval was successful.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_ERROR:</b> The URL retrieval failed.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_UNSAFE:</b> The URL retrieval failed because the content is unsafe.
+ * <br/>
+ *
+ * @beta
+ */
+export declare const URLRetrievalStatus: {
+    /**
+     * Unspecified retrieval status.
+     */
+    URL_RETRIEVAL_STATUS_UNSPECIFIED: string;
+    /**
+     * The URL retrieval was successful.
+     */
+    URL_RETRIEVAL_STATUS_SUCCESS: string;
+    /**
+     * The URL retrieval failed.
+     */
+    URL_RETRIEVAL_STATUS_ERROR: string;
+    /**
+     * The URL retrieval failed because the content is behind a paywall.
+     */
+    URL_RETRIEVAL_STATUS_PAYWALL: string;
+    /**
+     * The URL retrieval failed because the content is unsafe.
+     */
+    URL_RETRIEVAL_STATUS_UNSAFE: string;
+};
+/**
+ * The status of a URL retrieval.
+ *
+ * @remarks
+ * <b>URL_RETRIEVAL_STATUS_UNSPECIFIED:</b> Unspecified retrieval status.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_SUCCESS:</b> The URL retrieval was successful.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_ERROR:</b> The URL retrieval failed.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_UNSAFE:</b> The URL retrieval failed because the content is unsafe.
+ * <br/>
+ *
+ * @beta
+ */
+export type URLRetrievalStatus = (typeof URLRetrievalStatus)[keyof typeof URLRetrievalStatus];
 /**
  * @public
  */

package/dist/index.cjs.js

@@ -8,7 +8,7 @@ var util = require('@firebase/util');
 var logger$1 = require('@firebase/logger');
 
 var name = "@firebase/ai";
-var version = "2.3.0-20250917161512";
+var version = "2.3.0-canary.0ffcb26af";
 
 /**
  * @license
@@ -420,6 +420,45 @@ const Language = {
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * The status of a URL retrieval.
+ *
+ * @remarks
+ * <b>URL_RETRIEVAL_STATUS_UNSPECIFIED:</b> Unspecified retrieval status.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_SUCCESS:</b> The URL retrieval was successful.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_ERROR:</b> The URL retrieval failed.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_UNSAFE:</b> The URL retrieval failed because the content is unsafe.
+ * <br/>
+ *
+ * @beta
+ */
+const URLRetrievalStatus = {
+    /**
+     * Unspecified retrieval status.
+     */
+    URL_RETRIEVAL_STATUS_UNSPECIFIED: 'URL_RETRIEVAL_STATUS_UNSPECIFIED',
+    /**
+     * The URL retrieval was successful.
+     */
+    URL_RETRIEVAL_STATUS_SUCCESS: 'URL_RETRIEVAL_STATUS_SUCCESS',
+    /**
+     * The URL retrieval failed.
+     */
+    URL_RETRIEVAL_STATUS_ERROR: 'URL_RETRIEVAL_STATUS_ERROR',
+    /**
+     * The URL retrieval failed because the content is behind a paywall.
+     */
+    URL_RETRIEVAL_STATUS_PAYWALL: 'URL_RETRIEVAL_STATUS_PAYWALL',
+    /**
+     * The URL retrieval failed because the content is unsafe.
+     */
+    URL_RETRIEVAL_STATUS_UNSAFE: 'URL_RETRIEVAL_STATUS_UNSAFE'
+};
 /**
  * The types of responses that can be returned by {@link LiveSession.receive}.
  *
@@ -1890,7 +1929,8 @@ function mapGenerateContentCandidates(candidates) {
                 finishMessage: candidate.finishMessage,
                 safetyRatings: mappedSafetyRatings,
                 citationMetadata,
-                groundingMetadata: candidate.groundingMetadata
+                groundingMetadata: candidate.groundingMetadata,
+                urlContextMetadata: candidate.urlContextMetadata
             };
             mappedCandidates.push(mappedCandidate);
         });
@@ -2060,6 +2100,17 @@ function aggregateResponses(responses) {
                     candidate.safetyRatings;
                 aggregatedResponse.candidates[i].groundingMetadata =
                     candidate.groundingMetadata;
+                // The urlContextMetadata object is defined in the first chunk of the response stream.
+                // In all subsequent chunks, the urlContextMetadata object will be undefined. We need to
+                // make sure that we don't overwrite the first value urlContextMetadata object with undefined.
+                // FIXME: What happens if we receive a second, valid urlContextMetadata object?
+                const urlContextMetadata = candidate.urlContextMetadata;
+                if (typeof urlContextMetadata === 'object' &&
+                    urlContextMetadata !== null &&
+                    Object.keys(urlContextMetadata).length > 0) {
+                    aggregatedResponse.candidates[i].urlContextMetadata =
+                        urlContextMetadata;
+                }
                 /**
                  * Candidates should always have content and parts, but this handles
                  * possible malformed responses.
@@ -4078,6 +4129,7 @@ exports.ResponseModality = ResponseModality;
 exports.Schema = Schema;
 exports.SchemaType = SchemaType;
 exports.StringSchema = StringSchema;
+exports.URLRetrievalStatus = URLRetrievalStatus;
 exports.VertexAIBackend = VertexAIBackend;
 exports.getAI = getAI;
 exports.getGenerativeModel = getGenerativeModel;