@realiizlabs/admin 0.11.2 → 0.13.0

package/dist/studio/index.d.cts

@@ -0,0 +1,325 @@
+import { a as IdentityUser, f as SiteRole, C as CookieStore, d as SiteMember, I as IdentityClient, c as SiteBranding } from '../members-nhbRSYyr.cjs';
+import { a as PullRequestStatus } from '../types-BP5G1myE.cjs';
+import { C as ContentTypeEntry } from '../types-D46UjOfv.cjs';
+import * as zod from 'zod';
+import * as zod_v4_core from 'zod/v4/core';
+import { R as RequireOptions } from '../roles-BjWuj2_v.cjs';
+import '@supabase/supabase-js';
+
+/**
+ * Server-side checks on the pictures a save carries. Pure.
+ *
+ * The browser already shrank them, but anyone can POST to a server action, so
+ * the path, type and size are re-checked before anything is committed: only
+ * WebP under the type's public folder, ≤ 800 KB each, ≤ 3.5 MB per save.
+ * Frontmatter paths are URL paths (/blog/x.webp); the repo file lives under public/.
+ */
+interface ImagePayload {
+    /** URL path as written in the frontmatter or body, e.g. /blog/my-post.webp. */
+    path: string;
+    /** Base64 of the WebP bytes. */
+    base64: string;
+}
+interface ImageLimits {
+    maxEach: number;
+    maxTotal: number;
+    /** URL prefix pictures must live under. */
+    prefix: string;
+}
+declare const IMAGE_LIMITS: ImageLimits;
+declare const IMAGE_ERRORS: {
+    readonly path: "That image path isn’t allowed.";
+    readonly size: "That picture is too large to send — try a smaller one.";
+};
+type ValidatedImages = {
+    ok: true;
+    files: {
+        path: string;
+        content: string;
+        encoding: "base64";
+    }[];
+} | {
+    ok: false;
+    error: string;
+};
+/** Bytes a base64 string decodes to, without decoding it. */
+declare function decodedSize(b64: string): number;
+declare function validateImages(images: ImagePayload[], limits?: ImageLimits): ValidatedImages;
+
+/**
+ * The contract between a site and its Studio. Everything a site knows and the
+ * package cannot — env values, cookies, the request's origin, its registry —
+ * arrives here, lazily, so `next build` with no env set still succeeds.
+ */
+
+interface RepoConfig {
+    owner: string;
+    repo: string;
+    token: string;
+}
+interface IdentityConfig {
+    url: string;
+    anonKey: string;
+}
+interface ServiceConfig {
+    url: string;
+    serviceRoleKey: string;
+}
+/** Read per request, never at import time (BUILD-ENV law lives in the site's env.ts). */
+interface StudioEnv {
+    siteId: string;
+    repo: RepoConfig;
+    identity: IdentityConfig;
+    /** Optional: without it the Team tab explains that invites aren't set up. */
+    service: ServiceConfig | null;
+}
+interface StudioConfig {
+    /** The site's registry, keyed by type id. */
+    contentTypes: Record<string, ContentTypeEntry>;
+    /** Public page for an item, per type; a type with no page returns null. */
+    publicUrls?: Record<string, (slug: string) => string | null>;
+    /** Called per request. Throw a clear message when something is missing. */
+    env: () => StudioEnv;
+    /** True when every variable is present — the layout shows a setup page otherwise. */
+    isConfigured: () => boolean;
+    /** This request's cookie store (next/headers `cookies()` in a site). */
+    cookies: () => Promise<CookieStore>;
+    /** proto://host of this request — where auth links come back to. */
+    baseUrl: () => Promise<string>;
+    /** Next's revalidatePath, passed in so the package never imports next/cache. */
+    revalidate?: (path: string, type?: "layout" | "page") => void;
+    /** Shown in Studio's own copy ("Ask Realiiz" → "Ask {supportName}"). */
+    supportName?: string;
+    siteName: string;
+    /** IANA zone used when an event names none. */
+    timezone?: string;
+}
+type ActionResult = {
+    ok: true;
+    message?: string;
+} | {
+    ok: false;
+    error: string;
+};
+interface Session {
+    user: IdentityUser;
+    role: SiteRole;
+}
+
+interface Located {
+    typeId: string;
+    slug: string;
+    entry: ContentTypeEntry;
+}
+
+/**
+ * The dashboard's own in-flight changes: open PRs on `admin/*` branches, keyed
+ * by the file they change. The branch name — `admin/{typeId}/{fileBase}-{stamp}`
+ * — is the index, so no extra call per PR is needed. One open change per file;
+ * if two ever exist the newest wins here and the older is left alone on GitHub.
+ */
+
+type PendingState = "checking" | "ready" | "failed";
+interface PendingChange {
+    number: number;
+    branch: string;
+    title: string;
+    html_url: string;
+    path: string;
+    typeId: string;
+    state: PendingState;
+    failingCheck: string | null;
+    /** The change removes the item rather than editing it. */
+    removal: boolean;
+}
+declare const pendingLabel: Record<PendingState, string>;
+declare function pendingText(p: PendingChange): string;
+
+interface ListItem {
+    slug: string;
+    path: string;
+    title: string;
+    /** publishedAt, falling back to date — ISO string, or null when the file has neither. */
+    date: string | null;
+    /** True when the frontmatter did not parse cleanly — still listed, still openable. */
+    needsAttention: boolean;
+    pending: PendingChange | null;
+    /** The file exists only in a pending change — nothing on the live site yet. */
+    isNew: boolean;
+}
+interface PrSummary {
+    number: number;
+    title: string;
+    html_url: string;
+    merged: boolean;
+    state: "open" | "closed";
+    /** Parsed from the PR body the publish action wrote, when present. */
+    postPath: string | null;
+    branch: string;
+    removal: boolean;
+    /** The commit that landed on main when this was published; null until then. */
+    mergeCommitSha: string | null;
+}
+/** Thrown when no file in the folder maps to the slug — the page turns it into a 404. */
+declare class NotHere extends Error {
+    constructor(slug: string);
+}
+
+/**
+ * Publish and remove: validated submission → one commit on a new branch → PR.
+ * The branch is cut from `main` as it is at this moment and named with a stamp
+ * so two edits of one file never collide. Nothing goes to main directly (PR Law).
+ */
+
+interface PublishInput {
+    type: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+    /** An open change for this file: save onto ITS branch so the same PR picks up the edit. */
+    existing?: {
+        number: number;
+        branch: string;
+    } | null;
+    /** Pictures chosen in this session, already shrunk in the browser; committed with the MDX. */
+    images?: ImagePayload[];
+}
+type PublishResult = {
+    ok: false;
+    error: string;
+};
+
+/** The Publish button (merge when green, never otherwise) and Discard (close + delete branch). */
+
+type MergeOutcome = {
+    state: "merged";
+    sha: string;
+} | {
+    state: "pending";
+} | {
+    state: "stale";
+} | {
+    state: "red";
+    failingCheck: string | null;
+} | {
+    state: "error";
+    message: string;
+};
+type DiscardOutcome = {
+    state: "discarded";
+} | {
+    state: "already-published";
+} | {
+    state: "error";
+    message: string;
+};
+
+/**
+ * Team actions. Reading the roster uses the signed-in user's client (the
+ * site_members() function refuses non-owners). Writes need the service role,
+ * which the auth helpers use ONLY after re-checking the actor's role in code.
+ */
+
+type TeamState = {
+    ok: true;
+    members: SiteMember[];
+    canInvite: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+
+declare function createStudio(config: StudioConfig): {
+    config: StudioConfig;
+    isConfigured: () => boolean;
+    entry: (typeId: string) => ContentTypeEntry | null;
+    entries: ContentTypeEntry<zod.ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>>>[];
+    requireAdmin: (opts?: RequireOptions) => Promise<Session>;
+    identityClient: () => Promise<IdentityClient>;
+    readers: {
+        locate: (path: string) => Located | null;
+        publicUrlFor: (typeId: string, slug: string) => string | null;
+        publicDirFor: (typeId: string) => string;
+        listPendingChanges: () => Promise<Map<string, PendingChange>>;
+        pendingFor: (path: string) => Promise<PendingChange | null>;
+        pathOf: (typeId: string, slug: string) => Promise<string | null>;
+        listItems: (typeId: string) => Promise<ListItem[]>;
+        countItems: (typeId: string) => Promise<number>;
+        readItem: (typeId: string, slug: string, opts?: {
+            ref?: string;
+        }) => Promise<{
+            frontmatter: Record<string, unknown>;
+            body: string;
+            sha: string;
+            path: string;
+        }>;
+        lastAuthor: (typeId: string) => Promise<string | null>;
+        getPullRequest: (number: number) => Promise<PrSummary | null>;
+        prStatus: (number: number) => Promise<PullRequestStatus>;
+    };
+    actions: {
+        loadTeam: () => Promise<TeamState>;
+        invite: (input: {
+            email: string;
+            role: "owner" | "editor";
+        }) => Promise<ActionResult>;
+        changeRole: (input: {
+            userId: string;
+            role: "owner" | "editor";
+        }) => Promise<ActionResult>;
+        resend: (input: {
+            email: string;
+        }) => Promise<ActionResult>;
+        remove: (input: {
+            userId: string;
+        }) => Promise<ActionResult>;
+        saveProfile: (input: {
+            name: string;
+            displayName: string;
+        }) => Promise<ActionResult>;
+        saveAvatar: (input: {
+            base64: string;
+        } | null) => Promise<ActionResult>;
+        changePassword: (input: {
+            password: string;
+            confirm: string;
+        }) => Promise<ActionResult>;
+        loadBranding: () => Promise<SiteBranding | null>;
+        saveBranding: (input: {
+            name: string;
+            businessEmail: string;
+            businessPhone: string;
+        }) => Promise<ActionResult>;
+        saveBrandingPicture: (input: {
+            kind: "logo" | "favicon";
+            base64: string | null;
+        }) => Promise<ActionResult>;
+        loadMe: () => Promise<{
+            name: string | null;
+            displayName: string | null;
+            avatarUrl: string | null;
+            email: string;
+            role: SiteRole;
+        }>;
+        previewBody: (markdown: string) => Promise<{
+            html: string;
+        } | {
+            error: string;
+        }>;
+        mergeContentPr: (number: number) => Promise<MergeOutcome>;
+        discardChange: (number: number, branch: string) => Promise<DiscardOutcome>;
+        publishContent: (input: PublishInput) => Promise<PublishResult | never>;
+        removeContent: (input: {
+            type: string;
+            slug: string;
+        }) => Promise<PublishResult | never>;
+    };
+    authHandlers: {
+        callback: (request: Request) => Promise<Response>;
+        signout: (request: Request) => Promise<Response>;
+    };
+};
+type Studio = ReturnType<typeof createStudio>;
+type StudioActions = Studio["actions"];
+type StudioReaders = Studio["readers"];
+
+export { type ActionResult, type DiscardOutcome, IMAGE_ERRORS, IMAGE_LIMITS, type IdentityConfig, type ImageLimits, type ImagePayload, type ListItem, type Located, type MergeOutcome, NotHere, type PendingChange, type PendingState, type PrSummary, type PublishInput, type PublishResult, type RepoConfig, type ServiceConfig, type Session, type Studio, type StudioActions, type StudioConfig, type StudioEnv, type StudioReaders, type TeamState, type ValidatedImages, createStudio, decodedSize, pendingLabel, pendingText, validateImages };

package/dist/studio/index.d.ts

@@ -0,0 +1,325 @@
+import { a as IdentityUser, f as SiteRole, C as CookieStore, d as SiteMember, I as IdentityClient, c as SiteBranding } from '../members-nhbRSYyr.js';
+import { a as PullRequestStatus } from '../types-BP5G1myE.js';
+import { C as ContentTypeEntry } from '../types-D46UjOfv.js';
+import * as zod from 'zod';
+import * as zod_v4_core from 'zod/v4/core';
+import { R as RequireOptions } from '../roles-Dnwj-DAm.js';
+import '@supabase/supabase-js';
+
+/**
+ * Server-side checks on the pictures a save carries. Pure.
+ *
+ * The browser already shrank them, but anyone can POST to a server action, so
+ * the path, type and size are re-checked before anything is committed: only
+ * WebP under the type's public folder, ≤ 800 KB each, ≤ 3.5 MB per save.
+ * Frontmatter paths are URL paths (/blog/x.webp); the repo file lives under public/.
+ */
+interface ImagePayload {
+    /** URL path as written in the frontmatter or body, e.g. /blog/my-post.webp. */
+    path: string;
+    /** Base64 of the WebP bytes. */
+    base64: string;
+}
+interface ImageLimits {
+    maxEach: number;
+    maxTotal: number;
+    /** URL prefix pictures must live under. */
+    prefix: string;
+}
+declare const IMAGE_LIMITS: ImageLimits;
+declare const IMAGE_ERRORS: {
+    readonly path: "That image path isn’t allowed.";
+    readonly size: "That picture is too large to send — try a smaller one.";
+};
+type ValidatedImages = {
+    ok: true;
+    files: {
+        path: string;
+        content: string;
+        encoding: "base64";
+    }[];
+} | {
+    ok: false;
+    error: string;
+};
+/** Bytes a base64 string decodes to, without decoding it. */
+declare function decodedSize(b64: string): number;
+declare function validateImages(images: ImagePayload[], limits?: ImageLimits): ValidatedImages;
+
+/**
+ * The contract between a site and its Studio. Everything a site knows and the
+ * package cannot — env values, cookies, the request's origin, its registry —
+ * arrives here, lazily, so `next build` with no env set still succeeds.
+ */
+
+interface RepoConfig {
+    owner: string;
+    repo: string;
+    token: string;
+}
+interface IdentityConfig {
+    url: string;
+    anonKey: string;
+}
+interface ServiceConfig {
+    url: string;
+    serviceRoleKey: string;
+}
+/** Read per request, never at import time (BUILD-ENV law lives in the site's env.ts). */
+interface StudioEnv {
+    siteId: string;
+    repo: RepoConfig;
+    identity: IdentityConfig;
+    /** Optional: without it the Team tab explains that invites aren't set up. */
+    service: ServiceConfig | null;
+}
+interface StudioConfig {
+    /** The site's registry, keyed by type id. */
+    contentTypes: Record<string, ContentTypeEntry>;
+    /** Public page for an item, per type; a type with no page returns null. */
+    publicUrls?: Record<string, (slug: string) => string | null>;
+    /** Called per request. Throw a clear message when something is missing. */
+    env: () => StudioEnv;
+    /** True when every variable is present — the layout shows a setup page otherwise. */
+    isConfigured: () => boolean;
+    /** This request's cookie store (next/headers `cookies()` in a site). */
+    cookies: () => Promise<CookieStore>;
+    /** proto://host of this request — where auth links come back to. */
+    baseUrl: () => Promise<string>;
+    /** Next's revalidatePath, passed in so the package never imports next/cache. */
+    revalidate?: (path: string, type?: "layout" | "page") => void;
+    /** Shown in Studio's own copy ("Ask Realiiz" → "Ask {supportName}"). */
+    supportName?: string;
+    siteName: string;
+    /** IANA zone used when an event names none. */
+    timezone?: string;
+}
+type ActionResult = {
+    ok: true;
+    message?: string;
+} | {
+    ok: false;
+    error: string;
+};
+interface Session {
+    user: IdentityUser;
+    role: SiteRole;
+}
+
+interface Located {
+    typeId: string;
+    slug: string;
+    entry: ContentTypeEntry;
+}
+
+/**
+ * The dashboard's own in-flight changes: open PRs on `admin/*` branches, keyed
+ * by the file they change. The branch name — `admin/{typeId}/{fileBase}-{stamp}`
+ * — is the index, so no extra call per PR is needed. One open change per file;
+ * if two ever exist the newest wins here and the older is left alone on GitHub.
+ */
+
+type PendingState = "checking" | "ready" | "failed";
+interface PendingChange {
+    number: number;
+    branch: string;
+    title: string;
+    html_url: string;
+    path: string;
+    typeId: string;
+    state: PendingState;
+    failingCheck: string | null;
+    /** The change removes the item rather than editing it. */
+    removal: boolean;
+}
+declare const pendingLabel: Record<PendingState, string>;
+declare function pendingText(p: PendingChange): string;
+
+interface ListItem {
+    slug: string;
+    path: string;
+    title: string;
+    /** publishedAt, falling back to date — ISO string, or null when the file has neither. */
+    date: string | null;
+    /** True when the frontmatter did not parse cleanly — still listed, still openable. */
+    needsAttention: boolean;
+    pending: PendingChange | null;
+    /** The file exists only in a pending change — nothing on the live site yet. */
+    isNew: boolean;
+}
+interface PrSummary {
+    number: number;
+    title: string;
+    html_url: string;
+    merged: boolean;
+    state: "open" | "closed";
+    /** Parsed from the PR body the publish action wrote, when present. */
+    postPath: string | null;
+    branch: string;
+    removal: boolean;
+    /** The commit that landed on main when this was published; null until then. */
+    mergeCommitSha: string | null;
+}
+/** Thrown when no file in the folder maps to the slug — the page turns it into a 404. */
+declare class NotHere extends Error {
+    constructor(slug: string);
+}
+
+/**
+ * Publish and remove: validated submission → one commit on a new branch → PR.
+ * The branch is cut from `main` as it is at this moment and named with a stamp
+ * so two edits of one file never collide. Nothing goes to main directly (PR Law).
+ */
+
+interface PublishInput {
+    type: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+    /** An open change for this file: save onto ITS branch so the same PR picks up the edit. */
+    existing?: {
+        number: number;
+        branch: string;
+    } | null;
+    /** Pictures chosen in this session, already shrunk in the browser; committed with the MDX. */
+    images?: ImagePayload[];
+}
+type PublishResult = {
+    ok: false;
+    error: string;
+};
+
+/** The Publish button (merge when green, never otherwise) and Discard (close + delete branch). */
+
+type MergeOutcome = {
+    state: "merged";
+    sha: string;
+} | {
+    state: "pending";
+} | {
+    state: "stale";
+} | {
+    state: "red";
+    failingCheck: string | null;
+} | {
+    state: "error";
+    message: string;
+};
+type DiscardOutcome = {
+    state: "discarded";
+} | {
+    state: "already-published";
+} | {
+    state: "error";
+    message: string;
+};
+
+/**
+ * Team actions. Reading the roster uses the signed-in user's client (the
+ * site_members() function refuses non-owners). Writes need the service role,
+ * which the auth helpers use ONLY after re-checking the actor's role in code.
+ */
+
+type TeamState = {
+    ok: true;
+    members: SiteMember[];
+    canInvite: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+
+declare function createStudio(config: StudioConfig): {
+    config: StudioConfig;
+    isConfigured: () => boolean;
+    entry: (typeId: string) => ContentTypeEntry | null;
+    entries: ContentTypeEntry<zod.ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>>>[];
+    requireAdmin: (opts?: RequireOptions) => Promise<Session>;
+    identityClient: () => Promise<IdentityClient>;
+    readers: {
+        locate: (path: string) => Located | null;
+        publicUrlFor: (typeId: string, slug: string) => string | null;
+        publicDirFor: (typeId: string) => string;
+        listPendingChanges: () => Promise<Map<string, PendingChange>>;
+        pendingFor: (path: string) => Promise<PendingChange | null>;
+        pathOf: (typeId: string, slug: string) => Promise<string | null>;
+        listItems: (typeId: string) => Promise<ListItem[]>;
+        countItems: (typeId: string) => Promise<number>;
+        readItem: (typeId: string, slug: string, opts?: {
+            ref?: string;
+        }) => Promise<{
+            frontmatter: Record<string, unknown>;
+            body: string;
+            sha: string;
+            path: string;
+        }>;
+        lastAuthor: (typeId: string) => Promise<string | null>;
+        getPullRequest: (number: number) => Promise<PrSummary | null>;
+        prStatus: (number: number) => Promise<PullRequestStatus>;
+    };
+    actions: {
+        loadTeam: () => Promise<TeamState>;
+        invite: (input: {
+            email: string;
+            role: "owner" | "editor";
+        }) => Promise<ActionResult>;
+        changeRole: (input: {
+            userId: string;
+            role: "owner" | "editor";
+        }) => Promise<ActionResult>;
+        resend: (input: {
+            email: string;
+        }) => Promise<ActionResult>;
+        remove: (input: {
+            userId: string;
+        }) => Promise<ActionResult>;
+        saveProfile: (input: {
+            name: string;
+            displayName: string;
+        }) => Promise<ActionResult>;
+        saveAvatar: (input: {
+            base64: string;
+        } | null) => Promise<ActionResult>;
+        changePassword: (input: {
+            password: string;
+            confirm: string;
+        }) => Promise<ActionResult>;
+        loadBranding: () => Promise<SiteBranding | null>;
+        saveBranding: (input: {
+            name: string;
+            businessEmail: string;
+            businessPhone: string;
+        }) => Promise<ActionResult>;
+        saveBrandingPicture: (input: {
+            kind: "logo" | "favicon";
+            base64: string | null;
+        }) => Promise<ActionResult>;
+        loadMe: () => Promise<{
+            name: string | null;
+            displayName: string | null;
+            avatarUrl: string | null;
+            email: string;
+            role: SiteRole;
+        }>;
+        previewBody: (markdown: string) => Promise<{
+            html: string;
+        } | {
+            error: string;
+        }>;
+        mergeContentPr: (number: number) => Promise<MergeOutcome>;
+        discardChange: (number: number, branch: string) => Promise<DiscardOutcome>;
+        publishContent: (input: PublishInput) => Promise<PublishResult | never>;
+        removeContent: (input: {
+            type: string;
+            slug: string;
+        }) => Promise<PublishResult | never>;
+    };
+    authHandlers: {
+        callback: (request: Request) => Promise<Response>;
+        signout: (request: Request) => Promise<Response>;
+    };
+};
+type Studio = ReturnType<typeof createStudio>;
+type StudioActions = Studio["actions"];
+type StudioReaders = Studio["readers"];
+
+export { type ActionResult, type DiscardOutcome, IMAGE_ERRORS, IMAGE_LIMITS, type IdentityConfig, type ImageLimits, type ImagePayload, type ListItem, type Located, type MergeOutcome, NotHere, type PendingChange, type PendingState, type PrSummary, type PublishInput, type PublishResult, type RepoConfig, type ServiceConfig, type Session, type Studio, type StudioActions, type StudioConfig, type StudioEnv, type StudioReaders, type TeamState, type ValidatedImages, createStudio, decodedSize, pendingLabel, pendingText, validateImages };