@sixtyninecommerce/admin 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -65,7 +65,7 @@ export type { Metafield, MetafieldAttachment, MetafieldDefinition, MetafieldDefi
 export { METAFIELD_OWNER_TYPES, METAFIELD_SCALAR_TYPES } from './metafields/index.js';
 export type { OrderSettlement, OrdersModule } from './orders/index.js';
 export type { SurchargeCall, SurchargedOrder, SurchargeInput, SurchargesModule, } from './orders/surcharges.js';
-export type { OrderPaymentPosition, PaidOrder, PaymentsModule, ProviderConnection, ProviderCredentialPath, ProviderOnboardingStart, ProviderReadiness, ProvidersModule, ProviderTerminal, ProviderTerminalsModule, ProvisionTerminalInput, ReadinessOptions, RecordPaymentInput, } from './payments/index.js';
+export type { IssuedRefund, OrderPaymentPosition, OrderRefundPosition, PaidOrder, PaymentsModule, ProviderConnection, ProviderCredentialPath, ProviderOnboardingStart, ProviderReadiness, ProvidersModule, ProviderTerminal, ProviderTerminalsModule, ProvisionTerminalInput, ReadinessOptions, RecordPaymentInput, RefundablePayment, RefundPaymentInput, } from './payments/index.js';
 export type { AppKey, PlatformAppsModule, RegisterAppResult, RegisteredApp, } from './platform/apps.js';
 export { requireHumanSession } from './platform/guard.js';
 export type { PlatformModule, ProvisionProfile, ProvisionRun, ProvisionRunStatus, ProvisionStep, ProvisionStepStatus, ProvisionStoreInput, ProvisionStoreResult, } from './platform/provision-store.js';

package/dist/payments/index.d.ts

@@ -51,6 +51,92 @@ export interface RecordPaymentInput {
      */
     metadata?: Record<string, unknown>;
 }
+/**
+ * One payment's contribution to an order's refund position.
+ */
+export interface RefundablePayment {
+    paymentId: string;
+    /** Vendure's payment state. */
+    state: string;
+    /** The payment method code, or null when the payment carries no label. */
+    method: string | null;
+    /** Gross amount taken, minor units. */
+    amount: number;
+    /** Non-failed refunds already recorded against it. A failed refund never left. */
+    refunded: number;
+    /** `amount - refunded` when this payment took money, floored at zero; else zero. */
+    refundable: number;
+    /**
+     * Whether this payment took money at all.
+     *
+     * True for a settled payment and for an authorized one on a real gateway — a
+     * card sale at a terminal rests authorized until the webhook settles it, and
+     * that hold is real money. False for an authorized payment on an offline or
+     * net-terms method, where authorized means the money has NOT arrived.
+     */
+    tookMoney: boolean;
+}
+/**
+ * What an order may still hand back, in minor units of its own currency.
+ *
+ * A different question from {@link OrderPaymentPosition}, and the two disagree
+ * on purpose: that one nets refunds against every authorization because it
+ * answers "what is this order covered for", while this one counts only money
+ * that was actually TAKEN, because that is all a refund can return.
+ */
+export interface OrderRefundPosition {
+    /** The order's currency. Every amount here is in its minor units. */
+    currencyCode: string;
+    /** Money already given back out of money that was taken. */
+    refunded: number;
+    /**
+     * What may still be handed back for this order: the sum of every payment's
+     * own remaining headroom, each floored at zero.
+     *
+     * There is deliberately no credit-note deduction. A credit note that moved
+     * money already has its refund on the payment; one that moved none has
+     * nothing to deduct.
+     */
+    refundable: number;
+    /** Every payment on the order, NEWEST FIRST, with its own headroom. */
+    perPayment: RefundablePayment[];
+}
+/** Money handed back to a customer. */
+export interface RefundPaymentInput {
+    orderId: string;
+    /** Minor units of the order's currency. Greater than zero. */
+    amount: number;
+    /**
+     * The payment to return the money to.
+     *
+     * Omit it and the platform allocates across the order's paying payments
+     * NEWEST FIRST: it picks the most recent one whose remaining headroom can
+     * carry the WHOLE amount. A part-paid order settles its remainder last, so
+     * that is the money a merchant means by "give some of it back".
+     *
+     * **One call refunds against ONE payment.** When the order can return the
+     * amount but no single payment can, the call is refused with
+     * `REFUND_EXCEEDS_PAYMENT` and `perPayment` shows exactly how to split it —
+     * rather than the platform spilling silently onto a payment you did not name,
+     * which is what the engine would do.
+     */
+    paymentId?: string;
+    /** Free text stored on the refund. Shown to nobody automatically. */
+    reason?: string;
+}
+/** A refund, as this surface projects it. */
+export interface IssuedRefund {
+    id: string;
+    /** Minor units. */
+    total: number;
+    /** `Pending`, `Settled` or `Failed`. */
+    state: string;
+    /** The payment method the refund was booked against. */
+    method: string | null;
+    /** The gateway's own receipt, when it gave one. */
+    transactionId: string | null;
+    reason: string | null;
+}
 /** The order, as much of it as this surface projects. */
 export interface PaidOrder {
     id: string;
@@ -96,8 +182,63 @@ export interface PaymentsModule {
     record(orderId: string, input: RecordPaymentInput, options?: Call): Promise<PaidOrder>;
     /** Read an order's payment position. */
     position(orderId: string, options?: Call): Promise<OrderPaymentPosition>;
+    /**
+     * Hand money back to a customer, never more than the order took.
+     *
+     * The platform's own refund ceiling, and the one the four surfaces that issue
+     * refunds — returns settlement, credit notes, the till and the order importer
+     * — are measured against. Refuses `REFUND_EXCEEDS_SETTLED` when the amount is
+     * more than the whole ORDER can return, which is the check no per-payment
+     * arithmetic can make: another surface may have refunded the rest of it ten
+     * seconds ago.
+     *
+     * `options.idempotencyKey` is honoured — the Admin API takes it as a mutation
+     * argument — so a retry under the same key returns the FIRST call's refund
+     * instead of raising a second one. Use a fresh key per intended refund.
+     *
+     * **`IDEMPOTENCY_OUTCOME_UNKNOWN` is neither success nor refusal.** The engine
+     * calls the payment gateway from inside the transaction that writes the refund
+     * row, so a failure after that call leaves an outcome nobody can read off the
+     * database: the money may be on its way back with no row to show for it. You
+     * get this code on the FIRST call when that happens, and on every repeat under
+     * the same key — the key is spent rather than released, so the refund never
+     * runs again. Do NOT treat it as `REFUND_REFUSED`: read
+     * `payments.refundPosition(orderId)`, reconcile against the gateway, and only
+     * then decide. If the money did not move, issue a new request under a NEW key.
+     *
+     * (The server also attaches the position to that error, but `PlatformError`
+     * carries only `code`, `message`, `details` and `traceId`, so an SDK caller
+     * reads it with `refundPosition(orderId)` rather than off the error.)
+     *
+     * Only money that was TAKEN can come back: a settled payment, or an
+     * authorized one on a real gateway. An offline or net-terms authorization
+     * took nothing and is refused with `REFUND_PAYMENT_HOLDS_NO_MONEY`.
+     *
+     * **The refund you get back is one that moved money.** On an OFFLINE method —
+     * bank transfer, invoice, cash, an imported order's historical tender — it
+     * comes back `Settled`, because there the money moves by hand and recording
+     * it is the settlement. On a live gateway it comes back `Pending` and settles
+     * when the gateway calls back. A method whose handler cannot be resolved at
+     * all, because it is disabled or no longer on this store, is refused
+     * `REFUND_METHOD_UNAVAILABLE` before anything is created, with the payment and
+     * the method in `extensions.details`.
+     *
+     * Other refusals: `REFUND_EXCEEDS_PAYMENT` (the order can return this much,
+     * but no single payment can — split it, using `perPayment`),
+     * `REFUND_PAYMENT_NOT_FOUND`, `REFUND_AMOUNT_NOT_POSITIVE`,
+     * `REFUND_ORDER_NOT_FOUND`, and `REFUND_REFUSED` when the money was there and
+     * the engine or the gateway said no anyway. Every refusal raised once the
+     * order has been read carries that order's position in
+     * `extensions.refundPosition`, so a till can correct itself without a second
+     * round trip.
+     */
+    refund(input: RefundPaymentInput, options?: Call): Promise<IssuedRefund>;
+    /** Read what an order may still hand back. */
+    refundPosition(orderId: string, options?: Call): Promise<OrderRefundPosition>;
 }
 export declare const RECORD_ORDER_PAYMENT_MUTATION = "\n  mutation RecordOrderPayment($orderId: ID!, $input: RecordPaymentInput!, $idempotencyKey: String) {\n    recordOrderPayment(orderId: $orderId, input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  code\n  state\n  currencyCode\n  total\n  totalWithTax\n\n    }\n  }\n";
 export declare const ORDER_PAYMENT_POSITION_QUERY = "\n  query OrderPaymentPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      \n  total\n  covered\n  settled\n  authorized\n  refunded\n  outstanding\n  overpaid\n  availableToCharge\n\n    }\n  }\n";
+export declare const ORDER_REFUND_POSITION_QUERY = "\n  query OrderRefundPosition($orderId: ID!) {\n    orderRefundPosition(orderId: $orderId) {\n      \n  currencyCode\n  refunded\n  refundable\n  perPayment {\n    paymentId\n    state\n    method\n    amount\n    refunded\n    refundable\n    tookMoney\n  }\n\n    }\n  }\n";
+export declare const REFUND_ORDER_PAYMENT_MUTATION = "\n  mutation RefundOrderPayment($input: RefundPaymentInput!, $idempotencyKey: String) {\n    refundOrderPayment(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";
 export declare function createPaymentsModule(transport: Transport): PaymentsModule;
 export type { ProviderConnection, ProviderCredentialPath, ProviderOnboardingStart, ProviderReadiness, ProvidersModule, ProviderTerminal, ProviderTerminalsModule, ProvisionTerminalInput, ReadinessOptions, } from './providers.js';

package/dist/payments/index.js

@@ -31,6 +31,39 @@ export const ORDER_PAYMENT_POSITION_QUERY = /* GraphQL */ `
     }
   }
 `;
+const REFUND_POSITION_FIELDS = /* GraphQL */ `
+  currencyCode
+  refunded
+  refundable
+  perPayment {
+    paymentId
+    state
+    method
+    amount
+    refunded
+    refundable
+    tookMoney
+  }
+`;
+export const ORDER_REFUND_POSITION_QUERY = /* GraphQL */ `
+  query OrderRefundPosition($orderId: ID!) {
+    orderRefundPosition(orderId: $orderId) {
+      ${REFUND_POSITION_FIELDS}
+    }
+  }
+`;
+export const REFUND_ORDER_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation RefundOrderPayment($input: RefundPaymentInput!, $idempotencyKey: String) {
+    refundOrderPayment(input: $input, idempotencyKey: $idempotencyKey) {
+      id
+      total
+      state
+      method
+      transactionId
+      reason
+    }
+  }
+`;
 export function createPaymentsModule(transport) {
     return {
         providers: createProvidersModule(transport),
@@ -51,5 +84,20 @@ export function createPaymentsModule(transport) {
             const data = await transport.graphql({ api: 'admin', query: ORDER_PAYMENT_POSITION_QUERY, variables: { orderId } }, options);
             return data.orderPaymentPosition;
         },
+        async refund(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REFUND_ORDER_PAYMENT_MUTATION,
+                // Forwarded as a VARIABLE, not a header: the Admin API has no header
+                // for it. `undefined`, never an explicit null — `JSON.stringify` drops
+                // it, so an omitted key stays off the wire entirely.
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.refundOrderPayment;
+        },
+        async refundPosition(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_REFUND_POSITION_QUERY, variables: { orderId } }, options);
+            return data.orderRefundPosition;
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixtyninecommerce/admin",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Back-office SDK for sixtynine-commerce: every capability of the platform as a method",
   "homepage": "https://github.com/SIXTYNINE-digital/sixtynine-commerce-engine/tree/main/packages/admin-client#readme",
   "repository": {