@meistrari/vault-sdk 1.9.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -237,7 +237,7 @@ function getFileName(content) {
237
237
  }
238
238
 
239
239
  const name = "@meistrari/vault-sdk";
240
- const version = "1.9.0";
240
+ const version = "2.0.0";
241
241
  const license = "UNLICENSED";
242
242
  const repository = {
243
243
  type: "git",
@@ -264,8 +264,8 @@ const scripts = {
264
264
  check: "bun run lint && bun tsc --noEmit"
265
265
  };
266
266
  const dependencies = {
267
- "@meistrari/vault-shared": "workspace:*",
268
267
  "@meistrari/file-type": "22.0.0",
268
+ "@meistrari/vault-shared": "workspace:*",
269
269
  "mime-types": "3.0.1",
270
270
  ofetch: "1.4.1",
271
271
  zod: "3.23.8"
@@ -326,6 +326,7 @@ async function wrappedFetch(url, requestInit) {
326
326
  };
327
327
  const request = new Request(url, options);
328
328
  request.headers.set("User-Agent", userAgent);
329
+ request.headers.set("x-compatibility-date", compatibilityDate);
329
330
  const response = await fetch(request);
330
331
  if (!response.ok) {
331
332
  throw await FetchError.from(request.url, request.method, response);
@@ -369,9 +370,7 @@ class VaultFile {
369
370
  * @returns The headers for the request
370
371
  */
371
372
  get headers() {
372
- const headers = this.config.authStrategy.getHeaders();
373
- headers.set("User-Agent", userAgent);
374
- return headers;
373
+ return this.config.authStrategy.getHeaders();
375
374
  }
376
375
  /**
377
376
  * Performs a request to the vault service and handles the response or errors.
@@ -388,7 +387,6 @@ class VaultFile {
388
387
  const { method, path, body, signal, query } = params;
389
388
  const url = new URL(path, this.baseUrl);
390
389
  const headers = new Headers(this.headers);
391
- headers.set("x-compatibility-date", compatibilityDate);
392
390
  if (query) {
393
391
  Object.entries(query).forEach(([key, value]) => {
394
392
  url.searchParams.set(key, value);
@@ -675,6 +673,84 @@ class VaultFile {
675
673
  }, { signal: options?.signal });
676
674
  return file;
677
675
  }
676
+ /**
677
+ * Creates multiple VaultFile instances from given content in a single request.
678
+ *
679
+ * @param params - Parameters for creating VaultFiles from content
680
+ * @param params.files - Array of file inputs with content and optional metadata
681
+ * @param params.config - The configuration for the VaultFiles
682
+ * @param params.upload - Whether to upload all files (default: false)
683
+ * @param options - The options for the request
684
+ * @param options.signal - The signal to abort the request
685
+ *
686
+ * @returns Array of new VaultFile instances
687
+ *
688
+ * @example
689
+ * ```ts
690
+ * const files = await VaultFile.fromContentBulk({
691
+ * files: [
692
+ * { content: blob1, name: 'file1.txt' },
693
+ * { content: blob2, name: 'file2.txt', parentId: 'parent-id' },
694
+ * ],
695
+ * config: { vaultUrl, authStrategy },
696
+ * upload: true
697
+ * })
698
+ * ```
699
+ */
700
+ static async fromContentBulk(params, options) {
701
+ const { files: fileInputs, config: vaultConfig, upload = false } = params;
702
+ const config = resolveConfig(vaultConfig);
703
+ const preparedFiles = await Promise.all(
704
+ fileInputs.map(async (input) => {
705
+ const name = basename(input.name) ?? getFileName(input.content);
706
+ const sha256sum = await getFileHash(input.content);
707
+ const mimeType = input.mimeType ?? await detectFileMimeType(input.content);
708
+ const size = input.content.size;
709
+ return { ...input, name, sha256sum, mimeType, size };
710
+ })
711
+ );
712
+ const url = new URL("files/bulk", config.vaultUrl);
713
+ const headers = config.authStrategy.getHeaders();
714
+ headers.set("Content-Type", "application/json");
715
+ const body = preparedFiles.map((file) => ({
716
+ fileName: file.name,
717
+ sha256sum: file.sha256sum,
718
+ mimeType: file.mimeType,
719
+ size: file.size,
720
+ parentId: file.parentId,
721
+ onMissingParent: file.onMissingParent,
722
+ onParentConflict: file.onParentConflict
723
+ }));
724
+ const response = await wrappedFetch(url, {
725
+ method: "POST",
726
+ headers,
727
+ body: JSON.stringify(body),
728
+ signal: options?.signal
729
+ });
730
+ const data = await response.json();
731
+ const vaultFiles = data.map((item, index) => {
732
+ const file = new VaultFile({
733
+ config,
734
+ id: item.id,
735
+ name: item.metadata?.originalFileName ?? preparedFiles[index].name,
736
+ content: preparedFiles[index].content,
737
+ metadata: item.metadata
738
+ });
739
+ file.lastUploadUrl = {
740
+ url: new URL(item.uploadUrl),
741
+ expiresAt: new Date(item.expiresAt)
742
+ };
743
+ return file;
744
+ });
745
+ if (upload) {
746
+ await Promise.all(
747
+ vaultFiles.map(
748
+ (file) => file.upload(void 0, void 0, { signal: options?.signal })
749
+ )
750
+ );
751
+ }
752
+ return vaultFiles;
753
+ }
678
754
  /**
679
755
  * Fetches and populates the metadata fields for this VaultFile instance.
680
756
  *
@@ -1596,8 +1672,80 @@ class VaultFile {
1596
1672
  options
1597
1673
  );
1598
1674
  }
1675
+ /**
1676
+ * Updates the metadata of this file in the vault.
1677
+ *
1678
+ * This method allows you to modify specific metadata properties of the file, such as renaming it.
1679
+ * The instance's metadata property is automatically updated with the response from the server.
1680
+ * Only the provided parameters will be updated; all other metadata remains unchanged.
1681
+ *
1682
+ * @param params - The metadata properties to update
1683
+ * @param params.name - The new name to assign to the file
1684
+ * @param options - Additional options for the request
1685
+ * @param options.signal - AbortSignal to cancel the request
1686
+ *
1687
+ * @returns A Promise that resolves when the update completes successfully
1688
+ * @throws {Error} If the file ID is not set
1689
+ * @throws {FetchError} If the update request fails
1690
+ *
1691
+ * @example
1692
+ * ```ts
1693
+ * // Rename a file
1694
+ * const vaultFile = await VaultFile.fromVaultReference({
1695
+ * reference: 'vault://file-id',
1696
+ * config: { vaultUrl, authStrategy }
1697
+ * })
1698
+ * await vaultFile.updateMetadata({ name: 'new-name.txt' })
1699
+ * console.log('File renamed to:', vaultFile.metadata?.originalFileName)
1700
+ * ```
1701
+ *
1702
+ * @example
1703
+ * ```ts
1704
+ * // Rename a file with abort signal
1705
+ * const controller = new AbortController()
1706
+ * await vaultFile.updateMetadata(
1707
+ * { name: 'document-v2.pdf' },
1708
+ * { signal: controller.signal }
1709
+ * )
1710
+ * // Later: controller.abort()
1711
+ * ```
1712
+ *
1713
+ * @example
1714
+ * ```ts
1715
+ * // Rename after upload
1716
+ * const file = new File(['content'], 'temp.txt')
1717
+ * const vaultFile = await VaultFile.fromContent({
1718
+ * name: 'temp.txt',
1719
+ * content: file,
1720
+ * config: { vaultUrl, authStrategy },
1721
+ * upload: true
1722
+ * })
1723
+ * // Later, rename the file
1724
+ * await vaultFile.updateMetadata({ name: 'final-document.txt' })
1725
+ * ```
1726
+ */
1727
+ async updateMetadata(params, options) {
1728
+ if (!this.id) {
1729
+ throw new Error("File ID is not set");
1730
+ }
1731
+ const updatedMetadata = await this._fetch({
1732
+ method: "PATCH",
1733
+ path: `files/${this.id}`,
1734
+ body: JSON.stringify(params),
1735
+ signal: options?.signal
1736
+ });
1737
+ this.metadata = updatedMetadata;
1738
+ }
1599
1739
  }
1600
1740
 
1741
+ const VAULT_REFERENCE_UUID_REGEX = /^vault:\/\/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
1742
+ const VAULT_REFERENCE_SHA256_REGEX = /^vault:\/\/[a-f0-9]{64}$/i;
1743
+ function isValidUuidV4(uuid) {
1744
+ return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(uuid);
1745
+ }
1746
+ function isValidSha256(sha256) {
1747
+ return /^[a-f0-9]{64}$/i.test(sha256);
1748
+ }
1601
1749
  function isS3UrlExpired(url) {
1602
1750
  try {
1603
1751
  const urlObj = new URL(url);
@@ -1621,59 +1769,94 @@ function isS3UrlExpired(url) {
1621
1769
  }
1622
1770
  }
1623
1771
  function isVaultReference(url) {
1624
- return url.startsWith("vault://") && url.length === 10;
1772
+ return VAULT_REFERENCE_UUID_REGEX.test(url) || VAULT_REFERENCE_SHA256_REGEX.test(url);
1625
1773
  }
1626
- function isVaultFileS3Url(url) {
1627
- const urlObj = new URL(url);
1628
- const amzDate = urlObj.searchParams.get("X-Amz-Date");
1629
- const amzExpires = urlObj.searchParams.get("X-Amz-Expires");
1630
- return urlObj.hostname.includes("amazonaws.com") && Boolean(amzDate) && Boolean(amzExpires);
1774
+ function isPresignedS3Url(url) {
1775
+ try {
1776
+ const urlObj = new URL(url);
1777
+ const amzDate = urlObj.searchParams.get("X-Amz-Date");
1778
+ const amzExpires = urlObj.searchParams.get("X-Amz-Expires");
1779
+ return urlObj.hostname.includes("amazonaws.com") && Boolean(amzDate) && Boolean(amzExpires);
1780
+ } catch {
1781
+ return false;
1782
+ }
1631
1783
  }
1632
1784
  const URL_STRATEGIES = [
1633
- {
1634
- separator: "/",
1635
- extractSegments: ([workspaceId, vaultFileId]) => ({
1636
- workspaceId,
1637
- vaultFileId
1638
- })
1639
- },
1640
1785
  {
1641
1786
  separator: "_",
1642
1787
  extractSegments: ([vaultFileId, workspaceId]) => ({
1643
1788
  vaultFileId,
1644
1789
  workspaceId
1645
1790
  })
1791
+ },
1792
+ {
1793
+ separator: "/",
1794
+ extractSegments: ([workspaceId, vaultFileId]) => ({
1795
+ workspaceId,
1796
+ vaultFileId
1797
+ })
1646
1798
  }
1647
1799
  ];
1648
- function extractVaultFileIdFromS3Url(url) {
1649
- if (isVaultReference(url))
1650
- return vaultUtils__default.file.getFileIdFromVaultReference(url);
1800
+ function extractVaultFileIdFromLegacyS3Url(url) {
1651
1801
  try {
1652
- if (!isVaultFileS3Url(url))
1653
- return null;
1654
1802
  const urlObj = new URL(url);
1655
1803
  const strategy = URL_STRATEGIES.find((strategy2) => urlObj.pathname.includes(strategy2.separator));
1656
1804
  if (!strategy)
1657
1805
  return null;
1658
- const segments = urlObj.pathname.split(strategy.separator).filter((segment) => segment.length > 0);
1806
+ const segments = urlObj.pathname.split(strategy.separator).map((segment) => segment.replace(/^\/+|\/+$/g, "")).filter((segment) => segment.length > 0);
1659
1807
  if (segments.length < 2)
1660
1808
  return null;
1661
1809
  const extractedIds = strategy.extractSegments(segments);
1662
- if (!extractedIds || !extractedIds.vaultFileId || !extractedIds.workspaceId || extractedIds.vaultFileId.length < 32)
1810
+ if (!extractedIds.vaultFileId || !extractedIds.workspaceId || extractedIds.vaultFileId.length < 32)
1663
1811
  return null;
1664
1812
  return extractedIds.vaultFileId;
1665
1813
  } catch {
1666
1814
  return null;
1667
1815
  }
1668
1816
  }
1817
+ function extractVaultFileIdFromS3Url(url) {
1818
+ if (isVaultReference(url))
1819
+ return vaultUtils__default.file.getFileIdFromVaultReference(url);
1820
+ if (!isPresignedS3Url(url))
1821
+ return null;
1822
+ if (isTaggedVaultPresignedUrl(url))
1823
+ return getVaultParamsFromS3Url(url)?.fileId ?? null;
1824
+ return extractVaultFileIdFromLegacyS3Url(url);
1825
+ }
1669
1826
  function convertS3UrlToVaultReference(url) {
1670
1827
  const vaultFileId = extractVaultFileIdFromS3Url(url);
1671
1828
  return vaultFileId ? `vault://${vaultFileId}` : null;
1672
1829
  }
1830
+ function isTaggedVaultPresignedUrl(url) {
1831
+ try {
1832
+ const urlObj = new URL(url);
1833
+ const workspaceId = urlObj.searchParams.get("vault-workspace-id");
1834
+ const fileId = urlObj.searchParams.get("vault-file-id");
1835
+ if (!workspaceId || !fileId) {
1836
+ return false;
1837
+ }
1838
+ const hasWorkspaceId = isValidUuidV4(workspaceId);
1839
+ const hasFileId = isValidSha256(fileId) || isValidUuidV4(fileId);
1840
+ const hasAmazonDomain = urlObj.hostname.endsWith("amazonaws.com");
1841
+ return hasWorkspaceId && hasFileId && hasAmazonDomain;
1842
+ } catch {
1843
+ return false;
1844
+ }
1845
+ }
1846
+ function getVaultParamsFromS3Url(url) {
1847
+ if (!isTaggedVaultPresignedUrl(url))
1848
+ return null;
1849
+ const urlObj = new URL(url);
1850
+ return {
1851
+ fileId: urlObj.searchParams.get("vault-file-id"),
1852
+ workspaceId: urlObj.searchParams.get("vault-workspace-id"),
1853
+ parentId: urlObj.searchParams.get("vault-parent-id")
1854
+ };
1855
+ }
1673
1856
 
1674
1857
  function vaultClient(vaultConfig) {
1675
1858
  const config = resolveConfig(vaultConfig);
1676
- function createFromContent(nameOrContent, contentOrNameOrOptions, options) {
1859
+ async function createFromContent(nameOrContent, contentOrNameOrOptions, options) {
1677
1860
  const isOptionsObject = (value) => {
1678
1861
  return typeof value === "object" && value !== null && !(value instanceof Blob) && !(value instanceof File);
1679
1862
  };
@@ -1684,7 +1867,7 @@ function vaultClient(vaultConfig) {
1684
1867
  const parentId2 = options?.parentId;
1685
1868
  const mimeType2 = options?.mimeType;
1686
1869
  const upload2 = options?.upload;
1687
- return VaultFile.fromContent({ content: content2, name: name2, config, parentId: parentId2, mimeType: mimeType2, upload: upload2 }, { signal: signal2 });
1870
+ return await VaultFile.fromContent({ content: content2, name: name2, config, parentId: parentId2, mimeType: mimeType2, upload: upload2 }, { signal: signal2 });
1688
1871
  }
1689
1872
  const content = nameOrContent;
1690
1873
  const name = typeof contentOrNameOrOptions === "string" ? contentOrNameOrOptions : void 0;
@@ -1692,16 +1875,16 @@ function vaultClient(vaultConfig) {
1692
1875
  const parentId = isOptionsObject(contentOrNameOrOptions) ? contentOrNameOrOptions.parentId : options?.parentId;
1693
1876
  const mimeType = isOptionsObject(contentOrNameOrOptions) ? contentOrNameOrOptions.mimeType : options?.mimeType;
1694
1877
  const upload = isOptionsObject(contentOrNameOrOptions) ? contentOrNameOrOptions.upload : options?.upload;
1695
- return VaultFile.fromContent({ content, name, config, parentId, mimeType, upload }, { signal });
1878
+ return await VaultFile.fromContent({ content, name, config, parentId, mimeType, upload }, { signal });
1696
1879
  }
1697
- function createFromReference(reference, options) {
1698
- return VaultFile.fromVaultReference({
1880
+ async function createFromReference(reference, options) {
1881
+ return await VaultFile.fromVaultReference({
1699
1882
  reference,
1700
1883
  config
1701
1884
  }, { signal: options?.signal });
1702
1885
  }
1703
1886
  async function createFromStream(name, contentLength, options) {
1704
- return VaultFile.fromStream({
1887
+ return await VaultFile.fromStream({
1705
1888
  name,
1706
1889
  contentLength,
1707
1890
  config,
@@ -1709,7 +1892,14 @@ function vaultClient(vaultConfig) {
1709
1892
  parentId: options?.parentId
1710
1893
  }, { signal: options?.signal });
1711
1894
  }
1712
- return { createFromContent, createFromReference, createFromStream };
1895
+ async function createFromContentBulk(files, options) {
1896
+ return await VaultFile.fromContentBulk({
1897
+ files,
1898
+ config,
1899
+ upload: options?.upload
1900
+ }, { signal: options?.signal });
1901
+ }
1902
+ return { createFromContent, createFromReference, createFromStream, createFromContentBulk };
1713
1903
  }
1714
1904
 
1715
1905
  exports.APIKeyAuthStrategy = APIKeyAuthStrategy;
@@ -1718,6 +1908,9 @@ exports.FetchError = FetchError;
1718
1908
  exports.VaultFile = VaultFile;
1719
1909
  exports.convertS3UrlToVaultReference = convertS3UrlToVaultReference;
1720
1910
  exports.extractVaultFileIdFromS3Url = extractVaultFileIdFromS3Url;
1911
+ exports.getVaultParamsFromS3Url = getVaultParamsFromS3Url;
1721
1912
  exports.isS3UrlExpired = isS3UrlExpired;
1722
- exports.isVaultFileS3Url = isVaultFileS3Url;
1913
+ exports.isTaggedVaultPresignedUrl = isTaggedVaultPresignedUrl;
1914
+ exports.isVaultFileS3Url = isPresignedS3Url;
1915
+ exports.isVaultReference = isVaultReference;
1723
1916
  exports.vaultClient = vaultClient;
package/dist/index.d.cts CHANGED
@@ -89,6 +89,21 @@ type VaultFileParams = {
89
89
  };
90
90
  type OnMissingParent = 'error' | 'create-as-root';
91
91
  type OnParentConflict = 'error' | 'update-parent-id' | 'ignore';
92
+ /**
93
+ * Parameters for updating metadata of a VaultFile.
94
+ */
95
+ interface VaultFileUpdateMetadataParams {
96
+ /** The new name to assign to the file. If not provided, the name will not be changed. */
97
+ name?: string;
98
+ }
99
+ type BulkFileInput = {
100
+ content: Blob | File;
101
+ name?: string;
102
+ mimeType?: string;
103
+ parentId?: string;
104
+ onMissingParent?: OnMissingParent;
105
+ onParentConflict?: OnParentConflict;
106
+ };
92
107
  /**
93
108
  * Represents a file in the vault and allows interacting with it.
94
109
  *
@@ -343,6 +358,37 @@ declare class VaultFile {
343
358
  }, options?: {
344
359
  signal?: AbortSignal;
345
360
  }): Promise<VaultFile>;
361
+ /**
362
+ * Creates multiple VaultFile instances from given content in a single request.
363
+ *
364
+ * @param params - Parameters for creating VaultFiles from content
365
+ * @param params.files - Array of file inputs with content and optional metadata
366
+ * @param params.config - The configuration for the VaultFiles
367
+ * @param params.upload - Whether to upload all files (default: false)
368
+ * @param options - The options for the request
369
+ * @param options.signal - The signal to abort the request
370
+ *
371
+ * @returns Array of new VaultFile instances
372
+ *
373
+ * @example
374
+ * ```ts
375
+ * const files = await VaultFile.fromContentBulk({
376
+ * files: [
377
+ * { content: blob1, name: 'file1.txt' },
378
+ * { content: blob2, name: 'file2.txt', parentId: 'parent-id' },
379
+ * ],
380
+ * config: { vaultUrl, authStrategy },
381
+ * upload: true
382
+ * })
383
+ * ```
384
+ */
385
+ static fromContentBulk(params: {
386
+ files: BulkFileInput[];
387
+ config: VaultConfig;
388
+ upload?: boolean;
389
+ }, options?: {
390
+ signal?: AbortSignal;
391
+ }): Promise<VaultFile[]>;
346
392
  /**
347
393
  * Fetches and populates the metadata fields for this VaultFile instance.
348
394
  *
@@ -1110,6 +1156,61 @@ declare class VaultFile {
1110
1156
  * ```
1111
1157
  */
1112
1158
  createChildFromStream(params: Omit<Parameters<typeof VaultFile.fromStream>[0], 'config' | 'parentId'>, options?: Parameters<typeof VaultFile.fromStream>[1]): Promise<VaultFile>;
1159
+ /**
1160
+ * Updates the metadata of this file in the vault.
1161
+ *
1162
+ * This method allows you to modify specific metadata properties of the file, such as renaming it.
1163
+ * The instance's metadata property is automatically updated with the response from the server.
1164
+ * Only the provided parameters will be updated; all other metadata remains unchanged.
1165
+ *
1166
+ * @param params - The metadata properties to update
1167
+ * @param params.name - The new name to assign to the file
1168
+ * @param options - Additional options for the request
1169
+ * @param options.signal - AbortSignal to cancel the request
1170
+ *
1171
+ * @returns A Promise that resolves when the update completes successfully
1172
+ * @throws {Error} If the file ID is not set
1173
+ * @throws {FetchError} If the update request fails
1174
+ *
1175
+ * @example
1176
+ * ```ts
1177
+ * // Rename a file
1178
+ * const vaultFile = await VaultFile.fromVaultReference({
1179
+ * reference: 'vault://file-id',
1180
+ * config: { vaultUrl, authStrategy }
1181
+ * })
1182
+ * await vaultFile.updateMetadata({ name: 'new-name.txt' })
1183
+ * console.log('File renamed to:', vaultFile.metadata?.originalFileName)
1184
+ * ```
1185
+ *
1186
+ * @example
1187
+ * ```ts
1188
+ * // Rename a file with abort signal
1189
+ * const controller = new AbortController()
1190
+ * await vaultFile.updateMetadata(
1191
+ * { name: 'document-v2.pdf' },
1192
+ * { signal: controller.signal }
1193
+ * )
1194
+ * // Later: controller.abort()
1195
+ * ```
1196
+ *
1197
+ * @example
1198
+ * ```ts
1199
+ * // Rename after upload
1200
+ * const file = new File(['content'], 'temp.txt')
1201
+ * const vaultFile = await VaultFile.fromContent({
1202
+ * name: 'temp.txt',
1203
+ * content: file,
1204
+ * config: { vaultUrl, authStrategy },
1205
+ * upload: true
1206
+ * })
1207
+ * // Later, rename the file
1208
+ * await vaultFile.updateMetadata({ name: 'final-document.txt' })
1209
+ * ```
1210
+ */
1211
+ updateMetadata(params: VaultFileUpdateMetadataParams, options?: {
1212
+ signal?: AbortSignal;
1213
+ }): Promise<void>;
1113
1214
  }
1114
1215
 
1115
1216
  /**
@@ -1121,19 +1222,41 @@ declare class VaultFile {
1121
1222
  */
1122
1223
  declare function isS3UrlExpired(url: string): boolean;
1123
1224
  /**
1124
- * Checks if a URL is a valid S3 vault URL
1125
- * @param url - The S3 URL to check
1126
- * @returns true if the URL is a valid S3 vault URL, false otherwise
1225
+ * Checks if a URL is a valid vault reference
1226
+ * @param url - The URL to check
1227
+ * @returns true if the URL is a valid vault reference, false otherwise
1228
+ */
1229
+ declare function isVaultReference(url: string): boolean;
1230
+ /**
1231
+ * Checks if a URL seems like a valid presigned S3 URL, with no additional checks.
1232
+ *
1233
+ * For usage with legacy URLs only. For new URLs, use {@link isTaggedVaultPresignedUrl} instead,
1234
+ * since this function only checks if the URL is a valid S3 URL, not if it was generated by Vault.
1235
+ *
1236
+ * @param url - The URL to check
1237
+ * @returns true if the URL is a valid S3 URL, false otherwise
1127
1238
  */
1128
- declare function isVaultFileS3Url(url: string): boolean;
1239
+ declare function isPresignedS3Url(url: string): boolean;
1129
1240
  /**
1130
- * Detects if a URL is an expired S3 vault URL and extracts the vault file ID
1131
- * Returns null if not a vault S3 URL, not expired, or extraction fails
1241
+ * Extracts the vault file ID from an S3 presigned URL.
1242
+ * Supports multiple URL formats: tagged vault URLs, vault references, and legacy URL formats.
1243
+ *
1244
+ * @param url - The S3 URL to extract the vault file ID from
1245
+ * @returns The vault file ID (UUID or SHA-256 hash) if extraction succeeds, null otherwise
1246
+ * @example
1247
+ * // Tagged vault URL
1248
+ * extractVaultFileIdFromS3Url('https://vault-prod.s3.amazonaws.com/file?vault-file-id=abc123...')
1249
+ * // Returns: 'abc123...'
1250
+ *
1251
+ * // Vault reference
1252
+ * extractVaultFileIdFromS3Url('vault://2fce5740-83da-49fe-3f10-b32205893ec0')
1253
+ * // Returns: '2fce5740-83da-49fe-3f10-b32205893ec0'
1132
1254
  */
1133
1255
  declare function extractVaultFileIdFromS3Url(url: string): string | null;
1134
1256
  /**
1135
1257
  * Converts an S3 vault URL to a vault reference format
1136
1258
  * Extracts the vault file ID from the S3 URL path and formats it as vault://[fileId]
1259
+ *
1137
1260
  * @param url - The S3 vault URL to convert
1138
1261
  * @returns A vault reference string (vault://[fileId]) if successful, null if the URL is not a valid vault S3 URL
1139
1262
  * @example
@@ -1141,6 +1264,33 @@ declare function extractVaultFileIdFromS3Url(url: string): string | null;
1141
1264
  * // Returns: 'vault://2fce574083da49fe3f10b32205893ec0bb024fe1c7673fa54927fdfe1d0db9d6'
1142
1265
  */
1143
1266
  declare function convertS3UrlToVaultReference(url: string): string | null;
1267
+ /**
1268
+ * Checks if a URL is a tagged vault presigned S3 URL.
1269
+ * Tagged URLs contain vault-specific query parameters (vault-workspace-id, vault-file-id)
1270
+ * that identify the vault workspace and file.
1271
+ *
1272
+ * @param url - The URL to check
1273
+ * @returns true if the URL is a tagged vault presigned URL with valid workspace and file IDs, false otherwise
1274
+ * @example
1275
+ * const isTagged = isTaggedVaultPresignedUrl('https://vault-prod.s3.amazonaws.com/file?vault-workspace-id=abc-123&vault-file-id=def456...')
1276
+ * // Returns: true
1277
+ */
1278
+ declare function isTaggedVaultPresignedUrl(url: string): boolean;
1279
+ /**
1280
+ * Extracts vault-specific parameters from a tagged vault presigned S3 URL.
1281
+ * Returns workspace ID, file ID, and optional parent ID from the URL query parameters.
1282
+ *
1283
+ * @param url - The tagged vault S3 URL to parse
1284
+ * @returns An object containing fileId, workspaceId, and parentId (if present), or null if the URL is not a tagged vault URL
1285
+ * @example
1286
+ * const params = getVaultParamsFromS3Url('https://vault-prod.s3.amazonaws.com/file?vault-workspace-id=abc-123&vault-file-id=def456&vault-parent-id=parent789')
1287
+ * // Returns: { fileId: 'def456', workspaceId: 'abc-123', parentId: 'parent789' }
1288
+ */
1289
+ declare function getVaultParamsFromS3Url(url: string): {
1290
+ fileId: string | null;
1291
+ workspaceId: string | null;
1292
+ parentId: string | null;
1293
+ } | null;
1144
1294
 
1145
1295
  declare function vaultClient(vaultConfig: VaultConfig): {
1146
1296
  createFromContent: {
@@ -1171,7 +1321,18 @@ declare function vaultClient(vaultConfig: VaultConfig): {
1171
1321
  signal?: AbortSignal;
1172
1322
  parentId?: string;
1173
1323
  }) => Promise<VaultFile>;
1324
+ createFromContentBulk: (files: Array<{
1325
+ content: Blob | File;
1326
+ name?: string;
1327
+ mimeType?: string;
1328
+ parentId?: string;
1329
+ onMissingParent?: "error" | "create-as-root";
1330
+ onParentConflict?: "error" | "update-parent-id" | "ignore";
1331
+ }>, options?: {
1332
+ upload?: boolean;
1333
+ signal?: AbortSignal;
1334
+ }) => Promise<VaultFile[]>;
1174
1335
  };
1175
1336
 
1176
- export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, isS3UrlExpired, isVaultFileS3Url, vaultClient };
1337
+ export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, getVaultParamsFromS3Url, isS3UrlExpired, isTaggedVaultPresignedUrl, isPresignedS3Url as isVaultFileS3Url, isVaultReference, vaultClient };
1177
1338
  export type { AuthStrategy, VaultConfig };