@gobing-ai/knowledge-kit 0.0.11 → 0.0.13

package/plugins/publishings/podcast-pub/src/map.ts

@@ -0,0 +1,165 @@
+import type { Content } from '@gobing-ai/kk-core';
+import { renderShowNotesHtml } from './show-notes';
+
+/** Resolved episode fields derived from a Content payload (design D6). */
+export interface EpisodeMapping {
+    /** Episode title: `content.title`, else the first `#` heading, else validation error. */
+    title: string;
+    /** Episode show notes as sanitized HTML: `metadata.showNotes` (markdown → HTML) or `content.body` rendered. */
+    contentHtml: string;
+    /** microfeed item status; `metadata.status` when given, `published` by default. */
+    status: string | number;
+    /** Audio reference: local file (upload flow) or already-hosted URL (single create call). */
+    audio: { kind: 'file'; path: string; mimeType: string } | { kind: 'url'; url: string; mimeType: string };
+    /** Optional playback duration in seconds (`metadata.durationSeconds`). */
+    durationSeconds?: number;
+    /** Optional episode cover: absolute or remote URL (`metadata.coverImage` → microfeed `image`). */
+    imageUrl?: string;
+    /** Optional local episode cover file (`metadata.coverImage` local path → presigned image upload). */
+    imagePath?: string;
+    /** Optional publish date as epoch ms (`metadata.publishedAt` ISO string or epoch). */
+    datePublishedMs?: number;
+    /** Optional public link for the episode (`metadata.articleUrl` → microfeed `url`). */
+    link?: string;
+    /** Podcast-directory fields (`metadata.itunes`) passed through to `_microfeed`. */
+    itunes?: {
+        title?: string;
+        episodeType?: 'full' | 'trailer' | 'bonus';
+        season?: number;
+        episode?: number;
+        explicit?: boolean;
+        block?: boolean;
+    };
+}
+
+/** Extension → audio MIME defaults; `metadata.mimeType` overrides. */
+const AUDIO_MIME_BY_EXTENSION: Record<string, string> = {
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.m4a': 'audio/mp4',
+    '.aac': 'audio/aac',
+    '.ogg': 'audio/ogg',
+    '.oga': 'audio/ogg',
+    '.flac': 'audio/flac',
+    '.opus': 'audio/opus',
+};
+
+/**
+ * Resolves the audio MIME type from `metadata.mimeType` or the file extension
+ * (`.wav` → `audio/wav`); unknown extensions fall back to `application/octet-stream`.
+ * The plugin never probes or transcodes audio (design anti-pattern) — metadata
+ * carries what the caller knows.
+ */
+export function resolveAudioMimeType(reference: string, mimeType?: unknown): string {
+    if (typeof mimeType === 'string' && mimeType.trim().length > 0) {
+        return mimeType.trim();
+    }
+    const dot = reference.lastIndexOf('.');
+    const extension = dot >= 0 ? reference.slice(dot).toLowerCase() : '';
+    return AUDIO_MIME_BY_EXTENSION[extension] ?? 'application/octet-stream';
+}
+
+/**
+ * Maps Content + episode metadata into microfeed item fields (design D6).
+ * Validates only the plugin's own requirements — title resolvable and exactly one
+ * audio reference — before any network call (R5); microfeed's `validate` endpoint
+ * and server 400s surface everything else (R4 error path).
+ * Throws with a diagnostic when the Content is not publishable.
+ */
+export function mapContentToEpisode(content: Content): EpisodeMapping {
+    const metadata = content.metadata ?? {};
+
+    let title = content.title?.trim();
+    if (!title) {
+        const match = content.body.match(/^#\s+(.+)$/m);
+        title = match?.[1]?.trim();
+    }
+    if (!title) {
+        throw new Error('episode title is required: set content.title or start the body with a "# " heading');
+    }
+
+    const audioFile = typeof metadata.audioFile === 'string' ? metadata.audioFile.trim() : undefined;
+    const audioUrl = typeof metadata.audioUrl === 'string' ? metadata.audioUrl.trim() : undefined;
+    if (audioFile && audioUrl) {
+        throw new Error('ambiguous audio reference: set either metadata.audioUrl or metadata.audioFile, not both');
+    }
+    if (!audioFile && !audioUrl) {
+        throw new Error(
+            'audio reference is required: set metadata.audioUrl (hosted) or metadata.audioFile (local path)',
+        );
+    }
+
+    const duration = metadata.durationSeconds;
+    if (duration !== undefined && (typeof duration !== 'number' || !Number.isFinite(duration) || duration < 0)) {
+        throw new Error(`invalid metadata.durationSeconds: expected a nonnegative number, got ${String(duration)}`);
+    }
+
+    const status = metadata.status ?? 'published';
+    if (typeof status !== 'string' && typeof status !== 'number') {
+        throw new Error(`invalid metadata.status: expected a status name or number, got ${typeof status}`);
+    }
+
+    const showNotes = typeof metadata.showNotes === 'string' ? metadata.showNotes.trim() : undefined;
+
+    const articleUrl = typeof metadata.articleUrl === 'string' ? metadata.articleUrl.trim() : undefined;
+    const link = articleUrl && articleUrl.length > 0 ? articleUrl : undefined;
+    const coverImage = typeof metadata.coverImage === 'string' ? metadata.coverImage.trim() : undefined;
+    // microfeed keeps remote image URLs verbatim (`image` field); a local cover file
+    // goes through the presigned image upload flow (no item_id required) instead.
+    const imageUrl = coverImage?.startsWith('http') ? coverImage : undefined;
+    const imagePath = !imageUrl && coverImage && coverImage.length > 0 ? coverImage : undefined;
+
+    let datePublishedMs: number | undefined;
+    const publishedAt = metadata.publishedAt;
+    if (typeof publishedAt === 'string' && publishedAt.length > 0) {
+        const parsed = Date.parse(publishedAt);
+        if (Number.isNaN(parsed)) {
+            throw new Error(`invalid metadata.publishedAt: not an ISO date string: ${publishedAt}`);
+        }
+        datePublishedMs = parsed;
+    } else if (typeof publishedAt === 'number' && Number.isFinite(publishedAt)) {
+        datePublishedMs = publishedAt;
+    }
+
+    let itunes: EpisodeMapping['itunes'] | undefined;
+    const rawItunes = metadata.itunes;
+    if (rawItunes !== undefined && typeof rawItunes === 'object' && !Array.isArray(rawItunes)) {
+        const rec = rawItunes as Record<string, unknown>;
+        const episodeType = rec.episodeType;
+        if (episodeType !== undefined && !['full', 'trailer', 'bonus'].includes(String(episodeType))) {
+            throw new Error(`invalid metadata.itunes.episodeType: ${String(episodeType)}`);
+        }
+        itunes = {
+            ...(typeof rec.title === 'string' ? { title: rec.title } : {}),
+            ...(episodeType !== undefined ? { episodeType: episodeType as 'full' | 'trailer' | 'bonus' } : {}),
+            ...(typeof rec.season === 'number' ? { season: rec.season } : {}),
+            ...(typeof rec.episode === 'number' ? { episode: rec.episode } : {}),
+            ...(typeof rec.explicit === 'boolean' ? { explicit: rec.explicit } : {}),
+            ...(typeof rec.block === 'boolean' ? { block: rec.block } : {}),
+        };
+    }
+
+    return {
+        title,
+        contentHtml:
+            showNotes && showNotes.length > 0
+                ? renderShowNotesHtml(showNotes)
+                : content.format === 'html'
+                  ? content.body
+                  : renderShowNotesHtml(content.body),
+        status,
+        audio: audioFile
+            ? { kind: 'file', path: audioFile, mimeType: resolveAudioMimeType(audioFile, metadata.mimeType) }
+            : {
+                  kind: 'url',
+                  url: audioUrl as string,
+                  mimeType: resolveAudioMimeType(audioUrl as string, metadata.mimeType),
+              },
+        durationSeconds: duration as number | undefined,
+        ...(imageUrl ? { imageUrl } : {}),
+        ...(imagePath ? { imagePath } : {}),
+        ...(datePublishedMs !== undefined ? { datePublishedMs } : {}),
+        ...(link ? { link } : {}),
+        ...(itunes !== undefined ? { itunes } : {}),
+    };
+}

package/plugins/publishings/podcast-pub/src/microfeed-client.ts

@@ -0,0 +1,196 @@
+/**
+ * Bearer-authenticated microfeed `/api/v1/` REST client (design D1).
+ * Endpoints pinned to `vendors/microfeed/src/server/api/handlers.ts` +
+ * `src/shared/ApiSchemas.ts`; every 4xx/5xx or transport fault throws a
+ * diagnostic — never silent (R4).
+ */
+
+/** microfeed API responses are `apiItemInputSchema`-shaped loose objects. */
+export type MicrofeedItemInput = Record<string, unknown>;
+/** microfeed item output (`apiItemOutputSchema` shape). */
+export type MicrofeedItem = Record<string, unknown>;
+/** JSON Feed document (`apiFeedSchema` shape) returned by the feed and item-get endpoints. */
+export interface MicrofeedFeed {
+    items?: MicrofeedItem[];
+    [key: string]: unknown;
+}
+
+/** Presigned upload target returned by `POST /api/v1/media_files/presigned_urls`. */
+export interface PreparedUpload {
+    presignedUrl: string;
+    mediaUrl: string;
+}
+
+/** Timeout floor so a zero/negative `MICROFEED_TIMEOUT_MS` cannot hang forever. */
+const MIN_TIMEOUT_MS = 1_000;
+/** Default timeout for large audio uploads (design D4). */
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+export function resolveTimeoutMs(raw: string | undefined): number {
+    const parsed = raw === undefined ? Number.NaN : Number(raw);
+    if (!Number.isFinite(parsed) || parsed < MIN_TIMEOUT_MS) {
+        return DEFAULT_TIMEOUT_MS;
+    }
+    return parsed;
+}
+
+export class MicrofeedClient {
+    private readonly baseUrl: string;
+    private readonly apiKey: string;
+    private readonly timeoutMs: number;
+
+    constructor(baseUrl: string, apiKey: string, timeoutMs: number) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.apiKey = apiKey;
+        this.timeoutMs = timeoutMs;
+    }
+
+    /** Canonical public URL fallback for an item page (`{base}/items/{id}`). */
+    public itemUrl(itemId: string): string {
+        return `${this.baseUrl}/items/${itemId}`;
+    }
+
+    private async request(path: string, init: RequestInit & { body?: string | Uint8Array }): Promise<unknown> {
+        let response: Response;
+        try {
+            response = await fetch(`${this.baseUrl}${path}`, {
+                ...init,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    Origin: this.baseUrl, // Astro CSRF origin check rejects cross-site form-like methods (DELETE/PUT/POST)
+                    ...init.headers,
+                },
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        } catch (error: unknown) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`microfeed transport error (${init.method ?? 'GET'} ${path}): ${reason}`);
+        }
+
+        if (!response.ok) {
+            const text = (await response.text()).slice(0, 1000);
+            let detail = text.trim();
+            try {
+                const parsed = JSON.parse(text) as { error?: unknown };
+                if (typeof parsed.error === 'string') detail = parsed.error;
+            } catch {
+                // keep raw text as the detail
+            }
+            throw new Error(
+                `microfeed API request failed (HTTP ${response.status} ${response.statusText} ${path}): ${detail || 'Unknown error'}`,
+            );
+        }
+
+        try {
+            return await response.json();
+        } catch {
+            throw new Error(`microfeed API returned a non-JSON response from ${path}`);
+        }
+    }
+
+    /** `POST /api/v1/items` → `{id}`; 201 with optional 24h idempotent create (design D3). */
+    public async createItem(input: MicrofeedItemInput, idempotencyKey?: string): Promise<string> {
+        const data = (await this.request('/api/v1/items', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+            },
+            body: JSON.stringify(input),
+        })) as { id?: unknown };
+        if (typeof data.id !== 'string' || data.id.length === 0) {
+            throw new Error('microfeed item create response is missing the item id');
+        }
+        return data.id;
+    }
+
+    /** `POST /api/v1/items/validate` → `{valid: true}`; 400s surface as thrown diagnostics. */
+    public async validateItem(input: MicrofeedItemInput): Promise<void> {
+        await this.request('/api/v1/items/validate', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(input),
+        });
+    }
+
+    /**
+     * `GET /api/v1/items/{itemId}` — returns the JSON Feed document limited to
+     * that item (the endpoint serves the feed shape, items[0] is the item).
+     */
+    public async getItem(itemId: string): Promise<MicrofeedFeed> {
+        return (await this.request(`/api/v1/items/${encodeURIComponent(itemId)}`, {
+            method: 'GET',
+        })) as MicrofeedFeed;
+    }
+
+    /** `PUT /api/v1/items/{itemId}` → the updated public item (includes `url` when live). */
+    public async updateItem(itemId: string, input: MicrofeedItemInput): Promise<MicrofeedItem> {
+        return (await this.request(`/api/v1/items/${encodeURIComponent(itemId)}`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(input),
+        })) as MicrofeedItem;
+    }
+
+    /**
+     * `DELETE /api/v1/items/{itemId}` → `{}` (404s surface as thrown diagnostics).
+     * Sends a JSON Content-Type: Astro 7 checkOrigin 403s non-safe methods without
+     * one when no Origin header is present (task 0087).
+     */
+    public async deleteItem(itemId: string): Promise<void> {
+        await this.request(`/api/v1/items/${encodeURIComponent(itemId)}`, {
+            method: 'DELETE',
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+
+    /** `GET /api/v1/feed` — the full JSON Feed document. */
+    public async listItems(): Promise<MicrofeedFeed> {
+        return (await this.request('/api/v1/feed', { method: 'GET' })) as MicrofeedFeed;
+    }
+
+    /**
+     * `POST /api/v1/media_files/presigned_urls` — audio uploads require `item_id`
+     * (handlers.ts `prepareApiMediaUpload`), so the draft item must exist first (design D2);
+     * image uploads (`category: 'image'`) presign without an item.
+     */
+    public async prepareUpload(input: {
+        category: 'audio' | 'image';
+        full_local_file_path: string;
+        item_id?: string;
+        size?: number;
+        type?: string;
+    }): Promise<PreparedUpload> {
+        const data = (await this.request('/api/v1/media_files/presigned_urls', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(input),
+        })) as { presigned_url?: unknown; media_url?: unknown };
+        if (typeof data.presigned_url !== 'string' || typeof data.media_url !== 'string') {
+            throw new Error('microfeed upload-preparation response is missing presigned_url/media_url');
+        }
+        return { presignedUrl: data.presigned_url, mediaUrl: data.media_url };
+    }
+
+    /** `PUT <presigned_url>` — raw audio bytes, same-origin. */
+    public async uploadBytes(presignedUrl: string, bytes: Uint8Array, mimeType: string): Promise<void> {
+        let response: Response;
+        try {
+            response = await fetch(presignedUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': mimeType },
+                body: bytes,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        } catch (error: unknown) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`microfeed transport error (PUT audio bytes): ${reason}`);
+        }
+        if (!response.ok) {
+            const text = (await response.text()).slice(0, 1000);
+            throw new Error(
+                `microfeed audio upload failed (HTTP ${response.status} ${response.statusText}): ${text.trim() || 'Unknown error'}`,
+            );
+        }
+    }
+}

package/plugins/publishings/podcast-pub/src/show-notes.ts

@@ -0,0 +1,132 @@
+/**
+ * Markdown show-notes → sanitized HTML for microfeed `content_html`
+ * (design D6.1; vendored-source contract: microfeed stores and re-emits
+ * `content_html` verbatim — JSON Feed, RSS `content:encoded`, and the theme
+ * template `{{{content_html}}}` unescaped-insert — and derives `content_text`
+ * by stripping tags, so the field must be HTML, never markdown).
+ *
+ * The plugin's own show-notes dialect is closed (generated by the workflow
+ * show-notes step): `#/##/###` headings, `[text](https://…)` links, `**bold**`,
+ * paragraphs. Everything else is escaped text — sanitize-by-construction: the
+ * input is escaped first, and only the tags this module emits reach the API.
+ */
+
+import type { Doc } from '@gobing-ai/kk-core';
+
+/** Escapes text content and attribute values (`&`, `<`, `>`, `"`). */
+function escapeHtml(value: string): string {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+}
+
+function renderInline(escaped: string): string {
+    let out = '';
+    let rest = escaped;
+    for (;;) {
+        const match = rest.match(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/);
+        if (!match || match.index === undefined) break;
+        out += `${rest.slice(0, match.index)}<a href="${match[2]}" target="_blank" rel="noopener">${match[1]}</a>`;
+        rest = rest.slice(match.index + match[0].length);
+    }
+    return (out + rest).replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+}
+
+/**
+ * Renders show-notes markdown to sanitized HTML.
+ * The leading `# ` heading is dropped: the episode `title` is rendered
+ * separately by the page theme, so keeping it would duplicate the H1.
+ * Input that already looks like HTML (`format: 'html'`) must be passed
+ * through untouched by the caller, not here.
+ */
+export function renderShowNotesHtml(markdown: string): string {
+    const blocks: string[] = [];
+    let paragraph: string[] = [];
+
+    const flush = () => {
+        if (paragraph.length > 0) {
+            blocks.push(`<p>${renderInline(escapeHtml(paragraph.join(' ')))}</p>`);
+            paragraph = [];
+        }
+    };
+
+    for (const rawLine of markdown.split('\n')) {
+        const line = rawLine.trim();
+        if (line.length === 0) {
+            flush();
+            continue;
+        }
+        const heading = line.match(/^(#{1,3})\s+(.*)$/);
+        if (heading) {
+            flush();
+            const tag = heading[1]?.length === 1 ? 'h1' : heading[1]?.length === 2 ? 'h2' : 'h3';
+            if (tag === 'h1' && blocks.length === 0 && paragraph.length === 0) {
+                continue; // drop the duplicate title heading
+            }
+            blocks.push(`<${tag}>${renderInline(escapeHtml(heading[2] ?? ''))}</${tag}>`);
+            continue;
+        }
+        paragraph.push(line);
+    }
+    flush();
+    return blocks.join('\n');
+}
+
+/**
+ * Options for {@link renderShowNotesMarkdown} — the workflow show-notes step's
+ * inputs (`title` = the effective episode title, `vars.title || article.title`
+ * at the call site; `runDate` = the `YYYY-MM-DD` slug prefix).
+ */
+export interface ShowNotesRenderOptions {
+    /** Episode heading, article-link text, and article-URL slug source. */
+    title: string;
+    /** Run date prefixing the article URL slug. */
+    runDate: string;
+    /** Article base URL; defaults to the production site (surfing.salty.vip). */
+    articleBaseUrl?: string;
+}
+
+/**
+ * Renders the episode show-notes markdown from a plan Doc[] — plugin-owned port
+ * of the workflow's inline show-notes bun -e (design L1 R6; the workflow keeps
+ * only the orchestration call). Output dialect: `# title` heading, per-item
+ * `## N. <title>` sections capped at the first two 。！？-terminated sentences,
+ * a `[来源：<label>](<sourceUri>)` link per item, and the full-article footer.
+ * Downstream HTML rendering stays with {@link renderShowNotesHtml}.
+ */
+export function renderShowNotesMarkdown(docs: Doc[], opts: ShowNotesRenderOptions): string {
+    const slugify = (t: string): string => {
+        const s = t
+            .toLowerCase()
+            .replace(/[^\w\s-]/g, '')
+            .trim()
+            .replace(/[\s_]+/g, '-');
+        return s.length > 0 ? s : 'post';
+    };
+    const articleUrl = `${opts.articleBaseUrl ?? 'https://surfing.salty.vip'}/zh/posts/${opts.runDate}-${slugify(opts.title)}`;
+    const sourceLabel = (d: Doc): string => {
+        const m = d.metadata ?? {};
+        if (typeof m.sourceName === 'string' && m.sourceName.trim()) return m.sourceName.trim();
+        try {
+            return new URL(d.sourceUri ?? '').hostname.replace(/^www\./, '');
+        } catch {
+            return '来源';
+        }
+    };
+    const lines: string[] = [`# ${opts.title}`, ''];
+    docs.forEach((d, i) => {
+        const body = (d.body ?? '').trim();
+        const sentences = body
+            .split(/(?<=[。！？])\s*/)
+            .slice(0, 2)
+            .join('');
+        lines.push(
+            `## ${i + 1}. ${d.title ?? `条目 ${i + 1}`}`,
+            '',
+            sentences,
+            '',
+            `[来源：${sourceLabel(d)}](${d.sourceUri ?? ''})`,
+            '',
+        );
+    });
+    lines.push(`详情见本期完整文章：[ ${opts.title} ](${articleUrl})`, '');
+    return lines.join('\n');
+}

package/plugins/publishings/podcast-pub/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "include": ["src", "tests"]
+}