@voltro/plugin-storage 0.70.0 → 0.71.1

package/dist/index.d.ts

@@ -3,12 +3,14 @@ import { ColumnType } from '@voltro/database';
 import { Context } from 'effect';
 import { DataStore } from '@voltro/database';
 import { Effect } from 'effect';
+import { FieldDefinitions } from '@voltro/database';
 import { Layer } from 'effect';
 import { mixin } from '@voltro/database';
 import { Readable } from 'node:stream';
 import { Schema } from 'effect';
 import { Stream } from 'effect';
 import { Subject } from '@voltro/protocol';
+import { Table } from '@voltro/database';
 import { TableLike } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
@@ -420,7 +422,20 @@ export declare const putObjectStream: (provider: StorageProvider, key: string, s
 export declare const refMatchesListQuery: (ref: StorageRef, q: ResolvedListQuery) => boolean;
 
 /** Where blob METADATA rows live (the bytes are in the provider). */
+export declare interface RefStatistics {
+    readonly byTenant: Record<string, {
+        count: number;
+        bytes: number;
+    }>;
+    readonly visibility: {
+        public: number;
+        private: number;
+    };
+}
+
 export declare interface RefStore {
+    /** Aggregate the complete reference index without a recent-object limit. */
+    readonly statistics: () => Effect.Effect<RefStatistics, StorageError>;
     readonly insert: (ref: StorageRef) => Effect.Effect<void, StorageError>;
     readonly getById: (id: string) => Effect.Effect<StorageRef | null, StorageError>;
     /** Remove one ref row. Returns whether a row was ACTUALLY removed — the
@@ -479,6 +494,7 @@ export declare interface Rendition {
 /** A `ListRefsInput` after the service normalizes its defaults / clamps — what
  *  a `RefStore.listRefs` impl receives. `limit` is already the `+1` probe. */
 export declare interface ResolvedListQuery {
+    readonly search?: string;
     readonly tenantId: string | null | undefined;
     readonly folder: string | undefined;
     readonly tags: ReadonlyArray<string>;
@@ -606,6 +622,39 @@ export declare type StorageGuard = (ctx: {
     readonly ref: StorageRef;
 }) => boolean | Promise<boolean> | Effect.Effect<boolean>;
 
+/**
+ * The instance name an upload ticket must carry, for THIS installation.
+ *
+ * `signUploadTicket` takes `instance: string`, and the upload route compares it
+ * against the plugin's own instance — so a wrong value is not a type error, it
+ * is a bare `401` on every upload. The value has always been derivable
+ * (`storagePlugin(options).name` is this same expression), but nothing said so
+ * and `BASE_NAME` is not exported, so a caller minting a ticket outside the
+ * plugin had to guess it. Guessing is exactly what a `string` parameter invites.
+ *
+ *     const ticket = signUploadTicket(
+ *       { instance: storageInstanceName(), key, contentType },
+ *       300,
+ *     )
+ *
+ * Pass the SAME options the installation was built with — `alias` and `name`
+ * both move the instance, and a ticket minted for the default name does not
+ * open a door installed under an alias.
+ */
+export declare const storageInstanceName: (options?: StoragePluginOptions) => string;
+
+declare interface StorageObjectIdentity {
+    readonly tenantId: string | null;
+    readonly bucket: string;
+    readonly operationId: string;
+    /** Hash of all immutable put inputs, including content and access metadata. */
+    readonly fingerprint: string;
+    /** SHA-256 of the actual normalized provider bytes, separate from metadata. */
+    readonly checksum: string;
+    /** Already tenant-scoped logical provider key. */
+    readonly logicalKey: string;
+}
+
 export declare const storagePlugin: (options?: StoragePluginOptions) => VoltroPlugin;
 
 export declare interface StoragePluginOptions {
@@ -815,6 +864,13 @@ export declare interface StorageProvider {
 
 export declare type StorageProviderName = 's3' | 'minio' | 'azure' | 'filesystem' | 'memory' | 'database';
 
+export declare const storagePutIntentsTable: Table<"_voltro_storage_put_intents", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "text", boolean>;
+    readonly refId: ColumnBuilder<string, "text", boolean>;
+    readonly identity: ColumnBuilder<StorageObjectIdentity, "json", boolean>;
+    readonly ref: ColumnBuilder<StorageRef, "json", boolean>;
+}>, false, never>;
+
 /** Per-tenant upload budget (see `StorageServiceOptions.quota`). */
 export declare interface StorageQuota {
     readonly maxBytes?: number;
@@ -938,6 +994,8 @@ export declare interface StorageServiceOptions {
      *  the app: a browser `<img>` and server-to-server AI-gateway fetches both
      *  need an absolute, reachable URL. Omit for same-origin (relative URL). */
     readonly publicBaseUrl?: string;
+    /** Instance-specific HTTP mount supplied by the storage plugin. */
+    readonly httpPath?: string;
     /** Normalize raster images on upload: apply EXIF orientation, then strip ALL
      *  metadata (GPS/camera) and re-encode. Off by default (it re-encodes, which
      *  changes the bytes + content-address). Width/height/placeholder are always
@@ -965,6 +1023,15 @@ export declare interface StorageServiceShape {
         readonly bytes: Uint8Array;
         readonly ref: StorageRef;
     }, StorageError>;
+    /** Trusted server-side streamed read with the same tenant guard as get.
+     * Provider acquisition is lazy; callers must authorize private-object access.
+     * Providers without getStream fall back to a buffered provider read. */
+    readonly getStream: (id: string, opts?: {
+        readonly tenantId?: string | null;
+    }) => Effect.Effect<{
+        readonly stream: ByteStream;
+        readonly ref: StorageRef;
+    }, StorageError>;
     /** Direct/presigned URL for an object. For PUBLIC objects this is the
      *  CDN/bucket URL (no app round-trip).
      *
@@ -1054,8 +1121,12 @@ export declare interface StorageServiceShape {
      *  migration / "adopt this remote image"). The content-type comes from the
      *  response unless overridden. NOTE: this fetches an arbitrary URL from the
      *  server — pass only trusted URLs (SSRF); front it with an allow-list if the
-     *  URL is user-supplied. */
+     *  URL is user-supplied. Reads are bounded by `limits.maxBytes` (64 MiB when
+     *  absent) before the scanning/checksum/put pipeline. This is bounded
+     *  buffering, not a zero-copy provider stream. Effect interruption cancels
+     *  the HTTP read; an optional caller signal interrupts the entire ingest. */
     readonly ingestUrl: (url: string, opts?: {
+        readonly abortSignal?: AbortSignal;
         readonly contentType?: string;
         readonly tenantId?: string | null;
         readonly ownerId?: string | null;
@@ -1247,7 +1318,8 @@ export declare interface TransformParams {
 }
 
 export declare interface UploadLimits {
-    /** Reject uploads larger than this many bytes. */
+    /** Reject uploads larger than this many bytes. URL ingestion enforces this
+     * while reading the response; absent a limit, ingestion caps at 64 MiB. */
     readonly maxBytes?: number;
     /** Allowed content types — exact (`application/pdf`) or wildcard
      *  (`image/*`). Omit to allow any. */
@@ -1260,6 +1332,8 @@ export declare interface UploadLimits {
 /** What an upload ticket authorizes: a single through-app upload bound to an
  *  owner/tenant/content-type/visibility, until `exp`. */
 export declare interface UploadTicketPayload {
+    /** Exact storage plugin instance authorized to accept the bytes. */
+    readonly instance: string;
     /** ownerId (subject id) the stored object is attributed to. */
     readonly sub: string | null;
     /** tenantId that scopes the key prefix + ref row. */