@xtrable-ltd/nanoesis 0.1.0

package/dist/editor-api.d.ts

@@ -0,0 +1,198 @@
+import { WorkingStore, IdentityProvider, PublishResult, AuthEndpoints, UserAdminEndpoints, AuthorOption, UserSummary, AuthorDirectory } from '@nanoesis/engine';
+
+/**
+ * Editor white-labelling storage (DESIGN §11, Phase B). This is the *editor app's*
+ * own chrome, a custom top-left logo + name an operator sets, deliberately kept out
+ * of the engine (which only compiles a site's data to data) and out of the site's
+ * `ContentSource` (so it can never leak into the published output). It lives here, in
+ * the host, behind a narrow port so a deploy can swap the file-backed store for a
+ * blob/table one without touching the routes.
+ *
+ * The logo bytes and the name are stored separately so reading the cheap metadata
+ * (for the `GET /api/branding` poll the login screen and top bar make) doesn't pull
+ * the image down every time; the image is fetched once via `GET /api/branding/logo`.
+ */
+interface BrandingLogoMeta {
+    readonly contentType: string;
+    /** Epoch ms of the last logo write, used to cache-bust the logo URL. */
+    readonly updatedAt: number;
+}
+interface BrandingState {
+    /** Operator-set display name, or null to fall back to the built-in brand. */
+    readonly name: string | null;
+    /** Logo metadata, or null when no logo is set. */
+    readonly logo: BrandingLogoMeta | null;
+}
+interface BrandingLogo {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+}
+interface BrandingStore {
+    /** Cheap metadata read (name + whether/when a logo exists); never the image bytes. */
+    get(): Promise<BrandingState>;
+    /** The logo image, or null when none is set. */
+    getLogo(): Promise<BrandingLogo | null>;
+    /** Set (or clear, with null) the display name. */
+    setName(name: string | null): Promise<void>;
+    /** Replace the logo image. */
+    setLogo(bytes: Uint8Array, contentType: string): Promise<void>;
+    /** Remove the logo image (revert to the built-in mark). */
+    clearLogo(): Promise<void>;
+}
+/** An ephemeral in-process {@link BrandingStore}, for tests and ephemeral examples. */
+declare class InMemoryBrandingStore implements BrandingStore {
+    private readonly now;
+    private name;
+    private logo;
+    private logoUpdatedAt;
+    constructor(now?: () => number);
+    get(): Promise<BrandingState>;
+    getLogo(): Promise<BrandingLogo | null>;
+    setName(name: string | null): Promise<void>;
+    setLogo(bytes: Uint8Array, contentType: string): Promise<void>;
+    clearLogo(): Promise<void>;
+}
+/**
+ * A file-backed {@link BrandingStore} for the local example and small self-hosted
+ * deploys. Metadata is a small JSON file (`{ name, logo: { contentType, updatedAt } }`)
+ * written atomically (tmp + rename); the image is a sibling file. BOM-tolerant on read
+ * (Windows / PowerShell-5 default). Bring your own store for blob/table persistence.
+ */
+declare class FileBrandingStore implements BrandingStore {
+    private readonly metaPath;
+    private readonly now;
+    private readonly logoPath;
+    constructor(metaPath: string, now?: () => number);
+    private loadMeta;
+    private saveMeta;
+    get(): Promise<BrandingState>;
+    getLogo(): Promise<BrandingLogo | null>;
+    setName(name: string | null): Promise<void>;
+    setLogo(bytes: Uint8Array, contentType: string): Promise<void>;
+    clearLogo(): Promise<void>;
+}
+
+/**
+ * The host's content API as a pure, framework-agnostic router. It reproduces the dev
+ * server's contract (`packages/editor/dev/content-api.ts`) exactly, `/api/list`,
+ * `/read`, `/exists`, `/write`, `/delete`, `/rename`, plus `/publish`, so the editor
+ * client talks to it unchanged. Keeping it free of `@azure/functions` means it is
+ * unit-tested in memory; the Functions glue (`functions.ts`) just maps the runtime's
+ * request/response onto these types.
+ */
+interface ApiRequest {
+    readonly method: string;
+    /** URL pathname, e.g. "/api/list". */
+    readonly path: string;
+    readonly query: URLSearchParams;
+    readonly getHeader: (name: string) => string | undefined;
+    readonly body: () => Promise<Uint8Array>;
+}
+interface ApiResponse {
+    readonly status: number;
+    readonly headers?: Record<string, string>;
+    readonly body?: string | Uint8Array;
+}
+interface ApiDeps {
+    /** The editor working store (read + write/delete/rename), any {@link WorkingStore}. */
+    readonly store: WorkingStore;
+    /** Who is calling, gates every editing route (DESIGN §11). */
+    readonly identity: IdentityProvider;
+    /** Run the publish pipeline (host binds source/sink/purge). */
+    readonly publish: () => Promise<PublishResult>;
+    /**
+     * Optional credential-management surface (DESIGN §11). When present, the router
+     * mounts `/api/login`, `/api/refresh`, `/api/logout`, and `/api/auth/state`,
+     * unauthenticated routes that bypass the editor-role check. Trusted-header /
+     * gateway-style deployments leave this unset.
+     */
+    readonly authEndpoints?: AuthEndpoints;
+    /**
+     * Optional admin-only user-management surface (DESIGN §11, Phase B). When present,
+     * the router mounts `/api/users` (list/create) and `/api/users/:id` (update/delete)
+     * plus `/api/users/:id/password` (reset), all gated on the `admin` role. Omitted by
+     * trusted-header / external-IdP providers, where users are managed upstream.
+     */
+    readonly userAdmin?: UserAdminEndpoints;
+    /**
+     * Optional editor white-labelling store (DESIGN §11, Phase B). When present, the
+     * router mounts the *anonymous* reads `GET /api/branding` (`{ name, logoUrl }`) and
+     * `GET /api/branding/logo` (the image, anonymous so the login screen is branded too),
+     * plus the admin-gated writes `PUT /api/branding`, `POST`/`DELETE /api/branding/logo`.
+     * When absent, the reads return the built-in defaults and writes 404.
+     */
+    readonly branding?: BrandingStore;
+    /**
+     * Optional author directory (DESIGN §6.11). When present, the router mounts
+     * `GET /api/authors` (any editing role, bylines are public) returning the users a
+     * byline can name as `{ name, user }`, for the editor's authors picker. Absent → the
+     * route returns `[]` and the picker is guest-only. The host builds this from its user
+     * store and feeds the *same* users to the compiler's `authorDirectory` at publish.
+     */
+    readonly authors?: () => Promise<readonly AuthorOption[]>;
+}
+/** Dispatch one API request. The editor is private, so every route requires an editing
+ * role (author/developer/admin); writes are further partitioned by path (DESIGN §11). */
+declare function handleApi(deps: ApiDeps, req: ApiRequest): Promise<ApiResponse>;
+
+/** The byline picker's options, display name + stable handle, sorted by display name. */
+declare function authorOptions(users: readonly UserSummary[]): AuthorOption[];
+/**
+ * A sync directory resolving a stored `user` handle to its current display name, for the
+ * compiler's `authorDirectory`. The compiler resolves synchronously, so snapshot a fresh
+ * user list (an async `listUsers()`) into this map *before* each compile/publish.
+ */
+declare function authorDirectory(users: readonly UserSummary[]): AuthorDirectory;
+
+/** A JSON Schema (2020-12 subset) for a tool's arguments. Plain data, no SDK types. */
+interface JsonSchemaProperty {
+    readonly type: 'string';
+    readonly description?: string;
+}
+interface JsonSchemaObject {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, JsonSchemaProperty>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties: false;
+}
+/** A transport-neutral MCP tool definition the host registers with the SDK. */
+interface McpToolDef {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+}
+/** The outcome of a tool call, ready for the host to wrap in the SDK's result type. */
+interface McpToolResult {
+    readonly text: string;
+    readonly isError: boolean;
+}
+/** Per-call options. The token threads the caller's identity for HTTP transports; a
+ *  local stdio host with a pass-through identity omits it. */
+interface McpCallOptions {
+    readonly token?: string;
+}
+/** A read-only MCP resource definition (context the client can pull). */
+interface McpResourceDef {
+    readonly uri: string;
+    readonly name: string;
+    readonly description: string;
+    readonly mimeType: string;
+}
+/** The catalog of MCP tools a host registers (the executable mapping is kept internal). */
+declare const MCP_TOOLS: readonly McpToolDef[];
+/**
+ * Execute an MCP tool call by routing it through {@link handleApi}, so it is authenticated
+ * and role-gated identically to the HTTP transport. An unknown tool name is a tool error,
+ * not a thrown exception (the client surfaces it to the model).
+ */
+declare function callMcpTool(deps: ApiDeps, name: string, args?: Readonly<Record<string, unknown>>, options?: McpCallOptions): Promise<McpToolResult>;
+/** The read-only resources a host exposes. The authoring reference is the keystone: the
+ *  engine-generated, never-drifting syntax guide the model reads before authoring. */
+declare const MCP_RESOURCES: readonly McpResourceDef[];
+/** Resolve a resource URI to its contents, or `undefined` if the URI is unknown. */
+declare function readMcpResource(uri: string): {
+    readonly text: string;
+    readonly mimeType: string;
+} | undefined;
+
+export { type ApiDeps, type ApiRequest, type ApiResponse, type BrandingLogo, type BrandingLogoMeta, type BrandingState, type BrandingStore, FileBrandingStore, InMemoryBrandingStore, MCP_RESOURCES, MCP_TOOLS, type McpCallOptions, type McpResourceDef, type McpToolDef, type McpToolResult, authorDirectory, authorOptions, callMcpTool, handleApi, readMcpResource };