bem-ai-sdk 0.0.4

package/src/resources/outputs.ts

@@ -0,0 +1,987 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as OutputsAPI from './outputs';
+import * as ErrorsAPI from './errors';
+import { APIPromise } from '../core/api-promise';
+import { OutputsPage, type OutputsPageParams, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Retrieve terminal non-error output events from workflow calls.
+ *
+ * Outputs are events produced by successful terminal function steps — steps that completed
+ * without errors and did not spawn further downstream function calls. A single workflow call
+ * may produce multiple outputs (e.g. from a split-then-transform pipeline).
+ *
+ * Outputs and errors from the same call are not mutually exclusive: a partially-completed
+ * workflow may have both.
+ *
+ * Use `GET /v3/outputs` to list outputs across calls, or `GET /v3/outputs/{eventID}` to
+ * retrieve a specific output. To get outputs scoped to a single call, filter by `callIDs`.
+ */
+export class Outputs extends APIResource {
+  /**
+   * **Retrieve a single output event by ID.**
+   *
+   * Fetches any non-error event by its `eventID`. Returns `404` if the event does
+   * not exist or if it is an error event (use `GET /v3/errors/{eventID}` for those).
+   */
+  retrieve(eventID: string, options?: RequestOptions): APIPromise<OutputRetrieveResponse> {
+    return this._client.get(path`/v3/outputs/${eventID}`, options);
+  }
+
+  /**
+   * **List terminal non-error output events.**
+   *
+   * Returns events that represent successful terminal outputs — primary events
+   * (non-split-collection) that did not trigger any downstream function calls. Error
+   * events are excluded; use `GET /v3/errors` to retrieve those.
+   *
+   * ## Intermediate Events
+   *
+   * By default, intermediate events (those that spawned a downstream function call
+   * in a multi-step workflow) are excluded. Pass `includeIntermediate=true` to
+   * include them.
+   *
+   * ## Filtering
+   *
+   * Filter by call, workflow, function, or reference ID. Multiple filters are ANDed
+   * together.
+   */
+  list(
+    query: OutputListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EventsOutputsPage, Event> {
+    return this._client.getAPIList('/v3/outputs', OutputsPage<Event>, { query, ...options });
+  }
+}
+
+export type EventsOutputsPage = OutputsPage<Event>;
+
+export type AnyType = unknown | Array<unknown> | string | number | boolean;
+
+export type Event =
+  | Event.TransformEvent
+  | Event.RouteEvent
+  | Event.SplitCollectionEvent
+  | Event.SplitItemEvent
+  | ErrorsAPI.ErrorEvent
+  | Event.JoinEvent
+  | Event.EnrichEvent
+  | Event.CollectionProcessingEvent;
+
+export namespace Event {
+  export interface TransformEvent {
+    /**
+     * Unique ID generated by bem to identify the event.
+     */
+    eventID: string;
+
+    /**
+     * Unique identifier of function that this event is associated with.
+     */
+    functionID: string;
+
+    /**
+     * Unique name of function that this event is associated with.
+     */
+    functionName: string;
+
+    /**
+     * The number of items that were transformed. Used for batch transformations to
+     * indicate how many items were transformed.
+     */
+    itemCount: number;
+
+    /**
+     * The offset of the first item that was transformed. Used for batch
+     * transformations to indicate which item in the batch this event corresponds to.
+     */
+    itemOffset: number;
+
+    /**
+     * The unique ID you use internally to refer to this data point, propagated from
+     * the original function input.
+     */
+    referenceID: string;
+
+    /**
+     * The transformed content of the input. The structure of this object is defined by
+     * the function configuration.
+     */
+    transformedContent: unknown;
+
+    /**
+     * Average confidence score across all extracted fields, in the range [0, 1].
+     */
+    avgConfidence?: number | null;
+
+    /**
+     * Unique identifier of workflow call that this event is associated with.
+     */
+    callID?: string;
+
+    /**
+     * Corrected feedback provided for fine-tuning purposes.
+     */
+    correctedContent?: TransformEvent.Output | unknown | Array<unknown> | string | number | boolean | null;
+
+    /**
+     * Timestamp indicating when the event was created.
+     */
+    createdAt?: string;
+
+    eventType?: 'transform';
+
+    /**
+     * Per-field confidence scores. A JSON object mapping RFC 6901 JSON Pointer paths
+     * (e.g. `"/invoiceNumber"`) to float values in the range [0, 1] indicating the
+     * model's confidence in each extracted field value.
+     */
+    fieldConfidences?: unknown;
+
+    /**
+     * Unique identifier of function call that this event is associated with.
+     */
+    functionCallID?: string;
+
+    /**
+     * The attempt number of the function call that created this event. 1 indexed.
+     */
+    functionCallTryNumber?: number;
+
+    /**
+     * Version number of function that this event is associated with.
+     */
+    functionVersionNum?: number;
+
+    /**
+     * The inbound email that triggered this event.
+     */
+    inboundEmail?: ErrorsAPI.InboundEmailEvent;
+
+    /**
+     * Array of transformation inputs with their types and S3 URLs.
+     */
+    inputs?: Array<TransformEvent.Input> | null;
+
+    /**
+     * The input type of the content you're sending for transformation.
+     */
+    inputType?:
+      | 'csv'
+      | 'docx'
+      | 'email'
+      | 'heic'
+      | 'html'
+      | 'jpeg'
+      | 'json'
+      | 'heif'
+      | 'm4a'
+      | 'mp3'
+      | 'pdf'
+      | 'png'
+      | 'text'
+      | 'wav'
+      | 'webp'
+      | 'xls'
+      | 'xlsx'
+      | 'xml';
+
+    /**
+     * List of properties that were invalid in the input.
+     */
+    invalidProperties?: Array<string>;
+
+    /**
+     * Indicates whether this transformation was created as part of a regression test.
+     */
+    isRegression?: boolean;
+
+    /**
+     * Last timestamp indicating when the transform was published via webhook and
+     * received a non-200 response. Set to `null` on a subsequent retry if the webhook
+     * service receives a 200 response.
+     */
+    lastPublishErrorAt?: string | null;
+
+    metadata?: TransformEvent.Metadata;
+
+    /**
+     * Accuracy, precision, recall, and F1 score when corrected JSON is provided.
+     */
+    metrics?: TransformEvent.Metrics | null;
+
+    /**
+     * Indicates whether array order matters when comparing corrected JSON with
+     * extracted JSON.
+     */
+    orderMatching?: boolean;
+
+    /**
+     * ID of pipeline that transformed the original input data.
+     */
+    pipelineID?: string;
+
+    /**
+     * Timestamp indicating when the transform was published via webhook and received a
+     * successful 200 response. Value is `null` if the transformation hasn't been sent.
+     */
+    publishedAt?: string;
+
+    /**
+     * Presigned S3 URL for the input content uploaded to S3.
+     */
+    s3URL?: string | null;
+
+    /**
+     * Unique ID for each transformation output generated by bem following Segment's
+     * KSUID conventions.
+     */
+    transformationID?: string;
+
+    /**
+     * Unique identifier of workflow that this event is associated with.
+     */
+    workflowID?: string;
+
+    /**
+     * Name of workflow that this event is associated with.
+     */
+    workflowName?: string;
+
+    /**
+     * Version number of workflow that this event is associated with.
+     */
+    workflowVersionNum?: number;
+  }
+
+  export namespace TransformEvent {
+    export interface Output {
+      output?: Array<OutputsAPI.AnyType | null>;
+    }
+
+    export interface Input {
+      inputContent?: string | null;
+
+      inputType?: string | null;
+
+      jsonInputContent?: unknown | null;
+
+      s3URL?: string | null;
+    }
+
+    export interface Metadata {
+      durationFunctionToEventSeconds?: number;
+    }
+
+    /**
+     * Accuracy, precision, recall, and F1 score when corrected JSON is provided.
+     */
+    export interface Metrics {
+      differences?: Array<Metrics.Difference>;
+
+      metrics?: Metrics.Metrics;
+    }
+
+    export namespace Metrics {
+      export interface Difference {
+        category?: string;
+
+        correctedVal?: unknown;
+
+        extractedVal?: unknown;
+
+        jsonPointer?: string;
+      }
+
+      export interface Metrics {
+        accuracy?: number;
+
+        f1Score?: number;
+
+        precision?: number;
+
+        recall?: number;
+      }
+    }
+  }
+
+  export interface RouteEvent {
+    /**
+     * The choice made by the router function.
+     */
+    choice: string;
+
+    /**
+     * Unique ID generated by bem to identify the event.
+     */
+    eventID: string;
+
+    /**
+     * Unique identifier of function that this event is associated with.
+     */
+    functionID: string;
+
+    /**
+     * Unique name of function that this event is associated with.
+     */
+    functionName: string;
+
+    /**
+     * The unique ID you use internally to refer to this data point, propagated from
+     * the original function input.
+     */
+    referenceID: string;
+
+    /**
+     * Unique identifier of workflow call that this event is associated with.
+     */
+    callID?: string;
+
+    /**
+     * Timestamp indicating when the event was created.
+     */
+    createdAt?: string;
+
+    eventType?: 'route';
+
+    /**
+     * Unique identifier of function call that this event is associated with.
+     */
+    functionCallID?: string;
+
+    /**
+     * The attempt number of the function call that created this event. 1 indexed.
+     */
+    functionCallTryNumber?: number;
+
+    /**
+     * Version number of function that this event is associated with.
+     */
+    functionVersionNum?: number;
+
+    /**
+     * The inbound email that triggered this event.
+     */
+    inboundEmail?: ErrorsAPI.InboundEmailEvent;
+
+    metadata?: RouteEvent.Metadata;
+
+    /**
+     * The presigned S3 URL of the file that was routed.
+     */
+    s3URL?: string;
+
+    /**
+     * Unique identifier of workflow that this event is associated with.
+     */
+    workflowID?: string;
+
+    /**
+     * Name of workflow that this event is associated with.
+     */
+    workflowName?: string;
+
+    /**
+     * Version number of workflow that this event is associated with.
+     */
+    workflowVersionNum?: number;
+  }
+
+  export namespace RouteEvent {
+    export interface Metadata {
+      durationFunctionToEventSeconds?: number;
+    }
+  }
+
+  export interface SplitCollectionEvent {
+    /**
+     * Unique ID generated by bem to identify the event.
+     */
+    eventID: string;
+
+    /**
+     * Unique identifier of function that this event is associated with.
+     */
+    functionID: string;
+
+    /**
+     * Unique name of function that this event is associated with.
+     */
+    functionName: string;
+
+    outputType: 'print_page' | 'semantic_page';
+
+    printPageOutput: SplitCollectionEvent.PrintPageOutput;
+
+    /**
+     * The unique ID you use internally to refer to this data point, propagated from
+     * the original function input.
+     */
+    referenceID: string;
+
+    semanticPageOutput: SplitCollectionEvent.SemanticPageOutput;
+
+    /**
+     * Unique identifier of workflow call that this event is associated with.
+     */
+    callID?: string;
+
+    /**
+     * Timestamp indicating when the event was created.
+     */
+    createdAt?: string;
+
+    eventType?: 'split_collection';
+
+    /**
+     * Unique identifier of function call that this event is associated with.
+     */
+    functionCallID?: string;
+
+    /**
+     * The attempt number of the function call that created this event. 1 indexed.
+     */
+    functionCallTryNumber?: number;
+
+    /**
+     * Version number of function that this event is associated with.
+     */
+    functionVersionNum?: number;
+
+    /**
+     * The inbound email that triggered this event.
+     */
+    inboundEmail?: ErrorsAPI.InboundEmailEvent;
+
+    metadata?: SplitCollectionEvent.Metadata;
+
+    /**
+     * Unique identifier of workflow that this event is associated with.
+     */
+    workflowID?: string;
+
+    /**
+     * Name of workflow that this event is associated with.
+     */
+    workflowName?: string;
+
+    /**
+     * Version number of workflow that this event is associated with.
+     */
+    workflowVersionNum?: number;
+  }
+
+  export namespace SplitCollectionEvent {
+    export interface PrintPageOutput {
+      itemCount?: number;
+
+      items?: Array<PrintPageOutput.Item>;
+    }
+
+    export namespace PrintPageOutput {
+      export interface Item {
+        itemOffset?: number;
+
+        itemReferenceID?: string;
+
+        s3URL?: string;
+      }
+    }
+
+    export interface SemanticPageOutput {
+      itemCount?: number;
+
+      items?: Array<SemanticPageOutput.Item>;
+
+      pageCount?: number;
+    }
+
+    export namespace SemanticPageOutput {
+      export interface Item {
+        itemClass?: string;
+
+        itemClassCount?: number;
+
+        itemClassOffset?: number;
+
+        itemOffset?: number;
+
+        itemReferenceID?: string;
+
+        pageEnd?: number;
+
+        pageStart?: number;
+
+        s3URL?: string;
+      }
+    }
+
+    export interface Metadata {
+      durationFunctionToEventSeconds?: number;
+    }
+  }
+
+  export interface SplitItemEvent {
+    /**
+     * Unique ID generated by bem to identify the event.
+     */
+    eventID: string;
+
+    /**
+     * Unique identifier of function that this event is associated with.
+     */
+    functionID: string;
+
+    /**
+     * Unique name of function that this event is associated with.
+     */
+    functionName: string;
+
+    outputType: 'print_page' | 'semantic_page';
+
+    /**
+     * The unique ID you use internally to refer to this data point, propagated from
+     * the original function input.
+     */
+    referenceID: string;
+
+    /**
+     * Unique identifier of workflow call that this event is associated with.
+     */
+    callID?: string;
+
+    /**
+     * Timestamp indicating when the event was created.
+     */
+    createdAt?: string;
+
+    eventType?: 'split_item';
+
+    /**
+     * Unique identifier of function call that this event is associated with.
+     */
+    functionCallID?: string;
+
+    /**
+     * The attempt number of the function call that created this event. 1 indexed.
+     */
+    functionCallTryNumber?: number;
+
+    /**
+     * Version number of function that this event is associated with.
+     */
+    functionVersionNum?: number;
+
+    /**
+     * The inbound email that triggered this event.
+     */
+    inboundEmail?: ErrorsAPI.InboundEmailEvent;
+
+    metadata?: SplitItemEvent.Metadata;
+
+    printPageOutput?: SplitItemEvent.PrintPageOutput;
+
+    semanticPageOutput?: SplitItemEvent.SemanticPageOutput;
+
+    /**
+     * Unique identifier of workflow that this event is associated with.
+     */
+    workflowID?: string;
+
+    /**
+     * Name of workflow that this event is associated with.
+     */
+    workflowName?: string;
+
+    /**
+     * Version number of workflow that this event is associated with.
+     */
+    workflowVersionNum?: number;
+  }
+
+  export namespace SplitItemEvent {
+    export interface Metadata {
+      durationFunctionToEventSeconds?: number;
+    }
+
+    export interface PrintPageOutput {
+      collectionReferenceID?: string;
+
+      itemCount?: number;
+
+      itemOffset?: number;
+
+      s3URL?: string;
+    }
+
+    export interface SemanticPageOutput {
+      collectionReferenceID?: string;
+
+      itemClass?: string;
+
+      itemClassCount?: number;
+
+      itemClassOffset?: number;
+
+      itemCount?: number;
+
+      itemOffset?: number;
+
+      pageCount?: number;
+
+      pageEnd?: number;
+
+      pageStart?: number;
+
+      s3URL?: string;
+    }
+  }
+
+  export interface JoinEvent {
+    /**
+     * Unique ID generated by bem to identify the event.
+     */
+    eventID: string;
+
+    /**
+     * Unique identifier of function that this event is associated with.
+     */
+    functionID: string;
+
+    /**
+     * Unique name of function that this event is associated with.
+     */
+    functionName: string;
+
+    /**
+     * List of properties that were invalid in the input.
+     */
+    invalidProperties: Array<string>;
+
+    /**
+     * The items that were joined.
+     */
+    items: Array<JoinEvent.Item>;
+
+    /**
+     * The type of join that was performed.
+     */
+    joinType: 'standard';
+
+    /**
+     * The unique ID you use internally to refer to this data point, propagated from
+     * the original function input.
+     */
+    referenceID: string;
+
+    /**
+     * The transformed content of the input. The structure of this object is defined by
+     * the function configuration.
+     */
+    transformedContent: unknown;
+
+    /**
+     * Average confidence score across all extracted fields, in the range [0, 1].
+     */
+    avgConfidence?: number | null;
+
+    /**
+     * Unique identifier of workflow call that this event is associated with.
+     */
+    callID?: string;
+
+    /**
+     * Timestamp indicating when the event was created.
+     */
+    createdAt?: string;
+
+    eventType?: 'join';
+
+    /**
+     * Per-field confidence scores. A JSON object mapping RFC 6901 JSON Pointer paths
+     * (e.g. `"/invoiceNumber"`) to float values in the range [0, 1] indicating the
+     * model's confidence in each extracted field value.
+     */
+    fieldConfidences?: unknown;
+
+    /**
+     * Unique identifier of function call that this event is associated with.
+     */
+    functionCallID?: string;
+
+    /**
+     * The attempt number of the function call that created this event. 1 indexed.
+     */
+    functionCallTryNumber?: number;
+
+    /**
+     * Version number of function that this event is associated with.
+     */
+    functionVersionNum?: number;
+
+    /**
+     * The inbound email that triggered this event.
+     */
+    inboundEmail?: ErrorsAPI.InboundEmailEvent;
+
+    metadata?: JoinEvent.Metadata;
+
+    /**
+     * Unique ID for each transformation output generated by bem following Segment's
+     * KSUID conventions.
+     */
+    transformationID?: string;
+
+    /**
+     * Unique identifier of workflow that this event is associated with.
+     */
+    workflowID?: string;
+
+    /**
+     * Name of workflow that this event is associated with.
+     */
+    workflowName?: string;
+
+    /**
+     * Version number of workflow that this event is associated with.
+     */
+    workflowVersionNum?: number;
+  }
+
+  export namespace JoinEvent {
+    export interface Item {
+      /**
+       * The number of items that were transformed.
+       */
+      itemCount: number;
+
+      /**
+       * The offset of the first item that was transformed. Used for batch
+       * transformations to indicate which item in the batch this event corresponds to.
+       */
+      itemOffset: number;
+
+      /**
+       * The unique ID you use internally to refer to this data point.
+       */
+      itemReferenceID: string;
+
+      /**
+       * The presigned S3 URL of the file that was joined.
+       */
+      s3URL?: string;
+    }
+
+    export interface Metadata {
+      durationFunctionToEventSeconds?: number;
+    }
+  }
+
+  export interface EnrichEvent {
+    /**
+     * The enriched content produced by the enrich function. Contains the input data
+     * augmented with results from semantic search against collections.
+     */
+    enrichedContent: unknown;
+
+    /**
+     * Unique ID generated by bem to identify the event.
+     */
+    eventID: string;
+
+    /**
+     * Unique identifier of function that this event is associated with.
+     */
+    functionID: string;
+
+    /**
+     * Unique name of function that this event is associated with.
+     */
+    functionName: string;
+
+    /**
+     * The unique ID you use internally to refer to this data point, propagated from
+     * the original function input.
+     */
+    referenceID: string;
+
+    /**
+     * Unique identifier of workflow call that this event is associated with.
+     */
+    callID?: string;
+
+    /**
+     * Timestamp indicating when the event was created.
+     */
+    createdAt?: string;
+
+    eventType?: 'enrich';
+
+    /**
+     * Unique identifier of function call that this event is associated with.
+     */
+    functionCallID?: string;
+
+    /**
+     * The attempt number of the function call that created this event. 1 indexed.
+     */
+    functionCallTryNumber?: number;
+
+    /**
+     * Version number of function that this event is associated with.
+     */
+    functionVersionNum?: number;
+
+    /**
+     * The inbound email that triggered this event.
+     */
+    inboundEmail?: ErrorsAPI.InboundEmailEvent;
+
+    metadata?: EnrichEvent.Metadata;
+
+    /**
+     * Unique identifier of workflow that this event is associated with.
+     */
+    workflowID?: string;
+
+    /**
+     * Name of workflow that this event is associated with.
+     */
+    workflowName?: string;
+
+    /**
+     * Version number of workflow that this event is associated with.
+     */
+    workflowVersionNum?: number;
+  }
+
+  export namespace EnrichEvent {
+    export interface Metadata {
+      durationFunctionToEventSeconds?: number;
+    }
+  }
+
+  export interface CollectionProcessingEvent {
+    /**
+     * Unique identifier of the collection.
+     */
+    collectionID: string;
+
+    /**
+     * Name/path of the collection.
+     */
+    collectionName: string;
+
+    /**
+     * Unique ID generated by bem to identify the event.
+     */
+    eventID: string;
+
+    /**
+     * The operation performed (add or update).
+     */
+    operation: 'add' | 'update';
+
+    /**
+     * Number of items successfully processed.
+     */
+    processedCount: number;
+
+    /**
+     * The unique ID you use internally to refer to this data point, propagated from
+     * the original function input.
+     */
+    referenceID: string;
+
+    /**
+     * Processing status (success or failed).
+     */
+    status: 'success' | 'failed';
+
+    /**
+     * Array of collection item KSUIDs that were added or updated.
+     */
+    collectionItemIDs?: Array<string>;
+
+    /**
+     * Timestamp indicating when the event was created.
+     */
+    createdAt?: string;
+
+    /**
+     * Error message if processing failed.
+     */
+    errorMessage?: string;
+
+    eventType?: 'collection_processing';
+
+    /**
+     * The attempt number of the function call that created this event. 1 indexed.
+     */
+    functionCallTryNumber?: number;
+
+    /**
+     * The inbound email that triggered this event.
+     */
+    inboundEmail?: ErrorsAPI.InboundEmailEvent;
+
+    metadata?: CollectionProcessingEvent.Metadata;
+  }
+
+  export namespace CollectionProcessingEvent {
+    export interface Metadata {
+      durationFunctionToEventSeconds?: number;
+    }
+  }
+}
+
+export interface OutputRetrieveResponse {
+  /**
+   * The output event. Polymorphic by `eventType`.
+   */
+  output: Event;
+}
+
+export interface OutputListParams extends OutputsPageParams {
+  /**
+   * Filter to outputs from specific calls.
+   */
+  callIDs?: Array<string>;
+
+  functionIDs?: Array<string>;
+
+  functionNames?: Array<string>;
+
+  /**
+   * When `true`, includes intermediate events (those that spawned a downstream
+   * function call). Default: `false`.
+   */
+  includeIntermediate?: boolean;
+
+  referenceIDs?: Array<string>;
+
+  /**
+   * Case-insensitive substring match against `referenceID`.
+   */
+  referenceIDSubstring?: string;
+
+  sortOrder?: 'asc' | 'desc';
+
+  workflowIDs?: Array<string>;
+
+  workflowNames?: Array<string>;
+}
+
+export declare namespace Outputs {
+  export {
+    type AnyType as AnyType,
+    type Event as Event,
+    type OutputRetrieveResponse as OutputRetrieveResponse,
+    type EventsOutputsPage as EventsOutputsPage,
+    type OutputListParams as OutputListParams,
+  };
+}