bem-ai-sdk 0.26.0 → 0.28.0

package/src/resources/index.ts

@@ -1,5 +1,16 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  Buckets,
+  type BucketCreateResponse,
+  type BucketRetrieveResponse,
+  type BucketUpdateResponse,
+  type BucketListResponse,
+  type BucketCreateParams,
+  type BucketUpdateParams,
+  type BucketListParams,
+  type BucketDeleteParams,
+} from './buckets';
 export {
   Calls,
   type Call,
@@ -28,6 +39,28 @@ export {
   type ConnectorCreateParams,
   type ConnectorListParams,
 } from './connectors';
+export {
+  Entities,
+  type EntityUpdateResponse,
+  type EntityBulkCreateResponse,
+  type EntityBulkValidateResponse,
+  type EntityRetrieveRelationsResponse,
+  type EntityRetrieveSeedStatusResponse,
+  type EntityUpdateParams,
+  type EntityBulkCreateParams,
+  type EntityBulkValidateParams,
+  type EntityRetrieveRelationsParams,
+} from './entities/entities';
+export {
+  EntityTypes,
+  type EntityTypeCreateResponse,
+  type EntityTypeRetrieveResponse,
+  type EntityTypeUpdateResponse,
+  type EntityTypeListResponse,
+  type EntityTypeCreateParams,
+  type EntityTypeUpdateParams,
+  type EntityTypeListParams,
+} from './entity-types/entity-types';
 export {
   Errors,
   type ErrorEvent,
@@ -68,6 +101,11 @@ export {
   type FunctionsFunctionsPage,
 } from './functions/functions';
 export { InferSchema, type InferSchemaCreateResponse, type InferSchemaCreateParams } from './infer-schema';
+export {
+  KnowledgeGraph,
+  type KnowledgeGraphRetrieveResponse,
+  type KnowledgeGraphRetrieveParams,
+} from './knowledge-graph';
 export {
   Outputs,
   type AnyType,
@@ -77,6 +115,7 @@ export {
   type OutputListParams,
   type EventsOutputsPage,
 } from './outputs';
+export { ReviewQueue, type ReviewQueueListResponse, type ReviewQueueListParams } from './review-queue';
 export {
   Subscriptions,
   type SubscriptionV3,
@@ -85,6 +124,7 @@ export {
   type SubscriptionUpdateParams,
   type SubscriptionListParams,
 } from './subscriptions';
+export { Users, type UserListReviewerAssignmentsResponse } from './users';
 export {
   Views,
   type ViewCreateResponse,

package/src/resources/knowledge-graph.ts

@@ -0,0 +1,174 @@
+// 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';
+
+/**
+ * Read the cross-document knowledge graph — the canonical entities and the
+ * directed relations between them that the Parse pipeline populates when
+ * `linkAcrossDocuments` is enabled.
+ *
+ * - **`GET /v3/entities/{id}/relations`** returns the inbound and outbound
+ *   edges incident to one entity, split by direction. Supports
+ *   `direction`, an exact `relationType` filter, and cursor pagination over
+ *   edges. A merged-away entity id transparently resolves to its surviving
+ *   canonical entity.
+ * - **`GET /v3/knowledge-graph`** returns the graph as `{ nodes, edges }`,
+ *   paginating over edges. The `nodes` for a page are the distinct endpoint
+ *   entities of that page's edges (both endpoints of every edge are
+ *   included). Filter with `type[]`, `since`, and `search`; an edge is
+ *   returned only when both of its endpoints survive the entity filters.
+ *
+ * Both endpoints take an optional `bucket` (`bkt_...`) to scope the read to
+ * a single bucket; omit it for the unscoped account+environment view.
+ */
+export class KnowledgeGraph extends APIResource {
+  /**
+   * Retrieve the Knowledge Graph
+   */
+  retrieve(
+    query: KnowledgeGraphRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<KnowledgeGraphRetrieveResponse> {
+    return this._client.get('/v3/knowledge-graph', { query, ...options });
+  }
+}
+
+/**
+ * Response body for `GET /v3/knowledge-graph`. Pagination is over edges; `nodes`
+ * are the distinct endpoint entities of the returned edge page (both endpoints of
+ * every edge are included).
+ */
+export interface KnowledgeGraphRetrieveResponse {
+  /**
+   * The page of edges.
+   */
+  edges: Array<KnowledgeGraphRetrieveResponse.Edge>;
+
+  /**
+   * Distinct endpoint entities of the returned edge page.
+   */
+  nodes: Array<KnowledgeGraphRetrieveResponse.Node>;
+
+  /**
+   * Opaque cursor for the next page of edges, or absent on the last page. Pass it
+   * back as `cursor`.
+   */
+  nextCursor?: string;
+}
+
+export namespace KnowledgeGraphRetrieveResponse {
+  /**
+   * One directed edge between two entities, addressed by their public ids.
+   */
+  export interface Edge {
+    /**
+     * How many times this edge has been observed.
+     */
+    mentionCount: number;
+
+    /**
+     * Free-form relation label.
+     */
+    relationType: string;
+
+    /**
+     * Source entity public id (`ent_...`).
+     */
+    sourceId: string;
+
+    /**
+     * Target entity public id (`ent_...`).
+     */
+    targetId: string;
+  }
+
+  /**
+   * One entity node in the knowledge graph.
+   */
+  export interface Node {
+    /**
+     * Stable public identifier for the entity (`ent_...`).
+     */
+    id: string;
+
+    /**
+     * Canonical (most descriptive) surface form.
+     */
+    canonical: string;
+
+    /**
+     * Hops from the center node when the request centers the graph on one entity
+     * (`nodeID`). The center is depth 0. When the request is uncentered (no `nodeID`),
+     * this is 0 for every node.
+     */
+    depth: number;
+
+    /**
+     * Total mentions of this entity across all parsed documents.
+     */
+    mentionCount: number;
+
+    /**
+     * Effective entity type.
+     */
+    type: string;
+  }
+}
+
+export interface KnowledgeGraphRetrieveParams {
+  /**
+   * Optional bucket public ID (`bkt_...`) to scope the read to one bucket. Omit for
+   * the unscoped (all account+environment) view.
+   */
+  bucket?: string;
+
+  /**
+   * Cursor: return edges whose KSUID sorts after this value.
+   */
+  cursor?: string;
+
+  /**
+   * Maximum number of edges per page (default 50, max 200).
+   */
+  limit?: number;
+
+  /**
+   * Maximum hops from the center node. Only meaningful with `nodeID`. Defaults to 2
+   * and is clamped down to a system maximum (5).
+   */
+  maxDepth?: number;
+
+  /**
+   * Center the graph on this entity (`ent_...`) and only return the subgraph within
+   * `maxDepth` hops of it; every node then carries its `depth` (hops from the
+   * center, center = 0). Omit for the uncentered whole-graph view. `rootNodeID` and
+   * `focusNodeID` are accepted as aliases.
+   */
+  nodeID?: string;
+
+  /**
+   * Case-insensitive substring match on canonical names. Both endpoints of an edge
+   * must match for the edge (and its nodes) to be returned.
+   */
+  search?: string;
+
+  /**
+   * Only edges created at/after this RFC 3339 timestamp.
+   */
+  since?: string;
+
+  /**
+   * Restrict to entities of these types. An edge is returned only when BOTH of its
+   * endpoints survive the type filter.
+   */
+  type?: Array<string>;
+}
+
+export declare namespace KnowledgeGraph {
+  export {
+    type KnowledgeGraphRetrieveResponse as KnowledgeGraphRetrieveResponse,
+    type KnowledgeGraphRetrieveParams as KnowledgeGraphRetrieveParams,
+  };
+}

package/src/resources/outputs.ts

@@ -85,7 +85,8 @@ export type Event =
   | Event.PayloadShapingEvent
   | Event.EvaluationEvent
   | Event.CollectionProcessingEvent
-  | Event.SendEvent;
+  | Event.SendEvent
+  | Event.RenderEvent;
 
 export namespace Event {
   export interface TransformEvent {
@@ -1836,6 +1837,103 @@ export namespace Event {
       httpStatusCode: number;
     }
   }
+
+  export interface RenderEvent {
+    /**
+     * Wall-clock seconds spent generating the output docx through the template.
+     */
+    docxRenderSeconds: number;
+
+    /**
+     * 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;
+
+    /**
+     * Short-lived presigned HTTPS URL the recipient can GET to download the rendered
+     * docx. Bearer-token semantics: possession equals access. Treat as a credential —
+     * do not log full URLs or store beyond the delivery window. The URL expires after
+     * the platform-configured TTL; the next API serialization mints a fresh one.
+     */
+    outputDownloadURL: string;
+
+    /**
+     * The unique ID you use internally to refer to this data point, propagated from
+     * the original function input.
+     */
+    referenceID: string;
+
+    /**
+     * Wall-clock seconds spent validating the upstream JSON against the doc-type
+     * schema.
+     */
+    validationSeconds: number;
+
+    /**
+     * Unique identifier of workflow call that this event is associated with.
+     */
+    callID?: string;
+
+    /**
+     * Timestamp indicating when the event was created.
+     */
+    createdAt?: string;
+
+    eventType?: 'render';
+
+    /**
+     * 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?: RenderEvent.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 RenderEvent {
+    export interface Metadata {
+      durationFunctionToEventSeconds?: number;
+    }
+  }
 }
 
 /**
@@ -1851,7 +1949,9 @@ export type InputType =
   | 'json'
   | 'heif'
   | 'm4a'
+  | 'mov'
   | 'mp3'
+  | 'mp4'
   | 'pdf'
   | 'png'
   | 'text'

package/src/resources/review-queue.ts

@@ -0,0 +1,234 @@
+// 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';
+
+/**
+ * The reviewer-facing read surface for entity curation, available on the
+ * dashboard (JWT) only.
+ *
+ * - **`GET /v3/review-queue`** returns a cursor-paginated set of entities
+ *   awaiting curation, scoped to your account+environment (and optional
+ *   `bucket`). Each row is a full entity plus a small preview (up to 2) of
+ *   its first mentions, so a reviewer can triage without opening every
+ *   entity.
+ *
+ * Filters AND together. `status` (repeatable) defaults to the pre-terminal
+ * states `extracted` + `proposed` when omitted. `type` (repeatable `ety_…`
+ * IDs) matches the entity's *effective* type — its assigned type id, or, for
+ * entities with no assigned type, its bem-inferred type name. `assignedTo`
+ * (`me` or a `usr_…` ID) restricts to entities whose effective type the user
+ * reviews. `since` (RFC3339) filters by creation time. Pagination is
+ * cursor-based on `entityID` ascending; default limit 50, maximum 200.
+ */
+export class ReviewQueue extends APIResource {
+  /**
+   * **List entities awaiting curation, for a human reviewer's queue.**
+   *
+   * Returns a cursor-paginated set of entities scoped to your account+environment
+   * (and optional `bucket`), each carrying a small preview of its first mentions so
+   * a reviewer can triage without opening every entity. All filters AND together.
+   *
+   * - **`status`** (repeatable) restricts to the given lifecycle states. Omitting it
+   *   defaults to the pre-terminal states `extracted` and `proposed`.
+   * - **`type`** (repeatable, `ety_...` IDs) matches the entity's _effective_ type:
+   *   an entity matches when its assigned type is one of these IDs, or it has no
+   *   assigned type and its bem-inferred type name matches one of them.
+   * - **`assignedTo`** (`me` or a `usr_...` ID) restricts to entities whose
+   *   effective type the given user reviews. `me` resolves to the calling user.
+   * - **`since`** (RFC3339) restricts to entities created at or after the time.
+   *
+   * Pagination is cursor-based on `entityID` ascending; default limit is 50,
+   * maximum 200.
+   */
+  list(
+    query: ReviewQueueListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ReviewQueueListResponse> {
+    return this._client.get('/v3/review-queue', { query, ...options });
+  }
+}
+
+/**
+ * `GET /v3/review-queue` response. Cursor-paginated by `entityID` ascending.
+ */
+export interface ReviewQueueListResponse {
+  /**
+   * The page of entities awaiting curation.
+   */
+  entities: Array<ReviewQueueListResponse.Entity>;
+
+  /**
+   * Whether more rows exist beyond this page.
+   */
+  hasMore: boolean;
+
+  /**
+   * Opaque cursor to pass as `?cursor=` for the next page. Empty when `hasMore` is
+   * false.
+   */
+  nextCursor?: string;
+}
+
+export namespace ReviewQueueListResponse {
+  /**
+   * One row of the review queue: an entity plus a small preview of its mentions.
+   */
+  export interface Entity {
+    /**
+     * The canonical (longest / most descriptive) surface form.
+     */
+    canonical: string;
+
+    /**
+     * When the entity was created.
+     */
+    createdAt: string;
+
+    /**
+     * Public ID (`ent_...`) of the entity.
+     */
+    entityID: string;
+
+    /**
+     * Total mentions across all parsed documents.
+     */
+    mentionCount: number;
+
+    /**
+     * A capped preview (up to 2) of the entity's first mentions, ordered by page then
+     * time, so a reviewer can triage without opening each entity.
+     */
+    previewMentions: Array<Entity.PreviewMention>;
+
+    /**
+     * Curation lifecycle state: `extracted`, `proposed`, `approved`, `rejected`.
+     */
+    status: string;
+
+    /**
+     * Distinct surface forms that have resolved to this entity.
+     */
+    surfaceForms: Array<string>;
+
+    /**
+     * The effective type name (assigned override if set, else bem-inferred).
+     */
+    type: string;
+
+    /**
+     * When the entity was last updated.
+     */
+    updatedAt: string;
+
+    /**
+     * Free-form description of the entity, when present.
+     */
+    description?: string;
+
+    /**
+     * Public ID (`ety_...`) of the customer-assigned type, when one is set.
+     */
+    typeID?: string;
+
+    /**
+     * When a human approved/rejected the entity. Omitted while un-validated.
+     */
+    validatedAt?: string;
+
+    /**
+     * Public ID (`usr_...`) of the user who validated the entity, when known.
+     */
+    validatedByUserID?: string;
+  }
+
+  export namespace Entity {
+    /**
+     * A single per-document occurrence of an entity, used in review-queue previews.
+     */
+    export interface PreviewMention {
+      /**
+       * When this mention was recorded.
+       */
+      createdAt: string;
+
+      /**
+       * Public ID (`ent_...`) of the entity this mention resolves to.
+       */
+      entityID: string;
+
+      /**
+       * Public ID (`emn_...`) of this mention.
+       */
+      mentionID: string;
+
+      /**
+       * 1-indexed page number within the source document.
+       */
+      page: number;
+
+      /**
+       * The user-provided document handle this mention came from.
+       */
+      referenceID: string;
+
+      /**
+       * The exact surface string Parse extracted on the page.
+       */
+      surface: string;
+
+      /**
+       * The parse-emitted section label this mention sat under, when present.
+       */
+      sectionLabel?: string;
+
+      /**
+       * Public ID of the parse transformation that produced this mention, when known.
+       */
+      transformationID?: string;
+    }
+  }
+}
+
+export interface ReviewQueueListParams {
+  /**
+   * `me` or a `usr_...` ID — restrict to entities whose effective type that user
+   * reviews.
+   */
+  assignedTo?: string;
+
+  /**
+   * Optional bucket public ID (`bkt_...`) to scope to. Omit for all buckets.
+   */
+  bucket?: string;
+
+  /**
+   * Cursor — an `entityID` defining your place in the list.
+   */
+  cursor?: string;
+
+  limit?: number;
+
+  /**
+   * RFC3339 timestamp — restrict to entities created at or after this time.
+   */
+  since?: string;
+
+  /**
+   * Restrict to these lifecycle states. Defaults to `extracted` + `proposed`.
+   */
+  status?: Array<string>;
+
+  /**
+   * Restrict to entities whose effective type is one of these `ety_...` IDs.
+   */
+  type?: Array<string>;
+}
+
+export declare namespace ReviewQueue {
+  export {
+    type ReviewQueueListResponse as ReviewQueueListResponse,
+    type ReviewQueueListParams as ReviewQueueListParams,
+  };
+}

package/src/resources/subscriptions.ts

@@ -9,11 +9,23 @@ import { path } from '../internal/utils/path';
 /**
  * Subscriptions wire up notifications for the events your functions and collections produce.
  *
- * Each subscription targets a single function (by `functionName` or `functionID`) or a single
- * collection (by `collectionName` or `collectionID`) and selects a `type` corresponding to the
+ * Most subscriptions target a single function (by `functionName` or `functionID`) or a single
+ * collection (by `collectionName` or `collectionID`) and select a `type` corresponding to the
  * event you want to receive — for example `transform`, `route`, `join`, `evaluation`, `error`,
  * `enrich`, or `collection_processing`.
  *
+ * Entity-lifecycle events are account-wide and target no function or collection. Set `type` to
+ * one of the following and provide a `webhookURL` (these event types support webhook delivery
+ * only):
+ *
+ * - `entity_proposed` — an entity entered the `proposed` curation status (queued for review).
+ * - `entity_validated` — an entity was approved/validated by a reviewer.
+ * - `entity_rejected` — an entity was rejected by a reviewer.
+ *
+ * Each entity-lifecycle delivery is a JSON POST describing the transition (`entityID`,
+ * `typeName`, `priorStatus`, `newStatus`, optional `actorUserID` and `reason`, and a
+ * `timestamp`).
+ *
  * Deliveries can be sent to any combination of:
  *
  * - `webhookURL` — HTTPS endpoint that receives a JSON POST per event.

package/src/resources/users.ts

@@ -0,0 +1,76 @@
+// 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';
+
+/**
+ * Reviewer assignments link users to the entity types they are responsible
+ * for reviewing, scoped to an account+environment. These are dashboard-only
+ * endpoints: an assignment needs a user identity, which only the dashboard
+ * (JWT) surface carries.
+ *
+ * - **`POST /v3/entity-types/{typeID}/reviewers`** assigns a user as a
+ *   reviewer of the type. The assignment is idempotent: re-assigning an
+ *   existing reviewer returns the existing assignment. Requires the `admin`
+ *   role.
+ * - **`GET /v3/entity-types/{typeID}/reviewers`** lists the users assigned
+ *   to review the type, with each user's email and role. Requires the
+ *   `operator` role.
+ * - **`DELETE /v3/entity-types/{typeID}/reviewers/{userID}`** removes an
+ *   assignment. Requires the `admin` role.
+ * - **`GET /v3/users/{userID}/reviewer-assignments`** is the reverse lookup:
+ *   the entity types a user reviews. A user may read their own assignments;
+ *   reading another user's assignments requires the `admin` role.
+ */
+export class Users extends APIResource {
+  /**
+   * List a User's Reviewer Assignments
+   */
+  listReviewerAssignments(
+    userID: string,
+    options?: RequestOptions,
+  ): APIPromise<UserListReviewerAssignmentsResponse> {
+    return this._client.get(path`/v3/users/${userID}/reviewer-assignments`, options);
+  }
+}
+
+/**
+ * Response body for the reverse lookup of a user's reviewer assignments.
+ */
+export interface UserListReviewerAssignmentsResponse {
+  assignments: Array<UserListReviewerAssignmentsResponse.Assignment>;
+}
+
+export namespace UserListReviewerAssignmentsResponse {
+  /**
+   * One entity type a user reviews, as returned by the reverse-lookup endpoint. The
+   * type is exposed via its public ID plus its name and description.
+   */
+  export interface Assignment {
+    /**
+     * When the assignment was created (RFC 3339).
+     */
+    createdAt: string;
+
+    /**
+     * The entity type's description.
+     */
+    description: string;
+
+    /**
+     * The entity type's human-facing name.
+     */
+    name: string;
+
+    /**
+     * Public ID (`ety_...`) of the entity type the user reviews.
+     */
+    typeID: string;
+  }
+}
+
+export declare namespace Users {
+  export { type UserListReviewerAssignmentsResponse as UserListReviewerAssignmentsResponse };
+}