@ai-matrx/data 0.18.1 → 0.18.3

package/dist/files.d.ts

@@ -74,11 +74,23 @@ interface FilesBlobHandle {
     /** Release the handle. Cache-backed handles no-op (the cache owns the URL). */
     release(): void;
 }
+/** `platform.shown_to`: a list filter, never row security (access ladder T-13). */
+type FileShownTo = "only_me" | "my_team" | "everyone" | "everyone_on_ai_matrx";
 interface MediaUploadOptions {
     onProgress?: ((loaded: number, total: number) => void) | undefined;
     fileName?: string | undefined;
     mimeType?: string | undefined;
-    /** Matrx visibility vocabulary (`personal` | `public` | `shared` | ...). */
+    /**
+     * Publish the upload to the web (the only anonymous lane; access ladder T-13).
+     * Omitted = not published.
+     */
+    publishedToWeb?: boolean | undefined;
+    /** The "Shown to" list filter; omitted = only me (the upload default). */
+    shownTo?: FileShownTo | undefined;
+    /**
+     * The retiring level word (`personal` | `internal` | `link` | `public`), read only when
+     * neither word above is given; hosts move to the two words.
+     */
     visibility?: string | undefined;
     /**
      * Host-side folder identity. The wire contract addresses folders by PATH
@@ -135,7 +147,8 @@ interface FileUploadResponseWire {
     url?: string | null;
     cdn_url?: string | null;
     download_url?: string | null;
-    visibility?: string;
+    published_to_web?: boolean;
+    shown_to?: string | null;
 }
 /**
  * `GET /files/{id}` response (`FileRecord`) — the subset this lane reads.
@@ -145,7 +158,8 @@ interface FileRecordWire {
     id: string;
     file_name?: string | null;
     mime_type?: string | null;
-    visibility?: string | null;
+    published_to_web?: boolean | null;
+    shown_to?: string | null;
     deleted_at?: string | null;
     public_url?: string | null;
     thumbnail_url?: string | null;
@@ -171,7 +185,8 @@ interface ShareLinkRecordWire {
 /** The per-file metadata this lane renders transport decisions from. */
 interface FileMetadata {
     mimeType?: string | null;
-    visibility?: string | null;
+    /** True only when the file is published to the web (its CDN URL is anonymous). */
+    publishedToWeb?: boolean | null;
     cdnUrl?: string | null;
     publicUrl?: string | null;
     thumbnailUrl?: string | null;
@@ -179,7 +194,7 @@ interface FileMetadata {
     fileName?: string | null;
 }
 /**
- * Where `resolve()` reads per-file metadata (visibility → CDN vs blob lane,
+ * Where `resolve()` reads per-file metadata (published to the web → CDN vs blob lane,
  * mime, thumbnail). `peek` is synchronous and render-safe; `hydrate` may hit
  * the network/store. DEFAULT: an in-client cache over `GET /files/{id}`.
  * A host with its own file store (Redux, Supabase reads) overrides this port
@@ -353,8 +368,6 @@ declare function mimeFromUrl(url: string): string | null;
  * shown as one.
  */
 declare function fileNameFromUrl(url: string): string | null;
-/** True when the string is a bare cld_files UUID (a fileId, not a URL). */
-declare function isFileIdString(value: string): boolean;
 interface FileUrls {
     /** Authenticated direct-download endpoint (`Content-Disposition: attachment`). */
     download: string;
@@ -524,6 +537,13 @@ interface MatrxFilesClient<TSrc extends string = DurableSrc> {
  * Persistent tiers (IndexedDB, the service worker) stay host-injected.
  */
 declare function createMemoryBlobCache(budgetBytes?: number): BlobCachePort;
+/**
+ * The upload's row-access form fields (access ladder T-13). The two words are written
+ * explicitly on every upload — never left to a server default: not published, shown to
+ * only me, unless the caller says otherwise. A caller still on the retiring level word
+ * is translated here, once.
+ */
+declare function uploadAccessFields(opts: MediaUploadOptions): Record<string, string>;
 declare function createMatrxFilesClient<TSrc extends string = DurableSrc>(config: MatrxFilesClientConfig): MatrxFilesClient<TSrc>;
 
 /**
@@ -663,4 +683,4 @@ interface FilesSession {
 }
 declare function createFilesSession(options: FilesSessionOptions): FilesSession;
 
-export { type BlobCacheEntry, type BlobCachePort, type DurableSrc, ExternalFetchError, FileAccessDeniedError, FileDeletedError, FileError, type FileErrorCode, type FileMetadata, type FileMetadataPort, FileNotFoundError, type FileOrigins, type FileRecordWire, type FileSessionResponseWire, FileUploadError, type FileUploadResponseWire, type FileUrlRecognizer, type FileUrls, type FilesBlobHandle, type FilesDiagnosticsEvent, type FilesDiagnosticsSink, type FilesRecoveryReport, type FilesRecoveryVerdict, type FilesResolution, type FilesSession, type FilesSessionOptions, type FilesSessionSnapshot, type MatrxFilesClient, type MatrxFilesClientConfig, type MediaKind, type MediaMultiUploadResult, type MediaRef, type MediaRefLike, type MediaUnavailableReason, type MediaUploadOptions, type MediaUploadResult, type MediaUrlKind, SIGNED_URL_RE, ShareLinkInvalidError, type ShareLinkRecordWire, TUS_TRANSPORT_THRESHOLD_BYTES, type UploadTransport, classifyMediaUrl, classifyUnavailable, createFileUrlRecognizer, createFilesSession, createMatrxFilesClient, createMemoryBlobCache, fileErrorFromStatus, fileNameFromUrl, fileUrls, isDurableMediaUrl, isFileIdString, isSignedUrl, mimeFromUrl, resolveUploadTransport, shareUrl, shareableMediaUrl };
+export { type BlobCacheEntry, type BlobCachePort, type DurableSrc, ExternalFetchError, FileAccessDeniedError, FileDeletedError, FileError, type FileErrorCode, type FileMetadata, type FileMetadataPort, FileNotFoundError, type FileOrigins, type FileRecordWire, type FileSessionResponseWire, type FileShownTo, FileUploadError, type FileUploadResponseWire, type FileUrlRecognizer, type FileUrls, type FilesBlobHandle, type FilesDiagnosticsEvent, type FilesDiagnosticsSink, type FilesRecoveryReport, type FilesRecoveryVerdict, type FilesResolution, type FilesSession, type FilesSessionOptions, type FilesSessionSnapshot, type MatrxFilesClient, type MatrxFilesClientConfig, type MediaKind, type MediaMultiUploadResult, type MediaRef, type MediaRefLike, type MediaUnavailableReason, type MediaUploadOptions, type MediaUploadResult, type MediaUrlKind, SIGNED_URL_RE, ShareLinkInvalidError, type ShareLinkRecordWire, TUS_TRANSPORT_THRESHOLD_BYTES, type UploadTransport, classifyMediaUrl, classifyUnavailable, createFileUrlRecognizer, createFilesSession, createMatrxFilesClient, createMemoryBlobCache, fileErrorFromStatus, fileNameFromUrl, fileUrls, isDurableMediaUrl, isSignedUrl, mimeFromUrl, resolveUploadTransport, shareUrl, shareableMediaUrl, uploadAccessFields };

package/dist/files.js

@@ -92,7 +92,7 @@ function classifyUnavailable(err) {
 }
 
 // src/files/recognize.ts
-var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+import { isUuidShape } from "@ai-matrx/kit/uuid";
 var SIGNED_URL_RE = /[?&](x-amz-signature|x-amz-credential|x-amz-date|x-amz-expires|awsaccesskeyid|signature|expires)=/i;
 function isSignedUrl(url) {
   if (!url) return false;
@@ -131,14 +131,14 @@ function createFileUrlRecognizer(origins = {}) {
     if (!u || !endpointHosts.test(u.hostname)) return null;
     const m = u.pathname.match(FILE_ENDPOINT_PATH_RE);
     const candidate = m ? m[1] ?? m[2] : null;
-    return candidate && UUID_RE.test(candidate) ? candidate : null;
+    return candidate && isUuidShape(candidate) ? candidate : null;
   }
   function fileIdFromUserFilesUrl(url) {
     const u = parse(url);
     if (!u || !userFilesHosts.test(u.hostname)) return null;
     const segs = u.pathname.split("/").filter(Boolean);
     const candidate = segs[1] ?? segs[segs.length - 1];
-    return candidate && UUID_RE.test(candidate) ? candidate : null;
+    return candidate && isUuidShape(candidate) ? candidate : null;
   }
   function looksLikeCdnUrl(url) {
     const u = parse(url);
@@ -197,9 +197,6 @@ function fileNameFromUrl(url) {
   if (!last || !/\.[a-z0-9]{1,5}$/i.test(last)) return null;
   return decodeURIComponent(last);
 }
-function isFileIdString(value) {
-  return UUID_RE.test(value);
-}
 function fileUrls(filesBaseUrl, fileId) {
   const id = encodeURIComponent(fileId);
   const base = `${filesBaseUrl.replace(/\/$/, "")}/files/${id}/download`;
@@ -209,6 +206,9 @@ function shareUrl(filesBaseUrl, token) {
   return `${filesBaseUrl.replace(/\/$/, "")}/share/${encodeURIComponent(token)}`;
 }
 
+// src/files/client.ts
+import { isUuidShape as isUuidShape2 } from "@ai-matrx/kit/uuid";
+
 // src/files/session.ts
 var REFRESH_SAFETY_MARGIN_MS = 60 * 60 * 1e3;
 function createFilesSession(options) {
@@ -529,10 +529,18 @@ function createMemoryBlobCache(budgetBytes = DEFAULT_BLOB_BUDGET_BYTES) {
     }
   };
 }
+function uploadAccessFields(opts) {
+  const legacy = opts.visibility;
+  const published = opts.publishedToWeb ?? (legacy === void 0 ? false : legacy === "public");
+  const shownTo = opts.shownTo ?? (opts.publishedToWeb !== void 0 || legacy === void 0 || legacy === "personal" ? "only_me" : null);
+  const fields = { published_to_web: String(published) };
+  if (shownTo) fields.shown_to = shownTo;
+  return fields;
+}
 function recordToMetadata(record) {
   return {
     mimeType: record.mime_type ?? null,
-    visibility: record.visibility ?? null,
+    publishedToWeb: record.published_to_web ?? null,
     cdnUrl: record.cdn_url ?? null,
     publicUrl: record.public_url ?? null,
     thumbnailUrl: record.thumbnail_url ?? null,
@@ -656,7 +664,7 @@ function createMatrxFilesClient(config) {
   function normalizeRef(ref) {
     if (!ref) return null;
     if (typeof ref === "string") {
-      if (isFileIdString(ref)) return { kind: "file_id", fileId: ref, mime: null };
+      if (isUuidShape2(ref)) return { kind: "file_id", fileId: ref, mime: null };
       if (!ref.trim()) return null;
       return normalizeUrl(ref, null);
     }
@@ -706,7 +714,7 @@ function createMatrxFilesClient(config) {
     return response.blob();
   }
   async function fileIdBlob(fileId) {
-    if (!isFileIdString(fileId)) {
+    if (!isUuidShape2(fileId)) {
       throw new FileError(
         "internal",
         `getBlob: "${fileId}" is not a cld_files id \u2014 host-namespaced/virtual ids are resolved by the host before this client.`,
@@ -832,7 +840,7 @@ function createMatrxFilesClient(config) {
     const form = new FormData();
     form.append("file", asFile);
     form.append("file_path", `${folder}/${asFile.name}`);
-    form.append("visibility", opts.visibility ?? "personal");
+    for (const [key, value] of Object.entries(uploadAccessFields(opts))) form.append(key, value);
     if (opts.metadata) form.append("metadata_json", JSON.stringify(opts.metadata));
     const response = await postMultipart(form, opts, newRequestId());
     if (!response.file_id) {
@@ -862,7 +870,7 @@ function createMatrxFilesClient(config) {
     return { uploaded, failed, cancelled: false };
   }
   function permanentPublicUrl(meta) {
-    if (meta?.visibility !== "public") return null;
+    if (meta?.publishedToWeb !== true) return null;
     const candidate = shareableMediaUrl(meta.cdnUrl ?? meta.publicUrl ?? null);
     if (!candidate) return null;
     return recognizer.fileIdFromFileEndpointUrl(candidate) ? null : candidate;
@@ -933,7 +941,7 @@ function createMatrxFilesClient(config) {
       }
       const { fileId } = norm;
       const meta = metadata.peek(fileId);
-      if (isFileIdString(fileId)) scheduleHydration(fileId);
+      if (isUuidShape2(fileId)) scheduleHydration(fileId);
       const mime = norm.mime ?? meta?.mimeType ?? null;
       const kind = mimeToKind(mime);
       const thumbRaw = meta?.thumbnailUrl ?? null;
@@ -1046,7 +1054,7 @@ function createMatrxFilesClient(config) {
       if (!norm) return null;
       if (norm.kind === "url") return shareableMediaUrl(norm.url);
       const { fileId } = norm;
-      if (!isFileIdString(fileId)) return null;
+      if (!isUuidShape2(fileId)) return null;
       const meta = await metadata.hydrate(fileId);
       const permanent = permanentPublicUrl(meta);
       if (permanent) return permanent;
@@ -1091,11 +1099,11 @@ export {
   fileNameFromUrl,
   fileUrls,
   isDurableMediaUrl,
-  isFileIdString,
   isSignedUrl,
   mimeFromUrl,
   resolveUploadTransport,
   shareUrl,
-  shareableMediaUrl
+  shareableMediaUrl,
+  uploadAccessFields
 };
 //# sourceMappingURL=files.js.map