@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/payments/methods.d.ts

@@ -1,6 +1,17 @@
-import type { Page, Transport } from '@sixtyninecommerce/core';
-import type { ListOptions } from '../types.js';
-/** One payment method of the store, as staff choose one. */
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import { type ConfigurableOperation, type ConfigurableOperationInput, type LanguageCode } from '../catalog/types.js';
+import type { Call, ConfigurableOperationDefinition, ListOptions } from '../types.js';
+import { type MollieMethodsModule } from './mollie-methods.js';
+import { type ProviderKeysModule } from './provider-keys.js';
+/** A payment method's name and description in one language. */
+export interface PaymentMethodTranslation {
+    id: string;
+    /** As the engine spells it: `en`, `nl`, `pt_BR`. */
+    languageCode: string;
+    name: string;
+    description: string;
+}
+/** One payment method of the store, as staff choose one and as its settings read. */
 export interface PaymentMethod {
     id: string;
     /**
@@ -8,30 +19,314 @@ export interface PaymentMethod {
      * deposit policy names in `storefront.methods`.
      */
     code: string;
+    /** In the language the client is set to (`tenant.language`), else the store's default. */
     name: string;
+    /** In the same language as {@link name}; empty when the method has none. */
+    description: string;
     /** A disabled method takes no new payments; it still names the ones it took. */
     enabled: boolean;
     /**
      * The code of the handler that takes the money (`manual-payment`, `mollie`, a
-     * payment app's handler, …): what kind of method this is.
+     * payment app's handler, …): what kind of method this is. Always `handler.code`.
      */
     handlerCode: string;
+    /**
+     * The handler with its stored arguments, every value a string as the engine keeps it.
+     *
+     * A SECRET argument (a PSP API key, a webhook secret, any argument the handler's definition
+     * renders as a password) is answered MASKED to every caller but the platform SuperAdmin:
+     * store staff, an API token and an app installation read `test_••••k6rW` or `••••`, never the
+     * credential. The mask is also how a later save says "keep the stored value". The SDK passes
+     * the engine's answer on as it is and never unmasks or re-masks one.
+     */
+    handler: ConfigurableOperation;
+    /** The eligibility checker that decides which customers may use the method; null without one. */
+    checker: ConfigurableOperation | null;
+    /** Every language the method is named in. A recorded payment may carry any of these names. */
+    translations: PaymentMethodTranslation[];
+    /**
+     * A net-terms ("pay later") method: an order placed with it holds no money, and it is offered
+     * and accepted only for the customers its checker allows.
+     */
+    isNetTermsCredit: boolean;
+    /** On a net-terms method: staff may use it for any customer; the webshop never reads this. */
+    netTermsStaffAnyCustomer: boolean;
+    /**
+     * Whether shoppers are offered the method at webshop checkout; on unless it was switched off.
+     * Staff orders and the till do not read it.
+     */
+    enabledInStorefront: boolean;
+    /** ISO-8601, UTC. */
+    createdAt: string;
+    /** ISO-8601, UTC. */
+    updatedAt: string;
+}
+/**
+ * Which credential a Mollie payment method takes payments with: its own pasted API key, or the
+ * store's Mollie Connect account (the legal entity's OAuth connection). Every other handler is
+ * `api_key`.
+ */
+export type PaymentMethodCredentialPath = 'api_key' | 'connect';
+/** A method's credential path, as {@link PaymentMethodsModule.setCredentialPath} answers it. */
+export interface PaymentMethodCredential {
+    paymentMethodCode: string;
+    credentialPath: PaymentMethodCredentialPath;
+}
+/**
+ * A method's name and description in one language, as a create or an update writes them. The
+ * engine keeps one row per language: writing a language the method has replaces that row's
+ * name and description, and any other language is added beside the ones it has.
+ */
+export interface PaymentMethodTranslationInput {
+    /** As the engine spells it: `en`, `nl`, `pt_BR`. */
+    languageCode: LanguageCode;
+    name: string;
+    /** Empty when left out. */
+    description?: string;
+}
+/** A new payment method, as {@link PaymentMethodsModule.create} takes it. */
+export interface CreatePaymentMethodInput {
+    /** What `payments.record` takes as `method` and a deposit policy names. */
+    code: string;
+    enabled: boolean;
+    /**
+     * The handler that takes the money, with every argument it needs (a value is always a string;
+     * lists and booleans JSON-encoded). One of {@link PaymentMethodsModule.handlers}.
+     */
+    handler: ConfigurableOperationInput;
+    /** Who may use the method; left out (or null), everyone. One of `checkers()`. */
+    checker?: ConfigurableOperationInput | null;
+    /** At least the store's default language: it is the name shoppers and staff are shown. */
+    translations: PaymentMethodTranslationInput[];
+    /** A net-terms ("pay later") method; off when left out. See {@link PaymentMethod}. */
+    isNetTermsCredit?: boolean;
+    /** On a net-terms method, staff may use it for any customer; off when left out. */
+    netTermsStaffAnyCustomer?: boolean;
+    /** Offered at webshop checkout; on when left out. */
+    enabledInStorefront?: boolean;
+}
+/**
+ * A change to a payment method, as {@link PaymentMethodsModule.update} takes it. A field left
+ * out keeps what the method has; `checker: null` takes its eligibility checker away.
+ */
+export interface UpdatePaymentMethodInput {
+    code?: string;
+    enabled?: boolean;
+    /**
+     * The method's WHOLE handler: it replaces the stored one, so send every argument the method
+     * keeps. A secret argument round-trips masked: see {@link PaymentMethodsModule.update}.
+     */
+    handler?: ConfigurableOperationInput;
+    checker?: ConfigurableOperationInput | null;
+    translations?: PaymentMethodTranslationInput[];
+    isNetTermsCredit?: boolean;
+    netTermsStaffAnyCustomer?: boolean;
+    enabledInStorefront?: boolean;
 }
 /**
  * The store's payment methods (`admin.payments.methods`): what staff record a
- * payment with, and what a deposit policy names.
+ * payment with, what a deposit policy names, and what the store's payment settings show.
  *
- * Needs `ReadSettings` or `ReadPaymentMethod`. Scoped to the channel the client
- * is on: another store's methods are not listed.
+ * Every read needs `ReadSettings` or `ReadPaymentMethod` (either one, so no `@permission` tag:
+ * the tag can only say "all of these"). Scoped to the channel the client is on: another
+ * store's methods are not listed, and not answered by id.
  */
 export interface PaymentMethodsModule {
+    /**
+     * Each method's own Mollie or Stripe API key (the legacy credential path): what the store's
+     * Mollie and Stripe cards set and test. See {@link ProviderKeysModule}.
+     */
+    providerKeys: ProviderKeysModule;
+    /**
+     * A Mollie method's checkout methods, their order and visibility, and a diagnosis of the
+     * Mollie account. See {@link MollieMethodsModule}.
+     */
+    mollie: MollieMethodsModule;
     /**
      * Every method of the store, enabled or not, in the engine's order. Paged
      * (`options.limit`, default 100, at most 1,000 or `INVALID_PAGE_SIZE`; and
      * `options.after` from a previous page); `for await (const method of page)`
      * walks them all.
+     *
+     * @effect read
      */
     list(options?: ListOptions): Promise<Page<PaymentMethod>>;
+    /**
+     * One method by id, or `null` when the store the client is on has no such method: an id that
+     * does not exist and the id of a method only ANOTHER store holds read the same. A value that
+     * is no id of the engine's kind at all is refused `ENTITY_NOT_FOUND` (`NotFoundError`, 404).
+     *
+     * @effect read
+     */
+    get(id: string, options?: Call): Promise<PaymentMethod | null>;
+    /**
+     * The payment handlers the engine has registered: what a method's `handler` may be, each with
+     * the arguments it takes. The whole list in one page, the same whichever store the client is
+     * on; labels and descriptions are in the language of the request.
+     *
+     * `args[].required` is NOT the enforced rule (see `ConfigArgDefinition.required`); never gate
+     * a form on it.
+     *
+     * @effect read
+     */
+    handlers(options?: Call): Promise<Page<ConfigurableOperationDefinition>>;
+    /**
+     * The eligibility checkers the engine has registered: what a method's `checker` may be, each
+     * with the arguments it takes. The whole list in one page, with the same `required` caveat as
+     * {@link handlers}.
+     *
+     * @effect read
+     */
+    checkers(options?: Call): Promise<Page<ConfigurableOperationDefinition>>;
+    /**
+     * The credential path of one method, by code; null when the store has no such method. Read
+     * from the method's own (readonly) custom field, so it is what the method pays with NOW.
+     *
+     * @effect read
+     */
+    credentialPath(paymentMethodCode: string, options?: Call): Promise<PaymentMethodCredentialPath | null>;
+    /**
+     * Move one Mollie method between its own API key and the store's Mollie Connect account.
+     * A payment keeps the credential it was taken with, so a switch never strands one. Asking for
+     * the path the method is on changes nothing.
+     *
+     * Needs `UpdatePaymentMethod` on every store holding the method AND every store of the legal
+     * entity. Coded refusals: `APP_SECRET_ARG_NOT_ALLOWED`, `SHARED_PAYMENT_METHOD_NOT_ALLOWED`,
+     * `SHARED_SELLER_NOT_ALLOWED`, `CREDENTIAL_PATH_UNSUPPORTED` (not a Mollie method); to
+     * `connect`: `CREDENTIAL_PATH_SHARED_ACROSS_SELLERS` (a store of another legal entity holds
+     * the method), `PROVIDER_NOT_CONNECTED`, `LIVE_PAYMENT_REFUSED`, `RECONNECT_REQUIRED`
+     * (each missing scope a `details[].code`), `PAYMENTS_NOT_ENABLED`, `MOLLIE_ACCOUNT_MISMATCH` (the method's
+     * key belongs to another Mollie profile); to `api_key`: `CREDENTIAL_PATH_KEY_MISSING`,
+     * `MOLLIE_ACCOUNT_MISMATCH`.
+     *
+     * @effect write
+     * @permission UpdatePaymentMethod
+     */
+    setCredentialPath(paymentMethodCode: string, path: PaymentMethodCredentialPath, options?: Call): Promise<PaymentMethodCredential>;
+    /**
+     * Add a payment method to the store the client is on, and answer it as {@link get} reads it
+     * (a secret argument masked for every caller but the platform SuperAdmin). Needs
+     * `CreateSettings` or `CreatePaymentMethod` (either one). Nothing is saved when it is refused:
+     *
+     * - `NET_TERMS_CHECKER_INVALID` (`ValidationError`, 400): an ENABLED net-terms method needs
+     *   the `customer-group-payment-checker`, which decides who may buy on terms. Judged on the
+     *   method as it would be saved; a disabled one may be saved without it.
+     * - `SECRET_ARG_MASK_INVALID` (`ValidationError`, 400): a secret argument carries the mask
+     *   glyph `••••`, which no provider issues; nothing is stored yet that a mask could keep.
+     * - `APP_SECRET_ARG_NOT_ALLOWED` (`PermissionDeniedError`, 403): an app installation may
+     *   create a method only with its secret arguments empty.
+     * - `LIVE_CONNECTION_REFUSED` (`BusinessRuleError`, 422): a store that is not live (a
+     *   sandbox) holds only a TEST Mollie or Stripe key (`test_…`, `sk_test_…`).
+     * - `PLUGIN_ACCESS_DENIED` (`PermissionDeniedError`, 403): the handler belongs to a plugin the
+     *   store does not hold (Mollie, Stripe, the till's card terminal, stored value).
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` (`BusinessRuleError`, 422): an organization's
+     *   workspace takes no payments; create the method in one of its stores.
+     *
+     * @effect write
+     */
+    create(input: CreatePaymentMethodInput, options?: Call): Promise<PaymentMethod>;
+    /**
+     * Change a payment method of the store the client is on, and answer it as {@link get} reads it.
+     * A field left out keeps what the method has; `checker: null` takes the checker away. Needs
+     * `UpdateSettings` or `UpdatePaymentMethod` (either one).
+     *
+     * **Secret arguments round-trip masked (`x-secret: masked-roundtrip`).** `handler` replaces
+     * the whole stored handler, and a read answers a secret argument (a PSP API key, a webhook
+     * secret) MASKED to everyone but the platform SuperAdmin. Send back the value the read
+     * answered, the mask included, and the engine keeps the stored secret; leaving `handler` out
+     * keeps it too. A new value replaces it, and an empty one CLEARS it (for staff and API tokens):
+     * a blank never means "keep". A mask that is no longer the stored value's (the key was changed
+     * after the read) is refused `SECRET_ARG_MASK_INVALID`: read the method again. An app
+     * installation may echo the mask or leave the argument as it is, never set, replace, clear or
+     * drop a secret (`APP_SECRET_ARG_NOT_ALLOWED`).
+     *
+     * Refused, with nothing saved, as {@link create} is (`NET_TERMS_CHECKER_INVALID` on the method
+     * as it would be saved, so enabling a net-terms method that has no checker is refused too;
+     * `SECRET_ARG_MASK_INVALID`; `APP_SECRET_ARG_NOT_ALLOWED`; `LIVE_CONNECTION_REFUSED`, also for
+     * a patch that only enables a method holding such a key; `PLUGIN_ACCESS_DENIED` for the
+     * handler named, or else the one stored), and:
+     *
+     * - `ENTITY_NOT_FOUND` (`NotFoundError`, 404): the store has no such method (another store's
+     *   reads the same).
+     * - `SHARED_PAYMENT_METHOD_NOT_ALLOWED` (`PermissionDeniedError`, 403): the method is shared
+     *   with other stores, and the caller lacks `UpdateSettings` or `UpdatePaymentMethod` in one
+     *   of them. A change reaches every store that holds the method.
+     *
+     * @effect write
+     */
+    update(id: string, patch: UpdatePaymentMethodInput, options?: Call): Promise<PaymentMethod>;
+    /**
+     * Take a payment method out of the store the client is on. Needs `DeleteSettings` or
+     * `DeletePaymentMethod` (either one).
+     *
+     * In a store this REMOVES the method from that store only: the engine unlinks it, and every
+     * other store holding it keeps it. Payments already taken with it stay on their orders, but
+     * this store can no longer refund them through it (a refund resolves its method in the store,
+     * enabled). Only in the platform's default channel is the method deleted outright, and there
+     * one that any store still holds is refused `PAYMENT_METHOD_NOT_DELETED` (`ConflictError`,
+     * 409) with the engine's reason naming those stores. The SDK never forces it.
+     *
+     * `ENTITY_NOT_FOUND` (`NotFoundError`, 404): the store has no such method.
+     *
+     * @effect destructive
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /**
+     * {@link delete} for several methods in one call. An empty list does nothing. An id the store
+     * does not hold refuses the whole call `ENTITY_NOT_FOUND` (`NotFoundError`, 404), and nothing
+     * is removed. A method the engine keeps (in the default channel, one another store still
+     * holds) does not stop the others: they ARE removed, and the call then rejects
+     * `PAYMENT_METHOD_NOT_DELETED` (`ConflictError`, 409) whose `details` name each id that was
+     * not (`field: 'ids.<index>'`).
+     *
+     * @effect destructive
+     */
+    deleteMany(ids: readonly string[], options?: Call): Promise<void>;
+    /**
+     * Share payment methods with one more store (`channelId`, the engine's id of that store), so
+     * its checkout and staff can use them too. Answers the methods as the store the client is on
+     * holds them. An empty list does nothing.
+     *
+     * Cross-store, so the engine asks twice: `UpdateSettings` or `UpdatePaymentMethod` on a store
+     * that holds each method (else `CHANNEL_ACCESS_DENIED`, `PermissionDeniedError`, 403, naming
+     * no method), and on the store that receives them (else `FORBIDDEN`, 403). The platform
+     * SuperAdmin passes both. Refused also:
+     *
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` (`BusinessRuleError`, 422): the receiving channel is
+     *   an organization's workspace, which takes no payments.
+     * - `PLUGIN_ACCESS_DENIED` (`PermissionDeniedError`, 403): a method uses a plugin's handler
+     *   (Mollie, Stripe, the till's card terminal, stored value) that either store does not hold.
+     *
+     * @effect write
+     */
+    assignToStores(ids: readonly string[], channelId: string, options?: Call): Promise<PaymentMethod[]>;
+    /**
+     * Take payment methods out of one store (`channelId`): its checkout and staff no longer offer
+     * them, and every other store holding them keeps them. Answers the methods as the store the
+     * client is on still holds them (none, when `channelId` is that store). An empty list does
+     * nothing.
+     *
+     * Needs `DeleteSettings` or `DeletePaymentMethod` on the store the client is on and on
+     * `channelId` (else `FORBIDDEN`, 403); the SuperAdmin passes. The platform's default channel
+     * keeps every method (`USER_INPUT_ERROR`, `ValidationError`, 400), and an id the engine
+     * does not know is `ENTITY_NOT_FOUND` (`NotFoundError`, 404). Payments already taken with a
+     * method in that store stay on their orders, but the store can no longer refund them
+     * through it.
+     *
+     * @effect destructive
+     */
+    removeFromStores(ids: readonly string[], channelId: string, options?: Call): Promise<PaymentMethod[]>;
 }
-export declare const PAYMENT_METHODS_QUERY = "\n  query StorePaymentMethods($options: PaymentMethodListOptions) {\n    paymentMethods(options: $options) {\n      items {\n        id\n        code\n        name\n        enabled\n        handler {\n          code\n        }\n      }\n      totalItems\n    }\n  }\n";
+export declare const PAYMENT_METHODS_QUERY = "\n  query StorePaymentMethods($options: PaymentMethodListOptions) {\n    paymentMethods(options: $options) {\n      items { \n  id\n  createdAt\n  updatedAt\n  code\n  name\n  description\n  enabled\n  handler { \n  code\n  args {\n    name\n    value\n  }\n }\n  checker { \n  code\n  args {\n    name\n    value\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n    description\n  }\n  customFields {\n    isNetTermsCredit\n    netTermsStaffAnyCustomer\n    enabledInStorefront\n  }\n }\n      totalItems\n    }\n  }\n";
+export declare const PAYMENT_METHOD_QUERY = "\n  query StorePaymentMethod($id: ID!) {\n    paymentMethod(id: $id) { \n  id\n  createdAt\n  updatedAt\n  code\n  name\n  description\n  enabled\n  handler { \n  code\n  args {\n    name\n    value\n  }\n }\n  checker { \n  code\n  args {\n    name\n    value\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n    description\n  }\n  customFields {\n    isNetTermsCredit\n    netTermsStaffAnyCustomer\n    enabledInStorefront\n  }\n }\n  }\n";
+export declare const PAYMENT_METHOD_HANDLERS_QUERY = "\n  query PaymentMethodHandlers {\n    paymentMethodHandlers { \n  code\n  description\n  args {\n    name\n    type\n    list\n    required\n    defaultValue\n    label\n    description\n    ui\n  }\n }\n  }\n";
+export declare const PAYMENT_METHOD_CHECKERS_QUERY = "\n  query PaymentMethodEligibilityCheckers {\n    paymentMethodEligibilityCheckers { \n  code\n  description\n  args {\n    name\n    type\n    list\n    required\n    defaultValue\n    label\n    description\n    ui\n  }\n }\n  }\n";
+export declare const PAYMENT_METHOD_CREDENTIAL_PATH_QUERY = "\n  query PaymentMethodCredentialPath($code: String!) {\n    paymentMethods(options: { filter: { code: { eq: $code } }, take: 1 }) {\n      items {\n        code\n        customFields {\n          mollieCredentialPath\n        }\n      }\n    }\n  }\n";
+export declare const SET_PAYMENT_METHOD_CREDENTIAL_PATH_MUTATION = "\n  mutation SetPaymentMethodCredentialPath(\n    $paymentMethodCode: String!\n    $path: PaymentMethodCredentialPath!\n  ) {\n    setPaymentMethodCredentialPath(paymentMethodCode: $paymentMethodCode, path: $path) {\n      paymentMethodCode\n      credentialPath\n    }\n  }\n";
+export declare const CREATE_PAYMENT_METHOD_MUTATION = "\n  mutation CreateStorePaymentMethod($input: CreatePaymentMethodInput!) {\n    createPaymentMethod(input: $input) { \n  id\n  createdAt\n  updatedAt\n  code\n  name\n  description\n  enabled\n  handler { \n  code\n  args {\n    name\n    value\n  }\n }\n  checker { \n  code\n  args {\n    name\n    value\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n    description\n  }\n  customFields {\n    isNetTermsCredit\n    netTermsStaffAnyCustomer\n    enabledInStorefront\n  }\n }\n  }\n";
+export declare const UPDATE_PAYMENT_METHOD_MUTATION = "\n  mutation UpdateStorePaymentMethod($input: UpdatePaymentMethodInput!) {\n    updatePaymentMethod(input: $input) { \n  id\n  createdAt\n  updatedAt\n  code\n  name\n  description\n  enabled\n  handler { \n  code\n  args {\n    name\n    value\n  }\n }\n  checker { \n  code\n  args {\n    name\n    value\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n    description\n  }\n  customFields {\n    isNetTermsCredit\n    netTermsStaffAnyCustomer\n    enabledInStorefront\n  }\n }\n  }\n";
+export declare const DELETE_PAYMENT_METHOD_MUTATION = "\n  mutation DeleteStorePaymentMethod($id: ID!) {\n    deletePaymentMethod(id: $id, force: false) {\n      result\n      message\n    }\n  }\n";
+export declare const DELETE_PAYMENT_METHODS_MUTATION = "\n  mutation DeleteStorePaymentMethods($ids: [ID!]!) {\n    deletePaymentMethods(ids: $ids, force: false) {\n      result\n      message\n    }\n  }\n";
+export declare const ASSIGN_PAYMENT_METHODS_TO_CHANNEL_MUTATION = "\n  mutation AssignPaymentMethodsToStore($input: AssignPaymentMethodsToChannelInput!) {\n    assignPaymentMethodsToChannel(input: $input) { \n  id\n  createdAt\n  updatedAt\n  code\n  name\n  description\n  enabled\n  handler { \n  code\n  args {\n    name\n    value\n  }\n }\n  checker { \n  code\n  args {\n    name\n    value\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n    description\n  }\n  customFields {\n    isNetTermsCredit\n    netTermsStaffAnyCustomer\n    enabledInStorefront\n  }\n }\n  }\n";
+export declare const REMOVE_PAYMENT_METHODS_FROM_CHANNEL_MUTATION = "\n  mutation RemovePaymentMethodsFromStore($input: RemovePaymentMethodsFromChannelInput!) {\n    removePaymentMethodsFromChannel(input: $input) { \n  id\n  createdAt\n  updatedAt\n  code\n  name\n  description\n  enabled\n  handler { \n  code\n  args {\n    name\n    value\n  }\n }\n  checker { \n  code\n  args {\n    name\n    value\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n    description\n  }\n  customFields {\n    isNetTermsCredit\n    netTermsStaffAnyCustomer\n    enabledInStorefront\n  }\n }\n  }\n";
 export declare function createPaymentMethodsModule(transport: Transport): PaymentMethodsModule;