@everfur/sdk 0.1.1 → 0.4.0

package/dist/attachments-DpldrvIW.d.ts

@@ -0,0 +1,146 @@
+import { E as EverfurError } from './EverfurResult-DN9pL2Ab.js';
+import { R as RequestFunnel } from './requestFunnel-DFMGcluw.js';
+import { F as FileHandle, U as UploadTransport, a as UploadPolicyWire } from './ports-BN6RHF9W.js';
+import { R as ReadableStore, T as Timers } from './ports-D7YW8qz9.js';
+
+/** The image MIME types the chat accepts (the server's `CHAT_ATTACHMENT` rule, plus the `image/jpg` alias). */
+declare const ATTACHMENT_MIME_TYPES: readonly string[];
+/** The `accept` list of a web file input: the MIME types and their extensions. */
+declare const ATTACHMENT_ACCEPT = "image/jpeg,image/png,image/webp,image/heic,image/heif,.jpg,.jpeg,.png,.webp,.heic,.heif";
+/** The server's cap on one attachment (`max_content_length: 10485760`). */
+declare const MAX_ATTACHMENT_BYTES: number;
+/** The server's cap on attachments per message (`image_s3_keys`). */
+declare const MAX_ATTACHMENTS_PER_MESSAGE = 5;
+/** The filename cap after sanitising. */
+declare const MAX_FILENAME_LENGTH = 120;
+/** The route the initiate step posts to. */
+declare const ATTACHMENT_INITIATE_PATH = "/widget/v1/uploads/initiate";
+/** True when `mime` is an accepted image type (case-insensitive). */
+declare function isAttachmentMime(mime: string | undefined): boolean;
+/**
+ * Sanitise a user-supplied filename so it can sit in a request body, a label or a log line: path separators
+ * become spaces, control characters and quotes are dropped, whitespace collapses, and the result is capped at
+ * `MAX_FILENAME_LENGTH` keeping the extension. Empty in, `attachment` out.
+ */
+declare function sanitizeFilename(input: string | undefined): string;
+/** `512 B`, `12.3 KB`, `10.0 MB`: the app's byte formatter, for the size copy. */
+declare function formatBytes(bytes: number): string;
+/** The closed set of attachment failures; the React layer maps each to the app's copy. */
+type AttachmentErrorCode = 'too_large' | 'too_many' | 'unsupported_type' | 'network' | 'server' | 'cancelled' | 'rate_limited' | 'quota_exceeded' | 'idempotency_conflict' | 'unknown';
+/** One attachment failure, typed; `retryable` says whether a retry control is honest. */
+interface AttachmentError {
+    readonly code: AttachmentErrorCode;
+    readonly retryable: boolean;
+    /** The sanitised filename the failure is about. */
+    readonly filename: string;
+    /** For `too_large`: the file's size. */
+    readonly sizeBytes?: number;
+    /** For `server`: the HTTP status when one is known. */
+    readonly httpStatus?: number;
+    /** The settled SDK error behind a wire failure, when there is one (`displayMessage` is safe). */
+    readonly cause?: EverfurError;
+}
+/** The settle-shaped outcome of every attachment step: `AttachmentError` on the failure branch, never a throw. */
+type AttachmentOutcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: AttachmentError;
+};
+/** A validated file: what the queue uploads. */
+interface ValidatedAttachment {
+    readonly file: FileHandle;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly sizeBytes: number;
+}
+/** The byte size of a handle: its `sizeBytes`, else its in-memory `blob`'s size; null when unknown. */
+declare function attachmentSize(file: FileHandle): number | null;
+/**
+ * The picker-boundary check: an accepted image type, at most `MAX_ATTACHMENT_BYTES`, a known size (the initiate
+ * body needs it), and a sanitised filename. Settles; never throws.
+ */
+declare function validateAttachment(file: FileHandle): AttachmentOutcome<ValidatedAttachment>;
+/** The presigned policy `POST /widget/v1/uploads/initiate` returns, plus the key the send names. */
+interface AttachmentUploadPolicy extends UploadPolicyWire {
+    readonly s3_key: string;
+    readonly purpose: string | null;
+}
+/**
+ * Step 2: ask for the presigned policy. Settles `ok(policy)` or a typed failure; a malformed policy is a
+ * non-retryable `server` failure (retrying cannot change the shape).
+ */
+declare function initiateAttachmentUpload(funnel: RequestFunnel, attachment: ValidatedAttachment, opts?: {
+    readonly signal?: AbortSignal;
+}): Promise<AttachmentOutcome<AttachmentUploadPolicy>>;
+/**
+ * Step 3: stage the bytes on S3 through the injected transport (the policy fields first, `file` last). A
+ * rejection is a retryable `server` failure, an abort a `cancelled` one; nothing here throws.
+ */
+declare function uploadAttachmentBytes(transport: UploadTransport, policy: AttachmentUploadPolicy, attachment: ValidatedAttachment, opts?: {
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (fraction: number) => void;
+}): Promise<AttachmentOutcome<void>>;
+declare const ATTACHMENT_QUEUE_CONCURRENCY = 2;
+declare const ATTACHMENT_MAX_ATTEMPTS = 3;
+declare const ATTACHMENT_BACKOFF_MS: readonly number[];
+type AttachmentStatus = 'uploading' | 'uploaded' | 'failed';
+/** One attachment as a composer renders it. `s3Key` is set once `status === 'uploaded'`. */
+interface AttachmentState {
+    readonly id: string;
+    readonly filename: string;
+    /** What the thumbnail shows: the handle's `uri` (an object URL on the web, the local file on native). */
+    readonly previewUri: string;
+    readonly contentType: string;
+    readonly sizeBytes: number;
+    readonly status: AttachmentStatus;
+    readonly s3Key: string | null;
+    readonly error: AttachmentError | null;
+    /** 0..1 while uploading (the transport may report completion only). */
+    readonly progress: number;
+}
+/** The queue's frozen snapshot: the attachments in the order they were added. */
+interface AttachmentQueueSnapshot {
+    readonly attachments: readonly AttachmentState[];
+}
+interface AttachmentQueueDeps {
+    /** The request funnel of the current scope (the initiate hop). */
+    readonly funnel: RequestFunnel;
+    /** The host's upload transport (`EverfurConfig.uploadTransport`); the absent sentinel means uploads cannot run. */
+    readonly transport: UploadTransport;
+    /** The cap on attachments in the queue (the composer's slots); default `MAX_ATTACHMENTS_PER_MESSAGE`. */
+    readonly maxPerMessage?: number;
+    readonly concurrency?: number;
+    readonly maxAttempts?: number;
+    readonly backoffMs?: readonly number[];
+    /** Injected clock for deterministic backoff in tests. */
+    readonly timers?: Timers;
+    /** Injected id factory for deterministic tests. */
+    readonly newId?: () => string;
+}
+interface AttachmentQueue extends ReadableStore<AttachmentQueueSnapshot> {
+    /** True when the host wired an upload transport; a surface hides its attach control otherwise. */
+    readonly available: boolean;
+    /**
+     * Validate and enqueue one picked file. Settles `ok(state)` (the row, already `uploading`) or the typed
+     * failure that kept it out (`too_many`, `unsupported_type`, `too_large`, ...). Never throws.
+     */
+    add(file: FileHandle): AttachmentOutcome<AttachmentState>;
+    /** Re-run a failed row from the start (a fresh initiate; the same 3-attempt budget). A no-op otherwise. */
+    retry(id: string): void;
+    /** Drop a row: cancels it when in flight. */
+    remove(id: string): void;
+    /** Drop every row (after a send, or on unmount). */
+    clear(): void;
+    /** True while any row is still uploading (the send is blocked meanwhile). */
+    readonly uploading: boolean;
+    /** The S3 keys of every uploaded row, in order: what `SendOptions.imageS3Keys` takes. */
+    readonly s3Keys: readonly string[];
+    /** Stop everything and drop every listener. */
+    dispose(): void;
+}
+/** Build a queue. Framework-free; a React surface binds it through `useSyncExternalStore`. */
+declare function createAttachmentQueue(deps: AttachmentQueueDeps): AttachmentQueue;
+
+export { type AttachmentError as A, MAX_ATTACHMENTS_PER_MESSAGE as M, type ValidatedAttachment as V, type AttachmentErrorCode as a, type AttachmentOutcome as b, type AttachmentQueue as c, type AttachmentState as d, type AttachmentStatus as e, ATTACHMENT_ACCEPT as f, ATTACHMENT_BACKOFF_MS as g, ATTACHMENT_INITIATE_PATH as h, ATTACHMENT_MAX_ATTEMPTS as i, ATTACHMENT_MIME_TYPES as j, ATTACHMENT_QUEUE_CONCURRENCY as k, type AttachmentQueueDeps as l, type AttachmentQueueSnapshot as m, type AttachmentUploadPolicy as n, MAX_ATTACHMENT_BYTES as o, MAX_FILENAME_LENGTH as p, attachmentSize as q, createAttachmentQueue as r, formatBytes as s, initiateAttachmentUpload as t, isAttachmentMime as u, sanitizeFilename as v, uploadAttachmentBytes as w, validateAttachment as x };