@air/api-rest 0.9.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, 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,10 @@ npm install @air/api-rest
 
 ## What's included
 
-- Resource classes: `BoardsResource`, `AssetsResource`, `TagsResource`, `CustomFieldsResource`, `UploadsResource`, `ImportsResource`, `RolesResource`
+- 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
 - Full TypeScript types for all API request/response shapes

package/dist/index.cjs

@@ -40,14 +40,17 @@ __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,
   RateLimitError: () => import_api_core2.RateLimitError,
   Roles: () => Roles,
+  Showcases: () => Showcases,
   Tags: () => Tags,
   TimeoutError: () => import_api_core2.TimeoutError,
   Uploads: () => Uploads,
@@ -99,6 +102,7 @@ var Assets = class {
       limit: params.limit,
       cursor: params.cursor,
       parentBoardId: params.parentBoardId,
+      showcaseId: params.showcaseId,
       search: params.search
     };
     if (params.includeNestedAssets !== void 0) {
@@ -248,6 +252,7 @@ var Boards = class {
       cursor: params.cursor,
       name: params.name,
       parentBoardId: params.parentBoardId,
+      showcaseId: params.showcaseId,
       libraryId: params.libraryId,
       inGeneralLibrary: params.inGeneralLibrary
     };
@@ -415,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) {
@@ -479,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) {
@@ -494,6 +635,137 @@ var Roles = class {
   }
 };
 
+// src/resources/showcases.ts
+var Showcases = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List the showcases the caller can see.
+   *
+   * A role that can view every showcase in the workspace sees all of them.
+   * Otherwise only the showcases that caller owns are returned. Showcases
+   * without a share link are omitted; read those with `get`. Sub-pages are
+   * not listed separately.
+   *
+   * Requires the `showcases.read` and `share_links.read` OAuth scopes.
+   */
+  list(params = {}) {
+    const query = {
+      limit: params.limit,
+      cursor: params.cursor,
+      search: params.search,
+      status: params.status
+    };
+    return this.client.requestCursorPage(
+      { method: "GET", path: "/showcases", query },
+      query
+    );
+  }
+  /**
+   * Get a showcase and its share link. `shareLink` is null when the
+   * showcase has none.
+   *
+   * Requires the `showcases.read` and `share_links.read` OAuth scopes.
+   */
+  async get(showcaseId) {
+    return this.client.request({
+      method: "GET",
+      path: `/showcases/${showcaseId}`
+    });
+  }
+  /**
+   * Create a showcase and its share link in one step. The result includes
+   * the link. Create does not take items.
+   *
+   * Requires the `showcases.write` and `share_links.write` OAuth scopes.
+   */
+  async create(params) {
+    return this.client.request({
+      method: "POST",
+      path: "/showcases",
+      body: params
+    });
+  }
+  /**
+   * Rename a showcase or change its description. Only the fields you send
+   * change. Returns no body.
+   *
+   * Requires the `showcases.write` OAuth scope.
+   */
+  async update(showcaseId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/showcases/${showcaseId}`,
+      body: params
+    });
+  }
+  /**
+   * Change the settings of a showcase's share link. Only the settings you
+   * send change. Send `password: null` or `expiresAt: null` to remove them.
+   * Returns no body.
+   *
+   * Requires the `share_links.write` and `showcases.read` OAuth scopes.
+   */
+  async updateShareLink(showcaseId, shareLinkId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/showcases/${showcaseId}/share-links/${shareLinkId}`,
+      body: params
+    });
+  }
+  /**
+   * Add assets to a showcase. Assets already in it are skipped. Returns no
+   * body. List them with `assets.list({ showcaseId })`.
+   *
+   * Requires the `showcases.write` and `assets.read` OAuth scopes.
+   */
+  async addAssets(showcaseId, params) {
+    return this.client.request({
+      method: "POST",
+      path: `/showcases/${showcaseId}/assets`,
+      body: params
+    });
+  }
+  /**
+   * Remove an asset from a showcase. The asset itself is not deleted.
+   * Removing an asset that is not in the showcase succeeds. Returns no body.
+   *
+   * Requires the `showcases.write` OAuth scope.
+   */
+  async removeAsset(showcaseId, assetId) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/showcases/${showcaseId}/assets/${assetId}`
+    });
+  }
+  /**
+   * Add boards to a showcase. Boards already in it are skipped. Returns no
+   * body. List them with `boards.list({ showcaseId })`.
+   *
+   * Requires the `showcases.write` and `boards.read` OAuth scopes.
+   */
+  async addBoards(showcaseId, params) {
+    return this.client.request({
+      method: "POST",
+      path: `/showcases/${showcaseId}/boards`,
+      body: params
+    });
+  }
+  /**
+   * Remove a board from a showcase. The board itself is not deleted.
+   * Removing a board that is not in the showcase succeeds. Returns no body.
+   *
+   * Requires the `showcases.write` OAuth scope.
+   */
+  async removeBoard(showcaseId, boardId) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/showcases/${showcaseId}/boards/${boardId}`
+    });
+  }
+};
+
 // src/resources/tags.ts
 var Tags = class {
   constructor(client) {
@@ -783,9 +1055,12 @@ var Workspaces = class {
 var AirApi = class extends import_api_core.AirBase {
   assets;
   boards;
+  showcases;
   libraries;
   tags;
   customFields;
+  discussions;
+  members;
   roles;
   imports;
   uploads;
@@ -794,9 +1069,12 @@ var AirApi = class extends import_api_core.AirBase {
     super(options);
     this.assets = new Assets(this);
     this.boards = new Boards(this);
+    this.showcases = new Showcases(this);
     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);
@@ -818,14 +1096,17 @@ var import_api_core2 = require("@air/api-core");
   ConnectionError,
   CursorPage,
   CustomFields,
+  Discussions,
   Imports,
   InternalServerError,
   Libraries,
+  Members,
   NotFoundError,
   PagePromise,
   PermissionError,
   RateLimitError,
   Roles,
+  Showcases,
   Tags,
   TimeoutError,
   Uploads,