@aglyn/plugins-commerce 1.0.0-beta.278 → 1.0.0-beta.283

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

@@ -0,0 +1,105 @@
+/**
+ * @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 { type MediaCdnScope } from '@aglyn/aglyn/app-utils/media-cdn-scope';
+import type { PluginApiHandler } 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";
+/** One family's default screen, as staff uploaded it. */
+export interface PlatformSplashImage {
+    storagePath: string;
+    sha256: string;
+    contentType: 'image/png' | 'image/jpeg';
+    bytes: number;
+    uploadedAtMs: number;
+    uploadedBy?: string;
+}
+export interface PlatformSplashDoc {
+    families?: Partial<Record<PosReaderSplashFamilyId, PlatformSplashImage>>;
+    updatedAtMs?: number;
+}
+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>;
+/** The default is usable once the S700/S710 screen is uploaded; the smaller one is drawn from it if absent. */
+export declare function platformSplashReady(doc: PlatformSplashDoc): boolean;
+interface LocatedAsset {
+    kind: 'asset';
+    scope: MediaCdnScope;
+    scopeSegment: string;
+    mediaId: string;
+    doc: Record<string, unknown>;
+    /** What changes when the asset's bytes do. */
+    version: string;
+}
+interface LocatedUrl {
+    kind: 'url';
+    url: string;
+    version: string;
+}
+type LocatedSource = LocatedAsset | LocatedUrl;
+/**
+ * The workspace's own logo: a white-label workspace's brand logo first,
+ * then the logo on its organization profile. Never the platform's: the
+ * resolved brand profile falls back to the platform's own logo for a
+ * 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 = {
+    mode: 'platform';
+    doc: PlatformSplashDoc;
+} | {
+    mode: 'logo' | 'artwork';
+    located: LocatedSource;
+};
+export interface PosReaderSplashPlan {
+    choice: PosReaderSplashChoice | null;
+    effectiveChoice: PosReaderSplashChoice;
+    whiteLabel: boolean;
+    productName: string;
+    platformReady: boolean;
+    logoValue: string | null;
+    image: {
+        mediaScope: string;
+        mediaId: string;
+    } | null;
+    /** `none` when the readers show Stripe's standard screen. */
+    key: string;
+    problem: string | null;
+    source: SplashSource | null;
+}
+export declare function planPosReaderSplash(hostId: string, org: Record<string, any> | null, config: Record<string, any> | undefined, platform?: PlatformSplashDoc): Promise<PosReaderSplashPlan>;
+/** 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 {
+    outcome: 'unchanged' | 'applied' | 'cleared' | 'skipped' | 'failed';
+    plan: PosReaderSplashPlan | null;
+    problem: string | null;
+}
+/**
+ * Puts the store's start-up screen on its readers' configuration when it
+ * changed since it was last applied. Never throws: a failure is recorded on
+ * the store's terminal document and returned, and the readers keep their
+ * previous screen.
+ */
+export declare function applyPosReaderSplash(hostId: string, options?: {
+    org?: Record<string, any> | null;
+    platform?: PlatformSplashDoc;
+    force?: boolean;
+}): Promise<PosReaderSplashApplyResult>;
+export declare const posReaderSplashHandler: PluginApiHandler;
+export {};

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

@@ -0,0 +1,548 @@
+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 } from "node:crypto";
+import { parseMediaCdnScope } from "@aglyn/aglyn/app-utils/media-cdn-scope";
+import { formatMediaRef, isMediaCdnPath, MEDIA_CDN_ROUTE, mediaRefFromStorageUrl, parseMediaRef, resolveMediaSrc } from "@aglyn/aglyn/app-utils/media-ref";
+import { checkEntitlement, resolveBrandingProfile } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { visibleToHost } from "@aglyn/aglyn/app-utils/scope-tokens";
+import { firebaseAdmin, getOrgForHost } from "@aglyn/tenant-data-admin";
+import { isPosReaderSplashChoice, POS_READER_SPLASH_DEVICE_TYPES, POS_READER_SPLASH_FAMILIES, POS_READER_SPLASH_SOURCE_MAX_BYTES, POS_READER_SPLASH_SOURCE_TYPES, posReaderSplashArtworkProblem, posReaderSplashEffectiveChoice } from "../model/pos-reader-splash.js";
+import { authorizePosStaff, posRequestBody } from "./pos-auth.js";
+import { PosReaderSplashRenderError, posReaderSplashImageFacts, renderPosReaderSplash } from "./pos-reader-splash-render.js";
+import { POS_STRIPE_VERSION, posTerminalAvailable } from "./pos-stripe.js";
+import { savePosReaderConfiguration } from "./pos-terminal.js";
+/*==========================================
+ * A STORE'S CARD READERS SHOW ITS START-UP SCREEN (AGL-4048).
+ *
+ * ## Where it lives
+ *
+ * Readers and Locations are the PLATFORM's (the destination-charge model,
+ * `pos-terminal.ts`), one Location per site. The screen is set on that
+ * site's one Terminal Configuration, the one reader tipping already uses,
+ * per device type (`stripe_s700`, `stripe_s710`, `bbpos_wisepos_e`), from a
+ * File uploaded to Stripe with purpose `terminal_reader_splashscreen`.
+ *
+ * The platform's account-default configuration is NEVER given a screen. A
+ * Location without an override inherits it, so an account default would put
+ * the platform's brand on a white-label store's readers, which is the one
+ * thing the white-label rule forbids. Staff's default screen is applied per
+ * Location instead, to the stores that use it.
+ *
+ * ## What is applied
+ *
+ * `hosts/{hostId}/terminal/config.splash` holds the store's choice
+ * (`model/pos-reader-splash.ts`); the screen applied is described by a KEY
+ * built from cheap metadata only: the choice, the platform default's
+ * version, the logo's address and its asset's content digest, the picked
+ * image's. `splashAppliedKey` records the last key that reached Stripe, so
+ * applying again with nothing changed makes no Stripe call at all, and a
+ * changed logo, a new staff default or a new choice makes exactly one round
+ * of uploads. Every upload and the first configuration write are keyed by
+ * content, so a retried apply never makes a second file or configuration.
+ *
+ * ## When it is applied
+ *
+ *   - when the store's Location is created (its first reader);
+ *   - when the POS devices card saves a choice, or opens and finds the key
+ *     stale (a logo changed since);
+ *   - when staff change the default, for every store with a Location
+ *     (`pos-reader-splash-admin.ts`).
+ *
+ * Never on the payment path: drawing and uploading takes a second or two,
+ * and a reader with an older screen still takes the payment.
+ *
+ * ## Test mode first
+ *
+ * Gated by `posTerminalAvailable()`: always in test mode, in live mode only
+ * once `STRIPE_TERMINAL_LIVE_ENABLED` is on, like every reader control.
+ *=========================================*/ /** Raised when the drawing or the Location changes how keys are built. */ const RENDER_VERSION = 'v1';
+/** `platformSettings/posReaderSplash`: staff's default screen. */ export const POS_READER_SPLASH_SETTINGS_ID = 'posReaderSplash';
+const firestore = ()=>firebaseAdmin.app().firestore();
+function terminalConfigRef(hostId) {
+    return firestore().collection('hosts').doc(hostId).collection('terminal').doc('config');
+}
+export function platformSplashRef() {
+    return firestore().collection('platformSettings').doc(POS_READER_SPLASH_SETTINGS_ID);
+}
+export function posReaderSplashBucket() {
+    return firebaseAdmin.app().storage().bucket(process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET || undefined);
+}
+export async function readPlatformSplash() {
+    const snapshot = await platformSplashRef().get();
+    return snapshot.exists ? snapshot.data() : {};
+}
+/** The default is usable once the S700/S710 screen is uploaded; the smaller one is drawn from it if absent. */ export function platformSplashReady(doc) {
+    var _doc_families_portraitlarge, _doc_families;
+    return Boolean((_doc_families = doc.families) == null ? void 0 : (_doc_families_portraitlarge = _doc_families['portrait-large']) == null ? void 0 : _doc_families_portraitlarge.storagePath);
+}
+function platformSplashVersion(doc) {
+    return POS_READER_SPLASH_FAMILIES.map((family)=>{
+        var _ref;
+        var _doc_families_family_id, _doc_families;
+        return (_ref = (_doc_families = doc.families) == null ? void 0 : (_doc_families_family_id = _doc_families[family.id]) == null ? void 0 : _doc_families_family_id.sha256) != null ? _ref : '-';
+    }).join('.');
+}
+const digest = (value)=>createHash('sha256').update(value).digest('hex');
+const cleanString = (value)=>typeof value === 'string' ? value.trim() : '';
+async function locateMediaAsset(scopeSegment, mediaId, hostId, orgId) {
+    var _doc_contentType, _ref, _doc_updatedAtMs;
+    const scope = parseMediaCdnScope(scopeSegment);
+    if (!scope || !/^[A-Za-z0-9_-]{1,64}$/.test(mediaId)) return null;
+    const owned = scope.isOrg ? scope.scopeId === orgId : scope.scopeId === hostId;
+    if (!owned) return null;
+    const snapshot = await firestore().collection(scope.isOrg ? 'orgs' : 'hosts').doc(scope.scopeId).collection('media').doc(mediaId).get();
+    const doc = snapshot.exists ? snapshot.data() : null;
+    if (!doc || doc['deletedAt'] || doc['private']) return null;
+    if (scope.isOrg && !visibleToHost(doc['visibleTo'], hostId)) return null;
+    if (!/^image\//.test(String((_doc_contentType = doc['contentType']) != null ? _doc_contentType : ''))) return null;
+    if (typeof doc['sizeBytes'] === 'number' && doc['sizeBytes'] > POS_READER_SPLASH_SOURCE_MAX_BYTES) return null;
+    const version = cleanString(doc['contentSha256']) || cleanString(doc['contentHash']) || String((_ref = (_doc_updatedAtMs = doc['updatedAtMs']) != null ? _doc_updatedAtMs : doc['sizeBytes']) != null ? _ref : '');
+    return {
+        kind: 'asset',
+        scope,
+        scopeSegment,
+        mediaId,
+        doc,
+        version
+    };
+}
+/** Where a stored logo or image value lives, or null when it cannot be read. */ async function locateSource(value, hostId, orgId) {
+    const stored = parseMediaRef(value) ? value : mediaRefFromStorageUrl(value);
+    const ref = stored ? parseMediaRef(stored) : null;
+    if (ref) return locateMediaAsset(ref.scope, ref.mediaId, hostId, orgId);
+    if (isMediaCdnPath(value)) {
+        const rest = value.slice(`${MEDIA_CDN_ROUTE}/`.length).split('?')[0];
+        const slash = rest.indexOf('/');
+        if (slash <= 0) return null;
+        return locateMediaAsset(rest.slice(0, slash), rest.slice(slash + 1), hostId, orgId);
+    }
+    // `isMediaCdnPath` narrows a string it refuses to `never`; the value is still the string.
+    const address = value;
+    if (/^https:\/\//.test(address) && address.length <= 2000) return {
+        kind: 'url',
+        url: address,
+        version: address
+    };
+    return null;
+}
+async function readAssetBytes(asset) {
+    const { mediaCdnServeBlock, mediaStoragePathInScope } = await import("./pos-reader-splash-server.js");
+    const blocked = await mediaCdnServeBlock(asset.scope, {
+        contentSha256: typeof asset.doc['contentSha256'] === 'string' ? asset.doc['contentSha256'] : undefined,
+        contentHash: typeof asset.doc['contentHash'] === 'string' ? asset.doc['contentHash'] : undefined,
+        scopeSegment: asset.scopeSegment,
+        mediaId: asset.mediaId
+    });
+    if (blocked) return null;
+    const objectPath = mediaStoragePathInScope({
+        storagePath: asset.doc['storagePath'],
+        base: `${asset.scope.isOrg ? 'orgs' : 'hosts'}/${asset.scope.scopeId}`,
+        mediaId: asset.mediaId
+    });
+    const [buffer] = await posReaderSplashBucket().file(objectPath).download();
+    return buffer.length > POS_READER_SPLASH_SOURCE_MAX_BYTES ? null : buffer;
+}
+const FETCH_TIMEOUT_MS = 8000;
+async function fetchPublicImage(url) {
+    const { createPinnedDispatcher, resolvePublicIp } = await import("./pos-reader-splash-server.js");
+    const pinnedIp = await resolvePublicIp(new URL(url).hostname);
+    if (!pinnedIp) return null;
+    const dispatcher = createPinnedDispatcher(pinnedIp);
+    const controller = new AbortController();
+    const timeout = setTimeout(()=>controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        var _response_headers_get, _response_headers_get1;
+        const init = {
+            redirect: 'error',
+            signal: controller.signal,
+            dispatcher
+        };
+        const response = await fetch(url, init);
+        if (!response.ok) return null;
+        if (!/^image\//.test((_response_headers_get = response.headers.get('content-type')) != null ? _response_headers_get : '')) return null;
+        const declared = Number((_response_headers_get1 = response.headers.get('content-length')) != null ? _response_headers_get1 : 0);
+        if (declared > POS_READER_SPLASH_SOURCE_MAX_BYTES) return null;
+        const buffer = Buffer.from(await response.arrayBuffer());
+        return buffer.length > POS_READER_SPLASH_SOURCE_MAX_BYTES ? null : buffer;
+    } catch (unused) {
+        return null;
+    } finally{
+        clearTimeout(timeout);
+        dispatcher.close == null ? void 0 : dispatcher.close.call(dispatcher).catch(()=>undefined);
+    }
+}
+async function readSourceBytes(source) {
+    return source.kind === 'asset' ? readAssetBytes(source) : fetchPublicImage(source.url);
+}
+/*==========================================
+ * WHAT A STORE SHOWS.
+ *=========================================*/ /**
+ * The workspace's own logo: a white-label workspace's brand logo first,
+ * then the logo on its organization profile. Never the platform's: the
+ * resolved brand profile falls back to the platform's own logo for a
+ * workspace without a brand, so its `logoUrl` is not read here.
+ */ export function workspaceLogoValue(org, whiteLabel) {
+    var _org_brandingProfile;
+    const brand = whiteLabel ? cleanString(org == null ? void 0 : (_org_brandingProfile = org['brandingProfile']) == null ? void 0 : _org_brandingProfile['logoUrl']) : '';
+    return brand || cleanString(org == null ? void 0 : org['logoUrl']) || null;
+}
+const NO_LOGO = 'Add a logo to your organization profile to show it on your card readers.';
+const NO_IMAGE = 'The image picked for your card readers is no longer in your media library. Choose another.';
+export async function planPosReaderSplash(hostId, org, config, platform) {
+    var _ref, _ref1;
+    const orgId = String((_ref = org == null ? void 0 : org['id']) != null ? _ref : '');
+    const whiteLabel = checkEntitlement(org, 'whiteLabel');
+    const productName = resolveBrandingProfile(org).productName;
+    const setting = (_ref1 = config == null ? void 0 : config['splash']) != null ? _ref1 : null;
+    const choice = isPosReaderSplashChoice(setting == null ? void 0 : setting.choice) ? setting.choice : null;
+    const effectiveChoice = posReaderSplashEffectiveChoice(choice, whiteLabel);
+    const doc = platform != null ? platform : await readPlatformSplash();
+    const logoValue = workspaceLogoValue(org, whiteLabel);
+    const image = (setting == null ? void 0 : setting.mediaScope) && (setting == null ? void 0 : setting.mediaId) ? {
+        mediaScope: setting.mediaScope,
+        mediaId: setting.mediaId
+    } : null;
+    const base = {
+        choice,
+        effectiveChoice,
+        whiteLabel,
+        productName,
+        platformReady: platformSplashReady(doc),
+        logoValue,
+        image
+    };
+    if (effectiveChoice === 'platform') {
+        // The white-label rule is in `posReaderSplashEffectiveChoice`; this is
+        // the guard behind it, because this branch is the platform's brand.
+        if (whiteLabel || !platformSplashReady(doc)) return _extends({}, base, {
+            key: 'none',
+            problem: null,
+            source: null
+        });
+        return _extends({}, base, {
+            key: `platform:${RENDER_VERSION}:${platformSplashVersion(doc)}`,
+            problem: null,
+            source: {
+                mode: 'platform',
+                doc
+            }
+        });
+    }
+    if (effectiveChoice === 'logo') {
+        const located = logoValue ? await locateSource(logoValue, hostId, orgId) : null;
+        if (!located) return _extends({}, base, {
+            key: 'none',
+            problem: NO_LOGO,
+            source: null
+        });
+        return _extends({}, base, {
+            key: `logo:${RENDER_VERSION}:${digest(`${logoValue}|${located.version}`).slice(0, 24)}`,
+            problem: null,
+            source: {
+                mode: 'logo',
+                located
+            }
+        });
+    }
+    const located = image ? await locateMediaAsset(image.mediaScope, image.mediaId, hostId, orgId) : null;
+    if (!located) return _extends({}, base, {
+        key: 'none',
+        problem: NO_IMAGE,
+        source: null
+    });
+    return _extends({}, base, {
+        key: `image:${RENDER_VERSION}:${digest(`${image == null ? void 0 : image.mediaScope}/${image == null ? void 0 : image.mediaId}|${located.version}`).slice(0, 24)}`,
+        problem: null,
+        source: {
+            mode: 'artwork',
+            located
+        }
+    });
+}
+async function loadSharpFactory() {
+    const { loadSharp } = await import("./pos-reader-splash-server.js");
+    return loadSharp();
+}
+/** Each family's screen for the plan, ready for Stripe. */ async function drawScreens(source) {
+    const sharp = await loadSharpFactory();
+    const screens = {};
+    if (source.mode === 'platform') {
+        var _source_doc_families;
+        const bucket = posReaderSplashBucket();
+        const read = async (image)=>(await bucket.file(image.storagePath).download())[0];
+        const large = (_source_doc_families = source.doc.families) == null ? void 0 : _source_doc_families['portrait-large'];
+        const largeBody = await read(large);
+        for (const family of POS_READER_SPLASH_FAMILIES){
+            var _source_doc_families1;
+            const own = (_source_doc_families1 = source.doc.families) == null ? void 0 : _source_doc_families1[family.id];
+            // Staff's own screen for the family is sent as uploaded: it was checked
+            // against Stripe's rules for exactly this family then. A family staff
+            // left empty is drawn from the S700/S710 screen, the same 9:16.
+            screens[family.id] = (own == null ? void 0 : own.storagePath) ? {
+                body: own === large ? largeBody : await read(own),
+                contentType: own.contentType
+            } : await renderPosReaderSplash({
+                source: largeBody,
+                family,
+                mode: 'artwork',
+                sharp
+            });
+        }
+        return screens;
+    }
+    const bytes = await readSourceBytes(source.located);
+    if (!bytes) throw new PosReaderSplashRenderError('That image could not be read.');
+    if (source.mode === 'artwork') {
+        var _ref, _ref1;
+        const facts = await posReaderSplashImageFacts(sharp, bytes);
+        const problem = posReaderSplashArtworkProblem({
+            contentType: (facts == null ? void 0 : facts.contentType) || null,
+            bytes: bytes.length,
+            width: (_ref = facts == null ? void 0 : facts.width) != null ? _ref : 0,
+            height: (_ref1 = facts == null ? void 0 : facts.height) != null ? _ref1 : 0
+        });
+        if (problem) throw new PosReaderSplashRenderError(problem);
+    }
+    for (const family of POS_READER_SPLASH_FAMILIES){
+        screens[family.id] = await renderPosReaderSplash({
+            source: bytes,
+            family,
+            mode: source.mode,
+            sharp
+        });
+    }
+    return screens;
+}
+/** One screen uploaded to Stripe, keyed by its content so a retry makes no second file. */ async function uploadSplashFile(hostId, family, screen) {
+    const form = new FormData();
+    form.append('purpose', 'terminal_reader_splashscreen');
+    const extension = screen.contentType === 'image/png' ? 'png' : 'jpg';
+    form.append('file', new Blob([
+        new Uint8Array(screen.body)
+    ], {
+        type: screen.contentType
+    }), `start-up-${family.id}.${extension}`);
+    const response = await fetch('https://files.stripe.com/v1/files', {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+            'Stripe-Version': POS_STRIPE_VERSION,
+            'Idempotency-Key': `pos-splash-file:${hostId}:${family.id}:${digest(screen.body).slice(0, 32)}`
+        },
+        body: form
+    });
+    const body = await response.json().catch(()=>({}));
+    if (!response.ok || !body.id) {
+        var _body_error;
+        throw new PosReaderSplashRenderError(((_body_error = body.error) == null ? void 0 : _body_error.message) || 'Stripe did not accept the start-up screen.');
+    }
+    return String(body.id);
+}
+/** The org that owns the site, with its id on it (`planPosReaderSplash` reads it). */ export async function ownerOrgOf(hostId) {
+    var _ref, _owner_org_id;
+    const owner = await getOrgForHost(hostId).catch(()=>null);
+    if (!(owner == null ? void 0 : owner.org)) return null;
+    return _extends({}, owner.org, {
+        id: String((_ref = (_owner_org_id = owner.org.id) != null ? _owner_org_id : owner.orgId) != null ? _ref : '')
+    });
+}
+/**
+ * Puts the store's start-up screen on its readers' configuration when it
+ * changed since it was last applied. Never throws: a failure is recorded on
+ * the store's terminal document and returned, and the readers keep their
+ * previous screen.
+ */ export async function applyPosReaderSplash(hostId, options = {}) {
+    if (!posTerminalAvailable()) return {
+        outcome: 'skipped',
+        plan: null,
+        problem: null
+    };
+    const ref = terminalConfigRef(hostId);
+    const config = (await ref.get()).data();
+    if (!(config == null ? void 0 : config['stripeLocationId'])) return {
+        outcome: 'skipped',
+        plan: null,
+        problem: null
+    };
+    const org = options.org !== undefined ? options.org : await ownerOrgOf(hostId);
+    const plan = await planPosReaderSplash(hostId, org, config, options.platform);
+    const applied = typeof config['splashAppliedKey'] === 'string' ? config['splashAppliedKey'] : null;
+    // Nothing to show and nothing ever shown: the readers already show
+    // Stripe's standard screen, and no Stripe call is needed to keep it.
+    if (plan.key === 'none' && (applied === null || applied === 'none') && !options.force) {
+        return {
+            outcome: 'unchanged',
+            plan,
+            problem: plan.problem
+        };
+    }
+    if (plan.key === applied && !options.force) return {
+        outcome: 'unchanged',
+        plan,
+        problem: plan.problem
+    };
+    try {
+        const params = {};
+        if (plan.key === 'none' || !plan.source) {
+            // An empty value unsets the device's screen on this configuration.
+            for (const deviceType of POS_READER_SPLASH_DEVICE_TYPES)params[deviceType] = '';
+        } else {
+            const screens = await drawScreens(plan.source);
+            for (const family of POS_READER_SPLASH_FAMILIES){
+                const fileId = await uploadSplashFile(hostId, family, screens[family.id]);
+                for (const deviceType of family.deviceTypes)params[`${deviceType}[splashscreen]`] = fileId;
+            }
+        }
+        const saved = await savePosReaderConfiguration(hostId, params, `splash:${digest(plan.key).slice(0, 24)}`);
+        if (!saved.ok) throw new PosReaderSplashRenderError('Stripe did not accept the start-up screen. Try again.');
+        await ref.set({
+            splashAppliedKey: plan.key,
+            splashAppliedAtMs: Date.now(),
+            splashProblem: firebaseAdmin.firestore.FieldValue.delete()
+        }, {
+            merge: true
+        });
+        return {
+            outcome: plan.key === 'none' ? 'cleared' : 'applied',
+            plan,
+            problem: plan.problem
+        };
+    } catch (error) {
+        const problem = error instanceof PosReaderSplashRenderError ? error.message : 'The start-up screen could not be applied. Try again.';
+        if (!(error instanceof PosReaderSplashRenderError)) console.error('[pos-reader-splash]', hostId, error);
+        await ref.set({
+            splashProblem: problem,
+            splashFailedAtMs: Date.now()
+        }, {
+            merge: true
+        }).catch(()=>undefined);
+        return {
+            outcome: 'failed',
+            plan,
+            problem
+        };
+    }
+}
+/*==========================================
+ * `POST /api/commerce/pos-reader-splash`: the POS devices card's setting.
+ *
+ *   status  the store's choice and what it shows (re-applies a stale one)
+ *   save    { choice, mediaScope?, mediaId? } — store and apply
+ *
+ * Gated like a sale (`authorizePosStaff`), as every reader control is.
+ *=========================================*/ function statusOf(plan, config, hostId, problem) {
+    var _ref, _ref1, _ref2, _ref3, _ref4, _resolveMediaSrc, _resolveMediaSrc1;
+    return {
+        available: posTerminalAvailable(),
+        choice: (_ref = plan == null ? void 0 : plan.choice) != null ? _ref : null,
+        effectiveChoice: (_ref1 = plan == null ? void 0 : plan.effectiveChoice) != null ? _ref1 : 'platform',
+        whiteLabel: (_ref2 = plan == null ? void 0 : plan.whiteLabel) != null ? _ref2 : false,
+        productName: (_ref3 = plan == null ? void 0 : plan.productName) != null ? _ref3 : '',
+        platformReady: (_ref4 = plan == null ? void 0 : plan.platformReady) != null ? _ref4 : false,
+        logoUrl: (plan == null ? void 0 : plan.logoValue) ? (_resolveMediaSrc = resolveMediaSrc(plan.logoValue, {
+            hostId
+        })) != null ? _resolveMediaSrc : null : null,
+        image: (plan == null ? void 0 : plan.image) ? _extends({}, plan.image, {
+            url: (_resolveMediaSrc1 = resolveMediaSrc(formatMediaRef(plan.image.mediaScope, plan.image.mediaId), {
+                hostId
+            })) != null ? _resolveMediaSrc1 : null
+        }) : null,
+        locationReady: Boolean(config == null ? void 0 : config['stripeLocationId']),
+        appliedAtMs: typeof (config == null ? void 0 : config['splashAppliedAtMs']) === 'number' ? config['splashAppliedAtMs'] : null,
+        problem: problem != null ? problem : typeof (config == null ? void 0 : config['splashProblem']) === 'string' ? config['splashProblem'] : null
+    };
+}
+async function currentStatus(hostId, org) {
+    var _result_plan;
+    const result = await applyPosReaderSplash(hostId, {
+        org
+    });
+    const config = (await terminalConfigRef(hostId).get()).data();
+    const plan = (_result_plan = result.plan) != null ? _result_plan : await planPosReaderSplash(hostId, org, config);
+    return statusOf(plan, config, hostId, result.outcome === 'failed' ? result.problem : plan.problem);
+}
+export const posReaderSplashHandler = async (req, res)=>{
+    var _body_hostId, _body_action;
+    if (req.method !== 'POST') return res.status(405).json({
+        error: 'Method not allowed'
+    });
+    const body = posRequestBody(req);
+    const hostId = String((_body_hostId = body['hostId']) != null ? _body_hostId : '');
+    const gate = await authorizePosStaff(req, hostId);
+    if ('error' in gate) return res.status(gate.status).json({
+        error: gate.error
+    });
+    const staff = gate.staff;
+    const org = staff.org ? _extends({}, staff.org, {
+        id: staff.orgId
+    }) : null;
+    const action = String((_body_action = body['action']) != null ? _body_action : '');
+    try {
+        if (action === 'status') return res.status(200).json(await currentStatus(hostId, org));
+        if (action !== 'save') return res.status(400).json({
+            error: 'Unknown action'
+        });
+        if (!posTerminalAvailable()) return res.status(409).json({
+            error: 'Card readers are not available yet.'
+        });
+        const choice = body['choice'];
+        if (!isPosReaderSplashChoice(choice)) return res.status(400).json({
+            error: 'Choose what your readers show.'
+        });
+        const whiteLabel = checkEntitlement(staff.org, 'whiteLabel');
+        if (choice === 'platform' && whiteLabel) {
+            return res.status(400).json({
+                error: 'Choose your logo or your own image.'
+            });
+        }
+        const setting = {
+            choice,
+            updatedAtMs: Date.now(),
+            updatedBy: staff.uid
+        };
+        if (choice === 'image') {
+            var _body_mediaScope, _body_mediaId, _located_doc_contentType;
+            const mediaScope = String((_body_mediaScope = body['mediaScope']) != null ? _body_mediaScope : '');
+            const mediaId = String((_body_mediaId = body['mediaId']) != null ? _body_mediaId : '');
+            const located = await locateMediaAsset(mediaScope, mediaId, hostId, staff.orgId);
+            if (!located) return res.status(400).json({
+                error: 'Choose an image from your media library.'
+            });
+            const contentType = String((_located_doc_contentType = located.doc['contentType']) != null ? _located_doc_contentType : '');
+            if (!POS_READER_SPLASH_SOURCE_TYPES.includes(contentType)) {
+                return res.status(400).json({
+                    error: 'Choose a PNG, JPEG or WebP image.'
+                });
+            }
+            setting.mediaScope = mediaScope;
+            setting.mediaId = mediaId;
+        }
+        await terminalConfigRef(hostId).set({
+            splash: setting
+        }, {
+            merge: true
+        });
+        return res.status(200).json(await currentStatus(hostId, org));
+    } catch (error) {
+        console.error('[pos-reader-splash]', action, error);
+        return res.status(500).json({
+            error: 'The start-up screen could not be updated'
+        });
+    }
+};
+
+//# sourceMappingURL=pos-reader-splash.js.map