@plume-press/cli 0.0.0-stage → 0.4.0

package/dist/schema.d.ts

@@ -0,0 +1,230 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type RecordData = {
+    [key: string]: JsonValue;
+};
+type FieldBase = {
+    name: string;
+    label: string;
+    required?: boolean;
+    locked?: boolean;
+    /** Authoring default for new Items; must validate as the Field's value. */
+    default?: JsonValue;
+};
+export type ScalarField = FieldBase & ({
+    kind: "richText" | "number" | "boolean" | "link";
+}
+/** `multiline` is a form hint only; `maxLength` counts characters. */
+ | {
+    kind: "text";
+    multiline?: boolean;
+    maxLength?: number;
+}
+/** `time: true` stores UTC timestamps, `false` dates only; absent allows both. */
+ | {
+    kind: "date";
+    time?: boolean;
+}
+/** `from` names a sibling text Field the CMS can generate the slug from. */
+ | {
+    kind: "slug";
+    from?: string;
+} | {
+    kind: "select";
+    options: readonly string[];
+    multiple?: boolean;
+} | {
+    kind: "reference";
+    collection: string;
+    multiple?: boolean;
+}
+/** `accept` lists MIME types (`image/png`, `image/*`) or extensions (`.pdf`). */
+ | {
+    kind: "image" | "file";
+    multiple?: boolean;
+    accept?: readonly string[];
+});
+export type Field = ScalarField | (FieldBase & {
+    kind: "list";
+    fields: readonly ScalarField[];
+});
+export type Collection = {
+    name: string;
+    label: string;
+    fields: readonly Field[];
+    /** The website page that shows an Item, e.g. `/work/{slug}`: `{id}` is the Item ID,
+     * `{<field>}` a text or slug Field's value. See `resolvePreviewPath`. */
+    previewPath?: string;
+};
+export type Singleton = {
+    name: string;
+    label: string;
+    fields: readonly Field[];
+    /** The website page that shows this Singleton; a fixed path, without placeholders. */
+    previewPath?: string;
+};
+export type SchemaDefinition = {
+    collections: readonly Collection[];
+    singletons?: readonly Singleton[];
+};
+export type MediaReference = {
+    id: string;
+    alt?: string;
+};
+/** Stored link. `newTab` applies to `url` links only. */
+export type LinkValue = {
+    kind: "url" | "email" | "phone";
+    value: string;
+    newTab?: boolean;
+};
+export type FieldValue<F extends Field> = F extends {
+    kind: "number";
+} ? number : F extends {
+    kind: "boolean";
+} ? boolean : F extends {
+    kind: "link";
+} ? LinkValue : F extends {
+    kind: "image" | "file";
+} ? F extends {
+    multiple: true;
+} ? MediaReference[] : MediaReference : F extends {
+    kind: "select";
+    options: readonly (infer O extends string)[];
+} ? F extends {
+    multiple: true;
+} ? O[] : O : F extends {
+    kind: "reference";
+} ? F extends {
+    multiple: true;
+} ? string[] : string : F extends {
+    kind: "list";
+    fields: infer L extends readonly ScalarField[];
+} ? InferFields<L>[] : string;
+/** Stored record shape, read with optional Fields present as `null` when unset.
+ * The SDK delivers `DeliveredFields`, which projects link, image and file values. */
+export type InferFields<F extends readonly Field[]> = {
+    [P in F[number] as P extends {
+        required: true;
+    } ? P["name"] : never]: FieldValue<P>;
+} & {
+    [P in F[number] as P extends {
+        required: true;
+    } ? never : P["name"]]: FieldValue<P> | null;
+};
+export type InferCollection<S extends SchemaDefinition, N extends S["collections"][number]["name"]> = InferFields<Extract<S["collections"][number], {
+    name: N;
+}>["fields"]>;
+export type InferSingleton<S extends SchemaDefinition, N extends NonNullable<S["singletons"]>[number]["name"]> = InferFields<Extract<NonNullable<S["singletons"]>[number], {
+    name: N;
+}>["fields"]>;
+/** A delivered link: `href` is ready for `<a href>`; only `url` links open a new tab. */
+export type DeliveredLink = {
+    kind: "url" | "email" | "phone";
+    href: string;
+    newTab: boolean;
+};
+/** `width`/`height` are null for assets uploaded before dimensions were recorded
+ * or whose header could not be read. `alt` is "" when the Editor left it empty. */
+export type DeliveredImage = {
+    url: string;
+    width: number | null;
+    height: number | null;
+    alt: string;
+};
+/** `name` is the uploaded filename, `size` its byte length, `mime` its media type. */
+export type DeliveredFile = {
+    url: string;
+    name: string;
+    size: number;
+    mime: string;
+};
+/** Every delivered Item; timestamps are ISO 8601 strings. */
+export type ContentItem<T> = {
+    id: string;
+    data: T;
+    createdAt: string;
+    updatedAt: string;
+};
+export type DeliveredValue<F extends Field> = F extends {
+    kind: "link";
+} ? DeliveredLink : F extends {
+    kind: "image";
+} ? F extends {
+    multiple: true;
+} ? DeliveredImage[] : DeliveredImage : F extends {
+    kind: "file";
+} ? F extends {
+    multiple: true;
+} ? DeliveredFile[] : DeliveredFile : F extends {
+    kind: "list";
+    fields: infer L extends readonly ScalarField[];
+} ? DeliveredFields<L>[] : FieldValue<F>;
+/** Delivered record shape: optional Fields are always present, `null` when unset. */
+export type DeliveredFields<F extends readonly Field[]> = {
+    [P in F[number] as P extends {
+        required: true;
+    } ? P["name"] : never]: DeliveredValue<P>;
+} & {
+    [P in F[number] as P extends {
+        required: true;
+    } ? never : P["name"]]: DeliveredValue<P> | null;
+};
+export type DeliveredCollection<S extends SchemaDefinition, N extends S["collections"][number]["name"]> = DeliveredFields<Extract<S["collections"][number], {
+    name: N;
+}>["fields"]>;
+export type DeliveredSingleton<S extends SchemaDefinition, N extends NonNullable<S["singletons"]>[number]["name"]> = DeliveredFields<Extract<NonNullable<S["singletons"]>[number], {
+    name: N;
+}>["fields"]>;
+/** A media Field path inside one Item, e.g. `["blocks", 0, "photo"]`. */
+export type MediaPath = (string | number)[];
+export type FieldIssue = {
+    path: string;
+    code: "required" | "type" | "format" | "unknown_field" | "unknown_collection" | "invalid_json";
+    message: string;
+};
+/** Rejects lossy JSON representations, accessors and prototype-bearing objects. */
+export declare function canonicalJson(value: JsonValue): string;
+/** Schema configuration is data only. Executable validators/transforms are unsupported. */
+export declare function defineSchema<const S extends SchemaDefinition>(schema: S): S;
+/** A schema stored with content, which an older Plume accepted: checked like
+ * `defineSchema`, except that a `previewPath` this version's grammar rejects is reported
+ * to `ignored` and left inert (`resolvePreviewPath` gives it no path), so that content
+ * stays readable. Defining or registering a schema stays strict. */
+export declare function readStoredSchema(schema: unknown, ignored?: (problem: string) => void): SchemaDefinition;
+/** A path on the Site's own website: one leading `/`, no backslash, whitespace or control
+ * character, at most 2048 characters, and still a path of the same site once a URL parser
+ * normalises it (`/./`, `..`), so no browser or parser reads it as another host. */
+export declare function isLocalPath(path: unknown): path is string;
+/** The website path showing one Item or Singleton, or null when the entity has no valid
+ * `previewPath` or a placeholder has no value: Plume never guesses a route. `{id}` is the
+ * Item ID (even when a Field is named `id`), `{<field>}` that text or slug Field's value,
+ * each trimmed and URL-encoded. The result is always an `isLocalPath`. */
+export declare function resolvePreviewPath(entity: Collection | Singleton, recordId: string, data: JsonValue | undefined): string | null;
+/** Hashes a schema as stored: a `previewPath` an older Plume accepted doesn't change or
+ * block its identity (see `readStoredSchema`). */
+export declare function schemaHash(schema: SchemaDefinition): Promise<string>;
+/** Validates shape only; richText HTML requires sanitization at the write/render boundary.
+ * Slug uniqueness, reference targets and media `accept` need the whole content and are
+ * checked where it is available (save, preparation, local store). */
+export declare function validateRecord(schema: SchemaDefinition, name: string, data: unknown, options: {
+    publication: boolean;
+}): FieldIssue[];
+/** Removes `null` (unset) optional values so stored records stay canonical. */
+export declare function stripNullFields(fields: readonly Field[], data: RecordData): RecordData;
+/** Delivered shape: every unset optional Field is present as `null`, one list level deep. */
+export declare function withNullFields(fields: readonly Field[], data: RecordData): RecordData;
+/** The record IDs a reference value names, single or `multiple`. */
+export declare function referenceIds(value: JsonValue | undefined): string[];
+/** Resolves optional references to Items that no longer exist to `null` (unset):
+ * a single reference is removed, a `multiple` one loses the missing IDs. Required
+ * references are kept so the caller can refuse them. Returns null when unchanged. */
+export declare function dropMissingReferences(fields: readonly Field[], data: RecordData, exists: (collection: string, id: string) => boolean): RecordData | null;
+/** Lowercase hyphen-separated slug from free text, in the slug Field's format. */
+export declare function slugify(value: string): string;
+/** Whether a stored asset satisfies a media Field's `accept` list (absent accepts all). */
+export declare function mediaAccepted(accept: readonly string[] | undefined, asset: {
+    mediaType: string;
+    filename: string;
+}): boolean;
+export {};