@humaan/payload-plugin-ai-assistant 0.0.0-stage → 0.1.1

package/dist/read/readable.js

@@ -0,0 +1,131 @@
+import { maxReadRichTextCharacters } from '../constants.js';
+const noiseKeys = new Set([
+    'createdAt',
+    'sizes',
+    'thumbnailURL',
+    'updatedAt'
+]);
+const maxListItems = 40;
+const maxStringCharacters = 4_000;
+const maxDepth = 12;
+/**
+ * A document as the assistant reads it. Rich text becomes markdown, timestamps and image sizes are dropped,
+ * and long lists and strings are cut so one read cannot fill the model's context.
+ */ export async function readableDocument(fields, data, readRichText) {
+    return readFields(fields, data, readRichText, 0);
+}
+async function readFields(fields, data, read, depth) {
+    const out = plain(data, depth);
+    if (!isRecord(data) || !isRecord(out)) {
+        return out;
+    }
+    await readInto(fields, data, out, read, depth);
+    return out;
+}
+/** Fields without a name (rows, collapsibles, unnamed tabs and groups) keep their children at the same level. */ async function readInto(fields, data, out, read, depth) {
+    for (const field of fields){
+        if (field.type === 'tabs') {
+            for (const tab of field.tabs){
+                if ('name' in tab && tab.name) {
+                    if (tab.name in data) {
+                        out[tab.name] = await readFields(tab.fields, data[tab.name], read, depth + 1);
+                    }
+                } else {
+                    await readInto(tab.fields, data, out, read, depth);
+                }
+            }
+            continue;
+        }
+        const name = 'name' in field && typeof field.name === 'string' ? field.name : undefined;
+        if (!name) {
+            if ('fields' in field && Array.isArray(field.fields)) {
+                await readInto(field.fields, data, out, read, depth);
+            }
+            continue;
+        }
+        if (name in data && !noiseKeys.has(name)) {
+            out[name] = await readField(field, data[name], read, depth + 1);
+        }
+    }
+}
+async function readField(field, value, read, depth) {
+    if (value === null || value === undefined || depth > maxDepth) {
+        return plain(value, depth);
+    }
+    if (field.type === 'richText') {
+        if (!isLexical(value)) {
+            return plain(value, depth);
+        }
+        try {
+            return cut((await read(field, value)).trim(), maxReadRichTextCharacters);
+        } catch  {
+            return '[rich text that could not be read]';
+        }
+    }
+    if (field.type === 'group') {
+        return readFields(field.fields, value, read, depth);
+    }
+    if (field.type === 'array' && Array.isArray(value)) {
+        return readList(value, (row)=>readFields(field.fields, row, read, depth + 1));
+    }
+    if (field.type === 'blocks' && Array.isArray(value)) {
+        return readList(value, (row)=>{
+            const blockType = isRecord(row) ? row.blockType : undefined;
+            const block = field.blocks.find((item)=>item.slug === blockType);
+            return block ? readFields(block.fields, row, read, depth + 1) : Promise.resolve(plain(row, depth + 1));
+        });
+    }
+    return plain(value, depth);
+}
+async function readList(items, readItem) {
+    const shown = await Promise.all(items.slice(0, maxListItems).map(readItem));
+    const hidden = items.length - shown.length;
+    return hidden > 0 ? [
+        ...shown,
+        `[${hidden} more not shown]`
+    ] : shown;
+}
+/** A copy without noise keys, cut to size. Rich text with no field to read it by is left as a marker. */ function plain(value, depth) {
+    if (typeof value === 'string') {
+        return cut(value, maxStringCharacters);
+    }
+    if (depth > maxDepth) {
+        return '[nested too deeply to show]';
+    }
+    if (Array.isArray(value)) {
+        const shown = value.slice(0, maxListItems).map((item)=>plain(item, depth + 1));
+        const hidden = value.length - shown.length;
+        return hidden > 0 ? [
+            ...shown,
+            `[${hidden} more not shown]`
+        ] : shown;
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    if (isLexical(value)) {
+        return '[rich text]';
+    }
+    const next = {};
+    for (const [key, item] of Object.entries(value)){
+        if (noiseKeys.has(key)) {
+            continue;
+        }
+        next[key] = plain(item, depth + 1);
+    }
+    return next;
+}
+function cut(value, limit) {
+    if (value.length <= limit) {
+        return value;
+    }
+    return `${value.slice(0, limit)} [cut: ${value.length - limit} more characters]`;
+}
+function isLexical(value) {
+    return isRecord(value) && isRecord(value.root);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+//# sourceMappingURL=readable.js.map

package/dist/read/readable.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/read/readable.ts"],"sourcesContent":["import type { Field, RichTextField } from 'payload'\n\nimport { maxReadRichTextCharacters } from '../constants.js'\n\n/** Turns one rich text value into markdown. Injected so the walk can be tested without a Payload config. */\nexport type RichTextReader = (\n  field: RichTextField,\n  value: Record<string, unknown>,\n) => Promise<string>\n\nconst noiseKeys = new Set(['createdAt', 'sizes', 'thumbnailURL', 'updatedAt'])\nconst maxListItems = 40\nconst maxStringCharacters = 4_000\nconst maxDepth = 12\n\n/**\n * A document as the assistant reads it. Rich text becomes markdown, timestamps and image sizes are dropped,\n * and long lists and strings are cut so one read cannot fill the model's context.\n */\nexport async function readableDocument(\n  fields: Field[],\n  data: unknown,\n  readRichText: RichTextReader,\n): Promise<unknown> {\n  return readFields(fields, data, readRichText, 0)\n}\n\nasync function readFields(\n  fields: Field[],\n  data: unknown,\n  read: RichTextReader,\n  depth: number,\n): Promise<unknown> {\n  const out = plain(data, depth)\n  if (!isRecord(data) || !isRecord(out)) {\n    return out\n  }\n  await readInto(fields, data, out, read, depth)\n  return out\n}\n\n/** Fields without a name (rows, collapsibles, unnamed tabs and groups) keep their children at the same level. */\nasync function readInto(\n  fields: Field[],\n  data: Record<string, unknown>,\n  out: Record<string, unknown>,\n  read: RichTextReader,\n  depth: number,\n): Promise<void> {\n  for (const field of fields) {\n    if (field.type === 'tabs') {\n      for (const tab of field.tabs) {\n        if ('name' in tab && tab.name) {\n          if (tab.name in data) {\n            out[tab.name] = await readFields(tab.fields, data[tab.name], read, depth + 1)\n          }\n        } else {\n          await readInto(tab.fields, data, out, read, depth)\n        }\n      }\n      continue\n    }\n    const name = 'name' in field && typeof field.name === 'string' ? field.name : undefined\n    if (!name) {\n      if ('fields' in field && Array.isArray(field.fields)) {\n        await readInto(field.fields, data, out, read, depth)\n      }\n      continue\n    }\n    if (name in data && !noiseKeys.has(name)) {\n      out[name] = await readField(field, data[name], read, depth + 1)\n    }\n  }\n}\n\nasync function readField(\n  field: Field,\n  value: unknown,\n  read: RichTextReader,\n  depth: number,\n): Promise<unknown> {\n  if (value === null || value === undefined || depth > maxDepth) {\n    return plain(value, depth)\n  }\n\n  if (field.type === 'richText') {\n    if (!isLexical(value)) {\n      return plain(value, depth)\n    }\n    try {\n      return cut((await read(field, value)).trim(), maxReadRichTextCharacters)\n    } catch {\n      return '[rich text that could not be read]'\n    }\n  }\n  if (field.type === 'group') {\n    return readFields(field.fields, value, read, depth)\n  }\n  if (field.type === 'array' && Array.isArray(value)) {\n    return readList(value, (row) => readFields(field.fields, row, read, depth + 1))\n  }\n  if (field.type === 'blocks' && Array.isArray(value)) {\n    return readList(value, (row) => {\n      const blockType = isRecord(row) ? row.blockType : undefined\n      const block = field.blocks.find((item) => item.slug === blockType)\n      return block\n        ? readFields(block.fields, row, read, depth + 1)\n        : Promise.resolve(plain(row, depth + 1))\n    })\n  }\n  return plain(value, depth)\n}\n\nasync function readList(\n  items: unknown[],\n  readItem: (item: unknown) => Promise<unknown>,\n): Promise<unknown[]> {\n  const shown = await Promise.all(items.slice(0, maxListItems).map(readItem))\n  const hidden = items.length - shown.length\n  return hidden > 0 ? [...shown, `[${hidden} more not shown]`] : shown\n}\n\n/** A copy without noise keys, cut to size. Rich text with no field to read it by is left as a marker. */\nfunction plain(value: unknown, depth: number): unknown {\n  if (typeof value === 'string') {\n    return cut(value, maxStringCharacters)\n  }\n  if (depth > maxDepth) {\n    return '[nested too deeply to show]'\n  }\n  if (Array.isArray(value)) {\n    const shown = value.slice(0, maxListItems).map((item) => plain(item, depth + 1))\n    const hidden = value.length - shown.length\n    return hidden > 0 ? [...shown, `[${hidden} more not shown]`] : shown\n  }\n  if (!isRecord(value)) {\n    return value\n  }\n  if (isLexical(value)) {\n    return '[rich text]'\n  }\n  const next: Record<string, unknown> = {}\n  for (const [key, item] of Object.entries(value)) {\n    if (noiseKeys.has(key)) {\n      continue\n    }\n    next[key] = plain(item, depth + 1)\n  }\n  return next\n}\n\nfunction cut(value: string, limit: number): string {\n  if (value.length <= limit) {\n    return value\n  }\n  return `${value.slice(0, limit)} [cut: ${value.length - limit} more characters]`\n}\n\nfunction isLexical(value: unknown): value is Record<string, unknown> {\n  return isRecord(value) && isRecord(value.root)\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)\n}\n"],"names":["maxReadRichTextCharacters","noiseKeys","Set","maxListItems","maxStringCharacters","maxDepth","readableDocument","fields","data","readRichText","readFields","read","depth","out","plain","isRecord","readInto","field","type","tab","tabs","name","undefined","Array","isArray","has","readField","value","isLexical","cut","trim","readList","row","blockType","block","blocks","find","item","slug","Promise","resolve","items","readItem","shown","all","slice","map","hidden","length","next","key","Object","entries","limit","root","Boolean"],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,15 @@
+import type { SanitizedConfig } from 'payload';
+import type { OwnKeySummary } from './billing.js';
+import type { AiAssistantPluginOptions } from './types.js';
+/** Plugin options that code holding only the request needs. The plugin keeps them on `config.custom`. */
+export type PluginRuntime = {
+    deniedCollections: readonly string[];
+    deniedGlobals: readonly string[];
+    /** The providers the own key covers, when its credentials are complete. Never the credentials themselves. */
+    ownKey?: OwnKeySummary;
+    /** Providers in the `byok` option left out because a value is not set. */
+    ownKeyIncomplete: string[];
+    /** IANA time zone for dates shown to editors. */
+    timeZone: string;
+} & Pick<AiAssistantPluginOptions, 'attachmentReadParams'>;
+export declare function pluginRuntime(config: Pick<SanitizedConfig, 'custom'>): PluginRuntime;

package/dist/runtime.js

@@ -0,0 +1,14 @@
+import { pluginCustomKey } from './constants.js';
+export function pluginRuntime(config) {
+    const stored = config.custom?.[pluginCustomKey];
+    return {
+        attachmentReadParams: stored?.attachmentReadParams,
+        timeZone: stored?.timeZone ?? 'UTC',
+        ownKey: stored?.ownKey,
+        ownKeyIncomplete: stored?.ownKeyIncomplete ?? [],
+        deniedCollections: stored?.deniedCollections ?? [],
+        deniedGlobals: stored?.deniedGlobals ?? []
+    };
+}
+
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["import type { SanitizedConfig } from 'payload'\n\nimport type { OwnKeySummary } from './billing.js'\nimport type { AiAssistantPluginOptions } from './types.js'\n\nimport { pluginCustomKey } from './constants.js'\n\n/** Plugin options that code holding only the request needs. The plugin keeps them on `config.custom`. */\nexport type PluginRuntime = {\n  deniedCollections: readonly string[]\n  deniedGlobals: readonly string[]\n  /** The providers the own key covers, when its credentials are complete. Never the credentials themselves. */\n  ownKey?: OwnKeySummary\n  /** Providers in the `byok` option left out because a value is not set. */\n  ownKeyIncomplete: string[]\n  /** IANA time zone for dates shown to editors. */\n  timeZone: string\n} & Pick<AiAssistantPluginOptions, 'attachmentReadParams'>\n\nexport function pluginRuntime(config: Pick<SanitizedConfig, 'custom'>): PluginRuntime {\n  const stored = config.custom?.[pluginCustomKey] as Partial<PluginRuntime> | undefined\n  return {\n    attachmentReadParams: stored?.attachmentReadParams,\n    timeZone: stored?.timeZone ?? 'UTC',\n    ownKey: stored?.ownKey,\n    ownKeyIncomplete: stored?.ownKeyIncomplete ?? [],\n    deniedCollections: stored?.deniedCollections ?? [],\n    deniedGlobals: stored?.deniedGlobals ?? [],\n  }\n}\n"],"names":["pluginCustomKey","pluginRuntime","config","stored","custom","attachmentReadParams","timeZone","ownKey","ownKeyIncomplete","deniedCollections","deniedGlobals"],"mappings":"AAKA,SAASA,eAAe,QAAQ,iBAAgB;AAchD,OAAO,SAASC,cAAcC,MAAuC;IACnE,MAAMC,SAASD,OAAOE,MAAM,EAAE,CAACJ,gBAAgB;IAC/C,OAAO;QACLK,sBAAsBF,QAAQE;QAC9BC,UAAUH,QAAQG,YAAY;QAC9BC,QAAQJ,QAAQI;QAChBC,kBAAkBL,QAAQK,oBAAoB,EAAE;QAChDC,mBAAmBN,QAAQM,qBAAqB,EAAE;QAClDC,eAAeP,QAAQO,iBAAiB,EAAE;IAC5C;AACF"}

package/dist/schema/fields.d.ts

@@ -0,0 +1,113 @@
+import type { Field, RichTextField } from 'payload';
+/** Whether a field is shown, from its `admin.condition`, given the values beside it. */
+type FieldCondition = (siblingData: Record<string, unknown>) => boolean;
+type GuideMeta = {
+    /** Present when the field is shown only for some sibling values, such as a link's doc or url. */
+    condition?: FieldCondition;
+    description?: string;
+    label?: string;
+    name: string;
+    /** Guidance for the assistant only, from `custom.aiAssistant` on the field. */
+    note?: string;
+    required: boolean;
+};
+export type CompiledField = ({
+    blocks: CompiledBlock[];
+    kind: 'blocks';
+    maxRows?: number;
+    minRows?: number;
+} & GuideMeta) | {
+    condition?: FieldCondition;
+    fields: CompiledField[];
+    kind: 'flatten';
+} | ({
+    field: RichTextField;
+    kind: 'richText';
+} & GuideMeta) | ({
+    fields: CompiledField[];
+    kind: 'array';
+    maxRows?: number;
+    minRows?: number;
+} & GuideMeta) | ({
+    fields: CompiledField[];
+    kind: 'group';
+} & GuideMeta) | ({
+    hasMany: boolean;
+    kind: 'date' | 'email' | 'text' | 'textarea';
+} & GuideMeta) | ({
+    hasMany: boolean;
+    kind: 'number';
+} & GuideMeta) | ({
+    hasMany: boolean;
+    kind: 'relationship' | 'upload';
+    relationTo: string[];
+} & GuideMeta) | ({
+    hasMany: boolean;
+    kind: 'select';
+    options: string[];
+} & GuideMeta) | ({
+    kind: 'checkbox';
+} & GuideMeta);
+type CompiledBlock = {
+    fields: CompiledField[];
+    label?: string;
+    /** Guidance for the assistant only, from `custom.aiAssistant` on the block. */
+    note?: string;
+    slug: string;
+};
+export type FieldError = {
+    message: string;
+    path: string;
+};
+export type ApplyContext = {
+    /** An update may omit fields. Missing required fields stay as they are. */
+    partial?: boolean;
+    toLexical: (field: RichTextField, markdown: string) => Promise<unknown>;
+};
+/**
+ * Guidance for the assistant that editors do not need to see: a string at `custom.aiAssistant` on a field,
+ * block, collection, or global. Guidance that helps editors too belongs in `admin.description`, which the
+ * guide also includes.
+ */
+export declare function assistantNote(config: {
+    custom?: unknown;
+}): string | undefined;
+/** Fields the model is allowed to fill. JSON, code, and point fields are left out. Every block in the schema is included. */
+export declare function compileFields(fields: Field[]): CompiledField[];
+export interface FieldGuideOptions {
+    /** Blocks to describe in full, by slug. Every other block is listed by name only. */
+    blocks?: readonly string[];
+}
+/**
+ * Compact field guide the model fills. Names match the collection schema.
+ * Block definitions are most of a page's schema, so only the blocks asked for are expanded.
+ */
+export declare function formatFieldGuide(fields: Field[], options?: FieldGuideOptions): string;
+/** The field a dotted path points at, through groups, tabs, and rows. Lists and blocks end the walk. */
+export declare function compiledFieldAtPath(fields: Field[], path: string): CompiledField | undefined;
+/**
+ * Keys in a set that match no field. Writes drop unknown keys, so these must be rejected
+ * before the editor sees a plan that would quietly skip them.
+ */
+export declare function unknownFieldPaths(fields: Field[], set: Record<string, unknown>): string[];
+/** Every block slug in the guide, so the model can be told which ones it can ask about. */
+export declare function blockSlugs(fields: Field[]): string[];
+export declare function exampleValues(fields: Field[]): Record<string, unknown>;
+export declare function applyFields(fields: Field[], values: unknown, context: ApplyContext): Promise<{
+    data: Record<string, unknown>;
+    ok: true;
+} | {
+    errors: FieldError[];
+    ok: false;
+}>;
+/** Fills slug, path, and hidden defaults the editor never types, so create validation can pass. */
+/**
+ * The slug a renamed document gets when its "Use title" toggle is on, matching the slug field in the editor,
+ * which rebuilds the slug from the title as it changes. Undefined when the slug stays as it is.
+ * The path field's own hook then rebuilds the URL from the slug and adds a redirect if the page was published.
+ */
+export declare function followedSlug(fields: Field[], current: unknown, nextTitle: unknown): string | undefined;
+export declare function withDerivedValues(fields: Field[], data: Record<string, unknown>, options?: {
+    prependPath?: string;
+}): Record<string, unknown>;
+export {};