@aglyn/plugins-marketplace 1.2.0 → 1.3.0

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

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * THE TAX CLASSIFICATION OF A MARKETPLACE SALE (AGL-1553).
+ *
+ * "Software as a service (SaaS) — business use". Sent explicitly on the line
+ * item below, because this session builds its product ad hoc from
+ * `price_data` and an ad-hoc product with no `tax_code` is classified by the
+ * ACCOUNT-LEVEL preset instead — a value set by hand in the Stripe Dashboard
+ * for Aglyn's own subscription products (AGL-1537/1877), which happens to be
+ * this same string.
+ *
+ * So this is not a change of tax position, and deliberately not: it is the
+ * position Aglyn already collects on, already verified, and already states in
+ * a signed filing. The pending Texas private letter ruling request proposes at
+ * Part 6.1 that plugin charges are DATA PROCESSING SERVICES under Tax Code
+ * § 151.0035, of which § 151.351 exempts 20%, so tax is due on 80% of the
+ * charge; Part 4.5 ¶ 4 represents to the Comptroller that "the payment
+ * processor's tax classification applied to these charges is the
+ * software-as-a-service category" and that the 80% measure was confirmed by
+ * computation. AGL-1817 ran that computation against the live account: $6.60
+ * of tax on a $100.00 charge at an 8.25% Texas address — 8.25% x $80.
+ *
+ * What was actually broken is that none of that was expressed HERE. The
+ * classification of every marketplace sale hung on a Dashboard field owned by
+ * a different product line. Re-preset the account for storefront goods or
+ * bookings and these sales silently re-classify, moving the Texas base off the
+ * 80% the filing describes — with no diff to review, no failing test, and no
+ * symptom short of reconciling a return. Naming it here is what makes the
+ * filed representation survive a Dashboard edit.
+ *
+ * NOT merged with `PLATFORM_TAX_CODE` in `tools/scripts/lib/stripe-tax-code.mjs`,
+ * which stamps Aglyn's OWN products with the same string today. They answer
+ * different questions — Aglyn's first-party subscription vs. a third party's
+ * sale through Aglyn's marketplace — and the ruling request itself flags at
+ * Part 8 ¶ 8 that the Comptroller could characterize the two differently. One
+ * shared constant would make a divergence the filing anticipates impossible to
+ * express without touching the other business.
+ *
+ * DO NOT change this value to a downloadable-software code (`txcd_10202003`,
+ * `txcd_10203001`) on the reasoning that a plugin is "downloaded". That is the
+ * OPPOSING characterization — tangible personal property under Rule 3.308,
+ * taxable in full — which Part 6.1 argues against and which the filing already
+ * states against itself, in full, at Part 8 ¶¶ 1-2. Adopting
+ * it here would raise the tax charged to every buyer by a quarter of the base
+ * and make Part 4.5 ¶ 4 false. It is the Comptroller's call, and if the ruling
+ * goes that way the change is a one-line edit at this constant plus a
+ * prospective conformance — which is exactly what naming it here buys.
+ */
+export declare const MARKETPLACE_TAX_CODE = "txcd_10103001";
+/** Who is buying: the person, the workspace the licence is for, and what they may do in it. */
+export interface SaleBuyer {
+    uid: string;
+    orgId: string;
+    permissions: {
+        createHosts?: boolean;
+        installPlugins?: boolean;
+    };
+}
+/** One sale, decided: everything the payment doors need and nothing they chose. */
+export interface MarketplaceSale {
+    listing: Record<string, any>;
+    /** A site starter is bought to create a site with, everything else to install. */
+    siteStarter: boolean;
+    sellerOrgId: string;
+    feePercent: number;
+    amountCents: number;
+    feeCents: number;
+    /** What the seller receives: 0 when the platform's own org is the seller. */
+    transferCents: number;
+    /** The seller's Connect account; absent when {@link platformSale}. */
+    accountId: string | undefined;
+    /** The platform's own org is selling, so no transfer is made at all. */
+    platformSale: boolean;
+}
+/** The answer a door sends instead of taking money: the status and body, decided together. */
+export interface SaleRefusal {
+    status: number;
+    body: Record<string, unknown>;
+}
+export type SaleResolution = {
+    sale: MarketplaceSale;
+} | {
+    refusal: SaleRefusal;
+};
+/**
+ * EVERYTHING A MARKETPLACE SALE DECIDES BEFORE STRIPE (AGL-4049).
+ *
+ * One value, for both doors that take money for a listing: the hosted
+ * checkout (`checkout.ts`) and the in-app payment (`pay.ts`). A second copy of
+ * these gates is how a door comes to sell something the other refuses, and
+ * every refusal below has already cost a real sale or a real refund to learn.
+ *
+ * The caller has settled WHO is buying, through the person's own membership;
+ * this settles whether that workspace may buy this listing, from this seller,
+ * today, and at what split.
+ *
+ * Deliberately before the door's idempotency claim, so none of these burns the
+ * key: each is a state somebody fixes before pressing the same button again.
+ */
+export declare function resolveSale(input: {
+    firestore: FirebaseFirestore.Firestore;
+    listingId: string;
+    buyer: SaleBuyer;
+}): Promise<SaleResolution>;

package/src/lib/server/sale.js

@@ -0,0 +1,304 @@
+/**
+ * @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 { merchantAccountIsReady } from "@aglyn/tenant-data-admin/server/payment-provider";
+import { checkEntitlement, isListingWideRevocation, resolveMarketplaceFeePct } from "@aglyn/aglyn/server";
+import { permissionRefusalText } from "@aglyn/aglyn/app-utils/org-permissions";
+import { SITE_STARTER_ARTIFACT_TYPE } from "@aglyn/aglyn/app-utils/site-starter";
+import { isListingBrowsable, isPrivateListing, listingArtifactType } from "../model/marketplace.js";
+import { sellsAsPlatform } from "../model/platform-seller.js";
+import { readPlatformOrgId } from "./platform-org.js";
+import { canActAsPublisher, resolvePublisherProfile } from "./publisher-profile.js";
+import { hasLivePurchase } from "./purchase-entitlement.js";
+import { isOrgMember } from "./sale-risk.js";
+/**
+ * THE TAX CLASSIFICATION OF A MARKETPLACE SALE (AGL-1553).
+ *
+ * "Software as a service (SaaS) — business use". Sent explicitly on the line
+ * item below, because this session builds its product ad hoc from
+ * `price_data` and an ad-hoc product with no `tax_code` is classified by the
+ * ACCOUNT-LEVEL preset instead — a value set by hand in the Stripe Dashboard
+ * for Aglyn's own subscription products (AGL-1537/1877), which happens to be
+ * this same string.
+ *
+ * So this is not a change of tax position, and deliberately not: it is the
+ * position Aglyn already collects on, already verified, and already states in
+ * a signed filing. The pending Texas private letter ruling request proposes at
+ * Part 6.1 that plugin charges are DATA PROCESSING SERVICES under Tax Code
+ * § 151.0035, of which § 151.351 exempts 20%, so tax is due on 80% of the
+ * charge; Part 4.5 ¶ 4 represents to the Comptroller that "the payment
+ * processor's tax classification applied to these charges is the
+ * software-as-a-service category" and that the 80% measure was confirmed by
+ * computation. AGL-1817 ran that computation against the live account: $6.60
+ * of tax on a $100.00 charge at an 8.25% Texas address — 8.25% x $80.
+ *
+ * What was actually broken is that none of that was expressed HERE. The
+ * classification of every marketplace sale hung on a Dashboard field owned by
+ * a different product line. Re-preset the account for storefront goods or
+ * bookings and these sales silently re-classify, moving the Texas base off the
+ * 80% the filing describes — with no diff to review, no failing test, and no
+ * symptom short of reconciling a return. Naming it here is what makes the
+ * filed representation survive a Dashboard edit.
+ *
+ * NOT merged with `PLATFORM_TAX_CODE` in `tools/scripts/lib/stripe-tax-code.mjs`,
+ * which stamps Aglyn's OWN products with the same string today. They answer
+ * different questions — Aglyn's first-party subscription vs. a third party's
+ * sale through Aglyn's marketplace — and the ruling request itself flags at
+ * Part 8 ¶ 8 that the Comptroller could characterize the two differently. One
+ * shared constant would make a divergence the filing anticipates impossible to
+ * express without touching the other business.
+ *
+ * DO NOT change this value to a downloadable-software code (`txcd_10202003`,
+ * `txcd_10203001`) on the reasoning that a plugin is "downloaded". That is the
+ * OPPOSING characterization — tangible personal property under Rule 3.308,
+ * taxable in full — which Part 6.1 argues against and which the filing already
+ * states against itself, in full, at Part 8 ¶¶ 1-2. Adopting
+ * it here would raise the tax charged to every buyer by a quarter of the base
+ * and make Part 4.5 ¶ 4 false. It is the Comptroller's call, and if the ruling
+ * goes that way the change is a one-line edit at this constant plus a
+ * prospective conformance — which is exactly what naming it here buys.
+ */ export const MARKETPLACE_TAX_CODE = 'txcd_10103001';
+const refuse = (status, body)=>({
+        refusal: {
+            status,
+            body
+        }
+    });
+/**
+ * EVERYTHING A MARKETPLACE SALE DECIDES BEFORE STRIPE (AGL-4049).
+ *
+ * One value, for both doors that take money for a listing: the hosted
+ * checkout (`checkout.ts`) and the in-app payment (`pay.ts`). A second copy of
+ * these gates is how a door comes to sell something the other refuses, and
+ * every refusal below has already cost a real sale or a real refund to learn.
+ *
+ * The caller has settled WHO is buying, through the person's own membership;
+ * this settles whether that workspace may buy this listing, from this seller,
+ * today, and at what split.
+ *
+ * Deliberately before the door's idempotency claim, so none of these burns the
+ * key: each is a state somebody fixes before pressing the same button again.
+ */ export async function resolveSale(input) {
+    var _listing_priceUsd, _listing_profileId, _sellerOrgDoc_data;
+    const { firestore, listingId, buyer } = input;
+    const listingSnapshot = await firestore.collection('marketplaceListings').doc(listingId).get();
+    const listing = listingSnapshot.data();
+    if (!listing || listing.deletedAt) {
+        return refuse(404, {
+            error: 'Unknown listing'
+        });
+    }
+    // A site starter is bought to create a site with (AGL-4049), so buying
+    // one takes the permission that creates sites, as picking one in Create
+    // site does; everything else is bought to install, as before. Asked of
+    // the listing, never of the request, and before anything else about the
+    // sale is read.
+    const siteStarter = listingArtifactType(listing) === SITE_STARTER_ARTIFACT_TYPE;
+    if (siteStarter ? !buyer.permissions.createHosts : !buyer.permissions.installPlugins) {
+        return refuse(403, {
+            error: siteStarter ? permissionRefusalText('hosts.create') : 'Your organization role does not allow installing from the marketplace'
+        });
+    }
+    // Review gating holds on the PAID path too (AGL-1543): browse hides
+    // rejected/submitted/in_review listings, so a direct checkout call must
+    // not be a side door that takes money for one. Absent = legacy = listed
+    // (AGL-432), and the same 404 as an unknown listing — purchasability is
+    // not a probe for review state.
+    const reviewStatus = listing.reviewStatus;
+    if (reviewStatus && reviewStatus !== 'listed' && reviewStatus !== 'verified') {
+        return refuse(404, {
+            error: 'Unknown listing'
+        });
+    }
+    // A TAKEN-DOWN or PRIVATE listing is not on sale (AGL-2288).
+    //
+    // The check above is a hand-rolled subset of `isListingBrowsable`, and
+    // the two lines it dropped are the two that matter here: `hiddenAt` and
+    // `isPrivateListing`. A staff takedown does NOT set a blocking
+    // `reviewStatus` — `plugin-reviews` demotes a verified listing to
+    // `VERIFIED_STRIPPED_STATUS`, which is literally `'listed'` — so after a
+    // takedown this route read `reviewStatus: 'listed'` and sold the listing
+    // in full, while `install-plugin` refused the very same listing at
+    // `hiddenAt` with a 404. The buyer was charged for something the platform
+    // had already decided nobody may install, and the only way out was a
+    // refund — which is Aglyn's Stripe fee, Aglyn's support time, and (until
+    // the partial-refund fix) a real hole in the split.
+    //
+    // Both tests are kept rather than replaced by the shared predicate: for a
+    // NON-plugin artifact `isListingBrowsable` returns true whatever the
+    // review status says, because pre-publication review is plugin-only. This
+    // route has always been stricter than that, and a sale is the wrong place
+    // to loosen a gate.
+    //
+    // No owner exemption, unlike the install routes: `canActAsPublisher`
+    // below already refuses a publisher buying their own listing, so the
+    // buyer here is never the owner.
+    if (!isListingBrowsable(listing) || isPrivateListing(listing)) {
+        return refuse(404, {
+            error: 'Unknown listing'
+        });
+    }
+    const priceUsd = Number((_listing_priceUsd = listing.priceUsd) != null ? _listing_priceUsd : 0);
+    if (!(priceUsd > 0)) {
+        return refuse(400, {
+            error: 'Listing is free'
+        });
+    }
+    // Publishing is org-owned (AGL-652): `profileId` IS the publisher org id.
+    const sellerOrgId = String((_listing_profileId = listing.profileId) != null ? _listing_profileId : '');
+    // ANY member of the publishing workspace, and any purchase FOR it
+    // (AGL-3365). `canActAsPublisher` asks only for an owner or admin, so an
+    // editor of the publisher — or an owner buying "for" the publisher's own
+    // workspace through a role that can install — passed it, and a publisher
+    // could pay itself: the stolen-card cash-out the payout exists to make
+    // worth doing. A workspace one step removed is the sale screen's to flag.
+    if (buyer.orgId === sellerOrgId || await canActAsPublisher(firestore, buyer.uid, sellerOrgId) || await isOrgMember(firestore, sellerOrgId, buyer.uid)) {
+        return refuse(400, {
+            error: 'Your organization published this listing'
+        });
+    }
+    // You cannot buy the same component twice (AGL-1697).
+    //
+    // This route validated review status, self-purchase and the seller's
+    // entitlements, and then never asked the one question the buyer cares
+    // about: do they already own it. A marketplace listing is a buy-once good —
+    // a second purchase buys nothing, since `requirePurchase` is satisfied by
+    // the first — so a buyer who clicked Buy again from a stale tab, or came
+    // back through a bookmarked checkout, was simply charged twice for it.
+    //
+    // Deliberately the SAME predicate the seven install routes gate on
+    // (AGL-1546/1699) rather than a second query beside it: "has this buyer
+    // paid for this listing" must have one answer, or the marketplace can take
+    // money for something it will not install, or refuse to sell something it
+    // will not install either. That predicate reads a fully REFUNDED purchase
+    // as absent, which is exactly right here too — a refunded buyer must be
+    // able to buy again, and a refunded row sitting beside a live one does not
+    // veto it.
+    //
+    // 409 rather than 400: nothing about the request is malformed, the buyer
+    // is just asking for a state that already holds.
+    //
+    // KEYED ON THE ORGANIZATION SINCE AGL-2331, and that is what turns this
+    // guard from a blocked sale back into a real one. A licence belongs to a
+    // workspace, so an agency developer who bought a component for one client
+    // must be able to buy it again for the next — the person-keyed version of
+    // this check answered `409 already_purchased` to exactly the second sale
+    // we want. It still refuses the case it was written for: the same
+    // workspace buying the same listing twice.
+    //
+    // A pre-AGL-2331 purchase still refuses, through the legacy grant inside
+    // the shared predicate: that buyer can already install this listing
+    // anywhere, so selling them a second copy would take money for nothing.
+    if (await hasLivePurchase({
+        firestore,
+        buyerUid: buyer.uid,
+        buyerOrgId: buyer.orgId,
+        listingId
+    })) {
+        return refuse(409, {
+            error: 'This organization already owns this listing — install it from ' + 'your library.',
+            code: 'already_purchased'
+        });
+    }
+    // The kill switch, on the SELL side too (AGL-2288).
+    //
+    // `revocations/{listingId}` with `versions: 'all'` is the listing-wide
+    // kill: `install-plugin` 409s on it through this same predicate, and the
+    // tenant runtime renders the disabled placeholder for anything already
+    // pinned. Selling into that state takes money for an artifact the
+    // platform has switched off.
+    //
+    // Only `'all'` is consulted, deliberately. A per-version revocation
+    // (AGL-1085) stops one build while other approved versions stay
+    // installable, and refusing the sale for it would turn a targeted control
+    // into a de-listing. Whether the newest approved version happens to be
+    // the revoked one is a question `install-plugin` answers with live data;
+    // duplicating that resolution here would be a second copy of it.
+    //
+    // One extra read on a path that already makes several Firestore and
+    // Stripe round trips, and it is the cheap half of the takedown check
+    // above: a hand-written revocation doc — which the rules permit any staff
+    // client to write — is caught here even when `hiddenAt` was never set.
+    const revocation = (await firestore.collection('revocations').doc(listingId).get()).data();
+    if (isListingWideRevocation(revocation)) {
+        return refuse(404, {
+            error: 'Unknown listing'
+        });
+    }
+    const publisher = await resolvePublisherProfile(firestore, sellerOrgId);
+    const accountId = publisher == null ? void 0 : publisher.stripeAccountId;
+    // The platform's cut comes from ENTITLEMENTS (AGL-1543), never the raw
+    // `plan` field: `resolveMarketplaceFeePct` prices a dead subscription
+    // as free-plan (30%) while the stale field still says pro, and honors
+    // a negotiated per-org `marketplaceFeePct` override. Same read gates
+    // SALE time on `marketplaceSelling` — publish already refuses without
+    // it, and a publisher who downgrades must stop selling, not merely
+    // stop publishing. Resolved per request; entitlements are never cached.
+    const sellerOrgDoc = await firestore.collection('orgs').doc(sellerOrgId).get();
+    const sellerOrg = (_sellerOrgDoc_data = sellerOrgDoc.data()) != null ? _sellerOrgDoc_data : {};
+    const feePercent = resolveMarketplaceFeePct(sellerOrg);
+    // THE PLATFORM'S OWN ORG, AT THE STAFF WAIVER (AGL-4049). Nobody to pay, so
+    // no account to be ready and no transfer to make. Asked here, ahead of the
+    // payout gate, which is the only refusal it changes: a lock and the plan
+    // below hold for it as for anyone.
+    const platformSale = sellsAsPlatform({
+        sellerOrgId,
+        feePercent,
+        platformOrgId: readPlatformOrgId()
+    });
+    if (!platformSale && !merchantAccountIsReady({
+        accountId,
+        chargesEnabled: publisher == null ? void 0 : publisher.stripeChargesEnabled,
+        accountLivemode: publisher == null ? void 0 : publisher.stripeAccountLivemode
+    }, {
+        subject: `marketplace publisher org ${sellerOrgId}`
+    })) {
+        return refuse(409, {
+            error: 'The publisher has not enabled payouts yet'
+        });
+    }
+    // A LOCKED publisher sells nothing (AGL-3365). Any lock, not only a
+    // security one: a sale to a workspace staff have stopped is money moving
+    // to it, and the lockdown's payout pause cannot reach a share that is
+    // never charged. The same answer as a taken-down listing — a lock is not
+    // a buyer's business.
+    if (sellerOrg.suspendedAt != null) {
+        return refuse(404, {
+            error: 'Unknown listing'
+        });
+    }
+    if (!checkEntitlement(sellerOrg, 'marketplaceSelling')) {
+        return refuse(409, {
+            error: "The publisher's current plan does not include marketplace selling"
+        });
+    }
+    const amountCents = Math.round(priceUsd * 100);
+    const feeCents = Math.round(amountCents * feePercent / 100);
+    return {
+        sale: {
+            listing,
+            siteStarter,
+            sellerOrgId,
+            feePercent,
+            amountCents,
+            feeCents,
+            transferCents: platformSale ? 0 : amountCents - feeCents,
+            accountId: platformSale ? undefined : accountId,
+            platformSale
+        }
+    };
+}
+
+//# sourceMappingURL=sale.js.map

package/src/lib/server/sale.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketplace/src/lib/server/sale.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 { merchantAccountIsReady } from '@aglyn/tenant-data-admin/server/payment-provider'\nimport {\n  checkEntitlement,\n  isListingWideRevocation,\n  resolveMarketplaceFeePct,\n  type PluginRevocation,\n} from '@aglyn/aglyn/server'\nimport { permissionRefusalText } from '@aglyn/aglyn/app-utils/org-permissions'\nimport { SITE_STARTER_ARTIFACT_TYPE } from '@aglyn/aglyn/app-utils/site-starter'\nimport { isListingBrowsable, isPrivateListing, listingArtifactType } from '../model/marketplace'\nimport { sellsAsPlatform } from '../model/platform-seller'\nimport { readPlatformOrgId } from './platform-org'\nimport { canActAsPublisher, resolvePublisherProfile } from './publisher-profile'\nimport { hasLivePurchase } from './purchase-entitlement'\nimport { isOrgMember } from './sale-risk'\n\n/**\n * THE TAX CLASSIFICATION OF A MARKETPLACE SALE (AGL-1553).\n *\n * \"Software as a service (SaaS) — business use\". Sent explicitly on the line\n * item below, because this session builds its product ad hoc from\n * `price_data` and an ad-hoc product with no `tax_code` is classified by the\n * ACCOUNT-LEVEL preset instead — a value set by hand in the Stripe Dashboard\n * for Aglyn's own subscription products (AGL-1537/1877), which happens to be\n * this same string.\n *\n * So this is not a change of tax position, and deliberately not: it is the\n * position Aglyn already collects on, already verified, and already states in\n * a signed filing. The pending Texas private letter ruling request proposes at\n * Part 6.1 that plugin charges are DATA PROCESSING SERVICES under Tax Code\n * § 151.0035, of which § 151.351 exempts 20%, so tax is due on 80% of the\n * charge; Part 4.5 ¶ 4 represents to the Comptroller that \"the payment\n * processor's tax classification applied to these charges is the\n * software-as-a-service category\" and that the 80% measure was confirmed by\n * computation. AGL-1817 ran that computation against the live account: $6.60\n * of tax on a $100.00 charge at an 8.25% Texas address — 8.25% x $80.\n *\n * What was actually broken is that none of that was expressed HERE. The\n * classification of every marketplace sale hung on a Dashboard field owned by\n * a different product line. Re-preset the account for storefront goods or\n * bookings and these sales silently re-classify, moving the Texas base off the\n * 80% the filing describes — with no diff to review, no failing test, and no\n * symptom short of reconciling a return. Naming it here is what makes the\n * filed representation survive a Dashboard edit.\n *\n * NOT merged with `PLATFORM_TAX_CODE` in `tools/scripts/lib/stripe-tax-code.mjs`,\n * which stamps Aglyn's OWN products with the same string today. They answer\n * different questions — Aglyn's first-party subscription vs. a third party's\n * sale through Aglyn's marketplace — and the ruling request itself flags at\n * Part 8 ¶ 8 that the Comptroller could characterize the two differently. One\n * shared constant would make a divergence the filing anticipates impossible to\n * express without touching the other business.\n *\n * DO NOT change this value to a downloadable-software code (`txcd_10202003`,\n * `txcd_10203001`) on the reasoning that a plugin is \"downloaded\". That is the\n * OPPOSING characterization — tangible personal property under Rule 3.308,\n * taxable in full — which Part 6.1 argues against and which the filing already\n * states against itself, in full, at Part 8 ¶¶ 1-2. Adopting\n * it here would raise the tax charged to every buyer by a quarter of the base\n * and make Part 4.5 ¶ 4 false. It is the Comptroller's call, and if the ruling\n * goes that way the change is a one-line edit at this constant plus a\n * prospective conformance — which is exactly what naming it here buys.\n */\nexport const MARKETPLACE_TAX_CODE = 'txcd_10103001'\n\n/** Who is buying: the person, the workspace the licence is for, and what they may do in it. */\nexport interface SaleBuyer {\n  uid: string\n  orgId: string\n  permissions: { createHosts?: boolean; installPlugins?: boolean }\n}\n\n/** One sale, decided: everything the payment doors need and nothing they chose. */\nexport interface MarketplaceSale {\n  listing: Record<string, any>\n  /** A site starter is bought to create a site with, everything else to install. */\n  siteStarter: boolean\n  sellerOrgId: string\n  feePercent: number\n  amountCents: number\n  feeCents: number\n  /** What the seller receives: 0 when the platform's own org is the seller. */\n  transferCents: number\n  /** The seller's Connect account; absent when {@link platformSale}. */\n  accountId: string | undefined\n  /** The platform's own org is selling, so no transfer is made at all. */\n  platformSale: boolean\n}\n\n/** The answer a door sends instead of taking money: the status and body, decided together. */\nexport interface SaleRefusal {\n  status: number\n  body: Record<string, unknown>\n}\n\nexport type SaleResolution = { sale: MarketplaceSale } | { refusal: SaleRefusal }\n\nconst refuse = (status: number, body: Record<string, unknown>): SaleResolution => ({\n  refusal: { status, body },\n})\n\n/**\n * EVERYTHING A MARKETPLACE SALE DECIDES BEFORE STRIPE (AGL-4049).\n *\n * One value, for both doors that take money for a listing: the hosted\n * checkout (`checkout.ts`) and the in-app payment (`pay.ts`). A second copy of\n * these gates is how a door comes to sell something the other refuses, and\n * every refusal below has already cost a real sale or a real refund to learn.\n *\n * The caller has settled WHO is buying, through the person's own membership;\n * this settles whether that workspace may buy this listing, from this seller,\n * today, and at what split.\n *\n * Deliberately before the door's idempotency claim, so none of these burns the\n * key: each is a state somebody fixes before pressing the same button again.\n */\nexport async function resolveSale(input: {\n  firestore: FirebaseFirestore.Firestore\n  listingId: string\n  buyer: SaleBuyer\n}): Promise<SaleResolution> {\n  const { firestore, listingId, buyer } = input\n  const listingSnapshot = await firestore\n    .collection('marketplaceListings')\n    .doc(listingId)\n    .get()\n  const listing = listingSnapshot.data() as any\n  if (!listing || listing.deletedAt) {\n    return refuse(404, { error: 'Unknown listing' })\n  }\n  // A site starter is bought to create a site with (AGL-4049), so buying\n  // one takes the permission that creates sites, as picking one in Create\n  // site does; everything else is bought to install, as before. Asked of\n  // the listing, never of the request, and before anything else about the\n  // sale is read.\n  const siteStarter = listingArtifactType(listing) === SITE_STARTER_ARTIFACT_TYPE\n  if (siteStarter ? !buyer.permissions.createHosts : !buyer.permissions.installPlugins) {\n    return refuse(403, {\n      error: siteStarter\n        ? permissionRefusalText('hosts.create')\n        : 'Your organization role does not allow installing from the marketplace',\n    })\n  }\n  // Review gating holds on the PAID path too (AGL-1543): browse hides\n  // rejected/submitted/in_review listings, so a direct checkout call must\n  // not be a side door that takes money for one. Absent = legacy = listed\n  // (AGL-432), and the same 404 as an unknown listing — purchasability is\n  // not a probe for review state.\n  const reviewStatus = listing.reviewStatus as string | undefined\n  if (reviewStatus && reviewStatus !== 'listed' && reviewStatus !== 'verified') {\n    return refuse(404, { error: 'Unknown listing' })\n  }\n  // A TAKEN-DOWN or PRIVATE listing is not on sale (AGL-2288).\n  //\n  // The check above is a hand-rolled subset of `isListingBrowsable`, and\n  // the two lines it dropped are the two that matter here: `hiddenAt` and\n  // `isPrivateListing`. A staff takedown does NOT set a blocking\n  // `reviewStatus` — `plugin-reviews` demotes a verified listing to\n  // `VERIFIED_STRIPPED_STATUS`, which is literally `'listed'` — so after a\n  // takedown this route read `reviewStatus: 'listed'` and sold the listing\n  // in full, while `install-plugin` refused the very same listing at\n  // `hiddenAt` with a 404. The buyer was charged for something the platform\n  // had already decided nobody may install, and the only way out was a\n  // refund — which is Aglyn's Stripe fee, Aglyn's support time, and (until\n  // the partial-refund fix) a real hole in the split.\n  //\n  // Both tests are kept rather than replaced by the shared predicate: for a\n  // NON-plugin artifact `isListingBrowsable` returns true whatever the\n  // review status says, because pre-publication review is plugin-only. This\n  // route has always been stricter than that, and a sale is the wrong place\n  // to loosen a gate.\n  //\n  // No owner exemption, unlike the install routes: `canActAsPublisher`\n  // below already refuses a publisher buying their own listing, so the\n  // buyer here is never the owner.\n  if (!isListingBrowsable(listing) || isPrivateListing(listing)) {\n    return refuse(404, { error: 'Unknown listing' })\n  }\n  const priceUsd = Number(listing.priceUsd ?? 0)\n  if (!(priceUsd > 0)) {\n    return refuse(400, { error: 'Listing is free' })\n  }\n  // Publishing is org-owned (AGL-652): `profileId` IS the publisher org id.\n  const sellerOrgId = String(listing.profileId ?? '')\n  // ANY member of the publishing workspace, and any purchase FOR it\n  // (AGL-3365). `canActAsPublisher` asks only for an owner or admin, so an\n  // editor of the publisher — or an owner buying \"for\" the publisher's own\n  // workspace through a role that can install — passed it, and a publisher\n  // could pay itself: the stolen-card cash-out the payout exists to make\n  // worth doing. A workspace one step removed is the sale screen's to flag.\n  if (\n    buyer.orgId === sellerOrgId ||\n    (await canActAsPublisher(firestore, buyer.uid, sellerOrgId)) ||\n    (await isOrgMember(firestore, sellerOrgId, buyer.uid))\n  ) {\n    return refuse(400, { error: 'Your organization published this listing' })\n  }\n  // You cannot buy the same component twice (AGL-1697).\n  //\n  // This route validated review status, self-purchase and the seller's\n  // entitlements, and then never asked the one question the buyer cares\n  // about: do they already own it. A marketplace listing is a buy-once good —\n  // a second purchase buys nothing, since `requirePurchase` is satisfied by\n  // the first — so a buyer who clicked Buy again from a stale tab, or came\n  // back through a bookmarked checkout, was simply charged twice for it.\n  //\n  // Deliberately the SAME predicate the seven install routes gate on\n  // (AGL-1546/1699) rather than a second query beside it: \"has this buyer\n  // paid for this listing\" must have one answer, or the marketplace can take\n  // money for something it will not install, or refuse to sell something it\n  // will not install either. That predicate reads a fully REFUNDED purchase\n  // as absent, which is exactly right here too — a refunded buyer must be\n  // able to buy again, and a refunded row sitting beside a live one does not\n  // veto it.\n  //\n  // 409 rather than 400: nothing about the request is malformed, the buyer\n  // is just asking for a state that already holds.\n  //\n  // KEYED ON THE ORGANIZATION SINCE AGL-2331, and that is what turns this\n  // guard from a blocked sale back into a real one. A licence belongs to a\n  // workspace, so an agency developer who bought a component for one client\n  // must be able to buy it again for the next — the person-keyed version of\n  // this check answered `409 already_purchased` to exactly the second sale\n  // we want. It still refuses the case it was written for: the same\n  // workspace buying the same listing twice.\n  //\n  // A pre-AGL-2331 purchase still refuses, through the legacy grant inside\n  // the shared predicate: that buyer can already install this listing\n  // anywhere, so selling them a second copy would take money for nothing.\n  if (\n    await hasLivePurchase({\n      firestore,\n      buyerUid: buyer.uid,\n      buyerOrgId: buyer.orgId,\n      listingId,\n    })\n  ) {\n    return refuse(409, {\n      error:\n        'This organization already owns this listing — install it from ' +\n        'your library.',\n      code: 'already_purchased',\n    })\n  }\n  // The kill switch, on the SELL side too (AGL-2288).\n  //\n  // `revocations/{listingId}` with `versions: 'all'` is the listing-wide\n  // kill: `install-plugin` 409s on it through this same predicate, and the\n  // tenant runtime renders the disabled placeholder for anything already\n  // pinned. Selling into that state takes money for an artifact the\n  // platform has switched off.\n  //\n  // Only `'all'` is consulted, deliberately. A per-version revocation\n  // (AGL-1085) stops one build while other approved versions stay\n  // installable, and refusing the sale for it would turn a targeted control\n  // into a de-listing. Whether the newest approved version happens to be\n  // the revoked one is a question `install-plugin` answers with live data;\n  // duplicating that resolution here would be a second copy of it.\n  //\n  // One extra read on a path that already makes several Firestore and\n  // Stripe round trips, and it is the cheap half of the takedown check\n  // above: a hand-written revocation doc — which the rules permit any staff\n  // client to write — is caught here even when `hiddenAt` was never set.\n  const revocation = (\n    await firestore.collection('revocations').doc(listingId).get()\n  ).data() as PluginRevocation | undefined\n  if (isListingWideRevocation(revocation)) {\n    return refuse(404, { error: 'Unknown listing' })\n  }\n  const publisher = await resolvePublisherProfile(firestore, sellerOrgId)\n  const accountId = publisher?.stripeAccountId\n  // The platform's cut comes from ENTITLEMENTS (AGL-1543), never the raw\n  // `plan` field: `resolveMarketplaceFeePct` prices a dead subscription\n  // as free-plan (30%) while the stale field still says pro, and honors\n  // a negotiated per-org `marketplaceFeePct` override. Same read gates\n  // SALE time on `marketplaceSelling` — publish already refuses without\n  // it, and a publisher who downgrades must stop selling, not merely\n  // stop publishing. Resolved per request; entitlements are never cached.\n  const sellerOrgDoc = await firestore.collection('orgs').doc(sellerOrgId).get()\n  const sellerOrg = (sellerOrgDoc.data() ?? {}) as any\n  const feePercent = resolveMarketplaceFeePct(sellerOrg)\n  // THE PLATFORM'S OWN ORG, AT THE STAFF WAIVER (AGL-4049). Nobody to pay, so\n  // no account to be ready and no transfer to make. Asked here, ahead of the\n  // payout gate, which is the only refusal it changes: a lock and the plan\n  // below hold for it as for anyone.\n  const platformSale = sellsAsPlatform({\n    sellerOrgId,\n    feePercent,\n    platformOrgId: readPlatformOrgId(),\n  })\n  if (\n    !platformSale &&\n    !merchantAccountIsReady(\n      {\n        accountId,\n        chargesEnabled: publisher?.stripeChargesEnabled,\n        accountLivemode: publisher?.stripeAccountLivemode,\n      },\n      { subject: `marketplace publisher org ${sellerOrgId}` },\n    )\n  ) {\n    return refuse(409, { error: 'The publisher has not enabled payouts yet' })\n  }\n  // A LOCKED publisher sells nothing (AGL-3365). Any lock, not only a\n  // security one: a sale to a workspace staff have stopped is money moving\n  // to it, and the lockdown's payout pause cannot reach a share that is\n  // never charged. The same answer as a taken-down listing — a lock is not\n  // a buyer's business.\n  if (sellerOrg.suspendedAt != null) {\n    return refuse(404, { error: 'Unknown listing' })\n  }\n  if (!checkEntitlement(sellerOrg, 'marketplaceSelling')) {\n    return refuse(409, {\n      error:\n        \"The publisher's current plan does not include marketplace selling\",\n    })\n  }\n  const amountCents = Math.round(priceUsd * 100)\n  const feeCents = Math.round((amountCents * feePercent) / 100)\n  return {\n    sale: {\n      listing,\n      siteStarter,\n      sellerOrgId,\n      feePercent,\n      amountCents,\n      feeCents,\n      transferCents: platformSale ? 0 : amountCents - feeCents,\n      accountId: platformSale ? undefined : accountId,\n      platformSale,\n    },\n  }\n}\n"],"names":["merchantAccountIsReady","checkEntitlement","isListingWideRevocation","resolveMarketplaceFeePct","permissionRefusalText","SITE_STARTER_ARTIFACT_TYPE","isListingBrowsable","isPrivateListing","listingArtifactType","sellsAsPlatform","readPlatformOrgId","canActAsPublisher","resolvePublisherProfile","hasLivePurchase","isOrgMember","MARKETPLACE_TAX_CODE","refuse","status","body","refusal","resolveSale","input","listing","sellerOrgDoc","firestore","listingId","buyer","listingSnapshot","collection","doc","get","data","deletedAt","error","siteStarter","permissions","createHosts","installPlugins","reviewStatus","priceUsd","Number","sellerOrgId","String","profileId","orgId","uid","buyerUid","buyerOrgId","code","revocation","publisher","accountId","stripeAccountId","sellerOrg","feePercent","platformSale","platformOrgId","chargesEnabled","stripeChargesEnabled","accountLivemode","stripeAccountLivemode","subject","suspendedAt","amountCents","Math","round","feeCents","sale","transferCents","undefined"],"mappings":"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"}

package/src/lib/server/starter-publish-facts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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';
+/**
+ * WHAT "PUBLISH AS A STARTER" READS BEFORE THE CLICK, ASKED OF THE SERVER
+ * (AGL-4049).
+ *
+ * `GET /api/marketplace/starter-publish-facts?hostId=` answers
+ * `StarterPublishFactsAnswer`: what the publish would capture, the built-in
+ * theme the site wears as the publish body carries it, and each setup step
+ * still in the way.
+ *
+ * The console's form works these out in the browser; the native apps ask
+ * here, so what a site's built-in theme is stays one function in core
+ * (`siteStarterBuiltinThemeOf`) rather than a port on each platform. It reads
+ * for the same person the door would take: the workspace's "Publish to the
+ * marketplace" (`marketplace.publish`), and the release flag, which staff
+ * pass. A refusal is also how an app knows to offer nothing. The door still
+ * decides: these are what it would say, read early.
+ */
+export declare const starterPublishFactsHandler: PluginApiHandler;
+export default starterPublishFactsHandler;

package/src/lib/server/starter-publish-facts.js

@@ -0,0 +1,135 @@
+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 { permissionRefusalText } from "@aglyn/aglyn/app-utils/org-permissions";
+import { planLabelGrantingFeature } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { SITE_STARTER_MAX_SCREENS } from "@aglyn/aglyn/app-utils/site-starter";
+import { siteStarterBuiltinThemeOf } from "@aglyn/aglyn/app-utils/site-starter-theme";
+import { checkEntitlement } from "@aglyn/aglyn/server";
+import { firebaseAdmin, getOrgForHost, isServerReleaseFlagOnForOrg } from "@aglyn/tenant-data-admin";
+import { isRefusedIdToken } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { resolveOrgPermissions } from "@aglyn/tenant-runtime/org-permissions";
+import { starterPublishFactsAnswer, starterPublishPages } from "../model/starter-publish.js";
+import { PUBLISHER_PROFILES, resolvePublisherProfile } from "./publisher-profile.js";
+import { SITE_STARTERS_UNRELEASED } from "./starters.js";
+/**
+ * WHAT "PUBLISH AS A STARTER" READS BEFORE THE CLICK, ASKED OF THE SERVER
+ * (AGL-4049).
+ *
+ * `GET /api/marketplace/starter-publish-facts?hostId=` answers
+ * `StarterPublishFactsAnswer`: what the publish would capture, the built-in
+ * theme the site wears as the publish body carries it, and each setup step
+ * still in the way.
+ *
+ * The console's form works these out in the browser; the native apps ask
+ * here, so what a site's built-in theme is stays one function in core
+ * (`siteStarterBuiltinThemeOf`) rather than a port on each platform. It reads
+ * for the same person the door would take: the workspace's "Publish to the
+ * marketplace" (`marketplace.publish`), and the release flag, which staff
+ * pass. A refusal is also how an app knows to offer nothing. The door still
+ * decides: these are what it would say, read early.
+ */ export const starterPublishFactsHandler = async (req, res)=>{
+    var _ref, _req_headers_authorization;
+    var _req_query;
+    if (req.method !== 'GET') {
+        return res.status(405).json({
+            error: 'Method not allowed'
+        });
+    }
+    const hostId = String((_ref = (_req_query = req.query) == null ? void 0 : _req_query['hostId']) != null ? _ref : '').trim();
+    if (!hostId) return res.status(400).json({
+        error: 'Missing hostId'
+    });
+    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 decoded;
+    try {
+        decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+    } catch (error) {
+        // Only a refused credential is the caller's 401; failing to check it is
+        // ours and keeps the dispatcher's 5xx.
+        if (!isRefusedIdToken(error)) throw error;
+        return res.status(401).json({
+            error: 'Unauthenticated'
+        });
+    }
+    try {
+        var _ref1;
+        const membership = await resolveOrgPermissions(decoded.uid, {
+            hostId
+        });
+        if (!membership.orgId || !membership.permissions.publishToMarketplace) {
+            return res.status(403).json({
+                error: permissionRefusalText('marketplace.publish')
+            });
+        }
+        const orgId = membership.orgId;
+        if (decoded['staff'] !== true && !await isServerReleaseFlagOnForOrg('release_site_starters', orgId)) {
+            return res.status(403).json({
+                error: SITE_STARTERS_UNRELEASED
+            });
+        }
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const hostSnapshot = await hostRef.get();
+        if (!hostSnapshot.exists) return res.status(404).json({
+            error: 'Unknown site'
+        });
+        const host = hostSnapshot.data();
+        // The routed pages, at most one past the most a starter may have: the
+        // window the door walks, enough to say a site is past the limit.
+        const routing = host['screens'];
+        const routedIds = routing && typeof routing === 'object' && !Array.isArray(routing) ? Object.keys(routing).slice(0, SITE_STARTER_MAX_SCREENS + 1) : [];
+        const screens = routedIds.length ? await firestore.getAll(...routedIds.map((id)=>hostRef.collection('screens').doc(id))) : [];
+        const pages = starterPublishPages(routing, screens.filter((screen)=>screen.exists).map((screen)=>_extends({}, screen.data(), {
+                $id: screen.id
+            })));
+        const [orgForHost, profile, publisher] = await Promise.all([
+            getOrgForHost(hostId),
+            firestore.collection(PUBLISHER_PROFILES).doc(orgId).get(),
+            resolvePublisherProfile(firestore, orgId)
+        ]);
+        const answer = starterPublishFactsAnswer({
+            facts: {
+                plan: _extends({
+                    ready: true,
+                    locked: !checkEntitlement((_ref1 = orgForHost == null ? void 0 : orgForHost.org) != null ? _ref1 : {}, 'marketplaceSelling')
+                }, planLabelGrantingFeature('marketplaceSelling') ? {
+                    planLabel: planLabelGrantingFeature('marketplaceSelling')
+                } : {}),
+                profile: profile.exists ? profile.data() : null,
+                pages,
+                sellsAsPlatform: (publisher == null ? void 0 : publisher.sellsAsPlatform) === true,
+                // The apps fix each step on a screen of their own.
+                marketplacePath: null,
+                pagesPath: null
+            },
+            builtin: siteStarterBuiltinThemeOf(host)
+        });
+        return res.status(200).json(answer);
+    } catch (error) {
+        console.error(error);
+        return res.status(500).json({
+            error: 'Could not read this site'
+        });
+    }
+};
+export default starterPublishFactsHandler;
+
+//# sourceMappingURL=starter-publish-facts.js.map