palbase 0.0.0-stage → 0.2.0

package/types/internal/src/modules/storage.d.ts

@@ -0,0 +1,691 @@
+import { type Reply, type Transport } from '../transport.js';
+export type Bucket = {
+    /**
+     * The content types it takes; empty: any. image/* names a family.
+     */
+    allowed_mime_types: string[];
+    /**
+     * When it was created.
+     */
+    created_at: string;
+    /**
+     * The largest object it takes, in bytes; absent: the platform's (5 GiB).
+     */
+    file_size_limit?: number;
+    /**
+     * The bucket's name.
+     */
+    name: string;
+    /**
+     * Whether anyone may read its objects at /storage/public/.
+     */
+    public: boolean;
+    /**
+     * When its declaration last changed.
+     */
+    updated_at: string;
+    /**
+     * The renditions made of every picture put in it.
+     */
+    variants: BucketVariant[];
+};
+export type BucketList = {
+    /**
+     * The project's buckets, by name.
+     */
+    buckets: Bucket[];
+};
+export type BucketVariant = {
+    /**
+     * cover fills the box and crops; contain and inside keep the whole picture inside it (inside never enlarges). Absent: contain.
+     */
+    fit: "cover" | "contain" | "inside";
+    /**
+     * The rendition's format. Absent: jpeg.
+     */
+    format: "jpeg" | "png" | "webp";
+    /**
+     * Pixels; 0 derives it from the width and the picture's aspect.
+     */
+    height: number;
+    /**
+     * The rendition's name: a lowercase letter, then lowercase letters, digits and _ (32 at most).
+     */
+    name: string;
+    /**
+     * 1 to 100 for jpeg and webp; 0: the format's default.
+     */
+    quality: number;
+    /**
+     * Pixels; 0 derives it from the height and the picture's aspect.
+     */
+    width: number;
+};
+export type BucketWrite = {
+    /**
+     * The content types it takes; empty or absent: any. image/* names a family. 64 at most.
+     */
+    allowed_mime_types?: string[];
+    /**
+     * The largest object it takes, in bytes (1 to 5 GiB); null or absent: the platform's.
+     */
+    file_size_limit?: number | null;
+    /**
+     * Whether anyone may read its objects at /storage/public/. Absent: false.
+     */
+    public?: boolean;
+    /**
+     * The renditions made of every picture put in it; 16 at most.
+     */
+    variants?: BucketVariant[];
+};
+export type ErrorResponse = {
+    /**
+     * Machine-readable error code (snake_case)
+     */
+    error: string;
+    /**
+     * Human-readable explanation
+     */
+    error_description: string;
+    /**
+     * Correlation ID for log/audit lookup
+     */
+    request_id: string;
+    /**
+     * Seconds to wait before retrying; present on a refusal that ends with time.
+     */
+    retry_after?: number;
+    /**
+     * HTTP status code (mirrors the response status)
+     */
+    status: number;
+};
+/**
+ * file.uploaded and file.deleted: an object written (or replaced) in a bucket, or removed from it — by an app, a signed URL, the project's server, or an upload route.
+ */
+export type FileEvent = {
+    /**
+     * The bucket.
+     */
+    bucket: string;
+    /**
+     * Its content type.
+     */
+    content_type: string;
+    /**
+     * The user it belongs to; null: the project's.
+     */
+    owner_id: string | null;
+    /**
+     * Its path in the bucket.
+     */
+    path: string;
+    /**
+     * Its size in bytes.
+     */
+    size: number;
+};
+/**
+ * file.moved: an object moved to another path in its bucket.
+ */
+export type FileMovedEvent = {
+    /**
+     * The bucket.
+     */
+    bucket: string;
+    /**
+     * The path it was at.
+     */
+    from: string;
+    /**
+     * The user it belongs to; null: the project's.
+     */
+    owner_id: string | null;
+    /**
+     * The path it is at now.
+     */
+    to: string;
+};
+/**
+ * An object's bytes.
+ */
+export type ObjectBytes = Blob;
+export type ObjectPage = {
+    /**
+     * The next page's cursor; absent on the last page.
+     */
+    next_cursor?: string;
+    /**
+     * A page of objects, newest first.
+     */
+    objects: StorageObject[];
+};
+export type ObjectRelocate = {
+    /**
+     * The object's path.
+     */
+    from: string;
+    /**
+     * Replace an object already at to. Absent: false.
+     */
+    overwrite?: boolean;
+    /**
+     * Where it goes.
+     */
+    to: string;
+};
+export type RenderedVariant = {
+    /**
+     * The rendition's content type, as it was made.
+     */
+    content_type: string;
+    /**
+     * Its size in bytes.
+     */
+    size: number;
+};
+export type SignedUrl = {
+    /**
+     * When it stops working.
+     */
+    expires_at: string;
+    /**
+     * The URL, at the project's own address.
+     */
+    url: string;
+};
+export type SignedUrlRequest = {
+    /**
+     * Seconds the URL works, 1 to 604800.
+     */
+    expires_in: number;
+    /**
+     * The object's path.
+     */
+    path: string;
+};
+export type StorageObject = {
+    /**
+     * Its bucket.
+     */
+    bucket: string;
+    /**
+     * The bytes' sha256, hex.
+     */
+    checksum_sha256: string;
+    /**
+     * Its content type, sniffed from its bytes.
+     */
+    content_type: string;
+    /**
+     * When an object was first stored at its path.
+     */
+    created_at: string;
+    /**
+     * A picture's height in pixels.
+     */
+    height?: number;
+    /**
+     * The user it belongs to; it is deleted with them. Absent: the project's.
+     */
+    owner_id?: string;
+    /**
+     * Its path.
+     */
+    path: string;
+    /**
+     * Its size in bytes.
+     */
+    size: number;
+    /**
+     * A picture's placeholder (ThumbHash, base64).
+     */
+    thumbhash?: string;
+    /**
+     * When its bytes or path last changed.
+     */
+    updated_at: string;
+    /**
+     * Its renditions, by name.
+     */
+    variants: {
+        [key: string]: RenderedVariant;
+    };
+    /**
+     * A picture's width in pixels.
+     */
+    width?: number;
+};
+/**
+ * What the project keeps, counted.
+ */
+export type StorageStats = {
+    /**
+     * Every bucket of the project, by name; an empty one with zeros.
+     */
+    buckets: StorageStatsBucket[];
+    /**
+     * One entry per UTC day of the window, oldest first; a day nothing was added on has zeros.
+     */
+    days: StorageStatsDay[];
+    totals: StorageStatsTotals;
+};
+/**
+ * One bucket's objects.
+ */
+export type StorageStatsBucket = {
+    /**
+     * Their bytes, renditions included.
+     */
+    bytes: number;
+    /**
+     * The bucket's name.
+     */
+    name: string;
+    /**
+     * The objects in it.
+     */
+    objects: number;
+};
+/**
+ * The objects first written on one UTC day that the project still keeps.
+ */
+export type StorageStatsDay = {
+    /**
+     * Their bytes now, renditions included.
+     */
+    bytes_added: number;
+    /**
+     * The UTC day, YYYY-MM-DD.
+     */
+    day: string;
+    /**
+     * How many.
+     */
+    objects_added: number;
+};
+/**
+ * Every object of the project.
+ */
+export type StorageStatsTotals = {
+    /**
+     * Their bytes, renditions included: what storage.bytes meters.
+     */
+    bytes: number;
+    /**
+     * How many.
+     */
+    objects: number;
+};
+/**
+ * What the app's completion handler (or its authorize's refusal) answered, as it answered it.
+ */
+export type UploadAnswer = unknown;
+export type UploadForm = {
+    /**
+     * The route's JSON body, at most 1 MiB; sent before the file.
+     */
+    body?: string;
+    /**
+     * The file; its part's filename and Content-Type are the app's to read (the type is detected from the bytes).
+     */
+    file: Blob;
+};
+export type UploadUrlRequest = {
+    /**
+     * Seconds the URL works, 1 to 604800.
+     */
+    expires_in: number;
+    /**
+     * A ceiling below the bucket's own, in bytes.
+     */
+    max_bytes?: number;
+    /**
+     * The user the object will belong to; it is deleted with them.
+     */
+    owner_id?: string;
+    /**
+     * The object's path.
+     */
+    path: string;
+};
+/** The events this module sends the project's webhooks (x-palbase-events), by type: each one's payload, the event's data. */
+export interface Events {
+    /**
+     * file.deleted: an object was removed from a bucket. An endpoint that names buckets hears only theirs.
+     */
+    "file.deleted": FileEvent;
+    /**
+     * file.moved: an object moved to another path in its bucket. An endpoint that names buckets hears only theirs.
+     */
+    "file.moved": FileMovedEvent;
+    /**
+     * file.uploaded: an object was written (or replaced) in a bucket. An endpoint that names buckets hears only theirs.
+     */
+    "file.uploaded": FileEvent;
+}
+/** Palbase Storage */
+export declare function client(t: Transport): {
+    /**
+     * List buckets
+     *
+     * Every bucket of the project, by name.
+     */
+    listBuckets(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, BucketList>>;
+    /**
+     * Read a bucket
+     *
+     * A bucket and its declaration.
+     */
+    getBucket(input: {
+        path: {
+            bucket: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Bucket>>;
+    /**
+     * Declare a bucket
+     *
+     * Creates the bucket as declared, or makes it so: whether anyone may read it (public), the largest object it takes, the content types it takes (empty: any; image/* a family), and the renditions made of every picture put in it. A declaration a renderer cannot honour is refused here, not at the first upload.
+     */
+    putBucket(input: {
+        path: {
+            bucket: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: BucketWrite; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Bucket> | Reply<201, Bucket>>;
+    /**
+     * Delete a bucket
+     *
+     * Deletes an empty bucket; one that still holds objects is refused (409 bucket_not_empty), so no file goes by surprise.
+     */
+    deleteBucket(input: {
+        path: {
+            bucket: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
+    /**
+     * Copy an object
+     *
+     * Writes a new object at to with from's bytes and renditions. An object already at to is refused (409 object_exists) unless overwrite. Emits file.uploaded.
+     */
+    copyObject(input: {
+        path: {
+            bucket: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: ObjectRelocate; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, StorageObject>>;
+    /**
+     * Move an object
+     *
+     * Gives the object at from the path to: no byte is copied. An object already at to is refused (409 object_exists) unless overwrite. Emits file.moved.
+     */
+    moveObject(input: {
+        path: {
+            bucket: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: ObjectRelocate; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, StorageObject>>;
+    /**
+     * List objects
+     *
+     * A bucket's objects, newest first, a page at a time; prefix narrows them to the paths that start with it.
+     */
+    listObjects(input: {
+        path: {
+            bucket: string;
+        };
+        query?: {
+            prefix?: string; /** Objects per page, 1 to 1000 (100 when absent). */
+            limit?: number; /** The next_cursor of the page before. */
+            cursor?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ObjectPage>>;
+    /**
+     * Read an object
+     *
+     * The object's bytes, or a rendition's (variant). Entity tags and one byte range are honoured; what is served is made inert (nosniff, a sandboxing CSP, and a download for any type a browser does not render safely). Counts toward the project's egress.
+     */
+    getObject(input: {
+        path: {
+            bucket: string; /** The object's path as ONE percent-encoded segment: a/b.jpg is a%2Fb.jpg. Segments are separated by /, none empty, . or ..; 1 to 1024 bytes of UTF-8. */
+            path: string;
+        };
+        query?: {
+            variant?: string;
+        };
+        headers?: {
+            Range?: string; /** The entity tag the caller holds; a match is answered 304 with no body. */
+            "If-None-Match"?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response> | Reply<206, Response> | Reply<304, undefined>>;
+    /**
+     * Write an object
+     *
+     * Stores the body at the path, replacing what is there (If-None-Match: * only creates). The type is sniffed from the bytes, not taken from Content-Type (which is used when the bytes cannot tell, as for HEIC); the bucket's ceiling and types are enforced while the bytes stream. A picture gets its dimensions, a placeholder (thumbhash) and the bucket's renditions, made inside the upload. owner_id makes the object a user's: it goes when they are deleted. Emits file.uploaded.
+     */
+    putObject(input: {
+        path: {
+            bucket: string; /** The object's path as ONE percent-encoded segment: a/b.jpg is a%2Fb.jpg. Segments are separated by /, none empty, . or ..; 1 to 1024 bytes of UTF-8. */
+            path: string;
+        };
+        query?: {
+            owner_id?: string;
+        };
+        headers?: {
+            "If-None-Match"?: "*"; /** The bytes' sha256, hex: bytes that do not match are refused and nothing is kept. */
+            "X-Checksum-Sha256"?: string;
+        };
+        body: BodyInit;
+        contentType?: string; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, StorageObject> | Reply<201, StorageObject>>;
+    /**
+     * Delete an object
+     *
+     * Deletes the object and its renditions; the bytes are swept from the blob store after. Emits file.deleted.
+     */
+    deleteObject(input: {
+        path: {
+            bucket: string; /** The object's path as ONE percent-encoded segment: a/b.jpg is a%2Fb.jpg. Segments are separated by /, none empty, . or ..; 1 to 1024 bytes of UTF-8. */
+            path: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
+    /**
+     * Read an object's headers
+     *
+     * GetObject without the body: size, type, entity tag.
+     */
+    headObject(input: {
+        path: {
+            bucket: string; /** The object's path as ONE percent-encoded segment: a/b.jpg is a%2Fb.jpg. Segments are separated by /, none empty, . or ..; 1 to 1024 bytes of UTF-8. */
+            path: string;
+        };
+        query?: {
+            variant?: string;
+        };
+        headers?: {
+            "If-None-Match"?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, undefined> | Reply<304, undefined>>;
+    /**
+     * Sign a download URL
+     *
+     * A URL that reads one object, by anyone holding it, until it expires (at most 7 days). The object must exist. The URL is the project's own address; it opens nothing at another project's.
+     */
+    createSignedUrl(input: {
+        path: {
+            bucket: string;
+        };
+        body: SignedUrlRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SignedUrl>>;
+    /**
+     * Sign an upload URL
+     *
+     * A URL a client PUTs one object to, until it expires (at most 7 days): the bytes go from the client to storage, never through the project's server. It pins the path, a ceiling (max_bytes, never above the bucket's), the bucket's content types and the user the object will belong to (owner_id).
+     */
+    createUploadUrl(input: {
+        path: {
+            bucket: string;
+        };
+        body: UploadUrlRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SignedUrl>>;
+    /**
+     * Read a public object
+     *
+     * An object of a public bucket, with no credential — what an <img src> or a CDN fetches. A private bucket's object is refused (403, the same answer a forged link gets).
+     */
+    getPublicObject(input: {
+        path: {
+            bucket: string; /** The object's path as ONE percent-encoded segment: a/b.jpg is a%2Fb.jpg. Segments are separated by /, none empty, . or ..; 1 to 1024 bytes of UTF-8. */
+            path: string;
+        };
+        query?: {
+            variant?: string;
+        };
+        headers?: {
+            Range?: string; /** The entity tag the caller holds; a match is answered 304 with no body. */
+            "If-None-Match"?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response> | Reply<206, Response> | Reply<304, undefined>>;
+    /**
+     * Read a public object's headers
+     *
+     * GetPublicObject without the body.
+     */
+    headPublicObject(input: {
+        path: {
+            bucket: string; /** The object's path as ONE percent-encoded segment: a/b.jpg is a%2Fb.jpg. Segments are separated by /, none empty, . or ..; 1 to 1024 bytes of UTF-8. */
+            path: string;
+        };
+        query?: {
+            variant?: string;
+        };
+        headers?: {
+            "If-None-Match"?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, undefined> | Reply<304, undefined>>;
+    /**
+     * Read through a signed URL
+     *
+     * What a download signature grants: the one object it names, until it expires. Any other object, an upload signature, an edited, expired or another project's signature: 403.
+     */
+    getSignedObject(input: {
+        path: {
+            bucket: string; /** The object's path as ONE percent-encoded segment: a/b.jpg is a%2Fb.jpg. Segments are separated by /, none empty, . or ..; 1 to 1024 bytes of UTF-8. */
+            path: string;
+        };
+        query: {
+            variant?: string; /** The bucket the signature grants (from the signed URL). */
+            b: string; /** The object path the signature grants (from the signed URL). */
+            p: string; /** When the signature expires, Unix seconds (from the signed URL). */
+            e: string; /** The signature (from the signed URL). Every parameter of the URL is covered by it. */
+            sig: string;
+        };
+        headers?: {
+            Range?: string; /** The entity tag the caller holds; a match is answered 304 with no body. */
+            "If-None-Match"?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response> | Reply<206, Response> | Reply<304, undefined>>;
+    /**
+     * Write through a signed URL
+     *
+     * What an upload signature grants: the one object it names, no larger than its ceiling, of its content types, belonging to its owner. If-None-Match: * only creates. Emits file.uploaded.
+     */
+    putSignedObject(input: {
+        path: {
+            bucket: string; /** The object's path as ONE percent-encoded segment: a/b.jpg is a%2Fb.jpg. Segments are separated by /, none empty, . or ..; 1 to 1024 bytes of UTF-8. */
+            path: string;
+        };
+        query: {
+            b: string; /** The object path the signature grants (from the signed URL). */
+            p: string; /** When the signature expires, Unix seconds (from the signed URL). */
+            e: string; /** The signature (from the signed URL). Every parameter of the URL is covered by it. */
+            sig: string; /** Marks an upload grant (from the signed URL). */
+            u: string; /** The largest object the upload may be, in bytes (from the signed URL). */
+            max: string; /** The content types the upload may be (from the signed URL). */
+            mime?: string; /** The user the uploaded object will belong to (from the signed URL). */
+            o?: string;
+        };
+        headers?: {
+            "If-None-Match"?: "*"; /** The bytes' sha256, hex: bytes that do not match are refused and nothing is kept. */
+            "X-Checksum-Sha256"?: string;
+        };
+        body: BodyInit;
+        contentType?: string; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, StorageObject> | Reply<201, StorageObject>>;
+    /**
+     * Read headers through a signed URL
+     *
+     * GetSignedObject without the body.
+     */
+    headSignedObject(input: {
+        path: {
+            bucket: string; /** The object's path as ONE percent-encoded segment: a/b.jpg is a%2Fb.jpg. Segments are separated by /, none empty, . or ..; 1 to 1024 bytes of UTF-8. */
+            path: string;
+        };
+        query: {
+            variant?: string; /** The bucket the signature grants (from the signed URL). */
+            b: string; /** The object path the signature grants (from the signed URL). */
+            p: string; /** When the signature expires, Unix seconds (from the signed URL). */
+            e: string; /** The signature (from the signed URL). Every parameter of the URL is covered by it. */
+            sig: string;
+        };
+        headers?: {
+            "If-None-Match"?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, undefined> | Reply<304, undefined>>;
+    /**
+     * Read the storage stats
+     *
+     * What the project keeps, counted: its objects and their bytes — an object's own and its renditions', as storage.bytes meters them — in all and per bucket (every bucket; an empty one with zeros), and, for each of the last `days` UTC days (today included; a day nothing was added on is listed with zeros), the objects first written that day and their bytes. Counted from the objects the project keeps now: a deleted object is in no count, and a replaced one counts on the day it was first written, with the bytes it holds now.
+     */
+    getStorageStats(input?: {
+        query?: {
+            days?: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, StorageStats>>;
+    /**
+     * Upload a file to an app's upload route
+     *
+     * An app's upload route (@Upload): one call carrying a file and a JSON body, answered with what the app's completion handler returned. The app's machine authorizes it (the route's own auth, and the object's bucket and path), storage writes the bytes under the bucket's rules and measures them, then gives the app the object and the body; its answer is this call's, as the app gave it. A completion that refuses, or does not answer, deletes the object. The caller is named to the app (id, session, role); its token is never forwarded.
+     */
+    upload(input: {
+        path: {
+            machine: string; /** The app's upload route as ONE percent-encoded segment: posts/photo is posts%2Fphoto. Segments separated by /, none empty, . or .. (after Unicode compatibility folding), no control character or backslash; 1 to 1024 bytes of UTF-8. Its query is the request's own. */
+            route: string;
+        };
+        body: BodyInit;
+        contentType?: string; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<never>;
+};
+export type Client = ReturnType<typeof client>;