@microsoft/webiq 0.1.8 → 1.0.0

package/dist/index.mjs

@@ -330,9 +330,31 @@ var APIStatusError = class _APIStatusError extends WebIQError {
     this.name = "APIStatusError";
     this.statusCode = statusCode;
     this.body = options?.body;
-    this.requestId = options?.requestId;
-    this.traceId = options?.traceId;
     Object.setPrototypeOf(this, _APIStatusError.prototype);
+    this.requestId = options?.requestId ?? this.stringField("requestId");
+    this.traceId = options?.traceId ?? this.stringField("traceId");
+  }
+  stringField(name) {
+    if (this.body && typeof this.body === "object" && name in this.body) {
+      const value = this.body[name];
+      return typeof value === "string" ? value : void 0;
+    }
+    return void 0;
+  }
+  get errorCode() {
+    return this.stringField("errorCode");
+  }
+  get errorCategory() {
+    return this.stringField("errorCategory");
+  }
+  get userMessage() {
+    return this.stringField("userMessage");
+  }
+  get technicalDetails() {
+    return this.stringField("technicalDetails");
+  }
+  get retryAfter() {
+    return this.stringField("retryAfter");
   }
 };
 var RateLimitError = class _RateLimitError extends APIStatusError {
@@ -349,6 +371,20 @@ var RateLimitError = class _RateLimitError extends APIStatusError {
     return void 0;
   }
 };
+var BadRequestError = class _BadRequestError extends APIStatusError {
+  constructor(statusCode, message, options) {
+    super(statusCode, message, options);
+    this.name = "BadRequestError";
+    Object.setPrototypeOf(this, _BadRequestError.prototype);
+  }
+};
+var NotFoundError = class _NotFoundError extends APIStatusError {
+  constructor(statusCode, message, options) {
+    super(statusCode, message, options);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
+  }
+};
 var AuthenticationError = class _AuthenticationError extends APIStatusError {
   constructor(statusCode, message, options) {
     super(statusCode, message, options);
@@ -396,7 +432,7 @@ var RetryPolicy = class {
     this.maxRetries = options?.maxRetries ?? 2;
     this.baseDelaySeconds = options?.baseDelaySeconds ?? 0.25;
     this.maxDelaySeconds = options?.maxDelaySeconds ?? 4;
-    this.retryOnStatus = new Set(options?.retryOnStatus ?? [408, 500, 502, 503, 504]);
+    this.retryOnStatus = new Set(options?.retryOnStatus ?? [408, 500, 502, 520, 523, 524]);
   }
   /**
    * Compute the delay before the next retry attempt.
@@ -407,7 +443,7 @@ var RetryPolicy = class {
    */
   computeDelay(attempt, retryAfter) {
     if (retryAfter !== void 0) {
-      return Math.min(retryAfter, this.maxDelaySeconds);
+      return retryAfter;
     }
     const delay = Math.random() * this.baseDelaySeconds * Math.pow(2, attempt - 1);
     return Math.min(delay, this.maxDelaySeconds);
@@ -419,8 +455,24 @@ var RetryPolicy = class {
     return this.retryOnStatus.has(statusCode);
   }
 };
-function sleep(seconds) {
-  return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+async function sleep(seconds, signal) {
+  let remainingMs = seconds * 1e3;
+  do {
+    signal?.throwIfAborted();
+    const delayMs = Math.min(remainingMs, 2147483647);
+    await new Promise((resolve, reject) => {
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason ?? new DOMException("Request aborted", "AbortError"));
+      };
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, delayMs);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+    remainingMs -= delayMs;
+  } while (remainingMs > 0);
 }
 
 // src/telemetry.ts
@@ -465,15 +517,18 @@ function extractMetadata(body, headers) {
 }
 var HttpTransport = class {
   baseUrl;
+  appId;
   auth;
   telemetry;
   retry;
   timeout;
   fetchFn;
   activeControllers = /* @__PURE__ */ new Set();
+  closeController = new AbortController();
   closed = false;
   constructor(options) {
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.appId = options.appId;
     this.auth = options.auth;
     this.telemetry = options.telemetryHook;
     this.retry = options.retry ?? new RetryPolicy();
@@ -482,7 +537,19 @@ var HttpTransport = class {
   }
   async request(options) {
     const { method, path, json, signal: callerSignal } = options;
+    const retrySignal = callerSignal ? AbortSignal.any([callerSignal, this.closeController.signal]) : this.closeController.signal;
     const effectiveTimeout = options.timeout ?? this.timeout;
+    let url = `${this.baseUrl}${path}`;
+    if (this.appId) {
+      const fragmentIndex = url.indexOf("#");
+      const fragment = fragmentIndex < 0 ? "" : url.slice(fragmentIndex);
+      const target = fragmentIndex < 0 ? url : url.slice(0, fragmentIndex);
+      const queryIndex = target.indexOf("?");
+      const pathname = queryIndex < 0 ? target : target.slice(0, queryIndex);
+      const params = new URLSearchParams(queryIndex < 0 ? "" : target.slice(queryIndex + 1));
+      params.set("appid", this.appId);
+      url = `${pathname}?${params.toString()}${fragment}`;
+    }
     let attempt = 0;
     while (true) {
       if (this.closed) {
@@ -501,7 +568,7 @@ var HttpTransport = class {
         const fetchSignal = callerSignal ? AbortSignal.any([callerSignal, abortController.signal]) : abortController.signal;
         let response;
         try {
-          response = await this.fetchFn(`${this.baseUrl}${path}`, {
+          response = await this.fetchFn(url, {
             method,
             headers: {
               "Content-Type": "application/json",
@@ -536,11 +603,13 @@ var HttpTransport = class {
             traceId,
             retryAfter,
             elapsedMs: elapsed,
+            responseSizeBytes: responseText ? new TextEncoder().encode(responseText).length : 0,
             errorBody: response.status >= 400 ? body : void 0
           })
         );
         if (response.status === 401) {
-          throw new AuthenticationError(response.status, "Unauthorized", {
+          const message = body && typeof body === "object" && "userMessage" in body ? String(body.userMessage) : "Unauthorized";
+          throw new AuthenticationError(response.status, message, {
             body,
             requestId,
             traceId
@@ -561,9 +630,17 @@ var HttpTransport = class {
         }
         if (this.retry.shouldRetry(response.status) && attempt <= this.retry.maxRetries) {
           const delay = this.retry.computeDelay(attempt, parseRetryAfter(retryAfter));
-          await sleep(delay);
+          await sleep(delay, retrySignal);
           continue;
         }
+        if (response.status === 400) {
+          const message = body && typeof body === "object" && "userMessage" in body ? String(body.userMessage) : "Bad request";
+          throw new BadRequestError(response.status, message, { body, requestId, traceId });
+        }
+        if (response.status === 404) {
+          const message = body && typeof body === "object" && "userMessage" in body ? String(body.userMessage) : "Not found";
+          throw new NotFoundError(response.status, message, { body, requestId, traceId });
+        }
         if (response.status >= 400) {
           const message = body && typeof body === "object" && "userMessage" in body ? String(body.userMessage) : `HTTP ${response.status}`;
           throw new APIStatusError(response.status, message, { body, requestId, traceId });
@@ -593,7 +670,7 @@ var HttpTransport = class {
           });
         }
         if (attempt <= this.retry.maxRetries) {
-          await sleep(this.retry.computeDelay(attempt));
+          await sleep(this.retry.computeDelay(attempt), retrySignal);
           continue;
         }
         throw new APIConnectionError(
@@ -605,13 +682,293 @@ var HttpTransport = class {
   }
   async close() {
     this.closed = true;
+    this.closeController.abort(new APIConnectionError("Transport is closed"));
     Array.from(this.activeControllers).forEach((controller) => controller.abort());
     this.activeControllers.clear();
   }
 };
 
+// src/feedback.ts
+var FeedbackError = class extends Error {
+  constructor(code, message, statusCode) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.name = new.target.name;
+  }
+  code;
+  statusCode;
+};
+var InvalidFeedbackInputError = class extends FeedbackError {
+  constructor(message = "Invalid feedback input.", code = "invalid_feedback_input") {
+    super(code, message);
+  }
+};
+var MissingInstrumentationError = class extends FeedbackError {
+  constructor() {
+    super("missing_citation_base", "Citation instrumentation is unavailable.");
+  }
+};
+var InvalidInstrumentationSuffixError = class extends FeedbackError {
+  constructor(code = "malformed_instrumentation_suffix") {
+    super(code, "Every cited result requires a valid instrumentation suffix.");
+  }
+};
+var FeedbackConnectionError = class extends FeedbackError {
+  constructor() {
+    super("feedback_connection", "Feedback request failed.");
+  }
+};
+var FeedbackTimeoutError = class extends FeedbackError {
+  constructor() {
+    super("feedback_timeout", "Feedback request timed out.");
+  }
+};
+var FeedbackCancelledError = class extends FeedbackError {
+  constructor() {
+    super("feedback_cancelled", "Feedback request was cancelled.");
+  }
+};
+var FeedbackHttpError = class extends FeedbackError {
+  constructor(statusCode) {
+    super("feedback_http", "Feedback endpoint returned an unsuccessful response.", statusCode);
+  }
+};
+var FeedbackNavigationError = class extends FeedbackError {
+  constructor() {
+    super("feedback_navigation", "Feedback navigation failed.");
+  }
+};
+function isPresent(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function buildClickPingUrl(response, result) {
+  if (isPresent(result.clickUrl) || !isPresent(response.instrumentationClickBase) || !isPresent(result.instrumentationSuffix)) {
+    return null;
+  }
+  return response.instrumentationClickBase + result.instrumentationSuffix;
+}
+function prepareClick(response, result) {
+  if (isPresent(result.clickUrl)) {
+    return { kind: "redirect", navigationUrl: result.clickUrl, pingUrl: null };
+  }
+  if (!isPresent(result.url)) {
+    throw new InvalidFeedbackInputError(
+      "A non-empty url or clickUrl is required to prepare a click.",
+      "missing_navigation_url"
+    );
+  }
+  const pingUrl = buildClickPingUrl(response, result);
+  return {
+    kind: pingUrl === null ? "untracked" : "ping",
+    navigationUrl: result.url,
+    pingUrl
+  };
+}
+function buildCitationPingUrl(response, results) {
+  const base = response.instrumentationCitationBase;
+  if (!isPresent(base)) {
+    throw new MissingInstrumentationError();
+  }
+  if (results.length === 0) {
+    throw new InvalidFeedbackInputError(
+      "At least one cited result is required.",
+      "empty_citation_results"
+    );
+  }
+  const payload = results.map((result) => {
+    const suffix = result.instrumentationSuffix;
+    if (!isPresent(suffix)) {
+      throw new InvalidInstrumentationSuffixError("missing_instrumentation_suffix");
+    }
+    const comma = suffix.indexOf(",");
+    const appNamespace = comma < 0 ? "" : suffix.slice(0, comma);
+    const key = comma < 0 ? "" : suffix.slice(comma + 1);
+    if (!isPresent(appNamespace) || !isPresent(key)) {
+      throw new InvalidInstrumentationSuffixError();
+    }
+    return { T: "CI.Info", FID: "LLM", Name: "citation", AppNS: appNamespace, K: key };
+  });
+  return base + encodeURIComponent(JSON.stringify(payload)).replace(
+    /[!'()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
+
+// src/feedback-client.ts
+var MAX_FEEDBACK_TIMEOUT = 2147483647;
+var DefaultFeedbackSender = class {
+  async send(url, options) {
+    const init = {
+      method: "GET",
+      credentials: "omit",
+      redirect: "error",
+      referrerPolicy: "no-referrer",
+      cache: "no-store",
+      signal: options?.signal
+    };
+    const response = await globalThis.fetch(url, init);
+    await response.body?.cancel();
+    return { status: response.status };
+  }
+};
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateFields(value, fields) {
+  if (!record(value) || fields.some((key) => value[key] != null && typeof value[key] !== "string")) {
+    throw new InvalidFeedbackInputError();
+  }
+}
+function validate(options) {
+  if (!record(options)) throw new InvalidFeedbackInputError();
+  validateFields(options.response, ["instrumentationClickBase", "instrumentationCitationBase"]);
+  if (!["citation", "click"].includes(options.type) || !Array.isArray(options.events) || options.events.length === 0 || options.type === "click" && options.events.length !== 1 || options.navigation !== void 0 && !["auto", "manual"].includes(options.navigation) || options.navigationPolicy !== void 0 && !["always", "on-feedback-success"].includes(options.navigationPolicy) || options.failureMode !== void 0 && !["collect", "throw"].includes(options.failureMode) || options.signal !== void 0 && (!record(options.signal) || typeof options.signal.aborted !== "boolean" || typeof options.signal.addEventListener !== "function" || typeof options.signal.removeEventListener !== "function") || options.timeout !== void 0 && (!Number.isFinite(options.timeout) || options.timeout <= 0 || options.timeout > MAX_FEEDBACK_TIMEOUT)) {
+    throw new InvalidFeedbackInputError();
+  }
+  for (const event of options.events) {
+    if (!record(event) || "type" in event) throw new InvalidFeedbackInputError();
+    if (options.type === "citation") {
+      if ("result" in event || !Array.isArray(event.results) || event.results.length === 0) {
+        throw new InvalidFeedbackInputError();
+      }
+      for (const result of event.results) {
+        validateFields(result, ["url", "clickUrl", "instrumentationSuffix"]);
+      }
+    } else {
+      if ("results" in event) throw new InvalidFeedbackInputError();
+      validateFields(event.result, ["url", "clickUrl", "instrumentationSuffix"]);
+    }
+  }
+}
+function validateHttpUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new InvalidFeedbackInputError("Feedback requires an absolute HTTP(S) URL.");
+  }
+  if (!["https:", "http:"].includes(parsed.protocol) || parsed.username || parsed.password) {
+    throw new InvalidFeedbackInputError(
+      "Feedback requires an absolute HTTP(S) URL without credentials."
+    );
+  }
+}
+function browserNavigation() {
+  const runtime = globalThis;
+  const location = record(runtime) ? runtime.location : void 0;
+  if (record(location) && typeof location.assign === "function") {
+    const assign = location.assign.bind(location);
+    return {
+      navigate: (url) => {
+        assign(url);
+      }
+    };
+  }
+  return void 0;
+}
+var FeedbackClient = class {
+  sender;
+  navigator;
+  constructor(options = {}) {
+    this.sender = options.sender ?? new DefaultFeedbackSender();
+    this.navigator = options.navigationHandler ?? browserNavigation();
+  }
+  async pushEvents(options) {
+    validate(options);
+    let outcome;
+    let requestUrl;
+    if (options.type === "citation") {
+      const results = options.events.flatMap((event) => [...event.results]);
+      requestUrl = buildCitationPingUrl(options.response, results);
+      outcome = {
+        type: "citation",
+        feedbackStatus: "submitted",
+        navigationStatus: "not-applicable",
+        resultCount: results.length
+      };
+    } else {
+      const prepared = prepareClick(options.response, options.events[0].result);
+      validateHttpUrl(prepared.navigationUrl);
+      requestUrl = prepared.pingUrl ?? void 0;
+      outcome = {
+        type: "click",
+        clickMode: prepared.kind,
+        feedbackStatus: prepared.kind === "redirect" ? "pending-navigation" : prepared.kind === "ping" ? "submitted" : "not-instrumented",
+        navigationStatus: "required",
+        navigationUrl: prepared.navigationUrl
+      };
+    }
+    if (requestUrl !== void 0) validateHttpUrl(requestUrl);
+    if (options.signal?.aborted) throw new FeedbackCancelledError();
+    if (requestUrl !== void 0) {
+      try {
+        await this.send(requestUrl, options);
+      } catch (error) {
+        outcome.feedbackStatus = "failed";
+        outcome.feedbackError = error instanceof FeedbackError ? error : new FeedbackConnectionError();
+      }
+    }
+    if (outcome.type === "click") {
+      if (outcome.feedbackError && options.navigationPolicy === "on-feedback-success") {
+        outcome.navigationStatus = "blocked";
+      } else if (options.navigation !== "manual" && this.navigator) {
+        try {
+          await this.navigator.navigate(outcome.navigationUrl);
+          outcome.navigationStatus = "navigated";
+          if (outcome.clickMode === "redirect") outcome.feedbackStatus = "dispatched";
+        } catch {
+          outcome.navigationStatus = "failed";
+          outcome.navigationError = new FeedbackNavigationError();
+        }
+      }
+    }
+    if (options.failureMode === "throw") {
+      const error = outcome.feedbackError ?? (outcome.type === "click" ? outcome.navigationError : void 0);
+      if (error) throw error;
+    }
+    return {
+      outcomes: [outcome],
+      submittedEventCount: outcome.feedbackStatus === "submitted" ? outcome.type === "citation" ? outcome.resultCount : 1 : 0,
+      dispatchedEventCount: outcome.feedbackStatus === "dispatched" ? 1 : 0,
+      requestCount: requestUrl === void 0 ? 0 : 1,
+      navigated: outcome.navigationStatus === "navigated"
+    };
+  }
+  async send(url, options) {
+    const controller = new AbortController();
+    const timeout = options.timeout ?? 1e4;
+    let timer;
+    let onAbort;
+    const stopped = new Promise((_, reject) => {
+      onAbort = () => {
+        reject(new FeedbackCancelledError());
+        controller.abort();
+      };
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      timer = setTimeout(() => {
+        reject(new FeedbackTimeoutError());
+        controller.abort();
+      }, timeout);
+    });
+    try {
+      const response = await Promise.race([
+        this.sender.send(url, { signal: controller.signal, timeout }),
+        stopped
+      ]);
+      if (!Number.isInteger(response.status)) throw new FeedbackConnectionError();
+      if (response.status < 200 || response.status >= 300)
+        throw new FeedbackHttpError(response.status);
+    } finally {
+      clearTimeout(timer);
+      if (onAbort) options.signal?.removeEventListener("abort", onAbort);
+    }
+  }
+};
+
 // src/client.ts
 var WebIQClient = class {
+  feedback;
   /** Web search resource */
   web;
   /** News search resource */
@@ -637,6 +994,7 @@ var WebIQClient = class {
     const retry = options.retry instanceof RetryPolicy ? options.retry : options.retry ? new RetryPolicy(options.retry) : new RetryPolicy();
     this._transport = new HttpTransport({
       baseUrl: options.baseUrl ?? "https://api.microsoft.ai/v3",
+      appId: options.appId,
       auth: this._auth,
       telemetryHook: options.telemetryHook,
       retry,
@@ -648,6 +1006,7 @@ var WebIQClient = class {
     this.videos = new VideosResource(this._transport);
     this.images = new ImagesResource(this._transport);
     this.browse = new BrowseResource(this._transport);
+    this.feedback = new FeedbackClient(options.feedback);
   }
   /**
    * Close the client and release resources.
@@ -717,6 +1076,15 @@ var LiveCrawlMode = /* @__PURE__ */ ((LiveCrawlMode2) => {
   return LiveCrawlMode2;
 })(LiveCrawlMode || {});
 
+// src/generated-otc/models/RiskLevel.ts
+var RiskLevel = /* @__PURE__ */ ((RiskLevel2) => {
+  RiskLevel2["LOW"] = "low";
+  RiskLevel2["MODERATE"] = "moderate";
+  RiskLevel2["HIGH"] = "high";
+  RiskLevel2["VERY_HIGH"] = "veryHigh";
+  return RiskLevel2;
+})(RiskLevel || {});
+
 // src/generated-otc/models/SafeSearch.ts
 var SafeSearch = /* @__PURE__ */ ((SafeSearch2) => {
   SafeSearch2["OFF"] = "off";
@@ -749,4 +1117,4 @@ var VideoResolution = /* @__PURE__ */ ((VideoResolution2) => {
   return VideoResolution2;
 })(VideoResolution || {});
 
-export { APIConnectionError, APIStatusError, ApiKeyAuth, AuthenticationError, BrowseContentFormat, BrowseResource, ContentFormat, ContentTier, DEFAULT_SCOPE, DEFAULT_TIMEOUT, EntraIDAuth, HttpTransport, ImageAspectRatio, ImageColor, ImageSize, ImagesResource, LiveCrawlMode, NewsResource, PermissionDeniedError, RateLimitError, RetryPolicy, SafeSearch, SourceQuality, VideoDuration, VideoResolution, VideosResource, WebIQClient, WebIQError, WebResource, createAuth, createClient, createTelemetryEvent, safeCall };
+export { APIConnectionError, APIStatusError, ApiKeyAuth, AuthenticationError, BadRequestError, BrowseContentFormat, BrowseResource, ContentFormat, ContentTier, DEFAULT_SCOPE, DEFAULT_TIMEOUT, DefaultFeedbackSender, EntraIDAuth, FeedbackCancelledError, FeedbackClient, FeedbackConnectionError, FeedbackError, FeedbackHttpError, FeedbackNavigationError, FeedbackTimeoutError, HttpTransport, ImageAspectRatio, ImageColor, ImageSize, ImagesResource, InvalidFeedbackInputError, InvalidInstrumentationSuffixError, LiveCrawlMode, MissingInstrumentationError, NewsResource, NotFoundError, PermissionDeniedError, RateLimitError, RetryPolicy, RiskLevel, SafeSearch, SourceQuality, VideoDuration, VideoResolution, VideosResource, WebIQClient, WebIQError, WebResource, buildCitationPingUrl, buildClickPingUrl, createAuth, createClient, createTelemetryEvent, prepareClick, safeCall };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/webiq",
-  "version": "0.1.8",
+  "version": "1.0.0",
   "description": "Web IQ API TypeScript SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",