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

package/src/lib/server/shipping-connector-gates.js

@@ -0,0 +1,97 @@
+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 "crypto";
+import * as Aglyn from "@aglyn/aglyn/server";
+import { PLATFORM_BRAND_NAME } from "@aglyn/aglyn/app-utils/platform-brand";
+import { getHostDisabledPlugins, getHostDocAdmin, getOrgForHost, getServerReleaseFlagValues, lockdownRefusal } from "@aglyn/tenant-data-admin";
+/*
+ * THE GATES EVERY SHIPPING CONNECTOR ASKS ITSELF (AGL-3613, AGL-3633).
+ *
+ * A shipping app's servers call a connector's route with credentials of the
+ * site's own and name no member, so each connector route is a MACHINE route:
+ * the dispatcher skips its per-site enablement, release and write-limit gates
+ * and the route answers them here, for the site its URL names, once the
+ * credentials are proven. ShipStation's Custom Store and ShippingEasy's
+ * shipment callback both stand on these; a connector that pushes orders out
+ * asks `connectorSiteRefusal` before each push the same way.
+ */ /** SHA-256 hex of a secret or a body. */ export function digestSecret(secret) {
+    return createHash('sha256').update(secret, 'utf8').digest('hex');
+}
+/** A plain-text answer: the shipping apps show the body of a refusal to the merchant. */ export function connectorText(status, body, headers = {}) {
+    return new Response(body, {
+        status,
+        headers: _extends({
+            'content-type': 'text/plain; charset=utf-8'
+        }, headers)
+    });
+}
+/**
+ * Whether the request arrived over HTTPS. Behind Vercel the transport is
+ * stated by `x-forwarded-proto`; a local or test run (`NODE_ENV` not
+ * production) is not held to it.
+ */ export function requestIsSecure(request, env = process.env) {
+    var _request_headers_get;
+    if (env['NODE_ENV'] !== 'production') return true;
+    const forwarded = String((_request_headers_get = request.headers.get('x-forwarded-proto')) != null ? _request_headers_get : '').split(',')[0].trim().toLowerCase();
+    if (forwarded) return forwarded === 'https';
+    try {
+        return new URL(request.url).protocol === 'https:';
+    } catch (unused) {
+        return false;
+    }
+}
+/** A site id as a document id may hold it. */ export const CONNECTOR_HOST_ID = /^[A-Za-z0-9_-]{1,128}$/;
+/** The `:hostId` a connector route was called with, or `null` when it is not one. */ export function connectorHostIdOf(params) {
+    const raw = params['hostId'];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === 'string' && CONNECTOR_HOST_ID.test(value) ? value : null;
+}
+/**
+ * The gates a dispatcher would have asked, for a site whose connector proved
+ * itself: commerce switched on for it, on the plan, released for the org, and
+ * the site not locked down. `null` when every one passes. `request` is the
+ * call being answered, or `{ method: 'POST' }` for a push the platform makes
+ * on its own, which a read-only lockdown refuses like any write.
+ */ export async function connectorSiteRefusal(request, hostId) {
+    const [owner, disabledPlugins, host] = await Promise.all([
+        getOrgForHost(hostId),
+        getHostDisabledPlugins(hostId),
+        getHostDocAdmin(hostId)
+    ]);
+    if (!(owner == null ? void 0 : owner.org) || !host) return connectorText(404, `This site no longer exists in ${PLATFORM_BRAND_NAME}.`);
+    const org = owner.org;
+    if (!Aglyn.resolveHostEnabledPlugins(owner.org, {
+        disabledPlugins
+    }).includes('commerce')) {
+        return connectorText(403, `Commerce is switched off for this site in ${PLATFORM_BRAND_NAME}.`);
+    }
+    if (!Aglyn.checkEntitlement(owner.org, 'commerce')) {
+        return connectorText(403, `This site’s ${PLATFORM_BRAND_NAME} plan does not include selling.`);
+    }
+    const flags = await getServerReleaseFlagValues();
+    const released = Aglyn.isReleaseFlagOnForOrg('release_commerce_v2', flags['release_commerce_v2'], owner.orgId, Aglyn.parseOrgReleaseFlagOverrides(org['releaseFlags']), Aglyn.resolveEffectivePlan(owner.org));
+    if (!released) return connectorText(403, 'Commerce is not available for this site yet.');
+    return lockdownRefusal({
+        request,
+        staff: false,
+        uid: null,
+        org,
+        host: host
+    });
+}
+
+//# sourceMappingURL=shipping-connector-gates.js.map

package/src/lib/server/shipping-connector-gates.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/shipping-connector-gates.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 } from 'crypto'\nimport * as Aglyn from '@aglyn/aglyn/server'\nimport { PLATFORM_BRAND_NAME } from '@aglyn/aglyn/app-utils/platform-brand'\nimport {\n  getHostDisabledPlugins,\n  getHostDocAdmin,\n  getOrgForHost,\n  getServerReleaseFlagValues,\n  lockdownRefusal,\n} from '@aglyn/tenant-data-admin'\n\n/*\n * THE GATES EVERY SHIPPING CONNECTOR ASKS ITSELF (AGL-3613, AGL-3633).\n *\n * A shipping app's servers call a connector's route with credentials of the\n * site's own and name no member, so each connector route is a MACHINE route:\n * the dispatcher skips its per-site enablement, release and write-limit gates\n * and the route answers them here, for the site its URL names, once the\n * credentials are proven. ShipStation's Custom Store and ShippingEasy's\n * shipment callback both stand on these; a connector that pushes orders out\n * asks `connectorSiteRefusal` before each push the same way.\n */\n\n/** SHA-256 hex of a secret or a body. */\nexport function digestSecret(secret: string): string {\n  return createHash('sha256').update(secret, 'utf8').digest('hex')\n}\n\n/** A plain-text answer: the shipping apps show the body of a refusal to the merchant. */\nexport function connectorText(status: number, body: string, headers: Record<string, string> = {}): Response {\n  return new Response(body, { status, headers: { 'content-type': 'text/plain; charset=utf-8', ...headers } })\n}\n\n/**\n * Whether the request arrived over HTTPS. Behind Vercel the transport is\n * stated by `x-forwarded-proto`; a local or test run (`NODE_ENV` not\n * production) is not held to it.\n */\nexport function requestIsSecure(request: Request, env: Record<string, string | undefined> = process.env): boolean {\n  if (env['NODE_ENV'] !== 'production') return true\n  const forwarded = String(request.headers.get('x-forwarded-proto') ?? '')\n    .split(',')[0]\n    .trim()\n    .toLowerCase()\n  if (forwarded) return forwarded === 'https'\n  try {\n    return new URL(request.url).protocol === 'https:'\n  } catch {\n    return false\n  }\n}\n\n/** A site id as a document id may hold it. */\nexport const CONNECTOR_HOST_ID = /^[A-Za-z0-9_-]{1,128}$/\n\n/** The `:hostId` a connector route was called with, or `null` when it is not one. */\nexport function connectorHostIdOf(params: Record<string, string | string[]>): string | null {\n  const raw = params['hostId']\n  const value = Array.isArray(raw) ? raw[0] : raw\n  return typeof value === 'string' && CONNECTOR_HOST_ID.test(value) ? value : null\n}\n\n/**\n * The gates a dispatcher would have asked, for a site whose connector proved\n * itself: commerce switched on for it, on the plan, released for the org, and\n * the site not locked down. `null` when every one passes. `request` is the\n * call being answered, or `{ method: 'POST' }` for a push the platform makes\n * on its own, which a read-only lockdown refuses like any write.\n */\nexport async function connectorSiteRefusal(request: { method?: string }, hostId: string): Promise<Response | null> {\n  const [owner, disabledPlugins, host] = await Promise.all([\n    getOrgForHost(hostId),\n    getHostDisabledPlugins(hostId),\n    getHostDocAdmin(hostId),\n  ])\n  if (!owner?.org || !host) return connectorText(404, `This site no longer exists in ${PLATFORM_BRAND_NAME}.`)\n  const org = owner.org as Record<string, unknown>\n  if (!Aglyn.resolveHostEnabledPlugins(owner.org as never, { disabledPlugins }).includes('commerce')) {\n    return connectorText(403, `Commerce is switched off for this site in ${PLATFORM_BRAND_NAME}.`)\n  }\n  if (!Aglyn.checkEntitlement(owner.org as never, 'commerce')) {\n    return connectorText(403, `This site’s ${PLATFORM_BRAND_NAME} plan does not include selling.`)\n  }\n  const flags = await getServerReleaseFlagValues()\n  const released = Aglyn.isReleaseFlagOnForOrg(\n    'release_commerce_v2',\n    flags['release_commerce_v2'],\n    owner.orgId,\n    Aglyn.parseOrgReleaseFlagOverrides(org['releaseFlags']),\n    Aglyn.resolveEffectivePlan(owner.org as never),\n  )\n  if (!released) return connectorText(403, 'Commerce is not available for this site yet.')\n  return lockdownRefusal({\n    request,\n    staff: false,\n    uid: null,\n    org,\n    host: host as Record<string, unknown>,\n  })\n}\n"],"names":["createHash","Aglyn","PLATFORM_BRAND_NAME","getHostDisabledPlugins","getHostDocAdmin","getOrgForHost","getServerReleaseFlagValues","lockdownRefusal","digestSecret","secret","update","digest","connectorText","status","body","headers","Response","requestIsSecure","request","env","process","forwarded","String","get","split","trim","toLowerCase","URL","url","protocol","CONNECTOR_HOST_ID","connectorHostIdOf","params","raw","value","Array","isArray","test","connectorSiteRefusal","hostId","owner","disabledPlugins","host","Promise","all","org","resolveHostEnabledPlugins","includes","checkEntitlement","flags","released","isReleaseFlagOnForOrg","orgId","parseOrgReleaseFlagOverrides","resolveEffectivePlan","staff","uid"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,UAAU,QAAQ,SAAQ;AACnC,YAAYC,WAAW,sBAAqB;AAC5C,SAASC,mBAAmB,QAAQ,wCAAuC;AAC3E,SACEC,sBAAsB,EACtBC,eAAe,EACfC,aAAa,EACbC,0BAA0B,EAC1BC,eAAe,QACV,2BAA0B;AAEjC;;;;;;;;;;CAUC,GAED,uCAAuC,GACvC,OAAO,SAASC,aAAaC,MAAc;IACzC,OAAOT,WAAW,UAAUU,MAAM,CAACD,QAAQ,QAAQE,MAAM,CAAC;AAC5D;AAEA,uFAAuF,GACvF,OAAO,SAASC,cAAcC,MAAc,EAAEC,IAAY,EAAEC,UAAkC,CAAC,CAAC;IAC9F,OAAO,IAAIC,SAASF,MAAM;QAAED;QAAQE,SAAS;YAAE,gBAAgB;WAAgCA;IAAU;AAC3G;AAEA;;;;CAIC,GACD,OAAO,SAASE,gBAAgBC,OAAgB,EAAEC,MAA0CC,QAAQD,GAAG;QAE5ED;IADzB,IAAIC,GAAG,CAAC,WAAW,KAAK,cAAc,OAAO;IAC7C,MAAME,YAAYC,QAAOJ,uBAAAA,QAAQH,OAAO,CAACQ,GAAG,CAAC,gCAApBL,uBAA4C,IAClEM,KAAK,CAAC,IAAI,CAAC,EAAE,CACbC,IAAI,GACJC,WAAW;IACd,IAAIL,WAAW,OAAOA,cAAc;IACpC,IAAI;QACF,OAAO,IAAIM,IAAIT,QAAQU,GAAG,EAAEC,QAAQ,KAAK;IAC3C,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA,4CAA4C,GAC5C,OAAO,MAAMC,oBAAoB,yBAAwB;AAEzD,mFAAmF,GACnF,OAAO,SAASC,kBAAkBC,MAAyC;IACzE,MAAMC,MAAMD,MAAM,CAAC,SAAS;IAC5B,MAAME,QAAQC,MAAMC,OAAO,CAACH,OAAOA,GAAG,CAAC,EAAE,GAAGA;IAC5C,OAAO,OAAOC,UAAU,YAAYJ,kBAAkBO,IAAI,CAACH,SAASA,QAAQ;AAC9E;AAEA;;;;;;CAMC,GACD,OAAO,eAAeI,qBAAqBpB,OAA4B,EAAEqB,MAAc;IACrF,MAAM,CAACC,OAAOC,iBAAiBC,KAAK,GAAG,MAAMC,QAAQC,GAAG,CAAC;QACvDvC,cAAckC;QACdpC,uBAAuBoC;QACvBnC,gBAAgBmC;KACjB;IACD,IAAI,EAACC,yBAAAA,MAAOK,GAAG,KAAI,CAACH,MAAM,OAAO9B,cAAc,KAAK,CAAC,8BAA8B,EAAEV,oBAAoB,CAAC,CAAC;IAC3G,MAAM2C,MAAML,MAAMK,GAAG;IACrB,IAAI,CAAC5C,MAAM6C,yBAAyB,CAACN,MAAMK,GAAG,EAAW;QAAEJ;IAAgB,GAAGM,QAAQ,CAAC,aAAa;QAClG,OAAOnC,cAAc,KAAK,CAAC,0CAA0C,EAAEV,oBAAoB,CAAC,CAAC;IAC/F;IACA,IAAI,CAACD,MAAM+C,gBAAgB,CAACR,MAAMK,GAAG,EAAW,aAAa;QAC3D,OAAOjC,cAAc,KAAK,CAAC,YAAY,EAAEV,oBAAoB,+BAA+B,CAAC;IAC/F;IACA,MAAM+C,QAAQ,MAAM3C;IACpB,MAAM4C,WAAWjD,MAAMkD,qBAAqB,CAC1C,uBACAF,KAAK,CAAC,sBAAsB,EAC5BT,MAAMY,KAAK,EACXnD,MAAMoD,4BAA4B,CAACR,GAAG,CAAC,eAAe,GACtD5C,MAAMqD,oBAAoB,CAACd,MAAMK,GAAG;IAEtC,IAAI,CAACK,UAAU,OAAOtC,cAAc,KAAK;IACzC,OAAOL,gBAAgB;QACrBW;QACAqC,OAAO;QACPC,KAAK;QACLX;QACAH,MAAMA;IACR;AACF"}

package/src/lib/server/shipping-connectors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 Aglyn from '@aglyn/aglyn/server';
+/** What the card shows about a connection. */
+export interface ShipStationConnectionStatus {
+    /** Whether this deployment can seal a password at all. */
+    available: boolean;
+    connected: boolean;
+    username?: string;
+    createdAtMs?: number;
+    rotatedAtMs?: number;
+    lastExportAtMs?: number;
+    lastShipNoticeAtMs?: number;
+}
+export declare const shippingConnectorsHandler: Aglyn.PluginApiHandler;

package/src/lib/server/shipping-connectors.js

@@ -0,0 +1,236 @@
+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 * as Aglyn from "@aglyn/aglyn/server";
+import { firebaseAdmin, getOrgForHost, logHostActivity } from "@aglyn/tenant-data-admin";
+import { readCommerceSecretKeyring } from "./order-webhooks.js";
+import { prepareOpenOrders } from "./orders-shipping-prepare.js";
+import { SHIPPINGEASY_ACTIONS, shippingEasyConnectorAction } from "./shippingeasy.js";
+import { SHIPSTATION_CONNECTIONS, mintShipStationCredentials, openShipStationPassword, sealShipStationPassword } from "./shipstation.js";
+function statusOf(connection, available) {
+    if (!connection) return {
+        available,
+        connected: false
+    };
+    return _extends({
+        available,
+        connected: true,
+        username: connection.username,
+        createdAtMs: connection.createdAtMs
+    }, connection.rotatedAtMs ? {
+        rotatedAtMs: connection.rotatedAtMs
+    } : {}, connection.lastExportAtMs ? {
+        lastExportAtMs: connection.lastExportAtMs
+    } : {}, connection.lastShipNoticeAtMs ? {
+        lastShipNoticeAtMs: connection.lastShipNoticeAtMs
+    } : {});
+}
+const ACTIVITY = {
+    type: 'commerce:shipStation',
+    id: 'shipstation',
+    name: 'ShipStation'
+};
+const ACTIONS = [
+    'status',
+    'connect',
+    'rotate',
+    'reveal',
+    'disconnect'
+];
+/** The shipping apps the card route manages. `shipstation` when a request names none. */ const CONNECTORS = [
+    'shipstation',
+    'shippingeasy'
+];
+const CONNECTOR_NAMES = {
+    shipstation: 'ShipStation',
+    shippingeasy: 'ShippingEasy'
+};
+export const shippingConnectorsHandler = async (req, res)=>{
+    var _req_headers_authorization, _ref, _ref1, _body_action;
+    if (req.method !== 'GET' && req.method !== 'POST') {
+        return res.status(405).json({
+            error: 'Method not allowed'
+        });
+    }
+    const authorization = String((_req_headers_authorization = req.headers.authorization) != null ? _req_headers_authorization : '');
+    const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
+    if (!idToken) return res.status(401).json({
+        error: 'Unauthenticated'
+    });
+    let body = {};
+    if (req.method === 'POST') {
+        try {
+            var _req_body;
+            body = typeof req.body === 'string' ? JSON.parse(req.body) : (_req_body = req.body) != null ? _req_body : {};
+        } catch (unused) {
+            return res.status(400).json({
+                error: 'The request could not be read'
+            });
+        }
+    }
+    const hostId = String((_ref = req.method === 'GET' ? req.query['hostId'] : body['hostId']) != null ? _ref : '');
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(hostId)) return res.status(400).json({
+        error: 'Missing hostId'
+    });
+    const connector = String((_ref1 = req.method === 'GET' ? req.query['connector'] : body['connector']) != null ? _ref1 : 'shipstation');
+    if (!CONNECTORS.includes(connector)) return res.status(400).json({
+        error: 'Unknown connector'
+    });
+    const action = req.method === 'GET' ? 'status' : String((_body_action = body['action']) != null ? _body_action : '');
+    const known = connector === 'shippingeasy' ? SHIPPINGEASY_ACTIONS : ACTIONS;
+    if (!known.includes(action) || req.method === 'POST' && action === 'status') {
+        return res.status(400).json({
+            error: 'Unknown action'
+        });
+    }
+    try {
+        var _hostSnapshot_get, _decoded_email;
+        const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+        const firestore = firebaseAdmin.app().firestore();
+        const hostSnapshot = await firestore.collection('hosts').doc(hostId).get();
+        if (!hostSnapshot.exists) return res.status(404).json({
+            error: 'Unknown site'
+        });
+        const role = ((_hostSnapshot_get = hostSnapshot.get('memberRoles')) != null ? _hostSnapshot_get : {})[decoded.uid];
+        // Reading the status is the order book's role; anything that makes,
+        // shows or ends a credential that reads it is the admin's.
+        const adminOnly = action !== 'status';
+        if (adminOnly ? role !== 'admin' : role !== 'admin' && role !== 'editor') {
+            return res.status(403).json({
+                error: adminOnly ? `Only a site admin can manage the ${CONNECTOR_NAMES[connector]} connection` : 'Not permitted'
+            });
+        }
+        const owner = await getOrgForHost(hostId);
+        if (!Aglyn.checkEntitlement(owner == null ? void 0 : owner.org, 'commerce')) {
+            return res.status(403).json({
+                error: 'Selling is not enabled'
+            });
+        }
+        const actor = {
+            uid: decoded.uid,
+            email: (_decoded_email = decoded.email) != null ? _decoded_email : null
+        };
+        if (connector === 'shippingeasy') {
+            const answer = await shippingEasyConnectorAction({
+                hostId,
+                action: action,
+                body,
+                actor,
+                log: (what, target)=>logHostActivity(hostId, actor, what, target),
+                prepareOpenOrders
+            });
+            return res.status(answer.status).json(answer.body);
+        }
+        const keyring = readCommerceSecretKeyring();
+        const available = keyring !== null;
+        const ref = firestore.collection(SHIPSTATION_CONNECTIONS).doc(hostId);
+        if (action === 'status') {
+            const doc = await ref.get();
+            return res.status(200).json(statusOf(doc.exists ? doc.data() : null, available));
+        }
+        if (action === 'disconnect') {
+            const doc = await ref.get();
+            if (!doc.exists) return res.status(200).json({
+                available,
+                connected: false
+            });
+            await ref.delete();
+            await logHostActivity(hostId, actor, 'Disconnected ShipStation', ACTIVITY);
+            return res.status(200).json({
+                available,
+                connected: false
+            });
+        }
+        if (!keyring) {
+            return res.status(503).json({
+                error: 'ShipStation cannot be connected on this deployment yet'
+            });
+        }
+        if (action === 'reveal') {
+            const doc = await ref.get();
+            if (!doc.exists) return res.status(409).json({
+                error: 'ShipStation is not connected.'
+            });
+            const connection = doc.data();
+            const opened = openShipStationPassword(connection, keyring);
+            if (!opened) {
+                return res.status(409).json({
+                    error: 'The password cannot be shown. Make a new password instead.'
+                });
+            }
+            await logHostActivity(hostId, actor, 'Showed the ShipStation password', ACTIVITY);
+            return res.status(200).json(_extends({}, statusOf(connection, available), {
+                password: opened.password
+            }));
+        }
+        const { username, password } = mintShipStationCredentials();
+        const sealed = sealShipStationPassword(hostId, password, keyring);
+        const nowMs = Date.now();
+        const outcome = await firestore.runTransaction(async (transaction)=>{
+            const doc = await transaction.get(ref);
+            if (action === 'connect') {
+                if (doc.exists) return {
+                    conflict: 'ShipStation is already connected. Make a new password instead.'
+                };
+                const connection = _extends({
+                    hostId,
+                    username
+                }, sealed, {
+                    createdAtMs: nowMs,
+                    createdBy: decoded.uid
+                });
+                transaction.create(ref, connection);
+                return {
+                    connection
+                };
+            }
+            if (!doc.exists) return {
+                conflict: 'ShipStation is not connected.'
+            };
+            const current = doc.data();
+            // A new password ends the old one at once: the merchant gives
+            // ShipStation the new one, and anything holding the old one is refused.
+            const connection = _extends({}, current, sealed, {
+                rotatedAtMs: nowMs
+            });
+            delete connection.exportCursor;
+            // Documents sealed before the secret box carried a digest; drop it.
+            delete connection['passwordHash'];
+            transaction.set(ref, connection);
+            return {
+                connection
+            };
+        });
+        if ('conflict' in outcome) return res.status(409).json({
+            error: outcome.conflict
+        });
+        if (action === 'connect') {
+            await prepareOpenOrders(hostId).catch((error)=>console.warn('shipping-connectors: open orders not stamped', hostId, error));
+        }
+        await logHostActivity(hostId, actor, action === 'connect' ? 'Connected ShipStation' : 'Made a new ShipStation password', ACTIVITY);
+        const connection = outcome.connection;
+        return res.status(200).json(_extends({}, statusOf(connection, available), {
+            password
+        }));
+    } catch (error) {
+        console.error('shipping-connectors failed', action, error);
+        return res.status(500).json({
+            error: 'That did not work. Try again.'
+        });
+    }
+};
+
+//# sourceMappingURL=shipping-connectors.js.map

package/src/lib/server/shipping-connectors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/shipping-connectors.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 * as Aglyn from '@aglyn/aglyn/server'\nimport { firebaseAdmin, getOrgForHost, logHostActivity } from '@aglyn/tenant-data-admin'\nimport { readCommerceSecretKeyring } from './order-webhooks'\nimport { prepareOpenOrders } from './orders-shipping-prepare'\nimport { SHIPPINGEASY_ACTIONS, shippingEasyConnectorAction, type ShippingEasyAction } from './shippingeasy'\nimport {\n  SHIPSTATION_CONNECTIONS,\n  mintShipStationCredentials,\n  openShipStationPassword,\n  sealShipStationPassword,\n  type ShipStationConnection,\n} from './shipstation'\n\n/*\n * THE CONSOLE'S SIDE OF THE SHIPPING CONNECTORS (AGL-3613, AGL-3633):\n * `commerce/shipping-connectors`. One door for every connector card: it\n * proves the caller and the site once, then answers for the connector the\n * request names (`connector`, `shipstation` when absent). ShippingEasy's\n * actions are `shippingEasyConnectorAction` in `./shippingeasy`; what follows\n * is ShipStation's.\n *\n * - GET `?hostId=` — whether ShipStation can be connected on this deployment\n *   (`available`: commerce's secret keyring exists), whether it is, its\n *   username and when it last called. Never the password.\n * - POST `{ hostId, action: 'connect' | 'rotate' | 'reveal' | 'disconnect' }`\n *   — a site's ADMINS only, because the credentials read every shippable\n *   order's name and address. `connect`, `rotate` and `reveal` answer the\n *   password; `rotate` ends the old one at once. `connect` also stamps the\n *   open orders written before the feed's fields existed\n *   (`prepareOpenOrders`), so ShipStation's first import finds them.\n */\n\n/** What the card shows about a connection. */\nexport interface ShipStationConnectionStatus {\n  /** Whether this deployment can seal a password at all. */\n  available: boolean\n  connected: boolean\n  username?: string\n  createdAtMs?: number\n  rotatedAtMs?: number\n  lastExportAtMs?: number\n  lastShipNoticeAtMs?: number\n}\n\nfunction statusOf(connection: ShipStationConnection | null, available: boolean): ShipStationConnectionStatus {\n  if (!connection) return { available, connected: false }\n  return {\n    available,\n    connected: true,\n    username: connection.username,\n    createdAtMs: connection.createdAtMs,\n    ...(connection.rotatedAtMs ? { rotatedAtMs: connection.rotatedAtMs } : {}),\n    ...(connection.lastExportAtMs ? { lastExportAtMs: connection.lastExportAtMs } : {}),\n    ...(connection.lastShipNoticeAtMs ? { lastShipNoticeAtMs: connection.lastShipNoticeAtMs } : {}),\n  }\n}\n\nconst ACTIVITY = { type: 'commerce:shipStation', id: 'shipstation', name: 'ShipStation' } as const\n\nconst ACTIONS = ['status', 'connect', 'rotate', 'reveal', 'disconnect'] as const\ntype Action = (typeof ACTIONS)[number] | ShippingEasyAction\n\n/** The shipping apps the card route manages. `shipstation` when a request names none. */\nconst CONNECTORS = ['shipstation', 'shippingeasy'] as const\ntype Connector = (typeof CONNECTORS)[number]\nconst CONNECTOR_NAMES: Readonly<Record<Connector, string>> = { shipstation: 'ShipStation', shippingeasy: 'ShippingEasy' }\n\nexport const shippingConnectorsHandler: Aglyn.PluginApiHandler = async (req, res) => {\n  if (req.method !== 'GET' && req.method !== 'POST') {\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n  const authorization = String(req.headers.authorization ?? '')\n  const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined\n  if (!idToken) return res.status(401).json({ error: 'Unauthenticated' })\n  let body: Record<string, unknown> = {}\n  if (req.method === 'POST') {\n    try {\n      body = typeof req.body === 'string' ? JSON.parse(req.body) : (req.body ?? {})\n    } catch {\n      return res.status(400).json({ error: 'The request could not be read' })\n    }\n  }\n  const hostId = String((req.method === 'GET' ? req.query['hostId'] : body['hostId']) ?? '')\n  if (!/^[A-Za-z0-9_-]{1,128}$/.test(hostId)) return res.status(400).json({ error: 'Missing hostId' })\n  const connector = String((req.method === 'GET' ? req.query['connector'] : body['connector']) ?? 'shipstation') as Connector\n  if (!CONNECTORS.includes(connector)) return res.status(400).json({ error: 'Unknown connector' })\n  const action = (req.method === 'GET' ? 'status' : String(body['action'] ?? '')) as Action\n  const known: readonly string[] = connector === 'shippingeasy' ? SHIPPINGEASY_ACTIONS : ACTIONS\n  if (!known.includes(action) || (req.method === 'POST' && action === 'status')) {\n    return res.status(400).json({ error: 'Unknown action' })\n  }\n\n  try {\n    const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken)\n    const firestore = firebaseAdmin.app().firestore()\n    const hostSnapshot = await firestore.collection('hosts').doc(hostId).get()\n    if (!hostSnapshot.exists) return res.status(404).json({ error: 'Unknown site' })\n    const role = (hostSnapshot.get('memberRoles') ?? {})[decoded.uid]\n    // Reading the status is the order book's role; anything that makes,\n    // shows or ends a credential that reads it is the admin's.\n    const adminOnly = action !== 'status'\n    if (adminOnly ? role !== 'admin' : role !== 'admin' && role !== 'editor') {\n      return res.status(403).json({\n        error: adminOnly ? `Only a site admin can manage the ${CONNECTOR_NAMES[connector]} connection` : 'Not permitted',\n      })\n    }\n    const owner = await getOrgForHost(hostId)\n    if (!Aglyn.checkEntitlement(owner?.org as never, 'commerce')) {\n      return res.status(403).json({ error: 'Selling is not enabled' })\n    }\n\n    const actor = { uid: decoded.uid, email: decoded.email ?? null }\n    if (connector === 'shippingeasy') {\n      const answer = await shippingEasyConnectorAction({\n        hostId,\n        action: action as ShippingEasyAction,\n        body,\n        actor,\n        log: (what, target) => logHostActivity(hostId, actor, what, target),\n        prepareOpenOrders,\n      })\n      return res.status(answer.status).json(answer.body)\n    }\n\n    const keyring = readCommerceSecretKeyring()\n    const available = keyring !== null\n    const ref = firestore.collection(SHIPSTATION_CONNECTIONS).doc(hostId)\n\n    if (action === 'status') {\n      const doc = await ref.get()\n      return res.status(200).json(statusOf(doc.exists ? (doc.data() as ShipStationConnection) : null, available))\n    }\n    if (action === 'disconnect') {\n      const doc = await ref.get()\n      if (!doc.exists) return res.status(200).json({ available, connected: false })\n      await ref.delete()\n      await logHostActivity(hostId, actor, 'Disconnected ShipStation', ACTIVITY)\n      return res.status(200).json({ available, connected: false })\n    }\n    if (!keyring) {\n      return res.status(503).json({ error: 'ShipStation cannot be connected on this deployment yet' })\n    }\n    if (action === 'reveal') {\n      const doc = await ref.get()\n      if (!doc.exists) return res.status(409).json({ error: 'ShipStation is not connected.' })\n      const connection = doc.data() as ShipStationConnection\n      const opened = openShipStationPassword(connection, keyring)\n      if (!opened) {\n        return res.status(409).json({ error: 'The password cannot be shown. Make a new password instead.' })\n      }\n      await logHostActivity(hostId, actor, 'Showed the ShipStation password', ACTIVITY)\n      return res.status(200).json({ ...statusOf(connection, available), password: opened.password })\n    }\n\n    const { username, password } = mintShipStationCredentials()\n    const sealed = sealShipStationPassword(hostId, password, keyring)\n    const nowMs = Date.now()\n    const outcome = await firestore.runTransaction(async (transaction) => {\n      const doc = await transaction.get(ref)\n      if (action === 'connect') {\n        if (doc.exists) return { conflict: 'ShipStation is already connected. Make a new password instead.' }\n        const connection: ShipStationConnection = {\n          hostId,\n          username,\n          ...sealed,\n          createdAtMs: nowMs,\n          createdBy: decoded.uid,\n        }\n        transaction.create(ref, connection)\n        return { connection }\n      }\n      if (!doc.exists) return { conflict: 'ShipStation is not connected.' }\n      const current = doc.data() as ShipStationConnection\n      // A new password ends the old one at once: the merchant gives\n      // ShipStation the new one, and anything holding the old one is refused.\n      const connection: ShipStationConnection = { ...current, ...sealed, rotatedAtMs: nowMs }\n      delete connection.exportCursor\n      // Documents sealed before the secret box carried a digest; drop it.\n      delete (connection as unknown as Record<string, unknown>)['passwordHash']\n      transaction.set(ref, connection)\n      return { connection }\n    })\n    if ('conflict' in outcome) return res.status(409).json({ error: outcome.conflict })\n    if (action === 'connect') {\n      await prepareOpenOrders(hostId).catch((error: unknown) =>\n        console.warn('shipping-connectors: open orders not stamped', hostId, error),\n      )\n    }\n    await logHostActivity(\n      hostId,\n      actor,\n      action === 'connect' ? 'Connected ShipStation' : 'Made a new ShipStation password',\n      ACTIVITY,\n    )\n    const connection = outcome.connection as ShipStationConnection\n    return res.status(200).json({ ...statusOf(connection, available), password })\n  } catch (error) {\n    console.error('shipping-connectors failed', action, error)\n    return res.status(500).json({ error: 'That did not work. Try again.' })\n  }\n}\n"],"names":["Aglyn","firebaseAdmin","getOrgForHost","logHostActivity","readCommerceSecretKeyring","prepareOpenOrders","SHIPPINGEASY_ACTIONS","shippingEasyConnectorAction","SHIPSTATION_CONNECTIONS","mintShipStationCredentials","openShipStationPassword","sealShipStationPassword","statusOf","connection","available","connected","username","createdAtMs","rotatedAtMs","lastExportAtMs","lastShipNoticeAtMs","ACTIVITY","type","id","name","ACTIONS","CONNECTORS","CONNECTOR_NAMES","shipstation","shippingeasy","shippingConnectorsHandler","req","res","body","method","status","json","error","authorization","String","headers","idToken","startsWith","slice","length","undefined","JSON","parse","hostId","query","test","connector","includes","action","known","hostSnapshot","decoded","app","auth","verifyIdToken","firestore","collection","doc","get","exists","role","uid","adminOnly","owner","checkEntitlement","org","actor","email","answer","log","what","target","keyring","ref","data","delete","opened","password","sealed","nowMs","Date","now","outcome","runTransaction","transaction","conflict","createdBy","create","current","exportCursor","set","catch","console","warn"],"mappings":"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"}

package/src/lib/server/shippingeasy.d.ts

@@ -0,0 +1,238 @@
+/**
+ * @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 { PluginDomainEventEnvelope } from '@aglyn/aglyn/plugin-manager/plugin-domain-events';
+import { type SecretBoxKeyring } from '@aglyn/shared-util-tools/secret-box';
+/** Where each site's connection is kept: server-only, every client denied. */
+export declare const SHIPPINGEASY_CONNECTIONS = "commerceShippingEasyConnections";
+/** The per-order records under a connection. */
+export declare const SHIPPINGEASY_ORDER_RECORDS = "orders";
+/** Callback requests per minute, per site and per calling address. */
+export declare const SHIPPINGEASY_RATE_LIMIT = 120;
+/** The largest callback body read. A shipment of a few orders is tens of kilobytes. */
+export declare const SHIPPINGEASY_CALLBACK_MAX_BYTES: number;
+/** How long a claimed push holds its order before another may try. */
+export declare const SHIPPINGEASY_CLAIM_MS: number;
+/** How long one call to ShippingEasy may take. */
+export declare const SHIPPINGEASY_REQUEST_TIMEOUT_MS = 15000;
+/** Orders "Send open orders" pushes per click. */
+export declare const SHIPPINGEASY_SYNC_LIMIT = 100;
+/** How far back "Send open orders" looks: older open orders are the merchant's to handle by hand. */
+export declare const SHIPPINGEASY_SYNC_WINDOW_MS: number;
+/** The env var that points the connector at another ShippingEasy address. */
+export declare const SHIPPINGEASY_BASE_URL_ENV = "SHIPPINGEASY_API_BASE_URL";
+/** A connection as stored. */
+export interface ShippingEasyConnection {
+    hostId: string;
+    /** The account's API key: sent in every query string, so not a secret on its own. */
+    apiKey: string;
+    /** The account's API secret, sealed with the secret box; never stored in the clear. */
+    sealedApiSecret: string;
+    /** The id of the key that sealed it, for rotation. */
+    secretKeyId: string;
+    /** The API store's key, from ShippingEasy's Stores & Orders page. */
+    storeApiKey: string;
+    createdAtMs: number;
+    createdBy: string;
+    updatedAtMs?: number;
+    lastPushAtMs?: number;
+    lastCallbackAtMs?: number;
+    /** The last thing that went wrong, for the card. Cleared by the next success. */
+    lastError?: {
+        message: string;
+        atMs: number;
+        orderNumber?: string;
+    } | null;
+}
+/** Where one order stands with ShippingEasy. */
+export type ShippingEasyOrderState = 'sending' | 'sent' | 'failed' | 'canceling' | 'canceled' | 'cancel_failed';
+/** One order's record under a connection. */
+export interface ShippingEasyOrderRecord {
+    orderId: string;
+    externalId: string;
+    state: ShippingEasyOrderState;
+    claimedAtMs?: number;
+    sentAtMs?: number;
+    canceledAtMs?: number;
+    error?: string | null;
+    updatedAtMs: number;
+}
+/** The merchant's keys in the clear, for one call. */
+export interface ShippingEasyCredentials {
+    apiKey: string;
+    apiSecret: string;
+    storeApiKey: string;
+}
+/** What the connector's server calls are given, so specs can stand in for the network and the clock. */
+export interface ShippingEasyDeps {
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    env?: Record<string, string | undefined>;
+}
+/** A failure that may pass: the outbox retries it. */
+export declare class ShippingEasyUnavailableError extends Error {
+    constructor(message: string);
+}
+/** What a key from ShippingEasy's pages looks like: their keys are hex, allowed some slack. */
+export declare const SHIPPINGEASY_KEY: RegExp;
+/** What binds a sealed secret to its site: a copy opens for no other. */
+export declare const shippingEasySealContext: (hostId: string) => string;
+/** The API secret sealed for a site, with the id of the key that sealed it. */
+export declare function sealShippingEasySecret(hostId: string, apiSecret: string, keyring: SecretBoxKeyring): Pick<ShippingEasyConnection, 'sealedApiSecret' | 'secretKeyId'>;
+/** A site's API secret in the clear and whether to seal it again, or `null` when it cannot be opened. */
+export declare function openShippingEasySecret(connection: Pick<ShippingEasyConnection, 'hostId' | 'sealedApiSecret'> | null, keyring: SecretBoxKeyring | null): {
+    apiSecret: string;
+    reseal: boolean;
+} | null;
+/** The connection's keys in the clear, or `null` when the secret cannot be opened. */
+export declare function shippingEasyCredentialsOf(connection: ShippingEasyConnection, keyring: SecretBoxKeyring | null): ShippingEasyCredentials | null;
+/** The hex HMAC-SHA256 ShippingEasy signs with. */
+export declare function signShippingEasy(apiSecret: string, plaintext: string): string;
+/** ShippingEasy's API address: the env's when it is an https URL, else theirs. */
+export declare function shippingEasyBaseUrl(env?: Record<string, string | undefined>): string;
+/** One signed call to ShippingEasy. `path` is the full path, `/api/…`. Network failures become `ShippingEasyUnavailableError`. */
+export declare function shippingEasyRequest(credentials: ShippingEasyCredentials, input: {
+    method: 'GET' | 'POST';
+    path: string;
+    query?: Record<string, string>;
+    body?: unknown;
+}, deps?: ShippingEasyDeps): Promise<{
+    status: number;
+    text: string;
+}>;
+/** A refusal's words for the card: ShippingEasy's own message when it sent one, else its status. */
+export declare function shippingEasyRefusalMessage(response: {
+    status: number;
+    text: string;
+}): string;
+/**
+ * Whether the keys work: one read of the store's orders. `refused` means
+ * ShippingEasy said no to these keys or this store; `unavailable` means it
+ * could not be asked.
+ */
+export declare function checkShippingEasyCredentials(credentials: ShippingEasyCredentials, deps?: ShippingEasyDeps): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: 'refused' | 'unavailable';
+    message: string;
+}>;
+/** What one push came to. A transient failure throws `ShippingEasyUnavailableError` instead. */
+export type ShippingEasyPushOutcome = {
+    result: 'not_connected' | 'skipped' | 'already' | 'sent' | 'canceled';
+} | {
+    result: 'refused';
+    message: string;
+} | {
+    result: 'failed';
+    message: string;
+};
+/**
+ * Sends one order to ShippingEasy as it stands now, or cancels it there.
+ * Safe to call any number of times for the same order: see the block header.
+ */
+export declare function pushShippingEasyOrder(hostId: string, orderId: string, deps?: ShippingEasyDeps): Promise<ShippingEasyPushOutcome>;
+/**
+ * The `shippingeasy` subscriber to commerce's order events. Throws on a
+ * failure that may pass, so the outbox retries; on its last attempt the
+ * site's managers are told and the card shows why.
+ */
+export declare function deliverOrderEventToShippingEasy(envelope: Pick<PluginDomainEventEnvelope, 'hostId' | 'payload' | 'attempt' | 'event'>, deps?: ShippingEasyDeps): Promise<ShippingEasyPushOutcome | null>;
+/** What "Send open orders" came to. */
+export interface ShippingEasySyncResult {
+    sent: number;
+    already: number;
+    failed: number;
+    /** Whether more open orders are left past this pass's limit. */
+    more: boolean;
+}
+/**
+ * Pushes the site's open orders from the last 90 days, a pass at a time: the
+ * orders paid before the connection, or while it was failing. One indexed
+ * query (`requiresShipping ==`, `updatedAtMs` range) — the same index the
+ * ShipStation feed reads.
+ */
+export declare function syncShippingEasyOrders(hostId: string, deps?: ShippingEasyDeps): Promise<ShippingEasySyncResult>;
+/**
+ * Whether a callback was signed with this secret: the HMAC of its method,
+ * path, query (without `api_signature`) and raw body, compared in constant
+ * time; and, when it carries `api_timestamp`, sent within the hour.
+ */
+export declare function verifyShippingEasyCallback(input: {
+    apiSecret: string;
+    method: string;
+    path: string;
+    query: URLSearchParams;
+    body: string;
+    nowMs: number;
+}): 'ok' | 'unsigned' | 'bad_signature' | 'expired';
+/** `POST /api/commerce/shippingeasy/{hostId}` — ShippingEasy's shipment notification. See the block header. */
+export declare function shippingEasyRoute(request: Request, context: {
+    params: Record<string, string | string[]>;
+}, deps?: ShippingEasyDeps): Promise<Response>;
+/** What the card shows about a connection. Never a key in full, never the secret. */
+export interface ShippingEasyConnectionStatus {
+    /** Whether this deployment can seal a secret at all. */
+    available: boolean;
+    connected: boolean;
+    apiKeyEnding?: string;
+    storeApiKeyEnding?: string;
+    createdAtMs?: number;
+    updatedAtMs?: number;
+    lastPushAtMs?: number;
+    lastCallbackAtMs?: number;
+    lastError?: {
+        message: string;
+        atMs: number;
+        orderNumber?: string;
+    } | null;
+}
+export declare function shippingEasyStatusOf(connection: ShippingEasyConnection | null, available: boolean): ShippingEasyConnectionStatus;
+/** The card's actions. `status` is the GET. */
+export declare const SHIPPINGEASY_ACTIONS: readonly ["status", "connect", "sync", "disconnect"];
+export type ShippingEasyAction = (typeof SHIPPINGEASY_ACTIONS)[number];
+declare const ACTIVITY: {
+    readonly type: "commerce:shippingEasy";
+    readonly id: "shippingeasy";
+    readonly name: "ShippingEasy";
+};
+/**
+ * One action of the ShippingEasy card, for a caller the connectors route has
+ * already proven a site admin (or, for `status`, an editor) on a site with
+ * commerce. Answers the status and body the route sends.
+ *
+ * - `connect` saves the three keys after one read proves them, sealing the
+ *   secret; on a site already connected it replaces them (a merchant who
+ *   made a new secret in ShippingEasy enters it here).
+ * - `sync` pushes the open orders, a pass at a time.
+ * - `disconnect` deletes the connection; the per-order records go with it,
+ *   so a later connect sends the open orders afresh.
+ */
+export declare function shippingEasyConnectorAction(input: {
+    hostId: string;
+    action: ShippingEasyAction;
+    body: Record<string, unknown>;
+    actor: {
+        uid: string;
+        email: string | null;
+    };
+    log: (action: string, target: typeof ACTIVITY) => Promise<void>;
+    prepareOpenOrders?: (hostId: string) => Promise<unknown>;
+}, deps?: ShippingEasyDeps): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+}>;
+export {};