@phis/contracts 0.5.0 → 0.7.0

package/dist/payments.d.ts

@@ -0,0 +1,385 @@
+/**
+ * The approved v1 Payment agreement. Core owns execution; consumers own prices and commerce.
+ *
+ * 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;
+export type PhisPaymentRefundId = string;
+export type PhisPaymentMoney = {
+    /** Uppercase ISO currency code; one agreed currency for the whole payment. */
+    currency: string;
+    /** Canonical non-negative integer string of minor units, never floating-point money. */
+    minor: string;
+};
+export type PhisPaymentCaptureMode = "automatic" | "manual";
+export type PhisPaymentCheckoutKind = "redirect" | "provider-ui";
+export type PhisPaymentFeatures = {
+    captureModes: readonly PhisPaymentCaptureMode[];
+    checkoutKinds: readonly PhisPaymentCheckoutKind[];
+    canPartialCapture: boolean;
+    canCancel: boolean;
+    canRefund: boolean;
+    canPartialRefund: boolean;
+    pricing: PhisPaymentPricingFeatures;
+};
+export type PhisPaymentMethod = {
+    profileKey: string;
+    methodKey: string | null;
+    title: string;
+    features: PhisPaymentFeatures;
+};
+export type PhisPaymentCheckoutPlan = {
+    kind: "redirect";
+    url: string;
+    expiresAt: string | null;
+} | {
+    kind: "provider-ui";
+    moduleId: string;
+    adapterKey: string;
+    parameters: Readonly<Record<string, string>>;
+    expiresAt: string | null;
+};
+export type PhisPaymentStatus = "created" | "awaiting_customer" | "processing" | "authorized" | "captured" | "canceled" | "expired" | "failed";
+export type PhisPayment = {
+    id: PhisPaymentId;
+    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;
+    capturedMinor: string;
+    refundedMinor: string;
+    authorizationExpiresAt: string | null;
+    checkout: PhisPaymentCheckoutPlan | null;
+    reconciliationRequired: boolean;
+    version: number;
+    lastObservedAt: string | null;
+};
+export type PhisPaymentErrorCode = "invalid_input" | "not_found" | "forbidden" | "profile_unavailable" | "method_unavailable" | "unsupported_operation" | "invalid_state" | "active_attempt_exists" | "idempotency_conflict" | "payment_declined" | "provider_rejected" | "provider_unavailable" | "reconciliation_required";
+export type PhisPaymentOperation = {
+    id: PhisPaymentOperationId;
+    paymentId: PhisPaymentId;
+    action: "create" | "complete" | "capture" | "cancel" | "refund";
+    state: "reserved" | "pending" | "succeeded" | "failed" | "indeterminate";
+    errorCode: PhisPaymentErrorCode | null;
+};
+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 = {
+    operation: PhisPaymentOperation;
+    payment: PhisPayment;
+    refund: PhisPaymentRefund | null;
+};
+export type PhisPaymentCreateInput = {
+    profileKey: string;
+    reference: string;
+    idempotencyKey: string;
+    amount: PhisPaymentMoney;
+    pricing: PhisPaymentPricing;
+    description: string;
+    captureMode: PhisPaymentCaptureMode;
+    methodKey: string | null;
+    checkoutKind: PhisPaymentCheckoutKind;
+    returnPath: string;
+};
+export type PhisPaymentCommandInput = {
+    paymentId: PhisPaymentId;
+    idempotencyKey: string;
+};
+export interface PhisPaymentsCapabilityV1 {
+    listMethods(input: {
+        profileKey: string;
+        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>;
+    get(paymentId: PhisPaymentId): Promise<PhisPayment | null>;
+    getOperation(operationId: PhisPaymentOperationId): Promise<PhisPaymentOperation | null>;
+    getRefund(refundId: PhisPaymentRefundId): Promise<PhisPaymentRefund | null>;
+    /** Customer continuation; never captures a manually authorized payment. */
+    complete(input: PhisPaymentCommandInput): Promise<PhisPaymentCommandResult>;
+    /** Explicit bounded reconciliation that may update state and enqueue a consumer event. */
+    refresh(paymentId: PhisPaymentId): Promise<PhisPayment | null>;
+    /** One final merchant-authorized capture; minor units inherit the stored currency. */
+    capture(input: PhisPaymentCommandInput & {
+        minor: string;
+    }): Promise<PhisPaymentCommandResult>;
+    cancel(input: PhisPaymentCommandInput): Promise<PhisPaymentCommandResult>;
+    /** Merchant-authorized refund; pending/unknown amounts reserve the captured balance. */
+    refund(input: PhisPaymentCommandInput & {
+        minor: string;
+        reason: string;
+    }): Promise<PhisPaymentCommandResult>;
+}
+export type PhisPaymentProviderConfigV1 = {
+    profileKey: string;
+    mode: "test" | "live";
+    merchantIdentity: string | null;
+};
+export type PhisPaymentProviderContextV1 = {
+    providerKey: string;
+    readCredentials(): Promise<Readonly<Record<string, string>> | null>;
+};
+export type PhisPaymentProviderBinding = {
+    reference: string;
+    data: Readonly<Record<string, string>>;
+};
+export type PhisPaymentProviderProbe = {
+    merchantIdentity: string;
+    mode: "test" | "live";
+    methods: readonly Omit<PhisPaymentMethod, "profileKey">[];
+};
+export type PhisPaymentProviderObservation = {
+    binding: PhisPaymentProviderBinding;
+    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;
+    checkout: PhisPaymentCheckoutPlan | null;
+    /** Complete refund observations, including remote refunds created outside Core. */
+    refunds: readonly {
+        operationId: PhisPaymentOperationId | null;
+        binding: PhisPaymentProviderBinding;
+        minor: string;
+        status: PhisPaymentRefund["status"];
+        additions: readonly PhisPaymentAddition[] | null;
+    }[];
+};
+export type PhisPaymentProviderCommand = {
+    operationId: PhisPaymentOperationId;
+    paymentId: PhisPaymentId;
+    providerIdempotencyKey: string;
+    signal: AbortSignal;
+} & ({
+    action: "create";
+    amount: PhisPaymentMoney;
+    pricing: PhisPaymentPricing;
+    description: string;
+    captureMode: PhisPaymentCaptureMode;
+    methodKey: string | null;
+    checkoutKind: PhisPaymentCheckoutKind;
+    returnUrl: string;
+    notificationUrl: string;
+} | {
+    action: "complete" | "cancel";
+    binding: PhisPaymentProviderBinding;
+} | {
+    action: "capture";
+    binding: PhisPaymentProviderBinding;
+    minor: string;
+} | {
+    action: "refund";
+    binding: PhisPaymentProviderBinding;
+    minor: string;
+    reason: string;
+});
+export type PhisPaymentProviderExecution = {
+    outcome: "applied" | "pending";
+    observation: PhisPaymentProviderObservation;
+} | {
+    outcome: "rejected";
+    code: PhisPaymentErrorCode;
+} | {
+    outcome: "unknown";
+};
+export type PhisPaymentProviderNotification = {
+    outcome: "verified";
+    deliveryId: string;
+    reference: string;
+} | {
+    outcome: "lookup-required";
+    reference: string;
+} | {
+    outcome: "irrelevant";
+} | {
+    outcome: "rejected";
+} | {
+    outcome: "unavailable";
+};
+export interface PhisPaymentProviderV1 {
+    probe(input: {
+        amount: PhisPaymentMoney;
+        captureMode: PhisPaymentCaptureMode;
+        checkoutKind: PhisPaymentCheckoutKind;
+        pricing: PhisPaymentPricingSelector;
+        signal: AbortSignal;
+    }): Promise<PhisPaymentProviderProbe>;
+    execute(input: PhisPaymentProviderCommand): Promise<PhisPaymentProviderExecution>;
+    observe(input: {
+        binding: PhisPaymentProviderBinding;
+        signal: AbortSignal;
+    }): Promise<PhisPaymentProviderObservation>;
+    /** Recover the same command; never replace its key, merchant, mode or Provider. */
+    recover(input: {
+        command: PhisPaymentProviderCommand;
+        binding: PhisPaymentProviderBinding | null;
+    }): Promise<PhisPaymentProviderExecution>;
+    verifyNotification(input: {
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        body: Uint8Array;
+        signal: AbortSignal;
+    }): Promise<PhisPaymentProviderNotification>;
+}
+export interface PhisPaymentNotificationsCapabilityV1 {
+    receive(input: {
+        profileKey: string;
+    }): Promise<{
+        outcome: "processed" | "duplicate" | "ignored";
+    }>;
+}
+export type PhisPaymentGrantedOperation = "read" | "create" | "complete" | "refresh" | "capture" | "cancel" | "refund";
+export type PhisPaymentMerchantActionPolicy = {
+    roles: readonly string[];
+    jobs: readonly string[];
+    events: readonly string[];
+};
+export type PhisPaymentProfileGrant = {
+    consumerAddonId: string;
+    operations: readonly PhisPaymentGrantedOperation[];
+    merchantActions: {
+        capture: PhisPaymentMerchantActionPolicy;
+        cancel: PhisPaymentMerchantActionPolicy;
+        refund: PhisPaymentMerchantActionPolicy;
+    };
+};
+/** Operator-controlled references and grants; contains no credential values. */
+export type PhisPaymentProfileDraft = {
+    key: string;
+    providerKey: string;
+    mode: "test" | "live";
+    credentialReferences: Readonly<Record<string, string>>;
+    grants: readonly PhisPaymentProfileGrant[];
+};
+/** A payment event reaches only the consuming Add-on stored on that payment. */
+export type PhisPaymentChangedEventFacts = {
+    event: "payment.changed";
+    subject: {
+        kind: "payment";
+        paymentId: PhisPaymentId;
+        reference: string;
+        version: number;
+        operationId: PhisPaymentOperationId | null;
+        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

@@ -0,0 +1,12 @@
+/**
+ * The approved v1 Payment agreement. Core owns execution; consumers own prices and commerce.
+ *
+ * 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/references.d.ts

@@ -98,6 +98,15 @@ export type PhiLinkTarget = {
      * goes. Whether the reader may follow it is still the target Area's own answer.
      */
     area?: PhiCmsAreaKey;
+    /**
+     * The values of the Page's route parameters, where its route has any (`/news/:slug`).
+     *
+     * A reference names the route and not one address of it, so a link to one entry of a family of
+     * Pages states which: `{ slug: "launch" }`. The resolver answers the route's pattern, and the link
+     * fills it from here and from what its caller adds -- a list that links each of its entries states
+     * the route once and the value per entry. A parameter nobody fills leaves no link at all.
+     */
+    params?: Readonly<Record<string, string>>;
     fragment?: string | null;
     newTab?: boolean;
 } | {
@@ -121,10 +130,10 @@ export declare const PHI_LINK_TARGET_CONFIG_KEY = "linkTarget";
 export declare function isPhiLinkTargetConfigKey(key: string): boolean;
 export declare function isPhiStorableExternalHref(value: string): boolean;
 /**
- * A stored link target, read back under the contract rather than trusted.
+ * A route pattern with its parameters filled, or `null` while one is still open.
  *
- * Anything that is not one of the two shapes answers `null`, and a Control that gets `null` draws no
- * link at all. That is the same answer the contract gives for a Page reference that no longer resolves:
- * non-interactive text beats a link that goes somewhere nobody chose.
+ * Each value is one path segment, encoded as one: a slug with a slash in it cannot step into another
+ * route. A pattern without parameters comes back as it is.
  */
+export declare function fillPhiRouteParams(pattern: string, params: Readonly<Record<string, string>> | null | undefined): string | null;
 export declare function readPhiLinkTarget(value: unknown): PhiLinkTarget | null;

package/dist/references.js

@@ -174,6 +174,37 @@ export function isPhiStorableExternalHref(value) {
  * link at all. That is the same answer the contract gives for a Page reference that no longer resolves:
  * non-interactive text beats a link that goes somewhere nobody chose.
  */
+const PHI_ROUTE_PARAM_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/u;
+/** Route parameter values as a target stores them: names a route can declare, non-empty string values. */
+function readPhiRouteParams(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const entries = Object.entries(value).flatMap(([name, entry]) => PHI_ROUTE_PARAM_NAME_PATTERN.test(name) && typeof entry === "string" && entry.trim()
+        ? [[name, entry.trim()]]
+        : []);
+    return entries.length > 0 ? Object.fromEntries(entries) : null;
+}
+/**
+ * A route pattern with its parameters filled, or `null` while one is still open.
+ *
+ * Each value is one path segment, encoded as one: a slug with a slash in it cannot step into another
+ * route. A pattern without parameters comes back as it is.
+ */
+export function fillPhiRouteParams(pattern, params) {
+    let open = false;
+    const filled = pattern.split("/").map((segment) => {
+        if (!segment.startsWith(":"))
+            return segment;
+        const value = params?.[segment.slice(1)];
+        if (!value) {
+            open = true;
+            return segment;
+        }
+        return encodeURIComponent(value);
+    }).join("/");
+    return open ? null : filled;
+}
 export function readPhiLinkTarget(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return null;
@@ -192,10 +223,12 @@ export function readPhiLinkTarget(value) {
          * the asking Area is the behaviour of every link that names none, which is the honest default.
          */
         const area = isPhiCmsAreaKey(record.area) ? { area: record.area } : {};
+        const params = readPhiRouteParams(record.params);
         return {
             kind: "page",
             reference: parsed.reference,
             ...area,
+            ...(params ? { params } : {}),
             ...(fragment ? { fragment } : {}),
             ...newTab,
         };

package/dist/resource-links.d.ts

@@ -59,8 +59,9 @@ export type PhisResourceLink = {
  *
  * Bounded twice: to this Add-on's own links, and to subjects the acting user may reach. Writing needs
  * an actor -- a link is a person saying these two things belong together, and it is what later lets the
- * Add-on act with no person there. A hook or a job may read the links it wrote and may not make new
- * ones.
+ * Add-on act with no person there. A hook or a job may read the links it wrote and may make new ones only
+ * on what it opened itself: a thread it owns -- or a ticket or task whose thread it owns -- it reaches
+ * already, so a link there grants nothing that needed anybody's consent.
  */
 export type PhisResourceLinksCapabilityV1 = {
     /** This Add-on's links on one subject, or none where the subject is out of reach. */
@@ -68,8 +69,10 @@ export type PhisResourceLinksCapabilityV1 = {
     /**
      * Records a reference, or hands back the one that is already there.
      *
-     * Asking twice is how an id is learned, the way a declared group is: `(type, externalId)` is unique
-     * within this Add-on and this Site, so a second call answers with the first link instead of failing.
+     * Asking twice is how an id is learned, the way a declared group is: `(subject, type, externalId)` is
+     * unique within this Add-on and this Site, so a second call for the same subject answers with the first
+     * link instead of failing. One external record may be linked from several subjects -- one issue that
+     * several tickets wait on -- and each of those links is its own.
      */
     link(input: {
         subject: PhisResourceLinkSubject;
@@ -86,9 +89,12 @@ export type PhisResourceLinksCapabilityV1 = {
     }): Promise<boolean>;
     /** Removes a link, and with it whatever actorless reach it granted. */
     unlink(linkId: number): Promise<boolean>;
-    /** One link of this Add-on by the external id it recorded, or null. */
-    findByExternalId(input: {
+    /**
+     * Every link of this Add-on to one external record, oldest first: what an event about that record has
+     * to reach. Empty where none is recorded.
+     */
+    listByExternalId(input: {
         type: number;
         externalId: string;
-    }): Promise<PhisResourceLink | null>;
+    }): Promise<PhisResourceLink[]>;
 };

package/dist/schema.d.ts

@@ -235,6 +235,15 @@ export type PhisAddonAssetSlotDescriptor = {
      * newest of several would be a fact nobody asked for.
      */
     mirrorColumn?: string;
+    /**
+     * A role this Add-on declares, which the actor must hold to put a file in this slot, take one out,
+     * or list what it holds -- the same guard `requiresRole` is on a declared query, refused loudly.
+     *
+     * On an owner- or group-scoped table it narrows: the row's own authority still has to agree. On a
+     * table with neither, Core has no row to judge, so a slot there must state one, and the role is then
+     * the whole authority -- which is what lets a category icon or a shop logo carry a file at all.
+     */
+    requiresRole?: string;
 };
 export type PhisAddonTableDescriptor = {
     name: string;