@aglyn/plugins-marketplace 1.0.0-beta.143

package/src/lib/model/marketplace.d.ts

@@ -0,0 +1,833 @@
+/**
+ * @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 { MarketplaceArtifactType } from '@aglyn/aglyn/app-utils/marketplace-provenance';
+import type { ListingVerificationRequest } from '@aglyn/aglyn/app-utils/marketplace-verification';
+import { type PluginRevocation } from '@aglyn/aglyn/app-utils/plugin-manifest';
+import { isListingBrowsable, isListingDeleted, isPrivateListing, LISTING_CLIENT_WRITABLE_FIELDS, LISTING_UNPERSISTED_FIELDS, listingArtifactType } from '@aglyn/aglyn/app-utils/marketplace-listing-visibility';
+export { isListingBrowsable, isListingDeleted, isPrivateListing, LISTING_CLIENT_WRITABLE_FIELDS, LISTING_UNPERSISTED_FIELDS, listingArtifactType, };
+/**
+ * `profiles/{uid}` — a person's public identity.
+ *
+ * NOT a publisher identity as of AGL-652: publishing is org-only, and the
+ * marketplace presence lives on `publisherProfiles/{orgId}` below. This doc
+ * survives because it is also the support forum's author identity, which
+ * renders poster names from `displayName`.
+ */
+export interface MarketplaceProfile {
+    handle: string;
+    displayName: string;
+    bio?: string;
+    avatarUrl?: string;
+}
+/**
+ * `publisherProfiles/{orgId}` — an organization's marketplace presence
+ * (AGL-652). Publishing is org-only: an org publishes, an org gets paid, and
+ * the org is who buyers see. Keyed by org id so authorization is a plain org
+ * role check with no ownership indirection.
+ *
+ * `stripeAccountId` / `stripeChargesEnabled` / `stripeAccountLivemode` are
+ * written only by the Connect route via the Admin SDK and are frozen from
+ * client writes by the rules — they decide who receives money, and
+ * `stripeAccountLivemode` is a gate INPUT (AGL-2471), so a client that could
+ * write it could re-open the hole by asserting its own readiness.
+ */
+export interface MarketplacePublisherProfile {
+    /** Unique marketplace handle; reserved in `publisherHandles/{handle}`. */
+    handle: string;
+    displayName: string;
+    bio?: string;
+    avatarUrl?: string;
+    website?: string;
+    /** Server-only. */
+    stripeAccountId?: string;
+    /** Server-only; true once Connect onboarding can accept charges. */
+    stripeChargesEnabled?: boolean;
+    /**
+     * Server-only; which Stripe world the account belongs to (AGL-2471).
+     * `true` = live, `false` = test, ABSENT = never established — and on a live
+     * deployment absent refuses the sale, because a payout destination whose
+     * mode nobody verified is exactly what shipped three unusable storefronts.
+     */
+    stripeAccountLivemode?: boolean;
+}
+/**
+ * `publisherHandles/{handle}` — uniqueness reservation for publisher handles,
+ * mirroring `orgSlugs` (AGL-652). Without it two publishers could claim the
+ * same handle, which the marketplace URL space cannot represent. `movedTo`
+ * tombstones a renamed handle so old links can still resolve.
+ */
+export interface PublisherHandleReservation {
+    orgId: string;
+    movedTo?: string;
+}
+/**
+ * Publisher handles share the org-slug shape: 3–30 chars, lowercase
+ * alphanumeric plus internal hyphens. Single source of truth — the two
+ * marketplace pages historically applied two subtly different regexes to the
+ * same field (AGL-653).
+ */
+export declare const PUBLISHER_HANDLE_PATTERN: RegExp;
+export declare function isValidPublisherHandle(handle: string): boolean;
+/**
+ * `marketplaceListings/{listingId}` — public component listing. Version
+ * snapshots live in the `versions/{n}` subcollection; installs copy a pinned
+ * version into `hosts/{hostId}/components` so the existing drawer/graft
+ * pipeline applies unchanged.
+ */
+export interface MarketplaceListing {
+    profileId: string;
+    displayName: string;
+    description?: string;
+    category?: string;
+    /**
+     * What this listing publishes (AGL-654). One discriminator for every
+     * artifact type — the previous scheme split across two orthogonal fields
+     * (`type: 'component'|'plugin'` plus a separate `kind: 'template'`), so a
+     * template was "kind template with no type" and each installer branched on
+     * whichever field it happened to care about. That does not survive adding
+     * layouts, dataset schemas and email templates.
+     *
+     * Read it through `listingArtifactType()`, never directly — listings
+     * written before this field still carry only the legacy pair.
+     */
+    artifactType?: MarketplaceArtifactType;
+    /** @deprecated Legacy discriminator; use `artifactType` (AGL-654). */
+    type?: 'component' | 'plugin';
+    /** @deprecated Legacy discriminator; use `artifactType` (AGL-654). */
+    kind?: 'template';
+    latestVersion: number | string;
+    /** Plugin manifest id, for `type: 'plugin'` listings (AGL-45). */
+    pluginId?: string;
+    /** One-time price in whole USD; 0/absent = free (AGL-46). */
+    priceUsd?: number;
+    deletedAt?: unknown;
+    logoUrl?: string;
+    screenshots?: string[];
+    /** Markdown documentation shown on the listing page (no raw HTML). */
+    readme?: string;
+    homepageUrl?: string;
+    repositoryUrl?: string;
+    /** SPDX-ish license label, e.g. "MIT". */
+    license?: string;
+    categories?: string[];
+    /**
+     * Marketplace review lifecycle (AGL-432). Absent = legacy listing,
+     * treated as 'listed'. New plugin listings start 'submitted'; staff move
+     * them through the queue. Only 'listed'/'verified' (or legacy) plugin
+     * listings appear in browse for non-owners.
+     */
+    reviewStatus?: ListingReviewStatus;
+    /**
+     * The publisher's standing ask for the Verified badge (AGL-1217).
+     *
+     * Its own field, never a `reviewStatus` member — see
+     * {@link ListingVerificationRequest}. Server-owned: the publisher route only
+     * moves it to `pending`/`withdrawn`, and only staff can decide it. Asking
+     * never grants anything; the checklist gate on `verify` stays the one route
+     * to the badge.
+     */
+    verificationRequest?: ListingVerificationRequest;
+    /** Publishing org id — the publisher profile's doc id (AGL-652). */
+    publisherOrgId?: string;
+    /** Source component for a `component` listing. */
+    sourceComponentId?: string;
+    /** Source site for a `template` listing. */
+    sourceHostId?: string;
+    /** Incremented by the install API; frozen from client writes. */
+    installCount?: number;
+    /**
+     * How many installs are LIVE right now — `installCount`'s sibling, and
+     * undeclared here until AGL-1420 went looking for it.
+     *
+     * That omission was the whole bug. AGL-1361's coverage guard builds the
+     * listing's field universe from this interface, the rules deny-list and the
+     * resolvers, so a server-owned field in none of the three is not classified
+     * as exposed — it is INVISIBLE to the guard, which is a worse failure than
+     * being classified wrongly. `installCount` was denied and this was not, so
+     * the sibling counter a publisher-org owner/admin could write was the one
+     * the browse grid and the listing header print to buyers.
+     *
+     * Written by the install/uninstall routes and by AGL-1419's derivation.
+     */
+    activeInstalls?: number;
+    /**
+     * AGL-1419's derived-count cache: the pin count as last verified, the wall
+     * clock it was verified at, and the per-version split.
+     *
+     * Server-owned for a stronger reason than the counters themselves. They are
+     * not merely a number that could be wrong — `verifiedLivePins` treats the
+     * triple as FRESH when `pinnedActiveInstalls === activeInstalls` and the
+     * timestamp is inside the TTL, and then returns `pinnedVersionInstalls`
+     * without querying anything. A client that could write all four could pin
+     * the cache open on numbers it chose and suppress the re-derivation that
+     * exists to bring a count back down.
+     */
+    pinnedActiveInstalls?: number;
+    pinsVerifiedAtMs?: number;
+    pinnedVersionInstalls?: Record<string, number>;
+    previewImageUrl?: string;
+    screenCount?: number;
+    versionHistory?: Array<{
+        version: number | string;
+        publishedAt?: unknown;
+    }>;
+    createdAt?: unknown;
+    updatedAt?: unknown;
+    /** Staff review audit (AGL-432); server-owned (AGL-651). */
+    reviewedBy?: string;
+    reviewedAt?: unknown;
+    rejectionReason?: string;
+}
+/**
+ * Everything an org can publish to the marketplace (AGL-654).
+ *
+ * Defined in core and re-exported here (AGL-1016): the console needs it to
+ * render update state for installed artifacts, and an app may not depend on an
+ * addon lib. Publishing code keeps importing it from this model unchanged.
+ */
+export type { MarketplaceArtifactType };
+/**
+ * Human-readable label for each artifact type (AGL-864).
+ *
+ * Shared by browse cards, the listing detail page, and the seller panel so
+ * "what kind of thing is this" reads the same everywhere. Resolve a listing's
+ * label through {@link listingArtifactLabel}, which tolerates the legacy
+ * `type`/`kind` shape the way {@link listingArtifactType} does.
+ */
+export declare const ARTIFACT_TYPE_LABELS: Record<MarketplaceArtifactType, string>;
+/** The friendly artifact-type label for a listing (AGL-864). */
+export declare function listingArtifactLabel(listing: {
+    artifactType?: string;
+    type?: string;
+    kind?: string;
+}): string;
+/** Where an installed artifact lives. */
+export type InstallTarget = 'org' | 'host';
+/**
+ * Install targets each artifact type actually supports (AGL-656).
+ *
+ * This is not a policy choice — it is where the install routes physically
+ * write. Only plugins have an org-scoped pin
+ * (`orgs/{orgId}/installs/{listingId}`, applying to every site, shadowed by
+ * a host pin). Components land in `hosts/{h}/components`, templates and
+ * layouts in `hosts/{h}/templates`: all host-scoped by nature, because a
+ * screen tree belongs to a site.
+ *
+ * Exported so the UI can ask rather than assume — an install picker that
+ * offers "this whole organization" for a template would be lying.
+ */
+export declare const INSTALL_TARGETS: Record<MarketplaceArtifactType, readonly InstallTarget[]>;
+/** Targets a listing can be installed to, defaulting to host-only. */
+export declare function installTargetsFor(listing: {
+    artifactType?: string;
+    type?: string;
+    kind?: string;
+}): readonly InstallTarget[];
+/** A plugin install pin — the version-pinned doc the install API writes. */
+export interface InstallPin {
+    version?: number | string;
+}
+/**
+ * The install state of a plugin listing for one site, told honestly (AGL-656).
+ *
+ * A plugin can be pinned at two scopes: the org pin
+ * (`orgs/{orgId}/installs/{listingId}`) applies to every site, and a host pin
+ * (`hosts/{hostId}/installs/{listingId}`) applies to just this one AND shadows
+ * the org pin. Detecting installs from `hosts/{h}/components` — the COMPONENT
+ * collection — never sees either pin, so an installed plugin used to read as
+ * "not installed" on both the browse grid and the detail page. This resolves
+ * the effective state from the two pins the way the loader does.
+ */
+export interface PluginInstallState {
+    /** Effective pin scope for this site — host wins over org — or null. */
+    scope: InstallTarget | null;
+    /** Version pinned at the effective scope, or null when not installed. */
+    installedVersion: string | null;
+    /** Both pins exist: the host pin takes precedence, shadowing the org one. */
+    shadowed: boolean;
+    /** Installed, but the pinned version is behind the listing's latest. */
+    updateAvailable: boolean;
+}
+/**
+ * Resolves a plugin listing's install state for a site from its two pins
+ * (AGL-656). The host pin shadows the org pin, mirroring the loader, so the
+ * effective version and update prompt always describe what actually runs here.
+ */
+export declare function resolvePluginInstallState(latestVersion: number | string | undefined, hostPin: InstallPin | null | undefined, orgPin: InstallPin | null | undefined): PluginInstallState;
+/** One site's slice of an org-scope install picture (AGL-997). */
+export interface OrgInstallSite {
+    hostId: string;
+    label: string;
+    /** The version that actually runs here, from the effective pin. */
+    version: string | null;
+    /** Where that pin lives — a host pin shadows the org one, as the loader does. */
+    pinnedBy: InstallTarget;
+    /** This site has its OWN pin on top of an org pin. */
+    shadowed: boolean;
+}
+/**
+ * The whole org's install picture for one listing (AGL-997).
+ *
+ * At org scope, "installed" is a SET, not a boolean. The detail page used to
+ * resolve state against the single acting host, so a plugin installed on one
+ * of five sites reported "Installed on this site" — describing one arbitrary
+ * site and staying silent about the other four — and offered an Uninstall
+ * that was all-or-nothing.
+ *
+ * `orgWide` and per-site pins are not exclusive: an org pin covers every
+ * site including ones created later, and a host pin on top of it shadows it
+ * for that one site. Both facts have to survive into the UI, which is why
+ * this returns the sites AND the pins rather than a single scope.
+ */
+export interface OrgInstallSummary {
+    /** An org pin exists: every site is covered, including future ones. */
+    orgWide: boolean;
+    /** Version of the org pin, when there is one. */
+    orgVersion: string | null;
+    /** Every site the listing effectively runs on. */
+    sites: OrgInstallSite[];
+    /** Sites carrying their own removable host pin. */
+    hostPinnedIds: string[];
+    /** Sites with no pin of their own and no org pin covering them. */
+    availableHostIds: string[];
+    installedAnywhere: boolean;
+}
+export declare function resolveOrgInstallSummary(hosts: ReadonlyArray<{
+    id: string;
+    label: string;
+}>, hostPins: Readonly<Record<string, InstallPin | null | undefined>>, orgPin: InstallPin | null | undefined): OrgInstallSummary;
+/** One site an uninstall would touch, and whether it really loses the plugin. */
+export interface UninstallTarget {
+    hostId: string;
+    label: string;
+    /**
+     * The plugin keeps running here. Removing a HOST pin while an org pin still
+     * covers the site, or the ORG pin while the site holds its own host pin,
+     * changes which pointer is in use and nothing a visitor can see.
+     */
+    stillCovered: boolean;
+}
+/**
+ * Which sites an uninstall actually affects (AGL-1027).
+ *
+ * The shadowing case is the whole reason this is a function rather than a
+ * filter at the call site. A pin is not a boolean per site: an org pin covers
+ * everything, a host pin names one site, and where both exist the host pin
+ * wins. So "remove" means three different things depending on which pointer is
+ * being dropped and what is left underneath — and the one thing the dialog must
+ * never do is tell someone a plugin will stop working when it will not.
+ *
+ * Returns every site the operation touches, including the ones that keep the
+ * plugin, so the dialog can say so explicitly instead of omitting them and
+ * leaving the count unexplained.
+ */
+export declare function resolveUninstallTargets(orgInstall: OrgInstallSummary, scope: 'org' | 'host', hostId?: string): UninstallTarget[];
+/** How the admin chose to target an install from the org marketplace. */
+export type InstallTargeting = 'all-sites' | 'selected-sites';
+/** One concrete install operation: an org pin, or a pin on a named host. */
+export interface InstallPlanStep {
+    scope: InstallTarget;
+    /** Present iff `scope === 'host'`. */
+    hostId?: string;
+}
+/**
+ * Turns a targeting choice into the concrete install operations for a listing
+ * (AGL-773), honoring what each artifact type physically supports (see
+ * {@link INSTALL_TARGETS}).
+ *
+ * The rules aren't uniform, and the picker must not promise what an artifact
+ * can't do:
+ * - **Org-pinnable** (plugin, datasetSchema) + "all sites" → a SINGLE org pin,
+ *   which also covers sites created later.
+ * - **Host-scoped** (component, template, layout, emailTemplate) has no org
+ *   pin, so "all sites" fans out to every CURRENT host — new sites are NOT
+ *   covered automatically. The UI has to say so.
+ * - "Selected sites" is always host pins, even for an org-pinnable artifact:
+ *   the admin named specific sites, so honor that literally — UNLESS the
+ *   artifact can't host-pin at all (datasetSchema), where the per-site choice
+ *   is meaningless and collapses to the org pin.
+ */
+export declare function resolveInstallPlan(listing: {
+    artifactType?: string;
+    type?: string;
+    kind?: string;
+}, targeting: InstallTargeting, hosts: {
+    selectedHostIds: readonly string[];
+    allHostIds: readonly string[];
+}): InstallPlanStep[];
+export type ListingReviewStatus = 'submitted' | 'in_review' | 'listed' | 'verified' | 'rejected';
+/**
+ * Verification requests live in core (AGL-1217), for the same reason
+ * `MarketplaceArtifactType` does (AGL-1016): the console's staff review route
+ * needs the policy, and `scope:app` may not depend on `aglyn:addons`.
+ * Re-exported here so publishing code keeps one import site.
+ */
+export { VERIFICATION_BLOCK_MESSAGES, VERIFICATION_DECLINE_COOLDOWN_DAYS, timestampMs, verificationRequestBlock, } from '@aglyn/aglyn/app-utils/marketplace-verification';
+export type { ListingVerificationRequest, TimestampLike, VerifiableListing, VerificationRequestBlock, VerificationRequestState, } from '@aglyn/aglyn/app-utils/marketplace-verification';
+/**
+ * Per-VERSION review state (AGL-966).
+ *
+ * Approval is a statement about specific bytes, so it lives on the version
+ * doc beside the verifier verdict and the review checklist — both already
+ * keyed to sha256. It used to live on the listing, which meant a publisher
+ * could get v1.0.0 verified and then ship v1.0.1 containing anything: the
+ * listing kept its status, the queue never surfaced the update, and
+ * installs resolved `latestVersion`.
+ */
+export type PluginVersionReviewState = 'pending' | 'approved' | 'rejected';
+/**
+ * The LISTING's cached summary of the version it currently offers.
+ *
+ * A different field from the one above and a different set of values, which is
+ * the whole reason it is written down here. `reviewState` lives on the version
+ * document and is a verdict about specific bytes;
+ * `latestVersionReviewState` lives on the LISTING and exists so browse cards
+ * and the listing page can answer "have the bytes on offer been read?" without
+ * a per-listing subcollection read.
+ *
+ * `'revoked'` is the value that only ever appears HERE. A kill is not a review
+ * verdict: the version keeps the `'approved'` it earned — the staff surface
+ * shows "Disabled" beside that verdict rather than instead of it, because
+ * collapsing the two would erase what the publisher earned — and it is only
+ * this listing-level summary that flips, so the "Reviewed" chip drops and the
+ * caution alert raises while the audit trail stays intact.
+ *
+ * The practical consequence, and the reason this is a type rather than a
+ * comment: the staff review QUEUE keys on the version's `reviewState`, never
+ * on this field. Were it to key on this one, every revoked version would
+ * reappear in the queue indistinguishable from one awaiting its first review,
+ * and a reviewer acting in good faith on a queue they trusted could approve a
+ * version somebody had deliberately killed. The two fields are not
+ * interchangeable and this names why.
+ */
+export type ListingLatestVersionReviewState = PluginVersionReviewState | 'revoked';
+export interface ReviewableVersion {
+    version?: string;
+    reviewState?: string;
+    publishedAt?: {
+        toMillis?: () => number;
+    } | null;
+}
+/** Only approved bytes may be installed. Absent state is NOT approval. */
+export declare function isVersionApproved(version: {
+    reviewState?: string;
+} | null | undefined): boolean;
+/**
+ * Whether an install would hand the viewer UNREVIEWED bytes (AGL-1083).
+ *
+ * `install-plugin` deliberately lets a publisher install their own
+ * unapproved version — you cannot test a version you cannot install, and
+ * the AGL-969 checklist asks them to confirm they tested these exact bytes
+ * on a site they control. The route reaches that case through
+ * `newestApprovedVersion(...) ?? fallback`, where the fallback is
+ * `latestVersion` and applies ONLY when the caller owns the listing and no
+ * approved version exists at all.
+ *
+ * Lives here rather than in the listing component because the UI has to
+ * describe exactly what the route will do. Two independent readings of
+ * "would this be unreviewed?" is how the affordance ends up warning about
+ * the wrong installs, or staying silent on the right ones.
+ *
+ * The route's `newest` is `newestInstallableVersion` since AGL-2368 — a
+ * revoked version is no longer a candidate, so it no longer suppresses the
+ * fallback either. `revocation` is optional because most callers have none;
+ * without it this asks the pre-AGL-2368 question, which is the same answer
+ * whenever the mirror is current.
+ */
+export declare function installsUnreviewedFallback(listing: {
+    profileId?: string;
+    latestVersion?: string | number;
+    latestApprovedVersion?: string | number;
+} | null | undefined, viewerOrgId: string | null | undefined, revocation?: PluginRevocation | null): boolean;
+/**
+ * The version a fresh install should pin: newest APPROVED, never
+ * `latestVersion`. A pending update is simply not offered, so publishing
+ * cannot ship code past review, and the previously approved version keeps
+ * installing while the new one waits.
+ */
+export declare function newestApprovedVersion<T extends ReviewableVersion>(versions: readonly T[]): T | null;
+/**
+ * What a listing is still missing before it can face the marketplace
+ * (AGL-968/994).
+ *
+ * A private plugin is allowed to be undocumented — its only audience already
+ * knows what it is and why it exists. A public one is not: description,
+ * README and license are what a stranger deciding whether to run your code
+ * has to go on, and they are exactly the fields the review checklist asks
+ * about. So going public is gated on the METADATA, never on a re-review —
+ * approval is a statement about bytes, and the bytes did not change.
+ *
+ * Returns the human field names, so the caller can say what to fix rather
+ * than just refusing.
+ */
+export declare function missingPublicListingContent(listing: {
+    description?: string;
+    readme?: string;
+    license?: string;
+}): string[];
+/** Fixed category taxonomy for marketplace listings (AGL-430). */
+export declare const LISTING_CATEGORIES: readonly string[];
+export declare const LISTING_README_MAX_CHARS = 20000;
+export declare const LISTING_MAX_SCREENSHOTS = 6;
+/**
+ * The message every listing IMAGE field returns when it is refused. Names the
+ * remedy, because "must be an https URL" was true of the value the publisher
+ * just typed and told them nothing.
+ */
+export declare const LISTING_IMAGE_ERROR: string;
+/**
+ * Validates publisher-editable listing content (AGL-430). Returns the
+ * normalized subset to persist, or an error. Shared by publish and the
+ * update-listing action so both paths accept exactly the same shapes.
+ *
+ * IMAGE fields and LINK fields are validated differently (AGL-1701).
+ * `homepageUrl` and `repositoryUrl` stay any-https: they are anchors a reader
+ * chooses to follow, and a publisher's homepage living on the publisher's
+ * domain is the entire point of the field. `logoUrl` and `screenshots` are
+ * `<img src>`, which fetches with no such choice, so those are held to
+ * first-party media.
+ */
+export declare function validateListingContent(input: Record<string, unknown>): {
+    ok: boolean;
+    error?: string;
+    content?: Partial<MarketplaceListing>;
+};
+/**
+ * Publisher-profile fields beyond the identity trio (AGL-1009): the logo,
+ * the support contact, and a FIXED set of external links. Fixed on purpose —
+ * the storefront renders each as a known icon, and a free-form list would
+ * turn the trust panel into a link farm.
+ */
+export interface PublisherProfileContent {
+    avatarUrl?: string;
+    website?: string;
+    supportEmail?: string;
+    supportUrl?: string;
+    githubUrl?: string;
+    xUrl?: string;
+    linkedinUrl?: string;
+}
+/**
+ * Validates the publisher-profile extras (AGL-1009), sharing
+ * `validateListingContent`'s URL discipline: https only, length capped,
+ * validated on the save route (server-owned like the handle — no client
+ * write path carries these). An explicit empty string comes back as `''` so
+ * the save route can distinguish "clear this field" from "left untouched".
+ */
+export declare function validatePublisherProfileContent(input: Record<string, unknown>): {
+    ok: boolean;
+    error?: string;
+    content?: PublisherProfileContent;
+};
+/**
+ * Render-time guard for publisher links (AGL-1009): only an `https://` URL
+ * is ever emitted as an href. The save route already refuses anything else,
+ * but the doc is client-updatable on its cosmetic fields historically, so
+ * the renderer must not trust stored data it did not write.
+ */
+export declare function safePublisherHref(url: unknown): string | undefined;
+/**
+ * Platform revenue share on paid listings (AGL-46) — UI COPY ONLY. The
+ * checkout route prices from the `marketplaceFeePct` ENTITLEMENT
+ * (`resolveMarketplaceFeePct`, AGL-1543), which resolves the effective
+ * plan and per-org overrides; these constants exist for seller-facing
+ * copy and must be kept in step with the plan table.
+ */
+export declare const MARKETPLACE_PLATFORM_FEE_PERCENT = 20;
+/** Free-plan publishers pay a higher share. See AGL-1543 note above. */
+export declare const MARKETPLACE_PLATFORM_FEE_PERCENT_FREE_PLAN = 30;
+/** One-time listing price ceiling (whole USD). */
+export declare const MARKETPLACE_MAX_PRICE_USD = 1000;
+/**
+ * One-time listing price FLOOR for a PAID listing (whole USD, AGL-2343).
+ *
+ * Marketplace checkout is a destination charge with no `application_fee_amount`
+ * — deliberately, so the sales tax stays with the platform that owes it
+ * (AGL-1544) — which means Stripe debits its fee from the PLATFORM's balance.
+ * Stripe's fixed 30¢ dominates at low prices, so under this figure the
+ * platform's cut is smaller than the cost of collecting it and every sale is a
+ * loss. The floor is the cheapest listing price that still clears the cost of
+ * processing it.
+ *
+ * NOT A CHOSEN NUMBER. `marketplaceMinPriceUsd` derives it from the plan
+ * table's lowest take rate and the dearest enabled payment method; this is a
+ * re-export so that the routes and the console forms cannot quote different
+ * minimums at the same publisher. Zero stays legal — a free listing takes no
+ * payment and costs nothing to process.
+ */
+export declare const MARKETPLACE_MIN_PRICE_USD: number;
+/**
+ * The refusal message for a listing price, or `undefined` when the price may
+ * be published (AGL-2343).
+ *
+ * ONE VALIDATOR FOR SEVEN DOORS. Each publish route used to inline its own
+ * range check against the maximum — and `publish-theme.ts` and
+ * `publish-layout.ts` had none at all, so a $250,000 theme was publishable.
+ * The doors call this, and `publishPreconditionRefusal` calls it too, so a
+ * route that forgets is still covered.
+ *
+ * Takes the price the route already rounded: a listing price is whole dollars
+ * everywhere, and a validator that accepted $2.99 would be validating a number
+ * that is never stored.
+ */
+export declare function marketplacePriceRefusal(priceUsd: number): string | undefined;
+/**
+ * The allowlists and the sanitizer live in core since AGL-2939 — see
+ * `@aglyn/aglyn/app-utils/node-definition-sanitizer` — and keep their
+ * marketplace names here for the publishers that import them.
+ */
+import { MARKETPLACE_COMPONENT_ID_ALLOWLIST, MARKETPLACE_EMAIL_COMPONENT_ID_ALLOWLIST, MARKETPLACE_EMAIL_STARTER_COMPONENT_ID_ALLOWLIST, MARKETPLACE_DEFINITION_MAX_BYTES, sanitizeMarketplaceDefinition, marketplaceDefinitionToNested, MARKETPLACE_DATASET_FIELD_TYPES } from '@aglyn/aglyn/app-utils/node-definition-sanitizer';
+export { MARKETPLACE_COMPONENT_ID_ALLOWLIST, MARKETPLACE_EMAIL_COMPONENT_ID_ALLOWLIST, MARKETPLACE_EMAIL_STARTER_COMPONENT_ID_ALLOWLIST, MARKETPLACE_DEFINITION_MAX_BYTES, sanitizeMarketplaceDefinition, marketplaceDefinitionToNested, MARKETPLACE_DATASET_FIELD_TYPES, };
+export { MARKETPLACE_SAFE_HREF, MARKETPLACE_SAFE_SRC, } from '@aglyn/aglyn/app-utils/node-definition-sanitizer';
+export type { MarketplaceDefinitionNodes, } from '@aglyn/aglyn/app-utils/node-definition-sanitizer';
+/** Field cap on a published schema — mirrors the console's create limit. */
+export declare const MARKETPLACE_DATASET_MAX_FIELDS = 100;
+/** A published dataset schema: the model, with no records. */
+export interface MarketplaceDatasetSchema {
+    fields: Record<string, MarketplaceDatasetField>;
+    order: string[];
+}
+export interface MarketplaceDatasetField {
+    name: string;
+    type: string;
+    customType?: string;
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+    validation?: Record<string, unknown>;
+    /**
+     * Kept so an install into an org that HAS the referenced dataset can relink
+     * it. `datasetId` is the publisher's id and is meaningless in another org,
+     * so `datasetLabel` carries the human name the installer matches on.
+     */
+    reference?: {
+        datasetId?: string;
+        datasetLabel?: string;
+        displayFieldId?: string;
+        multiple?: boolean;
+        onDelete?: string;
+    };
+}
+/**
+ * Validates and strips a `DatasetModel` for publishing as a marketplace
+ * dataset schema (AGL-657).
+ *
+ * Publishes STRUCTURE ONLY — records never travel. That is the whole safety
+ * story for this artifact type: a dataset's rows are the org's customer data,
+ * so the publish path reads the model and nothing else, and there is no code
+ * path here that can reach the `records` subcollection.
+ *
+ * Two cross-org hazards the issue called out, handled by carrying enough
+ * context for the INSTALLER to decide rather than by rejecting at publish:
+ * - `reference` FKs point at a dataset id that only exists in the publisher's
+ *   org. The id is kept alongside the referenced dataset's label so the
+ *   installer can relink by name and degrade the field when it can't (see
+ *   `resolveInstalledDatasetSchema`).
+ * - `customType` names a plugin-declared field type (AGL-434) whose plugin the
+ *   installing org may not have. Unknown custom types already degrade to their
+ *   base type at render, so the name rides along untouched.
+ */
+export declare function sanitizeDatasetSchema(model: {
+    fields?: Record<string, any>;
+    order?: unknown;
+}): {
+    ok: true;
+    schema: MarketplaceDatasetSchema;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Rewrites a published schema for the installing org (AGL-657).
+ *
+ * `reference` fields are the only part of a schema that can't cross an org
+ * boundary as-is: they name a dataset id in the PUBLISHER's org. Relink by the
+ * referenced dataset's label when the installing org has one by that name;
+ * otherwise degrade the field to plain `text` and report it, because a
+ * reference field pointing at a dataset that doesn't exist renders as a broken
+ * picker — silently keeping the dead id would install something visibly
+ * broken and blame the installer for it.
+ *
+ * `existingDatasets` maps lowercased display name → dataset id in the target.
+ */
+export declare function resolveInstalledDatasetSchema(schema: MarketplaceDatasetSchema, existingDatasets: Readonly<Record<string, string>>): {
+    schema: MarketplaceDatasetSchema;
+    degradedFieldIds: string[];
+};
+/** One row of the listing detail's `What's included` checklist. */
+export interface ListingInclusion {
+    label: string;
+    /** Whether the row is a positive inclusion or a stated limit. */
+    tone: 'included' | 'note';
+}
+/**
+ * The `WHAT'S INCLUDED` checklist the marketplace listing mockup shows
+ * (AGL-2173), derived entirely from facts the listing already carries.
+ *
+ * The mockup's own bullets — `12 responsive screens`, `Blog & work
+ * layouts` — are publisher-authored prose, and nothing collects them:
+ * there is no content manifest on a listing or a version, so counting
+ * screens would mean inventing a number. What IS knowable is what the
+ * install physically does, where it lands, whether it has been reviewed,
+ * and under what licence — which is the question a shopper is asking when
+ * they read that box.
+ *
+ * Ordered decision-first: what you get, then where it goes, then the two
+ * facts that most often stop an install.
+ */
+export declare function listingInclusions(listing: {
+    artifactType?: string;
+    type?: string;
+    kind?: string;
+    license?: string;
+    priceUsd?: number;
+    reviewStatus?: string;
+}, options?: {
+    reviewedVersion?: boolean;
+}): ListingInclusion[];
+/**
+ * WHO STILL OWNS WHAT THEY BOUGHT — the one predicate (AGL-2158).
+ *
+ * `hasLivePurchase` (server/purchase-entitlement.ts) is the gate on all eight
+ * ways into paid content, and it reads exactly one field: a purchase with
+ * `refundedAt` — stamped by the `charge.refunded` and lost-`charge.dispute`
+ * doors of the marketplace billing webhook — no longer entitles.
+ *
+ * The listing page carried its OWN copy of that question,
+ * `some(p => p.listingId === listingId)`, with no refund test at all. The two
+ * then disagreed on the one buyer they must not disagree on: the refunded
+ * one. The page showed "Purchased", hid the buy button, and the install
+ * routes answered 402 — a buyer who could neither install nor re-purchase.
+ *
+ * It lives HERE, in the model, rather than in the server module, because the
+ * server module is the wrong side of the client/server boundary for a React
+ * component and copying four characters of predicate is precisely how the two
+ * came apart. This module is context-free by construction (see the header) —
+ * importable from a client component, an API route and another plugin alike.
+ */
+export interface PurchaseLiveness {
+    /** Stamped when a full refund or a lost dispute un-buys the listing. */
+    refundedAt?: unknown;
+    listingId?: unknown;
+    /**
+     * THE ORGANIZATION THE LICENCE BELONGS TO (AGL-2331).
+     *
+     * Absent on every purchase written before AGL-2331 — see
+     * `purchaseEntitlesOrg` for what that absence means and why it is never
+     * treated as "no licence".
+     */
+    buyerOrgId?: unknown;
+    /** The person who paid. Kept for the receipt trail and the legacy grant. */
+    buyerUid?: unknown;
+}
+/**
+ * True when this purchase document still entitles.
+ *
+ * Deliberately a truthiness test and not `!= null`: `refundedAt` is a
+ * Firestore Timestamp on the server, a client Timestamp in the browser and a
+ * sentinel in the webhook's own tests, and every one of those is truthy while
+ * a missing field (every purchase written before AGL-1546) is not.
+ */
+export declare function isLivePurchase(purchase: PurchaseLiveness | null | undefined): boolean;
+/**
+ * True when this buyer's purchase documents include a live one for `listingId`.
+ *
+ * Both callers pass everything they read — the server's query is already
+ * narrowed to the listing, the client's is narrowed only to the buyer — so the
+ * listing filter belongs inside the shared predicate too, not beside it.
+ */
+export declare function hasLivePurchaseOf(purchases: readonly (PurchaseLiveness | null | undefined)[] | null | undefined, listingId: string): boolean;
+/**
+ * WHO A PURCHASE LICENSES (AGL-2331).
+ *
+ * ## The model
+ *
+ * **A marketplace purchase licenses an ORGANIZATION, not a person.** That is
+ * not a new decision — it is the one already published. The Marketplace
+ * Publisher Agreement §8.1 says a paid Artifact is licensed "to the installing
+ * organization", and §2 grants the right to sublicense "to organizations that
+ * install it". Until now the code enforced a per-PERSON licence instead, and
+ * the mismatch cut both ways: an agency developer who is an owner across five
+ * client workspaces bought once and installed into all five, and — because the
+ * duplicate-purchase guard shares this predicate — could not buy a second
+ * licence even when they wanted to. Conforming the code to the published terms
+ * is the smaller of the two changes; the alternative amends a version-pinned
+ * legal document and stops every publisher until they re-accept it.
+ *
+ * Three consequences follow, and all three are the point:
+ *
+ * 1. A licence held by org A does not install into org B. The agency buys per
+ *    client workspace, which is what the agreement says they are buying.
+ * 2. Buying a second licence is a real second sale, not a `409`.
+ * 3. Any member of the owning org with `installPlugins` may install what the
+ *    ORG bought — including colleagues who were not the buyer, and including
+ *    the buyer's replacement after they leave. A licence that evaporates when
+ *    one employee's account is deleted is not an organizational licence.
+ *
+ * ## The legacy grant, and why it never expires
+ *
+ * A purchase written before this change carries NO `buyerOrgId` — there was
+ * no buyer org anywhere in the pipeline to record. Those are real purchases by
+ * real customers, and reinterpreting one as "licensed to no organization"
+ * would revoke access somebody paid for. So a purchase with no `buyerOrgId` at
+ * all keeps its ORIGINAL, person-scoped meaning, forever: it entitles the uid
+ * that bought it, in every org that uid can install into. Nothing is
+ * migrated, nothing is claimed by the first org to use it, and nothing is
+ * revoked — the ambiguity resolves in the customer's favour by construction,
+ * with no backfill to get right and no window during which a paying customer
+ * is locked out.
+ *
+ * The grandfather is bounded by time rather than policed: it can only ever
+ * apply to purchases already written, because from AGL-2331 onward checkout
+ * refuses to open a session that does not name a validated buyer org. It is
+ * therefore a shrinking set that never grows, not a hole left open.
+ *
+ * `orgId` may be empty (a site with no owning org). That is not a licence to
+ * anything, so only the legacy uid grant can hold — never a `buyerOrgId ===
+ * ''` match, which is why the org branch tests for a non-empty string on the
+ * document itself rather than comparing the two values directly.
+ */
+export declare function purchaseEntitlesOrg(purchase: PurchaseLiveness | null | undefined, actor: {
+    orgId?: string | null;
+    uid?: string | null;
+}): boolean;
+/**
+ * True when these purchase documents include one that licenses `orgId` for
+ * `listingId` — the org-scoped counterpart of `hasLivePurchaseOf`.
+ *
+ * Same shape and same home as the liveness predicate, and for the same reason
+ * (AGL-2158): the install routes, the checkout duplicate guard and the listing
+ * page all have to answer "does this workspace hold a licence" identically, and
+ * the way they came apart last time was four characters of predicate copied
+ * into a component.
+ */
+export declare function hasOrgLicenceOf(purchases: readonly (PurchaseLiveness | null | undefined)[] | null | undefined, listingId: string, actor: {
+    orgId?: string | null;
+    uid?: string | null;
+}): boolean;
+/**
+ * Every org id these purchases license for `listingId`, in document order.
+ *
+ * What the console renders so a buyer can see WHICH workspace a licence they
+ * paid for belongs to (AGL-2331) — the question that has no answer at all
+ * while entitlement is person-scoped, and the one an agency has to answer
+ * before deciding whether it needs another.
+ *
+ * Legacy person-scoped purchases contribute no org id, because they name
+ * none; a caller rendering this list has to say so rather than invent one.
+ */
+export declare function licensedOrgIdsFor(purchases: readonly (PurchaseLiveness | null | undefined)[] | null | undefined, listingId: string): string[];