@scalemule/news-publication 0.0.75 → 0.0.76

package/README.md

@@ -337,3 +337,33 @@ 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.
+
+### Replace an existing, prepared cover
+
+For a legacy published article and an already public, scanned Photo asset,
+use `client.replacePublishedCover(...)` or the included executable:
+
+```sh
+scalemule-article inspect --publication "$PUBLICATION_ID" --article "$ARTICLE_ID"
+scalemule-article replace-cover --publication "$PUBLICATION_ID" --article "$ARTICLE_ID" \
+  --file-id "$PHOTO_FILE_ID" --expected-version "$VERSION" --metadata photo.json
+```
+
+Use normal `SCALEMULE_API_KEY` and `SCALEMULE_ACCESS_TOKEN` authorization.
+`inspect` reports the public-projection version and whether collaboration is
+enabled, without logging draft text or review capabilities. The metadata file
+records caption, credit, factual alt text, `rightsConfirmed`, `aiGenerated` and
+the internal provenance `label` (null for an ordinary photograph).
+
+The replacement reads measured hero/social manifests and makes one version-fenced
+media write. A missing social rendition gets one normal Photo transform request
+and a fresh measured metadata lookup; pending work stops without polling forever.
+It never invents dimensions or delivery URLs, uploads another copy,
+restarts narration, republishes text or silently enrolls a story. Missing or
+incomplete Photo renditions leave the existing cover unchanged; inspect and
+resume with the same asset. Collaboration-managed stories retain their exact
+revision approval/release requirements and the server rejects this legacy path.
+This helper does not source or ingest a new photograph. Use managed asset intake
+for that phase, preserving source rights and private capture information.
+Reported elapsed time covers the API operation; verify the real public page and
+homepage allocation separately before claiming the replacement is visible.

package/bin/scalemule-article.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { PublicationArticleClient } from '../dist/article-workflow-client.js';
+
+const help = `Usage:
+  scalemule-article inspect --publication ID --article ID
+  scalemule-article replace-cover --publication ID --article ID --file-id ID --expected-version N --metadata photo.json
+
+Credentials: SCALEMULE_API_KEY and SCALEMULE_ACCESS_TOKEN (normal authorized member).
+Platform admins may use their normal access token with --application-id ID.
+Optional --api-url URL defaults to https://api.scalemule.com.
+
+replace-cover selects an already public, scanned Photo asset. It reads measured
+hero and social renditions, preserves the article text, and changes media with
+the supplied version fence. It never uploads raw bytes, republishes the story,
+starts narration, or silently enrolls a legacy story into collaboration.
+Collaboration-managed articles must use their immutable review/release workflow.
+
+photo.json: { "caption": "...", "credit": "...", "alt": "...",
+  "rightsConfirmed": true, "aiGenerated": false, "label": null }
+Optional metadata: focalPoint, socialRenditionKey (a Photo metadata lookup key).
+The label is internal provenance, subject to each publication's caption policy.
+Pending scan/renditions stop without changing the existing cover. Inspect the
+same asset instead of uploading again. Output records API timing, not a claim
+that every website/CDN cache already displays the new image.
+`;
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true, strict: true,
+    options: Object.fromEntries(['publication', 'article', 'file-id', 'expected-version', 'metadata', 'application-id', 'api-url'].map(k => [k, { type: 'string' }]).concat([['help', { type: 'boolean' }]])),
+  });
+  if (values.help || !positionals.length) {
+    console.log(help);
+  } else {
+    const [command, ...extra] = positionals;
+    if (extra.length || !['inspect', 'replace-cover'].includes(command)) throw Error('Use inspect or replace-cover; see --help');
+    for (const key of ['publication', 'article']) if (!values[key]) throw Error(`Missing --${key}`);
+    if (!process.env.SCALEMULE_ACCESS_TOKEN) throw Error('SCALEMULE_ACCESS_TOKEN is required; use normal member or platform admin authorization');
+    if (!values['application-id'] && !process.env.SCALEMULE_API_KEY) throw Error('Member calls also require SCALEMULE_API_KEY');
+    const client = new PublicationArticleClient({
+      apiUrl: values['api-url'] ?? 'https://api.scalemule.com',
+      publicationId: values.publication,
+      applicationId: values['application-id'],
+      apiKey: process.env.SCALEMULE_API_KEY,
+      accessToken: process.env.SCALEMULE_ACCESS_TOKEN,
+    });
+    const started = performance.now();
+    if (command === 'inspect') {
+      const [options, processing, collaboration] = await Promise.all([
+        client.options(values.article), client.processing(values.article),
+        client.get(values.article).then(current => ({ enabled: true, generation: current.generation, status: current.status })).catch(error => {
+          if (error.status === 404 && error.message === 'Story collaboration is not enabled') return { enabled: false };
+          throw error;
+        }),
+      ]);
+      console.log(JSON.stringify({
+        article_id: processing.article_id, version: processing.version,
+        publication_status: processing.publication_status,
+        workflow_version: options.workflow_version, profile_version: options.profile_version,
+        capabilities: options.capabilities, narration: processing.narration,
+        assets: processing.assets, collaboration, elapsed_ms: Math.round(performance.now() - started),
+      }, null, 2));
+    } else {
+      for (const key of ['file-id', 'expected-version', 'metadata']) if (!values[key]) throw Error(`Missing --${key}`);
+      const metadata = JSON.parse(await readFile(values.metadata, 'utf8'));
+      for (const key of ['caption', 'credit', 'alt']) if (typeof metadata[key] !== 'string') throw Error(`photo.json requires a string ${key}`);
+      if (typeof metadata.aiGenerated !== 'boolean' || !(metadata.label === null || typeof metadata.label === 'string')) throw Error('photo.json must explicitly record aiGenerated and label');
+      const result = await client.replacePublishedCover({
+        articleId: values.article, expectedVersion: Number(values['expected-version']),
+        fileId: values['file-id'], caption: metadata.caption, credit: metadata.credit,
+        alt: metadata.alt, rightsConfirmed: metadata.rightsConfirmed,
+        aiGenerated: metadata.aiGenerated, label: metadata.label,
+        focalPoint: metadata.focalPoint, socialRenditionKey: metadata.socialRenditionKey,
+      });
+      console.log(JSON.stringify({ article_id: result.post_id, version: result.version, state: 'cover_updated', elapsed_ms: Math.round(performance.now() - started) }, null, 2));
+    }
+  }
+} catch (error) {
+  console.error(JSON.stringify({ error: error.message, status: error.status }));
+  process.exitCode = 1;
+}

package/dist/article-workflow-client.cjs

@@ -77,6 +77,87 @@ var PublicationArticleClient = class {
       `/articles/${encodeURIComponent(articleId)}/processing`
     );
   }
+  /** 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.
+   */
+  async replacePublishedCover(input) {
+    if (!Number.isSafeInteger(input.expectedVersion) || input.expectedVersion < 1)
+      throw new Error("Use the current public-projection version from processing()");
+    if (input.rightsConfirmed !== true || !input.alt.trim())
+      throw new Error("Confirm publication rights and supply factual image alt text");
+    if (input.aiGenerated && !input.label?.trim())
+      throw new Error("Generated art requires its internal provenance label");
+    const focal = input.focalPoint ?? { x: 0.5, y: 0.5 };
+    if (![focal.x, focal.y].every((v) => Number.isFinite(v) && v >= 0 && v <= 1))
+      throw new Error("Focal point must be within the image");
+    const photo = `/v1/photos/public/${encodeURIComponent(input.fileId)}/manifest`;
+    const socialKey = input.socialRenditionKey ?? "w1200_h630_cover_q85_jpeg";
+    const socialPath = `${photo}?rendition=${encodeURIComponent(socialKey)}`;
+    const [current, hero, initialSocial] = await Promise.all([
+      this.processing(input.articleId),
+      this.request(`${photo}?preset=hero`),
+      this.request(socialPath)
+    ]);
+    if (current.publication_status !== "published" || current.version !== input.expectedVersion)
+      throw new ArticleWorkflowError("Article is not published or its version changed; reload before updating its cover", 409, input.articleId);
+    let social = initialSocial;
+    if (hero.ready && [hero.file_id, hero.photo_id].includes(input.fileId) && !social.ready && social.file_id === hero.file_id) {
+      const spec = /^w(\d+)_h(\d+)_(cover|contain|fill|scaledown)_q(\d+)_(jpeg|webp|avif)$/.exec(socialKey);
+      if (spec && Number(spec[1]) > 0 && Number(spec[1]) <= 12e3 && Number(spec[2]) > 0 && Number(spec[2]) <= 12e3 && Number(spec[4]) > 0 && Number(spec[4]) <= 100) {
+        const query = new URLSearchParams({ width: spec[1], height: spec[2], fit: spec[3], quality: spec[4], format: spec[5] });
+        const url = new URL(this.config.apiUrl.replace(/\/$/, "") + `/v1/photos/public/${encodeURIComponent(input.fileId)}/transform?${query}`);
+        const response = await (this.config.fetch ?? fetch)(url, { method: "GET", redirect: "manual", cache: "no-store", signal: AbortSignal.timeout(3e4) });
+        const accepted = response.ok && response.headers.get("content-type")?.startsWith("image/") || [302, 303, 307, 308].includes(response.status);
+        await response.body?.cancel();
+        if (accepted) social = await this.request(socialPath);
+      }
+    }
+    const dimension = (v) => Number.isInteger(v) && Number(v) > 0 && Number(v) <= 12e3;
+    const publicUrl = (raw) => {
+      try {
+        const url = new URL(raw);
+        return url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash;
+      } catch {
+        return false;
+      }
+    };
+    const variants = Object.values(hero.variant_metadata ?? {});
+    if (!hero.ready || !social.ready || !hero.file_id || ![hero.file_id, hero.photo_id].includes(input.fileId) || social.file_id !== hero.file_id || !variants.length || variants.length > 20 || variants.some((v) => !dimension(v.width) || !dimension(v.height) || !publicUrl(v.url) || !["jpeg", "webp", "avif"].includes(v.format)) || !dimension(social.width) || !dimension(social.height) || !social.url || !publicUrl(social.url))
+      throw new ArticleWorkflowError("Public Photo renditions are not ready with measured dimensions; inspect Photo processing, keep the existing cover and resume with the same asset", 409, input.articleId);
+    const ordered = [...variants].sort((a, b) => a.width - b.width);
+    const master = [...ordered].reverse().find((v) => v.width <= 1600) ?? ordered[0];
+    return this.request(
+      `/articles/${encodeURIComponent(input.articleId)}/media`,
+      "PUT",
+      {
+        expected_version: input.expectedVersion,
+        cover_image_url: master.url,
+        og_image_url: social.url,
+        cover_image: {
+          file_id: hero.file_id,
+          master_url: master.url,
+          width: master.width,
+          height: master.height,
+          aspect_ratio: `${master.width}:${master.height}`,
+          alt: input.alt,
+          caption: input.caption,
+          attribution: input.credit,
+          ai_generated: input.aiGenerated,
+          label: input.label,
+          focal_point: focal,
+          variants
+        },
+        open_graph_image: {
+          file_id: hero.file_id,
+          url: social.url,
+          width: social.width,
+          height: social.height,
+          aspect_ratio: `${social.width}:${social.height}`
+        }
+      }
+    );
+  }
   /** Existing private narration path for a saved revision and a before-publication audio policy. */
   narrateRevision(articleId, expectedGeneration) {
     return this.request(

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

@@ -33,6 +33,24 @@ type AssetMetadata = {
     rights_confirmed: boolean;
     private_preview_only?: boolean;
 };
+type PublishedCoverReplacement = {
+    articleId: string;
+    expectedVersion: number;
+    /** A real, already public Photo/Storage ID, never an invented ID or URL. */
+    fileId: string;
+    rightsConfirmed: boolean;
+    caption: string;
+    credit: string;
+    alt: string;
+    aiGenerated: boolean;
+    label: string | null;
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Metadata lookup key only; no rendition URL or dimensions are inferred. */
+    socialRenditionKey?: string;
+};
 type ArticleProcessing = {
     article_id: string;
     version: number;
@@ -145,6 +163,16 @@ declare class PublicationArticleClient {
     }>;
     get(articleId: string): Promise<Record>;
     processing(articleId: string): Promise<ArticleProcessing>;
+    /** 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.
+     */
+    replacePublishedCover(input: PublishedCoverReplacement): Promise<{
+        post_id: string;
+        version: number;
+        cover_image_url: string;
+        og_image_url: string;
+    }>;
     /** Existing private narration path for a saved revision and a before-publication audio policy. */
     narrateRevision(articleId: string, expectedGeneration: number): Promise<{
         status: string;
@@ -185,4 +213,4 @@ declare class PublicationArticleClient {
     }): Promise<ArticleOperation>;
 }
 
-export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, PublicationArticleClient };
+export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, PublicationArticleClient, type PublishedCoverReplacement };

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

@@ -33,6 +33,24 @@ type AssetMetadata = {
     rights_confirmed: boolean;
     private_preview_only?: boolean;
 };
+type PublishedCoverReplacement = {
+    articleId: string;
+    expectedVersion: number;
+    /** A real, already public Photo/Storage ID, never an invented ID or URL. */
+    fileId: string;
+    rightsConfirmed: boolean;
+    caption: string;
+    credit: string;
+    alt: string;
+    aiGenerated: boolean;
+    label: string | null;
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Metadata lookup key only; no rendition URL or dimensions are inferred. */
+    socialRenditionKey?: string;
+};
 type ArticleProcessing = {
     article_id: string;
     version: number;
@@ -145,6 +163,16 @@ declare class PublicationArticleClient {
     }>;
     get(articleId: string): Promise<Record>;
     processing(articleId: string): Promise<ArticleProcessing>;
+    /** 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.
+     */
+    replacePublishedCover(input: PublishedCoverReplacement): Promise<{
+        post_id: string;
+        version: number;
+        cover_image_url: string;
+        og_image_url: string;
+    }>;
     /** Existing private narration path for a saved revision and a before-publication audio policy. */
     narrateRevision(articleId: string, expectedGeneration: number): Promise<{
         status: string;
@@ -185,4 +213,4 @@ declare class PublicationArticleClient {
     }): Promise<ArticleOperation>;
 }
 
-export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, PublicationArticleClient };
+export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, PublicationArticleClient, type PublishedCoverReplacement };

package/dist/article-workflow-client.js

@@ -75,6 +75,87 @@ var PublicationArticleClient = class {
       `/articles/${encodeURIComponent(articleId)}/processing`
     );
   }
+  /** 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.
+   */
+  async replacePublishedCover(input) {
+    if (!Number.isSafeInteger(input.expectedVersion) || input.expectedVersion < 1)
+      throw new Error("Use the current public-projection version from processing()");
+    if (input.rightsConfirmed !== true || !input.alt.trim())
+      throw new Error("Confirm publication rights and supply factual image alt text");
+    if (input.aiGenerated && !input.label?.trim())
+      throw new Error("Generated art requires its internal provenance label");
+    const focal = input.focalPoint ?? { x: 0.5, y: 0.5 };
+    if (![focal.x, focal.y].every((v) => Number.isFinite(v) && v >= 0 && v <= 1))
+      throw new Error("Focal point must be within the image");
+    const photo = `/v1/photos/public/${encodeURIComponent(input.fileId)}/manifest`;
+    const socialKey = input.socialRenditionKey ?? "w1200_h630_cover_q85_jpeg";
+    const socialPath = `${photo}?rendition=${encodeURIComponent(socialKey)}`;
+    const [current, hero, initialSocial] = await Promise.all([
+      this.processing(input.articleId),
+      this.request(`${photo}?preset=hero`),
+      this.request(socialPath)
+    ]);
+    if (current.publication_status !== "published" || current.version !== input.expectedVersion)
+      throw new ArticleWorkflowError("Article is not published or its version changed; reload before updating its cover", 409, input.articleId);
+    let social = initialSocial;
+    if (hero.ready && [hero.file_id, hero.photo_id].includes(input.fileId) && !social.ready && social.file_id === hero.file_id) {
+      const spec = /^w(\d+)_h(\d+)_(cover|contain|fill|scaledown)_q(\d+)_(jpeg|webp|avif)$/.exec(socialKey);
+      if (spec && Number(spec[1]) > 0 && Number(spec[1]) <= 12e3 && Number(spec[2]) > 0 && Number(spec[2]) <= 12e3 && Number(spec[4]) > 0 && Number(spec[4]) <= 100) {
+        const query = new URLSearchParams({ width: spec[1], height: spec[2], fit: spec[3], quality: spec[4], format: spec[5] });
+        const url = new URL(this.config.apiUrl.replace(/\/$/, "") + `/v1/photos/public/${encodeURIComponent(input.fileId)}/transform?${query}`);
+        const response = await (this.config.fetch ?? fetch)(url, { method: "GET", redirect: "manual", cache: "no-store", signal: AbortSignal.timeout(3e4) });
+        const accepted = response.ok && response.headers.get("content-type")?.startsWith("image/") || [302, 303, 307, 308].includes(response.status);
+        await response.body?.cancel();
+        if (accepted) social = await this.request(socialPath);
+      }
+    }
+    const dimension = (v) => Number.isInteger(v) && Number(v) > 0 && Number(v) <= 12e3;
+    const publicUrl = (raw) => {
+      try {
+        const url = new URL(raw);
+        return url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash;
+      } catch {
+        return false;
+      }
+    };
+    const variants = Object.values(hero.variant_metadata ?? {});
+    if (!hero.ready || !social.ready || !hero.file_id || ![hero.file_id, hero.photo_id].includes(input.fileId) || social.file_id !== hero.file_id || !variants.length || variants.length > 20 || variants.some((v) => !dimension(v.width) || !dimension(v.height) || !publicUrl(v.url) || !["jpeg", "webp", "avif"].includes(v.format)) || !dimension(social.width) || !dimension(social.height) || !social.url || !publicUrl(social.url))
+      throw new ArticleWorkflowError("Public Photo renditions are not ready with measured dimensions; inspect Photo processing, keep the existing cover and resume with the same asset", 409, input.articleId);
+    const ordered = [...variants].sort((a, b) => a.width - b.width);
+    const master = [...ordered].reverse().find((v) => v.width <= 1600) ?? ordered[0];
+    return this.request(
+      `/articles/${encodeURIComponent(input.articleId)}/media`,
+      "PUT",
+      {
+        expected_version: input.expectedVersion,
+        cover_image_url: master.url,
+        og_image_url: social.url,
+        cover_image: {
+          file_id: hero.file_id,
+          master_url: master.url,
+          width: master.width,
+          height: master.height,
+          aspect_ratio: `${master.width}:${master.height}`,
+          alt: input.alt,
+          caption: input.caption,
+          attribution: input.credit,
+          ai_generated: input.aiGenerated,
+          label: input.label,
+          focal_point: focal,
+          variants
+        },
+        open_graph_image: {
+          file_id: hero.file_id,
+          url: social.url,
+          width: social.width,
+          height: social.height,
+          aspect_ratio: `${social.width}:${social.height}`
+        }
+      }
+    );
+  }
   /** Existing private narration path for a saved revision and a before-publication audio policy. */
   narrateRevision(articleId, expectedGeneration) {
     return this.request(

package/dist/meet-view.d.cts

@@ -18,7 +18,7 @@ declare function MeetupDetail({ meetup, joined }: {
     joined: boolean;
 }): React.JSX.Element;
 declare function activityChoices(): {
-    value: "walk" | "other" | "games" | "coffee" | "hike" | "pickleball" | "tennis" | "soccer" | "bike" | "dogs" | "books" | "kids" | "volunteer";
+    value: "other" | "walk" | "games" | "coffee" | "hike" | "pickleball" | "tennis" | "soccer" | "bike" | "dogs" | "books" | "kids" | "volunteer";
     label: string;
 }[];
 

package/dist/meet-view.d.ts

@@ -18,7 +18,7 @@ declare function MeetupDetail({ meetup, joined }: {
     joined: boolean;
 }): React.JSX.Element;
 declare function activityChoices(): {
-    value: "walk" | "other" | "games" | "coffee" | "hike" | "pickleball" | "tennis" | "soccer" | "bike" | "dogs" | "books" | "kids" | "volunteer";
+    value: "other" | "walk" | "games" | "coffee" | "hike" | "pickleball" | "tennis" | "soccer" | "bike" | "dogs" | "books" | "kids" | "volunteer";
     label: string;
 }[];
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@scalemule/news-publication",
-  "version": "0.0.75",
+  "version": "0.0.76",
   "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": { "scalemule-article": "./bin/scalemule-article.mjs" },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -197,6 +198,7 @@
     }
   },
   "files": [
+    "bin",
     "dist",
     "tokens",
     "marketplace.css",