@tinycloud/sdk-services 3.7.0-beta.2 → 3.7.0-beta.3

package/dist/index.d.cts

@@ -1574,50 +1574,76 @@ interface StorageFullEvent {
 type StorageFullHandler = (event: StorageFullEvent) => void;
 /**
  * Turns the storage rejections seen by any number of service contexts into
- * one `storage.full` event, and remembers whose storage is full so read paths
+ * `storage.full` events, and remembers whose storage is full so read paths
  * can skip their best-effort writes.
  *
  * Storage is one budget per owner, so fullness is recorded per owner, apart
  * from the event: a rejection on one owner's space never hides a later
- * rejection on another's. The event fires once per episode, which lasts until
- * no owner is known to be full.
+ * rejection on another's.
+ *
+ * The signed-in account's own storage has an episode. Its first rejection
+ * starts the episode and emits `storage.full`; later rejections do not emit
+ * again. The episode ends only when a write to that owner's storage succeeds,
+ * or on {@link clear}. A status read does not end it. A rejection on another
+ * owner's delegated space emits `storage.full` once per owner until a status
+ * read or a successful write clears that owner, and starts no episode.
  *
  * The event goes through the rejecting context's `emit` (so telemetry and the
  * debug log see it) and then to the handlers registered with {@link on}.
  */
 declare class StorageFullMonitor {
     private readonly ownerOf;
-    /** The emitted event, until the episode ends. */
-    private event;
-    /** First rejection per owner key; {@link UNKNOWN_OWNER} when the space was unknown. */
+    private readonly ownOwner;
+    /** The own-storage episode, until a successful write or {@link clear} ends it. */
+    private episode;
+    /**
+     * First rejection per owner key; {@link UNKNOWN_OWNER} when the space was unknown.
+     * A status read or a successful write removes the owner, so best-effort writes resume.
+     */
     private readonly full;
     private readonly handlers;
+    private readonly episodeListeners;
+    private readonly delegatedListeners;
     /**
      * @param ownerOf Owner key of a space id. Spaces with one key share one
      * storage budget. Defaults to the space id itself.
+     * @param ownOwner Owner key of the signed-in account, or undefined when
+     * there is none. Rejections on that owner's storage, or on a space that was
+     * unknown, start the episode.
      */
-    constructor(ownerOf?: (spaceId: string) => string);
-    /** True while any owner's storage is known to be full. */
+    constructor(ownerOf?: (spaceId: string) => string, ownOwner?: () => string | undefined);
+    /** True while any owner's storage is known to be full for best-effort writes. */
     get isFull(): boolean;
-    /** The rejection `storage.full` announced, until the episode ends. */
+    /** The rejection that started the own-storage episode, until it ends. */
     get rejection(): StorageFullEvent | undefined;
     /**
      * True when a write to `spaceId`'s owner was rejected, or a write whose
      * space was unknown was: that one could have been any owner's.
      */
     isFullFor(spaceId: string | undefined): boolean;
-    /** Watch a context's service errors. Returns the unsubscribe function. */
+    /** Subscribe to the own-storage episode starting or ending. Returns the unsubscribe function. */
+    onEpisode(listener: () => void): () => void;
+    /**
+     * Subscribe to a delegated owner's storage being found full: once per owner
+     * until that owner is cleared. The own-storage episode does not fire it.
+     * Returns the unsubscribe function.
+     */
+    onDelegated(listener: () => void): () => void;
+    /** Watch a context's service errors and successful writes. Returns the unsubscribe function. */
     observe(context: IServiceContext): () => void;
     /** Subscribe to the `storage.full` event. Returns the unsubscribe function. */
     on(handler: StorageFullHandler): () => void;
-    /** Forget that any owner's storage is full; the next rejection emits `storage.full` again. */
+    /** Forget every owner's full state and end the episode; the next rejection starts a new one. */
     clear(): void;
     /**
-     * Forget that `spaceId`'s owner is full (`undefined`: the rejections whose
-     * space was unknown). Once no owner is full, the next rejection emits
-     * `storage.full` again.
+     * Forget that `spaceId`'s owner is full for best-effort writes (`undefined`:
+     * the rejections whose space was unknown). Does not end the episode.
      */
     clearFor(spaceId: string | undefined): void;
+    private isOwn;
+    private ownerFor;
+    private notifyEpisode;
+    private notifyDelegated;
 }
 
 /** Where the owner frees up space or upgrades their plan. */

package/dist/index.d.ts

@@ -1574,50 +1574,76 @@ interface StorageFullEvent {
 type StorageFullHandler = (event: StorageFullEvent) => void;
 /**
  * Turns the storage rejections seen by any number of service contexts into
- * one `storage.full` event, and remembers whose storage is full so read paths
+ * `storage.full` events, and remembers whose storage is full so read paths
  * can skip their best-effort writes.
  *
  * Storage is one budget per owner, so fullness is recorded per owner, apart
  * from the event: a rejection on one owner's space never hides a later
- * rejection on another's. The event fires once per episode, which lasts until
- * no owner is known to be full.
+ * rejection on another's.
+ *
+ * The signed-in account's own storage has an episode. Its first rejection
+ * starts the episode and emits `storage.full`; later rejections do not emit
+ * again. The episode ends only when a write to that owner's storage succeeds,
+ * or on {@link clear}. A status read does not end it. A rejection on another
+ * owner's delegated space emits `storage.full` once per owner until a status
+ * read or a successful write clears that owner, and starts no episode.
  *
  * The event goes through the rejecting context's `emit` (so telemetry and the
  * debug log see it) and then to the handlers registered with {@link on}.
  */
 declare class StorageFullMonitor {
     private readonly ownerOf;
-    /** The emitted event, until the episode ends. */
-    private event;
-    /** First rejection per owner key; {@link UNKNOWN_OWNER} when the space was unknown. */
+    private readonly ownOwner;
+    /** The own-storage episode, until a successful write or {@link clear} ends it. */
+    private episode;
+    /**
+     * First rejection per owner key; {@link UNKNOWN_OWNER} when the space was unknown.
+     * A status read or a successful write removes the owner, so best-effort writes resume.
+     */
     private readonly full;
     private readonly handlers;
+    private readonly episodeListeners;
+    private readonly delegatedListeners;
     /**
      * @param ownerOf Owner key of a space id. Spaces with one key share one
      * storage budget. Defaults to the space id itself.
+     * @param ownOwner Owner key of the signed-in account, or undefined when
+     * there is none. Rejections on that owner's storage, or on a space that was
+     * unknown, start the episode.
      */
-    constructor(ownerOf?: (spaceId: string) => string);
-    /** True while any owner's storage is known to be full. */
+    constructor(ownerOf?: (spaceId: string) => string, ownOwner?: () => string | undefined);
+    /** True while any owner's storage is known to be full for best-effort writes. */
     get isFull(): boolean;
-    /** The rejection `storage.full` announced, until the episode ends. */
+    /** The rejection that started the own-storage episode, until it ends. */
     get rejection(): StorageFullEvent | undefined;
     /**
      * True when a write to `spaceId`'s owner was rejected, or a write whose
      * space was unknown was: that one could have been any owner's.
      */
     isFullFor(spaceId: string | undefined): boolean;
-    /** Watch a context's service errors. Returns the unsubscribe function. */
+    /** Subscribe to the own-storage episode starting or ending. Returns the unsubscribe function. */
+    onEpisode(listener: () => void): () => void;
+    /**
+     * Subscribe to a delegated owner's storage being found full: once per owner
+     * until that owner is cleared. The own-storage episode does not fire it.
+     * Returns the unsubscribe function.
+     */
+    onDelegated(listener: () => void): () => void;
+    /** Watch a context's service errors and successful writes. Returns the unsubscribe function. */
     observe(context: IServiceContext): () => void;
     /** Subscribe to the `storage.full` event. Returns the unsubscribe function. */
     on(handler: StorageFullHandler): () => void;
-    /** Forget that any owner's storage is full; the next rejection emits `storage.full` again. */
+    /** Forget every owner's full state and end the episode; the next rejection starts a new one. */
     clear(): void;
     /**
-     * Forget that `spaceId`'s owner is full (`undefined`: the rejections whose
-     * space was unknown). Once no owner is full, the next rejection emits
-     * `storage.full` again.
+     * Forget that `spaceId`'s owner is full for best-effort writes (`undefined`:
+     * the rejections whose space was unknown). Does not end the episode.
      */
     clearFor(spaceId: string | undefined): void;
+    private isOwn;
+    private ownerFor;
+    private notifyEpisode;
+    private notifyDelegated;
 }
 
 /** Where the owner frees up space or upgrades their plan. */

package/dist/index.js

@@ -5395,20 +5395,29 @@ var StorageFullMonitor = class {
   /**
    * @param ownerOf Owner key of a space id. Spaces with one key share one
    * storage budget. Defaults to the space id itself.
+   * @param ownOwner Owner key of the signed-in account, or undefined when
+   * there is none. Rejections on that owner's storage, or on a space that was
+   * unknown, start the episode.
    */
-  constructor(ownerOf = (spaceId) => spaceId) {
+  constructor(ownerOf = (spaceId) => spaceId, ownOwner = () => void 0) {
     this.ownerOf = ownerOf;
-    /** First rejection per owner key; {@link UNKNOWN_OWNER} when the space was unknown. */
+    this.ownOwner = ownOwner;
+    /**
+     * First rejection per owner key; {@link UNKNOWN_OWNER} when the space was unknown.
+     * A status read or a successful write removes the owner, so best-effort writes resume.
+     */
     this.full = /* @__PURE__ */ new Map();
     this.handlers = /* @__PURE__ */ new Set();
+    this.episodeListeners = /* @__PURE__ */ new Set();
+    this.delegatedListeners = /* @__PURE__ */ new Set();
   }
-  /** True while any owner's storage is known to be full. */
+  /** True while any owner's storage is known to be full for best-effort writes. */
   get isFull() {
     return this.full.size > 0;
   }
-  /** The rejection `storage.full` announced, until the episode ends. */
+  /** The rejection that started the own-storage episode, until it ends. */
   get rejection() {
-    return this.event;
+    return this.episode?.event;
   }
   /**
    * True when a write to `spaceId`'s owner was rejected, or a write whose
@@ -5417,13 +5426,31 @@ var StorageFullMonitor = class {
   isFullFor(spaceId) {
     return this.full.has(UNKNOWN_OWNER) || spaceId !== void 0 && this.full.has(this.ownerOf(spaceId));
   }
-  /** Watch a context's service errors. Returns the unsubscribe function. */
+  /** Subscribe to the own-storage episode starting or ending. Returns the unsubscribe function. */
+  onEpisode(listener) {
+    this.episodeListeners.add(listener);
+    return () => {
+      this.episodeListeners.delete(listener);
+    };
+  }
+  /**
+   * Subscribe to a delegated owner's storage being found full: once per owner
+   * until that owner is cleared. The own-storage episode does not fire it.
+   * Returns the unsubscribe function.
+   */
+  onDelegated(listener) {
+    this.delegatedListeners.add(listener);
+    return () => {
+      this.delegatedListeners.delete(listener);
+    };
+  }
+  /** Watch a context's service errors and successful writes. Returns the unsubscribe function. */
   observe(context) {
-    return context.on(TelemetryEvents.SERVICE_ERROR, (data) => {
+    const stopErrors = context.on(TelemetryEvents.SERVICE_ERROR, (data) => {
       const { service, error } = data;
       if (!error || !isStorageFullError(error)) return;
       const spaceId = context.session?.spaceId;
-      const owner = spaceId ? this.ownerOf(spaceId) : UNKNOWN_OWNER;
+      const owner = this.ownerFor(spaceId);
       if (this.full.has(owner)) return;
       const meta = error.meta ?? {};
       const event = { service: service ?? error.service, error };
@@ -5434,8 +5461,13 @@ var StorageFullMonitor = class {
       }
       if (spaceId) event.spaceId = spaceId;
       this.full.set(owner, event);
-      if (this.event) return;
-      this.event = event;
+      if (this.isOwn(owner)) {
+        if (this.episode) return;
+        this.episode = { owner, event };
+        this.notifyEpisode();
+      } else {
+        this.notifyDelegated();
+      }
       context.emit(TelemetryEvents.STORAGE_FULL, event);
       for (const handler of this.handlers) {
         try {
@@ -5445,6 +5477,19 @@ var StorageFullMonitor = class {
         }
       }
     });
+    const stopWrites = context.on(TelemetryEvents.SERVICE_RESPONSE, (data) => {
+      const { service, action, ok: ok2 } = data;
+      if (ok2 !== true || !isCommittingWrite(service, action)) return;
+      const owner = this.ownerFor(context.session?.spaceId);
+      this.full.delete(owner);
+      if (this.episode?.owner !== owner) return;
+      this.episode = void 0;
+      this.notifyEpisode();
+    });
+    return () => {
+      stopErrors();
+      stopWrites();
+    };
   }
   /** Subscribe to the `storage.full` event. Returns the unsubscribe function. */
   on(handler) {
@@ -5453,22 +5498,56 @@ var StorageFullMonitor = class {
       this.handlers.delete(handler);
     };
   }
-  /** Forget that any owner's storage is full; the next rejection emits `storage.full` again. */
+  /** Forget every owner's full state and end the episode; the next rejection starts a new one. */
   clear() {
     this.full.clear();
-    this.event = void 0;
+    if (!this.episode) return;
+    this.episode = void 0;
+    this.notifyEpisode();
   }
   /**
-   * Forget that `spaceId`'s owner is full (`undefined`: the rejections whose
-   * space was unknown). Once no owner is full, the next rejection emits
-   * `storage.full` again.
+   * Forget that `spaceId`'s owner is full for best-effort writes (`undefined`:
+   * the rejections whose space was unknown). Does not end the episode.
    */
   clearFor(spaceId) {
-    this.full.delete(spaceId === void 0 ? UNKNOWN_OWNER : this.ownerOf(spaceId));
-    if (this.full.size === 0) this.event = void 0;
+    this.full.delete(this.ownerFor(spaceId));
+  }
+  isOwn(owner) {
+    return owner === UNKNOWN_OWNER || owner === this.ownOwner();
+  }
+  ownerFor(spaceId) {
+    return spaceId ? this.ownerOf(spaceId) : UNKNOWN_OWNER;
+  }
+  notifyEpisode() {
+    for (const listener of this.episodeListeners) {
+      try {
+        listener();
+      } catch (listenerError) {
+        console.error("Error in storage episode listener:", listenerError);
+      }
+    }
+  }
+  notifyDelegated() {
+    for (const listener of this.delegatedListeners) {
+      try {
+        listener();
+      } catch (listenerError) {
+        console.error("Error in delegated storage listener:", listenerError);
+      }
+    }
   }
 };
 var UNKNOWN_OWNER = "\0unknown";
+var COMMITTING_ACTIONS = /* @__PURE__ */ new Map([
+  ["kv", ["put", "batchPut"]],
+  ["vault", ["put"]],
+  ["sql", ["execute", "batch", "executeStatement", "migrations.apply"]],
+  ["duckdb", ["execute", "batch", "executeStatement", "import"]]
+]);
+function isCommittingWrite(service, action) {
+  if (service === void 0 || action === void 0) return false;
+  return COMMITTING_ACTIONS.get(service)?.includes(action) ?? false;
+}
 
 // src/storage/status.ts
 var STORAGE_MANAGE_URL = "https://account.tinycloud.xyz/storage";