bem-ai-sdk 0.0.4

package/src/internal/utils/values.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { BemError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+export let isArray = (val: unknown): val is unknown[] => ((isArray = Array.isArray), isArray(val));
+export let isReadonlyArray = isArray as (val: unknown) => val is readonly unknown[];
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new BemError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new BemError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new BemError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new BemError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new BemError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,9 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';
+export * from './utils/query';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/calls.ts

@@ -0,0 +1,264 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as ErrorsAPI from './errors';
+import * as OutputsAPI from './outputs';
+import { APIPromise } from '../core/api-promise';
+import { CallsPage, type CallsPageParams, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * The Calls API provides a unified interface for invoking both **Workflows** and **Functions**.
+ *
+ * Use this API when you want to:
+ * - Execute a complete workflow that chains multiple functions together
+ * - Call a single function directly without defining a workflow
+ * - Submit batch requests with multiple inputs in a single API call
+ * - Track execution status using call reference IDs
+ *
+ * **Key Difference**: Calls vs Function Calls
+ * - **Calls API** (`/v3/calls`): High-level API for invoking workflows or functions by name/ID. Supports batch processing and workflow orchestration.
+ * - **Function Calls API** (`/v3/functions/{functionName}/call`): Direct function invocation with function-type-specific arguments. Better for granular control over individual function calls.
+ */
+export class Calls extends APIResource {
+  /**
+   * **Retrieve a workflow call by ID.**
+   *
+   * Returns the full call object including status, workflow details, terminal
+   * outputs, and terminal errors. `outputs` and `errors` are both populated once the
+   * call finishes — they are not mutually exclusive (a partially-completed workflow
+   * may have both).
+   *
+   * ## Status
+   *
+   * | Status      | Description                                                 |
+   * | ----------- | ----------------------------------------------------------- |
+   * | `pending`   | Queued, not yet started                                     |
+   * | `running`   | Currently executing                                         |
+   * | `completed` | All enclosed function calls finished without errors         |
+   * | `failed`    | One or more enclosed function calls produced an error event |
+   *
+   * Poll this endpoint or configure a webhook subscription to detect completion.
+   */
+  retrieve(callID: string, options?: RequestOptions): APIPromise<CallGetResponse> {
+    return this._client.get(path`/v3/calls/${callID}`, options);
+  }
+
+  /**
+   * **List workflow calls with filtering and pagination.**
+   *
+   * Returns calls created via `POST /v3/workflows/{workflowName}/call`.
+   *
+   * ## Filtering
+   *
+   * - `callIDs`: Specific call identifiers
+   * - `referenceIDs`: Your custom reference IDs
+   * - `workflowIDs` / `workflowNames`: Filter by workflow
+   *
+   * ## Pagination
+   *
+   * Use `startingAfter` and `endingBefore` cursors with a default limit of 50.
+   */
+  list(
+    query: CallListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CallsCallsPage, Call> {
+    return this._client.getAPIList('/v3/calls', CallsPage<Call>, { query, ...options });
+  }
+}
+
+export type CallsCallsPage = CallsPage<Call>;
+
+/**
+ * A workflow call returned by the V3 API.
+ *
+ * Compared to the V2 `Call` model:
+ *
+ * - Terminal outputs are split into `outputs` (non-error events) and `errors`
+ *   (error events)
+ * - `callType` and function-scoped fields are removed — V3 calls are always
+ *   workflow calls
+ * - The deprecated `functionCalls` field is removed (use
+ *   `GET /v3/calls/{callID}/trace`)
+ * - `url` and `traceUrl` hint fields are included for resource discovery
+ */
+export interface Call {
+  /**
+   * Unique identifier of the call.
+   */
+  callID: string;
+
+  /**
+   * The date and time the call was created.
+   */
+  createdAt: string;
+
+  /**
+   * Terminal error events of this call. Workflow calls are not atomic — `errors` and
+   * `outputs` may both be non-empty if some enclosed function calls succeeded and
+   * others failed.
+   *
+   * Retrieve individual errors via `GET /v3/errors/{eventID}`.
+   */
+  errors: Array<ErrorsAPI.ErrorEvent>;
+
+  /**
+   * Terminal non-error outputs of this call: primary events (non-split-collection)
+   * that did not trigger any downstream function calls. Workflow calls are not
+   * atomic — `outputs` and `errors` may both be non-empty if some enclosed function
+   * calls succeeded and others failed.
+   *
+   * Each element is a polymorphic event object; inspect `eventType` to determine the
+   * type. Retrieve individual outputs via `GET /v3/outputs/{eventID}`.
+   */
+  outputs: Array<OutputsAPI.Event>;
+
+  /**
+   * Hint URL for the full execution trace: `GET /v3/calls/{callID}/trace`.
+   */
+  traceUrl: string;
+
+  /**
+   * Hint URL for retrieving this call: `GET /v3/calls/{callID}`.
+   */
+  url: string;
+
+  /**
+   * Your reference ID for this call, propagated from the original request.
+   */
+  callReferenceID?: string;
+
+  /**
+   * The date and time the call finished. Only set once status is `completed` or
+   * `failed`.
+   */
+  finishedAt?: string;
+
+  /**
+   * Input to the main function call.
+   */
+  input?: Call.Input;
+
+  /**
+   * Status of call.
+   */
+  status?: 'pending' | 'running' | 'completed' | 'failed';
+
+  /**
+   * Unique identifier of the workflow.
+   */
+  workflowID?: string;
+
+  /**
+   * Name of the workflow.
+   */
+  workflowName?: string;
+
+  /**
+   * Version number of the workflow.
+   */
+  workflowVersionNum?: number;
+}
+
+export namespace Call {
+  /**
+   * Input to the main function call.
+   */
+  export interface Input {
+    batchFiles?: Input.BatchFiles;
+
+    singleFile?: Input.SingleFile;
+  }
+
+  export namespace Input {
+    export interface BatchFiles {
+      inputs?: Array<BatchFiles.Input>;
+    }
+
+    export namespace BatchFiles {
+      export interface Input {
+        /**
+         * Input type of the file
+         */
+        inputType?: string;
+
+        /**
+         * Item reference ID
+         */
+        itemReferenceID?: string;
+
+        /**
+         * Presigned S3 URL for the file
+         */
+        s3URL?: string;
+      }
+    }
+
+    export interface SingleFile {
+      /**
+       * Input type of the file
+       */
+      inputType?: string;
+
+      /**
+       * Presigned S3 URL for the file
+       */
+      s3URL?: string;
+    }
+  }
+}
+
+export interface CallGetResponse {
+  /**
+   * A workflow call returned by the V3 API.
+   *
+   * Compared to the V2 `Call` model:
+   *
+   * - Terminal outputs are split into `outputs` (non-error events) and `errors`
+   *   (error events)
+   * - `callType` and function-scoped fields are removed — V3 calls are always
+   *   workflow calls
+   * - The deprecated `functionCalls` field is removed (use
+   *   `GET /v3/calls/{callID}/trace`)
+   * - `url` and `traceUrl` hint fields are included for resource discovery
+   */
+  call?: Call;
+
+  /**
+   * Error message if the call retrieval failed, or if the call itself failed when
+   * using `wait=true`.
+   */
+  error?: string;
+}
+
+export interface CallListParams extends CallsPageParams {
+  callIDs?: Array<string>;
+
+  referenceIDs?: Array<string>;
+
+  /**
+   * Case-insensitive substring match against `callReferenceID`.
+   */
+  referenceIDSubstring?: string;
+
+  sortOrder?: 'asc' | 'desc';
+
+  /**
+   * Filter by one or more statuses.
+   */
+  statuses?: Array<'pending' | 'running' | 'completed' | 'failed'>;
+
+  workflowIDs?: Array<string>;
+
+  workflowNames?: Array<string>;
+}
+
+export declare namespace Calls {
+  export {
+    type Call as Call,
+    type CallGetResponse as CallGetResponse,
+    type CallsCallsPage as CallsCallsPage,
+    type CallListParams as CallListParams,
+  };
+}

package/src/resources/errors.ts

@@ -0,0 +1,199 @@
+// 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 { ErrorsPage, type ErrorsPageParams, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Retrieve terminal error events from workflow calls.
+ *
+ * Errors are events produced by function steps that failed during processing. A single workflow
+ * call may produce multiple error events if several steps fail independently.
+ *
+ * Errors and outputs from the same call are not mutually exclusive: a partially-completed
+ * workflow may have both.
+ *
+ * Use `GET /v3/errors` to list errors across calls, or `GET /v3/errors/{eventID}` to retrieve
+ * a specific error. To get errors scoped to a single call, filter by `callIDs`.
+ */
+export class Errors extends APIResource {
+  /**
+   * **Retrieve a single error event by ID.**
+   *
+   * Returns `404` if the event does not exist or if it is not an error event (use
+   * `GET /v3/outputs/{eventID}` for non-error events).
+   */
+  retrieve(eventID: string, options?: RequestOptions): APIPromise<ErrorRetrieveResponse> {
+    return this._client.get(path`/v3/errors/${eventID}`, options);
+  }
+
+  /**
+   * **List terminal error events.**
+   *
+   * Returns error events produced by failed function calls within workflow
+   * executions. Non-error output events are excluded; use `GET /v3/outputs` to
+   * retrieve those.
+   *
+   * ## Filtering
+   *
+   * Filter by call, workflow, function, or reference ID. Multiple filters are ANDed
+   * together.
+   */
+  list(
+    query: ErrorListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ErrorEventsErrorsPage, ErrorEvent> {
+    return this._client.getAPIList('/v3/errors', ErrorsPage<ErrorEvent>, { query, ...options });
+  }
+}
+
+export type ErrorEventsErrorsPage = ErrorsPage<ErrorEvent>;
+
+export interface ErrorEvent {
+  /**
+   * 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;
+
+  /**
+   * Error message.
+   */
+  message: 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?: 'error';
+
+  /**
+   * 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?: InboundEmailEvent;
+
+  metadata?: ErrorEvent.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 ErrorEvent {
+  export interface Metadata {
+    durationFunctionToEventSeconds?: number;
+  }
+}
+
+export interface InboundEmailEvent {
+  /**
+   * The email address of the sender.
+   */
+  from: string;
+
+  /**
+   * The subject of the email.
+   */
+  subject: string;
+
+  /**
+   * The email address of the recipient.
+   */
+  to: string;
+
+  /**
+   * The email address of the original intended recipient if the email itself was
+   * forwarded.
+   */
+  deliveredTo?: string;
+}
+
+export interface ErrorRetrieveResponse {
+  /**
+   * The error event.
+   */
+  error: ErrorEvent;
+}
+
+export interface ErrorListParams extends ErrorsPageParams {
+  /**
+   * Filter to errors from specific calls.
+   */
+  callIDs?: Array<string>;
+
+  functionIDs?: Array<string>;
+
+  functionNames?: Array<string>;
+
+  referenceIDs?: Array<string>;
+
+  /**
+   * Case-insensitive substring match against `referenceID`.
+   */
+  referenceIDSubstring?: string;
+
+  sortOrder?: 'asc' | 'desc';
+
+  workflowIDs?: Array<string>;
+
+  workflowNames?: Array<string>;
+}
+
+export declare namespace Errors {
+  export {
+    type ErrorEvent as ErrorEvent,
+    type InboundEmailEvent as InboundEmailEvent,
+    type ErrorRetrieveResponse as ErrorRetrieveResponse,
+    type ErrorEventsErrorsPage as ErrorEventsErrorsPage,
+    type ErrorListParams as ErrorListParams,
+  };
+}

package/src/resources/functions/copy.ts

@@ -0,0 +1,96 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as FunctionsAPI from './functions';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+
+/**
+ * Functions are the core building blocks of data transformation in Bem. Each function type serves a specific purpose:
+ *
+ * - **Transform**: Extract structured JSON data from unstructured documents (PDFs, emails, images)
+ * - **Analyze**: Perform visual analysis on documents to extract layout-aware information
+ * - **Route**: Direct data to different processing paths based on conditions
+ * - **Split**: Break multi-page documents into individual pages for parallel processing
+ * - **Join**: Combine outputs from multiple function calls into a single result
+ * - **Payload Shaping**: Transform and restructure data using JMESPath expressions
+ * - **Enrich**: Enhance data with semantic search against collections
+ *
+ * Use these endpoints to create, update, list, and manage your functions.
+ */
+export class Copy extends APIResource {
+  /**
+   * Copy a Function
+   */
+  create(body: CopyCreateParams, options?: RequestOptions): APIPromise<FunctionsAPI.FunctionResponse> {
+    return this._client.post('/v3/functions/copy', { body, ...options });
+  }
+}
+
+/**
+ * Request to copy an existing function with a new name and optional
+ * customizations.
+ */
+export interface FunctionCopyRequest {
+  /**
+   * Name of the function to copy from. Must be a valid existing function name.
+   */
+  sourceFunctionName: string;
+
+  /**
+   * Name for the new copied function. Must be unique within the target environment.
+   */
+  targetFunctionName: string;
+
+  /**
+   * Optional array of tags for the copied function. If not provided, defaults to the
+   * source function's tags.
+   */
+  tags?: Array<string>;
+
+  /**
+   * Optional display name for the copied function. If not provided, defaults to the
+   * source function's display name with " (Copy)" appended.
+   */
+  targetDisplayName?: string;
+
+  /**
+   * Optional environment name to copy the function to. If not provided, the function
+   * will be copied within the same environment.
+   */
+  targetEnvironment?: string;
+}
+
+export interface CopyCreateParams {
+  /**
+   * Name of the function to copy from. Must be a valid existing function name.
+   */
+  sourceFunctionName: string;
+
+  /**
+   * Name for the new copied function. Must be unique within the target environment.
+   */
+  targetFunctionName: string;
+
+  /**
+   * Optional array of tags for the copied function. If not provided, defaults to the
+   * source function's tags.
+   */
+  tags?: Array<string>;
+
+  /**
+   * Optional display name for the copied function. If not provided, defaults to the
+   * source function's display name with " (Copy)" appended.
+   */
+  targetDisplayName?: string;
+
+  /**
+   * Optional environment name to copy the function to. If not provided, the function
+   * will be copied within the same environment.
+   */
+  targetEnvironment?: string;
+}
+
+export declare namespace Copy {
+  export { type FunctionCopyRequest as FunctionCopyRequest, type CopyCreateParams as CopyCreateParams };
+}