@burdenoff/fe-libs 2026.1007.6 → 2026.1008.1

package/dist/shared/assistant/attachmentCommit.d.ts

@@ -0,0 +1,175 @@
+import { FilesPort } from '../../storage/filesPort';
+import { AssistantAttachment } from './attachments';
+/** files-svc switches to MULTIPART above this size; the browser cannot upload those. */
+export declare const ATTACHMENT_DIRECT_UPLOAD_MAX_BYTES: number;
+/**
+ * The commit path's OWN bounded retry policy. It is deliberately not the cold-start ladder
+ * `uploadBlobToFiles` walks (10 s then 20 s, up to 75 s): a person is waiting on Send, and
+ * Cancel is always there. The Files service is warmed when the panel opens.
+ */
+export declare const ATTACHMENT_COMMIT_POLICY: {
+    /** Files uploaded at once. */
+    readonly concurrency: 2;
+    /** ensureFolderByPath / initiateUpload / reads: at most this many attempts. */
+    readonly gatewayAttempts: 2;
+    readonly gatewayRetryDelayMs: 1500;
+    /** The PUT: network error or 5xx is retried this many times. */
+    readonly putRetries: 1;
+    readonly putRetryDelayMs: 1000;
+    /** `getUploadSession` attempts before falling back to `getMyUploadSessions`. */
+    readonly lookupAttempts: 2;
+    readonly lookupRetryDelayMs: 500;
+    /** After a reconcile finds the session still IN_PROGRESS. */
+    readonly completeReissues: 1;
+    /** How long a stopped commit still waits for an in-flight completeUpload to answer. */
+    readonly settleGraceMs: 3000;
+    /** Attempts at each rollback step. */
+    readonly discardAttempts: 2;
+    /**
+     * `discardPending()` (panel closed, draft cleared) looks again at what is still undecided, this
+     * many times, `finalDrainDelayMs * round` apart: after the committer is gone nothing else will,
+     * and a completeUpload that timed out can still land a few seconds later.
+     */
+    readonly finalDrainRounds: 3;
+    readonly finalDrainDelayMs: 5000;
+};
+export type AttachmentCommitPolicy = {
+    -readonly [K in keyof typeof ATTACHMENT_COMMIT_POLICY]: number;
+};
+/** Codes for failures the commit decides itself; a server failure keeps the server's own code. */
+export declare const ATTACHMENT_COMMIT_CODES: {
+    readonly quotaNotProvisioned: "QUOTA_NOT_PROVISIONED";
+    readonly quotaExceeded: "QUOTA_EXCEEDED";
+    readonly tooLarge: "ATTACHMENT_TOO_LARGE_FOR_DIRECT_UPLOAD";
+    readonly noBytes: "ATTACHMENT_NO_BYTES";
+    readonly noDownloadUrl: "ATTACHMENT_NO_DOWNLOAD_URL";
+    readonly timeout: "ATTACHMENT_SAVE_TIMEOUT";
+    readonly uploadFailed: "ATTACHMENT_UPLOAD_FAILED";
+    readonly folderFailed: "ATTACHMENT_FOLDER_FAILED";
+};
+/** One draft attachment and the bytes held for it in memory. */
+export interface CommitDraft {
+    attachment: AssistantAttachment;
+    /** Null when the bytes are gone (the failure is reported on the chip, nothing is sent). */
+    blob: Blob | null;
+}
+export interface AttachmentCommitFailure {
+    /** The attachment's id. */
+    id: string;
+    message: string;
+    code: string | undefined;
+}
+/** What a failed rollback leaves for the next commit (or `discardPending`) to retry. */
+export type PendingDiscard = 
+/** A file this commit created and could not delete. */
+{
+    kind: 'file';
+    fileId: string;
+}
+/** A session whose `completeUpload` was issued and whose outcome is unknown: reconcile, delete if FINALIZED. */
+ | {
+    kind: 'session';
+    sessionId: string;
+};
+export interface PendingDiscardStore {
+    entries: PendingDiscard[];
+    /**
+     * The drain that is running now. A drain takes the entries out of `entries` while it works and
+     * puts back what it could not settle, so a second drain (or the final one after an unmount)
+     * must wait for it instead of reading an empty list.
+     */
+    draining?: Promise<void>;
+}
+export type CommitMode = 
+/** Any failure undoes everything and sends nothing (composer). */
+'all-or-nothing'
+/** A failed file is dropped and the rest is kept (voice: the spoken question is still asked). */
+ | 'best-effort';
+export type AttachmentCommitSuccess = {
+    ok: true;
+    /** The input attachments in order: committed ones carry fileId/downloadUrl; skipped ones are untouched. */
+    attachments: AssistantAttachment[];
+    /** Best-effort only: attachments that could not be saved and are NOT in `attachments`. */
+    dropped: AttachmentCommitFailure[];
+    /** Call once the files are referenced by a sent message; rollback is a no-op from then on. */
+    handedOver: () => void;
+    /** Hard-delete what this commit created (the turn could not be sent after all). */
+    rollback: () => Promise<void>;
+};
+export type AttachmentCommitFailureResult = {
+    ok: false;
+    cancelled: boolean;
+    /** Per-attachment reasons (empty for a plain cancel). */
+    failures: AttachmentCommitFailure[];
+    /** The first failure's message, ready for a live region. */
+    message: string | undefined;
+};
+export type AttachmentCommitResult = AttachmentCommitSuccess | AttachmentCommitFailureResult;
+export interface CommitOptions {
+    port: FilesPort;
+    /** The product's attachments folder, e.g. `/BigConsole/AI Assistant/Attachments`. */
+    folderPath: string;
+    drafts: readonly CommitDraft[];
+    signal?: AbortSignal;
+    mode?: CommitMode;
+    /** Total time allowed; when it runs out unfinished files are dropped (or fail the commit). */
+    budgetMs?: number;
+    /** Chip updates: `uploading` + progress while running, `ready` (+ `saveError`) at the end. */
+    onChange?: (id: string, patch: Partial<AssistantAttachment>) => void;
+    /** Where failed rollbacks are remembered. Defaults to a fresh store. */
+    pendingDiscard?: PendingDiscardStore;
+    policy?: Partial<AttachmentCommitPolicy>;
+    /** Test seams. `sleep` resolves early when its signal aborts. */
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** Retry earlier failed rollbacks. A session with a FINALIZED outcome becomes a file delete. */
+export declare function drainPendingDiscards(port: FilesPort, store: PendingDiscardStore, options?: Pick<CommitOptions, 'sleep'> & {
+    policy?: Partial<AttachmentCommitPolicy>;
+}): Promise<void>;
+export declare function commitAttachments(options: CommitOptions): Promise<AttachmentCommitResult>;
+export interface AttachmentCommitterConfig {
+    port: FilesPort;
+    folderPath: string;
+    onChange?: CommitOptions['onChange'];
+    policy?: CommitOptions['policy'];
+    now?: CommitOptions['now'];
+    sleep?: CommitOptions['sleep'];
+}
+export interface AttachmentCommitter {
+    /**
+     * Single flight: while a commit is running, another call returns the SAME promise, so
+     * Enter held down or a double click yields one set of Files calls.
+     */
+    commit: (drafts: readonly CommitDraft[], options?: {
+        mode?: CommitMode;
+        budgetMs?: number;
+        signal?: AbortSignal;
+    }) => Promise<AttachmentCommitResult>;
+    /** Abort the running commit (it rolls back and resolves `{ ok: false, cancelled: true }`). */
+    cancel: () => void;
+    readonly isCommitting: boolean;
+    /** Retry rollbacks that failed earlier (draft cleared, panel closed). */
+    discardPending: () => Promise<void>;
+    readonly pendingDiscard: readonly PendingDiscard[];
+}
+export declare function createAttachmentCommitter(config: AttachmentCommitterConfig): AttachmentCommitter;
+/**
+ * How old a minted download URL may get before a Retry mints a new one. The URL is minted at
+ * Send, seconds before the turn; "Try again" on a failed turn can come much later, and the
+ * presigned URL has a short life.
+ */
+export declare const ATTACHMENT_URL_MAX_AGE_MS: number;
+/**
+ * Whether a saved attachment's URL should be re-minted before it is replayed. An unknown age
+ * (`urlResolvedAt` unset: sent by an older build) counts as stale; an attachment with no
+ * `fileId` has nothing to mint a URL for.
+ */
+export declare function attachmentUrlIsStale(attachment: Pick<AssistantAttachment, 'fileId' | 'urlResolvedAt'>, now: number, maxAgeMs?: number): boolean;
+/**
+ * The same attachments with a fresh download URL where the old one is stale. A lookup that
+ * fails or answers nothing keeps the old URL: the replay still goes out, and its inlined text
+ * and metadata are intact.
+ */
+export declare function refreshStaleAttachmentUrls(attachments: readonly AssistantAttachment[], resolveUrl: (fileId: string) => Promise<string | null>, now?: number): Promise<AssistantAttachment[]>;
+//# sourceMappingURL=attachmentCommit.d.ts.map

package/dist/shared/assistant/attachmentCommit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachmentCommit.d.ts","sourceRoot":"","sources":["../../../src/shared/assistant/attachmentCommit.ts"],"names":[],"mappings":"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"}