@meistrari/vault-sdk 3.3.0 → 3.4.0

package/dist/index.mjs

@@ -1,7 +1,6 @@
-import { z } from 'zod';
+import { CreateAssetUploadResponse, GetUploadUrlResponseV2, GetDownloadUrlResponse } from '@meistrari/vault-shared/schemas';
 import { fileTypeFromBlob } from '@meistrari/file-type';
 import { lookup } from 'mime-types';
-import { GetUploadUrlResponseV2, GetDownloadUrlResponse } from '@meistrari/vault-shared/schemas';
 import vaultUtils from '@meistrari/vault-shared/utils';
 
 var __defProp$3 = Object.defineProperty;
@@ -72,7 +71,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();
@@ -100,7 +99,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";
     }
   }
@@ -132,7 +131,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",
@@ -160,7 +159,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"
@@ -204,13 +203,6 @@ var __publicField$2 = (obj, key, value) => {
   return value;
 };
 const compatibilityDate$1 = "2025-05-19";
-const PublicAssetUploadResponse = z.object({
-  assetId: z.string(),
-  assetUrl: z.string().url(),
-  uploadUrl: z.string().url(),
-  expiresAt: z.string().datetime(),
-  uploadHeaders: z.record(z.string(), z.string())
-});
 async function wrappedFetch$1(url, requestInit) {
   const request = new Request(url, requestInit);
   request.headers.set("User-Agent", userAgent);
@@ -222,18 +214,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();
@@ -244,19 +276,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) => 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);
@@ -265,6 +318,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",
@@ -2098,9 +2161,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/vault-sdk",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   },
   "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"