bem-ai-sdk 0.26.0 → 0.27.0

package/src/resources/knowledge-graph.ts

@@ -0,0 +1,153 @@
+// 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;
+
+    /**
+     * 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;
+
+  /**
+   * 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/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 };
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.26.0'; // x-release-please-version
+export const VERSION = '0.27.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.26.0";
+export declare const VERSION = "0.27.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.26.0";
+export declare const VERSION = "0.27.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.26.0'; // x-release-please-version
+exports.VERSION = '0.27.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.26.0'; // x-release-please-version
+export const VERSION = '0.27.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map