@meistrari/vault-sdk 3.2.1 → 3.4.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { SerializedPermalink, FileMetadata } from '@meistrari/vault-shared/schemas';
+import { AssetMetadata, SerializedPermalink, FileMetadata } from '@meistrari/vault-shared/schemas';
+export { AssetMetadata } from '@meistrari/vault-shared/schemas';
 
 interface AuthStrategy {
     getHeaders: () => Headers;
@@ -28,6 +29,150 @@ type VaultConfig = {
     authStrategy: AuthStrategy;
 };
 
+/**
+ * Parameters for creating an asset upload URL.
+ */
+type CreateAssetUploadParams = {
+    /** Application-defined class for grouping assets, such as `avatar` or `cover-image`. */
+    assetClass: string;
+    /**
+     * Opaque application-owned entity reference for this asset.
+     *
+     * Use a stable, namespaced value that points to the domain object the asset represents
+     * or belongs to, such as `user:user_123`, `organization:org_123`, or `app:app_123`.
+     * Vault stores this value for lookup and cleanup workflows but does not interpret it,
+     * enforce authorization from it, or include it in the stable asset URL.
+     */
+    subject: string;
+    /** MIME type of the content that will be uploaded. */
+    mimeType: string;
+    /** Size of the content in bytes, when known. */
+    size?: number;
+};
+/**
+ * Parameters for creating an asset from in-memory content.
+ */
+type CreateAssetFromContentParams = {
+    /** Application-defined class for grouping assets, such as `avatar` or `cover-image`. */
+    assetClass: string;
+    /**
+     * Opaque application-owned entity reference for this asset.
+     *
+     * Use a stable, namespaced value that points to the domain object the asset represents
+     * or belongs to, such as `user:user_123`, `organization:org_123`, or `app:app_123`.
+     * Vault stores this value for lookup and cleanup workflows but does not interpret it,
+     * enforce authorization from it, or include it in the stable asset URL.
+     */
+    subject: string;
+    /** MIME type override. When omitted, the SDK attempts to detect the content type. */
+    mimeType?: string;
+    /** Whether to upload the content immediately after creating the asset. */
+    upload?: boolean;
+};
+/** Values required to construct a VaultAsset instance. */
+type VaultAssetParams = {
+    /** Vault-assigned asset ID. */
+    assetId: string;
+    /** Stable URL used to resolve or download the asset. */
+    assetUrl: string | URL;
+    /** Presigned URL used to upload the asset content. */
+    uploadUrl: string | URL;
+    /** Expiration time for the presigned upload URL. */
+    expiresAt: string | Date;
+    /** Headers that must be sent with the presigned upload request. */
+    uploadHeaders: Record<string, string>;
+    /** Stored asset metadata returned by Vault. */
+    asset: AssetMetadata;
+};
+/**
+ * Represents a Vault asset with a stable asset URL and a presigned upload URL.
+ */
+declare class VaultAsset {
+    /** Vault-assigned asset ID. */
+    readonly assetId: string;
+    /** Stable URL used to resolve or download the asset. */
+    readonly assetUrl: URL;
+    /** Presigned URL used to upload asset content. */
+    readonly uploadUrl: URL;
+    /** Expiration time for the presigned upload URL. */
+    readonly expiresAt: Date;
+    /** Headers that must be sent when uploading to {@link VaultAsset.uploadUrl}. */
+    readonly uploadHeaders: Record<string, string>;
+    /** Stored asset metadata returned by Vault. */
+    readonly asset: AssetMetadata;
+    /**
+     * Constructs a VaultAsset instance from Vault response data.
+     *
+     * Direct usage of the constructor is not usually needed. Prefer
+     * {@link VaultAsset.create} or {@link VaultAsset.fromContent}.
+     *
+     * @param params - Values returned by Vault when creating an asset upload.
+     * @param params.assetId - Vault-assigned asset ID.
+     * @param params.assetUrl - Stable URL used to resolve or download the asset.
+     * @param params.uploadUrl - Presigned URL used to upload the asset content.
+     * @param params.expiresAt - Expiration time for the presigned upload URL.
+     * @param params.uploadHeaders - Headers required by the presigned upload URL.
+     * @param params.asset - Stored asset metadata returned by Vault.
+     */
+    constructor({ assetId, assetUrl, uploadUrl, expiresAt, uploadHeaders, asset }: VaultAssetParams);
+    /**
+     * Creates an asset upload URL without uploading content.
+     *
+     * Use {@link VaultAsset.upload} to upload content later, or use
+     * {@link VaultAsset.fromContent} with `upload: true` to create and upload in one call.
+     *
+     * @param vaultConfig - Vault client configuration.
+     * @param params - Parameters for the asset upload.
+     * @param params.assetClass - Application-defined class for grouping assets.
+     * @param params.subject - Opaque application-owned entity reference for lookup and cleanup. Use a stable namespaced value such as `user:user_123`; Vault does not interpret it or include it in the asset URL.
+     * @param params.mimeType - MIME type of the content that will be uploaded.
+     * @param params.size - Size of the content in bytes, when known.
+     * @param options - Additional options for the request.
+     * @param options.signal - Signal used to abort the request.
+     * @returns A VaultAsset containing the asset URL and presigned upload URL.
+     * @throws {FetchError} If Vault rejects the create request.
+     * @throws {Error} If Vault returns a response that does not match the SDK schema.
+     */
+    static create(vaultConfig: VaultConfig, params: CreateAssetUploadParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<VaultAsset>;
+    /**
+     * Creates an asset from Blob or File content.
+     *
+     * The SDK detects the MIME type when `params.mimeType` is omitted. Set
+     * `params.upload` to `true` to upload the content immediately.
+     *
+     * @param vaultConfig - Vault client configuration.
+     * @param content - Content to associate with the asset.
+     * @param params - Parameters for the asset.
+     * @param params.assetClass - Application-defined class for grouping assets.
+     * @param params.subject - Opaque application-owned entity reference for lookup and cleanup. Use a stable namespaced value such as `user:user_123`; Vault does not interpret it or include it in the asset URL.
+     * @param params.mimeType - MIME type override for the content.
+     * @param params.upload - Whether to upload the content immediately after creating the asset.
+     * @param options - Additional options for the create and upload requests.
+     * @param options.signal - Signal used to abort either request.
+     * @returns A VaultAsset containing the asset URL and presigned upload URL.
+     * @throws {FetchError} If Vault rejects the create request or the upload request fails.
+     * @throws {Error} If Vault returns a response that does not match the SDK schema.
+     */
+    static fromContent(vaultConfig: VaultConfig, content: Blob | File, params: CreateAssetFromContentParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<VaultAsset>;
+    /**
+     * Uploads content to this asset's presigned upload URL.
+     *
+     * The upload request sends the headers returned by Vault when the asset was created.
+     *
+     * @param content - Content to upload.
+     * @param options - Additional options for the upload request.
+     * @param options.signal - Signal used to abort the upload.
+     * @throws {FetchError} If the upload endpoint returns an error response.
+     */
+    upload(content: Blob | File, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+
 declare class Permalink {
     private readonly config;
     readonly id: string;
@@ -1349,57 +1494,124 @@ declare function getVaultParamsFromS3Url(url: string): {
     parentId: string | null;
 } | null;
 
+/** Options shared by content-based file creation overloads. */
+type CreateFromContentOptions = {
+    /** Signal used to abort the request. */
+    signal?: AbortSignal;
+    /** Parent file ID for hierarchical file relationships. */
+    parentId?: string;
+    /** MIME type override for the uploaded content. */
+    mimeType?: string;
+    /** Whether to upload the content immediately after creating the file metadata. */
+    upload?: boolean;
+};
+/** Options for fetching an existing Vault file by reference. */
+type CreateFromReferenceOptions = {
+    /** Signal used to abort the request. */
+    signal?: AbortSignal;
+};
+/** Options for stream-based file creation. */
+type CreateFromStreamOptions = {
+    /** MIME type of the stream content. */
+    contentType?: string;
+    /** Signal used to abort the request. */
+    signal?: AbortSignal;
+    /** Parent file ID for hierarchical file relationships. */
+    parentId?: string;
+};
+/** File input used by bulk content creation. */
+type CreateFromContentBulkFile = {
+    /** File or Blob content to register and optionally upload. */
+    content: Blob | File;
+    /** File name override. */
+    name?: string;
+    /** MIME type override for the content. */
+    mimeType?: string;
+    /** Parent file ID for hierarchical file relationships. */
+    parentId?: string;
+    /** Behavior when the requested parent cannot be found. */
+    onMissingParent?: 'error' | 'create-as-root';
+    /** Behavior when the file already exists under a different parent. */
+    onParentConflict?: 'error' | 'update-parent-id' | 'ignore';
+};
+/** Options for bulk content creation. */
+type CreateFromContentBulkOptions = {
+    /** Whether to upload all created files immediately. */
+    upload?: boolean;
+    /** Signal used to abort the request. */
+    signal?: AbortSignal;
+};
+/** File input used by bulk stream creation. */
+type CreateFromStreamBulkFile = {
+    /** Name of the file represented by the stream. */
+    name: string;
+    /** Size of the stream content in bytes. */
+    contentLength: number;
+    /** MIME type of the stream content. */
+    contentType?: string;
+    /** Parent file ID for hierarchical file relationships. */
+    parentId?: string;
+    /** Behavior when the requested parent cannot be found. */
+    onMissingParent?: 'error' | 'create-as-root';
+    /** Behavior when the file already exists under a different parent. */
+    onParentConflict?: 'error' | 'update-parent-id' | 'ignore';
+};
+/** Options for bulk stream creation. */
+type CreateFromStreamBulkOptions = {
+    /** Signal used to abort the request. */
+    signal?: AbortSignal;
+};
+/** Options shared by asset creation helpers. */
+type AssetRequestOptions = {
+    /** Signal used to abort the request. */
+    signal?: AbortSignal;
+};
+/**
+ * Creates a Vault SDK client bound to a Vault URL and auth strategy.
+ *
+ * @param vaultConfig - Vault client configuration.
+ * @param vaultConfig.vaultUrl - Base URL for the Vault API.
+ * @param vaultConfig.authStrategy - Auth strategy used to sign Vault requests.
+ * @returns Client helpers for files, streams, bulk creation, references, and assets.
+ */
 declare function vaultClient(vaultConfig: VaultConfig): {
     createFromContent: {
-        (name: string, content: Blob | File, options?: {
-            signal?: AbortSignal;
-            parentId?: string;
-            mimeType?: string;
-            upload?: boolean;
-        }): Promise<VaultFile>;
-        (content: Blob | File, name?: string, options?: {
-            signal?: AbortSignal;
-            parentId?: string;
-            mimeType?: string;
-            upload?: boolean;
-        }): Promise<VaultFile>;
-        (content: Blob | File, options: {
-            signal?: AbortSignal;
-            parentId?: string;
-            mimeType?: string;
-            upload?: boolean;
-        }): Promise<VaultFile>;
+        (name: string, content: Blob | File, options?: CreateFromContentOptions): Promise<VaultFile>;
+        (content: Blob | File, name?: string, options?: CreateFromContentOptions): Promise<VaultFile>;
+        (content: Blob | File, options: CreateFromContentOptions): Promise<VaultFile>;
+    };
+    createFromReference: (reference: string, options?: CreateFromReferenceOptions) => Promise<VaultFile>;
+    createFromStream: (name: string, contentLength: number, options?: CreateFromStreamOptions) => Promise<VaultFile>;
+    createFromContentBulk: (files: CreateFromContentBulkFile[], options?: CreateFromContentBulkOptions) => Promise<VaultFile[]>;
+    createFromStreamBulk: (files: CreateFromStreamBulkFile[], options?: CreateFromStreamBulkOptions) => Promise<VaultFile[]>;
+    assets: {
+        /**
+         * Creates an asset upload URL without uploading content.
+         *
+         * `params.subject` should be a stable application-owned entity reference such as
+         * `user:user_123` or `organization:org_123`. Vault stores it for lookup and cleanup,
+         * but does not interpret it, enforce authorization from it, or include it in the asset URL.
+         *
+         * @param params - Parameters for the asset upload.
+         * @param options - Additional options for the request.
+         * @returns A VaultAsset with the stable asset URL and presigned upload URL.
+         */
+        create(params: CreateAssetUploadParams, options?: AssetRequestOptions): Promise<VaultAsset>;
+        /**
+         * Creates an asset from File or Blob content and optionally uploads it immediately.
+         *
+         * `params.subject` should be a stable application-owned entity reference such as
+         * `user:user_123` or `organization:org_123`. Vault stores it for lookup and cleanup,
+         * but does not interpret it, enforce authorization from it, or include it in the asset URL.
+         *
+         * @param content - File or Blob content to associate with the asset.
+         * @param params - Parameters for the asset.
+         * @param options - Additional options for the create and upload requests.
+         * @returns A VaultAsset with the stable asset URL and presigned upload URL.
+         */
+        createFromContent(content: Blob | File, params: CreateAssetFromContentParams, options?: AssetRequestOptions): Promise<VaultAsset>;
     };
-    createFromReference: (reference: string, options?: {
-        signal?: AbortSignal;
-    }) => Promise<VaultFile>;
-    createFromStream: (name: string, contentLength: number, options?: {
-        contentType?: string;
-        signal?: AbortSignal;
-        parentId?: string;
-    }) => Promise<VaultFile>;
-    createFromContentBulk: (files: Array<{
-        content: Blob | File;
-        name?: string;
-        mimeType?: string;
-        parentId?: string;
-        onMissingParent?: "error" | "create-as-root";
-        onParentConflict?: "error" | "update-parent-id" | "ignore";
-    }>, options?: {
-        upload?: boolean;
-        signal?: AbortSignal;
-    }) => Promise<VaultFile[]>;
-    createFromStreamBulk: (files: Array<{
-        name: string;
-        contentLength: number;
-        contentType?: string;
-        parentId?: string;
-        onMissingParent?: "error" | "create-as-root";
-        onParentConflict?: "error" | "update-parent-id" | "ignore";
-    }>, options?: {
-        signal?: AbortSignal;
-    }) => Promise<VaultFile[]>;
 };
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, extractVaultReferences, getVaultParamsFromS3Url, isS3UrlExpired, isTaggedVaultPresignedUrl, isPresignedS3Url as isVaultFileS3Url, isVaultReference, vaultClient };
-export type { AuthStrategy, VaultConfig };
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, Permalink, VaultAsset, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, extractVaultReferences, getVaultParamsFromS3Url, isS3UrlExpired, isTaggedVaultPresignedUrl, isPresignedS3Url as isVaultFileS3Url, isVaultReference, vaultClient };
+export type { AuthStrategy, CreateAssetFromContentParams, CreateAssetUploadParams, VaultConfig };