@aglyn/plugins-commerce 1.0.0-beta.229 → 1.0.0-beta.231

package/src/lib/server/pos-terminal-connection-token.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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 { PluginApiHandler } from '@aglyn/aglyn/server';
+import { type PosStaff } from './pos-auth';
+import { type PosTerminalAddress } from './pos-terminal';
+/**
+ * `POST /api/commerce/pos-terminal-connection-token` (AGL-3618): what the
+ * native Aglyn POS app's Stripe Terminal SDK (iOS and Android) needs to drive
+ * Tap to Pay and Bluetooth readers for ONE site.
+ *
+ * Gated exactly like a register sale (`authorizePosStaff`): a site role that
+ * may sell, `managePos`, and the `pos` entitlement. The app holds no key and
+ * no privileged path. Every token is scoped to the site's own Terminal
+ * Location, so the SDK can connect only to readers in that Location, and the
+ * PaymentIntents it collects are the server's own (`card-present-sdk`).
+ *
+ * Actions:
+ * - `token` (the default): the secret, the Location id, the merchant's
+ *   account id and display name, and test mode; or a 409 whose `code` names
+ *   what is missing: `terminal-unavailable`, `merchant-not-ready`,
+ *   `location-required`.
+ * - `status`: the same readiness as booleans, minting nothing.
+ * - `location`: registers the site's Location from an address, once.
+ */
+export declare const posTerminalConnectionTokenHandler: PluginApiHandler;
+/** Readiness as the native POS app's readers panel draws it. */
+export declare function terminalReadiness(staff: PosStaff): Promise<{
+    available: boolean;
+    testMode: boolean;
+    merchantReady: boolean;
+    locationReady: boolean;
+}>;
+/** An address from the native POS app, bounded the way `pos-readers` bounds it. */
+export declare function readPosTerminalAddress(raw: unknown): PosTerminalAddress | undefined;

package/src/lib/server/pos-terminal-connection-token.js

@@ -0,0 +1,166 @@
+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 { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { authorizePosStaff, posRequestBody } from "./pos-auth.js";
+import { posStripeTestMode, posTerminalAvailable } from "./pos-stripe.js";
+import { createPosTerminalConnectionToken, ensurePosTerminalLocation, posMerchantAccount, posTerminalLocationId } from "./pos-terminal.js";
+/**
+ * `POST /api/commerce/pos-terminal-connection-token` (AGL-3618): what the
+ * native Aglyn POS app's Stripe Terminal SDK (iOS and Android) needs to drive
+ * Tap to Pay and Bluetooth readers for ONE site.
+ *
+ * Gated exactly like a register sale (`authorizePosStaff`): a site role that
+ * may sell, `managePos`, and the `pos` entitlement. The app holds no key and
+ * no privileged path. Every token is scoped to the site's own Terminal
+ * Location, so the SDK can connect only to readers in that Location, and the
+ * PaymentIntents it collects are the server's own (`card-present-sdk`).
+ *
+ * Actions:
+ * - `token` (the default): the secret, the Location id, the merchant's
+ *   account id and display name, and test mode; or a 409 whose `code` names
+ *   what is missing: `terminal-unavailable`, `merchant-not-ready`,
+ *   `location-required`.
+ * - `status`: the same readiness as booleans, minting nothing.
+ * - `location`: registers the site's Location from an address, once.
+ */ export const posTerminalConnectionTokenHandler = 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 gate = await authorizePosStaff(req, String((_body_hostId = body['hostId']) != null ? _body_hostId : ''));
+    if ('error' in gate) return res.status(gate.status).json({
+        error: gate.error
+    });
+    const staff = gate.staff;
+    const action = String((_body_action = body['action']) != null ? _body_action : 'token');
+    try {
+        switch(action){
+            case 'token':
+                return await mintToken(staff, res);
+            case 'status':
+                return res.status(200).json(await terminalReadiness(staff));
+            case 'location':
+                return await registerLocation(staff, body, res);
+            default:
+                return res.status(400).json({
+                    error: 'Unknown action'
+                });
+        }
+    } catch (error) {
+        console.error('[pos-terminal-connection-token]', action, error);
+        return res.status(500).json({
+            error: 'Card readers could not be reached. Try again.'
+        });
+    }
+};
+async function hostName(hostId) {
+    var _ref, _host_get;
+    const host = await firebaseAdmin.app().firestore().collection('hosts').doc(hostId).get();
+    return String((_ref = (_host_get = host.get('name')) != null ? _host_get : host.get('title')) != null ? _ref : '').trim().slice(0, 100) || 'Store';
+}
+/** Readiness as the native POS app's readers panel draws it. */ export async function terminalReadiness(staff) {
+    const available = posTerminalAvailable();
+    const [merchant, locationId] = await Promise.all([
+        posMerchantAccount(staff.hostId, staff.org),
+        posTerminalLocationId(staff.hostId)
+    ]);
+    return {
+        available,
+        testMode: posStripeTestMode(),
+        merchantReady: Boolean(merchant),
+        locationReady: Boolean(locationId)
+    };
+}
+async function mintToken(staff, res) {
+    if (!posTerminalAvailable()) {
+        return res.status(409).json({
+            error: 'Card readers are not available yet.',
+            code: 'terminal-unavailable'
+        });
+    }
+    // A reader that connects for a store that cannot take card payments would
+    // only fail at the first sale, in front of a customer.
+    const merchantAccountId = await posMerchantAccount(staff.hostId, staff.org);
+    if (!merchantAccountId) {
+        return res.status(409).json({
+            error: 'Finish setting up payments in the console before taking cards.',
+            code: 'merchant-not-ready'
+        });
+    }
+    const token = await createPosTerminalConnectionToken(staff.hostId);
+    if (!token) {
+        const locationId = await posTerminalLocationId(staff.hostId);
+        return locationId ? res.status(502).json({
+            error: 'Stripe did not answer. Try again.'
+        }) : res.status(409).json({
+            error: 'Add the store address card readers are used at.',
+            code: 'location-required'
+        });
+    }
+    return res.status(200).json({
+        secret: token.secret,
+        locationId: token.locationId,
+        // Identifies the merchant only. It is never the SDK's `onBehalfOf`:
+        // card-present charges settle on Aglyn's platform account (AGL-3607), and
+        // an intent collected under a different account would be refused.
+        merchantAccountId,
+        merchantDisplayName: await hostName(staff.hostId),
+        testMode: posStripeTestMode()
+    });
+}
+/** An address from the native POS app, bounded the way `pos-readers` bounds it. */ export function readPosTerminalAddress(raw) {
+    if (!raw || typeof raw !== 'object') return undefined;
+    const address = raw;
+    const text = (value, max)=>String(value != null ? value : '').trim().slice(0, max);
+    return _extends({
+        line1: text(address['line1'], 200)
+    }, text(address['line2'], 200) ? {
+        line2: text(address['line2'], 200)
+    } : {}, {
+        city: text(address['city'], 100)
+    }, text(address['state'], 100) ? {
+        state: text(address['state'], 100)
+    } : {}, {
+        postalCode: text(address['postalCode'], 20),
+        country: text(address['country'], 2).toUpperCase()
+    });
+}
+async function registerLocation(staff, body, res) {
+    if (!posTerminalAvailable()) {
+        return res.status(409).json({
+            error: 'Card readers are not available yet.',
+            code: 'terminal-unavailable'
+        });
+    }
+    const address = readPosTerminalAddress(body['address']);
+    const location = await ensurePosTerminalLocation(_extends({
+        hostId: staff.hostId,
+        orgId: staff.orgId,
+        displayName: await hostName(staff.hostId)
+    }, address ? {
+        address
+    } : {}));
+    if ('error' in location) return res.status(location.status).json({
+        error: location.error
+    });
+    return res.status(200).json({
+        locationId: location.locationId
+    });
+}
+
+//# sourceMappingURL=pos-terminal-connection-token.js.map

package/src/lib/server/pos-terminal-connection-token.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/pos-terminal-connection-token.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 { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport type { PluginApiHandler } from '@aglyn/aglyn/server'\nimport { authorizePosStaff, posRequestBody, type PosStaff } from './pos-auth'\nimport { posStripeTestMode, posTerminalAvailable } from './pos-stripe'\nimport {\n  createPosTerminalConnectionToken,\n  ensurePosTerminalLocation,\n  posMerchantAccount,\n  posTerminalLocationId,\n  type PosTerminalAddress,\n} from './pos-terminal'\n\n/**\n * `POST /api/commerce/pos-terminal-connection-token` (AGL-3618): what the\n * native Aglyn POS app's Stripe Terminal SDK (iOS and Android) needs to drive\n * Tap to Pay and Bluetooth readers for ONE site.\n *\n * Gated exactly like a register sale (`authorizePosStaff`): a site role that\n * may sell, `managePos`, and the `pos` entitlement. The app holds no key and\n * no privileged path. Every token is scoped to the site's own Terminal\n * Location, so the SDK can connect only to readers in that Location, and the\n * PaymentIntents it collects are the server's own (`card-present-sdk`).\n *\n * Actions:\n * - `token` (the default): the secret, the Location id, the merchant's\n *   account id and display name, and test mode; or a 409 whose `code` names\n *   what is missing: `terminal-unavailable`, `merchant-not-ready`,\n *   `location-required`.\n * - `status`: the same readiness as booleans, minting nothing.\n * - `location`: registers the site's Location from an address, once.\n */\nexport const posTerminalConnectionTokenHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') return res.status(405).json({ error: 'Method not allowed' })\n  const body = posRequestBody(req)\n  const gate = await authorizePosStaff(req, String(body['hostId'] ?? ''))\n  if ('error' in gate) return res.status(gate.status).json({ error: gate.error })\n  const staff = gate.staff\n  const action = String(body['action'] ?? 'token')\n  try {\n    switch (action) {\n      case 'token':\n        return await mintToken(staff, res)\n      case 'status':\n        return res.status(200).json(await terminalReadiness(staff))\n      case 'location':\n        return await registerLocation(staff, body, res)\n      default:\n        return res.status(400).json({ error: 'Unknown action' })\n    }\n  } catch (error) {\n    console.error('[pos-terminal-connection-token]', action, error)\n    return res.status(500).json({ error: 'Card readers could not be reached. Try again.' })\n  }\n}\n\nasync function hostName(hostId: string): Promise<string> {\n  const host = await firebaseAdmin.app().firestore().collection('hosts').doc(hostId).get()\n  return String(host.get('name') ?? host.get('title') ?? '').trim().slice(0, 100) || 'Store'\n}\n\n/** Readiness as the native POS app's readers panel draws it. */\nexport async function terminalReadiness(staff: PosStaff) {\n  const available = posTerminalAvailable()\n  const [merchant, locationId] = await Promise.all([\n    posMerchantAccount(staff.hostId, staff.org),\n    posTerminalLocationId(staff.hostId),\n  ])\n  return {\n    available,\n    testMode: posStripeTestMode(),\n    merchantReady: Boolean(merchant),\n    locationReady: Boolean(locationId),\n  }\n}\n\ntype Res = Parameters<PluginApiHandler>[1]\n\nasync function mintToken(staff: PosStaff, res: Res) {\n  if (!posTerminalAvailable()) {\n    return res\n      .status(409)\n      .json({ error: 'Card readers are not available yet.', code: 'terminal-unavailable' })\n  }\n  // A reader that connects for a store that cannot take card payments would\n  // only fail at the first sale, in front of a customer.\n  const merchantAccountId = await posMerchantAccount(staff.hostId, staff.org)\n  if (!merchantAccountId) {\n    return res.status(409).json({\n      error: 'Finish setting up payments in the console before taking cards.',\n      code: 'merchant-not-ready',\n    })\n  }\n  const token = await createPosTerminalConnectionToken(staff.hostId)\n  if (!token) {\n    const locationId = await posTerminalLocationId(staff.hostId)\n    return locationId\n      ? res.status(502).json({ error: 'Stripe did not answer. Try again.' })\n      : res.status(409).json({\n          error: 'Add the store address card readers are used at.',\n          code: 'location-required',\n        })\n  }\n  return res.status(200).json({\n    secret: token.secret,\n    locationId: token.locationId,\n    // Identifies the merchant only. It is never the SDK's `onBehalfOf`:\n    // card-present charges settle on Aglyn's platform account (AGL-3607), and\n    // an intent collected under a different account would be refused.\n    merchantAccountId,\n    merchantDisplayName: await hostName(staff.hostId),\n    testMode: posStripeTestMode(),\n  })\n}\n\n/** An address from the native POS app, bounded the way `pos-readers` bounds it. */\nexport function readPosTerminalAddress(raw: unknown): PosTerminalAddress | undefined {\n  if (!raw || typeof raw !== 'object') return undefined\n  const address = raw as Record<string, unknown>\n  const text = (value: unknown, max: number) => String(value ?? '').trim().slice(0, max)\n  return {\n    line1: text(address['line1'], 200),\n    ...(text(address['line2'], 200) ? { line2: text(address['line2'], 200) } : {}),\n    city: text(address['city'], 100),\n    ...(text(address['state'], 100) ? { state: text(address['state'], 100) } : {}),\n    postalCode: text(address['postalCode'], 20),\n    country: text(address['country'], 2).toUpperCase(),\n  }\n}\n\nasync function registerLocation(staff: PosStaff, body: Record<string, unknown>, res: Res) {\n  if (!posTerminalAvailable()) {\n    return res\n      .status(409)\n      .json({ error: 'Card readers are not available yet.', code: 'terminal-unavailable' })\n  }\n  const address = readPosTerminalAddress(body['address'])\n  const location = await ensurePosTerminalLocation({\n    hostId: staff.hostId,\n    orgId: staff.orgId,\n    displayName: await hostName(staff.hostId),\n    ...(address ? { address } : {}),\n  })\n  if ('error' in location) return res.status(location.status).json({ error: location.error })\n  return res.status(200).json({ locationId: location.locationId })\n}\n"],"names":["firebaseAdmin","authorizePosStaff","posRequestBody","posStripeTestMode","posTerminalAvailable","createPosTerminalConnectionToken","ensurePosTerminalLocation","posMerchantAccount","posTerminalLocationId","posTerminalConnectionTokenHandler","req","res","body","method","status","json","error","gate","String","staff","action","mintToken","terminalReadiness","registerLocation","console","hostName","hostId","host","app","firestore","collection","doc","get","trim","slice","available","merchant","locationId","Promise","all","org","testMode","merchantReady","Boolean","locationReady","code","merchantAccountId","token","secret","merchantDisplayName","readPosTerminalAddress","raw","undefined","address","text","value","max","line1","line2","city","state","postalCode","country","toUpperCase","location","orgId","displayName"],"mappings":"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"}

package/src/lib/server/pos-terminal.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @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 * as CommerceModel from '../model';
+import type { PosRegisterSettings } from '../plugin-config';
+import { type PosLiftedOrder, type PosPaymentOutcome } from './pos-sale';
+/** `hosts/{hostId}/terminalReaders/{readerId}`. */
+export interface PosTerminalReader {
+    label: string;
+    registerId?: string;
+    stripeLocationId: string;
+    deviceType?: string;
+    serialNumber?: string;
+    status?: 'online' | 'offline' | string;
+    livemode: boolean;
+    createdAtMs: number;
+    createdBy?: string;
+    lastSeenAtMs?: number;
+}
+/** The merchant's connected account, when it can take card payments now. */
+export declare function posMerchantAccount(hostId: string, org: Record<string, any> | null): Promise<string | null>;
+/** A reader id as Stripe mints them; anything else never reaches Stripe. */
+export declare function isTerminalReaderId(value: unknown): value is string;
+/** The reader, when it is THIS site's; null for anyone else's or none. */
+export declare function ownedTerminalReader(hostId: string, readerId: unknown): Promise<(PosTerminalReader & {
+    id: string;
+}) | null>;
+/** A Terminal Location's address, as the console sends it. */
+export interface PosTerminalAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    country: string;
+}
+export declare function posTerminalAddressProblem(address: Partial<PosTerminalAddress> | undefined): string | null;
+/**
+ * The site's Terminal Location, created on first use (on the PLATFORM, with
+ * the merchant named in metadata). Its address is the store's, because Stripe
+ * uses it to configure the reader for the right country.
+ */
+export declare function ensurePosTerminalLocation(options: {
+    hostId: string;
+    orgId: string;
+    displayName: string;
+    address?: PosTerminalAddress;
+}): Promise<{
+    ok: true;
+    locationId: string;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+}>;
+/** The tipping a reader shows: Stripe offers three buttons, so three presets. */
+export declare function posReaderTippingKey(settings: PosRegisterSettings): string;
+/**
+ * Keeps the site's reader tipping in step with the merchant's settings: one
+ * Terminal Configuration per site, assigned to its Location, rewritten only
+ * when the presets changed. Never fatal: a reader that keeps the previous
+ * presets still takes the payment.
+ */
+export declare function syncPosReaderTipping(hostId: string, settings: PosRegisterSettings): Promise<void>;
+/** Reads a reader from Stripe and keeps its status on the site's document. */
+export declare function refreshPosReaderStatus(hostId: string, readerId: string): Promise<{
+    status: string;
+    action: any;
+} | null>;
+interface CardStart {
+    hostId: string;
+    orderId: string;
+    paymentId: string;
+    amountCents: number;
+    /** A tip already chosen (on the customer display or by the cashier). */
+    tipCents: number;
+    cashierId: string;
+    org: Record<string, any> | null;
+}
+/**
+ * Creates (or finds) the card-present PaymentIntent for one payment WITHOUT
+ * choosing how the card is collected: reserves the amount in the ledger and
+ * creates a manual-capture destination charge to the merchant (settled on
+ * Aglyn's platform account, with no `on_behalf_of`, as ToS §10.7 states),
+ * keyed by the payment so a retry returns the same intent.
+ *
+ * Two collectors use it. {@link startCardPresentPayment} pushes the intent
+ * to a smart reader the site owns; a native companion app (AGL-3618)
+ * collects it with the Stripe Terminal SDK (Tap to Pay, Bluetooth readers)
+ * using the returned `clientSecret`. However the card is collected, the
+ * payment is recorded by {@link refreshPosCardPayment}, keyed on the intent's
+ * metadata, from the register's poll or the webhook alike.
+ */
+export declare function createCardPresentIntent(start: CardStart & {
+    readerId?: string;
+}): Promise<PosPaymentOutcome & {
+    clientSecret?: string;
+    paymentIntentId?: string;
+}>;
+/**
+ * A smart-reader payment: the card-present intent from
+ * {@link createCardPresentIntent}, pushed to a reader THIS site owns. The
+ * register then polls {@link refreshPosCardPayment} until the reader answers;
+ * webhooks land on the same function.
+ */
+export declare function startCardPresentPayment(start: CardStart & {
+    readerId: string;
+    settings: PosRegisterSettings;
+}): Promise<PosPaymentOutcome>;
+/** The site's Terminal Location id, or null before a reader was ever set up. */
+export declare function posTerminalLocationId(hostId: string): Promise<string | null>;
+/**
+ * A Terminal SDK connection token scoped to the site's own Location, for a
+ * native companion app's SDK (AGL-3618). Scoping it to the Location is what
+ * keeps one store's app from discovering another store's readers: Stripe
+ * only lets a location-scoped token connect to readers in that Location.
+ * Null when the site has no Location yet, never an unscoped token.
+ */
+export declare function createPosTerminalConnectionToken(hostId: string): Promise<{
+    secret: string;
+    locationId: string;
+} | null>;
+/**
+ * Re-arms a declined or failed reader payment on the SAME PaymentIntent, as
+ * Stripe asks (a new one per attempt risks a double charge).
+ */
+export declare function retryCardPresentPayment(input: {
+    hostId: string;
+    orderId: string;
+    paymentId: string;
+    settings: PosRegisterSettings;
+}): Promise<PosPaymentOutcome>;
+/**
+ * A typed card (card not present): a PaymentIntent the console confirms with
+ * the Payment Element. No MOTO: the card is keyed into Stripe's own field and
+ * goes through Stripe's normal online checks, 3-D Secure included.
+ */
+export declare function startCardKeyedPayment(start: CardStart): Promise<PosPaymentOutcome & {
+    clientSecret?: string;
+}>;
+/**
+ * The customer pays on their own phone from a QR code: a Stripe payment page
+ * for this payment's amount (and tip, as its own line). Settled by
+ * `checkout.session.completed` or by the register's poll.
+ */
+export declare function startCardLinkPayment(start: CardStart & {
+    returnUrl: string;
+}): Promise<PosPaymentOutcome>;
+/** The tip on an intent: what the display chose plus what the reader added. */
+export declare function posIntentTipCents(intent: any): number;
+/**
+ * The fee a register card charge is captured with: the payment's share of the
+ * take (fixed at reservation, the sale's share and never the tip's) plus the
+ * card processing cost on the whole amount, tip included.
+ */
+export declare function posCaptureFeeCents(payment: CommerceModel.OrderPayment, intent: any): number;
+/**
+ * Brings one card payment up to date with Stripe, from a webhook or the
+ * register's poll alike: captures an authorized reader payment with its final
+ * fee, records a success, a decline or a cancellation. Idempotent: the
+ * capture is keyed by the intent, and the ledger change is a no-op when the
+ * payment already says what Stripe says.
+ */
+export declare function refreshPosCardPayment(input: {
+    hostId: string;
+    orderId: string;
+    paymentId: string;
+}): Promise<PosPaymentOutcome>;
+/**
+ * Stops a card payment that has not been paid: clears the reader, cancels the
+ * intent, expires the payment page. A charge that already went through is
+ * left alone and recorded as paid, never cancelled under the customer.
+ */
+export declare function cancelPosCardPayment(input: {
+    hostId: string;
+    orderId: string;
+    paymentId: string;
+}): Promise<PosPaymentOutcome>;
+/**
+ * TEST MODE ONLY: Stripe's simulated reader is "tapped" with a test card.
+ * Refused outright on a live key, whatever the request says.
+ */
+export declare function simulatePosReaderTap(input: {
+    hostId: string;
+    orderId: string;
+    paymentId: string;
+    /** `4000000000000002` declines; anything else Stripe's default approves. */
+    cardNumber?: string;
+}): Promise<PosPaymentOutcome>;
+/**
+ * The register's Stripe events: a reader finished or failed an action, a
+ * register PaymentIntent was authorized, paid, declined or cancelled, or a
+ * register QR page was paid or expired. Each resolves to ONE payment and is
+ * answered by re-reading Stripe through {@link refreshPosCardPayment}, never
+ * by trusting the event's own copy (whose API version predates the tip
+ * fields). Returns the site when the event was the register's, so the
+ * dispatcher can count it as claimed; null for every other event.
+ */
+export declare function handlePosStripeEvent(input: {
+    type: string;
+    object: any;
+}): Promise<{
+    hostId: string;
+} | null>;
+export type { PosLiftedOrder };