@nonext/husk 0.2.3

package/dist/cms-9fSA3uQV.d.ts

@@ -0,0 +1,158 @@
+import { b as ContentTypeKind, A as AnyContentTypeShape, f as Entry } from './entry-D3kiE8T1.js';
+import { M as MediaItem } from './field-Diyf5siF.js';
+import { C as CmsAdapter, L as ListQuery, P as Page } from './adapter-C_0mhENy.js';
+
+/** The minimum a kind guard needs to know about a content type. */
+interface KindShape {
+    slug: string;
+    kind: ContentTypeKind;
+}
+declare function isCollection(type: KindShape): boolean;
+declare function isSingleton(type: KindShape): boolean;
+/**
+ * The one document id a singleton is allowed to use.
+ *
+ * Derived from the slug rather than generated, so "exactly one entry" is a property of the
+ * path itself: a second create targets the same document and is a write conflict rather
+ * than a second entry. See .docs/decisions/2026-09-18-firestore-layout.md.
+ */
+declare function singletonEntryId(slug: string): string;
+/**
+ * Guards a create against a singleton.
+ *
+ * `exists` is what the adapter read a moment ago. The path-derived id makes the race
+ * harmless: two concurrent creates address the same document, so the second is an
+ * overwrite of the first rather than a duplicate entry.
+ */
+declare function assertSingletonCreatable(type: KindShape, exists: boolean): void;
+/** Guards an addressed write or read against a singleton. */
+declare function assertSingletonEntryId(type: KindShape, entryId: string): void;
+/** Guards list-shaped operations, which a singleton does not have. */
+declare function assertListable(type: KindShape): void;
+/** Guards deletion, which would leave a singleton in a state the schema does not describe. */
+declare function assertDeletable(type: KindShape): void;
+
+/**
+ * The public read SDK. The surface a customer project programs against.
+ *
+ * Everything here goes through `CmsAdapter`, which is the whole point: the concept document
+ * says the SDK will probably outlive the admin, and that a change to the internal Firestore
+ * layout should cost a rewrite of the adapter rather than a rewrite of every customer
+ * project. Nothing in this file names a collection, a document id, or a field path in
+ * storage, so there is no layout knowledge here to invalidate.
+ *
+ * It is read-only on purpose. Writing is the admin's job, and it goes through the adapter
+ * with a signed-in user, permission checks, and validation. Adding a `create` here would
+ * mean a second write path with none of that.
+ */
+/**
+ * The code-defined content types an instance knows at compile time, keyed by slug.
+ *
+ * Keyed rather than a list, because that is what makes `cms.collection("projects")` return
+ * a typed entry. `ContentType<TFields>` declares `slug: string`, not the literal, so a list
+ * of content types offers the type system nothing to index by. The key is the index.
+ *
+ * The key must equal the type's own `slug`; `createCMS` rejects a map where it does not,
+ * because a mismatch would type one content type and read another.
+ */
+type ContentTypeMap = {
+    readonly [slug: string]: KindShape & AnyContentTypeShape;
+};
+/** The slugs a map declares. */
+type KnownSlug<TTypes extends ContentTypeMap> = keyof TTypes & string;
+/**
+ * A known slug, or any other string.
+ *
+ * Both halves are required. The known slugs are what an editor offers and what carries the
+ * inference; the open half is what keeps a database-defined content type readable, since
+ * one created in the Schema Builder has no compile-time existence at all.
+ */
+type SlugOf<TTypes extends ContentTypeMap> = KnownSlug<TTypes> | (string & Record<never, never>);
+/**
+ * What one slug reads as.
+ *
+ * A declared slug resolves to its inferred entry, so `project.title` is `string`. Anything
+ * else resolves to the erased `Entry`, whose field values are the union of every field
+ * type's value, nullable. That is deliberately not a lie: a database-defined type has no
+ * shape at compile time, so the honest type is "some field value or null", and a consumer
+ * has to narrow before using it. Typing it as `any`, or pretending it has the fields of
+ * some other type, would make the compiler agree to code that cannot work.
+ */
+type EntryOf<TTypes extends ContentTypeMap, TSlug extends string> = TSlug extends keyof TTypes ? Entry<TTypes[TSlug]> : Entry;
+/**
+ * What a public read may narrow by.
+ *
+ * `ListQuery.status` is removed rather than defaulted. A caller on a customer's website
+ * cannot ask for drafts at all, which means a leak cannot come from a forwarded query
+ * object, a URL parameter that ends up in a filter, or a copied snippet. Status is decided
+ * once, by whether the instance is a preview instance.
+ */
+type CmsQuery = Omit<ListQuery, "status">;
+/** The narrowing a count understands. The rest of a query does not change a total. */
+type CmsCountQuery = Pick<CmsQuery, "filters" | "search">;
+interface CollectionReader<TEntry = Entry> {
+    /** One page of entries. Pass `page.cursor` back as `query.cursor` for the next one. */
+    findMany(query?: CmsQuery): Promise<Page<TEntry>>;
+    /** By the value of the content type's slug field, which is what a URL segment carries. */
+    findBySlug(value: string): Promise<TEntry | null>;
+    /** By entry id. */
+    findById(entryId: string): Promise<TEntry | null>;
+    /** How many entries the same narrowing would return. */
+    count(query?: CmsCountQuery): Promise<number>;
+}
+interface SingleReader<TEntry = Entry> {
+    /** The one entry of a singleton. Null when it has never been saved. */
+    get(): Promise<TEntry | null>;
+}
+interface MediaReader {
+    getById(mediaId: string): Promise<MediaItem | null>;
+    /** Missing ids are omitted rather than returned as holes, so the result may be shorter. */
+    getMany(mediaIds: readonly string[]): Promise<readonly MediaItem[]>;
+}
+interface SettingsReader {
+    /** A settings document by key, or null when it has never been written. */
+    get(key: string): Promise<Record<string, unknown> | null>;
+}
+interface Cms<TTypes extends ContentTypeMap = ContentTypeMap> {
+    collection<TSlug extends SlugOf<TTypes>>(slug: TSlug): CollectionReader<EntryOf<TTypes, TSlug>>;
+    single<TSlug extends SlugOf<TTypes>>(slug: TSlug): SingleReader<EntryOf<TTypes, TSlug>>;
+    media(): MediaReader;
+    settings(): SettingsReader;
+    /** True when this instance reads unpublished entries. False on every public instance. */
+    readonly isPreview: boolean;
+}
+/**
+ * Everything an instance needs except the decision about unpublished content.
+ *
+ * Split out so the client entry can accept exactly this and nothing more: a config type
+ * with no `preview` key makes passing one a compile error rather than a review comment.
+ */
+interface CmsReadConfig<TTypes extends ContentTypeMap = ContentTypeMap> {
+    /** The storage seam. The SDK holds no other handle on data. */
+    adapter: CmsAdapter;
+    /**
+     * The code-defined content types, keyed by slug. Omitting them costs the inference and
+     * nothing else: every read still works and every entry is typed as the erased `Entry`.
+     */
+    contentTypes?: TTypes;
+}
+interface CmsConfig<TTypes extends ContentTypeMap = ContentTypeMap> extends CmsReadConfig<TTypes> {
+    /**
+     * Reads every status instead of published only.
+     *
+     * Off unless it is passed, and there is no way to turn it on after construction: a
+     * preview instance is a different object built by a different call. See
+     * `.docs/decisions/2026-09-19-cms-sdk-surface.md` for why it is not a per-call argument.
+     */
+    preview?: boolean;
+}
+/**
+ * Builds a CMS instance over an adapter.
+ *
+ * Server and client variants live in `@nonext/husk/server` and `@nonext/husk/client`; this is
+ * the shared implementation both are built from, and it is exported so a test or a custom
+ * runtime can construct one directly over a test double.
+ */
+declare function createCMS<TTypes extends ContentTypeMap = ContentTypeMap>(config: CmsConfig<TTypes>): Cms<TTypes>;
+
+export { type Cms as C, type EntryOf as E, type KnownSlug as K, type MediaReader as M, type SettingsReader as S, type CmsConfig as a, type CmsCountQuery as b, type CmsQuery as c, type CmsReadConfig as d, type CollectionReader as e, type ContentTypeMap as f, type SingleReader as g, type SlugOf as h, assertDeletable as i, assertListable as j, assertSingletonCreatable as k, assertSingletonEntryId as l, createCMS as m, isCollection as n, isSingleton as o, singletonEntryId as s };