@air/api-rest 0.10.0 → 0.11.0

package/README.md

@@ -2,7 +2,7 @@
 
 Typed REST client for the [Air API SDK](https://github.com/AirLabsTeam/air-api-sdk).
 
-This package provides the resource classes (boards, showcases, assets, tags, custom fields, uploads, imports, roles) and their TypeScript types. It builds on `@air/api-core` for HTTP transport.
+This package provides the resource classes (boards, showcases, assets, tags, custom fields, discussions, members, uploads, imports, roles) and their TypeScript types. It builds on `@air/api-core` for HTTP transport.
 
 ## Installation
 
@@ -20,7 +20,9 @@ npm install @air/api-rest
 
 ## What's included
 
-- Resource classes: `Boards`, `Showcases`, `Assets`, `Tags`, `CustomFields`, `Uploads`, `Imports`, `Roles`
+- Resource classes: `Boards`, `Showcases`, `Assets`, `Tags`, `CustomFields`, `Discussions`, `Members`, `Uploads`, `Imports`, `Roles`
+- Discussions: `list`, `get`, `listComments`, `create`, `createComment`, `update`, `updateComment`, `deleteComment`
+- Members: `list`
 - Showcases: `list`, `get`, `create`, `update`, `updateShareLink`, `addAssets`, `removeAsset`, `addBoards`, `removeBoard`, plus a `showcaseId` filter on `assets.list` and `boards.list`
 - Asset CDN link helpers: `listCdnLinks`, `createCdnLink`, and `updateCdnLink`
 - Share links: `listShareLinks`, `createShareLink`, and `updateShareLink` on assets and boards

package/dist/index.cjs

@@ -40,9 +40,11 @@ __export(index_exports, {
   ConnectionError: () => import_api_core2.ConnectionError,
   CursorPage: () => import_api_core2.CursorPage,
   CustomFields: () => CustomFields,
+  Discussions: () => Discussions,
   Imports: () => Imports,
   InternalServerError: () => import_api_core2.InternalServerError,
   Libraries: () => Libraries,
+  Members: () => Members,
   NotFoundError: () => import_api_core2.NotFoundError,
   PagePromise: () => import_api_core2.PagePromise,
   PermissionError: () => import_api_core2.PermissionError,
@@ -418,6 +420,118 @@ var CustomFields = class {
   }
 };
 
+// src/resources/discussions.ts
+var Discussions = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List discussions on an asset or on the assets currently in a board.
+   * Exactly one of `assetId` or `boardId` is required.
+   *
+   * Pages don't overlap. With the default `lastCommentedAt` sort, a reply
+   * between pages can move a discussion, so it may repeat or be skipped. For
+   * a stable walk, use `sortBy: "createdAt"` and `sortDirection: "asc"`.
+   */
+  list(params) {
+    const query = {
+      assetId: params.assetId,
+      assetVersionId: params.assetVersionId,
+      boardId: params.boardId,
+      resolved: params.resolved,
+      sortBy: params.sortBy,
+      sortDirection: params.sortDirection,
+      limit: params.limit,
+      cursor: params.cursor
+    };
+    return this.client.requestCursorPage(
+      { method: "GET", path: "/discussions", query },
+      query
+    );
+  }
+  /** Get one discussion, including its first 10 comments. A discussion you cannot view is 404. */
+  async get(discussionId) {
+    return this.client.request({
+      method: "GET",
+      path: `/discussions/${discussionId}`
+    });
+  }
+  /**
+   * List every comment on a discussion, oldest first.
+   * `discussion.comments.pagination.cursor` is accepted as `cursor`.
+   */
+  listComments(discussionId, params = {}) {
+    const query = {
+      limit: params.limit,
+      cursor: params.cursor
+    };
+    return this.client.requestCursorPage(
+      { method: "GET", path: `/discussions/${discussionId}/comments`, query },
+      query
+    );
+  }
+  /**
+   * Start a discussion on an asset version. `assetVersionId` is required.
+   * Mention someone with `{{mention:N}}` and a `mentions` entry at that index.
+   * On a document or PDF, every annotation needs a `pageNumber`.
+   *
+   * The body has no board. In a workspace that scopes comments to boards, a
+   * discussion with no board needs `asset.canManageDiscussions` at the
+   * workspace level, so a board guest gets 403 even when they can comment in
+   * their board. A timeout can create a duplicate: list before retrying.
+   */
+  async create(params) {
+    return this.client.request({
+      method: "POST",
+      path: "/discussions",
+      body: params
+    });
+  }
+  /** Add a comment. The body and mention rules match `create`. */
+  async createComment(discussionId, params) {
+    return this.client.request({
+      method: "POST",
+      path: `/discussions/${discussionId}/comments`,
+      body: params
+    });
+  }
+  /**
+   * Resolve or reopen a discussion. The response is empty, including when the
+   * discussion was already in the requested state.
+   */
+  async update(discussionId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/discussions/${discussionId}`,
+      body: params
+    });
+  }
+  /**
+   * Replace a comment's text and mentions. Only the author can edit.
+   * The response is empty, and the edit notifies no one. An edit that leaves
+   * the text and mentions as they are changes nothing and keeps `updatedAt`.
+   * Omitting `mentions`, or sending `null`, when the comment has them is 409.
+   * `[]` removes them.
+   */
+  async updateComment(discussionId, commentId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/discussions/${discussionId}/comments/${commentId}`,
+      body: params
+    });
+  }
+  /**
+   * Delete a comment. Only the author can delete. The response is empty.
+   * Deleting the last comment deletes the discussion.
+   */
+  async deleteComment(discussionId, commentId) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/discussions/${discussionId}/comments/${commentId}`
+    });
+  }
+};
+
 // src/resources/imports.ts
 var Imports = class {
   constructor(client) {
@@ -482,6 +596,30 @@ var Libraries = class {
   }
 };
 
+// src/resources/members.ts
+var Members = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List people in the workspace. Requires `members.read`.
+   * `workspace.read` does not grant it.
+   *
+   * Sort is fixed: `firstJoinedAt` ascending, then `id`.
+   * `email` without `type` searches every type. An unknown email is an empty list.
+   */
+  list(params = {}) {
+    const query = {
+      type: params.type,
+      email: params.email,
+      search: params.search,
+      limit: params.limit,
+      cursor: params.cursor
+    };
+    return this.client.requestCursorPage({ method: "GET", path: "/members", query }, query);
+  }
+};
+
 // src/resources/roles.ts
 var Roles = class {
   constructor(client) {
@@ -921,6 +1059,8 @@ var AirApi = class extends import_api_core.AirBase {
   libraries;
   tags;
   customFields;
+  discussions;
+  members;
   roles;
   imports;
   uploads;
@@ -933,6 +1073,8 @@ var AirApi = class extends import_api_core.AirBase {
     this.libraries = new Libraries(this);
     this.tags = new Tags(this);
     this.customFields = new CustomFields(this);
+    this.discussions = new Discussions(this);
+    this.members = new Members(this);
     this.roles = new Roles(this);
     this.imports = new Imports(this);
     this.uploads = new Uploads(this);
@@ -954,9 +1096,11 @@ var import_api_core2 = require("@air/api-core");
   ConnectionError,
   CursorPage,
   CustomFields,
+  Discussions,
   Imports,
   InternalServerError,
   Libraries,
+  Members,
   NotFoundError,
   PagePromise,
   PermissionError,

package/dist/index.d.cts

@@ -457,6 +457,226 @@ declare class CustomFields {
     deleteValue(customFieldId: string, valueId: string): Promise<void>;
 }
 
+/**
+ * Exactly one of `assetId` or `boardId`. `assetVersionId` requires `assetId`.
+ * The server rejects any other combination, so the type does too.
+ */
+type DiscussionListParams = DiscussionListOptions & ({
+    /** Discussions on this asset. */
+    assetId: string;
+    /** Limit the asset list to this version. */
+    assetVersionId?: string;
+    boardId?: never;
+} | {
+    /** Discussions on assets currently on this board. */
+    boardId: string;
+    assetId?: never;
+    assetVersionId?: never;
+});
+interface DiscussionListOptions extends CursorPageParams {
+    /** When set, only discussions in that resolved state. */
+    resolved?: boolean;
+    /**
+     * `lastCommentedAt` is the default and moves when someone replies.
+     * `createdAt` is the first comment and stays put.
+     */
+    sortBy?: "lastCommentedAt" | "createdAt";
+    /** `desc` is the default. */
+    sortDirection?: "asc" | "desc";
+}
+interface DiscussionCommentListParams extends CursorPageParams {
+}
+interface Discussion {
+    id: string;
+    resolved: boolean;
+    /** When the first comment was created. */
+    createdAt: string | null;
+    /** When the latest comment was created. A reply moves this. */
+    lastCommentedAt: string | null;
+    asset: {
+        id: string;
+    };
+    assetVersion: {
+        /** Asset version id. This is `assetVersionId` on create. */
+        id: string;
+        version: number;
+    };
+    /**
+     * Present only when the stored board is active and the caller can view it.
+     * Otherwise the field is omitted.
+     */
+    boardId?: string;
+    annotations: DiscussionAnnotation[];
+    /** The first 10 comments, oldest first. */
+    comments: DiscussionCommentPage;
+}
+interface DiscussionCommentPage {
+    data: DiscussionComment[];
+    pagination: {
+        hasMore: boolean;
+        cursor: string | null;
+    };
+    total: number;
+}
+interface DiscussionComment {
+    id: string;
+    discussionId: string;
+    /** Plain text with mentions rendered as `@Display Name`. */
+    body: string;
+    createdAt: string;
+    /**
+     * Equal to `createdAt` until the first edit that changes the stored text.
+     * An edit is `updatedAt !== createdAt`.
+     */
+    updatedAt: string;
+    author: DiscussionAuthor;
+    mentions: DiscussionMention[];
+}
+type DiscussionAuthor = {
+    type: "workspace_account";
+    /** Account id. The same id as `members.list` `id`. */
+    id: string;
+    displayName: string | null;
+} | {
+    type: "anonymous";
+    displayName: string | null;
+};
+/** A mention on a comment. `id` is the account id. */
+interface DiscussionMention {
+    id: string;
+    displayName: string | null;
+}
+/** A mention sent on create or edit. `accountId` is `DiscussionMention.id`. */
+interface DiscussionMentionInput {
+    accountId: string;
+}
+type DiscussionAnnotation = BoxAnnotation | PencilAnnotation;
+interface BoxAnnotation {
+    type: "box";
+    /** Seconds into a video. Omit for a still image. */
+    timestamp?: number;
+    /** Requires `timestamp`, and must be greater than or equal to it. */
+    endTimestamp?: number;
+    /** Top-left corner as fractions of the frame, from 0 to 1. */
+    coordinates: {
+        x: number;
+        y: number;
+    };
+    /** Width and height as fractions of the frame. The box must fit in the frame. */
+    dimensions: {
+        width: number;
+        height: number;
+    };
+    /** `#RRGGBB`, either case, on write. A stored annotation read back may use another color format. */
+    color: string;
+    /** Document page, from 1. Required on a document or PDF. Omit for an image or video. */
+    pageNumber?: number;
+}
+interface PencilAnnotation {
+    type: "pencil";
+    /** Seconds into a video. Omit for a still image. */
+    timestamp?: number;
+    /** Requires `timestamp`, and must be greater than or equal to it. */
+    endTimestamp?: number;
+    /** 1 to 10 lines. */
+    lines: PencilLine[];
+}
+interface PencilLine {
+    /** 2 to 1000 points, each a fraction of the frame from 0 to 1. */
+    coordinates: {
+        x: number;
+        y: number;
+    }[];
+    /** Greater than 0 and at most 1000. */
+    lineWidth: number;
+    /** `#RRGGBB`, either case, on write. A stored annotation read back may use another color format. */
+    color: string;
+    /** Document page, from 1. Required on a document or PDF. Omit for an image or video. */
+    pageNumber?: number;
+}
+interface DiscussionCreateParams {
+    assetId: string;
+    /** Required. There is no default to the current version. */
+    assetVersionId: string;
+    /** Plain text, 1 to 500 characters. Mention someone with `{{mention:N}}`. */
+    body: string;
+    /** At most 10. `null` is the same as omitting it. */
+    mentions?: DiscussionMentionInput[] | null;
+    /** At most 10. */
+    annotations?: DiscussionAnnotation[];
+}
+interface DiscussionCommentCreateParams {
+    /** Plain text, 1 to 500 characters. Mention someone with `{{mention:N}}`. */
+    body: string;
+    /** At most 10. `null` is the same as omitting it. */
+    mentions?: DiscussionMentionInput[] | null;
+}
+interface DiscussionCommentUpdateParams {
+    body: string;
+    /**
+     * Required when the stored comment has mentions. Send the mentions again to
+     * keep them, or `[]` to remove them. Omitting this field, or sending `null`,
+     * on a comment that has mentions is 409.
+     */
+    mentions?: DiscussionMentionInput[] | null;
+}
+interface DiscussionUpdateParams {
+    /** `true` resolves the discussion. `false` reopens it. */
+    resolved: boolean;
+}
+
+declare class Discussions {
+    private client;
+    constructor(client: AirBase);
+    /**
+     * List discussions on an asset or on the assets currently in a board.
+     * Exactly one of `assetId` or `boardId` is required.
+     *
+     * Pages don't overlap. With the default `lastCommentedAt` sort, a reply
+     * between pages can move a discussion, so it may repeat or be skipped. For
+     * a stable walk, use `sortBy: "createdAt"` and `sortDirection: "asc"`.
+     */
+    list(params: DiscussionListParams): PagePromise<Discussion>;
+    /** Get one discussion, including its first 10 comments. A discussion you cannot view is 404. */
+    get(discussionId: string): Promise<Discussion>;
+    /**
+     * List every comment on a discussion, oldest first.
+     * `discussion.comments.pagination.cursor` is accepted as `cursor`.
+     */
+    listComments(discussionId: string, params?: DiscussionCommentListParams): PagePromise<DiscussionComment>;
+    /**
+     * Start a discussion on an asset version. `assetVersionId` is required.
+     * Mention someone with `{{mention:N}}` and a `mentions` entry at that index.
+     * On a document or PDF, every annotation needs a `pageNumber`.
+     *
+     * The body has no board. In a workspace that scopes comments to boards, a
+     * discussion with no board needs `asset.canManageDiscussions` at the
+     * workspace level, so a board guest gets 403 even when they can comment in
+     * their board. A timeout can create a duplicate: list before retrying.
+     */
+    create(params: DiscussionCreateParams): Promise<Discussion>;
+    /** Add a comment. The body and mention rules match `create`. */
+    createComment(discussionId: string, params: DiscussionCommentCreateParams): Promise<DiscussionComment>;
+    /**
+     * Resolve or reopen a discussion. The response is empty, including when the
+     * discussion was already in the requested state.
+     */
+    update(discussionId: string, params: DiscussionUpdateParams): Promise<void>;
+    /**
+     * Replace a comment's text and mentions. Only the author can edit.
+     * The response is empty, and the edit notifies no one. An edit that leaves
+     * the text and mentions as they are changes nothing and keeps `updatedAt`.
+     * Omitting `mentions`, or sending `null`, when the comment has them is 409.
+     * `[]` removes them.
+     */
+    updateComment(discussionId: string, commentId: string, params: DiscussionCommentUpdateParams): Promise<void>;
+    /**
+     * Delete a comment. Only the author can delete. The response is empty.
+     * Deleting the last comment deletes the discussion.
+     */
+    deleteComment(discussionId: string, commentId: string): Promise<void>;
+}
+
 interface ImportCreateParams {
     sourceUrl: string;
     fileName?: string;
@@ -533,6 +753,53 @@ declare class Libraries {
     delete(libraryId: string): Promise<void>;
 }
 
+type MemberType = "member" | "guest" | "libraryMember";
+interface MemberListParams extends CursorPageParams {
+    /**
+     * Defaults to `member`. With `email` and no `type`, every type is searched,
+     * so omit it to look up an email across member, guest, and libraryMember.
+     */
+    type?: MemberType;
+    /** Exact email. Cannot be combined with `search`. An unknown email is an empty list. */
+    email?: string;
+    /** Name or email search, 1 to 100 characters. Cannot be combined with `email`. */
+    search?: string;
+}
+interface Member {
+    /** Account id. The same id as a comment mention `id` and `accountId`. */
+    id: string;
+    type: MemberType;
+    displayName: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    email: string;
+    /**
+     * The first time this person joined. A rejoin does not change it.
+     *
+     * The stored Postgres timestamp text, not ISO 8601 like the other
+     * timestamps: for example `2024-03-01 12:00:00.123456+00`. It has up to 6
+     * fraction digits with trailing zeros dropped (`12:00:00.12+00`,
+     * `12:00:00+00`), and a UTC offset (currently `+00`). Don't parse a fixed
+     * width.
+     */
+    firstJoinedAt: string;
+    /** Present when the person has an avatar URL. */
+    avatar?: string;
+}
+
+declare class Members {
+    private client;
+    constructor(client: AirBase);
+    /**
+     * List people in the workspace. Requires `members.read`.
+     * `workspace.read` does not grant it.
+     *
+     * Sort is fixed: `firstJoinedAt` ascending, then `id`.
+     * `email` without `type` searches every type. An unknown email is an empty list.
+     */
+    list(params?: MemberListParams): PagePromise<Member>;
+}
+
 interface Role {
     id: string;
     name: string;
@@ -866,6 +1133,8 @@ declare class AirApi extends AirBase {
     readonly libraries: Libraries;
     readonly tags: Tags;
     readonly customFields: CustomFields;
+    readonly discussions: Discussions;
+    readonly members: Members;
     readonly roles: Roles;
     readonly imports: Imports;
     readonly uploads: Uploads;
@@ -873,4 +1142,4 @@ declare class AirApi extends AirBase {
     constructor(options?: AirApiOptions);
 }
 
-export { type AddBoardAssetsParams, type AddGuestParams, type AddShowcaseAssetsParams, type AddShowcaseBoardsParams, type AddVersionTagParams, AirApi, type AirApiOptions, type Asset, type AssetBoardListParams, type AssetCdnLinkCreateParams, type AssetCdnLinkListResponse, type AssetCdnLinkUpdateParams, type AssetCustomFieldDateFilter, type AssetCustomFieldDateOperator, type AssetCustomFieldFilter, type AssetCustomFieldSelectFilter, type AssetCustomFieldTextFilter, type AssetCustomFieldTextOperator, type AssetCustomFieldValue, type AssetListParams, type AssetShareLink, type AssetShareLinkCreateParams, type AssetShareLinkListParams, type AssetShareLinkUpdateParams, type AssetShareLinkWriteSettings, type AssetVersion, type AssetVersionDownloadUrl, type AssetVersionListResponse, type AssetVersionUpdateParams, type AssetVersionUrls, Assets, type Board, type BoardCreateParams, type BoardListParams, type BoardShareLink, type BoardShareLinkCreateParams, type BoardShareLinkListResponse, type BoardShareLinkUpdateParams, type BoardUpdateParams, Boards, type CdnLink, type CompleteMultipartParams, type CustomField, type CustomFieldCreateParams, type CustomFieldListParams, type CustomFieldType, type CustomFieldUpdateParams, type CustomFieldValue, type CustomFieldValueCreateParams, type CustomFieldValueUpdateParams, CustomFields, type FileMeta, type FileSource, type GetPartUploadUrlParams, type GetPartUploadUrlResponse, type Guest, type GuestListParams, type GuestListResponse, type ImportCreateParams, type ImportCreateResponse, type ImportStatus, type ImportStatusResponse, Imports, type LargeUploadResponse, Libraries, type Library, type LibraryCreateParams, type LibraryListParams, type LibraryUpdateParams, type Role, type RoleListParams, type RoleListResponse, Roles, type SetBoardCustomFieldParams, type SetCustomFieldParams, type ShareLink, type ShareLinkCommentsAccess, type ShareLinkCustomFieldsAccess, type ShareLinkWriteSettings, type Showcase, type ShowcaseCreateParams, type ShowcaseListParams, type ShowcaseShareLink, type ShowcaseShareLinkStatus, type ShowcaseShareLinkUpdateParams, type ShowcaseStats, type ShowcaseUpdateParams, Showcases, type SmallUploadResponse, type SmartTag, type Tag, type TagCreateParams, type TagListParams, type TagUpdateParams, Tags, type UpdateGuestParams, type UploadCreateParams, type UploadCreateResponse, type UploadFileOptions, type UploadFileParams, type UploadFileResponse, Uploads, type Workspace, type WorkspaceListResponse, Workspaces };
+export { type AddBoardAssetsParams, type AddGuestParams, type AddShowcaseAssetsParams, type AddShowcaseBoardsParams, type AddVersionTagParams, AirApi, type AirApiOptions, type Asset, type AssetBoardListParams, type AssetCdnLinkCreateParams, type AssetCdnLinkListResponse, type AssetCdnLinkUpdateParams, type AssetCustomFieldDateFilter, type AssetCustomFieldDateOperator, type AssetCustomFieldFilter, type AssetCustomFieldSelectFilter, type AssetCustomFieldTextFilter, type AssetCustomFieldTextOperator, type AssetCustomFieldValue, type AssetListParams, type AssetShareLink, type AssetShareLinkCreateParams, type AssetShareLinkListParams, type AssetShareLinkUpdateParams, type AssetShareLinkWriteSettings, type AssetVersion, type AssetVersionDownloadUrl, type AssetVersionListResponse, type AssetVersionUpdateParams, type AssetVersionUrls, Assets, type Board, type BoardCreateParams, type BoardListParams, type BoardShareLink, type BoardShareLinkCreateParams, type BoardShareLinkListResponse, type BoardShareLinkUpdateParams, type BoardUpdateParams, Boards, type BoxAnnotation, type CdnLink, type CompleteMultipartParams, type CustomField, type CustomFieldCreateParams, type CustomFieldListParams, type CustomFieldType, type CustomFieldUpdateParams, type CustomFieldValue, type CustomFieldValueCreateParams, type CustomFieldValueUpdateParams, CustomFields, type Discussion, type DiscussionAnnotation, type DiscussionAuthor, type DiscussionComment, type DiscussionCommentCreateParams, type DiscussionCommentListParams, type DiscussionCommentPage, type DiscussionCommentUpdateParams, type DiscussionCreateParams, type DiscussionListOptions, type DiscussionListParams, type DiscussionMention, type DiscussionMentionInput, type DiscussionUpdateParams, Discussions, type FileMeta, type FileSource, type GetPartUploadUrlParams, type GetPartUploadUrlResponse, type Guest, type GuestListParams, type GuestListResponse, type ImportCreateParams, type ImportCreateResponse, type ImportStatus, type ImportStatusResponse, Imports, type LargeUploadResponse, Libraries, type Library, type LibraryCreateParams, type LibraryListParams, type LibraryUpdateParams, type Member, type MemberListParams, type MemberType, Members, type PencilAnnotation, type PencilLine, type Role, type RoleListParams, type RoleListResponse, Roles, type SetBoardCustomFieldParams, type SetCustomFieldParams, type ShareLink, type ShareLinkCommentsAccess, type ShareLinkCustomFieldsAccess, type ShareLinkWriteSettings, type Showcase, type ShowcaseCreateParams, type ShowcaseListParams, type ShowcaseShareLink, type ShowcaseShareLinkStatus, type ShowcaseShareLinkUpdateParams, type ShowcaseStats, type ShowcaseUpdateParams, Showcases, type SmallUploadResponse, type SmartTag, type Tag, type TagCreateParams, type TagListParams, type TagUpdateParams, Tags, type UpdateGuestParams, type UploadCreateParams, type UploadCreateResponse, type UploadFileOptions, type UploadFileParams, type UploadFileResponse, Uploads, type Workspace, type WorkspaceListResponse, Workspaces };

package/dist/index.d.ts

@@ -457,6 +457,226 @@ declare class CustomFields {
     deleteValue(customFieldId: string, valueId: string): Promise<void>;
 }
 
+/**
+ * Exactly one of `assetId` or `boardId`. `assetVersionId` requires `assetId`.
+ * The server rejects any other combination, so the type does too.
+ */
+type DiscussionListParams = DiscussionListOptions & ({
+    /** Discussions on this asset. */
+    assetId: string;
+    /** Limit the asset list to this version. */
+    assetVersionId?: string;
+    boardId?: never;
+} | {
+    /** Discussions on assets currently on this board. */
+    boardId: string;
+    assetId?: never;
+    assetVersionId?: never;
+});
+interface DiscussionListOptions extends CursorPageParams {
+    /** When set, only discussions in that resolved state. */
+    resolved?: boolean;
+    /**
+     * `lastCommentedAt` is the default and moves when someone replies.
+     * `createdAt` is the first comment and stays put.
+     */
+    sortBy?: "lastCommentedAt" | "createdAt";
+    /** `desc` is the default. */
+    sortDirection?: "asc" | "desc";
+}
+interface DiscussionCommentListParams extends CursorPageParams {
+}
+interface Discussion {
+    id: string;
+    resolved: boolean;
+    /** When the first comment was created. */
+    createdAt: string | null;
+    /** When the latest comment was created. A reply moves this. */
+    lastCommentedAt: string | null;
+    asset: {
+        id: string;
+    };
+    assetVersion: {
+        /** Asset version id. This is `assetVersionId` on create. */
+        id: string;
+        version: number;
+    };
+    /**
+     * Present only when the stored board is active and the caller can view it.
+     * Otherwise the field is omitted.
+     */
+    boardId?: string;
+    annotations: DiscussionAnnotation[];
+    /** The first 10 comments, oldest first. */
+    comments: DiscussionCommentPage;
+}
+interface DiscussionCommentPage {
+    data: DiscussionComment[];
+    pagination: {
+        hasMore: boolean;
+        cursor: string | null;
+    };
+    total: number;
+}
+interface DiscussionComment {
+    id: string;
+    discussionId: string;
+    /** Plain text with mentions rendered as `@Display Name`. */
+    body: string;
+    createdAt: string;
+    /**
+     * Equal to `createdAt` until the first edit that changes the stored text.
+     * An edit is `updatedAt !== createdAt`.
+     */
+    updatedAt: string;
+    author: DiscussionAuthor;
+    mentions: DiscussionMention[];
+}
+type DiscussionAuthor = {
+    type: "workspace_account";
+    /** Account id. The same id as `members.list` `id`. */
+    id: string;
+    displayName: string | null;
+} | {
+    type: "anonymous";
+    displayName: string | null;
+};
+/** A mention on a comment. `id` is the account id. */
+interface DiscussionMention {
+    id: string;
+    displayName: string | null;
+}
+/** A mention sent on create or edit. `accountId` is `DiscussionMention.id`. */
+interface DiscussionMentionInput {
+    accountId: string;
+}
+type DiscussionAnnotation = BoxAnnotation | PencilAnnotation;
+interface BoxAnnotation {
+    type: "box";
+    /** Seconds into a video. Omit for a still image. */
+    timestamp?: number;
+    /** Requires `timestamp`, and must be greater than or equal to it. */
+    endTimestamp?: number;
+    /** Top-left corner as fractions of the frame, from 0 to 1. */
+    coordinates: {
+        x: number;
+        y: number;
+    };
+    /** Width and height as fractions of the frame. The box must fit in the frame. */
+    dimensions: {
+        width: number;
+        height: number;
+    };
+    /** `#RRGGBB`, either case, on write. A stored annotation read back may use another color format. */
+    color: string;
+    /** Document page, from 1. Required on a document or PDF. Omit for an image or video. */
+    pageNumber?: number;
+}
+interface PencilAnnotation {
+    type: "pencil";
+    /** Seconds into a video. Omit for a still image. */
+    timestamp?: number;
+    /** Requires `timestamp`, and must be greater than or equal to it. */
+    endTimestamp?: number;
+    /** 1 to 10 lines. */
+    lines: PencilLine[];
+}
+interface PencilLine {
+    /** 2 to 1000 points, each a fraction of the frame from 0 to 1. */
+    coordinates: {
+        x: number;
+        y: number;
+    }[];
+    /** Greater than 0 and at most 1000. */
+    lineWidth: number;
+    /** `#RRGGBB`, either case, on write. A stored annotation read back may use another color format. */
+    color: string;
+    /** Document page, from 1. Required on a document or PDF. Omit for an image or video. */
+    pageNumber?: number;
+}
+interface DiscussionCreateParams {
+    assetId: string;
+    /** Required. There is no default to the current version. */
+    assetVersionId: string;
+    /** Plain text, 1 to 500 characters. Mention someone with `{{mention:N}}`. */
+    body: string;
+    /** At most 10. `null` is the same as omitting it. */
+    mentions?: DiscussionMentionInput[] | null;
+    /** At most 10. */
+    annotations?: DiscussionAnnotation[];
+}
+interface DiscussionCommentCreateParams {
+    /** Plain text, 1 to 500 characters. Mention someone with `{{mention:N}}`. */
+    body: string;
+    /** At most 10. `null` is the same as omitting it. */
+    mentions?: DiscussionMentionInput[] | null;
+}
+interface DiscussionCommentUpdateParams {
+    body: string;
+    /**
+     * Required when the stored comment has mentions. Send the mentions again to
+     * keep them, or `[]` to remove them. Omitting this field, or sending `null`,
+     * on a comment that has mentions is 409.
+     */
+    mentions?: DiscussionMentionInput[] | null;
+}
+interface DiscussionUpdateParams {
+    /** `true` resolves the discussion. `false` reopens it. */
+    resolved: boolean;
+}
+
+declare class Discussions {
+    private client;
+    constructor(client: AirBase);
+    /**
+     * List discussions on an asset or on the assets currently in a board.
+     * Exactly one of `assetId` or `boardId` is required.
+     *
+     * Pages don't overlap. With the default `lastCommentedAt` sort, a reply
+     * between pages can move a discussion, so it may repeat or be skipped. For
+     * a stable walk, use `sortBy: "createdAt"` and `sortDirection: "asc"`.
+     */
+    list(params: DiscussionListParams): PagePromise<Discussion>;
+    /** Get one discussion, including its first 10 comments. A discussion you cannot view is 404. */
+    get(discussionId: string): Promise<Discussion>;
+    /**
+     * List every comment on a discussion, oldest first.
+     * `discussion.comments.pagination.cursor` is accepted as `cursor`.
+     */
+    listComments(discussionId: string, params?: DiscussionCommentListParams): PagePromise<DiscussionComment>;
+    /**
+     * Start a discussion on an asset version. `assetVersionId` is required.
+     * Mention someone with `{{mention:N}}` and a `mentions` entry at that index.
+     * On a document or PDF, every annotation needs a `pageNumber`.
+     *
+     * The body has no board. In a workspace that scopes comments to boards, a
+     * discussion with no board needs `asset.canManageDiscussions` at the
+     * workspace level, so a board guest gets 403 even when they can comment in
+     * their board. A timeout can create a duplicate: list before retrying.
+     */
+    create(params: DiscussionCreateParams): Promise<Discussion>;
+    /** Add a comment. The body and mention rules match `create`. */
+    createComment(discussionId: string, params: DiscussionCommentCreateParams): Promise<DiscussionComment>;
+    /**
+     * Resolve or reopen a discussion. The response is empty, including when the
+     * discussion was already in the requested state.
+     */
+    update(discussionId: string, params: DiscussionUpdateParams): Promise<void>;
+    /**
+     * Replace a comment's text and mentions. Only the author can edit.
+     * The response is empty, and the edit notifies no one. An edit that leaves
+     * the text and mentions as they are changes nothing and keeps `updatedAt`.
+     * Omitting `mentions`, or sending `null`, when the comment has them is 409.
+     * `[]` removes them.
+     */
+    updateComment(discussionId: string, commentId: string, params: DiscussionCommentUpdateParams): Promise<void>;
+    /**
+     * Delete a comment. Only the author can delete. The response is empty.
+     * Deleting the last comment deletes the discussion.
+     */
+    deleteComment(discussionId: string, commentId: string): Promise<void>;
+}
+
 interface ImportCreateParams {
     sourceUrl: string;
     fileName?: string;
@@ -533,6 +753,53 @@ declare class Libraries {
     delete(libraryId: string): Promise<void>;
 }
 
+type MemberType = "member" | "guest" | "libraryMember";
+interface MemberListParams extends CursorPageParams {
+    /**
+     * Defaults to `member`. With `email` and no `type`, every type is searched,
+     * so omit it to look up an email across member, guest, and libraryMember.
+     */
+    type?: MemberType;
+    /** Exact email. Cannot be combined with `search`. An unknown email is an empty list. */
+    email?: string;
+    /** Name or email search, 1 to 100 characters. Cannot be combined with `email`. */
+    search?: string;
+}
+interface Member {
+    /** Account id. The same id as a comment mention `id` and `accountId`. */
+    id: string;
+    type: MemberType;
+    displayName: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    email: string;
+    /**
+     * The first time this person joined. A rejoin does not change it.
+     *
+     * The stored Postgres timestamp text, not ISO 8601 like the other
+     * timestamps: for example `2024-03-01 12:00:00.123456+00`. It has up to 6
+     * fraction digits with trailing zeros dropped (`12:00:00.12+00`,
+     * `12:00:00+00`), and a UTC offset (currently `+00`). Don't parse a fixed
+     * width.
+     */
+    firstJoinedAt: string;
+    /** Present when the person has an avatar URL. */
+    avatar?: string;
+}
+
+declare class Members {
+    private client;
+    constructor(client: AirBase);
+    /**
+     * List people in the workspace. Requires `members.read`.
+     * `workspace.read` does not grant it.
+     *
+     * Sort is fixed: `firstJoinedAt` ascending, then `id`.
+     * `email` without `type` searches every type. An unknown email is an empty list.
+     */
+    list(params?: MemberListParams): PagePromise<Member>;
+}
+
 interface Role {
     id: string;
     name: string;
@@ -866,6 +1133,8 @@ declare class AirApi extends AirBase {
     readonly libraries: Libraries;
     readonly tags: Tags;
     readonly customFields: CustomFields;
+    readonly discussions: Discussions;
+    readonly members: Members;
     readonly roles: Roles;
     readonly imports: Imports;
     readonly uploads: Uploads;
@@ -873,4 +1142,4 @@ declare class AirApi extends AirBase {
     constructor(options?: AirApiOptions);
 }
 
-export { type AddBoardAssetsParams, type AddGuestParams, type AddShowcaseAssetsParams, type AddShowcaseBoardsParams, type AddVersionTagParams, AirApi, type AirApiOptions, type Asset, type AssetBoardListParams, type AssetCdnLinkCreateParams, type AssetCdnLinkListResponse, type AssetCdnLinkUpdateParams, type AssetCustomFieldDateFilter, type AssetCustomFieldDateOperator, type AssetCustomFieldFilter, type AssetCustomFieldSelectFilter, type AssetCustomFieldTextFilter, type AssetCustomFieldTextOperator, type AssetCustomFieldValue, type AssetListParams, type AssetShareLink, type AssetShareLinkCreateParams, type AssetShareLinkListParams, type AssetShareLinkUpdateParams, type AssetShareLinkWriteSettings, type AssetVersion, type AssetVersionDownloadUrl, type AssetVersionListResponse, type AssetVersionUpdateParams, type AssetVersionUrls, Assets, type Board, type BoardCreateParams, type BoardListParams, type BoardShareLink, type BoardShareLinkCreateParams, type BoardShareLinkListResponse, type BoardShareLinkUpdateParams, type BoardUpdateParams, Boards, type CdnLink, type CompleteMultipartParams, type CustomField, type CustomFieldCreateParams, type CustomFieldListParams, type CustomFieldType, type CustomFieldUpdateParams, type CustomFieldValue, type CustomFieldValueCreateParams, type CustomFieldValueUpdateParams, CustomFields, type FileMeta, type FileSource, type GetPartUploadUrlParams, type GetPartUploadUrlResponse, type Guest, type GuestListParams, type GuestListResponse, type ImportCreateParams, type ImportCreateResponse, type ImportStatus, type ImportStatusResponse, Imports, type LargeUploadResponse, Libraries, type Library, type LibraryCreateParams, type LibraryListParams, type LibraryUpdateParams, type Role, type RoleListParams, type RoleListResponse, Roles, type SetBoardCustomFieldParams, type SetCustomFieldParams, type ShareLink, type ShareLinkCommentsAccess, type ShareLinkCustomFieldsAccess, type ShareLinkWriteSettings, type Showcase, type ShowcaseCreateParams, type ShowcaseListParams, type ShowcaseShareLink, type ShowcaseShareLinkStatus, type ShowcaseShareLinkUpdateParams, type ShowcaseStats, type ShowcaseUpdateParams, Showcases, type SmallUploadResponse, type SmartTag, type Tag, type TagCreateParams, type TagListParams, type TagUpdateParams, Tags, type UpdateGuestParams, type UploadCreateParams, type UploadCreateResponse, type UploadFileOptions, type UploadFileParams, type UploadFileResponse, Uploads, type Workspace, type WorkspaceListResponse, Workspaces };
+export { type AddBoardAssetsParams, type AddGuestParams, type AddShowcaseAssetsParams, type AddShowcaseBoardsParams, type AddVersionTagParams, AirApi, type AirApiOptions, type Asset, type AssetBoardListParams, type AssetCdnLinkCreateParams, type AssetCdnLinkListResponse, type AssetCdnLinkUpdateParams, type AssetCustomFieldDateFilter, type AssetCustomFieldDateOperator, type AssetCustomFieldFilter, type AssetCustomFieldSelectFilter, type AssetCustomFieldTextFilter, type AssetCustomFieldTextOperator, type AssetCustomFieldValue, type AssetListParams, type AssetShareLink, type AssetShareLinkCreateParams, type AssetShareLinkListParams, type AssetShareLinkUpdateParams, type AssetShareLinkWriteSettings, type AssetVersion, type AssetVersionDownloadUrl, type AssetVersionListResponse, type AssetVersionUpdateParams, type AssetVersionUrls, Assets, type Board, type BoardCreateParams, type BoardListParams, type BoardShareLink, type BoardShareLinkCreateParams, type BoardShareLinkListResponse, type BoardShareLinkUpdateParams, type BoardUpdateParams, Boards, type BoxAnnotation, type CdnLink, type CompleteMultipartParams, type CustomField, type CustomFieldCreateParams, type CustomFieldListParams, type CustomFieldType, type CustomFieldUpdateParams, type CustomFieldValue, type CustomFieldValueCreateParams, type CustomFieldValueUpdateParams, CustomFields, type Discussion, type DiscussionAnnotation, type DiscussionAuthor, type DiscussionComment, type DiscussionCommentCreateParams, type DiscussionCommentListParams, type DiscussionCommentPage, type DiscussionCommentUpdateParams, type DiscussionCreateParams, type DiscussionListOptions, type DiscussionListParams, type DiscussionMention, type DiscussionMentionInput, type DiscussionUpdateParams, Discussions, type FileMeta, type FileSource, type GetPartUploadUrlParams, type GetPartUploadUrlResponse, type Guest, type GuestListParams, type GuestListResponse, type ImportCreateParams, type ImportCreateResponse, type ImportStatus, type ImportStatusResponse, Imports, type LargeUploadResponse, Libraries, type Library, type LibraryCreateParams, type LibraryListParams, type LibraryUpdateParams, type Member, type MemberListParams, type MemberType, Members, type PencilAnnotation, type PencilLine, type Role, type RoleListParams, type RoleListResponse, Roles, type SetBoardCustomFieldParams, type SetCustomFieldParams, type ShareLink, type ShareLinkCommentsAccess, type ShareLinkCustomFieldsAccess, type ShareLinkWriteSettings, type Showcase, type ShowcaseCreateParams, type ShowcaseListParams, type ShowcaseShareLink, type ShowcaseShareLinkStatus, type ShowcaseShareLinkUpdateParams, type ShowcaseStats, type ShowcaseUpdateParams, Showcases, type SmallUploadResponse, type SmartTag, type Tag, type TagCreateParams, type TagListParams, type TagUpdateParams, Tags, type UpdateGuestParams, type UploadCreateParams, type UploadCreateResponse, type UploadFileOptions, type UploadFileParams, type UploadFileResponse, Uploads, type Workspace, type WorkspaceListResponse, Workspaces };

package/dist/index.js

@@ -356,6 +356,118 @@ var CustomFields = class {
   }
 };
 
+// src/resources/discussions.ts
+var Discussions = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List discussions on an asset or on the assets currently in a board.
+   * Exactly one of `assetId` or `boardId` is required.
+   *
+   * Pages don't overlap. With the default `lastCommentedAt` sort, a reply
+   * between pages can move a discussion, so it may repeat or be skipped. For
+   * a stable walk, use `sortBy: "createdAt"` and `sortDirection: "asc"`.
+   */
+  list(params) {
+    const query = {
+      assetId: params.assetId,
+      assetVersionId: params.assetVersionId,
+      boardId: params.boardId,
+      resolved: params.resolved,
+      sortBy: params.sortBy,
+      sortDirection: params.sortDirection,
+      limit: params.limit,
+      cursor: params.cursor
+    };
+    return this.client.requestCursorPage(
+      { method: "GET", path: "/discussions", query },
+      query
+    );
+  }
+  /** Get one discussion, including its first 10 comments. A discussion you cannot view is 404. */
+  async get(discussionId) {
+    return this.client.request({
+      method: "GET",
+      path: `/discussions/${discussionId}`
+    });
+  }
+  /**
+   * List every comment on a discussion, oldest first.
+   * `discussion.comments.pagination.cursor` is accepted as `cursor`.
+   */
+  listComments(discussionId, params = {}) {
+    const query = {
+      limit: params.limit,
+      cursor: params.cursor
+    };
+    return this.client.requestCursorPage(
+      { method: "GET", path: `/discussions/${discussionId}/comments`, query },
+      query
+    );
+  }
+  /**
+   * Start a discussion on an asset version. `assetVersionId` is required.
+   * Mention someone with `{{mention:N}}` and a `mentions` entry at that index.
+   * On a document or PDF, every annotation needs a `pageNumber`.
+   *
+   * The body has no board. In a workspace that scopes comments to boards, a
+   * discussion with no board needs `asset.canManageDiscussions` at the
+   * workspace level, so a board guest gets 403 even when they can comment in
+   * their board. A timeout can create a duplicate: list before retrying.
+   */
+  async create(params) {
+    return this.client.request({
+      method: "POST",
+      path: "/discussions",
+      body: params
+    });
+  }
+  /** Add a comment. The body and mention rules match `create`. */
+  async createComment(discussionId, params) {
+    return this.client.request({
+      method: "POST",
+      path: `/discussions/${discussionId}/comments`,
+      body: params
+    });
+  }
+  /**
+   * Resolve or reopen a discussion. The response is empty, including when the
+   * discussion was already in the requested state.
+   */
+  async update(discussionId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/discussions/${discussionId}`,
+      body: params
+    });
+  }
+  /**
+   * Replace a comment's text and mentions. Only the author can edit.
+   * The response is empty, and the edit notifies no one. An edit that leaves
+   * the text and mentions as they are changes nothing and keeps `updatedAt`.
+   * Omitting `mentions`, or sending `null`, when the comment has them is 409.
+   * `[]` removes them.
+   */
+  async updateComment(discussionId, commentId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/discussions/${discussionId}/comments/${commentId}`,
+      body: params
+    });
+  }
+  /**
+   * Delete a comment. Only the author can delete. The response is empty.
+   * Deleting the last comment deletes the discussion.
+   */
+  async deleteComment(discussionId, commentId) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/discussions/${discussionId}/comments/${commentId}`
+    });
+  }
+};
+
 // src/resources/imports.ts
 var Imports = class {
   constructor(client) {
@@ -420,6 +532,30 @@ var Libraries = class {
   }
 };
 
+// src/resources/members.ts
+var Members = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List people in the workspace. Requires `members.read`.
+   * `workspace.read` does not grant it.
+   *
+   * Sort is fixed: `firstJoinedAt` ascending, then `id`.
+   * `email` without `type` searches every type. An unknown email is an empty list.
+   */
+  list(params = {}) {
+    const query = {
+      type: params.type,
+      email: params.email,
+      search: params.search,
+      limit: params.limit,
+      cursor: params.cursor
+    };
+    return this.client.requestCursorPage({ method: "GET", path: "/members", query }, query);
+  }
+};
+
 // src/resources/roles.ts
 var Roles = class {
   constructor(client) {
@@ -859,6 +995,8 @@ var AirApi = class extends AirBase {
   libraries;
   tags;
   customFields;
+  discussions;
+  members;
   roles;
   imports;
   uploads;
@@ -871,6 +1009,8 @@ var AirApi = class extends AirBase {
     this.libraries = new Libraries(this);
     this.tags = new Tags(this);
     this.customFields = new CustomFields(this);
+    this.discussions = new Discussions(this);
+    this.members = new Members(this);
     this.roles = new Roles(this);
     this.imports = new Imports(this);
     this.uploads = new Uploads(this);
@@ -908,9 +1048,11 @@ export {
   ConnectionError,
   CursorPage,
   CustomFields,
+  Discussions,
   Imports,
   InternalServerError,
   Libraries,
+  Members,
   NotFoundError,
   PagePromise,
   PermissionError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@air/api-rest",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Typed REST client for Air API",
   "main": "./dist/index.cjs",
@@ -29,7 +29,7 @@
     "clean": "rm -rf dist .tsc-out tsconfig.tsbuildinfo"
   },
   "dependencies": {
-    "@air/api-core": "0.10.0"
+    "@air/api-core": "0.11.0"
   },
   "engines": {
     "node": ">=18"