@avocadostudio-ai/orchestrator-core 0.3.3 → 0.4.0

package/dist/cms/adapter.d.ts

@@ -67,14 +67,33 @@ export type CmsPublishResult = void | {
 export interface CmsMediaItem {
     /** Stable id in the source store. Used as the picker's selection key. */
     id: string;
+    /**
+     * What this asset is.
+     *
+     * Absent means `"image"`, because every adapter written before documents
+     * existed returns images and must keep working unchanged. `"file"` is a
+     * document — a menu PDF, a price list, a consent form — which the editor
+     * offers into a `file` field or a prose link rather than an `<img>`.
+     */
+    kind?: "image" | "file";
     /** Human-facing filename or title, if the store has one. */
     name?: string;
     /** Full-size URL to insert into the page. Omitted only if the store has none. */
     imageUrl?: string;
-    /** Grid thumbnail. May be the same URL as `imageUrl` when no derivative exists. */
+    /**
+     * Grid thumbnail. May be the same URL as `imageUrl` when no derivative
+     * exists. A `file` has nothing to show, so this is `""` for one and the
+     * picker draws an icon from `contentType` instead.
+     */
     thumbUrl: string;
     /** Alt text the store already holds, so the editor does not invent one. */
     alt?: string;
+    /** For `kind: "file"`: the URL to link to. */
+    url?: string;
+    /** MIME type, when the store knows it. Drives the picker's icon and filter. */
+    contentType?: string;
+    /** Bytes, when the store knows it. Shown to a person; nothing decides on it. */
+    size?: number;
 }
 /** One page of a media-library search. */
 export interface CmsMediaQuery {
@@ -84,6 +103,16 @@ export interface CmsMediaQuery {
     page: number;
     /** Items per page. */
     limit: number;
+    /**
+     * Which kind the caller wants.
+     *
+     * Absent means "images", which is what every existing caller meant and every
+     * existing adapter answers. An adapter that does not understand this field
+     * returns images to a request for documents; the route filters the response
+     * by `kind` as well, so an old adapter degrades to an empty document tab
+     * rather than to a grid of images offered as PDFs.
+     */
+    kind?: "image" | "file";
 }
 /** What `getMedia` returns: the page, and how many there are in total. */
 export interface CmsMediaPage {
@@ -200,6 +229,43 @@ export interface CmsAdapter {
      * requirement, and nothing in the route path knows it exists.
      */
     getMedia?(query: CmsMediaQuery): Promise<CmsMediaPage>;
+    /**
+     * Optional media *write*, the other half of `getMedia`.
+     *
+     * Somebody has to be able to add a document, and until this existed the only
+     * way was to put the file on disk yourself and commit it — which is not a
+     * path a non-technical editor has, and is the whole reason the editor could
+     * list a site's PDFs but never gain one.
+     *
+     * The adapter decides where a file goes, for the same reason it decides where
+     * pages come from: we do not know. A static site writes into `public/`; a
+     * Sanity site uploads an asset and gets a CDN URL; a site on a read-only
+     * filesystem implements nothing and the editor offers no upload button.
+     * Owning storage here instead would mean owning it *badly* — the existing
+     * `POST /image/upload` writes to the orchestrator's local disk, which on an
+     * ephemeral container loses every upload on redeploy, and building the
+     * document path on that foundation would spread the defect rather than fix
+     * it.
+     *
+     * Implement it and the editor offers upload. Leave it off and it does not —
+     * silence means no, as everywhere else on this interface.
+     *
+     * Throwing rejects the upload with the thrown message shown to the editor, so
+     * a refusal ("we only accept PDFs", "that name is taken") is expressible
+     * without a second return shape.
+     */
+    uploadMedia?(input: CmsMediaUpload): Promise<CmsMediaItem>;
+}
+/** One file on its way in. */
+export interface CmsMediaUpload {
+    /** Original filename as the browser reported it. Treat as untrusted. */
+    filename: string;
+    /** MIME type the browser reported, or "" — also untrusted. */
+    contentType: string;
+    /** The bytes. */
+    data: Uint8Array;
+    /** What the caller says this is. The adapter may disagree and throw. */
+    kind: "image" | "file";
 }
 /**
  * Per-operation capability declaration. Every field is tri-state, and the
@@ -266,6 +332,13 @@ export interface ResolvedCapabilities {
      * opens onto a method nobody implemented is a worse answer than no tab.
      */
     readsMedia: boolean;
+    /**
+     * Whether this site can take a new file — derived from `uploadMedia`, the
+     * same way `readsMedia` is derived from `getMedia`. The editor offers an
+     * upload control only where there is something behind it; a button that
+     * always fails is worse than no button.
+     */
+    writesMedia: boolean;
     /**
      * The subset the adapter actually declared. A caller that needs to
      * distinguish "this site says no" from "nobody said" reads this; everything

package/dist/cms/adapter.js

@@ -15,6 +15,7 @@ export function resolveCapabilities(adapter, override) {
         // `=== true`, not truthiness: an adapter that says nothing has not said yes.
         readsDraftPerspective: adapter?.perspectives === true,
         readsMedia: typeof adapter?.getMedia === "function",
+        writesMedia: typeof adapter?.uploadMedia === "function",
         declared
     };
 }

package/dist/cms/index.d.ts

@@ -3,4 +3,4 @@ export { resolveCapabilities } from "./adapter.ts";
 export { jsonFileAdapter, type JsonFileAdapterOptions } from "./json-file-adapter.ts";
 export { editorApiAdapter, type EditorApiAdapterOptions } from "./editor-api-adapter.ts";
 export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache, type CmsBootstrapCache, type CmsBootstrapCacheOptions, warmSessionBootstrap } from "./bootstrap.ts";
-export { cmsMediaSource, cmsMediaLabel, mediaSourceFromUnknown, type CmsMediaSource, type CmsMediaSourceConfig } from "./media-sources.ts";
+export { cmsMediaSource, cmsMediaUploader, cmsMediaLabel, mediaSourceFromUnknown, type CmsMediaSource, type CmsMediaUploader, type CmsMediaSourceConfig } from "./media-sources.ts";

package/dist/cms/index.js

@@ -2,4 +2,4 @@ export { resolveCapabilities } from "./adapter.js";
 export { jsonFileAdapter } from "./json-file-adapter.js";
 export { editorApiAdapter } from "./editor-api-adapter.js";
 export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache, warmSessionBootstrap } from "./bootstrap.js";
-export { cmsMediaSource, cmsMediaLabel, mediaSourceFromUnknown } from "./media-sources.js";
+export { cmsMediaSource, cmsMediaUploader, cmsMediaLabel, mediaSourceFromUnknown } from "./media-sources.js";

package/dist/cms/media-sources.d.ts

@@ -1,4 +1,4 @@
-import type { CmsMediaPage, CmsMediaQuery } from "./adapter.ts";
+import type { CmsMediaItem, CmsMediaPage, CmsMediaQuery, CmsMediaUpload } from "./adapter.ts";
 /** Connection details for one of the built-in media readers. */
 export type CmsMediaSourceConfig = {
     provider: "contentful";
@@ -17,6 +17,8 @@ export type CmsMediaSourceConfig = {
 };
 /** A media reader: the exact shape of `CmsAdapter.getMedia`. */
 export type CmsMediaSource = (query: CmsMediaQuery) => Promise<CmsMediaPage>;
+/** A media writer: the exact shape of `CmsAdapter.uploadMedia`. */
+export type CmsMediaUploader = (input: CmsMediaUpload) => Promise<CmsMediaItem>;
 /** Display name for a provider id, for the picker's tab. */
 export declare function cmsMediaLabel(provider: CmsMediaSourceConfig["provider"]): string;
 /**
@@ -37,6 +39,32 @@ export declare function cmsMediaLabel(provider: CmsMediaSourceConfig["provider"]
  * promise inside a modal is not.
  */
 export declare function cmsMediaSource(config: CmsMediaSourceConfig): CmsMediaSource;
+/**
+ * Build a media writer from the same connection details as the reader, or
+ * `null` when this provider (or this configuration) cannot take an upload.
+ *
+ * ```ts
+ * const uploadMedia = cmsMediaUploader({ provider: "sanity", projectId, dataset, token })
+ * return { id: "sanity", getPages, getMedia, ...(uploadMedia ? { uploadMedia } : {}) }
+ * ```
+ *
+ * Null rather than a stub that throws, and spread rather than assigned,
+ * because `writesMedia` is derived from whether the method *exists*
+ * (`resolveCapabilities`) and the editor shows its upload control on the
+ * strength of that. A method that is always present and always fails is a
+ * button that is always there and never works.
+ *
+ * So a project with a read-only token gets no upload control at all, which is
+ * the truth about it: Sanity's query API answers a viewer token and its asset
+ * API does not, and that difference is invisible until somebody picks a file.
+ *
+ * **Sanity only, for now.** Uploading to Contentful is a three-step
+ * asynchronous dance — create the asset, ask for processing, poll, publish —
+ * and Strapi's is a multipart POST to its upload plugin; neither is written
+ * yet, and both answer `null` so that an adapter which spreads the result
+ * simply offers no upload rather than offering a broken one.
+ */
+export declare function cmsMediaUploader(config: CmsMediaSourceConfig): CmsMediaUploader | null;
 /**
  * Build a reader from an untrusted object, or `null` if it is not one of the
  * three shapes.

package/dist/cms/media-sources.js

@@ -1,3 +1,5 @@
+/** Sanity's dated API: one version for both the query and the asset endpoints. */
+const SANITY_API_VERSION = "v2024-01-01";
 const LABELS = {
     contentful: "Contentful",
     sanity: "Sanity",
@@ -69,20 +71,33 @@ async function contentfulMedia(config, { query, page, limit }) {
 // ---------------------------------------------------------------------------
 // Sanity — GROQ, slice paging, a second query for the count.
 // ---------------------------------------------------------------------------
-async function sanityMedia(config, { query, page, limit }) {
+async function sanityMedia(config, { query, page, limit, kind }) {
     const label = LABELS.sanity;
     const dataset = config.dataset ?? "production";
     const offset = (page - 1) * limit;
     const end = offset + limit - 1;
+    const wantsFiles = kind === "file";
+    /*
+     * Sanity keeps documents in a second asset type. A PDF uploaded through the
+     * Studio — or through `cmsMediaUploader` below — is a `sanity.fileAsset`,
+     * and asking for `sanity.imageAsset` finds none of them however many the
+     * project holds. Before this branch existed, a request for documents was
+     * answered with the image list, and the route's own kind filter then dropped
+     * every item: an empty Documents tab on a project full of menus.
+     */
+    const assetType = wantsFiles ? "sanity.fileAsset" : "sanity.imageAsset";
     // GROQ is interpolated, so the filter term is stripped of the two characters
     // that could close the string literal it lands inside.
     const safeQuery = (query ?? "").replace(/["\\]/g, "");
     const filter = safeQuery
-        ? `_type == "sanity.imageAsset" && originalFilename match "*${safeQuery}*"`
-        : `_type == "sanity.imageAsset"`;
-    const groq = `*[${filter}] | order(_createdAt desc) [${offset}..${end}] { _id, url, originalFilename, metadata { dimensions } }`;
+        ? `_type == "${assetType}" && originalFilename match "*${safeQuery}*"`
+        : `_type == "${assetType}"`;
+    const projection = wantsFiles
+        ? `{ _id, url, originalFilename, mimeType, size }`
+        : `{ _id, url, originalFilename, metadata { dimensions } }`;
+    const groq = `*[${filter}] | order(_createdAt desc) [${offset}..${end}] ${projection}`;
     const countGroq = `count(*[${filter}])`;
-    const base = `https://${config.projectId}.api.sanity.io/v2024-01-01/data/query/${dataset}`;
+    const base = `https://${config.projectId}.api.sanity.io/${SANITY_API_VERSION}/data/query/${dataset}`;
     const headers = {};
     if (config.token)
         headers.authorization = `Bearer ${config.token}`;
@@ -95,17 +110,37 @@ async function sanityMedia(config, { query, page, limit }) {
     const assets = (await assetsRes.json());
     const count = countRes.ok ? (await countRes.json()).result ?? 0 : 0;
     return {
-        items: (assets.result ?? []).map((asset) => ({
+        items: (assets.result ?? []).map((asset) => wantsFiles ? sanityFileItem(asset) : {
             id: asset._id,
             name: asset.originalFilename,
             alt: asset.originalFilename,
             imageUrl: asset.url,
             thumbUrl: `${asset.url}?w=200&h=200&fit=crop`
-        })),
+        }),
         totalPages: Math.ceil(count / limit),
         label
     };
 }
+/**
+ * One `sanity.fileAsset` as the picker's document tab renders it.
+ *
+ * `url` rather than `imageUrl`, because this is a link target and not something
+ * to draw, and `thumbUrl: ""` for the same reason — the picker draws an icon
+ * from `contentType` when there is nothing to show. The URL is Sanity's own
+ * `cdn.sanity.io/files/…` address: durable, CDN-served, and unchanged by any
+ * redeploy of the site that links to it.
+ */
+function sanityFileItem(asset) {
+    return {
+        id: asset._id,
+        kind: "file",
+        name: asset.originalFilename,
+        url: asset.url,
+        thumbUrl: "",
+        contentType: asset.mimeType ?? "application/octet-stream",
+        ...(typeof asset.size === "number" ? { size: asset.size } : {})
+    };
+}
 // ---------------------------------------------------------------------------
 // Strapi — upload plugin, page/pageSize paging, count in a response header.
 // ---------------------------------------------------------------------------
@@ -142,6 +177,152 @@ async function strapiMedia(config, { query, page, limit }) {
         label
     };
 }
+// ---------------------------------------------------------------------------
+// Adding one — the write half, for the CMSes whose asset API is a single call.
+// ---------------------------------------------------------------------------
+/**
+ * Build a media writer from the same connection details as the reader, or
+ * `null` when this provider (or this configuration) cannot take an upload.
+ *
+ * ```ts
+ * const uploadMedia = cmsMediaUploader({ provider: "sanity", projectId, dataset, token })
+ * return { id: "sanity", getPages, getMedia, ...(uploadMedia ? { uploadMedia } : {}) }
+ * ```
+ *
+ * Null rather than a stub that throws, and spread rather than assigned,
+ * because `writesMedia` is derived from whether the method *exists*
+ * (`resolveCapabilities`) and the editor shows its upload control on the
+ * strength of that. A method that is always present and always fails is a
+ * button that is always there and never works.
+ *
+ * So a project with a read-only token gets no upload control at all, which is
+ * the truth about it: Sanity's query API answers a viewer token and its asset
+ * API does not, and that difference is invisible until somebody picks a file.
+ *
+ * **Sanity only, for now.** Uploading to Contentful is a three-step
+ * asynchronous dance — create the asset, ask for processing, poll, publish —
+ * and Strapi's is a multipart POST to its upload plugin; neither is written
+ * yet, and both answer `null` so that an adapter which spreads the result
+ * simply offers no upload rather than offering a broken one.
+ */
+export function cmsMediaUploader(config) {
+    if (config.provider !== "sanity")
+        return null;
+    const token = config.token?.trim();
+    if (!token)
+        return null;
+    return (input) => sanityUpload({ ...config, token }, input);
+}
+/**
+ * MIME types for the document extensions a site is likely to be handed, used
+ * only when the browser reported none.
+ *
+ * Sanity sniffs the bytes and would usually get there on its own; sending
+ * `application/octet-stream` for a PDF, though, is how an asset ends up in the
+ * library with a type the picker cannot draw an icon for.
+ */
+const UPLOAD_MIME_BY_EXT = {
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    csv: "text/csv",
+    txt: "text/plain",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    webp: "image/webp",
+    gif: "image/gif",
+    svg: "image/svg+xml"
+};
+function uploadContentType(input) {
+    const declared = input.contentType.trim();
+    if (declared)
+        return declared;
+    const ext = input.filename.toLowerCase().split(".").pop() ?? "";
+    return UPLOAD_MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+/**
+ * The filename Sanity records as `originalFilename`.
+ *
+ * It is not a path — the asset's own URL is derived from a content hash — so
+ * this strips directory segments and control characters and otherwise leaves
+ * the name a person chose intact, accents and spaces included. The picker
+ * shows this string, and "Menükarte Winter 2026.pdf" is what makes a document
+ * recognisable in a list of twenty.
+ */
+function uploadFilename(raw) {
+    const base = raw.split(/[\\/]/).pop() ?? "";
+    // Control characters, written as escapes: a literal one in the source is
+    // invisible to every reader and turns the file binary to `grep`.
+    return base.replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, 120);
+}
+async function sanityUpload(config, input) {
+    const dataset = config.dataset ?? "production";
+    /*
+     * Two buckets, and picking the wrong one is not a detail: `images` runs the
+     * bytes through image processing and refuses anything that is not a picture,
+     * which is exactly the refusal a PDF sent there produces. `kind` is what the
+     * editor said it was uploading, so it decides.
+     */
+    const bucket = input.kind === "file" ? "files" : "images";
+    const filename = uploadFilename(input.filename);
+    const params = new URLSearchParams();
+    if (filename)
+        params.set("filename", filename);
+    const res = await fetch(`https://${config.projectId}.api.sanity.io/${SANITY_API_VERSION}/assets/${bucket}/${dataset}?${params}`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${config.token}`,
+            "content-type": uploadContentType(input)
+        },
+        body: new Uint8Array(input.data)
+    });
+    /*
+     * Throwing is the contract's way of refusing an upload, and the message
+     * reaches the person who picked the file — so it has to say what Sanity
+     * said, not that something went wrong.
+     */
+    if (!res.ok)
+        throw new Error(await sanityUploadError(res));
+    const body = (await res.json());
+    const doc = body.document;
+    if (!doc?._id || !doc.url) {
+        throw new Error("Sanity accepted the upload but returned no asset.");
+    }
+    if (input.kind === "file") {
+        return sanityFileItem({ _id: doc._id, url: doc.url, originalFilename: doc.originalFilename, mimeType: doc.mimeType, size: doc.size });
+    }
+    return {
+        id: doc._id,
+        name: doc.originalFilename,
+        alt: doc.originalFilename,
+        imageUrl: doc.url,
+        thumbUrl: `${doc.url}?w=200&h=200&fit=crop`
+    };
+}
+async function sanityUploadError(res) {
+    /*
+     * 401/403 has one overwhelmingly likely cause and it is not obvious from
+     * Sanity's own wording: the token reads fine — the picker's grid is full of
+     * images, which is what makes it confusing — and simply has no write grant.
+     */
+    const suffix = res.status === 401 || res.status === 403
+        ? " The API token needs write access to this dataset; a read token fills the picker but cannot upload."
+        : "";
+    const fallback = `Sanity refused the upload (${res.status}).${suffix}`;
+    try {
+        const body = (await res.json());
+        const described = typeof body.error === "string"
+            ? body.error
+            : body.error?.description ?? body.error?.message ?? body.message;
+        return described ? `Sanity refused the upload: ${described}${suffix}` : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
 /**
  * Build a reader from an untrusted object, or `null` if it is not one of the
  * three shapes.