@voltro/plugin-storage 0.73.0 → 0.75.0

package/dist/types.d.ts

@@ -136,8 +136,29 @@ export declare interface PutInput {
      * Needs a bound data store; the in-memory ref store cannot hold intents.
      */
     readonly operationId?: string;
+    /**
+     * This caller's CLAIM on the operation's object, any stable string the
+     * caller owns (an attempt id, a replica id). Two callers completing the same
+     * `operationId` share one ref; each holds its own claim, registered when it
+     * receives the ref. `delete(id, { claim })` releases only that claim and the
+     * object goes with the LAST one — so a caller that fails and cleans up what
+     * it put cannot delete the file another caller already kept. The same claim
+     * repeated is one claim. Requires `operationId`; refused otherwise
+     * (`StorageRejected`, `'claim-without-operation'`).
+     */
+    readonly claim?: string;
 }
 
+/**
+ * What a `put` did to its object. A plain put is always `'created'`. With an
+ * `operationId`: `'created'` reserved the operation, `'resumed'` found it
+ * half-done and finished the write, `'joined'` found it finished and took its
+ * ref. Informational — ownership is the `claim`, not the outcome: "only clean
+ * up what I created" deletes a joiner's kept file whenever the creator is the
+ * caller that fails.
+ */
+export declare type PutOutcome = 'created' | 'resumed' | 'joined';
+
 /** One derived output a `Transcoder` produces from a source asset. Each becomes
  *  a normal storage ref linked back to the original via `derivedFrom`. */
 export declare interface Rendition {
@@ -372,7 +393,8 @@ declare const StorageService_base: Context.TagClass<StorageService, "@voltro/plu
 
 /** The service handlers consume: `const storage = yield* StorageService`. */
 export declare interface StorageServiceShape {
-    readonly put: (input: PutInput) => Effect.Effect<StorageRef, StorageError | StorageRejected | StorageScanRejected>;
+    /** Store bytes. The result is the ref plus this call's `outcome`. */
+    readonly put: (input: PutInput) => Effect.Effect<StoredRef, StorageError | StorageRejected | StorageScanRejected>;
     /** Fetch an object's bytes by id. Enforces the tenant guard ONLY — it does
      *  NOT run the access policy / grant check. Use this for trusted server-side
      *  reads where the caller has already authorized the access; to deliver a
@@ -426,8 +448,15 @@ export declare interface StorageServiceShape {
         readonly ref: StorageRef;
         readonly totalSize: number;
     }, StorageError>;
+    /** Delete an object. Without a `claim` this is the WHOLE object, whatever
+     *  claims it holds. With one, only that claim is released, and the object
+     *  is deleted when it was the last (`PutInput.claim`). A claim that is not
+     *  held, or named on a ref that was not written through an operation, is a
+     *  `StorageError` with status 409 — nothing is deleted. Releasing a claim
+     *  twice is a no-op. */
     readonly delete: (id: string, opts?: {
         readonly tenantId?: string | null;
+        readonly claim?: string;
     }) => Effect.Effect<void, StorageError>;
     /** Run the access check for `subject`, then return a URL that delivers
      *  the bytes: a public/CDN URL, a presigned GET (s3/minio), or an app
@@ -628,6 +657,13 @@ export declare interface StoredObject {
     readonly contentType: string;
 }
 
+/** What `put` returns: the stored ref, plus what this call did to it. The
+ *  `outcome` is a fact about the CALL, not the row — it is never persisted and
+ *  a ref read back from the store does not carry it. */
+export declare type StoredRef = StorageRef & {
+    readonly outcome: PutOutcome;
+};
+
 /** A streamed read from a provider — the object as a {@link ByteStream} plus
  *  its content type and, when the backend reports it up front, its size. */
 export declare interface StoredStream {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-storage",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "description": "File-storage plugin — one StorageProvider contract, switchable backends (S3 / MinIO / Azure / filesystem / memory / database). Public (CDN-direct) + private (access policy + per-object grants) objects, upload constraints, virus-scan hook, on-the-fly image transforms.",
   "keywords": [
     "voltro",
@@ -43,9 +43,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.73.0",
-    "@voltro/env": "0.73.0",
-    "@voltro/protocol": "0.73.0"
+    "@voltro/database": "0.75.0",
+    "@voltro/env": "0.75.0",
+    "@voltro/protocol": "0.75.0"
   },
   "optionalDependencies": {
     "@aws-sdk/client-s3": "^3.1126.0",