Assets 10 Client SDK

Use assets-client-sdk for Assets 6

The Assets 10 Client SDK enables UI plugins to communicate with the Assets 10 host. It handles the handshake and session lifecycle, exposes typed methods for all supported host operations, and delivers push updates (selection changes, upload progress, process info) via subscriptions.

Full TypeScript typings are included and will surface automatically in your IDE.

Installation

npm install @woodwing/a10-client-sdk

Import in TypeScript / ES modules:

import { Assets10Client } from '@woodwing/a10-client-sdk';

Bootstrap

Initialize the client by calling the static bootstrap method. It performs the handshake with the host and returns a ready-to-use client instance.

const client = await Assets10Client.bootstrap();

Optional bootstrap configuration:

const client = await Assets10Client.bootstrap({
    debug: true, // Enable debug logging (token is always redacted). Default: false
    handshakeTimeoutMs: 10000, // Max time to wait for handshake + grant. Default: 10000
    requestTimeoutMs: 15000, // Per-request timeout. Default: 15000
});

When done, close the client to stop listening on the MessagePort:

client.close();

Plugin Context

After bootstrap, the plugin context is available and reflects the current state of the host application.

const context = client.getPluginContext();

context.app.queryString; // Current search query string
context.app.userProfile; // Logged-in user info
context.app.folderSelection; // Currently selected folders
context.app.assetSelection; // Currently selected assets

context.configProperties['my_key'].value; // Plugin configuration properties

Get the current asset selection directly:

const assets: Asset[] = client.getSelection();

API Reference

Subscriptions

Subscribe to host push updates for selection changes. The handler receives the full updated Asset[]. Returns an unsubscribe function.

client.onSelectionUpdate(handler) → () => void

const unsubscribe = client.onSelectionUpdate((assets: Asset[]) => {
    console.log('Selection changed:', assets);
});

Subscribe to host push updates for upload progress. Returns an unsubscribe function.

client.onUploadProgress(handler) → () => void

const unsubscribe = client.onUploadProgress((progress: UploadProgressUpdatePayload) => {
    console.log(`${progress.uploaded}/${progress.total} (${progress.progress}%)`);
});

UI / Navigation

Opens a search view in the host with the given query and sort order.

client.openSearch(q, sort) → Promise<void>

await client.openSearch('cat filename:*.jpg', 'assetCreated-desc');

Opens the browse view in the host for the given folder path.

client.openBrowse(folderPath) → Promise<void>

await client.openBrowse('/My Projects/Campaign');

Opens the detail view for the given asset IDs in the host.

client.openAssets(assetIds) → Promise<void>

await client.openAssets(['abc123', 'def456']);

Pins the given collection IDs in the host UI.

client.pinCollections(collectionIds) → Promise<void>

Opens the upload dialog in the host. Optionally accepts a folder path to pre-select and a progress handler that is automatically subscribed and unsubscribed for the duration of the dialog.

client.openUploadDialog(folderPath?, onProgress?) → Promise<{ sessionId: string }>

const { sessionId } = await client.openUploadDialog('/My Folder', (progress) => {
    console.log(`Upload: ${progress.progress}%`);
});

Requests translations for a map of translation keys to parameter maps. Returns a map of key → translated string.

client.translate(tasks) → Promise<{ messages: Record<string, string> }>

const { messages } = await client.translate([
    { key: 'button.save', params: { context: 'dialog' } },
    { key: 'button.cancel' },
]);
// messages['button.save'] => 'Save'

Search & Metadata

Searches for assets using the given query payload.

client.search(query) → Promise<{ total: number; hits: SearchHit[] }>

const { total, hits } = await client.search({ q: 'cat', num: 20, sort: 'assetCreated-desc' });

Fetches metadata field definitions available in Assets 10, grouped by field group and indexed by field name.

client.getFieldInfo() → Promise<FieldInfoResult>

Asset Operations

Creates a placeholder asset at the given path with the provided metadata. Returns an upload URL for uploading the file content.

client.createPlaceholder(assetPath, metadata) → Promise<{ assetId: string; metadata: Record<string, unknown>; uploadUrl: string }>

Creates and uploads an asset in one call. Internally creates the placeholder and immediately uploads the file. The uploadUrl is stripped from the result.

client.create(assetPath, metadata, file, handler?) → Promise<{ assetId: string; metadata: Record<string, unknown> }>

const asset = await client.create(
    '/My Folder/photo.jpg',
    { 'dc:title': 'My Photo' },
    file,
    (progress) => {
        console.log(`${progress.progress}%`);
    },
);

Updates all assets matching the given query with the provided metadata patch.

client.updateBulkByQuery(query, metadata) → Promise<{ updated: number }>

Updates the assets with the given IDs with the provided metadata patch.

client.updateBulkById(assetIds, metadata) → Promise<{ updated: number }>

Copies an asset or folder from source to target. Optionally tracks the async process via a ProcessInfoUpdateHandler.

client.copy(source, target, folderReplacePolicy?, fileReplacePolicy?, filterQuery?, flattenFolders?, handler?) → Promise<void>

Moves an asset or folder from source to target. Optionally tracks the async process via a ProcessInfoUpdateHandler.

client.move(source, target, folderReplacePolicy?, fileReplacePolicy?, handler?) → Promise<void>

Removes assets or folders. Accepts one of the following payload forms. Optionally tracks the async process via a ProcessInfoUpdateHandler.

client.remove(payload, handler?) → Promise<void>

await client.remove({ assetIds: ['abc123', 'def456'] });
await client.remove({ q: 'status:archived' });
await client.remove({ folderPath: '/Archive/2020' });

Folders

Creates a folder at the given path.

client.createFolder(path) → Promise<Record<string, string>>

Collections

Creates a new collection at the given path with the provided name.

client.createCollection(path, name) → Promise<{ id: string; type: string; metadata: Record<string, unknown> }>

Adds the given asset IDs to a collection.

client.addToCollection(collectionId, assetIds) → Promise<{ updated: boolean }>

Removes the given asset IDs from a collection.

client.removeFromCollection(collectionId, assetIds) → Promise<{ updated: boolean }>

Type Reference

Core Types

interface Asset {
    id: string;
    metadata: Record<string, any>;
    thumbnailUrl: string;
    previewUrl?: string;
    originalUrl?: string;
    highlightedText?: string;
    thumbnailHits?: any;
    permissions?: string;
}

interface SearchHit {
    id: string;
    metadata: Record<string, unknown>;
    thumbnailUrl: string;
    previewUrl?: string;
    originalUrl?: string;
    highlightedText?: string;
    thumbnailHits?: unknown;
    permissions?: string;
}

interface UploadProgressUpdatePayload {
    sessionId?: string; // available when tracked via onUploadProgress
    state: UploadSessionState;
    total: number;
    uploaded: number;
    progress: number; // 0–100
}

interface ProcessInfoUpdatePayload {
    id: string;
    state: ProcessInfoState;
    progress: number;
    total: number;
    errorCount: number;
}

interface Field {
    name: string;
    description: string;
    editable: boolean;
    filterUI?: FilterUIType;
    editorUI?: EditorUI;
    predefinedValues: unknown[];
    predefinedValuesOnlyFromList: boolean;
    onlyForAssetDomains: string[];
}

interface FieldGroup {
    name: string;
    fields: Field[];
}

interface FieldInfoResult {
    fieldGroups: FieldGroup[];
    fieldInfoByName: Record<string, Field>;
}

interface Folder {
    name: string;
    assetPath: string;
}

interface SearchRequestPayload {
    q: string;
    num?: number;
    sort?: string;
}

interface TranslationTask {
    key: string;
    params?: Record<string, string>;
}

Enums

UploadSessionState Represents the lifecycle state of an upload session.

enum UploadSessionState {
    WAITING = 'waiting',
    UPLOADING = 'uploading',
    UPLOADED = 'uploaded',
    FAILING = 'failing',
    FAILED = 'failed',
    CANCELING = 'canceling',
    CANCELED = 'canceled',
}

FolderReplacePolicy Controls what happens when a folder already exists at the target path during a copy or move.

enum FolderReplacePolicy {
    AUTO_RENAME = 'AUTO_RENAME',
    MERGE = 'MERGE',
    ABORT = 'ABORT',
}

FileReplacePolicy Controls what happens when a file already exists at the target path during a copy or move.

enum FileReplacePolicy {
    AUTO_RENAME = 'AUTO_RENAME',
    DO_NOTHING = 'DO_NOTHING',
    ABORT = 'ABORT',
}

FilterUIType The UI component used to render a metadata field in the filter panel.

enum FilterUIType {
    TEXT = 'text',
    NUMBER = 'number',
    CHECKBOXES = 'checkBoxes',
    TAG_CLOUD = 'tagCloud',
    RANGE = 'range',
    DATE = 'date',
    TOGGLE = 'toggle',
    FILESIZE = 'fileSize',
    TAXONOMY = 'taxonomy',
}

EditorUI The UI component used to render a metadata field in the editor panel.

enum EditorUI {
    FILE_NAME = 'file-name',
    FOLDER_PATH = 'folder-path',
    TEXT = 'text',
    NUMBER = 'number',
    DECIMAL = 'decimal',
    DATE = 'date',
    DATE_TIME = 'datetime',
    DISPLAY = 'display',
    RATING = 'rating',
    TOGGLE = 'toggle',
    MULTIVALUE = 'multivalue',
    AUTO_COMPLETE = 'auto-complete',
    TAXONOMY = 'taxonomy',
}

ProcessInfoState The possible states of an async process (copy, move, remove).

enum ProcessInfoState {
    PENDING = 'PENDING',
    RUNNING = 'RUNNING',
    COMPLETED = 'COMPLETED',
    COMPLETED_WITH_ERRORS = 'COMPLETED_WITH_ERRORS',
    FAILED = 'FAILED',
    CANCELLED = 'CANCELLED',
    UNKNOWN = 'UNKNOWN',
}

Sort order A string in the format <field>-<direction>, where direction is either asc (ascending) or desc (descending). Any metadata field name can be used.

'filename-asc'; // sort by filename, A → Z
'assetCreated-desc'; // sort by creation date, newest first
'assetModified-desc'; // sort by last modified date, newest first

Callback Types

type SelectionUpdateHandler = (assets: Asset[]) => void;
type UploadProgressUpdateHandler = (payload: UploadProgressUpdatePayload) => void;
type ProcessInfoUpdateHandler = (payload: ProcessInfoUpdatePayload) => void;