@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/order-figures.js

@@ -0,0 +1,220 @@
+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 { PLUGIN_FIGURE_MAX_ROWS, pluginFigureChange, pluginFigureWindows, registerPluginFigureReader } from "@aglyn/aglyn/plugin-manager/plugin-figures";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { orderWindowFigures, productSales } from "../model/order-figures.js";
+/** Orders one window reads; a store past it is told its figures read low. */ export const ORDER_FIGURES_WINDOW_CEILING = 1000;
+const WINDOWS = [
+    7,
+    14,
+    30,
+    90
+];
+const SOURCE = {
+    label: 'Store analytics',
+    path: 'products/analytics'
+};
+async function ordersBetween(firestore, hostId, startMs, endMs) {
+    // `createdAtMs` is the field every order writer stamps and the one the
+    // orders group is indexed on; range and order on it need no composite index.
+    const snapshot = await firestore.collection('hosts').doc(hostId).collection('orders').where('createdAtMs', '>=', startMs).where('createdAtMs', '<', endMs).orderBy('createdAtMs', 'desc').limit(ORDER_FIGURES_WINDOW_CEILING + 1).get();
+    const orders = snapshot.docs.map((doc)=>{
+        var _doc_data;
+        return _extends({}, (_doc_data = doc.data()) != null ? _doc_data : {}, {
+            $id: doc.id
+        });
+    });
+    return {
+        orders: orders.slice(0, ORDER_FIGURES_WINDOW_CEILING),
+        truncated: orders.length > ORDER_FIGURES_WINDOW_CEILING
+    };
+}
+const dollars = (cents)=>Math.round(cents) / 100;
+function ceilingNote(truncated) {
+    return truncated ? [
+        `The store took more than ${ORDER_FIGURES_WINDOW_CEILING.toLocaleString('en-US')} orders in a window, so its figures are summed over the most recent ${ORDER_FIGURES_WINDOW_CEILING.toLocaleString('en-US')} and read low.`
+    ] : [];
+}
+function refusal(request) {
+    if (!request.hostId) return {
+        ok: false,
+        status: 400,
+        error: 'Open a site to read its sales'
+    };
+    if (!WINDOWS.includes(request.days)) {
+        return {
+            ok: false,
+            status: 400,
+            error: 'That window is not one sales are read over'
+        };
+    }
+    return null;
+}
+export function orderFigureReaders(firestore) {
+    return [
+        {
+            id: 'commerce.sales',
+            label: 'Sales',
+            description: 'The store’s revenue, orders and average order over the window and the window before it, with the change in revenue and in orders. Pending, canceled and test orders are left out, and refunds come off.',
+            scope: 'site',
+            windows: WINDOWS,
+            feature: 'commerceAnalytics',
+            read: async (request)=>{
+                const refused = refusal(request);
+                if (refused) return refused;
+                const hostId = request.hostId;
+                const { current, previous } = pluginFigureWindows(request.now, request.days);
+                const [now, before] = await Promise.all([
+                    ordersBetween(firestore(), hostId, current.startMs, current.endMs),
+                    ordersBetween(firestore(), hostId, previous.startMs, previous.endMs)
+                ]);
+                const a = orderWindowFigures(now.orders, current.startMs, current.endMs);
+                const b = orderWindowFigures(before.orders, previous.startMs, previous.endMs);
+                return {
+                    ok: true,
+                    table: {
+                        title: 'Sales',
+                        source: SOURCE,
+                        period: {
+                            from: current.from,
+                            to: current.to,
+                            days: request.days
+                        },
+                        columns: [
+                            {
+                                key: 'window',
+                                label: 'Window',
+                                kind: 'text'
+                            },
+                            {
+                                key: 'revenue',
+                                label: 'Revenue',
+                                kind: 'money',
+                                currency: 'USD'
+                            },
+                            {
+                                key: 'orders',
+                                label: 'Orders',
+                                kind: 'count'
+                            },
+                            {
+                                key: 'averageOrder',
+                                label: 'Average order',
+                                kind: 'money',
+                                currency: 'USD'
+                            },
+                            {
+                                key: 'revenueChange',
+                                label: 'Revenue change',
+                                kind: 'change'
+                            },
+                            {
+                                key: 'ordersChange',
+                                label: 'Orders change',
+                                kind: 'change'
+                            }
+                        ],
+                        rows: [
+                            {
+                                window: `${current.from} to ${current.to}`,
+                                revenue: dollars(a.revenueCents),
+                                orders: a.orders,
+                                averageOrder: dollars(a.averageCents),
+                                revenueChange: pluginFigureChange(a.revenueCents, b.revenueCents),
+                                ordersChange: pluginFigureChange(a.orders, b.orders)
+                            },
+                            {
+                                window: `${previous.from} to ${previous.to}`,
+                                revenue: dollars(b.revenueCents),
+                                orders: b.orders,
+                                averageOrder: dollars(b.averageCents),
+                                revenueChange: null,
+                                ordersChange: null
+                            }
+                        ],
+                        omitted: 0,
+                        notes: ceilingNote(now.truncated || before.truncated)
+                    }
+                };
+            }
+        },
+        {
+            id: 'commerce.products',
+            label: 'Top products',
+            description: 'The products that brought in the most over the window, with units sold and line revenue.',
+            scope: 'site',
+            windows: WINDOWS,
+            feature: 'commerceAnalytics',
+            read: async (request)=>{
+                const refused = refusal(request);
+                if (refused) return refused;
+                const { current } = pluginFigureWindows(request.now, request.days);
+                const window = await ordersBetween(firestore(), request.hostId, current.startMs, current.endMs);
+                const sales = productSales(window.orders);
+                return {
+                    ok: true,
+                    table: {
+                        title: 'Top products',
+                        source: SOURCE,
+                        period: {
+                            from: current.from,
+                            to: current.to,
+                            days: request.days
+                        },
+                        columns: [
+                            {
+                                key: 'product',
+                                label: 'Product',
+                                kind: 'text'
+                            },
+                            {
+                                key: 'units',
+                                label: 'Units',
+                                kind: 'count'
+                            },
+                            {
+                                key: 'revenue',
+                                label: 'Line revenue',
+                                kind: 'money',
+                                currency: 'USD'
+                            }
+                        ],
+                        rows: sales.slice(0, PLUGIN_FIGURE_MAX_ROWS).map((entry)=>({
+                                product: entry.name,
+                                units: entry.units,
+                                revenue: dollars(entry.cents)
+                            })),
+                        omitted: Math.max(0, sales.length - PLUGIN_FIGURE_MAX_ROWS),
+                        notes: [
+                            'Line revenue is each line’s price times its quantity, before discounts, shipping and tax.',
+                            ...ceilingNote(window.truncated)
+                        ]
+                    }
+                };
+            }
+        }
+    ];
+}
+/** Registers the sales readers from the console surface, where insight jobs run. */ export function registerOrderFigureReaders(firestore) {
+    for (const reader of orderFigureReaders(firestore)){
+        registerPluginFigureReader(reader, {
+            pluginId: BUNDLE_ID
+        });
+    }
+}
+
+//# sourceMappingURL=order-figures.js.map

package/src/lib/server/order-figures.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/order-figures.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 {\n  PLUGIN_FIGURE_MAX_ROWS,\n  pluginFigureChange,\n  pluginFigureWindows,\n  registerPluginFigureReader,\n  type PluginFigureReader,\n  type PluginFigureRequest,\n} from '@aglyn/aglyn/plugin-manager/plugin-figures'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport {\n  orderWindowFigures,\n  productSales,\n  type OrderFigureSource,\n} from '../model/order-figures'\n\n/**\n * The store's sales figures for another plugin to read (AGL-2915): what the\n * Analytics tab's card shows, as tables on the `plugin-figures` seam. The\n * insight job reads them by id and never reads an order.\n *\n * A table carries sums and counts and product names — never a buyer, an\n * address or an order. Sold under `commerceAnalytics`, the entitlement the\n * card is sold under.\n */\n\ntype Firestore = FirebaseFirestore.Firestore\n\n/** Orders one window reads; a store past it is told its figures read low. */\nexport const ORDER_FIGURES_WINDOW_CEILING = 1_000\n\nconst WINDOWS: readonly number[] = [7, 14, 30, 90]\n\nconst SOURCE = { label: 'Store analytics', path: 'products/analytics' }\n\nasync function ordersBetween(\n  firestore: Firestore,\n  hostId: string,\n  startMs: number,\n  endMs: number,\n): Promise<{ orders: OrderFigureSource[]; truncated: boolean }> {\n  // `createdAtMs` is the field every order writer stamps and the one the\n  // orders group is indexed on; range and order on it need no composite index.\n  const snapshot = await firestore\n    .collection('hosts')\n    .doc(hostId)\n    .collection('orders')\n    .where('createdAtMs', '>=', startMs)\n    .where('createdAtMs', '<', endMs)\n    .orderBy('createdAtMs', 'desc')\n    .limit(ORDER_FIGURES_WINDOW_CEILING + 1)\n    .get()\n  const orders = snapshot.docs.map((doc) => ({ ...(doc.data() ?? {}), $id: doc.id }) as OrderFigureSource)\n  return {\n    orders: orders.slice(0, ORDER_FIGURES_WINDOW_CEILING),\n    truncated: orders.length > ORDER_FIGURES_WINDOW_CEILING,\n  }\n}\n\nconst dollars = (cents: number): number => Math.round(cents) / 100\n\nfunction ceilingNote(truncated: boolean): string[] {\n  return truncated\n    ? [\n        `The store took more than ${ORDER_FIGURES_WINDOW_CEILING.toLocaleString('en-US')} orders in a window, so its figures are summed over the most recent ${ORDER_FIGURES_WINDOW_CEILING.toLocaleString('en-US')} and read low.`,\n      ]\n    : []\n}\n\nfunction refusal(request: PluginFigureRequest) {\n  if (!request.hostId) return { ok: false as const, status: 400 as const, error: 'Open a site to read its sales' }\n  if (!WINDOWS.includes(request.days)) {\n    return { ok: false as const, status: 400 as const, error: 'That window is not one sales are read over' }\n  }\n  return null\n}\n\nexport function orderFigureReaders(firestore: () => Firestore): PluginFigureReader[] {\n  return [\n    {\n      id: 'commerce.sales',\n      label: 'Sales',\n      description:\n        'The store’s revenue, orders and average order over the window and the window before it, with the change in revenue and in orders. Pending, canceled and test orders are left out, and refunds come off.',\n      scope: 'site',\n      windows: WINDOWS,\n      feature: 'commerceAnalytics',\n      read: async (request) => {\n        const refused = refusal(request)\n        if (refused) return refused\n        const hostId = request.hostId as string\n        const { current, previous } = pluginFigureWindows(request.now, request.days)\n        const [now, before] = await Promise.all([\n          ordersBetween(firestore(), hostId, current.startMs, current.endMs),\n          ordersBetween(firestore(), hostId, previous.startMs, previous.endMs),\n        ])\n        const a = orderWindowFigures(now.orders, current.startMs, current.endMs)\n        const b = orderWindowFigures(before.orders, previous.startMs, previous.endMs)\n        return {\n          ok: true,\n          table: {\n            title: 'Sales',\n            source: SOURCE,\n            period: { from: current.from, to: current.to, days: request.days },\n            columns: [\n              { key: 'window', label: 'Window', kind: 'text' },\n              { key: 'revenue', label: 'Revenue', kind: 'money', currency: 'USD' },\n              { key: 'orders', label: 'Orders', kind: 'count' },\n              { key: 'averageOrder', label: 'Average order', kind: 'money', currency: 'USD' },\n              { key: 'revenueChange', label: 'Revenue change', kind: 'change' },\n              { key: 'ordersChange', label: 'Orders change', kind: 'change' },\n            ],\n            rows: [\n              {\n                window: `${current.from} to ${current.to}`,\n                revenue: dollars(a.revenueCents),\n                orders: a.orders,\n                averageOrder: dollars(a.averageCents),\n                revenueChange: pluginFigureChange(a.revenueCents, b.revenueCents),\n                ordersChange: pluginFigureChange(a.orders, b.orders),\n              },\n              {\n                window: `${previous.from} to ${previous.to}`,\n                revenue: dollars(b.revenueCents),\n                orders: b.orders,\n                averageOrder: dollars(b.averageCents),\n                revenueChange: null,\n                ordersChange: null,\n              },\n            ],\n            omitted: 0,\n            notes: ceilingNote(now.truncated || before.truncated),\n          },\n        }\n      },\n    },\n    {\n      id: 'commerce.products',\n      label: 'Top products',\n      description: 'The products that brought in the most over the window, with units sold and line revenue.',\n      scope: 'site',\n      windows: WINDOWS,\n      feature: 'commerceAnalytics',\n      read: async (request) => {\n        const refused = refusal(request)\n        if (refused) return refused\n        const { current } = pluginFigureWindows(request.now, request.days)\n        const window = await ordersBetween(firestore(), request.hostId as string, current.startMs, current.endMs)\n        const sales = productSales(window.orders)\n        return {\n          ok: true,\n          table: {\n            title: 'Top products',\n            source: SOURCE,\n            period: { from: current.from, to: current.to, days: request.days },\n            columns: [\n              { key: 'product', label: 'Product', kind: 'text' },\n              { key: 'units', label: 'Units', kind: 'count' },\n              { key: 'revenue', label: 'Line revenue', kind: 'money', currency: 'USD' },\n            ],\n            rows: sales\n              .slice(0, PLUGIN_FIGURE_MAX_ROWS)\n              .map((entry) => ({ product: entry.name, units: entry.units, revenue: dollars(entry.cents) })),\n            omitted: Math.max(0, sales.length - PLUGIN_FIGURE_MAX_ROWS),\n            notes: [\n              'Line revenue is each line’s price times its quantity, before discounts, shipping and tax.',\n              ...ceilingNote(window.truncated),\n            ],\n          },\n        }\n      },\n    },\n  ]\n}\n\n/** Registers the sales readers from the console surface, where insight jobs run. */\nexport function registerOrderFigureReaders(firestore: () => Firestore): void {\n  for (const reader of orderFigureReaders(firestore)) {\n    registerPluginFigureReader(reader, { pluginId: BUNDLE_ID })\n  }\n}\n"],"names":["PLUGIN_FIGURE_MAX_ROWS","pluginFigureChange","pluginFigureWindows","registerPluginFigureReader","BUNDLE_ID","orderWindowFigures","productSales","ORDER_FIGURES_WINDOW_CEILING","WINDOWS","SOURCE","label","path","ordersBetween","firestore","hostId","startMs","endMs","snapshot","collection","doc","where","orderBy","limit","get","orders","docs","map","data","$id","id","slice","truncated","length","dollars","cents","Math","round","ceilingNote","toLocaleString","refusal","request","ok","status","error","includes","days","orderFigureReaders","description","scope","windows","feature","read","refused","current","previous","now","before","Promise","all","a","b","table","title","source","period","from","to","columns","key","kind","currency","rows","window","revenue","revenueCents","averageOrder","averageCents","revenueChange","ordersChange","omitted","notes","sales","entry","product","name","units","max","registerOrderFigureReaders","reader","pluginId"],"mappings":"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"}

package/src/lib/server/paid-media-delivery.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @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 MediaDeliveryProvider } from '@aglyn/aglyn/plugin-manager/media-delivery-provider';
+/**
+ * Turning a URL stored on a product into a link a buyer may follow (AGL-2814).
+ *
+ * A product's paid media — its members videos — is stored as whatever the
+ * author's picker wrote: a media reference, a CDN path, a raw Storage download
+ * URL, or a hotlink somebody typed. `parsePaidMediaSource` says which of those
+ * a value is. The commerce routes verify who is entitled and then redirect;
+ * this module decides WHERE they may redirect, and its whole job is that the
+ * answer is never a URL that outlives the purchase.
+ *
+ * ## The rules, in the order they are applied
+ *
+ * 1. **A library asset is delivered only when it is PRIVATE**, as a CDN URL
+ *    signed with {@link mintMediaSignature}. The CDN refuses a private asset on
+ *    every path without an unexpired signature, which is what makes the link
+ *    die. A public asset is refused here instead of redirected to: its URL
+ *    works for anyone forever, so handing it to a buyer is the leak itself.
+ * 2. **A Storage download URL is never redirected to.** Its token lives as
+ *    long as the object. When the object belongs to a library asset, rule 1
+ *    applies to that asset. When no asset owns it (a legacy object, a derived
+ *    rendition file), it gets a V4 signed read URL with the same bounded
+ *    lifetime. When it is not in this platform's bucket, or not inside the
+ *    site's own library or its org's, it is refused.
+ * 3. **Only the requesting site's own libraries are signed.** A product is
+ *    author data. Signing whatever scope it names would let one site's author
+ *    mint working links to another org's private files, so a host scope must
+ *    be this site and an org scope must be this site's org, and the signed
+ *    scope is always qualified with this site so the CDN's `visibleTo` check
+ *    runs against the site actually selling it.
+ * 4. **A hotlink to somebody else's server passes through unchanged.** No code
+ *    of ours runs there and nothing here can make its URL expire. That is the
+ *    author's hosting decision, and the docs say so.
+ *
+ * ## A video with a copy at the delivery provider (AGL-2824)
+ *
+ * A caller that asks for it with `delivery` gets, for a video that passes
+ * rule 1, the delivery provider's own short-lived URL instead of the signed CDN
+ * URL, whenever `mediaDeliveryRedirect` finds a current copy and the release
+ * flag is on for the owning org. It is the URL the CDN would redirect the
+ * signed request to anyway, minted one hop earlier and bounded by the same
+ * lifetime. Anything else takes the signed CDN URL exactly as before.
+ */
+/** Why a stored URL was not turned into a link. */
+export type PaidMediaRefusal = 
+/** A library asset the public can still fetch without a signature. */
+'not-private'
+/** No such asset, a deleted one, or one not shared with this site. */
+ | 'not-found'
+/** Another site's library, another org's, or outside the media prefixes. */
+ | 'out-of-scope'
+/** A Storage URL for a bucket this platform does not serve from. */
+ | 'foreign-storage'
+/** Not a value any delivery can be built from. */
+ | 'malformed';
+export type PaidMediaDelivery = {
+    ok: true;
+    via: 'signed-cdn';
+    location: string;
+    expiresAtMs: number;
+    /** The scope segment the signature covers. */
+    scope: string;
+    mediaId: string;
+} | {
+    ok: true;
+    via: 'signed-storage';
+    location: string;
+    expiresAtMs: number;
+    objectPath: string;
+} | {
+    ok: true;
+    via: 'external';
+    location: string;
+} | {
+    ok: true;
+    via: 'delivery';
+    location: string;
+    expiresAtMs: number;
+    /** The scope segment the delivery was minted for. */
+    scope: string;
+    mediaId: string;
+} | {
+    ok: false;
+    refusal: PaidMediaRefusal;
+};
+/** A document read, reduced to what this module asks of one. */
+export interface PaidMediaDocument {
+    exists: boolean;
+    get(field: string): unknown;
+}
+/** Every read and signature this module needs, injectable for tests. */
+export interface PaidMediaDeliveryIo {
+    /** The platform's media bucket; empty when unconfigured. */
+    bucketName: string;
+    readMedia(collection: 'hosts' | 'orgs', scopeId: string, mediaId: string): Promise<PaidMediaDocument>;
+    /** The org a site belongs to, or null for an unindexed site. */
+    orgIdForHost(hostId: string): Promise<string | null>;
+    /** A V4 signed read URL for one object in {@link bucketName}. */
+    signStorageRead(objectPath: string, expiresAtMs: number): Promise<string>;
+}
+/**
+ * Resolves a stored product media URL to a redirect target that expires, or
+ * says why there is none. See the module comment for the rules.
+ *
+ * `cdnParams` ride on a signed CDN URL ahead of the signature, which covers
+ * `(scope, mediaId, exp)` and never the parameters, so they select a
+ * representation of the one asset the signature names and nothing else.
+ */
+export declare function resolvePaidMediaDelivery(options: {
+    stored: unknown;
+    /** The site selling the media; the only libraries it may sign from. */
+    hostId: string;
+    /** The lifetime of the link; bounded by `assertMediaSignatureTtl`. */
+    ttlMs: number;
+    cdnParams?: ReadonlyArray<readonly [string, string]>;
+    /**
+     * Hand a video with a current copy at the delivery provider its URL there
+     * (AGL-2824). `accept` is the request's `Accept`, which chooses the
+     * rendition when `cdnParams` asks for `?r=auto`. The provider and the flag
+     * verdict default to the registered provider and the release flag.
+     */
+    delivery?: {
+        accept?: unknown;
+        provider?: MediaDeliveryProvider | null;
+        enabled?: (orgId: string | null) => Promise<boolean>;
+    };
+    nowMs?: number;
+    io: PaidMediaDeliveryIo;
+}): Promise<PaidMediaDelivery>;
+/**
+ * The production reads behind {@link resolvePaidMediaDelivery}, built on the
+ * caller's Firestore and bucket handles so a route's own mocks reach them.
+ */
+export declare function createPaidMediaDeliveryIo(options: {
+    firestore: {
+        collection(name: string): {
+            doc(id: string): {
+                get(): Promise<PaidMediaDocument>;
+                collection(name: string): {
+                    doc(id: string): {
+                        get(): Promise<PaidMediaDocument>;
+                    };
+                };
+            };
+        };
+    };
+    bucket: {
+        name?: string;
+        file(path: string): {
+            getSignedUrl(config: {
+                version: 'v4';
+                action: 'read';
+                expires: number;
+            }): Promise<[string] | string[]>;
+        };
+    };
+}): PaidMediaDeliveryIo;

package/src/lib/server/paid-media-delivery.js

@@ -0,0 +1,212 @@
+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 { hostQualifiedScope, MEDIA_CDN_RENDITION_AUTO, MEDIA_CDN_RENDITION_PARAM, MEDIA_CDN_ROUTE, paidMediaAssetOfObject, parseMediaRenditions, parsePaidMediaSource } from "@aglyn/aglyn/server";
+import { mediaDeliveryProvider } from "@aglyn/aglyn/plugin-manager/media-delivery-provider";
+import { mediaDeliveryRedirect } from "@aglyn/tenant-data-admin/server/media-delivery";
+import { assertMediaSignatureTtl, mediaSignatureQuery, mintMediaSignature } from "@aglyn/tenant-data-admin/server/media-signing";
+import { isMediaStoragePathInScope } from "@aglyn/tenant-data-admin/server/media-storage-path";
+import { mediaCdnScopeRefusal, parseMediaCdnScope, selectAutoRendition } from "@aglyn/tenant-data-admin/server/serve-media-cdn";
+/**
+ * Resolves a stored product media URL to a redirect target that expires, or
+ * says why there is none. See the module comment for the rules.
+ *
+ * `cdnParams` ride on a signed CDN URL ahead of the signature, which covers
+ * `(scope, mediaId, exp)` and never the parameters, so they select a
+ * representation of the one asset the signature names and nothing else.
+ */ export async function resolvePaidMediaDelivery(options) {
+    var _options_nowMs;
+    const { hostId, ttlMs, io } = options;
+    const nowMs = (_options_nowMs = options.nowMs) != null ? _options_nowMs : Date.now();
+    const refuse = (refusal)=>({
+            ok: false,
+            refusal
+        });
+    if (!hostId) return refuse('out-of-scope');
+    // One lookup per call, and only for the forms that need to know the org.
+    let orgId;
+    const siteOrgId = ()=>orgId != null ? orgId : orgId = io.orgIdForHost(hostId);
+    /**
+   * The delivery provider's URL for a private library video, or null for
+   * the signed CDN URL. The representation is the one the CDN would pick for
+   * the same `?r=` and `Accept`, so the buyer gets the copy the signed URL
+   * would have been redirected to.
+   */ const deliverFromProvider = async (delivery, asset)=>{
+        var _options_cdnParams;
+        var _find;
+        const provider = delivery.provider === undefined ? mediaDeliveryProvider('deliver') : delivery.provider;
+        if (!provider) return null;
+        const requested = (_find = ((_options_cdnParams = options.cdnParams) != null ? _options_cdnParams : []).find(([key])=>key === MEDIA_CDN_RENDITION_PARAM)) == null ? void 0 : _find[1];
+        const renditions = parseMediaRenditions(asset.document.get('videoRenditions'));
+        const rendition = !requested ? undefined : requested === MEDIA_CDN_RENDITION_AUTO ? selectAutoRendition(renditions, delivery.accept) : renditions.find((entry)=>entry.key === requested);
+        const redirect = await mediaDeliveryRedirect(_extends({
+            provider,
+            asset: {
+                collection: asset.collection,
+                scopeId: asset.scopeId,
+                mediaId: asset.mediaId
+            },
+            document: asset.document,
+            rendition,
+            servedType: rendition ? rendition.contentType : asset.document.get('contentType'),
+            claims: {
+                scope: asset.deliveryScope,
+                mediaId: asset.mediaId,
+                hostId
+            },
+            orgId: async ()=>asset.orgScope ? asset.scopeId : await siteOrgId()
+        }, delivery.enabled ? {
+            deliveryEnabled: delivery.enabled
+        } : {}, {
+            ttlMs,
+            nowMs
+        })).catch(()=>null);
+        if (!redirect) return null;
+        return {
+            ok: true,
+            via: 'delivery',
+            location: redirect.location,
+            expiresAtMs: redirect.expiresAtMs,
+            scope: asset.deliveryScope,
+            mediaId: asset.mediaId
+        };
+    };
+    const deliverAsset = async (scope, mediaId)=>{
+        var _options_cdnParams;
+        const parsed = parseMediaCdnScope(scope);
+        if (!parsed) return refuse('malformed');
+        let collection;
+        let deliveryScope;
+        if (parsed.isOrg) {
+            const owner = await siteOrgId();
+            if (!owner || parsed.scopeId !== owner) return refuse('out-of-scope');
+            collection = 'orgs';
+            deliveryScope = hostQualifiedScope(scope, hostId);
+        } else {
+            if (parsed.scopeId !== hostId) return refuse('out-of-scope');
+            collection = 'hosts';
+            deliveryScope = hostId;
+        }
+        const deliveryParsed = parseMediaCdnScope(deliveryScope);
+        if (!deliveryParsed) return refuse('malformed');
+        const document = await io.readMedia(collection, parsed.scopeId, mediaId);
+        if (!(document == null ? void 0 : document.exists) || document.get('deletedAt')) {
+            return refuse('not-found');
+        }
+        // The CDN would 404 an org asset this site is not allowed to use, so a
+        // link to one is a link that cannot play.
+        if (mediaCdnScopeRefusal(deliveryParsed, document.get('visibleTo'))) {
+            return refuse('not-found');
+        }
+        if (document.get('private') !== true) return refuse('not-private');
+        assertMediaSignatureTtl(ttlMs);
+        const delivered = options.delivery ? await deliverFromProvider(options.delivery, {
+            collection,
+            scopeId: parsed.scopeId,
+            orgScope: parsed.isOrg,
+            deliveryScope,
+            mediaId,
+            document
+        }) : null;
+        if (delivered) return delivered;
+        const signature = mintMediaSignature(deliveryScope, mediaId, nowMs, ttlMs);
+        const params = new URLSearchParams();
+        for (const [key, value] of (_options_cdnParams = options.cdnParams) != null ? _options_cdnParams : []){
+            if (key !== 'exp' && key !== 'sig') params.set(key, value);
+        }
+        const prefix = params.toString();
+        return {
+            ok: true,
+            via: 'signed-cdn',
+            location: `${MEDIA_CDN_ROUTE}/${deliveryScope}/${mediaId}?` + `${prefix ? `${prefix}&` : ''}${mediaSignatureQuery(signature)}`,
+            expiresAtMs: signature.exp,
+            scope: deliveryScope,
+            mediaId
+        };
+    };
+    const source = parsePaidMediaSource(options.stored);
+    switch(source.kind){
+        case 'malformed':
+            return refuse('malformed');
+        case 'external':
+            return {
+                ok: true,
+                via: 'external',
+                location: source.url
+            };
+        case 'asset':
+            return deliverAsset(source.scope, source.mediaId);
+        case 'storage-object':
+            {
+                if (!io.bucketName || source.bucket !== io.bucketName) {
+                    return refuse('foreign-storage');
+                }
+                const { objectPath } = source;
+                const segments = objectPath.split('/');
+                let base = null;
+                if (segments[0] === 'hosts' && segments[1] === hostId) {
+                    base = `hosts/${hostId}`;
+                } else if (segments[0] === 'orgs' && segments[1]) {
+                    const owner = await siteOrgId();
+                    if (owner && segments[1] === owner) base = `orgs/${owner}`;
+                }
+                // The same prefix test the CDN applies to a document's `storagePath`,
+                // which also refuses traversal and empty segments.
+                if (!base || !isMediaStoragePathInScope(objectPath, base)) {
+                    return refuse('out-of-scope');
+                }
+                // An object keyed like an asset IS that asset, and the asset's own rules
+                // decide — including refusing it when the asset is still public.
+                const asset = paidMediaAssetOfObject(objectPath);
+                if (asset) return deliverAsset(asset.scope, asset.mediaId);
+                assertMediaSignatureTtl(ttlMs);
+                const expiresAtMs = nowMs + ttlMs;
+                return {
+                    ok: true,
+                    via: 'signed-storage',
+                    location: await io.signStorageRead(objectPath, expiresAtMs),
+                    expiresAtMs,
+                    objectPath
+                };
+            }
+    }
+}
+/**
+ * The production reads behind {@link resolvePaidMediaDelivery}, built on the
+ * caller's Firestore and bucket handles so a route's own mocks reach them.
+ */ export function createPaidMediaDeliveryIo(options) {
+    var _ref;
+    const { firestore, bucket } = options;
+    return {
+        bucketName: String((_ref = bucket == null ? void 0 : bucket.name) != null ? _ref : ''),
+        readMedia: (collection, scopeId, mediaId)=>firestore.collection(collection).doc(scopeId).collection('media').doc(mediaId).get(),
+        orgIdForHost: async (hostId)=>{
+            const index = await firestore.collection('hostIndex').doc(hostId).get();
+            const orgId = index.exists ? index.get('orgId') : undefined;
+            return typeof orgId === 'string' && orgId ? orgId : null;
+        },
+        signStorageRead: async (objectPath, expiresAtMs)=>{
+            const [url] = await bucket.file(objectPath).getSignedUrl({
+                version: 'v4',
+                action: 'read',
+                expires: expiresAtMs
+            });
+            return String(url);
+        }
+    };
+}
+
+//# sourceMappingURL=paid-media-delivery.js.map