@mj-biz-apps/orders-core-entities-server 0.0.1 → 5.2.0

package/dist/EmailDeliveryChannel.d.ts

@@ -0,0 +1,31 @@
+import { BaseDeliveryChannel, type DeliverableDocument, type DeliveryAddressing, type DeliveryContext, type DeliveryResult } from './BaseDeliveryChannel.js';
+export declare class EmailDeliveryChannel extends BaseDeliveryChannel {
+    /**
+     * Which MJ communication provider to send through.
+     *
+     * A GETTER, NOT AN ENV READ. This package's tsconfig sets `"types": []` — it has no Node globals
+     * by design, which is also why the signature code uses Web Crypto rather than `node:crypto`. So a
+     * deployment that sends through Microsoft Graph subclasses this and overrides the getter, and its
+     * `@RegisterClass(BaseDeliveryChannel, 'Email')` wins by load-order priority. That is the same
+     * escape hatch the payment drivers offer, and it keeps the choice in code somebody can read rather
+     * than in an environment variable nobody can find.
+     */
+    protected get ProviderName(): string;
+    Deliver(document: DeliverableDocument, addressing: DeliveryAddressing, context: DeliveryContext): Promise<DeliveryResult>;
+    /**
+     * Our vocabulary, translated into MJ's `Message`.
+     *
+     * `From` IS LEFT UNSET WHEN THE CALLER DID NOT SUPPLY ONE, rather than defaulted to something
+     * plausible. MJ's provider resolves its own configured sender, and a guess here — a no-reply
+     * address this app invented — would either be rejected by the provider's domain authentication or,
+     * worse, accepted and send the company's invoices from an address nobody monitors for replies.
+     *
+     * BOTH BODIES ARE SET when the caller supplied a plain-text alternative. An HTML-only message is
+     * one of the strongest spam signals there is, and an invoice landing in a junk folder is
+     * indistinguishable from one that was never sent.
+     */
+    private buildMessage;
+}
+/** Tree-shaking anchor — call from the server bootstrap so @RegisterClass is retained. */
+export declare function LoadEmailDeliveryChannel(): void;
+//# sourceMappingURL=EmailDeliveryChannel.d.ts.map

package/dist/EmailDeliveryChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmailDeliveryChannel.d.ts","sourceRoot":"","sources":["../src/EmailDeliveryChannel.ts"],"names":[],"mappings":"AAqCA,OAAO,EACH,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,cAAc,EACtB,MAAM,0BAA0B,CAAC;AAclC,qBACa,oBAAqB,SAAQ,mBAAmB;IACzD;;;;;;;;;OASG;IACH,SAAS,KAAK,YAAY,IAAI,MAAM,CAEnC;IAEqB,OAAO,CACzB,QAAQ,EAAE,mBAAmB,EAC7B,UAAU,EAAE,kBAAkB,EAC9B,OAAO,EAAE,eAAe,GACzB,OAAO,CAAC,cAAc,CAAC;IAiE1B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,YAAY;CAkBvB;AAED,0FAA0F;AAC1F,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/EmailDeliveryChannel.js

@@ -0,0 +1,158 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * EmailDeliveryChannel — sending a rendered document, over MJ's communication framework.
+ *
+ * THIS CLASS IS DELIBERATELY THIN, and the thinness is the design. MJ's `CommunicationEngine` already
+ * owns provider registration, credential resolution, template processing, dry-run preview, and — the
+ * one that matters most here — a persisted log row per message with its status and any error. Every
+ * one of those is a thing a hand-rolled mail path in this app would have had to grow, badly, over the
+ * following year. So this channel translates our vocabulary into MJ's and gets out of the way.
+ *
+ * THE LOG IS WHY THERE IS NO ORDERS-SIDE DELIVERY TABLE YET. `CommunicationEngine.SendSingleMessage`
+ * writes a `MJ: Communication Logs` row for every send, carrying the recipient, the body as sent, the
+ * status and the failure reason. That answers "was it sent, to whom, and did it work" today, without
+ * a schema change. What it does NOT answer is "has THIS ORDER been invoiced, and when" — that needs a
+ * row keyed by the order, and it is the deliberate next step rather than something to fake here by
+ * stuffing an order id into a log message.
+ *
+ * ONE MESSAGE PER RECIPIENT, NOT ONE MESSAGE WITH MANY RECIPIENTS. Two reasons, and the second is the
+ * one that decided it. A single message would expose every billing contact's address to all the
+ * others — a real disclosure when a customer's contacts span two organisations. And a partial failure
+ * on a multi-recipient send is unattributable: the provider reports one status for the message, so
+ * "delivered to two of three" is indistinguishable from "delivered", and nobody learns which contact
+ * did not get the bill.
+ *
+ * A PARTIAL SEND IS A FAILURE, reported with the addresses that DID work. The alternative — reporting
+ * success because at least one landed — is how an invoice quietly stops reaching the person who
+ * actually pays it while the send log stays green.
+ *
+ * CONNECTS TO:
+ *   BASE:  ./BaseDeliveryChannel.ts
+ *   PURE:  ./DeliveryBehavior.ts
+ *   MJ:    @memberjunction/communication-engine
+ *   DOC:   plans/archive/bizapps-orders-master.md §4.4
+ */
+import { LogError, LogStatus } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { CommunicationEngine } from '@memberjunction/communication-engine';
+import { Message } from '@memberjunction/communication-types';
+import { BaseDeliveryChannel, } from './BaseDeliveryChannel.js';
+/**
+ * The MJ communication provider used when the app has not been told otherwise.
+ *
+ * SendGrid because it is the provider MJ ships an email implementation for and the one most
+ * deployments already configure. It is a constant rather than a hard-coded string in five places so
+ * a deployment that uses Microsoft Graph changes it here, and so this comment has somewhere to live.
+ */
+const DEFAULT_PROVIDER = 'SendGrid';
+/** MJ's own name for the message type. Not ours to invent — it is looked up in MJ's metadata. */
+const MESSAGE_TYPE = 'Email';
+let EmailDeliveryChannel = class EmailDeliveryChannel extends BaseDeliveryChannel {
+    /**
+     * Which MJ communication provider to send through.
+     *
+     * A GETTER, NOT AN ENV READ. This package's tsconfig sets `"types": []` — it has no Node globals
+     * by design, which is also why the signature code uses Web Crypto rather than `node:crypto`. So a
+     * deployment that sends through Microsoft Graph subclasses this and overrides the getter, and its
+     * `@RegisterClass(BaseDeliveryChannel, 'Email')` wins by load-order priority. That is the same
+     * escape hatch the payment drivers offer, and it keeps the choice in code somebody can read rather
+     * than in an environment variable nobody can find.
+     */
+    get ProviderName() {
+        return DEFAULT_PROVIDER;
+    }
+    async Deliver(document, addressing, context) {
+        const recipients = (addressing.To ?? []).filter((r) => (r.Address ?? '').trim());
+        if (!recipients.length) {
+            // A REFUSAL, not a throw: nothing is broken, there is simply nobody to send to. The caller
+            // should have asked `DecideDelivery` first, and this is the backstop for the one who did not.
+            return { Success: false, Delivered: [], Reason: 'no recipient address was supplied' };
+        }
+        const engine = CommunicationEngine.Instance;
+        await engine.Config(false, context.User, context.Provider);
+        const delivered = [];
+        const failures = [];
+        let providerMessageID;
+        for (const recipient of recipients) {
+            const address = recipient.Address.trim();
+            const message = this.buildMessage(document, addressing, address, recipient.FullName ?? undefined);
+            try {
+                const result = await engine.SendSingleMessage(this.ProviderName, MESSAGE_TYPE, message, undefined, context.PreviewOnly === true);
+                if (result?.Success) {
+                    delivered.push(address);
+                    providerMessageID ??= result.Message?.MessageType?.ID;
+                }
+                else {
+                    failures.push(`${address}: ${result?.Error || 'the provider reported a failure with no reason'}`);
+                }
+            }
+            catch (err) {
+                // A FAULT — the provider was unreachable or threw. It is caught rather than propagated
+                // so one unreachable recipient does not abandon the rest, and it is recorded as a
+                // failure so the overall result cannot come back green.
+                const reason = err instanceof Error ? err.message : String(err);
+                LogError(`Delivering ${document.DocumentNumber} to ${address} threw: ${reason}`);
+                failures.push(`${address}: ${reason}`);
+            }
+        }
+        if (failures.length) {
+            // Partial success is reported as failure WITH the addresses that worked, so a retry can
+            // skip them. Reporting success because one landed is how a bill quietly stops reaching the
+            // person who pays it.
+            return {
+                Success: false,
+                Delivered: delivered,
+                ProviderMessageID: providerMessageID,
+                Reason: `${document.DocumentNumber} reached ${delivered.length} of ${recipients.length} recipients. ` +
+                    `Failures: ${failures.join('; ')}`,
+            };
+        }
+        LogStatus(`${document.Kind} ${document.DocumentNumber} ${context.PreviewOnly ? 'previewed for' : 'sent to'} ` +
+            `${delivered.join(', ')}.`);
+        return { Success: true, Delivered: delivered, ProviderMessageID: providerMessageID };
+    }
+    /**
+     * Our vocabulary, translated into MJ's `Message`.
+     *
+     * `From` IS LEFT UNSET WHEN THE CALLER DID NOT SUPPLY ONE, rather than defaulted to something
+     * plausible. MJ's provider resolves its own configured sender, and a guess here — a no-reply
+     * address this app invented — would either be rejected by the provider's domain authentication or,
+     * worse, accepted and send the company's invoices from an address nobody monitors for replies.
+     *
+     * BOTH BODIES ARE SET when the caller supplied a plain-text alternative. An HTML-only message is
+     * one of the strongest spam signals there is, and an invoice landing in a junk folder is
+     * indistinguishable from one that was never sent.
+     */
+    buildMessage(document, addressing, address, fullName) {
+        const message = new Message();
+        message.To = address;
+        message.Subject = document.Subject;
+        message.HTMLBody = document.BodyHtml;
+        if (document.BodyPlain)
+            message.Body = document.BodyPlain;
+        if (addressing.From)
+            message.From = addressing.From;
+        if (addressing.FromName)
+            message.FromName = addressing.FromName;
+        if (addressing.CC?.length)
+            message.CCRecipients = [...addressing.CC];
+        if (addressing.BCC?.length)
+            message.BCCRecipients = [...addressing.BCC];
+        void fullName; // MJ's Message carries no per-recipient display name; kept for the seam's shape.
+        return message;
+    }
+};
+EmailDeliveryChannel = __decorate([
+    RegisterClass(BaseDeliveryChannel, 'Email')
+], EmailDeliveryChannel);
+export { EmailDeliveryChannel };
+/** Tree-shaking anchor — call from the server bootstrap so @RegisterClass is retained. */
+export function LoadEmailDeliveryChannel() {
+    // intentionally empty
+}
+//# sourceMappingURL=EmailDeliveryChannel.js.map

package/dist/EmailDeliveryChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmailDeliveryChannel.js","sourceRoot":"","sources":["../src/EmailDeliveryChannel.ts"],"names":[],"mappings":"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"}

package/dist/EntitlementBehavior.d.ts

@@ -0,0 +1,235 @@
+/**
+ * What a purchase grants, and for how long — the arithmetic, with no database in sight.
+ *
+ * A `ProductEntitlement` is a TEMPLATE: this product confers this feature, access level, or resource
+ * quantity. An `EntitlementGrant` is the INSTANCE created when somebody buys it, carrying a
+ * beneficiary and a validity window. This module decides what that instance should look like.
+ *
+ * THREE SETTINGS, ONE WALK (D76). Timing, quantity and validity are all configurable per deployment,
+ * and all three resolve down the SAME chain taxability uses:
+ *
+ *     product → its category → that category's ancestors → the product type
+ *
+ * Nullable at product and category so "ask my parent" is sayable; NOT NULL at the type so the walk
+ * always terminates with a real answer. Sharing the chain is deliberate rather than tidy: anyone who
+ * understands how taxability resolves already understands this, and the two cannot drift into
+ * disagreeing about what "the product's category tree" means.
+ *
+ * WHY VALIDITY IS DIFFERENT FROM THE OTHER TWO. It is read from the `ProductEntitlement` FIRST and
+ * from the walk only when the template is silent, because one product can grant two entitlements with
+ * different windows. A course might give perpetual access to the downloadable materials and ninety
+ * days in the discussion forum. A policy resolved purely from the product could not say that.
+ *
+ * THE NON-SUBSCRIPTION CASES ARE THE INTERESTING ONES. It is tempting to assume access follows a
+ * subscription term, because that is the case with the most moving parts. But the commonest grants
+ * have nothing to do with subscriptions at all: a digital download is good forever, and a ticket to
+ * an online event is good for the length of the event and not a minute longer.
+ *
+ * CONNECTS TO:
+ *   SERVER: ./EntitlementEngine.ts (the lookups and the writes)
+ *   CALLER: OrderEntityServer (grants are created inside the booking transaction)
+ *   MIRROR: ./TaxResolver.ts — the same walk, for the same reason
+ *   DOC:    plans/archive/bizapps-orders-master.md D27, D76
+ */
+/** When access begins. */
+export type GrantTiming = 'OnConfirm' | 'OnPaidInFull' | 'OnActivation';
+/** How the template quantity relates to the line quantity. */
+export type QuantityMode = 'PerUnit' | 'Flat';
+/** How long access lasts. */
+export type ValidityMode = 'Perpetual' | 'EventWindow' | 'FixedDuration' | 'SubscriptionTerm';
+/** Where in the chain an answer came from. Recorded because "nobody said" differs from "it said no". */
+export type PolicyLevel = 'ProductEntitlement' | 'Product' | 'ProductCategory' | 'ProductType';
+export interface EntitlementPolicySource {
+    EntitlementGrantTiming: GrantTiming | null;
+    EntitlementQuantityMode: QuantityMode | null;
+    EntitlementValidityMode: ValidityMode | null;
+}
+/** One level of the category tree. Callers build these NEAREST FIRST. */
+export interface PolicyCategoryLevel extends EntitlementPolicySource {
+    ID: string;
+}
+/** The type's answers are NOT NULL — this is what makes the walk terminate. */
+export interface PolicyTypeDefaults {
+    DefaultEntitlementGrantTiming: GrantTiming;
+    DefaultEntitlementQuantityMode: QuantityMode;
+    DefaultEntitlementValidityMode: ValidityMode;
+}
+export interface ResolvedEntitlementPolicy {
+    GrantTiming: GrantTiming;
+    QuantityMode: QuantityMode;
+    ValidityMode: ValidityMode;
+    /** Which level decided each one, for the support question "why did this happen?". */
+    DecidedAt: {
+        GrantTiming: PolicyLevel;
+        QuantityMode: PolicyLevel;
+        ValidityMode: PolicyLevel;
+    };
+}
+/**
+ * Walk the chain for all three settings at once.
+ *
+ * ONE walk rather than three, because they resolve identically and a caller that walked separately
+ * would do the same lookups three times and could be given three different category chains.
+ *
+ * `entitlement` is consulted for VALIDITY ONLY — see the module header. Timing and quantity are
+ * properties of the purchase, not of the individual thing granted: it would make no sense for one
+ * entitlement on a line to appear at confirm and another to wait for payment.
+ */
+export declare function ResolveEntitlementPolicy(product: EntitlementPolicySource, 
+/** NEAREST FIRST: the product's own category, then its parent, up to the root. */
+categoryChain: PolicyCategoryLevel[], type: PolicyTypeDefaults, entitlement?: {
+    ValidityMode: ValidityMode | null;
+} | null): ResolvedEntitlementPolicy;
+/**
+ * How much of the entitlement this line grants.
+ *
+ * `PerUnit` multiplies, so three 5-seat packs give fifteen seats — which is what somebody buying
+ * three packs expects. `Flat` ignores the line quantity entirely, for entitlements that are not
+ * countable: "access to the member portal" does not become three portals.
+ *
+ * ROUNDED UP, and only ever up. A prorated subscription line carries a fractional quantity (0.5833
+ * for a short first period), and 0.5833 × 5 seats is 2.9165. Rounding down hands the customer two
+ * seats for a five-seat product and generates a support ticket; rounding up hands them three and
+ * generates nothing. Under-granting is the expensive direction, exactly as under-collecting is with
+ * tax, and for the same reason: the customer notices.
+ *
+ * A null template quantity means the entitlement is not a countable thing (a Feature or AccessLevel
+ * rather than a ResourceQuantity), and stays null rather than becoming zero — zero would read as
+ * "granted none of it".
+ */
+export declare function ResolveGrantQuantity(templateQuantity: number | null, lineQuantity: number, mode: QuantityMode): number | null;
+/** Everything a validity window might need to know, so the pure function needs no lookups. */
+export interface ValidityContext {
+    /** When the grant takes effect — normally the order date. */
+    GrantedOn: Date;
+    /** FixedDuration only. */
+    DurationDays?: number | null;
+    /** EventWindow only: the event's own dates, and how far either side access opens. */
+    EventStartsAt?: Date | null;
+    EventEndsAt?: Date | null;
+    AccessLeadHours?: number | null;
+    AccessLagHours?: number | null;
+    /** SubscriptionTerm only. */
+    TermStartDate?: Date | null;
+    TermEndDate?: Date | null;
+}
+export interface ResolvedValidity {
+    ValidFrom: Date;
+    /** NULL means perpetual. A grant with no end is a real thing, not a missing value. */
+    ValidTo: Date | null;
+    ModeApplied: ValidityMode;
+}
+/**
+ * Turn a validity mode plus its context into an actual window.
+ *
+ * FALLS BACK RATHER THAN THROWING when a mode's own inputs are missing, and records what it actually
+ * applied. A ticket whose product has no event dates should not fail the customer's order — but the
+ * grant must not silently claim to be an event window either, so `ModeApplied` says `Perpetual` and
+ * an auditor can see the mode was requested and could not be honoured.
+ *
+ * The one thing it will not do is produce a window that ends before it starts. An event whose end
+ * date precedes its start, or a lag that somehow lands behind the lead, yields a window ending at its
+ * own start — an instantaneous grant, which reads as "nothing was granted" and is at least honest,
+ * rather than a negative window the database CHECK would reject at insert time with an error naming
+ * neither the product nor the event.
+ */
+export declare function ResolveValidityWindow(mode: ValidityMode, ctx: ValidityContext): ResolvedValidity;
+/**
+ * Should the grant be ACTIVE yet, given when access is supposed to begin?
+ *
+ * The grant row is written at confirm either way — downstream apps poll grants (D27), and a grant
+ * that does not exist until payment clears cannot be seen coming. What timing changes is the STATUS:
+ *
+ *   OnConfirm     Active immediately. A confirmed order is a claim on the seller.
+ *   OnPaidInFull  Suspended until the order's balance reaches zero. Access follows cash.
+ *   OnActivation  Suspended until something explicitly activates it. Note that nothing does yet —
+ *                 this exists because it was asked for, and a deployment choosing it is choosing to
+ *                 grant nothing until it builds the caller.
+ *
+ * `Suspended` rather than a missing row, and rather than `Revoked`: revoked means somebody took it
+ * away, which is a different fact that an access dispute turns on.
+ */
+export declare function InitialGrantStatus(timing: GrantTiming, order: {
+    Balance: number | null;
+    TotalGross: number | null;
+}): 'Active' | 'Suspended';
+/**
+ * How much of a grant survives a partial return.
+ *
+ * A customer who bought five seats and sent two back keeps three. Returning everything revokes the
+ * grant outright rather than leaving a zero-quantity row, because zero is indistinguishable from a
+ * Feature grant that never had a quantity.
+ */
+export declare function ReduceGrantForReturn(grantQuantity: number | null, originalLineQuantity: number, returnedQuantity: number): {
+    Quantity: number | null;
+    Revoke: boolean;
+};
+/** Why a check granted or refused. Collapsing these to a boolean loses the support conversation. */
+export type EntitlementDecision = 'Granted' | 'NoGrant' | 'NotYetValid' | 'Expired' | 'Revoked' | 'Suspended' | 'SubscriptionInactive';
+/** The facts a grant row carries that the evaluator needs — no database. */
+export interface GrantAccessFacts {
+    Status: string;
+    ValidFrom: Date | null;
+    ValidTo: Date | null;
+    /** True when `EntitlementGrant.SubscriptionID` is set. Missing subscription row → fail closed. */
+    LinkedToSubscription?: boolean;
+    /** True when `EntitlementGrant.SubscriptionTermID` is set. Missing term row → fail closed. */
+    LinkedToTerm?: boolean;
+}
+/** Subscription facts that can cut access short or extend it through grace. */
+export interface SubscriptionAccessFacts {
+    Status: string;
+    /**
+     * When the subscription is `Canceled`, this is access-through (`EndDate` stamped from
+     * `CancellationDecision.AccessThroughDate`). Ignored while the sub is Active/Trialing.
+     */
+    EndDate: Date | null;
+}
+export interface TermAccessFacts {
+    Status: string;
+    StartDate: Date;
+    EndDate: Date;
+}
+export interface GrantAccessEvaluation {
+    HasAccess: boolean;
+    Decision: EntitlementDecision;
+    ValidFrom: Date | null;
+    ValidTo: Date | null;
+}
+/**
+ * Is this grant in force at `asOf`?
+ *
+ * ONE function, because a second “is this in force” will drift from the first — that failure
+ * has already bitten this codebase twice. Bounds are inclusive: access holds at the exact
+ * `ValidFrom` / `ValidTo` / cancel `EndDate` instant.
+ *
+ * Cancelled subscriptions are the interesting case. The grant's `ValidTo` is the original term
+ * end, which is a LIE after an immediate cancel: access-through is `subscription.EndDate`
+ * (grace included). Grace can also EXTEND past `ValidTo`. Either way, `EndDate` is the bound
+ * once the sub is `Canceled`. Paused/Migrated refuse immediately — they have no grace story.
+ */
+export declare function EvaluateGrantAccess(grant: GrantAccessFacts, asOf: Date, subscription?: SubscriptionAccessFacts | null, term?: TermAccessFacts | null): GrantAccessEvaluation;
+export interface RankableAccess {
+    HasAccess: boolean;
+    Decision: EntitlementDecision;
+    ValidTo: Date | null;
+}
+/**
+ * One answer from many grants for the same Code. A Granted perpetual beats a Granted with an
+ * end; among denials the most useful reason wins, not the most recent row.
+ */
+export declare function PickWinningAccess<T extends RankableAccess>(results: T[]): T | null;
+/** Default CacheUntil cap for a check answer. Short so a revoke is felt quickly. */
+export declare const ENTITLEMENT_CHECK_TTL_MS = 60000;
+/**
+ * When the caller may reuse this answer. Never past `ValidTo` on a grant that is in force —
+ * caching a Granted past its own end is how paid content stays open after the window closed.
+ */
+export declare function CacheUntilFor(evaluatedAt: Date, validTo: Date | null | undefined, hasAccess: boolean): Date;
+/**
+ * After `Orders.CancelSubscription`, stored grant Status is a lie unless we revoke when
+ * access has already ended. Grace (`AccessThroughDate` in the future) leaves the rows
+ * standing — the evaluator honours `subscription.EndDate`.
+ */
+export declare function ShouldRevokeGrantsOnCancel(accessThroughDate: Date, now: Date): boolean;
+//# sourceMappingURL=EntitlementBehavior.d.ts.map

package/dist/EntitlementBehavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntitlementBehavior.d.ts","sourceRoot":"","sources":["../src/EntitlementBehavior.ts"],"names":[],"mappings":"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"}