@vertracloud/blob 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+import { APIBlobObject, BlobVisibility, BlobContentDisposition, APIBlobUpload, SnowFlake, APIBlobObjectList, APIBlobBatchResult, APIBlobDeleteResult, APIBlobDownload, APIBlobStats, APIBlobUploadToken, APIBlobS3Credentials, APIBlobShare, APIBlobRules, RESTPutAPIBlobRuleBody, APIBlobCustomDomain, RESTPatchAPIBlobDomainBody } from '@vertracloud/api-types/v1';
+export { APIBlobBatchResult, APIBlobCustomDomain, APIBlobDeleteResult, APIBlobDownload, APIBlobLimits, APIBlobObject, APIBlobObjectList, APIBlobRule, APIBlobRules, APIBlobS3Credentials, APIBlobShare, APIBlobSharePublic, APIBlobStats, APIBlobUpload, APIBlobUploadPart, APIBlobUploadToken, APIErrorCode, BlobContentDisposition, BlobCustomDomainStatus, BlobUploadMode, BlobUploadStatus, BlobVisibility, ISODateString, RESTBlobObjectWriteOptions, RESTBlobRuleInput, RESTDeleteAPIBlobObjectsBody, RESTDeleteAPIBlobObjectsResponse, RESTDeleteAPIBlobRuleResponse, RESTGetAPIBlobDomainsResponse, RESTGetAPIBlobObjectDownloadQuery, RESTGetAPIBlobObjectDownloadResponse, RESTGetAPIBlobObjectResponse, RESTGetAPIBlobObjectsQuery, RESTGetAPIBlobObjectsResponse, RESTGetAPIBlobRulesResponse, RESTGetAPIBlobS3CredentialsResponse, RESTGetAPIBlobSharesQuery, RESTGetAPIBlobSharesResponse, RESTGetAPIBlobStatsResponse, RESTGetAPIBlobUploadResponse, RESTGetAPIBlobUploadsResponse, RESTPatchAPIBlobDomainBody, RESTPatchAPIBlobDomainResponse, RESTPatchAPIBlobObjectBody, RESTPatchAPIBlobObjectResponse, RESTPatchAPIBlobObjectsBody, RESTPatchAPIBlobObjectsResponse, RESTPostAPIBlobDomainBody, RESTPostAPIBlobDomainResponse, RESTPostAPIBlobDomainVerifyResponse, RESTPostAPIBlobObjectCopyBody, RESTPostAPIBlobObjectCopyResponse, RESTPostAPIBlobObjectQuery, RESTPostAPIBlobObjectResponse, RESTPostAPIBlobShareBody, RESTPostAPIBlobShareResponse, RESTPostAPIBlobUploadBody, RESTPostAPIBlobUploadCompleteResponse, RESTPostAPIBlobUploadPartsBody, RESTPostAPIBlobUploadPartsResponse, RESTPostAPIBlobUploadResponse, RESTPostAPIBlobUploadTokenBody, RESTPostAPIBlobUploadTokenResponse, RESTPutAPIBlobRuleBody, RESTPutAPIBlobRuleResponse, RESTPutAPIBlobRulesBody, RESTPutAPIBlobRulesResponse, SnowFlake } from '@vertracloud/api-types/v1';
+
+/** Alias of `APIBlobObject`, the object returned by `put`, `get`, `list`, … */
+type BlobObject = APIBlobObject;
+
+/** Everything `put` and `resume` accept as file content. A `ReadableStream` also needs `size`. */
+type BlobData = Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array> | string;
+
+/** Error envelope sent by the API on any non-2xx response: `{ code, message?, details? }`. */
+interface BlobErrorBody {
+    code: string;
+    message?: string;
+    details?: unknown;
+}
+/**
+ * Codes the SDK raises itself (they never come from the API): `NETWORK_ERROR`, `TIMEOUT`, `ABORTED`,
+ * `INVALID_ARGUMENT`, `UPLOAD_FAILED` (the storage rejected a direct upload) and `INVALID_RESPONSE`.
+ * `status` is `0` for the ones that happened before an HTTP response existed.
+ */
+type BlobClientErrorCode = "NETWORK_ERROR" | "TIMEOUT" | "ABORTED" | "INVALID_ARGUMENT" | "UPLOAD_FAILED" | "INVALID_RESPONSE";
+/**
+ * Error thrown for every failed call: an API error response (`code` is an `APIErrorCode`, for example
+ * `BLOB_OBJECT_NOT_FOUND`) or a client-side failure (see {@link BlobClientErrorCode}).
+ *
+ * `toString()` and `toJSON()` never include the request that produced the error (URL, headers,
+ * credentials, signed upload URLs) — only `status`, `code`, `message`, `details` and `retryAfter`.
+ */
+declare class BlobError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: unknown;
+    /** Seconds to wait before retrying, from the `Retry-After` header (429 responses). */
+    readonly retryAfter: number | undefined;
+    constructor(status: number, body: BlobErrorBody, retryAfter?: number);
+    toJSON(): {
+        name: string;
+        status: number;
+        code: string;
+        message: string;
+        details: unknown;
+        retryAfter: number | undefined;
+    };
+    toString(): string;
+}
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+interface BlobClientOptions {
+    /** API key (`blob:read` / `blob:write`). Sent as `Authorization: Bearer <apiKey>`. */
+    apiKey?: string;
+    /** Upload token (`vcup_…`) for browsers and other untrusted clients; valid on the upload routes only. */
+    uploadToken?: string;
+    /**
+     * API base URL **including the version prefix**; every route is appended to it (`${baseUrl}/objects`).
+     * Default `https://blob.vertracloud.app/v1`.
+     */
+    baseUrl?: string;
+    /** Custom `fetch` (proxies, tests, instrumentation). When set, upload progress is by completed part instead of by byte. */
+    fetch?: FetchLike;
+    /** Sent with every API call. Use `"include"` with a cookie session; then no Authorization header is needed. Never sent to signed upload URLs. */
+    credentials?: RequestCredentials;
+    /** Added as `?workspace_id=` to every API call, to act on the blob of a workspace owner. */
+    workspaceId?: string;
+    /** Extra headers for every API call. */
+    headers?: Record<string, string>;
+    /** Parts uploaded at the same time in a multipart upload. Default 4. */
+    partConcurrency?: number;
+    /** Retries for idempotent calls (GET, and the PUT of a part or single upload) on 5xx and network errors. Default 3. Never applied to 429. */
+    maxRetries?: number;
+    /** First retry delay in ms; doubles each attempt, with jitter. Default 300. */
+    retryDelayMs?: number;
+    /** Default timeout in ms for each API call. Default 30000; `0` disables. */
+    timeout?: number;
+    /** Timeout in ms for each request that sends file bytes (a part, a single PUT, or the simple upload). Default 300000; `0` disables. */
+    uploadTimeout?: number;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+    /** Timeout in ms for this call, overriding the client default. */
+    timeout?: number;
+}
+interface BlobProgress {
+    loaded: number;
+    total: number;
+}
+interface BlobWriteOptions {
+    visibility?: BlobVisibility;
+    /** Replace an existing object at the same path. */
+    overwrite?: boolean;
+    /** Insert `-<10 random characters>` before the extension. */
+    randomSuffix?: boolean;
+    cacheControl?: string;
+    contentDisposition?: BlobContentDisposition;
+    /** File name suggested on download. */
+    filename?: string;
+    expiresAt?: Date | string;
+    /** Hex SHA-256 of the file. */
+    checksumSha256?: string;
+    /** Up to 5 keys, plan-dependent. */
+    metadata?: Record<string, string>;
+}
+interface BlobPutOptions extends BlobWriteOptions, RequestOptions {
+    /** Total size in bytes. Required for a `ReadableStream`. */
+    size?: number;
+    /** Called as bytes are sent. By byte in browsers (XMLHttpRequest); by finished part in Node and edge runtimes. */
+    onProgress?: (progress: BlobProgress) => void;
+    /** Called once a direct upload exists, before any byte is sent. Keep `upload.id` to `resume` after a crash. */
+    onUpload?: (upload: APIBlobUpload) => void;
+}
+interface BlobResumeOptions extends RequestOptions {
+    size?: number;
+    onProgress?: (progress: BlobProgress) => void;
+}
+interface BlobListOptions extends RequestOptions {
+    prefix?: string;
+    /** Group paths into folders at this character (usually `/`); folders only come back from `listPage`. */
+    delimiter?: string;
+    visibility?: BlobVisibility;
+    /** Page size, 1–1000. Default 100. */
+    limit?: number;
+}
+interface BlobListPageOptions extends BlobListOptions {
+    cursor?: string;
+}
+interface BlobUpdateChanges {
+    visibility?: BlobVisibility;
+    /** `null` restores the default. */
+    cacheControl?: string | null;
+    contentDisposition?: BlobContentDisposition | null;
+    filename?: string | null;
+    expiresAt?: Date | string | null;
+    /** A `null` value removes that key. */
+    metadata?: Record<string, string | null>;
+}
+interface BlobCopyOptions extends RequestOptions {
+    overwrite?: boolean;
+    randomSuffix?: boolean;
+    visibility?: BlobVisibility;
+}
+interface BlobDownloadUrlOptions extends RequestOptions {
+    /** Seconds, 60–86400. Default 3600. */
+    expiresIn?: number;
+    disposition?: BlobContentDisposition;
+    filename?: string;
+}
+interface BlobUploadTokenOptions extends RequestOptions {
+    path?: string;
+    prefix?: string;
+    visibility?: BlobVisibility;
+    /** Let uploads made with the token replace an existing object. Default `false`. */
+    overwrite?: boolean;
+    maxSize?: number;
+    allowedExtensions?: string[];
+    cacheControl?: string;
+    contentDisposition?: BlobContentDisposition;
+    expiresAt?: Date | string;
+    metadata?: Record<string, string>;
+    /** Seconds the token stays valid, 60–3600. Default 900. */
+    expiresIn?: number;
+    /** 1–100. Default 1. */
+    maxUses?: number;
+}
+interface BlobShareOptions extends RequestOptions {
+    /** Seconds, 60 to 30 days. Default 24 hours. */
+    expiresIn?: number;
+    maxDownloads?: number;
+    password?: string;
+}
+/** One folder rule, with camelCase keys (the snake_case wire shape returned by `rules.get()` is accepted too). */
+interface BlobRuleInput {
+    visibility?: BlobVisibility;
+    expireSeconds?: number;
+    maxSize?: number;
+    extensions?: string[];
+    cacheControl?: string;
+    deleteAfterDays?: number;
+}
+type BlobRuleWithPrefix = (BlobRuleInput | RESTPutAPIBlobRuleBody) & {
+    prefix: string;
+};
+interface BlobImageOptions {
+    width?: number;
+    height?: number;
+    /** For example `scale-down`, `contain`, `cover`, `crop`, `pad`. */
+    fit?: string;
+    /** For example `auto`, `webp`, `avif`, `jpeg`, `png`. */
+    format?: string;
+    /** 1–100. */
+    quality?: number;
+}
+type BlobDeleteManyInput = {
+    ids: SnowFlake[];
+} | {
+    prefix: string;
+};
+declare class BlobClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly credentials;
+    private readonly workspaceId;
+    private readonly extraHeaders;
+    private readonly partConcurrency;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly timeout;
+    private readonly uploadTimeout;
+    constructor(options?: BlobClientOptions);
+    /**
+     * Uploads a file. Up to 5 MB it is one `POST /objects`; above that it starts a direct upload and
+     * follows the mode the API picks: one signed PUT, or parts sent in parallel. Returns the object.
+     * Aborting `signal` during a direct upload cancels it on the server (best effort).
+     */
+    put(path: string, data: BlobData, options?: BlobPutOptions): Promise<APIBlobObject>;
+    /** Continues an interrupted direct upload, sending only the parts the server does not have yet. `data` must be the same file. */
+    resume(uploadId: SnowFlake, data: BlobData, options?: BlobResumeOptions): Promise<APIBlobObject>;
+    /** Direct uploads still in progress. */
+    listUploads(options?: RequestOptions): Promise<APIBlobUpload[]>;
+    /** Aborts a direct upload and frees its reserved storage. Repeating it is not an error. */
+    abortUpload(uploadId: SnowFlake, options?: RequestOptions): Promise<void>;
+    private putSimple;
+    private transfer;
+    private putSingle;
+    private putParts;
+    /** PUT to a signed URL with exactly the headers the API returned. No credentials are attached. Retried on 5xx and network errors. */
+    private putBytes;
+    /** One page of objects plus the `folders` found under the prefix, and the `cursor` of the next page (`null` on the last). */
+    listPage(options?: BlobListPageOptions): Promise<APIBlobObjectList>;
+    /** Iterates every object that matches, fetching pages as needed. */
+    list(options?: BlobListOptions): AsyncGenerator<APIBlobObject, void, undefined>;
+    get(id: SnowFlake, options?: RequestOptions): Promise<APIBlobObject>;
+    update(id: SnowFlake, changes: BlobUpdateChanges, options?: RequestOptions): Promise<APIBlobObject>;
+    /** Applies the same changes to any number of objects (sent in batches of 100, the API limit); one result per id, in the order of `ids`. */
+    updateMany(ids: SnowFlake[], changes: BlobUpdateChanges, options?: RequestOptions): Promise<APIBlobBatchResult[]>;
+    copy(id: SnowFlake, path: string, options?: BlobCopyOptions & {
+        move?: boolean;
+    }): Promise<APIBlobObject>;
+    /** Moves or renames an object; the id stays the same. */
+    move(id: SnowFlake, path: string, options?: BlobCopyOptions): Promise<APIBlobObject>;
+    delete(id: SnowFlake, options?: RequestOptions): Promise<void>;
+    /**
+     * Deletes by `ids` or by folder `prefix`, repeating while the API reports `remaining`
+     * (it deletes up to 1000 per call). The result merges every round.
+     */
+    deleteMany(input: BlobDeleteManyInput, options?: RequestOptions): Promise<APIBlobDeleteResult>;
+    /** A temporary download link (`{ url, expires_at }`). It cannot be revoked. */
+    downloadUrl(id: SnowFlake, options?: BlobDownloadUrlOptions): Promise<APIBlobDownload>;
+    /**
+     * Builds an image-transformation URL from a public object (or its public URL). Pure: no request is made.
+     * Throws for a private object, which has no public URL.
+     */
+    imageUrl(source: Pick<APIBlobObject, "url"> | string, options?: BlobImageOptions): string;
+    stats(options?: RequestOptions): Promise<APIBlobStats>;
+    /** Creates a token that fixes every constraint you pass; hand it to a browser as `uploadToken`. */
+    createUploadToken(options?: BlobUploadTokenOptions): Promise<APIBlobUploadToken>;
+    /** S3-compatible credentials derived from the API key, for aws-cli, rclone or boto3. */
+    s3Credentials(options?: RequestOptions): Promise<APIBlobS3Credentials>;
+    readonly shares: {
+        create: (objectId: SnowFlake, options?: BlobShareOptions) => Promise<APIBlobShare>;
+        list: (options?: RequestOptions & {
+            objectId?: SnowFlake;
+        }) => Promise<APIBlobShare[]>;
+        revoke: (shareId: SnowFlake, options?: RequestOptions) => Promise<void>;
+    };
+    readonly rules: {
+        get: (options?: RequestOptions) => Promise<APIBlobRules>;
+        /** Replaces the whole list. `etag` is the one from the list you read; a stale one fails with `BLOB_RULES_CONFLICT`. */
+        set: (rules: BlobRuleWithPrefix[], etag: string, options?: RequestOptions) => Promise<APIBlobRules>;
+        /** Creates or changes the rule of one folder; returns the whole list and its new etag. */
+        put: (prefix: string, rule: BlobRuleInput | RESTPutAPIBlobRuleBody, options?: RequestOptions) => Promise<APIBlobRules>;
+        delete: (prefix: string, options?: RequestOptions) => Promise<APIBlobRules>;
+    };
+    readonly domains: {
+        list: (options?: RequestOptions) => Promise<APIBlobCustomDomain[]>;
+        add: (hostname: string, options?: RequestOptions & {
+            prefix?: string;
+            web_content?: boolean;
+        }) => Promise<APIBlobCustomDomain>;
+        update: (domainId: SnowFlake, body: RESTPatchAPIBlobDomainBody, options?: RequestOptions) => Promise<APIBlobCustomDomain>;
+        verify: (domainId: SnowFlake, options?: RequestOptions) => Promise<APIBlobCustomDomain>;
+        remove: (domainId: SnowFlake, options?: RequestOptions) => Promise<void>;
+    };
+    /** One API call: builds the URL, authenticates, unwraps `{ response }` and turns an error envelope into a `BlobError`. */
+    private api;
+    /** Sends a request, retrying 5xx and network errors when `req.retry` (never 429). */
+    private exec;
+    private once;
+}
+
+declare const VERSION = "0.1.0";
+
+export { BlobClient, type BlobClientErrorCode, type BlobClientOptions, type BlobCopyOptions, type BlobData, type BlobDeleteManyInput, type BlobDownloadUrlOptions, BlobError, type BlobErrorBody, type BlobImageOptions, type BlobListOptions, type BlobListPageOptions, type BlobObject, type BlobProgress, type BlobPutOptions, type BlobResumeOptions, type BlobRuleInput, type BlobRuleWithPrefix, type BlobShareOptions, type BlobUpdateChanges, type BlobUploadTokenOptions, type BlobWriteOptions, type FetchLike, type RequestOptions, VERSION };