@air/api-rest 0.8.0 → 0.10.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, uploads, imports, roles) and their TypeScript types. It builds on `@air/api-core` for HTTP transport.
 
 ## Installation
 
@@ -20,7 +20,8 @@ npm install @air/api-rest
 
 ## What's included
 
-- Resource classes: `BoardsResource`, `AssetsResource`, `TagsResource`, `CustomFieldsResource`, `UploadsResource`, `ImportsResource`, `RolesResource`
+- Resource classes: `Boards`, `Showcases`, `Assets`, `Tags`, `CustomFields`, `Uploads`, `Imports`, `Roles`
+- 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

@@ -48,6 +48,7 @@ __export(index_exports, {
   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 +100,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 +250,7 @@ var Boards = class {
       cursor: params.cursor,
       name: params.name,
       parentBoardId: params.parentBoardId,
+      showcaseId: params.showcaseId,
       libraryId: params.libraryId,
       inGeneralLibrary: params.inGeneralLibrary
     };
@@ -494,6 +497,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,6 +917,7 @@ var Workspaces = class {
 var AirApi = class extends import_api_core.AirBase {
   assets;
   boards;
+  showcases;
   libraries;
   tags;
   customFields;
@@ -794,6 +929,7 @@ 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);
@@ -826,6 +962,7 @@ var import_api_core2 = require("@air/api-core");
   PermissionError,
   RateLimitError,
   Roles,
+  Showcases,
   Tags,
   TimeoutError,
   Uploads,

package/dist/index.d.cts

@@ -82,6 +82,19 @@ interface AssetCustomFieldDateFilter {
 type AssetCustomFieldFilter = string | AssetCustomFieldSelectFilter | AssetCustomFieldTextFilter | AssetCustomFieldDateFilter;
 interface AssetListParams extends CursorPageParams {
     parentBoardId?: string;
+    /**
+     * Only return assets added to this showcase. With `includeNestedAssets`,
+     * also returns the assets inside the boards added to it. Items on the
+     * showcase's sub-pages are not returned. Combining with `parentBoardId`
+     * or `semantic: true` is rejected with 400. An unknown showcase is 404;
+     * one the caller cannot view is 403.
+     */
+    showcaseId?: string;
+    /**
+     * With `parentBoardId`, return assets from nested sub-boards. With
+     * `showcaseId`, also return assets inside the boards added to the
+     * showcase. Requires one of those filters.
+     */
     includeNestedAssets?: boolean;
     tag?: string | string[];
     /**
@@ -111,7 +124,7 @@ interface AssetListParams extends CursorPageParams {
      * When true, `search` is used for semantic search via AI embeddings.
      * Requires a non-blank `search` value and Semantic Search enabled on the workspace.
      * Returns a single page of results ordered by relevance. Combining with `tag`,
-     * `customField`, `createdAt`, or `cursor` is rejected by the API with 400.
+     * `customField`, `createdAt`, `cursor`, or `showcaseId` is rejected by the API with 400.
      */
     semantic?: boolean;
     "createdAt[gte]"?: string;
@@ -181,6 +194,13 @@ interface Board {
 interface BoardListParams extends CursorPageParams {
     name?: string;
     parentBoardId?: string;
+    /**
+     * Only return boards added to this showcase. Boards on the showcase's
+     * sub-pages are not returned. Combining with `parentBoardId`, `libraryId`,
+     * or `inGeneralLibrary` is rejected with 400. An unknown showcase is 404;
+     * one the caller cannot view is 403.
+     */
+    showcaseId?: string;
     /**
      * Select filters only, as `fieldId:valueId`. Repeats of one field are OR, and
      * different fields are AND. Plain-text and date operators are rejected with
@@ -189,13 +209,14 @@ interface BoardListParams extends CursorPageParams {
     customField?: string | string[];
     /**
      * Only return boards in this library. Mutually exclusive with
-     * `inGeneralLibrary` — passing both results in a `400` (BadRequestError).
+     * `inGeneralLibrary` and with `showcaseId`. Combining either pair results
+     * in a `400` (BadRequestError).
      */
     libraryId?: string;
     /**
      * Only return boards in the General library (boards not in any real library).
-     * Mutually exclusive with `libraryId` — passing both results in a `400`
-     * (BadRequestError).
+     * Mutually exclusive with `libraryId` and with `showcaseId`. Combining
+     * either pair results in a `400` (BadRequestError).
      */
     inGeneralLibrary?: boolean;
 }
@@ -238,12 +259,18 @@ interface GuestListResponse {
     data: Guest[];
 }
 
-/** Visitor comment access on a share link. */
+/**
+ * Visitor comment access on a share link.
+ * `allowed` lets anyone with the link post comments.
+ */
 type ShareLinkCommentsAccess = "hidden" | "read_only" | "allowed";
-/** Visitor custom field access on a share link. */
+/**
+ * Visitor custom field access on a share link.
+ * `editable` lets anyone with the link change custom field values.
+ */
 type ShareLinkCustomFieldsAccess = "hidden" | "read_only" | "editable";
 /**
- * Public share link fields shared by assets and boards.
+ * Public share link fields shared by assets, boards, and showcases.
  * `url` is the link to give to people. The password is never returned;
  * `hasPassword` says whether one is set. Disabled links are included
  * with `active: false`.
@@ -292,10 +319,31 @@ interface BoardShareLinkListResponse extends CursorPageResponse<BoardShareLink>
  * Settings accepted on share-link create and update.
  * Omitted fields follow the workspace Share Link Defaults on create,
  * and stay unchanged on update.
+ *
+ * `password` is write only; reads return `hasPassword`. `null` clears
+ * `password` and `expiresAt`. An empty password is rejected. `expiresAt`
+ * must be an ISO 8601 date-time in the future.
+ *
+ * Turning `password`, `expiresAt`, `requireAccount`, `comments`, or
+ * `customFields` on needs the workspace `shareLinks` add-on. Otherwise the
+ * API returns 422 `ADDON_DISABLED` and applies nothing in the request.
+ * Raising `comments` from `read_only` to `allowed`, or `customFields` from
+ * `read_only` to `editable`, counts as turning it on, so a link that already
+ * shows comments or custom fields can still get that 422.
+ * `extra.settings` names the rejected settings, and uses `expiration` for
+ * `expiresAt`. Re-sending a value the link already has, changing an existing
+ * password or expiration, and turning a setting off are accepted.
  */
 interface ShareLinkWriteSettings {
     active?: boolean;
     allowDownload?: boolean;
+    /** Write only. `null` removes the password. */
+    password?: string | null;
+    /** ISO 8601 date-time in the future. `null` removes the expiration. */
+    expiresAt?: string | null;
+    requireAccount?: boolean;
+    comments?: ShareLinkCommentsAccess;
+    customFields?: ShareLinkCustomFieldsAccess;
 }
 /** Asset links also accept `showAllVersions`. */
 interface AssetShareLinkWriteSettings extends ShareLinkWriteSettings {
@@ -505,6 +553,179 @@ declare class Roles {
     list(params?: RoleListParams): Promise<Role[]>;
 }
 
+/**
+ * Filter for the state of a showcase's share link.
+ * `active`: the link is enabled. `inactive`: the link is disabled.
+ * `expired`: the link's expiration date has passed.
+ */
+type ShowcaseShareLinkStatus = "active" | "inactive" | "expired";
+/** How many items the showcase holds. */
+interface ShowcaseStats {
+    assetCount: number;
+    fileCount: number;
+    boardCount: number;
+}
+/**
+ * Showcase share link. A showcase has at most one, and it uses the same
+ * fields as a board share link.
+ */
+type ShowcaseShareLink = ShareLink;
+/**
+ * A showcase and its share link.
+ *
+ * `shareLink` is null when the showcase has no link. `get` returns those
+ * showcases. `list` omits them. Every showcase created through `create`
+ * has a link.
+ *
+ * Sub-pages are not part of this object. A showcase that has them still
+ * comes back as one showcase, and item lists return only its top-level items.
+ */
+interface Showcase {
+    id: string;
+    name: string;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
+    stats: ShowcaseStats;
+    shareLink: ShowcaseShareLink | null;
+}
+/**
+ * Query for `GET /showcases`.
+ * The API defaults `limit` to 12 and treats values above 200 as 200.
+ * An empty `search`, an unknown `status`, a `limit` that is not a positive
+ * integer, or a cursor this endpoint did not issue is 400.
+ */
+interface ShowcaseListParams extends CursorPageParams {
+    /** Only return showcases whose name contains this text. */
+    search?: string;
+    /** Filter by the state of the showcase's share link. */
+    status?: ShowcaseShareLinkStatus;
+}
+/**
+ * Body for `POST /showcases`.
+ * Creates the showcase and its share link together. It does not take items;
+ * add them with `addAssets` and `addBoards`. Omitted `shareLink` settings
+ * follow the workspace Share Link Defaults. The same paid settings as a
+ * board link apply, including `422` `ADDON_DISABLED` when the plan does not
+ * include one that the request turns on. If the link cannot be created, the
+ * showcase is not created either.
+ */
+interface ShowcaseCreateParams {
+    name: string;
+    /** Empty string is rejected. Omit the field to leave the description unset. */
+    description?: string;
+    shareLink?: ShareLinkWriteSettings;
+}
+/**
+ * Body for `PATCH /showcases/:showcaseId`.
+ * Only the fields you send change. `null` removes the description. An empty
+ * or null `name` is rejected. An empty body changes nothing.
+ */
+interface ShowcaseUpdateParams {
+    name?: string;
+    description?: string | null;
+}
+/** Body for `POST /showcases/:showcaseId/assets`. `assetIds` must be non-empty. */
+interface AddShowcaseAssetsParams {
+    assetIds: string[];
+}
+/** Body for `POST /showcases/:showcaseId/boards`. `boardIds` must be non-empty. */
+interface AddShowcaseBoardsParams {
+    boardIds: string[];
+}
+/**
+ * Body for `PATCH /showcases/:showcaseId/share-links/:shareLinkId`.
+ * Same settings as a board share link.
+ */
+type ShowcaseShareLinkUpdateParams = ShareLinkWriteSettings;
+
+/**
+ * Showcases. A showcase is a collection with one share link.
+ *
+ * `create` makes the showcase and its share link together. The result
+ * includes the link, and the showcase starts empty. Add items with
+ * `addAssets` and `addBoards`.
+ *
+ * Sub-pages are not exposed. Item lists return only a showcase's top-level
+ * items, and a sub-page id is not found on these routes.
+ *
+ * An unknown, trashed, or other-workspace id is 404. An item or showcase
+ * the caller cannot view is 403. Adding an item that is already in the
+ * showcase, or removing one that is not, succeeds and returns 204.
+ */
+declare class Showcases {
+    private client;
+    constructor(client: AirBase);
+    /**
+     * 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?: ShowcaseListParams): PagePromise<Showcase>;
+    /**
+     * 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.
+     */
+    get(showcaseId: string): Promise<Showcase>;
+    /**
+     * 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.
+     */
+    create(params: ShowcaseCreateParams): Promise<Showcase>;
+    /**
+     * Rename a showcase or change its description. Only the fields you send
+     * change. Returns no body.
+     *
+     * Requires the `showcases.write` OAuth scope.
+     */
+    update(showcaseId: string, params: ShowcaseUpdateParams): Promise<void>;
+    /**
+     * 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.
+     */
+    updateShareLink(showcaseId: string, shareLinkId: string, params: ShowcaseShareLinkUpdateParams): Promise<void>;
+    /**
+     * 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.
+     */
+    addAssets(showcaseId: string, params: AddShowcaseAssetsParams): Promise<void>;
+    /**
+     * 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.
+     */
+    removeAsset(showcaseId: string, assetId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    addBoards(showcaseId: string, params: AddShowcaseBoardsParams): Promise<void>;
+    /**
+     * 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.
+     */
+    removeBoard(showcaseId: string, boardId: string): Promise<void>;
+}
+
 declare class Tags {
     private client;
     constructor(client: AirBase);
@@ -641,6 +862,7 @@ interface AirApiOptions extends AirBaseOptions {
 declare class AirApi extends AirBase {
     readonly assets: Assets;
     readonly boards: Boards;
+    readonly showcases: Showcases;
     readonly libraries: Libraries;
     readonly tags: Tags;
     readonly customFields: CustomFields;
@@ -651,4 +873,4 @@ declare class AirApi extends AirBase {
     constructor(options?: AirApiOptions);
 }
 
-export { type AddBoardAssetsParams, type AddGuestParams, 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 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 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 };

package/dist/index.d.ts

@@ -82,6 +82,19 @@ interface AssetCustomFieldDateFilter {
 type AssetCustomFieldFilter = string | AssetCustomFieldSelectFilter | AssetCustomFieldTextFilter | AssetCustomFieldDateFilter;
 interface AssetListParams extends CursorPageParams {
     parentBoardId?: string;
+    /**
+     * Only return assets added to this showcase. With `includeNestedAssets`,
+     * also returns the assets inside the boards added to it. Items on the
+     * showcase's sub-pages are not returned. Combining with `parentBoardId`
+     * or `semantic: true` is rejected with 400. An unknown showcase is 404;
+     * one the caller cannot view is 403.
+     */
+    showcaseId?: string;
+    /**
+     * With `parentBoardId`, return assets from nested sub-boards. With
+     * `showcaseId`, also return assets inside the boards added to the
+     * showcase. Requires one of those filters.
+     */
     includeNestedAssets?: boolean;
     tag?: string | string[];
     /**
@@ -111,7 +124,7 @@ interface AssetListParams extends CursorPageParams {
      * When true, `search` is used for semantic search via AI embeddings.
      * Requires a non-blank `search` value and Semantic Search enabled on the workspace.
      * Returns a single page of results ordered by relevance. Combining with `tag`,
-     * `customField`, `createdAt`, or `cursor` is rejected by the API with 400.
+     * `customField`, `createdAt`, `cursor`, or `showcaseId` is rejected by the API with 400.
      */
     semantic?: boolean;
     "createdAt[gte]"?: string;
@@ -181,6 +194,13 @@ interface Board {
 interface BoardListParams extends CursorPageParams {
     name?: string;
     parentBoardId?: string;
+    /**
+     * Only return boards added to this showcase. Boards on the showcase's
+     * sub-pages are not returned. Combining with `parentBoardId`, `libraryId`,
+     * or `inGeneralLibrary` is rejected with 400. An unknown showcase is 404;
+     * one the caller cannot view is 403.
+     */
+    showcaseId?: string;
     /**
      * Select filters only, as `fieldId:valueId`. Repeats of one field are OR, and
      * different fields are AND. Plain-text and date operators are rejected with
@@ -189,13 +209,14 @@ interface BoardListParams extends CursorPageParams {
     customField?: string | string[];
     /**
      * Only return boards in this library. Mutually exclusive with
-     * `inGeneralLibrary` — passing both results in a `400` (BadRequestError).
+     * `inGeneralLibrary` and with `showcaseId`. Combining either pair results
+     * in a `400` (BadRequestError).
      */
     libraryId?: string;
     /**
      * Only return boards in the General library (boards not in any real library).
-     * Mutually exclusive with `libraryId` — passing both results in a `400`
-     * (BadRequestError).
+     * Mutually exclusive with `libraryId` and with `showcaseId`. Combining
+     * either pair results in a `400` (BadRequestError).
      */
     inGeneralLibrary?: boolean;
 }
@@ -238,12 +259,18 @@ interface GuestListResponse {
     data: Guest[];
 }
 
-/** Visitor comment access on a share link. */
+/**
+ * Visitor comment access on a share link.
+ * `allowed` lets anyone with the link post comments.
+ */
 type ShareLinkCommentsAccess = "hidden" | "read_only" | "allowed";
-/** Visitor custom field access on a share link. */
+/**
+ * Visitor custom field access on a share link.
+ * `editable` lets anyone with the link change custom field values.
+ */
 type ShareLinkCustomFieldsAccess = "hidden" | "read_only" | "editable";
 /**
- * Public share link fields shared by assets and boards.
+ * Public share link fields shared by assets, boards, and showcases.
  * `url` is the link to give to people. The password is never returned;
  * `hasPassword` says whether one is set. Disabled links are included
  * with `active: false`.
@@ -292,10 +319,31 @@ interface BoardShareLinkListResponse extends CursorPageResponse<BoardShareLink>
  * Settings accepted on share-link create and update.
  * Omitted fields follow the workspace Share Link Defaults on create,
  * and stay unchanged on update.
+ *
+ * `password` is write only; reads return `hasPassword`. `null` clears
+ * `password` and `expiresAt`. An empty password is rejected. `expiresAt`
+ * must be an ISO 8601 date-time in the future.
+ *
+ * Turning `password`, `expiresAt`, `requireAccount`, `comments`, or
+ * `customFields` on needs the workspace `shareLinks` add-on. Otherwise the
+ * API returns 422 `ADDON_DISABLED` and applies nothing in the request.
+ * Raising `comments` from `read_only` to `allowed`, or `customFields` from
+ * `read_only` to `editable`, counts as turning it on, so a link that already
+ * shows comments or custom fields can still get that 422.
+ * `extra.settings` names the rejected settings, and uses `expiration` for
+ * `expiresAt`. Re-sending a value the link already has, changing an existing
+ * password or expiration, and turning a setting off are accepted.
  */
 interface ShareLinkWriteSettings {
     active?: boolean;
     allowDownload?: boolean;
+    /** Write only. `null` removes the password. */
+    password?: string | null;
+    /** ISO 8601 date-time in the future. `null` removes the expiration. */
+    expiresAt?: string | null;
+    requireAccount?: boolean;
+    comments?: ShareLinkCommentsAccess;
+    customFields?: ShareLinkCustomFieldsAccess;
 }
 /** Asset links also accept `showAllVersions`. */
 interface AssetShareLinkWriteSettings extends ShareLinkWriteSettings {
@@ -505,6 +553,179 @@ declare class Roles {
     list(params?: RoleListParams): Promise<Role[]>;
 }
 
+/**
+ * Filter for the state of a showcase's share link.
+ * `active`: the link is enabled. `inactive`: the link is disabled.
+ * `expired`: the link's expiration date has passed.
+ */
+type ShowcaseShareLinkStatus = "active" | "inactive" | "expired";
+/** How many items the showcase holds. */
+interface ShowcaseStats {
+    assetCount: number;
+    fileCount: number;
+    boardCount: number;
+}
+/**
+ * Showcase share link. A showcase has at most one, and it uses the same
+ * fields as a board share link.
+ */
+type ShowcaseShareLink = ShareLink;
+/**
+ * A showcase and its share link.
+ *
+ * `shareLink` is null when the showcase has no link. `get` returns those
+ * showcases. `list` omits them. Every showcase created through `create`
+ * has a link.
+ *
+ * Sub-pages are not part of this object. A showcase that has them still
+ * comes back as one showcase, and item lists return only its top-level items.
+ */
+interface Showcase {
+    id: string;
+    name: string;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
+    stats: ShowcaseStats;
+    shareLink: ShowcaseShareLink | null;
+}
+/**
+ * Query for `GET /showcases`.
+ * The API defaults `limit` to 12 and treats values above 200 as 200.
+ * An empty `search`, an unknown `status`, a `limit` that is not a positive
+ * integer, or a cursor this endpoint did not issue is 400.
+ */
+interface ShowcaseListParams extends CursorPageParams {
+    /** Only return showcases whose name contains this text. */
+    search?: string;
+    /** Filter by the state of the showcase's share link. */
+    status?: ShowcaseShareLinkStatus;
+}
+/**
+ * Body for `POST /showcases`.
+ * Creates the showcase and its share link together. It does not take items;
+ * add them with `addAssets` and `addBoards`. Omitted `shareLink` settings
+ * follow the workspace Share Link Defaults. The same paid settings as a
+ * board link apply, including `422` `ADDON_DISABLED` when the plan does not
+ * include one that the request turns on. If the link cannot be created, the
+ * showcase is not created either.
+ */
+interface ShowcaseCreateParams {
+    name: string;
+    /** Empty string is rejected. Omit the field to leave the description unset. */
+    description?: string;
+    shareLink?: ShareLinkWriteSettings;
+}
+/**
+ * Body for `PATCH /showcases/:showcaseId`.
+ * Only the fields you send change. `null` removes the description. An empty
+ * or null `name` is rejected. An empty body changes nothing.
+ */
+interface ShowcaseUpdateParams {
+    name?: string;
+    description?: string | null;
+}
+/** Body for `POST /showcases/:showcaseId/assets`. `assetIds` must be non-empty. */
+interface AddShowcaseAssetsParams {
+    assetIds: string[];
+}
+/** Body for `POST /showcases/:showcaseId/boards`. `boardIds` must be non-empty. */
+interface AddShowcaseBoardsParams {
+    boardIds: string[];
+}
+/**
+ * Body for `PATCH /showcases/:showcaseId/share-links/:shareLinkId`.
+ * Same settings as a board share link.
+ */
+type ShowcaseShareLinkUpdateParams = ShareLinkWriteSettings;
+
+/**
+ * Showcases. A showcase is a collection with one share link.
+ *
+ * `create` makes the showcase and its share link together. The result
+ * includes the link, and the showcase starts empty. Add items with
+ * `addAssets` and `addBoards`.
+ *
+ * Sub-pages are not exposed. Item lists return only a showcase's top-level
+ * items, and a sub-page id is not found on these routes.
+ *
+ * An unknown, trashed, or other-workspace id is 404. An item or showcase
+ * the caller cannot view is 403. Adding an item that is already in the
+ * showcase, or removing one that is not, succeeds and returns 204.
+ */
+declare class Showcases {
+    private client;
+    constructor(client: AirBase);
+    /**
+     * 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?: ShowcaseListParams): PagePromise<Showcase>;
+    /**
+     * 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.
+     */
+    get(showcaseId: string): Promise<Showcase>;
+    /**
+     * 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.
+     */
+    create(params: ShowcaseCreateParams): Promise<Showcase>;
+    /**
+     * Rename a showcase or change its description. Only the fields you send
+     * change. Returns no body.
+     *
+     * Requires the `showcases.write` OAuth scope.
+     */
+    update(showcaseId: string, params: ShowcaseUpdateParams): Promise<void>;
+    /**
+     * 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.
+     */
+    updateShareLink(showcaseId: string, shareLinkId: string, params: ShowcaseShareLinkUpdateParams): Promise<void>;
+    /**
+     * 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.
+     */
+    addAssets(showcaseId: string, params: AddShowcaseAssetsParams): Promise<void>;
+    /**
+     * 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.
+     */
+    removeAsset(showcaseId: string, assetId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    addBoards(showcaseId: string, params: AddShowcaseBoardsParams): Promise<void>;
+    /**
+     * 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.
+     */
+    removeBoard(showcaseId: string, boardId: string): Promise<void>;
+}
+
 declare class Tags {
     private client;
     constructor(client: AirBase);
@@ -641,6 +862,7 @@ interface AirApiOptions extends AirBaseOptions {
 declare class AirApi extends AirBase {
     readonly assets: Assets;
     readonly boards: Boards;
+    readonly showcases: Showcases;
     readonly libraries: Libraries;
     readonly tags: Tags;
     readonly customFields: CustomFields;
@@ -651,4 +873,4 @@ declare class AirApi extends AirBase {
     constructor(options?: AirApiOptions);
 }
 
-export { type AddBoardAssetsParams, type AddGuestParams, 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 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 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 };

package/dist/index.js

@@ -38,6 +38,7 @@ var Assets = class {
       limit: params.limit,
       cursor: params.cursor,
       parentBoardId: params.parentBoardId,
+      showcaseId: params.showcaseId,
       search: params.search
     };
     if (params.includeNestedAssets !== void 0) {
@@ -187,6 +188,7 @@ var Boards = class {
       cursor: params.cursor,
       name: params.name,
       parentBoardId: params.parentBoardId,
+      showcaseId: params.showcaseId,
       libraryId: params.libraryId,
       inGeneralLibrary: params.inGeneralLibrary
     };
@@ -433,6 +435,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) {
@@ -722,6 +855,7 @@ var Workspaces = class {
 var AirApi = class extends AirBase {
   assets;
   boards;
+  showcases;
   libraries;
   tags;
   customFields;
@@ -733,6 +867,7 @@ var AirApi = class extends 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);
@@ -781,6 +916,7 @@ export {
   PermissionError,
   RateLimitError,
   Roles,
+  Showcases,
   Tags,
   TimeoutError,
   Uploads,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@air/api-rest",
-  "version": "0.8.0",
+  "version": "0.10.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.8.0"
+    "@air/api-core": "0.10.0"
   },
   "engines": {
     "node": ">=18"