@air/api-rest 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -62,6 +62,33 @@ module.exports = __toCommonJS(index_exports);
 // src/api.ts
 var import_api_core = require("@air/api-core");
 
+// src/resources/serialize-asset-custom-field-filter.ts
+var INVALID_ASSET_CUSTOM_FIELD_FILTER = "Asset custom field filter must be a select { id, valueId } or an operator { id, operator, value }";
+var readOwn = (filter, key) => Object.hasOwn(filter, key) ? filter[key] : void 0;
+var isSelectFilter = (filter) => {
+  const valueId = readOwn(filter, "valueId");
+  const operator = readOwn(filter, "operator");
+  return typeof filter.id === "string" && typeof valueId === "string" && operator === void 0;
+};
+var isOperatorFilter = (filter) => {
+  const valueId = readOwn(filter, "valueId");
+  const operator = readOwn(filter, "operator");
+  const value = readOwn(filter, "value");
+  return typeof filter.id === "string" && valueId === void 0 && typeof operator === "string" && typeof value === "string";
+};
+var serializeAssetCustomFieldFilter = (filter) => {
+  if (typeof filter === "string") {
+    return filter;
+  }
+  if (isSelectFilter(filter)) {
+    return `${filter.id}:${filter.valueId}`;
+  }
+  if (isOperatorFilter(filter)) {
+    return `${filter.id}:${filter.operator}:${filter.value}`;
+  }
+  throw new Error(INVALID_ASSET_CUSTOM_FIELD_FILTER);
+};
+
 // src/resources/assets.ts
 var Assets = class {
   constructor(client) {
@@ -84,7 +111,7 @@ var Assets = class {
       query.tag = params.tag;
     }
     if (params.customField) {
-      query.customField = params.customField;
+      query.customField = Array.isArray(params.customField) ? params.customField.map(serializeAssetCustomFieldFilter) : serializeAssetCustomFieldFilter(params.customField);
     }
     if (params["createdAt[gte]"]) {
       query["createdAt[gte]"] = params["createdAt[gte]"];

package/dist/index.d.cts

@@ -56,11 +56,56 @@ interface Asset {
     customFields: AssetCustomFieldValue[] | undefined;
     coverVersion: AssetVersion;
 }
+type AssetCustomFieldTextOperator = "text" | "textPrefix" | "textNot";
+type AssetCustomFieldDateOperator = "dateGte" | "dateLte";
+interface AssetCustomFieldSelectFilter {
+    id: string;
+    valueId: string;
+}
+interface AssetCustomFieldTextFilter {
+    id: string;
+    operator: AssetCustomFieldTextOperator;
+    value: string;
+}
+interface AssetCustomFieldDateFilter {
+    id: string;
+    operator: AssetCustomFieldDateOperator;
+    value: string;
+}
+/**
+ * One `customField` query value for `assets.list`.
+ *
+ * A string is sent unchanged (`fieldId:valueId`, or an operator string the
+ * caller already formatted). A structured filter is serialized to that same
+ * query value. Repeats become repeated query params.
+ */
+type AssetCustomFieldFilter = string | AssetCustomFieldSelectFilter | AssetCustomFieldTextFilter | AssetCustomFieldDateFilter;
 interface AssetListParams extends CursorPageParams {
     parentBoardId?: string;
     includeNestedAssets?: boolean;
     tag?: string | string[];
-    customField?: string | string[];
+    /**
+     * Filter by custom field. Select filters are `{ id, valueId }` (or the
+     * `fieldId:valueId` string). Repeats of one field are OR, and different
+     * fields are AND.
+     *
+     * Plain text is `{ id, operator: "text" | "textPrefix" | "textNot", value }`.
+     * `text` repeats are OR, `textPrefix` is one prefix, and `textNot` excludes.
+     * The value keeps colons and surrounding spaces. Empty text, more than 256
+     * characters, and more than 20 values are rejected with 400.
+     *
+     * Dates are `{ id, operator: "dateGte" | "dateLte", value }`. `dateGte` is an
+     * inclusive start and `dateLte` is an inclusive end, one of each per field.
+     * A `YYYY-MM-DD` value is that UTC day (`dateGte` at `T00:00:00.000Z`,
+     * `dateLte` at `T23:59:59.999Z`). The app stores a picked date as the
+     * viewer's local midnight converted to UTC, so match that shown day with an
+     * ISO-8601 instant (`T` and `Z` or `±HH:MM`). A start after the end is 400.
+     *
+     * One field accepts one operator kind. A mix of select, `text`, `textPrefix`,
+     * `textNot`, and date bounds on that field is 400. `boards.list` accepts
+     * select strings only. `semantic: true` rejects `customField`.
+     */
+    customField?: AssetCustomFieldFilter | AssetCustomFieldFilter[];
     search?: string;
     /**
      * When true, `search` is used for semantic search via AI embeddings.
@@ -136,6 +181,11 @@ interface Board {
 interface BoardListParams extends CursorPageParams {
     name?: string;
     parentBoardId?: 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
+     * 400; use `assets.list` for those.
+     */
     customField?: string | string[];
     /**
      * Only return boards in this library. Mutually exclusive with
@@ -188,9 +238,15 @@ 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.
@@ -242,10 +298,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 {
@@ -601,4 +678,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 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 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 };

package/dist/index.d.ts

@@ -56,11 +56,56 @@ interface Asset {
     customFields: AssetCustomFieldValue[] | undefined;
     coverVersion: AssetVersion;
 }
+type AssetCustomFieldTextOperator = "text" | "textPrefix" | "textNot";
+type AssetCustomFieldDateOperator = "dateGte" | "dateLte";
+interface AssetCustomFieldSelectFilter {
+    id: string;
+    valueId: string;
+}
+interface AssetCustomFieldTextFilter {
+    id: string;
+    operator: AssetCustomFieldTextOperator;
+    value: string;
+}
+interface AssetCustomFieldDateFilter {
+    id: string;
+    operator: AssetCustomFieldDateOperator;
+    value: string;
+}
+/**
+ * One `customField` query value for `assets.list`.
+ *
+ * A string is sent unchanged (`fieldId:valueId`, or an operator string the
+ * caller already formatted). A structured filter is serialized to that same
+ * query value. Repeats become repeated query params.
+ */
+type AssetCustomFieldFilter = string | AssetCustomFieldSelectFilter | AssetCustomFieldTextFilter | AssetCustomFieldDateFilter;
 interface AssetListParams extends CursorPageParams {
     parentBoardId?: string;
     includeNestedAssets?: boolean;
     tag?: string | string[];
-    customField?: string | string[];
+    /**
+     * Filter by custom field. Select filters are `{ id, valueId }` (or the
+     * `fieldId:valueId` string). Repeats of one field are OR, and different
+     * fields are AND.
+     *
+     * Plain text is `{ id, operator: "text" | "textPrefix" | "textNot", value }`.
+     * `text` repeats are OR, `textPrefix` is one prefix, and `textNot` excludes.
+     * The value keeps colons and surrounding spaces. Empty text, more than 256
+     * characters, and more than 20 values are rejected with 400.
+     *
+     * Dates are `{ id, operator: "dateGte" | "dateLte", value }`. `dateGte` is an
+     * inclusive start and `dateLte` is an inclusive end, one of each per field.
+     * A `YYYY-MM-DD` value is that UTC day (`dateGte` at `T00:00:00.000Z`,
+     * `dateLte` at `T23:59:59.999Z`). The app stores a picked date as the
+     * viewer's local midnight converted to UTC, so match that shown day with an
+     * ISO-8601 instant (`T` and `Z` or `±HH:MM`). A start after the end is 400.
+     *
+     * One field accepts one operator kind. A mix of select, `text`, `textPrefix`,
+     * `textNot`, and date bounds on that field is 400. `boards.list` accepts
+     * select strings only. `semantic: true` rejects `customField`.
+     */
+    customField?: AssetCustomFieldFilter | AssetCustomFieldFilter[];
     search?: string;
     /**
      * When true, `search` is used for semantic search via AI embeddings.
@@ -136,6 +181,11 @@ interface Board {
 interface BoardListParams extends CursorPageParams {
     name?: string;
     parentBoardId?: 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
+     * 400; use `assets.list` for those.
+     */
     customField?: string | string[];
     /**
      * Only return boards in this library. Mutually exclusive with
@@ -188,9 +238,15 @@ 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.
@@ -242,10 +298,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 {
@@ -601,4 +678,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 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 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 };

package/dist/index.js

@@ -1,6 +1,33 @@
 // src/api.ts
 import { AirBase } from "@air/api-core";
 
+// src/resources/serialize-asset-custom-field-filter.ts
+var INVALID_ASSET_CUSTOM_FIELD_FILTER = "Asset custom field filter must be a select { id, valueId } or an operator { id, operator, value }";
+var readOwn = (filter, key) => Object.hasOwn(filter, key) ? filter[key] : void 0;
+var isSelectFilter = (filter) => {
+  const valueId = readOwn(filter, "valueId");
+  const operator = readOwn(filter, "operator");
+  return typeof filter.id === "string" && typeof valueId === "string" && operator === void 0;
+};
+var isOperatorFilter = (filter) => {
+  const valueId = readOwn(filter, "valueId");
+  const operator = readOwn(filter, "operator");
+  const value = readOwn(filter, "value");
+  return typeof filter.id === "string" && valueId === void 0 && typeof operator === "string" && typeof value === "string";
+};
+var serializeAssetCustomFieldFilter = (filter) => {
+  if (typeof filter === "string") {
+    return filter;
+  }
+  if (isSelectFilter(filter)) {
+    return `${filter.id}:${filter.valueId}`;
+  }
+  if (isOperatorFilter(filter)) {
+    return `${filter.id}:${filter.operator}:${filter.value}`;
+  }
+  throw new Error(INVALID_ASSET_CUSTOM_FIELD_FILTER);
+};
+
 // src/resources/assets.ts
 var Assets = class {
   constructor(client) {
@@ -23,7 +50,7 @@ var Assets = class {
       query.tag = params.tag;
     }
     if (params.customField) {
-      query.customField = params.customField;
+      query.customField = Array.isArray(params.customField) ? params.customField.map(serializeAssetCustomFieldFilter) : serializeAssetCustomFieldFilter(params.customField);
     }
     if (params["createdAt[gte]"]) {
       query["createdAt[gte]"] = params["createdAt[gte]"];

package/package.json

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