@alliumcloud/asset-manager 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,397 @@
+/**
+ * Shared primitive types and SDK config used across all modules.
+ */
+type AssetManagerSDKConfig = {
+    apiKey: string;
+    jwksUri?: string;
+    accessTokenProvider: () => string | Promise<string>;
+    timeout?: number;
+    /** @internal - dev only, not for production use */
+    _devBaseUrl?: string;
+};
+type AssetType = "UNREAL_PROJECT" | "OTHER_3D";
+type UploadStatus = "PENDING" | "COMPLETED" | "FAILED";
+type ValidationStatus = "PENDING" | "VALID" | "INVALID";
+type BuildStatus = "PENDING" | "BUILDING" | "COMPLETED" | "FAILED";
+type SourceType = "UNIVERSAL_SCENE";
+declare const SUPPORTED_UNREAL_ENGINE_VERSIONS: readonly ["5.0.3", "5.2.1"];
+type SupportedUnrealEngineVersion = (typeof SUPPORTED_UNREAL_ENGINE_VERSIONS)[number];
+declare const UNREAL_PROJECT_VERSION_TARGETS: readonly ["Development", "Shipping"];
+type UnrealProjectVersionTarget = (typeof UNREAL_PROJECT_VERSION_TARGETS)[number];
+type ProjectVersionState = "new" | "odyssey_plugin_version_invalid" | "failed_missing_unreal_plugin_version" | "failed_missing_unreal_project" | "failed_missing_package_archive_url" | "failed_missing_package_archive_checksum" | "upload_complete" | "upload_invalid" | "upload_failed" | "upload_validating" | "builder_pod_creating" | "builder_pod_failed_to_create" | "builder_pod_timed_out_creating" | "builder_pod_waiting_for_ready" | "builder_pod_failed" | "builder_pod_ready" | "builder_downloading_project_version" | "builder_downloading_project_version_failed" | "builder_finding_project_file_failed" | "builder_copying_plugin_version" | "builder_copying_plugin_version_failed" | "builder_downloading_plugin_version" | "builder_downloading_plugin_version_failed" | "builder_validating" | "builder_validation_failed" | "builder_update_unreal_project_name" | "builder_settings_uploaded" | "builder_building" | "builder_failed" | "builder_retrying" | "builder_uploading" | "builder_upload_failed" | "builder_upload_complete" | "package_validator_required" | "package_validator_pod_creating" | "package_validator_pod_failed_to_create" | "package_validator_pod_waiting_for_ready" | "package_validator_pod_timed_out" | "package_validator_pod_ready" | "package_validator_failed" | "package_validator_retrying" | "package_validator_validating" | "package_validator_updating_unreal_project_name" | "package_validator_updating_project_path" | "package_validator_complete" | "volume_copy_pvcs_creating" | "volume_copy_pvcs_bound" | "volume_copy_pvcs_failed" | "volume_copy_pods_creating" | "volume_copy_pods_failed_to_create" | "volume_copy_pods_timed_out_creating" | "volume_copy_pods_waiting_for_ready" | "volume_copy_pods_failed" | "volume_copy_pods_ready" | "volume_copy_region_copying" | "volume_copy_region_failed" | "volume_copy_region_complete" | "volume_copy_failed" | "volume_copy_retrying" | "volume_copy_complete" | "volume_copy_expiring" | "volume_copy_expired" | "expiring" | "expired";
+type ProjectVersionStateGroup = "uploading" | "validating" | "building" | "deploying" | "complete" | "failed" | "uploaded" | "expired";
+type HealthResponse = {
+    status: string;
+    timestamp: string;
+};
+type RedisHealthResponse = {
+    status: string;
+    latencyMs?: number;
+};
+
+/**
+ * Unreal project version types.
+ */
+
+type UnrealProjectVersion = {
+    id: string;
+    orgId: string;
+    projectId: string;
+    authorUserId: string;
+    appType: string;
+    unrealProjectId: string;
+    buildRegion: string | null;
+    levelFilePath: string | null;
+    levelName: string | null;
+    name: string;
+    packageArchiveSha256Sum: string;
+    packageArchiveUrl: string;
+    pluginVersionId: string;
+    selfPackaged: boolean;
+    state: ProjectVersionState;
+    stateGroup: ProjectVersionStateGroup;
+    symbolsArchiveSha256Sum: string;
+    symbolsArchiveUrl: string;
+    bridgeToolkitFileSettings: Record<string, any>;
+    stateChanges: Record<string, any>;
+    target: string;
+    uploader: string;
+    uploadId: string | null;
+    objectName: string | null;
+    downloadUrl: string | null;
+    uploadSha256Sum: string | null;
+    unrealEngineVersion: string | null;
+    volumeCopyRegionsComplete: string[];
+    volumeRegions: string[];
+    volumeSizeGb: number;
+    unrealProjectDirectoryPath: string | null;
+    disableMultiplayer: boolean | null;
+    lastPingFromBuilder: Date | null;
+    lastPingFromVolumeCopyRegion: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+};
+type CreateUnrealProjectVersionInput = {
+    orgId: string;
+    projectId: string;
+    authorUserId: string;
+    appType: string;
+    unrealProjectId: string;
+    name: string;
+    pluginVersionId: string;
+    selfPackaged: boolean;
+    state: ProjectVersionState;
+    target: UnrealProjectVersionTarget;
+    uploader: string;
+    packageArchiveSha256Sum: string;
+    packageArchiveUrl: string;
+    symbolsArchiveSha256Sum: string;
+    symbolsArchiveUrl: string;
+    bridgeToolkitFileSettings: Record<string, any>;
+    stateChanges: Record<string, any>;
+    volumeCopyRegionsComplete: string[];
+    volumeRegions: string[];
+    volumeSizeGb: number;
+    buildRegion?: string;
+    unrealEngineVersion?: SupportedUnrealEngineVersion;
+    uploadId?: string;
+    objectName?: string;
+    downloadUrl?: string;
+    uploadSha256Sum?: string;
+    unrealProjectDirectoryPath?: string;
+    disableMultiplayer?: boolean;
+    lastPingFromBuilder?: Date;
+    lastPingFromVolumeCopyRegion?: Date;
+    levelFilePath?: string;
+    levelName?: string;
+};
+type UpdateUnrealProjectVersionInput = Record<string, any>;
+
+/**
+ * Asset-related types.
+ */
+
+type AssetResponse = {
+    id: string;
+    name: string;
+    orgId: string;
+    projectId: string;
+    assetType: AssetType;
+    sourceType: SourceType;
+    uploadStatus: UploadStatus;
+    validationStatus: ValidationStatus;
+    buildStatus: BuildStatus;
+    uploadId: string | null;
+    objectName: string | null;
+    downloadUrl: string | null;
+    thumb: string | null;
+    description: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+};
+type UnrealProjectResponse = {
+    assetId: string;
+    orgId: string;
+    projectId: string;
+    displayName: string;
+    unrealProjectVersion: string;
+    unrealPluginVersion: string;
+    versions?: UnrealProjectVersion[];
+    createdAt: Date;
+    updatedAt: Date;
+};
+type Other3dResponse = {
+    assetId: string;
+    orgId: string;
+    projectId: string;
+    displayName: string;
+    unrealPluginVersion: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
+type AssetWithRelations = AssetResponse & {
+    unrealProjects?: UnrealProjectResponse[];
+    other3d?: Other3dResponse[];
+};
+type CreateAssetInput = {
+    name: string;
+    orgId: string;
+    projectId: string;
+    assetType: AssetType;
+    sourceType: SourceType;
+    storageBucket: string;
+    storagePath: string;
+};
+type UpdateUnrealProjectInput = {
+    displayName?: string;
+    unrealProjectVersion?: string;
+    unrealPluginVersion?: string;
+};
+type UpdateOther3dInput = {
+    displayName?: string;
+    unrealPluginVersion?: string;
+};
+type UpdateAssetInput = {
+    name?: string;
+    uploadStatus?: UploadStatus;
+    validationStatus?: ValidationStatus;
+    buildStatus?: BuildStatus;
+    storageBucket?: string;
+    storagePath?: string;
+    uploadId?: string;
+    objectName?: string;
+    downloadUrl?: string;
+    thumb?: string;
+    description?: string;
+    unrealProject?: UpdateUnrealProjectInput;
+    other3d?: UpdateOther3dInput;
+};
+type UpdateAssetStatusInput = {
+    uploadStatus?: UploadStatus;
+    validationStatus?: ValidationStatus;
+    buildStatus?: BuildStatus;
+};
+
+/**
+ * User types.
+ */
+type User = {
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
+type CreateUserInput = {
+    id?: string;
+};
+type UpdateUserInput = {
+    id?: string;
+};
+
+/**
+ * Upload and session recovery types.
+ */
+
+type InitiateUploadRequest = {
+    orgId: string;
+    projectId: string;
+    userId: string;
+    assetType: AssetType;
+    assetFilename: string;
+    assetDisplayName?: string;
+    unrealProjectId?: string;
+    unrealProjectDisplayName?: string;
+    unrealEngineVersion?: SupportedUnrealEngineVersion;
+    selfPackaged?: boolean;
+    target?: UnrealProjectVersionTarget;
+    other_3dId?: string;
+    other_3dDisplayName?: string;
+    buildRegion?: string;
+    volumeRegions?: string[];
+};
+type InitiateUploadResponse = {
+    orgId: string;
+    projectId: string;
+    assetId: string;
+    assetVersionId: string;
+    uploadId: string;
+    objectName: string;
+};
+type CompleteUploadRequest = {
+    orgId: string;
+    projectId: string;
+    assetId: string;
+    assetType: AssetType;
+    assetVersionId: string;
+    uploadId: string;
+    objectName: string;
+    parts: {
+        partNumber: number;
+        etag: string;
+    }[];
+    failed?: boolean;
+    sha256Sum?: string;
+};
+type AbortUploadRequest = {
+    orgId: string;
+    projectId: string;
+    assetId: string;
+    assetType: AssetType;
+    assetVersionId: string;
+    uploadId: string;
+    objectName: string;
+};
+type UploadSession = {
+    orgId: string;
+    projectId: string;
+    assetId: string;
+    assetVersionId: string;
+    uploadId: string;
+    objectName: string;
+};
+type UploadPart = {
+    partNumber: number;
+    etag: string;
+};
+
+/**
+ * Deep sanitization types.
+ */
+type DeletionStepResult = {
+    step: string;
+    success: boolean;
+    skipped?: boolean;
+    error?: string;
+};
+type DeleteProjectReport = {
+    assetId: string;
+    assetType: "UNREAL_PROJECT" | "OTHER_3D";
+    orgId: string;
+    projectId: string;
+    steps: DeletionStepResult[];
+    fullyDeleted: boolean;
+};
+
+/**
+ * Health module — server and Redis health checks.
+ */
+
+interface HealthHandle {
+    getHealth(): Promise<HealthResponse>;
+    getRedisHealth(): Promise<RedisHealthResponse>;
+    testRedis(): Promise<void>;
+}
+
+/**
+ * Assets module — CRUD operations for assets.
+ */
+
+interface AssetsHandle {
+    create(data: CreateAssetInput): Promise<AssetWithRelations>;
+    getAll(): Promise<AssetWithRelations[]>;
+    getById(assetId: string): Promise<AssetWithRelations>;
+    getByOrg(orgId: string): Promise<AssetWithRelations[]>;
+    getByProject(projectId: string): Promise<AssetWithRelations[]>;
+    update(assetId: string, data: UpdateAssetInput): Promise<AssetWithRelations>;
+    updateStatus(assetId: string, data: UpdateAssetStatusInput): Promise<AssetWithRelations>;
+    markAsUploaded(assetId: string): Promise<AssetWithRelations>;
+    markAsValidated(assetId: string): Promise<AssetWithRelations>;
+    markAsFailed(assetId: string, stage: "upload" | "validation" | "build"): Promise<AssetWithRelations>;
+    uploadThumb(assetId: string, userId: string, file: File | Blob): Promise<AssetWithRelations>;
+    delete(assetId: string): Promise<void>;
+}
+
+/**
+ * Versions module — Unreal project version operations.
+ */
+
+interface VersionsHandle {
+    create(data: CreateUnrealProjectVersionInput): Promise<UnrealProjectVersion>;
+    getById(versionId: string): Promise<UnrealProjectVersion>;
+    getByAsset(assetId: string): Promise<UnrealProjectVersion[]>;
+    update(versionId: string, data: UpdateUnrealProjectVersionInput): Promise<UnrealProjectVersion>;
+    delete(versionId: string): Promise<void>;
+    deleteByAsset(assetId: string): Promise<void>;
+}
+
+/**
+ * Users module — user management operations.
+ */
+
+interface UsersHandle {
+    getAll(): Promise<User[]>;
+    getById(userId: string): Promise<User>;
+    create(data: CreateUserInput): Promise<User>;
+    update(userId: string, data: UpdateUserInput): Promise<User>;
+    delete(userId: string): Promise<void>;
+}
+
+/**
+ * Upload module — multipart upload lifecycle management.
+ */
+
+interface UploadHandle {
+    initiate(data: InitiateUploadRequest): Promise<InitiateUploadResponse>;
+    getSignedUrl(orgId: string, projectId: string, assetId: string, assetVersionId: string, uploadId: string, objectName: string, partNumber: number): Promise<string>;
+    batchGetSignedUrls(orgId: string, projectId: string, assetId: string, assetVersionId: string, uploadId: string, objectName: string, partNumbers: number[]): Promise<Record<number, string>>;
+    complete(data: CompleteUploadRequest): Promise<AssetWithRelations>;
+    abort(data: AbortUploadRequest): Promise<void>;
+    deleteRecords(data: AbortUploadRequest): Promise<void>;
+    getSession(filename: string): Promise<UploadSession | null>;
+    listParts(objectName: string, uploadId: string): Promise<UploadPart[]>;
+}
+
+/**
+ * Sanitization module — deep project deletion operations.
+ */
+
+interface SanitizationHandle {
+    deleteProjectAndFootprint(assetId: string): Promise<DeleteProjectReport>;
+}
+
+/**
+ * SDK Error factories.
+ */
+interface AlliumError extends Error {
+    readonly code: string;
+}
+/** Type guard — works for all Allium error factories */
+declare function isAlliumError(err: unknown): err is AlliumError;
+
+interface AssetManagerSDKHandle {
+    health: HealthHandle;
+    assets: AssetsHandle;
+    versions: VersionsHandle;
+    users: UsersHandle;
+    upload: UploadHandle;
+    sanitization: SanitizationHandle;
+}
+declare function createAssetManagerSDK(config: AssetManagerSDKConfig): AssetManagerSDKHandle;
+declare const AssetManagerSDK: {
+    /**
+     * Create a new SDK client instance.
+     * @param config  SDK configuration — apiKey is required, timeout is optional.
+     */
+    readonly create: (config: AssetManagerSDKConfig) => AssetManagerSDKHandle;
+};
+
+export { type AbortUploadRequest, type AlliumError, type AssetManagerSDKConfig, type AssetManagerSDKHandle, type AssetType, type AssetWithRelations, type BuildStatus, type CompleteUploadRequest, type CreateUserInput, type DeleteProjectReport, type DeletionStepResult, type HealthResponse, type InitiateUploadRequest, type InitiateUploadResponse, type RedisHealthResponse, type UnrealProjectVersion, type UpdateAssetInput, type UpdateUnrealProjectVersionInput, type UpdateUserInput, type UploadPart, type UploadSession, type UploadStatus, type User, type ValidationStatus, createAssetManagerSDK, AssetManagerSDK as default, isAlliumError };