@phis/contracts 0.6.0 → 0.7.1

package/README.md

@@ -4,6 +4,13 @@ The agreements phis (`@phis/server`) keeps with what surrounds it: the site UI (
 separately shipped Add-ons. Each lives under its own subpath, because they hold between different parties
 and change at different moments.
 
+> **Part of phis.** This package is one piece of a larger whole and does nothing on its own. A Phi
+> installation is the server [`@phis/server`](https://github.com/phis-dev/phis-server), installed as the
+> Debian package `phis` from `apt.phisys.com` (not from npm), plus Sites built on
+> [`@phis/ui`](https://github.com/phis-dev/phis-ui), which brings this package along. Installation and
+> documentation: [phis.dev](https://phis.dev). Install it directly only to build an Add-on or a Module
+> against these contracts.
+
 ```
 @phis/contracts/addon                what phis and a separately shipped Add-on promise each other
 @phis/contracts/payments             the approved Payment consumer, Provider and merchant-profile types

package/dist/addon.d.ts

@@ -199,6 +199,46 @@ export type PhisAddonEventHandlerDescriptor = {
     event: PhisAddonEventId;
     handler: string;
 };
+/**
+ * One sentence of an occasion, with the parameters it takes in order.
+ *
+ * `%1`, `%2`, ... in `text` stand for the named parameters, the way Core's own templates are written,
+ * so the sentence translates as one unit and the values are put in afterwards. A text parameter is
+ * escaped where it lands; a path parameter arrives as a link on the Site's own public address.
+ */
+export type PhisAddonOccasionLine = {
+    text: string;
+    parameters?: string[];
+};
+/**
+ * One kind of message this Add-on may ask Core to write to a person.
+ *
+ * Declared rather than composed at the call: the words are part of the manifest and therefore of the
+ * digest, so what a Site can say in an Add-on's name is readable at install and cannot change under a
+ * running Site. Core renders the lines through its own layout, salutation and translation, and adds
+ * what the class owes -- which is why an Add-on cannot produce a mail without Core's frame.
+ *
+ * `class` is `asked-for` and nothing else this release: the person's own action is the reason for the
+ * message (an order they placed, a request they made), no consent bit applies and no unsubscribe link
+ * is offered. The sent class -- a message somebody decided to send to people who did not ask today --
+ * is Core's own bulk case and is not declarable here until it is.
+ */
+export type PhisAddonOccasionDescriptor = {
+    /** `^[a-z][a-z0-9-]{0,63}$`; the name a `notify` call and the outbox row carry. */
+    name: string;
+    class: "asked-for";
+    description?: string;
+    subject: PhisAddonOccasionLine;
+    lines: PhisAddonOccasionLine[];
+    /**
+     * What a call must bring, by name. `text` is inserted as written; `path` is a Site-relative path
+     * (`/shop/order/1234`) that Core turns into an absolute link on the Site's public address.
+     */
+    parameters: {
+        name: string;
+        type: "text" | "path";
+    }[];
+};
 export type PhisAddonManifestV1 = {
     manifestVersion: typeof PHIS_ADDON_MANIFEST_VERSION;
     addonId: string;
@@ -260,6 +300,13 @@ export type PhisAddonManifestV1 = {
      * provider, and every write here refuses a group carrying anybody else's.
      */
     groupWriter?: PhisAddonGroupWriterDescriptor;
+    /**
+     * The occasions this Add-on may write to a person about. Absent means none, and `notify` then has
+     * nothing it could be asked for.
+     *
+     * Optional for the reason `settings` is: it arrived after the manifest version was in the wild.
+     */
+    occasions?: PhisAddonOccasionDescriptor[];
     /**
      * The Modules this package's other half contributes. Absent means it has no Module half.
      *

package/dist/capabilities.d.ts

@@ -107,6 +107,8 @@ export type PhisAddonCapabilities = {
     payments?: PhisPaymentsCapabilityV1;
     /** Supplied only to an original, bound Payment Provider hook request. */
     paymentNotifications?: PhisPaymentNotificationsCapabilityV1;
+    /** Writing to a person about an occasion this Add-on declared; Core owns the frame and the sending. */
+    notifications?: PhisNotificationsCapabilityV1;
 };
 /**
  * The roles capability: `@phis/server/roles:v1`.
@@ -224,6 +226,55 @@ export type PhisSecretsCapabilityV1 = {
 };
 /** Which secret `PhisSecretsCapabilityV1.read` names: the Site's own, or the one shared by all Sites. */
 export type PhisSecretScope = "site" | "addon";
+/**
+ * The notifications capability: `@phis/server/notifications:v1`.
+ *
+ * `notify` names **who** and **what happened**, and nothing about how. The occasion is one this Add-on
+ * declared in its manifest (`occasions`), so its words are sealed by the digest; Core resolves the
+ * address, picks the language, writes the salutation, renders the lines through its own layout and
+ * translation, chooses the sender, and sends -- through the outbox, with retry and a record. There is no
+ * subject, body, `from`, header or attachment on the call, because every one of those is a decision
+ * about how a Site speaks, and a Site speaks with one voice.
+ *
+ * Two recipients. A `user` is a member of this Site, named by id: the address is resolved when the
+ * message is sent, so a corrected address is used and a membership that is gone is not written to.
+ * A `contact` is a person who has no account here and gave this Add-on their address for exactly this
+ * purpose -- a guest who placed an order, somebody who filled in a form. It is the one place an Add-on
+ * hands Core an address, and it is admitted on two conditions Core enforces: the occasion is one the
+ * person's own action asked for (every declared occasion is, this release), and the locale is stated,
+ * because there is no profile to ask.
+ *
+ * `params` are values about the event, never about the person: a `text` parameter is inserted as
+ * written, a `path` parameter is a Site-relative path Core turns into an absolute link on the Site's own
+ * public address. An occasion cannot put an arbitrary URL into a Site's outgoing mail.
+ *
+ * Answers the outbox row's id, or `null` when `dedupeKey` named a message already written -- which is
+ * what makes a repeated run safe. Refused outright: an undeclared occasion, a parameter the occasion
+ * did not declare or lacks, a `user` who is not a member of this Site, and any call from an
+ * unverified hook, which may change nothing.
+ */
+export type PhisNotificationsCapabilityV1 = {
+    notify(input: PhisNotificationInput): Promise<{
+        notificationId: string | null;
+    }>;
+};
+export type PhisNotificationRecipient = {
+    kind: "user";
+    userId: number;
+    locale?: string | null;
+} | {
+    kind: "contact";
+    address: string;
+    locale: string;
+    name?: string | null;
+};
+export type PhisNotificationInput = {
+    occasion: string;
+    recipient: PhisNotificationRecipient;
+    params: Readonly<Record<string, string>>;
+    /** Unique within the Site; a second call with the same key writes nothing and answers `null`. */
+    dedupeKey?: string | null;
+};
 /**
  * What an Add-on may learn about a person.
  *

package/dist/core.d.ts

@@ -48,6 +48,8 @@ export declare const PHIS_CORE_CAPABILITIES: {
     readonly roles: "@phis/server/roles:v1";
     readonly payments: "@phis/server/payments:v1";
     readonly paymentNotifications: "@phis/server/payment-notifications:v1";
+    /** Writing to a person about an occasion the Add-on declared, with Core owning frame and transport. */
+    readonly notifications: "@phis/server/notifications:v1";
 };
 export type PhisCoreCapabilityId = (typeof PHIS_CORE_CAPABILITIES)[keyof typeof PHIS_CORE_CAPABILITIES];
 /**

package/dist/core.js

@@ -47,6 +47,8 @@ export const PHIS_CORE_CAPABILITIES = {
     roles: "@phis/server/roles:v1",
     payments: "@phis/server/payments:v1",
     paymentNotifications: "@phis/server/payment-notifications:v1",
+    /** Writing to a person about an occasion the Add-on declared, with Core owning frame and transport. */
+    notifications: "@phis/server/notifications:v1",
 };
 /**
  * What Core tells an Add-on about after the fact.

package/dist/payments.d.ts

@@ -4,6 +4,10 @@
  * Execution belongs to Core; its implemented capability, service and event identities live in core.ts.
  * These declarations contain no SDK, credentials, persistence or exchange-rate conversion. See phis-server's
  * PAYMENTS.md and PAYMENTS_STRIPE.md for authority, durability and Provider mapping requirements.
+ *
+ * `amount` is always the consumer's base amount. Under a pricing policy other than `final`/`none` the
+ * Provider adds tax, shipping and discounts on top of it and reports the customer's total with its parts
+ * (PAYMENTS.md section 12); authorized, captured and refunded funds are measured against that total.
  */
 export type PhisPaymentId = string;
 export type PhisPaymentOperationId = string;
@@ -23,6 +27,7 @@ export type PhisPaymentFeatures = {
     canCancel: boolean;
     canRefund: boolean;
     canPartialRefund: boolean;
+    pricing: PhisPaymentPricingFeatures;
 };
 export type PhisPaymentMethod = {
     profileKey: string;
@@ -47,7 +52,10 @@ export type PhisPayment = {
     reference: string;
     profileKey: string;
     mode: "test" | "live";
+    /** The consumer's base amount; the customer pays `totals.total` once the Provider reports it. */
     amount: PhisPaymentMoney;
+    pricing: PhisPaymentPricing;
+    totals: PhisPaymentTotals | null;
     captureMode: PhisPaymentCaptureMode;
     status: PhisPaymentStatus;
     authorizedMinor: string;
@@ -71,6 +79,8 @@ export type PhisPaymentRefund = {
     id: PhisPaymentRefundId;
     paymentId: PhisPaymentId;
     amount: PhisPaymentMoney;
+    /** The tax or discount share of this refund when the Provider reports one; informational. */
+    additions: readonly PhisPaymentAddition[] | null;
     status: "pending" | "succeeded" | "failed" | "canceled";
 };
 export type PhisPaymentCommandResult = {
@@ -83,6 +93,7 @@ export type PhisPaymentCreateInput = {
     reference: string;
     idempotencyKey: string;
     amount: PhisPaymentMoney;
+    pricing: PhisPaymentPricing;
     description: string;
     captureMode: PhisPaymentCaptureMode;
     methodKey: string | null;
@@ -99,6 +110,7 @@ export interface PhisPaymentsCapabilityV1 {
         amount: PhisPaymentMoney;
         captureMode: PhisPaymentCaptureMode;
         checkoutKind: PhisPaymentCheckoutKind;
+        pricing: PhisPaymentPricingSelector;
     }): Promise<readonly PhisPaymentMethod[]>;
     /** Core binds Site/consumer/profile; the consumer checks access to its business resource. */
     create(input: PhisPaymentCreateInput): Promise<PhisPaymentCommandResult>;
@@ -143,7 +155,10 @@ export type PhisPaymentProviderObservation = {
     merchantIdentity: string;
     mode: "test" | "live";
     status: PhisPaymentStatus;
+    /** The base amount as created; a Provider never changes it. */
     amount: PhisPaymentMoney;
+    /** Null only while the Provider cannot yet know the total; required from `authorized` on. */
+    totals: PhisPaymentObservedTotals | null;
     authorizedMinor: string;
     capturedMinor: string;
     authorizationExpiresAt: string | null;
@@ -154,6 +169,7 @@ export type PhisPaymentProviderObservation = {
         binding: PhisPaymentProviderBinding;
         minor: string;
         status: PhisPaymentRefund["status"];
+        additions: readonly PhisPaymentAddition[] | null;
     }[];
 };
 export type PhisPaymentProviderCommand = {
@@ -164,6 +180,7 @@ export type PhisPaymentProviderCommand = {
 } & ({
     action: "create";
     amount: PhisPaymentMoney;
+    pricing: PhisPaymentPricing;
     description: string;
     captureMode: PhisPaymentCaptureMode;
     methodKey: string | null;
@@ -211,6 +228,7 @@ export interface PhisPaymentProviderV1 {
         amount: PhisPaymentMoney;
         captureMode: PhisPaymentCaptureMode;
         checkoutKind: PhisPaymentCheckoutKind;
+        pricing: PhisPaymentPricingSelector;
         signal: AbortSignal;
     }): Promise<PhisPaymentProviderProbe>;
     execute(input: PhisPaymentProviderCommand): Promise<PhisPaymentProviderExecution>;
@@ -272,3 +290,96 @@ export type PhisPaymentChangedEventFacts = {
         refundId: PhisPaymentRefundId | null;
     };
 };
+export type PhisPaymentPricingBasis = "final" | "net";
+export type PhisPaymentTaxHandling = "none" | "provider" | "merchant-of-record";
+export type PhisPaymentPromotionCodes = "none" | "provider";
+/** What is sold, never a rate; each Provider maps the closed vocabulary to its own codes. */
+export type PhisPaymentTaxCategory = "general" | "reduced-goods" | "digital-goods" | "digital-service" | "service" | "shipping" | "exempt";
+export type PhisPaymentLineItem = {
+    reference: string;
+    description: string;
+    quantity: number;
+    unitMinor: string;
+    taxCategory: PhisPaymentTaxCategory;
+    /** Provider-specific code overriding the category mapping, keyed by provider key. */
+    providerTaxCodes: Readonly<Record<string, string>> | null;
+};
+/** A reduction the consumer decided; the Provider shows it and taxes the reduced amount. */
+export type PhisPaymentDiscount = {
+    reference: string;
+    label: string;
+    minor: string;
+};
+export type PhisPaymentCustomerDetails = {
+    country: string;
+    postalCode: string | null;
+    region: string | null;
+    addressSource: "billing" | "shipping";
+    taxIds: readonly {
+        type: string;
+        value: string;
+    }[];
+};
+/**
+ * `final`/`none` is v1: the base amount is what the customer pays and the Provider adds nothing. Every
+ * other policy carries line items; the base amount then equals their sum plus shipping minus discounts.
+ */
+export type PhisPaymentPricing = {
+    basis: "final";
+    tax: "none";
+} | {
+    basis: PhisPaymentPricingBasis;
+    tax: PhisPaymentTaxHandling;
+    lineItems: readonly PhisPaymentLineItem[];
+    shipping: {
+        minor: string;
+        taxCategory: "shipping";
+    } | null;
+    discounts: readonly PhisPaymentDiscount[];
+    promotionCodes: PhisPaymentPromotionCodes;
+    customer: PhisPaymentCustomerDetails | null;
+};
+/** The facts of a policy a method must support; `discounts` is the number of stated discounts. */
+export type PhisPaymentPricingSelector = {
+    basis: PhisPaymentPricingBasis;
+    tax: PhisPaymentTaxHandling;
+    discounts: number;
+    promotionCodes: PhisPaymentPromotionCodes;
+};
+export type PhisPaymentPricingFeatures = {
+    /** Always includes `final`. */
+    bases: readonly PhisPaymentPricingBasis[];
+    /** Always includes `none`. */
+    tax: readonly PhisPaymentTaxHandling[];
+    /** How many stated discounts one payment may carry; 0 when the Provider shows none. */
+    maxDiscounts: number;
+    /** Whether a customer may enter a code on the Provider's page, and whether next to stated discounts. */
+    promotionCodes: "none" | "alone" | "with-discounts";
+    collectsCustomerDetails: boolean;
+    collectsTaxIds: boolean;
+};
+export type PhisPaymentAdditionKind = "tax" | "shipping" | "discount";
+export type PhisPaymentAddition = {
+    kind: PhisPaymentAdditionKind;
+    minor: string;
+    label: string;
+    /** Contained in the base amount rather than added to it; a `discount` is never inclusive. */
+    inclusive: boolean;
+    /** Display-only decimal string such as "8.1"; never enters Core arithmetic. */
+    rate: string | null;
+    /** ISO country code, optionally followed by "-" and a region. */
+    jurisdiction: string | null;
+    /** Who owes a tax addition to the authority: the merchant, or the Provider as Merchant of Record. */
+    collectedBy: "merchant" | "provider";
+    /** The promotion code or stated discount reference behind a `discount`; null for every other kind. */
+    code: string | null;
+};
+export type PhisPaymentObservedTotals = {
+    total: PhisPaymentMoney;
+    additions: readonly PhisPaymentAddition[];
+    customer: PhisPaymentCustomerDetails | null;
+};
+export type PhisPaymentTotals = PhisPaymentObservedTotals & {
+    /** Set by Core when the total became binding; a differing total afterwards is an inconsistency. */
+    frozenAt: string | null;
+};

package/dist/payments.js

@@ -4,5 +4,9 @@
  * Execution belongs to Core; its implemented capability, service and event identities live in core.ts.
  * These declarations contain no SDK, credentials, persistence or exchange-rate conversion. See phis-server's
  * PAYMENTS.md and PAYMENTS_STRIPE.md for authority, durability and Provider mapping requirements.
+ *
+ * `amount` is always the consumer's base amount. Under a pricing policy other than `final`/`none` the
+ * Provider adds tax, shipping and discounts on top of it and reports the customer's total with its parts
+ * (PAYMENTS.md section 12); authorized, captured and refunded funds are measured against that total.
  */
 export {};

package/dist/queries.d.ts

@@ -84,6 +84,20 @@ export type PhisAddonQueryCondition = {
     column: string;
     negated?: boolean;
 }
+/**
+ * Whether bits of a flags column are set: every bit of `mask` (`all`), or none of them (`none`).
+ *
+ * Yes/no state is kept as bit flags rather than boolean columns, so "the rows that are not a draft"
+ * is a question about one bit of an integer. `compare` cannot ask it -- `=` sees the whole number --
+ * and without this an Add-on reads every row and filters in code, which also breaks paging: a page of
+ * 25 comes back with fewer. The mask is a positive integer; the column is an integer column.
+ */
+ | {
+    kind: "flags";
+    column: string;
+    mask: PhisAddonQueryValue;
+    match: "all" | "none";
+}
 /**
  * Whether a text column contains this fragment, case-insensitively.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phis/contracts",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "license": "Apache-2.0",
   "type": "module",
   "publishConfig": {
@@ -140,7 +140,7 @@
     "type": "git",
     "url": "git+https://github.com/phis-dev/phis-contracts.git"
   },
-  "homepage": "https://github.com/phis-dev/phis-contracts#readme",
+  "homepage": "https://phis.dev",
   "bugs": {
     "url": "https://github.com/phis-dev/phis-contracts/issues"
   }