@aglyn/plugins-commerce 1.0.0-beta.143

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/paid-media-delivery.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  hostQualifiedScope,\n  MEDIA_CDN_RENDITION_AUTO,\n  MEDIA_CDN_RENDITION_PARAM,\n  MEDIA_CDN_ROUTE,\n  paidMediaAssetOfObject,\n  parseMediaRenditions,\n  parsePaidMediaSource,\n} from '@aglyn/aglyn/server'\nimport {\n  type MediaDeliveryProvider,\n  mediaDeliveryProvider,\n} from '@aglyn/aglyn/plugin-manager/media-delivery-provider'\nimport { mediaDeliveryRedirect } from '@aglyn/tenant-data-admin/server/media-delivery'\nimport {\n  assertMediaSignatureTtl,\n  mediaSignatureQuery,\n  mintMediaSignature,\n} from '@aglyn/tenant-data-admin/server/media-signing'\nimport { isMediaStoragePathInScope } from '@aglyn/tenant-data-admin/server/media-storage-path'\nimport {\n  mediaCdnScopeRefusal,\n  parseMediaCdnScope,\n  selectAutoRendition,\n} from '@aglyn/tenant-data-admin/server/serve-media-cdn'\n\n/**\n * Turning a URL stored on a product into a link a buyer may follow (AGL-2814).\n *\n * A product's paid media — its members videos — is stored as whatever the\n * author's picker wrote: a media reference, a CDN path, a raw Storage download\n * URL, or a hotlink somebody typed. `parsePaidMediaSource` says which of those\n * a value is. The commerce routes verify who is entitled and then redirect;\n * this module decides WHERE they may redirect, and its whole job is that the\n * answer is never a URL that outlives the purchase.\n *\n * ## The rules, in the order they are applied\n *\n * 1. **A library asset is delivered only when it is PRIVATE**, as a CDN URL\n *    signed with {@link mintMediaSignature}. The CDN refuses a private asset on\n *    every path without an unexpired signature, which is what makes the link\n *    die. A public asset is refused here instead of redirected to: its URL\n *    works for anyone forever, so handing it to a buyer is the leak itself.\n * 2. **A Storage download URL is never redirected to.** Its token lives as\n *    long as the object. When the object belongs to a library asset, rule 1\n *    applies to that asset. When no asset owns it (a legacy object, a derived\n *    rendition file), it gets a V4 signed read URL with the same bounded\n *    lifetime. When it is not in this platform's bucket, or not inside the\n *    site's own library or its org's, it is refused.\n * 3. **Only the requesting site's own libraries are signed.** A product is\n *    author data. Signing whatever scope it names would let one site's author\n *    mint working links to another org's private files, so a host scope must\n *    be this site and an org scope must be this site's org, and the signed\n *    scope is always qualified with this site so the CDN's `visibleTo` check\n *    runs against the site actually selling it.\n * 4. **A hotlink to somebody else's server passes through unchanged.** No code\n *    of ours runs there and nothing here can make its URL expire. That is the\n *    author's hosting decision, and the docs say so.\n *\n * ## A video with a copy at the delivery provider (AGL-2824)\n *\n * A caller that asks for it with `delivery` gets, for a video that passes\n * rule 1, the delivery provider's own short-lived URL instead of the signed CDN\n * URL, whenever `mediaDeliveryRedirect` finds a current copy and the release\n * flag is on for the owning org. It is the URL the CDN would redirect the\n * signed request to anyway, minted one hop earlier and bounded by the same\n * lifetime. Anything else takes the signed CDN URL exactly as before.\n */\n\n/** Why a stored URL was not turned into a link. */\nexport type PaidMediaRefusal =\n  /** A library asset the public can still fetch without a signature. */\n  | 'not-private'\n  /** No such asset, a deleted one, or one not shared with this site. */\n  | 'not-found'\n  /** Another site's library, another org's, or outside the media prefixes. */\n  | 'out-of-scope'\n  /** A Storage URL for a bucket this platform does not serve from. */\n  | 'foreign-storage'\n  /** Not a value any delivery can be built from. */\n  | 'malformed'\n\nexport type PaidMediaDelivery =\n  | {\n      ok: true\n      via: 'signed-cdn'\n      location: string\n      expiresAtMs: number\n      /** The scope segment the signature covers. */\n      scope: string\n      mediaId: string\n    }\n  | {\n      ok: true\n      via: 'signed-storage'\n      location: string\n      expiresAtMs: number\n      objectPath: string\n    }\n  | { ok: true; via: 'external'; location: string }\n  | {\n      ok: true\n      via: 'delivery'\n      location: string\n      expiresAtMs: number\n      /** The scope segment the delivery was minted for. */\n      scope: string\n      mediaId: string\n    }\n  | { ok: false; refusal: PaidMediaRefusal }\n\n/** A document read, reduced to what this module asks of one. */\nexport interface PaidMediaDocument {\n  exists: boolean\n  get(field: string): unknown\n}\n\n/** Every read and signature this module needs, injectable for tests. */\nexport interface PaidMediaDeliveryIo {\n  /** The platform's media bucket; empty when unconfigured. */\n  bucketName: string\n  readMedia(\n    collection: 'hosts' | 'orgs',\n    scopeId: string,\n    mediaId: string,\n  ): Promise<PaidMediaDocument>\n  /** The org a site belongs to, or null for an unindexed site. */\n  orgIdForHost(hostId: string): Promise<string | null>\n  /** A V4 signed read URL for one object in {@link bucketName}. */\n  signStorageRead(objectPath: string, expiresAtMs: number): Promise<string>\n}\n\n/**\n * Resolves a stored product media URL to a redirect target that expires, or\n * says why there is none. See the module comment for the rules.\n *\n * `cdnParams` ride on a signed CDN URL ahead of the signature, which covers\n * `(scope, mediaId, exp)` and never the parameters, so they select a\n * representation of the one asset the signature names and nothing else.\n */\nexport async function resolvePaidMediaDelivery(options: {\n  stored: unknown\n  /** The site selling the media; the only libraries it may sign from. */\n  hostId: string\n  /** The lifetime of the link; bounded by `assertMediaSignatureTtl`. */\n  ttlMs: number\n  cdnParams?: ReadonlyArray<readonly [string, string]>\n  /**\n   * Hand a video with a current copy at the delivery provider its URL there\n   * (AGL-2824). `accept` is the request's `Accept`, which chooses the\n   * rendition when `cdnParams` asks for `?r=auto`. The provider and the flag\n   * verdict default to the registered provider and the release flag.\n   */\n  delivery?: {\n    accept?: unknown\n    provider?: MediaDeliveryProvider | null\n    enabled?: (orgId: string | null) => Promise<boolean>\n  }\n  nowMs?: number\n  io: PaidMediaDeliveryIo\n}): Promise<PaidMediaDelivery> {\n  const { hostId, ttlMs, io } = options\n  const nowMs = options.nowMs ?? Date.now()\n  const refuse = (refusal: PaidMediaRefusal): PaidMediaDelivery => ({\n    ok: false,\n    refusal,\n  })\n  if (!hostId) return refuse('out-of-scope')\n\n  // One lookup per call, and only for the forms that need to know the org.\n  let orgId: Promise<string | null> | undefined\n  const siteOrgId = () => (orgId ??= io.orgIdForHost(hostId))\n\n  /**\n   * The delivery provider's URL for a private library video, or null for\n   * the signed CDN URL. The representation is the one the CDN would pick for\n   * the same `?r=` and `Accept`, so the buyer gets the copy the signed URL\n   * would have been redirected to.\n   */\n  const deliverFromProvider = async (\n    delivery: NonNullable<typeof options.delivery>,\n    asset: {\n      collection: 'hosts' | 'orgs'\n      scopeId: string\n      orgScope: boolean\n      deliveryScope: string\n      mediaId: string\n      document: PaidMediaDocument\n    },\n  ): Promise<PaidMediaDelivery | null> => {\n    const provider =\n      delivery.provider === undefined ? mediaDeliveryProvider('deliver') : delivery.provider\n    if (!provider) return null\n    const requested = (options.cdnParams ?? []).find(\n      ([key]) => key === MEDIA_CDN_RENDITION_PARAM,\n    )?.[1]\n    const renditions = parseMediaRenditions(asset.document.get('videoRenditions'))\n    const rendition = !requested\n      ? undefined\n      : requested === MEDIA_CDN_RENDITION_AUTO\n        ? selectAutoRendition(renditions, delivery.accept)\n        : renditions.find((entry) => entry.key === requested)\n    const redirect = await mediaDeliveryRedirect({\n      provider,\n      asset: {\n        collection: asset.collection,\n        scopeId: asset.scopeId,\n        mediaId: asset.mediaId,\n      },\n      document: asset.document,\n      rendition,\n      servedType: rendition ? rendition.contentType : asset.document.get('contentType'),\n      claims: { scope: asset.deliveryScope, mediaId: asset.mediaId, hostId },\n      orgId: async () => (asset.orgScope ? asset.scopeId : await siteOrgId()),\n      ...(delivery.enabled ? { deliveryEnabled: delivery.enabled } : {}),\n      ttlMs,\n      nowMs,\n    }).catch(() => null)\n    if (!redirect) return null\n    return {\n      ok: true,\n      via: 'delivery',\n      location: redirect.location,\n      expiresAtMs: redirect.expiresAtMs,\n      scope: asset.deliveryScope,\n      mediaId: asset.mediaId,\n    }\n  }\n\n  const deliverAsset = async (\n    scope: string,\n    mediaId: string,\n  ): Promise<PaidMediaDelivery> => {\n    const parsed = parseMediaCdnScope(scope)\n    if (!parsed) return refuse('malformed')\n    let collection: 'hosts' | 'orgs'\n    let deliveryScope: string\n    if (parsed.isOrg) {\n      const owner = await siteOrgId()\n      if (!owner || parsed.scopeId !== owner) return refuse('out-of-scope')\n      collection = 'orgs'\n      deliveryScope = hostQualifiedScope(scope, hostId)\n    } else {\n      if (parsed.scopeId !== hostId) return refuse('out-of-scope')\n      collection = 'hosts'\n      deliveryScope = hostId\n    }\n    const deliveryParsed = parseMediaCdnScope(deliveryScope)\n    if (!deliveryParsed) return refuse('malformed')\n    const document = await io.readMedia(collection, parsed.scopeId, mediaId)\n    if (!document?.exists || document.get('deletedAt')) {\n      return refuse('not-found')\n    }\n    // The CDN would 404 an org asset this site is not allowed to use, so a\n    // link to one is a link that cannot play.\n    if (mediaCdnScopeRefusal(deliveryParsed, document.get('visibleTo'))) {\n      return refuse('not-found')\n    }\n    if (document.get('private') !== true) return refuse('not-private')\n    assertMediaSignatureTtl(ttlMs)\n    const delivered = options.delivery\n      ? await deliverFromProvider(options.delivery, {\n          collection,\n          scopeId: parsed.scopeId,\n          orgScope: parsed.isOrg,\n          deliveryScope,\n          mediaId,\n          document,\n        })\n      : null\n    if (delivered) return delivered\n    const signature = mintMediaSignature(deliveryScope, mediaId, nowMs, ttlMs)\n    const params = new URLSearchParams()\n    for (const [key, value] of options.cdnParams ?? []) {\n      if (key !== 'exp' && key !== 'sig') params.set(key, value)\n    }\n    const prefix = params.toString()\n    return {\n      ok: true,\n      via: 'signed-cdn',\n      location:\n        `${MEDIA_CDN_ROUTE}/${deliveryScope}/${mediaId}?` +\n        `${prefix ? `${prefix}&` : ''}${mediaSignatureQuery(signature)}`,\n      expiresAtMs: signature.exp,\n      scope: deliveryScope,\n      mediaId,\n    }\n  }\n\n  const source = parsePaidMediaSource(options.stored)\n  switch (source.kind) {\n    case 'malformed':\n      return refuse('malformed')\n    case 'external':\n      return { ok: true, via: 'external', location: source.url }\n    case 'asset':\n      return deliverAsset(source.scope, source.mediaId)\n    case 'storage-object': {\n      if (!io.bucketName || source.bucket !== io.bucketName) {\n        return refuse('foreign-storage')\n      }\n      const { objectPath } = source\n      const segments = objectPath.split('/')\n      let base: string | null = null\n      if (segments[0] === 'hosts' && segments[1] === hostId) {\n        base = `hosts/${hostId}`\n      } else if (segments[0] === 'orgs' && segments[1]) {\n        const owner = await siteOrgId()\n        if (owner && segments[1] === owner) base = `orgs/${owner}`\n      }\n      // The same prefix test the CDN applies to a document's `storagePath`,\n      // which also refuses traversal and empty segments.\n      if (!base || !isMediaStoragePathInScope(objectPath, base)) {\n        return refuse('out-of-scope')\n      }\n      // An object keyed like an asset IS that asset, and the asset's own rules\n      // decide — including refusing it when the asset is still public.\n      const asset = paidMediaAssetOfObject(objectPath)\n      if (asset) return deliverAsset(asset.scope, asset.mediaId)\n      assertMediaSignatureTtl(ttlMs)\n      const expiresAtMs = nowMs + ttlMs\n      return {\n        ok: true,\n        via: 'signed-storage',\n        location: await io.signStorageRead(objectPath, expiresAtMs),\n        expiresAtMs,\n        objectPath,\n      }\n    }\n  }\n}\n\n/**\n * The production reads behind {@link resolvePaidMediaDelivery}, built on the\n * caller's Firestore and bucket handles so a route's own mocks reach them.\n */\nexport function createPaidMediaDeliveryIo(options: {\n  firestore: {\n    collection(name: string): {\n      doc(id: string): {\n        get(): Promise<PaidMediaDocument>\n        collection(name: string): {\n          doc(id: string): { get(): Promise<PaidMediaDocument> }\n        }\n      }\n    }\n  }\n  bucket: {\n    name?: string\n    file(path: string): {\n      getSignedUrl(config: {\n        version: 'v4'\n        action: 'read'\n        expires: number\n      }): Promise<[string] | string[]>\n    }\n  }\n}): PaidMediaDeliveryIo {\n  const { firestore, bucket } = options\n  return {\n    bucketName: String(bucket?.name ?? ''),\n    readMedia: (collection, scopeId, mediaId) =>\n      firestore\n        .collection(collection)\n        .doc(scopeId)\n        .collection('media')\n        .doc(mediaId)\n        .get(),\n    orgIdForHost: async (hostId) => {\n      const index = await firestore.collection('hostIndex').doc(hostId).get()\n      const orgId = index.exists ? index.get('orgId') : undefined\n      return typeof orgId === 'string' && orgId ? orgId : null\n    },\n    signStorageRead: async (objectPath, expiresAtMs) => {\n      const [url] = await bucket.file(objectPath).getSignedUrl({\n        version: 'v4',\n        action: 'read',\n        expires: expiresAtMs,\n      })\n      return String(url)\n    },\n  }\n}\n"],"names":["hostQualifiedScope","MEDIA_CDN_RENDITION_AUTO","MEDIA_CDN_RENDITION_PARAM","MEDIA_CDN_ROUTE","paidMediaAssetOfObject","parseMediaRenditions","parsePaidMediaSource","mediaDeliveryProvider","mediaDeliveryRedirect","assertMediaSignatureTtl","mediaSignatureQuery","mintMediaSignature","isMediaStoragePathInScope","mediaCdnScopeRefusal","parseMediaCdnScope","selectAutoRendition","resolvePaidMediaDelivery","options","hostId","ttlMs","io","nowMs","Date","now","refuse","refusal","ok","orgId","siteOrgId","orgIdForHost","deliverFromProvider","delivery","asset","provider","undefined","requested","cdnParams","find","key","renditions","document","get","rendition","accept","entry","redirect","collection","scopeId","mediaId","servedType","contentType","claims","scope","deliveryScope","orgScope","enabled","deliveryEnabled","catch","via","location","expiresAtMs","deliverAsset","parsed","isOrg","owner","deliveryParsed","readMedia","exists","delivered","signature","params","URLSearchParams","value","set","prefix","toString","exp","source","stored","kind","url","bucketName","bucket","objectPath","segments","split","base","signStorageRead","createPaidMediaDeliveryIo","firestore","String","name","doc","index","file","getSignedUrl","version","action","expires"],"mappings":"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"}

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

@@ -0,0 +1,54 @@
+/**
+ * @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';
+/**
+ * The settlement claim (AGL-1691) now lives in `@aglyn/aglyn/server`
+ * (AGL-1697), because it is the answer for every unkeyed money route and not
+ * just this one. Moved whole and unchanged in behaviour — the digest is still
+ * `sha256('pos:{hostId}:{key}')`, so keys minted against the local version
+ * still resolve. The only difference is the claim document: it carries
+ * `scopeId` where this file wrote `hostId`, and no longer writes a
+ * `serverTimestamp` sentinel alongside `createdAtMs`, since the shared version
+ * takes a plain Firestore-shaped store rather than firebase-admin itself.
+ */
+/**
+ * POS sale (AGL-312): manager-gated, server-priced. Cash sales create a
+ * paid `channel: 'pos'` order immediately (with change calculation);
+ * card sales mint a Stripe payment link the register shows as a QR
+ * (Stripe Terminal hardware can slot in behind the same endpoint
+ * later). Inventory decrements per line from the register's location,
+ * and sales can post to an open reservation folio instead (AGL-317).
+ */
+export declare const posOrderHandler: PluginApiHandler;
+/**
+ * The billing month a non-card POS fee accrues into (AGL-2111): `YYYY-MM` in
+ * **UTC**, byte-identical to the key `apps/console/utils/billing-month.ts`
+ * mints and to the twelve other month counters on the platform
+ * (`orgs/{id}/apiUsage/*`, `orgs/{id}/assistUsage/*`, the per-host counters).
+ *
+ * It has to be UTC and it has to be this exact expression: `report-usage`
+ * sweeps `previousMonth()` in UTC and reads the accrual document by that key,
+ * so a local-time month would strand every sale rung in the offset window on a
+ * document no sweep ever looks at — which is uncollected revenue that leaves
+ * no trace. `offline-pos-fee-month-key.spec.ts` pins the two against each
+ * other rather than trusting the comment.
+ *
+ * Local rather than imported because `apps/console` is an app: a plugin
+ * library cannot import from it, and the repo's other eleven copies of this
+ * one-liner are the established shape.
+ */
+export declare function offlineFeeMonthKey(now?: Date): string;