@air/api-rest 0.5.1 → 0.7.0

package/README.md

@@ -22,6 +22,7 @@ npm install @air/api-rest
 
 - Resource classes: `BoardsResource`, `AssetsResource`, `TagsResource`, `CustomFieldsResource`, `UploadsResource`, `ImportsResource`, `RolesResource`
 - 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
 - `AirApi` client class that composes all resources
 

package/dist/index.cjs

@@ -171,6 +171,30 @@ var Assets = class {
       path: `/assets/${assetId}/versions/${versionId}/tags/${tagId}`
     });
   }
+  listShareLinks(assetId, params = {}) {
+    const query = {
+      limit: params.limit,
+      cursor: params.cursor
+    };
+    return this.client.requestCursorPage(
+      { method: "GET", path: `/assets/${assetId}/share-links`, query },
+      query
+    );
+  }
+  async createShareLink(assetId, params) {
+    return this.client.request({
+      method: "POST",
+      path: `/assets/${assetId}/share-links`,
+      body: params
+    });
+  }
+  async updateShareLink(assetId, shareLinkId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/assets/${assetId}/share-links/${shareLinkId}`,
+      body: params
+    });
+  }
   listBoards(assetId, params = {}) {
     const query = {
       limit: params.limit,
@@ -251,6 +275,26 @@ var Boards = class {
       body: params
     });
   }
+  async listShareLinks(boardId) {
+    return this.client.request({
+      method: "GET",
+      path: `/boards/${boardId}/share-links`
+    });
+  }
+  async createShareLink(boardId, params = {}) {
+    return this.client.request({
+      method: "POST",
+      path: `/boards/${boardId}/share-links`,
+      body: params
+    });
+  }
+  async updateShareLink(boardId, shareLinkId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/boards/${boardId}/share-links/${shareLinkId}`,
+      body: params
+    });
+  }
   async addGuest(boardId, params) {
     return this.client.request({
       method: "POST",

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { CursorPageParams, AirBase, PagePromise, AirBaseOptions } from '@air/api-core';
+import { CursorPageParams, CursorPageResponse, AirBase, PagePromise, AirBaseOptions } from '@air/api-core';
 export { APIError, AirBase, AirBaseOptions, AuthenticationError, BadRequestError, BuildAuthorizationUrlOptions, ConnectionError, CursorPage, CursorPageParams, CursorPageResponse, ExchangeAuthorizationCodeOptions, InternalServerError, NotFoundError, OAuthAccessToken, OAuthClientAuthMethod, PKCEChallenge, PagePromise, PermissionError, RateLimitError, RequestOptions, TimeoutError, VERSION, buildAuthorizationUrl, exchangeAuthorizationCode, generatePKCEChallenge } from '@air/api-core';
 
 interface Tag {
@@ -188,6 +188,87 @@ interface GuestListResponse {
     data: Guest[];
 }
 
+/** Visitor comment access on a share link. */
+type ShareLinkCommentsAccess = "hidden" | "read_only" | "allowed";
+/** Visitor custom field access on a share link. */
+type ShareLinkCustomFieldsAccess = "hidden" | "read_only" | "editable";
+/**
+ * Public share link fields shared by assets and boards.
+ * `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`.
+ */
+interface ShareLink {
+    id: string;
+    url: string;
+    active: boolean;
+    hasPassword: boolean;
+    expiresAt: string | null;
+    requireAccount: boolean;
+    allowDownload: boolean;
+    comments: ShareLinkCommentsAccess;
+    customFields: ShareLinkCustomFieldsAccess;
+    createdAt: string;
+}
+/**
+ * Asset share link. An asset can have one link that follows the current
+ * version and one link per pinned version. `versionId` is present only
+ * when the link is pinned to a version.
+ */
+type AssetShareLink = (ShareLink & {
+    followsDefaultVersion: true;
+    versionId?: never;
+    showAllVersions: boolean;
+}) | (ShareLink & {
+    followsDefaultVersion: false;
+    versionId: string;
+    showAllVersions: boolean;
+});
+/** Board share link. A board has at most one. */
+type BoardShareLink = ShareLink;
+/**
+ * Pagination for `GET /assets/:assetId/share-links`.
+ * The API defaults `limit` to 12 and caps it at 200.
+ */
+type AssetShareLinkListParams = CursorPageParams;
+/**
+ * Response for `GET /boards/:boardId/share-links`.
+ * `data` holds the board's share link, or is empty when the board has none.
+ */
+interface BoardShareLinkListResponse extends CursorPageResponse<BoardShareLink> {
+    total: number;
+}
+/**
+ * Settings accepted on share-link create and update.
+ * Omitted fields follow the workspace Share Link Defaults on create,
+ * and stay unchanged on update.
+ */
+interface ShareLinkWriteSettings {
+    active?: boolean;
+    allowDownload?: boolean;
+}
+/** Asset links also accept `showAllVersions`. */
+interface AssetShareLinkWriteSettings extends ShareLinkWriteSettings {
+    showAllVersions?: boolean;
+}
+/**
+ * Body for `POST /assets/:assetId/share-links`.
+ * Exactly one of `followsDefaultVersion: true` or `versionId`.
+ */
+type AssetShareLinkCreateParams = AssetShareLinkWriteSettings & ({
+    followsDefaultVersion: true;
+    versionId?: never;
+} | {
+    versionId: string;
+    followsDefaultVersion?: never;
+});
+/** Body for `PATCH /assets/:assetId/share-links/:shareLinkId`. */
+type AssetShareLinkUpdateParams = AssetShareLinkWriteSettings;
+/** Body for `POST /boards/:boardId/share-links`. */
+type BoardShareLinkCreateParams = ShareLinkWriteSettings;
+/** Body for `PATCH /boards/:boardId/share-links/:shareLinkId`. */
+type BoardShareLinkUpdateParams = ShareLinkWriteSettings;
+
 declare class Assets {
     private client;
     constructor(client: AirBase);
@@ -204,6 +285,9 @@ declare class Assets {
     getVersionDownloadUrl(assetId: string, versionId: string): Promise<AssetVersionDownloadUrl>;
     addVersionTag(assetId: string, versionId: string, params: AddVersionTagParams): Promise<AssetVersion>;
     removeVersionTag(assetId: string, versionId: string, tagId: string): Promise<void>;
+    listShareLinks(assetId: string, params?: AssetShareLinkListParams): PagePromise<AssetShareLink>;
+    createShareLink(assetId: string, params: AssetShareLinkCreateParams): Promise<AssetShareLink>;
+    updateShareLink(assetId: string, shareLinkId: string, params: AssetShareLinkUpdateParams): Promise<void>;
     listBoards(assetId: string, params?: AssetBoardListParams): PagePromise<Board>;
 }
 
@@ -218,6 +302,9 @@ declare class Boards {
     addAssets(boardId: string, params: AddBoardAssetsParams): Promise<void>;
     removeAsset(boardId: string, assetId: string): Promise<void>;
     setCustomField(boardId: string, customFieldId: string, params: SetBoardCustomFieldParams): Promise<void>;
+    listShareLinks(boardId: string): Promise<BoardShareLinkListResponse>;
+    createShareLink(boardId: string, params?: BoardShareLinkCreateParams): Promise<BoardShareLink>;
+    updateShareLink(boardId: string, shareLinkId: string, params: BoardShareLinkUpdateParams): Promise<void>;
     addGuest(boardId: string, params: AddGuestParams): Promise<Guest>;
     listGuests(boardId: string, params?: GuestListParams): Promise<Guest[]>;
     updateGuest(boardId: string, guestId: string, params: UpdateGuestParams): Promise<void>;
@@ -514,4 +601,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 AssetCustomFieldValue, type AssetListParams, type AssetVersion, type AssetVersionDownloadUrl, type AssetVersionListResponse, type AssetVersionUpdateParams, type AssetVersionUrls, Assets, type Board, type BoardCreateParams, type BoardListParams, 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 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 AddVersionTagParams, AirApi, type AirApiOptions, type Asset, type AssetBoardListParams, type AssetCdnLinkCreateParams, type AssetCdnLinkListResponse, type AssetCdnLinkUpdateParams, 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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CursorPageParams, AirBase, PagePromise, AirBaseOptions } from '@air/api-core';
+import { CursorPageParams, CursorPageResponse, AirBase, PagePromise, AirBaseOptions } from '@air/api-core';
 export { APIError, AirBase, AirBaseOptions, AuthenticationError, BadRequestError, BuildAuthorizationUrlOptions, ConnectionError, CursorPage, CursorPageParams, CursorPageResponse, ExchangeAuthorizationCodeOptions, InternalServerError, NotFoundError, OAuthAccessToken, OAuthClientAuthMethod, PKCEChallenge, PagePromise, PermissionError, RateLimitError, RequestOptions, TimeoutError, VERSION, buildAuthorizationUrl, exchangeAuthorizationCode, generatePKCEChallenge } from '@air/api-core';
 
 interface Tag {
@@ -188,6 +188,87 @@ interface GuestListResponse {
     data: Guest[];
 }
 
+/** Visitor comment access on a share link. */
+type ShareLinkCommentsAccess = "hidden" | "read_only" | "allowed";
+/** Visitor custom field access on a share link. */
+type ShareLinkCustomFieldsAccess = "hidden" | "read_only" | "editable";
+/**
+ * Public share link fields shared by assets and boards.
+ * `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`.
+ */
+interface ShareLink {
+    id: string;
+    url: string;
+    active: boolean;
+    hasPassword: boolean;
+    expiresAt: string | null;
+    requireAccount: boolean;
+    allowDownload: boolean;
+    comments: ShareLinkCommentsAccess;
+    customFields: ShareLinkCustomFieldsAccess;
+    createdAt: string;
+}
+/**
+ * Asset share link. An asset can have one link that follows the current
+ * version and one link per pinned version. `versionId` is present only
+ * when the link is pinned to a version.
+ */
+type AssetShareLink = (ShareLink & {
+    followsDefaultVersion: true;
+    versionId?: never;
+    showAllVersions: boolean;
+}) | (ShareLink & {
+    followsDefaultVersion: false;
+    versionId: string;
+    showAllVersions: boolean;
+});
+/** Board share link. A board has at most one. */
+type BoardShareLink = ShareLink;
+/**
+ * Pagination for `GET /assets/:assetId/share-links`.
+ * The API defaults `limit` to 12 and caps it at 200.
+ */
+type AssetShareLinkListParams = CursorPageParams;
+/**
+ * Response for `GET /boards/:boardId/share-links`.
+ * `data` holds the board's share link, or is empty when the board has none.
+ */
+interface BoardShareLinkListResponse extends CursorPageResponse<BoardShareLink> {
+    total: number;
+}
+/**
+ * Settings accepted on share-link create and update.
+ * Omitted fields follow the workspace Share Link Defaults on create,
+ * and stay unchanged on update.
+ */
+interface ShareLinkWriteSettings {
+    active?: boolean;
+    allowDownload?: boolean;
+}
+/** Asset links also accept `showAllVersions`. */
+interface AssetShareLinkWriteSettings extends ShareLinkWriteSettings {
+    showAllVersions?: boolean;
+}
+/**
+ * Body for `POST /assets/:assetId/share-links`.
+ * Exactly one of `followsDefaultVersion: true` or `versionId`.
+ */
+type AssetShareLinkCreateParams = AssetShareLinkWriteSettings & ({
+    followsDefaultVersion: true;
+    versionId?: never;
+} | {
+    versionId: string;
+    followsDefaultVersion?: never;
+});
+/** Body for `PATCH /assets/:assetId/share-links/:shareLinkId`. */
+type AssetShareLinkUpdateParams = AssetShareLinkWriteSettings;
+/** Body for `POST /boards/:boardId/share-links`. */
+type BoardShareLinkCreateParams = ShareLinkWriteSettings;
+/** Body for `PATCH /boards/:boardId/share-links/:shareLinkId`. */
+type BoardShareLinkUpdateParams = ShareLinkWriteSettings;
+
 declare class Assets {
     private client;
     constructor(client: AirBase);
@@ -204,6 +285,9 @@ declare class Assets {
     getVersionDownloadUrl(assetId: string, versionId: string): Promise<AssetVersionDownloadUrl>;
     addVersionTag(assetId: string, versionId: string, params: AddVersionTagParams): Promise<AssetVersion>;
     removeVersionTag(assetId: string, versionId: string, tagId: string): Promise<void>;
+    listShareLinks(assetId: string, params?: AssetShareLinkListParams): PagePromise<AssetShareLink>;
+    createShareLink(assetId: string, params: AssetShareLinkCreateParams): Promise<AssetShareLink>;
+    updateShareLink(assetId: string, shareLinkId: string, params: AssetShareLinkUpdateParams): Promise<void>;
     listBoards(assetId: string, params?: AssetBoardListParams): PagePromise<Board>;
 }
 
@@ -218,6 +302,9 @@ declare class Boards {
     addAssets(boardId: string, params: AddBoardAssetsParams): Promise<void>;
     removeAsset(boardId: string, assetId: string): Promise<void>;
     setCustomField(boardId: string, customFieldId: string, params: SetBoardCustomFieldParams): Promise<void>;
+    listShareLinks(boardId: string): Promise<BoardShareLinkListResponse>;
+    createShareLink(boardId: string, params?: BoardShareLinkCreateParams): Promise<BoardShareLink>;
+    updateShareLink(boardId: string, shareLinkId: string, params: BoardShareLinkUpdateParams): Promise<void>;
     addGuest(boardId: string, params: AddGuestParams): Promise<Guest>;
     listGuests(boardId: string, params?: GuestListParams): Promise<Guest[]>;
     updateGuest(boardId: string, guestId: string, params: UpdateGuestParams): Promise<void>;
@@ -514,4 +601,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 AssetCustomFieldValue, type AssetListParams, type AssetVersion, type AssetVersionDownloadUrl, type AssetVersionListResponse, type AssetVersionUpdateParams, type AssetVersionUrls, Assets, type Board, type BoardCreateParams, type BoardListParams, 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 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 AddVersionTagParams, AirApi, type AirApiOptions, type Asset, type AssetBoardListParams, type AssetCdnLinkCreateParams, type AssetCdnLinkListResponse, type AssetCdnLinkUpdateParams, 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 };

package/dist/index.js

@@ -110,6 +110,30 @@ var Assets = class {
       path: `/assets/${assetId}/versions/${versionId}/tags/${tagId}`
     });
   }
+  listShareLinks(assetId, params = {}) {
+    const query = {
+      limit: params.limit,
+      cursor: params.cursor
+    };
+    return this.client.requestCursorPage(
+      { method: "GET", path: `/assets/${assetId}/share-links`, query },
+      query
+    );
+  }
+  async createShareLink(assetId, params) {
+    return this.client.request({
+      method: "POST",
+      path: `/assets/${assetId}/share-links`,
+      body: params
+    });
+  }
+  async updateShareLink(assetId, shareLinkId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/assets/${assetId}/share-links/${shareLinkId}`,
+      body: params
+    });
+  }
   listBoards(assetId, params = {}) {
     const query = {
       limit: params.limit,
@@ -190,6 +214,26 @@ var Boards = class {
       body: params
     });
   }
+  async listShareLinks(boardId) {
+    return this.client.request({
+      method: "GET",
+      path: `/boards/${boardId}/share-links`
+    });
+  }
+  async createShareLink(boardId, params = {}) {
+    return this.client.request({
+      method: "POST",
+      path: `/boards/${boardId}/share-links`,
+      body: params
+    });
+  }
+  async updateShareLink(boardId, shareLinkId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/boards/${boardId}/share-links/${shareLinkId}`,
+      body: params
+    });
+  }
   async addGuest(boardId, params) {
     return this.client.request({
       method: "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@air/api-rest",
-  "version": "0.5.1",
+  "version": "0.7.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.5.1"
+    "@air/api-core": "0.7.0"
   },
   "engines": {
     "node": ">=18"