@sixtyninecommerce/admin 0.7.0 → 0.9.0

package/dist/payments/account-credit.d.ts

@@ -0,0 +1,171 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Unapplied cash: money a customer paid on an order OVER what the order bills,
+ * moved to their account and held there until it pays an invoice or is paid
+ * back. Never a credit note: nothing that was billed is credited.
+ *
+ * Every amount is in minor units of `currencyCode`, and
+ * `amount = applied + refunded + remaining`.
+ */
+export interface UnappliedCash {
+    id: string;
+    customerId: string;
+    /** The currency of the payment the money came from: its order's. */
+    currencyCode: string;
+    /** What was moved to the account. */
+    amount: number;
+    /** What of it has paid invoices. */
+    applied: number;
+    /** What of it was paid back to the customer. */
+    refunded: number;
+    /** What is still on the account, applied to nothing. */
+    remaining: number;
+    /** The order the money was paid on. */
+    orderId: string;
+    /** The payment of that order it was taken from. */
+    paymentId: string;
+    /** Date only (`YYYY-MM-DD`). */
+    receivedOn: string;
+    reference: string | null;
+    /** The reason given when the money was moved. */
+    notes: string | null;
+    /** ISO-8601 with offset. */
+    createdAt: string;
+}
+export interface CreditOverpaymentInput {
+    orderId: string;
+    /**
+     * Minor units of the order's currency. Omit it to move everything the order
+     * holds over what it bills.
+     */
+    amount?: number;
+    /** Why, in your own words: shown on the receipt and in the order's history. */
+    reason?: string;
+}
+export interface ApplyUnappliedCashInput {
+    unappliedCashId: string;
+    /** The AR invoice to pay. Give exactly one of `invoiceId` and `orderId`. */
+    invoiceId?: string;
+    /** An order, paid through the live AR invoice that bills it. */
+    orderId?: string;
+    /**
+     * Minor units. Omit it to apply as much as fits: the lesser of what the cash
+     * still holds and what the invoice still owes.
+     */
+    amount?: number;
+}
+export interface RefundUnappliedCashInput {
+    unappliedCashId: string;
+    /** Minor units. Omit it to pay back everything the cash still holds. */
+    amount?: number;
+    /** Free text stored on the refund. Shown to nobody automatically. */
+    reason?: string;
+}
+/** A payout's refund, as this surface projects it. */
+export interface UnappliedCashRefund {
+    id: string;
+    /** Minor units. */
+    total: number;
+    /** `Pending`, `Settled` or `Failed`. */
+    state: string;
+    method: string | null;
+    transactionId: string | null;
+    reason: string | null;
+}
+/** What of an order's money is on its customer's account now. */
+export interface OrderMoneyOnAccount {
+    /** The order's currency. Every amount here is in its minor units. */
+    currencyCode: string;
+    /**
+     * Money that left the order for the customer's account and was not paid back
+     * since. Already taken off the order's `refundable` and `overpaid`.
+     */
+    creditedToAccount: number;
+    /** The same figure per payment of the order, newest first. */
+    perPayment: Array<{
+        paymentId: string;
+        creditedToAccount: number;
+    }>;
+}
+/**
+ * An order's overpayment on the customer's account (`admin.payments.accountCredit`).
+ *
+ * For a store that keeps its own accounts-receivable ledger and a customer with
+ * a credit account in it. Anywhere else an overpayment is refunded: the calls
+ * here are refused `AR_LEDGER_NOT_ENABLED`, `AR_ACCOUNT_REQUIRED` or
+ * `AR_ACCOUNT_IN_ERP`. The last one covers every customer of a store whose ERP
+ * integration is on, and any ERP-linked account: balances are kept in the ERP
+ * there, where a credit recorded here would not show.
+ *
+ * Needs `UpdateOrder` to write, `ReadOrder` to read. Every write honours
+ * `options.idempotencyKey`: a repeat under the same key answers the first
+ * call's result instead of running again.
+ */
+export interface AccountCreditModule {
+    /**
+     * Move money a customer paid on an order over what it bills onto their
+     * account. Answers one {@link UnappliedCash} per payment the money came from,
+     * newest payment first.
+     *
+     * Only money a settled payment still holds can move, net of every refund and
+     * of what was moved before, and at most what the order holds over its
+     * billable total. From then on that money is no longer the order's:
+     * `payments.refundPosition` takes it off `refundable` and `payments.position`
+     * no longer reports it as `overpaid` (read it with {@link onOrder}).
+     *
+     * An order that is already on a live AR invoice is refused
+     * `AR_ORDER_ALREADY_INVOICED`: refund its overpayment with `payments.refund`.
+     *
+     * Other refusals: `ACCOUNT_CREDIT_NOTHING_OVERPAID`,
+     * `ACCOUNT_CREDIT_EXCEEDS_OVERPAYMENT`, `ACCOUNT_CREDIT_AMOUNT_INVALID`,
+     * `ACCOUNT_CREDIT_NO_CUSTOMER`, `ACCOUNT_CREDIT_ORDER_NOT_FOUND`, and the three
+     * account refusals above.
+     */
+    creditOverpayment(input: CreditOverpaymentInput, options?: Call): Promise<UnappliedCash[]>;
+    /** A customer's unapplied cash in this store, oldest first. */
+    list(customerId: string, options?: Call): Promise<UnappliedCash[]>;
+    /**
+     * Pay an AR invoice with unapplied cash. The customer's balance does not
+     * move: the cash was already theirs.
+     *
+     * The invoice must be the same customer's, in the same currency, live and
+     * still owing. Refusals: `AR_INVOICE_NOT_FOUND`, `AR_CURRENCY_MISMATCH`,
+     * `AR_INVOICE_NOT_OPEN`, `AR_ORDER_NOT_INVOICED` (an order with no live
+     * invoice: invoice it first), `UNAPPLIED_CASH_EXCEEDED`,
+     * `UNAPPLIED_CASH_NOT_FOUND`, `UNAPPLIED_CASH_REFUND_UNRECONCILED` (a payout
+     * of the same cash has an unknown outcome), `AR_LEDGER_NOT_ENABLED`.
+     */
+    apply(input: ApplyUnappliedCashInput, options?: Call): Promise<UnappliedCash>;
+    /**
+     * Pay unapplied cash back to the customer: a refund of the payment it was
+     * taken from, with `payments.refund`'s rules and refusals. When one refuses,
+     * nothing has changed.
+     *
+     * At most what the cash still holds, and at most what the customer's account
+     * is in credit by in that currency (`UNAPPLIED_CASH_EXCEEDED`): cash is
+     * applied to what a customer owes before it is paid out.
+     *
+     * **`IDEMPOTENCY_OUTCOME_UNKNOWN`** means the payment provider was asked and
+     * never confirmed. The cash STAYS on the account and is frozen
+     * (`UNAPPLIED_CASH_REFUND_UNRECONCILED`). Find the attempt with
+     * `payments.unreconciledRefunds(orderId)`, check the provider, and record its
+     * answer with `payments.reconcileRefund(...)`: `MADE` takes the cash off the
+     * account then, `NOT_MADE` unfreezes it. Never pay out again on the
+     * assumption that nothing happened.
+     */
+    refund(input: RefundUnappliedCashInput, options?: Call): Promise<UnappliedCashRefund>;
+    /** What of an order's money is on its customer's account now. Needs `ReadOrder`. */
+    onOrder(orderId: string, options?: Call): Promise<OrderMoneyOnAccount>;
+}
+export declare const CREDIT_ORDER_OVERPAYMENT_MUTATION = "\n  mutation CreditOrderOverpaymentToAccount(\n    $input: CreditOrderOverpaymentInput!\n    $idempotencyKey: String\n  ) {\n    creditOrderOverpaymentToAccount(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
+export declare const UNAPPLIED_CASH_QUERY = "\n  query ArUnappliedCash($customerId: ID!) {\n    arUnappliedCash(customerId: $customerId) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
+export declare const APPLY_UNAPPLIED_CASH_MUTATION = "\n  mutation ApplyArUnappliedCash($input: ApplyArUnappliedCashInput!, $idempotencyKey: String) {\n    applyArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
+export declare const REFUND_UNAPPLIED_CASH_MUTATION = "\n  mutation RefundArUnappliedCash($input: RefundArUnappliedCashInput!, $idempotencyKey: String) {\n    refundArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";
+/**
+ * Its own query, never a field added to `payments.refundPosition`'s: an SDK
+ * released ahead of a server without `creditedToAccount` must not break that
+ * read.
+ */
+export declare const ORDER_MONEY_ON_ACCOUNT_QUERY = "\n  query OrderMoneyOnAccount($orderId: ID!) {\n    orderRefundPosition(orderId: $orderId) {\n      currencyCode\n      creditedToAccount\n      perPayment {\n        paymentId\n        creditedToAccount\n      }\n    }\n  }\n";
+export declare function createAccountCreditModule(transport: Transport): AccountCreditModule;

package/dist/payments/account-credit.js

@@ -0,0 +1,107 @@
+const UNAPPLIED_CASH_FIELDS = /* GraphQL */ `
+  id
+  customerId
+  currencyCode
+  amount
+  applied
+  refunded
+  remaining
+  orderId
+  paymentId
+  receivedOn
+  reference
+  notes
+  createdAt
+`;
+export const CREDIT_ORDER_OVERPAYMENT_MUTATION = /* GraphQL */ `
+  mutation CreditOrderOverpaymentToAccount(
+    $input: CreditOrderOverpaymentInput!
+    $idempotencyKey: String
+  ) {
+    creditOrderOverpaymentToAccount(input: $input, idempotencyKey: $idempotencyKey) {
+      ${UNAPPLIED_CASH_FIELDS}
+    }
+  }
+`;
+export const UNAPPLIED_CASH_QUERY = /* GraphQL */ `
+  query ArUnappliedCash($customerId: ID!) {
+    arUnappliedCash(customerId: $customerId) {
+      ${UNAPPLIED_CASH_FIELDS}
+    }
+  }
+`;
+export const APPLY_UNAPPLIED_CASH_MUTATION = /* GraphQL */ `
+  mutation ApplyArUnappliedCash($input: ApplyArUnappliedCashInput!, $idempotencyKey: String) {
+    applyArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {
+      ${UNAPPLIED_CASH_FIELDS}
+    }
+  }
+`;
+export const REFUND_UNAPPLIED_CASH_MUTATION = /* GraphQL */ `
+  mutation RefundArUnappliedCash($input: RefundArUnappliedCashInput!, $idempotencyKey: String) {
+    refundArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {
+      id
+      total
+      state
+      method
+      transactionId
+      reason
+    }
+  }
+`;
+/**
+ * Its own query, never a field added to `payments.refundPosition`'s: an SDK
+ * released ahead of a server without `creditedToAccount` must not break that
+ * read.
+ */
+export const ORDER_MONEY_ON_ACCOUNT_QUERY = /* GraphQL */ `
+  query OrderMoneyOnAccount($orderId: ID!) {
+    orderRefundPosition(orderId: $orderId) {
+      currencyCode
+      creditedToAccount
+      perPayment {
+        paymentId
+        creditedToAccount
+      }
+    }
+  }
+`;
+export function createAccountCreditModule(transport) {
+    return {
+        async creditOverpayment(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CREDIT_ORDER_OVERPAYMENT_MUTATION,
+                // A variable, not a header: the Admin API takes the key as an argument.
+                // `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.creditOrderOverpaymentToAccount;
+        },
+        async list(customerId, options) {
+            const data = await transport.graphql({ api: 'admin', query: UNAPPLIED_CASH_QUERY, variables: { customerId } }, options);
+            return data.arUnappliedCash;
+        },
+        async apply(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: APPLY_UNAPPLIED_CASH_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.applyArUnappliedCash;
+        },
+        async refund(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REFUND_UNAPPLIED_CASH_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.refundArUnappliedCash;
+        },
+        async onOrder(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_MONEY_ON_ACCOUNT_QUERY, variables: { orderId } }, options);
+            return data.orderRefundPosition;
+        },
+    };
+}