@aglyn/plugins-commerce 1.0.0-beta.285 → 1.0.0-beta.288

package/src/lib/server/pos-reader-splash-images-route.js

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { POS_READER_SPLASH_MAX_BYTES } from "../model/pos-reader-splash.js";
+import { drawAndUploadPosReaderSplash, ownerOrgOf, planPosReaderSplash, terminalConfigRef } from "./pos-reader-splash.js";
+import { posReaderSplashImageFacts, PosReaderSplashRenderError } from "./pos-reader-splash-render.js";
+import { POS_READER_SPLASH_IMAGES_SIGNATURE, verifyPosReaderSplashImagesRequest } from "./pos-reader-splash-images.js";
+/*==========================================
+ * `POST /api/plugin-images/commerce/pos-reader-splash-images` (AGL-4048):
+ * the start-up screen's image work, in the one function that ships `sharp`'s
+ * native library (the console's plugins' image function; see
+ * `pos-reader-splash-images.ts` for why).
+ *
+ *   {op: 'draw', hostId, key}   the store's plan is read again here, and
+ *                               drawn and uploaded only while its key is
+ *                               still the one the caller asked for:
+ *                               `{fileIds}`, or 409 when it moved on
+ *   {op: 'facts', dataBase64}   an uploaded screen's format and size:
+ *                               `{facts}` (null when it is not an image)
+ *
+ * A machine's door: no session, a signature over the moment and the body
+ * (401 without one). A screen the store must hear about is 422 with its
+ * words; anything else is 500, and the caller records the failure as before.
+ *=========================================*/ const DOCUMENT_ID = /^[A-Za-z0-9_-]{1,128}$/;
+function json(body, status = 200) {
+    return Response.json(body, {
+        status,
+        headers: {
+            'Cache-Control': 'no-store'
+        }
+    });
+}
+export async function posReaderSplashImagesRoute(request) {
+    if (request.method !== 'POST') return json({
+        error: 'Method not allowed'
+    }, 405);
+    const raw = await request.text();
+    if (!verifyPosReaderSplashImagesRequest(request.headers.get(POS_READER_SPLASH_IMAGES_SIGNATURE), raw)) {
+        return json({
+            error: 'Unauthenticated'
+        }, 401);
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    } catch (unused) {
+        return json({
+            error: 'Bad request'
+        }, 400);
+    }
+    try {
+        var _body_hostId, _body_key;
+        if (body['op'] === 'facts') {
+            var _body_dataBase64;
+            const data = String((_body_dataBase64 = body['dataBase64']) != null ? _body_dataBase64 : '');
+            // A base64 body is 4/3 of the file; anything longer cannot be under 2 MB.
+            if (!data || data.length > Math.ceil(POS_READER_SPLASH_MAX_BYTES * 4 / 3) + 4) {
+                return json({
+                    facts: null
+                });
+            }
+            const { loadSharp } = await import("./pos-reader-splash-server.js");
+            return json({
+                facts: await posReaderSplashImageFacts(await loadSharp(), Buffer.from(data, 'base64'))
+            });
+        }
+        if (body['op'] !== 'draw') return json({
+            error: 'Unknown op'
+        }, 400);
+        const hostId = String((_body_hostId = body['hostId']) != null ? _body_hostId : '');
+        const key = String((_body_key = body['key']) != null ? _body_key : '');
+        if (!DOCUMENT_ID.test(hostId) || !key) return json({
+            error: 'Bad request'
+        }, 400);
+        const config = (await terminalConfigRef(hostId).get()).data();
+        if (!(config == null ? void 0 : config['stripeLocationId'])) return json({
+            error: 'This store has no card reader location.'
+        }, 409);
+        const plan = await planPosReaderSplash(hostId, await ownerOrgOf(hostId), config);
+        // Drawn only for the screen the caller decided on: a save that landed
+        // in between is the next pass's to draw.
+        if (plan.key !== key || !plan.source) {
+            return json({
+                error: 'The start-up screen changed while it was being drawn. Try again.'
+            }, 409);
+        }
+        return json({
+            fileIds: await drawAndUploadPosReaderSplash(hostId, plan.source)
+        });
+    } catch (error) {
+        if (error instanceof PosReaderSplashRenderError) return json({
+            error: error.message
+        }, 422);
+        console.error('[pos-reader-splash-images]', body['op'], error);
+        return json({
+            error: 'The start-up screen could not be drawn.'
+        }, 500);
+    }
+}
+
+//# sourceMappingURL=pos-reader-splash-images-route.js.map

package/src/lib/server/pos-reader-splash-images-route.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/pos-reader-splash-images-route.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { POS_READER_SPLASH_MAX_BYTES } from '../model/pos-reader-splash'\nimport {\n  drawAndUploadPosReaderSplash,\n  ownerOrgOf,\n  planPosReaderSplash,\n  terminalConfigRef,\n} from './pos-reader-splash'\nimport { posReaderSplashImageFacts, PosReaderSplashRenderError } from './pos-reader-splash-render'\nimport { POS_READER_SPLASH_IMAGES_SIGNATURE, verifyPosReaderSplashImagesRequest } from './pos-reader-splash-images'\n\n/*==========================================\n * `POST /api/plugin-images/commerce/pos-reader-splash-images` (AGL-4048):\n * the start-up screen's image work, in the one function that ships `sharp`'s\n * native library (the console's plugins' image function; see\n * `pos-reader-splash-images.ts` for why).\n *\n *   {op: 'draw', hostId, key}   the store's plan is read again here, and\n *                               drawn and uploaded only while its key is\n *                               still the one the caller asked for:\n *                               `{fileIds}`, or 409 when it moved on\n *   {op: 'facts', dataBase64}   an uploaded screen's format and size:\n *                               `{facts}` (null when it is not an image)\n *\n * A machine's door: no session, a signature over the moment and the body\n * (401 without one). A screen the store must hear about is 422 with its\n * words; anything else is 500, and the caller records the failure as before.\n *=========================================*/\n\nconst DOCUMENT_ID = /^[A-Za-z0-9_-]{1,128}$/\n\nfunction json(body: unknown, status = 200): Response {\n  return Response.json(body, { status, headers: { 'Cache-Control': 'no-store' } })\n}\n\nexport async function posReaderSplashImagesRoute(request: Request): Promise<Response> {\n  if (request.method !== 'POST') return json({ error: 'Method not allowed' }, 405)\n  const raw = await request.text()\n  if (!verifyPosReaderSplashImagesRequest(request.headers.get(POS_READER_SPLASH_IMAGES_SIGNATURE), raw)) {\n    return json({ error: 'Unauthenticated' }, 401)\n  }\n  let body: Record<string, unknown>\n  try {\n    body = JSON.parse(raw) as Record<string, unknown>\n  } catch {\n    return json({ error: 'Bad request' }, 400)\n  }\n  try {\n    if (body['op'] === 'facts') {\n      const data = String(body['dataBase64'] ?? '')\n      // A base64 body is 4/3 of the file; anything longer cannot be under 2 MB.\n      if (!data || data.length > Math.ceil((POS_READER_SPLASH_MAX_BYTES * 4) / 3) + 4) {\n        return json({ facts: null })\n      }\n      const { loadSharp } = await import('./pos-reader-splash-server')\n      return json({ facts: await posReaderSplashImageFacts((await loadSharp()) as never, Buffer.from(data, 'base64')) })\n    }\n    if (body['op'] !== 'draw') return json({ error: 'Unknown op' }, 400)\n    const hostId = String(body['hostId'] ?? '')\n    const key = String(body['key'] ?? '')\n    if (!DOCUMENT_ID.test(hostId) || !key) return json({ error: 'Bad request' }, 400)\n    const config = (await terminalConfigRef(hostId).get()).data() as Record<string, unknown> | undefined\n    if (!config?.['stripeLocationId']) return json({ error: 'This store has no card reader location.' }, 409)\n    const plan = await planPosReaderSplash(hostId, await ownerOrgOf(hostId), config as Record<string, any>)\n    // Drawn only for the screen the caller decided on: a save that landed\n    // in between is the next pass's to draw.\n    if (plan.key !== key || !plan.source) {\n      return json({ error: 'The start-up screen changed while it was being drawn. Try again.' }, 409)\n    }\n    return json({ fileIds: await drawAndUploadPosReaderSplash(hostId, plan.source) })\n  } catch (error) {\n    if (error instanceof PosReaderSplashRenderError) return json({ error: error.message }, 422)\n    console.error('[pos-reader-splash-images]', body['op'], error)\n    return json({ error: 'The start-up screen could not be drawn.' }, 500)\n  }\n}\n"],"names":["POS_READER_SPLASH_MAX_BYTES","drawAndUploadPosReaderSplash","ownerOrgOf","planPosReaderSplash","terminalConfigRef","posReaderSplashImageFacts","PosReaderSplashRenderError","POS_READER_SPLASH_IMAGES_SIGNATURE","verifyPosReaderSplashImagesRequest","DOCUMENT_ID","json","body","status","Response","headers","posReaderSplashImagesRoute","request","method","error","raw","text","get","JSON","parse","data","String","length","Math","ceil","facts","loadSharp","Buffer","from","hostId","key","test","config","plan","source","fileIds","message","console"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,2BAA2B,QAAQ,gCAA4B;AACxE,SACEC,4BAA4B,EAC5BC,UAAU,EACVC,mBAAmB,EACnBC,iBAAiB,QACZ,yBAAqB;AAC5B,SAASC,yBAAyB,EAAEC,0BAA0B,QAAQ,gCAA4B;AAClG,SAASC,kCAAkC,EAAEC,kCAAkC,QAAQ,gCAA4B;AAEnH;;;;;;;;;;;;;;;;2CAgB2C,GAE3C,MAAMC,cAAc;AAEpB,SAASC,KAAKC,IAAa,EAAEC,SAAS,GAAG;IACvC,OAAOC,SAASH,IAAI,CAACC,MAAM;QAAEC;QAAQE,SAAS;YAAE,iBAAiB;QAAW;IAAE;AAChF;AAEA,OAAO,eAAeC,2BAA2BC,OAAgB;IAC/D,IAAIA,QAAQC,MAAM,KAAK,QAAQ,OAAOP,KAAK;QAAEQ,OAAO;IAAqB,GAAG;IAC5E,MAAMC,MAAM,MAAMH,QAAQI,IAAI;IAC9B,IAAI,CAACZ,mCAAmCQ,QAAQF,OAAO,CAACO,GAAG,CAACd,qCAAqCY,MAAM;QACrG,OAAOT,KAAK;YAAEQ,OAAO;QAAkB,GAAG;IAC5C;IACA,IAAIP;IACJ,IAAI;QACFA,OAAOW,KAAKC,KAAK,CAACJ;IACpB,EAAE,eAAM;QACN,OAAOT,KAAK;YAAEQ,OAAO;QAAc,GAAG;IACxC;IACA,IAAI;YAWoBP,cACHA;QAXnB,IAAIA,IAAI,CAAC,KAAK,KAAK,SAAS;gBACNA;YAApB,MAAMa,OAAOC,QAAOd,mBAAAA,IAAI,CAAC,aAAa,YAAlBA,mBAAsB;YAC1C,0EAA0E;YAC1E,IAAI,CAACa,QAAQA,KAAKE,MAAM,GAAGC,KAAKC,IAAI,CAAC,AAAC5B,8BAA8B,IAAK,KAAK,GAAG;gBAC/E,OAAOU,KAAK;oBAAEmB,OAAO;gBAAK;YAC5B;YACA,MAAM,EAAEC,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC;YACnC,OAAOpB,KAAK;gBAAEmB,OAAO,MAAMxB,0BAA2B,MAAMyB,aAAuBC,OAAOC,IAAI,CAACR,MAAM;YAAW;QAClH;QACA,IAAIb,IAAI,CAAC,KAAK,KAAK,QAAQ,OAAOD,KAAK;YAAEQ,OAAO;QAAa,GAAG;QAChE,MAAMe,SAASR,QAAOd,eAAAA,IAAI,CAAC,SAAS,YAAdA,eAAkB;QACxC,MAAMuB,MAAMT,QAAOd,YAAAA,IAAI,CAAC,MAAM,YAAXA,YAAe;QAClC,IAAI,CAACF,YAAY0B,IAAI,CAACF,WAAW,CAACC,KAAK,OAAOxB,KAAK;YAAEQ,OAAO;QAAc,GAAG;QAC7E,MAAMkB,SAAS,AAAC,CAAA,MAAMhC,kBAAkB6B,QAAQZ,GAAG,EAAC,EAAGG,IAAI;QAC3D,IAAI,EAACY,0BAAAA,MAAQ,CAAC,mBAAmB,GAAE,OAAO1B,KAAK;YAAEQ,OAAO;QAA0C,GAAG;QACrG,MAAMmB,OAAO,MAAMlC,oBAAoB8B,QAAQ,MAAM/B,WAAW+B,SAASG;QACzE,sEAAsE;QACtE,yCAAyC;QACzC,IAAIC,KAAKH,GAAG,KAAKA,OAAO,CAACG,KAAKC,MAAM,EAAE;YACpC,OAAO5B,KAAK;gBAAEQ,OAAO;YAAmE,GAAG;QAC7F;QACA,OAAOR,KAAK;YAAE6B,SAAS,MAAMtC,6BAA6BgC,QAAQI,KAAKC,MAAM;QAAE;IACjF,EAAE,OAAOpB,OAAO;QACd,IAAIA,iBAAiBZ,4BAA4B,OAAOI,KAAK;YAAEQ,OAAOA,MAAMsB,OAAO;QAAC,GAAG;QACvFC,QAAQvB,KAAK,CAAC,8BAA8BP,IAAI,CAAC,KAAK,EAAEO;QACxD,OAAOR,KAAK;YAAEQ,OAAO;QAA0C,GAAG;IACpE;AACF"}

package/src/lib/server/pos-reader-splash-images.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** The images route's registered path, served under `/api/plugin-images/`. */
+export declare const POS_READER_SPLASH_IMAGES_PATH = "commerce/pos-reader-splash-images";
+/** The request header that carries the signature: `t=<ms>,v1=<hex>`. */
+export declare const POS_READER_SPLASH_IMAGES_SIGNATURE = "x-aglyn-images-signature";
+/** How far a signed request's moment may be from the function's clock. */
+export declare const POS_READER_SPLASH_IMAGES_WINDOW_MS: number;
+/** Test seam. */
+export declare function setPosReaderSplashImagesSecretForTests(secret: (() => string) | null): void;
+/** The header value for a body signed now. Throws on a deploy with no signing secret. */
+export declare function signPosReaderSplashImagesRequest(body: string, nowMs?: number): string;
+/**
+ * Whether a request's signature is ours, over this body, and recent. False
+ * for anything else, a deploy with no signing secret included (fail closed).
+ */
+export declare function verifyPosReaderSplashImagesRequest(header: string | null | undefined, body: string, nowMs?: number): boolean;
+/**
+ * Where to ask for the image work, or `null` to do it in this process. On
+ * Vercel only the images function ships libvips, so every other function
+ * asks it, at the console's own address; anywhere else this process can draw.
+ */
+export declare function posReaderSplashImagesOrigin(): string | null;
+/** The function refused the work with words meant for the store (`422`), or the store moved on (`409`). */
+export declare class PosReaderSplashImagesRefusal extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** Asks the images function for one piece of work, signed. */
+export declare function requestPosReaderSplashImages<T>(origin: string, payload: {
+    op: 'draw';
+    hostId: string;
+    key: string;
+} | {
+    op: 'facts';
+    dataBase64: string;
+}): Promise<T>;

package/src/lib/server/pos-reader-splash-images.js

@@ -0,0 +1,123 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { PLUGIN_IMAGES_API_PREFIX } from "@aglyn/aglyn/app-utils/api-plugins";
+import { platformConsoleOrigin } from "@aglyn/aglyn/app-utils/platform-brand";
+import { tokenSigningSecret } from "@aglyn/tenant-data-admin/server/media-signing";
+/*==========================================
+ * THE START-UP SCREEN'S IMAGE WORK HAS ITS OWN FUNCTION (AGL-4048).
+ *
+ * Drawing a card reader's start-up screen takes `sharp`, and `sharp` takes
+ * libvips, a 17 MB native library the plugin API's function would otherwise
+ * carry into every cold start of every plugin door. So the drawing is a
+ * route of its own, registered to draw images (`images: true`), which the
+ * console serves only from the plugins' image function at
+ * `/api/plugin-images/commerce/pos-reader-splash-images`
+ * (`pos-reader-splash-images-route.ts`), the one function that ships
+ * libvips; on Vercel everything else that needs a screen drawn, or an
+ * uploaded screen read, asks it over HTTP:
+ *
+ *   draw   {hostId, key}   draw the store's screen for the plan with that
+ *                          key and upload each family's file to Stripe:
+ *                          `{fileIds}` back
+ *   facts  {dataBase64}    an uploaded image's format and size: `{facts}`
+ *
+ * The caller signs each request with the platform's signing secret, over
+ * the moment and the body, so nobody else spends the function's time and no
+ * request is replayed later. Off Vercel (a self-hosted server, a developer's
+ * machine, a spec) one process holds every route and libvips with it, so
+ * the work runs where it is asked for, exactly as before.
+ *=========================================*/ /** The images route's registered path, served under `/api/plugin-images/`. */ export const POS_READER_SPLASH_IMAGES_PATH = 'commerce/pos-reader-splash-images';
+/** The request header that carries the signature: `t=<ms>,v1=<hex>`. */ export const POS_READER_SPLASH_IMAGES_SIGNATURE = 'x-aglyn-images-signature';
+/** How far a signed request's moment may be from the function's clock. */ export const POS_READER_SPLASH_IMAGES_WINDOW_MS = 5 * 60 * 1000;
+/** How long a caller waits for the function: inside its own 60 seconds. */ const REQUEST_TIMEOUT_MS = 55000;
+let secretOverride = null;
+/** Test seam. */ export function setPosReaderSplashImagesSecretForTests(secret) {
+    secretOverride = secret;
+}
+function signature(at, body) {
+    const digest = createHash('sha256').update(body).digest('hex');
+    return createHmac('sha256', (secretOverride != null ? secretOverride : tokenSigningSecret)()).update(`pos-reader-splash-images:${at}.${digest}`).digest('hex');
+}
+/** The header value for a body signed now. Throws on a deploy with no signing secret. */ export function signPosReaderSplashImagesRequest(body, nowMs = Date.now()) {
+    return `t=${nowMs},v1=${signature(nowMs, body)}`;
+}
+/**
+ * Whether a request's signature is ours, over this body, and recent. False
+ * for anything else, a deploy with no signing secret included (fail closed).
+ */ export function verifyPosReaderSplashImagesRequest(header, body, nowMs = Date.now()) {
+    var _parts_v1;
+    const parts = Object.fromEntries(String(header != null ? header : '').split(',').map((part)=>part.trim().split('=')).filter((pair)=>pair.length === 2));
+    const at = Number(parts['t']);
+    const given = String((_parts_v1 = parts['v1']) != null ? _parts_v1 : '');
+    if (!Number.isFinite(at) || !/^[a-f0-9]{64}$/.test(given)) return false;
+    if (Math.abs(nowMs - at) > POS_READER_SPLASH_IMAGES_WINDOW_MS) return false;
+    let expected;
+    try {
+        expected = signature(at, body);
+    } catch (unused) {
+        return false;
+    }
+    return timingSafeEqual(Buffer.from(given), Buffer.from(expected));
+}
+/**
+ * Where to ask for the image work, or `null` to do it in this process. On
+ * Vercel only the images function ships libvips, so every other function
+ * asks it, at the console's own address; anywhere else this process can draw.
+ */ export function posReaderSplashImagesOrigin() {
+    if (process.env['VERCEL'] !== '1') return null;
+    return platformConsoleOrigin();
+}
+/**
+ * The headers that get our own request past our own edge, when configured:
+ * the same pair the render monitor sends (AGL-3571).
+ */ function edgeBypassHeaders() {
+    var _process_env_AGLYN_PROBE_TOKEN;
+    const probe = String((_process_env_AGLYN_PROBE_TOKEN = process.env['AGLYN_PROBE_TOKEN']) != null ? _process_env_AGLYN_PROBE_TOKEN : '').trim();
+    const bypass = String(process.env['AGLYN_VERCEL_BYPASS'] || process.env['VERCEL_AUTOMATION_BYPASS_SECRET'] || '').trim();
+    return _extends({}, probe ? {
+        'x-aglyn-probe': probe
+    } : {}, bypass ? {
+        'x-vercel-protection-bypass': bypass
+    } : {});
+}
+/** The function refused the work with words meant for the store (`422`), or the store moved on (`409`). */ export class PosReaderSplashImagesRefusal extends Error {
+    constructor(message, status){
+        super(message), this.status = status;
+    }
+}
+/** Asks the images function for one piece of work, signed. */ export async function requestPosReaderSplashImages(origin, payload) {
+    const body = JSON.stringify(payload);
+    const response = await fetch(`${origin}/api/${PLUGIN_IMAGES_API_PREFIX}/${POS_READER_SPLASH_IMAGES_PATH}`, {
+        method: 'POST',
+        headers: _extends({
+            'content-type': 'application/json',
+            [POS_READER_SPLASH_IMAGES_SIGNATURE]: signPosReaderSplashImagesRequest(body)
+        }, edgeBypassHeaders()),
+        body,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+    const answer = await response.json().catch(()=>({}));
+    if (response.status === 422 || response.status === 409) {
+        var _ref;
+        throw new PosReaderSplashImagesRefusal(String((_ref = answer == null ? void 0 : answer.error) != null ? _ref : 'That image could not be read.'), response.status);
+    }
+    if (!response.ok) throw new Error(`the start-up screen's images function answered ${response.status}`);
+    return answer;
+}
+
+//# sourceMappingURL=pos-reader-splash-images.js.map

package/src/lib/server/pos-reader-splash-images.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/pos-reader-splash-images.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createHash, createHmac, timingSafeEqual } from 'node:crypto'\nimport { PLUGIN_IMAGES_API_PREFIX } from '@aglyn/aglyn/app-utils/api-plugins'\nimport { platformConsoleOrigin } from '@aglyn/aglyn/app-utils/platform-brand'\nimport { tokenSigningSecret } from '@aglyn/tenant-data-admin/server/media-signing'\n\n/*==========================================\n * THE START-UP SCREEN'S IMAGE WORK HAS ITS OWN FUNCTION (AGL-4048).\n *\n * Drawing a card reader's start-up screen takes `sharp`, and `sharp` takes\n * libvips, a 17 MB native library the plugin API's function would otherwise\n * carry into every cold start of every plugin door. So the drawing is a\n * route of its own, registered to draw images (`images: true`), which the\n * console serves only from the plugins' image function at\n * `/api/plugin-images/commerce/pos-reader-splash-images`\n * (`pos-reader-splash-images-route.ts`), the one function that ships\n * libvips; on Vercel everything else that needs a screen drawn, or an\n * uploaded screen read, asks it over HTTP:\n *\n *   draw   {hostId, key}   draw the store's screen for the plan with that\n *                          key and upload each family's file to Stripe:\n *                          `{fileIds}` back\n *   facts  {dataBase64}    an uploaded image's format and size: `{facts}`\n *\n * The caller signs each request with the platform's signing secret, over\n * the moment and the body, so nobody else spends the function's time and no\n * request is replayed later. Off Vercel (a self-hosted server, a developer's\n * machine, a spec) one process holds every route and libvips with it, so\n * the work runs where it is asked for, exactly as before.\n *=========================================*/\n\n/** The images route's registered path, served under `/api/plugin-images/`. */\nexport const POS_READER_SPLASH_IMAGES_PATH = 'commerce/pos-reader-splash-images'\n\n/** The request header that carries the signature: `t=<ms>,v1=<hex>`. */\nexport const POS_READER_SPLASH_IMAGES_SIGNATURE = 'x-aglyn-images-signature'\n\n/** How far a signed request's moment may be from the function's clock. */\nexport const POS_READER_SPLASH_IMAGES_WINDOW_MS = 5 * 60 * 1000\n\n/** How long a caller waits for the function: inside its own 60 seconds. */\nconst REQUEST_TIMEOUT_MS = 55_000\n\nlet secretOverride: (() => string) | null = null\n\n/** Test seam. */\nexport function setPosReaderSplashImagesSecretForTests(secret: (() => string) | null): void {\n  secretOverride = secret\n}\n\nfunction signature(at: number, body: string): string {\n  const digest = createHash('sha256').update(body).digest('hex')\n  return createHmac('sha256', (secretOverride ?? tokenSigningSecret)())\n    .update(`pos-reader-splash-images:${at}.${digest}`)\n    .digest('hex')\n}\n\n/** The header value for a body signed now. Throws on a deploy with no signing secret. */\nexport function signPosReaderSplashImagesRequest(body: string, nowMs: number = Date.now()): string {\n  return `t=${nowMs},v1=${signature(nowMs, body)}`\n}\n\n/**\n * Whether a request's signature is ours, over this body, and recent. False\n * for anything else, a deploy with no signing secret included (fail closed).\n */\nexport function verifyPosReaderSplashImagesRequest(\n  header: string | null | undefined,\n  body: string,\n  nowMs: number = Date.now(),\n): boolean {\n  const parts = Object.fromEntries(\n    String(header ?? '')\n      .split(',')\n      .map((part) => part.trim().split('=') as [string, string])\n      .filter((pair) => pair.length === 2),\n  )\n  const at = Number(parts['t'])\n  const given = String(parts['v1'] ?? '')\n  if (!Number.isFinite(at) || !/^[a-f0-9]{64}$/.test(given)) return false\n  if (Math.abs(nowMs - at) > POS_READER_SPLASH_IMAGES_WINDOW_MS) return false\n  let expected: string\n  try {\n    expected = signature(at, body)\n  } catch {\n    return false\n  }\n  return timingSafeEqual(Buffer.from(given), Buffer.from(expected))\n}\n\n/**\n * Where to ask for the image work, or `null` to do it in this process. On\n * Vercel only the images function ships libvips, so every other function\n * asks it, at the console's own address; anywhere else this process can draw.\n */\nexport function posReaderSplashImagesOrigin(): string | null {\n  if (process.env['VERCEL'] !== '1') return null\n  return platformConsoleOrigin()\n}\n\n/**\n * The headers that get our own request past our own edge, when configured:\n * the same pair the render monitor sends (AGL-3571).\n */\nfunction edgeBypassHeaders(): Record<string, string> {\n  const probe = String(process.env['AGLYN_PROBE_TOKEN'] ?? '').trim()\n  const bypass = String(\n    process.env['AGLYN_VERCEL_BYPASS'] || process.env['VERCEL_AUTOMATION_BYPASS_SECRET'] || '',\n  ).trim()\n  return {\n    ...(probe ? { 'x-aglyn-probe': probe } : {}),\n    ...(bypass ? { 'x-vercel-protection-bypass': bypass } : {}),\n  }\n}\n\n/** The function refused the work with words meant for the store (`422`), or the store moved on (`409`). */\nexport class PosReaderSplashImagesRefusal extends Error {\n  constructor(\n    message: string,\n    readonly status: number,\n  ) {\n    super(message)\n  }\n}\n\n/** Asks the images function for one piece of work, signed. */\nexport async function requestPosReaderSplashImages<T>(\n  origin: string,\n  payload: { op: 'draw'; hostId: string; key: string } | { op: 'facts'; dataBase64: string },\n): Promise<T> {\n  const body = JSON.stringify(payload)\n  const response = await fetch(`${origin}/api/${PLUGIN_IMAGES_API_PREFIX}/${POS_READER_SPLASH_IMAGES_PATH}`, {\n    method: 'POST',\n    headers: {\n      'content-type': 'application/json',\n      [POS_READER_SPLASH_IMAGES_SIGNATURE]: signPosReaderSplashImagesRequest(body),\n      ...edgeBypassHeaders(),\n    },\n    body,\n    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),\n  })\n  const answer = (await response.json().catch(() => ({}))) as T & { error?: string }\n  if (response.status === 422 || response.status === 409) {\n    throw new PosReaderSplashImagesRefusal(String(answer?.error ?? 'That image could not be read.'), response.status)\n  }\n  if (!response.ok) throw new Error(`the start-up screen's images function answered ${response.status}`)\n  return answer\n}\n"],"names":["createHash","createHmac","timingSafeEqual","PLUGIN_IMAGES_API_PREFIX","platformConsoleOrigin","tokenSigningSecret","POS_READER_SPLASH_IMAGES_PATH","POS_READER_SPLASH_IMAGES_SIGNATURE","POS_READER_SPLASH_IMAGES_WINDOW_MS","REQUEST_TIMEOUT_MS","secretOverride","setPosReaderSplashImagesSecretForTests","secret","signature","at","body","digest","update","signPosReaderSplashImagesRequest","nowMs","Date","now","verifyPosReaderSplashImagesRequest","header","parts","Object","fromEntries","String","split","map","part","trim","filter","pair","length","Number","given","isFinite","test","Math","abs","expected","Buffer","from","posReaderSplashImagesOrigin","process","env","edgeBypassHeaders","probe","bypass","PosReaderSplashImagesRefusal","Error","message","status","requestPosReaderSplashImages","origin","payload","JSON","stringify","response","fetch","method","headers","signal","AbortSignal","timeout","answer","json","catch","error","ok"],"mappings":"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"}

package/src/lib/server/pos-reader-splash.d.ts

@@ -16,6 +16,8 @@
  */
 import { type MediaCdnScope } from '@aglyn/aglyn/app-utils/media-cdn-scope';
 import type { PluginApiHandler } from '@aglyn/aglyn/server';
+import type { PluginEventPayloads } from '@aglyn/aglyn/plugin-manager/plugin-events';
+import type { PluginJobHostGate } from '@aglyn/aglyn/server';
 import { type PosReaderSplashChoice, type PosReaderSplashFamilyId } from '../model/pos-reader-splash';
 /** `platformSettings/posReaderSplash`: staff's default screen. */
 export declare const POS_READER_SPLASH_SETTINGS_ID = "posReaderSplash";
@@ -32,6 +34,7 @@ export interface PlatformSplashDoc {
     families?: Partial<Record<PosReaderSplashFamilyId, PlatformSplashImage>>;
     updatedAtMs?: number;
 }
+export declare function terminalConfigRef(hostId: string): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
 export declare function platformSplashRef(): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
 export declare function posReaderSplashBucket(): import("@google-cloud/storage").Bucket;
 export declare function readPlatformSplash(): Promise<PlatformSplashDoc>;
@@ -59,7 +62,7 @@ type LocatedSource = LocatedAsset | LocatedUrl;
  * workspace without a brand, so its `logoUrl` is not read here.
  */
 export declare function workspaceLogoValue(org: Record<string, any> | null, whiteLabel: boolean): string | null;
-type SplashSource = {
+export type SplashSource = {
     mode: 'platform';
     doc: PlatformSplashDoc;
 } | {
@@ -83,6 +86,12 @@ export interface PosReaderSplashPlan {
     source: SplashSource | null;
 }
 export declare function planPosReaderSplash(hostId: string, org: Record<string, any> | null, config: Record<string, any> | undefined, platform?: PlatformSplashDoc): Promise<PosReaderSplashPlan>;
+/**
+ * Draws each reader family's screen from the plan's source and uploads it to
+ * Stripe: the image work, which needs `sharp`. Runs in the images function
+ * on Vercel (`pos-reader-splash-images-route.ts`), and in any process off it.
+ */
+export declare function drawAndUploadPosReaderSplash(hostId: string, source: SplashSource): Promise<Record<PosReaderSplashFamilyId, string>>;
 /** The org that owns the site, with its id on it (`planPosReaderSplash` reads it). */
 export declare function ownerOrgOf(hostId: string): Promise<Record<string, any> | null>;
 export interface PosReaderSplashApplyResult {
@@ -100,6 +109,64 @@ export declare function applyPosReaderSplash(hostId: string, options?: {
     org?: Record<string, any> | null;
     platform?: PlatformSplashDoc;
     force?: boolean;
+    /**
+     * Leave a screen that failed to apply alone until this long after the
+     * failure, when it is still the same screen: a background pass must not
+     * draw and upload a logo Stripe keeps refusing on every beat. The card
+     * passes none, so opening it always tries again.
+     */
+    retryFailedAfterMs?: number;
 }): Promise<PosReaderSplashApplyResult>;
+/** How many stores one pass reaches, and how many it works on at once. */
+export declare const POS_READER_SPLASH_SWEEP_WINDOW = 400;
+export interface PosReaderSplashSweep {
+    applied: number;
+    unchanged: number;
+    failed: number;
+    /** Locked stores, and screens still inside their failure's retry wait. */
+    skipped: number;
+    /** More stores have readers than one pass reaches. */
+    more: boolean;
+}
+/**
+ * Brings every store with a Location up to date with
+ * {@link applyPosReaderSplash}, the call the POS devices card makes: a store
+ * whose screen key has not moved costs reads and no Stripe call, and one
+ * that moved gets exactly one round of uploads. At most
+ * {@link POS_READER_SPLASH_SWEEP_WINDOW} stores a pass.
+ */
+export declare function applyPosReaderSplashToStores(options?: {
+    platform?: PlatformSplashDoc;
+    /** Asked before each store; a locked store is left as it is. */
+    isLocked?: (hostId: string) => Promise<boolean>;
+    retryFailedAfterMs?: number;
+}): Promise<PosReaderSplashSweep>;
+/** How long a background pass leaves a screen Stripe refused before trying it again. */
+export declare const POS_READER_SPLASH_RETRY_FAILED_AFTER_MS: number;
+/**
+ * The `pos-reader-splash-refresh` beat (AGL-4048): a logo changed on the
+ * organization profile or the white-label brand, or the logo's file replaced
+ * in the media library, reaches the store's readers without anybody opening
+ * the POS devices card. The screen's key already moves with each of those,
+ * so the beat only has to ask; nothing waits on it, and a save never waits
+ * on Stripe. Asks the runner's lockdown gate for every store.
+ */
+export declare function refreshPosReaderSplashes(gate: {
+    isLocked: (hostId: string) => Promise<boolean>;
+}): Promise<PosReaderSplashSweep>;
+/**
+ * Core's `org.logo.changed` (AGL-4048): a logo saved on the organization
+ * profile or the white-label brand reaches the readers of every store of
+ * that workspace now, not on the next beat. Raised after the save has
+ * answered, so nobody waits on it.
+ *
+ * {@link applyPosReaderSplash} for each store, the call the POS devices card
+ * makes: a store with no Location, or whose screen does not show the logo
+ * that moved (a dark-mode logo, a store showing its own image), costs reads
+ * and no Stripe call. A store that is locked is left alone, and a screen
+ * Stripe refused waits as it does on the beat; the beat, which stays, is
+ * the backstop for anything this misses. Never throws.
+ */
+export declare function onOrgLogoChanged(payload: Pick<PluginEventPayloads['org.logo.changed'], 'orgId'>, gate?: PluginJobHostGate): Promise<PosReaderSplashSweep>;
 export declare const posReaderSplashHandler: PluginApiHandler;
 export {};