@rebasepro/types 0.23.0 → 0.24.0

package/dist/controllers/storage.d.ts

@@ -8,13 +8,135 @@
  */
 export declare const PUBLIC_STORAGE_PREFIX = "public/";
 /**
- * True when a storage key/path points at a public object (lives under
- * {@link PUBLIC_STORAGE_PREFIX}). The check is applied to the key *within the
- * bucket* — strip any `bucket/` and `scheme://` prefixes first.
+ * True when a storage **key** is public: it lies under
+ * {@link PUBLIC_STORAGE_PREFIX}.
+ *
+ * The key is read exactly as it is — the canonical key within its bucket, the
+ * one the server stores, serves, and hands a `storageAuthorize` hook as
+ * `key` — and nothing is parsed out of it. That is the difference from
+ * {@link isPublicStoragePath}, which reads a client-side *path* and so strips
+ * a `scheme://` and a leading `default/` bucket segment first. On a key both are
+ * wrong: `default/public/x` is a key in a folder called `default`, and a
+ * request path `notes://public/x` names the key `notes:/public/x`. Neither is
+ * public, and the server decides on this function so that it never says they
+ * are.
+ *
+ * @group Models
+ */
+export declare function isPublicStorageKey(key: string | null | undefined): boolean;
+/**
+ * True when a storage key or client-side path points at a public object
+ * (lives under {@link PUBLIC_STORAGE_PREFIX}).
+ *
+ * For a path as a client holds it: a `scheme://` prefix and a single leading
+ * `default/` bucket segment are stripped first. The server and a
+ * `storageAuthorize` hook, which hold the canonical key, use
+ * {@link isPublicStorageKey}.
  *
  * @group Models
  */
 export declare function isPublicStoragePath(path: string | null | undefined): boolean;
+/**
+ * The path the storage routes address an object by, from a key or from the
+ * `storageUrl` an upload returned (`<scheme>://<bucket>/<key>`, which is what a
+ * property with `includeBucketUrl: true` keeps in its column).
+ *
+ * The routes address a source's objects by key. On S3 and GCS the bucket in a
+ * `storageUrl` is always the source's own — the server refuses any other — so
+ * it is dropped: sent along, `s3://acme-media/products/a.png` reached the
+ * server as the key `acme-media/products/a.png`, the preview found nothing and
+ * a delete reported success while the object stayed. It worked on local disk
+ * only, because `local://default/<key>` happens to carry the one bucket
+ * segment the routes recognise — which is kept, as is any other local bucket.
+ *
+ * A bare key whose first folder is `default` is sent behind that bucket
+ * segment. The routes read one leading `default/` (in any case) as the bucket,
+ * so the key `default/photo.png` sent as it is names the root `photo.png`:
+ * {@link defaultBucketPath} is the spelling that names the key itself.
+ *
+ * Shared by every storage source that talks to those routes — the SDK's and
+ * the admin panel's `useBackendStorageSource` — so they address an object alike.
+ *
+ * @group Models
+ */
+export declare function storageObjectPath(keyOrUrl: string, bucket?: string): string;
+/**
+ * The scheme of a **storage reference**: a stored object named inside text.
+ *
+ * Text that embeds a file — a markdown body above all — cannot hold a private
+ * object's URL: that URL carries a download token which expires in minutes,
+ * after which every reader of the text gets a 401 for an image that is still in
+ * the bucket. It holds a reference instead,
+ * `rebase-storage:posts/cover.png` (`?storageId=media` for a named source),
+ * and whoever renders the text exchanges each reference for a fresh URL with
+ * {@link resolveStorageReferences} — `resolveStorageReferences(text, client)`
+ * from `@rebasepro/client` on a site.
+ *
+ * @group Models
+ */
+export declare const STORAGE_REFERENCE_SCHEME = "rebase-storage:";
+/**
+ * The object a storage reference names.
+ *
+ * @group Models
+ */
+export interface StorageReferenceTarget {
+    /** The object's key in its storage source. */
+    key: string;
+    /** The named storage source holding it. Absent for the default source. */
+    storageId?: string;
+}
+/**
+ * The reference for an object — what text stores in place of its URL.
+ *
+ * Every part is percent-encoded, so the reference contains no space,
+ * parenthesis or quote and survives as one markdown link destination whatever
+ * the file was called.
+ *
+ * @group Models
+ */
+export declare function storageReference(key: string, storageId?: string | null): string;
+/**
+ * Whether a string — an image's `src`, a link's `href` — is a storage reference.
+ *
+ * @group Models
+ */
+export declare function isStorageReference(value: string | null | undefined): value is string;
+/**
+ * The object a storage reference names, or `null` for anything else — a URL, a
+ * bare key, or a reference whose key would climb out of its prefix.
+ *
+ * @group Models
+ */
+export declare function parseStorageReference(value: string | null | undefined): StorageReferenceTarget | null;
+/**
+ * Where {@link resolveStorageReferences} gets URLs from: a function that
+ * answers one, or anything shaped like a Rebase client — its `storage` for the
+ * default source and `createStorageSource(id)` for a named one.
+ *
+ * @group Models
+ */
+export type StorageReferenceResolver = ((target: StorageReferenceTarget) => Promise<string | null | undefined>) | {
+    storage?: StorageSource;
+    createStorageSource?(storageId: string): StorageSource;
+};
+/**
+ * Exchange every storage reference in `text` for a URL, at the moment the text
+ * is rendered.
+ *
+ * ```ts
+ * const html = markdown.render(await resolveStorageReferences(post.body, client));
+ * ```
+ *
+ * Each distinct object is asked for once — `getSignedUrl(key)` on its source —
+ * so a private object gets a freshly minted download URL every time the text is
+ * rendered. A reference that cannot be resolved (no such object, an unknown
+ * source) is left as it was, so a missing object reads as a missing image
+ * rather than as a failed render.
+ *
+ * @group Models
+ */
+export declare function resolveStorageReferences(text: string, from: StorageReferenceResolver): Promise<string>;
 /**
  * @group Models
  */
@@ -35,18 +157,15 @@ export interface UploadFileProps {
      * and the property path within it (`coverImage`, `meta.avatar`,
      * `gallery` for an array of files).
      *
-     * The server reads it to enforce that property's own `storage.maxSize` and
-     * `storage.acceptedFiles`, which were declared per property, published in
-     * the generated types, rendered by the panel's file picker, and until now
-     * enforced by nothing on the server — so a `curl` past the picker put a
-     * 40 MB executable in a bucket whose config said "images, under 200 KB".
+     * The server holds the upload to that property's own `storage.maxSize`
+     * and `storage.acceptedFiles`. It holds every upload to the limits of the
+     * properties whose `storagePath` its key falls in anyway, named or not;
+     * naming the property adds that property's rule, which matters for a
+     * property whose `storagePath` is a function the server cannot read.
      *
      * Advisory in one direction only. The rules are resolved from the server's
-     * own registry by slug, so naming a property can make an upload *stricter*
-     * or leave it at the global cap; it can never widen anything.
-     *
-     * Omitted, the upload is checked against the deployment's global
-     * `maxFileSize` exactly as before.
+     * own registry by slug, so naming a property can make an upload *stricter*;
+     * it can never widen anything.
      */
     context?: UploadPropertyContext;
 }

package/dist/errors.d.ts

@@ -23,7 +23,21 @@
  *
  * @group Errors
  */
-export type RebaseErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE" | "NETWORK_ERROR" | "OFFLINE" | "DB_PERMISSION_DENIED" | "SCHEMA_DRIFT" | (string & {});
+export type RebaseErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE" | "NETWORK_ERROR" | "OFFLINE" | "DB_PERMISSION_DENIED" | "SCHEMA_DRIFT"
+/**
+ * Realtime: the socket closed after a request was written and before the
+ * server answered — the request may or may not have run, and it is never
+ * re-sent. On a live subscription's `onError`: the connection has been
+ * down longer than a blip; the subscription is kept and resumes, with a
+ * fresh `onUpdate`, when the socket is back.
+ */
+ | "CONNECTION_LOST"
+/**
+ * Realtime: no answer within the request timeout of the call — either it
+ * waited for a socket the whole time and was never sent, or it was written
+ * and never answered.
+ */
+ | "REQUEST_TIMEOUT" | (string & {});
 /**
  * Structured initializer for {@link RebaseApiError}.
  *