@papr/memory 1.8.3 → 1.10.0

package/src/internal/request-options.ts

@@ -9,17 +9,70 @@ import { type HeadersLike } from './headers';
 export type FinalRequestOptions = RequestOptions & { method: HTTPMethod; path: string };
 
 export type RequestOptions = {
+  /**
+   * The HTTP method for the request (e.g., 'get', 'post', 'put', 'delete').
+   */
   method?: HTTPMethod;
+
+  /**
+   * The URL path for the request.
+   *
+   * @example "/v1/foo"
+   */
   path?: string;
+
+  /**
+   * Query parameters to include in the request URL.
+   */
   query?: object | undefined | null;
+
+  /**
+   * The request body. Can be a string, JSON object, FormData, or other supported types.
+   */
   body?: unknown;
+
+  /**
+   * HTTP headers to include with the request. Can be a Headers object, plain object, or array of tuples.
+   */
   headers?: HeadersLike;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 2
+   */
   maxRetries?: number;
+
   stream?: boolean | undefined;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * @unit milliseconds
+   */
   timeout?: number;
+
+  /**
+   * Additional `RequestInit` options to be passed to the underlying `fetch` call.
+   * These options will be merged with the client's default fetch options.
+   */
   fetchOptions?: MergedRequestInit;
+
+  /**
+   * An AbortSignal that can be used to cancel the request.
+   */
   signal?: AbortSignal | undefined | null;
+
+  /**
+   * A unique key for this request to enable idempotency.
+   */
   idempotencyKey?: string;
+
+  /**
+   * Override the default base URL for this specific request.
+   */
   defaultBaseURL?: string | undefined;
 
   __binaryResponse?: boolean | undefined;

package/src/internal/uploads.ts

@@ -90,7 +90,7 @@ export const multipartFormRequestOptions = async (
   return { ...opts, body: await createForm(opts.body, fetch) };
 };
 
-const supportsFormDataMap = /** @__PURE__ */ new WeakMap<Fetch, Promise<boolean>>();
+const supportsFormDataMap = /* @__PURE__ */ new WeakMap<Fetch, Promise<boolean>>();
 
 /**
  * node-fetch doesn't support the global FormData object in recent node versions. Instead of sending

package/src/internal/utils/log.ts

@@ -58,7 +58,7 @@ const noopLogger = {
   debug: noop,
 };
 
-let cachedLoggers = /** @__PURE__ */ new WeakMap<Logger, [LogLevel, Logger]>();
+let cachedLoggers = /* @__PURE__ */ new WeakMap<Logger, [LogLevel, Logger]>();
 
 export function loggerFor(client: Papr): Logger {
   const logger = client.logger;
@@ -106,8 +106,9 @@ export const formatRequestDetails = (details: {
         ([name, value]) => [
           name,
           (
-            name.toLowerCase() === 'x-api-key' ||
             name.toLowerCase() === 'authorization' ||
+            name.toLowerCase() === 'x-session-token' ||
+            name.toLowerCase() === 'x-api-key' ||
             name.toLowerCase() === 'cookie' ||
             name.toLowerCase() === 'set-cookie'
           ) ?

package/src/internal/utils/path.ts

@@ -12,25 +12,43 @@ export function encodeURIPath(str: string) {
   return str.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
 }
 
+const EMPTY = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.create(null));
+
 export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
   function path(statics: readonly string[], ...params: readonly unknown[]): string {
     // If there are no params, no processing is needed.
     if (statics.length === 1) return statics[0]!;
 
     let postPath = false;
+    const invalidSegments = [];
     const path = statics.reduce((previousValue, currentValue, index) => {
       if (/[?#]/.test(currentValue)) {
         postPath = true;
       }
-      return (
-        previousValue +
-        currentValue +
-        (index === params.length ? '' : (postPath ? encodeURIComponent : pathEncoder)(String(params[index])))
-      );
+      const value = params[index];
+      let encoded = (postPath ? encodeURIComponent : pathEncoder)('' + value);
+      if (
+        index !== params.length &&
+        (value == null ||
+          (typeof value === 'object' &&
+            // handle values from other realms
+            value.toString ===
+              Object.getPrototypeOf(Object.getPrototypeOf((value as any).hasOwnProperty ?? EMPTY) ?? EMPTY)
+                ?.toString))
+      ) {
+        encoded = value + '';
+        invalidSegments.push({
+          start: previousValue.length + currentValue.length,
+          length: encoded.length,
+          error: `Value of type ${Object.prototype.toString
+            .call(value)
+            .slice(8, -1)} is not a valid path parameter`,
+        });
+      }
+      return previousValue + currentValue + (index === params.length ? '' : encoded);
     }, '');
 
     const pathOnly = path.split(/[?#]/, 1)[0]!;
-    const invalidSegments = [];
     const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
     let match;
 
@@ -39,9 +57,12 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
       invalidSegments.push({
         start: match.index,
         length: match[0].length,
+        error: `Value "${match[0]}" can\'t be safely passed as a path parameter`,
       });
     }
 
+    invalidSegments.sort((a, b) => a.start - b.start);
+
     if (invalidSegments.length > 0) {
       let lastEnd = 0;
       const underline = invalidSegments.reduce((acc, segment) => {
@@ -51,7 +72,11 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
         return acc + spaces + arrows;
       }, '');
 
-      throw new PaprError(`Path parameters result in path with invalid segments:\n${path}\n${underline}`);
+      throw new PaprError(
+        `Path parameters result in path with invalid segments:\n${invalidSegments
+          .map((e) => e.error)
+          .join('\n')}\n${path}\n${underline}`,
+      );
     }
 
     return path;

package/src/resources/feedback.ts

@@ -0,0 +1,424 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Feedback extends APIResource {
+  /**
+   * Retrieve feedback by ID.
+   *
+   *     This endpoint allows developers to fetch feedback details by feedback ID.
+   *     Only the user who created the feedback or users with appropriate permissions can access it.
+   *
+   *     **Authentication Required**:
+   *     One of the following authentication methods must be used:
+   *     - Bearer token in `Authorization` header
+   *     - API Key in `X-API-Key` header
+   *     - Session token in `X-Session-Token` header
+   *
+   *     **Required Headers**:
+   *     - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
+   *
+   * @example
+   * ```ts
+   * const feedbackResponse = await client.feedback.getByID(
+   *   'feedback_id',
+   * );
+   * ```
+   */
+  getByID(feedbackID: string, options?: RequestOptions): APIPromise<FeedbackResponse> {
+    return this._client.get(path`/v1/feedback/${feedbackID}`, options);
+  }
+
+  /**
+   * Submit feedback on search results to help improve model performance.
+   *
+   *     This endpoint allows developers to provide feedback on:
+   *     - Overall answer quality (thumbs up/down, ratings)
+   *     - Specific memory relevance and accuracy
+   *     - User engagement signals (copy, save, create document actions)
+   *     - Corrections and improvements
+   *
+   *     The feedback is used to train and improve:
+   *     - Router model tier predictions
+   *     - Memory retrieval ranking
+   *     - Answer generation quality
+   *     - Agentic graph search performance
+   *
+   *     **Authentication Required**:
+   *     One of the following authentication methods must be used:
+   *     - Bearer token in `Authorization` header
+   *     - API Key in `X-API-Key` header
+   *     - Session token in `X-Session-Token` header
+   *
+   *     **Required Headers**:
+   *     - Content-Type: application/json
+   *     - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
+   *
+   * @example
+   * ```ts
+   * const feedbackResponse = await client.feedback.submit({
+   *   feedbackData: {
+   *     feedbackSource: 'inline',
+   *     feedbackType: 'thumbs_up',
+   *   },
+   *   search_id: 'abc123def456',
+   * });
+   * ```
+   */
+  submit(body: FeedbackSubmitParams, options?: RequestOptions): APIPromise<FeedbackResponse> {
+    return this._client.post('/v1/feedback', { body, ...options });
+  }
+
+  /**
+   * Submit multiple feedback items in a single request.
+   *
+   *     Useful for submitting session-end feedback or bulk feedback collection.
+   *     Each feedback item is processed independently, so partial success is possible.
+   *
+   *     **Authentication Required**:
+   *     One of the following authentication methods must be used:
+   *     - Bearer token in `Authorization` header
+   *     - API Key in `X-API-Key` header
+   *     - Session token in `X-Session-Token` header
+   *
+   *     **Required Headers**:
+   *     - Content-Type: application/json
+   *     - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
+   *
+   * @example
+   * ```ts
+   * const batchResponse = await client.feedback.submitBatch({
+   *   feedback_items: [
+   *     {
+   *       feedbackData: {
+   *         feedbackSource: 'inline',
+   *         feedbackType: 'thumbs_up',
+   *       },
+   *       search_id: 'abc123def456',
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  submitBatch(body: FeedbackSubmitBatchParams, options?: RequestOptions): APIPromise<BatchResponse> {
+    return this._client.post('/v1/feedback/batch', { body, ...options });
+  }
+}
+
+/**
+ * Request model for submitting multiple feedback items
+ */
+export interface BatchRequest {
+  /**
+   * List of feedback items to submit
+   */
+  feedback_items: Array<FeedbackRequest>;
+
+  /**
+   * Session-level context for batch feedback
+   */
+  session_context?: { [key: string]: unknown } | null;
+}
+
+/**
+ * Response model for batch feedback submission
+ */
+export interface BatchResponse {
+  /**
+   * HTTP status code
+   */
+  code: number;
+
+  /**
+   * Human-readable message
+   */
+  message: string;
+
+  /**
+   * 'success' or 'error'
+   */
+  status: string;
+
+  /**
+   * Error message if status is 'error'
+   */
+  error?: string | null;
+
+  /**
+   * List of error details
+   */
+  errors?: Array<{ [key: string]: unknown }>;
+
+  /**
+   * Number of failed feedback items
+   */
+  failed_count?: number;
+
+  /**
+   * List of feedback IDs
+   */
+  feedback_ids?: Array<string>;
+
+  /**
+   * Number of successfully processed feedback items
+   */
+  successful_count?: number;
+}
+
+/**
+ * Request model for submitting feedback on search results
+ */
+export interface FeedbackRequest {
+  /**
+   * The feedback data containing all feedback information
+   */
+  feedbackData: FeedbackRequest.FeedbackData;
+
+  /**
+   * The search_id from SearchResponse that this feedback relates to
+   */
+  search_id: string;
+
+  /**
+   * External user ID for developer API keys acting on behalf of end users
+   */
+  external_user_id?: string | null;
+
+  /**
+   * Internal user ID (if not provided, will be resolved from authentication)
+   */
+  user_id?: string | null;
+}
+
+export namespace FeedbackRequest {
+  /**
+   * The feedback data containing all feedback information
+   */
+  export interface FeedbackData {
+    /**
+     * Where the feedback was provided from
+     */
+    feedbackSource: 'inline' | 'post_query' | 'session_end' | 'memory_citation' | 'answer_panel';
+
+    /**
+     * Types of feedback that can be provided
+     */
+    feedbackType:
+      | 'thumbs_up'
+      | 'thumbs_down'
+      | 'rating'
+      | 'correction'
+      | 'report'
+      | 'copy_action'
+      | 'save_action'
+      | 'create_document'
+      | 'memory_relevance'
+      | 'answer_quality';
+
+    /**
+     * A pointer to a Parse object
+     */
+    assistantMessage?: FeedbackData.AssistantMessage | null;
+
+    citedMemoryIds?: Array<string> | null;
+
+    citedNodeIds?: Array<string> | null;
+
+    feedbackImpact?: string | null;
+
+    feedbackProcessed?: boolean | null;
+
+    feedbackScore?: number | null;
+
+    feedbackText?: string | null;
+
+    feedbackValue?: string | null;
+
+    /**
+     * A pointer to a Parse object
+     */
+    userMessage?: FeedbackData.UserMessage | null;
+  }
+
+  export namespace FeedbackData {
+    /**
+     * A pointer to a Parse object
+     */
+    export interface AssistantMessage {
+      className: string;
+
+      objectId: string;
+
+      __type?: string;
+    }
+
+    /**
+     * A pointer to a Parse object
+     */
+    export interface UserMessage {
+      className: string;
+
+      objectId: string;
+
+      __type?: string;
+    }
+  }
+}
+
+/**
+ * Response model for feedback submission
+ */
+export interface FeedbackResponse {
+  /**
+   * HTTP status code
+   */
+  code: number;
+
+  /**
+   * Human-readable message
+   */
+  message: string;
+
+  /**
+   * 'success' or 'error'
+   */
+  status: string;
+
+  /**
+   * Additional error details
+   */
+  details?: { [key: string]: unknown } | null;
+
+  /**
+   * Error message if status is 'error'
+   */
+  error?: string | null;
+
+  /**
+   * Unique feedback ID
+   */
+  feedback_id?: string | null;
+}
+
+export interface FeedbackSubmitParams {
+  /**
+   * The feedback data containing all feedback information
+   */
+  feedbackData: FeedbackSubmitParams.FeedbackData;
+
+  /**
+   * The search_id from SearchResponse that this feedback relates to
+   */
+  search_id: string;
+
+  /**
+   * External user ID for developer API keys acting on behalf of end users
+   */
+  external_user_id?: string | null;
+
+  /**
+   * Internal user ID (if not provided, will be resolved from authentication)
+   */
+  user_id?: string | null;
+}
+
+export namespace FeedbackSubmitParams {
+  /**
+   * The feedback data containing all feedback information
+   */
+  export interface FeedbackData {
+    /**
+     * Where the feedback was provided from
+     */
+    feedbackSource: 'inline' | 'post_query' | 'session_end' | 'memory_citation' | 'answer_panel';
+
+    /**
+     * Types of feedback that can be provided
+     */
+    feedbackType:
+      | 'thumbs_up'
+      | 'thumbs_down'
+      | 'rating'
+      | 'correction'
+      | 'report'
+      | 'copy_action'
+      | 'save_action'
+      | 'create_document'
+      | 'memory_relevance'
+      | 'answer_quality';
+
+    /**
+     * A pointer to a Parse object
+     */
+    assistantMessage?: FeedbackData.AssistantMessage | null;
+
+    citedMemoryIds?: Array<string> | null;
+
+    citedNodeIds?: Array<string> | null;
+
+    feedbackImpact?: string | null;
+
+    feedbackProcessed?: boolean | null;
+
+    feedbackScore?: number | null;
+
+    feedbackText?: string | null;
+
+    feedbackValue?: string | null;
+
+    /**
+     * A pointer to a Parse object
+     */
+    userMessage?: FeedbackData.UserMessage | null;
+  }
+
+  export namespace FeedbackData {
+    /**
+     * A pointer to a Parse object
+     */
+    export interface AssistantMessage {
+      className: string;
+
+      objectId: string;
+
+      __type?: string;
+    }
+
+    /**
+     * A pointer to a Parse object
+     */
+    export interface UserMessage {
+      className: string;
+
+      objectId: string;
+
+      __type?: string;
+    }
+  }
+}
+
+export interface FeedbackSubmitBatchParams {
+  /**
+   * List of feedback items to submit
+   */
+  feedback_items: Array<FeedbackRequest>;
+
+  /**
+   * Session-level context for batch feedback
+   */
+  session_context?: { [key: string]: unknown } | null;
+}
+
+export declare namespace Feedback {
+  export {
+    type BatchRequest as BatchRequest,
+    type BatchResponse as BatchResponse,
+    type FeedbackRequest as FeedbackRequest,
+    type FeedbackResponse as FeedbackResponse,
+    type FeedbackSubmitParams as FeedbackSubmitParams,
+    type FeedbackSubmitBatchParams as FeedbackSubmitBatchParams,
+  };
+}

package/src/resources/index.ts

@@ -1,5 +1,14 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  Feedback,
+  type BatchRequest,
+  type BatchResponse,
+  type FeedbackRequest,
+  type FeedbackResponse,
+  type FeedbackSubmitParams,
+  type FeedbackSubmitBatchParams,
+} from './feedback';
 export {
   Memory,
   type AddMemory,