@meistrari/vault-sdk 3.3.0 → 3.4.0

package/README.md

@@ -1,8 +1,8 @@
 # Vault SDK
 
-TypeScript SDK for interacting with the Vault file storage service. It supports file upload, download, streaming uploads, file hierarchies, public assets, permalinks, and vault reference utilities.
+TypeScript SDK for interacting with the Vault file storage service. It supports file upload, download, streaming uploads, file hierarchies, assets, permalinks, and vault reference utilities.
 
-Use the SDK when an application needs to store private files in Vault, publish stable public asset URLs such as avatars or logos, or keep durable `vault://` references instead of temporary presigned URLs.
+Use the SDK when an application needs to store private files in Vault, publish stable asset URLs such as avatars or logos, or keep durable `vault://` references instead of temporary presigned URLs.
 
 ## Installation
 

package/dist/index.cjs

@@ -1,9 +1,8 @@
 'use strict';
 
-const zod = require('zod');
+const schemas = require('@meistrari/vault-shared/schemas');
 const fileType = require('@meistrari/file-type');
 const mimeTypes = require('mime-types');
-const schemas = require('@meistrari/vault-shared/schemas');
 const vaultUtils = require('@meistrari/vault-shared/utils');
 
 function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
@@ -78,7 +77,7 @@ async function getFileHash(blob) {
 }
 async function detectFileMimeType(blob) {
   if (blob instanceof Blob && blob.type) {
-    return blob.type.split(";")[0].trim();
+    return blob.type.split(";")[0]?.trim();
   }
   if ("name" in blob && typeof blob.name === "string") {
     const extension = blob.name.split(".").pop()?.toLowerCase();
@@ -106,7 +105,7 @@ async function detectFileMimeType(blob) {
   if (lines.length > 1) {
     const commaCounts = lines.map((line) => (line.match(/,/g) || []).length);
     const allSame = commaCounts.every((count) => count === commaCounts[0]);
-    if (allSame && commaCounts[0] > 0) {
+    if (allSame && (commaCounts[0] ?? 0) > 0) {
       return "text/csv";
     }
   }
@@ -138,7 +137,7 @@ function getFileName(content) {
 }
 
 const name = "@meistrari/vault-sdk";
-const version = "3.3.0";
+const version = "3.4.0";
 const license = "UNLICENSED";
 const repository = {
 	type: "git",
@@ -166,7 +165,7 @@ const scripts = {
 };
 const dependencies = {
 	"@meistrari/file-type": "22.0.0",
-	"@meistrari/vault-shared": "0.1.2",
+	"@meistrari/vault-shared": "0.2.0",
 	"mime-types": "3.0.1",
 	ofetch: "1.4.1",
 	zod: "4.3.6"
@@ -210,13 +209,6 @@ var __publicField$2 = (obj, key, value) => {
   return value;
 };
 const compatibilityDate$1 = "2025-05-19";
-const PublicAssetUploadResponse = zod.z.object({
-  assetId: zod.z.string(),
-  assetUrl: zod.z.string().url(),
-  uploadUrl: zod.z.string().url(),
-  expiresAt: zod.z.string().datetime(),
-  uploadHeaders: zod.z.record(zod.z.string(), zod.z.string())
-});
 async function wrappedFetch$1(url, requestInit) {
   const request = new Request(url, requestInit);
   request.headers.set("User-Agent", userAgent);
@@ -228,18 +220,58 @@ async function wrappedFetch$1(url, requestInit) {
   return response;
 }
 class VaultAsset {
-  constructor({ assetId, assetUrl, uploadUrl, expiresAt, uploadHeaders }) {
+  /**
+   * 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 }) {
+    /** Vault-assigned asset ID. */
     __publicField$2(this, "assetId");
+    /** Stable URL used to resolve or download the asset. */
     __publicField$2(this, "assetUrl");
+    /** Presigned URL used to upload asset content. */
     __publicField$2(this, "uploadUrl");
+    /** Expiration time for the presigned upload URL. */
     __publicField$2(this, "expiresAt");
+    /** Headers that must be sent when uploading to {@link VaultAsset.uploadUrl}. */
     __publicField$2(this, "uploadHeaders");
+    /** Stored asset metadata returned by Vault. */
+    __publicField$2(this, "asset");
     this.assetId = assetId;
     this.assetUrl = new URL(assetUrl);
     this.uploadUrl = new URL(uploadUrl);
     this.expiresAt = new Date(expiresAt);
     this.uploadHeaders = uploadHeaders;
+    this.asset = asset;
   }
+  /**
+   * 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 async create(vaultConfig, params, options) {
     const config = resolveConfig(vaultConfig);
     const headers = config.authStrategy.getHeaders();
@@ -250,19 +282,40 @@ class VaultAsset {
       headers,
       body: JSON.stringify({
         assetClass: params.assetClass,
+        subject: params.subject,
         mimeType: params.mimeType,
         size: params.size
       })
-    }).then(async (response2) => await response2.json()).then((data) => PublicAssetUploadResponse.safeParse(data));
+    }).then(async (response2) => await response2.json()).then((data) => schemas.CreateAssetUploadResponse.safeParse(data));
     if (!response.success) {
       throw new Error(`Invalid response from vault service. ${JSON.stringify(response.error)}`);
     }
     return new VaultAsset(response.data);
   }
+  /**
+   * 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 async fromContent(vaultConfig, content, params, options) {
     const mimeType = params.mimeType ?? await detectFileMimeType(content) ?? "application/octet-stream";
     const asset = await VaultAsset.create(vaultConfig, {
       assetClass: params.assetClass,
+      subject: params.subject,
       mimeType,
       size: content.size
     }, options);
@@ -271,6 +324,16 @@ class VaultAsset {
     }
     return asset;
   }
+  /**
+   * 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.
+   */
   async upload(content, options) {
     await wrappedFetch$1(this.uploadUrl, {
       method: "PUT",
@@ -2104,9 +2167,32 @@ function vaultClient(vaultConfig) {
     }, { signal: options?.signal });
   }
   const 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.
+     */
     async create(params, options) {
       return await VaultAsset.create(config, params, { signal: options?.signal });
     },
+    /**
+     * 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.
+     */
     async createFromContent(content, params, options) {
       return await VaultAsset.fromContent(config, content, params, { signal: options?.signal });
     }

package/dist/index.d.cts

@@ -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,36 +29,145 @@ 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>;
-    constructor({ assetId, assetUrl, uploadUrl, expiresAt, uploadHeaders }: VaultAssetParams);
+    /** 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>;
@@ -1384,63 +1494,122 @@ 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?: {
-        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[]>;
+    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: {
-        create(params: CreateAssetUploadParams, options?: {
-            signal?: AbortSignal;
-        }): Promise<VaultAsset>;
-        createFromContent(content: Blob | File, params: CreateAssetFromContentParams, options?: {
-            signal?: AbortSignal;
-        }): Promise<VaultAsset>;
+        /**
+         * 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>;
     };
 };