@scalemule/news-publication 0.0.80 → 0.0.82

package/dist/article-workflow-client.js

@@ -10,6 +10,47 @@ function articlePhotoHtmlMatches(html, lead, social) {
   return image && openGraph;
 }
 
+// src/article-edit-verification.ts
+var decode = (value) => value.replace(/&(?:amp|lt|gt|quot|apos|#39|#\d+|#x[\da-f]+);/giu, (s) => {
+  const named = {
+    "&": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&apos;": "'",
+    "&#39;": "'"
+  };
+  if (named[s.toLowerCase()]) return named[s.toLowerCase()];
+  const hex = s.toLowerCase().startsWith("&#x");
+  const n = parseInt(s.slice(hex ? 3 : 2, -1), hex ? 16 : 10);
+  return Number.isFinite(n) && n >= 0 && n <= 1114111 ? String.fromCodePoint(n) : s;
+});
+var text = (html) => decode(html.replace(/<[^>]*>/gu, " ")).replace(/\s+/gu, " ").trim();
+var plain = (value) => value.replace(/\s+/gu, " ").trim();
+function articleEditHtmlMatches(html, expected) {
+  const visible = html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/giu, " ").replace(/<style\b[^>]*>[\s\S]*?<\/style>/giu, " ");
+  const headline = [...visible.matchAll(/<h1\b[^>]*>([\s\S]*?)<\/h1>/giu)].some(
+    (m) => text(m[1]) === plain(expected.title)
+  );
+  if (!headline) return false;
+  const paragraphs = [
+    ...expected.content_html.matchAll(
+      /<(p|li|h[2-6]|blockquote)\b[^>]*>([\s\S]*?)<\/\1>/giu
+    )
+  ].map((m) => text(m[2])).filter(Boolean);
+  const all = text(visible);
+  if (!paragraphs.length || !paragraphs.every((p) => all.includes(p)))
+    return false;
+  const titles = [
+    ...visible.matchAll(
+      /<aside\b[^>]*class=["'][^"']*\barticle-verified-card\b[^"']*["'][^>]*>([\s\S]*?)<\/aside>/giu
+    )
+  ].flatMap(
+    (m) => [...m[1].matchAll(/<h2\b[^>]*>([\s\S]*?)<\/h2>/giu)].map((m2) => text(m2[1]))
+  );
+  return JSON.stringify(titles.sort()) === JSON.stringify(expected.card_titles.map(plain).sort());
+}
+
 // src/article-photo-operation.ts
 var ArticlePhotoOperationError = class extends Error {
   constructor(code, stage, message, fileId, status) {
@@ -285,6 +326,325 @@ async function runArticlePhoto(t, input) {
   }
 }
 
+// src/article-edit-operation.ts
+var ArticleEditOperationError = class extends Error {
+  constructor(code, stage, message, status, revisionId) {
+    super(message);
+    this.code = code;
+    this.stage = stage;
+    this.status = status;
+    this.revisionId = revisionId;
+    this.name = "ArticleEditOperationError";
+  }
+  code;
+  stage;
+  status;
+  revisionId;
+};
+var canonical2 = (v) => Array.isArray(v) ? v.map(canonical2) : v && typeof v === "object" ? Object.fromEntries(
+  Object.keys(v).sort().map((k) => [k, canonical2(v[k])])
+) : v;
+var equal = (a, b) => JSON.stringify(canonical2(a)) === JSON.stringify(canonical2(b));
+var digest2 = async (v) => [
+  ...new Uint8Array(
+    await crypto.subtle.digest(
+      "SHA-256",
+      new TextEncoder().encode(JSON.stringify(canonical2(v)))
+    )
+  )
+].map((v2) => v2.toString(16).padStart(2, "0")).join("");
+var patchKeys = /* @__PURE__ */ new Set([
+  "title",
+  "subtitle",
+  "content_markdown",
+  "excerpt",
+  "section",
+  "community",
+  "format",
+  "layout",
+  "cards",
+  "citations"
+]);
+function validate(input) {
+  if (!input.operationKey || !/^[\w.:-]{1,128}$/u.test(input.operationKey) || !input.articleId || !input.patch || typeof input.patch !== "object" || Array.isArray(input.patch) || !Object.keys(input.patch).length)
+    throw Error(
+      "Supply an article, stable operation key and nonempty editorial patch"
+    );
+  for (const [key, value] of Object.entries(input.patch)) {
+    if (!patchKeys.has(key)) throw Error("Unsupported edit field: " + key);
+    if (["cards", "citations"].includes(key)) {
+      if (!Array.isArray(value)) throw Error(key + " must be an array");
+    } else if (key === "layout") {
+      if (!value || typeof value !== "object" || typeof value.id !== "string" || !Number.isInteger(value.version))
+        throw Error("Select an existing versioned layout");
+    } else if (typeof value !== "string")
+      throw Error(key + " must be a string");
+  }
+  if (input.expectedGeneration !== void 0 && (!Number.isSafeInteger(input.expectedGeneration) || input.expectedGeneration < 1))
+    throw Error("Expected generation must be positive");
+  if (input.enableReviewPolicy && ![
+    "NONE",
+    "FACT_CHECK",
+    "CONTRIBUTOR_REVIEW",
+    "SUBJECT_APPROVAL_REQUIRED",
+    "SUBJECT_APPROVAL_PLUS_EDITOR"
+  ].includes(input.enableReviewPolicy))
+    throw Error("Select an explicit supported review policy");
+  if (new TextEncoder().encode(JSON.stringify(input.patch)).length > 128 * 1024)
+    throw Error("Editorial patch exceeds 128 KiB");
+}
+async function runArticleEdit(t, input) {
+  validate(input);
+  const started = performance.now();
+  let stage = "preflight";
+  const timeout = input.timeoutMs ?? 1e4;
+  if (!Number.isFinite(timeout) || timeout < 100 || timeout > 12e4)
+    throw Error("Edit deadline must be between 100 and 120000 milliseconds");
+  const signal = AbortSignal.timeout(timeout);
+  const request = (path, method, body, extra) => t.request(path, method, body, extra, signal);
+  const identity = await digest2([
+    t.publicationId,
+    input.articleId,
+    input.operationKey,
+    input.patch,
+    input.expectedGeneration ?? null,
+    input.enableReviewPolicy ?? null
+  ]);
+  if (input.checkpoint && (input.checkpoint.version !== 1 || input.checkpoint.identity !== identity || input.checkpoint.articleId !== input.articleId))
+    throw new ArticleEditOperationError(
+      "OPERATION_CONFLICT",
+      "validation",
+      "This checkpoint belongs to different input; reuse its original patch and operation key"
+    );
+  let state = input.checkpoint ? structuredClone(input.checkpoint) : { version: 1, identity, articleId: input.articleId, stage };
+  const save = async (next) => {
+    stage = next;
+    state.stage = next;
+    await input.saveCheckpoint(structuredClone(state));
+  };
+  const article = "/articles/" + encodeURIComponent(input.articleId);
+  const currentRevision = (record) => record.revisions?.find((v) => v.id === record.current_revision_id);
+  const identityOf = (post) => ({
+    slug: post.slug,
+    published_at: post.published_at ?? null,
+    canonical_url: post.canonical_url ?? null
+  });
+  const identityMatches = (post) => !state.sourceIdentity || state.sourceIdentity.slug === post.slug && (state.sourceIdentity.published_at === null || state.sourceIdentity.published_at === (post.published_at ?? null)) && (state.sourceIdentity.canonical_url === null || state.sourceIdentity.canonical_url === (post.canonical_url ?? null));
+  const result = (record, status) => ({
+    article_id: input.articleId,
+    revision_id: state.revisionId ?? record.current_revision_id,
+    generation: record.generation,
+    state: status,
+    editorial_status: record.status,
+    elapsed_ms: Math.round(performance.now() - started)
+  });
+  try {
+    const [options, source, initial] = await Promise.all([
+      request(
+        "/article-workflow/options?article_id=" + encodeURIComponent(input.articleId)
+      ),
+      request(article + "/document"),
+      request(article + "/collaboration").catch((error) => {
+        if (error.status === 404 && error.message === "Story collaboration is not enabled")
+          return null;
+        throw error;
+      })
+    ]);
+    if (options.workflow_version !== 1 || options.capabilities?.versioned_editorial_fields !== true)
+      throw new ArticleEditOperationError(
+        "CAPABILITY_UNAVAILABLE",
+        stage,
+        "The server must expose versioned_editorial_fields before this edit; no article was changed"
+      );
+    if (!identityMatches(source))
+      throw new ArticleEditOperationError(
+        "ARTICLE_IDENTITY_CHANGED",
+        stage,
+        "Article URL, publication date or canonical identity changed; inspect before continuing"
+      );
+    state.sourceIdentity ??= identityOf(source);
+    let record = initial;
+    if (!record) {
+      if (!input.enableReviewPolicy)
+        throw new ArticleEditOperationError(
+          "ENROLLMENT_REQUIRED",
+          stage,
+          "Legacy article: choose an explicit review policy for versioned editorial onboarding; no content was changed"
+        );
+      if (source.status === "scheduled")
+        throw new ArticleEditOperationError(
+          "SCHEDULED_ARTICLE",
+          stage,
+          "Onboarding cancels an old schedule; handle this scheduled article explicitly"
+        );
+      await save("enroll");
+      await request(article + "/collaboration/enable", "POST", {
+        review_policy: input.enableReviewPolicy
+      });
+      record = await request(article + "/collaboration");
+    }
+    if (state.revisionId) {
+      if (record.current_revision_id !== state.revisionId)
+        throw new ArticleEditOperationError(
+          "ARTICLE_CHANGED",
+          stage,
+          "Another revision is current; this operation cannot release or overwrite it",
+          409,
+          state.revisionId
+        );
+      const selected = currentRevision(record);
+      if (!selected || !equal(selected.document, state.document))
+        throw new ArticleEditOperationError(
+          "VERIFICATION_CONFLICT",
+          stage,
+          "The saved revision differs from this operation",
+          409,
+          state.revisionId
+        );
+    } else {
+      if (!state.document) {
+        if (input.expectedGeneration !== void 0 && record.generation !== input.expectedGeneration)
+          throw new ArticleEditOperationError(
+            "ARTICLE_CHANGED",
+            stage,
+            "The article generation changed; reload before applying this patch",
+            409
+          );
+        const selected = currentRevision(record);
+        if (!selected?.complete_snapshot && selected?.complete_snapshot !== void 0)
+          throw new ArticleEditOperationError(
+            "INCOMPLETE_REVISION",
+            stage,
+            "Inspect this historical revision before editing"
+          );
+        if (!selected?.document)
+          throw Error("Current immutable article document is missing");
+        const effective = { ...selected.document };
+        for (const key of ["cards", "citations"])
+          if (effective[key] === void 0 && selected.editorial_metadata?.[key] !== void 0)
+            effective[key] = selected.editorial_metadata[key];
+        if (effective.excerpt === void 0 && source.excerpt !== null && source.excerpt !== void 0)
+          effective.excerpt = source.excerpt;
+        const changed = Object.entries(input.patch).some(
+          ([key, value]) => !equal(effective[key], value)
+        );
+        if (!changed) {
+          state.document = selected.document;
+          state.revisionId = record.current_revision_id;
+          state.savedGeneration = record.generation;
+          state.unchanged = true;
+          await save("verify");
+          if (!input.release) return result(record, "unchanged");
+        } else {
+          const document = { ...selected.document, ...input.patch };
+          if (document.excerpt === void 0 && source.excerpt !== null && source.excerpt !== void 0)
+            document.excerpt = source.excerpt;
+          state.document = document;
+          state.expectedGeneration = record.generation;
+          await save("save");
+        }
+      }
+      if (!state.revisionId) {
+        const saved = await request(
+          "/article-workflow",
+          "POST",
+          {
+            operation: "save",
+            article_id: input.articleId,
+            expected_generation: state.expectedGeneration,
+            document: state.document,
+            reason: state.sourceIdentity?.published_at ? "POST_PUBLICATION_CORRECTION" : "EDITOR_EDIT"
+          },
+          { "Idempotency-Key": input.operationKey }
+        );
+        state.revisionId = saved.revision_id;
+        state.savedGeneration = saved.generation;
+        await save("verify");
+        record = await request(article + "/collaboration");
+        if (record.current_revision_id !== state.revisionId || !equal(currentRevision(record)?.document, state.document))
+          throw new ArticleEditOperationError(
+            "ARTICLE_CHANGED",
+            stage,
+            "A different revision is current; no release was attempted",
+            409,
+            state.revisionId
+          );
+      }
+    }
+    if (record.published_revision_id === state.revisionId) {
+      await save("published");
+      return result(record, "already_published");
+    }
+    if (!input.release) {
+      await save("saved");
+      return result(record, state.unchanged ? "unchanged" : "saved_for_review");
+    }
+    await save("release");
+    try {
+      await request(article + "/collaboration", "POST", {
+        action: "RELEASE",
+        expected_generation: record.generation,
+        scheduled_at: null
+      });
+    } catch (error) {
+      const checked = await request(article + "/collaboration");
+      if (checked.published_revision_id === state.revisionId && checked.current_revision_id === state.revisionId) {
+        record = checked;
+      } else throw error;
+    }
+    record = await request(article + "/collaboration");
+    if (record.current_revision_id !== state.revisionId || record.published_revision_id !== state.revisionId)
+      throw new ArticleEditOperationError(
+        "VERIFICATION_CONFLICT",
+        stage,
+        "This exact revision has not been confirmed published",
+        409,
+        state.revisionId
+      );
+    const after = await request(article + "/document");
+    if (!identityMatches(after))
+      throw new ArticleEditOperationError(
+        "ARTICLE_IDENTITY_CHANGED",
+        stage,
+        "The release changed a permanent article identity",
+        409,
+        state.revisionId
+      );
+    for (const key of ["title", "subtitle", "content_markdown", "excerpt"])
+      if (state.document?.[key] !== void 0 && !equal(after[key] ?? "", state.document[key]))
+        throw new ArticleEditOperationError(
+          "VERIFICATION_CONFLICT",
+          stage,
+          "Public article field differs after release: " + key,
+          409,
+          state.revisionId
+        );
+    const normalizedCards = state.document?.cards;
+    if (normalizedCards && after.metadata?.cards?.length !== normalizedCards.length)
+      throw new ArticleEditOperationError(
+        "VERIFICATION_CONFLICT",
+        stage,
+        "Public card count differs from the saved revision",
+        409,
+        state.revisionId
+      );
+    await save("published");
+    return result(record, "published");
+  } catch (error) {
+    if (error instanceof ArticleEditOperationError) throw error;
+    const status = error?.status;
+    const message = error instanceof Error ? error.message : "Article edit failed";
+    const code = signal.aborted ? "DEADLINE_EXCEEDED" : status === 401 || status === 403 ? "PERMISSION_DENIED" : status === 409 && stage === "release" ? "RELEASE_HELD" : status === 409 ? "ARTICLE_CHANGED" : "STEP_FAILED";
+    throw new ArticleEditOperationError(
+      code,
+      stage,
+      signal.aborted ? "Edit reached its deadline; resume the same patch, operation key and checkpoint. Success was not asserted." : message,
+      status,
+      state.revisionId
+    );
+  }
+}
+
 // src/article-workflow-client.ts
 var ArticleWorkflowError = class extends Error {
   constructor(message, status, articleId) {
@@ -341,6 +701,9 @@ var PublicationArticleClient = class {
       `/article-workflow/options${articleId ? `?article_id=${encodeURIComponent(articleId)}` : ""}`
     );
   }
+  publicArticle(slug, signal) {
+    return this.request("/article-content/" + encodeURIComponent(slug), void 0, void 0, void 0, signal);
+  }
   /** Explicit approver-authorized onboarding for a legacy article; never called by get().
    * Existing schedules are cancelled by the server; public content remains unchanged.
    * Missing immutable media identities must be resolved through newsroom media controls.
@@ -369,6 +732,10 @@ var PublicationArticleClient = class {
   uploadAndReplacePublishedCover(input) {
     return runArticlePhoto({ publicationId: this.config.publicationId, apiUrl: this.config.apiUrl, fetch: this.config.fetch ?? fetch, request: this.request.bind(this) }, input);
   }
+  /** Save one exact revision; release is explicit and never manufactures approval. */
+  editArticle(input) {
+    return runArticleEdit({ publicationId: this.config.publicationId, request: this.request.bind(this) }, input);
+  }
   /** Replace a legacy publication cover using ready, measured public Photo renditions.
    * This never enrolls a story, publishes text, creates narration or retries a conflict.
    * Collaboration-managed stories retain their server-enforced immutable revision workflow.
@@ -531,138 +898,34 @@ var PublicationArticleClient = class {
       "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 digest2 = 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 === digest2 && 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
-      );
-    }
+  /** One server-owned submission. No client-side Photo/TTS orchestration and no
+   * fallback to a different workflow. A 202 receipt is acceptance, not readiness.
+   * Replay the identical manifest/files/key after an uncertain acknowledgement.
+   */
+  submit(manifest, operationKey, files = [], signal) {
+    if (!operationKey) throw new Error("A stable operation key is required");
+    if (files.length > 10 || files.some((f) => f.file.size < 1 || f.file.size > 25 * 1024 * 1024) || files.reduce((n, f) => n + f.file.size, 0) > 50 * 1024 * 1024) throw new Error("Supply up to ten photographs, at most 25 MiB each and 50 MiB total");
+    const slots = new Set(files.map((f) => f.slot));
+    if (slots.size !== files.length || files.length !== (manifest.assets?.length ?? 0) || manifest.assets?.some((a) => !slots.has(a.slot))) throw new Error("Supply one file for each declared asset slot");
+    if (!files.length) return this.request("/submissions", "POST", manifest, { "Idempotency-Key": operationKey }, signal);
+    const form = new FormData();
+    form.append("manifest", JSON.stringify(manifest));
+    for (const asset of files) form.append(asset.slot, asset.file, asset.filename);
+    return this.request("/submissions", "POST", form, { "Idempotency-Key": operationKey }, signal);
+  }
+  submission(submissionId, signal) {
+    return this.request("/submissions/" + encodeURIComponent(submissionId), "GET", void 0, void 0, signal);
+  }
+  submitArticle(input) {
+    if (input.document.media?.length) throw new Error("Pass file assets separately when creating an article package");
+    const assets = (input.assets ?? []).map((a, i) => ({ ...a, slot: "asset_" + String.fromCharCode(97 + i) }));
+    return this.submit({
+      article: { operation: "create", author_profile_id: input.authorProfileId, document: input.document, review_policy: input.reviewPolicy },
+      intent: input.intent ?? "draft",
+      approve_media: input.approveMedia,
+      assets: assets.map((a) => ({ slot: a.slot, position: a.position, metadata: a.metadata }))
+    }, input.operationKey, assets);
   }
 };
-function sameDocument(a, b) {
-  const canonical2 = (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(canonical2(a)) === JSON.stringify(canonical2(b));
-}
 
-export { ArticlePhotoOperationError, ArticleWorkflowError, PublicationArticleClient, articlePhotoHtmlMatches };
+export { ArticleEditOperationError, ArticlePhotoOperationError, ArticleWorkflowError, PublicationArticleClient, articleEditHtmlMatches, articlePhotoHtmlMatches };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalemule/news-publication",
-  "version": "0.0.80",
+  "version": "0.0.82",
   "description": "Shared server framework for ScaleMule local news publications. Walnut Creek Times is the broadsheet default; each paper supplies its own identity and feature flags.",
   "type": "module",
   "bin": {