@scalemule/news-publication 0.0.67 → 0.0.68

package/README.md

@@ -305,3 +305,15 @@ The publisher-supplied `PawMark` preserves the approved SVG paths. Hosts may set
 ### Homepage image identity
 
 `NewsItem.visual_identity` is a versioned public identity from the Blog feed. `composeEdition` allocates covers across the entire bounded inventory, gives the selected lead priority, and holds repeated covers as `null` without dropping stories or mutating inputs. Never re-add duplicate images as fallback. Legacy Photo rendition URLs are normalized by tenant/asset ID; server-side Photo identity detects copies under different IDs and ordinary resize/re-encoding/crop variants. Do not fetch or decode images in page components. Preserve existing caption/credit policy. See platform `docs/HOMEPAGE-PHOTO-IDENTITY.md` for storage, rights, concurrency and rollout tests.
+
+### Standard article submission
+
+Server tools and authorized agents use `PublicationArticleClient` from
+`@scalemule/news-publication/article-workflow`. Discover `options()` first;
+require `workflow_version: 1`. Use `submitArticle()` for a private draft plus
+managed photo staging, or `get()` and `save()` for a generation-fenced edit.
+Keep the operation key when resuming. Editorial approval and release remain
+explicit commands; acceptance does not certify scan, image or audio completion.
+The platform contract and a complete example live in
+`docs/news-platform/ARTICLE-WORKFLOW-V1.md` in the ScaleMule meta-repo.
+Do not use direct SQL, S3 paths, base64 bodies or invented media readiness.

package/dist/article-presentation-0d1FiDgA.d.cts

@@ -0,0 +1,21 @@
+/** Declarative presentation resolved by Blog from the article's pinned profile version. */
+type ArticleFormat = "news" | "brief" | "explainer" | "interview" | "opinion" | "photo_essay" | "video_story";
+type ArticleLayout = {
+    id: string;
+    version: number;
+    name: string;
+    renderer: "standard" | "feature" | "portrait";
+    hero_aspect: "landscape" | "portrait" | "square";
+    headline_position: "before_hero" | "after_hero";
+    wide_body: boolean;
+};
+type ArticlePresentation = {
+    format?: ArticleFormat | null;
+    layout: ArticleLayout;
+};
+/** Never turn an arbitrary API field into CSS, HTML, a class name or a URL. */
+declare function articlePresentation(value?: ArticlePresentation | null): ArticlePresentation;
+declare function articleHeroRatio(layout: ArticleLayout): number;
+declare function articleFormatLabel(format?: ArticleFormat | null): string | undefined;
+
+export { type ArticleFormat as A, type ArticlePresentation as a, type ArticleLayout as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };

package/dist/article-presentation-0d1FiDgA.d.ts

@@ -0,0 +1,21 @@
+/** Declarative presentation resolved by Blog from the article's pinned profile version. */
+type ArticleFormat = "news" | "brief" | "explainer" | "interview" | "opinion" | "photo_essay" | "video_story";
+type ArticleLayout = {
+    id: string;
+    version: number;
+    name: string;
+    renderer: "standard" | "feature" | "portrait";
+    hero_aspect: "landscape" | "portrait" | "square";
+    headline_position: "before_hero" | "after_hero";
+    wide_body: boolean;
+};
+type ArticlePresentation = {
+    format?: ArticleFormat | null;
+    layout: ArticleLayout;
+};
+/** Never turn an arbitrary API field into CSS, HTML, a class name or a URL. */
+declare function articlePresentation(value?: ArticlePresentation | null): ArticlePresentation;
+declare function articleHeroRatio(layout: ArticleLayout): number;
+declare function articleFormatLabel(format?: ArticleFormat | null): string | undefined;
+
+export { type ArticleFormat as A, type ArticlePresentation as a, type ArticleLayout as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };

package/dist/article-workflow-client.cjs

@@ -0,0 +1,265 @@
+'use strict';
+
+// src/article-workflow-client.ts
+var ArticleWorkflowError = class extends Error {
+  constructor(message, status, articleId) {
+    super(message);
+    this.status = status;
+    this.articleId = articleId;
+    this.name = "ArticleWorkflowError";
+  }
+  status;
+  articleId;
+};
+var PublicationArticleClient = class {
+  constructor(config) {
+    this.config = config;
+    const url = new URL(config.apiUrl);
+    if (url.protocol !== "https:" && !["localhost", "127.0.0.1"].includes(url.hostname))
+      throw new Error("Use an HTTPS API endpoint");
+    this.base = config.apiUrl.replace(/\/$/, "") + `/v1/blog/publications/${encodeURIComponent(config.publicationId)}`;
+  }
+  config;
+  base;
+  async request(path, method = "GET", body, extra) {
+    const headers = new Headers(extra);
+    headers.set("accept", "application/json");
+    if (this.config.apiKey) headers.set("x-api-key", this.config.apiKey);
+    if (this.config.accessToken)
+      headers.set("authorization", `Bearer ${this.config.accessToken}`);
+    const form = body instanceof FormData;
+    if (body !== void 0 && !form)
+      headers.set("content-type", "application/json");
+    const url = new URL(
+      path.startsWith("/v1/") ? this.config.apiUrl.replace(/\/$/, "") + path : this.base + path
+    );
+    if (this.config.applicationId)
+      url.searchParams.set("application_id", this.config.applicationId);
+    const response = await (this.config.fetch ?? fetch)(url, {
+      method,
+      headers,
+      body: body === void 0 ? void 0 : form ? body : JSON.stringify(body),
+      cache: "no-store",
+      redirect: "error"
+    });
+    const value = await response.json();
+    if (!response.ok || value.success !== true || value.data == null)
+      throw new ArticleWorkflowError(
+        value.error?.message || `Article API returned ${response.status}`,
+        response.status
+      );
+    return value.data;
+  }
+  options(articleId) {
+    return this.request(
+      `/article-workflow/options${articleId ? `?article_id=${encodeURIComponent(articleId)}` : ""}`
+    );
+  }
+  get(articleId) {
+    return this.request(
+      `/articles/${encodeURIComponent(articleId)}/collaboration`
+    );
+  }
+  processing(articleId) {
+    return this.request(`/articles/${encodeURIComponent(articleId)}/processing`);
+  }
+  retryProcessing(articleId, expectedVersion, assetSourceFileId) {
+    return this.request(
+      `/articles/${encodeURIComponent(articleId)}/processing`,
+      "POST",
+      {
+        expected_version: expectedVersion,
+        asset_source_file_id: assetSourceFileId
+      }
+    );
+  }
+  create(key, authorProfileId, document, reviewPolicy = "SUBJECT_APPROVAL_PLUS_EDITOR") {
+    return this.request(
+      "/article-workflow",
+      "POST",
+      {
+        operation: "create",
+        author_profile_id: authorProfileId,
+        document,
+        review_policy: reviewPolicy
+      },
+      { "Idempotency-Key": key }
+    );
+  }
+  save(key, articleId, generation, document, reason = "EDITOR_EDIT") {
+    return this.request(
+      "/article-workflow",
+      "POST",
+      {
+        operation: "save",
+        article_id: articleId,
+        expected_generation: generation,
+        document,
+        reason
+      },
+      { "Idempotency-Key": key }
+    );
+  }
+  command(articleId, generation, action) {
+    return this.request(
+      `/articles/${encodeURIComponent(articleId)}/collaboration`,
+      "POST",
+      { ...action, expected_generation: generation }
+    );
+  }
+  registerPhoto(fileId) {
+    return this.request(
+      `/v1/photos/${this.config.applicationId ? "admin/register" : "register"}`,
+      "POST",
+      {
+        file_id: fileId,
+        content_kind: "article",
+        publication_id: this.config.publicationId,
+        ...this.config.applicationId ? { application_id: this.config.applicationId } : {}
+      }
+    );
+  }
+  upload(articleId, generation, file, filename, metadata) {
+    const body = new FormData();
+    body.set("metadata", JSON.stringify(metadata));
+    body.set("file", file, filename);
+    return this.request(`/articles/${encodeURIComponent(articleId)}/assets`, "POST", body, {
+      "If-Match": String(generation)
+    });
+  }
+  /** One agent operation over existing owners. Stops at conflicts/unknown upload acknowledgement;
+   * replay the same operation key to inspect/reuse staged contributions before another transfer.
+   * Editorial approval and release are always separate explicit operations. */
+  async submitArticle(input) {
+    if (input.document.media?.length)
+      throw new Error(
+        "Pass file assets separately when creating an article package"
+      );
+    const capabilities = await this.options();
+    if (capabilities.workflow_version !== 1)
+      throw new Error("Unsupported article workflow version");
+    if (input.assets?.length && !capabilities.capabilities.managed_private_asset_upload)
+      throw new Error("Managed article upload is not deployed");
+    const created = await this.create(
+      input.operationKey,
+      input.authorProfileId,
+      input.document,
+      input.reviewPolicy
+    );
+    try {
+      const selected = [];
+      for (const asset of input.assets ?? []) {
+        let current = await this.get(created.article_id);
+        const digest = Array.from(
+          new Uint8Array(
+            await crypto.subtle.digest(
+              "SHA-256",
+              await asset.file.arrayBuffer()
+            )
+          )
+        ).map((v) => v.toString(16).padStart(2, "0")).join("");
+        const existing = current.contributions.find(
+          (c) => c.kind === "MEDIA" && c.state !== "REJECTED" && c.state !== "WITHDRAWN" && c.payload.sha256 === digest && Object.entries(asset.metadata).every(
+            ([k, v]) => c.payload[k] === v
+          )
+        );
+        const staged = existing?.payload.file_id ? { contribution_id: existing.id, file_id: existing.payload.file_id } : await this.upload(
+          created.article_id,
+          current.generation,
+          asset.file,
+          asset.filename,
+          asset.metadata
+        );
+        await this.registerPhoto(staged.file_id);
+        if (input.approveMedia) {
+          if (!asset.metadata.rights_confirmed || asset.metadata.private_preview_only)
+            throw new Error("Publication requires confirmed image rights");
+          if (existing?.state !== "APPROVED") {
+            current = await this.get(created.article_id);
+            await this.command(created.article_id, current.generation, {
+              action: "RESOLVE",
+              contribution_id: staged.contribution_id,
+              state: "APPROVED"
+            });
+          }
+          selected.push({
+            kind: "image",
+            contribution_id: staged.contribution_id,
+            file_id: staged.file_id,
+            caption: asset.metadata.caption,
+            credit: asset.metadata.credit,
+            alt: asset.metadata.alt,
+            position: asset.position
+          });
+        }
+      }
+      if (selected.length) {
+        const current = await this.get(created.article_id);
+        const document = { ...input.document, media: selected };
+        const saved = current.revisions.find(
+          (r) => r.id === current.current_revision_id
+        )?.document;
+        if (!saved) throw new Error("Current immutable revision is missing");
+        if (sameDocument(saved, document))
+          return {
+            ...created,
+            revision_id: current.current_revision_id,
+            generation: current.generation,
+            editorial_status: current.status,
+            replayed: true
+          };
+        if (!sameDocument(
+          { ...saved, media: [] },
+          { ...input.document, media: [] }
+        ) || saved.media?.length)
+          throw new ArticleWorkflowError(
+            "The article was edited after this package began; load its current revision before changing it",
+            409,
+            created.article_id
+          );
+        return await this.save(
+          `${input.operationKey}:assets`,
+          created.article_id,
+          current.generation,
+          document,
+          "MEDIA_UPDATE"
+        );
+      }
+      return created;
+    } catch (error) {
+      if (error instanceof ArticleWorkflowError) {
+        error.articleId = created.article_id;
+        throw error;
+      }
+      throw new ArticleWorkflowError(
+        error instanceof Error ? error.message : "Article package interrupted",
+        0,
+        created.article_id
+      );
+    }
+  }
+};
+function sameDocument(a, b) {
+  const canonical = (d) => [
+    d.title,
+    d.subtitle || "",
+    d.content_markdown,
+    d.section,
+    d.community || "",
+    d.format || null,
+    d.layout ? [d.layout.id, d.layout.version] : null,
+    (d.media || []).map((m) => [
+      m.kind || "image",
+      m.contribution_id,
+      m.file_id,
+      m.caption,
+      m.credit,
+      m.alt,
+      m.position
+    ])
+  ];
+  return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+}
+
+exports.ArticleWorkflowError = ArticleWorkflowError;
+exports.PublicationArticleClient = PublicationArticleClient;

package/dist/article-workflow-client.d.cts

@@ -0,0 +1,131 @@
+import { A as ArticleFormat } from './article-presentation-0d1FiDgA.cjs';
+
+type ArticleDocument = {
+    title: string;
+    subtitle?: string;
+    content_markdown: string;
+    section: string;
+    community?: string;
+    format?: ArticleFormat;
+    layout?: {
+        id: string;
+        version: number;
+    };
+    media?: ArticleMedia[];
+};
+type ArticleMedia = {
+    kind?: "image" | "video";
+    contribution_id: string;
+    file_id: string;
+    caption: string;
+    credit: string;
+    alt: string;
+    position: "hero" | "inline" | "gallery" | "attachment";
+};
+type AssetMetadata = {
+    caption: string;
+    credit: string;
+    alt: string;
+    creator: string;
+    who_is_pictured: string;
+    when_taken: string;
+    where_taken: string;
+    rights_confirmed: boolean;
+    private_preview_only?: boolean;
+};
+type ArticleOperation = {
+    article_id: string;
+    revision_id: string;
+    generation: number;
+    editorial_status: string;
+    permalink_path: string;
+    replayed: boolean;
+};
+type Record = {
+    post_id: string;
+    current_revision_id: string;
+    generation: number;
+    status: string;
+    revisions: {
+        id: string;
+        document: ArticleDocument;
+    }[];
+    contributions: {
+        id: string;
+        kind: string;
+        state: string;
+        payload: Partial<AssetMetadata> & {
+            file_id?: string;
+            sha256?: string;
+        };
+    }[];
+};
+declare class ArticleWorkflowError extends Error {
+    status: number;
+    articleId?: string | undefined;
+    constructor(message: string, status: number, articleId?: string | undefined);
+}
+/** Server/CLI client. Credentials belong to the caller and are never embedded in a publication bundle. */
+declare class PublicationArticleClient {
+    private config;
+    private base;
+    constructor(config: {
+        apiUrl: string;
+        publicationId: string;
+        apiKey?: string;
+        accessToken?: string;
+        applicationId?: string;
+        fetch?: typeof fetch;
+    });
+    private request;
+    options(articleId?: string): Promise<{
+        workflow_version: number;
+        formats: string[];
+        layouts: unknown[];
+        capabilities: {
+            managed_private_asset_upload: boolean;
+        };
+    }>;
+    get(articleId: string): Promise<Record>;
+    processing(articleId: string): Promise<{
+        narration: {
+            status: string;
+            error_code?: string;
+        };
+        visual: {
+            status: string;
+        };
+    }>;
+    retryProcessing(articleId: string, expectedVersion: number, assetSourceFileId?: string): Promise<unknown>;
+    create(key: string, authorProfileId: string, document: ArticleDocument, reviewPolicy?: string): Promise<ArticleOperation>;
+    save(key: string, articleId: string, generation: number, document: ArticleDocument, reason?: string): Promise<ArticleOperation>;
+    command(articleId: string, generation: number, action: object): Promise<unknown>;
+    registerPhoto(fileId: string): Promise<{
+        id?: string;
+        status?: string;
+    }>;
+    upload(articleId: string, generation: number, file: Blob, filename: string, metadata: AssetMetadata): Promise<{
+        contribution_id: string;
+        file_id: string;
+        kind: "image";
+        state: "OPEN";
+    }>;
+    /** One agent operation over existing owners. Stops at conflicts/unknown upload acknowledgement;
+     * replay the same operation key to inspect/reuse staged contributions before another transfer.
+     * Editorial approval and release are always separate explicit operations. */
+    submitArticle(input: {
+        operationKey: string;
+        authorProfileId: string;
+        document: ArticleDocument;
+        reviewPolicy?: string;
+        assets?: {
+            file: Blob;
+            filename: string;
+            metadata: AssetMetadata;
+            position: ArticleMedia["position"];
+        }[];
+        approveMedia?: boolean;
+    }): Promise<ArticleOperation>;
+}
+
+export { type ArticleDocument, type ArticleMedia, type ArticleOperation, ArticleWorkflowError, type AssetMetadata, PublicationArticleClient };

package/dist/article-workflow-client.d.ts

@@ -0,0 +1,131 @@
+import { A as ArticleFormat } from './article-presentation-0d1FiDgA.js';
+
+type ArticleDocument = {
+    title: string;
+    subtitle?: string;
+    content_markdown: string;
+    section: string;
+    community?: string;
+    format?: ArticleFormat;
+    layout?: {
+        id: string;
+        version: number;
+    };
+    media?: ArticleMedia[];
+};
+type ArticleMedia = {
+    kind?: "image" | "video";
+    contribution_id: string;
+    file_id: string;
+    caption: string;
+    credit: string;
+    alt: string;
+    position: "hero" | "inline" | "gallery" | "attachment";
+};
+type AssetMetadata = {
+    caption: string;
+    credit: string;
+    alt: string;
+    creator: string;
+    who_is_pictured: string;
+    when_taken: string;
+    where_taken: string;
+    rights_confirmed: boolean;
+    private_preview_only?: boolean;
+};
+type ArticleOperation = {
+    article_id: string;
+    revision_id: string;
+    generation: number;
+    editorial_status: string;
+    permalink_path: string;
+    replayed: boolean;
+};
+type Record = {
+    post_id: string;
+    current_revision_id: string;
+    generation: number;
+    status: string;
+    revisions: {
+        id: string;
+        document: ArticleDocument;
+    }[];
+    contributions: {
+        id: string;
+        kind: string;
+        state: string;
+        payload: Partial<AssetMetadata> & {
+            file_id?: string;
+            sha256?: string;
+        };
+    }[];
+};
+declare class ArticleWorkflowError extends Error {
+    status: number;
+    articleId?: string | undefined;
+    constructor(message: string, status: number, articleId?: string | undefined);
+}
+/** Server/CLI client. Credentials belong to the caller and are never embedded in a publication bundle. */
+declare class PublicationArticleClient {
+    private config;
+    private base;
+    constructor(config: {
+        apiUrl: string;
+        publicationId: string;
+        apiKey?: string;
+        accessToken?: string;
+        applicationId?: string;
+        fetch?: typeof fetch;
+    });
+    private request;
+    options(articleId?: string): Promise<{
+        workflow_version: number;
+        formats: string[];
+        layouts: unknown[];
+        capabilities: {
+            managed_private_asset_upload: boolean;
+        };
+    }>;
+    get(articleId: string): Promise<Record>;
+    processing(articleId: string): Promise<{
+        narration: {
+            status: string;
+            error_code?: string;
+        };
+        visual: {
+            status: string;
+        };
+    }>;
+    retryProcessing(articleId: string, expectedVersion: number, assetSourceFileId?: string): Promise<unknown>;
+    create(key: string, authorProfileId: string, document: ArticleDocument, reviewPolicy?: string): Promise<ArticleOperation>;
+    save(key: string, articleId: string, generation: number, document: ArticleDocument, reason?: string): Promise<ArticleOperation>;
+    command(articleId: string, generation: number, action: object): Promise<unknown>;
+    registerPhoto(fileId: string): Promise<{
+        id?: string;
+        status?: string;
+    }>;
+    upload(articleId: string, generation: number, file: Blob, filename: string, metadata: AssetMetadata): Promise<{
+        contribution_id: string;
+        file_id: string;
+        kind: "image";
+        state: "OPEN";
+    }>;
+    /** One agent operation over existing owners. Stops at conflicts/unknown upload acknowledgement;
+     * replay the same operation key to inspect/reuse staged contributions before another transfer.
+     * Editorial approval and release are always separate explicit operations. */
+    submitArticle(input: {
+        operationKey: string;
+        authorProfileId: string;
+        document: ArticleDocument;
+        reviewPolicy?: string;
+        assets?: {
+            file: Blob;
+            filename: string;
+            metadata: AssetMetadata;
+            position: ArticleMedia["position"];
+        }[];
+        approveMedia?: boolean;
+    }): Promise<ArticleOperation>;
+}
+
+export { type ArticleDocument, type ArticleMedia, type ArticleOperation, ArticleWorkflowError, type AssetMetadata, PublicationArticleClient };