@phis/contracts 0.4.0 → 0.6.0

package/dist/payments.d.ts

@@ -0,0 +1,274 @@
+/**
+ * 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.
+ */
+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;
+};
+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";
+    amount: PhisPaymentMoney;
+    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;
+    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;
+    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;
+    }): 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;
+    amount: PhisPaymentMoney;
+    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"];
+    }[];
+};
+export type PhisPaymentProviderCommand = {
+    operationId: PhisPaymentOperationId;
+    paymentId: PhisPaymentId;
+    providerIdempotencyKey: string;
+    signal: AbortSignal;
+} & ({
+    action: "create";
+    amount: PhisPaymentMoney;
+    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;
+        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;
+    };
+};

package/dist/payments.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export {};

package/dist/record.d.ts

@@ -0,0 +1,8 @@
+export declare function isPhiRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * The value a dotted path names inside a record: `"author.name"` reads `input.author.name`.
+ *
+ * Empty segments are skipped, so `""` names the input itself, and only records are walked -- an array
+ * or a primitive on the way ends the walk with `undefined` rather than being indexed into.
+ */
+export declare function readPhiDotPath(input: unknown, path: string): unknown;

package/dist/record.js

@@ -0,0 +1,24 @@
+/*
+ * Shared by the parsers of this package and not exported from it: each consumer keeps its own, and
+ * the one question they all answer is settled the same way -- an array is not a keyed record.
+ */
+export function isPhiRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * The value a dotted path names inside a record: `"author.name"` reads `input.author.name`.
+ *
+ * Empty segments are skipped, so `""` names the input itself, and only records are walked -- an array
+ * or a primitive on the way ends the walk with `undefined` rather than being indexed into.
+ */
+export function readPhiDotPath(input, path) {
+    let current = input;
+    for (const segment of path.split(".")) {
+        if (!segment)
+            continue;
+        if (!isPhiRecord(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}

package/dist/references.d.ts

@@ -0,0 +1,139 @@
+/**
+ * What one side of the house means when it points at a Page: `@phis/server/references:v1`.
+ *
+ * The codec stood in two copies, in phis-ui and in phi-server, for the same reason the CMS instance id
+ * did before it moved here -- and with the same risk, which is that two sides agreeing byte for byte is
+ * a thing nobody notices stopping. It is one file now.
+ *
+ * **A reference is short because a Page already has a name.** It used to be base64-encoded JSON carrying
+ * the whole identity, which for a Module Page ran to 98 characters in every Markdown body that linked to
+ * one. The envelope was never protection -- it is encoding, not a signature, and the server revalidates
+ * Site and Area regardless -- so what it actually bought was a payload the server could unpack. It no
+ * longer needs to: a Module Page is named by the CMS Page id derived from `(ownerModuleId, presetKey)`,
+ * which is recomputable rather than allocated and therefore stands before any row does.
+ *
+ * The two variants are shaped differently on purpose. A Site Page carries its Page Scope id as a plain
+ * number because the server writes that number into a foreign key with `ON DELETE RESTRICT`: the
+ * database itself refuses to delete a Page something still points at, and nothing derived could take
+ * that column's place. A Module Page has no row to point a foreign key at -- the Site may never have
+ * touched it -- so it carries the derived id, which the server passes on without ever unpacking.
+ */
+import { type PhiCmsAreaKey, type PhiCmsInstanceId } from "./cms.js";
+export declare const PHIS_INTERNAL_PAGE_SCHEME: "phis:page/";
+export declare const PHIS_INTERNAL_ASSET_SCHEME: "phis:asset/";
+/**
+ * A Module Page's identity, hashed to one token both sides can recompute.
+ *
+ * Recomputable rather than allocated, so no row has to exist before the Page can be addressed, and it
+ * never mentions the path: reassigning where a Page answers leaves everything pointing at it alone.
+ */
+export declare function createPhiPresetCmsPageId(identity: {
+    ownerModuleId: string;
+    presetKey: string;
+}): PhiCmsInstanceId;
+/** What a reference says, once read. A Module Page answers with its id, never with what was hashed. */
+export type PhiPageTarget = {
+    kind: "site";
+    pageScopeId: number;
+} | {
+    kind: "module";
+    pageId: PhiCmsInstanceId;
+};
+/** What a reference is made from. The Module variant differs: the identity goes in, the id comes out. */
+export type PhiPageTargetInput = {
+    kind: "site";
+    pageScopeId: number;
+} | {
+    kind: "module";
+    ownerModuleId: string;
+    presetKey: string;
+};
+export type PhiPageReference = string & {
+    readonly __phiPageReference: unique symbol;
+};
+export type PhiInternalReference = {
+    kind: "page";
+    reference: PhiPageReference;
+    target: PhiPageTarget;
+    fragment: string | null;
+} | {
+    kind: "asset";
+    assetId: number;
+};
+export declare function createPhiPageReference(target: PhiPageTargetInput): PhiPageReference;
+export declare function readPhiPageReference(value: unknown): {
+    reference: PhiPageReference;
+    target: PhiPageTarget;
+} | null;
+export declare function createPhiPageUri(reference: PhiPageReference, fragment?: string | null): string;
+export declare function createPhiAssetUri(assetId: number): string;
+export declare function readPhiInternalReference(value: unknown): PhiInternalReference | null;
+/**
+ * Where a Control that offers one link leads.
+ *
+ * Two kinds and no third. A Page is named by its reference, which is identity and outlives the path
+ * moving under it; everything else is a literal URL somebody typed. What this refuses is the middle --
+ * the root-relative string that reads as external and means internal -- because that is the shape that
+ * rots in silence: the Page moves, the string does not, and nothing in the system ever knew the two were
+ * related.
+ *
+ * `newTab` sits inside the target rather than beside it. A Widget that offers two links -- a Card with a
+ * heading and an action -- otherwise grows one flag per link and names them in parallel (`newTab`,
+ * `actionNewTab`, and a third the day a third link lands). That is one decision written twice, and it
+ * drifts the first time only one of the two is read.
+ */
+export type PhiLinkTarget = {
+    kind: "page";
+    reference: PhiPageReference;
+    /**
+     * Which Area to resolve the reference in, where it is not the one asking.
+     *
+     * A reference names a Page and not where to look for it: the Area is resolution context, supplied
+     * by whoever asks. Every asker supplied its own, so a link out of one Area into another resolved
+     * to nothing -- the Navigation source tree let an author pick a Page from another Area, the drop
+     * kept it, and the table then showed it as unresolvable.
+     *
+     * Absent means the asking Area, which is nearly every link, so nothing is stored for the ordinary
+     * case. Present, it does not make the reference mean something else; it says where the question
+     * 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;
+} | {
+    kind: "external";
+    href: string;
+    newTab?: boolean;
+};
+/**
+ * The field names a stored link target may stand under, and nothing else identifies one in persisted
+ * config.
+ *
+ * The Asset rule is the precedent and the reason: the server's reference collector reads persisted JSON,
+ * not the Widget catalogue, so it cannot ask a plugin which of its fields hold targets. A Widget that
+ * keeps one under another name authors a reference the delete guard cannot see, and the Page it points
+ * at can be removed while the Widget still draws a link to it.
+ *
+ * One plain name for the single-link case and a suffix for the rest, so a Card's second link is
+ * `actionLinkTarget` and is found by the same rule that finds the first.
+ */
+export declare const PHI_LINK_TARGET_CONFIG_KEY = "linkTarget";
+export declare function isPhiLinkTargetConfigKey(key: string): boolean;
+export declare function isPhiStorableExternalHref(value: string): boolean;
+/**
+ * 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 declare function fillPhiRouteParams(pattern: string, params: Readonly<Record<string, string>> | null | undefined): string | null;
+export declare function readPhiLinkTarget(value: unknown): PhiLinkTarget | null;