@signiant/media-shuttle-sdk
Version:
The SDK for supporting file transfer to and from Media Shuttle
385 lines • 12.8 kB
TypeScript
import { GetFormDefinitionRequestOptions } from '../../internal/services/PlatformService';
import { BasicRequestOptions } from '../common/BasicRequestOptions';
export declare enum RoleTypes {
MEDIA_SHUTTLE_MEMBER = "MEDIA_SHUTTLE_MEMBER",
MEDIA_SHUTTLE_OPS_ADMIN = "MEDIA_SHUTTLE_OPS_ADMIN",
MEDIA_SHUTTLE_IT_ADMIN = "MEDIA_SHUTTLE_IT_ADMIN"
}
/**
* Represents a Media Shuttle Account including the corresponding serviceId.
*/
export interface Account {
/**
* Media Shuttle Service identifier
*/
serviceId: string;
/**
* Identifier of the Signiant account containing Media Shuttle service.
*/
accountId: string;
/**
* Media Shuttle Account Id. Useful for debugging.
*/
msAccountId: string;
/**
* Account name.
*/
name: string;
/**
* True if MFA is enabled on the Signiant account
*/
mfaEnabled: boolean;
/**
* Media Shuttle roles for user
*/
roles: RoleTypes[];
}
/**
* Response including a list of Accounts with Media Shuttle subscriptions represented by {@link Account}.
*/
export interface AccountListResponse {
/**
* A list of {@link Account} objects.
*/
mediaShuttleAccounts: Account[];
}
/**
* An interface that describes the details of a portal.
*/
export interface Portal {
/**
* Unique Identifier of the Media Shuttle Portal.
*/
portalId: string;
/**
* Portal name.
*/
name: string;
/**
* Web address of the portal.
*/
url: string;
/**
* Type of portal.
*/
type: string;
/**
* The date on which the portal was created.
*/
createdOn: Date;
/**
* The date on which the portal expires.
*/
expiresOn: Date;
/**
* The date that the portal was last modified.
*/
lastModifiedOn: Date;
/**
* Account Identifier of the Media Shuttle Service Id
*/
accountId: string;
}
/**
* The permissions attached to a particular portal.
*
* If at least one of these properties are set the logged in user should have listing access to the portal contents.
* Otherwise these permissions are not currently applicable to the SDK workflow.
*/
export interface PortalLevelPermissions {
/**
* True if files can be sent from the Media Shuttle UI.
*/
canSendFromShare: boolean;
/**
* True if the portal can be configured with auto delivery. See
* [here](https://help.signiant.com/media-shuttle/portal-administration/enabling-auto-delivery) for more details.
*/
canDeliveryAutomatically: boolean;
}
/**
* What operations can and cannot be performed on a particular folder.
*/
export interface FolderLevelPermissions {
/**
* Required to download content from this folder.
*/
canDownload: boolean;
/**
* Required to upload content to this folder.
*/
canUpload: boolean;
/**
* Required to move or delete content from this folder.
*
* Not currently relevant to the SDK workflow.
*/
canDelete: boolean;
}
/**
* Details of a folder associated with a particular media shuttle portal.
*/
export interface FolderDetails {
/**
* The id of the folder. Note that this id will change when the permissions of a folder change.
*/
id: string;
/**
* The path of the folder.
*/
path: string;
/**
* Whether this folder is the user home folder. Any folder that is not a home folder is a linked folder.
*/
isUserHome: true;
/**
* Permissions attached to a particular folder.
*/
permissions: FolderLevelPermissions;
}
/**
* This interface represents the structure of a Portal Permission.
*
* Note that if the logged in user has no permissions associated with a given portal, no actions can be
* taken including listing files within a portal.
*/
export interface PortalPermissions {
/**
* Creation date of the permissions given to the user
*/
createdOn: Date;
/**
* Unique Identifier of the Media Shuttle Portal
*/
portalId: string;
/**
* Type of portal
*/
type: string;
/**
* Media Shuttle Account Id
*/
msAccountId: string;
/**
* Permissions assigned to this user's portal
*/
permissions: {
canSendFromShare: boolean;
canDeliveryAutomatically: boolean;
};
/**
* Home and Linked folders this user has access to with the corresponding permissions
*/
folders: [
{
id: string;
path: string;
isUserHome: true;
permissions: {
canDownload: boolean;
canUpload: boolean;
canDelete: boolean;
};
}
];
}
export interface PortalMetadataForms {
enabled: boolean;
formStyle: 'JSON' | 'WEB';
jsonFormConfig: {
formDefinitionId: string;
};
}
export interface FormDefinition {
formDefinitionId: string;
name: string;
accountId: string;
createdOn: string;
lastModifiedOn: string;
type: 'JSON_FORMS';
/**
* https://jsonforms.io/api/core/interfaces/jsonformscore.html#schema
*/
schema: unknown;
}
/**
* Definition of a PortalFile item
*/
export interface PortalFile {
/**
* Indicates if the item is a directory
*/
isDirectory: boolean;
/**
* Path relative to the home folder or linked folder
*/
path: string;
/**
* Size of the file, this is only available when isDirectory=false
*/
sizeInBytes?: number;
/**
* Item modification date
*/
modifiedOn: Date;
}
/**
* Portal File list definition
*/
export interface PortalListRequest extends BasicRequestOptions {
/**
* Flag to include expired portals
*/
showExpired?: boolean;
/**
* If the user has multiple MediaShuttle roles and this flag is used, we only fetch the portals this user is MEMBER of
*/
limitPortalsToMemberRole?: boolean;
}
/**
* An interface defining options required by every portal level request.
*/
export interface PortalBasicRequest extends BasicRequestOptions {
/**
* Unique Identifier of the Media Shuttle Portal
*/
portalId: string;
}
/**
* Options specified when fetching the content of a specific folder.
*/
export interface GetFolderContentRequest extends PortalBasicRequest {
/**
* Home folder or Linked folder identifier
*/
folderId: string | null;
/**
* Path relative to the linked or home folder
*/
browsePath: string | null;
}
/**
* Interface used to explore [Media Shuttle Share portals](https://help.signiant.com/media-shuttle/using-portals/using-share-portals)
*
* @example
* ```
* import { MediaShuttleResourceFactory, AccountListResponse, PortalListRequest, Portal, PortalBasicRequest, PortalPermissions, PortalFile } from '@signiant/media-shuttle-sdk';
* //...
*
* //This is a simplified example typically there is no need to look up account details more than once per session.
* async fetchFirstPortalFiles (resourceFactory: MediaShuttleResourceFactory): Promise<PortalFile[]> {
* * //See MediaShuttleResourceFactory for instantiation details.
* const explorer: Explorer = resourceFactory.getExplorer();
*
* const showExpiredAccounts: boolean = false;
* const accountsResponse: AccountListResponse = await explorer.listAccounts(showExpiredAccounts);
* const { serviceId, accountId }: { serviceId: string; accountId: string } = accountsResponse.mediaShuttleAccounts[0];
*
* const portalListRequest: PortalListRequest = {
* serviceId,
* accountId
* };
* const portals: Portal[] = await explorer.listPortals(portalListRequest);
* const { portalId }: { portalId: string } = portals[0];
*
* const portalBasicRequest: PortalBasicRequest = {
* serviceId,
* accountId,
* portalId
* };
* const portalPermissions: PortalPermissions = await explorer.getPortalMemberPermissions(portalBasicRequest);
* if (portalPermissions.folders.length > 0) {
* const getFolderContentRequest: GetFolderContentRequest = {
* serviceId,
* accountId,
* portalId,
* folderId: portalPermissions.folders[0].folderId,
* }
*
* //Results are not recursive so if folders are found the request must be repeated per sub folder.
* const files: PortalFile[] = await explorer.getFolderContent(getFolderContentRequest);
* return files;
* }
* throw new Error(`No folder permissions set for portal [${portalId}]`);
* }
* ```
*/
export default interface Explorer {
/**
* List the accounts the user has access to.
* @param {boolean} showExpired flag to also include expired accounts
* @returns {Promise<AccountListResponse>} Promise to resolve a list of accounts
*/
listAccounts(showExpired: boolean): Promise<AccountListResponse>;
/**
* Lists portals where user is a member under a Media Shuttle accountId.
*
* @param {PortalListRequest} request
* @param {string} request.accountId | account identifier
* @param {string} request.serviceId | service identifier
* @param {boolean} request.showExpired | flag to include expired portals in the response
* @returns {Promise<Portal[]>} Promise to resolve a list of portals
*/
listPortals(request: PortalListRequest): Promise<Portal[]>;
/**
* Returns the content of a given portal folder.
* @param {GetFolderContentRequest} request parameters required to get Portal folder contents
* @param {string} request.accountId | account identifier
* @param {string} request.serviceId | service identifier
* @param {string} request.portalId | portal identifier
* @param {string} request.folderId | home or linked folder identifier
* @param {string} request.browsePath | relative folder path to the home or linked folder to be listed
* @returns {Promise<PortalFile[]>} Promise to resolve a list of portal folder content (files/folders)
*/
getFolderContent(request: GetFolderContentRequest): Promise<PortalFile[]>;
/**
* Returns the users member permissions.
* @param {PortalBasicRequest} request
* @param {string} request.accountId | account identifier
* @param {string} request.serviceId | service identifier
* @param {string} request.portalId | portal identifier
* @returns {Promise<PortalPermissions>} Member permissions
*/
getPortalMemberPermissions(request: PortalBasicRequest): Promise<PortalPermissions>;
/**
* Retrieves the metadata form definitions configured for a Media Shuttle portal.
* @param {PortalBasicRequest} request - The request object containing the necessary parameters to identify the portal.
* @param request.accountId - The unique identifier of the account that owns the portal.
* @param request.serviceId - The identifier of the Media Shuttle service within the account.
* @param request.portalId - The unique identifier of the portal whose metadata forms are requested.
*
* @returns A promise that resolves to the portal's metadata form definitions.
*
* @throws Error - If the request fails due to network errors, authorization issues, or a non-2xx API response.
*
*/
getPortalMetadataForms(request: PortalBasicRequest): Promise<PortalMetadataForms>;
/**
* Retrieves a form definition by its unique identifier from the Platform API.
*
* Constructs an authenticated GET request to the `/v1/formDefinitions/{formDefinitionId}` endpoint
* using account- and service-scoped headers generated for the provided identifiers.
*
* @param options - Options used to authorize and locate the form definition.
* @param options.accountId - The account identifier used to scope and authorize the request.
* @param options.serviceId - The service identifier used to scope and authorize the request.
* @param options.formDefinitionId - The unique identifier of the form definition to retrieve.
*
* @returns A promise that resolves to the matching FormDefinition.
*
* @throws {Error} If the request fails due to authentication/authorization errors (e.g., 401/403),
* not found (404), network issues, or any non-2xx HTTP response from the platform.
*
* @example
* ```ts
* const formDef = await platformService.getFormDefinitionById({
* accountId: 'acc_123',
* serviceId: 'svc_456',
* formDefinitionId: 'fd_789',
* });
* console.log(formDef.name);
* ```
*/
getFormDefinitionById(request: GetFormDefinitionRequestOptions): Promise<FormDefinition>;
}
//# sourceMappingURL=Explorer.d.ts.map