@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/catalog/assets.d.ts

@@ -19,6 +19,11 @@ export interface Asset {
         y: number;
     } | null;
     tags: string[];
+    /**
+     * The image's alt text: the store's default-language description
+     * ({@link AssetDescriptionsModule}); null when it has none.
+     */
+    altText: string | null;
     /** The store's own asset, or its organization's; see {@link CatalogueOwnership}. */
     catalogueOwnership: CatalogueOwnership;
 }
@@ -92,11 +97,79 @@ export interface AssetDescriptionsModule {
      */
     set(assetId: string, descriptions: readonly AssetDescription[], options?: Call): Promise<AssetDescriptionsResult>;
 }
+/** What an asset list can be sorted by. */
+export type AssetSortField = 'createdAt' | 'updatedAt' | 'name' | 'fileSize' | 'id';
+export declare const ASSET_SORT_FIELDS: readonly AssetSortField[];
 export interface AssetListOptions extends ListOptions {
     /** Case-insensitive substring of the name. */
     name?: string;
     /** Assets carrying ALL of these tags. */
     tags?: string[];
+    /**
+     * Only these assets. An id the store does not hold is left out, never an error; an empty list
+     * answers an empty page without asking the engine.
+     */
+    ids?: readonly string[];
+    /**
+     * ONE sort key; the engine's own order when omitted. `createdAt` `DESC` lists the newest
+     * upload first. Anything else is refused before sending (`ValidationError`,
+     * `INVALID_ASSET_SORT`).
+     */
+    sort?: {
+        field: AssetSortField;
+        direction: 'ASC' | 'DESC';
+    };
+}
+/** A tag of the store's asset library. Tags belong to one store. */
+export interface AssetTag {
+    id: string;
+    value: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AssetTagListOptions extends ListOptions {
+    /** Case-insensitive substring of the value. */
+    value?: string;
+}
+/**
+ * The store's asset tags: the registry an asset's `tags` draw from. Setting `tags` on an
+ * asset's own `create` / `update` adds a value the store does not have yet; these methods manage
+ * the values themselves.
+ *
+ * Reads need `ReadAsset`, `ReadTag` or `ReadSettings`; each write the permission it names, or the
+ * matching `…Settings` one.
+ */
+export interface AssetTagsModule {
+    /**
+     * The store's tags, a page at a time.
+     *
+     * @effect read
+     * @permission ReadTag
+     */
+    list(options?: AssetTagListOptions): Promise<Page<AssetTag>>;
+    /**
+     * Adds a tag value to the store.
+     *
+     * @effect write
+     * @permission CreateTag
+     */
+    create(value: string, options?: Call): Promise<AssetTag>;
+    /**
+     * Renames a tag: every asset of the store carrying it now carries the new value.
+     *
+     * @effect write
+     * @permission UpdateTag
+     */
+    update(id: string, value: string, options?: Call): Promise<AssetTag>;
+    /**
+     * Removes the tag from the store and from every asset carrying it. Nothing in the SDK brings it
+     * back. A refusal the engine answers as a `DeletionResponse` is `ConflictError`
+     * (`TAG_NOT_DELETED`).
+     *
+     * @effect destructive
+     * @permission DeleteTag
+     */
+    delete(id: string, options?: Call): Promise<void>;
 }
 /**
  * The asset library. Assign an asset to a product, variant or collection with
@@ -114,10 +187,42 @@ export interface AssetListOptions extends ListOptions {
 export interface AssetsModule {
     /** An image's descriptions (its alt text per language) in the store. */
     descriptions: AssetDescriptionsModule;
+    /** The store's asset tags. */
+    tags: AssetTagsModule;
+    /**
+     * The store's assets, a page at a time.
+     *
+     * @effect read
+     * @permission ReadAsset
+     */
     list(options?: AssetListOptions): Promise<Page<Asset>>;
+    /**
+     * One asset, or null when the store holds none with that id.
+     *
+     * @effect read
+     * @permission ReadAsset
+     */
     get(id: string, options?: Call): Promise<Asset | null>;
+    /**
+     * Uploads one file as an asset of the store. Never retried.
+     *
+     * @effect write
+     * @permission CreateAsset
+     */
     create(input: CreateAssetInput, options?: Call): Promise<Asset>;
+    /**
+     * @effect write
+     * @permission UpdateAsset
+     */
     update(input: UpdateAssetInput, options?: Call): Promise<Asset>;
+    /**
+     * Removes the asset. One still featured by a product or collection is refused
+     * (`ASSET_NOT_DELETED`) unless `force` is set, which takes it off them too. Nothing in the SDK
+     * brings it back.
+     *
+     * @effect destructive
+     * @permission DeleteAsset
+     */
     delete(id: string, options?: Call & {
         force?: boolean;
     }): Promise<void>;
@@ -126,21 +231,28 @@ export interface AssetsModule {
  * An asset's own fields, without `catalogueOwnership`: what a read outside the catalogue (the
  * settings images) selects, so it keeps working against an engine older than the field.
  */
-export declare const ASSET_FILE_FIELDS = "\n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n";
-export declare const ASSET_FIELDS = "\n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n";
-export declare const ASSETS_QUERY = "\n  query CatalogAssets($options: AssetListOptions) {\n    assets(options: $options) {\n      items { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n      totalItems\n    }\n  }\n";
-export declare const ASSET_QUERY = "\n  query CatalogAsset($id: ID!) {\n    asset(id: $id) { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n  }\n";
-export declare const CREATE_ASSETS_MUTATION = "\n  mutation CatalogCreateAssets($input: [CreateAssetInput!]!) {\n    createAssets(input: $input) {\n      ... on Asset { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
-export declare const UPDATE_ASSET_MUTATION = "\n  mutation CatalogUpdateAsset($input: UpdateAssetInput!) {\n    updateAsset(input: $input) { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n  }\n";
+export declare const ASSET_FILE_FIELDS = "\n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n  customFields {\n    altText\n  }\n";
+export declare const ASSET_FIELDS = "\n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n  customFields {\n    altText\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n";
+export declare const ASSETS_QUERY = "\n  query CatalogAssets($options: AssetListOptions) {\n    assets(options: $options) {\n      items { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n  customFields {\n    altText\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n      totalItems\n    }\n  }\n";
+export declare const ASSET_QUERY = "\n  query CatalogAsset($id: ID!) {\n    asset(id: $id) { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n  customFields {\n    altText\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n  }\n";
+export declare const CREATE_ASSETS_MUTATION = "\n  mutation CatalogCreateAssets($input: [CreateAssetInput!]!) {\n    createAssets(input: $input) {\n      ... on Asset { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n  customFields {\n    altText\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare const UPDATE_ASSET_MUTATION = "\n  mutation CatalogUpdateAsset($input: UpdateAssetInput!) {\n    updateAsset(input: $input) { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n  customFields {\n    altText\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n  }\n";
 export declare const DELETE_ASSET_MUTATION = "\n  mutation CatalogDeleteAsset($input: DeleteAssetInput!) {\n    deleteAsset(input: $input) { \n  result\n  message\n }\n  }\n";
+export declare const TAGS_QUERY = "\n  query CatalogAssetTags($options: TagListOptions) {\n    tags(options: $options) {\n      items { \n  id\n  value\n  createdAt\n  updatedAt\n }\n      totalItems\n    }\n  }\n";
+export declare const CREATE_TAG_MUTATION = "\n  mutation CatalogCreateTag($input: CreateTagInput!) {\n    createTag(input: $input) { \n  id\n  value\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const UPDATE_TAG_MUTATION = "\n  mutation CatalogUpdateTag($input: UpdateTagInput!) {\n    updateTag(input: $input) { \n  id\n  value\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DELETE_TAG_MUTATION = "\n  mutation CatalogDeleteTag($id: ID!) {\n    deleteTag(id: $id) { \n  result\n  message\n }\n  }\n";
 export declare const SET_ASSET_DESCRIPTIONS_MUTATION = "\n  mutation CatalogSetAssetDescriptions(\n    $assetId: ID!\n    $descriptions: [AssetDescriptionInput!]!\n  ) {\n    setAssetDescriptions(assetId: $assetId, descriptions: $descriptions) {\n      assetId\n      descriptions {\n        languageCode\n        description\n      }\n      altText\n    }\n  }\n";
 /** An asset as {@link ASSET_FILE_FIELDS} reads it: no `catalogueOwnership`. */
 export type AssetFile = Omit<Asset, 'catalogueOwnership'>;
-/** An asset as the Admin API answers it: tags as objects. */
-export type WireOf<T extends AssetFile> = Omit<T, 'tags'> & {
+/** An asset as the Admin API answers it: tags as objects, the alt text a custom field. */
+export type WireOf<T extends AssetFile> = Omit<T, 'tags' | 'altText'> & {
     tags: Array<{
         value: string;
     }>;
+    customFields?: {
+        altText?: string | null;
+    } | null;
 };
 export declare function toAsset(wire: WireOf<Asset>): Asset;
 export declare function toAsset(wire: WireOf<AssetFile>): AssetFile;

package/dist/catalog/assets.js

@@ -1,5 +1,12 @@
-import { UpstreamError, ValidationError } from '@sixtyninecommerce/core';
-import { assertDeleted, CATALOGUE_OWNERSHIP_FIELDS, DELETION_FIELDS, fieldOf, unwrapResult, vendureListPage, } from './types.js';
+import { pageFromVendureList, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
+import { assertDeleted, CATALOGUE_OWNERSHIP_FIELDS, DEFAULT_PAGE_SIZE, DELETION_FIELDS, fieldOf, unwrapResult, vendureListPage, } from './types.js';
+export const ASSET_SORT_FIELDS = [
+    'createdAt',
+    'updatedAt',
+    'name',
+    'fileSize',
+    'id',
+];
 /**
  * An asset's own fields, without `catalogueOwnership`: what a read outside the catalogue (the
  * settings images) selects, so it keeps working against an engine older than the field.
@@ -23,6 +30,9 @@ export const ASSET_FILE_FIELDS = /* GraphQL */ `
   tags {
     value
   }
+  customFields {
+    altText
+  }
 `;
 export const ASSET_FIELDS = /* GraphQL */ `
   ${ASSET_FILE_FIELDS}
@@ -62,6 +72,35 @@ export const DELETE_ASSET_MUTATION = /* GraphQL */ `
     deleteAsset(input: $input) { ${DELETION_FIELDS} }
   }
 `;
+const TAG_FIELDS = /* GraphQL */ `
+  id
+  value
+  createdAt
+  updatedAt
+`;
+export const TAGS_QUERY = /* GraphQL */ `
+  query CatalogAssetTags($options: TagListOptions) {
+    tags(options: $options) {
+      items { ${TAG_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const CREATE_TAG_MUTATION = /* GraphQL */ `
+  mutation CatalogCreateTag($input: CreateTagInput!) {
+    createTag(input: $input) { ${TAG_FIELDS} }
+  }
+`;
+export const UPDATE_TAG_MUTATION = /* GraphQL */ `
+  mutation CatalogUpdateTag($input: UpdateTagInput!) {
+    updateTag(input: $input) { ${TAG_FIELDS} }
+  }
+`;
+export const DELETE_TAG_MUTATION = /* GraphQL */ `
+  mutation CatalogDeleteTag($id: ID!) {
+    deleteTag(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
 export const SET_ASSET_DESCRIPTIONS_MUTATION = /* GraphQL */ `
   mutation CatalogSetAssetDescriptions(
     $assetId: ID!
@@ -78,7 +117,39 @@ export const SET_ASSET_DESCRIPTIONS_MUTATION = /* GraphQL */ `
   }
 `;
 export function toAsset(wire) {
-    return { ...wire, tags: wire.tags.map((tag) => tag.value) };
+    const { customFields, ...rest } = wire;
+    return {
+        ...rest,
+        tags: wire.tags.map((tag) => tag.value),
+        altText: customFields?.altText ?? null,
+    };
+}
+function invalidSort(sort) {
+    return new ValidationError({
+        code: 'INVALID_ASSET_SORT',
+        message: `sort must name one of ${ASSET_SORT_FIELDS.join(', ')} and the direction ASC or DESC; got ${JSON.stringify(sort)}. Nothing was sent.`,
+        status: 400,
+        service: 'vendure',
+    });
+}
+/** The `AssetListOptions` the engine takes, minus paging; refuses an unknown sort. */
+function assetListOptionsOf(options) {
+    const sort = options?.sort;
+    if (sort !== undefined &&
+        (!ASSET_SORT_FIELDS.includes(sort.field) ||
+            (sort.direction !== 'ASC' && sort.direction !== 'DESC'))) {
+        throw invalidSort(sort);
+    }
+    const filter = {};
+    if (options?.name !== undefined)
+        filter.name = { contains: options.name };
+    if (options?.ids !== undefined)
+        filter.id = { in: [...options.ids] };
+    return {
+        ...(Object.keys(filter).length > 0 ? { filter } : {}),
+        ...(options?.tags !== undefined ? { tags: options.tags, tagsOperator: 'AND' } : {}),
+        ...(sort === undefined ? {} : { sort: { [sort.field]: sort.direction } }),
+    };
 }
 /** A `File` without depending on the DOM lib: anything Blob-like carrying a `name`. */
 function nameOf(file) {
@@ -106,16 +177,31 @@ export function createAssetsModule(transport) {
                 })),
             }, options),
         },
-        list: (options) => vendureListPage(transport, ASSETS_QUERY, 'assets', (skip, take) => ({
-            options: {
-                skip,
-                take,
-                ...(options?.name !== undefined
-                    ? { filter: { name: { contains: options.name } } }
-                    : {}),
-                ...(options?.tags !== undefined ? { tags: options.tags, tagsOperator: 'AND' } : {}),
+        tags: {
+            list: (options) => vendureListPage(transport, TAGS_QUERY, 'tags', (skip, take) => ({
+                options: {
+                    skip,
+                    take,
+                    ...(options?.value !== undefined
+                        ? { filter: { value: { contains: options.value } } }
+                        : {}),
+                },
+            }), options),
+            create: (value, options) => fieldOf(transport, CREATE_TAG_MUTATION, 'createTag', { input: { value } }, options),
+            update: (id, value, options) => fieldOf(transport, UPDATE_TAG_MUTATION, 'updateTag', { input: { id, value } }, options),
+            async delete(id, options) {
+                const response = await fieldOf(transport, DELETE_TAG_MUTATION, 'deleteTag', { id }, options);
+                assertDeleted('TAG_NOT_DELETED', [response]);
             },
-        }), options, toAsset),
+        },
+        async list(options) {
+            // Checked before anything is sent: an unknown sort never reaches the engine.
+            const listOptions = assetListOptionsOf(options);
+            if (options?.ids !== undefined && options.ids.length === 0) {
+                return pageFromVendureList({ items: [], totalItems: 0 }, 0, options.limit ?? DEFAULT_PAGE_SIZE, () => Promise.reject(new Error('an empty page has no next page')));
+            }
+            return vendureListPage(transport, ASSETS_QUERY, 'assets', (skip, take) => ({ options: { skip, take, ...listOptions } }), options, toAsset);
+        },
         async get(id, options) {
             const wire = await fieldOf(transport, ASSET_QUERY, 'asset', { id }, options);
             return wire ? toAsset(wire) : null;