@rebasepro/types 0.17.3 → 0.18.1

package/src/controllers/storage.ts

@@ -1,252 +0,0 @@
-/**
- * Path prefix that marks an object as **public**. Files stored under this
- * prefix are served without any auth token via a stable, permanent,
- * CDN-cacheable URL (see {@link StorageSource.getSignedUrl}). Shared by the
- * client SDK and the backend so both agree on which objects are public.
- *
- * @group Models
- */
-export 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.
- *
- * @group Models
- */
-export function isPublicStoragePath(path: string | null | undefined): boolean {
-    if (!path) return false;
-    let p = path;
-    const scheme = p.indexOf("://");
-    if (scheme !== -1) p = p.substring(scheme + 3);
-    p = p.replace(/^\/+/, "");
-
-    // Defense-in-depth: a path containing traversal segments is never public,
-    // so an attacker can't reach a private object via `public/../secret`.
-    if (p.split("/").some((seg) => seg === "..")) return false;
-
-    // Public iff the object **key** starts with the public prefix. A single
-    // leading `default/` bucket segment is tolerated (the default bucket).
-    // A substring match is deliberately NOT used — a private object under a
-    // folder literally named `public` (e.g. `reports/public/q3.pdf`) must stay
-    // private. Named buckets: pass the key (not `bucket/key`) so the prefix is
-    // anchored; otherwise it falls back to a private, token-scoped URL (safe).
-    return p.startsWith(PUBLIC_STORAGE_PREFIX) || p.startsWith(`default/${PUBLIC_STORAGE_PREFIX}`);
-}
-
-/**
- * @group Models
- */
-export interface UploadFileProps {
-    file: File,
-    key: string,
-    metadata?: Record<string, unknown>,
-    bucket?: string,
-    /**
-     * Store this object as **public**: it is placed under
-     * {@link PUBLIC_STORAGE_PREFIX} and served via a stable, token-less,
-     * permanent URL (safe to persist in a database and cache on a CDN).
-     * Defaults to `false` (private, short-lived signed URLs).
-     */
-    public?: boolean
-}
-
-/**
- * @group Models
- */
-export interface UploadFileResult {
-    /**
-     * Storage key including the file name where the file was uploaded.
-     */
-    key: string;
-    /**
-     * Bucket where the file was uploaded
-     */
-    bucket: string;
-
-    /**
-     * Fully qualified storage URL for the uploaded file.
-     *
-     * For example: `s3://my-bucket/path/to/file.png`. Every controller in the
-     * framework returns one — S3, GCS and local alike — and a caller that stores
-     * the reference needs it, so it is part of the result rather than a maybe.
-     */
-    storageUrl: string;
-}
-
-/**
- * @group Models
- */
-export interface DownloadConfig {
-    /**
-     * Temporal url that can be used to download the file
-     */
-    url: string | null;
-
-    metadata?: DownloadMetadata;
-
-    fileNotFound?: boolean;
-}
-
-/**
- * The full set of object metadata, including read-only properties.
- * @public
- */
-export declare interface DownloadMetadata {
-    /**
-     * The bucket this object is contained in.
-     */
-    bucket: string;
-    /**
-     * The full path of this object.
-     */
-    fullPath: string;
-    /**
-     * The short name of this object, which is the last component of the full path.
-     * For example, if path is 'full/path/image.png', name is 'image.png'.
-     */
-    name: string;
-    /**
-     * The size of this object, in bytes.
-     */
-    size: number;
-    /**
-     * Type of the uploaded file
-     * e.g. "image/jpeg"
-     */
-    contentType: string;
-
-    customMetadata: Record<string, unknown>;
-    /**
-     * Optional short-lived download token (for local/server-mediated storage).
-     * Absent for public objects, which need no token.
-     */
-    token?: string;
-    /**
-     * Optional remaining lifetime of the token, in seconds.
-     */
-    tokenExpiresIn?: number;
-    /**
-     * True when this object is public: it is served without a token via a
-     * stable, permanent, CDN-cacheable URL. When set, the client builds a
-     * token-less URL and caches it indefinitely.
-     */
-    public?: boolean;
-}
-
-/**
- * @group Models
- */
-export interface StorageSource {
-    /**
-     * Upload an object, specifying a key
-     * @param file
-     * @param key
-     * @param metadata
-     * @param bucket
-     */
-    putObject: ({
-                     file,
-                     key,
-                     metadata,
-                     bucket
-                 }: UploadFileProps) => Promise<UploadFileResult>;
-
-    /**
-     * Convert a storage key or URL into a download configuration (signed URL equivalent)
-     * @param keyOrUrl
-     * @param bucket
-     */
-    getSignedUrl: (keyOrUrl: string, bucket?: string) => Promise<DownloadConfig>;
-
-    /**
-     * Get an object from a storage key.
-     * It returns null if the object does not exist.
-     * @param key
-     * @param bucket
-     */
-    getObject: (key: string, bucket?: string) => Promise<File | null>;
-
-    /**
-     * Delete an object.
-     * @param key
-     * @param bucket
-     */
-    deleteObject: (key: string, bucket?: string) => Promise<void>;
-
-    /**
-     * List the contents of a prefix.
-     * @param prefix
-     * @param options
-     */
-    listObjects: (prefix: string, options?: {
-        bucket?: string,
-        maxResults?: number,
-        pageToken?: string
-    }) => Promise<StorageListResult>;
-
-}
-
-/**
- * Result returned by list().
- * @public
- */
-export declare interface StorageListResult {
-    /**
-     * References to prefixes (sub-folders). You can call list() on them to
-     * get its contents.
-     *
-     * Folders are implicit based on '/' in the object paths.
-     * For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a')
-     * will return '/a/b' as a prefix.
-     */
-    prefixes: StorageReference[];
-    /**
-     * Objects in this directory.
-     * You can call getMetadata() and getDownloadUrl() on them.
-     */
-    items: StorageReference[];
-    /**
-     * If set, there might be more results for this list. Use this token to resume the list.
-     */
-    nextPageToken?: string;
-}
-
-/**
- * Represents a reference to an S3-compatible storage object. Developers can
- * upload, download, and delete objects, as well as get/set object metadata.
- * @public
- */
-export declare interface StorageReference {
-    /**
-     * Returns a s3:// URL for this object in the form
-     *   `s3://<bucket>/<path>/<to>/<object>`
-     * @returns The s3:// URL.
-     */
-    toString(): string;
-
-    /**
-     * A reference to the root of this object's bucket.
-     */
-    root: StorageReference;
-    /**
-     * The name of the bucket containing this reference's object.
-     */
-    bucket: string;
-    /**
-     * The full path of this object.
-     */
-    fullPath: string;
-    /**
-     * The short name of this object, which is the last component of the full path.
-     * For example, if path is 'full/path/image.png', name is 'image.png'.
-     */
-    name: string;
-
-    /**
-     * A reference pointing to the parent location of this reference, or null if
-     * this reference is the root.
-     */
-    parent: StorageReference | null;
-}

package/src/errors.ts

@@ -1,119 +0,0 @@
-/**
- * The error codes every route can produce, as `RebaseApiError.code`.
- *
- * These are the defaults on `ApiError`'s static constructors server-side, so
- * any endpoint can answer with one. They are **not** the complete set: routes
- * pass their own more specific codes too (`EMAIL_EXISTS`, `TOKEN_EXPIRED`,
- * `INVALID_BULK_BODY`, …), and auth alone defines a couple of dozen.
- *
- * Hence the union is deliberately open rather than closed. It exists to give
- * autocomplete and to catch a typo in the common cases — `code` was a bare
- * `string`, so `e.code === "NOT_FOUND"` and `e.code === "NOTFOUND"` were
- * equally valid and only one of them worked. Closing it would be a lie that
- * broke the moment a route added a code.
- *
- * @example
- * if (e instanceof RebaseApiError) {
- *   switch (e.code) {
- *     case "NOT_FOUND": return null;          // completed
- *     case "FORBIDDEN": return redirect();
- *     default: throw e;                       // routes' own codes land here
- *   }
- * }
- *
- * @group Errors
- */
-export type RebaseErrorCode =
-    | "BAD_REQUEST"
-    | "UNAUTHORIZED"
-    | "FORBIDDEN"
-    | "NOT_FOUND"
-    | "CONFLICT"
-    | "INTERNAL_ERROR"
-    | "SERVICE_UNAVAILABLE"
-    | "DB_PERMISSION_DENIED"
-    | "SCHEMA_DRIFT"
-    // `string & {}` keeps the union open while preserving completion on the
-    // literals above — a bare `| string` would collapse them and offer nothing.
-    | (string & {});
-
-/**
- * Structured initializer for {@link RebaseApiError}.
- *
- * @group Errors
- */
-export interface RebaseErrorInit {
-    /**
-     * HTTP status code, when the error originated from an HTTP response.
-     * Left `undefined` for realtime/WebSocket, network, and client-side
-     * logic errors that have no HTTP status.
-     */
-    status?: number;
-    /** Stable, machine-readable error code. See {@link RebaseErrorCode}. */
-    code?: RebaseErrorCode;
-    /** Structured error payload returned by the server, when present. */
-    details?: unknown;
-    /** The underlying error this one wraps, if any. */
-    cause?: unknown;
-}
-
-/**
- * The single error type thrown across the entire Rebase client surface —
- * HTTP data/control-plane calls, realtime/WebSocket operations, and
- * client-side logic errors (e.g. an unknown collection accessor). A `catch`
- * block only ever needs to check for this one class:
- *
- * ```ts
- * import { RebaseApiError } from "@rebasepro/client"; // re-exported
- *
- * try {
- *   await client.data.products.update(id, { price: 9 });
- * } catch (e) {
- *   if (e instanceof RebaseApiError) {
- *     if (e.status === 404) { ... }   // HTTP failures carry a status
- *     console.error(e.code, e.details);
- *   }
- * }
- * ```
- *
- * `status` is present for HTTP failures and `undefined` otherwise, so its
- * presence distinguishes transport-level errors from realtime/logic errors.
- *
- * @group Errors
- */
-export class RebaseApiError extends Error {
-    /** HTTP status code, or `undefined` for non-HTTP errors. */
-    readonly status?: number;
-    /** Stable machine-readable error code, when the server supplied one. See {@link RebaseErrorCode}. */
-    readonly code?: RebaseErrorCode;
-    /** Structured error payload from the server, when present. */
-    readonly details?: unknown;
-
-    constructor(message: string, init: RebaseErrorInit = {}) {
-        super(message);
-        this.name = "RebaseApiError";
-        this.status = init.status;
-        this.code = init.code;
-        this.details = init.details;
-        if (init.cause !== undefined) {
-            // `cause` is standard on Error but not always in the lib target's type.
-            (this as { cause?: unknown }).cause = init.cause;
-        }
-    }
-}
-
-/**
- * Client-side logic error — raised before any request is made (e.g. accessing
- * an unknown collection accessor when a typed dictionary is configured).
- *
- * A subclass of {@link RebaseApiError} (with no `status`), so a single
- * `catch (e) { if (e instanceof RebaseApiError) ... }` handles it too.
- *
- * @group Errors
- */
-export class RebaseClientError extends RebaseApiError {
-    constructor(message: string) {
-        super(message);
-        this.name = "RebaseClientError";
-    }
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-export * from "./errors";
-export * from "./call_context";
-export * from "./types";
-export * from "./controllers";
-export * from "./users";

package/src/types/admin_block.ts

@@ -1,209 +0,0 @@
-/**
- * The keys of a collection's admin block, as data.
- *
- * There is no *type* for the block in this package any more, and that is the point:
- * `admin` is not declared on `BaseCollectionConfig` or on any property here, so a
- * BaaS install cannot even write one. `@rebasepro/cms-types` adds the field back by
- * declaration merging, which is why installing it is what makes the admin surface
- * appear.
- *
- * The *list* still has to live here, because three runtime consumers need it and two
- * of them are core — see below.
- */
-
-/**
- * Every key that belongs inside a collection's `admin` block, as data.
- *
- * The type that describes these fields is `AdminCollectionOptions` in
- * `@rebasepro/cms-types`, and it is erased at build time — but three runtime
- * consumers need the list, and two of them are core:
- *
- * - `serializeCollections`, to drop the block from the contract
- * - the ts-morph schema editor in `@rebasepro/server`, which rewrites collection
- *   files on disk from the admin panel and has to know where each key goes. A key
- *   missing from this list gets written to the *top level* of the file, where the
- *   backend ignores it and the panel never finds it again.
- * - the `collections-admin-block` codemod
- *
- * `@rebasepro/cms-types` re-exports this and asserts it names only real option
- * keys; the count is pinned by a test there.
- *
- * @group Models
- */
-export const ADMIN_COLLECTION_KEYS = [
-    "Actions",
-    "additionalFields",
-    "alwaysApplyDefaultValues",
-    "components",
-    "customViews",
-    "defaultEntityAction",
-    "defaultFilter",
-    "defaultSelectedView",
-    "defaultSize",
-    "defaultViewMode",
-    "disableDefaultActions",
-    "display",
-    "enabledViews",
-    "entityActions",
-    "entityViews",
-    "exportable",
-    "filterPresets",
-    "fixedFilter",
-    "form",
-    "formAutoSave",
-    "formView",
-    "group",
-    "hideFromEntityViews",
-    "hideFromNavigation",
-    "hideIdFromCollection",
-    "hideIdFromForm",
-    "icon",
-    "includeJsonView",
-    "inlineEditing",
-    "kanban",
-    "listProperties",
-    "localChangesBackup",
-    "openEntityMode",
-    "orderProperty",
-    "pagination",
-    "previewProperties",
-    "propertiesOrder",
-    "selectionController",
-    "selectionEnabled",
-    "sideDialogWidth",
-    "sort"
-] as const;
-
-/** A key of a collection's `admin` block. @group Models */
-export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
-
-/**
- * Every key that belongs inside a *property's* `admin` block, as data.
- *
- * The union of `AdminPropertyOptions` and its per-type extensions
- * (`AdminStringOptions`, `AdminArrayOptions`, …) in `@rebasepro/cms-types`.
- * It lives here for the same reason {@link ADMIN_COLLECTION_KEYS} does: the
- * runtime consumers are core packages that the BaaS guard forbids from
- * importing `@rebasepro/cms-types`. Here it is the boot-time collection
- * validator in `@rebasepro/server`, which has to tell "you left `readOnly` at
- * the top of the property, where nothing reads it" apart from "you invented a
- * key we have never heard of".
- *
- * `@rebasepro/cms-types` re-exports this and asserts it names only real
- * option keys.
- *
- * @group Models
- */
-export const ADMIN_PROPERTY_KEYS = [
-    "canAddElements",
-    "clearable",
-    "columnWidth",
-    "customProps",
-    "disabled",
-    "expanded",
-    "Field",
-    "Filter",
-    "filterOperators",
-    "fixedFilter",
-    "hideFromCollection",
-    "includeEntityLink",
-    "includeId",
-    "markdown",
-    "minimalistView",
-    "multiline",
-    "Preview",
-    "previewAsTag",
-    "previewProperties",
-    "readOnly",
-    "sortable",
-    "span",
-    "spreadChildren",
-    "urlPreview",
-    "widget",
-] as const;
-
-/** A key of a property's `admin` block. @group Models */
-export type AdminPropertyKey = typeof ADMIN_PROPERTY_KEYS[number];
-
-/**
- * Move flattened admin keys back down into the `admin` block.
- *
- * The admin panel works with a *flat* view model — the block merged onto the
- * collection — so what comes back from a form has `icon` and `defaultViewMode`
- * at the top level while `admin` still holds whatever the file was loaded with.
- * This is the way back.
- *
- * **The top-level value wins.** It is the one the form just wrote; the block is
- * the copy the collection was loaded with, and preferring it resolves every edit
- * in favour of the value the user changed away from.
- *
- * This lives here, next to the key lists, because it had two implementations —
- * `toAdminCollectionConfig` in `@rebasepro/cms-types` and `nestAdminKeys` in
- * `@rebasepro/server`'s schema editor — that agreed on everything except that
- * precedence, which is the only part that decides whether a save is visible.
- *
- * @group Models
- */
-export function nestAdminKeysOf(
-    source: Record<string, unknown>,
-    adminKeys: readonly string[]
-): Record<string, unknown> {
-    const keys = new Set<string>(adminKeys);
-    const top: Record<string, unknown> = {};
-    const block: Record<string, unknown> = { ...((source.admin as Record<string, unknown> | undefined) ?? {}) };
-
-    for (const [key, value] of Object.entries(source)) {
-        if (key === "admin") continue;
-        if (keys.has(key)) block[key] = value;
-        else top[key] = value;
-    }
-
-    if (Object.keys(block).length > 0) top.admin = block;
-    return top;
-}
-
-/**
- * {@link nestAdminKeysOf} for a collection.
- *
- * @group Models
- */
-export function nestAdminCollectionKeys(collection: Record<string, unknown>): Record<string, unknown> {
-    return nestAdminKeysOf(collection, ADMIN_COLLECTION_KEYS);
-}
-
-/**
- * {@link nestAdminKeysOf} for a property, applied to its children too.
- *
- * A map property carries `properties`, an array property carries `of`, and both
- * hold properties with `admin` blocks of their own. A flat `readOnly` left on a
- * child is as dead — and as fatal at the next boot — as one left on the parent,
- * so the walk goes all the way down.
- *
- * @group Models
- */
-export function nestAdminPropertyKeys(property: Record<string, unknown>): Record<string, unknown> {
-    const nested = nestAdminKeysOf(property, ADMIN_PROPERTY_KEYS);
-
-    const children = nested.properties;
-    if (children && typeof children === "object" && !Array.isArray(children)) {
-        nested.properties = Object.fromEntries(
-            Object.entries(children as Record<string, unknown>).map(([key, child]) => [
-                key,
-                child && typeof child === "object" && !Array.isArray(child)
-                    ? nestAdminPropertyKeys(child as Record<string, unknown>)
-                    : child
-            ])
-        );
-    }
-
-    const of = nested.of;
-    if (Array.isArray(of)) {
-        nested.of = of.map(entry => entry && typeof entry === "object" && !Array.isArray(entry)
-            ? nestAdminPropertyKeys(entry as Record<string, unknown>)
-            : entry);
-    } else if (of && typeof of === "object") {
-        nested.of = nestAdminPropertyKeys(of as Record<string, unknown>);
-    }
-
-    return nested;
-}

package/src/types/api_keys.ts

@@ -1,108 +0,0 @@
-/**
- * Service API keys — machine-to-machine authentication for scripts, cron jobs
- * and third-party integrations.
- *
- * The wire contract lives here because all three sides need it and used to
- * declare it separately: `@rebasepro/server` implements the routes,
- * `@rebasepro/client` calls them, and {@link ApiKeysAPI} types the SDK surface.
- * The client's copy had already drifted — it never gained `admin`.
- *
- * The database row itself (`ApiKey`, which carries `key_hash`) stays in the
- * server package: nothing off the server may see it.
- */
-
-/**
- * A single permission entry scoping an API key to a collection and set of
- * operations.
- *
- * Use `"*"` as the collection value to grant access to all collections (and all
- * custom functions). Custom functions are addressed with the `functions`
- * namespace: `"functions"` grants every function, `"functions/<name>"` grants a
- * single one.
- *
- * @group Models
- */
-export interface ApiKeyPermission {
-    /** Collection slug, `"functions"`/`"functions/<name>"`, or `"*"` for everything. */
-    collection: string;
-    /** Allowed operations on the collection. */
-    operations: ("read" | "write" | "delete")[];
-}
-
-/**
- * An API key with the secret portion masked — what list / get / update return.
- * @group Models
- */
-export interface ApiKeyMasked {
-    id: string;
-    name: string;
-    /** First 12 characters of the plaintext key, for display only. */
-    key_prefix: string;
-    permissions: ApiKeyPermission[];
-    /**
-     * When true, the key is granted the `admin` role: it passes the admin-gated
-     * routes (users, roles, cron, backups, logs, API keys) and the RLS
-     * `default_admin` policies. Non-admin keys carry only the `service` role —
-     * RLS grants them nothing unless a collection policy names that role.
-     */
-    admin: boolean;
-    /**
-     * Requests per 15-minute window. `null` means "no per-key override" — the
-     * data rate limiter then applies its default API-key limit (1000/window
-     * unless configured otherwise), not unlimited.
-     */
-    rate_limit: number | null;
-    created_by: string;
-    created_at: string;
-    updated_at: string;
-    last_used_at: string | null;
-    expires_at: string | null;
-    revoked_at: string | null;
-}
-
-/**
- * Returned exactly once, when a key is created. The `key` field holds the full
- * plaintext key — it is never stored or returned again.
- * @group Models
- */
-export interface ApiKeyWithSecret extends ApiKeyMasked {
-    /** Full plaintext API key (e.g. `rk_live_abc123...`). */
-    key: string;
-}
-
-/**
- * Payload for creating a new API key.
- * @group Models
- */
-export interface CreateApiKeyRequest {
-    name: string;
-    permissions: ApiKeyPermission[];
-    /** When true, grants the `admin` role. See {@link ApiKeyMasked.admin}. */
-    admin?: boolean;
-    /** Requests per 15-minute window. Omit or `null` for the server default. */
-    rate_limit?: number | null;
-    /** ISO-8601 expiration timestamp. Omit for no expiration. */
-    expires_at?: string | null;
-}
-
-/**
- * Payload for updating an existing API key. Only the fields provided change.
- * @group Models
- */
-export interface UpdateApiKeyRequest {
-    name?: string;
-    permissions?: ApiKeyPermission[];
-    /** When true, grants the `admin` role. See {@link ApiKeyMasked.admin}. */
-    admin?: boolean;
-    rate_limit?: number | null;
-    expires_at?: string | null;
-}
-
-/** @group Models */
-export interface ApiKeysAPI {
-    listKeys(): Promise<{ keys: ApiKeyMasked[] }>;
-    getKey(id: string): Promise<{ key: ApiKeyMasked }>;
-    createKey(data: CreateApiKeyRequest): Promise<{ key: ApiKeyWithSecret }>;
-    updateKey(id: string, data: UpdateApiKeyRequest): Promise<{ key: ApiKeyMasked }>;
-    revokeKey(id: string): Promise<{ success: boolean }>;
-}